# CLI for AI agents

Source: https://docs.settlemint.com/docs/api-reference/cli/ai-agents
Register the DALP CLI as an MCP server or an agent skill, run it safely from a coding agent's shell, and scope the session an operator hands an assistant.

An AI agent can drive the DALP CLI the same way a person does, from a shell. The CLI has two more integrations for agents: an MCP server, which serves `dalp` commands as tools over the Model Context Protocol, and a skill file, an instruction file an agent reads to learn the command tree without shelling out first. Both modes read from the same generated command tree covered in [CLI commands](https://docs.settlemint.com/docs/api-reference/cli/commands).

The agent does not get a separate authority model. Every command it runs uses the authenticated account, the active organisation, the assigned roles, and the same API validation that applies when you run a command yourself. Unlike the [hosted MCP server](https://docs.settlemint.com/docs/api-reference/cli/hosted-mcp), the CLI has no draft step: a write the agent sends runs as soon as it passes those checks.

[Figure] An agent works inside the operator's CLI session. The operator signs the CLI in and picks the organisation with the login and org switch commands. The agent uses that session, with the same account, organisation and roles. A get command is a read: the agent can list, inspect and summarise. A create, patch, replace or delete command is a write. The CLI does not prompt before a write, so your own policy has the operator review the exact command first. Every command passes the same API checks as a command a person types. The agent acts with the CLI's API key. DALP roles and membership, custody and signing policy, approval policy, wallet and recovery codes and incident sign-off stay with people. Labels: read; write; Operator's CLI session; Your session; Signed in, organisation picked; Agent uses your session; Agent; Same account, organisation and roles; Stays with people; DALP roles and membership; Custody and signing policy; Approval policy; Wallet and recovery codes; Incident sign-off; Reads; get commands; List, inspect and summarise; Review the exact command; Your policy; The CLI does not prompt for writes; Same API checks as a command you type; Every command; Account, organisation, roles and validation apply.

The operator signs the CLI in, and the agent then works inside that session with the same account, organisation and roles.

`dalp login`, `dalp logout`, `dalp config`, `dalp completions` and the two agent-integration commands below do not need stored credentials, and neither do global flags such as `--help` and `--llms`. `dalp whoami`, `dalp org` and every generated command do.

This page covers the MCP server that `dalp --mcp` runs on your own machine. To let a member connect Claude, ChatGPT or another app to DALP without the CLI, see [Hosted MCP server](https://docs.settlemint.com/docs/api-reference/cli/hosted-mcp).

## Shell mode [#shell-mode]

An agent that already has a shell tool can call `dalp` directly, exactly as a person would from a terminal.

Set `--format json` to get structured output instead of the human-oriented `toon` default. A run with a `--format` flag, or with output that is not a terminal, is in agent mode. Its output lists each progress event and then the command's response body. When the response links to resources the CLI can read, the output is an object with numbered keys and a `cta` key with suggested commands. Otherwise it is a JSON array. An agent reads the last numbered entry for the result.

```bash
dalp get tokens index --format json
```

## Registering an MCP server [#registering-an-mcp-server]

Run `dalp mcp add` to register the CLI as an MCP server with a compatible agent:

```bash
dalp mcp add
```

This registers `dalp --mcp` as an MCP server, so the agent reaches every command as a tool through the four tools that [MCP tools](#mcp-tools) describes. It installs for your user, or into the current project with `--no-global`. `--agent` targets one agent, such as `claude-code` or `cursor`, and `--command` overrides the command the agent runs.

`dalp mcp doctor` starts the server in the same process, asks it to initialise and to list its tools, and prints `ok`, `toolCount` and the tool list. It exits with status 1 when either step fails. It does not read an agent's configuration, so a passing check does not prove that an agent registered the server.

## MCP tools [#mcp-tools]

Every `get` command is marked read-only, so an agent finds a read with `search_tools` and runs it through `call_read_tool`.

The MCP server offers four tools: `search_tools`, `get_tool_details`, `call_read_tool` and `call_write_tool`. `call_read_tool` runs only tools marked read-only, and `call_write_tool` refuses them. The CLI sets the mark from the HTTP method of the route behind each command:

| Method | MCP mark | Runs through |
| --- | --- | --- |
| `GET` | read-only | `call_read_tool` |
| `DELETE` | destructive write | `call_write_tool` |
| `POST`, `PUT`, `PATCH` | write | `call_write_tool` |

A `get` command sent through `call_write_tool` gets the error `Tool is read-only: <tool name>`, and any other command sent through `call_read_tool` gets `Tool is not read-only: <tool name>`. Neither call reaches the API. Tool names are the command words joined with underscores, such as `get_tokens_holders`.

The hand-written commands `whoami`, `org`, `config`, `login` and `logout` are tools too, named `whoami`, `org_list`, `config_set` and so on. They carry no read-only mark, so `call_read_tool` refuses them and `call_write_tool` runs them. Through `call_write_tool` an agent can therefore run `logout`, which revokes the stored key, and `config_set`. Register the server only for an agent whose session you supervise. If an agent runs `logout`, the key is revoked and you sign in again with `dalp login`.

A tool result is a list of progress events that ends with the route's response body. A failed call ends with an event whose `phase` is `error` and whose `message` is the route's own message, such as the refusal a route sends when the API key lacks the role the read needs. After a blank line the message gives the cause, after `Why:`, the suggested fix, after `Fix:`, and the `dalp` commands that may help. When the route gives no message, the event says `Request failed`. Without stored credentials, a call answers `Not logged in. Run 'dalp login' to authenticate.` and sends nothing to the API.

The Console assistant reads the same routes. The two surfaces differ in what a call takes and returns:

|  | Console assistant | `dalp --mcp` |
| --- | --- | --- |
| Credentials | The session of the person asking | The API key from `dalp login` |
| Route authorisation | The live API router | The same router |
| Tool inputs | Handles from the conversation | The route's own parameters, such as the asset identifier |
| Tool results | Handles and figure references in place of the names and numbers a read returns | The route's own response body |

The difference in results is deliberate. The assistant replaces names and numbers in a read result before its model sees them. `dalp --mcp` returns the route's own response body, so names, wallet addresses, balances and identity data in a read reach the MCP client and the model provider it sends tool results to. The organisation's assistant data settings do not apply to it. An MCP client is the key holder's own agent, and the operator who registered it chose it, as [operating an organisation with an assistant](#operating-an-organisation-with-an-assistant) describes.

`search_tools` ranks by tool name first and description second, so name the capability in the query, for example `holders`.

## The Console assistant and the CLI [#the-console-assistant-and-the-cli]

The CLI has no command that asks the Console assistant a question. The assistant's routes serve the Console only and are not part of the published API that the CLI is built from, so neither `dalp` nor `dalp --mcp` can reach them. An agent that answers questions from a terminal uses the read commands from [MCP tools](#mcp-tools), under the API key's own roles.

On the latest answer in a Console conversation, the line that names what the assistant read, such as "Read holders and transfers", opens a list of each read in order. A read the CLI offers shows the `dalp` command that repeats it, with the asset identifier and the query filled in, and a copy button. A read the CLI does not offer shows its request line, such as `GET /api/v2/...`, with no copy button. The list comes from the reads the assistant made while it wrote the answer, so opening it sends no request.

A copied command runs under the CLI's API key, not the session of the person who asked, and it returns the route's own response body without the masking the assistant applies. [What the assistant sends](https://docs.settlemint.com/docs/concepts/operating/assistant-data) covers the model, the masking and the limits on the Console side.

## Registering a skill [#registering-a-skill]

Run `skills add` to install skill files that teach an agent the command tree directly, without a round trip through `--help`:

```bash
dalp skills add
```

`dalp skills add` writes one skill per top-level command group, such as `dalp-get` and `dalp-create`. It installs for your user, or into the current project with `--no-global`, and `--depth` changes the grouping. `dalp skills list` lists those skills and marks each as installed or not. Both `mcp add` and `skills add` finish by suggesting example prompts scoped to what the CLI does, for example asking the agent to log in, list tokens, switch the active organisation, or check `whoami`.

## Safe patterns for agent-driven commands [#safe-patterns-for-agent-driven-commands]

- Run `dalp whoami` and `dalp org current` before letting an agent run a mutation, so both you and the agent confirm which account and organisation a command acts against.
- A mutating command (`create`, `patch`, `replace`, `delete`) asks the platform to hold the response for up to 15 seconds while the write settles, and `--no-wait` asks it to answer at once. Neither makes the CLI poll: a write that outlives the wait returns a handle, and the command says `Request accepted; the transaction is still settling`. An agent must inspect the returned handle before reporting completion. Follow `statusUrl`, for example with `dalp get transaction-requests index <transactionId>`, because resubmitting with a new idempotency key can create a second instruction.
- Prefer `--format json` or `--schema` over parsing `toon` or human help text. `--schema` returns a command's argument and option shape as JSON Schema, which an agent can validate against before it runs anything.
- Treat any command under `delete`, `patch`, or `replace` as requiring explicit confirmation in your agent's own policy. The CLI itself does not prompt for confirmation before a mutating call.

## Operating an organisation with an assistant [#operating-an-organisation-with-an-assistant]

An operator decides whether, and how, to let an assistant touch a live organisation rather than a build or test pipeline. The assistant is not a separate DALP role: it inherits the authenticated account, active organisation, visible data, and assigned roles of the session you give it, so the same permission checks and API validation apply to every command it runs. If those credentials allow minting, pausing, inviting users, or changing compliance provider state, the assistant can run the same operations, and the CLI does not ask before it does. `dalp login` always creates a `read-write` key that lasts 90 days, so the account's roles are the only way to narrow what the assistant can do. Sign the CLI in as a separate account with only the roles the task needs when your operating model calls for tighter supervision. [Install and configure the DALP CLI](https://docs.settlemint.com/docs/api-reference/cli/install) covers authentication and pinning the active organisation before a session starts.

### Privileged operations need a human sign-off [#privileged-operations-need-a-human-sign-off]

Use an assistant for inspection and for preparing commands. Keep execution of a privileged command under operator review, with the operator accountable for each run. An assistant must not run a command that changes token state, identity or compliance records, or platform access without a human operator approving it first:

- creating a token, or minting, burning, pausing, or unpausing one.
- changing platform access roles.
- submitting or approving an identity or KYC record.
- changing a compliance provider's state, secret, or webhook configuration.
- retrying a failed webhook delivery, or re-running a mutation after an unclear result, since a blind retry against a consumer that already processed the first attempt can duplicate its effect.

The CLI does not ask before a write, so enforce this rule in the agent host, for example with its approval step for `call_write_tool` and for shell commands that write.

Apply these rules on every run:

- Have the assistant read current state before it proposes a mutation.
- Confirm the exact command, including the target token, address, amount, and organisation, before approving it.
- Keep high-risk operations under the same approval process you already use for Console or CLI work.
- Use roles to limit what the authenticated account can do. Prompt wording is not a permission control.
- Keep credentials in the CLI's local credential store. Do not paste an API key, session token, or participant data into the assistant conversation.
- Treat assistant output as a draft until you check it against the CLI's own JSON output.

### Safe operating pattern [#safe-operating-pattern]

1. Inspect current state with a read-only command.
2. Ask the assistant to propose one exact mutation command.
3. Review the command: the organisation, the target resource, and the expected effect.
4. Run the approved command yourself, or approve the assistant running it.
5. Inspect the target state again when the result is unclear.
6. Keep the CLI's own response as your evidence, not the assistant's summary of it.
7. If the inspected state still does not match what you approved, stop. Escalate through your incident process before another mutation. Retain the exact command and the CLI's before-and-after output as evidence.

Do not let an assistant retry a failed mutation on its own judgment. If a command times out or returns an unclear error, inspect the target state again before retrying.

### What the assistant should return [#what-the-assistant-should-return]

Before approving a privileged command, ask the assistant for a short run note. Require these facts:

| Fact | Why it matters |
| --- | --- |
| Active organisation | Confirms the assistant is acting in the right organisation. |
| Target record | Confirms the exact token, user, provider, or delivery being changed. |
| Read-only checks performed | Shows what state the assistant inspected before proposing the change. |
| Proposed command | Lets you review the exact operation before it runs. |
| Expected effect | Makes the state change, and how to recover from it, explicit. |

Keep secrets, API keys, and recovery material out of the run note.

### What stays outside the assistant [#what-stays-outside-the-assistant]

The platform account, wallet custody, and your human approval process decide what is allowed. Keep each of the following entirely outside the assistant:

- DALP roles and organisation membership.
- wallet custody and transaction signing policy.
- approval policy for privileged operations.
- API keys, session credentials, and recovery material.
- incident escalation and final operational sign-off.

A command like mint, burn, pause, or unpause is a platform-side state change. An agent that runs it with the CLI's API key sends no wallet PIN or code, because the platform does not ask an API-key request for wallet verification, and the configured custody path signs the instruction. The account's roles and any maker-checker hold still apply. Keep private signing keys outside the assistant environment.

### No platform switch controls this [#no-platform-switch-controls-this]

No platform setting enables, disables, or scopes an AI assistant that drives the CLI. The organisation's hosted MCP switch governs only the [Hosted MCP server](https://docs.settlemint.com/docs/api-reference/cli/hosted-mcp), not the CLI. An assistant is an ordinary CLI session, indistinguishable from a person running the same commands from the same workstation: the platform applies the same credential and permission checks and writes its audit records under the account and its CLI API key. Restrict it through the roles of the account it signs in as. End its access with `dalp logout`, or by revoking the `dalp-cli` key under API keys in the Console.

## Next steps [#next-steps]

- [Install and configure the DALP CLI](https://docs.settlemint.com/docs/api-reference/cli/install) covers authentication, configuration precedence, and credential storage that apply the same way whether a person or an agent runs the command.
- Read [security and compliance posture](https://docs.settlemint.com/docs/deployment/security-compliance-posture) for the control layers a privileged command still has to pass.


# CLI commands

Source: https://docs.settlemint.com/docs/api-reference/cli/commands
The DALP CLI generates a verb-first command tree from the Platform API. Learn the pattern, discover commands, and follow a write that has not settled.

The DALP CLI uses verb-first commands: `dalp get tokens index` lists tokens, and `dalp create tokens mints <assetId>` submits a mint. Most commands map to a public v2 Platform API route. Run `dalp --help` to see the commands available in your installed version.

The top-level commands `login`, `logout`, `whoami`, `config` and `org` are hand-written, not generated. [Install and configure the DALP CLI](https://docs.settlemint.com/docs/api-reference/cli/install) covers those.

## The verb-first pattern [#the-verb-first-pattern]

Every generated command path starts with a verb derived from the HTTP method. The API path's static segments follow the verb, and a variable part, like a token address, becomes a command argument instead.

| HTTP method | CLI verb |
| --- | --- |
| `GET` | `get` |
| `POST` | `create` |
| `PATCH` | `patch` |
| `PUT` | `replace` |
| `DELETE` | `delete` |

`create` covers more than creation. An instruction posted against an existing resource, such as a mint against a token, is also a `POST` and takes the same verb.

These examples show the mapping between API routes and CLI commands.

| API call | CLI command |
| --- | --- |
| `GET /api/v2/tokens` | `dalp get tokens index` |
| `GET /api/v2/tokens/{assetId}` | `dalp get tokens index <assetId>` |
| `POST /api/v2/tokens/{assetId}/mints` | `dalp create tokens mints <assetId>` |
| `GET /api/v2/webhooks` | `dalp get webhooks index` |
| `POST /api/v2/webhooks/{webhookId}/secret-rotations` | `dalp create webhooks secret-rotations <webhookId>` |
| `GET /api/v2/webhooks/{webhookId}/deliveries` | `dalp get webhooks deliveries <webhookId>` |
| `GET /api/v2/users` | `dalp get users index` |

The rule tells you what a command is called, not whether your machine has it. The tree is built from the API description inside the CLI build you installed, so deriving a command correctly and finding it missing means the build predates the operation. Pin the CLI version your automation expects and treat an upgrade as the moment new commands appear, rather than assuming a derived name is wrong.

A list endpoint and its matching single-item read endpoint share one command. When the resource also has nested commands, that shared command is named `index`: `dalp get tokens index` with no argument lists tokens, and `dalp get tokens index <assetId>` reads one. `dalp get tokens` alone prints the help for the commands under it.

Where the list and the single-item read differ by a trailing path parameter, the command declares both parameters, and only the trailing one is optional. Give it only the first argument and it sends the list request. Give it both and it sends the single-item request. `get webhooks deliveries <webhookId>` lists the deliveries of a webhook, and `get webhooks deliveries <webhookId> <deliveryId>` reads one. `get token-compliance modules`, `get system addon-access-managers proposals` and `create tokens corporate-actions commit` work the same way.

Every command supports `--help`, which shows its arguments and options and works through an example pulled from the same API description used to generate the command.

This page does not list the command tree. Run `dalp --help`, `dalp get --help` or `dalp create --help` to list what your installed CLI version registers.

Not every API operation becomes a CLI command. The CLI omits two operations that only the Console uses: a converter form-validation check and an invitation resend-dialog check. Sign-in is not a version 2 operation, so there is no generated `auth` command group, and `dalp login` covers CLI authentication.

Three further top-level commands, `completions`, `mcp` and `skills`, come from the command-line framework the CLI is built on rather than from an API operation, so they are neither generated nor part of the hand-written list.

## Supply a body, query, or header [#supply-a-body-query-or-header]

An operation that takes a request body exposes it two ways at once. `--body` accepts the whole body as a single JSON value, and every simple top-level field of that body also gets an option of its own, so a short call needs no JSON at all. Fields that are nested, or that accept more than one shape, stay on `--body` only. Query parameters follow the same pattern, with `--query` as the whole-object escape hatch. Supply both `--body` and individual field options and `--body` wins outright, so build a call one way or the other rather than mixing them, and read `dalp <command> --help` for the options that operation's own body produced. `--query` overrides individual query options in the same way, but a query parameter the operation requires must still be passed as its own option, because the JSON object alone does not satisfy it.

A command built from an operation that declares header parameters exposes those headers as ordinary command options, lower-cased and hyphenated from the header's own name. A header the operation calls `Idempotency-Key` becomes the option `--idempotency-key`, settable per call without changing the command's own shape.

`--format <value>` with a space selects CLI output and refuses any value outside the five formats. A route with its own `format` query parameter takes `--format=csv`, `--format=xlsx` or `--format=pdf`, as that route supports. The command does not save the response body, so a route that answers with file bytes prints `null`. Download those files through the API or the SDK.

## Mutations and settlement [#mutations-and-settlement]

A `create`, `patch`, `replace`, or `delete` command that triggers an on-chain transaction asks the platform to wait up to 15 seconds for settlement. The command prints the settled resource if the write finishes during that wait. Otherwise, it prints a handle with `statusUrl` and either `transactionId` or, for a custody lifecycle write, `requestId`. The message `Request accepted; the transaction is still settling` means the instruction remains in progress. A write held under maker-checker, the control in which a second person approves what one person raised, reports `Request held for a second approver` instead.

The CLI does not follow a handle for you. Read the transaction request until its status is terminal, which for an EVM transaction is `COMPLETED`, `FAILED` or `CANCELLED`, or `DEAD_LETTER` with `mayStillLand` set to `false`. While `mayStillLand` is `true`, keep reading and do not send the write again:

```bash
dalp get transaction-requests index <transactionId>
```

Pass `--no-wait` to skip the hold and take the handle back immediately:

```bash
dalp create tokens mints <assetId> \
  --body '{"amounts":"1000","recipients":"0x8ba1f109551bD432803012645Ac136ddd64DBA72"}' \
  --idempotency-key mint-example-001 --no-wait
```

A command run with the stored API key sends no wallet verification, because the platform does not ask an API-key request for it. The account's roles and any maker-checker hold still apply. Send the same `--idempotency-key` with the same body to retry the write, and [Idempotency and async settlement](https://docs.settlemint.com/docs/api-reference/guides/idempotency-async-settlement) describes what a repeat returns.

A command backed by a streaming (Server-Sent Events) endpoint, such as `dalp get transaction-requests stream <transactionId>`, prints each event of the stream as it arrives and exits when the stream ends. Under `--format jsonl` every event is its own line. When the stream fails before it ends, the command prints the API error with its Why and Fix lines and exits with code 1.

## Output and discovery for scripts and agents [#output-and-discovery-for-scripts-and-agents]

Every command accepts `--format` (`toon`, `json`, `yaml`, `md`, or `jsonl`). See [Install and configure the DALP CLI](https://docs.settlemint.com/docs/api-reference/cli/install) for the default. The CLI also has global options and discovery features for scripts and agents:

- `--llms` prints an index of every registered command with its description, and `--llms-full` prints the same tree with each command's help text, arguments, options and worked example.
- `--schema` on a leaf command prints its arguments and options as JSON Schema, so a caller can validate before it runs the command.
- `--filter-output` keeps only the output keys you name, `--full-output` prints the whole output envelope, and `--token-count`, `--token-limit` and `--token-offset` measure or bound what a model reads.

Every command distinguishes a person running it interactively from an agent or script consuming it. A run is in agent mode when standard output is not a terminal or a `--format` flag is present. In agent mode the same command reports progress as discrete events ahead of its result instead of a spinner, and piped output carries the events too. [Output format](https://docs.settlemint.com/docs/api-reference/cli/install#output-format) gives the shape each `--format` prints.

[Using the CLI with AI agents](https://docs.settlemint.com/docs/api-reference/cli/ai-agents) covers registering `dalp` as an MCP server and as an agent skill, which build on these same features.

## CLI-local error codes [#cli-local-error-codes]

An error the CLI raises itself, before or after it calls the API, carries its own `code` string rather than a `DALP-NNNN` id. When the API or the SDK supplies a code, that code is the one your script sees, so branch on the codes in [Errors](https://docs.settlemint.com/docs/api-reference/guides/errors) for any failure response the API itself returns. A failed command exits with status 1 and prints its code and message, so a script can branch on the code without parsing a sentence meant for a person. It also prints the cause, after `Why:`, and a suggested fix, after `Fix:`, followed by commands that may help. A generated command adds these lines to the end of its message, so they appear in every output format. A hand-written command prints them as a separate `cta` block.

| Code | Meaning |
| --- | --- |
| `NOT_AUTHENTICATED` | No stored credentials. Run `dalp login`. |
| `kit.cli.MISSING_PATH` / `kit.cli.INVALID_PATH` | A required path argument (for example a token address) is missing or fails validation. |
| `kit.cli.INVALID_QUERY` / `kit.cli.INVALID_BODY` | An option or the request body fails validation against the operation's schema. |
| `FEATURE_NOT_ENABLED` | A Canton command got the unknown-route answer because the deployment has `features.canton` switched off. |
| `API_OPERATION_FAILED` | A failure that carries no code of its own, such as an unexpected transport error. |
| `UNKNOWN_ERROR` | A hand-written command failed in a way that carries no code of its own. |
| `kit.cli.CREDENTIAL_STORE_FAILED` | Reading or writing stored credentials failed, including an insecure credentials file permission. |
| `kit.cli.CONFIG_INVALID` / `kit.cli.CONFIG_READ_FAILED` | A configuration file fails validation or cannot be read. |
| `NO_URL` | `dalp login` has no instance URL from `--url`, `DALP_URL` or configuration. |
| `kit.cli.INVALID_URL` | The instance URL for `dalp login` is not absolute, is not HTTPS outside a loopback host, or carries credentials, a query string or a fragment. |
| `kit.cli.DEVICE_CLIENT_REJECTED` | The instance refused the CLI's device client id. |
| `DEVICE_CODE_FAILED` | The request for a device code failed. |
| `kit.cli.DEVICE_AUTHORIZATION_TIMEOUT` | The device code expired before it was approved. |
| `kit.cli.AUTHORIZATION_DENIED` | The sign-in was denied in the Console. |
| `kit.cli.DEVICE_TOKEN_FAILED` | The poll for the device sign-in got an answer the CLI does not recognise. |
| `SESSION_FAILED` | The approved session could not be read. |
| `kit.cli.NO_ACTIVE_ORGANIZATION` | The approved login session has no active organisation, so no key was created. |
| `kit.cli.WALLET_CODE_REQUIRED` | `dalp login` has no wallet code and no terminal to ask for one. |
| `API_KEY_FAILED` | The instance refused to create the key for a reason other than a wallet or two-factor refusal. |
| `kit.cli.API_KEY_REVOKE_FAILED` | `dalp login` could not revoke the previous key, so it removed the new key and kept the previous credentials. |
| `kit.cli.LOGIN_RESPONSE_TOO_LARGE` | A login response was larger than 1 MiB. |
| `kit.cli.API_KEY_REVOKE_UNCONFIRMED` | `dalp logout` removed the local credentials but the instance did not confirm the key's revocation. |
| `INVALID_CONFIG_KEY` | `dalp config` was given a key that is not `apiUrl`, `defaultOrg` or `format`. |
| `KEY_HAS_NO_ORGANIZATION` / `ORGANIZATION_NOT_ON_KEY` | `dalp org switch` was given an organisation the stored key does not belong to, or the key has none. |


# Hosted MCP server

Source: https://docs.settlemint.com/docs/api-reference/cli/hosted-mcp
Connect Claude, ChatGPT or another MCP app to DALP at /api/mcp: read tools, and prepare tools that post a draft to sign or run a write under an agent's mandate.

The hosted MCP server lets a member connect an AI app that speaks MCP, the Model Context Protocol, to DALP. Claude and ChatGPT are examples. The server runs inside DALP at `/api/mcp`, so the app needs no CLI and no API key. The app reads what the member can read. By default it prepares changes as drafts that the member opens and signs. With `execution` set to `mandate`, DALP instead runs a mint, burn, pause, resume, block or unblock from one of the organisation's agent accounts, inside that agent's on-chain mandate and with no person signing, as [Execution modes](#execution-modes) describes. The app never signs, and the member's key never signs for it.

This page covers the hosted server. The `dalp --mcp` server described in [CLI for AI agents](https://docs.settlemint.com/docs/api-reference/cli/ai-agents) is a different server, started on a person's own machine, and it is unaffected by the hosted server. Choose the hosted server when the member uses a chat app and the organisation wants a per-member grant it can see and revoke. Choose `dalp --mcp` when an agent runs next to a shell with the API key from `dalp login`.

[Figure] A member connects an app, and the app reads or prepares drafts the member signs. An organisation owner switches the MCP server on. The organisation's assistant must be on too, and so must the platform-wide assistant switch, which is on by default. The app finds the OAuth sign-in from the metadata at /api/mcp. The member signs in, picks the organisation and allows read and prepare. Each tool call runs as that member in that organisation. A read tool returns what the member can read. A prepare tool posts a draft to the member's Actions inbox. The member reviews the draft and signs it with wallet verification. The app never signs. A prepare call with execution set to mandate skips the draft: one of the organisation's agents runs the write under its on-chain mandate. Labels: read tool; prepare_* tool; Switch the server on; Owner; The assistant must; be on too; Finds the sign-in; App; OAuth metadata at; /api/mcp; Allows the app; Member; Picks the organisation,; allows read and prepare; Runs as the member; Tool call; In the one organisation the grant binds to; Returns data; Read; What the member can read; and nothing else; Posts a draft; Prepare; To the member's Actions inbox; Nothing is signed yet; Reviews and signs; Member; Signs with wallet verification.

An owner switches the MCP server on, the member signs the app in over OAuth, and each tool call then reads as that member or posts a draft the member signs.

## Switch the server on [#switch-the-server-on]

An organisation owner or a platform administrator switches the server on. It is off by default. The platform-wide assistant switch, which is on by default, must be on too. While the server is off, or while either assistant switch is off, every request to `/api/mcp` answers 403 with `mcp_server_off`. Sign-in and consent still complete, but the app gets no data.

1. Open the Assistant page in organisation settings.
2. Make sure **Assistant in search** is on. The MCP server needs the assistant, and with the assistant off the "Connected apps" list is hidden.
3. Turn on **MCP server**.

The same two roles are the only ones who can switch it off, in the Console or through the Platform API. The Assistant page appears only in their navigation, and another member who opens its address cannot change the switch and sees "Only an owner can change this setting."

When an owner turns the switch off again, every request to `/api/mcp` for that organisation answers 403 with `mcp_server_off` until an owner turns it back on.

## Connect an app [#connect-an-app]

Give the app the server URL. Replace `<your DALP address>` with the address your organisation uses for the Console:

```text
<your DALP address>/api/mcp
```

The app finds the sign-in by itself. The server answers a request without a valid token with 401 and a `WWW-Authenticate` header that points to its protected-resource metadata. The metadata names DALP's OAuth issuer, and the app registers itself as an OAuth client without signing in, so no one creates a client by hand and DALP does not check who the app is. The registration requires PKCE, the OAuth Proof Key for Code Exchange extension that binds each sign-in to the app that started it. An access token lasts one hour and a refresh token lasts 30 days.

The metadata is served by the Platform API at `/.well-known/oauth-protected-resource/api/mcp`. The `WWW-Authenticate` header of the 401 carries the exact address, and an app that follows it reads this document:

```json
{
  "resource": "https://dalp.northwind.example/api/mcp",
  "authorization_servers": ["https://dalp.northwind.example/api/auth"],
  "bearer_methods_supported": ["header"],
  "scopes_supported": ["dalp:read", "dalp:prepare"],
  "resource_name": "DALP"
}
```

The Console forwards `/.well-known/*` to the API, as it does `/api/*` and `/dalp/*`, so the Console address serves this metadata. A gateway in front of the Console must pass `/.well-known` through as well.

The server is stateless and speaks streamable HTTP. An app sends JSON-RPC requests with `POST`, and a `GET` to `/api/mcp` answers 405 with "This MCP server is stateless: POST JSON-RPC requests to it."

### What the member does [#what-the-member-does]

1. The app opens a sign-in page titled with the app's name, such as **Sign in to connect Claude**. This page offers no account creation. The member signs in, including two-factor verification, and returns to the app's request.
2. The consent page, titled with the app's name, such as "Connect Claude to DALP", shows the **Organisation** the grant binds to. A member of several organisations picks one with "Choose an organisation", and the page reloads with the choice.
3. Under **The app will be able to**, the page lists what the app asked for: "Read the DALP data you can see", "Prepare actions for you to review in your Actions inbox", or both. With "Prepare actions" it also lists "Have your organisation's agent principal, if it has one, run a mint, burn, pause, resume, block or unblock within its mandate, with no one signing", which is `execution` set to `mandate`, as [Execution modes](#execution-modes) describes. The page then states: "It cannot sign anything with your account."
4. The member selects **Allow** or "Deny". A member with no organisation cannot select "Allow", and the page says "You are not a member of an organisation." A failed answer keeps the member on the page with "Your answer could not be sent. Try again."

The name on both pages is the name the app gave itself, so allow only apps you trust. A request that lost its signed parameters shows "This connection request is incomplete" and offers no answer. When the server is off, an owner sees "The MCP server is off" with a link, **Open assistant settings**. A member sees no notice, because only an owner can change the switch.

The grant belongs to one member in one organisation. The app works in that organisation only, with that member's permissions.

## Read tools [#read-tools]

The server offers the same four tools as `dalp --mcp`. An app finds a tool with `search_tools`, reads its schema with `get_tool_details`, and runs a read with `call_read_tool` or a prepare tool with `call_write_tool`. The view tool `show_holders` is listed on its own.

The read tools are the CLI's `get` commands, the same set `dalp --mcp` offers through `call_read_tool`, described in [MCP tools](https://docs.settlemint.com/docs/api-reference/cli/ai-agents#mcp-tools). Every read runs as the member who signed the app in, in the organisation the grant binds to. The app sees what the member sees and nothing else. A read returns the route's own response body, without the masking the Console assistant applies, so names, wallet addresses, balances and identity data in it reach the app and the model provider behind it. The organisation's assistant data settings do not limit what the hosted server returns.

The access token is read-only on the API. A write method sent with it answers 403 `SESSION_POLICY_DENIED` (DALP-0036). A route that only the Console may call refuses the token with the same code, whatever the method. A write goes through a prepare tool instead, as a draft for a person to confirm in DALP or, under a mandate, as a write one of the organisation's agents runs.

## Prepare tools [#prepare-tools]

Each `prepare_*` tool matches one Console control, such as the controls on an asset's page, and is named after it, for example `prepare_asset_pause`. A prepare tool takes the asset's contract address as `assetId`, the control's own fields and an optional `execution`.

`search_tools` and `get_tool_details` return each prepare tool's MCP annotations, the hints that tell an app what a tool can change. `prepare_asset_mint`, `prepare_asset_burn`, `prepare_asset_pause`, `prepare_asset_unpause`, `prepare_asset_blocklist_block` and `prepare_asset_blocklist_unblock` carry `destructiveHint: true`, because with `execution` set to `mandate` they run the write at once and no person signs. The hint stays the same when a call uses `inbox`. Every other prepare tool carries `destructiveHint: false`. It answers `mandate` with `execution-unsupported`, so it can only post a draft. No prepare tool is marked read-only or idempotent, because an `inbox` call takes no idempotency key. The app runs every prepare tool through `call_write_tool`, which is marked destructive whatever tool it runs.

A prepare tool checks the address and each field, reads the asset as the member, and refuses when the member does not hold the permission the control needs. When the checks pass, the platform posts a draft to the member's Actions inbox. Nothing is signed or submitted at that point.

The draft appears as a "Request from an app". Its sheet says which app prepared it through the MCP server. Its checks record that, when the app prepared it, the member held the permission the change needs and the app filled in every required field. The member selects **Review** to open the item's sheet, then "Open draft", and the existing control opens with the values filled in. The member confirms with wallet verification. Opening the draft closes the item as accepted, whether or not the member then signs.

The app learns the draft's `itemId` and `openUrl` from the tool result. The link `/actions?agentItem=<itemId>` opens the item's sheet in the Actions inbox, and only the member it belongs to can open it.

### Refusals [#refusals]

A refused prepare call returns an error result, not a draft. The caller fixes the cause and calls again.

| Reason | What the platform observed | What to do |
| --- | --- | --- |
| `scope-missing` | The member did not allow the app to prepare writes. | Sign the app in again and allow **Prepare actions for you to review**. |
| `invalid-fields` | `assetId`, a field, `agentId` or `idempotencyKey` is missing or bad. | Fix the fields the message lists and call the tool again. |
| `asset-unreadable` | The member cannot read the asset. | Use an asset the member can see. |
| `permission-missing` | The member does not hold the permission the control needs on the asset. | Ask an administrator to grant the permission. Retrying does not help. |
| `no-agent-principal` | With `mandate`, `agentId` names no agent of the member's organisation. | Use an agent from the Agents page, or call the tool with `inbox`. |
| `execution-unsupported` | With `mandate`, the control has no call an agent can run. | Call the tool with `inbox`. |
| `mandate-refused` | The agent's mandate, its state or the organisation's halt refused it. | Read the reason in the message. Change the mandate or use `inbox`. |
| `restriction-held` | With `mandate`, the call asks to unblock a wallet, and an active [wallet restriction](https://docs.settlemint.com/docs/console/participants/restrict-a-wallet) on that wallet lists the asset. | Ask the organisation's owner to lift the restriction, as [Lift a restriction](https://docs.settlemint.com/docs/console/participants/restrict-a-wallet#lift-a-restriction) describes. A lift that completes unfreezes the wallet on the tokens the restriction froze. If the wallet was frozen on this asset before the restriction, call the unblock again once the restriction is lifted. Neither a retry nor `inbox` helps while the restriction is active. |
| `execution-unavailable` | DALP could not read the agent, the asset's metadata or the restrictions of the wallet to unblock, or could not reach the agent execution service. | Retry the call. |
| `store-unavailable` | DALP could not save the draft. | Retry the call. This is a retryable platform error. |

A `call_write_tool` call that names a tool the server does not list returns the error `Unknown tool: <name>`. List the tools again and call one of them.

### Execution modes [#execution-modes]

`execution` takes `inbox`, the default, or `mandate`. With `inbox` the draft goes to a person to sign. With `mandate`, DALP runs the write from an agent's account. An agent is a participant the organisation set up to act through a key the platform holds, and its [mandate](https://docs.settlemint.com/docs/concepts/custody-and-signing/agent-mandates) is the set of calls, amounts and expiry the chain enforces on it. The member's key never signs.

A `mandate` call names two more fields. `agentId` is the id of any of the organisation's agents from the Agents page: DALP checks that the agent belongs to the organisation, not that the member set it up. `idempotencyKey` is 8 to 128 letters, digits, dots, colons, dashes or underscores that the app sends again unchanged on a retry. A retry from the same app and member, with the same `agentId` and key, never runs the write twice. Another app, another member, another agent or an app that registered again as a new client starts a new write.

DALP makes the same checks as for a draft first, including the member's own permission for the control. Mint, burn, pause, resume, block and unblock run under a mandate. Any other control answers `execution-unsupported`. Every mint or burn row needs its holder and a positive amount with no more decimals than the asset has: DALP refuses an incomplete row or an over-precise amount instead of dropping or rounding it.

A [wallet restriction](https://docs.settlemint.com/docs/console/participants/restrict-a-wallet) freezes a participant's wallet on the tokens it lists, and DALP releases those freezes only through its lift. While one is active and lists the asset, DALP refuses an unblock of that wallet with `restriction-held`. The Console's "Unblock" sheet and the Platform API refuse the same unblock, so a draft prepared with `inbox` is refused before the member signs it.

A mandate meters transfers and approvals only, so a mandate that sets a limit on an asset cannot allow a mint or burn on it. DALP refuses such a mint or burn with `mandate-refused` and the reason `target-not-allowed`. When the mandate sets no limit on the asset and allows the call, the mint or burn runs with no amount cap. The answer carries the agent's account, the queue request and a `state` of `queued` or `landed`. A refused `mandate` call submits nothing and prepares no draft.

## Views in the app [#views-in-the-app]

In an app that renders MCP Apps, `show_holders` opens a table of an asset's holders and balances, as the member can read them. The tool takes `assetId`.

A prepared draft has no view in the app. The prepare result carries the draft's `openUrl` and tells the app to give that link to the member, who opens the item in the Actions inbox.

## Limits [#limits]

Tool calls share the assistant's limits. The per-member and per-organisation windows are the assistant's turn windows, multiplied by ten for tool calls, and they follow whether the organisation uses the shared assistant or its own model key. A call that spends the window is refused with 429 and a `Retry-After` header that gives the seconds until the window resets:

```json
{
  "error": "rate_limited",
  "error_description": "Too many MCP tool calls. Try again shortly."
}
```

The error is retryable. The app waits for `Retry-After` and sends the call again. A batch that carries several tool calls spends one unit per call.

## Other responses [#other-responses]

| Status | Meaning | What to do |
| --- | --- | --- |
| 401 | The token is missing (`invalid_request`), or it is expired or revoked (`invalid_token`). The `WWW-Authenticate` header points to the metadata. | Sign the app in again. |
| 403 | `mcp_server_off`: the organisation's MCP server is off, the assistant is off for the organisation or the whole platform, or the token carries no organisation. | Ask an owner to switch the server on. |
| 403 | `insufficient_scope`: the app was not granted `dalp:read`. Every tool needs it. | Sign the app in again and allow it to read. |
| 405 | A `GET` to `/api/mcp`. | Send JSON-RPC with `POST`. |
| 429 | The window is spent. | Wait for `Retry-After`. |
| 503 | DALP could not serve the request. This is a retryable platform error. | Retry after a moment. |

## Audit [#audit]

Every tool call writes one audit row before the call runs and settles it with the outcome. The row records the route `mcp.<tool>`, the auth source `oauth`, the member, the organisation, and the app's id and name next to the tool's arguments. A call made through `call_read_tool` or `call_write_tool` is recorded under the tool it runs. A prepare tool is recorded as a mutation, and any other tool as a sensitive read. DALP settles the rows of one request together: when the request fails, or any call in it fails or is refused, every row of that request is recorded as failed, including a call in the same batch that succeeded. A call refused for the limit window leaves no row, because it never ran. A `mandate` call also writes an `agent-execution` row with the auth source `agent`, the member as actor and the submitted calls. The rows are part of the [audit trail](https://docs.settlemint.com/docs/console/reporting/audit-trail).

## Connected apps and revocation [#connected-apps-and-revocation]

The **Connected apps** list on the Assistant page shows each connected app with these columns: "App", "Member", "Access", "Connected" and "Last used". "Access" reads "Read", "Prepare actions" or both. "Last used" reads "Never" until the app uses the grant. An empty list reads "No apps are connected."

An organisation owner sees every member's apps. A platform administrator who is not an owner sees only the apps they connected themselves.

Select "Revoke" on a row, then **Revoke access** to confirm:

| Who revokes | What the dialog says | What is removed |
| --- | --- | --- |
| An owner | The app loses access for every member who connected it. Members can connect it again. | The app's grants for the whole organisation. |
| A member | The app loses your access. You can connect it again. | Only that member's grant. |

A revoked app must be signed in again. A revoke that finds no matching grant answers as not found. The list and the revoke belong to the Console only. The published API reference, the SDK and the CLI do not offer them.

## Next steps [#next-steps]

- [CLI for AI agents](https://docs.settlemint.com/docs/api-reference/cli/ai-agents) covers the local `dalp --mcp` server, which the hosted server leaves unaffected, and how to scope an assistant session.


# CLI install and setup

Source: https://docs.settlemint.com/docs/api-reference/cli/install
Install the DALP CLI, authenticate with a browser device code flow, and configure the API URL, active organisation, and output format.

The DALP CLI (`dalp`) is a standalone command-line client for the Platform API. It ships as the package `@settlemint/dalp-cli`, and every business command it exposes calls the same public v2 endpoints documented in the [DALP API reference](https://docs.settlemint.com/docs/api-reference).

## Install [#install]

Install the package globally with the package manager you already use. Run this once per machine, then confirm the install by printing the installed version:

```bash
npm install --global @settlemint/dalp-cli
dalp --version
```

```bash
pnpm add --global @settlemint/dalp-cli
dalp --version
```

```bash
bun add --global @settlemint/dalp-cli
dalp --version
```

The `dalp` command runs on one specific JavaScript runtime, which can differ from the one your package manager uses, and the package does not install it. Read the runtime and version from the package's `engines` field, install that runtime, and confirm it is on your `PATH`:

```bash
npm view @settlemint/dalp-cli engines
# example output: { bun: '1.4.4' }
bun --version
```

If `dalp --version` reports that a program was not found, the runtime is missing or not on your `PATH`.

Run `dalp --update` to install the latest published version. In a terminal, `dalp` also prints a notice when a newer version exists. It checks the package registry at most once a day for that notice, and the `NO_UPDATE_NOTIFIER` environment variable or a CI environment switches the notice off.

The [TypeScript SDK](https://docs.settlemint.com/docs/api-reference/sdk) runs in browser, server and React Native applications on the runtime your application already uses. Use the CLI for terminal access to an instance, and the SDK when you build software.

## Authenticate [#authenticate]

Point the CLI at your instance, then sign in and confirm the session:

```bash
dalp config set apiUrl https://your-instance.example.com
dalp login
dalp whoami
```

`dalp login` requests a device code and a short user code from the instance, then polls until you approve the request in the browser. When its output is a terminal and you pass no `--format` flag, it prints the verification URL and the user code and tries to open the URL. In [agent mode](#output-format) the CLI does neither, so start the sign-in from a terminal without `--format`.

The Console shows its device approval screen at `/auth/device`. Enter the code shown in the terminal, or open the link that already carries it, and select Approve. If you have no Console session, the Console asks you to sign in first and returns you to that screen. A code the instance does not know, or that has expired, answers "That code is wrong or has expired. Check the code in your terminal and try again." The user code has eight characters and expires after 10 minutes. The poll backs off when the instance asks it to slow down. It sends no token request once the code has expired and does not accept a token response that arrives after expiry. It stops with `kit.cli.DEVICE_AUTHORIZATION_TIMEOUT` if the code expires, and with `kit.cli.AUTHORIZATION_DENIED` if you select Deny.

On approval, the CLI reads the session it was granted, requires that the session has an active organisation, asks for your wallet PIN and creates a new API key scoped `read-write`. The key is named `dalp-cli` with the hostname of the machine that created it, such as `dalp-cli (dev-laptop)`, expires after 90 days, and is stored locally. API key names hold at most 32 characters, so a hostname longer than 21 characters is cut to its first 20 and ends with `…`, as in `dalp-cli (build-agent-07.eu-we…)`. A session with no active organisation creates nothing and fails with `kit.cli.NO_ACTIVE_ORGANIZATION`. After the CLI stores the key, it saves the instance URL as `apiUrl` and the organisation as `defaultOrg` in the global configuration file.

The scope and lifetime are fixed: `dalp login` offers no read-only or shorter-lived key, and the CLI reads no API key from the environment. For a CI job, a service or a read-only credential, create an API key as [Authentication and API keys](https://docs.settlemint.com/docs/api-reference/guides/authentication-api-keys) describes and call the API or the SDK with it.

Creating the key needs the same wallet verification as signing a transaction. The CLI asks for your wallet PIN on the terminal and does not echo it. To confirm with your authenticator app, your identity provider's authenticator or a recovery code instead, pass `--wallet-factor otp`, `--wallet-factor oidc-mfa` or `--wallet-factor secret-codes`. An account that holds an authenticator must use its code, `otp` for a wallet authenticator or `oidc-mfa` for the identity provider's, because the platform refuses a PIN or recovery code for it with `WALLET_STEP_UP_STRONGER_FACTOR_REQUIRED`. When standard input is not a terminal, set `DALP_WALLET_CODE` to the code. Without it the login stops with `kit.cli.WALLET_CODE_REQUIRED` after the approval and creates nothing.

Requests made with the key afterwards carry no wallet verification. The platform does not ask an API-key request for it, and refuses one only during the cooling-off period after a security change. The stored key therefore carries the signing authority of the account until it expires or is revoked.

During the cooling-off period after a security change, the login stops with `WALLET_STEP_UP_HELD` and keeps your stored credentials. A wrong code stops it with `WALLET_STEP_UP_REJECTED`. When your deployment requires two-factor sign-in and your account has not set it up, the browser approval succeeds and the CLI asks for the wallet code, but the platform refuses the key before it checks that code. The CLI prints `Authorized, but the API key was not created` with the code `LOGIN_TWO_FACTOR_REQUIRED` and the reason `Set up two-factor sign-in before you create or change an API key.`, and it stores no key. Set up two-factor sign-in on the [Security page](https://docs.settlemint.com/docs/console/my-account/security), then run `dalp login` again. Any other refusal of the key request stops with `API_KEY_FAILED`.

The CLI process never touches your password: you approve the short code inside your own browser, where you authenticate however your organisation normally requires. On approval the CLI briefly holds a short-lived session token. It sends that token as a bearer token only to read the session and to create the key, and every other account route refuses it. Those two routes accept a bearer token only from a device sign-in, so a token from a browser session cannot mint a key. The CLI never writes the session token to disk. When the Console signs in through an identity provider, only a Console session can approve a device code, and the Investor portal refuses device routes with `DEVICE_SIGN_IN_NEEDS_CONSOLE`.

The minted key is an ordinary API key, the same kind of secret a backend service holds, and once it is issued the platform treats it like a key created through [the API key routes](https://docs.settlemint.com/docs/api-reference/guides/authentication-api-keys). It differs only in how it is made: a person's browser login creates it. Nothing binds it to the machine that stored it, so whoever holds the key can use it from any host until it expires after 90 days or is revoked under API keys in the Console.

The login step accepts only HTTPS instance URLs. HTTP is accepted for `localhost`, `127.0.0.1` and `::1` alone, for local development. A URL that is not absolute, or that carries embedded credentials, a query string or a fragment, is refused with `kit.cli.INVALID_URL`. There is no default instance. Without a URL from `dalp login --url`, `DALP_URL` or the `apiUrl` config key, login stops with `NO_URL`.

Confirm the session at any time with `dalp whoami`. End it with `dalp logout`, which removes the stored credentials from this machine.

```bash
dalp whoami
dalp logout
```

Logging out revokes this machine's API key on the server and then removes the stored credentials. When the instance does not confirm the revocation, the command removes the local credentials anyway and fails with `kit.cli.API_KEY_REVOKE_UNCONFIRMED`, and the fix it prints is to revoke the `dalp-cli` key under API keys in the Console.

The CLI stores one credential set at a time, not several named identities you switch between. Re-running `dalp login` creates the new key, revokes the key that was stored before, and only then saves the new one. A key it cannot revoke is rolled back so the stored credentials still work, and that login fails with `kit.cli.API_KEY_REVOKE_FAILED`. If the CLI cannot save the new credentials, it revokes the new key and fails with `kit.cli.CREDENTIAL_STORE_FAILED`. The previous key is already revoked by then, so run `dalp login` again. On Linux and Windows, separate identities on one machine mean separate config directories, set with the `DALP_CONFIG_DIR` environment variable. On macOS the keychain holds one login at a time, because saving a credential deletes every other account under the `dalp-cli` service name.

## Active organisation [#active-organisation]

The API key that `dalp login` creates belongs to one organisation: the active organisation of the session that approved the login. Inspect it with the `org` command group:

```bash
dalp org list
dalp org switch <organizationId>
dalp org current
```

`org list` lists only the organisation the stored key belongs to, because a key reads only its own organisation. `org switch` reads the stored key and accepts only the organisation that key belongs to. It saves that organisation in the stored credentials and in `defaultOrg`. Any other organisation id fails with a message that names the key's organisation, and the command saves nothing. A key cannot move to another organisation. To work in another organisation, run `dalp login` again so that the new key belongs to it. A key with no organisation also fails `org switch`. Run `dalp login` to replace it.

## Configuration [#configuration]

The CLI resolves three configurable keys: `apiUrl`, `defaultOrg`, and `format`. Read and write them with:

```bash
dalp config get apiUrl
dalp config set defaultOrg <organizationId>
dalp config list
```

`config get` and `config set` both require the key argument, and an unknown key is refused with `INVALID_CONFIG_KEY`. `config set` always writes the global file, stores `apiUrl` and `defaultOrg` as typed, and refuses a `format` value other than `toon`, `json`, `yaml` or `md`. There is no bare `dalp config get` that dumps every key. Use `dalp config list` to see every stored and resolved value at once: it returns the global file's own values and the effective value after layering, so you can see which layer decides.

These keys are read by `dalp login`, `dalp config` and the other configuration-aware commands. They do not move an existing login: every other command talks to the instance URL and the organisation that `dalp login` stored, so to change where the CLI points, run `dalp login` against the new instance.

`dalp login` resolves its instance URL from three layers, each overriding the one before it:

1. The global file at `~/.config/dalp/config.json` (override the directory with the `DALP_CONFIG_DIR` environment variable).
2. A project file named `.dalprc.json` in the current working directory.
3. The `DALP_URL` environment variable, or `dalp login --url`.

Every request the CLI makes acts in the organisation the stored API key belongs to. `defaultOrg`, which the `DALP_ORG` environment variable also sets, records the organisation the login is for. It does not move a request to another organisation.

The CLI creates the config directory with mode `0700` and writes `config.json` with mode `0600`. A configuration file that fails validation stops every command that reads it with `kit.cli.CONFIG_INVALID`, so fix or delete the file. Credentials are stored separately, as the next section describes.

## Credential storage [#credential-storage]

The CLI stores your API key by operating system:

| Platform | Storage |
| --- | --- |
| macOS | The system keychain, under the service name `dalp-cli`. |
| Linux and Windows | `credentials.json` in the config directory, `~/.config/dalp` unless `DALP_CONFIG_DIR` names another one, written with `0600` permissions. |

On Linux and Windows, the CLI refuses to read a credentials file whose permissions have been loosened. It tells you to run `chmod 600` on it, rather than silently trusting a world-readable file, because a shared machine can otherwise leak your API key to another account. The file is not encrypted. Its permissions keep the key from other accounts on the machine, not from programs that run as you, such as an agent with a shell.

Neither storage path writes the credential to a shell history file or a log. On Linux and Windows the value is written straight to the file. On macOS it is handed to the system's `security` tool on its standard input, never as a command argument, so it does not appear in the process list while that tool runs. The tool reads each input line into a 4,096-byte buffer, so a sign-in whose email holds a line break, or whose credentials do not fit that buffer with the line break, fails with `kit.cli.CREDENTIAL_STORE_FAILED` and stores nothing.

## Output format [#output-format]

Every command you run accepts `--format` to control how it prints results: `toon`, a compact text format and the default, or `json`, `yaml`, `md`, or `jsonl` for newline-delimited output. In agent mode, which means standard output is not a terminal or a `--format` flag is present, a generated command prints its progress events ahead of its result. With `--format json` the output lists the events and then the response body: a JSON array, or, when the response links to resources the CLI can read, an object with numbered keys and a `cta` key. With `--format jsonl` each event and the result is its own `chunk` line, followed by a `done` line. Read the last numbered entry, or the last `chunk` line, before you pass the body to another program. A terminal run without `--format` prints only the result on standard output and sends progress to standard error.

The `format` config key accepts `toon`, `json`, `yaml` and `md`, and it is read by `dalp config` only: the installed CLI selects its output format from `--format` alone, so pass the flag on every command whose output a script parses. `jsonl` is a per-call format and is not a stored value.

## Next steps [#next-steps]

- [CLI commands](https://docs.settlemint.com/docs/api-reference/cli/commands) covers the generated command tree, how to discover a command you do not already know, and how to wait for on-chain settlement.
- [Using the CLI with AI agents](https://docs.settlemint.com/docs/api-reference/cli/ai-agents) covers running `dalp` from an MCP client or a coding agent's shell.


# Docs for AI agents

Source: https://docs.settlemint.com/docs/api-reference/docs-for-agents
Choose between the llms.txt index, the full corpus, a markdown page, the OpenAPI documents, the MCP endpoint and search, and handle each one's failures.

The documentation site serves every page to software over public, read-only addresses. None of them needs a sign-in.

An agent can read the page index, one page as markdown, all pages in one file, the pages that match a query, or the OpenAPI documents. It can also call a Model Context Protocol server, MCP for short, that serves the documentation pages through tools.

This page covers reading the documentation. To let an agent operate DALP, see [CLI for AI agents](https://docs.settlemint.com/docs/api-reference/cli/ai-agents), whose `dalp --mcp` server runs `dalp` commands against the Platform API, or [Hosted MCP server](https://docs.settlemint.com/docs/api-reference/cli/hosted-mcp), which runs inside a DALP deployment.

The addresses on this page are relative to the documentation host, `https://docs.settlemint.com`. A DALP deployment also serves its own copy of the pages under `/docs` on its hostname. To call your own deployment, keep the path and replace the host. That copy builds these absolute links from the host in its `PUBLIC_URL` environment variable:

- the `llms.txt` and `llms-full.txt` indexes
- the `Source:` line of each markdown page
- the canonical `Link` header of each markdown response
- the canonical and Open Graph tags of each page
- the URLs that MCP `search` and `list_pages` return

The DALP Helm chart sets `PUBLIC_URL` from the hostname that serves the documentation, unless the operator overrides it. [Documentation host](https://docs.settlemint.com/docs/deployment/install/values-secrets#documentation-host) explains how the chart picks it.

Call these addresses from a script or a server-side client. The MCP and search endpoints answer 403 when a request has `Sec-Fetch-Site: cross-site` or an `Origin` header for another origin. They send no cross-origin resource sharing headers, so a page on another origin cannot call them. The 403 body is the plain text `Forbidden`, not JSON-RPC.

## Choose an endpoint [#choose-an-endpoint]

| Your agent has | Call | Returns | Rate limit |
| --- | --- | --- | --- |
| No page in mind | `GET` [`/docs/llms.txt`](https://docs.settlemint.com/docs/llms.txt) or [`/llms.txt`](https://docs.settlemint.com/llms.txt) | A plain text index of every page. It ends with an "Agent endpoints" section that lists the other addresses. | None |
| A large context and wants everything | `GET` [`/docs/llms-full.txt`](https://docs.settlemint.com/docs/llms-full.txt) or [`/llms-full.txt`](https://docs.settlemint.com/llms-full.txt) | Every page as markdown in one plain text file. It is several megabytes. | None |
| The path of one page | `GET /docs/<path>.md`, or `GET /docs/<path>` with `Accept: text/markdown`, for example [`/docs/api-reference/webhooks/consuming.md`](https://docs.settlemint.com/docs/api-reference/webhooks/consuming.md) | The page as markdown | None |
| The API contract | `GET` [`/docs/api-reference/openapi-v2.json`](https://docs.settlemint.com/docs/api-reference/openapi-v2.json) or [`/docs/api-reference/openapi-v1.json`](https://docs.settlemint.com/docs/api-reference/openapi-v1.json) | The OpenAPI document as JSON | None |
| An MCP client | `POST /docs/api/mcp`. A `GET` answers 405. | The tools `list_pages`, `get_page` and `search` | 60 requests per minute |
| Words, not a path | `GET /docs/api/search?query=<terms>`, for example [`/docs/api/search?query=webhook`](https://docs.settlemint.com/docs/api/search?query=webhook) | Matching pages and text fragments as JSON | 300 requests per minute |

A crawl can read the index, then fetch each page with `.md`. The links in the table open the public host.

The OpenAPI documents in the table are the contract built with this documentation. To generate a client for a running deployment, fetch that deployment's own `/api/v2/spec.json`, as [the API reference overview](https://docs.settlemint.com/docs/api-reference) describes.

## Page markdown [#page-markdown]

A page answers as markdown in two ways. Append `.md` to the page path, or send `Accept: text/markdown` to the page URL. The root page `/docs` is the exception: its `.md` address is `/docs/index.md`. Both forms return the same markdown with the same headers.

```bash
DOCS=https://docs.settlemint.com

curl -sSD - "$DOCS/docs/api-reference/webhooks/consuming.md"
curl -sSD - -H 'Accept: text/markdown' "$DOCS/docs/api-reference/webhooks/consuming"
```

Both calls return `200` and a markdown body that starts with a `# Title` line and a `Source:` line with the canonical URL. The headers that matter to a client are:

```http
Content-Type: text/markdown; charset=utf-8
Link: <https://docs.settlemint.com/docs/api-reference/webhooks/consuming>; rel="canonical"
Vary: Accept
Cache-Control: public, max-age=300, s-maxage=900, stale-while-revalidate=3600
```

For the `Accept` form, the types `text/markdown`, `text/x-markdown` and `text/plain` count as markdown. A q-value is the weight from 0 to 1 that a client gives a type, and 1 is the default. Markdown wins when the highest q-value among the markdown types is greater than 0 and at least the highest q-value among `text/html`, `text/*` and `*/*`. A request with no `Accept` header, or with `*/*` alone, returns the HTML page.

An HTML response for a page that has a markdown form includes `Link: </docs/<path>.md>; rel="alternate"; type="text/markdown"`, which points an agent to that form. An unknown page has no markdown form, so its HTML response has no such header.

The two forms differ only when a page has no markdown form:

| Page state | `.md` suffix | `Accept: text/markdown` alone |
| --- | --- | --- |
| Page at its present path | 200 markdown | 200 markdown |
| Moved, so the old path redirects | 301 to the new `.md` path | 406 JSON |
| Unknown | 404 markdown | 406 JSON |
| API explorer, such as `/docs/api-reference/v2` | 200 markdown | 200 markdown |

The 404 body for an unknown page reads:

```markdown
# Page not found

No markdown page exists at /docs/no/such/page. The index at /docs/llms.txt lists every page.
```

The 406 body is `{"error":"Only HTML requests are supported here"}`. To get the HTML answer instead, add the HTML type to the header: `Accept: text/markdown, text/html;q=0.9`. A moved page then answers 301 to its new HTML path, and an unknown path answers 404 HTML.

## MCP endpoint [#mcp-endpoint]

`POST /docs/api/mcp` is a Model Context Protocol server over streamable HTTP, which lets the server answer a request with an event stream. Requests and replies use JSON-RPC, a JSON message format for remote procedure calls. The public site serves the endpoint at `https://docs.settlemint.com/docs/api/mcp`. Each request stands alone: there is no session.

This section describes requests in the protocol revisions up to 2025-11-25, which have no `_meta` envelope. The `MCP-Protocol-Version` header is optional for them. A request that names an older revision the server does not support gets 400, and the error message lists the supported older revisions. Revision 2026-07-28 uses a different request format, with its own headers and a `_meta` envelope in `params`. This page does not describe it. A request in that format that breaks its rules gets 400 with a JSON-RPC error code.

A request needs three things:

- `Content-Type: application/json`. Another type gets 415.
- An `Accept` header that lists both `application/json` and `text/event-stream`. `*/*` does not count, and a request without both gets 406.
- The `POST` method. `GET` and `DELETE` answer 405.

`tools/call` works without an earlier `initialize` call. This request uses the `DOCS` variable from [Page markdown](https://docs.settlemint.com/docs/api-reference/docs-for-agents#page-markdown) and asks for a page that does not exist:

```bash
curl -sS -X POST "$DOCS/docs/api/mcp" \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call",
"params":{"name":"get_page","arguments":{"url":"/docs/no/such/page"}}}'
```

The reply is an event stream with one message, and the response sends `Cache-Control: no-cache, no-transform`:

```text
event: message
data: {"result":{"content":[{"type":"text","text":"page not found: /docs/no/such/page"}],"isError":true},"jsonrpc":"2.0","id":1}
```

The server offers three tools. Send `tools/list` for the exact input schemas.

| Tool | Arguments | Notes |
| --- | --- | --- |
| `list_pages` | None | The page index, with a `.md` URL for each page. |
| `get_page` | `url` | The page as markdown, starting with a `# Title` line and a `Source:` line. `url` is a `/docs/...` path, or a full URL on the origin in `PUBLIC_URL`, with or without `.md`. A `/docs/...` path works whichever host `PUBLIC_URL` names. |
| `search` | `query`, optional `locale` | Up to 60 matching records as JSON text. See [Search endpoint](https://docs.settlemint.com/docs/api-reference/docs-for-agents#search-endpoint). |

`get_page` reports a problem in the result, not in the HTTP status, which stays 200 with `isError` set to `true`. A missing page gives the text `page not found: <input>`. The same result comes back for a URL on another host, a moved page and an API explorer page, because `get_page` reads only documentation pages at their present path, and an API explorer page is not one of them. Read an API explorer page with `.md`.

A missing or mistyped argument gives `Input validation error: ...` with the same `isError`.

A request for a tool that does not exist returns a JSON-RPC `error` object with code `-32602` in place of `result`. A body that is not valid JSON gets 400.

## Search endpoint [#search-endpoint]

`GET /docs/api/search?query=<terms>` matches page titles, descriptions, headings and body text, and returns a JSON array.

A page whose title holds every searched word comes before a page that only mentions them. Title words match whole and ignore case and accents, without stemming. The last word may be half typed, from two letters. Only the first 201 records the engine finds are reordered.

Each matched page gives one record for the page and up to eight records for text fragments on it. Every record has `id`, `type`, `content` and `url`. A page record has `type` set to `page`, the page title in `content` and a `breadcrumbs` list. A fragment record has `type` set to `heading` or `text` and a `url` that usually ends in an anchor. A `heading` record has the heading text in `content`. A `text` record has the text fragment in `content`. A `text` record that comes from a table row holds the header row and that row as a markdown table in `content`, and has a `table` key that names the table. This request uses the `DOCS` variable from Page markdown, holds the search to one section and raises the cap:

```bash
curl -sSD - "$DOCS/docs/api/search?query=retries&tag=api-reference&limit=100"
```

The reply sends `X-Docs-Search-Limit: 100` and an `X-Docs-Search-Truncated` header, and its body is an array of records. This is one page record from such a reply:

```json
{
  "id": "/docs/api-reference/webhooks/consuming",
  "type": "page",
  "content": "Consuming events",
  "breadcrumbs": ["Documentation", "API reference", "Webhooks"],
  "url": "/docs/api-reference/webhooks/consuming"
}
```

| Parameter | Effect |
| --- | --- |
| `query` | The terms to match. A missing or empty `query` returns 200 and `[]`. |
| `tag` | Holds the search to one section: `overview`, `getting-started`, `platform`, `console`, `concepts`, `deployment`, `api-reference`, `changelog` or `business`. `overview` holds the root page `/docs`, and `business` holds the privacy policy. `tag` takes one value. A list such as `&tag=a,b`, or an unknown value, returns `[]`. |
| `limit` | The maximum number of records, not pages. The default is 60. A value that is not a whole number of 1 or more falls back to 60, and a value over 200 becomes 200. |

Every 200 response reports the cap it applied in `X-Docs-Search-Limit`. `X-Docs-Search-Truncated: true` means more records exist: raise `limit` up to 200, then narrow the query or add `tag`. `false` does not prove the array holds every match, because a page contributes at most eight fragments. The endpoint has no offset, page or cursor parameter. Send only `query`, `tag` and `limit`: a search with a `query` and `mode=vector` answers 500, because the index holds no embeddings.

Three groups of error pages are not in the search index: the error index at `/docs/api-reference/errors`, and the two error references at `/docs/api-reference/errors/error-code-reference` and `/docs/api-reference/errors/platform-api-error-reference` with every code-range page under them. Find them through `llms.txt`, or open the error index and follow the link for the code's range.

The MCP `search` tool takes `query` and `locale`, and ignores `locale`. It has no `tag` and no `limit`: it returns at most 60 records, with a page whose title holds every searched word ahead of a page that only mentions them. Nothing in the reply says whether more records exist, so use the HTTP endpoint when you need to know whether the result was cut, or need more than 60 records.

MCP `search` records have full page URLs on the `PUBLIC_URL` host, such as `https://docs.settlemint.com/docs/api-reference/webhooks/consuming`, while `list_pages` returns `.md` URLs. `get_page` accepts both.

## Limits and freshness [#limits-and-freshness]

The MCP endpoint allows 60 requests per minute for each client, and search allows 300. Both budgets count HTTP requests, not tool calls. The `initialize` and `tools/list` calls each use one request, and so does a `GET` that gets 405. A client over its budget gets status 429, the plain text body `Too many requests` and a `Retry-After` header in seconds. The 429 body is not JSON-RPC. The `Retry-After` value depends on the cause:

| `Retry-After` | Cause |
| --- | --- |
| Seconds until the client's window resets | The client used its own budget. |
| 60 | The server already tracks 10,000 clients and cannot add another. |
| 1 | The Redis store that all instances share is configured but unreachable. Every caller gets 429, whatever its own rate. |

The server counts a client by the address that a configured trusted proxy forwards. A deployment with no trusted proxy configured counts every caller as one client, and all callers share one budget. A request whose forwarded address is missing or invalid also counts against that shared budget. The default install sets `DOCS_CHAT_TRUSTED_PROXY`, the setting that names the trusted proxy for these budgets and for the docs chat, to `none`, as [Ask AI provider key](https://docs.settlemint.com/docs/deployment/install/values-secrets#ask-ai-provider-key) in the install values reference describes. A 429 can then come from other callers' traffic: wait for `Retry-After` before you send again. On a deployment behind Cloudflare that sets `DOCS_CHAT_TRUSTED_PROXY` to `envoy`, the server counts each caller by the address Cloudflare adds to `X-Forwarded-For` when the operator has configured Envoy Gateway as [Count readers separately behind Cloudflare](https://docs.settlemint.com/docs/deployment/install/values-secrets#count-readers-separately-behind-cloudflare) describes. Otherwise callers that arrive through the same Cloudflare address share a budget. A deployment that has no Redis store keeps a separate budget on each server instance.

Three kinds of `200` response send `Cache-Control: public, max-age=300, s-maxage=900, stale-while-revalidate=3600`: markdown pages in either form, the `llms.txt` and `llms-full.txt` files at both the `/docs/...` path and the root path, and the two OpenAPI JSON files. Error responses, redirects and search replies send none, and MCP event-stream replies send `Cache-Control: no-cache, no-transform`. A browser or agent can reuse a response for 5 minutes. A shared cache holds it fresh for 15 minutes and can serve it for up to 60 more minutes while it fetches a new copy, so an answer can be 75 minutes behind the server.

The server builds `llms-full.txt` on the first request after it starts and reuses that text until it restarts, so the first request takes longer than the ones after it.

## When a request fails [#when-a-request-fails]

Every endpoint on this page only reads, so any request is safe to send again. Retry a `429` after its delay, and retry a `5xx` or a timeout with your own backoff. Fix the request and resend for `400`, `403`, `405`, `406` and `415`. Do not retry a `404` or an `isError` result with the same input. A search with a `query` and `mode=vector` answers `500` every time, so remove `mode` instead of retrying.

| Symptom | Cause and fix |
| --- | --- |
| `.md` answers 404 with "Page not found" | No page exists at that path. Look the path up in `llms.txt`. |
| `Accept: text/markdown` answers 406 with `{"error":"Only HTML requests are supported here"}` | The page has no markdown form: it is moved or unknown. Add `text/html;q=0.9` to the header to see which: 301 is moved and 404 HTML is unknown. |
| `.md` answers 301 | The page moved. Follow `Location`. |
| MCP answers 415 | The `Content-Type` is not `application/json`. |
| MCP answers 406 | `Accept` lacks `application/json` or `text/event-stream`, or is `*/*`. |
| MCP answers 405 | The request used `GET` or `DELETE`. Use `POST`. |
| MCP answers 400 | The body is not valid JSON, is JSON that is not a JSON-RPC message, the `MCP-Protocol-Version` header names an unsupported revision, or a 2026-07-28 request breaks that revision's rules. |
| MCP or search answers 403 | The request came from another site: it has an `Origin` header for another origin or `Sec-Fetch-Site: cross-site`. Call from a server-side client. |
| MCP result has `isError: true` and `page not found` | The page is missing, moved, on another host or an API explorer page. Check the path in `llms.txt`, and read a moved page or an API explorer page with `.md`. |
| MCP result has `isError: true` and `Input validation error` | An argument is missing or has the wrong type. Match the tool definition from `tools/list`. |
| MCP answers a JSON-RPC error `-32602` | The tool name is wrong or missing or `arguments` is not an object. Send `tools/list`. |
| Search answers 500 | The request has a `query` and `mode=vector`, and the index holds no embeddings. Remove `mode`. |
| Search returns `[]` for `tag=a,b`, an unknown tag or an empty `query` | `tag` takes one value from the list in [Search endpoint](https://docs.settlemint.com/docs/api-reference/docs-for-agents#search-endpoint). `query` is required. |
| The error index, an error reference or a code-range page is missing from search | Those pages are not indexed. Use `llms.txt`, or open `/docs/api-reference/errors` and follow the link for the code's range. |
| MCP or search answers 429 | Wait for `Retry-After`. See [Limits and freshness](https://docs.settlemint.com/docs/api-reference/docs-for-agents#limits-and-freshness). |
| A new page is missing from a cached response | A shared cache can be 75 minutes behind. See [Limits and freshness](https://docs.settlemint.com/docs/api-reference/docs-for-agents#limits-and-freshness). |

## Related [#related]

- [CLI for AI agents](https://docs.settlemint.com/docs/api-reference/cli/ai-agents): run the `dalp` client from an agent.
- [API explorer](https://docs.settlemint.com/docs/api-reference/v2): browse the v2 OpenAPI contract.
- [API reference overview](https://docs.settlemint.com/docs/api-reference): authenticate and integrate the Platform API.


# DALP-1000 to DALP-1049

Source: https://docs.settlemint.com/docs/api-reference/errors/error-code-reference/dalp-1000-1049
Cause, fix and retry flag for every on-chain contract error with a code from DALP-1000 to DALP-1049.

This page lists the 49 errors in the contract error reference with a code from DALP-1000 to DALP-1049. Match the error's `id`, or its `dalpCode` on a contract error or a failed deployment step, for example `DALP-1001`, to the DALP Code column, then read Retryable and Suggested Fix. The [contract error reference](https://docs.settlemint.com/docs/api-reference/errors/error-code-reference#how-to-use-this-reference) explains each column, including Severity, and the [DALP error index](https://docs.settlemint.com/docs/api-reference/errors) lists the page for every code range.

| DALP Code | Message | Why | Suggested Fix | Severity | Retryable | Solidity Error |
| --- | --- | --- | --- | --- | --- | --- |
| DALP-1001 | Bond already matured. | The contract already matured this bond. It blocks a second call to mature() and also blocks any non-forced transfer to a non-zero address once the bond reaches the matured state, because tokens can only be redeemed at that point. | Read the isMatured flag on the bond before calling mature(). If the bond is already matured, redeem tokens directly instead of calling mature() again. | error | No | `BondAlreadyMatured()` |
| DALP-1002 | Bond maturity date must be in the future. | The contract checks that the supplied maturity date is strictly greater than the current block timestamp at initialization. A maturity date at or before the current block timestamp causes the contract to revert. | Supply a maturity date that is at least one second ahead of the expected block timestamp when the transaction confirms. Check the current on-chain timestamp before constructing the bond parameters. | error | No | `BondInvalidMaturityDate()` |
| DALP-1003 | Bond has not matured. | `mature()` was called before the bond's maturity date, or a redemption was attempted before the bond was matured. Passing the maturity date does not mature the bond. A holder of the governance role must call `mature()`. | Before the maturity date, wait for it. After it, ask a governance-role holder to call `mature()`, then redeem. | error | No | `BondNotYetMatured(uint256,uint256)` |
| DALP-1004 | Bytes feeds not supported. | The registration passes feed kind BYTES. The feeds directory registers SCALAR feeds only. | Register the feed with kind SCALAR. | error | No | `BytesFeedsNotSupported()` |
| DALP-1005 | Caller must have identity. | The caller's wallet address has no identity contract registered in the identity registry for this token. The transfer-approval compliance module requires the caller to hold a registered on-chain identity before granting or revoking approvals. | Register an on-chain identity for the caller's wallet through the identity registry before attempting to create or revoke a transfer approval. | error | No | `CallerMustHaveIdentity()` |
| DALP-1006 | Caller not identity owner. | Self-service registration binds an identity to the caller's own wallet. The wallet being registered is not the caller, or it holds no MANAGEMENT_KEY on the identity contract. | Register from the wallet itself, or use the signed registration, and give that wallet a MANAGEMENT_KEY on the identity contract. | error | No | `CallerNotIdentityOwner()` |
| DALP-1007 | Cannot transfer converted tokens. | The token uses the MarkConverted debt-reduction method, which keeps source tokens on the holder's balance after conversion but marks them as encumbered. The contract tracks the holder's converted token count and blocks any transfer or burn that would move tokens beyond the unconverted portion. | Reduce the transfer or burn amount to at most the holder's unconverted balance. The unconverted balance equals the holder's total token balance minus the amount already converted. Check the current converted total on-chain before resubmitting. | error | No | `CannotTransferConvertedTokens(uint256,uint256)` |
| DALP-1008 | Cannot withdraw sale token. | The token sale contract restricts fund withdrawal to accepted payment currencies only. The sale token itself cannot pass through this path because withdrawing it would drain the pool of tokens held for distribution to investors. | To recover unsold sale tokens after the sale ends, use the dedicated unsold-token withdrawal call rather than withdrawFunds. Pass a payment currency address, not the sale token address, to withdrawFunds. | error | No | `CannotWithdrawSaleToken()` |
| DALP-1009 | Compliance check failed: `{{reason}}`. | A V1 compliance module's pre-transfer check ran and found the proposed operation does not satisfy its rules. The module reverted with a descriptive reason, which the platform captures as the compliance reason. Each compliance module enforces its own rule set, so this reason describes the specific constraint. | Read the compliance reason to identify which compliance rule the module applied. Resolve the underlying condition (for example, ensure the party has the required identity claims or is not on a block list), then resubmit. | error | No | `ComplianceCheckFailed(string)` |
| DALP-1010 | Compliance implementation not set. | The system's compliance implementation address is zero. System initialisation and bootstrap need it, and `setComplianceImplementation` refuses the zero address. | Call `setComplianceImplementation` with a non-zero compliance implementation address, then retry. | error | No | `ComplianceImplementationNotSet()` |
| DALP-1011 | Compliance module already registered. | A compliance module with the same type identifier (derived from its name) already exists in the compliance module registry. Each compliance module type must have a unique registration. | Check the existing registry for a module with the same name before registering. To update an existing module, use the update path rather than registering again. | error | No | `ComplianceModuleAlreadyRegistered(string)` |
| DALP-1012 | Compliance module registry implementation not set. | The compliance module registry logic contract address is absent from the system configuration. Operations that require the registry revert until the system stores this address. | Set the compliance module registry implementation address in the system configuration before bootstrapping or operating on compliance modules. | error | No | `ComplianceModuleRegistryImplementationNotSet()` |
| DALP-1013 | Contract identity topic id not set. | The contract identity topic ID passed to ensureContractIdentityClaimIsSet is zero. The topic ID must be a non-zero value from the topic scheme registry to issue a CONTRACT_IDENTITY claim. | Retrieve the correct CONTRACT_IDENTITY topic ID from the topic scheme registry and pass it as the contractIdentityTopicId argument. | error | No | `ContractIdentityTopicIdNotSet()` |
| DALP-1014 | Contract missing identity interface. | The contract address passed to createContractIdentityFor lacks the IContractWithIdentity interface. The factory checks this via ERC165 supportsInterface before creating an identity. | Ensure the target contract implements IContractWithIdentity and registers its interface ID via ERC165. Confirm the contract address is correct before calling. | error | No | `ContractMissingIdentityInterface(address)` |
| DALP-1015 | Empty token type. | The tokenType string provided to the external token registry is empty. The registry requires a non-empty type string for every token registration or type update. | Provide a non-empty tokenType string that describes the category of the external token you are registering or updating. | error | No | `EmptyTokenType()` |
| DALP-1016 | Exceeds unconverted balance. | The conversion amount exceeds the holder's remaining unconverted principal balance. Under the MarkConverted debt method the contract tracks how much principal the holder already converted, and the requested amount exceeds what remains. | Read the holder's unconverted balance before converting. Pass an amount no greater than the unconverted remainder, or pass 0 to convert the full remaining unconverted balance in one call. | error | No | `ExceedsUnconvertedBalance(uint256,uint256)` |
| DALP-1017 | External token registry implementation not set. | The external token registry logic contract address is absent from the system configuration. The system needs this address before the external token registry can bootstrap. An update that sets the address to zero is refused with the same error. | Set the external token registry implementation address in the system configuration before bootstrapping or using the external token registry. | error | No | `ExternalTokenRegistryImplementationNotSet()` |
| DALP-1018 | Feature token mismatch. | The feature contract's token() returns an address different from the token under configuration. Each feature contract is deployed and bound to a specific token, and the contract rejects features bound to a different token. | Deploy a feature contract pointing to this specific token address, or verify that the feature address you are passing targets this token and not a different one. | error | No | `FeatureTokenMismatch(address)` |
| DALP-1019 | Fee rate frozen. | A governance call to freezeFeeRate() froze the AUM fee rate and fee recipient on this fee feature. The freeze cannot be lifted on this feature. | Replace the feature with a new one through the token's governance role. | error | No | `FeeRateIsFrozen()` |
| DALP-1020 | Fee rates frozen. | A governance call to freezeFeeRates() froze the fee rates on this fee feature. A transaction fee keeps its recipient configurable. An accounting fee locks its recipient with the rates. | Change only a transaction fee's recipient on this feature, or replace the feature with a new one through the token's governance role. | error | No | `FeeRatesAreFrozen()` |
| DALP-1021 | Feed already exists. | A feed is already registered for the given subject address and topicId combination. The feeds directory prevents duplicate feed registrations for the same subject and topic. | Call `replaceFeed` from an account that holds `FEEDS_MANAGER_ROLE` to swap the existing feed, or register under a different subject or topic ID. | error | No | `FeedAlreadyExists(address,uint256)` |
| DALP-1022 | No feed exists for this subject and topic. | The feeds directory holds no feed for the given subject address and topicId combination. The operation requires an existing feed entry at that location. | Register a feed for this subject and topicId first, then retry the update or lookup. Confirm the subject address and topicId are correct. | error | No | `FeedNotFound(address,uint256)` |
| DALP-1023 | Feeds directory implementation not set. | The feeds directory implementation address was absent from the system when bootstrapFeedsDirectory ran. The system needs a non-zero implementation address before it can deploy the feeds directory proxy. | Set the feeds directory implementation with `setImplementation` for `FEEDS_DIRECTORY` from an account that holds `SYSTEM_MANAGER_ROLE`, then call `bootstrapFeedsDirectory` again. | error | No | `FeedsDirectoryImplementationNotSet()` |
| DALP-1024 | Fees frozen. | A governance call to freezeFees() froze the external transaction fee configuration on this fee feature. The fee amounts, fee recipient and fee token cannot change on this feature. | Replace the feature with a new one through the token's governance role. | error | No | `FeesAreFrozen()` |
| DALP-1025 | Freeze amount exceeds available balance. | The requested freeze amount is larger than the holder's available (unfrozen) token balance. The custodian calculates available balance as total balance minus already-frozen tokens, and the requested amount exceeds that. | Read the holder's current balance and frozen amount before freezing. The freeze amount must be no greater than (totalBalance - alreadyFrozen). Reduce the requested freeze amount accordingly. | error | No | `FreezeAmountExceedsAvailableBalance(uint256,uint256)` |
| DALP-1026 | Global compliance not available. | The system's global compliance contract address is absent from the configuration. Token compliance creation requires a deployed global compliance contract in the system before the platform can create any per-token compliance proxy. | Confirm that the system completed full bootstrap with a global compliance implementation before creating token compliance. Contact your platform administrator to verify the system configuration. | error | No | `GlobalComplianceNotAvailable()` |
| DALP-1027 | Historical balances not available. | Dividend and fixed treasury yield need the token's historical balances, either built into the token or from an attached historical-balances feature. This token has neither. | Attach the historical-balances feature to the token, then attach the yield feature. | error | No | `HistoricalBalancesNotAvailable()` |
| DALP-1028 | Identity already accepted. | The address `{{userAddress}}` already holds an identity in accepted (fully registered) state. The contract applies the accept step only to identities currently in the pending state, and `{{userAddress}}` has already passed that step. | Query the identity registry to confirm the current registration status for `{{userAddress}}`. The contract requires no further acceptance step for this address. | error | No | `IdentityAlreadyAccepted(address)` |
| DALP-1029 | Identity already exists. | The identity storage contract already holds an identity contract for the address `{{userAddress}}`. The registry stores each address only once. | Use the address lookup API to retrieve the existing identity for `{{userAddress}}` rather than attempting a second registration. | error | No | `IdentityAlreadyExists(address)` |
| DALP-1030 | Identity already registered. | The address `{{userAddress}}` already has an identity association in the registry, either in pending or accepted state. The registry prevents duplicate registrations across both states to maintain a one-identity-per-address invariant. | Use the identity registry read API to check the current state for `{{userAddress}}` before attempting registration. If a pending identity exists and you hold the appropriate role, you can accept it rather than re-registering. | error | No | `IdentityAlreadyRegistered(address)` |
| DALP-1031 | Identity already set. | The token sale contract already has an on-chain identity address set and enforces a write-once policy. The contract blocks any attempt to assign a different identity after the first assignment. | Read the current on-chain identity address from the token sale contract. If the contract already holds the correct identity, no further step is required. | error | No | `IdentityAlreadySet()` |
| DALP-1032 | Identity factory implementation not set. | The system holds no identity factory implementation address. The system requires a deployed identity factory logic contract before creating identity proxies during bootstrap or token deployment. | Register the identity factory implementation address in the system before retrying. A platform administrator must complete this configuration step during system setup. | error | No | `IdentityFactoryImplementationNotSet()` |
| DALP-1033 | Identity implementation not set. | The identity logic contract address has not been set in the identity factory. Proxy creation requires the factory to hold a reference to a deployed identity implementation contract. | Set the identity implementation address in the identity factory before creating identity proxies. A platform administrator must complete this configuration step during platform setup. | error | No | `IdentityImplementationNotSet()` |
| DALP-1034 | Identity not pending. | The address `{{userAddress}}` does not have an identity in the pending state, so the contract cannot accept it. The address either has no identity associated with it at all, or the contract already accepted it previously. | Register a pending identity for `{{userAddress}}` first using the pending registration call, then retry the accept step. Use the identity registry read API to confirm the current state. | error | No | `IdentityNotPending(address)` |
| DALP-1035 | Identity not registered. | The address `{{userAddress}}` has no accepted (fully registered) identity in the registry. The operation requires the address to be present in the accepted identity storage layer. | Register and accept an identity for `{{userAddress}}` before retrying this operation. Use the identity registry read API to confirm the registration state. | error | No | `IdentityNotRegistered(address)` |
| DALP-1036 | Identity registry already bound. | The registry at `{{registryAddress}}` is already bound to the identity registry storage contract. Each identity registry can be bound only once to prevent duplicate bindings. | Use the bound registries read API to verify the current binding state for `{{registryAddress}}`. No further step is required if the binding is already correct. | error | No | `IdentityRegistryAlreadyBound(address)` |
| DALP-1037 | Identity registry implementation not set. | The system holds no identity registry logic contract address. The system cannot deploy or reference an identity registry until an administrator registers an implementation address. An update that sets the address to zero is refused with the same error. | Register the identity registry implementation address in the system configuration before retrying. Completing this step requires platform administrator access. | error | No | `IdentityRegistryImplementationNotSet()` |
| DALP-1038 | Identity registry not bound. | The registry at `{{registryAddress}}` is not currently bound to the identity registry storage contract. The unbind operation requires the registry to have been bound previously. | Verify that `{{registryAddress}}` was successfully bound before attempting to unbind it. Use the bound registries read API to confirm the current state. | error | No | `IdentityRegistryNotBound(address)` |
| DALP-1039 | Identity registry storage implementation not set. | The system holds no identity registry storage logic contract address. The system requires an identity registry storage implementation before deploying the registry storage proxy. An update that sets the address to zero is refused with the same error. | Register the identity registry storage implementation address in the system configuration before bootstrapping. Completing this step requires platform administrator access. | error | No | `IdentityRegistryStorageImplementationNotSet()` |
| DALP-1040 | The token's collateral does not cover this mint. | The token's collateral claim covers `{{available}}` units but minting this amount would require `{{required}}` units of collateral backing. The contract enforces a configured collateral ratio against the post-mint total supply before each mint. | Obtain a new or updated collateral claim from a trusted issuer that covers at least `{{required}}` units, then retry the mint. Reduce the mint amount so that the post-mint total supply stays within the coverage of the existing claim. | error | No | `InsufficientCollateral(uint256,uint256)` |
| DALP-1041 | The contract does not hold enough of the denomination asset. | The contract holds `{{currentBalance}}` of the denomination asset but the operation needs `{{requiredBalance}}`. Bond maturity, bond redemption and a yield schedule withdrawal each check the contract's own balance. | Transfer denomination asset to the contract until it holds `{{requiredBalance}}`, or withdraw less from the schedule, then retry. | error | No | `InsufficientDenominationAssetBalance(uint256,uint256)` |
| DALP-1042 | The contract does not hold enough tokens for this operation. | The contract's token balance is below what the operation needs. An offering must hold its full hard cap before activation, and a token recovery cannot move more than the contract holds. | For an offering, transfer tokens to its contract until the balance reaches the hard cap. For a recovery, reduce the amount to what the contract holds. Then retry. | error | No | `InsufficientTokenBalance()` |
| DALP-1043 | The treasury does not hold enough to cover the redemption payout. | The treasury holds `{{available}}` of the denomination asset but needs `{{required}}`. `mature()` checks the payout for the whole supply. `redeem` checks the payout for this redemption. | Fund the treasury with at least `{{required}}` of the denomination asset, then retry. | error | No | `InsufficientTreasuryBalance(uint256,uint256)` |
| DALP-1044 | Collateral ratio exceeds the 200% ceiling. | The contract requires `ratioBps` to be at most 20,000 (200%). The value supplied is above that limit. | Supply a collateral ratio in basis points between 0 and 20,000 inclusive. A value of 0 disables collateral enforcement; 10,000 equals 100%. | error | No | `InvalidCollateralRatio(uint16)` |
| DALP-1045 | Collateral proof topic ID must be non-zero. | The contract treats topic ID 0 as unset and rejects it. A collateral proof topic must reference a real claim topic registered on-chain. | Supply a non-zero `uint256` topic ID that corresponds to a valid collateral proof claim topic. | error | No | `InvalidCollateralTopic(uint256)` |
| DALP-1046 | Compliance module address must be a non-zero contract address. | The compliance module registry rejects a zero address when a module is registered. A zero address indicates the module contract has not been deployed or was not provided. | Supply the deployed address of a compliance module contract. | error | No | `InvalidComplianceModuleAddress()` |
| DALP-1047 | Contract identity implementation does not support the required interface. | The identity factory validates that the contract identity implementation reports support for the `IDALPContractIdentity` interface via ERC-165. The provided address does not pass that check. | Supply the address of a deployed contract identity implementation that correctly implements `IDALPContractIdentity` and returns true from `supportsInterface`. | error | No | `InvalidContractIdentityImplementation()` |
| DALP-1048 | Fee rate exceeds the 100% maximum (10,000 basis points). | The AUM fee rate and the mint, burn and transfer fee rates cannot exceed 10,000 basis points (100%). One or more of the supplied rates is above that limit. | Supply fee rates in basis points where each value is between 0 and 10,000 inclusive. For example, 250 equals 2.5%. | error | No | `InvalidFeeRate()` |
| DALP-1049 | Fee recipient address must be a non-zero address. | The fee feature requires a valid recipient address to hold accrued fees. A zero address is rejected because fees cannot be sent to the null address. | Supply a non-zero Ethereum address that will receive collected fees. | error | No | `InvalidFeeRecipient()` |

The next page is [DALP-1050 to DALP-1099](https://docs.settlemint.com/docs/api-reference/errors/error-code-reference/dalp-1050-1099).


# DALP-1050 to DALP-1099

Source: https://docs.settlemint.com/docs/api-reference/errors/error-code-reference/dalp-1050-1099
Cause, fix and retry flag for every on-chain contract error with a code from DALP-1050 to DALP-1099.

This page lists the 50 errors in the contract error reference with a code from DALP-1050 to DALP-1099. Match the error's `id`, or its `dalpCode` on a contract error or a failed deployment step, for example `DALP-1050`, to the DALP Code column, then read Retryable and Suggested Fix. The [contract error reference](https://docs.settlemint.com/docs/api-reference/errors/error-code-reference#how-to-use-this-reference) explains each column, including Severity, and the [DALP error index](https://docs.settlemint.com/docs/api-reference/errors) lists the page for every code range.

| DALP Code | Message | Why | Suggested Fix | Severity | Retryable | Solidity Error |
| --- | --- | --- | --- | --- | --- | --- |
| DALP-1050 | Fee token must not be the token contract itself. | The external transaction fee feature does not allow the fee token to be the same contract as the token being transferred or this contract's own address. Using the same token for fees would create circular dependency in transfers. | Supply a different ERC-20 token address as the fee token. The zero address disables external transaction fee collection. | error | No | `InvalidFeeToken()` |
| DALP-1051 | Feed address must be a non-zero contract address. | The feeds directory rejects a zero address when registering or updating a feed. A valid feed must be deployed at a real contract address. | Supply the deployed address of a feed contract before submitting the registration or update request. | error | No | `InvalidFeedAddress()` |
| DALP-1052 | Feed contract must implement the required price feed interface. | The feeds directory calls `decimals()` and `latestRoundData()` on the provided feed address to verify it conforms to the expected price feed interface. The contract at the supplied address did not respond correctly to one or both of those calls. | Supply the address of a feed contract that fully implements the required price feed interface, including `decimals()` returning a 32-byte value and `latestRoundData()` returning 160 bytes. | error | No | `InvalidFeedInterface(address)` |
| DALP-1053 | Identity contract must implement the IIdentity interface. | The identity registry checks via ERC-165 that the supplied contract implements `IIdentity`. The contract at the provided address either does not support ERC-165 or explicitly returns false for the `IIdentity` interface ID. | Supply the address of an on-chain identity contract that implements `IIdentity` and returns true from `supportsInterface` for that interface ID. | error | No | `InvalidIdentityContract()` |
| DALP-1054 | Identity factory address must be a non-zero address that implements the factory interface. | The identity proxy constructor rejects a zero address and also rejects any address that does not report support for the `IDALPIdentityFactory` interface via ERC-165. | Supply the deployed address of a contract that implements `IDALPIdentityFactory` and returns true from `supportsInterface` for that interface ID. | error | No | `InvalidIdentityFactoryAddress()` |
| DALP-1055 | Identity implementation does not support the IDALPIdentity interface. | The identity factory checks via ERC-165 that the provided implementation address returns true for the `IDALPIdentity` interface ID. The supplied address does not pass this check. | Supply the address of a deployed identity implementation contract that fully implements `IDALPIdentity` and returns true from `supportsInterface`. | error | No | `InvalidIdentityImplementation()` |
| DALP-1056 | Identity registry address must be a non-zero address. | The identity registry storage rejects a zero address when binding an identity registry. Only a real, deployed registry contract address is accepted. | Supply a non-zero address of a deployed identity registry contract before calling `bindIdentityRegistry`. | error | No | `InvalidIdentityRegistryAddress()` |
| DALP-1057 | Wallet address must be a non-zero address. | The identity registry storage rejects a zero wallet address when adding, updating, or recovering identity records. Every identity record must be linked to a valid, non-zero wallet address. | Supply a non-zero Ethereum wallet address for the user whose identity record is being created or modified. | error | No | `InvalidIdentityWalletAddress()` |
| DALP-1058 | Redemption amount must be greater than zero. | The bond contract rejects a redemption call where the token amount is zero. A redemption must burn at least one token to release denomination assets. | Supply a positive token amount to redeem. The bond must also have reached maturity before redemption is possible. | error | No | `InvalidRedemptionAmount()` |
| DALP-1059 | Target identity address must be a non-zero address. | The system contract rejects a claim issuance request where the target identity address is the zero address. A claim can only be issued to a deployed on-chain identity contract. | Supply the address of the on-chain identity contract for the intended claim recipient. | error | No | `InvalidTargetIdentity()` |
| DALP-1060 | Token address must be a non-zero address. | The token sale factory and airdrop factory both reject a zero address when a token address is required. A zero address indicates the token has not been deployed or was not provided. | Supply the deployed address of the token contract for which the sale or airdrop is being created. | error | No | `InvalidTokenAddress()` |
| DALP-1061 | Token factory address must be a non-zero address. | The token factory registry rejects a zero address when registering or updating a factory implementation, and an update for a factory type that has no registered factory. A token proxy also rejects a factory address that is zero or does not implement `IDALPTokenFactory`. | Supply the deployed address of a token factory contract that implements `IDALPTokenFactory`. | error | No | `InvalidTokenFactoryAddress()` |
| DALP-1062 | Token implementation address must be a non-zero address. | When registering a token factory, the registry also requires a non-zero token implementation address. A zero address indicates the implementation contract has not been provided. | Supply the deployed address of a token implementation contract alongside the factory address. | error | No | `InvalidTokenImplementationAddress()` |
| DALP-1063 | Token implementation is not accepted by the factory's interface validation. | The token factory registry calls `isValidTokenImplementation` on the factory to verify the implementation is compatible. The factory returned false, meaning the implementation does not satisfy the factory's required interface or type constraints. | Supply a token implementation address that the associated factory's `isValidTokenImplementation` check accepts. | error | No | `InvalidTokenImplementationInterface()` |
| DALP-1064 | Issuer identity setup required. | The system's issuer identity contract does not exist yet. Operations that issue claims on behalf of the platform require the organisation identity to be deployed and registered during system bootstrap. | Complete system bootstrap, which deploys the organisation identity, before attempting claim issuance or other operations that depend on the issuer identity. | error | No | `IssuerIdentityNotInitialized()` |
| DALP-1065 | Maturity date in past. | The maturity date `{{provided}}` is in the past relative to the current block timestamp `{{current}}`. The contract requires the maturity date to be strictly in the future at the time of deployment or initialization to ensure redemptions become available at a future point. | Provide a maturity date that is strictly greater than the current block timestamp. Check the current on-chain timestamp before submitting the deployment parameters. | error | No | `MaturityDateInPast(uint256,uint256)` |
| DALP-1066 | Maturity date not reached. | You called `mature()` before the bond's configured maturity date arrived. The contract reads `maturityDate` from storage and compares it to the current block timestamp; when the timestamp is still earlier than `maturityDate`, the revert fires and returns both values. | Wait until `block.timestamp >= maturityDate` before calling `mature()`. The `maturityDate` value returned with this error (or readable from the bond contract) tells you the earliest timestamp at which the call will succeed. | error | Yes | `MaturityDateNotReached(uint256,uint256)` |
| DALP-1067 | Minting failed. | During a token conversion, the step that mints target tokens to the holder did not complete successfully. The conversion feature calls the target token's minter contract; if that call fails or the minter is misconfigured, the contract reverts to prevent issuing partial conversions. | Verify that the target token's conversion minter feature is correctly deployed and that the token's minter contract has authorized it. If the configuration looks correct, contact the token issuer to inspect the minter contract's state before retrying the conversion. | error | No | `MintingFailed()` |
| DALP-1068 | Net balance invariant violation. | After executing an XvP settlement, the contract checked that each asset's net positions across all participants sum to zero. At least one asset's net balance was not zero. | Construct the settlement flows so that every asset's total outflows equal its total inflows across all participants. Review the flow definitions for the asset address returned in this error and correct the amounts before resubmitting the settlement. | error | No | `NetBalanceInvariantViolation(address)` |
| DALP-1069 | No denomination asset balance. | You attempted to withdraw denomination asset from a fixed yield schedule, but the schedule contract holds no denomination asset balance. The contract checks the ERC-20 balance of the denomination asset before transferring and reverts when the balance is zero. | Fund the yield schedule with the denomination asset, then withdraw. | error | No | `NoDenominationAssetBalance()` |
| DALP-1070 | No fees to reconcile. | You called `reconcileFees()` on the transaction fee accounting feature, but the contract's `totalAccruedFees` counter is currently zero. The feature processes a reconciliation only when fee amounts have accumulated since the last reconciliation. | Reconciliation is only possible after at least one fee-bearing transfer, mint, or burn has occurred. Verify that fee-generating operations have taken place and that the accrued total is greater than zero before calling `reconcileFees()`. | error | No | `NoFeesToReconcile()` |
| DALP-1071 | No historical balances provider. | A query requiring historical balance data was made against a token that has no historical balances provider configured. The resolver checks both the ISMARTHistoricalBalances extension on the token itself and any registered IHistoricalBalancesFeature; neither was found for the token address returned in this error. | The token requires a historical balances extension or a historical balances feature before historical balance queries can succeed. Contact the token issuer to verify that the historical balances capability is configured on the token. | error | No | `NoHistoricalBalancesProvider(address)` |
| DALP-1072 | No tokens to recover. | You attempted to recover a token from an address that holds a zero balance of the target ERC-20. The contract checks the token balance before initiating recovery and reverts when there is nothing to recover. | Verify that the target address holds a non-zero balance of the token you are attempting to recover. Query the token balance on-chain before calling the recovery function. | error | No | `NoTokensToRecover()` |
| DALP-1073 | Not whitelisted. | The caller attempted to participate in a presale token purchase, but their address is not on the presale whitelist. The token sale contract enforces a whitelist during the presale phase; only addresses added by the sale operator can purchase during this period. | Contact the token sale operator to request inclusion on the presale whitelist. Once the operator adds your address, you can retry the purchase. Alternatively, wait for the presale to end and the public sale to begin, at which point the whitelist restriction is lifted. | error | No | `NotWhitelisted()` |
| DALP-1074 | Recipient address frozen. | A custodian froze the recipient's whole address on this token, so the token refused to deliver tokens to it. A mint or an ordinary transfer to a frozen address raises this error on every token contract. The DALP 3.2 token contract also raises it for a custodian's forced transfer into a frozen address, which every other token contract delivers. Recovering a lost wallet onto a frozen replacement wallet is not refused, and the freeze stays in place. | An authorized custodian must unfreeze the recipient's address before tokens can be delivered to it. Contact the token custodian or issuer to request that the recipient address be unfrozen. | error | No | `RecipientAddressFrozen()` |
| DALP-1075 | Recover insufficient balance. | An ERC-20 recovery call requested an amount larger than the contract's current balance of that token. The recovery function checks the contract balance before transferring and reverts when the balance is lower than the requested amount. | Reduce the recovery amount to at most the contract's current token balance, or split the recovery into smaller amounts. Query the contract's token balance first to determine the maximum recoverable amount. | error | No | `RecoverInsufficientBalance()` |
| DALP-1076 | Sender address frozen. | A custodian froze this address as a whole, so the token refused to move tokens out of it. A transfer from a frozen address raises this error on every token contract. The DALP 3.2 token contract also raises it for a burn from that address, whether a supply manager or a token feature burns. | Ask a custodian to unfreeze the address. To burn the units and keep the freeze, move them to an eligible wallet with a forced transfer and burn them there. | error | No | `SenderAddressFrozen()` |
| DALP-1077 | Token access manager implementation not set. | The system deployment step requires a token access manager implementation address, but none has been set in the system registry. The system contract checks this implementation slot before deploying or bootstrapping tokens and reverts when the slot is empty. An update that sets the address to zero is refused with the same error. | Set the token access manager implementation address in the system registry before retrying the deployment or bootstrap step. A holder of the SYSTEM_MANAGER_ROLE must complete this system configuration step. | error | No | `TokenAccessManagerImplementationNotSet()` |
| DALP-1078 | Token already bound. | The token is already bound. The system compliance contract refuses to bind a bound token again, and a token compliance contract refuses a second token while one is bound. | Call `isTokenBound(tokenAddress)` on the system compliance contract to check whether the token is already bound before attempting to bind it again. If it is already bound, no further step is needed. | error | No | `TokenAlreadyBound(address)` |
| DALP-1079 | Token already registered. | You submitted a token address to the external token registry's `registerToken` function, but the contract already records that address in its `_isRegistered` mapping. Each external token can only be registered once. | Check whether the token is already registered by calling `isRegistered(tokenAddress)` on the external token registry before attempting to register it again. If already registered and the type is wrong, use `updateTokenType` instead. | error | No | `TokenAlreadyRegistered(address)` |
| DALP-1080 | Token compliance already exists. | The token compliance factory received a `createTokenCompliance` call for a token address that already has a compliance contract recorded in its `_tokenCompliances` mapping. A token can only have one compliance contract created through this factory. | Retrieve the existing compliance contract address by calling `predictTokenComplianceAddress(tokenAddress)` on the compliance factory, or look up the address stored in the factory's mapping. Use the existing compliance contract rather than creating another. | error | No | `TokenComplianceAlreadyExists(address)` |
| DALP-1081 | Token compliance factory not available. | The V2 token factory's `_createTokenCompliance` helper resolved the token compliance factory proxy address from the system registry and found a zero address. The token compliance factory must be deployed and registered before V2 tokens can be created. | Deploy and register the token compliance factory in the system registry before deploying V2 tokens. A holder of the SYSTEM_MANAGER_ROLE must complete this system setup step. | error | No | `TokenComplianceFactoryNotAvailable()` |
| DALP-1082 | Token decimals too high. | The conversion feature factory checked the ERC-20 `decimals()` of the loan token or the target token and found a value greater than 18. The conversion's WAD-based pricing math requires both tokens to have at most 18 decimal places. | The token returned in this error has more than 18 decimals, which is incompatible with the conversion feature. Use a token with 18 or fewer decimals as either the loan token or the target token in the conversion configuration. | error | No | `TokenDecimalsTooHigh(address,uint8)` |
| DALP-1083 | Token factory registry implementation not set. | A system operation required the token factory registry implementation address, but the slot in the system registry is empty. The system contract checks this implementation slot during setup and bootstrap steps. An update that sets the address to zero is refused with the same error. | Set the token factory registry implementation address in the system registry before retrying the setup step. A holder of the SYSTEM_MANAGER_ROLE must complete this system configuration step. | error | No | `TokenFactoryRegistryImplementationNotSet()` |
| DALP-1084 | Token factory type name already registered. | A token factory type with the same name was already registered in the factory registry. The V1 registry uses a keccak256 hash of the type name as its key; if that key is already occupied, a second registration for the same name reverts. | Each token factory type name must be unique in the registry. Check the registered factory types before attempting to register, and use a distinct name if you are registering a new factory type. | error | No | `TokenFactoryTypeAlreadyRegistered(string)` |
| DALP-1085 | Token factory type ID already registered. | A token factory type with the same `typeId` (bytes32) was already registered in the V2 factory registry and is not in an archived state. The V2 registry allows unarchiving an archived entry under the same key but rejects a fully active duplicate registration. | Each token factory type identifier must be unique in the V2 registry. If you are trying to upgrade an existing factory, archive the old registration first. If you are registering a new type, use a distinct `typeId`. | error | No | `TokenFactoryTypeAlreadyRegisteredV2(bytes32)` |
| DALP-1086 | Token identity address mismatch. | During token deployment the factory computes a deterministic CREATE2 address for the token identity contract and then verifies the deployed address matches. The deployed identity address (deployedTokenIdentityAddress) does not match the predicted address (tokenIdentityAddress), meaning the factory's internal consistency check failed. | Adjusting request parameters cannot resolve this system-level deployment failure. Contact support with the deployedTokenIdentityAddress and tokenIdentityAddress values from the error. | error | No | `TokenIdentityAddressMismatch(address,address)` |
| DALP-1087 | Token implementation not set. | The token factory that deployed this token has no token implementation set, so the token proxy has nothing to forward calls to. | Set the token implementation on this token's factory with `updateTokenImplementation`. This takes the system manager role. | error | No | `TokenImplementationNotSet()` |
| DALP-1088 | Token does not support access management. | Token sales and airdrops read roles from the token, so the token must implement `ISMARTTokenAccessManaged`. ERC-165 reports that it does not. | Token sales and airdrops are only supported for tokens that implement the ISMARTTokenAccessManaged interface. Verify you are using the correct token address and that the token was deployed with access-management support enabled. | error | No | `TokenMustSupportAccessManaged()` |
| DALP-1089 | Token compliance contract has no bound token. | The per-token compliance contract has no token address bound to it. The compliance contract requires a bound token before it can process transfer checks or other operations. | The token compliance contract must be bound to a token address before use. The token factory performs this binding during deployment. If you see this error outside of a factory flow, contact support. | error | No | `TokenNotBound()` |
| DALP-1090 | Token is not bound to the system compliance contract. | The system compliance contract has no binding recorded for the token address provided. Transfer hooks and burn hooks require the token to be registered with the system compliance layer before the contract can process them. | The token must be bound to the system compliance contract first. For newly deployed tokens this happens during factory setup. For pre-existing tokens, use the batch binding migration path. Contact your platform operator if the binding is missing. | error | No | `TokenNotBound(address)` |
| DALP-1091 | Token not registered. | The external token registry does not contain the token address. Operations that read or update the token type require you to register the token first. | Register the token address in the external token registry before calling operations that require it. A TOKEN_MANAGER_ROLE holder can register the token via the registry's registration function. | error | No | `TokenNotRegistered(address)` |
| DALP-1092 | Transfer blocked after maturity. | The token matured. After maturity it refuses all mints and ordinary transfers. Burns, forced custodian transfers and fee movements still run. | Redeem the tokens, or move them with a forced custodian transfer. Minting is closed after maturity. | error | No | `TransferBlockedAfterMaturity(address,address)` |
| DALP-1093 | Caller is not a transfer approval authority. | The caller's on-chain identity is not in the list of configured approval authorities for this transfer approval compliance module. Only registered approval authorities can create, revoke, or consume transfer approvals. | Request that a system administrator add your identity as an approval authority for this module, then retry the operation. | error | No | `UnauthorizedApprover()` |
| DALP-1094 | Caller cannot create a feed for this subject. | Creating a feed requires FEEDS_MANAGER_ROLE, or GOVERNANCE_ROLE on the subject token for a token-scoped feed. A global feed accepts FEEDS_MANAGER_ROLE only. | Ask a feeds manager to create the feed, or get GOVERNANCE_ROLE on the subject token. | error | No | `UnauthorizedFeedCreation()` |
| DALP-1095 | Caller cannot create token sales. | Creating a token sale requires either the TOKEN_FACTORY_MODULE_ROLE at the system level or the GOVERNANCE_ROLE on the specific subject token. The caller holds neither role, so the factory rejects the request. | Obtain the GOVERNANCE_ROLE on the subject token or have a system administrator with TOKEN_FACTORY_MODULE_ROLE create the sale on your behalf. | error | No | `UnauthorizedTokenSaleCreation()` |
| DALP-1096 | The compliance rules blocked this transfer: the sender or recipient does not meet the token's requirements. | One of the token's compliance rules blocked the transfer. | Check both parties' identity registration and claims, then retry. | error | No | `TransferNotCompliant()` |
| DALP-1097 | Wallet not registered to this identity. | The identity recovery process verifies that the wallet you are reporting as lost is linked to the specified identity contract. The registry does not record that wallet address as belonging to that identity contract, so the recovery request cannot proceed. | Confirm the correct identity contract address for the wallet. Retrieve the wallet's registered identity from the identity registry and retry the recovery request with the matching identity contract address. | error | No | `WalletNotRegisteredToThisIdentity(address,address)` |
| DALP-1098 | Redemption amount or payout is zero. | The amount is zero, or after the transfer fee and the remaining payout budget the redemption pays nothing. `redeemForBatch` also raises it when `holders` and `amounts` differ in length or name more than 100 holders. | Redeem a positive amount that yields a payout. For a batch, pass arrays of equal length with at most 100 holders. | error | No | `ZeroRedemptionAmount()` |
| DALP-1099 | Feeds directory address is zero. | The price resolver contract requires a non-zero feeds directory address during initialization. The address passed to `initialize` was the zero address. | Supply the deployed feeds directory contract address when calling `initialize`. | error | No | `InvalidFeedsDirectory()` |

The previous page is [DALP-1000 to DALP-1049](https://docs.settlemint.com/docs/api-reference/errors/error-code-reference/dalp-1000-1049). The next page is [DALP-1100 to DALP-1199](https://docs.settlemint.com/docs/api-reference/errors/error-code-reference/dalp-1100-1199).


# DALP-1100 to DALP-1199

Source: https://docs.settlemint.com/docs/api-reference/errors/error-code-reference/dalp-1100-1199
Cause, fix and retry flag for every on-chain contract error with a code from DALP-1100 to DALP-1199.

This page lists the 38 errors in the contract error reference with a code from DALP-1100 to DALP-1199. Match the error's `id`, or its `dalpCode` on a contract error or a failed deployment step, for example `DALP-1100`, to the DALP Code column, then read Retryable and Suggested Fix. The [contract error reference](https://docs.settlemint.com/docs/api-reference/errors/error-code-reference#how-to-use-this-reference) explains each column, including Severity, and the [DALP error index](https://docs.settlemint.com/docs/api-reference/errors) lists the page for every code range.

| DALP Code | Message | Why | Suggested Fix | Severity | Retryable | Solidity Error |
| --- | --- | --- | --- | --- | --- | --- |
| DALP-1100 | This wallet is not associated with the expected identity. | The identity registry storage contract checked whether the given wallet is currently registered under the specified identity contract. The wallet's on-chain record points to a different identity, so the contract blocked the operation to prevent an incorrect lost-wallet marking. | Confirm your wallet is linked to the correct identity, or contact your administrator for assistance. | error | No | `WalletNotAssociatedWithIdentity(address,address)` |
| DALP-1101 | The account does not have enough tokens. Available: `{{available}}`, required: `{{required}}`. | The ERC-20 contract requires the account to hold at least the requested amount before a transfer or burn can proceed. For tokens with custodian controls, `{{available}}` can exclude a frozen portion of the balance. | Check the token balance and try again with a smaller amount, or acquire more tokens. | error | No | `ERC20InsufficientBalance(address,uint256,uint256)` |
| DALP-1102 | The token allowance is too low. Current allowance: `{{allowance}}`, required: `{{required}}`. | The ERC-20 contract requires a spender to have an approved allowance of at least the requested amount before it can transfer tokens on behalf of the owner. The current allowance is `{{allowance}}`, which is below the `{{required}}` needed for this transfer. | Approve a sufficient token allowance before retrying the operation. | error | No | `ERC20InsufficientAllowance(address,uint256,uint256)` |
| DALP-1103 | Contract paused. | An administrator paused this contract, which can be a token sale, a yield schedule or a dividend feature. It rejects purchases, claims and withdrawals until resumed. | Ask an administrator to resume the contract, then submit the operation again. | warning | No | `EnforcedPause()` |
| DALP-1104 | The account `{{account}}` does not have a registered identity on this platform. | The identity registry storage has no identity for `{{account}}`. Reading, updating or removing that account's identity needs one. | Register an identity for `{{account}}` first, or check the account address. | error | No | `IdentityDoesNotExist(address)` |
| DALP-1105 | The approved spending amount is not enough. Current: `{{currentAllowance}}`, required: `{{requiredAllowance}}`. | During settlement approval, the contract checks that the caller has approved enough of the asset token for the settlement contract to pull. The current allowance (`{{currentAllowance}}`) is less than the amount the settlement flow requires (`{{requiredAllowance}}`), so the contract cannot lock the tokens. | Increase the token allowance to cover the required amount, then try again. | error | No | `InsufficientAllowance(address,address,address,uint256,uint256)` |
| DALP-1106 | The amount exceeds the currently frozen token balance. Available: `{{available}}`, requested: `{{requested}}`. | The unfreeze request asks for more tokens (`{{requested}}`) than are currently held in the frozen balance for this address (`{{available}}`). The contract blocks the operation to prevent the frozen balance from going below zero. | Reduce the amount to at most the currently frozen balance, or freeze additional tokens first. | error | No | `InsufficientFrozenTokens(uint256,uint256)` |
| DALP-1107 | Identity contract address is zero. | The identity registry storage contract requires a non-zero identity contract address. The `_identity` argument passed to `addIdentityToStorage` or `updateIdentityToStorage` was the zero address. | Provide the deployed on-chain identity contract address for the wallet being registered. | error | No | `InvalidIdentityAddress()` |
| DALP-1108 | Settlement flow asset is not a valid ERC-20 token. | Each settlement flow must reference a non-zero token address that exposes the ERC-20 `decimals()` selector. | Set each flow's asset to a deployed ERC-20 token contract address and confirm the contract exposes `decimals()`. | error | No | `InvalidToken()` |
| DALP-1109 | The token's pause state does not allow this operation. | The token contract raises this error in two cases. The token is paused, and its whenNotPaused guard blocks transfers, mints and burns until an administrator resumes it; forced custodian operations are exempt. Or a halt (pause) was requested while the token is already paused. A token on an older implementation raises it for a resume (unpause) requested while the token is already active instead. | Read the token's pause state. If it is paused, submit the operation again after the token administrator resumes the token. If you asked to halt or resume it and it is already in that state, there is nothing to change. | warning | No | `TokenPaused()` |
| DALP-1110 | The compliance rules blocked this mint: the recipient does not meet the token's requirements. | One of the token's compliance rules blocked the mint. | Check the recipient's identity registration and claims, then retry. | error | No | `MintNotCompliant()` |
| DALP-1111 | Stale feed. | The price resolver read a feed whose last update timestamp is older than the configured maximum staleness window. The error returns the subject address, topic id, the feed's last updatedAt timestamp and the configured maxAge. | Wait for the price feed to receive a fresh update, then retry the operation. If the feed is consistently stale, contact the feed provider or your platform operator to investigate the oracle update frequency. | error | Yes | `StaleFeed(address,uint256,uint256,uint256)` |
| DALP-1112 | Token compliance creation failed. | The token factory called the token compliance factory to create a per-token compliance contract, but the factory returned the zero address instead of a deployed contract address. The token deployment cannot proceed without a valid compliance contract. | This is a system configuration failure. Contact your platform operator to verify that the token compliance factory is correctly deployed and that the directory points to it. | error | No | `TokenComplianceCreationFailed()` |
| DALP-1113 | Not factory token. | The migration call passed a token address that was not originally deployed by this factory. The factory tracks every token it created, and the provided address is absent from that record. | Ensure the token address belongs to this factory by checking the factory's token list. Only tokens this factory originally deployed can be migrated through it. | error | No | `NotFactoryToken(address)` |
| DALP-1114 | Only compliance engine. | An address other than the bound compliance engine called a configuration update on this module. The module restricts this operation to the engine contract it governs. | Configuration updates to this compliance module must be sent through the compliance engine that governs it. Call updateConfig via the engine, not directly on the module. | error | No | `OnlyComplianceEngine()` |
| DALP-1115 | Token registries already exist. | The registry factory already deployed per-token identity and storage registries for this token address. The registry factory enforces one set of per-token registries per token to prevent duplicate deployments. | The registry factory creates per-token registries only once per token. Retrieve the existing registries from the registry factory instead of attempting to create new ones. | error | No | `TokenRegistriesAlreadyExist(address)` |
| DALP-1116 | Token registry implementations missing. | Deploying the per-token registry factory requires all three registry implementations (token identity registry, token storage registry, and identity registry) to be present in the directory. At least one is missing. | A system administrator must register all three per-token registry implementations in the directory before the registry factory can deploy. | error | No | `TokenRegistryImplementationsMissing()` |
| DALP-1117 | Compliance module type mismatch. | Updating a compliance module implementation requires the new contract's typeId() to match the module slot being updated. The new implementation reports a different typeId (actualTypeId) than the slot's registered identifier (expectedTypeId), indicating you provided the wrong implementation. | Deploy or supply a compliance module implementation whose typeId() matches the module slot identifier you are updating. Verify the correct implementation address against the module registry. | error | No | `ComplianceModuleTypeMismatch(bytes32,bytes32)` |
| DALP-1118 | Unsupported compliance module. | The address provided as a compliance module implementation does not support any recognized compliance module interface. The directory validates the interface via ERC-165 before accepting an implementation, and this address failed all three probes. | Supply an implementation address that correctly implements a supported compliance module interface. Verify you have deployed the contract and that it exposes the expected ERC-165 interface identifiers. | error | No | `UnsupportedComplianceModule(address)` |
| DALP-1119 | Token scope not supported. | The compliance module you are installing belongs to a token-level compliance engine. Token-level engines do not support per-token inclusion or exemption scope filters; only the system compliance engine accepts those dimensions. The contract reverts whenever the scope passed to installScopedModule contains a non-empty tokenInclusion or tokenExemption list. | Remove the tokenInclusion and tokenExemption entries from the scope before calling installScopedModule on a token-level compliance engine. If you require per-token scoping, use the system compliance engine instead. | error | No | `TokenScopeNotSupported()` |
| DALP-1120 | Compliance check failed: `{{reason}}`. | A compliance rule on the token refused this transfer or mint. The reason after the colon names the check that failed, for example a blocked address or a blocked country. | Change the recipient or the amount so it meets that rule, or ask a compliance officer to review the token's compliance rules, then try again. | error | No | `ComplianceCheckFailed(address,bytes32,bytes32,string)` |
| DALP-1121 | Identity v2 not supported. | The identity factory targets V2 identity proxy deployment, but the underlying implementation contract does not expose the IDALPIdentityV2 interface. The factory checks supportsInterface at deploy time and reverts when the implementation predates V2. | Ask the platform administrator to point the factory at an implementation that supports IDALPIdentityV2, then retry. | error | No | `IdentityV2NotSupported()` |
| DALP-1122 | Authorization deadline expired. | The signed authorization included a deadline timestamp, and the current block time is past that deadline. The contract validates the authorization before creating the identity with management keys and reverts when the deadline has elapsed. | Request a new signed authorization with a deadline that has not passed, then resubmit the identity creation call with the updated signature and deadline. | error | No | `ExpiredIdentityManagementKeyAuthorization(uint256)` |
| DALP-1123 | Identity authorization signature does not match the wallet. | The EIP-712 signature for `createIdentityWithManagementKeyAuthorization` is malformed or recovered to an address other than the wallet. `recovered` holds the recovered address. | Re-sign the authorization digest with the private key of the wallet address passed as `_wallet`. Confirm the domain separator matches the identity factory contract and chain. | error | No | `InvalidIdentityManagementKeyAuthorization(address,address)` |
| DALP-1124 | The scheduled maturity date has passed; early maturity is not applicable. | The emergency early maturity call is only available before the scheduled maturity date. The current time (`{{currentTime}}`) has reached or passed the maturity timestamp (`{{maturityDate}}`), so the early maturity path is no longer applicable. | Use the regular maturity operation (governance role) to mature this bond. The emergency window applies only before the scheduled date. | error | No | `MaturityDateAlreadyReached(uint256,uint256)` |
| DALP-1125 | Fee rate too high. | The fee rate supplied in the feature configuration exceeds 10,000 basis points (100%). The contract enforces that no fee rate can be set above 100 percent of the transaction amount. | Set feeBps to a value of 10,000 or less in the feature configuration and resubmit. | error | No | `FeeRateTooHigh(uint16)` |
| DALP-1126 | Fee token required when fees non zero. | The external transaction fee feature configuration sets at least one of mintFee, burnFee, or transferFee to a non-zero value but leaves the fee token address as the zero address. The contract requires a fee token whenever any fee amount is non-zero. | Supply a valid fee token address in the configuration alongside the non-zero fee amounts, or set all fee amounts to zero if no fee token is available. | error | No | `FeeTokenRequiredWhenFeesNonZero()` |
| DALP-1127 | Conversion feature target token address is zero. | The conversion feature configuration requires a non-zero `targetToken` address. The value supplied in the config was the zero address. | Set `config.targetToken` to the deployed address of the token to be received after conversion. | error | No | `InvalidTargetToken()` |
| DALP-1128 | Maturity date zero. | The maturity date value in the maturity redemption feature configuration is zero. The contract requires a non-zero Unix timestamp for the maturity date before it will accept the configuration. | Provide a valid future Unix timestamp as the maturityDate in the feature configuration and resubmit. | error | No | `MaturityDateZero()` |
| DALP-1129 | Native recovery failed. | The paymaster refund splitter sent native currency to the target address and the low-level call returned false. Either the recipient contract rejected the transfer or it ran out of gas. | Verify that the recipient address can accept native currency transfers. If the recipient is a contract, confirm it has a payable fallback or receive function, then retry the recoverNative call. | error | No | `NativeRecoveryFailed()` |
| DALP-1130 | Token not system registered. | The system identity registry does not record the token address you provided. The token sale factory requires all tokens to be registered in the system registry before a sale can be created for them. | Confirm the system has registered the token in its identity registry before you create a token sale. | error | No | `TokenNotSystemRegistered()` |
| DALP-1131 | Current-holder counting needs a token that has no holders yet; choose lifetime counting for this rule. | A current-holder count starts from zero, so the module refuses a scope it cannot prove is empty. A token rule is refused when its token (`{{token}}`) already has supply. A global control is refused with the zero address, because a system-wide scope has no single token whose supply the module can check. | Install the rule with lifetime counting. For a token rule, current-holder counting can be installed before the token is minted; for a global control it is not available. | error | No | `CountingScopeHasHoldings(address)` |
| DALP-1132 | The counting policy is fixed at installation. | The configuration named a counting policy different from the one this rule was installed with. Changing it would recount existing holders under different rules. | Resubmit the configuration with the installed counting policy. To count differently, remove the rule and install a new one. | error | No | `CountingPolicyImmutable()` |
| DALP-1133 | Country limits are unavailable on this rule. | This rule was upgraded from Investor count, and wallets counted before the upgrade carry no country, so per-country counts would be wrong. The maximum still applies. | Resubmit the configuration without country limits. | error | No | `CountryAccountingIncomplete()` |
| DALP-1134 | Holder is not registered. | A holder lock is keyed on the holder's identity, and the wallet named for the lock is not registered in the token's identity registry. | Register the holder's wallet with an identity first, or name a wallet of the holder that is already registered. | error | No | `HolderNotRegistered(address)` |
| DALP-1135 | Holder lock amount is invalid. | A holder lock must lock a non-zero amount that fits the module's stored width. | Lock a positive amount in base units; to remove a lock, clear it instead. | error | No | `InvalidHolderLockAmount(uint256)` |
| DALP-1136 | Unlock time must be in the future. | A holder lock's unlock time is not later than the current block time, so the lock would never refuse a transfer. | Choose an unlock time after the current time. | error | No | `UnlockTimeNotInFuture(uint256)` |
| DALP-1137 | Holder lock not found. | The holder's identity has no lock on this token to clear. | Read the holder's lock before clearing it; nothing needs clearing when no lock is set. | error | No | `HolderLockNotFound(address)` |

The previous page is [DALP-1050 to DALP-1099](https://docs.settlemint.com/docs/api-reference/errors/error-code-reference/dalp-1050-1099). The next page is [DALP-2000 to DALP-2999](https://docs.settlemint.com/docs/api-reference/errors/error-code-reference/dalp-2000-2999).


# DALP-2000 to DALP-2999

Source: https://docs.settlemint.com/docs/api-reference/errors/error-code-reference/dalp-2000-2999
Cause, fix and retry flag for every on-chain contract error with a code from DALP-2000 to DALP-2999.

This page lists the 12 errors in the contract error reference with a code from DALP-2000 to DALP-2999. Match the error's `id`, or its `dalpCode` on a contract error or a failed deployment step, for example `DALP-2001`, to the DALP Code column, then read Retryable and Suggested Fix. The [contract error reference](https://docs.settlemint.com/docs/api-reference/errors/error-code-reference#how-to-use-this-reference) explains each column, including Severity, and the [DALP error index](https://docs.settlemint.com/docs/api-reference/errors) lists the page for every code range.

| DALP Code | Message | Why | Suggested Fix | Severity | Retryable | Solidity Error |
| --- | --- | --- | --- | --- | --- | --- |
| DALP-2001 | Sender not approved settlement. | The caller attempted to revoke their approval on an XvP settlement, but their address has no recorded approval. The settlement contract only permits revoking an approval that the same address previously granted. | Only call revokeApproval from an address that has already called approve on this settlement. Verify the address and settlement contract before retrying. | error | No | `SenderNotApprovedSettlement()` |
| DALP-2003 | You are not a participant in this settlement. | The contract checks every flow's sender address against the caller. Your account does not appear as a sender in any of this settlement's configured flows, so the contract cannot grant you access. | Verify that you are using the correct account and settlement reference. | error | No | `SenderNotInvolvedInSettlement()` |
| DALP-2004 | Settlement already cancelled. | The settlement reached a cancelled terminal state before this call arrived. Once cancelled, the contract blocks all further operations on this settlement. | No further step is possible. Create a new settlement if needed. | error | No | `XvPSettlementAlreadyCancelled()` |
| DALP-2005 | Settlement already completed. | The contract already executed this settlement and transferred all token flows. It blocks further operations once execution completes. | No further step is needed. The settlement completed successfully. | error | No | `XvPSettlementAlreadyExecuted()` |
| DALP-2006 | Settlement expired and the contract blocked execution. | The settlement's cutoff date has passed. The contract blocks execution and approval once the cutoff timestamp passes. | Create a new settlement with an updated deadline. | error | No | `XvPSettlementExpired()` |
| DALP-2007 | Settlement expired and the contract already returned the funds. | The contract already processed this expired withdrawal. It sets a withdrawn flag after the first successful call to withdrawExpired and rejects any repeat calls. | No further withdrawal is needed. The contract returned the funds when the settlement expired. | error | No | `XvPSettlementExpiredWithdrawalAlreadyProcessed()` |
| DALP-2008 | Not all parties have approved this settlement. | Execution requires every local sender in the settlement to have called approve. At least one local sender has not approved, so the settlement is not fully approved. | Check which participants still need to approve, then ask them to do so. | error | Yes | `XvPSettlementNotApproved()` |
| DALP-2009 | This settlement has not expired. | The withdrawExpired call requires the settlement's cutoff timestamp to have passed. The settlement is still within its active window, so the expired withdrawal path is not available yet. | Wait until the cutoff date has passed, then call `withdrawExpired`. | error | Yes | `XvPSettlementNotExpired()` |
| DALP-2010 | A settlement with external flows needs a hashlock. | This settlement includes flows on external chains, which requires a hashlock to coordinate cross-chain execution. You did not provide a hashlock when you created the settlement, so the contract rejected initialization. | Create the settlement again with a hashlock for its cross-chain flows. | error | No | `HashlockRequired()` |
| DALP-2011 | Settlement cutoff date is not in the future. | The XvP settlement factory requires the cutoff date to be strictly greater than the current block timestamp. The value supplied was equal to or before the current time. | Set the cutoff date to a Unix timestamp that is at least one second after the current block time. | error | No | `InvalidCutoffDate()` |
| DALP-2012 | The settlement has no payment flows defined. | The settlement requires at least one payment flow specifying what token each party sends and receives. You submitted the settlement with an empty flows array. | Add at least one payment flow specifying the tokens and amounts to exchange. | error | No | `EmptyFlows()` |
| DALP-2013 | You have already approved this settlement. | The contract records one approval per sender address. Your account has already called approve for this settlement, and the approval is already on-chain. | No further step is needed. The contract has recorded your approval. | warning | No | `SenderAlreadyApprovedSettlement()` |

The previous page is [DALP-1100 to DALP-1199](https://docs.settlemint.com/docs/api-reference/errors/error-code-reference/dalp-1100-1199). The next page is [DALP-3000 to DALP-3999](https://docs.settlemint.com/docs/api-reference/errors/error-code-reference/dalp-3000-3999).


# DALP-3000 to DALP-3999

Source: https://docs.settlemint.com/docs/api-reference/errors/error-code-reference/dalp-3000-3999
Cause, fix and retry flag for every on-chain contract error with a code from DALP-3000 to DALP-3999.

This page lists the 32 errors in the contract error reference with a code from DALP-3000 to DALP-3999. Match the error's `id`, or its `dalpCode` on a contract error or a failed deployment step, for example `DALP-3001`, to the DALP Code column, then read Retryable and Suggested Fix. The [contract error reference](https://docs.settlemint.com/docs/api-reference/errors/error-code-reference#how-to-use-this-reference) explains each column, including Severity, and the [DALP error index](https://docs.settlemint.com/docs/api-reference/errors) lists the page for every code range.

| DALP Code | Message | Why | Suggested Fix | Severity | Retryable | Solidity Error |
| --- | --- | --- | --- | --- | --- | --- |
| DALP-3001 | Airdrop ended. | The current block timestamp is past the airdrop's configured end time. The time-bound airdrop contract enforces a claim window and reverts any claim submitted after the window closes. | The claim window for this airdrop has closed. You cannot submit further claims. Review the airdrop's configured end time to confirm. | error | No | `AirdropEnded()` |
| DALP-3002 | Airdrop not started. | The current block timestamp is before the airdrop's configured start time. The time-bound airdrop contract enforces a claim window and reverts any claim submitted before the window opens. | Wait until the airdrop's start time has passed before submitting a claim. Check the airdrop's configured startTime to determine when claims become available. | error | Yes | `AirdropNotStarted()` |
| DALP-3003 | Claim already revoked. | The signature hash for this claim is already present in the revoked claims registry. The contract permits revoking each claim signature only once and blocks duplicate revocations. | The contract already revoked this claim. No further steps are needed for revocation. Verify the claim's current state before submitting another revocation request. | error | No | `ClaimAlreadyRevoked(bytes32)` |
| DALP-3004 | Identity holds no claim with this claim ID. | The ERC-735 identity contract stores no claim under the claimId you provided. The contract looks up claims by their computed ID and reverts when no matching claim exists. | Verify the claimId by computing it from the correct issuer and topic for the identity address. Confirm the contract successfully added the claim before attempting to retrieve or remove it. | error | No | `ClaimDoesNotExist(bytes32)` |
| DALP-3005 | Claim not eligible. | The vesting airdrop contract determined the caller does not meet the eligibility conditions required to claim at this time. The airdrop may have eligibility requirements that the caller's address or state does not currently satisfy. | Confirm the airdrop includes your address in the eligible set and that you meet all required conditions. If eligibility depends on a time-based or on-chain state, verify that the current state satisfies those conditions before retrying. | error | No | `ClaimNotEligible()` |
| DALP-3006 | Claim not valid according to issuer. | When adding a claim signed by an external issuer, the issuer's isClaimValid function returned false for the given topic and signature. The contract verifies claim validity with the issuer before storing it, and reverts when the issuer rejects the claim. | Request a fresh, valid claim signature from the issuer for the correct topic and identity address. Verify the issuer address and topic value match what the issuer signed before resubmitting. | error | No | `ClaimNotValidAccordingToIssuer(address,uint256)` |
| DALP-3007 | Cliff exceeds vesting duration. | The cliff duration provided to the linear vesting strategy is longer than the total vesting duration. The contract enforces that the cliff period must fall within the overall vesting period. | Set the cliff duration to a value less than or equal to the vesting duration and redeploy the vesting strategy. | error | No | `CliffExceedsVestingDuration()` |
| DALP-3008 | Distribution cap exceeded. | The amount being distributed would cause the total distributed so far to exceed the distribution cap configured on the airdrop. The contract enforces the cap to prevent distributing more tokens than the allocation permits. | Reduce the distribution amount so that the sum of all distributed amounts stays within the configured cap, or verify the cap value against the intended total allocation. | error | No | `DistributionCapExceeded()` |
| DALP-3009 | Duplicate claim topic. | The claim topics array provided when registering or updating a trusted issuer contains the same topic value more than once. The contract requires each topic to appear exactly once in the list. | Remove duplicate topic values from the claimTopics array so that each topic appears only once, then resubmit the trusted issuer registration call. | error | No | `DuplicateClaimTopic(uint256)` |
| DALP-3010 | Airdrop name is empty. | The airdrop contract requires a non-empty name string during initialization. The `name_` argument passed to the initializer had zero bytes. | Provide a non-empty string as the airdrop name. | error | No | `InvalidAirdropName()` |
| DALP-3011 | Claim tracker address is zero or missing the required interface. | The airdrop initializer requires a non-zero claim tracker address that implements `IDALPClaimTracker`. The address was either zero or the interface probe call failed. | Supply the address of a deployed `IDALPClaimTracker` contract such as `DALPBitmapClaimTracker`. | error | No | `InvalidClaimTrackerAddress()` |
| DALP-3012 | Distribution recipient address is zero. | Each push airdrop distribution call requires a non-zero recipient address. The `recipient` argument was the zero address. | Provide a valid, non-zero recipient address for the distribution. | error | No | `InvalidDistributionAddress()` |
| DALP-3013 | Merkle root is zero. | The Merkle root supplied is zero, which no proof can match. Airdrop setup and dividend snapshot recording both need a non-zero root. | Supply the Merkle root computed from the allocation or holder tree. | error | No | `InvalidMerkleRoot()` |
| DALP-3014 | Vesting duration is zero. | The linear vesting strategy constructor requires a vesting duration greater than zero. A duration of zero would make the vesting schedule complete immediately at deployment. | Set `vestingDuration_` to the desired total vesting period in seconds (greater than zero). | error | No | `InvalidVestingDuration()` |
| DALP-3015 | Vesting strategy does not support multiple claims. | The vesting airdrop contract requires a vesting strategy that returns `true` from `supportsMultipleClaims()`. The strategy at the provided address either reverted or returned `false`. | Use a vesting strategy implementation that supports incremental claim release, such as `DALPLinearVestingStrategy`. | error | No | `InvalidVestingStrategy(address)` |
| DALP-3016 | Vesting strategy address is zero. | The vesting airdrop initializer and `setVestingStrategy` need a non-zero vesting strategy address. The address supplied was zero. | Deploy a compatible vesting strategy contract and pass its address to the initializer. | error | No | `InvalidVestingStrategyAddress()` |
| DALP-3017 | No claim topics provided. | The trusted issuers registry requires at least one claim topic when registering or updating a trusted issuer. The call supplied an empty list of claim topics, so the registry rejected it. | Include at least one claim topic in the trusted issuer registration request and resubmit. | error | No | `NoClaimTopicsProvided()` |
| DALP-3018 | Push airdrop claim not allowed. | Push airdrops are admin-controlled: the contract owner distributes tokens directly to recipients. The contract disables the claim functions by design, so calling them always reverts. | Ask the airdrop administrator to distribute your allocation. | error | No | `PushAirdropClaimNotAllowed()` |
| DALP-3019 | Sender lacks claim signer key. | Adding or removing a claim on an identity requires the caller to hold a CLAIM_SIGNER_KEY for that identity. The sending address does not have that key registered on-chain. | Use an address that holds the CLAIM_SIGNER_KEY on the target identity, or ask the identity owner to add the key before retrying. | error | No | `SenderLacksClaimSignerKey()` |
| DALP-3020 | Caller cannot create an airdrop for this token. | Creating an airdrop requires GOVERNANCE_ROLE on the token, or the system's TOKEN_FACTORY_MODULE_ROLE. The caller holds neither. | Create the airdrop from an address that holds GOVERNANCE_ROLE on the token. | error | No | `UnauthorizedAirdropCreation()` |
| DALP-3021 | Claim must come from the issuer identity itself. | A CONTRACT-scheme claim requires the claim issuer contract itself to call `addClaim`, with its own address as `msg.sender`. The call arrived from a different address. | Submit the claim from the issuer identity (`{{issuer}}`) itself. `{{caller}}` is not that identity. | error | No | `UnauthorizedContractClaim(address,address)` |
| DALP-3022 | Unsupported claim scheme. | The ERC-735 claim implementation accepts ECDSA and ERC-1271 signature schemes, plus CONTRACT. You submitted a scheme value (`{{scheme}}`) that does not match any of those. | Resubmit the claim with a supported scheme: `1` for ECDSA, `3` for CONTRACT or `4` for ERC-1271. | error | No | `UnsupportedClaimScheme(uint256)` |
| DALP-3023 | Vesting airdrop implementation not set. | The vesting airdrop factory requires a deployed vesting airdrop implementation contract before new vesting airdrops can be created. No one has configured the factory's implementation address yet. | A system manager must call `updateImplementation` on the vesting airdrop factory with a valid implementation address before creating vesting airdrops. | error | No | `VestingAirdropImplementationNotSet()` |
| DALP-3024 | Vesting already initialized. | Vesting for this allocation index has already been initialized. Each Merkle-tree index can only start vesting once, and the contract found a non-zero initialization timestamp for the requested index. | Check `isVestingInitialized(index)` before calling `initializeVesting`. After vesting starts, call `claim` to collect vested tokens. | error | No | `VestingAlreadyInitialized()` |
| DALP-3025 | Vesting initialization required. | Claiming vested tokens requires that you started vesting first for this allocation index. The contract found no initialization record (timestamp of zero) for the requested index. | Call `initializeVesting` with a valid Merkle proof for this index to start the vesting schedule, then claim once tokens have vested. | error | No | `VestingNotInitialized()` |
| DALP-3026 | Claim fallback disabled. | The price resolver's claim fallback feature is turned off. Without an active feed for the requested token, the resolver cannot return a price. | Either register a price feed for this token in the FeedsDirectory, or ask the feeds manager to enable claim fallback on the price resolver before retrying. | error | No | `ClaimFallbackDisabled()` |
| DALP-3027 | No claim fallback. | The price resolver attempted to fall back to a trusted identity claim for token `{{token}}`, but the token has no valid trusted claim available. The fallback path found nothing to return. | Ensure a trusted claim issuer has issued a valid base-price claim for token `{{token}}`, or register a price feed for this token in the FeedsDirectory so the fallback path is unnecessary. | error | No | `NoClaimFallback(address)` |
| DALP-3028 | Nothing to claim. | There is nothing to claim: no locked or parked XvP balance, or no accrued interest for this holder. | Check that you have an outstanding XvP balance or accrued interest before you claim. Each balance supports a single claim. | error | No | `NothingToClaim()` |
| DALP-3029 | The claim amount cannot be zero. | The airdrop contract requires a non-zero token quantity for every claim. You submitted a claim amount of zero, so the contract reverted before any tokens were transferred. | Enter a valid amount greater than zero to claim your airdrop tokens. | error | No | `ZeroClaimAmount()` |
| DALP-3030 | Airdrop reward already claimed. | The full allocation for this index is already claimed. Each claim adds to the index's claimed total, and the contract refuses a claim once that total reaches the allocation. | Check your balance. Earlier claims for this index already transferred the tokens. | warning | No | `IndexAlreadyClaimed()` |
| DALP-3031 | Claim amount exceeds the unclaimed remainder for this index. | The claim is larger than what remains unclaimed for this index: the total allocation minus earlier claims. | Claim no more than the unclaimed remainder of this index's allocation. | error | No | `InvalidClaimAmount()` |
| DALP-3032 | Merkle proof does not match the airdrop root. | The contract verified the supplied Merkle proof against the stored root and the proof failed. The proof was generated for a different index, account, total allocation or Merkle tree than the one stored on-chain. | Regenerate the proof from the allocation tree behind the on-chain root, for the exact index, account and total allocation. | error | No | `InvalidMerkleProof()` |

The previous page is [DALP-2000 to DALP-2999](https://docs.settlemint.com/docs/api-reference/errors/error-code-reference/dalp-2000-2999). The next page is [DALP-4000 to DALP-4049](https://docs.settlemint.com/docs/api-reference/errors/error-code-reference/dalp-4000-4049).


# DALP-4000 to DALP-4049

Source: https://docs.settlemint.com/docs/api-reference/errors/error-code-reference/dalp-4000-4049
Cause, fix and retry flag for every on-chain contract error with a code from DALP-4000 to DALP-4049.

This page lists the 49 errors in the contract error reference with a code from DALP-4000 to DALP-4049. Match the error's `id`, or its `dalpCode` on a contract error or a failed deployment step, for example `DALP-4001`, to the DALP Code column, then read Retryable and Suggested Fix. The [contract error reference](https://docs.settlemint.com/docs/api-reference/errors/error-code-reference#how-to-use-this-reference) explains each column, including Severity, and the [DALP error index](https://docs.settlemint.com/docs/api-reference/errors) lists the page for every code range.

| DALP Code | Message | Why | Suggested Fix | Severity | Retryable | Solidity Error |
| --- | --- | --- | --- | --- | --- | --- |
| DALP-4001 | Authority address has no deployed contract code. | The `setAuthority` function checks that the new authority address contains deployed contract bytecode. The address supplied has no contract code, so the contract rejected the update. | Supply an address where an authority contract is already deployed. Passing a wallet address or an address with no contract at it will always revert. | error | No | `AccessManagedInvalidAuthority(address)` |
| DALP-4002 | Access managed required delay. | The OpenZeppelin AccessManager enforces a mandatory delay before certain restricted calls can execute. The caller (`{{caller}}`) triggered a function that requires waiting `{{delay}}` seconds after scheduling before it may proceed. | Schedule the operation first, wait for the required delay of `{{delay}}` seconds, then execute it. Use the AccessManager's `schedule` function and check the operation's execution window before calling. | error | No | `AccessManagedRequiredDelay(address,uint32)` |
| DALP-4003 | Access manager already deployed. | The factory deploys each token's access manager with CREATE2 at an address derived from the caller, the token name, symbol and decimals, and for custom assets the asset type name. An access manager already exists at that address. | Change the token name or symbol. The existing access manager stays at the address in the error. | error | No | `AccessManagerAlreadyDeployed(address)` |
| DALP-4004 | Access manager already scheduled. | The OpenZeppelin AccessManager's schedule function rejected this call because an operation with the same id is already scheduled and its scheduled timepoint has not expired. The operation id is derived from the caller and target pair together with the calldata. The contract blocks duplicate scheduling of the same pending operation. | Wait for the existing scheduled operation to either execute or expire before scheduling it again. You can check the current schedule timepoint by calling getSchedule with the operation id, or cancel the existing schedule first. | error | No | `AccessManagerAlreadyScheduled(bytes32)` |
| DALP-4005 | Access manager bad confirmation. | The OpenZeppelin AccessManager's renounceRole function requires the caller to pass their own address as the callerConfirmation argument. The address supplied does not match the address of the account that sent the transaction. | Call renounceRole again and pass your own wallet address as the callerConfirmation argument. The value must exactly match the address that signs and sends the transaction. | error | No | `AccessManagerBadConfirmation()` |
| DALP-4006 | Scheduled operation deadline expired. | You submitted the scheduled operation (`{{operationId}}`) to the AccessManager after its execution window had already closed. Scheduled operations must execute within the allowed time window. | Re-schedule the operation to obtain a fresh execution window, then execute it before the window expires. | error | No | `AccessManagerExpired(bytes32)` |
| DALP-4007 | AccessManager deployed with a zero initial admin address. | The AccessManager constructor requires a non-zero address for the initial admin. The address supplied was the zero address (0x000...000), so the contract cannot grant the ADMIN_ROLE to any account. | Provide a valid, non-zero wallet or contract address as the initial admin when deploying the AccessManager. The address must be a real account that will hold the ADMIN_ROLE. | error | No | `AccessManagerInvalidInitialAdmin(address)` |
| DALP-4008 | Access manager locked role. | Role `{{roleId}}` is a locked administrative role in the AccessManager. The AccessManager protects this role from configuration changes. | Choose a different role ID that the AccessManager allows to be modified, or contact the system administrator if you believe this restriction needs to change at the governance level. | error | No | `AccessManagerLockedRole(uint64)` |
| DALP-4009 | Access manager not configured. | The token sale contract requires an AccessManager on the subject token before role checks can run. The token's access manager address is zero, meaning no one has set an access manager for it. | Ensure the subject token has an access manager deployed and configured before creating or interacting with a token sale for that token. | error | No | `AccessManagerNotConfigured()` |
| DALP-4010 | Access manager not ready. | The scheduled operation (`{{operationId}}`) exists in the AccessManager, but its delay period has not elapsed. The AccessManager blocks execution until the scheduled time arrives. | Wait until the scheduled execution window opens for operation `{{operationId}}`, then retry. Check the AccessManager for the exact scheduled timestamp. | error | No | `AccessManagerNotReady(bytes32)` |
| DALP-4011 | Access manager not scheduled. | The operation (`{{operationId}}`) has not been scheduled in the AccessManager. Executing or cancelling a delayed operation requires scheduling it first. | Call `schedule` on the AccessManager for this operation before attempting to execute or cancel it. | error | No | `AccessManagerNotScheduled(bytes32)` |
| DALP-4012 | Access manager unauthorized account. | The account (`{{msgsender}}`) does not hold role `{{roleId}}` in the AccessManager and is therefore not permitted to call the restricted function. | Request that an AccessManager admin grant role `{{roleId}}` to your address, or use an address that already holds the required role. | error | No | `AccessManagerUnauthorizedAccount(address,uint64)` |
| DALP-4013 | Access manager unauthorized call. | The caller (`{{caller}}`) attempted to call a function on target contract (`{{target}}`) with selector `{{selector}}`, but the AccessManager has no permission granting access to that call. | Ensure the AccessManager has a permission configured that allows your address (or role) to call the target function. Contact the system administrator to grant the necessary permission. | error | No | `AccessManagerUnauthorizedCall(address,address,bytes4)` |
| DALP-4014 | Access manager unauthorized cancel. | The OpenZeppelin AccessManager contract received a cancel request from an account that is not permitted to cancel this scheduled operation. Only the original caller or an account with the appropriate admin role may cancel a pending operation. | Retry the cancel from the account that originally scheduled the operation, or from an account holding the admin role that governs the target function. | error | No | `AccessManagerUnauthorizedCancel(address,address,address,bytes4)` |
| DALP-4015 | Access manager unauthorized consume. | The OpenZeppelin AccessManager blocked an attempt to consume a scheduled operation because the consuming target does not match the target the operation recorded at scheduling time. | Ensure the contract consuming the scheduled operation is the same target address that the operation recorded when scheduled. | error | No | `AccessManagerUnauthorizedConsume(address)` |
| DALP-4016 | Account implementation not set. | The directory does not have an account implementation address registered. The account proxy resolves its logic contract from the directory at call time, and found a zero address for the ACCOUNT key. | Register a valid account implementation address in the directory before deploying or calling through an account proxy. | error | No | `AccountImplementationNotSet()` |
| DALP-4017 | Account unauthorized. | The call reached the account contract from an address that is neither the configured EntryPoint nor the resolved canonical EntryPoint. The account only accepts UserOperation calls from its bound EntryPoint. | Submit this operation through the EntryPoint that is bound to this account. Direct calls to restricted account functions are not permitted. | error | No | `AccountUnauthorized(address)` |
| DALP-4018 | Accrual already closed. | Yield accrual for this holder address is already in a closed state. The fixed treasury yield feature records a closed flag per holder and blocks a second close on the same holder. | Check the holder's accrual status before calling closeAccrual. Nothing further is required if accrual is already closed. | error | No | `AccrualAlreadyClosed(address)` |
| DALP-4019 | Addon registry implementation not set. | The system cannot create or operate an addon registry because no logic contract address has been set for it. The system checked the addon registry implementation slot and found a zero address. An update that sets the address to zero is refused with the same error. | Configure a non-zero addon registry implementation address in the system before attempting to bootstrap or use the addon registry. | error | No | `AddonRegistryImplementationNotSet()` |
| DALP-4020 | Address already deployed. | A system addon factory or a token factory already deployed a contract at this CREATE2 address. | Change the inputs the address derives from. For a token, these are its name, symbol and decimals. | error | No | `AddressAlreadyDeployed(address)` |
| DALP-4021 | Address already on bypass list. | A call to the compliance contract named an address that is already on the compliance bypass list. DALP's factories check the list before they add an address, so the call came from a Compliance manager or from a custom token factory or add-on that a System manager registered or pointed at new code. | The list did not change and the address is already on it. Retrying changes nothing. To find out who made the call, read which account called the compliance contract in the transaction's call trace. | error | No | `AddressAlreadyOnBypassList(address)` |
| DALP-4022 | Address not in trusted issuer list. | The trusted issuer address you are trying to remove was not found in the registry list. The contract scans the list and reverts when no matching entry exists. | Confirm that the trusted issuer registry currently holds this address before you attempt to remove it. | error | No | `AddressNotFoundInList(address)` |
| DALP-4023 | Address not on bypass list. | A call to the compliance contract tried to remove an address that is not on the compliance bypass list. DALP's own factories never remove an address from the list, so the call came from a Compliance manager or from a custom token factory or add-on that a System manager registered or pointed at new code. | The list did not change and the address is not on it. Retrying changes nothing. To find out who made the call, read which account called the compliance contract in the transaction's call trace. | error | No | `AddressNotOnBypassList(address)` |
| DALP-4024 | Already archived. | The registration under this key is already archived, and a second archive call is blocked. | Confirm the current state of the registration before calling archive. No further step is required if the entry already carries the archived state. | error | No | `AlreadyArchived(bytes32)` |
| DALP-4025 | Already distributed. | The push airdrop contract already recorded a non-zero claimed amount for this index, which means the contract already distributed tokens for it. The contract blocks a second distribution for the same index. | Each airdrop index supports one distribution. Verify the contract has not already processed this index before you submit the distribution request. | error | No | `AlreadyDistributed()` |
| DALP-4026 | Already initialized. | The contract or feature already completed initialization. This guard prevents a second initialization call from overwriting the configured state. | The contract supports one initialization per deployment. Check whether the contract already ran initialization before calling the initialize function. | error | No | `AlreadyInitialized()` |
| DALP-4027 | Already matured. | The token is already matured. `mature()` and `matureEarly()` run once. The treasury cannot change after maturity. | Read `isMatured()` first. To fund redemptions after maturity, send the denomination asset to the current treasury address. | error | No | `AlreadyMatured()` |
| DALP-4028 | Key already registered. | The directory already has an entry under this key. Token types, compliance modules, addons, implementation keys and instance keys are each registered once. | Use a unique registration key. Retrieve the existing entry if you need to reference the already-registered resource. | error | No | `AlreadyRegistered(bytes32)` |
| DALP-4029 | Ambiguous interest provider. | During conversion, the contract resolved `{{providerCount}}` interest providers and could not determine which one to use. Configure the conversion feature with an explicit interest provider so that resolution selects exactly one. | Configure the conversion feature with an explicit interest provider so that resolution is unambiguous before triggering conversion. | error | No | `AmbiguousInterestProvider(uint256)` |
| DALP-4030 | Amount exceeds int256 max. | One of the settlement flow amounts exceeds the maximum value representable as a signed 256-bit integer. The XvP settlement uses signed integers to compute net positions, so all flow amounts must fit within that range. | Reduce the flow amount so that it does not exceed 2^255 - 1 before submitting the settlement. | error | No | `AmountExceedsInt256Max()` |
| DALP-4031 | Identity verification module `AND` or `OR` node needs two operands. | The identity verification compliance expression contains an `AND` or `OR` node that does not have at least two operands on the evaluation stack at that point. The expression has a structural problem at that node. | Correct the expression so that every `AND` or `OR` node follows at least two TOPIC or sub-expression nodes. Validate the expression structure before submitting it. | error | No | `AndOrOperationRequiresTwoOperands()` |
| DALP-4032 | Identity verification library `AND` or `OR` node needs two operands. | The identity verification expression passed to IdentityVerificationLib contains an `AND` or `OR` operation node that does not have at least two operands on the evaluation stack at that position. | Ensure that at least two TOPIC or sub-expression result nodes appear before each `AND` or `OR` node in the expression. Review the expression structure and resubmit. | error | No | `AndOrOperationsRequireTwoOperands()` |
| DALP-4033 | Approval already exists. | An active, unexpired approval for this exact token, sender identity, recipient identity, and amount already exists; a different approver created it. The contract prevents duplicate approvals from separate approvers for the same transfer parameters. | Check for an existing active approval for these transfer parameters. Either use the existing approval or wait for it to expire before creating a new one from a different approver. | error | No | `ApprovalAlreadyExists()` |
| DALP-4034 | Approval already used. | A previous transfer already consumed the transfer approval record for this sender-to-recipient pair. Each approval is single-use: once a transfer succeeds, the contract records the approval as used and blocks any further transfer against it. | Request a new transfer approval for this sender-to-recipient pair and token amount, then resubmit the transfer. | error | No | `ApprovalAlreadyUsed()` |
| DALP-4035 | Transfer approval expired. | The transfer approval record for this sender-to-recipient pair has passed its expiry timestamp. The contract enforces that you consume approvals before their deadline. | Request a fresh transfer approval with a suitable expiry, then resubmit the transfer before that expiry passes. | error | No | `ApprovalExpired()` |
| DALP-4036 | Approval required. | No transfer approval record exists for this sender-to-recipient pair and token amount. The token's transfer compliance module requires an explicit approval to be on-chain before the transfer can proceed. | Create a transfer approval for the sender identity, recipient identity, and exact token amount, then resubmit the transfer. | error | No | `ApprovalRequired()` |
| DALP-4037 | Archive not registered. | The registration key you supplied does not correspond to any registered system addon. The contract requires the addon to exist in the registry before you can archive it. | Verify the registration key against the addon registry and resubmit with a key that matches an existing registered addon. | error | No | `ArchiveNotRegistered(bytes32)` |
| DALP-4038 | Array length mismatch. | Two input arrays passed to this call have different lengths. The contract requires all array parameters to be the same length so each element maps to a corresponding element in the other arrays. | Ensure all array arguments have equal length and resubmit the call. | error | No | `ArrayLengthMismatch()` |
| DALP-4039 | Array length mismatch. | Two arrays in a batch call have different lengths. Batch registrations of topic schemes, system addons and token factories pair each entry with the entry at the same position. | Send arrays of equal length. This call sent `{{namesLength}}` and `{{signaturesLength}}` entries. | error | No | `ArrayLengthMismatch(uint256,uint256)` |
| DALP-4040 | Associated contract not set. | The on-chain identity contract has no associated contract address configured. The issueClaimTo path requires a non-zero associated contract address before you can issue claims on behalf of a contract. | Configure the associated contract address on this identity contract before calling claim issuance operations. | error | No | `AssociatedContractNotSet()` |
| DALP-4041 | Authorization contract already registered. | The claim authorization contract at the supplied address is already present in the registry. The registry accepts each authorization contract only once. | Remove the existing registration for this contract before re-registering it, or supply a different authorization contract address. | error | No | `AuthorizationContractAlreadyRegistered(address)` |
| DALP-4042 | Authorization contract not registered. | The claim authorization contract at the supplied address is not present in the registry. The contract requires a registration to exist before you can remove it. | Register the authorization contract before attempting to remove it, or verify the correct contract address. | error | No | `AuthorizationContractNotRegistered(address)` |
| DALP-4043 | Batch size exceeds limit. | The number of entries in the batch exceeds the airdrop contract's maximum of 100. | Split the batch into segments of 100 entries or fewer and submit each segment separately. | error | No | `BatchSizeExceedsLimit()` |
| DALP-4044 | Below min conversion amount. | The conversion amount you submitted is below the token's minimum conversion threshold. The contract checks that the amount you want to convert meets or exceeds the configured minimum before proceeding. | Increase the conversion amount to at least the minimum required. The current minimum is `{{minimum}}` and your amount was `{{amount}}`. | error | No | `BelowMinConversionAmount(uint256,uint256)` |
| DALP-4045 | Buyer not eligible. | The buyer's wallet does not pass the token's compliance check. The token sale delegates eligibility to the token's on-chain compliance module, which returned false for this buyer and amount. | Verify that the buyer's identity has the required compliance claims and that the purchase amount is within the allowed limits for this buyer, then retry. | error | No | `BuyerNotEligible()` |
| DALP-4046 | Caller not factory. | Only the factory contract that deployed this XvP settlement or trading venue may call this function. The caller's address does not match the stored factory address. | Route this call through the factory contract that created this settlement, or verify you are calling the correct settlement address. | error | No | `CallerNotFactory()` |
| DALP-4047 | Cancel not allowed. | The settlement cannot be cancelled in its current state. Cancellation is blocked either because the contract has already recorded a revealed HTLC secret, or because the settlement holds external flows with full approval but has not collected unanimous cancel votes. | If the secret remains unrevealed and the settlement has external flows, use proposeCancel to submit a cancel vote. Each local participant must vote before the contract cancels the settlement. | error | No | `CancelNotAllowed()` |
| DALP-4048 | Cancel vote already cast. | This participant has already submitted a cancel vote for this settlement. The contract records one cancel vote per participant and rejects duplicate votes. | Withdraw the existing cancel vote with withdrawCancelProposal before casting a new one, or proceed without re-voting. | error | No | `CancelVoteAlreadyCast(address)` |
| DALP-4049 | Cancel vote not cast. | The contract holds no cancel vote from this participant for this settlement. Withdrawing a cancel vote requires that you previously submitted one via proposeCancel. | Submit a cancel vote with proposeCancel before attempting to withdraw it. | error | No | `CancelVoteNotCast(address)` |

The previous page is [DALP-3000 to DALP-3999](https://docs.settlemint.com/docs/api-reference/errors/error-code-reference/dalp-3000-3999). The next page is [DALP-4050 to DALP-4099](https://docs.settlemint.com/docs/api-reference/errors/error-code-reference/dalp-4050-4099).


# DALP-4050 to DALP-4099

Source: https://docs.settlemint.com/docs/api-reference/errors/error-code-reference/dalp-4050-4099
Cause, fix and retry flag for every on-chain contract error with a code from DALP-4050 to DALP-4099.

This page lists the 50 errors in the contract error reference with a code from DALP-4050 to DALP-4099. Match the error's `id`, or its `dalpCode` on a contract error or a failed deployment step, for example `DALP-4050`, to the DALP Code column, then read Retryable and Suggested Fix. The [contract error reference](https://docs.settlemint.com/docs/api-reference/errors/error-code-reference#how-to-use-this-reference) explains each column, including Severity, and the [DALP error index](https://docs.settlemint.com/docs/api-reference/errors) lists the page for every code range.

| DALP Code | Message | Why | Suggested Fix | Severity | Retryable | Solidity Error |
| --- | --- | --- | --- | --- | --- | --- |
| DALP-4050 | Cannot execute to zero address. | The ERC-734 key manager does not permit on-chain executions targeting the zero address. The target address provided in the execution call is the zero address. | Provide a valid non-zero target address for the execution call. | error | No | `CannotExecuteToZeroAddress()` |
| DALP-4051 | Cannot initialize logic contract. | You called the initialize function directly on a logic (implementation) contract that the constructor already configured. Only proxy instances may be initialized; the logic contract itself must remain uninitialized. | Call initialize only on the proxy contract, not on the implementation contract directly. | error | No | `CannotInitializeLogicContract()` |
| DALP-4052 | Cannot recover self. | The recovery named the token contract itself, either as the lost wallet or as the ERC-20 token to recover. A token cannot recover its own balance or its own units. | Name the holder's lost wallet, or a token other than this one for an ERC-20 recovery. | error | No | `CannotRecoverSelf()` |
| DALP-4053 | Cannot remove default validator. | The module at the supplied address is the account factory's currently configured default validator. The contract does not permit you to remove the default validator while it holds that designation. | Assign a different default validator before removing this module, or remove a different module that is not the default validator. | error | No | `CannotRemoveDefaultValidator(address)` |
| DALP-4054 | Contract already linked. | The identity factory already links an identity to this contract address. Each contract address links to one identity. | Use the existing identity. The factory has no call that removes the link. | error | No | `ContractAlreadyLinked(address)` |
| DALP-4055 | Conversion id already used. | The conversion identifier computed for this request was already recorded as used. The contract enforces replay protection by rejecting any conversion that produces a previously seen identifier. | Do not resubmit an identical conversion request. Each conversion produces a unique identifier based on token, target, holder, trigger, and an incrementing nonce. Submitting a new conversion with fresh parameters will generate a distinct identifier. | error | No | `ConversionIdAlreadyUsed(bytes32)` |
| DALP-4056 | Conversion minter missing. | The conversion configuration names no minter, and the target token has no conversion minter feature installed. | Ensure the target token has a conversion minter installed and configured. Check the token's feature set and register the minter if it is absent. | error | No | `ConversionMinterMissing()` |
| DALP-4057 | Conversion window closed. | The token's configured conversion window has ended. The current block timestamp is past the window's end time, so the contract no longer accepts conversion requests. | Check the token's conversion window end time. The contract processes conversions only within the configured window. Contact the token issuer if you believe the window should be extended. | error | No | `ConversionWindowClosed()` |
| DALP-4058 | Conversion window not open. | The token's conversion window has not started yet. The current block timestamp is before the window's start time, so the contract rejects conversion requests until the window opens. | Check the token's conversion window start time and resubmit after the window opens. You can read the configured start timestamp from the token's conversion configuration. | error | No | `ConversionWindowNotOpen()` |
| DALP-4059 | Create2 empty bytecode. | The deployment bytecode supplied to the CREATE2 factory was empty. The factory requires non-empty bytecode to deploy a contract at a deterministic address. | Verify that the bytecode you pass to the deployment call is complete and non-empty. The contract always rejects an empty bytes value at the deployment step. | error | No | `Create2EmptyBytecode()` |
| DALP-4060 | Feed update deadline expired. | The signed feed update carries a non-zero deadline that has already passed. The contract rejects updates whose deadline falls before the current block timestamp to prevent replay of stale price data. | Have the issuer sign the update again with a future deadline, then resubmit. | error | No | `DeadlineExpired()` |
| DALP-4061 | Decimal mismatch. | The replacement feed reports a different decimal precision than the feed it is replacing. The directory enforces that scalar feed upgrades preserve the same decimal count to prevent precision mismatches in downstream consumers. | Supply a replacement feed whose decimals() return value matches the existing feed's decimals. Verify both feeds report the same value before submitting the replacement. | error | No | `DecimalMismatch(uint8,uint8)` |
| DALP-4062 | Default validator not set. | The account factory has no default validator configured. The simple account creation path requires a directory administrator to set a default validator before you can create wallets without an explicit validator parameter. | Ensure the account factory's default validator is set before creating accounts via the default path. Alternatively, supply an explicit validator address in the account creation parameters. | error | No | `DefaultValidatorNotSet()` |
| DALP-4063 | Delegate and revert. | The ERC-4337 EntryPoint's delegateAndRevert function always reverts with this error after performing a delegatecall. The function is a diagnostic tool that returns the delegatecall result inside the revert data rather than propagating a real failure. | Decode the success and ret fields from the revert data to inspect the outcome of the delegatecall. The delegateAndRevert diagnostic endpoint intentionally produces this error and it does not represent an on-chain state problem. | error | No | `DelegateAndRevert(bool,bytes)` |
| DALP-4064 | Denomination mismatch. | The denomination asset recorded in the conversion configuration does not match the denomination asset provided by the trigger or interest rate provider. The conversion feature requires all parties to reference the same denomination currency. | Ensure the trigger or provider you are using carries the same denomination asset as the token's conversion configuration. Check the expected denomination address from the error arguments and compare it with your trigger's denomination. | error | No | `DenominationMismatch(address,address)` |
| DALP-4065 | Deployment address mismatch. | The identity contract deployed by the factory landed at a different address than the one computed by CREATE2 before deployment. This indicates a mismatch in the salt, constructor arguments, or bytecode used for the address prediction. | Contact support with the `requestId` from the error. | error | No | `DeploymentAddressMismatch()` |
| DALP-4066 | Deposit withdrawal failed. | The ERC-4337 stake manager attempted to transfer the deposited ETH to the specified withdrawal address, but the ETH transfer call failed. The error arguments carry the revert reason the failed call returned. | Check that the withdrawal address is able to receive ETH (not a contract that rejects ETH or has an insufficient gas stipend). Inspect the revertReason field in the error for more detail, then retry with a valid withdrawal address. | error | No | `DepositWithdrawalFailed(address,address,uint256,bytes)` |
| DALP-4067 | Directory already set. | The system contract's directory reference already points to a non-zero address. The contract accepts only one directory assignment and rejects any attempt to overwrite it. | The directory is a one-time configuration. If the current directory address is wrong, the system must undergo redeployment or migration rather than an overwrite via setDirectory. | error | No | `DirectoryAlreadySet()` |
| DALP-4068 | Directory not set. | The system contract requires a non-zero directory address, but no one has set one yet. Directory-dependent operations will revert until a valid directory address is in place. | Set the directory address on the system contract before calling directory-dependent operations. Use setDirectory or initializeWithDirectory with a valid address. | error | No | `DirectoryNotSet()` |
| DALP-4069 | Duplicate feature. | The list of features passed to the token configuration contains the same feature contract address more than once. Each feature address must appear at most once in an ordered feature set. | Remove duplicate entries from the features list before resubmitting. Each feature address must be unique within the ordered list supplied to the token configuration call. | error | No | `DuplicateFeature(address)` |
| DALP-4070 | Duplicate module. | The same compliance module address appears more than once in the initial compliance module set supplied to the token. The contract rejects duplicate modules to prevent redundant or conflicting compliance checks. | Remove the duplicate module address from the compliance module list before resubmitting. Each module address must appear only once in the initial module set. | error | No | `DuplicateModule(address)` |
| DALP-4071 | Duplicate signature. | You supplied a signature from the same address more than once in a multi-signature verification context. The contract rejects duplicate signers to prevent a single key from counting multiple times toward a threshold. | Ensure that each signer address contributes exactly one signature to the set. Remove the duplicate signature before resubmitting. | error | No | `DuplicateSignature(address)` |
| DALP-4072 | Duplicate type id. | Two features in the list you submitted share the same type identifier. Each feature type may be installed at most once per token; the contract rejects a second feature that reports the same typeId. | Remove one of the conflicting features from the list so that each typeId appears only once. Check each feature's typeId before assembling the feature list. | error | No | `DuplicateTypeId(bytes32)` |
| DALP-4073 | ETH not accepted. | The proxy contract does not accept direct ETH transfers. Its receive function exists solely to block accidental ETH sends, which the contract would trap with no way to recover. | Do not send ETH directly to this contract address. If you intend to interact with a payable function, call that function explicitly rather than sending a plain ETH transfer. | error | No | `ETHNotAccepted()` |
| DALP-4074 | ETH transfers not allowed. | The contract proxy does not accept ETH deposits. Its receive() function reverts unconditionally because the proxy has no withdrawal mechanism, and any ETH sent would be permanently locked inside it. | Do not send ETH directly to this contract address. If your request includes a value field, set it to zero before resubmitting. | error | No | `ETHTransfersNotAllowed()` |
| DALP-4075 | Eip7702 sender not delegate. | The sender address has deployed code, but its bytecode does not start with the EIP-7702 delegation prefix (0xef0100). The EntryPoint requires the sender to be a valid EIP-7702 delegated account when an EIP-7702 initCode marker is present in the UserOperation. | Authorize the sender account as an EIP-7702 delegate before submitting this UserOperation. Verify the EIP-7702 authorization transaction landed on-chain for the sender address. | error | No | `Eip7702SenderNotDelegate(address)` |
| DALP-4076 | Eip7702 sender without code. | The sender address has no deployed bytecode. When the UserOperation includes an EIP-7702 `initCode` marker, the EntryPoint requires code at the sender address before reading its delegation target. | Submit the EIP-7702 authorization to establish the sender's delegation on-chain before sending this UserOperation. The sender must have bytecode present at the time the EntryPoint processes the operation. | error | No | `Eip7702SenderWithoutCode(address)` |
| DALP-4077 | Empty arrays provided. | A batch registration of topic schemes, system addons, compliance modules or token factories arrived with no entries. | Include at least one entry in the batch. | error | No | `EmptyArraysProvided()` |
| DALP-4078 | Empty expression not allowed. | The module configuration received an empty expression array. This module requires at least one claim-topic node to define its verification logic. | Supply a non-empty array of ExpressionNode entries when configuring this compliance module's scope. | error | No | `EmptyExpressionNotAllowed()` |
| DALP-4079 | Empty id. | The ID is zero, either as supplied or as returned by the implementation's `typeId()`. The directory needs a non-zero ID for every token type, compliance module and addon. | Supply a non-zero ID, or deploy an implementation whose `typeId()` returns one. | error | No | `EmptyId()` |
| DALP-4080 | Empty name. | You submitted a topic scheme registration or update with an empty name string. The registry requires every topic scheme to have a non-empty name, because the name computes the topic identifier. | Provide a non-empty string for the name parameter when registering or updating a topic scheme. | error | No | `EmptyName()` |
| DALP-4081 | Empty signature. | You submitted a topic scheme registration or update with an empty signature string. The registry requires every topic scheme to carry a non-empty ABI signature that describes the claim data type. | Provide a non-empty ABI type signature string for the signature parameter when registering or updating a topic scheme. | error | No | `EmptySignature()` |
| DALP-4082 | Exceeded cap. | Minting the requested amount would push the token's total supply above its configured cap. The error returns the would-be supply (newSupply) and the maximum allowed supply (cap). | Reduce the mint amount so that the resulting total supply stays at or below the cap value returned in the error. | error | No | `ExceededCap(uint256,uint256)` |
| DALP-4083 | Execution already performed. | The contract already carried out the execution request identified by executionId. An ERC-734 execution can only run once; the contract marks it as executed on success and rejects any further approval attempts. | Check the execution state before calling approve. If you need to perform the same call again, create a new execution request with execute() to receive a fresh executionId. | error | No | `ExecutionAlreadyPerformed(uint256)` |
| DALP-4084 | Execution failed. | A low-level call that the contract expected to succeed returned a failure indicator. The calling contract reverts to surface this failure rather than silently continuing. | Check the target contract address and calldata for correctness. Simulate the call to inspect any revert data before retrying. | error | No | `ExecutionFailed()` |
| DALP-4085 | Execution request not found. | The executionId you supplied to approve() is greater than or equal to the current execution nonce, so no execution request with that identifier exists on this identity contract. | Retrieve the correct executionId from the ExecutionRequested event that execute() emitted when the execution was first created, then retry with that value. | error | No | `ExecutionIdDoesNotExist(uint256)` |
| DALP-4086 | Expression stack overflow. | The compliance expression evaluator's internal boolean stack overflowed during postfix evaluation. This occurs when the expression pushes more intermediate results than the stack can hold at once, typically from deeply nested or unbalanced operator sequences. | Reduce the nesting depth of AND, OR and NOT operators, and keep the postfix expression balanced. | error | No | `ExpressionStackOverflow()` |
| DALP-4087 | Expression too complex. | The compliance expression contains more than 32 nodes (MAX_EXPRESSION_NODES). The contract enforces this limit to bound gas consumption during expression evaluation. | Reduce the expression to 32 nodes or fewer. Combine related claim topics before you encode the expression. | error | No | `ExpressionTooComplex()` |
| DALP-4088 | Failed deployment. | The CREATE2 or clone deployment returned no contract. Its constructor reverted without a reason, or a contract already exists at that address. | Send the request with an unused deployment address and valid constructor arguments. | error | No | `FailedDeployment()` |
| DALP-4089 | Failed op. | The ERC-4337 EntryPoint rejected the UserOperation at index opIndex during handleOps. The reason string identifies the failing component: AA1x means factory, AA2x means account, AA3x means paymaster. | Read the reason string to identify which component failed (factory, account, or paymaster) and the specific error code. Run simulateValidation to diagnose the rejection before resubmitting. | error | No | `FailedOp(uint256,string)` |
| DALP-4090 | Failed op with revert. | The ERC-4337 EntryPoint rejected the UserOperation at index opIndex, and the sub-call provided additional revert data in inner. The reason string identifies the failing component (factory, account, or paymaster) as in FailedOp. | Decode the inner bytes to read the nested revert reason from the sub-call. Use simulateValidation to reproduce the failure and identify the root cause before resubmitting. | error | No | `FailedOpWithRevert(uint256,string,bytes)` |
| DALP-4091 | Failed send to beneficiary. | After processing UserOperations, the EntryPoint attempted to transfer collected fees to the beneficiary address but the ETH transfer failed. The revertData field contains the inner revert from the beneficiary contract. | Ensure the beneficiary address can accept ETH (it must not revert on receive). Inspect the revertData to diagnose why the beneficiary rejected the transfer. | error | No | `FailedSendToBeneficiary(address,uint256,bytes)` |
| DALP-4092 | Feature already exists. | A feature of this type is already deployed for the given token address. The token feature factory stores one feature per (token, feature-type) pair and rejects a second creation for the same token. | Query the factory to retrieve the existing feature address for this token before creating a new one. Use replaceFeature instead of createFeature if you need to swap the existing feature. | error | No | `FeatureAlreadyExists()` |
| DALP-4093 | Feature creation failed. | Deploying the permit feature with CREATE2 returned no contract: the address is already taken or the constructor reverted. | Check whether the token already has a permit feature. If it has none, contact support with the `requestId` from the error. | error | No | `FeatureCreationFailed()` |
| DALP-4094 | Feature factory not registered. | The asset factory looks up the addon `<featureType>-feature-factory` in the system addon registry and finds none. | Register a feature factory for this feature type in the addon registry before creating an asset that uses it. Use the feature type name exactly as registered, for example `historical-balances`. | error | No | `FeatureFactoryNotFound(bytes32)` |
| DALP-4095 | Future lookup. | The requested timepoint is ahead of the contract's current clock value. Historical balance and supply queries only accept timepoints at or before the current block, so the contract blocks the call to prevent reads of data that does not exist yet. | Pass a timepoint at or before the current block when querying historical balances or total supply. The error returns both the requested timepoint and the current timepoint so you can correct the value. | error | No | `FutureLookup(uint256,uint48)` |
| DALP-4096 | Global module already added. | The compliance module at the provided address is already registered as a global module. The registry tracks modules by address and rejects duplicate additions to prevent the same rules from applying twice. | Check the current list of global compliance modules before calling addGlobalComplianceModule. If the module is already present, no further registration is needed. | error | No | `GlobalModuleAlreadyAdded(address)` |
| DALP-4097 | Global compliance module not found. | The compliance module at the provided address is not currently registered as a global module. The operation (remove or update parameters) requires the module to exist in the global registry. | Verify the module address is correct and confirm it has been added as a global compliance module before attempting to remove or update it. | error | No | `GlobalModuleNotFound(address)` |
| DALP-4098 | Governor already cast vote. | The voter address has already submitted a vote for this proposal. The Governor contract records each vote by address per proposal and rejects a second vote from the same address. | Each address may vote only once per proposal. Check whether the address has already voted before submitting a castVote call. | error | No | `GovernorAlreadyCastVote(address)` |
| DALP-4099 | Governor already queued proposal. | The Governor has already queued this proposal in the timelock. A proposal can only be queued once, and the Governor rejects a second queue request for the same proposalId. | Check the proposal state before calling queue. If the proposal is already in the Queued state, wait for the timelock delay to expire and then execute it directly. | error | No | `GovernorAlreadyQueuedProposal(uint256)` |

The previous page is [DALP-4000 to DALP-4049](https://docs.settlemint.com/docs/api-reference/errors/error-code-reference/dalp-4000-4049). The next page is [DALP-4100 to DALP-4149](https://docs.settlemint.com/docs/api-reference/errors/error-code-reference/dalp-4100-4149).


# DALP-4100 to DALP-4149

Source: https://docs.settlemint.com/docs/api-reference/errors/error-code-reference/dalp-4100-4149
Cause, fix and retry flag for every on-chain contract error with a code from DALP-4100 to DALP-4149.

This page lists the 50 errors in the contract error reference with a code from DALP-4100 to DALP-4149. Match the error's `id`, or its `dalpCode` on a contract error or a failed deployment step, for example `DALP-4100`, to the DALP Code column, then read Retryable and Suggested Fix. The [contract error reference](https://docs.settlemint.com/docs/api-reference/errors/error-code-reference#how-to-use-this-reference) explains each column, including Severity, and the [DALP error index](https://docs.settlemint.com/docs/api-reference/errors) lists the page for every code range.

| DALP Code | Message | Why | Suggested Fix | Severity | Retryable | Solidity Error |
| --- | --- | --- | --- | --- | --- | --- |
| DALP-4100 | Governor disabled deposit. | The governor refuses ETH, ERC-721 and ERC-1155 transfers because its timelock holds the treasury. | Send the funds or tokens to the governance timelock instead. | error | No | `GovernorDisabledDeposit()` |
| DALP-4101 | Governor insufficient proposer votes. | The proposer's current voting weight is below the proposal threshold required by the Governor. The contract compares the proposer's votes at the current block against the configured threshold and blocks proposals that do not meet it. | The error returns the proposer address, current votes, and the required threshold. Increase the proposer's delegated voting weight to at least the threshold value before submitting a proposal. | error | No | `GovernorInsufficientProposerVotes(address,uint256,uint256)` |
| DALP-4102 | Proposal arrays have mismatched or zero length. | The `propose` call requires the `targets`, `values`, and `calldatas` arrays to be the same length and to contain at least one entry. The contract received arrays whose lengths differ or all three are empty. | Ensure `targets`, `values`, and `calldatas` each contain the same number of entries and that the proposal includes at least one call before submitting. | error | No | `GovernorInvalidProposalLength(uint256,uint256,uint256)` |
| DALP-4103 | Vote signature does not match the stated voter. | The signature supplied to `castVoteBySig` or `castVoteWithReasonAndParamsBySig` did not recover to the voter address. The contract verifies the EIP-712 signature before recording the vote. | Re-sign the ballot with the voter's key over `proposalId`, `support`, `voter` and the voter's current `nonces(voter)` value. For the extended call, sign `reason` and `params` too. | error | No | `GovernorInvalidSignature(address)` |
| DALP-4104 | Vote params have the wrong length for the chosen vote type. | When casting a full vote (`support` 0, 1, or 2), the `params` field must be empty. When casting a fractional vote (`support` 255), `params` must be exactly 48 bytes encoding three packed `uint128` values (againstVotes, forVotes, abstainVotes). | Pass an empty `params` for a full vote, or pass exactly 48 bytes encoded as `abi.encodePacked(uint128, uint128, uint128)` for a fractional vote. | error | No | `GovernorInvalidVoteParams()` |
| DALP-4105 | Vote support value is outside the accepted range. | In a For/Against/Abstain proposal, `support` accepts only 0 (Against), 1 (For) or 2 (Abstain). | Set `support` to 0, 1 or 2. | error | No | `GovernorInvalidVoteType()` |
| DALP-4106 | Voting period must be at least one block. | The Governor contract requires the voting period to be a positive value. A voting period of zero would open and immediately close every proposal, so the contract rejects it. | Set the voting period to a value greater than zero when calling `setVotingPeriod` or during Governor initialization. | error | No | `GovernorInvalidVotingPeriod(uint256)` |
| DALP-4107 | Governor nonexistent proposal. | No proposal exists with the given proposalId. The Governor derives proposal IDs deterministically from the proposal parameters; an ID that was never created returns no record. | Verify the proposalId by recomputing it from the original proposal parameters (targets, values, calldatas, description hash) or by reading it from the ProposalCreated event the contract emitted when you submitted the proposal. | error | No | `GovernorNonexistentProposal(uint256)` |
| DALP-4108 | Governor not queued proposal. | The proposal is not in the Queued state. Executing a proposal through a timelock-backed Governor requires you to queue the proposal first and wait for the timelock delay to elapse. | Check the proposal state. If it is in the Succeeded state, call queue first. If it is already Queued, wait for the timelock delay to pass before calling execute. | error | No | `GovernorNotQueuedProposal(uint256)` |
| DALP-4109 | Governor only executor. | An address other than the Governor's designated executor (typically the timelock contract) sent this call. Governor operations like relay require the executor itself to send the message. | Route this call through the governance execution path rather than sending it directly. Submit the operation as a governance proposal and let the timelock execute it. | error | No | `GovernorOnlyExecutor(address)` |
| DALP-4110 | Governor queue unavailable on this contract. | You called queue on a Governor that has no timelock or queue module. This Governor executes proposals directly without a queuing phase. | Do not call queue on this Governor. After a proposal reaches the Succeeded state, call execute directly. | error | No | `GovernorQueueNotImplemented()` |
| DALP-4111 | Governor restricted proposer. | The proposal description ends with `#proposer=<address>`, which reserves the proposal for that address. A different address submitted it. | Submit from the address named in the description, or drop the `#proposer=` suffix. | error | No | `GovernorRestrictedProposer(address)` |
| DALP-4112 | Governor unable to cancel. | A proposal can be cancelled only while it is Pending or Queued. Only an account that holds the token's governance role can cancel it. | Cancel from an account with the token's governance role, before voting starts or while the proposal waits in the timelock. | error | No | `GovernorUnableToCancel(uint256,address)` |
| DALP-4113 | Governor unexpected proposal state. | The proposal is in a lifecycle state that does not permit the requested operation. For example, queuing requires Succeeded, executing requires Succeeded or Queued, and voting requires Active. The error carries the current state and a bitmask of acceptable states. | Read the proposal state before performing governance operations. The error returns the current state and the expected states bitmask so you can determine what step to take next in the proposal lifecycle. | error | No | `GovernorUnexpectedProposalState(uint256,uint8,bytes32)` |
| DALP-4114 | Hard cap exceeded. | The requested token purchase would push the total amount sold past the sale's hard cap. The contract tracks cumulative tokens sold and rejects any purchase that would exceed the configured maximum supply for this sale. | Reduce the purchase amount so that the total sold does not exceed the hard cap. You can query totalSold and hardCap on the token sale contract to determine the remaining capacity. | error | No | `HardCapExceeded()` |
| DALP-4115 | Hard cap must be positive. | You submitted a token sale creation request with a hard cap of zero. The factory requires a positive hard cap to define the maximum number of tokens available for sale. | Provide a hardCap value greater than zero when calling createTokenSale. | error | No | `HardCapMustBePositive()` |
| DALP-4116 | Hashlock reveal not required. | You called revealSecret on an XvP settlement that has no external cross-chain flows. Hashlock secret revelation applies only to settlements that involve external flows; settlements with only local flows do not use a hashlock. | Check the settlement's hasExternalFlows flag before calling revealSecret. For settlements with only local flows, proceed directly to execution without revealing a secret. | error | No | `HashlockRevealNotRequired()` |
| DALP-4117 | History not supported. | The price feed runs in LATEST_ONLY mode, which retains only the most recent observation. The Chainlink-compatible getRoundData function requires historical round storage, which this feed does not maintain. | Use latestRoundData to retrieve the most recent value from this feed, or use the indexed API for past accepted observations. For historical reads directly from a contract, register a separately deployed compatible feed that retains history. | error | No | `HistoryNotSupported()` |
| DALP-4118 | Identities required. | The transfer-approval compliance module checks that both the sender and the recipient have a registered on-chain identity. When either party's identity address resolves to zero, the contract cannot look up a valid approval record and blocks the transfer. | Ensure both the sending and receiving wallet addresses have an on-chain identity registered in the identity registry before submitting this transfer. | error | No | `IdentitiesRequired()` |
| DALP-4119 | Implementation not set in factory. | The proxy contract queries the factory for its logic implementation address at deployment time. The factory holds no implementation address yet, so the returned address is zero and the proxy cannot initialize. | Set a valid implementation address on the factory before deploying or upgrading this proxy. | error | No | `ImplementationNotSetInFactory()` |
| DALP-4120 | Index out of bounds. | The index you supplied is greater than or equal to the total number of deployed systems recorded in the factory. The contract cannot return a system at a position that does not exist. | Call getSystemCount() first to check the valid range, then supply an index between 0 and getSystemCount() minus 1. | error | No | `IndexOutOfBounds(uint256,uint256)` |
| DALP-4121 | Initial key already setup. | The ERC-734 identity contract already has a management key set during initialization. The contract rejects a second initialization call to prevent overwriting the existing key set. | The identity contract is already fully initialized. No further key setup call is needed. To change keys, use the key-management functions on the live identity instead. | error | No | `InitialKeyAlreadySetup()` |
| DALP-4122 | Initialization deadline passed. | The vesting airdrop contract requires claimants to initialize their vesting schedule before a fixed deadline. The current block timestamp is past that deadline, so new vesting initializations are no longer accepted. | Contact the token issuer to ask whether a new airdrop round will open. | error | No | `InitializationDeadlinePassed()` |
| DALP-4123 | Initialization with zero address. | You supplied a zero address as the implementation for this proxy to delegate to. A proxy cannot forward calls to the zero address, so initialization is rejected. | Supply a valid, non-zero implementation contract address when deploying or initializing this proxy. | error | No | `InitializationWithZeroAddress()` |
| DALP-4124 | This amount is more than the interest accrued. | The requested amount exceeds the interest this holder has accrued and has not claimed or converted. | Reduce the amount to at most the accrued interest, or wait for more interest to accrue, then retry. | error | No | `InsufficientAccruedInterest(uint256,uint256)` |
| DALP-4125 | This withdrawal is more than the deposit held in the EntryPoint. | The ERC-4337 EntryPoint rejected a deposit withdrawal because the requested withdrawal amount exceeds the account's or paymaster's current deposit balance held in the EntryPoint. | Reduce the withdrawal amount to at most the current deposited balance shown in the EntryPoint for this account or paymaster. | error | No | `InsufficientDeposit(uint256,uint256)` |
| DALP-4126 | Conversion amount exceeds the holder's token balance. | The conversion requested a principal amount that exceeds the holder's current token balance. The contract validates the available balance before executing any conversion. | Reduce the principal conversion amount to at most the holder's current token balance, or pass zero to convert the full available balance. | error | No | `InsufficientPrincipal(uint256,uint256)` |
| DALP-4127 | This transaction does not have enough signer confirmations. | The DALPVault multisig transaction requires a minimum number of valid signer confirmations before execution. The number of signatures provided is below that required threshold. | Collect the remaining required signatures from authorized vault signers and resubmit the transaction. | error | No | `InsufficientSignatures(uint256,uint256)` |
| DALP-4128 | The signers' combined weight is below the required threshold. | The DALPVault multisig uses weighted signatures and requires the combined weight of all provided signers to meet or exceed a configured threshold. The total weight of the submitted signatures is below that threshold. | Add signatures from higher-weight signers or collect more signer confirmations until the combined weight meets the required threshold. | error | No | `InsufficientWeight(uint256,uint256)` |
| DALP-4129 | Interest provider missing. | The conversion feature targets accrued interest, and it needs exactly one interest provider. The configuration names none, and the token has none attached or more than one. | Attach one interest provider to the token, or set it explicitly in the conversion configuration. | error | No | `InterestProviderMissing()` |
| DALP-4130 | Interface registration limit reached. | Each SMART token extension can register a fixed maximum number of ERC-165 interface identifiers. The contract has filled all available slots in the interface registry, so it cannot accept another interface. | Contact support with the token address and the `requestId` from the error. | error | No | `InterfaceRegistrationLimitReached()` |
| DALP-4131 | Internal function. | The ERC-4337 EntryPoint rejected a direct external call to a function that only the EntryPoint itself may call as part of its internal user-operation processing loop. | This function is part of the EntryPoint's internal execution flow. Submit the operation through the standard ERC-4337 user-operation submission path instead of calling this function directly. | error | No | `InternalFunction()` |
| DALP-4132 | Interoperable address empty reference and address. | When formatting an ERC-7930 interoperable address, both the chain reference and the address components were empty. At least one of the two components must contain data for the encoding to be valid. | Provide either a non-empty chain reference, a non-empty address component, or both when constructing the interoperable address. | error | No | `InteroperableAddressEmptyReferenceAndAddress()` |
| DALP-4133 | Interoperable address parsing error. | The byte sequence supplied does not conform to the ERC-7930 version-1 interoperable address encoding. The parser could not extract a valid version header, chain type, chain reference, or address from the input. | Verify that a conforming ERC-7930 v1 encoder produced the interoperable address bytes and that no bytes were truncated or corrupted before submitting. | error | No | `InteroperableAddressParsingError(bytes)` |
| DALP-4134 | Access manager must implement the required interface. | The contract initialization checks that the access manager address supports the `IDALPSystemAccessManager` interface via ERC-165. The provided address failed that check. | Pass the address of a deployed `IDALPSystemAccessManager`-compliant contract to the initializer. | error | No | `InvalidAccessManager()` |
| DALP-4135 | Nonce does not match the account's current nonce. | The contract uses OpenZeppelin's `Nonces` utility to prevent replay attacks. The nonce supplied with the signed message does not equal the account's stored current nonce. | Fetch the account's current nonce from the contract before signing, and include that value in the message. | error | No | `InvalidAccountNonce(address,uint256)` |
| DALP-4136 | Addon implementation address is zero. | The system addon registry requires a non-zero implementation address when registering a new addon. The `implementation_` argument passed to `registerSystemAddon` was the zero address. | Deploy the addon implementation contract and pass its address to `registerSystemAddon`. | error | No | `InvalidAddonAddress()` |
| DALP-4137 | Address is zero or not usable. | An address argument is the zero address, or the contract it names lacks the interface the call needs. | Pass a non-zero address of the right contract type. | error | No | `InvalidAddress()` |
| DALP-4138 | Withdrawal amount is zero. | The fixed yield schedule contract requires a non-zero denomination asset amount when withdrawing. A withdrawal of zero tokens is not a valid operation. | Specify a non-zero amount of denomination asset tokens to withdraw. | error | No | `InvalidAmount()` |
| DALP-4139 | Claim authorization contract address is zero or missing the required interface. | The contract validates each authorization contract by calling `supportsInterface` for `IClaimAuthorizer`. The provided address is either the zero address or a contract that did not return true for that interface check. | Supply the address of a deployed contract that correctly implements `IClaimAuthorizer` and passes ERC-165 interface detection. | error | No | `InvalidAuthorizationContract(address)` |
| DALP-4140 | Yield basis-per-unit is zero. | The fixed treasury yield schedule requires a non-zero `basisPerUnit` value. A value of zero produces no yield and is treated as a configuration error. | Set `basisPerUnit` to a positive integer equal to the yield amount per token unit before submitting the schedule. | error | No | `InvalidBasisPerUnit()` |
| DALP-4141 | Fee beneficiary address is zero. | The EIP-4337 EntryPoint requires the beneficiary address passed to `handleOps` to be a non-zero address. A zero address cannot receive the gas-cost refund. | Pass a valid, non-zero address as the `beneficiary` argument when calling `handleOps`. | error | No | `InvalidBeneficiary(address)` |
| DALP-4142 | Token supply cap is zero or below the current total supply. | The contract enforces a cap that must be greater than zero and, when updated, must be at least as large as the current total supply. A cap of zero would make minting impossible, and a cap below current supply would be inconsistent. | Provide a cap value that is greater than zero and greater than or equal to the current token total supply. | error | No | `InvalidCap(uint256)` |
| DALP-4143 | Contract address is zero or not supported. | The call needs a non-zero contract address: a subject for the trusted issuers meta-registry, an owning contract that implements `IContractWithIdentity` for a contract identity, or each extra management key of a contract identity. | Provide the actual on-chain address of the subject whose registry entry is being configured. | error | No | `InvalidContractAddress()` |
| DALP-4144 | Conversion window end is at or before the start, or already past. | The contract checks two conditions: the window end must be after the window start, and the window end minus one must be at or after the current block timestamp. The provided window fails at least one of these checks. | Set the window start to a time before the window end, and set the end to a future timestamp (at least one second ahead of the current block time). | error | No | `InvalidConversionWindow(uint256,uint256)` |
| DALP-4145 | Token decimal precision exceeds the maximum of 18. | The SMART token core enforces a maximum of 18 decimal places to remain compatible with WAD-based fixed-point arithmetic. A decimals value above 18 is out of range. | Set the `decimals` parameter to a value between 0 and 18 inclusive. | error | No | `InvalidDecimals(uint8)` |
| DALP-4146 | Denomination asset is not valid. | The denomination asset is the zero address or the token itself, or, for a bond, a contract that does not answer `totalSupply()`. Bonds, maturity redemption, conversion and the yield features check it at setup. A fixed yield schedule also raises it when a withdrawal names the zero address as recipient. | Supply the address of a deployed ERC-20 that is not this token. For a schedule withdrawal, name a non-zero recipient. | error | No | `InvalidDenominationAsset()` |
| DALP-4147 | Feeds directory address is zero. | The scalar feed aggregator adapter stores the directory address as an immutable at construction time. A zero address cannot be used as a feeds directory. | Pass the address of the deployed `IFeedsDirectory` contract when constructing the adapter. | error | No | `InvalidDirectory()` |
| DALP-4148 | Directory address is zero. | Several contracts (the system factory, the global trusted issuers registry, and the topic scheme registry) require a non-zero directory address during initialization. Without a valid directory the contract cannot resolve implementation addresses. | Provide the address of the deployed `IDALPDirectory` contract during construction or initialization. | error | No | `InvalidDirectoryAddress()` |
| DALP-4149 | Yield end date is not after the start date. | The fixed treasury yield schedule requires the end date to be strictly greater than the start date. Providing an end date equal to or before the start date produces a zero-length or reversed schedule. | Set the end date to a timestamp that is at least one second after the start date. | error | No | `InvalidEndDate()` |

The previous page is [DALP-4050 to DALP-4099](https://docs.settlemint.com/docs/api-reference/errors/error-code-reference/dalp-4050-4099). The next page is [DALP-4150 to DALP-4199](https://docs.settlemint.com/docs/api-reference/errors/error-code-reference/dalp-4150-4199).


# DALP-4150 to DALP-4199

Source: https://docs.settlemint.com/docs/api-reference/errors/error-code-reference/dalp-4150-4199
Cause, fix and retry flag for every on-chain contract error with a code from DALP-4150 to DALP-4199.

This page lists the 50 errors in the contract error reference with a code from DALP-4150 to DALP-4199. Match the error's `id`, or its `dalpCode` on a contract error or a failed deployment step, for example `DALP-4150`, to the DALP Code column, then read Retryable and Suggested Fix. The [contract error reference](https://docs.settlemint.com/docs/api-reference/errors/error-code-reference#how-to-use-this-reference) explains each column, including Severity, and the [DALP error index](https://docs.settlemint.com/docs/api-reference/errors) lists the page for every code range.

| DALP Code | Message | Why | Suggested Fix | Severity | Retryable | Solidity Error |
| --- | --- | --- | --- | --- | --- | --- |
| DALP-4150 | Airdrop end time is not after the start time. | The time-bound airdrop requires its end time to be strictly greater than the start time. An end time equal to or before the start time creates a zero-length or reversed claim window. | Set the end time to a timestamp at least one second after the start time. | error | No | `InvalidEndTime()` |
| DALP-4151 | Compliance expression does not reduce to exactly one result. | The identity-verification compliance module evaluates a postfix boolean expression. After processing all operands and operators the evaluation stack must contain exactly one value. A stack count other than one means the expression is structurally malformed. | Correct the compliance expression so every operator consumes the right number of operands and the final stack holds exactly one boolean result. | error | No | `InvalidExpressionMustEvaluateToOneResult()` |
| DALP-4152 | Identity verification expression stack did not resolve to a single result. | After evaluating the postfix claim expression in `IdentityVerificationLib`, the internal stack index must equal 1. A stack index other than 1 indicates unbalanced operators or extra operands remain. | Review the postfix expression for unbalanced operators or extra operands, then resubmit with a well-formed expression that leaves exactly one value on the stack. | error | No | `InvalidExpressionStackResult()` |
| DALP-4153 | XvP flow external chain ID matches the current chain. | An XvP settlement flow marked as external must reference a different blockchain. The provided `externalChainId` equals the chain ID of the contract's own network. | Set `externalChainId` to the chain ID of the remote network involved in the cross-chain leg, not the chain where this contract is deployed. | error | No | `InvalidExternalChainId(uint64)` |
| DALP-4154 | Bond face value is zero. | A bond's face value is the principal amount and must be a positive integer. A face value of zero makes the bond economically meaningless and is rejected at initialization. | Set `faceValue` to the intended positive principal amount before initializing the bond. | error | No | `InvalidFaceValue()` |
| DALP-4155 | Factory address is zero or not a matching factory. | The proxy checks that its factory address is non-zero and supports the factory interface through ERC-165. The address failed one of these checks. | Supply the address of the deployed factory for this proxy type, one that reports its factory interface through ERC-165. | error | No | `InvalidFactoryAddress()` |
| DALP-4156 | Token feature configuration data failed validation. | The Booked movements feature takes exactly one 32-byte word of configuration: the set of request kinds holders may open. The configuration had a different length. | Encode the requestable kinds as one `uint256`. | error | No | `InvalidFeatureConfig()` |
| DALP-4157 | Global trusted issuers registry lacks the required interface. | Migrating to V2 or setting the global registry checks through ERC-165 that the address implements `IDALPTrustedIssuersRegistry`. It does not. | Provide the address of a contract that implements `IDALPTrustedIssuersRegistry` and reports it through ERC-165. | error | No | `InvalidGlobalRegistryAddress(address)` |
| DALP-4158 | Feed history size is zero in BOUNDED mode. | When the issuer-signed scalar feed is configured in BOUNDED history mode, it must retain at least one historical entry. A `historySize` of zero is not permitted in this mode. | Set `historySize` to a positive integer equal to the number of historical entries the feed should retain. Switch to UNBOUNDED mode if a fixed history size is not needed. | error | No | `InvalidHistorySize()` |
| DALP-4159 | Proposed implementation does not support the required contract interface. | The contract requires any registered implementation to pass an ERC-165 interface check before it is accepted. The address provided does not advertise the expected interface. | Supply an implementation contract that correctly implements and advertises the required interface via ERC-165 `supportsInterface`. | error | No | `InvalidImplementation()` |
| DALP-4160 | Implementation address is not valid. | A token factory rejects a token implementation that is the zero address, does not support the SMART token interface, or does not fit the factory. The compliance module registry rejects a zero implementation address. | Provide the address of a deployed token implementation contract that supports the required SMART token interface. | error | No | `InvalidImplementationAddress()` |
| DALP-4161 | Implementation contract does not support the expected module interface. | The contract checks via ERC-165 that the supplied implementation address supports a specific interface (identified by `interfaceId`). The address must implement ERC-165 and advertise support for that interface. | Supply the address of an implementation contract that supports the interface identified by the `interfaceId` field returned in the error. | error | No | `InvalidImplementationInterface(address,bytes4)` |
| DALP-4162 | Initial management key address is the zero address. | ERC-734 identity setup requires a non-zero management key to seed the key store. A zero address was provided. | Provide a valid, non-zero wallet address as the initial management key. | error | No | `InvalidInitialManagementKey()` |
| DALP-4163 | Contract already initialized. | OpenZeppelin's `Initializable` guard prevents a contract from being initialized more than once. The contract's initialization slot is already consumed. | Call `initialize` only once, at deployment time. If an upgrade is needed, use the appropriate reinitializer function for the new version. | error | No | `InvalidInitialization()` |
| DALP-4164 | Initialization deadline must be at least one second in the future. | The vesting airdrop contract requires `initializationDeadline` to be strictly greater than the current block timestamp. A value at or before the current time was supplied. | Set the initialization deadline to a timestamp that is at least one second after the current block time. | error | No | `InvalidInitializationDeadline()` |
| DALP-4165 | Batch input arrays have mismatched lengths. | A batch claim, distribution or vesting call needs input arrays of equal length. The arrays provided have different lengths. | Ensure all arrays passed to the batch call contain the same number of elements. | error | No | `InvalidInputArrayLengths()` |
| DALP-4166 | Yield distribution interval must be greater than zero. | The yield schedule configuration requires a non-zero distribution interval (in seconds). A value of zero was supplied. | Set the distribution interval to a positive number of seconds representing how often yield is distributed. | error | No | `InvalidInterval()` |
| DALP-4167 | Trusted issuer address is the zero address. | Registering a trusted issuer requires a non-zero contract address. A zero address was provided. | Provide the address of a deployed claim issuer contract as the trusted issuer. | error | No | `InvalidIssuerAddress()` |
| DALP-4168 | Source wallet is not lost or caller is not its replacement. | Token recovery requires the source wallet to be marked as lost in the identity registry, and the caller's new wallet must match the registry's recorded replacement for that source. One of these conditions was not met. | Confirm that the wallet to recover from is marked as lost in the identity registry and that the recovery is initiated from the wallet designated as its replacement. | error | No | `InvalidLostWallet()` |
| DALP-4169 | Address is not a recognized compliance module. | The compliance contract requires each module address to be non-zero and to declare support for `ISMARTComplianceModule` via ERC-165. The address provided failed this check. | Supply the address of a deployed contract that correctly implements and advertises `ISMARTComplianceModule`. | error | No | `InvalidModule()` |
| DALP-4170 | Feed update nonce is out of sequence. | The issuer-signed scalar feed requires each update's nonce to be exactly one greater than the issuer's last accepted nonce. The nonce in the submitted update does not match this expected value. | Fetch the current nonce for the issuer from the feed contract and submit the update with a nonce equal to that value plus one. | error | No | `InvalidNonce()` |
| DALP-4171 | Feed update observedAt timestamp is zero. | The issuer-signed scalar feed requires a non-zero `observedAt` timestamp in every update. A zero value was submitted. | Set `observedAt` to the Unix timestamp (in seconds) at which the data value was observed. | error | No | `InvalidObservedAt()` |
| DALP-4172 | OnchainID address is the zero address. | `setOnchainId` on a yield schedule or a smart account received the zero address. | Provide the address of the deployed OnchainID contract. | error | No | `InvalidOnchainID()` |
| DALP-4173 | OnchainID address is the zero address. | The XvP settlement contract requires a non-zero OnchainID address when the factory calls `setOnchainId`. A zero address was provided. | Provide the address of the deployed OnchainID contract for this settlement instance. | error | No | `InvalidOnchainId()` |
| DALP-4174 | Sale parameter is zero or out of range. | The token sale contract validates each numeric configuration parameter (sale duration, hard cap, token decimals, price ratio, soft cap, presale settings, extension duration). A value of zero or an out-of-range value was supplied for one of these. | Review the sale configuration and ensure all numeric parameters are non-zero and within accepted bounds. Token decimals must not exceed 24. | error | No | `InvalidParameter()` |
| DALP-4175 | Asset configuration has an empty required field. | The asset factory requires non-empty `name`, `symbol`, and `assetTypeName` strings in the configuration. At least one of these fields was an empty string. | Provide non-empty values for `name`, `symbol`, and `assetTypeName` in the asset configuration. | error | No | `InvalidParameters()` |
| DALP-4176 | Compliance module configuration parameters are not accepted. | A compliance module's `validateParameters` function rejected the provided configuration bytes. The error includes a reason string describing the specific constraint that was violated (for example, empty parameters, a zero hold period, or a duplicate entry). | Consult the reason string in the error and correct the module configuration to satisfy that constraint before resubmitting. | error | No | `InvalidParameters(string)` |
| DALP-4177 | Paymaster field in the user operation decodes to the zero address. | The EIP-4337 EntryPoint unpacks the `paymasterAndData` field of the user operation and requires the extracted paymaster address to be non-zero. The decoded address was the zero address. | Supply a valid, non-zero paymaster contract address in the `paymasterAndData` field, or omit `paymasterAndData` entirely to use no paymaster. | error | No | `InvalidPaymaster(address)` |
| DALP-4178 | The paymasterAndData field is shorter than the minimum required length. | The EIP-4337 EntryPoint requires `paymasterAndData`, when present, to be at least `PAYMASTER_DATA_OFFSET` bytes long so it can unpack the paymaster address and gas limits. The field provided is shorter than this minimum. | Encode `paymasterAndData` with the full required structure: paymaster address (20 bytes) followed by verification gas limit and post-op gas limit (each packed as uint128), then any additional paymaster-specific data. | error | No | `InvalidPaymasterData(uint256)` |
| DALP-4179 | Paymaster signature length exceeds available paymaster data. | The ERC-4337 entry point decoded a `pmSignatureLength` value from the paymaster-and-data field that would extend before the start of the paymaster data. The encoded length must fit within the data that follows the fixed paymaster header. | Reconstruct the paymaster-and-data payload so that the appended signature length value does not exceed `dataLength` minus the minimum paymaster data size with suffix. | error | No | `InvalidPaymasterSignatureLength(uint256,uint256)` |
| DALP-4180 | Payment currency rejected for this token sale. | The contract rejects a payment currency that is the sale token itself, any ERC20 token whose `decimals()` call reverts, or any token with more than 24 decimal places. All three conditions prevent safe price conversion. | Use a different ERC20 token as the payment currency. Confirm the token is not the sale token, that its `decimals()` function returns successfully, and that the returned value is 24 or below. | error | No | `InvalidPaymentCurrency()` |
| DALP-4181 | Period number is outside the range of configured yield periods. | The fixed yield schedule reverts when the requested period is zero or greater than the total number of periods calculated from the schedule configuration. | Supply a period number between 1 and the value returned by the schedule's total-periods query. | error | No | `InvalidPeriod()` |
| DALP-4182 | Sale phase cannot transition to public sale from the current status. | The `transitionToPublicSale` function requires the sale to be in the `PRESALE` phase. Calling it from any other status, including `SETUP` or `PUBLIC_SALE`, causes a revert. | Activate the pre-sale phase first. Once the sale is in `PRESALE` status, call `transitionToPublicSale` to advance it. | error | No | `InvalidPhaseTransition()` |
| DALP-4183 | Token sale price calculation produced an unusable result. | A price computation within the token sale contract encountered parameters that would produce an overflow, division by zero, or otherwise unresolvable result. | Review the price ratio and token decimal configuration. Ensure the base price and payment currency ratio are both non-zero and that the resulting amount fits within the expected numeric range. | error | No | `InvalidPriceCalculation()` |
| DALP-4184 | Vesting or purchase range parameters are in the wrong order. | The contract enforces that `vestingCliff` does not exceed `vestingDuration`, and that `minPurchase` does not exceed `maxPurchase`. Either pairing is out of order. | Set the cliff to be less than or equal to the total vesting duration. Set the minimum purchase amount to be less than or equal to the maximum purchase amount. | error | No | `InvalidRange()` |
| DALP-4185 | Yield rate is zero or over the maximum. | A yield schedule needs a rate greater than zero. An interest schedule also caps the rate at 20,000 basis points, which is 200%. | Use a rate from 1 to 20,000 basis points. | error | No | `InvalidRate()` |
| DALP-4186 | Redemption owner address is the zero address. | The redeemable token extension requires a non-zero owner address when processing a redemption. Passing the zero address is rejected before any token movement occurs. | Supply the address of the account whose tokens are being redeemed. The address must be a valid, non-zero Ethereum address. | error | No | `InvalidRedeemAddress()` |
| DALP-4187 | Redemption amount must be greater than zero. | The redeemable token extension rejects a redemption call where the token amount is zero. Redeeming zero tokens has no effect and is treated as an error. | Provide a redemption amount that is at least 1 token unit. | error | No | `InvalidRedeemAmount()` |
| DALP-4188 | Registry address is the zero address. | The identity registry contract requires a non-zero address when setting a trusted issuers registry. The zero address cannot refer to a deployed contract. | Provide the address of a deployed trusted issuers registry contract. | error | No | `InvalidRegistryAddress()` |
| DALP-4189 | Registry address does not refer to a usable registry contract. | The contract encodes the provided address in the error and reverts because the address is not a valid registry. Zero addresses and addresses that fail the required interface check are both rejected. | Replace the registry address with the address of a correctly deployed and compatible registry contract. | error | No | `InvalidRegistryAddress(address)` |
| DALP-4190 | Required confirmation count exceeds the number of signers. | A multisig contract rejects any configuration where the number of required confirmations is greater than the total number of registered signers. Such a threshold can never be reached. | Set the required confirmation count to a value that is less than or equal to the current number of signers. | error | No | `InvalidRequirement(uint256,uint256)` |
| DALP-4191 | This operation cannot run while the sale is in its current status. | The operation needs a different sale status than the current one. | Check the current sale status and complete any prerequisite steps, such as activation or finalization, before retrying. | error | No | `InvalidSaleStatus()` |
| DALP-4192 | Feed topic schema hash does not match the required scalar schema. | The feeds directory only accepts topics whose schema hash equals `SCALAR_SCHEMA_HASH`. The topic's registered signature produced a different hash, meaning the topic is not typed as a scalar feed. | Register the feed under a topic whose schema signature matches the scalar schema, or register the topic with the correct scalar type signature before adding the feed. | error | No | `InvalidScalarSchemaHash(bytes32,bytes32)` |
| DALP-4193 | Secret preimage does not match the settlement hashlock. | The XvP settlement contract checks that `keccak256(secret)` equals the stored hashlock. The value provided does not produce the expected hash. | Provide the exact secret bytes whose keccak256 hash matches the hashlock stored in this settlement. | error | No | `InvalidSecret()` |
| DALP-4194 | ShortString storage encoding is corrupt. | The OpenZeppelin `ShortStrings` library encodes string length in the low byte of a `bytes32` slot. A value greater than 31 in that byte indicates a corrupt or miswritten short-string value. | Contact support with the `requestId` from the error. | error | No | `InvalidShortString()` |
| DALP-4195 | Signature malformed or verification failed. | The issuer-signed scalar feed rejected the signature. Its EIP-1271 envelope is malformed, ECDSA recovery returned the zero address, the EIP-1271 signer has no contract code or rejected the signature, or the `s` value is in the upper half of the curve order (malleable signature). | Re-sign the payload using the authorized issuer key. Ensure the signature uses the correct encoding for either the ECDSA path (65 bytes, canonical `s`) or the EIP-1271 path (abi-encoded signer address and inner signature). | error | No | `InvalidSignature()` |
| DALP-4196 | ECDSA signature must be exactly 65 bytes. | The issuer-signed scalar feed's ECDSA verification path requires a signature of exactly 65 bytes (32 bytes `r`, 32 bytes `s`, 1 byte `v`). A shorter or longer byte string cannot be decoded. | Provide a standard 65-byte ECDSA signature. If using a smart-wallet signer, use the EIP-1271 envelope path instead. | error | No | `InvalidSignatureLength()` |
| DALP-4197 | Recovered signer does not hold a CLAIM key on the issuer identity. | The issuer-signed scalar feed validates that the address that signed the payload holds key purpose 3 (CLAIM) on the issuer's on-chain identity contract. The recovered address does not satisfy this check. | Sign the payload with a key that is registered on the issuer identity contract with CLAIM purpose (purpose 3). Contact the issuer to add the signing key if needed. | error | No | `InvalidSigner()` |
| DALP-4198 | Stake amount is zero or exceeds the maximum allowed. | The ERC-4337 stake manager rejects a stake deposit when the resulting total stake is zero or exceeds `type(uint112).max`. Either no value was sent, or the cumulative stake would overflow the storage slot. | Send a non-zero ETH amount with the stake call. If the account already has a large existing stake, ensure the sum of the existing stake and the new deposit stays within the `uint112` maximum. | error | No | `InvalidStake(uint256,uint256)` |
| DALP-4199 | Yield schedule start date is not valid. | A fixed treasury schedule must start after the current block time. An interest schedule must start at or before it, and an ACT/360 interest schedule must start at UTC midnight. | Set a future start date for a fixed treasury schedule. For an interest schedule, set a start date at or before now. For ACT/360, set it at UTC midnight. | error | No | `InvalidStartDate()` |

The previous page is [DALP-4100 to DALP-4149](https://docs.settlemint.com/docs/api-reference/errors/error-code-reference/dalp-4100-4149). The next page is [DALP-4200 to DALP-4249](https://docs.settlemint.com/docs/api-reference/errors/error-code-reference/dalp-4200-4249).


# DALP-4200 to DALP-4249

Source: https://docs.settlemint.com/docs/api-reference/errors/error-code-reference/dalp-4200-4249
Cause, fix and retry flag for every on-chain contract error with a code from DALP-4200 to DALP-4249.

This page lists the 48 errors in the contract error reference with a code from DALP-4200 to DALP-4249. Match the error's `id`, or its `dalpCode` on a contract error or a failed deployment step, for example `DALP-4200`, to the DALP Code column, then read Retryable and Suggested Fix. The [contract error reference](https://docs.settlemint.com/docs/api-reference/errors/error-code-reference#how-to-use-this-reference) explains each column, including Severity, and the [DALP error index](https://docs.settlemint.com/docs/api-reference/errors) lists the page for every code range.

| DALP Code | Message | Why | Suggested Fix | Severity | Retryable | Solidity Error |
| --- | --- | --- | --- | --- | --- | --- |
| DALP-4200 | Airdrop start time is in the past. | The start time is before the current block timestamp. The claim window cannot open in the past. | Set the start time to the current time or later. | error | No | `InvalidStartTime()` |
| DALP-4201 | Identity registry storage address is zero. | The identity registry contract requires a non-zero address for its storage contract. A zero address was provided. | Supply the address of a deployed identity registry storage contract. | error | No | `InvalidStorageAddress()` |
| DALP-4202 | Subject address does not match the token's on-chain identity. | The trusted issuers registry on this token only accepts queries where the subject address equals the token's own `onchainID()`. The provided subject address differs from that value. | Pass the token's on-chain identity address as the subject parameter. | error | No | `InvalidSubjectAddress()` |
| DALP-4203 | System contract address is zero or missing the required interface. | The proxy requires a non-zero system address that supports the `IDALPSystem` interface. The provided address is either zero or does not pass the interface check. | Provide the address of a deployed system contract that correctly implements `IDALPSystem`. | error | No | `InvalidSystemAddress()` |
| DALP-4204 | Airdrop start and end times do not form a usable claim window. | The combination of start time and end time supplied for this airdrop does not form a valid claim window. The end time must be at least one second after the start time, and the start time must be in the future. | Set a future start time and an end time that is strictly after the start time before submitting. | error | No | `InvalidTimeWindow()` |
| DALP-4205 | Sale or vesting timestamp conflicts with required time ordering. | The contract enforces that sale start, vesting start, presale end, and sale end times form a valid, non-overlapping sequence. One of the supplied timestamps violates this ordering. | Ensure the sale start is in the future, the vesting start is after the sale end, and the presale end falls within the sale window. | error | No | `InvalidTiming()` |
| DALP-4206 | Topic ID zero is not allowed in compliance expressions. | The compliance module's expression evaluator requires each topic node to carry a non-zero topic ID. A topic node with value zero was found in the supplied expression. | Replace any topic node with value zero with a valid, non-zero topic ID before submitting the expression. | error | No | `InvalidTopicIdZeroNotAllowed()` |
| DALP-4207 | Topic scheme registry address is zero. | The feed or feeds directory requires a non-zero address for the topic scheme registry contract. A zero address was supplied during initialization. | Provide the address of a deployed topic scheme registry contract. | error | No | `InvalidTopicSchemeRegistry()` |
| DALP-4208 | Identity registry topic scheme registry address is zero. | The identity registry contract requires a non-zero address for the topic scheme registry when initializing or updating that reference. A zero address was provided. | Provide the address of a deployed topic scheme registry contract. | error | No | `InvalidTopicSchemeRegistryAddress()` |
| DALP-4209 | Treasury address is zero. | The maturity redemption, fixed treasury yield, dividend yield and interest yield features need a non-zero treasury address, at setup and on a treasury change. | Provide the non-zero address that funds the payouts. | error | No | `InvalidTreasury()` |
| DALP-4210 | Trusted issuers registry address is zero. | The issuer-signed scalar feed and the document anchor registry each need a trusted issuers registry at creation. The feed received the zero address, or the system the anchor registry reads from has no trusted issuers registry. | Pass a deployed trusted issuers registry to the feed. For an anchor registry, set up the system's trusted issuers registry first. | error | No | `InvalidTrustedIssuersRegistry()` |
| DALP-4211 | Unstake delay is zero or less than the current delay. | The ERC-4337 stake manager requires the new unstake delay to be greater than zero and at least as large as the previously set delay. The provided value violates one of these constraints. | Supply an unstake delay value that is greater than zero and greater than or equal to the current `unstakeDelaySec` recorded for this account. | error | No | `InvalidUnstakeDelay(uint256,uint256)` |
| DALP-4212 | User wallet address is zero. | The identity registry requires a non-zero wallet address when registering, recovering, or updating an identity. A zero address was supplied for the user wallet. | Supply the actual wallet address of the user whose identity is being registered or recovered. | error | No | `InvalidUserAddress()` |
| DALP-4213 | Withdrawal destination address is zero. | The airdrop contract requires a non-zero address as the destination when executing a token withdrawal. A zero address was passed as the recipient. | Provide a valid non-zero wallet or contract address as the withdrawal destination. | error | No | `InvalidWithdrawalAddress()` |
| DALP-4214 | Issuer already exists. | The trusted issuers registry already contains an entry for the supplied issuer address. The registry allows each issuer address to appear only once. | Check the current registry contents before adding an issuer. If the issuer's claim topics need updating, use the update function rather than adding a duplicate entry. | error | No | `IssuerAlreadyExists(address)` |
| DALP-4215 | Issuer cannot be zero address. | You supplied the zero address as the claim issuer when registering a claim. A trusted issuer must be a deployed contract capable of signing claims, and the zero address does not satisfy that requirement. | Supply the address of a deployed claim issuer contract instead of the zero address. | error | No | `IssuerCannotBeZeroAddress()` |
| DALP-4216 | Issuer is not in the trusted issuers registry. | Reading, updating or removing an issuer needs an existing registry entry. The supplied issuer address has none. | Confirm the issuer address is correct. If the issuer was never registered, add it before attempting to update or remove it. | error | No | `IssuerDoesNotExist(address)` |
| DALP-4217 | Issuer is not trusted for this feed's topic and subject. | The issuer identity address submitted with the feed update is not listed as a trusted issuer for this feed's topic and subject in the trusted issuers registry. The feed only accepts updates from pre-authorized issuers. | Register the issuer in the trusted issuers registry for this feed's topic and subject before submitting updates, or use a different issuer that is already authorized. | error | No | `IssuerNotAuthorized()` |
| DALP-4218 | Issuer is not trusted for this claim topic. | The contract attempted to remove the issuer at the given address from the trusted-issuers list for a specific claim topic, but that issuer was never added to that topic's list. The registry tracks which issuers each claim topic authorises, and this combination has no entry. | Verify that you previously added the issuer address to the claim topic's trusted-issuers list before attempting removal. Retrieve the current list for the claim topic and confirm the address is present. | error | No | `IssuerNotFoundInTopicList(address,uint256)` |
| DALP-4219 | Key already has this purpose. | The on-chain identity key you are adding already holds the requested purpose. The ERC-734 key registry records each purpose only once per key. | Check the key's current purposes with getKey() before calling addKey(). If the purpose is already present, no further step is needed. | error | No | `KeyAlreadyHasThisPurpose(bytes32,uint256)` |
| DALP-4220 | Key cannot be zero. | `addKey` refuses a zero key hash, `bytes32(0)`. | Supply a non-zero key hash. For an address key, use `keccak256(abi.encode(address))`. | error | No | `KeyCannotBeZero()` |
| DALP-4221 | Key hash is not in the identity key registry. | The key hash you referenced does not exist in the ERC-734 key registry. The registry only holds keys that a prior addKey() call explicitly added. | Confirm the key hash is registered by calling keyHasPurpose() or getKey() before attempting removal. If the key is missing, add it first with addKey(). | error | No | `KeyDoesNotExist(bytes32)` |
| DALP-4222 | Key does not have this purpose. | The key exists in the ERC-734 registry, but it does not hold the purpose you are trying to remove. The contract requires you to assign a purpose to a key before you can revoke it. | Call getKey() to inspect the key's current purposes before calling removeKey(). Only attempt to remove a purpose that appears in the key's purposes array. | error | No | `KeyDoesNotHaveThisPurpose(bytes32,uint256)` |
| DALP-4223 | Kind mismatch. | A replaceFeed() call specified a feed kind that differs from the kind of the feed already registered at that subject-and-topic slot. The registry enforces that a replacement feed must be the same kind as the one it replaces. | Check the existing feed's kind with getFeed() and supply a replacement feed of the same kind. To change the kind, remove the existing feed first, then register a new one. | error | No | `KindMismatch(uint8,uint8)` |
| DALP-4224 | Length mismatch. | A batch operation received two arrays (recipients and amounts) whose lengths differ. The contract requires one-to-one correspondence between each recipient address and its corresponding amount. | Ensure the toList and amounts arrays you pass to the batch call contain the same number of elements before submitting. | error | No | `LengthMismatch()` |
| DALP-4225 | Locked amount mismatch. | During XvP settlement execution, the contract tried to release more tokens from escrow than the participant had locked. The escrowed balance for that asset and account is less than the amount the settlement leg requires. | Confirm that the participant's locked balance for the asset covers the full settlement amount before submitting. If the escrow is short, the participant must top up the locked amount first. | error | No | `LockedAmountMismatch(address,address,uint256,uint256)` |
| DALP-4226 | Max features reached. | The ordered feature list has more than 32 entries. | Reduce the number of features in the ordered list to 32 or fewer. Remove features that are no longer needed before registering new ones. | error | No | `MaxFeaturesReached()` |
| DALP-4227 | Maximum allocation exceeded. | The buyer's cumulative token purchase would exceed a limit the sale enforces: the sale's per-address maximum, the presale per-address cap, or the per-investor allocation cap the issuer set for the buyer's investor identity. The sale contract tracks each buyer's total across all purchases, and the allocation cap counts every wallet registered to the same identity together. | Check the buyer's purchase total against the sale's maxPurchase and presale.maxPerAddress limits and the investor's remaining allocation in the sale's investor-allocations read. Reduce the token amount so the total stays within every limit. | error | No | `MaximumAllocationExceeded()` |
| DALP-4228 | Meta registry cannot provide complete answer. | The trusted-issuers meta-registry received a call to an aggregation operation that it cannot satisfy on its own. The meta-registry is a registry-of-registries and certain operations require a direct registry, not the aggregating proxy. | Call the operation directly on the specific subject registry or system registry rather than on the meta-registry. Retrieve the target registry address from getRegistryForSubject() or getSystemRegistry() first. | error | No | `MetaRegistryCannotProvideCompleteAnswer()` |
| DALP-4229 | Metadata immutable. | The contract marked this metadata key as immutable when it first stored the value. The contract permanently blocks any subsequent update or removal of metadata stored under an immutable key. | Metadata stored under an immutable key cannot change. Store the updated value under a different key. | error | No | `MetadataImmutable()` |
| DALP-4230 | Missing type identifier. | The implementation has no `typeId()`, or the call reverted. The directory, the addon registry and the token factory registry key every implementation by its type identifier. | Ensure the implementation contract implements IWithTypeIdentifier and returns a non-reverting typeId(). Deploy or supply a corrected implementation before retrying registration. | error | No | `MissingTypeIdentifier(address)` |
| DALP-4231 | Module already added. | The compliance module at the given address is already registered on this token. The token contract allows each module to appear only once in its active compliance list. | Check the token's current compliance modules before calling addComplianceModule(). If the module is already present, no step is needed. | error | No | `ModuleAlreadyAdded()` |
| DALP-4233 | Module type already registered. | A module with the same type identifier is already registered in the account factory's module registry. The factory allows only one module per type identifier. | Check the registered modules list and confirm no module with the same typeId is already present before calling registerModule(). To replace an existing module, remove it first with removeModule(). | error | No | `ModuleAlreadyRegistered(bytes32,address)` |
| DALP-4234 | Compliance module not found. | The compliance module at the given address is not present in this token's active compliance list. The token cannot update parameters or remove a module that was never added. | Call the token's module-listing function to verify which modules are active before attempting to update or remove one. If you need the module, add it with addComplianceModule() first. | error | No | `ModuleNotFound()` |
| DALP-4236 | Module not registered. | The module address does not appear in the account factory's module registry. Operations such as removing a module or setting it as the default validator require prior registration. | Register the module with registerModule() before referencing it in removeModule() or setDefaultValidator(). Confirm the address matches the one originally registered. | error | No | `ModuleNotRegistered(address)` |
| DALP-4237 | No approval to revoke. | The revokeApproval() call found no active, unconsumed transfer approval for the specified token, sender identity, recipient identity, and amount combination. The approval either never existed, already expired, or was already consumed by a transfer. | Confirm an active approval exists for the exact token, sender identity, recipient identity, and amount before calling revokeApproval(). Use getApproval() or getExactApproval() to check the current state. | error | No | `NoApprovalToRevoke()` |
| DALP-4238 | No bytecode. | The address has no deployed code. Account modules, imported accounts and proxy implementations must be deployed contracts. | Confirm the module contract deployed successfully to the target address before registering it. Check deployment transaction receipts and confirm the address is correct for the target network. | error | No | `NoBytecode(address)` |
| DALP-4239 | No checkpoint at timepoint. | The requested timepoint is earlier than the first recorded checkpoint for the account or total supply in the historical-balances extension. When strict mode is on, the contract requires the timepoint to fall within the tracked history range. | Query balanceOfAt() or totalSupplyAt() with strict=false to get a zero result for timepoints before the first checkpoint, or supply a timepoint at or after the first recorded checkpoint. | error | No | `NoCheckpointAtTimepoint(uint256)` |
| DALP-4240 | No contribution to refund, so no money moved. | The sale holds no contribution from this address in this currency, so the contract refused the refund and no money moved. The payment was already refunded or reclaimed, or it was paid from another address or in another currency. | Check your balance and the sale's activity to see whether the payment already came back. If it did not, ask for the refund again from the address and in the currency you paid with. | error | No | `NoContributionToRefund()` |
| DALP-4241 | No initial admins. | You called initialization with an empty list of admin addresses. The access manager or yield schedule requires at least one admin address to complete setup. | Provide a non-empty array of admin addresses when deploying or initializing this contract. | error | No | `NoInitialAdmins()` |
| DALP-4242 | No local flows. | An XvP settlement requires at least one local sender flow on the current chain. All of the settlement's flows are external-chain only, which leaves no local participant to start an on-chain transfer. | Include at least one flow where the sender is on the current chain before creating the settlement. | error | No | `NoLocalFlows()` |
| DALP-4243 | No yield available. | You attempted to claim yield, but no completed accrual periods carry a positive balance for this holder. This occurs when no periods have completed yet, the holder already claimed all completed periods, or the holder held no tokens during any unclaimed period. | Wait for at least one yield period to complete and ensure the account holds tokens during that period before claiming. | error | No | `NoYieldAvailable()` |
| DALP-4244 | Initialization required. | The contract requires a prior initialization step before this call can proceed. The real estate asset contract checks that initialization stored premint parameters before allowing premint to complete. | Ensure you fully initialized the contract with a non-zero premint amount before calling the premint completion step. | error | No | `NotInitialized()` |
| DALP-4245 | Contract initialization sequence required. | You called a function decorated with `onlyInitializing` outside the contract's initialization sequence. This guard is part of OpenZeppelin's Initializable pattern and prevents protected setup functions from running after initialization is complete. | Do not call this function after deployment. It runs only inside the contract's `initialize` call chain. | error | No | `NotInitializing()` |
| DALP-4246 | Module installation required. | The ERC-7579 ECDSA validator module has no owner recorded for the calling smart account. Install the module on the account before updating its owner record. | Install the ECDSA validator module on the smart account first, then retry the owner update. | error | No | `NotInstalled()` |
| DALP-4247 | Not matured. | The token is not matured. Only `mature()` or `matureEarly()` moves it to matured. | Ask a governance-role holder to call `mature()` once the maturity date has passed, or an emergency-role holder to call `matureEarly()`, then redeem. | error | No | `NotMatured()` |
| DALP-4248 | NOT operation requires one operand. | During evaluation of an identity verification expression tree, the evaluator encountered a NOT node with an empty operand stack. A NOT operation consumes exactly one stack value, so the expression must have at least one preceding operand. | Place each NOT node after the operand or sub-expression it negates. | error | No | `NotOperationRequiresOneOperand()` |
| DALP-4249 | Not registered. | A directory administrator tried to update a token type, compliance module or addon whose ID the directory has never registered. | Register the entry first, or check the ID against the directory's registered entries. | error | No | `NotRegistered(bytes32)` |

The previous page is [DALP-4150 to DALP-4199](https://docs.settlemint.com/docs/api-reference/errors/error-code-reference/dalp-4150-4199). The next page is [DALP-4250 to DALP-4299](https://docs.settlemint.com/docs/api-reference/errors/error-code-reference/dalp-4250-4299).


# DALP-4250 to DALP-4299

Source: https://docs.settlemint.com/docs/api-reference/errors/error-code-reference/dalp-4250-4299
Cause, fix and retry flag for every on-chain contract error with a code from DALP-4250 to DALP-4299.

This page lists the 50 errors in the contract error reference with a code from DALP-4250 to DALP-4299. Match the error's `id`, or its `dalpCode` on a contract error or a failed deployment step, for example `DALP-4250`, to the DALP Code column, then read Retryable and Suggested Fix. The [contract error reference](https://docs.settlemint.com/docs/api-reference/errors/error-code-reference#how-to-use-this-reference) explains each column, including Severity, and the [DALP error index](https://docs.settlemint.com/docs/api-reference/errors) lists the page for every code range.

| DALP Code | Message | Why | Suggested Fix | Severity | Retryable | Solidity Error |
| --- | --- | --- | --- | --- | --- | --- |
| DALP-4250 | Caller is not a registered feature. | Only a feature registered on the token may call `executeFeatureUpdate`, `executeFeatureApproval` or `payout`. The caller is not one. | Ensure the token's feature registry includes the caller's feature contract before calling these entry points. | error | No | `NotRegisteredFeature(address)` |
| DALP-4251 | Not staked. | The EntryPoint holds no locked stake for this account. `unlockStake` needs a locked stake. `withdrawStake` needs a non-zero one. | Call `addStake` first, or check the account's deposit info before you unlock or withdraw. | error | No | `NotStaked(uint256,uint256,bool)` |
| DALP-4252 | Observed at too far in future. | The `observedAt` timestamp in the submitted feed update is further in the future than the feed's configured drift allowance permits. The contract compares `observedAt` to `block.timestamp + driftAllowance` and rejects values that exceed this bound. | Reduce the `observedAt` timestamp so it falls within the feed's drift allowance relative to the current block time. | error | No | `ObservedAtTooFarInFuture()` |
| DALP-4253 | OnchainID already set. | This contract's on-chain identity address already holds a non-zero value. The contract blocks any reassignment of the identity address once set. | The on-chain identity for this contract already has a value. No further call to `setOnchainId` is needed. | error | No | `OnchainIdAlreadySet()` |
| DALP-4254 | Out of range access. | A byte-packing read or write operation in OpenZeppelin's Packing library attempted to access a byte range that lies outside the bounds of the packed value. The requested offset and length exceed the 32-byte word size. | Review the byte offset and length parameters passed to the packing call and ensure they fit within the 32-byte word. | error | No | `OutOfRangeAccess()` |
| DALP-4255 | Owner already set. | The ERC-7579 ECDSA validator module already has an owner recorded for the calling smart account. The `onInstall` function can only set the owner once per account. | The validator is already installed on this account. Use `updateOwner` to rotate the owner address instead of calling `onInstall` again. | error | No | `OwnerAlreadySet()` |
| DALP-4256 | Partial conversion disabled. | The conversion feature on this token has partial conversion disabled. The requested conversion amount is less than the holder's full available principal, which the contract treats as a partial conversion. | Submit the conversion for the full available principal amount, or contact the token issuer to confirm whether this token supports partial conversions. | error | No | `PartialConversionDisabled()` |
| DALP-4257 | Paymaster unauthorized. | An address other than the configured EntryPoint called the paymaster's `validatePaymasterUserOp` or `postOp` entry point. The EntryPoint contract and its canonical resolver are the only callers these functions accept. | Only the ERC-4337 EntryPoint calls these paymaster entry points. Do not call them directly. | error | No | `PaymasterUnauthorized(address)` |
| DALP-4258 | Paymaster zero entry point. | You initialized or updated the paymaster with a zero address as the EntryPoint. The contract requires a non-zero EntryPoint address for the ERC-4337 validation pipeline to function. | Provide the deployed ERC-4337 EntryPoint contract address when initializing or updating the paymaster. | error | No | `PaymasterZeroEntryPoint()` |
| DALP-4259 | Paymaster zero signer. | You initialized or updated the paymaster with a zero address as the trusted signer. EIP-712 sponsorship ticket verification requires a non-zero signer address. | Provide a valid non-zero signer address when initializing or rotating the paymaster signer. | error | No | `PaymasterZeroSigner()` |
| DALP-4260 | Phase not active. | The token sale contract requires an active phase (PRESALE or PUBLIC_SALE) before it accepts purchases. You attempted a purchase while the sale was in SETUP, PAUSED, SUCCESS, or FAILED, where the contract does not accept purchases. | Check the current sale status before submitting a purchase. Wait until the sale operator advances the sale to PRESALE or PUBLIC_SALE, then retry. | error | No | `PhaseNotActive()` |
| DALP-4261 | Post op reverted. | The ERC-4337 EntryPoint requires each paymaster's post-operation call to succeed after a user operation executes. The paymaster's postOp function reverted, causing the EntryPoint to reject the operation. | Review the returnData included in the error for the specific reason the paymaster's postOp reverted. Ensure the paymaster has sufficient deposit and that its validation logic matches the executed operation. | error | No | `PostOpReverted(bytes)` |
| DALP-4262 | Premint already completed. | The real-estate token contract's premint step can only be completed once, immediately after deployment. The factory already called completePremint successfully, and you attempted a second call. | Premint completion is a one-time factory step. Do not call completePremint after it has already succeeded. If you need to mint additional tokens, use the standard mint flow instead. | error | No | `PremintAlreadyCompleted()` |
| DALP-4263 | Proxy creation failed. | The contract factory computed a deterministic deployment address with CREATE2 before deploying, but the deployed contract landed at a different address. This indicates a salt or bytecode mismatch between the prediction and the actual deploy. | Contact support with the `requestId` from the error. | error | No | `ProxyCreationFailed()` |
| DALP-4264 | Purchase amount too low. | The token sale contract blocks purchases or token withdrawals when the effective amount is zero or below the configured minimum. This can occur when: the payment amount is zero, the payment is too small to convert to any tokens at the current rate, the withdrawable vested amount is zero, or the first purchase is below the sale's minimum purchase limit. | Ensure the purchase amount converts to at least one token unit at the current rate and meets the sale's minimum purchase requirement. For token withdrawals, check that the vesting schedule has released a non-zero amount before calling withdrawTokens. | error | No | `PurchaseAmountTooLow()` |
| DALP-4265 | Query before enabled. | The historical balances feature only records checkpoints from the block at which it was enabled. You queried a timepoint (`{{requestedTimepoint}}`) that is earlier than the enabledAt timepoint (`{{enabledAt}}`), so no checkpoint data exists for that period. | Query a timepoint at or after the value returned as enabledAt in the error. Historical balance data is not available for blocks before the token activated this feature. | error | No | `QueryBeforeEnabled(uint256,uint48)` |
| DALP-4266 | Recipient not verified. | The identity verification compliance module checks each recipient against the token's identity registry and required claim-topic expression before allowing a transfer or mint. The recipient's on-chain identity does not hold the required claims (such as KYC or AML) from trusted issuers. | The recipient must complete the required identity verification process and have the necessary claims issued to their on-chain identity. Once the claims are present and the identity registry confirms the recipient as verified, retry the transfer. | error | No | `RecipientNotVerified()` |
| DALP-4267 | Recover zero address. | The emergency ERC-20 recovery function requires both the token address and the recipient address to be non-zero. You supplied a zero address for one of those parameters. | Provide a valid non-zero token contract address and a valid non-zero recipient address when calling the ERC-20 recovery function. | error | No | `RecoverZeroAddress()` |
| DALP-4268 | EntryPoint call did not come from an externally owned account. | The EntryPoint accepts `handleOps` and `handleAggregatedOps` only from an externally owned account that calls it directly. This call came from a contract or a nested call. | Submit the bundle from an externally owned account in its own transaction. | error | No | `Reentrancy()` |
| DALP-4269 | Reentrant initialization. | The fixed yield schedule contract detected a reentrant call during its initialization sequence. The initialize function must complete before anything calls it again. | The initialization sequence must run to completion before any further calls to the contract are made. Ensure no external callbacks or nested calls re-enter the contract's initialize function. | error | No | `ReentrantInitialization()` |
| DALP-4270 | Refund grace period active. | The sale ended in a failed state, and the contract keeps the payment pool for investor refunds until the refund grace period ends. | Withdraw again after the refund grace period ends. Until then, investors claim their refunds with claimRefund. | error | Yes | `RefundGracePeriodActive()` |
| DALP-4271 | Remap source key not found. | You attempted a registry key migration but no implementation is registered under the source key (`{{oldKey}}`). The registry cannot remap a key that has no existing entry. | Verify that the source type key you pass to the remap call matches an addon or factory implementation that is currently registered. List registered keys first and confirm the correct source key before retrying. | error | No | `RemapSourceNotFound(bytes32)` |
| DALP-4272 | Remap target already exists. | You attempted a registry key migration but the target key (`{{newKey}}`) derived from the implementation's typeId is already occupied by another registered implementation. Each type key must map to exactly one implementation. | The new key resolved from the implementation's typeId conflicts with an existing registration. Remove or remap the existing entry at the target key first, or resolve the typeId collision between implementations before retrying. | error | No | `RemapTargetAlreadyExists(bytes32)` |
| DALP-4273 | Replicated execution already performed. | The on-chain identity contract's approve function checks that an execution has not already been carried out before processing an approval. The contract already performed execution `{{executionId}}` and will not approve it again. | The contract approves and runs each execution exactly once. Check the execution state before calling approve. If you need to perform the same operation again, submit a new execution request via the execute function. | error | No | `ReplicatedExecutionAlreadyPerformed(uint256)` |
| DALP-4274 | Execution ID not found. | The on-chain identity contract's approve function validates that the execution ID exists before processing. The supplied `{{executionId}}` is greater than or equal to the current execution nonce, meaning the contract has never created an execution with that ID. | Verify the execution ID by checking the current execution nonce on the identity contract. Only IDs below the nonce represent valid pending executions. Submit a new execution request to obtain a valid ID. | error | No | `ReplicatedExecutionIdDoesNotExist(uint256)` |
| DALP-4275 | Revocation not allowed after commit. | The XvP settlement has external (cross-chain) flows and all local participants have already approved, committing the settlement to the external counterparty. Once the counterparty chain acts on that commitment, individual parties can no longer revoke their approval. | To cancel a fully committed external settlement, use the cancel vote mechanism so all parties agree to cancel together rather than attempting an individual revocation. | error | No | `RevocationNotAllowedAfterCommit()` |
| DALP-4276 | Feed round not found. | The feed never recorded this round, or, in bounded-history mode, has already overwritten it. | Request a round ID that falls within the feed's current retention window. Use the latest round ID if historical data for the requested round is no longer available. | error | No | `RoundNotFound(uint80)` |
| DALP-4277 | Sale duration must be positive. | The token sale factory requires a positive, non-zero sale duration. A duration of zero would create a sale that ends immediately and can never accept purchases. | Supply a saleDuration value greater than zero when calling createTokenSale. | error | No | `SaleDurationMustBePositive()` |
| DALP-4278 | Sale ended. | The current block timestamp is at or past the sale's configured end time. The sale's purchase window has closed and the contract no longer accepts purchases. | Create a new sale to accept purchases. | error | No | `SaleEnded()` |
| DALP-4279 | Sale never activated. | The finalizeSale call targeted a sale that is still in SETUP status, meaning the sale was configured but never activated. The finalization path requires the sale to have been activated at least once. | Activate the sale before you finalise it. Unsold tokens come back through `withdrawUnsoldTokens` once the sale has ended. | error | No | `SaleNeverActivated()` |
| DALP-4280 | Sale not active. | The requested operation requires the sale to be in PRESALE or PUBLIC_SALE phase, but the sale is currently in a different phase (for example, SETUP, PAUSED, ENDED, or FAILED). Phase-gated operations such as purchasing tokens or pausing can only proceed when the sale is running. | Check the current sale phase. If the sale administrator has paused the sale, they must resume it before purchases can proceed. | error | No | `SaleNotActive()` |
| DALP-4281 | Sale not ended. | The operation requires the sale to have ended, but the current block timestamp is still before the sale's configured end time and the contract has not moved the sale to ENDED status. Operations such as finalizing the sale or withdrawing unsold tokens are only permitted after the sale window closes. | Wait until the sale's end time has passed, then retry the operation. | error | No | `SaleNotEnded()` |
| DALP-4282 | Sale not failed. | Refunds are only available when the sale has reached a FAILED final state (the soft cap did not reach its target). The sale is currently in a different final state such as SUCCESS, or the contract has not finalized it. | If the sale succeeded, withdraw the purchased tokens with `withdrawTokens`. If it is not finalised yet, call `finalizeSale` after the end time. | error | No | `SaleNotFailed()` |
| DALP-4283 | Sale not finalized as success. | This sale has a soft cap configured. The contract blocks token withdrawal until the sale administrator finalizes the sale as SUCCESS, confirming the soft cap was met. This prevents buyers from withdrawing tokens while refunds might still apply if the sale ultimately fails. | Wait for the sale administrator to call finalizeSale. Once the contract records the sale as SUCCESS, token withdrawal becomes available. | error | No | `SaleNotFinalizedAsSuccess()` |
| DALP-4284 | Sale not started. | The current block timestamp is before the sale's configured start time. The purchase window has not opened. | Wait until the sale's start time arrives before submitting a purchase. | error | No | `SaleNotStarted()` |
| DALP-4285 | Sale start must be in future. | The sale start timestamp provided to createTokenSale is earlier than the current block timestamp. The contract requires the sale to start in the future so there is a defined period for setup and activation. | Provide a saleStart value that is greater than the current block timestamp when calling createTokenSale. | error | No | `SaleStartMustBeInFuture()` |
| DALP-4286 | Salt already taken. | The identity factory uses CREATE2 for deterministic deployment. A previous deployment from this factory already consumed the salt derived from the provided wallet or contract address, so the factory cannot create a second identity at the same deterministic address. | Retrieve the existing identity address with the factory's lookup functions instead of creating a new one. | error | No | `SaltAlreadyTaken(string)` |
| DALP-4287 | Same address. | The new implementation address equals the one the factory already uses. | Provide a different implementation address that has not already been set on this factory. | error | No | `SameAddress()` |
| DALP-4288 | Schedule not active. | The fixed treasury yield schedule's start date has not arrived. Yield accrual begins only on or after the configured startDate, so the contract has no yield to calculate before that point. | Wait until the yield schedule's start date has passed before calling calculateAccruedYield. | error | Yes | `ScheduleNotActive()` |
| DALP-4289 | Update schema hash does not match the feed's pinned hash. | The update's `schemaHash` differs from the schema hash this feed pinned at deployment. | Set `schemaHash` in the update to the feed's `expectedSchemaHash` and sign the update again. | error | No | `SchemaHashMismatch()` |
| DALP-4290 | Topic schema changed since this feed was registered. | The topic's schema changed after this feed was registered, so `replaceFeed` cannot swap the feed in place. | Remove the feed with `removeFeed`, then register the new feed with `registerFeed`. | error | No | `SchemaHashMismatch(bytes32,bytes32)` |
| DALP-4291 | Secret already revealed. | The secret for this settlement is already revealed. A second reveal is refused, and so is any refund or expired withdrawal, because the counterparty chain can already settle. | Execute the settlement. It cannot be refunded after the reveal. | error | No | `SecretAlreadyRevealed()` |
| DALP-4292 | Secret not revealed. | The XvP settlement uses a hashlock gate and you attempted to execute before revealing the secret on-chain. The contract blocks execution until you submit the pre-image of the hashlock. | Call the revealSecret function with the correct pre-image before attempting to execute the settlement. | error | No | `SecretNotRevealed()` |
| DALP-4293 | Self transfer. | One of the settlement flows specifies the same address as both sender and recipient. A transfer from an address to itself has no net effect and the contract rejects it as a configuration error. | Review the settlement flows and correct any flow where flow.from and flow.to are the same address. | error | No | `SelfTransfer()` |
| DALP-4294 | Sender address result. | The ERC-4337 EntryPoint's getSenderAddress function always reverts with SenderAddressResult to return the computed counterfactual smart account address. The revert carries the address as data and signals successful address discovery, not a failure. | Read the sender address from the revert data of the getSenderAddress call. Decode the SenderAddressResult(address) error to extract the computed address. | error | No | `SenderAddressResult(address)` |
| DALP-4295 | Sender's key lacks the required purpose. | The caller's address does not hold an `ACTION_KEY` purpose on the ERC-734 identity contract. The identity gate checks that the sender's key hash carries `ACTION_KEY` before allowing the requested call to proceed. | Add the `ACTION_KEY` purpose to the caller's key on the identity contract, then retry the call. | error | No | `SenderLacksActionKey()` |
| DALP-4296 | Sender lacks management key. | The caller's address does not hold a MANAGEMENT_KEY purpose on the ERC-734 identity contract. The identity gate checks that the sender's key hash carries MANAGEMENT_KEY before allowing key management or approval calls. | Have an existing MANAGEMENT_KEY holder add the MANAGEMENT_KEY purpose to the caller's key on the identity contract, then retry the call. | error | No | `SenderLacksManagementKey()` |
| DALP-4297 | Sender not local. | The caller is not registered as a local participant in this XvP settlement. Only addresses designated as local counterparties during settlement setup may perform this step. | Retry the call from an address registered as a local participant in this settlement, or verify the correct settlement contract address. | error | No | `SenderNotLocal()` |
| DALP-4298 | Signature unchanged. | The topic scheme's signature is already set to the value you submitted. The registry rejects an update when the new signature is byte-for-byte identical to the one currently stored on-chain. | Supply a different signature string when calling the update function, or skip the call if the current signature is already correct. | error | No | `SignatureUnchanged(string,string)` |
| DALP-4299 | Signature validation failed. | The ERC-4337 EntryPoint could not validate the aggregated signature produced by the aggregator at the address returned in the error. The aggregator's own validation check rejected the bundle's combined signature. | Confirm the aggregator contract at the reported address is correct and that the signatures in the UserOperation bundle match the aggregation scheme. | error | No | `SignatureValidationFailed(address)` |

The previous page is [DALP-4200 to DALP-4249](https://docs.settlemint.com/docs/api-reference/errors/error-code-reference/dalp-4200-4249). The next page is [DALP-4300 to DALP-4399](https://docs.settlemint.com/docs/api-reference/errors/error-code-reference/dalp-4300-4399).


# DALP-4300 to DALP-4399

Source: https://docs.settlemint.com/docs/api-reference/errors/error-code-reference/dalp-4300-4399
Cause, fix and retry flag for every on-chain contract error with a code from DALP-4300 to DALP-4399.

This page lists the 91 errors in the contract error reference with a code from DALP-4300 to DALP-4399. Match the error's `id`, or its `dalpCode` on a contract error or a failed deployment step, for example `DALP-4300`, to the DALP Code column, then read Retryable and Suggested Fix. The [contract error reference](https://docs.settlemint.com/docs/api-reference/errors/error-code-reference#how-to-use-this-reference) explains each column, including Severity, and the [DALP error index](https://docs.settlemint.com/docs/api-reference/errors) lists the page for every code range.

| DALP Code | Message | Why | Suggested Fix | Severity | Retryable | Solidity Error |
| --- | --- | --- | --- | --- | --- | --- |
| DALP-4300 | Slippage exceeded. | The token amount calculated from your payment is below the minimum you specified. The sale contract enforces slippage protection: if the computed output is less than your stated minimum, the purchase reverts. | Lower your minimum token amount or increase your payment amount, then resubmit the purchase. | error | Yes | `SlippageExceeded(uint256,uint256)` |
| DALP-4301 | Soft cap not reached. | A soft cap is configured on this sale and the sale has not reached a successful finalization. The contract requires successful finalization before allowing fund withdrawals, to prevent funds from leaving while a failed-sale refund window may still apply. | Wait for the sale to finalize as SUCCESS before withdrawing funds. Check the current sale status and finalize if the soft cap has been met. | error | No | `SoftCapNotReached()` |
| DALP-4302 | Stake not unlocked. | The stake was never unlocked. The EntryPoint withdraws a stake only after `unlockStake()` starts its unstake delay. | Call `unlockStake()`, wait out the unstake delay, then withdraw the stake. | error | No | `StakeNotUnlocked(uint256,uint256)` |
| DALP-4303 | Stake withdrawal failed. | The EIP-4337 StakeManager attempted to transfer the withdrawn stake as native ETH to the destination address, but the transfer call failed. The revert reason from the failed transfer is included in the error. | Verify that the withdrawal address can receive native ETH (it must not revert on plain transfers) and that sufficient gas is available, then retry the withdrawal. | error | No | `StakeWithdrawalFailed(address,address,uint256,bytes)` |
| DALP-4304 | Stale observation. | The feed update's observedAt timestamp is older than the timestamp of the most recently accepted observation. The issuer-signed scalar feed enforces monotonic ordering to prevent older data from overwriting newer data. | Submit an update whose observedAt value is greater than or equal to the current latest observation timestamp recorded by the feed. | error | No | `StaleObservation()` |
| DALP-4305 | String too long. | The string value supplied exceeds 31 bytes, which is the maximum length that the OpenZeppelin ShortStrings library can pack into a single storage slot. | Shorten the string to 31 bytes or fewer before submitting the call. | error | No | `StringTooLong(string)` |
| DALP-4306 | System access manager not set. | The compliance contract requires a system access manager address before this call can proceed, and no address has been configured yet. | Configure the system access manager on the compliance contract before retrying this call. | error | No | `SystemAccessManagerNotSet()` |
| DALP-4307 | System addon implementation not set. | The system registry attempted to update the implementation address for an addon type whose implementation slot has never been populated. The registry allows updates only to addon types previously registered with an initial implementation. | Register the addon type with an initial implementation address before attempting to update it. Confirm that the addonTypeHash in the error matches the intended addon type. | error | No | `SystemAddonImplementationNotSet(bytes32)` |
| DALP-4308 | Addon type name already registered. | An addon type with the given name is already registered in the system addon registry (V1, name-based). Each addon type name must be unique across all registrations. | Choose a different type name for the new addon registration, or retrieve the existing addon proxy for the already-registered type name. | error | No | `SystemAddonTypeAlreadyRegistered(string)` |
| DALP-4309 | Addon type ID already registered. | An addon type with the given typeId is already registered and currently active in the system addon registry (V2, typeId-based). The registry permits re-registration only for archived addon types. | Use the existing addon proxy for the registered typeId, or archive the existing registration before re-registering with the same typeId. | error | No | `SystemAddonTypeAlreadyRegisteredV2(bytes32)` |
| DALP-4310 | System already bootstrapped. | The system bootstrap function has already run and completed. The system accepts bootstrap only once. | Do not call bootstrap again on this system. If you need to update individual subsystem implementations, use the dedicated setter functions on the system contract. | error | No | `SystemAlreadyBootstrapped()` |
| DALP-4311 | System trusted issuers registry implementation not set. | The system bootstrap or setter call requires a non-zero trusted issuers registry implementation address, but the provided address is zero. The system validates this address before deploying or updating the registry proxy. | Provide a valid, deployed trusted issuers registry implementation address when calling the system bootstrap or the setSystemTrustedIssuersRegistryImplementation function. | error | No | `SystemTrustedIssuersRegistryImplementationNotSet()` |
| DALP-4312 | Terms already set. | The sale's terms hash can only be set while the sale is in SETUP status. The sale has already been activated, so the terms hash is now locked. | The terms hash for this sale cannot change after activation. To use different terms, deploy a new sale contract with the correct terms hash before activation. | error | No | `TermsAlreadySet()` |
| DALP-4313 | Terms not accepted. | A terms hash is set on this sale and the buyer has not accepted it. The sale contract requires each buyer to call acknowledgeTerms before the contract processes their purchase. | Call acknowledgeTerms on the sale contract from the buyer's address before submitting the purchase. | error | No | `TermsNotAccepted()` |
| DALP-4314 | Terms not set. | The acknowledgeTerms call requires a terms hash configured on the sale, but the sale admin has not set one yet. Buyers cannot acknowledge terms until the admin publishes them. | Have the sale admin call setTermsHash with the correct terms hash before buyers attempt to acknowledge terms. | error | No | `TermsNotSet()` |
| DALP-4315 | Payment currency limit exceeded. | The token sale contract enforces a maximum of 10 accepted payment currencies to prevent unbounded iteration during refund processing. Adding this currency would exceed that limit. | Remove an existing payment currency before adding a new one, or reduce the number of accepted currencies to stay within the 10-currency limit. | error | No | `TooManyPaymentCurrencies()` |
| DALP-4316 | Topic ID is missing from the topic scheme registry. | The topic scheme registry could not locate the topic ID in its internal enumeration array during a removal. The topic ID has an index of zero, meaning it was never recorded in the array. | Confirm the topic ID exists in the registry before attempting to remove it. Use the registry's lookup functions to verify the topic is registered. | error | No | `TopicIdNotFoundInArray(uint256)` |
| DALP-4317 | Topic mismatch. | The feed update's topic ID does not match the topic ID this feed contract was configured for. Each issuer-signed scalar feed is pinned to exactly one topic at deployment. | Submit the update to the feed contract whose pinned topic ID matches the topic ID in your update payload. | error | No | `TopicMismatch()` |
| DALP-4318 | Topic not registered. | The feeds directory registers a feed only for a topic ID that has a scheme in the topic scheme registry. This topic ID has none. | Register a topic scheme for this topic ID in the topic scheme registry, then retry the feed registration. | error | No | `TopicNotRegistered(uint256)` |
| DALP-4319 | Topic scheme already exists. | A topic scheme with this name already exists in the registry. The name is hashed to derive the topic ID, and that ID is already occupied. | Choose a unique name for the new topic scheme. To update an existing scheme's signature, use the update function rather than the registration function. | error | No | `TopicSchemeAlreadyExists(string)` |
| DALP-4320 | No topic scheme is registered for this topic ID. | No topic scheme is registered for this topic ID, either locally or via the parent chain. The registry requires a scheme to exist before you can query or use it. | Register a topic scheme for this topic ID before performing this operation. Verify the topic ID is correct and that it matches a scheme in the registry. | error | No | `TopicSchemeDoesNotExist(uint256)` |
| DALP-4321 | No topic scheme is registered under this name. | No topic scheme is registered under this name. The registry cannot resolve the name to a topic ID with an associated scheme. | Verify the name matches a scheme registered in the topic scheme registry. Names are case-sensitive and must match exactly. | error | No | `TopicSchemeDoesNotExistByName(string)` |
| DALP-4322 | Topic scheme registry implementation not set. | The system contract has no topic scheme registry implementation address configured. This address must be set before the system can bootstrap or perform operations that require the registry. | Set a non-zero topic scheme registry implementation with `setTopicSchemeRegistryImplementation` from an account that holds `SYSTEM_MANAGER_ROLE`, then retry. | error | No | `TopicSchemeRegistryImplementationNotSet()` |
| DALP-4323 | Trigger already exists. | The contract already holds a conversion trigger with this ID. Triggers are identified by their ID, and each ID must be unique. | Publish the trigger under a new ID. An ID stays taken after its trigger is turned off. | error | No | `TriggerAlreadyExists(bytes32)` |
| DALP-4324 | Trigger expired. | The conversion trigger has passed its expiry timestamp. The contract checks that the current block timestamp does not exceed the trigger's configured expiry. | Publish a new conversion trigger with an updated expiry timestamp in the future, then retry the conversion. | error | No | `TriggerExpired(bytes32)` |
| DALP-4325 | Trigger not active. | The referenced conversion trigger exists but the contract deactivated it. Only triggers with their active flag set can be used for conversions. | Publish a new trigger under a new ID, then convert against it. | error | No | `TriggerNotActive(bytes32)` |
| DALP-4326 | Trigger not found. | No conversion trigger exists for this trigger ID. The contract checks that the trigger's publishedAt field is non-zero before allowing a conversion. | Publish a conversion trigger with the expected trigger ID before attempting the conversion. | error | No | `TriggerNotFound(bytes32)` |
| DALP-4327 | Trusted issuers meta registry implementation not set. | The system contract requires a trusted issuers meta registry implementation address before it can bootstrap or deploy identity infrastructure. No address is set. | Set the trusted issuers meta registry implementation address on the system contract using the system manager function before proceeding. | error | No | `TrustedIssuersMetaRegistryImplementationNotSet()` |
| DALP-4328 | The requested resource could not be found. | The referenced multisig transaction does not exist at the requested index. The transaction index is out of range for the contract's transaction list. | Verify the transaction index is correct and within the range of recorded transactions before submitting the request. | error | No | `TxDoesNotExist(uint256,uint256)` |
| DALP-4329 | Tx executed. | The multisig contract already executed the transaction at this index. Each transaction can run only once. | Check the transaction status before submitting an execution request. The contract executes each transaction exactly once. | error | No | `TxExecuted(uint256)` |
| DALP-4330 | Caller is not the authorised address. | The caller's address does not match the address the contract requires for this operation. This contract restricts certain calls to a specific address, such as the factory that deployed it. | Ensure the call originates from the authorized address for this operation. Check the contract's deployment configuration to identify the required caller. | error | No | `Unauthorized()` |
| DALP-4331 | You do not have permission for this operation. | The caller may not make this call on the token feature. Guarded calls need a token role, token hooks accept only the bound token or a registered feature, and a movement request must come from its own party. A feature set up with a zero token address raises the same error. | Call from an address that holds the token role the operation needs. Hook calls come from the token itself and cannot be made directly. | error | No | `UnauthorizedCaller()` |
| DALP-4332 | Caller is not the bound token or compliance contract. | A compliance contract accepts hooks and transfer checks only for its bound token, and binding calls only from the system compliance contract. The caller or token named in the error is not the expected one. | Ensure these compliance hooks are invoked only by the token contract associated with this compliance instance. The contract rejects direct calls from other addresses. | error | No | `UnauthorizedCaller(address,address)` |
| DALP-4333 | Only the associated contract can issue claims. | An address other than the associated contract submitted a claim to this on-chain contract identity. This identity contract only allows its associated contract address to issue claims on its behalf. | Trigger claim issuance through the associated contract rather than calling the identity directly from a different address. | error | No | `UnauthorizedContractOperation(address)` |
| DALP-4334 | Conversion feature is not an authorised converter on the target token. | The caller is not registered as an authorized converter for this token. The conversion minter checks the authorizedConverters mapping before allowing a conversion mint. | Ask a holder of GOVERNANCE_ROLE on the target token to add this conversion feature with `addAuthorizedConverter` on its conversion minter, then retry. | error | No | `UnauthorizedConverter(address)` |
| DALP-4335 | Caller cannot create or replace token features. | The token feature factory checks the caller's role before creating or replacing a feature. The call needs TOKEN_FACTORY_MODULE_ROLE at the system level or GOVERNANCE_ROLE on the subject token, and the calling address held neither. | Ensure the caller holds TOKEN_FACTORY_MODULE_ROLE in the system, or holds GOVERNANCE_ROLE on the token whose feature is being created. Then resubmit the request. | error | No | `UnauthorizedFeatureCreation()` |
| DALP-4336 | Caller may not call compliance module hooks. | The token contract, its configured compliance contract, or the system compliance contract must call compliance module hooks (transferred, created, destroyed). The address in the error did not match any of these permitted callers. | Route compliance hook calls through the token or its compliance contract. Direct calls to compliance module hooks from other addresses are not permitted. | error | No | `UnauthorizedHookCaller(address)` |
| DALP-4337 | Owning contract did not approve this caller. | The owning contract's permission check (canAddClaim or canRemoveClaim) returned false for the calling address. Contract identities delegate claim management authorization to their owning contract, and the caller was not approved. | Obtain approval from the owning contract for this address before calling addClaim, removeClaim, registerClaimAuthorizationContract, or removeClaimAuthorizationContract on the contract identity. | error | No | `UnauthorizedOperation(address)` |
| DALP-4338 | You do not have permission for this operation. | The multi-signature contract verified that the submitted signer address does not hold SIGNER_ROLE. Only registered signers may participate in or update multi-sig operations. | Verify that the signer address holds SIGNER_ROLE on the multi-sig contract. Add the address to the signer set before submitting a transaction or weight update that references it. | error | No | `UnauthorizedSigner(address)` |
| DALP-4339 | You do not have permission for this operation. | An address other than the associated token contract called the voting power feature's internal voting-units function. The feature restricts this query to the token itself. | Query voting units through the token contract or the feature's public getVotingUnits view function rather than calling the internal hook directly. | error | No | `UnauthorizedVotingUnitsQuery()` |
| DALP-4340 | Unknown expression type. | The on-chain RPN expression evaluator in the identity verification library encountered a node whose type does not match any known ExpressionType: `TOPIC`, `AND`, `OR` or `NOT`. The expression tree stored in the compliance rule contains an unrecognised node. | Rebuild the compliance expression from supported node types and update the module configuration. If the platform produced the expression, contact support with the `requestId` from the error. | error | No | `UnknownExpressionType()` |
| DALP-4341 | Unregistered key. | The key has no registered interface. `setImplementation`, `setInstance` and `reregisterImplementation` need a registered key, and an import row needs a non-zero `interfaceId`. | Register the directory key first by calling registerImplementation or registerInstance with the key and its expected interface. Once registered, setImplementation or setInstance will accept the call. | error | No | `UnregisteredKey(bytes32)` |
| DALP-4342 | Unsupported attribute. | The ERC-7786 cross-chain gateway source contract received a message attribute with a 4-byte selector that is not recognized by this gateway implementation. The gateway cannot forward messages that carry unsupported attributes. | Remove the unsupported attribute from the cross-chain message before sending, or use a gateway implementation that declares support for the attribute selector returned in the error. | error | No | `UnsupportedAttribute(bytes4)` |
| DALP-4343 | Unsupported execution operation. | Contract identities do not support ERC-734 execution operations (approve, execute). These functions always revert because contract-owned identities manage authorization through their owning contract, not through the ERC-734 execution queue. | Use the owning contract's authorisation mechanisms instead of calling ERC-734 approve or execute on a contract identity. | error | No | `UnsupportedExecutionOperation()` |
| DALP-4344 | Unsupported key operation. | Contract identities have no ERC-734 key store: `addKey`, `removeKey`, `getKey`, `getKeyPurposes` and `getKeysByPurpose` always revert. | Manage access through the owning contract's permission model rather than calling ERC-734 addKey or removeKey on a contract identity. Use a user wallet identity if key-based access control is required. | error | No | `UnsupportedKeyOperation()` |
| DALP-4345 | Unsupported payment currency. | The token sale contract requires you to register payment currencies before accepting purchases. You have not added the currency address used in the buy call to the sale's accepted payment currencies list. | Use a payment currency that you have registered for this sale. Call paymentCurrencies on the sale contract to see which currencies the sale accepts, then resubmit with a supported currency address. | error | No | `UnsupportedPaymentCurrency()` |
| DALP-4346 | Value not positive. | The issuer-signed scalar feed has requirePositive enabled, and the submitted value was zero or negative. The feed enforces that all accepted values must be strictly positive when this flag is set. | Submit a value greater than zero. If the data source must preserve zero or negative values, use a separately deployed compatible feed whose contract permits them. | error | No | `ValueNotPositive()` |
| DALP-4347 | Delegation signature expired. | The ERC-5805 delegateBySig call presented a signature whose expiry timestamp has passed. The Votes contract rejects expired signatures to prevent replay of stale delegation authorizations. | Generate a new delegateBySig signature with an expiry timestamp in the future and resubmit. The expiry argument in the error shows the timestamp the contract found to be expired. | error | No | `VotesExpiredSignature(uint256)` |
| DALP-4348 | Wallet already linked. | The identity factory already maps this wallet address to an existing identity contract. Each wallet address can link to at most one identity in the factory. | Use the identity the factory already links to this wallet. The factory has no call that removes the link. | error | No | `WalletAlreadyLinked(address)` |
| DALP-4349 | Wallet already marked as lost. | The identity registry has already recorded this wallet address as lost in the pending or accepted identity layer. The registry blocks recording a wallet as lost a second time, and a lost wallet cannot be the replacement wallet in a recovery. | Check the wallet's current status in the identity registry before initiating recovery. Use a different replacement wallet address, or contact the identity manager if the lost status was set in error. | error | No | `WalletAlreadyMarkedAsLost(address)` |
| DALP-4350 | Wallet in management keys. | The identity factory detected that the wallet address being registered also appears in the management keys list supplied during creation. A wallet's own address cannot serve as an explicit management key because the contract rejects redundant key entries to prevent configuration errors. | Remove the wallet address from the managementKeys array before submitting the identity creation request. The wallet already receives management access through its account registration. | error | No | `WalletInManagementKeys()` |
| DALP-4351 | Withdrawal already scheduled. | The airdrop contract already has a withdrawal scheduled that has not run yet. Only one withdrawal can be pending at a time. | Run the scheduled withdrawal or cancel it before scheduling a new one. Call executeWithdrawal once its eligible time has passed, or cancelScheduledWithdrawal to clear it. | error | No | `WithdrawalAlreadyScheduled()` |
| DALP-4352 | Withdrawal not due. | The ERC-4337 EntryPoint stake manager requires callers to wait for the full unstake delay after calling unlockStake before withdrawing. The current block timestamp has not reached the scheduled withdrawal time returned in the error. | Wait until the block timestamp reaches the withdrawTime value returned in the error, then resubmit the withdrawStake call. The error includes both the eligible withdrawal time and the current block timestamp. | error | Yes | `WithdrawalNotDue(uint256,uint256)` |
| DALP-4353 | Withdrawal not ready. | The airdrop contract has a withdrawal scheduled, but its eligible time has not passed. A withdrawal waits seven days after scheduleWithdrawal and, while claims are open, until they close: the end of a time-bound airdrop's claim window or a vesting airdrop's initialization deadline. | Read the eligible time from withdrawalSchedule or the WithdrawalScheduled event, then call executeWithdrawal after it. | error | Yes | `WithdrawalNotReady()` |
| DALP-4354 | Withdrawal not scheduled. | You called executeWithdrawal or cancelScheduledWithdrawal with no withdrawal scheduled, or called withdrawTokens, which always refuses because a withdrawal must be scheduled first. | Call scheduleWithdrawal first. Once the eligible time it records has passed, call executeWithdrawal. | error | No | `WithdrawalNotScheduled()` |
| DALP-4355 | Wrapped error. | The ERC-4337 EntryPoint caught a revert from an inner call, such as a paymaster or account execution, and re-emits it as this error. The error carries the target address, the called function selector, the raw revert reason, and any extra detail bytes. The original failure originates inside the inner contract, not in the EntryPoint itself. | Decode the nested `reason` bytes to find the root revert. The `target` and `selector` fields identify which contract and function reverted. Resolve the inner error using those details. | error | No | `WrappedError(address,bytes4,bytes,bytes)` |
| DALP-4356 | Yield schedule active. | The token's yield schedule has already started: its start date is at or before the current block timestamp. The contract blocks minting after the yield schedule becomes active to preserve the fairness of yield distribution. | The contract closes minting once the yield schedule becomes active. Check the yield schedule's start date before attempting to mint, or contact the token issuer to confirm the minting window. | error | No | `YieldScheduleActive()` |
| DALP-4357 | Yield schedule already set. | A yield schedule is already associated with this token. The contract permits only one yield schedule per token and reverts if you attempt to set a second one. | Read the current `yieldSchedule` address on the token before calling set. If the token already has a schedule, the contract blocks assigning another one. | error | No | `YieldScheduleAlreadySet()` |
| DALP-4358 | Trading venue or settlement address is zero. | A required address parameter was the zero address. The contract requires a non-zero address at this position. | Provide a non-zero address for each address argument. | error | No | `ZeroAddress()` |
| DALP-4359 | Address field is zero. | The address parameter named in the `field` argument was the zero address. The contract requires a non-zero address for that field. | Provide a valid, deployed contract or wallet address for the field identified in the error. The `field` value in the error data names the specific parameter that was zero. | error | No | `ZeroAddress(string)` |
| DALP-4360 | Address is zero. | An address argument that must be non-zero was the zero address. | Provide a non-zero address for each address argument. | error | No | `ZeroAddressNotAllowed()` |
| DALP-4361 | ECDSA validator owner address is zero. | The owner address provided during ECDSA validator installation or update was the zero address. The validator requires a real key-holding address as the account owner. | Provide a non-zero EOA or contract address as the owner when installing or updating the ECDSA validator module. | error | No | `ZeroAddressOwner()` |
| DALP-4362 | Amount is zero. | A token amount argument was zero where the contract requires a positive value. The operation requires a non-zero quantity to proceed. | Provide a positive amount. | error | No | `ZeroAmount()` |
| DALP-4363 | Distribution amount is zero. | You called distribute or batchDistribute with an amount of zero. The contract requires each distribution entry to transfer at least one token unit. | Ensure every distribution amount in your `distribute` or `batchDistribute` call is greater than zero. Remove or correct any zero-amount entries before submitting. | error | No | `ZeroAmountToDistribute()` |
| DALP-4364 | No vested tokens are claimable. | The vesting strategy releases nothing new for this index since the last claim. Either no further tokens have vested yet, or the full allocation is already claimed. | Read `getClaimedAmount(index)`. If it is below the allocation, claim again after more tokens vest. | error | No | `ZeroAmountToTransfer()` |
| DALP-4365 | Denomination asset address is zero. | The denomination asset address provided to the maturity redemption feature was the zero address. The feature requires a deployed ERC-20 contract as the payout currency. | Provide a valid, deployed ERC-20 token address as the denomination asset when configuring the maturity redemption feature. | error | No | `ZeroDenominationAsset()` |
| DALP-4366 | Effective conversion price is zero. | The conversion pricing calculation produced an effective price of zero. This can happen when the configured discount is so high that the round price rounds down to zero after applying basis-point arithmetic. | Reduce the discount percentage so that the effective price remains above zero, or increase the round price per share. Verify the discount and cap configuration for this conversion trigger. | error | No | `ZeroEffectivePrice()` |
| DALP-4367 | EntryPoint wrapper deployed with a zero EntryPoint address. | You deployed the EntryPoint wrapper with a zero-address canonical EntryPoint. The wrapper has no target to forward calls to and cannot operate. | Deploy the EntryPoint wrapper with the correct canonical ERC-4337 EntryPoint address. Confirm the address is a deployed contract before passing it to the constructor. | error | No | `ZeroEntryPoint()` |
| DALP-4368 | Face value is zero. | The face value parameter for the maturity redemption feature was zero. The face value determines the redemption payout per token unit, so it must be a positive amount. | Provide a positive face value (in the smallest unit of the denomination asset) when initializing the maturity redemption feature. | error | No | `ZeroFaceValue()` |
| DALP-4369 | Recipient address is zero. | The recipient address is the zero address. Conversion mints, converter registration, supply delegate mints and hold deliveries need a real recipient. | Provide a non-zero recipient address. | error | No | `ZeroRecipient()` |
| DALP-4370 | Conversion target amount is zero. | The conversion calculation computed a target amount of zero. The principal or interest, after the contract applies the effective price and token decimals, rounds down to zero tokens of the target asset. | Increase the principal amount you are converting, or adjust the effective price configuration so that the resulting target amount is at least one token unit of the target asset. | error | No | `ZeroTargetAmount()` |
| DALP-4371 | Treasury address is zero. | The maturity redemption feature needs a non-zero treasury address to pay redemptions from. | Provide a valid, non-zero treasury address when initializing or reconfiguring the maturity redemption feature. | error | No | `ZeroTreasuryAddress()` |
| DALP-4372 | Cannot remove last validator. | Removing this validator module would leave the account with no validators. An account with no validators cannot validate UserOperations and becomes permanently inoperable. | Install a replacement validator module before removing the current one, so the account always retains at least one active validator. | error | No | `CannotRemoveLastValidator()` |
| DALP-4373 | Validator module limit exceeded. | Installing this validator module would exceed the account's maximum of `{{maxValidators}}` validator modules. The contract enforces this limit to keep UserOp validation gas costs bounded. | Remove an existing validator module before installing a new one, keeping the total at or below `{{maxValidators}}`. | error | No | `TooManyValidators(uint256)` |
| DALP-4374 | Operation unavailable on this contract. | The contract function you called has no implementation. The contract reached the selector but the body is a stub that always reverts. | This function is not available on this contract version. Check the API reference to confirm the correct method name and contract version, then retry with a supported call. | error | No | `NotImplemented()` |
| DALP-4375 | Paymaster not deployed. | The ERC-4337 EntryPoint simulation found that the paymaster address you supplied has no deployed bytecode. The EntryPoint rejects the user operation because it cannot call a contract that does not exist at that address. | Confirm the paymaster contract has deployed bytecode on the target network, then provide its correct address before resubmitting the user operation. | error | No | `PaymasterNotDeployed(address)` |
| DALP-4376 | Max staleness value is zero. | The price resolver requires a max staleness threshold that is greater than zero seconds. A value of zero would disable the staleness check entirely, which the contract does not permit. | Provide a positive number of seconds for the max staleness threshold. | error | No | `InvalidMaxStaleness()` |
| DALP-4377 | Paymaster entry point not contract. | The new EntryPoint address passed to `setEntryPoint` has no deployed bytecode. The paymaster calls into the EntryPoint during validation, so it must be a live contract. | Supply the address of the currently deployed EntryPoint contract. Confirm the address has code on the target network before calling setEntryPoint. | error | No | `PaymasterEntryPointNotContract(address)` |
| DALP-4378 | Asset type name required. | The access manager address for a DALP asset depends on its asset type name. The generic `predictAccessManagerAddress` always reverts, and `predictAccessManagerAddressForAssetType` reverts when `assetTypeName` is empty. | Call `predictAccessManagerAddressForAssetType` rather than the generic predictor. Supply a non-empty `assetTypeName` string that identifies the concrete asset type. | error | No | `AssetTypeNameRequired()` |
| DALP-4379 | Parent registry address is self-referencing, unsupported, or creates a cycle. | The chained registry requires a parent that is a distinct address implementing the required registry interface and absent from this contract's own chain. The provided address fails at least one of these conditions. | Provide the address of a different, already-deployed registry contract whose parent chain excludes this contract entirely. | error | No | `InvalidParentAddress(address)` |
| DALP-4380 | Implementation not registered. | The compliance module registry has no registered entry for the requested typeId. Either the typeId was never registered, or it refers to a different registry. The registry blocks the call to prevent deploying or upgrading with an unknown module type. | Verify that the typeId you are using matches a module type previously registered in this compliance module registry. Use the registry's enumeration to list registered types and confirm your typeId. | error | No | `ImplementationNotRegistered(bytes32)` |
| DALP-4381 | Instance deployment failed. | The module instance deployment returned no address. On a V3 registry the constructor ran out of gas or reverted with no data. On a V2 registry a module that rejects its configuration raises the same error. | Check the module configuration. If the create shared a request with other heavy work, retry with fewer modules, or create the token first and install modules afterwards. | error | No | `InstanceDeploymentFailed()` |
| DALP-4382 | Compliance module rejected the configuration. | The compliance module rejected the supplied configuration. The error includes a reason string describing the specific constraint that failed, such as a zero value where a positive one is required, a duplicate entry, or an address that exceeds an allowed limit. | Correct the configuration field identified in the error reason and resubmit. Consult the error reason string for the exact constraint. | error | No | `InvalidConfig(string)` |
| DALP-4383 | Not module admin. | The compliance module's updateConfig call requires the caller to be either the compliance engine that owns the module or an address the engine has granted module admin status. The caller held neither role. | Use an address that is the compliance engine for this module, or one that the engine's isModuleAdmin check returns true for. Contact the platform operator to have the correct address granted module admin status. | error | No | `NotModuleAdmin()` |
| DALP-4384 | Registry not available. | The compliance engine tried to resolve the compliance module registry through the system contract, but the system contract's registry address is zero. The registry address must be set on the DALPSystem proxy before compliance operations can proceed. | Confirm that the DALPSystem proxy has a non-zero complianceModuleRegistry address configured. Platform setup requires this; contact the operator if the registry address is absent. | error | No | `RegistryNotAvailable()` |
| DALP-4389 | Module family mismatch. | An attempt was made to upgrade a compliance module implementation to a contract from a different V1/V2 family than the one originally registered. Changing the family would break all existing per-engine proxy instances that delegate to the current implementation. | Supply an implementation from the same family as the registered type. A module from the other family needs its own type id. | error | No | `ModuleFamilyMismatch(bool,bool)` |
| DALP-4390 | Type id mismatch. | The new compliance module implementation reports a typeId that does not match the typeId you are registering it under. The registry enforces this to prevent a module from replacing one of a different type. | Ensure the implementation contract's typeId() return value matches the typeId key you are registering it under. Check the implementation contract to confirm its declared type. | error | No | `TypeIdMismatch(bytes32,bytes32)` |
| DALP-4392 | Max chain depth exceeded. | A chained registry (topic scheme or trusted issuers) attempted to set a parent that would create a parent chain longer than 3 levels. The contract enforces this depth limit to prevent unbounded traversal during lookups. | Restructure the registry hierarchy so that no chain from a child registry to a root registry exceeds 3 hops. Remove an intermediate level or flatten the hierarchy before setting the parent. | error | No | `MaxChainDepthExceeded()` |
| DALP-4393 | Not a validator module. | The address passed as a validator module during account creation does not satisfy the ERC-7579 validator interface. The account factory verifies this before creating the smart account to prevent creating accounts with non-functional validators. | Use a module address registered in the account factory that implements the ERC-7579 Module interface with module type VALIDATOR. Confirm the module contract reports the correct module type before submitting. | error | No | `NotAValidatorModule(address)` |
| DALP-4394 | System registry not available. | The token identity registry factory requires one or more system registries to be set on the DALPSystem proxy before a token identity registry can deploy. The named registry address resolves to zero. | Confirm all required system registries are configured on the DALPSystem proxy. The registryName field in the error identifies the missing registry. Contact the platform operator to complete system setup. | error | No | `SystemRegistryNotAvailable(string)` |
| DALP-4396 | V1 hook must bypass adapter. | You called a state-changing compliance hook (transferred, created, or destroyed) directly on the V1 compliance module adapter. The adapter does not handle these hooks because V1 modules require the engine to be msg.sender, so the engine must call the wrapped V1 module directly. | Do not call state-changing hooks on the adapter contract. Read the v1Module() and config() from the adapter, then call the hook on the V1 module directly from the compliance engine. | error | No | `V1HookMustBypassAdapter()` |

The previous page is [DALP-4250 to DALP-4299](https://docs.settlemint.com/docs/api-reference/errors/error-code-reference/dalp-4250-4299). The next page is [DALP-4400 to DALP-4499](https://docs.settlemint.com/docs/api-reference/errors/error-code-reference/dalp-4400-4499).


# DALP-4400 to DALP-4499

Source: https://docs.settlemint.com/docs/api-reference/errors/error-code-reference/dalp-4400-4499
Cause, fix and retry flag for every on-chain contract error with a code from DALP-4400 to DALP-4499.

This page lists the 97 errors in the contract error reference with a code from DALP-4400 to DALP-4499. Match the error's `id`, or its `dalpCode` on a contract error or a failed deployment step, for example `DALP-4400`, to the DALP Code column, then read Retryable and Suggested Fix. The [contract error reference](https://docs.settlemint.com/docs/api-reference/errors/error-code-reference#how-to-use-this-reference) explains each column, including Severity, and the [DALP error index](https://docs.settlemint.com/docs/api-reference/errors) lists the page for every code range.

| DALP Code | Message | Why | Suggested Fix | Severity | Retryable | Solidity Error |
| --- | --- | --- | --- | --- | --- | --- |
| DALP-4400 | The account `{{account}}` does not have the required role to perform this operation. | Account `{{account}}` does not hold the role this function requires, in the contract or in the access manager it defers to. | Ask an administrator of this contract to grant account `{{account}}` the role the function requires. | error | No | `AccessControlUnauthorizedAccount(address,bytes32)` |
| DALP-4401 | Only the owner of this resource can perform this operation. | The function is restricted to the contract owner, and the calling address is not the owner recorded on-chain. | Send the call from the owner address, or ask the owner to run the operation. | error | No | `OwnableUnauthorizedAccount(address)` |
| DALP-4402 | The calling address is not permitted to perform this operation. | The contract delegates authorization to an external access manager, and that manager has determined the calling address is not permitted to call this function. The restriction is set at the access manager level, not within the token contract itself. | Contact your administrator to request access. | error | No | `AccessManagedUnauthorized(address)` |
| DALP-4404 | System already set. | The contract already has a non-zero DALPSystem proxy address stored. The contract permits this reference only once to prevent silent redirection. | The system reference is write-once after initial setup. If you need to point to a different system, re-deploy the compliance contract. Verify the currently configured system address before attempting to set it again. | error | No | `SystemAlreadySet()` |
| DALP-4405 | System not set. | The compliance contract tried to resolve the compliance module registry, but no DALPSystem proxy address has been configured yet. The registry address flows through the system proxy and the contract cannot resolve it without one. | Call setSystem on the compliance contract with the DALPSystem proxy address before attempting registry-dependent operations. Perform this one-time initialization during platform setup. | error | No | `SystemNotSet()` |
| DALP-4406 | Scope expression too complex. | The compliance module scope being set contains at least one expression array that exceeds 32 nodes, or a country list that exceeds 250 entries. The contract enforces these limits to keep on-chain evaluation within gas bounds. | Reduce each expression array in the module scope to 32 nodes or fewer and each country inclusion or exclusion list to 250 entries or fewer. | error | No | `ScopeExpressionTooComplex()` |
| DALP-4407 | Management keys not supported. | The identity implementation deployed at this proxy does not support the V2 interface required for management keys. Management keys can only be set on identities backed by a V2-compatible implementation. | Deploy the identity proxy without management keys when using a V1 implementation, or upgrade to an implementation that supports the IDALPContractIdentityV2 interface before providing management keys. | error | No | `ManagementKeysNotSupported()` |
| DALP-4408 | Config immutable. | The CapitalRaiseLimit compliance module already has a configuration set from its first initialization, and the module policy locks that configuration permanently. The contract blocks any subsequent updateConfig call. | Deploy a new module instance with the parameters you need. | error | No | `ConfigImmutable()` |
| DALP-4409 | Binding already active. | The binding for this instance address is already active. | No action is needed. The binding is already active. | error | No | `BindingAlreadyActive(address)` |
| DALP-4410 | Binding already inactive. | The binding for this instance address is already inactive. | No action is needed. The binding is already inactive. | error | No | `BindingAlreadyInactive(address)` |
| DALP-4411 | Binding not active. | The compliance module binding for the given instance address exists in the registry but has a disabled state. Operations such as reconfiguring the module or updating its scope require an active binding, so the contract blocks the call until you re-enable it. | Call `enableModule` with the instance address, then retry. | error | No | `BindingNotActive(address)` |
| DALP-4412 | Compliance module binding not found. | The compliance module registry holds no record for the given instance address. The contract looks up the binding by address and finds no type identifier, meaning you never installed this module or it has already been fully uninstalled. | Verify that the instance address is correct and that the compliance module has been installed on the token. Install the module first if you have not registered it. | error | No | `BindingNotFound(address)` |
| DALP-4413 | Caller cannot set the OnchainID on this account. | The caller of setOnchainID does not satisfy authorization from any validator installed on the account. Single-owner validators require the recorded EOA owner to call directly. Threshold validators require the call to arrive as a UserOp self-call so a quorum check runs first. | Call setOnchainID from the authorized owner address, or route the call through a UserOp self-call if the account uses a threshold validator. Confirm which validator is installed on the account and satisfy its canManage check. | error | No | `UnauthorizedOnchainIDSetter(address)` |
| DALP-4414 | Caller `{{caller}}` is not authorized to create management keys for contract `{{contractAddress}}`. | The caller (`{{caller}}`) does not hold the authorization required to create management keys for the contract identity at `{{contractAddress}}`. Contract identity creation with management keys requires an authorized signer. | Use an authorized contract-management signer or ask an administrator to create the contract identity. | error | No | `UnauthorizedContractManagementKeys(address,address)` |
| DALP-4415 | Caller `{{caller}}` is not authorized to create an identity for wallet `{{wallet}}`. | The identity factory requires that the wallet creates its own on-chain identity by calling as itself. Caller `{{caller}}` attempted to create the identity for wallet `{{wallet}}`, but the factory accepts direct creation only when the caller and the wallet address match. This prevents any third party from pre-claiming a wallet's CREATE2 identity slot. | Call `createIdentity` as the wallet itself, or have the wallet sign a `createIdentityWithManagementKeyAuthorization` that a relayer then submits. | error | No | `UnauthorizedWalletManagementKeys(address,address)` |
| DALP-4416 | Account onchain id mismatch. | The account at the computed address already stores an ONCHAINID that does not match the expectedOnchainID you supplied in the creation parameters. The factory validates this when you supply a non-zero expectedOnchainID. | Supply the correct expectedOnchainID that matches the ONCHAINID already recorded on the existing account, or omit expectedOnchainID if you do not need to enforce an identity match. | error | No | `AccountOnchainIDMismatch(address,address,address)` |
| DALP-4417 | Account creation authorization deadline expired. | The authorization you supplied carries a deadline that has already passed. The factory checks block.timestamp against the deadline encoded in the authorization parameters and rejects the call when the deadline is in the past. | Request a new account creation authorization signed with a future deadline, then resubmit the call before that deadline passes. | error | No | `ExpiredAccountCreationAuthorization(uint256)` |
| DALP-4418 | Account creation authorization signature does not recover the required owner. | The account factory verified the EIP-712 authorization signature and recovered a signer address that does not match the required owner address. The signature is from a different key than expected. | Have the correct owner sign a fresh account creation authorization and resubmit. | error | No | `InvalidAccountCreationAuthorization(address,address)` |
| DALP-4419 | Unexpected validator init data. | You submitted account creation with non-empty validatorInitData but provided no explicit validator address. When you use the default validator, the factory sets the init data automatically and does not accept caller-supplied init data. | Remove the validatorInitData from the request when creating an account with the default validator, or supply an explicit validator address that accepts the provided init data. | error | No | `UnexpectedValidatorInitData()` |
| DALP-4420 | Empty batch. | A batch call arrived with an empty list. | Include at least one entry in the batch before submitting. | error | No | `EmptyBatch()` |
| DALP-4421 | Conversion trigger expiry timestamp is in the past. | When a non-zero expiry is provided, the contract requires it to be strictly in the future. The supplied `expiresAt` value refers to a time that has already passed. | Set `expiresAt` to a future timestamp, or pass zero to create a trigger that never expires. | error | No | `InvalidExpiry(uint256)` |
| DALP-4422 | The authorized converter must be a conversion feature. | When authorizing a converter address on the minter feature, the contract verifies via ERC-165 introspection that the address implements the IConversionFeature interface. The address at `{{converter}}` did not return a positive response to the interface check, so the contract rejected the authorization. | Select a loan token conversion feature address that supports IConversionFeature, then retry. | error | No | `NotAConversionFeature(address)` |
| DALP-4423 | This transfer is more than the remaining approved allowance. | The transfer approval record for the sender-recipient pair has a remaining allowance that is smaller than the requested transfer amount. The contract enforces that the approval covers the full amount before permitting the transfer. | Request a new transfer approval for an amount at least as large as the transfer you intend to make, or reduce the transfer amount to fit within the existing approval balance. | error | No | `InsufficientApproval()` |
| DALP-4424 | Basis per unit zero. | The fixed treasury yield feature configuration sets basisPerUnit to zero. The contract requires a non-zero value because yield calculations divide by basisPerUnit to compute payouts. | Set basisPerUnit to a positive non-zero value in the feature configuration before creating the fixed treasury yield feature. | error | No | `BasisPerUnitZero()` |
| DALP-4425 | Config data must be empty. | The token feature factory for this feature type does not accept configuration data. The default validateConfig implementation rejects any non-empty configData because this feature has no configurable parameters. | Submit the createFeature or replaceFeature call with an empty configData byte array for this feature type. | error | No | `ConfigDataMustBeEmpty()` |
| DALP-4426 | Config data required. | The token feature factory requires non-empty configuration data for this feature type, but the call arrived with an empty configData byte array. Features such as maturity redemption and fixed treasury yield encode their parameters in configData. | Provide the ABI-encoded configuration parameters for this feature type in configData. Consult the feature factory's validateConfig signature for the expected encoding. | error | No | `ConfigDataRequired()` |
| DALP-4427 | Discount too high. | The discountBps value in the conversion feature configuration exceeds 9999 basis points (99.99%). The contract enforces this limit so the effective conversion price remains non-zero: effectivePrice = roundPrice \* (10000 - discountBps) / 10000. | Set discountBps to a value between 0 and 9999 inclusive in the conversion feature configuration. | error | No | `DiscountTooHigh(uint256)` |
| DALP-4428 | Duplicate converter address. | The initialConverters list you provided to the conversion minter feature contains the same converter address more than once. The factory checks for duplicates to ensure each converter appears exactly once. | Remove duplicate entries from the initialConverters array so every address appears exactly once before submitting the feature creation request. | error | No | `DuplicateConverterAddress(address)` |
| DALP-4429 | End date not after start date. | The endDate in the fixed treasury yield configuration is less than or equal to the startDate. The contract requires endDate to be strictly after startDate for the yield schedule to be valid. | Set endDate to a Unix timestamp that is strictly greater than startDate in the feature configuration. | error | No | `EndDateNotAfterStartDate(uint256,uint256)` |
| DALP-4430 | End date zero. | The endDate in the fixed treasury yield configuration is zero. The contract requires a non-zero endDate to define when yield accrual stops. | Set endDate to a non-zero Unix timestamp in the feature configuration before creating the fixed treasury yield feature. | error | No | `EndDateZero()` |
| DALP-4431 | Escrow required for lock method. | The conversion feature uses the Lock debt reduction method, which requires an escrow contract address to hold locked tokens, but you did not provide one. The contract enforces this dependency at configuration time. | Supply a non-zero escrow contract address in the conversion feature configuration when using the Lock debt reduction method. | error | No | `EscrowRequiredForLockMethod()` |
| DALP-4432 | Face value zero. | The faceValue in the maturity redemption feature configuration is zero. The contract requires a non-zero face value to calculate redemption payouts per token unit at maturity. | Set faceValue to a positive non-zero value in the maturity redemption feature configuration before creating the feature. | error | No | `FaceValueZero()` |
| DALP-4433 | Implementation address zero. | The implementation address provided to the token feature factory upgrade call is the zero address. The contract requires a deployed contract address for the new implementation. | Provide the address of the deployed feature implementation contract when calling validateImplementation or the upgrade path on the feature factory. | error | No | `ImplementationAddressZero()` |
| DALP-4435 | Interval zero. | The interval parameter in the fixed treasury yield feature configuration is zero. The contract requires a non-zero interval to define the time step between yield accrual periods. | Set interval to a positive non-zero duration in seconds in the feature configuration before creating the fixed treasury yield feature. | error | No | `IntervalZero()` |
| DALP-4436 | Conversion window start is after the end timestamp. | The contract requires `conversionWindowStart` to be at or before `conversionWindowEnd` when an end is set. A start timestamp later than the end produces a window that can never open. | Set `conversionWindowStart` to a timestamp that is equal to or earlier than `conversionWindowEnd`, then resubmit the configuration. | error | No | `InvalidConversionWindow()` |
| DALP-4437 | Converter address at position `{{index}}` is the zero address. | Each address in the initial converters list must be a non-zero address. The contract found the zero address at list position `{{index}}`. | Replace the zero address at index `{{index}}` with the intended converter address and resubmit. | error | No | `InvalidConverterAddress(uint256)` |
| DALP-4438 | Treasury address is the zero address. | The fixed treasury yield feature requires a non-zero treasury address to receive yield distributions. A zero address was supplied. | Supply the address of the treasury contract that will receive yield payments. | error | No | `InvalidTreasuryAddress()` |
| DALP-4439 | No feature to replace. | You called replaceFeature for a token that has no feature currently registered in this factory. The factory requires an existing feature before it can replace one. | Call createFeature first to register a feature for this token, then use replaceFeature to update it. | error | No | `NoFeatureToReplace()` |
| DALP-4440 | Rate zero. | The fixed treasury yield feature requires a non-zero yield rate. The rate field in the configuration data resolved to zero, so the factory rejected the deployment. | Supply a positive integer for the yield rate field in the feature configuration and resubmit. | error | No | `RateZero()` |
| DALP-4441 | Replacement not supported. | The Permit and Booked movements feature factories do not replace a feature in place. | To change the feature, remove it and create a new one. The replaceFeature path is not available for these factories. | error | No | `ReplacementNotSupported()` |
| DALP-4442 | Replacement would collide. | The new configuration produces the same CREATE2 address as the feature already registered for this token. This happens when the replacement configuration is identical to the configuration used to deploy the current feature. | Change at least one configuration parameter so the replacement resolves to a different address, then resubmit the replaceFeature call. | error | No | `ReplacementWouldCollide()` |
| DALP-4443 | Start date zero. | The fixed treasury yield feature requires a non-zero start date timestamp. The startDate field in the configuration data resolved to zero, so the factory rejected the deployment. | Supply a valid Unix timestamp for the startDate field in the feature configuration and resubmit. | error | No | `StartDateZero()` |
| DALP-4444 | Implementation interface check failed. | The contract probed the proposed implementation address for ERC-165 support and the call reverted rather than returning a boolean. The implementation contract does not respond correctly to interface introspection. | Verify that the implementation address is a deployed contract that correctly implements ERC-165 supportsInterface without reverting, then resubmit the implementation registration. | error | No | `ImplementationInterfaceCheckFailed()` |
| DALP-4445 | Implementation missing interface. | The proposed implementation contract returned false when queried for ERC-165 interface support for the required feature interface (interfaceId). The contract exists but does not expose the expected capability. | Ensure the implementation contract declares support for the required feature interface via supportsInterface, then resubmit the implementation registration. | error | No | `ImplementationMissingInterface(bytes4)` |
| DALP-4446 | Not deployer. | Only the account that deployed a deferred proxy, such as the Directory or account factory proxy, can call `initializeProxy`. The caller's address does not match the deployer address recorded at construction. | Call initializeProxy from the same account that deployed the proxy contract. | error | No | `NotDeployer()` |
| DALP-4447 | Proxy already initialized. | This deferred directory, account factory or identity factory proxy has already run `initializeProxy`. The contract records a proxy-initialised storage flag on first call, and the contract blocks any further initialisation attempt. | The proxy is ready for use and needs no further initialization. If you intended to upgrade, use the UUPS upgrade path instead. | error | No | `ProxyAlreadyInitialized()` |
| DALP-4448 | Proxy uninitialized. | This deferred directory, account factory or identity factory proxy has not run initializeProxy. The ERC1967 implementation slot holds no address, so the proxy cannot forward calls. | Call initializeProxy on the proxy contract before making any other calls through it. | error | No | `ProxyUninitialized()` |
| DALP-4449 | Bundler call failed. | The paymaster refund splitter tried to forward the bundler portion of a refund to the configured bundler address, but the native ETH transfer reverted. | Verify that the configured bundler address is able to receive native ETH (not a contract that rejects transfers), then retry the refund routing. | error | No | `BundlerCallFailed()` |
| DALP-4450 | Bundler share in basis points exceeds 10000. | The paymaster refund splitter requires the bundler share `bps` to be at most 10000 (100%). The supplied value `{{bps}}` is higher than that limit. | Provide a `bps` value between 0 and 10000 inclusive, where 10000 represents 100% of the refund going to the bundler. | error | No | `InvalidBps(uint16)` |
| DALP-4451 | Bundler address is the zero address. | The paymaster refund splitter requires a non-zero bundler address to route the bundler share of refunds. A zero address was supplied during initialization. | Supply the address of the bundler that will receive its share of EntryPoint refunds. | error | No | `InvalidBundler()` |
| DALP-4453 | Paymaster address does not point to a deployed paymaster contract. | The refund splitter requires the paymaster to be a deployed contract that implements `depositEntryPoint()` and returns a valid, deployed EntryPoint address. The supplied address is either zero, has no deployed code, or its `depositEntryPoint` call failed or returned a zero/undeployed address. | Supply the address of a deployed paymaster contract that implements `depositEntryPoint()` and whose `depositEntryPoint` resolves to a live EntryPoint contract. | error | No | `InvalidPaymaster()` |
| DALP-4454 | Paymaster call failed. | The paymaster refund splitter tried to deposit the paymaster portion of a refund to the paymaster's EntryPoint, but the deposit call reverted. | Verify that the paymaster's canonical EntryPoint is operational and accepts deposits, then retry the refund routing. | error | No | `PaymasterCallFailed()` |
| DALP-4455 | Multicall3 address is zero. | The Multicall3Reference wrapper requires a valid underlying Multicall3 contract address. The address provided to the constructor was the zero address. | Provide the address of a deployed Multicall3 contract when constructing the Multicall3Reference wrapper. | error | No | `ZeroMulticall3()` |
| DALP-4456 | Not refundable. | The settlement owes you nothing yet. A refund opens when the settlement is cancelled, its cutoff date passes or you revoke your approval, and never after it executed. | Check the settlement status. If the settlement executed, use the delivery claim path instead. If the cutoff passed or the settlement was cancelled by the counterparty, confirm your approval state and retry the refund claim. | error | No | `NotRefundable()` |
| DALP-4457 | Stake management must call the canonical EntryPoint directly. | The EntryPointReference wrapper intentionally blocks stake management calls (addStake, unlockStake, withdrawStake). The canonical ERC-4337 EntryPoint records stake keyed by msg.sender, so forwarding through the wrapper would credit stake to the wrapper address rather than your contract. | Call addStake, unlockStake and withdrawStake on the canonical EntryPoint directly, not through the EntryPointReference wrapper. | error | No | `StakeManagementMustCallCanonical()` |
| DALP-4458 | Deposit withdrawal must call the canonical EntryPoint directly. | The EntryPointReference wrapper intentionally blocks `withdrawTo`. The canonical ERC-4337 EntryPoint keys deposits by the calling address, so a forwarded withdrawal would spend the wrapper's own balance instead of yours. Deposits made through the wrapper are credited to the original sender on the canonical EntryPoint. | Call `withdrawTo` on the canonical EntryPoint directly. Your deposit is recorded there under the address that sent it, so the direct call reaches your balance. | error | No | `DepositWithdrawalMustCallCanonical()` |
| DALP-4459 | Sale not finalized. | Sale proceeds stay in the sale contract until the sale is finalized. The sale is still in setup, running, paused, or ended without finalization, so the contract blocks the withdrawal whether or not a soft cap is set. | Finalize the sale after its end time, then withdraw the proceeds. If the sale fails, wait for the refund grace period to pass before withdrawing. | error | No | `SaleNotFinalized()` |
| DALP-4460 | Purchase still deliverable. | The token sale contract releases a buyer's purchase only when it can no longer deliver the tokens, for example because the buyer's wallet is frozen or its identity verification lapsed. A transfer of the buyer's tokens would still succeed, so the contract keeps the purchase. | Let the buyer withdraw their tokens. Release the purchase only for a buyer the sale cannot deliver to. | error | No | `PurchaseStillDeliverable()` |
| DALP-4461 | No undelivered tokens. | The buyer has no tokens left for the sale to deliver: they already withdrew everything they bought, or their purchase was already released. | Read the buyer's position on the sale's cap table. Nothing remains to release for this buyer. | error | No | `NoUndeliveredTokens()` |
| DALP-4462 | Delivery check failed. | The token sale contract could not tell whether the buyer's purchase is still deliverable. A test transfer of the tokens to the sale itself also failed, for example because the token is paused or the sale holds too few tokens, so the refusal is not about the buyer. | Resolve the condition that blocks every transfer of the sale's tokens, such as unpausing the token, then release the purchase again. | error | No | `DeliveryCheckFailed()` |
| DALP-4463 | Waterfall class count mismatch. | The distribution-waterfall feature needs one inclusion flag and one dividend reference per configured share class. The request gave a different number of entries than the waterfall has classes. | Read the waterfall's classes and send one inclusion flag and one dividend reference for each class, in configuration order. | error | No | `ClassCountMismatch(uint256,uint256)` |
| DALP-4464 | No class included in the distribution. | Every share class was left out of the distribution, so the waterfall has no class to give the pool to. A class is left out when it held no supply on the record date. | Choose a record date on which at least one share class has holders, then fund the distribution again. | error | No | `NoClassIncluded()` |
| DALP-4465 | Class dividend cannot be bound. | The waterfall binds each class dividend to that class's part of the distribution when it is funded. This dividend cannot be bound: its class is left out of the distribution, it belongs to a dividend feature the class token does not use, or it does not exist or is already recorded, paid or cancelled. | Preview the coordinated distribution again so each class gets a fresh dividend on its current dividend feature, then fund it. | error | No | `DividendNotBindable(address,uint256)` |
| DALP-4466 | Class dividend already bound. | This class dividend already pays from another distribution of the waterfall. A dividend pays from one distribution only. | Preview the coordinated distribution again so each class gets a new dividend, then fund it. | error | No | `DividendAlreadyBound(address,uint256)` |
| DALP-4467 | Class dividend pays from another treasury. | The class's dividend feature pays its holders from a treasury other than the distribution waterfall, so its claims would never reach the money the waterfall holds for the class. | Use a dividend feature whose treasury is the distribution waterfall for every share class of the instrument. | error | No | `TreasuryMismatch(address,address)` |
| DALP-4468 | Dividend not funded by the waterfall. | The claimed dividend was never bound to a funded distribution of the waterfall, so the waterfall holds no money for it. | Claim a dividend from a coordinated distribution that was funded through the waterfall. Contact the issuer if you expected this dividend to be paid. | error | No | `UnboundDividend(address,uint256)` |
| DALP-4469 | Payout must name its dividend. | The distribution waterfall holds each distribution's money separately, so it pays only a request that names the dividend being claimed. This request did not name one. | Claim through the class's dividend feature, which names the dividend when it asks the waterfall to pay. | error | No | `ReferenceRequired()` |
| DALP-4470 | Class dividend still open for claims. | The share class's dividend for this distribution is still open, so holders can still claim from the money the waterfall holds for it. | Wait until the claim deadline has passed and reclaim the unclaimed dividend, or cancel the dividend if it was never recorded, then release the money. | error | No | `DividendStillOpen(address,uint256)` |
| DALP-4471 | Class money already released. | The money the waterfall held for this share class of the distribution was already returned to the wallet that funded it. | No action is needed. Check the funding wallet for the earlier release. | error | No | `AlreadyReleased(uint256,uint256)` |
| DALP-4472 | Nothing left to release. | The waterfall holds no money for this share class of the distribution: its holders claimed it all, or the class named does not exist or took no part in the distribution. | No action is needed. | error | No | `NothingToRelease(uint256,uint256)` |
| DALP-4473 | Waterfall holds less than it owes. | The waterfall's balance of the distribution currency is below what it still owes across every distribution, so no money is released until the shortfall is covered. Holder claims keep paying while money remains. | Transfer the missing amount of the distribution currency to the waterfall, then release again. | error | No | `WaterfallUnderfunded(uint256,uint256)` |
| DALP-4474 | Governance operation not ready for this step. | The timelock holds each queued governance operation through a fixed delay and runs each step only in the matching operation state. The operation `{{operationId}}` is not in a state that allows this step: it may still be waiting out its delay, or it may already be executed or cancelled. | Read the proposal state and its earliest execution time. Wait until the delay has passed before you execute it, and do not execute or cancel a proposal that is already done. | error | No | `TimelockUnexpectedOperationState(bytes32,bytes32)` |
| DALP-4475 | Governance delay below the timelock minimum. | The timelock refuses to schedule an operation with a delay of `{{delay}}` seconds because its minimum delay is `{{minDelay}}` seconds. | Schedule the operation with a delay of at least the timelock's minimum delay. | error | No | `TimelockInsufficientDelay(uint256,uint256)` |
| DALP-4476 | Earlier governance operation not executed yet. | This governance operation depends on an earlier operation, `{{predecessorId}}`, and the timelock runs it only after that operation has been executed. | Execute the earlier operation first, then execute this one. | error | No | `TimelockUnexecutedPredecessor(bytes32)` |
| DALP-4477 | Only the timelock can change its minimum delay. | Only the timelock itself can change its minimum delay. `{{caller}}` called `updateDelay` directly. | Propose the delay change through the token's governor so the timelock calls `updateDelay` after the delay. | error | No | `TimelockUnauthorizedCaller(address)` |
| DALP-4478 | Governance operation lists do not match. | The timelock needs one target, one value, and one call payload for each action in the operation. It received `{{targets}}` targets, `{{values}}` values, and `{{payloads}}` payloads. | Send the same number of targets, values, and call payloads, one of each per action. | error | No | `TimelockInvalidOperationLength(uint256,uint256,uint256)` |
| DALP-4479 | Buyer wallet not lost. | The token sale contract delivers a buyer's tokens to another wallet only when the identity registry marks the buyer's own wallet as lost and replaced through identity recovery. This buyer's wallet is not marked lost, so the buyer withdraws their tokens themselves. | Let the buyer withdraw their tokens from their own wallet. Recover the buyer's identity onto a new wallet first if the wallet is lost. | error | No | `BuyerWalletNotLost()` |
| DALP-4480 | Buyer wallet lost. | The identity registry marks the buyer's wallet as lost, and no current replacement wallet is known for it, so the token sale contract has no wallet to pay or deliver to. | Recover the buyer's identity onto a new wallet through identity recovery, then deliver or pay again. | error | No | `BuyerWalletLost()` |
| DALP-4481 | This token only moves through a movement the administrator books. | The token has the Booked movements feature attached. A plain transfer, mint, or burn was attempted, and the feature only lets units move when the administrator books a movement in the register. | Ask the administrator to book this movement. | error | No | `MovementRequiresRegisterLine()` |
| DALP-4482 | Movement not found. | The movement number does not exist in this token's register. | Check the movement number and try again. | error | No | `LineNotFound(uint256)` |
| DALP-4483 | Movement cannot change state. | The movement was already booked or cancelled, or it has not been opened yet, so the action does not apply. | Refresh the register and check the movement's current state before you retry. | error | No | `InvalidLineState(uint256,uint8)` |
| DALP-4484 | Request kind not allowed. | The administrator chose which request kinds holders can open for this token. This kind is not on that list. | Open a request of a kind the token accepts, or ask the administrator to allow this kind. | error | No | `KindNotRequestable(uint8)` |
| DALP-4485 | Subscription request already open. | A holder can have one open subscription request at a time, and this holder has one that is still waiting. | Wait for the open request to be booked or cancelled, then open a new one. | error | No | `OpenSubscriptionRequestExists(address)` |
| DALP-4486 | Movement parties invalid. | A movement needs two different parties, and at most one of them can be the zero address. This movement named the same wallet twice, or both parties were the zero address. | Name two different parties, with at most one of them the zero address, and try again. | error | No | `InvalidParties()` |
| DALP-4487 | Register reference missing. | Every movement must carry the reference of the entry it records in the register. This one was empty. | Enter the register reference and try again. | error | No | `EmptyRegisterReference()` |
| DALP-4488 | Corrected movement invalid. | A correction must name an earlier booked movement. The movement given is not a booked movement. | Name a booked movement to correct, or book a new movement instead. | error | No | `InvalidCorrectedLine(uint256)` |
| DALP-4489 | Request kinds invalid. | The setting must be a combination of subscription, transfer, and redemption. The value given has other bits set. | Choose any combination of subscription, transfer, and redemption. | error | No | `InvalidRequestableKinds(uint8)` |
| DALP-4490 | Wallet marked lost. | The identity registry marks the wallet making the request as lost, so it cannot request a movement. | Use a different wallet, or ask the administrator to recover the lost wallet first. | error | No | `WalletMarkedLost(address)` |
| DALP-4491 | Hold feature missing. | Booked movements reserve units with the hold feature. This token does not have it attached. | Attach the hold feature to the token, then try again. | error | No | `HoldFeatureMissing()` |
| DALP-4492 | Feature detached from the token. | The token no longer registers this Booked movements or Hold feature, so it takes no new commitments. | Attach the feature to the token again if you still need it. | error | No | `FeatureDetached()` |
| DALP-4493 | Investor wallet has no registered identity. | The sale sets and reads an allocation cap on the investor's identity. It looks the wallet up in the token's identity registry, and the registry holds no identity for this wallet. | Register the wallet to the investor's identity in the token's identity registry, then set or read the allocation again. | error | No | `InvestorIdentityNotRegistered(address)` |
| DALP-4494 | Investor identity lookup failed. | The sale looked up the buyer's identity in the token's identity registry for the allocation cap, and the registry call reverted without a reason. The sale cannot tell whether a cap applies, so it refuses the purchase. | Check that the token's identity registry is deployed and answers identity lookups. Retry after the registry is fixed. | error | No | `InvestorIdentityLookupFailed()` |
| DALP-4495 | Not a supply delegate. | The address is not registered as a supply delegate on this token, or it is registered without the permission for this mint or burn. | Ask the token's governance to register the address as a supply delegate with the permission it needs. | error | No | `NotADelegate(address)` |
| DALP-4496 | Already a supply delegate. | The address is already registered as a supply delegate on this token. | To change its permissions, remove the delegate and add it again. | error | No | `AlreadyDelegate(address)` |
| DALP-4497 | Supply delegate address is empty. | The zero address cannot be a supply delegate. | Enter the address of the wallet or add-on factory to register. | error | No | `ZeroDelegate()` |
| DALP-4498 | Supply delegate has no permission. | A supply delegate must be allowed to mint, to burn, or both. | Turn on mint, burn, or both before you add the delegate. | error | No | `NoPermission(address)` |
| DALP-4499 | Mint cap without mint permission. | A mint cap was set for a supply delegate that is not allowed to mint. | Allow the delegate to mint, or leave the cap empty. | error | No | `CapWithoutMint(address)` |

The previous page is [DALP-4300 to DALP-4399](https://docs.settlemint.com/docs/api-reference/errors/error-code-reference/dalp-4300-4399). The next page is [DALP-4500 to DALP-4999](https://docs.settlemint.com/docs/api-reference/errors/error-code-reference/dalp-4500-4999).


# DALP-4500 to DALP-4999

Source: https://docs.settlemint.com/docs/api-reference/errors/error-code-reference/dalp-4500-4999
Cause, fix and retry flag for every on-chain contract error with a code from DALP-4500 to DALP-4999.

This page lists the 34 errors in the contract error reference with a code from DALP-4500 to DALP-4999. Match the error's `id`, or its `dalpCode` on a contract error or a failed deployment step, for example `DALP-4500`, to the DALP Code column, then read Retryable and Suggested Fix. The [contract error reference](https://docs.settlemint.com/docs/api-reference/errors/error-code-reference#how-to-use-this-reference) explains each column, including Severity, and the [DALP error index](https://docs.settlemint.com/docs/api-reference/errors) lists the page for every code range.

| DALP Code | Message | Why | Suggested Fix | Severity | Retryable | Solidity Error |
| --- | --- | --- | --- | --- | --- | --- |
| DALP-4500 | Delegate cannot vouch for callers. | The address was registered as a vouching delegate, but it is not a contract that answers which callers it vouches for. | Register a contract that answers the supply delegate question, such as a vouching add-on factory, or register the address as a plain delegate. | error | No | `NotASupplyAuthority(address)` |
| DALP-4501 | Too many supply delegates. | The token already has the largest number of supply delegates it accepts. | Remove a delegate the token no longer needs, then add the new one. | error | No | `TooManyDelegates(uint256)` |
| DALP-4502 | Mint cap reached. | The mint would take the supply delegate's outstanding units, its mints minus its own burns, past the cap governance set. | Mint a smaller amount, burn units first, or ask governance to raise the delegate's cap. | error | No | `MintCapExceeded(address,uint256,uint256,uint256)` |
| DALP-4503 | Settlement not executed. | A settled delivery can only be claimed after the XvP settlement executed, and this settlement has not executed yet. Before execution, a parked amount is a refund of your own escrow. | Claim the parked amount as a refund, or wait until the settlement executes and claim the settled delivery then. | error | No | `SettlementNotExecuted()` |
| DALP-4504 | Applications are not enabled for this sale. | The token sale only takes applications, allocation and settlement when the sale admin switched on application mode while the sale was in setup. This sale did not. | Use the regular purchase flow for this sale. To allocate an oversubscribed offering, create a new sale and enable application mode before activating it. | error | No | `ApplicationModeNotEnabled()` |
| DALP-4505 | This sale takes applications, not purchases. | The sale is in application mode. Investors escrow payment with an application, and the issuer allocates the offering and settles it after the sale closes. A direct purchase would skip the allocation. | Submit an application with the payment currency and amount instead of buying tokens. | error | No | `ApplicationModeActive()` |
| DALP-4506 | Application mode is already on. | Application mode is set once per sale, and its allocation basis cannot change afterwards. | Keep the existing basis. Read it from the sale's application book. | error | No | `ApplicationModeAlreadySet()` |
| DALP-4507 | Application mode cannot be combined with a presale. | A presale prices and limits purchases per address before the public sale. Applications are allocated together after the sale closes, so the two cannot share a sale. | Remove the presale, or run the presale and the application round as two separate sales. | error | No | `ApplicationModeExcludesPresale()` |
| DALP-4508 | Application mode cannot be combined with vesting. | Settlement credits every allocation to the investors in one run. A vesting schedule would release the shares later, so the sale refuses it. | Remove the vesting schedule from the sale. Apply vesting to the shares after settlement if the offering needs it. | error | No | `ApplicationModeExcludesVesting()` |
| DALP-4509 | The applications changed after they were approved. | The allocation runs against the exact set of applications the approver reviewed. A new application arrived after that, so the book hash is now `{{currentBookHash}}`. | Review the new set of applications and the allocation preview, then approve the allocation again. | error | No | `BookChanged(bytes32)` |
| DALP-4510 | The allocation is not complete. | The sale can only be finalized and settled after every application has been allocated. | Continue the allocation until it reports complete, then retry. | error | No | `AllocationIncomplete()` |
| DALP-4511 | The allocation is already complete. | Every application of this sale has been allocated, so there is nothing left to allocate. | Finalize the sale and run the settlement. | error | No | `AllocationAlreadyComplete()` |
| DALP-4512 | The allocation has already started. | Escrow can be reclaimed only while the allocation has not started. Once it starts, the settlement returns every refund. | Wait for the settlement. Each applicant receives their shares and refund in that run. | error | No | `AllocationAlreadyStarted()` |
| DALP-4513 | The allocation window has closed. | The allocation has to start within 30 days after the sale ends. That period has passed, so applicants can reclaim their escrow. | Ask each applicant to reclaim their escrow, then open a new sale if the offering should continue. | error | No | `AllocationWindowExpired()` |
| DALP-4514 | Escrow cannot be reclaimed yet. | The issuer has 30 days after the sale ends to start the allocation. Applicants can reclaim their escrow only after that period. | Wait until the period ends. If the issuer starts the allocation before then, the settlement refunds the excess payment instead. | error | No | `AllocationGracePeriodActive()` |
| DALP-4515 | The settlement is not complete. | The shares nobody received stay in the sale until every applicant has been settled, so the issuer cannot withdraw them yet. | Continue the settlement until it reports complete, then withdraw the unsold shares. | error | No | `SettlementIncomplete()` |
| DALP-4516 | The settlement is already complete. | Every applicant has been settled: shares delivered, refunds paid and the retained payment sent to the recipient. | Withdraw the unsold shares if any remain. | error | No | `SettlementAlreadyComplete()` |
| DALP-4517 | Not enough gas left to pay a refund. | The payment currency refused a refund after it started with less than about 1,050,000 gas, so the refusal may come from the gas limit and not from the currency. The platform sizes a settlement's gas by simulating it, so this most likely means the sale or the currency changed after the settlement was priced. The batch stopped without changing anything. | Start the allocation run again; it needs a second approver's approval again. It continues from the first unsettled applicant and is priced from the current state, so a refund the currency still refuses is recorded as owed. | error | Yes | `RefundCallStarved()` |
| DALP-4518 | This sale cannot mint the shares it issues. | An application-mode sale in this contract version issues its shares when the settlement delivers them, instead of holding the offering in tokens. It can only do that with the supply management role on the sold token, held by the sale's own address, and it does not hold it. | Grant the sale's address the supply management role on the sold token, then activate the sale again. The role shows on the token's permissions page. | error | No | `SaleCannotMint()` |
| DALP-4520 | This greenshoe is not exercised by hand. | Only a discretionary greenshoe is exercised by the sale admin. This sale has an automatic greenshoe, which the allocation decides itself, or no greenshoe at all. | Configure a discretionary greenshoe while the sale is in setup if the sale admin should decide how much of it is used. | error | No | `GreenshoeNotDiscretionary()` |
| DALP-4521 | The greenshoe was already exercised. | A discretionary greenshoe is exercised once, and its amount is part of the book the allocation runs on. | Continue with the allocation. The exercised amount cannot be changed. | error | No | `GreenshoeAlreadyExercised()` |
| DALP-4522 | That greenshoe amount is not available. | The greenshoe adds at most its capacity and at most the demand above the hard cap, in whole tokens. At most `{{available}}` base units can be added now, and the request was zero, larger than that, or not a whole number of tokens. | Exercise a whole number of tokens that does not exceed the available amount. | error | No | `GreenshoeExceedsAvailable(uint256)` |
| DALP-4523 | Too many lock-up categories. | A settlement checks every lock-up category for each applicant, so a sale takes at most eight categories. | Merge categories until there are eight or fewer. | error | No | `TooManyLockupTiers()` |
| DALP-4524 | A lock-up category needs its own claim topic. | Each lock-up category is chosen by a claim topic the investor is verified for. The topic `{{claimTopic}}` is zero or appears in more than one category. | Give every category a distinct, non-zero claim topic. | error | No | `InvalidLockupTopic(uint256)` |
| DALP-4525 | The lock-up is longer than five years. | A lock-up lasts at most five years from the first delivery. The request asked for `{{duration}}` seconds. | Use a lock-up of five years or less. | error | No | `LockupTooLong(uint64)` |
| DALP-4526 | The token has no active lock-up rule. | A sale with lock-ups writes each allocation as a holder lock in the token's lock-up rule. The token has no active lock-up rule, or it was disabled before the sale could lock an allocation. | Install and enable the lock-up rule on the token, then activate or settle the sale again. | error | No | `LockupRuleMissing()` |
| DALP-4527 | This sale cannot lock the shares it issues. | Writing a holder lock in the token's lock-up rule needs the governance role on the token, and the sale does not hold it. | Grant the sale's address the governance role on the sold token, then activate the sale again. The role shows on the token's permissions page. | error | No | `SaleCannotLock()` |
| DALP-4528 | The unlock schedule is invalid. | A schedule holds up to four unlock steps whose shares add up to the whole allocation, each unlocking after the one before it. This schedule breaks one of those rules. | Give every step a positive share, order the steps by their wait from the first delivery, and make the shares add up to 10,000 basis points. | error | No | `InvalidVestingSchedule()` |
| DALP-4529 | The token's lock-up rule cannot store unlock steps. | A sale with more than one unlock step writes each step as a tranche in the token's lock-up rule. The rule installed on the token stores one lock per holder, not tranches. | Install the current lock-up rule on the token, then activate the sale again. A single step that releases the whole allocation works with either rule. | error | No | `LockupTranchesUnsupported()` |
| DALP-4530 | The holder has too many unlock steps. | A holder identity stores at most eight unlock steps on a token, across every allocation that wrote them. This delivery would pass that count with `{{count}}`. | Settle the remaining allocations of this holder in a sale whose schedule adds no more steps, or clear the holder's expired steps on the token first. | error | No | `TooManyHolderTranches(uint256)` |
| DALP-4531 | This wallet was recovered, so it can no longer claim. | Identity recovery replaced this wallet with another one. Refunds, yield and interest that belong to the investor are paid to the replacement wallet, not to the lost key. | Claim with the replacement wallet. If the replacement wallet cannot claim for itself, anyone can ask for the payout to the replacement wallet through the claim for a recovered wallet. | error | No | `ClaimantWalletLost(address)` |
| DALP-4532 | This wallet has no replacement wallet to pay. | A claim for a recovered wallet pays the wallet that identity recovery replaced it with. This wallet is not marked lost, or its recovery chain does not end in a usable wallet, so there is nowhere to send the payout. | Check that identity recovery completed for this wallet. A wallet that is not lost claims for itself. | error | No | `ClaimForNotRecoverable(address)` |
| DALP-4533 | A corporate action is holding this contract's records. | A corporate action on this token froze the contract's records from its record date until the step that re-sizes them lands. The contract refuses deposits, purchases, claims, withdrawals, refunds and releases of the token in that window, so its records stay what the action counted. | Wait until the corporate action finishes, then send the request again. An action that ended while a contract still holds its freeze stays in the status Releasing custody: ask a token manager with the supply management role to choose Release frozen custody on the action's page. The freeze lifts once that release lands, and the request then goes through. | error | No | `CorporateActionInProgress(address,bytes32)` |
| DALP-4539 | Custody gateway holds not yet moved to the recovered wallet. | A custody gateway can rebind to a recovered wallet only once the receipts it holds for custody sit in that wallet. The issuer's forced token recovery moves those receipts and their holds; until it has, the lost wallet still carries them. | Finish the issuer's token recovery for the lost wallet, then execute the identity recovery again. The workflow looks the gateway up again and rebinds it. | error | No | `CustodyGatewayHoldNotMovable(address,address,address)` |

The previous page is [DALP-4400 to DALP-4499](https://docs.settlemint.com/docs/api-reference/errors/error-code-reference/dalp-4400-4499). The next page is [DALP-9000 to DALP-9099](https://docs.settlemint.com/docs/api-reference/errors/error-code-reference/dalp-9000-9099).


# DALP-9000 to DALP-9099

Source: https://docs.settlemint.com/docs/api-reference/errors/error-code-reference/dalp-9000-9099
Cause, fix and retry flag for every on-chain contract error with a code from DALP-9000 to DALP-9099.

This page lists the 70 errors in the contract error reference with a code from DALP-9000 to DALP-9099. Match the error's `id`, or its `dalpCode` on a contract error or a failed deployment step, for example `DALP-9001`, to the DALP Code column, then read Retryable and Suggested Fix. The [contract error reference](https://docs.settlemint.com/docs/api-reference/errors/error-code-reference#how-to-use-this-reference) explains each column, including Severity, and the [DALP error index](https://docs.settlemint.com/docs/api-reference/errors) lists the page for every code range.

| DALP Code | Message | Why | Suggested Fix | Severity | Retryable | Solidity Error |
| --- | --- | --- | --- | --- | --- | --- |
| DALP-9001 | Access control bad confirmation. | OpenZeppelin AccessControl requires callers to confirm role renunciation by passing their own address. The confirmation address provided did not match the caller. | Pass your own account address as the confirmation argument when calling renounceRole. | error | No | `AccessControlBadConfirmation()` |
| DALP-9002 | Access control enforced default admin delay. | A default admin transfer is scheduled but the required delay period has not elapsed. The contract enforces a minimum wait before it will accept the transfer. | Wait until the scheduled timestamp (returned as schedule in the error) has passed, then call acceptDefaultAdminTransfer to complete the role handover. | error | No | `AccessControlEnforcedDefaultAdminDelay(uint48)` |
| DALP-9003 | Access control enforced default admin rules. | Contracts that enforce default admin rules do not allow you to grant or revoke DEFAULT_ADMIN_ROLE directly. The two-step transfer process with a time delay is required for this role. | Use the beginDefaultAdminTransfer and acceptDefaultAdminTransfer sequence to change the default admin, rather than calling grantRole or revokeRole on DEFAULT_ADMIN_ROLE. | error | No | `AccessControlEnforcedDefaultAdminRules()` |
| DALP-9004 | Default admin address cannot be the zero address. | The contract requires the new default admin address to be a non-zero address. OpenZeppelin AccessControl rejects the zero address because it cannot be used as a role holder. | Provide a non-zero account address as the default admin when calling `beginDefaultAdminTransfer`. | error | No | `AccessControlInvalidDefaultAdmin(address)` |
| DALP-9005 | Access control missing any of roles. | The contract checked the caller's address against both role1 and role2 and found neither held. The caller must hold at least one of the two required roles to proceed. | Grant the caller at least one of the two required roles through the token's access manager before retrying the call. | error | No | `AccessControlMissingAnyOfRoles(address,bytes32,bytes32)` |
| DALP-9006 | Address empty code. | The target address passed to an address utility function has no deployed contract code. The call expected a contract at that address but found an externally owned account or an empty address. | Verify that the target address refers to a deployed contract on the current network before retrying the call. | error | No | `AddressEmptyCode(address)` |
| DALP-9007 | Checkpoint unordered insertion. | The checkpoint history accepts keys in non-decreasing order only. This key is lower than the most recent checkpoint key, which is an internal ordering fault. | Contact support with the `requestId` from the error. | error | No | `CheckpointUnorderedInsertion()` |
| DALP-9008 | ECDSA signature malformed. | The ECDSA recovery function returned the zero address, which means the signature bytes do not encode a valid secp256k1 signature. This typically occurs when the signature is truncated, zeroed out, or otherwise corrupted. | Re-sign the message with a valid secp256k1 private key and supply the resulting 65-byte signature. | error | No | `ECDSAInvalidSignature()` |
| DALP-9009 | ECDSA signature length is wrong. | The signature byte array supplied is `{{length}}` bytes long. A valid ECDSA signature must be exactly 65 bytes (r: 32, s: 32, v: 1). | Supply a 65-byte signature produced by signing the EIP-712 or raw hash with the owner's key. | error | No | `ECDSAInvalidSignatureLength(uint256)` |
| DALP-9010 | ECDSA signature s-value is in the upper curve half. | The `s` component of the signature (`{{s}}`) falls in the upper half of the secp256k1 curve order. The contract rejects upper-half `s` values to prevent signature malleability. | Use a signing library that produces a canonical (lower-half `s`) signature, such as a library that normalises `s` after signing. | error | No | `ECDSAInvalidSignatureS(bytes32)` |
| DALP-9011 | ERC 1155 insufficient balance. | The sender's ERC-1155 balance for the specified tokenId is less than the amount you are transferring. The error payload includes both the current balance and the needed amount. | Reduce the transfer amount to no more than the sender's current balance for tokenId, or ensure the sender has received sufficient tokens before retrying. | error | No | `ERC1155InsufficientBalance(address,uint256,uint256,uint256)` |
| DALP-9012 | ERC-1155 approval cannot come from the zero address. | The contract requires the approver in `setApprovalForAll` to be a non-zero address. OpenZeppelin ERC-1155 rejects approvals where the caller resolves to the zero address. | Call `setApprovalForAll` from a funded, non-zero account that owns the tokens. | error | No | `ERC1155InvalidApprover(address)` |
| DALP-9013 | ERC-1155 ids and values arrays have different lengths. | A batch transfer requires one value entry for every token id. The `ids` array has `{{idsLength}}` entries and the `values` array has `{{valuesLength}}` entries, so the contract cannot pair them. | Ensure the `ids` and `values` arrays passed to `safeBatchTransferFrom` have the same length before submitting. | error | No | `ERC1155InvalidArrayLength(uint256,uint256)` |
| DALP-9014 | ERC-1155 operator cannot be the zero address. | The contract requires the operator in `setApprovalForAll` to be a non-zero address. OpenZeppelin ERC-1155 rejects approval grants where the operator is the zero address. | Supply a non-zero operator address when calling `setApprovalForAll`. | error | No | `ERC1155InvalidOperator(address)` |
| DALP-9015 | ERC-1155 receiver address cannot accept tokens. | The transfer target is either the zero address or a contract that returned a value other than the ERC-1155 acceptance magic from `onERC1155Received` or `onERC1155BatchReceived`. The contract halted the transfer to prevent token loss. | Use a recipient address that is either an externally owned account or a contract that correctly implements `IERC1155Receiver`. | error | No | `ERC1155InvalidReceiver(address)` |
| DALP-9016 | ERC-1155 sender cannot be the zero address. | Transferring tokens from the zero address is not permitted by the ERC-1155 standard. The zero address has no balance and cannot be the origin of a transfer. | Initiate the transfer from a non-zero account that holds the tokens being transferred. | error | No | `ERC1155InvalidSender(address)` |
| DALP-9017 | ERC 1155 missing approval for all. | The ERC-1155 standard requires an owner to grant operator approval via setApprovalForAll before that operator can transfer tokens on their behalf. The contract blocked this transfer because the operator address does not have that approval from the token owner. | The token owner must call setApprovalForAll with the operator address and approve=true before the operator can transfer tokens. Retry the transfer after the approval transaction confirms on-chain. | error | No | `ERC1155MissingApprovalForAll(address,address)` |
| DALP-9018 | ERC-1967 implementation address has no contract code. | The contract store rejected the new implementation address (`{{implementation}}`) because it has no deployed bytecode. Setting the implementation slot to an address without code would make all proxied calls revert immediately. | Supply the address of a fully deployed, non-zero implementation contract before calling the upgrade function. | error | No | `ERC1967InvalidImplementation(address)` |
| DALP-9019 | ERC-1967 proxy upgrade cannot receive ETH. | The upgrade sent ETH with no initialisation call to pass it to. ERC-1967 refuses value on a bare upgrade. | Resubmit the upgrade with zero value, or include the initialisation call that the value is for. | error | No | `ERC1967NonPayable()` |
| DALP-9020 | ERC-1967 proxy deployed without initialisation data. | The proxy was deployed with empty initialisation data. The proxy refuses to start uninitialised. | Deploy the proxy with the implementation's initialize call as its data. | error | No | `ERC1967ProxyUninitialized()` |
| DALP-9021 | ERC 20 exceeded safe supply. | The token tracks voting power, which caps total supply at `{{cap}}`. This mint would raise total supply to `{{increasedSupply}}`. | Reduce the mint amount so total supply stays at or below `{{cap}}`. | error | No | `ERC20ExceededSafeSupply(uint256,uint256)` |
| DALP-9022 | ERC-20 approver cannot be the zero address. | The contract requires the approver (the account calling `approve`) to be a non-zero address. An allowance set by the zero address cannot be enforced. | Call `approve` from a non-zero account. The zero address cannot hold or grant token allowances. | error | No | `ERC20InvalidApprover(address)` |
| DALP-9023 | ERC-20 receiver cannot be the zero address. | Transferring or minting tokens to the zero address permanently removes them from circulation. The contract blocks this to prevent accidental token loss. | Supply a non-zero recipient address for the transfer or mint operation. | error | No | `ERC20InvalidReceiver(address)` |
| DALP-9024 | ERC-20 sender cannot be the zero address. | Transferring or burning from the zero address is not permitted. The zero address carries no real balance, and the standard treats it as the token mint/burn sink. | Initiate the transfer or burn from a non-zero account that holds the tokens. | error | No | `ERC20InvalidSender(address)` |
| DALP-9025 | ERC-20 spender cannot be the zero address. | The contract requires the spender in an `approve` or `permit` call to be a non-zero address. The standard blocks an allowance for the zero address, because no one can spend it. | Supply a non-zero spender address when calling `approve` or `permit`. | error | No | `ERC20InvalidSpender(address)` |
| DALP-9026 | Permit signature deadline expired. | The permit signature carries a deadline timestamp and the contract checks that block.timestamp is at or before that deadline. The current block time is past the deadline of `{{deadline}}`, so the permit is no longer usable. | Request a new permit signature with a future deadline timestamp. The deadline in the new permit must be greater than or equal to the current block timestamp at submission time. | error | No | `ERC2612ExpiredSignature(uint256)` |
| DALP-9027 | Permit signature signer does not match the token owner. | The contract recovered address `{{signer}}` from the permit signature, but the expected owner is `{{owner}}`. The recovered address must equal the owner for the permit to authorise the allowance. | Re-sign the EIP-712 permit digest using the private key of the token owner (`{{owner}}`), then resubmit the permit call with the updated signature. | error | No | `ERC2612InvalidSigner(address,address)` |
| DALP-9028 | Forwarder request deadline expired. | The ERC-2771 meta-transaction forwarder checks that the request deadline has not passed before executing the forwarded call. The request deadline of `{{deadline}}` has already elapsed, so the forwarder rejected the request. | Create a new meta-transaction request with a deadline in the future and re-sign it. Submit the updated request before its deadline elapses. | error | No | `ERC2771ForwarderExpiredRequest(uint48)` |
| DALP-9029 | Forwarded request signer does not match the declared sender. | The ERC-2771 forwarder recovered `{{signer}}` from the request signature, but the request declares `{{from}}` as the sender. These two addresses must match for the forwarder to authorise execution. | Re-sign the request with the `from` account's key over its current `nonces(from)` value and the exact fields submitted, then resubmit. | error | No | `ERC2771ForwarderInvalidSigner(address,address)` |
| DALP-9030 | ERC 2771 forwarder mismatched value. | The ERC-2771 forwarder requires that msg.value exactly matches the value declared in the forwarded request. The declared request value was `{{requestedValue}}` but the call arrived with msg.value of `{{msgValue}}`, so the forwarder blocked it. | Resubmit the forwarded call ensuring the ETH value sent with the transaction exactly equals the value field in the signed request. Both values must match. | error | No | `ERC2771ForwarderMismatchedValue(uint256,uint256)` |
| DALP-9031 | ERC 2771 untrustful target. | The ERC-2771 standard requires the target contract to trust the forwarder submitting the request. The target at `{{target}}` does not recognize `{{forwarder}}` as a trusted forwarder, so the contract rejected the forwarded call. | Verify that the target contract lists the forwarder address as trusted. Use a forwarder that the target contract has already registered as trusted. | error | No | `ERC2771UntrustfulTarget(address,address)` |
| DALP-9032 | ERC 5805 future lookup. | The ERC-5805 Votes extension only allows querying vote weight at past timepoints. The requested timepoint of `{{timepoint}}` is ahead of the contract's current clock value of `{{clock}}`, so the contract cannot satisfy the lookup. | Query vote weight using a timepoint that is in the past relative to the current block. Wait for the clock to advance beyond the target timepoint before retrying the lookup. | error | No | `ERC5805FutureLookup(uint256,uint48)` |
| DALP-9033 | ERC 6372 inconsistent clock. | The ERC-6372 clock extension requires that a contract's declared clock mode matches the values it returns. The contract detected an inconsistency between its clock mode descriptor and the clock value, which would make vote timestamps unreliable. | This indicates a contract configuration error. Contact the token administrator to verify that the clock mode and clock implementation are consistent. | error | No | `ERC6372InconsistentClock()` |
| DALP-9034 | ERC 721 incorrect owner. | The ERC-721 transfer function checks that the sender is the current owner of the token before executing a transfer. The contract records `{{owner}}` as the owner of token `{{tokenId}}`, not the caller address `{{sender}}`. | Only the token owner or an approved operator can transfer the token. Confirm the correct owner address and submit the transfer from that address or an approved operator. | error | No | `ERC721IncorrectOwner(address,uint256,address)` |
| DALP-9035 | ERC 721 insufficient approval. | The ERC-721 standard requires the owner to approve an operator for a specific token or for all tokens before the operator can transfer. The operator `{{operator}}` does not have sufficient approval to transfer token `{{tokenId}}`. | The token owner must approve the operator for the specific token via approve, or grant full approval via setApprovalForAll, before the operator can transfer it. | error | No | `ERC721InsufficientApproval(address,uint256)` |
| DALP-9036 | ERC-721 approver cannot be the zero address. | The contract requires the account calling `approve` to be a non-zero address. The zero address cannot own tokens and therefore cannot grant approvals. | Call `approve` from a non-zero account that is the current owner of the token. | error | No | `ERC721InvalidApprover(address)` |
| DALP-9037 | ERC-721 operator cannot be the zero address. | The contract requires the operator in `setApprovalForAll` to be a non-zero address. Granting blanket approval to the zero address has no valid use and the standard blocks it. | Supply a non-zero operator address when calling `setApprovalForAll`. | error | No | `ERC721InvalidOperator(address)` |
| DALP-9038 | ERC-721 owner cannot be the zero address. | The contract maps token ownership to non-zero addresses. Querying or minting to the zero address is not permitted because the zero address is the burned or unminted state. | Supply a non-zero owner address for the mint or ownership query. Check that the token ID exists and has not been burned. | error | No | `ERC721InvalidOwner(address)` |
| DALP-9039 | ERC-721 receiver address cannot accept tokens. | The transfer target is either the zero address or a contract that did not return the ERC-721 acceptance magic from `onERC721Received`. The contract halted the transfer to prevent the token from becoming permanently inaccessible. | Use a recipient address that is either an externally owned account or a contract that correctly implements `IERC721Receiver`. | error | No | `ERC721InvalidReceiver(address)` |
| DALP-9040 | ERC-721 transfer sender is the zero address. | The contract requires the sender address in an ERC-721 transfer or burn to be a non-zero address that holds the token. The zero address was supplied as the sender, which the contract does not recognize as a valid token holder. | Supply the actual owner address as the sender when calling the transfer or burn operation. Confirm the address holds the token before submitting. | error | No | `ERC721InvalidSender(address)` |
| DALP-9041 | ERC 721 nonexistent token. | The ERC-721 contract has no record of token `{{tokenId}}`. Either no one has minted this token yet, or a previous holder burned it, and the contract blocks all operations on it. | Verify the token ID exists by checking current ownership on-chain. Use a token ID that an address has minted and no one has burned. | error | No | `ERC721NonexistentToken(uint256)` |
| DALP-9042 | ERC 7579 already installed module. | The ERC-7579 modular account requires each module to be installed only once per module type. The account already holds module `{{module}}` under type ID `{{moduleTypeId}}`, so the contract blocked a second installation. | Check the account's currently installed modules before calling install. If you need a different module of the same type, uninstall the existing one first, then install the new one. | error | No | `ERC7579AlreadyInstalledModule(uint256,address)` |
| DALP-9043 | ERC 7579 cannot decode fallback data. | Installing or removing a fallback-handler module needs init data that starts with the 4-byte function selector the handler serves. The data supplied is shorter than 4 bytes. | Prefix the module's init data with the selector the fallback handler serves, then resubmit. | error | No | `ERC7579CannotDecodeFallbackData()` |
| DALP-9044 | ERC 7579 decoding error. | The account could not decode the batch execution data: it is too short, or its array offset or length points outside the data. | ABI-encode the batch as an `Execution[]` array of `(target, value, callData)` tuples and resubmit. | error | No | `ERC7579DecodingError()` |
| DALP-9045 | ERC 7579 mismatched module type id. | The ERC-7579 module installation verifies that the module at `{{module}}` self-reports a type that matches the requested type ID `{{moduleTypeId}}`. The module returned a different type, so the contract blocked installation to prevent misconfiguration. | Confirm that the module address and module type ID are correct. Install the module using the type ID that matches what the module contract itself declares. | error | No | `ERC7579MismatchedModuleTypeId(uint256,address)` |
| DALP-9046 | ERC 7579 missing fallback handler. | The ERC-7579 account received a call for function selector `{{selector}}` via the fallback path, but no fallback handler module covers that selector. The contract reverted rather than silently drop the call. | Install a fallback handler module that registers the required function selector before making this call. Check the account's installed fallback handlers and add the appropriate one. | error | No | `ERC7579MissingFallbackHandler(bytes4)` |
| DALP-9047 | ERC 7579 multisig already exists. | The ERC-7579 multisig module maintains a set of unique signers per account. The account's signer set already holds the provided signer bytes, so the contract blocked the duplicate addition to preserve set uniqueness. | Check the account's current signer list before calling addSigners. Remove the duplicate signer from the list or skip entries that are already registered. | error | No | `ERC7579MultisigAlreadyExists(bytes)` |
| DALP-9048 | Multisig init data is too short to decode. | The contract requires `initData` to be at least 96 bytes so it can ABI-decode the signers array and threshold. The data provided is shorter than that minimum and cannot be parsed. | Provide `initData` as a valid ABI-encoded `(bytes[], uint64)` (or `(bytes[], uint64, uint64[])` for weighted installs). A correct encoding is always at least 96 bytes. | error | No | `ERC7579MultisigInvalidInitData()` |
| DALP-9049 | Signer bytes are too short to represent a valid ERC-7913 signer. | The contract stores signers as variable-length bytes and requires each signer to be at least 20 bytes long. The signer value you supplied (`{{signer}}`) is shorter than 20 bytes, which does not meet the minimum length for an ERC-7913 signer. | Supply signer bytes that are at least 20 bytes long. For a plain EOA, encode the 20-byte address. For a contract signer, follow the ERC-7913 encoding format. | error | No | `ERC7579MultisigInvalidSigner(bytes)` |
| DALP-9050 | Signer weight of zero is not permitted. | The contract requires every signer weight to be at least 1. The weight supplied for signer `{{signer}}` is 0, which would make the signer contribute nothing toward the approval threshold. | Set the weight for each signer to 1 or greater. The minimum effective weight is 1. | error | No | `ERC7579MultisigInvalidWeight(bytes,uint64)` |
| DALP-9051 | ERC 7579 multisig mismatched length. | The multisig weight update requires one weight entry for each signer. The signers array and the weights array have different lengths, so the contract cannot map each signer to a weight. | Ensure the signers array and the weights array you pass to the weight-update call contain the same number of entries, then resubmit. | error | No | `ERC7579MultisigMismatchedLength()` |
| DALP-9052 | ERC 7579 multisig nonexistent signer. | The address bytes you provided as a signer do not appear in the account's signer set. The contract requires each signer to be registered before you can change its weight or remove it. | Verify the signer bytes match an address you previously added to the multisig. Add the signer first, or correct the signer bytes, then retry the operation. | error | No | `ERC7579MultisigNonexistentSigner(bytes)` |
| DALP-9053 | ERC 7579 multisig unreachable threshold. | The combined weight of all registered signers (`{{signers}}`) is less than the required threshold (`{{threshold}}`). Every signer would need to approve and the total weight would still fall short, making approval permanently impossible. | Either reduce the threshold to at most the current total signer weight, or add more signers with sufficient weight before setting the threshold. | error | No | `ERC7579MultisigUnreachableThreshold(uint64,uint64)` |
| DALP-9054 | ERC 7579 multisig zero threshold. | The multisig threshold must be at least 1. A threshold of zero would allow any call to pass without any signer approvals, which the contract prevents. | Set the threshold to a value of 1 or greater before installing or reconfiguring the multisig. | error | No | `ERC7579MultisigZeroThreshold()` |
| DALP-9055 | ERC 7579 uninstalled module. | The account does not have the module at the given address installed for the specified module type. The operation requires the module to be present before you can use or remove it. | Install the module on the account first using the install module call, then retry the operation. | error | No | `ERC7579UninstalledModule(uint256,address)` |
| DALP-9056 | ERC 7579 unsupported call type. | The call type byte in the execution mode (`{{callType}}`) does not match any of the supported types. This account supports single call (0x00), batch call (0x01), and delegatecall (0xff). | Set the call type byte in your execution mode to one of the supported values: 0x00 for single, 0x01 for batch, or 0xff for delegatecall. | error | No | `ERC7579UnsupportedCallType(bytes1)` |
| DALP-9057 | ERC 7579 unsupported exec type. | The exec type byte in the execution mode (`{{execType}}`) is not one of the supported types. This account supports default execution (0x00, reverts on failure) and try execution (0x01, emits an event on failure). | Set the exec type byte in your execution mode to 0x00 (default, revert on failure) or 0x01 (try, emit on failure). | error | No | `ERC7579UnsupportedExecType(bytes1)` |
| DALP-9058 | ERC 7579 unsupported module type. | The module type identifier (`{{moduleTypeId}}`) is not supported by this account. The account supports validator modules (type 1), executor modules (type 2), and fallback handler modules (type 3). | Use one of the supported module type identifiers: 1 for validator, 2 for executor, or 3 for fallback handler. | error | No | `ERC7579UnsupportedModuleType(uint256)` |
| DALP-9059 | Expected pause. | The token contract is in the wrong pause state for this call. A resume (unpause) was requested while the token is already active, or a function that requires the paused state was called while the token is active. A token on an older implementation raises it for a halt (pause) requested while the token is already paused instead. | Read the token's pause state before calling. If you asked to halt or resume it and it is already in that state, there is nothing to change. Pause the token before you call a function that requires the paused state. | error | No | `ExpectedPause()` |
| DALP-9060 | Failed call. | A low-level call failed without returning a reason. The target reverted with no data or ran out of gas. | Confirm the target address is a deployed contract and that it accepts the call. Check that you provide sufficient gas, then retry the operation. | error | No | `FailedCall()` |
| DALP-9061 | The contract does not hold enough ETH for this operation. | The ETH balance held by the contract (`{{balance}}`) is below the amount needed (`{{needed}}`) to complete the operation. The contract enforces that it holds enough ETH before proceeding. | Ensure the contract holds enough ETH to cover the required amount before retrying. You may need to send ETH to the contract first. | error | No | `InsufficientBalance(uint256,uint256)` |
| DALP-9062 | Ownership transfer to the zero address rejected. | The contract rejects `address(0)` as a proposed owner because a zero-address owner would make the contract permanently unowned and unmanageable. | Supply a non-zero Ethereum address as the new owner when calling the ownership transfer or initialization function. | error | No | `OwnableInvalidOwner(address)` |
| DALP-9063 | Reentrancy guard reentrant call. | Your code called a protected function while the same function (or another protected function) was still executing. The reentrancy guard detected a nested call and blocked it to prevent exploits. | Ensure your code does not call back into this contract from within a callback or external call that the contract itself initiates. Restructure the calling sequence to avoid nesting calls to protected functions. | error | No | `ReentrancyGuardReentrantCall()` |
| DALP-9064 | Safe cast overflowed uint downcast. | The numeric value (`{{value}}`) exceeds the maximum that a `{{bits}}`-bit unsigned integer can hold. The safe cast library prevents silent overflow by reverting instead of truncating the value. | Reduce the input value so it fits within the `{{bits}}`-bit range, then retry the operation. | error | No | `SafeCastOverflowedUintDowncast(uint8,uint256)` |
| DALP-9065 | Safe erc 20 failed operation. | A transfer or approval call on the ERC-20 token at address `{{token}}` returned false or reverted. The token contract did not confirm success. | Check that the sending address has sufficient balance and allowance, and that the token at `{{token}}` is a standard ERC-20 contract. Resolve any token-level rejection and retry the operation. | error | No | `SafeERC20FailedOperation(address)` |
| DALP-9066 | Strings insufficient hex length. | The numeric value (`{{value}}`) requires more hex digits than the requested output length (`{{length}}`) can hold. The contract cannot produce a shorter representation without losing data. | Increase the requested hex string length to fit the value, or reduce the value, then retry the operation. | error | No | `StringsInsufficientHexLength(uint256,uint256)` |
| DALP-9067 | UUPS unauthorized call context. | You called a UUPS upgrade function in an unsupported context. Either you called it directly on the implementation contract instead of through the proxy, or the notDelegated guard detected a delegatecall on a function that must run directly. | Route the upgrade call through the proxy contract, not directly to the implementation. Confirm your client is calling the proxy address. | error | No | `UUPSUnauthorizedCallContext()` |
| DALP-9068 | UUPS unsupported proxiable uuid. | During an upgrade, the new implementation's proxiableUUID() returned a storage slot (`{{slot}}`) that does not match the expected ERC-1967 implementation slot. This means the proposed implementation is not compatible with the UUPS proxy pattern used by this contract. | Ensure the new implementation contract inherits from UUPSUpgradeable correctly and returns the ERC-1967 implementation slot from proxiableUUID(). Deploy a corrected implementation, then retry the upgrade. | error | No | `UUPSUnsupportedProxiableUUID(bytes32)` |
| DALP-9069 | Permit signature verification failed for owner `{{owner}}`. | The contract called `SignatureChecker.isValidSignatureNow` with the provided bytes signature and it returned false for the expected owner (`{{owner}}`). This overload supports both ECDSA signatures and EIP-1271 contract-wallet validation, so the signature may be malformed, signed with the wrong key, or the owner contract rejected it. | Re-sign the EIP-712 permit digest with the correct key for the owner address. If the owner is a smart wallet, confirm it implements `isValidSignature` and that the signature bytes match what the wallet expects. | error | No | `ERC2612InvalidSignature(address)` |
| DALP-9081 | Convert needs the accrued-interest backlog settled first. | A full conversion on a feature set to close interest on conversion must close the holder's yield accrual. The holder still has unsettled convertible interest, and closing accrual now would discard it. | Send the conversion again. The platform drains the backlog before each convert. To settle it yourself, call `convertYield` for target tokens or `claimYield` for cash. | error | Yes | `UnsettledConvertibleInterest()` |

The previous page is [DALP-4500 to DALP-4999](https://docs.settlemint.com/docs/api-reference/errors/error-code-reference/dalp-4500-4999). The next page is [DALP-9200 to DALP-9299](https://docs.settlemint.com/docs/api-reference/errors/error-code-reference/dalp-9200-9299).


# DALP-9200 to DALP-9299

Source: https://docs.settlemint.com/docs/api-reference/errors/error-code-reference/dalp-9200-9299
Cause, fix and retry flag for every on-chain contract error with a code from DALP-9200 to DALP-9299.

This page lists the 28 errors in the contract error reference with a code from DALP-9200 to DALP-9299. Match the error's `id`, or its `dalpCode` on a contract error or a failed deployment step, for example `DALP-9203`, to the DALP Code column, then read Retryable and Suggested Fix. The [contract error reference](https://docs.settlemint.com/docs/api-reference/errors/error-code-reference#how-to-use-this-reference) explains each column, including Severity, and the [DALP error index](https://docs.settlemint.com/docs/api-reference/errors) lists the page for every code range.

| DALP Code | Message | Why | Suggested Fix | Severity | Retryable | Solidity Error |
| --- | --- | --- | --- | --- | --- | --- |
| DALP-9203 | The yield feature's default claim-deadline period must be greater than zero days. | The feature is configured with a default number of days holders get to claim each dividend, and zero days is rejected at setup. | Configure the feature with a positive default claim-deadline period, then retry. | error | No | `InvalidClaimDeadlineDays()` |
| DALP-9204 | The yield schedule configuration could not be applied. | The dividend feature configuration must encode exactly a denomination asset, a treasury and a default claim-deadline period. | Encode exactly those three values, then send the configuration again. | error | No | `InvalidConfig()` |
| DALP-9206 | The dividend dates are out of order. | Dividend dates must not run backwards through the order ex-date, record date, payment date, claim deadline. The claim deadline must also be in the future. | Order the dates ex-date, record date, payment date, claim deadline, with the deadline in the future, then retry. | error | No | `InvalidDates()` |
| DALP-9207 | The dividend's per-share amount must be greater than zero. | Dividends require a positive per-share payout amount. | Enter a per-share amount greater than zero, then declare the dividend again. | error | No | `InvalidAmountPerShare()` |
| DALP-9209 | No dividend with this identifier exists on the schedule. | The dividend identifier does not match any declared dividend on this schedule. | Check the dividend identifier against the schedule's dividend list, then retry. | error | No | `InvalidDividendId()` |
| DALP-9210 | This dividend is not in the right state for that operation. | The dividend is cancelled or paid, which ends its lifecycle. Reclaiming unclaimed funds also needs a recorded snapshot, and extending the claim deadline needs a payable dividend. | Read the dividend's status before the operation. A cancelled or paid dividend accepts none. Reclaiming needs a recorded snapshot, and extending the claim deadline needs a payable dividend. | error | No | `InvalidStatus()` |
| DALP-9211 | This dividend is not in a payable state yet, so it cannot be claimed. | Dividends become claimable only after the holder snapshot is recorded and the payment date has passed. | Wait until the dividend has been recorded and its payment date has passed. Holders can claim once the dividend becomes payable. | error | Yes | `DividendNotPayable()` |
| DALP-9212 | The dividend's record date has not been reached yet, so the holder snapshot cannot be taken. | Holder snapshots are only valid once the record date has passed. | Wait until the record date has passed, then record the holder snapshot for this dividend. | error | Yes | `RecordDateNotReached()` |
| DALP-9213 | The holder snapshot for this dividend has already been recorded. | Each dividend accepts exactly one holder snapshot, and this dividend already has one. | No further recording is needed. Continue with the next step of the dividend lifecycle. | error | No | `AlreadyRecorded()` |
| DALP-9214 | This dividend can no longer be cancelled because its holder snapshot is already recorded. | Cancellation is only possible before the holder snapshot is recorded; after that the payout obligations are fixed. | The dividend must proceed to payment. Contact your administrator if the distribution was declared in error. | error | No | `CannotCancelAfterRecord()` |
| DALP-9215 | This dividend has more eligible holders than a single on-chain snapshot can record. | A dividend snapshot holds at most 16,384 entitled holders, and this dividend has more. | Contact support with the `requestId` from the error. | error | No | `TooManyHolders()` |
| DALP-9216 | Your dividend claim could not be verified against the recorded holder snapshot. | The leaf index, holder and amount do not match a leaf in the recorded snapshot. | Claim with the account, leaf index and exact amount from your allocation. | error | No | `InvalidProof()` |
| DALP-9217 | You have already claimed this dividend. | Each holder can claim a dividend only once. | No further action is needed. The payout from this dividend is already in your balance. | error | No | `AlreadyClaimed()` |
| DALP-9219 | This dividend is closed and can no longer be claimed. | The dividend was cancelled, or its unclaimed funds were reclaimed after the claim deadline. | Contact your administrator to ask about a missed eligible claim. | error | No | `DividendClosed()` |
| DALP-9220 | Your identity is not verified for this token, so dividend claims are blocked. | Dividend claims re-check the holder's on-chain identity at claim time. | Contact your administrator to restore your identity verification, then claim again before the deadline. | error | No | `IdentityRevoked()` |
| DALP-9222 | The dividend snapshot lists no entitled holders. | The contract needs at least one entitled holder to pay a dividend to. | Re-run the holder snapshot with at least one entitled holder, then submit again. | error | No | `InvalidTotalEntitled()` |
| DALP-9223 | The dividend snapshot's total payout is zero. | The holder amounts in the snapshot add up to zero, so no payout is owed. | Re-run the holder snapshot so the total payout is greater than zero, then submit again. | error | No | `InvalidTotalRequired()` |
| DALP-9224 | This dividend cannot be closed yet because its claim deadline has not passed. | Closing a dividend reclaims unclaimed funds, which is only allowed after the claim deadline expires. | Wait until the claim deadline has passed, then close the dividend. | error | Yes | `ClaimDeadlineNotReached()` |
| DALP-9225 | The claim deadline for this dividend has already been extended once. | Each dividend allows a single claim-deadline extension. | No further extension is possible. Holders need to claim before the current deadline. | error | No | `DeadlineAlreadyExtended()` |
| DALP-9226 | The new claim deadline must be later than the current one. | The contract only extends a claim deadline. A date equal to or before the current deadline extends nothing. | Choose a date after the current claim deadline, then retry. | error | No | `InvalidClaimDeadline()` |
| DALP-9228 | This yield schedule is paused. | An emergency-role holder paused this interest schedule, which blocks claims and conversions until it is resumed. Pausing a schedule that is already paused also fails. | Ask an emergency-role holder to resume the schedule, then retry. A pause request for a schedule that is already paused needs no retry. | error | No | `SchedulePaused()` |
| DALP-9231 | This interest schedule has not been configured yet. | The operation requires the schedule's rate and start date to be set first. | Configure the schedule with a rate and start date, then retry the operation. | error | No | `ScheduleNotConfigured()` |
| DALP-9232 | This interest schedule is already configured. | A schedule's rate and start date can be set only once. | Use the rate-change operation to adjust an existing schedule instead of configuring it again. | error | No | `ScheduleAlreadyConfigured()` |
| DALP-9234 | The interest rate cannot be changed while the schedule is paused. | Rate changes are blocked during a pause so accrual resumes from a consistent state. | Resume the schedule first, then apply the rate change. | error | No | `PausedRateChangeForbidden()` |
| DALP-9235 | The schedule is not paused, so it cannot be resumed. | Resuming is only meaningful when the schedule is currently paused. | No action is needed. The schedule is already active. | error | No | `NotPaused()` |
| DALP-9237 | The selected denomination asset is not permitted for this yield schedule. | The denomination asset is registered on this platform as a fee-on-transfer or rebasing token, and a yield schedule cannot pay exact amounts with either. Unregistered tokens pass this guard. | Choose a denomination asset whose balance does not change on transfer or over time, then create the schedule again. | error | No | `DenominationNotAllowed()` |
| DALP-9294 | The record date is before the token's balance history begins. | A dividend with a past record date is paid on balances from the historical-balances feature, which only holds balances from the moment it was enabled. | Choose a record date on or after the moment historical balances were enabled for this token, then declare the dividend again. | error | No | `RecordDateNotCovered()` |
| DALP-9295 | This holder's address is frozen on this token, so the dividend cannot be paid to them. | Dividend claims re-check the holder's freeze at claim time, for the holder's own claim and for a custodian's. | Lift the freeze first, then claim again before the deadline. | error | No | `HolderFrozen()` |

The previous page is [DALP-9000 to DALP-9099](https://docs.settlemint.com/docs/api-reference/errors/error-code-reference/dalp-9000-9099). The next page is [DALP-9300 to DALP-9399](https://docs.settlemint.com/docs/api-reference/errors/error-code-reference/dalp-9300-9399).


# DALP-9300 to DALP-9399

Source: https://docs.settlemint.com/docs/api-reference/errors/error-code-reference/dalp-9300-9399
Cause, fix and retry flag for every on-chain contract error with a code from DALP-9300 to DALP-9399.

This page lists the 9 errors in the contract error reference with a code from DALP-9300 to DALP-9399. Match the error's `id`, or its `dalpCode` on a contract error or a failed deployment step, for example `DALP-9339`, to the DALP Code column, then read Retryable and Suggested Fix. The [contract error reference](https://docs.settlemint.com/docs/api-reference/errors/error-code-reference#how-to-use-this-reference) explains each column, including Severity, and the [DALP error index](https://docs.settlemint.com/docs/api-reference/errors) lists the page for every code range.

| DALP Code | Message | Why | Suggested Fix | Severity | Retryable | Solidity Error |
| --- | --- | --- | --- | --- | --- | --- |
| DALP-9339 | This document is already anchored under the same issuer and nonce. | An entry is identified by its issuer and the nonce reserved for it, and the registry only ever appends. A repeat of the same pair with the same subject, digest, document type and label means an earlier attempt's write reached the chain even if its response did not. | Read the existing entry back and record it as the anchor. Do not reserve a new nonce; that would write a second entry for one document. | error | No | `AlreadyAnchored(bytes32)` |
| DALP-9340 | The sending wallet holds no claim key on the issuer identity it named. | The registry accepts an entry only from a wallet the issuer identity lists with claim purpose, so an issuer cannot be attested for by a key it never authorized. | Add a claim key for this wallet on the issuer identity, or send from a wallet that already holds one, then retry. | error | No | `SenderNotClaimKeyHolder(address,address)` |
| DALP-9341 | The issuer identity is not a trusted issuer for document hashes in this system. | The registry checks the trusted-issuer registry pinned to it when it was created, so a registration made in another system's registry does not authorize an entry here. | Register the issuer identity for the documentHash topic in this system's own trusted-issuer registry, then retry. | error | No | `IssuerNotTrusted(address,address)` |
| DALP-9342 | This registry holds no entry with that identifier. | An entry identifier is derived from the issuer and the nonce reserved for it, so an identifier the registry does not hold was never anchored here. | Check the identifier and the registry address. Look the document up by its digest if you do not have the entry identifier. | error | No | `EntryNotFound(bytes32)` |
| DALP-9343 | The issuer or the subject identity is the zero address. | An entry records which identity attested to the document and which identity it belongs to, and neither can be the zero address. | Send the issuer identity contract and the subject identity contract, then retry. | error | No | `InvalidIdentity()` |
| DALP-9344 | The document digest is empty. | The digest is the evidence the entry exists to hold, so an all-zero value is rejected rather than recorded on a permanent record. | Send the document's 32-byte manifest digest, then retry. | error | No | `InvalidDigest()` |
| DALP-9345 | The anchor registry was created without a trusted-issuer registry. | The registry pins the trusted-issuer registry it checks when it is created, so it cannot be created without one. | Deploy the anchor registry through the system bootstrap or migration, which supplies the system's own trusted-issuer registry. | error | No | `InvalidTrustedIssuersRegistry()` |
| DALP-9346 | The anchor registry for this system has been retired. | A system manager archived the registry's registration. The registry only ever appends, so it stops accepting entries the moment it is retired rather than adding a record nobody can withdraw. | Ask a system manager to re-register the anchor registry on this system, then retry. | error | No | `RegistryArchived()` |
| DALP-9347 | The wallet signing this anchor is no longer an active registration. | The wallet was marked lost during an identity recovery, or it has no registration in the system's identity registry. The registry only ever appends, so it refuses a wallet the identity registry no longer recognises rather than leaving a record nobody can withdraw. | Sign the anchor with the wallet the recovery replaced this one with, or ask an identity manager to register it. | error | No | `SenderIdentityNotActive(address)` |

The previous page is [DALP-9200 to DALP-9299](https://docs.settlemint.com/docs/api-reference/errors/error-code-reference/dalp-9200-9299). The next page is [DALP-9500 to DALP-9999](https://docs.settlemint.com/docs/api-reference/errors/error-code-reference/dalp-9500-9999).


# DALP-9500 to DALP-9999

Source: https://docs.settlemint.com/docs/api-reference/errors/error-code-reference/dalp-9500-9999
Cause, fix and retry flag for every on-chain contract error with a code from DALP-9500 to DALP-9999.

This page lists the 2 errors in the contract error reference with a code from DALP-9500 to DALP-9999. Match the error's `id`, or its `dalpCode` on a contract error or a failed deployment step, for example `DALP-9545`, to the DALP Code column, then read Retryable and Suggested Fix. The [contract error reference](https://docs.settlemint.com/docs/api-reference/errors/error-code-reference#how-to-use-this-reference) explains each column, including Severity, and the [DALP error index](https://docs.settlemint.com/docs/api-reference/errors) lists the page for every code range.

| DALP Code | Message | Why | Suggested Fix | Severity | Retryable | Solidity Error |
| --- | --- | --- | --- | --- | --- | --- |
| DALP-9545 | The interest day-count convention is not supported. | Interest yield accepts continuous (per second over a 365-day year) or ACT/360 (per completed UTC day over a 360-day year). Any other value is refused. | Choose continuous or act-360, then attach the interest schedule again. | error | No | `InvalidDaycountConvention()` |
| DALP-9562 | This issuer and nonce already anchor a different document. | An entry is identified by its issuer and the nonce reserved for it, and the registry only ever appends. The stored entry differs from this submission in its subject, digest, document type or label (a changed label alone is enough), so this attempt is not a replay of one that landed: either another claim key on the issuer wrote this identifier first, or this submission's content changed since the first attempt. | Reserve a fresh nonce for this document and retry. Do not treat the existing entry as this document's anchor. | error | No | `NonceReused(bytes32)` |

The previous page is [DALP-9300 to DALP-9399](https://docs.settlemint.com/docs/api-reference/errors/error-code-reference/dalp-9300-9399). The next page is [Codes without a number](https://docs.settlemint.com/docs/api-reference/errors/error-code-reference/unnumbered-codes).


# Contract error reference

Source: https://docs.settlemint.com/docs/api-reference/errors/error-code-reference
Find the cause and the fix for every catalogued on-chain revert DALP contracts can return, with retryability for each.

A DALP smart contract error is a revert that reaches you in an API or SDK error as `id`, or as `dalpCode` on a contract error or a failed deployment step. Open the page for the code's range from [Pages by code range](#pages-by-code-range), then read the Why and Suggested Fix columns. The reference covers validation and permission checks, the asset lifecycle, settlement and infrastructure.

Errors the Platform API raises itself, such as authentication or validation failures, are in the [Platform API error reference](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference). The [DALP error index](https://docs.settlemint.com/docs/api-reference/errors) lists the page for every code range in both references, [Read and handle DALP errors](https://docs.settlemint.com/docs/api-reference/guides/errors) explains the error envelope, and [Error handling](https://docs.settlemint.com/docs/api-reference/errors/error-handling) explains retries and escalation.

## How to use this reference [#how-to-use-this-reference]

1. Find the `id` in the error, or its `dalpCode` on a contract error or a failed deployment step, and open the page for the code range that holds it.
2. Read the Message and Why columns to understand what the contract rejected and why.
3. Apply the Suggested Fix, then use Retryable for control flow. `Yes` means the same request can succeed later without a change to the request, for example once a date passes or a price feed updates. `No` means repeat calls fail until you act on the Suggested Fix.
4. Read Severity as a default for your own alerting. [Error handling](https://docs.settlemint.com/docs/api-reference/errors/error-handling#criticality-and-escalation) says who handles each level and when to escalate.
5. Keep the `requestId` or `correlationId` from the error, whichever is present, and include it when you open a support ticket.

Message is the headline, Why is the on-chain condition that failed, Suggested Fix is the next step, and Solidity Error is the custom error the contract reverted with. Do not parse the Message, Why or Suggested Fix columns in program logic, because their wording can change. Branch on the `id` (or `dalpCode`) together with the `retryable` flag.

## Pages by code range [#pages-by-code-range]

- [DALP-1000 to DALP-1049](https://docs.settlemint.com/docs/api-reference/errors/error-code-reference/dalp-1000-1049): 49 errors.
- [DALP-1050 to DALP-1099](https://docs.settlemint.com/docs/api-reference/errors/error-code-reference/dalp-1050-1099): 50 errors.
- [DALP-1100 to DALP-1199](https://docs.settlemint.com/docs/api-reference/errors/error-code-reference/dalp-1100-1199): 38 errors.
- [DALP-2000 to DALP-2999](https://docs.settlemint.com/docs/api-reference/errors/error-code-reference/dalp-2000-2999): 12 errors.
- [DALP-3000 to DALP-3999](https://docs.settlemint.com/docs/api-reference/errors/error-code-reference/dalp-3000-3999): 32 errors.
- [DALP-4000 to DALP-4049](https://docs.settlemint.com/docs/api-reference/errors/error-code-reference/dalp-4000-4049): 49 errors.
- [DALP-4050 to DALP-4099](https://docs.settlemint.com/docs/api-reference/errors/error-code-reference/dalp-4050-4099): 50 errors.
- [DALP-4100 to DALP-4149](https://docs.settlemint.com/docs/api-reference/errors/error-code-reference/dalp-4100-4149): 50 errors.
- [DALP-4150 to DALP-4199](https://docs.settlemint.com/docs/api-reference/errors/error-code-reference/dalp-4150-4199): 50 errors.
- [DALP-4200 to DALP-4249](https://docs.settlemint.com/docs/api-reference/errors/error-code-reference/dalp-4200-4249): 48 errors.
- [DALP-4250 to DALP-4299](https://docs.settlemint.com/docs/api-reference/errors/error-code-reference/dalp-4250-4299): 50 errors.
- [DALP-4300 to DALP-4399](https://docs.settlemint.com/docs/api-reference/errors/error-code-reference/dalp-4300-4399): 91 errors.
- [DALP-4400 to DALP-4499](https://docs.settlemint.com/docs/api-reference/errors/error-code-reference/dalp-4400-4499): 97 errors.
- [DALP-4500 to DALP-4999](https://docs.settlemint.com/docs/api-reference/errors/error-code-reference/dalp-4500-4999): 34 errors.
- [DALP-9000 to DALP-9099](https://docs.settlemint.com/docs/api-reference/errors/error-code-reference/dalp-9000-9099): 70 errors.
- [DALP-9200 to DALP-9299](https://docs.settlemint.com/docs/api-reference/errors/error-code-reference/dalp-9200-9299): 28 errors.
- [DALP-9300 to DALP-9399](https://docs.settlemint.com/docs/api-reference/errors/error-code-reference/dalp-9300-9399): 9 errors.
- [DALP-9500 to DALP-9999](https://docs.settlemint.com/docs/api-reference/errors/error-code-reference/dalp-9500-9999): 2 errors.
- [Codes without a number](https://docs.settlemint.com/docs/api-reference/errors/error-code-reference/unnumbered-codes): 5 errors.

## Contents [#contents]

- [Compliance & token operations](#compliance--token-operations): 137 errors.
- [Settlement & XvP](#settlement--xvp): 12 errors.
- [Airdrop & distribution](#airdrop--distribution): 32 errors.
- [System & infrastructure](#system--infrastructure): 519 errors.
- [Internal (OpenZeppelin / low-level)](#internal-openzeppelin--low-level): 109 errors.
- [Chain & workflow](#chain--workflow): 5 errors.

## Compliance & token operations [#compliance--token-operations]

The 137 errors in this group are on these pages:

- [DALP-1000 to DALP-1049](https://docs.settlemint.com/docs/api-reference/errors/error-code-reference/dalp-1000-1049): 49 errors.
- [DALP-1050 to DALP-1099](https://docs.settlemint.com/docs/api-reference/errors/error-code-reference/dalp-1050-1099): 50 errors.
- [DALP-1100 to DALP-1199](https://docs.settlemint.com/docs/api-reference/errors/error-code-reference/dalp-1100-1199): 38 errors.

## Settlement & XvP [#settlement--xvp]

The 12 errors in this group are on this page:

- [DALP-2000 to DALP-2999](https://docs.settlemint.com/docs/api-reference/errors/error-code-reference/dalp-2000-2999): 12 errors.

## Airdrop & distribution [#airdrop--distribution]

The 32 errors in this group are on this page:

- [DALP-3000 to DALP-3999](https://docs.settlemint.com/docs/api-reference/errors/error-code-reference/dalp-3000-3999): 32 errors.

## System & infrastructure [#system--infrastructure]

The 519 errors in this group are on these pages:

- [DALP-4000 to DALP-4049](https://docs.settlemint.com/docs/api-reference/errors/error-code-reference/dalp-4000-4049): 49 errors.
- [DALP-4050 to DALP-4099](https://docs.settlemint.com/docs/api-reference/errors/error-code-reference/dalp-4050-4099): 50 errors.
- [DALP-4100 to DALP-4149](https://docs.settlemint.com/docs/api-reference/errors/error-code-reference/dalp-4100-4149): 50 errors.
- [DALP-4150 to DALP-4199](https://docs.settlemint.com/docs/api-reference/errors/error-code-reference/dalp-4150-4199): 50 errors.
- [DALP-4200 to DALP-4249](https://docs.settlemint.com/docs/api-reference/errors/error-code-reference/dalp-4200-4249): 48 errors.
- [DALP-4250 to DALP-4299](https://docs.settlemint.com/docs/api-reference/errors/error-code-reference/dalp-4250-4299): 50 errors.
- [DALP-4300 to DALP-4399](https://docs.settlemint.com/docs/api-reference/errors/error-code-reference/dalp-4300-4399): 91 errors.
- [DALP-4400 to DALP-4499](https://docs.settlemint.com/docs/api-reference/errors/error-code-reference/dalp-4400-4499): 97 errors.
- [DALP-4500 to DALP-4999](https://docs.settlemint.com/docs/api-reference/errors/error-code-reference/dalp-4500-4999): 34 errors.

## Internal (OpenZeppelin / low-level) [#internal-openzeppelin--low-level]

The 109 errors in this group are on these pages:

- [DALP-9000 to DALP-9099](https://docs.settlemint.com/docs/api-reference/errors/error-code-reference/dalp-9000-9099): 70 errors.
- [DALP-9200 to DALP-9299](https://docs.settlemint.com/docs/api-reference/errors/error-code-reference/dalp-9200-9299): 28 errors.
- [DALP-9300 to DALP-9399](https://docs.settlemint.com/docs/api-reference/errors/error-code-reference/dalp-9300-9399): 9 errors.
- [DALP-9500 to DALP-9999](https://docs.settlemint.com/docs/api-reference/errors/error-code-reference/dalp-9500-9999): 2 errors.

## Chain & workflow [#chain--workflow]

The 5 errors in this group are on this page:

- [Codes without a number](https://docs.settlemint.com/docs/api-reference/errors/error-code-reference/unnumbered-codes): 5 errors.


# Codes without a number

Source: https://docs.settlemint.com/docs/api-reference/errors/error-code-reference/unnumbered-codes
Cause, fix and retry flag for every on-chain contract error without a numeric code.

This page lists the 5 errors in the contract error reference whose code is a name, not a number. Match the error's `id`, or its `dalpCode` on a contract error or a failed deployment step, for example `DALP-WORKFLOW-FAILED`, to the DALP Code column, then read Retryable and Suggested Fix. The [contract error reference](https://docs.settlemint.com/docs/api-reference/errors/error-code-reference#how-to-use-this-reference) explains each column, including Severity, and the [DALP error index](https://docs.settlemint.com/docs/api-reference/errors) lists the page for every code range.

| DALP Code | Message | Why | Suggested Fix | Severity | Retryable | Solidity Error |
| --- | --- | --- | --- | --- | --- | --- |
| DALP-CHAIN-EMPTY-REVERT | The blockchain rejected this transaction with no reason code. | The transaction reverted without revert data, so DALP cannot name the check that failed. This happens when a contract calls an address with no contract code, or when an inner call runs out of gas. | Check that the system is fully deployed on this network and that the request targets the right contract. Share the `requestId` from the error with your administrator. | error | No | `EmptyRevert()` |
| DALP-EXT-TOKEN-NO-CODE | No contract exists at `{{tokenAddress}}` on this network. | The external token registry checks that the address provided for registration contains deployed bytecode. The address `{{tokenAddress}}` has no bytecode on this network, so the registry blocks registration before any interface detection can proceed. | Verify the address is correct, that you are connected to the right network, and that the token contract exists at that address before retrying. | error | No | `TokenAddressHasNoCode(address)` |
| DALP-TOKEN-DUPLICATE | Your organization already has an asset named `{{name}}` with symbol `{{symbol}}` and `{{decimals}}` decimals. | The token factory derives each asset's on-chain address from its name, symbol, and decimals, then rejects any deployment whose address already exists. This organization already deployed an asset with that exact combination, so the factory cannot create a second one at the same address. | Change the name, symbol, or number of decimals to a combination your organization does not already use, then create the asset again. | error | No | `DALPAssetAlreadyExists()` |
| DALP-WORKFLOW-FAILED | The deployment workflow failed before it could finish. | The deployment workflow stopped before it finished. Either a contract reverted with data the platform could not decode, or the failure matched no known type. | Retry the deployment. If the problem persists, share the correlation id with your administrator. | error | Yes | `WorkflowFailed()` |
| DALP-WORKFLOW-RPC-UNAVAILABLE | The blockchain RPC endpoint is temporarily unreachable and the deployment did not complete. | The deployment workflow could not complete a call to the blockchain node or a platform service. The cause is an HTTP error, a timeout, a socket error or a nonce conflict. | Check that the network's RPC endpoint is reachable and its node is healthy, then retry the deployment. If it keeps failing, share `data.correlationId` and the `requestId` from the error with your administrator. | error | Yes | `RpcUnavailable()` |

The previous page is [DALP-9500 to DALP-9999](https://docs.settlemint.com/docs/api-reference/errors/error-code-reference/dalp-9500-9999).


# Error handling

Source: https://docs.settlemint.com/docs/api-reference/errors/error-handling
Handle DALP API failures with stable error identifiers, retry decisions, and support-ready diagnostics.

A failed API call needs three decisions: whether the request can succeed after a change, whether an earlier write may still complete, and who on your side handles it. Read the stable error identifier, such as `DALP-12074`, and the `retryable` flag, then check the transaction state before you resubmit an uncertain write. This page applies those rules to authentication, validation, funding, custody, indexing, deployment and compliance failures, and sets the escalation order for a back office.

## Read the error contract [#read-the-error-contract]

Versioned REST routes return `code`, `status`, `message`, and a `data` object. The data carries the stable DALP identifier, reason, recovery step, retry flag, and category when the failure maps to the catalogue. See [Read and handle DALP errors](https://docs.settlemint.com/docs/api-reference/guides/errors) for the complete envelope and field table.

The SDK raises an API failure as `DalpApiError`, with the DALP identifier in `id` and the machine name in `code`. When `code` starts with `sdk.` or is `DALP_SDK_ERROR`, the SDK raised the error itself, after a network, configuration or response-format failure, or an answer the route does not publish. Read the API fields only on other codes. `waitForTransaction` raises its own `DalpTransactionWaitError`.

Transport framing differs. A JSON-RPC error keeps JSON-RPC framing. An SSE failure after the stream starts arrives as an event. Read the documented schema for that transport instead of assuming every failure is an HTTP JSON body.

Use these fields in order:

1. Identify the failure by its stable `data.id` or the SDK's `id`.
2. Read `retryable` and the recovery instructions before retrying.
3. Show `message`, `why`, and `fix` to the person who can resolve the condition.
4. Retain the request identifier when supplied, plus the affected resource and transaction-request identifier.

Do not parse human-readable messages for control flow. Look up the identifier in the [DALP error index](https://docs.settlemint.com/docs/api-reference/errors).

## Decide whether to retry [#decide-whether-to-retry]

[Figure] Three checks decide whether to retry a failed call. After a failed call, first ask whether the write outcome is uncertain. If it is, read the existing instruction state through its status URL before going on. Then check the retryable flag. If it is false, follow the recovery step and show message, why and fix to the person who can act. If it is true, check whether the required condition is resolved. If not, fund the wallet, get the approval or honour Retry-After first. Once it is resolved, retry with bounded backoff and keep the Idempotency-Key of the same instruction. Labels: YES; NO; NO; YES; NO; YES; Receive a failed call; Failure; Read data.id and retryable; 1. Is the write outcome uncertain?; A timeout or an unclear result; Read the instruction state; Follow its status URL first; 2. Is retryable true?; Read the code, not the HTTP status; Follow the recovery step; Show message, why and fix; 3. Is the condition resolved?; Funding, approval or Retry-After; Resolve the condition; Fund, approve or honour Retry-After; Retry with bounded backoff; Retry; Keep the Idempotency-Key; of the same instruction.

After a failed call, check the write outcome, then `retryable`, then the required condition, and retry only with bounded backoff.

When the outcome of a write is uncertain, such as after a timeout, read the existing instruction state through its status URL before you go on. When `retryable` is false, follow the recovery step and show `message`, `why` and `fix` to the person who can act on them. When it is true, first resolve the required condition: fund the wallet, get the approval or honour `Retry-After`. Then retry with bounded backoff and keep the `Idempotency-Key` of the same instruction.

HTTP status alone does not decide retryability. Some `4xx` errors become recoverable after funding or approval. An unknown `500` does not prove a retry is safe. Follow the code's retry flag and recovery step.

On an error the SDK raised itself, `retryable` is the SDK's own estimate: it is `true` after a network failure, an unreadable response, a failed stream or a `5xx` without a DALP body. Read the state of a write before you retry it after one of these.

For a retryable failure, use a bounded backoff policy with jitter and honour `Retry-After` when supplied. For example, your integration can wait 1, 2, and 4 seconds plus jitter, then stop and report the unresolved failure. This is an example client policy, not a platform guarantee.

A request timeout does not cancel a transaction. Keep its original `Idempotency-Key`, follow its returned status URL, and record any transaction hashes. Create a new instruction with a new key only after confirming the earlier outcome and deciding a separate write is required. [Idempotency and async settlement](https://docs.settlemint.com/docs/api-reference/guides/idempotency-async-settlement) defines the 24-hour window and the wallet-selection rule.

## Authentication, permissions, and validation [#authentication-permissions-and-validation]

An authentication rejection means the credential is absent, invalid, expired or disabled, or the session lacks a required step such as two-factor authentication or a step-up challenge. Read the code. Confirm the `X-Api-Key` header and key record. An organisation-scoped key also needs the organisation context stored with it. See [Authentication and API keys](https://docs.settlemint.com/docs/api-reference/guides/authentication-api-keys).

A permission rejection means the authenticated caller lacks access to the operation or resource. Check the current organisation, participant context, and required roles. Repeating the request with the same permissions does not resolve it.

For a validation rejection, inspect the route's documented error data and correct the named fields. A missing resource or state conflict requires a current read: verify the identifier, selected organisation, and whether another operation changed the resource.

## Pending work and idempotency conflicts [#pending-work-and-idempotency-conflicts]

`202 Accepted` is a normal pending result for a transaction-writing route. Poll the returned status URL or follow its documented stream. An instruction waiting for custody approval is still pending. Submitting another instruction can duplicate the intended action. A change held for a second user's approval also answers `202`, and the SDK raises it as `sdk.transport.APPROVAL_HELD` with `retryable: false`. Do not repeat that request: read the approval at the status URL it names.

An idempotency conflict means the key now names a different write. The target contract, call data or value changed, which covers a changed recipient or amount. Or the wallet selection changed, or the key's 24-hour window closed. Read the exact code. Keep the original key and instruction details while you investigate.

For a `FAILED` or `DEAD_LETTER` instruction, read the transaction request before any recovery. A `DEAD_LETTER` call that was broadcast or filed with a custody provider can still land on the chain. Reusing the original key does not requeue a failed instruction. When it failed before anything was signed, a matching resubmission under the same key starts a new request, and the failed one keeps its own id. Otherwise the replay returns the recorded failure, such as `TRANSACTION_QUEUE_DUPLICATE_SETTLED` or `TRANSACTION_QUEUE_DEAD_LETTER`. Read the transaction request, and send a new key only when it shows `FAILED` or `CANCELLED`, or `DEAD_LETTER` with `mayStillLand: false`.

An authorised operator can force a retry of a failed request. When the chain does not show the original call, the operator states that the call was stopped, for a custody call after checking with the provider. The platform does not verify that statement, and it records the operator and the reason with the retry.

## Funding and custody failures [#funding-and-custody-failures]

For `GAS_REQUIRED`, inspect the network and wallet named by `data.chainId` and `data.address`. Amounts such as `shortfallWei` and `recommendedTotalWei` are integer strings in the network's gas-token base units. Verify the destination and current fee conditions before funding it, then inspect the original instruction before resubmitting. [Gas sponsorship](https://docs.settlemint.com/docs/concepts/custody-and-signing/gas-sponsorship) explains which wallet pays on each network and how a funding pause resolves.

A token role change, or a token or token-feature write that sends its transaction directly, answers `400` with `TRANSACTION_QUEUE_FUNDING_REQUIRED` when the call waits for the result and the platform refused it for gas. `data.refusal` is `FundingRequired`, and `data.transactionId` names the transaction request when the platform recorded one. That request keeps the `GAS_REQUIRED` detail, so read it to find the wallet and the shortfall before you fund it.

A token role change from an EOA executor wallet answers this way whether the first call or a later one was refused, as long as the platform undid every earlier call. When it could not undo one of them, it answers `422` with `TOKEN_WORKFLOW_FAILED` and no `data.refusal`, and you should read the held roles before another write.

A coordinated distribution's preview, abort and leg release, and the confirm of a corporate action that issues or burns units for each holder when its first batch stops before anything is sent, answer the same way when a step stops for gas. The corporate action keeps its progress, so fund the wallet and send the same step again. Send that confirm with a new `Idempotency-Key`, because the refused batch stays recorded under the first key.

A token creation and a token price update answer the same way when the call waits for the result. A price write that the queue accepted, and whose funding window then closed while the call waited, answers `503` with `TOKEN_WRITE_PERSISTENCE_FAILED` instead. That holds for a price update and for the initial price of a token creation. A retry that sends the same `Idempotency-Key` answers `TRANSACTION_QUEUE_DUPLICATE_SETTLED`, so fund the paying account and send the call again under a new key. A token creation refused after its token was deployed answers `500` with `TOKEN_CREATE_WORKFLOW_FAILED`. That answer says the token can exist, so check for it before you create it again. Its `data.step` names the failed step and `data.reason` the kind of failure. When the initial price could not be published (`data.step` is `TOKEN_CREATE_STEP_PRICE_FEED_PUBLISH`), `data.reason` is `price-feed-not-authorized` when the token's price feed does not trust the organisation's feed signer, `price-feed-conflict` when a feed already holds the token's price topic or a newer answer, and `price-feed-unavailable` when the feed, the feed directory or the feeds add-on could not serve the write. Any step whose payload the organisation's custody signer could not sign answers `signing-failed`.

A Luna HSM signing request fails when the required partition approval does not arrive inside the signing window. Ask the HSM operator to activate the partition before retrying. When the observed partition state and the signing result disagree, the instruction also fails. Inspect the HSM state and retain the request identifier for support.

Other providers have their own policy and availability failures. The [Platform API error reference](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference) gives per-code recovery steps.

## Indexing and deployment failures [#indexing-and-deployment-failures]

Onboarding deployment routes can reject with [DALP-12331](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference/dalp-12300-12399), machine name `platform.http.REINDEXING`, when a request opts into `Prefer: dalp-fail-on-indexer-reindexing`. The response includes `Retry-After` and `data.retryAfterSeconds`. Wait for the indicated interval before retrying, with a bounded client deadline.

A write can answer `504` with `INDEXER_BARRIER_TIMEOUT`, id `DALP-12074`. The transaction succeeded on chain, but its block was not indexed before the request deadline. `retryable` is `false`, because the write has already happened and must not be sent again. Read the transaction request with `data.transactionId`, then repeat the read that needs the indexed result. If the index stays behind, ask the platform operator to inspect indexing for `data.chainId` at or before `data.blockNumber`.

A deployment can fail after acceptance. Read the structured failed-step data in the status response or the deployment stream. Known contract and workflow failures can carry `dalpCode`, `retryable`, `selector`, `solidityError` and a correlation identifier. Preserve those fields, because a generic display message is not enough to diagnose which step failed.

## Compliance failures [#compliance-failures]

A failed mint or transfer can carry `data.args.reason` with one of these values:

| Reason | Meaning | Recovery |
| --- | --- | --- |
| `identity-not-registered` | The wallet is absent from the token's identity registry. | Register the correct identity before retrying. |
| `identity-not-verified` | Required claims are missing, revoked, or expired. | Resolve the claim requirements with a trusted issuer. |
| `module-blocked` | A compliance module refused the operation. | Review the active policy and the reported module detail. |
| `stale-price` | A required price is older than the allowed window. | Restore a current observation and repeat the check. |
| `classification-unavailable` | DALP could not read the token's trusted issuer registries to classify the refusal. | Branch on the error id and read the general refusal. |

Classification is best effort. Branch first on the stable error identifier, then use `args` when present. An absent classification is a supported response, not a decoding failure.

Detailed transfer and mint diagnostics need the executing wallet to hold the System manager, Identity manager or Verification issuer role, and mint diagnostics also accept the Supply management role. A caller without one receives the general refusal. Forced-transfer classification is narrower and can report an unregistered identity while other failures retain the general message. These restrictions prevent errors from disclosing another participant's compliance state.

Two kinds of write do not meet every compliance module. A custodian's forced transfer and a lost-wallet recovery skip the compliance modules and run while the token is paused. A transfer to an address on the compliance bypass list skips the rules that judge the recipient, including transfer approval. DALP manages that list: the token and add-on factories add the contracts they deploy, and no Console screen or Platform API route edits it directly. [Who manages the compliance bypass list](https://docs.settlemint.com/docs/concepts/compliance-and-identity/compliance-policy#who-manages-the-compliance-bypass-list-and-how-does-an-address-end-up-on-it) says who can still change it. [Roles and segregation of duties](https://docs.settlemint.com/docs/concepts/compliance-and-identity/roles-and-segregation-of-duties) lists who holds each power.

## Criticality and escalation [#criticality-and-escalation]

Every code in the [Platform API error reference](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference) and the [Contract error reference](https://docs.settlemint.com/docs/api-reference/errors/error-code-reference) carries a Severity value. Severity is metadata that the error registry holds for the code. It is a default for your own alerting, not a service-level commitment. The platform logs each error response at that level, but the response does not carry it, so look it up by the stable `data.id`. When an asynchronous deployment or workflow failure has no `data.id`, look up its `dalpCode` instead and read the matching reference row. The row's suggested fix is the authority for what to do. The severity table sets the default only when the fix does not say.

| Severity | What it means | Who handles it | Escalate to support when |
| --- | --- | --- | --- |
| `info` | An expected rejection a caller triggers in normal use, such as a validation failure, a missing API permission or a route-level compliance check. | The calling application or the operator who submitted the request. Count it. Do not page anyone. | Never on a single occurrence. Open a ticket only when the rate rises with no change on your side. |
| `warning` | A recoverable or state-based refusal: a transient condition (confirmation timeout, request deadline, incomplete indexed data) or a state that blocks the action (paused contract or token, already approved or claimed). | Your integration. Retry only when the retry flag is true. Otherwise wait for the state to change. | A retryable code persists after bounded retries, or the affected instruction never reaches a terminal state. |
| `error` | A failure that stops the operation until something changes: a dependency fault, an on-chain revert (including a compliance or role revert) or an operational fault. | A person on your side who can act on the suggested fix. | The suggested fix tells you to contact support, or the failure persists after you apply it. A `dependency`, `operational` or `unknown` failure that persists goes to support. |
| `fatal` | Reserved for a failure that leaves the platform unable to serve requests. No catalogued code uses it. | Treat as an incident: page your on-call owner. | Immediately. |

Escalation order for a back office:

1. Match the `data.id` (or `dalpCode`) to its reference row, read its Severity, then follow the step in `data.fix`. Read the retry flag from `data.retryable`. A failed deployment or workflow step carries `retryable` directly on its error object instead.
2. For a `warning`, retry with the bounded policy only when the retry flag is true, and check the instruction state before any resubmission.
3. For an `error`, change the request, credentials, permissions, or asset state the suggested fix names. Escalate when the fix says to contact support or does not resolve the failure.
4. When the severity table sends the failure to support, open a ticket with the [instruction record](#escalate-with-the-instruction-record). On an instance your organisation operates, your platform operator handles `dependency` and `operational` failures first.

Do not resubmit an uncertain write while you wait for support. Read the original instruction's state instead.

### Escalate with the instruction record [#escalate-with-the-instruction-record]

Include the public error code, request identifier when supplied, route, timestamp in UTC, affected resource, idempotency key, and transaction status URL. Add the custody approval reference when relevant. Keep credentials, signing secrets, raw provider responses, and identity documents out of the support note.

## Next steps [#next-steps]

- [Platform API error reference](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference) and [Contract error reference](https://docs.settlemint.com/docs/api-reference/errors/error-code-reference) for every error id.
- [Read and handle DALP errors](https://docs.settlemint.com/docs/api-reference/guides/errors) for the REST envelope.
- [Idempotency and async settlement](https://docs.settlemint.com/docs/api-reference/guides/idempotency-async-settlement) for retry identity and pending writes.
- [Webhook outcomes](https://docs.settlemint.com/docs/api-reference/webhooks/consuming#outcome-model) for event finality and later retractions.


# Error index

Source: https://docs.settlemint.com/docs/api-reference/errors
Find the reference page for any DALP error id by its code range, then read its cause, its fix and its retry flag.

Find the range that holds the `id` in your error, such as `DALP-12074`, and open that page for the cause, suggested fix, severity and retry flag. The `id` is in `data.id` of the error envelope, and in `id` of an SDK `DalpApiError`. The `code` field, such as `INDEXER_BARRIER_TIMEOUT`, holds the machine name, which the Platform API pages list in their Machine name column. A code that is a name rather than a number, such as `DALP-WORKFLOW-FAILED`, is on [Codes without a number](https://docs.settlemint.com/docs/api-reference/errors/error-code-reference/unnumbered-codes). An error the SDK raises itself, such as `sdk.transport.REQUEST_FAILED`, has no `DALP-` id and is not listed here.

Each code is on exactly one page. These ranges have a page in both references, and each of those pages holds different codes: DALP-9000 to DALP-9099, DALP-9200 to DALP-9299, DALP-9300 to DALP-9399, DALP-9500 to DALP-9999. For a code in one of them, search both pages.

## Find the page for your error [#find-the-page-for-your-error]

| You have | Read |
| --- | --- |
| A smart contract revert | [Contract error reference](https://docs.settlemint.com/docs/api-reference/errors/error-code-reference) |
| Any other DALP error | [Platform API error reference](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference) |
| A question about retry policy or idempotency | [Error handling](https://docs.settlemint.com/docs/api-reference/errors/error-handling) |
| A question about the error envelope and its fields | [Read and handle DALP errors](https://docs.settlemint.com/docs/api-reference/guides/errors) |

Branch your integration on the `id`, the `category` and the `retryable` flag in the error envelope, never on the message text. `retryable: true`, shown as `Yes` in the Retryable column, means the same request can succeed later without a change to the request. `retryable: false` means sending it again does not succeed until you act on the suggested fix. [Error handling](https://docs.settlemint.com/docs/api-reference/errors/error-handling) sets the retry policy.

## Platform API errors [#platform-api-errors]

The [Platform API error reference](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference) covers the 1,138 errors the Platform API routes return, on these pages:

- [DALP-0000 to DALP-0499](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference/dalp-0000-0499): 100 errors.
- [DALP-0500 to DALP-0599](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference/dalp-0500-0599): 27 errors.
- [DALP-0600 to DALP-0699](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference/dalp-0600-0699): 36 errors.
- [DALP-0700 to DALP-0799](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference/dalp-0700-0799): 38 errors.
- [DALP-9000 to DALP-9099](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference/dalp-9000-9099): 16 errors.
- [DALP-9100 to DALP-9199](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference/dalp-9100-9199): 22 errors.
- [DALP-9200 to DALP-9299](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference/dalp-9200-9299): 22 errors.
- [DALP-9300 to DALP-9399](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference/dalp-9300-9399): 19 errors.
- [DALP-9400 to DALP-9499](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference/dalp-9400-9499): 48 errors.
- [DALP-9500 to DALP-9999](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference/dalp-9500-9999): 56 errors.
- [DALP-12000 to DALP-12099](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference/dalp-12000-12099): 69 errors.
- [DALP-12100 to DALP-12199](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference/dalp-12100-12199): 51 errors.
- [DALP-12200 to DALP-12299](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference/dalp-12200-12299): 52 errors.
- [DALP-12300 to DALP-12399](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference/dalp-12300-12399): 78 errors.
- [DALP-12400 to DALP-12499](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference/dalp-12400-12499): 14 errors.
- [DALP-13000 to DALP-13999](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference/dalp-13000-13999): 2 errors.
- [DALP-14000 to DALP-14049](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference/dalp-14000-14049): 48 errors.
- [DALP-14050 to DALP-14099](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference/dalp-14050-14099): 50 errors.
- [DALP-14100 to DALP-14199](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference/dalp-14100-14199): 41 errors.
- [DALP-14200 to DALP-14299](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference/dalp-14200-14299): 64 errors.
- [DALP-14300 to DALP-14399](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference/dalp-14300-14399): 97 errors.
- [DALP-14400 to DALP-14499](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference/dalp-14400-14499): 36 errors.
- [DALP-14500 to DALP-14999](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference/dalp-14500-14999): 54 errors.
- [DALP-15000 to DALP-19999](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference/dalp-15000-19999): 18 errors.
- [DALP-20000 to DALP-29999](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference/dalp-20000-29999): 13 errors.
- [DALP-100000 to DALP-199999](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference/dalp-100000-199999): 58 errors.
- [DALP-200000 to DALP-299999](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference/dalp-200000-299999): 9 errors.

## Contract errors [#contract-errors]

The [contract error reference](https://docs.settlemint.com/docs/api-reference/errors/error-code-reference) covers the 814 errors of DALP smart contracts and their deployment, on these pages:

- [DALP-1000 to DALP-1049](https://docs.settlemint.com/docs/api-reference/errors/error-code-reference/dalp-1000-1049): 49 errors.
- [DALP-1050 to DALP-1099](https://docs.settlemint.com/docs/api-reference/errors/error-code-reference/dalp-1050-1099): 50 errors.
- [DALP-1100 to DALP-1199](https://docs.settlemint.com/docs/api-reference/errors/error-code-reference/dalp-1100-1199): 38 errors.
- [DALP-2000 to DALP-2999](https://docs.settlemint.com/docs/api-reference/errors/error-code-reference/dalp-2000-2999): 12 errors.
- [DALP-3000 to DALP-3999](https://docs.settlemint.com/docs/api-reference/errors/error-code-reference/dalp-3000-3999): 32 errors.
- [DALP-4000 to DALP-4049](https://docs.settlemint.com/docs/api-reference/errors/error-code-reference/dalp-4000-4049): 49 errors.
- [DALP-4050 to DALP-4099](https://docs.settlemint.com/docs/api-reference/errors/error-code-reference/dalp-4050-4099): 50 errors.
- [DALP-4100 to DALP-4149](https://docs.settlemint.com/docs/api-reference/errors/error-code-reference/dalp-4100-4149): 50 errors.
- [DALP-4150 to DALP-4199](https://docs.settlemint.com/docs/api-reference/errors/error-code-reference/dalp-4150-4199): 50 errors.
- [DALP-4200 to DALP-4249](https://docs.settlemint.com/docs/api-reference/errors/error-code-reference/dalp-4200-4249): 48 errors.
- [DALP-4250 to DALP-4299](https://docs.settlemint.com/docs/api-reference/errors/error-code-reference/dalp-4250-4299): 50 errors.
- [DALP-4300 to DALP-4399](https://docs.settlemint.com/docs/api-reference/errors/error-code-reference/dalp-4300-4399): 91 errors.
- [DALP-4400 to DALP-4499](https://docs.settlemint.com/docs/api-reference/errors/error-code-reference/dalp-4400-4499): 97 errors.
- [DALP-4500 to DALP-4999](https://docs.settlemint.com/docs/api-reference/errors/error-code-reference/dalp-4500-4999): 34 errors.
- [DALP-9000 to DALP-9099](https://docs.settlemint.com/docs/api-reference/errors/error-code-reference/dalp-9000-9099): 70 errors.
- [DALP-9200 to DALP-9299](https://docs.settlemint.com/docs/api-reference/errors/error-code-reference/dalp-9200-9299): 28 errors.
- [DALP-9300 to DALP-9399](https://docs.settlemint.com/docs/api-reference/errors/error-code-reference/dalp-9300-9399): 9 errors.
- [DALP-9500 to DALP-9999](https://docs.settlemint.com/docs/api-reference/errors/error-code-reference/dalp-9500-9999): 2 errors.
- [Codes without a number](https://docs.settlemint.com/docs/api-reference/errors/error-code-reference/unnumbered-codes): 5 errors.

For retry policy, severity and escalation, read [Error handling](https://docs.settlemint.com/docs/api-reference/errors/error-handling).


# DALP-0000 to DALP-0499

Source: https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference/dalp-0000-0499
Cause, fix, HTTP status and retry flag for every Platform API error with a code from DALP-0000 to DALP-0499.

This page lists the 100 errors the Platform API can return with a code from DALP-0000 to DALP-0499. Match the `id` in the error envelope to the DALP Code column, then read Retryable and Suggested Fix. The [Platform API error reference](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference#how-to-use-this-reference) explains each column, including Severity, and the [DALP error index](https://docs.settlemint.com/docs/api-reference/errors) lists the page for every code range.

| DALP Code | Machine name | Category | Message | Why | Suggested Fix | Severity | Retryable | HTTP Status |
| --- | --- | --- | --- | --- | --- | --- | --- | --- |
| DALP-0001 | `BAD_REQUEST` | client | The request could not be read. | A check on this route refused the request as invalid, and no more specific error code covers that check. | Check the field names, types, and content type against the route schema, then send the request again. | info | No | 400 |
| DALP-0002 | `UNAUTHORIZED` | auth | Authentication missing or failed. | The request did not include valid authentication credentials. | Authenticate again or send a valid API key/session credential. | info | No | 401 |
| DALP-0003 | `FORBIDDEN` | permission | This operation is not available to the caller. | The route runs behind an access gate that the caller does not satisfy. When `data.requiredRoles` is present, it lists the roles that pass the gate and the wallet that authorized this request holds none of them. When it is absent, the gate is an off-chain permission or an ownership scope the caller sits outside. | Retry with an actor that already holds one of the roles in `data.requiredRoles`, or ask an administrator to grant one of them. When the record is the caller's own, confirm the request names that record on the network where the caller's account lives. | info | No | 403 |
| DALP-0004 | `NOT_ONBOARDED` | auth | User not onboarded. | The authenticated user has not completed onboarding required for this operation. | Complete onboarding and retry the request. | info | No | 403 |
| DALP-0005 | `USER_MISSING_2FA` | auth | Two-factor authentication required. | The operation requires wallet-signing protection that is not configured for this user. | Set up PIN or two-factor authentication and retry. | info | No | 401 |
| DALP-0006 | `USER_NOT_AUTHORIZED` | permission | This action requires a role the acting wallet does not hold. | The token or system contract restricts this action to the `{{requiredRoles}}` role, and the acting wallet was granted no matching role. | Ask an administrator to grant the `{{requiredRoles}}` role, then retry, or perform this action with a wallet that already holds it. | info | No | 403 |
| DALP-0009 | `SESSION_RESOLUTION_FAILED` | dependency | Session resolution failed. | Platform API could not resolve the authenticated session from the request headers. | Retry with a fresh session or API key. If the problem continues, contact support with the request id. | error | Yes | 503 |
| DALP-0012 | `TRANSACTION_PROVIDER_READ_FAILED` | dependency | Transaction provider read failed. | The configured chain RPC provider could not read transaction state for this request. | Retry after a short backoff. If the problem continues, contact support with the request id. | error | Yes | 503 |
| DALP-0020 | `DEPLOYMENT_STREAM_POLLING_FAILED` | dependency | Deployment stream polling failed. | The deployment event stream could not read the latest workflow status from the Workflow Engine. | Reconnect to the stream or poll deployment status after a short backoff. If it continues, contact support with the request id. | error | Yes | 503 |
| DALP-0021 | `DEPLOYMENT_WORKFLOW_TERMINAL_FAILED` | operational | Deployment workflow reported a terminal failure. | The deployment workflow ended with a Workflow Engine terminal error before the stream could read a typed failed workflow tree. | Open the deployment details or retry only after correcting the workflow failure. Include the request id when contacting support. | error | No | 503 |
| DALP-0022 | `NOT_FOUND` | client | Resource not found. | The requested resource could not be found. | Check the identifier and retry only if the resource should exist. | info | No | 404 |
| DALP-0023 | `RESOURCE_ALREADY_EXISTS` | client | Resource already exists. | The request tried to create or register a resource that already exists. | Use the existing resource or choose a unique identifier. | info | No | 409 |
| DALP-0024 | `CONFLICT` | client | The change conflicts with the current resource state. | Another write already changed this resource, or the resource is already in the requested state. | Read the current resource, resolve the difference, and send the request again. | info | No | 409 |
| DALP-0025 | `TOKEN_INTERFACE_NOT_SUPPORTED` | domain | The token contract at the provided address lacks the required interface. | The target token does not expose the interface required for this operation. | Use a compatible token contract or enable the required interface before retrying. | info | No | 422 |
| DALP-0026 | `SYSTEM_NOT_CREATED` | domain | System not created. | The DALP system bootstrap has not completed for this environment or organization. | Create or finish deploying the system before calling this operation. | warning | No | 403 |
| DALP-0031 | `CONFIRMATION_TIMEOUT` | operational | Transaction confirmation timeout. | The transaction was submitted but confirmation did not arrive before the timeout. | Check transaction status using the transaction hash and retry only if it was not confirmed. | warning | Yes | 504 |
| DALP-0032 | `ADMIN_ACCESS_REQUIRED` | permission | Insufficient role for this operation. | The operation requires elevated permissions and the authenticated actor does not hold the role required for this route. | Retry with an account that has the role required by this route, or check the route documentation for the required role. | info | No | 403 |
| DALP-0034 | `ACTIVE_ORGANIZATION_REQUIRED` | permission | Active organization required for this operation. | The request requires organization-scoped permissions, but the session does not have an active organization selected. | Select an organization, refresh the session, and retry the request. | info | No | 403 |
| DALP-0036 | `SESSION_POLICY_DENIED` | auth | This authentication method or API key scope is not permitted for this request. | The presented authentication method or API-key scope is not permitted for this request. | Use a permitted session or an API key with the required scope. | info | No | 403 |
| DALP-0045 | `REINDEX_SERVICE_UNREACHABLE` | dependency | Ledger Data reindex admin is unreachable. | The platform could not contact the Ledger Data service that starts blockchain reindex jobs. | Retry after a short backoff. If the problem continues, contact support with the request id. | error | Yes | 503 |
| DALP-0046 | `REINDEX_REQUEST_INVALID` | client | Reindex request wasn't accepted. | The Ledger Data reindex admin rejected the range, target or mode of this reindex request, or the network catalogue has no single enabled entry for the requested chain. | Adjust the reindex request to a supported chain, range, and mode before retrying. | info | No | 400 |
| DALP-0048 | `API_MONITORING_LOG_ENTRY_NOT_FOUND` | client | API monitoring log entry was not found. | No API monitoring log entry exists for the requested id in the active organization. | Verify the log entry id and organization, then retry. | info | No | 404 |
| DALP-0054 | `DEPLOYMENT_NOT_FOUND` | client | Deployment not found. | The requested deployment id is malformed, stale, or does not belong to a deployment the caller may observe. | Refresh deployment state and subscribe using the current deployment id. | info | No | 404 |
| DALP-0061 | `XVP_HASHLOCK_INVALID` | client | XvP hashlock must be a 0x-prefixed hex string. | A cross-chain XvP settlement was created with a hashlock that is not valid hex. | Send a 0x-prefixed hashlock or provide the secret so the API can derive it. | info | No | 400 |
| DALP-0070 | `XVP_APPROVAL_NOT_FOUND` | client | XvP approval was not found. | The caller has not approved the requested XvP settlement or the approval is not indexed. | Approve the settlement first or retry after indexing catches up. | info | No | 404 |
| DALP-0076 | `FIXED_YIELD_DENOMINATION_ASSET_NOT_INDEXED` | dependency | Denomination asset pending indexing. | The fixed-yield operation needs the denomination asset row, but the indexer has not exposed it yet. | Retry after indexing catches up. | error | Yes | 503 |
| DALP-0080 | `INPUT_VALIDATION_FAILED` | client | Input validation failed. | The request body or parameters did not match the API contract. | Check the request fields against the API documentation and retry with valid values. | info | No | 422 |
| DALP-0082 | `SERVICE_UNAVAILABLE` | dependency | Service temporarily unavailable. | A required backend service is temporarily unavailable. | Retry after a short backoff. If the problem continues, contact support with the request id. | error | Yes | 503 |
| DALP-0083 | n/a | dependency | Indexer data temporarily incomplete. | Platform API is reading from an indexer schema that is still rolling out or reindexing. | Retry after the indexer rollout completes. If the problem continues, contact support with the request id. | warning | Yes | 503 |
| DALP-0084 | `INTERNAL_SERVER_ERROR` | unknown | The platform could not complete this request. | An unexpected failure occurred after the request passed validation. | Read the state the request would change before you send it again. If the failure continues, contact support with the X-Request-Id response header. | error | No | 500 |
| DALP-0091 | `ASSET_TYPE_TEMPLATE_NOT_FOUND` | client | Asset type template not found. | No asset type template with this id is visible to your organisation, or the template is a draft or hidden from issuance. | Confirm the ID matches an existing template owned by your organization or a published system template. Re-fetch the list of asset type templates to verify the ID before retrying. | info | No | 404 |
| DALP-0115 | `TOKEN_ACCESS_SYNC_RESULT_UNAVAILABLE` | dependency | The v1 token access change returned no synchronous result. | The frozen v1 mutation did not produce a synchronous result. | Retry with the same idempotency key or inspect the transaction request status. | error | Yes | 503 |
| DALP-0116 | `EXCHANGE_RATE_NOT_FOUND` | client | Exchange rate not found. | No active FX feed covers the requested currency pair on the current chain, or the feed exists but has not recorded an observed rate. | Check the supported currencies list to confirm the pair is available. If the pair was recently added, retry after the feed publishes its first observation. | info | No | 404 |
| DALP-0125 | `FEEDS_FEED_ADDRESS_NOT_FOUND` | client | Feed with address `{feedAddress}` not found. | The platform could not find a feed at the given address in the system index. The feed may not have been registered, or the indexer has not processed its registration event. | Confirm the feed address is correct and the feed has been registered in the system. If the feed was recently registered, wait for the indexer to catch up and retry. | info | No | 404 |
| DALP-0127 | `FEEDS_GET_FEEDSDIRECTORY_NOT_FOUND_BOOTSTRAPPED_V3_INDEXER_CAUGHT_UP` | client | FeedsDirectory not found for this system. | The platform found no `FeedsDirectory` address for this system in the index, or the request resolved no system. The system has not completed its V3 bootstrap, or the indexer has not processed the bootstrap event. | Complete the V3 bootstrap for the system and wait for the indexer to process the event before retrying. | info | No | 404 |
| DALP-0131 | `FEED_ROUND_NOT_FOUND` | domain | The feed round was not found. | Feed `{feedAddress}` has no readable round `{roundId}`. | Request an existing round from a feed whose history mode retains it. | info | No | 404 |
| DALP-0147 | `OFFCHAIN_ORGANIZATION_PERMISSION_REQUIRED` | permission | Your organisation role does not grant the permission this operation needs. | Your role in the active organisation does not grant the off-chain permission this route requires. | Ask an organisation owner for a role that grants the permission, then retry. | info | No | 403 |
| DALP-0148 | `OFFCHAIN_USER_PERMISSION_REQUIRED` | permission | The authenticated user does not have the required permission for this operation. | The permission check on the authenticated user failed. The user has not been granted the off-chain permission required by this route. | Ask an administrator to grant the required user-level permission, then retry. | info | No | 403 |
| DALP-0151 | `DURABLE_EXECUTION_ENGINE_CALL_FAILED` | dependency | The workflow engine call failed. | The workflow execution service could not reach its message store, had no runner free to accept the call, or was already handling this exact request. | Retry the request. If the problem persists, contact support with the request ID. | error | Yes | 503 |
| DALP-0175 | `SETTINGS_THEME_PAYLOAD_EXCEEDS_SUPPORTED_LIMITS` | client | Theme payload exceeds supported limits. | One or more fields in the submitted theme configuration exceed the platform's size or structural constraints. This is checked before any data is stored. | Keep the theme within its limits: at most 32 KiB for the whole payload, exactly the required token set in light and dark, at most 500 KiB per embedded logo and at most 5 MiB for an uploaded logo file. Then send it again. | info | No | 400 |
| DALP-0227 | `SYSTEM_ADDON_FACTORY_NOT_FOUND_INDEXER` | client | Addon factory `{factoryAddress}` was not found in the indexer. | Coupon operations run on the token's `fixed-treasury-yield` feature, and none is attached to this token. | Attach the `fixed-treasury-yield` feature to the token, then send the request again. | info | No | 404 |
| DALP-0242 | `SYSTEM_CLAIM_TOPIC_NOT_FOUND` | client | Topic "`{topicId}`" not found. | The current organization's topic scheme registry has no topic registered under the name `{topicId}` on the selected chain. | Verify the topic name, organization, and chain. Create the topic in this organization's topic scheme registry if it is missing. | info | No | 404 |
| DALP-0247 | `SYSTEM_COMPLIANCE_MODULE_NOT_REGISTERED_REGISTRY` | client | The compliance module is not registered. | The active system has no compliance module registry, the registry holds no entry for this module, the chain's directory has no implementation of the requested module type, or the token has no indexed identity registry. | Confirm the module address is correct and that it appears in the system's compliance module registry before calling this operation. | info | No | 404 |
| DALP-0254 | `SYSTEM_IDENTITY_CLAIM_ISSUE` | client | Claim issue failed. | The platform validated the claim topic and data but the claim value failed an auto-claim business rule check specific to the topic type. For example, a boolean auto-claim topic rejected the supplied value. | Review the claim data for the topic named in the request and correct the value to satisfy the topic's validation rules before retrying. | info | No | 422 |
| DALP-0262 | `SYSTEM_IDENTITY_MULTIPLE_ACTIVE_CLAIMS_FOUND_TOPIC` | operational | Multiple active claims found for topic `{topicId}` on identity `{identityAddress}`. | The platform found more than one active, non-revoked claim for the same topic on this identity contract. Each topic should have at most one active claim, so this state indicates a data integrity issue the platform cannot resolve automatically. | Contact support with the request id and the identity address. The platform team will audit the duplicate claims and restore the expected single-claim state for this topic. | error | No | 500 |
| DALP-0272 | `SYSTEM_IDENTITY_TOPIC_NOT_REGISTERED_SCHEME_REGISTRY` | client | Topic `{topicId}` is not registered in the topic scheme registry. | The platform searched the registered topic schemes for the requested topic name and found no match. The topic may not exist in this system's claim-topics configuration. | Retrieve the list of registered claim topics via the claim-topics endpoint and use a topic name from that list. | info | No | 404 |
| DALP-0279 | `SYSTEM_NOT_FOUND` | client | System not found. | The platform resolved the requested system address but found no matching system record in the indexer, and the address does not match this organization's configured system. The system address may be incorrect or belong to a different organization. | Confirm the system address is correct and belongs to your organization. Use the system read endpoint with `default` to retrieve the active system address for your organization. | info | No | 404 |
| DALP-0283 | `SYSTEM_PAYMASTER_NOT_FOUND_ADDRESS_INDEXED_LIST_AVAILABLE_PAYMASTERS_VIA_GET` | client | Paymaster `{paymasterAddress}` not found. | The platform could not find a paymaster with the given address in the indexed state for this system. The address may be incorrect, or the paymaster may not have been indexed yet. | Confirm the paymaster address is correct and that the indexer has processed the registration transaction. Use GET /api/v2/system/paymasters to list all paymasters currently indexed for this system. | info | No | 404 |
| DALP-0284 | `SYSTEM_PAYMASTER_NOT_FOUND_ADDRESS_INDEXED_LIST_AVAILABLE_PAYMASTERS_VIA_GET_V2` | client | Paymaster `{systemAddress}` not found. | The platform could not find a paymaster with the given address in the indexed state for this system. The address may be incorrect, or the paymaster registration may not be indexed yet. | Confirm the paymaster address is correct and that the indexer has processed the registration transaction. Use GET /api/v2/system/paymasters to list all paymasters currently indexed for this system. | info | No | 404 |
| DALP-0285 | `SYSTEM_PAYMASTER_SPONSORSHIP_NOT_FOUND_ADDRESS` | client | Sponsorship paymaster not found with address `{paymasterAddress}`. | The address is not this organisation's active indexed paymaster on this network. | Use the paymaster address that GET /api/v2/system/paymasters returns for this network. | info | No | 404 |
| DALP-0294 | `SYSTEM_TRUSTED_ISSUER_NOT_FOUND` | client | Trusted issuer "`{issuerAddress}`" not found. | The platform searched the trusted-issuer registry (and its parent chain) in the indexer but found no entry for the given issuer address. The issuer may not have been registered, or the address may be incorrect. | Verify the issuer address is correct and that the issuer has been registered in the system's trusted-issuers registry. Use GET /api/v2/system/trusted-issuers to list registered issuers. | info | No | 404 |
| DALP-0314 | `TOKEN_CREATE_FACTORY_TYPE_NOT_FOUND` | client | Token factory for type `{factoryAddress}` not found. | The platform could not locate a registered token factory for the requested token type, so it cannot proceed with token deployment. | Verify that the token type and optional factory address are correct, and that the system has completed bootstrapping with a factory for that type. | info | No | 404 |
| DALP-0315 | `TOKEN_CREATE_WORKFLOW_PHASE_FAILED` | domain | Token creation workflow failed during phase execution. | The token deployment workflow failed in one of its phases. | Inspect the phase failure, correct the deployment inputs, and submit a new operation. | info | No | 422 |
| DALP-0316 | `TOKEN_CREATE_TEMPLATEID_REQUIRED_DALP_ASSET_CREATION_SELECT_INSTRUMENT_TEMPLATE_CREATING` | client | Token creation needs a `templateId`. | DALP asset creation requires an instrument template identifier. | Select an instrument template and retry the request. | info | No | 422 |
| DALP-0318 | `TOKEN_CREATE_USER_ADDRESS_DOES_NOT_ASSOCIATED_IDENTITY_CONTRACT` | domain | The user address has no associated identity contract. | The selected participant has no on-chain identity on the request chain. | Create or select a participant identity on the request chain, then retry. | info | No | 403 |
| DALP-0321 | `TOKEN_DOCUMENTS_DECLARED_FILE_SIZE_DOES_NOT_MATCH_ACTUAL_STORAGE` | client | Declared file size does not match actual file size in storage. | The stored object's byte length differs from the `fileSize` in the confirm-upload request. The platform removed the object from storage. | Re-upload the file and submit a confirm-upload request with the exact byte length of the file as reported by your file system. | info | No | 422 |
| DALP-0322 | `TOKEN_DOCUMENTS_DOCUMENT_GROUP_NOT_FOUND_REPLACEMENT` | client | Document group not found for replacement. | The `replaceGroupId` supplied in the request does not name a document group of the requested `documentType` on this token. A new version keeps the type of the group it replaces, so a group whose latest live document has another type is not found either. | List the token's current documents and resubmit with the `groupId` of a document of the same `documentType`, or omit `replaceGroupId` to start a new group. | info | No | 404 |
| DALP-0323 | `TOKEN_DOCUMENTS_DOCUMENT_NOT_FOUND` | client | Document not found. | The document ID matches no non-deleted document for this token. The document was deleted, or the ID belongs to a different token. | Verify the document ID against the token's active document list and resubmit with a valid ID. | info | No | 404 |
| DALP-0324 | `TOKEN_DOCUMENTS_DOCUMENT_TYPE_NOT_VALID_ASSET` | client | Document type `{value}` is not valid for asset type `{value}`. | The requested document type is not permitted for the token's asset type. Each asset type (for example, bond, equity) has a specific set of allowed document types. | Check the list of permitted document types for this token's asset type and resubmit with a compatible document type. | info | No | 400 |
| DALP-0325 | `TOKEN_DOCUMENTS_FAILED_TO_CREATE_DOCUMENT_RECORD` | operational | Failed to create document record. | The platform inserted the document metadata into the database but the insert returned no row, indicating a persistence failure. The orphaned object was removed from storage to avoid an inconsistent state. | Retry the confirm-upload request. If the error recurs, contact support with the request id and the object key. | error | No | 500 |
| DALP-0326 | `TOKEN_DOCUMENTS_FILE_NOT_FOUND_STORAGE_UPLOAD_FAILED` | client | File not found in storage. | No file exists at the expected storage location, so the pre-signed upload did not finish before the confirm step. | Re-upload the file using the pre-signed URL, confirm the upload completed successfully, then call the confirm step again. | info | No | 404 |
| DALP-0327 | `TOKEN_DOCUMENTS_INVALID_OBJECT_KEY` | client | Object key is outside the permitted path for this token. | The `objectKey` in the request does not start with the expected `token-documents/:tokenAddress/` prefix, or contains path traversal sequences (`..` or `//`). The platform rejects keys that fall outside the token's storage namespace. | Use the `objectKey` returned by the upload URL endpoint without modification. Do not alter the path prefix or add traversal sequences. | info | No | 400 |
| DALP-0328 | `TOKEN_LIST_FACTORY_NOT_FOUND` | client | Token factory not found in the active system. | The requested token factory is not registered in the active system. | Use a token factory returned for the active system. | info | No | 404 |
| DALP-0330 | `TOKEN_FEATURES_FIXED_TREASURY_YIELD_FEATURE_STATE_NOT_YET_INDEXED_INDEXER_PROCESSED_INITIA` | dependency | Fixed-treasury-yield feature state is not indexed for this token yet. | The index has no `fixed-treasury-yield` record (denomination asset and treasury address) for this token, or the record holds zero-address values. The index has not processed the feature initialisation event yet. | Retry after a short delay to allow the platform's index to process the feature initialization. If the error persists, contact support with the request ID. | error | Yes | 503 |
| DALP-0332 | `TOKEN_FEATURES_NO_YIELD_AVAILABLE_CLAIM_FIRST_PERIOD_NOT_COMPLETED_YET` | client | No yield is claimable until the first yield period completes. | The platform confirmed from indexed schedule data that fewer than one full interval has elapsed since the yield schedule's start date. No yield periods have completed, so there is nothing to claim. | Wait until at least one full yield interval has elapsed from the schedule start date, then retry the claim. | info | No | 400 |
| DALP-0333 | `TOKEN_FEATURES_UNAVAILABLE` | dependency | Token features for `{featureName}` are not available. | The platform could not read the feature state for this token from the chain or the index. The chain node or a downstream data source returned an error. | Retry after a short delay. If the error persists, contact support with the request ID. | error | Yes | 503 |
| DALP-0339 | `TOKEN_INDEXER_DATA_INVALID` | dependency | Indexed data validation failed. | A field in the indexed token or feature inventory does not match the expected format. | Do not retry the request. It fails the same way until the indexed data is repaired. Report the X-Request-Id response header to the platform operator. | error | No | 500 |
| DALP-0340 | `TOKEN_INDEXER_TOKEN_NOT_FOUND` | client | Token `{address}` has no historical-balances feature. | Historical balance reads use the token's historical-balances feature, and none is attached to this token. | Attach the historical-balances feature to the token, then read again. | info | No | 404 |
| DALP-0343 | `TOKEN_PRICE_RESOLUTION_FAILED` | domain | Token price cannot be resolved from the indexed pricing state. | `data.reason` names the failed price state: `no-feed` has no registered feed; `feed-not-indexed` has no indexed row; `registration-date-missing` has no indexed registration date; `inactive-feed` is disabled; `unsupported-quote` does not quote a supported fiat currency; `unanswered-feed` has no observation; and `stale-feed` is outside the configured window. | Read `data.reason`, then register, reindex, activate, correct, answer, or refresh the feed as that state requires. | error | No | 503 |
| DALP-0345 | `TOKEN_PRICE_IDENTITY_REQUIRED` | auth | An on-chain identity is required to set a token price. | The authenticated participant has no on-chain identity on the request chain, or the organisation has no eligible CLAIM signer to sign price declarations. | Create or select a participant identity on the request chain, then retry the token price update. If the message names the CLAIM signer, set up the organisation's claim signer first. | info | No | 403 |
| DALP-0346 | `TOKEN_PRICE_FEED_FACTORY_UNAVAILABLE` | domain | The price feed system is not installed. | The active system has no issuer-signed price-feed factory. | Install the price feed system before setting token prices. | error | No | 503 |
| DALP-0347 | `TOKEN_PRICE_TOKEN_UNAVAILABLE` | client | Token `{tokenAddress}` is not indexed in the active scope. | Token `{tokenAddress}` is not indexed in the active tenant and chain scope. | Verify the token address and wait for indexing before retrying. | info | No | 404 |
| DALP-0351 | `LEGACY_BOND_NOT_INDEXED` | operational | The bond is not indexed yet for this token. | The indexer has not projected a denomination asset for the legacy bond. | Wait for the bond initialization block to be indexed, then retry. | error | Yes | 404 |
| DALP-0353 | `TOKEN_LIFECYCLE_CUSTODIAN_REQUIRED` | permission | Delegated redemption requires the custodian role. | Redeeming for owner `{owner}` requires the custodian role. | Redeem from the caller's own wallet, or ask a token custodian to redeem for another owner. | info | No | 403 |
| DALP-0357 | `TOKEN_SALE_ADDON_NOT_IN_OWNER_SCOPE_AUTHENTICATED` | permission | Provided system addon does not belong to the authenticated system. | The `systemAddon` filter address supplied in the request is not one of the token sale addon addresses registered under the authenticated system. | Use a `systemAddon` address from the list of addons returned by the system addons endpoint for the authenticated system. | info | No | 403 |
| DALP-0372 | `TOKEN_TRANSFER_MISSING_ITEM` | client | Missing transfer item. | The `transfers` array is empty. A transfer request needs at least one item. | Provide at least one transfer item in the `transfers` array and retry. | info | No | 422 |
| DALP-0375 | `TOKEN_TRANSFER_PAUSED` | domain | Token `{tokenAddress}` is halted. | Token operations are halted, so transfers are disabled. | Resume token operations before transferring. | info | No | 409 |
| DALP-0383 | `TRANSACTION_NOT_FOUND` | client | Transaction `{requestId}` not found. | The platform could not locate a transaction with that id in the queue or ownership scope. Transactions belonging to another organization's wallets are reported the same way as genuinely missing ones to prevent enumeration. | Verify the transaction id is correct and belongs to your organization's wallets. If the transaction was recently created, retry after a short delay to allow processing. | info | No | 404 |
| DALP-0388 | `USER_KYC_CANNOT_APPROVE_VERSION_STATUS_ONLY_VERSIONS_UNDER_REVIEW_CAN_APPROVED` | domain | Cannot approve version with status "`{value}`". Approval requires a version under review. | The KYC profile version is not in the `under_review` state. The approval route reads the version with a row lock and checks its status before transitioning it to `approved`. | Submit a KYC version for review first with `POST /api/v2/kyc-profile-versions/:versionId/submissions`, then retry the approval once the version reaches `under_review` status. | info | No | 409 |
| DALP-0389 | `USER_KYC_CANNOT_FULFILL_ACTION_STATUS_ONLY_OPEN_REQUESTS_CAN_FULFILLED` | domain | Cannot fulfill request with status "`{value}`". Fulfillment requires an open request. | The KYC action request is not open: it was fulfilled or cancelled, or no such request exists. | Verify the current status of the action request before retrying. Only `open` action requests can be fulfilled. | info | No | 409 |
| DALP-0390 | `USER_KYC_CANNOT_REJECT_VERSION_STATUS_ONLY_VERSIONS_UNDER_REVIEW_CAN_REJECTED` | domain | Cannot reject version with status "`{value}`". Rejection requires a version under review. | The KYC profile version is not in the `under_review` state. The rejection route reads the version with a row lock and checks its status before transitioning it to `rejected`. | Confirm the version is currently `under_review` before calling the rejection endpoint. A version that is already approved, rejected, or still a draft cannot be rejected. | info | No | 409 |
| DALP-0391 | `USER_KYC_CANNOT_SUBMIT_VERSION_STATUS_ONLY_DRAFT_VERSIONS_CAN_SUBMITTED` | domain | Cannot submit version with status "`{value}`". Submission requires a draft version. | The KYC profile version is not in the `draft` state. The submit route reads the version with a row lock and checks its status before transitioning it to `under_review`. | Confirm the version status is `draft` before submitting. A version that is already `under_review`, `approved`, or `rejected` cannot be submitted again. | info | No | 409 |
| DALP-0392 | `USER_KYC_CANNOT_UPDATE_VERSION_STATUS_ONLY_DRAFT_VERSIONS_CAN_UPDATED` | domain | Cannot update version with status "`{value}`". Updates require a draft version. | The KYC profile version is not in the `draft` state. The update route reads the version with a row lock and rejects writes to any version that has already been submitted for review, approved, or rejected. | Create a new draft version to make further changes, or check whether the existing draft can be cloned from the approved version. | info | No | 409 |
| DALP-0417 | `USER_KYC_PROFILE_NOT_FOUND_ACTION` | client | KYC profile not found for this request. | The fulfill handler resolved the KYC version linked to the action request but found no KYC profile for the participant who owns that version. The profile row is required to clear the pending-update flag after fulfillment. | Verify the action request ID and that the participant has a KYC profile. If the profile was deleted, create a new one before retrying. | info | No | 404 |
| DALP-0431 | `XVP_CREATE_COULD_NOT_RESOLVE_CREATED_SETTLEMENT_INDEXER_RETRIES` | dependency | The completed settlement write is not indexed yet. | The settlement or token-sale write completed on chain, but its result was not readable from the index before the read window closed. | Do not send the write under a new Idempotency-Key, because it already completed. Repeat the request unchanged with the same Idempotency-Key to read its result once it is indexed. Contact support with the X-Request-Id response header if it keeps failing. | error | Yes | 503 |
| DALP-0441 | `DURABLE_EXECUTION_ENGINE_CALL_CONFLICT` | dependency | Workflow Engine workflow call conflicted with the current workflow state. | A Workflow Engine endpoint returned HTTP 409 because the downstream workflow state did not allow this call at this time. | Refresh the resource or deployment status, wait for the active workflow step to finish, then retry if the operation is still valid. | info | No | 409 |
| DALP-0447 | `TRANSACTION_QUEUE_UNPROCESSABLE` | dependency | Transaction queue could not complete the operation. | The transaction failed on-chain without a revert reason the API can decode, the sending smart wallet cannot fund it, or the queue rejected its input. | Check the operation input, the current contract and token state, and the funds of the sending wallet, then retry with a new idempotency key. | info | No | 422 |
| DALP-0448 | `TRANSACTION_QUEUE_CONFIRMATION_TIMEOUT` | dependency | Transaction queue confirmation timed out. | The transaction queue did not observe the queued transaction confirmation before its timeout window expired. | Check the transaction status before retrying so you do not submit a duplicate operation. | warning | Yes | 504 |
| DALP-0462 | `SETTINGS_COMPLIANCE_TEMPLATE_INCOMPATIBLE_MODULE_SET` | domain | Compliance template modules and controls must match the selected module set. | The template contains configured modules or required controls from a different compliance module generation. | Remove the incompatible controls or create a template with the matching legacy/current module set. | info | No | 422 |
| DALP-0463 | `SETTINGS_TEMPLATE_NAME_ALREADY_EXISTS` | client | A template with this name already exists in this organisation. | The organisation already has a custom template with the submitted name. | Choose a unique template name or update the existing template instead. | info | No | 409 |
| DALP-0467 | `TREASURY_WALLET_MISMATCH` | client | Caller wallet is not the treasury wallet for the `fixed-treasury-yield` feature. | ERC-20 `approve` must be called from the wallet that owns the funds. The authenticated caller is not the configured treasury wallet, so this route cannot proxy the approval. | Retry signed in as the configured treasury wallet. | info | No | 403 |
| DALP-0471 | `SYSTEM_IDENTITY_NO_ACTIVE_CLAIM_FOUND_TOPIC` | client | No active claim found for topic `{topicId}` on identity `{identityAddress}`. | Platform API could not find an active (non-revoked) claim matching the requested topic on the target identity. | Verify the topic and identity address, and confirm the claim has not already been revoked, before retrying. | info | No | 404 |
| DALP-0472 | `STEP_UP_REQUIRED` | auth | Step-up authentication required for this operation. | The route requires a recent re-authentication and the current session is older than the policy window. | Re-authenticate (sign in again or complete the step-up challenge) and retry the request. | info | No | 403 |
| DALP-0474 | `PRICE_RESOLVER_ADDON_NOT_INSTALLED` | domain | PriceResolver addon missing on system `{systemAddress}`. | No PriceResolver addon is installed on the target system. | Install the PriceResolver addon on the system before resolving prices. | info | No | 404 |
| DALP-0488 | `COMPLIANCE_SIGNATURE_INVALID` | auth | Webhook authentication failed. | The compliance webhook signature could not be verified against the provider's signing secret. | Verify the provider webhook URL and signing secret configuration, then send a freshly signed event. | info | No | 401 |
| DALP-0489 | `COMPLIANCE_REPLAY_WINDOW_EXCEEDED` | client | Webhook timestamp is outside the accepted replay window. | The compliance webhook event carries no timestamp, or its timestamp is more than five minutes from the server clock. | Send a fresh provider event with a current timestamp and verify clock synchronization for the provider. | info | No | 400 |
| DALP-0491 | `COMPLIANCE_PROVIDER_PAUSED` | domain | Compliance provider is not accepting webhook events. | The compliance provider is paused, so its webhook accepts no events. | Verify the provider configuration and resume the provider before sending more provider events. | info | No | 404 |
| DALP-0492 | `COMPLIANCE_PROVIDER_FAILED` | domain | Compliance provider is in a failed state. | The compliance provider failed provisioning or health checks and cannot process provider events. | Repair or reprovision the provider before retrying webhook processing. | info | No | 409 |
| DALP-0493 | `COMPLIANCE_UNMAPPED_EVENT` | domain | Compliance provider event has no supported mapping. | The provider payload is not JSON, or does not match a supported ClaimSource verdict or monitoring-alert shape. A parsed payload is kept for audit when the audit write succeeds. | Review the provider event type and update the adapter mapping before replaying the event. | info | No | 422 |
| DALP-0496 | `COMPLIANCE_APPLICANT_CREATE_FAILED` | dependency | Compliance provider rejected applicant creation. | The provider applicant or monitored-subject creation call failed before DALP could persist the subject mapping. | Verify provider credentials and the submitted subject fields, then retry applicant creation. | error | No | 502 |

The next page is [DALP-0500 to DALP-0599](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference/dalp-0500-0599).


# DALP-0500 to DALP-0599

Source: https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference/dalp-0500-0599
Cause, fix, HTTP status and retry flag for every Platform API error with a code from DALP-0500 to DALP-0599.

This page lists the 27 errors the Platform API can return with a code from DALP-0500 to DALP-0599. Match the `id` in the error envelope to the DALP Code column, then read Retryable and Suggested Fix. The [Platform API error reference](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference#how-to-use-this-reference) explains each column, including Severity, and the [DALP error index](https://docs.settlemint.com/docs/api-reference/errors) lists the page for every code range.

| DALP Code | Machine name | Category | Message | Why | Suggested Fix | Severity | Retryable | HTTP Status |
| --- | --- | --- | --- | --- | --- | --- | --- | --- |
| DALP-0500 | `COMPLIANCE_SECRET_ROTATION_GRACE_EXPIRED` | domain | Compliance webhook signing secret rotation grace period expired. | The pending webhook signing secret expired before it was promoted to the active secret. | Start a new secret rotation and update the provider dashboard with the active webhook signing secret. | info | No | 410 |
| DALP-0501 | `COMPLIANCE_INVALID_STATE_TRANSITION` | client | Compliance provider cannot transition to the requested state. | The provider's state does not permit the operation: it is paused, revoked or not active, its status or pending secret changed meanwhile, a secret rotation is already pending, its kind does not offer the operation, or the trusted-issuers registry refused the change. | Refresh the provider and choose an operation that matches its current state. | info | No | 409 |
| DALP-0502 | `COMPLIANCE_PROVIDER_NOT_FOUND` | client | Compliance provider not found. | No active compliance provider matches the webhook URL: the provider id or URL token is unknown or wrong, the provider was revoked, or the URL names another provider kind. | Use the webhook URL the provider was given when it was created. | info | No | 404 |
| DALP-0507 | `WEBHOOK_REPLAY_RATE_LIMITED` | client | Webhook replay rate limit exceeded. | The organisation used up its per-minute allowance of webhook replays or test events, or the endpoint used up its test-event allowance. | Wait the number of seconds in `data.retryAfterSeconds`, then send the request again. | info | Yes | 429 |
| DALP-0508 | `WEBHOOK_REPLAY_RANGE_TOO_LARGE` | client | Webhook replay range is too large. | The replay range spans more blocks than one request may replay without `confirmLargeRange`. | Split the range into smaller ranges, or send `confirmLargeRange: true`, then retry. | info | No | 400 |
| DALP-0509 | `WEBHOOK_ENDPOINT_DISABLED` | domain | Webhook endpoint disabled. | The endpoint is disabled or its circuit breaker is open, so a replay onto it would never be attempted. | Re-enable the endpoint after fixing the delivery failure cause, or wait for its breaker to close, then retry the replay. | info | No | 409 |
| DALP-0510 | `WEBHOOK_SIGNING_VERIFICATION_FAILED` | auth | Webhook signature verification failed. | The receipt's signature does not verify against the endpoint's active or previous signing secret, its innerEventHash does not match the delivered payload, or its receipt window has closed. | Sign the receipt with the endpoint's current signing secret, hash the exact delivered payload, and send the receipt within the receipt window. | info | No | 401 |
| DALP-0512 | `WEBHOOK_URL_PRIVATE_RANGE` | client | Webhook endpoint URL is not allowed. | The endpoint URL is not a valid URL, or its host resolves to a private, loopback or link-local address, or outside the operator's target allow list when one is set. | Use a valid https:// URL whose host resolves only to public addresses, or ask an operator to admit its range. | info | No | 400 |
| DALP-0513 | `WEBHOOK_ENDPOINT_LIMIT_REACHED` | domain | Webhook endpoint limit reached. | The organisation already has 1,000 webhook endpoints that are not deleted, the most it may register. | Delete an unused endpoint, then create the new one. | info | No | 409 |
| DALP-0516 | `WEBHOOK_PENDING_RETARGET_REQUIRED` | client | Webhook endpoint has pending delivery attempts. | The endpoint has queued deliveries, and the request changes its URL, which re-targets them, or disables it, which cancels them, without `acknowledgePending=true`. | Wait for the queue to drain, or re-send the request with `?acknowledgePending=true` to confirm the effect on queued deliveries. | info | No | 409 |
| DALP-0517 | `WEBHOOK_FAT_ACK_INCOMPLETE` | client | Fat-event acknowledgement is missing required field paths. | A fat endpoint delivers unredacted personal data for its active subscriptions. Every `<eventType>.<fieldPath>` that the thin shape would strip must be named in `fatEventsAcknowledgment.fieldsAcknowledged` for the resulting subscription set. The acknowledgement on this request, or the stored one when the request omits it, does not cover that set, so the platform rejected the update. | Resend the PATCH with `fatEventsAcknowledgment.fieldsAcknowledged` listing every personal-data field that thin payloads remove for the resulting subscriptions and their retractions, in `<eventType>.<fieldPath>` form. The Console's switch-to-fat dialog prepares this list and records the acknowledgment. To create a fat endpoint, register it thin, then switch it with this PATCH. | info | No | 422 |
| DALP-0523 | `TOKEN_FEE_RATES_FROZEN` | domain | Transaction fee rates frozen. | Transaction fee rates are frozen on this token's fee feature. | Leave the frozen rates unchanged or configure a different token feature. | info | No | 409 |
| DALP-0524 | `REQUEST_PARTICIPANT_FORBIDDEN` | permission | The selected participant is not available. | The selected participant does not exist or cannot be assumed by the authenticated user. | Select an authorized participant or request an administrator grant. | info | No | 403 |
| DALP-0525 | `COMPLIANCE_TRANSACTION_REGISTER_FAILED` | dependency | Compliance provider rejected transaction registration. | The compliance provider's transaction-registration call failed before DALP could persist the transaction-id mapping. | Verify provider credentials and the submitted transaction fields, then retry transaction registration. | error | No | 502 |
| DALP-0526 | `WEBHOOK_ENDPOINT_NOT_FOUND` | client | Webhook endpoint not found. | No webhook endpoint with that identifier exists in the current tenant, or the endpoint has been deleted. Deleted endpoints remain as audit tombstones and are not available for new operations. | Verify the endpoint identifier belongs to the authenticated tenant. If the endpoint was deleted, create a new endpoint. | info | No | 404 |
| DALP-0527 | `WEBHOOK_DELIVERY_NOT_FOUND` | client | Webhook delivery not found. | No delivery record matches the combination of delivery identifier, endpoint identifier, and tenant, plus the event identifier on the receipt-create path. On that path, this also surfaces when the delivery's own `counterSignedReceipts` snapshot is false, meaning the feature was not enabled on the endpoint when that delivery was dispatched. | Confirm the delivery identifier and endpoint identifier are correct and belong to the authenticated tenant. List deliveries for the endpoint to retrieve valid identifiers. | info | No | 404 |
| DALP-0529 | `WEBHOOK_RECEIPT_NOT_FOUND` | client | Webhook receipt not found. | No receipt record with that identifier exists in the current tenant scope. | Verify the receipt identifier belongs to the authenticated tenant. Use the receipt list endpoint to retrieve valid identifiers. | info | No | 404 |
| DALP-0533 | `METADATA_NOT_FOUND` | client | Metadata not found. | No metadata document resolved for this hash from IPFS or the object-storage mirror within the resolution time limit. | Verify the metadata hash and retry after the metadata source has replicated. | info | No | 404 |
| DALP-0534 | `WEBHOOK_SUBSCRIPTION_INVALID` | client | Webhook subscription pattern is not recognized. | The subscription pattern does not match any registered webhook event type or documented wildcard form, or it requests retracted events without a matching source subscription that can create the rows retractions are derived from. A test event also gets this answer when it names an event reserved for internal emitters. | Use an exact registered event name, a lifecycle wildcard (\*.pending, \*.provisional, \*.final, \*.retracted, _.recalled), a prefix wildcard for a registered event family (token.transfer._), or \*. Pair every retraction pattern with a pending, provisional, or final source subscription. | info | No | 400 |
| DALP-0535 | `WEBHOOK_URL_SCHEME_REQUIRED` | client | Webhook endpoint URL must use HTTPS. | The endpoint URL uses a scheme other than HTTPS. Untrusted destinations must be HTTPS so delivery traffic is encrypted and the SSRF guard can apply its public-address policy. | Register an https:// URL, or ask an operator to add this exact origin to DALP_WEBHOOKS_TRUSTED_DESTINATIONS on a private-network install that needs plain HTTP. | info | No | 400 |
| DALP-0536 | `AUTHORIZATION_CHECK_FAILED` | dependency | The permission check could not be completed. | The authentication provider could not evaluate whether the caller holds the permission this route requires, so the platform refused the request rather than admitting or denying it on a guess. | Retry the request. If the failure continues, ask your operator to confirm the authentication provider is reachable. | error | Yes | 503 |
| DALP-0537 | `WEBHOOK_IDEMPOTENCY_KEY_REUSED` | client | Webhook Idempotency-Key reused. | The Idempotency-Key already started a registration from a different request, a registration that never completed, or one whose endpoint has since been deleted. | Send a new Idempotency-Key for a new registration, and reuse a key only to retry the identical request. | info | No | 409 |
| DALP-0538 | `WEBHOOK_CREATE_IN_PROGRESS` | domain | Webhook registration still in progress. | Another request with the same Idempotency-Key is still registering its endpoint. | Retry the identical request with the same Idempotency-Key after a few seconds. | info | Yes | 409 |
| DALP-0539 | `USER_KYC_CANNOT_APPROVE_VERSION_FIELDS_NEED_CHANGES` | domain | Cannot approve version while fields "`{value}`" are missing or still need changes. | An approval must leave the version approved. A required field that is empty, a field a reviewer marked `changes_requested`, or a document an open action request still waits for keeps the version under review, so the approval is refused and writes nothing: no field verdict and no review outcome. | Wait for the investor to supply the listed fields or documents, or correct the fields with `PATCH /api/v2/users/:userId/profile`. A reviewer who did not make the correction then approves the version. | info | No | 409 |
| DALP-0540 | `WEBHOOK_REPLAY_RANGE_REVERSED` | client | Webhook replay range ends before it begins. | The replay range's `toBlock` is before its `fromBlock`. | Send a `toBlock` at or after `fromBlock`, then retry. | info | No | 400 |
| DALP-0541 | `WEBHOOK_REPLAY_CHAIN_NOT_AVAILABLE` | client | Webhook replay chain is not available for this organization. | The replay's `chainId` names a network the active organization has no network for. | Send the `chainId` of a network listed in the organization's settings, then retry. | info | No | 400 |
| DALP-0542 | `WEBHOOK_ENDPOINT_VERSION_CONFLICT` | domain | Webhook endpoint changed since you read it. | Someone else saved a change to this endpoint after you read it, so your change was not applied. | Read the endpoint again and reapply your change to its current version. | info | No | 409 |

The previous page is [DALP-0000 to DALP-0499](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference/dalp-0000-0499). The next page is [DALP-0600 to DALP-0699](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference/dalp-0600-0699).


# DALP-0600 to DALP-0699

Source: https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference/dalp-0600-0699
Cause, fix, HTTP status and retry flag for every Platform API error with a code from DALP-0600 to DALP-0699.

This page lists the 36 errors the Platform API can return with a code from DALP-0600 to DALP-0699. Match the `id` in the error envelope to the DALP Code column, then read Retryable and Suggested Fix. The [Platform API error reference](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference#how-to-use-this-reference) explains each column, including Severity, and the [DALP error index](https://docs.settlemint.com/docs/api-reference/errors) lists the page for every code range.

| DALP Code | Machine name | Category | Message | Why | Suggested Fix | Severity | Retryable | HTTP Status |
| --- | --- | --- | --- | --- | --- | --- | --- | --- |
| DALP-0605 | `TOKEN_CREATE_FEATURES_INCOMPATIBLE` | client | The requested token features contain an incompatible pair. | The requested token features contain an incompatible pair. | Remove one feature from every reported incompatible pair and retry. | info | No | 409 |
| DALP-0606 | `TOKEN_FEATURES_YIELD_FULLY_CONSUMED` | client | No yield is claimable: a prior conversion consumed it for the completed periods. | The accrued yield quotes as zero because interest consumed in a prior token conversion offsets it, and accrual is still open. | Wait for the next yield period to complete after the conversion. Check the conversion history to see which periods were consumed. | info | No | 400 |
| DALP-0608 | `TOKEN_FEATURES_NO_YIELD_AVAILABLE_FOR_HOLDER` | client | No yield available to claim for this holder. | The holder has no claimable yield. The periods are already claimed, accrual closed after conversion, or consumed interest offset the accrued amount. | Verify holder eligibility (last claimed period, conversion state) before retrying. | info | No | 400 |
| DALP-0615 | `XVP_HASHLOCK_REVEAL_NOT_REQUIRED` | client | Hashlock reveal not required for this XvP settlement. | Revealing a secret applies only to HTLC-enabled XvP settlements with external flows; the target settlement is local-only. | Skip the reveal call for local settlements, or target an HTLC settlement that has external flows. | info | No | 400 |
| DALP-0616 | `X_EXECUTOR_AA_DISABLED_GLOBALLY` | client | smart-wallet executor not available. | The X-Executor header requested smart-wallet execution while platform Account Abstraction is disabled. | Use X-Executor: eoa or omit the header until platform Account Abstraction is enabled. | info | No | 403 |
| DALP-0617 | `AA_ENABLED_REQUIRES_GLOBAL_AA` | domain | Platform AA disabled; per-org AA requires platform AA enabled. | The organization setting requested Account Abstraction routing while the platform-wide Account Abstraction feature is disabled. | Keep AA_ENABLED disabled, or enable platform Account Abstraction before enabling the organization setting. | info | No | 403 |
| DALP-0621 | `X_EXECUTOR_AA_DISABLED_FOR_ORG` | client | smart-wallet executor not available. | The X-Executor header requested smart-wallet execution while Account Abstraction is disabled for this organization. | Ask your organization administrator to enable Account Abstraction for this organization, or omit the X-Executor header to use the organization's default routing. | info | No | 403 |
| DALP-0635 | `GAS_REQUIREMENT_CONFIG_ERROR` | operational | Gas requirement computation failed for this chain. | The gas the platform computed for this chain exceeds the chain's configured ceiling, or the chain's pending base fee is below its configured floor. | Contact support with the X-Request-Id response header so an operator can correct the chain's gas settings. | error | No | 503 |
| DALP-0637 | `AA_ENABLED_IDENTITY_MISMATCH` | domain | Account abstraction identity sync found a different smart-wallet OnchainID. | A participant's smart wallet is already registered to a different OnchainID than the participant's EOA. | Review the participant identity binding before enabling account abstraction. | info | No | 409 |
| DALP-0638 | `AA_ENABLED_CONTROLLER_MISMATCH` | domain | Account abstraction identity sync found a different smart-wallet controller. | An existing smart-wallet row points at a controller that does not match the participant's current signing EOA. | Repair the participant wallet pairing before enabling account abstraction. | info | No | 409 |
| DALP-0639 | `FEEDS_SUBMIT_OBSERVED_AT_TOO_FAR_IN_FUTURE` | client | No observation time fits the feed at the selected chain time. | The feed already holds an observation later than the selected chain time, or the submission names an observation time later than chain time or earlier than the feed's latest observation. | Wait until chain time passes the feed's latest observation, then submit again with an observation time at or before chain time. | info | No | 400 |
| DALP-0645 | `TOKEN_LIST_METADATA_KEY_UNKNOWN` | client | The requested metadata key is not declared in any accessible asset-type template. | Token list grouping and metadata filters resolve eligible keys from the metadata schemas of the asset-type templates the caller can see. The requested key is not declared in any of those schemas, so it cannot be used as `groupBy` or as a `filter[metadata.<key>]` axis. | Verify the key name matches a field declared in a system or organization template's metadata schema. Use `data.availableKeys` (capped, alphabetically sorted) for a quick discovery list, or `meta.facets["metadata.<key>"]` on a regular list request for the authoritative bucketable axes. | info | No | 400 |
| DALP-0646 | `TOKEN_LIST_METADATA_KEY_NOT_BUCKETABLE` | client | Continuous-type metadata key not eligible for grouping or facets. | Token list `groupBy` and facet axes are restricted to bucketable metadata field types (`string`, `enum`, `country-code`, `currency-code`, `address`). Continuous types such as `number`, `date`, `decimal-money`, `percentage`, `bps`, and `url` are filterable via `filter[metadata.<key>]` but not bucketable. | Pick a bucketable-typed key for `groupBy` and faceting, or apply this key as a filter only. | info | No | 400 |
| DALP-0647 | `TOKEN_LIST_METADATA_KEY_IDENTIFIER_INELIGIBLE` | client | Identifier-type metadata keys not eligible for grouping or facets. | Identifier-typed metadata fields (`isin`, `cusip`, `lei`, `figi`) are typically unique per token. Using them as `groupBy` yields degenerate one-token-per-group results and as facet axes they yield single-bucket noise, so token list excludes them from both surfaces. | Use the identifier key as a filter via `filter[metadata.<key>]`, or pick a non-identifier bucketable-typed key for grouping and facets. | info | No | 400 |
| DALP-0653 | `TREASURY_HEALTH_TREASURY_UNCONFIGURED` | client | Treasury address missing for the maturity-redemption or fixed-treasury-yield feature. | An attached treasury feature has no configured treasury address. | Configure a non-zero treasury address, then retry. | info | No | 404 |
| DALP-0655 | `TREASURY_HEALTH_TREASURY_MISMATCH` | client | Attached treasury-bearing features disagree on `treasury`, `denominationAsset`, or `treasuryIsContract`. | Attached treasury features disagree on treasury configuration. | Align the treasury, denomination asset, and implementation classification, then retry. | info | No | 409 |
| DALP-0656 | `TREASURY_HEALTH_BOND_STATUS_UNAVAILABLE` | dependency | The bond row for the maturity-redemption feature is not indexed yet. | The `/api/v2/tokens/:assetId/treasury/health` route reads the bond's required redemption amount from the indexed bond row. The maturity-redemption feature is attached, but its bond row is not indexed yet, and a zero amount would show a false `green` badge. | Retry after the indexer catches up. If the failure persists, check that the indexer is processing the active chain. | error | Yes | 503 |
| DALP-0657 | `TOKEN_HISTORICAL_BALANCE_BLOCK_NOT_INDEXED` | client | Requested block not reached yet by the historical balance indexer. | The requested block is ahead of the indexed head for the historical-balances feature, so no checkpoint covers it yet. | Wait for the indexer to reach the requested block, or request a block at or below `data.headBlock`. | info | Yes | 409 |
| DALP-0659 | `OIDC_MFA_INVALID` | auth | Identity provider verification failed. | The authenticator code did not pass the identity provider's verification for this signing request. | Enter a fresh code from your authenticator app and try the operation again. | info | No | 403 |
| DALP-0660 | `OIDC_MFA_UNAVAILABLE` | dependency | Identity provider verification is temporarily unavailable. | Platform API could not reach the identity provider to complete the verification for this signing request. | Retry after a short backoff; if it persists, contact support with the request id. | error | Yes | 503 |
| DALP-0670 | `USER_EMAIL_ALREADY_EXISTS` | client | A user with this email already exists. | Each platform user must have a unique email address. | Use a different email or open the existing user in User management. | info | No | 409 |
| DALP-0671 | `ACTIONS_STREAM_ORIGIN_REJECTED` | permission | Live actions feed requires Console origin. | The live actions feed carries browser session cookies, and the request origin did not match the Console origin accepted for live updates. | Refresh the Console and retry the actions view. An API client authenticates the stream with an API key, or calls `GET /api/v2/action-inbox` instead. | info | No | 403 |
| DALP-0673 | `CUSTODY_CREDENTIALS_UNAVAILABLE` | operational | Custody credentials for this organization are unavailable. | The organisation's custody record or provider configuration is missing, its provider is unsupported, its stored credential payload or workspace pin is invalid, or the secrets backend refused access. Custody operations fail closed rather than substitute another provider. | Contact support with the request id so an operator can restore the organization's custody configuration. | error | No | 500 |
| DALP-0674 | `CUSTODY_CREDENTIALS_INVALID` | domain | The supplied custody credentials failed validation. | The credential probe against the custody provider failed: the payload was malformed, authentication was rejected, the probe timed out, or the credentials cannot reach the organization's pinned workspace. | Verify the credential values with your custody provider, confirm they belong to the organization's workspace, and try again. | info | No | 422 |
| DALP-0677 | `CUSTODY_RECORD_DESTROYED` | domain | This organization's custody configuration has been destroyed and cannot be modified. | An operator destroyed the organization's custody credentials; the record is retained as a tombstone and lifecycle writes against it are rejected to prevent silent resurrection with deleted credentials. | Re-onboard the organization's custody through the explicit re-onboarding path, or contact support with the request id. | info | No | 409 |
| DALP-0678 | `CUSTODY_PROVIDER_IMMUTABLE` | domain | The custody provider for this organization is locked and cannot be changed. | The organization's custody provider was locked when its first wallet was created; switching providers would orphan existing keys. | Keep the locked provider and supply replacement credentials for it instead of selecting a different provider. | info | No | 409 |
| DALP-0679 | `TOKEN_SALE_CANNOT_WITHDRAW_SALE_TOKEN_CURRENCY` | client | The sale token cannot be withdrawn as a payment currency. | The selected withdrawal currency is the token being sold; the contract reserves those tokens for buyers and reverts CannotWithdrawSaleToken. | Choose one of the sale's payment currencies instead of the sale token, then retry. | info | No | 400 |
| DALP-0681 | `PRECONDITION_FAILED` | client | A precondition on the request was not met. | The `If-Match` or `If-None-Match` condition sent with the request does not hold for the current resource: it was changed, created, or removed since the version the request was built against. | Read the resource again, apply your change to the version you just read, and send the request with the entity-tag from that read. | info | No | 412 |
| DALP-0683 | `AIRDROP_ADDON_NOT_FOUND` | domain | No airdrop addon is deployed in this system. | Listing or reading airdrops needs at least one airdrop factory registered in the active system, and this system has none. | Deploy an airdrop addon for this system, then retry the request. | info | No | 404 |
| DALP-0684 | `AIRDROP_NOT_FOUND_INDEXER` | client | The requested airdrop was not found. | No airdrop at the requested address has been indexed for the active chain, so there is nothing to return. | Confirm the airdrop address and that it has been deployed and indexed, then retry. | info | No | 404 |
| DALP-0685 | `AIRDROP_NOT_IN_OWNER_SCOPE` | domain | The requested airdrop belongs to another system. | The airdrop at this address was deployed under a different system than the active one, so this endpoint does not return it. | Read this airdrop from the system that owns it, or pick an airdrop deployed in the active system. | info | No | 404 |
| DALP-0686 | `TOKEN_SALE_PURCHASE_OFF_GRID` | client | The purchase is off the sale's subscription step. | The sale accepts only cumulative subscriptions that are a multiple of its purchase increment, and this payment buys a token amount that leaves the buyer's total off that step; the contract would revert PurchaseNotMultipleOfIncrement. | Pick a token amount on the sale's subscription step and send the exact payment for it, then retry. | info | No | 400 |
| DALP-0687 | `COMPLIANCE_TEMPLATE_NOT_READY` | domain | Template is not ready to publish. | The publish readiness check found at least one required control with no configured module of that type on the template; `data.gaps` names the specific controls. | Open the Controls and rules step for each control listed in `data.gaps`, configure a compatible module for it (or remove it from required controls), save the template, and retry publish. | info | No | 422 |
| DALP-0693 | `CLAIM_TOPIC_EXCLUSION_REFUSED` | domain | This claim topic may not be used in exclusions in this system. | A NOT branch of the compliance rule excludes the holders of a claim the system's claim policy manager has set to Not allowed. Excluding those holders is defeated by its own subject: the holder manages their own identity and can delete the claim to pass the rule. | Use an identity block-list, whose identities you enumerate in `IdentityBlockListComplianceModule` and the holder holds no key to edit; a country block-list, which reads the registry country field only the identity manager writes; or a positive claim for the group you admit, so a holder who deletes it loses access instead of gaining it. The claim policy manager can also change the topic's setting for this system. | info | No | 422 |
| DALP-0694 | `CLAIM_TOPIC_EXCLUSION_ACKNOWLEDGEMENT_REQUIRED` | client | Excluding the holders of this claim needs an acknowledgement from a named actor. | A NOT branch of the compliance rule excludes the holders of a claim they carry on their own identity, so a holder can delete that claim and pass the rule. The control does not hold on its own, and accepting that is a decision that must carry a name, which is why an impersonated session cannot make it. | Send `holderRemovableNot.accepted` as `true` from a session that is not impersonated. Or use an identity block-list, whose identities you enumerate in `IdentityBlockListComplianceModule` and the holder holds no key to edit; a country block-list, which reads the registry country field only the identity manager writes; or a positive claim for the group you admit, so a holder who deletes it loses access instead of gaining it. | info | No | 400 |
| DALP-0699 | `OPERATIONS_REINDEX_CONFLICT` | domain | A reindex is already running. | A reindex rebuilds the indexed data of every network at once, and one is already running. | Wait for the running reindex to finish, then start the next one. | info | No | 409 |

The previous page is [DALP-0500 to DALP-0599](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference/dalp-0500-0599). The next page is [DALP-0700 to DALP-0799](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference/dalp-0700-0799).


# DALP-0700 to DALP-0799

Source: https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference/dalp-0700-0799
Cause, fix, HTTP status and retry flag for every Platform API error with a code from DALP-0700 to DALP-0799.

This page lists the 38 errors the Platform API can return with a code from DALP-0700 to DALP-0799. Match the `id` in the error envelope to the DALP Code column, then read Retryable and Suggested Fix. The [Platform API error reference](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference#how-to-use-this-reference) explains each column, including Severity, and the [DALP error index](https://docs.settlemint.com/docs/api-reference/errors) lists the page for every code range.

| DALP Code | Machine name | Category | Message | Why | Suggested Fix | Severity | Retryable | HTTP Status |
| --- | --- | --- | --- | --- | --- | --- | --- | --- |
| DALP-0705 | `DEBUG_BUNDLE_WINDOW_INVALID` | client | The debug bundle time window was not accepted. | The debug bundle window starts at or after its end. | Send a start before the end, or leave both out to export the default window. | info | No | 400 |
| DALP-0706 | `TOKEN_NOT_FOUND` | domain | Token not found. | The token is not present in the serving projection. | Confirm the token reference and wait for indexing if it was created recently. | info | No | 404 |
| DALP-0707 | `ASSET_REF_INVALID` | client | Token reference is incomplete. | The asset reference cannot identify a token in its stated family. | Send an EVM contract address, or a Canton instrument id together with its instrument admin. | info | No | 400 |
| DALP-0708 | `TOKEN_CROSS_FAMILY_MISMATCH` | client | Values from two chain families were combined. | The request combines values that belong to different chain families. | Filter and address the token within one family. | info | No | 400 |
| DALP-0709 | `TOKEN_PAUSED` | domain | The token is paused. | The token is paused, and this operation changes balances. | Unpause the token, then run the operation again. | info | No | 409 |
| DALP-0711 | `TOKEN_MUTATION_REJECTED` | domain | The token's state does not allow this write. | The token's current state does not allow this write. | Read the token, resolve the named condition, and write again. | info | No | 409 |
| DALP-0712 | `TOKEN_ROLE_REQUIREMENT_NOT_MET` | permission | This operation is not available to the caller. | The acting wallet holds none of the roles this operation requires. | Ask an administrator to grant one of the listed roles on this token. | info | No | 403 |
| DALP-0713 | `TOKEN_DOCUMENT_INVALID` | client | Document upload does not match its declaration. | The uploaded document does not match what the request declared. | Upload the file again and confirm it with its real size and type. | info | No | 422 |
| DALP-0715 | `TOKEN_COMPLIANCE_REJECTED` | permission | A compliance rule refused the transfer. | A compliance rule on this token refused the transfer. | Clear the named compliance blocker, then transfer again. | info | No | 403 |
| DALP-0717 | `TOKEN_DEPENDENCY_UNAVAILABLE` | dependency | A dependency of this route is unavailable. | A dependency this route needs did not answer. | Retry; the request was not applied. | error | Yes | 503 |
| DALP-0718 | `OBLIGATION_IMMUTABLE` | domain | This obligation cannot be edited. | The obligation is a platform catalogue entry, the same in every deployment, so no organisation can change it or add filing periods to it. | Copy the catalogue obligation and change the copy. | info | No | 409 |
| DALP-0719 | `APPROVER_SHORTFALL` | client | The organization has too few approvers to publish. | The organization has fewer approvers than maker-checker publishing requires. | Give the organization a second owner, then publish again. | info | No | 422 |
| DALP-0720 | `OBLIGATION_INVALID` | client | The obligation configuration does not hold together. | The obligation configuration is internally inconsistent. `data.violations` lists every problem the platform found, so they can be corrected in one pass. | Correct every violation listed in `data.violations`, then send the request again. | info | No | 422 |
| DALP-0721 | `TRANSITION_REFUSED` | domain | The submission's state does not allow this act. | The filing lifecycle does not permit this act from the submission's or filing period's current state. `data.from` and `data.event` name both. | Read the submission again and choose an act its current state permits. | info | No | 409 |
| DALP-0722 | `REPORTING_FILING_ROW_VERSION_CONFLICT` | domain | The submission changed before this act was applied. | Someone else changed this filing after you opened it, so your action was not applied. | Reload the filing, check its current state, and try the action again. | info | No | 409 |
| DALP-0723 | `SIGN_OFF_REFUSED` | domain | Sign-off was refused. | The artifact changed after the approver reviewed it, so the approved digest no longer matches. `data.reason` is `digest-moved`. | Review the current artifact, then approve the digest of the version you read. | info | No | 409 |
| DALP-0724 | `REACH_BACK_EXCEEDED` | permission | The filing period is outside the reach-back window. | The filing period is older than the reach-back window its obligation allows. | Raise the obligation's reach-back window before filing against a period this old. | info | No | 409 |
| DALP-0725 | `REPORTING_GENERATION_CONFLICT` | domain | Another report generation holds this slot. | Another generation holds this organisation's slot, so no run was started for this filing. | Start the generation again once the running one finishes. | info | Yes | 409 |
| DALP-0726 | `REPORTING_COVERAGE_UNAVAILABLE` | domain | The period starts before the platform's recorded history. | The reference period begins before the earliest date the platform has recorded history for. | File this period outside the platform; it predates the named date. | info | No | 422 |
| DALP-0727 | `ANCHOR_ENABLEMENT_REFUSED` | domain | The anchoring change was refused. | A check refused turning anchoring on or off for this obligation, or accepting a missing anchor. `data.reason` names which check. | Read `data.reason`. For `disclosure-not-confirmed`, confirm the disclosure with a written reason. For `no-published-version`, publish a version of the obligation. For `blocking-severity-unavailable`, choose a warning severity where publication is the fulfilment act. For `issuer-untrusted` or `issuer-unresolved`, register the issuer as trusted for the document-hash topic. For `already-disabled`, `no-standing-exception` or `already-overridden`, send no further request. | info | No | 409 |
| DALP-0728 | `OBLIGATION_NOT_FOUND` | domain | The reporting record was not found. | No reporting record of the requested kind with that identifier is visible to the caller in the active organization. A record another organization or another investor holds answers the same way, so the reply never confirms that an identifier exists elsewhere. | List the records of that kind, such as obligations, statements, or confirmations, and use an identifier from that list. | info | No | 404 |
| DALP-0730 | `EXTERNAL_TOKEN_ALREADY_REGISTERED` | domain | This token is already registered. | The token address is already registered as an external token for this organization. | Open the existing registration instead of registering the address a second time. | info | No | 422 |
| DALP-0732 | `RETURNS_SNAPSHOT_CONTENTION` | dependency | The returns snapshot could not be taken. | The snapshot reads every position in one transaction and lost that read to concurrent writers twice, so it stopped rather than answer a torn total. | Retry after a short backoff. | error | Yes | 503 |
| DALP-0733 | `PORTFOLIO_RESOURCE_NOT_FOUND` | client | Portfolio resource was not found. | The requested portfolio resource does not exist in the active organization. | Verify the identifier and the active organization, then request it again. | info | No | 404 |
| DALP-0734 | `GOVERNANCE_BALLOT_REJECTED` | client | The ballot wasn't accepted. | The ballot did not satisfy one of the rules a cast has to pass. The `reason` field names which one. | Read `reason`, correct that one condition, and send the ballot again. | info | No | 422 |
| DALP-0735 | `GOVERNANCE_STATE_UNAVAILABLE` | dependency | Governance state is temporarily unavailable. | Governance state could not be read from the chain or from its indexed projection. | Retry after a short backoff. If the problem continues, contact support with the request id. | error | Yes | 503 |
| DALP-0736 | `EXTERNAL_TOKEN_REGISTRATION_REJECTED` | client | The external token wasn't registered. | The address did not pass on-chain ERC-20 metadata verification, or it is already registered. | Check that the address exposes name, symbol, and decimals on this chain, and that it is not registered already. | info | No | 422 |
| DALP-0737 | `PORTFOLIO_RETURNS_UNAVAILABLE` | dependency | Portfolio returns are temporarily unavailable. | A return amount has incomplete denomination metadata, its denomination asset has no price, or no configured FX path connects its price currency to the organization's base currency. The response data names the currencies and reason. | For `denomination-metadata-missing`, wait for the denomination token to index. For `denomination-unpriced`, publish a price for the denomination asset. For `fx-path-unavailable`, configure a feed path from `priceCurrency` to `baseCurrency`, then retry after pricing updates. | error | Yes | 503 |
| DALP-0738 | `ARTIFACT_UNAVAILABLE` | domain | This filing has no stored artifact. | No artifact was ever stored for this submission, so there is nothing to download and nothing was erased. A split artifact is served as its parts, an erased one answers with its tombstone, and one under legal hold stays retrievable; none of those reaches this error. | Read the submission's state. An artifact exists only once generation has written one, so wait for the filing to be generated or read a submission that already has been. | info | No | 409 |
| DALP-0744 | `FILING_NOT_FOUND` | domain | The filing period or submission was not found. | No filing period or submission with that identifier is visible to the active organization. `data.subject` names which of the two was addressed. A row another tenant owns answers the same way, so the reply never confirms that an identifier exists elsewhere. | List the organization's filing periods and submissions, and use an identifier from that list. | info | No | 404 |
| DALP-0746 | `ANCHOR_LOOKUP_REFUSED` | client | The anchor question cannot be answered as asked. | An anchor lookup takes exactly one of a document digest, a subject identity or a registry address, and a verification takes the artifact's parts in order within the published ceilings. A page cursor the platform did not issue is refused the same way. `data.reason` names which of those the request broke. | Read `data.reason`. Send one of `digest`, `subject` or `registry` to read registry entries, or send each part's SHA-256 and byte length in the order of delivery, with `issuer`, to check a document you hold. | info | No | 422 |
| DALP-0747 | `ANCHOR_RETRY_REFUSED` | domain | This filing cannot be anchored yet. | An anchor may only fire from a discharged filing, and this submission has not been acknowledged or published. Before that the artifact can still legitimately be regenerated, and a commitment to a digest that may still change is one a document holder would later fail to reproduce, with no way to tell an honest regeneration from tampering. | Discharge the filing first: enter the authority's acknowledgement, or publish it to holders. Anchoring runs on its own at that act, and the retry route exists for the attempt that failed there. | info | No | 409 |
| DALP-0749 | `ANCHOR_WRITE_REFUSED` | domain | This document cannot be anchored. | Writing a registry entry is a permanent, public disclosure that can never be corrected, only superseded by a further entry, so every prerequisite is checked before anything reaches a chain. `data.reason` names which one refused: the confirmation of permanence was missing, the session is an operator acting as somebody else, the subject is not a usable identity, this organisation has no active system on the chosen chain, its issuer identity is inactive or has no resolvable claim key, that identity is not trusted for the document-hash topic in its own system's registry, the system carries no anchor registry, or the label would carry something identifying onto a public chain. | Read `data.reason`. Anchor as the organisation's owner or a platform administrator on your own session. Use a chain where your organisation runs a system whose anchor-registry migration has completed. Send a subject identity your issuer is trusted for, a short non-identifying label, and `disclosureConfirmed` set to true. A chain that was reached and declined is not this error: that arrives as `data.outcome` in a successful response. | info | No | 409 |
| DALP-0751 | `EXTERNAL_TOKEN_MANAGER_REQUIRED` | permission | Only a token manager can dismiss an external token. | Dismissing an external token hides it from the organization's holdings, portfolio, holder lists, token catalog, token details, and marks, and stops the platform from registering it again. It requires the tokenManager role on the organization's system. | Ask a system administrator to grant you the tokenManager role, then retry. | info | No | 403 |
| DALP-0752 | `SHAREHOLDER_LIST_NOT_FOUND` | domain | The security of this shareholder list was not found. | No security with that contract address is indexed in the active organization's system at `data.recordBlock`. A security another organization issued answers the same way, so the reply never confirms that a contract address exists elsewhere. | Use the contract address of a security the organization issued, as shown in the Console. For a security created after `data.recordBlock`, choose a later record block, or leave the block out to use the newest final block. | info | No | 404 |
| DALP-0753 | `SHAREHOLDER_LIST_REFUSED` | domain | No shareholder list can be read at this block. | The security's balance history does not reach the record block, or the record block is not final yet. `data.reason` names which, and `data.boundaryBlock` is the block the history starts at, the block the feature was detached at, or the newest final block. | For `feature-not-attached`, the security never had a historical-balances feature, so it has no record block to list. For `feature-detached`, the feature was detached at `data.boundaryBlock`: choose a record block before that block. For `enablement-after-record-block`, choose a record block at or after `data.boundaryBlock`. For `history-incomplete`, no record block can be listed, because the security had supply before the feature was attached; `data.boundaryBlock` is the block the feature was attached at. For `record-block-not-final`, wait until that block is final, or leave the block out to use the newest final block. | info | No | 422 |
| DALP-0754 | `STATEMENT_RANGE_REFUSED` | domain | No statement can be produced for this range yet. | A statement covers only blocks that are final on the chain, and the chain has not finalized the block at the end of the requested range yet. `data.periodEnd` is the inclusive end of the range the request asked for. | Choose an `end` before the newest final block, or send the same request again after the chain finalizes the block at `data.periodEnd`. | info | Yes | 422 |
| DALP-0755 | `ASSISTANT_VIEW_NOT_FOUND` | client | Saved view not found. | No saved view with that identifier was saved by the caller in the active organization. A view another member saved answers the same way to a rename, share or removal, so the reply never confirms that it exists. | List the saved views and use the identifier of a view the caller saved. | info | No | 404 |

The previous page is [DALP-0600 to DALP-0699](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference/dalp-0600-0699). The next page is [DALP-9000 to DALP-9099](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference/dalp-9000-9099).


# DALP-100000 to DALP-199999

Source: https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference/dalp-100000-199999
Cause, fix, HTTP status and retry flag for every Platform API error with a code from DALP-100000 to DALP-199999.

This page lists the 58 errors the Platform API can return with a code from DALP-100000 to DALP-199999. Match the `id` in the error envelope to the DALP Code column, then read Retryable and Suggested Fix. The [Platform API error reference](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference#how-to-use-this-reference) explains each column, including Severity, and the [DALP error index](https://docs.settlemint.com/docs/api-reference/errors) lists the page for every code range.

| DALP Code | Machine name | Category | Message | Why | Suggested Fix | Severity | Retryable | HTTP Status |
| --- | --- | --- | --- | --- | --- | --- | --- | --- |
| DALP-173531 | `reporting.venue-archive.VENUE_NOT_FOUND` | domain | The venue is not found. | No venue at that address is operated by the caller on the active network. A venue the caller does not operate answers the same way, so the reply never confirms that a venue exists. | Open the venue from the venue list as one of its operators or administrators, then repeat the request. | info | No | 404 |
| DALP-173532 | `reporting.venue-archive.HOLD_NOT_FOUND` | domain | The legal hold is not found. | No legal hold with that identifier exists on this venue in the active organization. | List the venue's legal holds and use an identifier from that list. | info | No | 404 |
| DALP-173533 | `reporting.venue-archive.HOLD_RELEASED` | domain | The legal hold is already released. | The legal hold is already released, so it cannot be released again. | Place a new legal hold if the records need protecting again. | info | No | 409 |
| DALP-173534 | `reporting.venue-archive.HOLD_RELEASE_PENDING` | domain | A release of this legal hold is already waiting. | A release of this legal hold is already waiting for a second duty manager. | Ask another duty manager to approve or reject the waiting release. | info | No | 409 |
| DALP-173535 | `reporting.venue-archive.HOLD_RELEASE_NOT_REQUESTED` | domain | No release of this legal hold is waiting. | Nobody has asked to release this legal hold, so there is no release to decide. | Request the release first, then have a second duty manager decide it. | info | No | 409 |
| DALP-173536 | `reporting.venue-archive.HOLD_SELF_APPROVAL` | permission | A second duty manager must approve this release. | The duty manager who asked to release a legal hold cannot approve that same release. | Ask a different duty manager to approve or reject the release. | info | No | 403 |
| DALP-173537 | `reporting.venue-archive.HOLD_MARKET_NOT_FOUND` | domain | The legal hold names an instrument this venue does not list. | The legal hold names an instrument that is not listed on this venue, so it would protect no record. | Use an instrument id from this venue's instruments, or leave the instrument out to hold the whole venue. | info | No | 404 |
| DALP-173561 | `TRADING_VENUE_SCHEDULED_TRANSITION_NOT_FOUND` | domain | The scheduled transition was not found. | The transition id does not name a scheduled transition of this instrument on the selected network. | Use a transition id from the instrument's scheduled transitions list. | info | No | 404 |
| DALP-173562 | `TRADING_VENUE_SCHEDULED_TRANSITION_CONFLICT` | domain | The scheduled transition conflicts with the instrument's schedule. | An instrument holds one pending scheduled transition at a time, and only a pending one, or one waiting to retry, can be cancelled. The reason is `pending-exists` when the instrument already has one, and `not-pending` when this one already ran, was cancelled, or is being applied right now, including while its transaction is still pending on the transaction queue. | Read the instrument's scheduled transitions, and cancel the pending one before scheduling another. | info | No | 409 |
| DALP-173563 | `TRADING_VENUE_SCHEDULED_TRANSITION_TIME_REFUSED` | client | The scheduled transition's effective time cannot be used. | The scheduled transition's effective time resolves to now or the past, the instrument has no trading calendar to resolve a date against, or its calendar opens no session in the coming year. | Pick a future instant or date, or schedule on an instrument whose calendar has upcoming sessions. | info | No | 422 |
| DALP-173571 | `TRADING_VENUE_PENDING_MARKET_CHANGE_NOT_FOUND` | domain | The pending instrument change was not found. | The change id does not name a pending change of this instrument on the selected network. | Use a change id from the instrument's pending changes list. | info | No | 404 |
| DALP-173572 | `TRADING_VENUE_PENDING_MARKET_CHANGE_CONFLICT` | domain | The pending instrument change can no longer be cancelled. | Only a pending change, or one waiting to retry, can be cancelled. This one already ran, was cancelled, or is being applied right now, including while its transaction is still pending on the transaction queue. | Read the instrument's pending changes, and make a new change if this one already applied. | info | No | 409 |
| DALP-173573 | `TRADING_VENUE_PENDING_MARKET_CHANGE_TIME_REFUSED` | client | The pending instrument change's effective time cannot be used. | The pending change's effective time resolves to now or the past, the instrument has no trading calendar to resolve a date against, or its calendar opens no session in the coming year. | Pick a future instant or date, or date the change on an instrument with a trading calendar. | info | No | 422 |
| DALP-173651 | `TRADING_VENUE_CANCELLATION_BATCH_NOT_FOUND` | client | The cancellation batch was not found. | The batch id does not name a mass cancel recorded on this venue for the selected network. | Use a batch id from the venue's cancellation batches list. | info | No | 404 |
| DALP-174241 | `TRADING_VENUE_NOTIFICATION_NOT_FOUND` | client | The notification was not found. | The notification id does not name one of your notifications on the selected network. A notification addressed to someone else, and one older than the 90-day retention window, answer the same way. | Use a notification id from your notifications list for the selected network. | info | No | 404 |
| DALP-174261 | `TRADING_VENUE_PRICE_ALERT_NOT_EDITABLE` | client | The price alert can no longer be edited. | The alert already triggered. Only an active alert can change its level, percentage or direction. | Create a new alert for the instrument instead of editing the one that triggered. | info | No | 409 |
| DALP-174262 | `TRADING_VENUE_PRICE_ALERT_REFUSED` | client | The percentage alert cannot be set on this instrument. | A percentage alert moves from the previous official close of the instrument. Either the instrument has no previous official close yet, or the fall would put the target below one tick. | Without a previous close, set the alert on a price level or wait until a session closes. For an unreachable move, use a smaller fall. | info | No | 422 |
| DALP-174391 | `VENUE_FEE_SCHEDULE_INVALID` | client | The instrument fee schedule is invalid. | A fee type, amount range, target, or bound in the schedule is not valid, or the approval named belongs to another instrument. | Correct the fee schedule fields and submit the edit again. | info | No | 422 |
| DALP-174392 | `VENUE_FEE_SCHEDULE_CONCURRENT_EDIT` | client | The instrument fee schedule changed while this edit was open. | Another schedule version was recorded after the version this edit started from. | Reload the instrument fee schedule, reapply the change to that version, and submit it again. | info | No | 409 |
| DALP-174401 | `MARKET_RESUME_INSIDE_CUTOFF` | domain | The instrument cannot resume this close to the session close. | The venue sets a resume cutoff: a halted instrument stays halted from the cutoff before the session close until the close itself, so a resume always leaves time to trade. The response carries the close time and the cutoff in minutes. | Resume the instrument after the session closes, or ask a venue admin to shorten the resume cutoff in the listing rules. | info | No | 409 |
| DALP-174411 | `ESCROW_COMMIT_REFUSED` | domain | The venue escrow refused to commit this order. | The wallet's escrow commitment for the order did not go through: the wallet has not approved the venue escrow for the order's amount, its balance and free escrow balance together do not cover the order, its balance of the token is frozen, or the commitment was already given back. The response does not say which of these applied. | Approve the venue escrow for the order's amount, fund the wallet, or sign a new order when the commitment was given back, then place the order again. | info | No | 409 |
| DALP-174412 | `ESCROW_FREE_BALANCE_SHORT` | domain | The wallet's free escrow balance is below the amount to withdraw. | A withdrawal can only take what the venue escrow holds free for the wallet and token. The response does not state the free amount or the amount requested. The same code answers a wallet that is not one of the caller's. | Withdraw no more than the free balance, or cancel resting orders to free more of the escrow. | info | No | 409 |
| DALP-174413 | `ESCROW_WITHDRAWAL_REVERTED` | domain | The escrow withdrawal reverted. | The withdrawal transaction mined and reverted, so the balance stays in the venue escrow. The response does not carry the revert reason. | Check on the chain why the withdrawal transaction reverted, correct the cause, then request the withdrawal again. | info | No | 409 |
| DALP-175811 | `SETTLEMENT_OVERRIDE_REQUIRED` | domain | This parked fill needs an override to retry. | The fill was held for a reason that retrying is not expected to clear, so a plain retry is refused. | Review the held reason, then send the retry again with the override confirmation set. | info | No | 409 |
| DALP-181131 | `PLATFORM_TEMPLATE_HAS_TOKENS` | domain | Tokens were issued from this template. | One or more tokens were issued from the template, and each token keeps a link to it, so it cannot be deleted. | Keep the template. To stop new issuance from it, unpublish it or hide it from Issue asset. | info | No | 409 |
| DALP-182131 | `TOKEN_CREATE_FIXED_YIELD_ENDS_AFTER_MATURITY` | domain | The fixed yield ends after the bond's maturity date. | The fixed-treasury-yield endDate `{endDate}` is later than the maturity-redemption maturityDate `{maturityDate}`, both in Unix seconds. The yield pays every period up to its own end date, so coupons after maturity would stay claimable on a token holders can only redeem. | Set `featureConfigs.fixed-treasury-yield.endDate` at or before `featureConfigs.maturity-redemption.maturityDate` and resubmit the token creation request. | info | No | 422 |
| DALP-182132 | `TOKEN_FEATURE_ATTACH_FIXED_YIELD_ENDS_AFTER_MATURITY` | domain | The fixed yield would end after the bond's maturity date. | The fixed-treasury-yield endDate `{endDate}` is later than the maturity-redemption maturityDate `{maturityDate}`, both in Unix seconds. The yield pays every period up to its own end date, so coupons after maturity would stay claimable on a token holders can only redeem. | Set the `{feature}` `{field}` so the yield ends at or before maturity, then attach the feature again. | info | No | 422 |
| DALP-184651 | `CORPORATE_ACTION_RIGHTS_SUBSCRIPTION_ASSET_INVALID` | domain | The subscription asset of this rights issue cannot be the share token or the rights token. | Exercising a right pays the subscription price in the subscription asset. Naming the share token or the rights token would pay in the units the rights issue creates or exchanges. | Abort this rights issue, then declare a new one with a different token that is indexed in this system as its subscription asset. | info | No | 409 |
| DALP-184652 | `CORPORATE_ACTION_RIGHTS_TRADING_ENDED` | domain | Trading in these rights has already ended. | Whole rights minted after their trading end could never be traded or exercised before they expire, so the rights issue is not opened, previewed or confirmed. | Abort this rights issue, then declare a new one with a trading end and an expiry in the future. | info | No | 409 |
| DALP-184653 | `CORPORATE_ACTION_PRICE_UNADJUSTABLE` | domain | The reference price of this share cannot follow the split. | A stock split moves the reference price of a priced share by the inverse of the share ratio. The price feed of this share is inactive, not indexed yet, has never answered or quotes something other than a fiat currency; or the new price would round to zero at the 8 fraction digits of the price feeds; or the system has no price-feed factory or eligible price signer to declare the new price. | Fix the price feed or the price signer of the share, or choose a ratio that keeps the price above zero, then preview again. | info | No | 409 |
| DALP-184654 | `CORPORATE_ACTION_PRICE_DRIFTED` | domain | The reference price of this share moved after the split was confirmed. | The split divided the supply, but the share price is neither the price planned before the split nor the price planned after it, so sending the planned price would overwrite a price someone set in between. | Set the share price to the planned price after the split with the Set price action, or back to the price before the split, then confirm the action again. | info | No | 409 |
| DALP-184671 | `CORPORATE_ACTION_RIGHTS_WINDOW_CLOSED` | domain | The subscription period of this rights issue is not open. | Rights can be exercised only between the start and the end of the subscription period. Rights not exercised by the end lapse with no value. | Exercise inside the subscription period shown on the rights issue. After it ends, the rights are lapsed and cannot be exercised. | info | No | 409 |
| DALP-184672 | `CORPORATE_ACTION_RIGHTS_EXERCISE_INVALID` | domain | These rights cannot be exercised for that amount. | An exercise needs a completed tradable rights issue, a whole number of rights, and no more rights or deposit than the exercising wallet holds. The subscription payee cannot exercise. Excess shares can be applied for only after every right is exercised. A key whose exercise was refused cannot be reused. The rights issue needs a subscription payee. | Exercise a whole number of rights up to your rights balance, with enough subscription asset to pay for them, from a wallet other than the subscription payee of the rights issue. | info | No | 409 |
| DALP-184673 | `CORPORATE_ACTION_RIGHTS_EXERCISE_INELIGIBLE` | domain | This investor cannot exercise these rights. | The share token would reject the new shares this exercise earns, because the investor is not eligible to hold them, or their eligibility could not be verified. | Ask the issuer to check the investor's identity and eligibility for the share token, then exercise again. | info | No | 409 |
| DALP-184674 | `CORPORATE_ACTION_RIGHTS_CLOSE_NOT_READY` | domain | The rights issue cannot be closed yet. | Closing issues one new share per exercised right. It needs a completed tradable rights issue of this token whose subscription period has ended, with every exercise settled, and no other close already open or done for it. | Wait until the subscription period ends and every exercise settles, name a completed rights issue of this token, and do not close the same rights issue twice. | info | No | 409 |
| DALP-184675 | `CORPORATE_ACTION_RIGHTS_PAYEE_INVALID` | domain | This rights issue names a subscription payee that cannot receive the payments. | Every exercise pays the subscription price and hands in the rights at the account the rights issue names. That account must be registered to your organization's on-chain identity on this token's network, as the organization's executor wallets are. A member's wallet, which is registered to the member's own identity, another organization's account, an unregistered account, an account on another network and the wallet the rights issue is declared from do not qualify. It must also be able to receive the rights and the subscription asset, so a maker cannot route the payments to an account the approver never reviewed. | Name an account registered to your organization's on-chain identity on this token's network, which must be able to receive the rights and the subscription asset and cannot be a token or the zero address, then declare the rights issue again. | info | No | 409 |
| DALP-184676 | `CORPORATE_ACTION_RECONCILIATION_BREAK_OPEN` | domain | An open reconciliation break holds the snapshot of this corporate action. | This mirror token has a reconciliation break, first seen on or before the record date, that is still open or under investigation. Its holders on chain may not match the custodian's or registrar's statement, so a snapshot taken now could pay or allot the wrong holders. | Resolve the break, or write it off through its approval, then preview the corporate action again. | info | No | 409 |
| DALP-184677 | `CORPORATE_ACTION_CUSTODIAN_FREEZE_REQUIRED` | domain | The custodial contracts holding this token are not frozen for this corporate action. | A stock split, bonus or similar action re-sizes the records that escrows, token sales, settlements and airdrops keep for their owners, after the units behind those records moved. To keep records and units equal, each of those contracts refuses every movement of the token from the record date until the action's step lands. The action needs a record date that is still ahead when it is created, and every contract holding the token must carry the action's freeze marker when it is confirmed. One did not: the record date is missing or has passed, or a contract began holding the token after the action was created. | Create the action again with a record date that is still ahead, so the freeze can be installed on every contract holding the token. If a contract began holding the token after the action was created, abort the action first. | info | No | 409 |
| DALP-185931 | `TRADING_VENUE_EXPORT_TOO_LARGE` | client | The export has too many rows for an XLSX file. | An XLSX worksheet holds at most 1,048,575 rows below its header, and the export holds more orders. | Download the export as CSV, which has no row limit. | info | No | 422 |
| DALP-188071 | `ORDER_STREAM_LIMIT_REACHED` | client | The order stream was not opened. | The caller already holds as many open order streams on this venue as one caller may. | Close an order stream the caller no longer reads, then open this one again. | info | Yes | 429 |
| DALP-190191 | `PARTICIPANT_STATUS_FINAL` | domain | A terminated participant account cannot change status. | Terminated is a final account status, so a terminated participant account cannot change status. | Keep the account terminated, or onboard the holder as a new participant. | info | No | 409 |
| DALP-190192 | `PARTICIPANT_STATUS_UNCHANGED` | domain | The participant account already has this status. | The participant account already has this status and these restrictions, and no change is scheduled, so nothing was recorded. | Read the current status and send a different status or restrictions. | info | No | 409 |
| DALP-190871 | `TOKEN_FEATURE_ATTACH_TOKEN_NOT_CONFIGURABLE` | domain | This token cannot take the `{feature}` feature. | The token was issued by a classic asset factory without the configurable-features interface, so it keeps no feature list and no feature can be attached to it. | Leave the token without features, or issue the instrument as a DALP asset when it needs `{feature}`. | info | No | 422 |
| DALP-190872 | `TOKEN_CREATE_TEMPLATE_FEATURES_UNAVAILABLE` | client | The template's features do not apply to a classic asset. | The request's `type` names a classic asset type, whose token cannot take features, and the template in `data.templateId` declares the features in `data.features`. Linking the template would present a token without those features as an instance of it, so nothing was deployed. | Create the token as a DALP asset from this template, or create the classic asset type without `templateId`. | info | No | 422 |
| DALP-191376 | `TRADING_VENUE_PARTICIPANT_NOT_FOUND` | client | The wallet is not a participant of this venue. | The wallet is not admitted to the venue, is on no instrument's participant list and is not blocked on it. When a broker is assigned, the broker is not a participant or the wallet belongs to no participant account. | Use a wallet from the venue's participants, or add the wallet to a private instrument first. | info | No | 404 |
| DALP-193271 | `VENUE_ROLE_EXPIRY_INVALID` | client | The role grant cannot end at that time. | A time-boxed venue role grant must end between one minute and one year after the request, and an administrator whose own role ends must grant roles that end before their own does. | Send a validUntil inside that window, or have an administrator without an expiry make the grant. | info | No | 422 |
| DALP-193272 | `VENUE_ROLE_OPERATIONS_ADMIN_IN_USE` | domain | The role cannot be granted to the operations signer now. | The platform's operations signer holds the role that administers this venue role only while it ends a time-boxed venue role, and it renounces that role once the change lands, so a grant to it now would be taken away again. | Wait until the platform has finished ending the expired venue role, then grant the role again, or grant it to another wallet. | info | No | 409 |
| DALP-193273 | `ESCROW_REFUND_NOT_EXHAUSTED` | domain | The order holds no exhausted escrow refund. | The order holds no exhausted escrow refund on this venue: its commitment was never left unreleased, its refund is still being retried, or its commitment already reads as released. | Retry or reconcile only an order the venue logged as exhausting its refund, and read the order's commitment from the venue's commitments list. | info | No | 409 |
| DALP-193274 | `ESCROW_REFUND_STILL_LOCKED` | domain | The venue escrow still holds units against this order's commitment. | The venue escrow still holds units against the order's commitment, so its refund has not landed on chain and releasing the commitment would record funds as returned that the escrow still holds. | Retry the refund once its revert cause is fixed, or book the lock back with the escrow's reclaim or the venue's refundOrder and reconcile again after it confirms. | info | No | 409 |
| DALP-196811 | `reporting.venue-archive.HOLD_IMPERSONATED` | permission | A legal hold needs your own session. | The session is acting as another user, so it cannot place a legal hold or count as either of the two people a release needs. | Ask that duty manager to sign in and act themselves, or end the impersonation and use your own session. | info | No | 403 |
| DALP-199481 | `ASSISTANT_AGENT_ITEM_NOT_FOUND` | client | The assistant finding was not found. | No assistant finding you may see has that id in your organisation. | Open the finding from the Actions inbox, or list the assistant findings again. | info | No | 404 |
| DALP-199482 | `compliance.price.RESOLVER_MISSING` | domain | This system has no price resolver for a capital-raise limit. | A capital-raise limit converts money raised with the system's price resolver, and this system has none installed. | Install the price resolver add-on on this system, then add the limit again. | info | No | 409 |
| DALP-199541 | `ASSISTANT_MCP_CLIENT_NOT_FOUND` | client | The MCP client was not found. | No MCP client connected to your organisation has that id, or the caller holds no grant of it to revoke. An owner revokes any client of the organisation; another member revokes only the client they connected. | List the connected MCP clients and use the id of one you may revoke. | info | No | 404 |
| DALP-199551 | `AGENT_ACTION_REFUSED` | domain | The agent may not take this action. | The agent's mandate, its state, or its organisation's kill switch does not allow this action. | Read the refusal reason, then change the action, or ask the organisation owner to change the mandate. | info | No | 409 |
| DALP-199552 | `AGENT_ORGANISATION_HALTED` | domain | The organisation's agent kill switch is on. | The organisation's agent kill switch is on, so no agent can be created or act. | Ask the organisation owner to turn the agent kill switch off. | info | No | 409 |
| DALP-199553 | `AGENT_NOT_ACTIVE` | domain | The agent is not active. | The agent is still being set up, or its mandate was revoked, and a revoked mandate is final. | Wait until the agent is active, or create a new agent to grant a new mandate. | info | No | 409 |
| DALP-199554 | `AGENT_MANDATE_INVALID` | client | The mandate cannot be enforced as written. | The mandate breaks a rule the chain enforces. `data.rule` names the rule, and `data.target`, `data.asset` or `data.selector` names the entry that breaks it. | Change the entry `data` names: list each contract, asset and function once, give an asset limit to every contract the agent may call transfer, transferFrom or approve on, allow only those three functions on an asset with a limit, and set a future expiry. | info | No | 400 |
| DALP-199555 | `AGENT_OWNER_REQUIRED` | auth | Only the organisation owner can do this. | Only the organisation owner creates agents, changes their mandates and uses the kill switches. | Ask the organisation owner to make this change. | info | No | 403 |

The previous page is [DALP-20000 to DALP-29999](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference/dalp-20000-29999). The next page is [DALP-200000 to DALP-299999](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference/dalp-200000-299999).


# DALP-12000 to DALP-12099

Source: https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference/dalp-12000-12099
Cause, fix, HTTP status and retry flag for every Platform API error with a code from DALP-12000 to DALP-12099.

This page lists the 69 errors the Platform API can return with a code from DALP-12000 to DALP-12099. Match the `id` in the error envelope to the DALP Code column, then read Retryable and Suggested Fix. The [Platform API error reference](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference#how-to-use-this-reference) explains each column, including Severity, and the [DALP error index](https://docs.settlemint.com/docs/api-reference/errors) lists the page for every code range.

| DALP Code | Machine name | Category | Message | Why | Suggested Fix | Severity | Retryable | HTTP Status |
| --- | --- | --- | --- | --- | --- | --- | --- | --- |
| DALP-12012 | `TRANSACTION_PREPARATION_EXPIRED` | domain | The transaction preparation has expired. | The authorization window ended before the prepared operation was finalized. | Prepare the operation again and authorize the new preparation. | info | No | 410 |
| DALP-12018 | `CUSTODY_ACCOUNT_NOT_ON_REQUESTED_NETWORK` | permission | The caller's custody account lives on a different network. | This read is scoped to network `{{chainId}}`, the network the request resolved to, and the signed-in participant holds no custody account there. Custody accounts are registered one network at a time, so an account created on another network owns nothing here and no role grant changes that. | Switch the active network to the one that holds the caller's custody account, or send `X-Chain-Id` with that network's chain id. Ask an administrator to provision a custody account on network `{{chainId}}` when the caller needs access there. | info | No | 403 |
| DALP-12019 | `REQUEST_CUSTODY_ACCOUNT_UNAVAILABLE` | client | The selected custody account cannot sign for this request. | Signing this request needs a custody account that is active, eligible on the network the request resolved to, and bound to a live provider signer. The account in `data.custodyAccountId` misses at least one of those: it is still provisioning, its account or organisation context left the active state, its provider reports an unhealthy signer, or its managed key binding is gone. When `data.custodyAccountId` is absent, the request named no account and the signed-in participant holds no eligible primary account on this network. When `data.reason` is present, this organisation cannot drive the account's wallet and the value names the capability it lacks, the same reason the custody-account list reports for that account. On a network where the participant is not set up yet, the identity, wallet binding and smart wallet that signing needs are still being created, failed to be created, or wait for the wallet that pays for them to be funded. | Read the custody-account list for the network this request targets, pick an account it reports as active and eligible, and send that identifier. Ask an administrator to provision or repair an account on that network when the list offers none. | info | No | 409 |
| DALP-12020 | `TOKEN_CLAIM_VALIDATION_FAILED` | client | The token claim request does not match the token's indexed identity state. | Before it signs a claim, the platform checks the requested topic against the token's topic registry chain, the claim data against the topic scheme, and the claim it is asked to revoke against the indexed claims; one of those checks refused the request. `data.reason` names which. | Read `data.reason`, then correct the topic, the claim data, or the claim selection to match the token's topic scheme and indexed claims. | info | No | 422 |
| DALP-12021 | `TOKEN_LIFECYCLE_VALIDATION_FAILED` | client | The token is not in a state that accepts this lifecycle change. | The platform checked the indexed token before it queued the transaction, and one lifecycle check failed. `data.reason` names it, for example no redeemable amount, not a bond, maturity not confirmed, solvency still unknown, a bond contract without its denomination balance, or schedule terms the factory refused. | Read the token, then send the request that matches its current state: a positive redeemable amount, a bond that is not mature yet, or a bond contract funded with its denomination asset. | info | No | 422 |
| DALP-12022 | `TOKEN_TRANSFER_APPROVAL_VALIDATION` | client | The transfer-approval request does not match the token's indexed identity state. | The platform resolves the wallet in the token identity registry and checks that the acting executor identity is an approval authority; one of those lookups found no indexed match. `data.reason` names which one. | Register the wallet in the token identity registry, or select an executor whose identity is an approval authority, wait for indexing, then retry. | info | No | 422 |
| DALP-12023 | `TOKEN_FORCED_TRANSFER_MISSING_ITEM` | client | The forced-transfer request has no complete transfer item. | A forced transfer moves tokens from an owner to a recipient. The request left out the owner, the recipient or the amount of at least one item, or an item names a DALP escrow as the owner, which a forced transfer cannot draw from. | Send each item with an owner, a recipient and an amount, and do not name a DALP escrow as the owner. Then resubmit. | info | No | 422 |
| DALP-12024 | `TOKEN_BATCH_TRANSFER_FROM_UNSUPPORTED` | client | This token does not support a batch `transferFrom`. | The token contract exposes a single-item `transferFrom` only. The platform refuses the batch before it signs anything, so no partial batch reaches the chain. | Submit each `transferFrom` as its own request. | info | No | 422 |
| DALP-12025 | `TOKEN_ACCESS_INTERFACE_UNSUPPORTED` | domain | The token does not implement the interface this operation needs. | `data.requiredInterfaces` names the interface the token contract lacks: `PAUSABLE`, `CUSTODIAN` or `IRecoverable`. `data.tokenAddress` names the token. | Run this operation on a token that implements the named interface. | info | No | 422 |
| DALP-12026 | `TOKEN_PRICE_UNSUPPORTED_TOKEN` | client | Prices cannot be set on this token. | Setting a price needs the token's access-control interface to confirm the administrator; the indexed token reports neither ERC-3643 nor the supported SMART interface. `data.tokenAddress` names the token. | Use a supported token contract, or correct the indexed token interface metadata, then retry. | info | No | 422 |
| DALP-12027 | `LEGACY_BOND_FEATURE_TREASURY_REQUIRED` | domain | This bond funds redemptions from its maturity-redemption feature treasury. | The bond has an attached maturity-redemption feature, and that feature's configured treasury pays redemptions. The legacy top-up route writes to the bond contract instead, so the deposit would never fund a redemption. | Use the maturity-redemption treasury top-up endpoint for this bond. | info | No | 422 |
| DALP-12028 | `STRICT_COMPLIANCE_PARAMS_INVALID` | client | The compliance parameters do not match the selected module schema. | The platform decodes each module's parameters against that module's own schema before it encodes them for the chain; `data.issues` lists every field that failed. | Correct each field listed in `data.issues`, then submit the request again. | info | No | 422 |
| DALP-12029 | `ORGANIZATION_SUBMISSION_SIGNER_CLAIM_PURPOSE_MISSING` | domain | The organization signing wallet holds no claim-signer key on the issuer identity. | Signing a claim needs the organization submission wallet to hold a key with the claim-signer purpose on the issuer identity. The indexed identity `data.issuerIdentityAddress` holds no such key for `data.walletAddress`. | Add the claim-signer purpose key for the wallet on the organization identity, wait for indexing, then retry the submission. | info | Yes | 422 |
| DALP-12030 | `FEATURE_CONFIG_INVALID` | client | The token feature configuration is not accepted. | The token create workflow validates every feature configuration against the feature catalog before it deploys; at least one feature configuration failed that validation. | Correct the feature configuration named in the message, then submit the token creation again. | info | No | 422 |
| DALP-12031 | `UNPROCESSABLE_ENTITY` | client | The request is well formed but cannot be applied to the current state. | The route understood the request and refused it against the current domain state. The refusing check publishes no error entry of its own, so this general 422 stands in for it. | Correct the request or the state it depends on, then retry. If you contact support, send the X-Request-Id response header. | info | No | 422 |
| DALP-12032 | `TOKEN_CLAIM_INDEXED_STATE_UNAVAILABLE` | dependency | The indexed state this claim needs is not recorded yet. | The platform authorizes a token claim against indexed state: the token's on-chain identity, the claim registries of the active system, and the acting wallet's active registration in the identity registry. The indexer has not recorded one of them yet. `data.reason` names which. | Wait for the indexer to catch up, then retry. If it does not clear, check that the token identity and the issuer registration exist on chain. | error | Yes | 503 |
| DALP-12033 | `WALLET_VERIFICATION_REQUIRED` | client | This operation needs wallet verification. | The operation signs with the caller's wallet, and the request carried no `walletVerification` block, so the platform stored nothing. | Add `walletVerification` with the method this account has enrolled, a PIN, an authenticator code, a recovery code, or an identity-provider code, then send the request again. | info | No | 400 |
| DALP-12034 | `WALLET_VERIFICATION_NOT_CONFIGURED` | auth | The requested wallet verification method is not enrolled. | The request named a wallet verification method this account has not enabled, so no credential exists to check it against. | Enroll the method in wallet security settings, or send a method this account already holds. | info | No | 401 |
| DALP-12035 | `WALLET_VERIFICATION_INVALID` | permission | The wallet verification credential was not accepted. | The supplied credential does not match the enrolled one, or it was already used. `data.remainingAttempts` reports how many attempts remain before verification locks. | Enter the current code or PIN and send the request again. A recovery code works once, so use a fresh one. | info | No | 403 |
| DALP-12036 | `WALLET_VERIFICATION_THROTTLED` | permission | Wallet verification is locked after repeated failures. | Wallet verification failed too many times in a row for this account, so the platform locked it and stored nothing. | Wait the number of seconds in `data.retryAfterSeconds`, then verify again. | info | No | 429 |
| DALP-12037 | `WALLET_VERIFICATION_CAPACITY` | operational | Wallet verification is at capacity. | Wallet verification admission is full, so the platform stored nothing. The same request can succeed later without any change. | Wait the number of seconds in `data.retryAfterSeconds`, then send the request again. | error | Yes | 503 |
| DALP-12038 | `WALLET_VERIFICATION_DEPENDENCY_FAILED` | dependency | Wallet verification could not complete. | A step wallet verification depends on did not complete, such as reading the wallet credential or the last wallet security change, storing or redeeming the step-up challenge, or settling the proof within its window. The platform stored nothing. | Retry after a short backoff. If it continues, contact support with the request id. | error | Yes | 503 |
| DALP-12048 | `CORPORATE_ACTION_NOT_FOUND` | domain | No Corporate Action with this identifier exists on the token. | The identifier does not name a Corporate Action on this token, or it belongs to another token. | List the token's Corporate Actions and use an identifier from that list. | info | No | 404 |
| DALP-12049 | `CORPORATE_ACTION_WRONG_STATUS` | domain | The Corporate Action is not in a status that accepts this operation. | Preview, approval, and confirm follow the drafted, previewed, approved, executing lifecycle, and this run has moved past the status the operation needs. | Read the record, then send the operation its current status accepts. | info | No | 409 |
| DALP-12050 | `CORPORATE_ACTION_DIVIDEND_UNLINKED` | domain | This Corporate Action needs a linked dividendId. | The declared dividend has not indexed onto this Corporate Action yet, so the dividend-backed operation cannot resolve its target. | Wait for the declare to index, then retry. | info | Yes | 409 |
| DALP-12051 | `CORPORATE_ACTION_SNAPSHOT_NOT_READY` | domain | The cash-dividend snapshot is not ready. | The record date has not passed yet, or its block has not reached finality, or a class's holder amounts are still indexing, so there is no final snapshot to preview or confirm. | Preview again after the record date has passed and its block is final, then confirm. | info | Yes | 409 |
| DALP-12052 | `CORPORATE_ACTION_PREVIEW_REQUIRED` | domain | Confirm requires a stored preview. | Confirm applies the allocations a preview computed, and this Corporate Action has none stored. | Request preview first, then confirm the previewed allocations. | info | No | 409 |
| DALP-12053 | `CORPORATE_ACTION_PREVIEW_MISMATCH` | domain | The confirm does not match the stored dividend-yield snapshot preview. | The merkle root, totalEntitled, or totalRequired differs from the stored preview, or an indexed holder balance no longer converts to token base units. | Preview again and confirm with the exact values that preview returns. | info | No | 409 |
| DALP-12054 | `CORPORATE_ACTION_COMPLETE_ON_CREATE` | domain | Corporate Actions of this type complete on create. | bondCoupon, maturityRedemption, and conversion name an attached feature program and settle when created, so there is no drafted run to preview or confirm. | Operate the linked program through its own feature routes. | info | No | 409 |
| DALP-12055 | `CORPORATE_ACTION_TOKEN_PAUSED` | domain | Confirm failed because the token is paused. | Pause blocks mint and burn, and this Corporate Action applies its allocations through them. | Unpause the token, then confirm again. | info | No | 409 |
| DALP-12056 | `CORPORATE_ACTION_SNAPSHOT_DRIFT` | domain | Confirm refused because the holder book changed after preview. | Holder balances, rights exercises or the rights that holders still hold moved after preview, or a funded coordinated distribution no longer matches its approved split or class snapshot, so the stored allocations no longer apply. A confirm refused before execution applies nothing. A rights-issue close whose new shares are already minted, or a coordinated distribution whose pool is already funded, keeps what already landed. The Corporate Action stays open until you abort it. | Abort this Corporate Action, then create a new one and preview it against the current holder book. For a rights-issue close whose new shares are already minted, raise the next close as a follow-up of the aborted one, which mints no share again. | info | No | 409 |
| DALP-12057 | `CORPORATE_ACTION_CHILD_NOT_EMPTY` | domain | A spin-off or tradable rights issue requires an empty child token. | The child token already has holders, gained holders after the preview, or is the parent token itself, so the allocations cannot define its initial distribution. | Use an existing empty child token, or preview again with one. | info | No | 409 |
| DALP-12058 | `CORPORATE_ACTION_CHILD_UNAUTHORIZED` | domain | A spin-off or tradable rights issue requires supply management on the child token. | Minting the allocations onto the child token needs the supply management role, and the caller does not hold it there. The action is refused when it is created, previewed or confirmed. | Grant supply management on the child token to the caller, or choose a child token the caller manages, then retry. | info | No | 409 |
| DALP-12059 | `CORPORATE_ACTION_HISTORICAL_BALANCES` | domain | Holder balances for this record date are not available yet. | The indexer has not covered the record date, a past record date needs the attached historical-balances feature, or the record date is before the token existed. | Use a record date on or after the token was created, wait for indexing to catch up, or attach historical-balances, then retry. | info | Yes | 409 |
| DALP-12060 | `CORPORATE_ACTION_SALE_MISSING` | domain | A rights-issue tokenSale path requires an existing tokenSaleId. | The rights issue was created without a token sale, so sale-backed operations have no sale to act on. | Create the rights issue with a tokenSaleId, or use the allotment path. | info | No | 409 |
| DALP-12061 | `CORPORATE_ACTION_SALE_DISABLED` | domain | The token-sale feature is off in this deployment. | Sale-backed rights-issue operations need the token-sale feature, and this deployment does not enable it. | Use the allotment path. | info | No | 409 |
| DALP-12062 | `CORPORATE_ACTION_SALE_UNKNOWN` | domain | No indexed token sale exists at the given address. | The sale contract has not been indexed yet, or the address does not hold a token sale. | Wait for indexing to catch up, verify the address, then retry. | info | Yes | 409 |
| DALP-12063 | `CORPORATE_ACTION_SALE_TOKEN_MISMATCH` | domain | The token sale sells a different token, not this Corporate Action's token. | Rights-issue sale operations must target a sale whose sale token is the Corporate Action's token. | Point the Corporate Action at a sale that sells this token. | info | No | 409 |
| DALP-12065 | `CORPORATE_ACTION_IDEMPOTENCY_CONFLICT` | domain | This idempotency key was already used for a different request. | The key already recorded a Corporate Action, declaration or rights exercise with different terms or from another executing wallet, so replaying it would change what the first request recorded. A declaration or rights exercise under this key can also still be in progress. | Send a new key for a new request, or repeat the identical original request from the original wallet. When the message says the first request is still in progress, send the same request again later to read the outcome. | info | No | 409 |
| DALP-12066 | `CORPORATE_ACTION_TOKEN_UNINDEXED` | domain | The indexer carries no decimals for the token yet. | Allocation math needs the token's decimals from the indexer, and the token has not indexed. | Wait for the token to index, then retry. | info | Yes | 409 |
| DALP-12067 | `CORPORATE_ACTION_IN_FLIGHT` | domain | Another Corporate Action is in flight for this token. | One composition Corporate Action runs at a time per token; a run that has not completed or been aborted blocks a second one and blocks primitive mint and burn. | Wait for the in-flight run to complete or abort it, then retry. | info | Yes | 409 |
| DALP-12069 | `CORPORATE_ACTION_FOLLOW_UP_UNKNOWN` | domain | The Corporate Action this run follows up on is not on this token. | `followsUpOn` fails when no such run exists on this token, when the follow-up changes the followed stock split's terms, or when that run still has an execution to reconcile. | Send the identifier of a Corporate Action on this token, or omit `followsUpOn` to start a fresh run. | info | No | 409 |
| DALP-12071 | `CORPORATE_ACTION_PROGRAM_MISSING` | domain | This Corporate Action needs a feature the token does not have attached. | A dividend, coupon, redemption or conversion Corporate Action dispatches to the token's own feature contract, and this token carries no attached one for it. The message names the token or class whose feature is missing or does not match, such as a class without dividend yield or a denomination that differs. | Attach the feature this Corporate Action type runs on, then retry. | info | No | 409 |
| DALP-12073 | `WORKFLOW_PROGRESS_DECODE_ERROR` | dependency | Stored workflow progress is malformed. | The saved workflow progress does not match a supported version, so Corporate Action recovery cannot determine which chunks completed. | Contact support with the X-Request-Id response header. The stored workflow progress needs an operator repair before the Corporate Action operation can continue. | error | No | 500 |
| DALP-12074 | `INDEXER_BARRIER_TIMEOUT` | dependency | The transaction succeeded on-chain, but its indexed data is not ready. | The indexer did not finish projecting the transaction's block before the request deadline. The write has already succeeded and must not be submitted again. | Do not resubmit the mutation. Read the transaction request with `data.transactionId` at `GET /api/v2/transaction-requests/:transactionId`, then repeat the read after a short wait. If the read keeps timing out, ask an operator to check indexer errors for `data.chainId` at or before `data.blockNumber`. | error | No | 504 |
| DALP-12075 | `TOKEN_CREATE_ASSET_FAMILY_DEPRECATED` | client | This deployment does not create new assets of that legacy family. | The requested asset family stays supported for deployments that already issue it, but the platform creates no new assets of that family. The deployment has not opted in with `features.legacyAssetCreation`, so the creation is refused before any contract is deployed. | Create the asset from a DALP asset template instead. Set `FEATURE_LEGACY_ASSET_CREATION=true` on this deployment when it still issues legacy assets. | info | No | 422 |
| DALP-12076 | `TOKEN_OPERATION_INPUT_INVALID` | client | The token operation cannot be built from the fields supplied. | A field the operation needs is missing, or the combination requested has no on-chain form: a bond without a maturity date, a role change whose target shape does not parse, a compliance module change without the address that identifies the module, or a batch transfer variant the token does not implement. | Correct the field named in the message and submit the operation again. | info | No | 422 |
| DALP-12077 | `TOKEN_COMPLIANCE_MODULE_BINDING_UNRESOLVED` | domain | The compliance module named cannot be resolved to a single binding. | Configuring a compliance module addresses one bound module instance on the token. The token has no binding for the module type requested, or it has more than one and the single-instance request cannot say which. | Bind the module to the token first, or address the instance directly with `instanceAddress` when the token holds several of that type. | info | No | 422 |
| DALP-12078 | `TOKEN_CREATE_DUPLICATE` | domain | An asset with the same name, symbol, and decimals already exists. | The factory refuses a second deployment of an asset whose name, symbol, and decimals match one it already deployed, so the address it would produce is the address of the existing asset. | Use the existing asset, or change the name, symbol, or decimals before creating a new one. | info | No | 422 |
| DALP-12079 | `TOKEN_CREATE_RECOVERY_FAILED` | operational | The asset was already deployed, but the platform could not recover its address. | The creation reverted because the access manager for this asset exists already, which means an earlier attempt deployed it. Recovery reads that earlier asset back so the request can answer with it, and that read found nothing to return. | Look the asset up by name and symbol in the asset list. Contact support with the request id if it is not there. | error | No | 422 |
| DALP-12080 | `TOKEN_PRICE_INPUT_INVALID` | domain | The initial price cannot be recorded as supplied. | An initial price is stored against the denomination asset at a fixed precision. The price supplied is not well-formed, or it cannot be represented at that precision without losing value. | Supply a price with fewer decimal places, or omit the initial price and set it after creation. | info | No | 422 |
| DALP-12081 | `TOKEN_PRICE_DENOMINATION_UNUSABLE` | domain | The denomination asset cannot back a price feed. | A price feed quotes the asset in its denomination asset, and reads that asset's ERC-20 `symbol()` and `decimals()` to name and scale the quote. The denomination asset does not answer both, or its symbol is not one a feed can quote. | Denominate the asset in an ERC-20 that reports a readable symbol and decimals, or create it without an initial price. | info | No | 422 |
| DALP-12082 | `TOKEN_PRICE_FEED_SIGNER_MISSING` | domain | The organization has no signer for price feed submissions. | A price feed update is signed by the organization's own feed signer, and the active organization has none provisioned. | Provision the organization's feed signer, then submit the price again. | info | No | 422 |
| DALP-12083 | `TOKEN_PRICE_FEED_FACTORY_MISSING` | domain | This deployment has no price feed factory. | Creating a price feed calls the feeds factory of the active system, and no feeds factory address is configured for it. | Install the feeds factory on this system, or create the asset without an initial price and set the price later. | error | No | 422 |
| DALP-12084 | `TOKEN_PRICE_UPDATE_FAILED` | operational | The price update did not complete. | The workflow that writes the new price to the asset's feed stopped before the feed was updated. The recorded price is the one that was there before the request. | Read the asset's current price, then submit the update again. | error | No | 422 |
| DALP-12085 | `TOKEN_CHAIN_UNAVAILABLE` | operational | The chain this operation targets could not be reached. | The operation needs the chain the token lives on, and the network is not configured on the platform, or the chain did not answer the reads the next step needs. | Check that the network is configured and reachable, then submit the operation again. | error | No | 422 |
| DALP-12086 | `TOKEN_WRITE_RECEIPT_INCOMPLETE` | operational | The transaction landed but its receipt does not describe the result. | The platform reads the outcome of a token write out of the transaction receipt: the hash, the block, and the event the step emits. One of them is absent, so the platform cannot say what the write produced. | Check the asset's current on-chain state before submitting the operation again, and send the request id to support if the state does not explain the outcome. | error | No | 422 |
| DALP-12087 | `TOKEN_WRITE_REVERTED` | domain | The contract rejected this token write. | The write reached the contract and the contract refused it. The on-chain state is unchanged, and the message names the condition the contract enforced. | Correct the operation against the asset's current on-chain state, then submit it again. | info | No | 422 |
| DALP-12088 | `TOKEN_WRITE_OUTCOME_UNKNOWN` | operational | Whether this token write completed could not be established. | The platform accepted the write but could not confirm its outcome, for example because the write still awaits approval. The write may still complete, or it may already have completed. | Do not resubmit this write until you know its outcome. When the response includes a transactionId, read the transaction request with that ID until it settles. Otherwise read the asset's on-chain state, such as the held roles after a role change. If the outcome stays unknown, give support the X-Request-Id value from the response. If the transaction request stays in `DEAD_LETTER`, give its transaction id to an Organisation owner, an Organisation admin or a Platform admin. Any of them can force-fail it with `POST /api/v2/transaction-requests/{transactionId}/transitions` and `action: "fail"`; an Organisation owner or a Platform admin can also force-fail it in the Console under Organisation settings, Platform status. | error | No | 422 |
| DALP-12089 | `TOKEN_FUNDING_PAUSE_FAILED` | operational | The operation could not pause for the wallet to be funded. | When a wallet cannot pay for its next transaction the operation pauses and records a funding requirement against the organization. Recording that requirement failed, so the operation stopped instead of waiting. | Fund the wallet named in the message, then submit the operation again. | error | No | 422 |
| DALP-12090 | `TOKEN_CLAIM_ISSUE_FAILED` | operational | A claim this asset needs could not be issued. | A new asset is issued the identity claims its configuration implies, each as its own step. One of those steps stopped for good, so the asset exists without that claim. | Issue the missing claim on the asset's identity, then continue. Send the request id to support if issuing it fails the same way. | error | No | 422 |
| DALP-12091 | `TOKEN_WORKFLOW_FAILED` | operational | The token workflow stopped for good. | A step in the workflow failed in a way none of the named terminal conditions covers, so the operation cannot continue and will not be retried. | When the response includes data.transactionId, read that transaction request to see which calls landed. Otherwise read the asset's current state to see how far the operation got. Then send the request id to support. | error | No | 422 |
| DALP-12092 | `TOKEN_QUEUE_WRITE_REFUSED` | domain | This token write ended without completing. | The write did not complete. The platform stopped it before it reached the contract because it breaks a queue rule, such as a role change that plans more calls than one user operation holds, or an idempotency key reused from a failed attempt. Or the queue ended it: it was cancelled, the contract reverted it, or the sending wallet cannot pay for it. In a role change from an EOA executor wallet, the platform undoes every earlier call when a later call fails for a reason other than gas, or when it cannot read the held roles before a call. A write stopped before the contract, or reverted by it, leaves the token unchanged. | When the response includes data.transactionId, read that transaction request before retrying. Read the message for the condition the queue named, correct it, then submit the write with a new idempotency key. When the message says a role-change call could still land, read the held roles before you submit again. When it says the held roles could not be read, check that the chain is reachable, then submit with a new idempotency key. When it says the wallet needs funding, fund it, then submit the write again. | info | No | 422 |
| DALP-12094 | `TOKEN_RECOVER_ERC20_NOT_ERC20` | domain | The contract at `{erc20Address}` is not an ERC-20 token. | Recovering an ERC-20 balance needs the token's live symbol() and decimals(), and the address has no contract code or does not answer those reads. | Send the address of an ERC-20 contract held by this token, then retry. | info | No | 422 |
| DALP-12095 | `TOKEN_METADATA_VALUES_INVALID` | client | Off-chain metadata values for token `{tokenAddress}` do not match its template. | The token's asset-type template declares a type, allowed options, or bounds for each off-chain metadata key, and at least one submitted value falls outside them. Every rejected key is listed with its reason. | Correct the listed keys against the template's field definitions, then submit the metadata again. | info | No | 400 |
| DALP-12096 | `TOKEN_METADATA_OFFCHAIN_IMMUTABLE` | client | Off-chain metadata key `{key}` on token `{tokenAddress}` is immutable and already set. | The token's asset-type template marks this off-chain key immutable, and a value for it is already stored, so it can neither change nor be removed. | Leave the stored value in place, or resubmit it unchanged alongside the other keys. | info | No | 400 |
| DALP-12097 | `CORPORATE_ACTION_CASH_LEG_UNDERFUNDED` | domain | The paying treasury cannot cover this redemption's cash leg. | The treasury holds less of the denomination asset than the announced burns are priced at, and nothing reserves the cash, so a run started now would stop part-paid with tokens already burned. | Fund the paying treasury with the denomination asset, then confirm again. | info | Yes | 409 |
| DALP-12098 | `CORPORATE_ACTION_CASH_LEG_WALLET_MISMATCH` | domain | This confirm does not execute from the redemption's paying treasury. | The cash leg leaves the wallet that executes the confirm, so a confirm from any other wallet would measure a balance nobody spends and pay from a treasury the terms did not name. | Confirm from the wallet the terms name as the paying treasury. | info | No | 409 |
| DALP-12099 | `MARK_REFRESH_COOLDOWN` | client | Mark refreshed less than ten minutes ago. | The mark of this subject was refreshed inside the ten-minute cooldown, so the platform fetched nothing and the stored mark is unchanged. | Wait for the window the `Retry-After` header reports, then refresh the mark again. | info | Yes | 429 |

The previous page is [DALP-9500 to DALP-9999](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference/dalp-9500-9999). The next page is [DALP-12100 to DALP-12199](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference/dalp-12100-12199).


# DALP-12100 to DALP-12199

Source: https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference/dalp-12100-12199
Cause, fix, HTTP status and retry flag for every Platform API error with a code from DALP-12100 to DALP-12199.

This page lists the 51 errors the Platform API can return with a code from DALP-12100 to DALP-12199. Match the `id` in the error envelope to the DALP Code column, then read Retryable and Suggested Fix. The [Platform API error reference](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference#how-to-use-this-reference) explains each column, including Severity, and the [DALP error index](https://docs.settlemint.com/docs/api-reference/errors) lists the page for every code range.

| DALP Code | Machine name | Category | Message | Why | Suggested Fix | Severity | Retryable | HTTP Status |
| --- | --- | --- | --- | --- | --- | --- | --- | --- |
| DALP-12100 | `ENS_NOT_CONFIGURED` | domain | This deployment resolves no ENS avatars. | The deployment names no ENS network, so no address carries an avatar the platform can fetch. | Ask an operator to configure the ENS network and gateway. The mark still answers the generated disc without this rung. | info | No | 422 |
| DALP-12101 | `MARK_REFRESH_DEPENDENCY_FAILED` | dependency | Mark refresh dependency did not answer. | The avatar store, the ENS resolver, or object storage did not answer, so the platform stored nothing and the mark is unchanged. | Retry the refresh after a short delay. | error | Yes | 503 |
| DALP-12103 | `party.dependency.FAILED` | dependency | Party service temporarily unavailable. | A service the party domain depends on did not answer. | Retry after a short backoff. If the problem continues, contact support with the X-Request-Id response header. | error | Yes | 503 |
| DALP-12104 | `exec.queue.DEPENDENCY` | dependency | Transaction dependency temporarily unavailable. | The transaction request could not read its caller scope or a required queue dependency. | Retry the same request after a short backoff. Do not submit a replacement transaction. | error | Yes | 503 |
| DALP-12105 | `exec.queue.OUTCOME_UNKNOWN` | dependency | Transaction outcome still unknown. | The transaction may have settled, but the platform could not read its final state. | Read the transaction request status using its transaction id. Do not submit a replacement transaction. | error | No | 503 |
| DALP-12106 | `portfolio.http.WRITE_OUTCOME_UNKNOWN` | dependency | Portfolio write outcome still unknown. | The portfolio write may have reached the chain, but its final outcome could not be read. | Read the transaction request status using its id. Do not submit a replacement write. | error | No | 503 |
| DALP-12107 | `party.write.OUTCOME_UNKNOWN` | operational | The party write outcome is unknown. | The queue may have accepted this write, but its final outcome could not be confirmed. | Look up the transaction request before taking further action. Do not submit a replacement write under a new idempotency key. | error | No | 503 |
| DALP-12108 | `compliance.write.OUTCOME_UNKNOWN` | operational | The compliance write outcome is unknown. | The queue may have accepted this compliance write, but its final outcome could not be confirmed. | Look up the transaction request before taking further action. Do not submit a replacement write under a new idempotency key. | error | No | 503 |
| DALP-12109 | `custody.write.OUTCOME_UNKNOWN` | operational | The smart-wallet write outcome is unknown. | The queue may have accepted this wallet write, but its final outcome could not be confirmed. | Look up the transaction request before taking further action. Do not submit a replacement write under a new idempotency key. | error | No | 503 |
| DALP-12110 | `PROFILE_SECTION_NOT_FOUND` | client | Profile section not found. | No profile section with this id is visible to the active organization; sections owned by another organization answer the same way. | List `GET /api/v2/settings/profile-sections` and retry with an id from that page. | info | No | 404 |
| DALP-12112 | `PROFILE_SECTION_STORAGE_LOCKED` | client | A profile field that holds a value is locked. | Every profile version records which fields held a value. Removing such a field, moving it between on-chain and off-chain storage, changing who fills it, changing its type, dropping one of its choices, or loosening an immutable field would orphan, expose, or invalidate a value an earlier version holds; `data.keys` lists the locked fields. | Keep those fields as they are, or add a new field with the other settings. | info | No | 409 |
| DALP-12113 | `PROFILE_SECTION_SYSTEM_READONLY` | permission | System profile sections are read-only. | System sections are shared by every organization, so no organization can change them; an organization may only retire one for itself. | Create an organization section with the fields you need instead. | info | No | 403 |
| DALP-12114 | `ASSET_TYPE_TEMPLATE_STORAGE_LOCKED` | client | The storage or mutability of a metadata field cannot change while deployed tokens use the template. | Tokens deployed from the template already carry metadata under its keys; moving a field between on-chain and off-chain storage would leave one key in both stores, removing an immutable field would orphan a value that cannot change, and loosening an immutable field would let a later write replace a value that was immutable when it was written. `data.keys` lists the locked fields. | Keep the storage and mutability of those fields as they are, or add a new field under a key no deployed token holds. | info | No | 409 |
| DALP-12115 | `party.user.IDENTITY_DEPLOY_FAILED` | domain | The created user's identity could not be deployed. | The chain failed the deployment of the created user's identity, so the user was not kept. | Repeat the create with a new Idempotency-Key. | error | No | 409 |
| DALP-12116 | `party.user.IDENTITY_BINDING_UNRESOLVED` | dependency | The created user's identity binding could not be read. | The chain did not answer the read that binds the created user's identity, so nothing was deployed and the user was not kept. | Repeat the create with a new Idempotency-Key after a short backoff. | error | Yes | 503 |
| DALP-12117 | `TOKEN_FORCED_TRANSFER_FROM_ESCROW` | client | The forced transfer's owner `{escrowAddress}` is a DALP escrow, so the token cannot force-transfer from it. | A DALP escrow tracks its own balances and locks. A token forced transfer out of the escrow address would move its units without updating them, so the platform refuses it before it signs anything. | Move the escrow's units with the escrow add-on's own forced transfer, which keeps its balances and locks right, or pick an owner that is not an escrow. | info | No | 422 |
| DALP-12131 | `TOKEN_BRAND_LOGO_REJECTED` | domain | The brand logo upload was rejected. | The brand logo upload does not meet the issued-token image rules: the token is external, or the file is not a PNG, JPEG or WebP of at most 5 MB and 2048 px a side, or its stored bytes differ from the declaration. | Upload a PNG, JPEG or WebP of at most 5 MB and 2048 px a side for a token this organization issued, then confirm it with its real size and type. | info | No | 422 |
| DALP-12133 | `USER_IMAGE_INVALID` | client | The profile image upload was rejected. | A rendition is not valid base64, is larger than its byte limit, is not a PNG, or is not exactly 256 px or 64 px square. The platform stored nothing. | Render both renditions as square PNG at 256 px and 64 px, encode them as base64, and send them again. | info | No | 400 |
| DALP-12134 | `USER_IMAGE_STORAGE_FAILED` | dependency | Object storage did not complete the profile image operation. | Object storage did not complete the upload of the profile image renditions. | Restore object storage availability, then send the same image request again. | error | Yes | 503 |
| DALP-12136 | `auth.apikey.THROTTLED` | permission | This API key filled its request window. | This key used its full request allowance for the current window, so the platform did not authenticate the request. | Wait for the key's request window to reopen, then send the request again. | info | Yes | 429 |
| DALP-12140 | `PROFILE_SECTION_SYSTEM_SLUG_TAKEN` | client | An organization section may not take the slug of a system section. | Filled profile fields are recorded as `<section slug>.<field key>`, so an organization section whose name derives a system section's slug would shadow it; `data.slug` names the slug. | Choose a section name that derives a different slug. | info | No | 400 |
| DALP-12142 | `TOKEN_FEATURE_DIVIDENDS_OUTSTANDING` | domain | Declared dividends are still unclaimed. | The `{{featureName}}` feature still owes declared dividends, and detaching or replacing it would leave them on the retired feature. | Let holders claim the declared dividends, or reclaim them, until the feature reports nothing outstanding. Then detach or replace the feature. | info | No | 409 |
| DALP-12146 | `ORDER_SIGNING_FAILED` | dependency | The order was not signed. | The custody provider did not return a signature for the order. Or the order cannot be signed on the platform: the instrument is listed on another chain, the maker is not the wallet that signs for the request, or the maker's signer no longer signs on the platform. | When custody did not answer, sign the order again once the custody provider is available. Otherwise scope the request to the instrument's chain and sign with the maker's own platform signer. | error | Yes | 503 |
| DALP-12148 | `core.database.QUERY_FAILED` | dependency | A database query failed. | The platform could not complete a database query required for this request. | Retry the request. If the failure continues, contact support with the request id. | error | Yes | 503 |
| DALP-12151 | `PROFILE_SECTION_HOLDS_VALUES` | client | A profile section a profile version filled cannot be deleted. | A participant holds a value for a field of the section, or a profile version of the organization recorded one, and deleting the section would orphan that value. | Retire the section instead of deleting it; earlier versions keep its values. | info | No | 409 |
| DALP-12159 | `TOKEN_ISSUANCE_RUN_DECLARATION_INVALID` | client | The members and links do not form one complete issuance. | The members, structure, templates, or feature links in the request do not form one complete issuance. `data.reason` names the rule the request broke. | Read `data.reason`. Send every structure member once with its declared template, or declare every link a standalone member needs, then retry. | info | No | 422 |
| DALP-12160 | `TOKEN_ISSUANCE_RUN_CONFLICT` | domain | The issuance run conflicts with a newer declaration or an earlier request. | The structure or a template changed after it was reviewed, or the idempotency key already accepted a different declaration. | Reload the structure and templates, review the issuance again, and accept it with a new idempotency key. | info | No | 409 |
| DALP-12161 | `TOKEN_ISSUANCE_RUN_NOT_FOUND` | client | The issuance run was not found. | The run does not exist in the active organization and system. | Use the run identifier returned when the issuance was accepted in this organization and system. | info | No | 404 |
| DALP-12162 | `PARTICIPANT_WALLET_REMOVAL_REFUSED` | client | Wallet removal refused. | Something still depends on the wallet, and `data.reason` names what: it still signs for a smart wallet (`signs-for-smart-wallet`), a custody account that is not archived still uses it (`custody-account-open`), it still holds a token balance (`holds-balance`), its holder's identity has a lock-up holder lock on a token of the system that has not reached its unlock time, which an approved wallet's removal through the organisation's managed signer cannot leave behind (`holder-locked`), its registration is not indexed yet (`registration-not-indexed`), it sits in an identity registry no organisation resolves (`registry-unresolved`), the organisation has no managed signer that may unregister it, because none is set up on that chain or it lacks the identity manager role (`organization-signer-missing`), another removal of it is running or the wallet is no longer active (`removal-in-progress`), it changed while it was being removed (`wallet-changed`), or it is not an EVM wallet of this participant (`not-an-evm-wallet`). `data.subjects` names the smart wallets, custody accounts, tokens or registry involved. For every reason except `wallet-changed`, nothing was submitted; for `wallet-changed`, the wallet's identity unregistrations may already have been submitted before the archive found the wallet changed. | Resolve what `data.reason` names, then request the removal again: remove the wallet as a signer, archive the named custody accounts, move the named tokens out, wait for the named tokens' holder lock to reach its unlock time or ask the token's issuer to clear it, or set up the organisation's managed signer on that chain and grant it the identity manager role. For `registration-not-indexed` and `removal-in-progress`, wait and retry. | info | No | 409 |
| DALP-12163 | `CORPORATE_ACTION_CASH_LEG_SELF_DENOMINATED` | domain | This redemption pays its cash leg in the token it burns. | The cash and the burn land in one transaction, so a holder is credited the units the burn destroys and ends the run holding what they started with, while the treasury is short the amount it paid and the record reports the holder as applied. | Name a different asset as the denomination, then confirm again. | info | No | 409 |
| DALP-12164 | `CORPORATE_ACTION_CASH_LEG_NEEDS_SMART_ACCOUNT` | domain | This redemption's cash leg needs a smart-account executor. | The cash and the burn settle in one smart-account transaction, so a holder is paid and burned together or left untouched. A plain externally owned account sends one call per transaction and has no atomic shape to offer. | Confirm from a smart-account executor, or declare the redemption without a cash leg and settle the payment separately. | info | No | 409 |
| DALP-12165 | `CORPORATE_ACTION_APPROVAL_REFUSED` | domain | The maker-checker rules refused this decision. | Maker-checker clears a Corporate Action for execution, and the decision breaks one of its rules: the caller may not decide, the session is impersonated or a machine credential, the caller raised or last previewed this record, a decision already landed on it, the record is not in a decidable state, the plan moved since it was read, the cash leg is not funded, or the approval window closed. The violation in the response names the rule. | Read the named rule. A distinct permitted operator decides from a signed-in session, on a fresh preview when the plan moved and on a funded treasury when the cash leg is short. | info | No | 409 |
| DALP-12166 | `CORPORATE_ACTION_CASH_LEG_UNPAYABLE_HOLDER` | domain | This redemption prices one or more holders at zero cash. | Cash is floored to whole base units of the denomination asset, so a holder whose units are worth less than one base unit is owed nothing. The cash and the burn land in one transaction, so confirming would destroy those holders' units and pay them nothing. | Raise the price per unit, or announce an amount that prices above zero for every holder, then confirm again. | info | No | 409 |
| DALP-12167 | `CORPORATE_ACTION_CASH_LEG_UNVERIFIABLE_ASSET` | domain | This redemption's denomination asset was not issued in this system. | The cash leg is paid with a plain ERC-20 transfer inside the burn's own transaction, and the executing smart account does not read what that call returned. An asset that reports failure by returning false instead of reverting would leave the burn standing beside a payment that never moved, and only an asset this system issued is known to revert. | Name a denomination asset issued in this system, then confirm again. | info | No | 409 |
| DALP-12168 | `CORPORATE_ACTION_CASH_LEG_BURN_FEE` | domain | This token charges a burn fee, so the cash leg cannot be priced. | A burn fee splits every redeemed amount into a transfer to the fee recipient and a smaller net burn. Cash priced on the announced amount therefore pays for units that stay outstanding in the fee recipient's balance, and those units can be redeemed a second time. | Set this token's burn fee to zero, then confirm again. A redemption that declares no cash leg is unaffected. | info | No | 409 |
| DALP-12171 | `CORPORATE_ACTION_ELECTION_CLOSED` | domain | This Corporate Action's election window is closed. | Holder elections are accepted only while the Corporate Action is previewed or approved and its election deadline is open. | Submit the election before the deadline, or use a new Corporate Action. | info | No | 409 |
| DALP-12172 | `CORPORATE_ACTION_ELECTION_OPTION_INVALID` | domain | The election choice is not offered by this Corporate Action. | The submitted choice is not one of the options configured for this Corporate Action. | Read the Corporate Action and submit one of its configured choices. | info | No | 409 |
| DALP-12173 | `CORPORATE_ACTION_ELECTION_HOLDER_INELIGIBLE` | domain | The holder is not eligible to elect on this Corporate Action. | The holder was not present in the Corporate Action's record-date eligibility set. | Submit an election only from an eligible holder account. | info | No | 409 |
| DALP-12174 | `CORPORATE_ACTION_ELECTION_HOLDER_UNAUTHORIZED` | domain | The holder wallet is not authorized to submit this election. | The authenticated wallet does not match the holder wallet authorized for the election. | Retry from the holder's authorized wallet. | info | No | 409 |
| DALP-12175 | `CORPORATE_ACTION_ELECTION_DEADLINE_INVALID` | domain | The election deadline does not permit submission. | The configured election deadline is not in the future. | Set an election deadline after now. | info | No | 409 |
| DALP-12176 | `CORPORATE_ACTION_ELECTION_SHAPE_INVALID` | domain | The Corporate Action election configuration cannot be used. | The election options or their settlement terms do not form a valid Corporate Action election. | Correct the election configuration and create the Corporate Action again. | info | No | 409 |
| DALP-12177 | `CORPORATE_ACTION_ELECTION_OPEN` | domain | The Corporate Action's election deadline is still open. | Execution must wait until holders can no longer change their elections. | Wait until the configured election deadline has passed, then confirm again. | info | Yes | 409 |
| DALP-12178 | `CORPORATE_ACTION_ELECTION_LOCKED` | domain | The Corporate Action's election window is locked. | Preview cannot be changed after the election deadline or after a holder has submitted an election. | Create a new Corporate Action or use the stored election outcome. | info | No | 409 |
| DALP-12179 | `CORPORATE_ACTION_ELECTION_ABSENT` | domain | This Corporate Action has no holder-election configuration. | The election route applies only to Corporate Actions created with holder-election terms. | Read the Corporate Action and use its supported operation, or create one with an election configuration. | info | No | 409 |
| DALP-12180 | `CORPORATE_ACTION_BOND_MATURED` | domain | A partial redemption cannot be recorded on a matured bond. | After maturity holders redeem their own tokens at face value, so a partial redemption that burns tokens without paying for them removes a holder's claim. | Let holders redeem their own tokens, or use the maturity redemption of this bond. | info | No | 409 |
| DALP-12181 | `CORPORATE_ACTION_DECIMALS_MISMATCH` | domain | A spin-off or tradable rights issue requires a child token with the same decimals as the parent. | The child token holds a different number of decimals than the token the holder book was taken from, so every allocation would be the wrong size. | Use a child token with the same decimals as the parent, or create one, then preview again. | info | No | 409 |
| DALP-12182 | `CORPORATE_ACTION_NO_ENTITLED_HOLDER` | domain | No holder outside the treasury is entitled to a payment at the record date. | The treasury takes no payment, and at the record date no other eligible holder held enough units to receive one, so the snapshot has no holder to pay. | If the message says no unclaimed entitlement is left to push, every holder is already paid and nothing is left to do. Otherwise cancel this dividend and declare a new one with a later record date or a larger amount, or abort the Corporate Action run. | info | No | 409 |
| DALP-12193 | `TOO_MANY_REQUESTS` | client | Too many requests for this operation. | The caller exceeded a rate or attempt limit on this operation. The refusing limit publishes no error entry of its own, so this general 429 stands in for it. | Wait before retrying. Honour a `Retry-After` header when the response carries one. | info | Yes | 429 |
| DALP-12194 | `BAD_GATEWAY` | dependency | A service this request depends on returned an answer the platform could not use. | A service this operation depends on answered, but the platform could not use the answer. The failing dependency publishes no error entry of its own, so this general 502 stands in for it. | Retry after a short delay. If it continues, contact support with the request id. | error | Yes | 502 |
| DALP-12195 | `PRIMARY_CUSTODY_ACCOUNT_REQUIRED` | client | Choose a primary custody account for this participant and network. | The acting participant has no usable primary custody account for this organization and network. No other account is substituted, even if one is eligible. | Choose a primary custody account in this network, or explicitly select one for this request. | info | No | 409 |
| DALP-12196 | `CUSTODY_ACCOUNT_SELECTION_INVALID` | client | The selected custody account is not eligible for this request. | The selected account is not available to the acting participant in this organisation and network, or is not active and eligible for the request. No other account was substituted. A portfolio read also answers this way when no enabled EVM network in the catalogue is deployed on the requested chain. | Select an active eligible account from this participant's custody-account list for this organization and network. | info | No | 409 |

The previous page is [DALP-12000 to DALP-12099](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference/dalp-12000-12099). The next page is [DALP-12200 to DALP-12299](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference/dalp-12200-12299).


# DALP-12200 to DALP-12299

Source: https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference/dalp-12200-12299
Cause, fix, HTTP status and retry flag for every Platform API error with a code from DALP-12200 to DALP-12299.

This page lists the 52 errors the Platform API can return with a code from DALP-12200 to DALP-12299. Match the `id` in the error envelope to the DALP Code column, then read Retryable and Suggested Fix. The [Platform API error reference](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference#how-to-use-this-reference) explains each column, including Severity, and the [DALP error index](https://docs.settlemint.com/docs/api-reference/errors) lists the page for every code range.

| DALP Code | Machine name | Category | Message | Why | Suggested Fix | Severity | Retryable | HTTP Status |
| --- | --- | --- | --- | --- | --- | --- | --- | --- |
| DALP-12230 | `CANTON_ALLOCATION_REQUEST_EXPIRED` | domain | The Canton allocation request expired. | The settlement allocation request passed its execution window before the allocation was made, so the platform cannot allocate against it. | Create a new allocation request with an execution window that has not passed. | info | No | 410 |
| DALP-12231 | `CANTON_APPROVAL_DECISION_CONFLICT` | domain | The Canton command already has a different approval decision. | This Canton command intent already has a terminal approval decision, and the new decision differs from it. A compensation, or a submission that groups others, carries no approval to decide and answers the same way. | Read the submission and keep its recorded approval decision. | info | No | 409 |
| DALP-12232 | `CANTON_APPROVAL_DECISION_FORBIDDEN` | permission | You may not decide this Canton command. | Only an organisation owner or a platform administrator can decide a Canton command intent. An instrument write also needs a party that holds the instrument role the write requires. | Ask an organisation owner or a platform administrator to record the decision. For an instrument write, submit as a party that holds the required role. | info | No | 403 |
| DALP-12233 | `CANTON_CAPABILITY_UNAVAILABLE` | dependency | A required Canton capability is unavailable. | The Canton participant or a service it depends on did not provide a capability this operation needs, so the platform did not complete the request. | Retry later. If the refusal persists, ask an operator to restore the Canton participant connection. | error | Yes | 503 |
| DALP-12234 | `CANTON_SUBMISSION_REJECTED` | domain | The Canton participant rejected the command. | The Canton participant rejected the command, the custody provider refused to sign it, or the command named a target it does not apply to, so the ledger did not change. | Correct the command or its target, then submit it again. If the custody provider refused to sign, ask its approver why before you resubmit. | info | No | 422 |
| DALP-12235 | `CANTON_INSTRUMENT_NOT_FOUND` | client | The Canton instrument was not found. | No Canton instrument with this admin and id is disclosed to the parties of the calling organization on the selected network. | Use an instrument admin and id from the Canton assets list, and select the network the instrument lives on with X-Network-Id. | info | No | 404 |
| DALP-12240 | `FEED_DIRECTORY_UNAVAILABLE` | dependency | The feed directory for this system is not available. | The selected network has no indexed feed directory for this system, or the directory could not be read. | Confirm the system bootstrap installed the feed directory and the indexer has caught up, then retry. | error | Yes | 503 |
| DALP-12241 | `FEED_ADDON_NOT_INSTALLED` | domain | This feed operation needs an add-on the system does not have. | The operation depends on a system add-on, such as the price resolver or a feed factory, that is not installed on this system. | Install the price resolver or feed factory add-on this operation uses on this system, then send the request again. | info | No | 409 |
| DALP-12242 | `FEED_MANAGER_PERMISSION_REQUIRED` | permission | The acting wallet cannot manage feeds on this system. | Feed writes need the feeds manager role on the system and a managed signing account for the organisation on this chain. The executing wallet does not hold the role, or the organisation has no such account. | Ask a system administrator to grant the feeds manager role to the executing wallet, or provision the organisation's managed signing account on this chain, then retry. | info | No | 403 |
| DALP-12243 | `FEED_SUBMISSION_NOT_AUTHORIZED` | permission | The feed update was not signed. | The custody policy for the issuer key refused to sign this feed update, no custody signer is recorded for the feed, or the feed does not trust the submitting identity as an issuer for its topic. | Check the custody policy and custody signer for the issuer key, or submit the update with an identity that the policy allows to sign and the feed trusts as an issuer for its topic. | info | No | 403 |
| DALP-12244 | `FEED_SUBMISSION_SIGNER_AMBIGUOUS` | domain | More than one signing key matches the feed participant. | The platform found several keys that can sign for this participant and will not pick one on its own. | Keep one signing key for the participant, then submit the update again. | error | No | 503 |
| DALP-12245 | `FEED_PRICE_NOT_REPRESENTABLE` | client | The price has more decimal places than the feed stores. | The feed stores prices at a fixed number of decimals, and the submitted price cannot be written at that precision without rounding. | Round the price to the feed's decimals, then submit it again. | info | No | 400 |
| DALP-12246 | `FEED_BATCH_NOT_SUBMITTABLE` | client | The feed update batch cannot be submitted. | The batch holds more feeds than the ceiling allows, names one feed twice, or every update in it would revert on chain. | Split the batch, give each feed at most one update, and check the nonce, deadline, and issuer authorization of each update. | info | No | 409 |
| DALP-12247 | `EXCHANGE_RATE_CURRENCY_UNSUPPORTED` | client | No feed on this network prices the currency. | The exchange-rate graph for the selected network has no feed that quotes the requested currency. | Use a currency that GET /api/v2/exchange-rates/supported-currencies returns, or add an exchange-rate feed for the currency on this network. | info | No | 422 |
| DALP-12248 | `compliance.kyc.DEPENDENCY_UNAVAILABLE` | dependency | KYC data temporarily unavailable. | A store the KYC or user profile route reads did not answer, so the route could not complete. `data.dependency` names the store. | Retry after a short backoff. If the problem continues, contact support with the X-Request-Id response header and `data.dependency`. | error | Yes | 503 |
| DALP-12249 | `compliance.provider.UNAVAILABLE` | dependency | Compliance service temporarily unavailable. | A service the compliance route depends on did not answer: the compliance provider, the secret store that holds its credentials, the network catalog, a KYC store write, or the claim-topic exclusion policy read. | Retry after a short backoff. If the problem continues, contact support with the X-Request-Id response header. | error | Yes | 503 |
| DALP-12250 | `platform.http.DEPENDENCY_UNAVAILABLE` | dependency | Platform dependency temporarily unavailable. | A dependency required to complete this platform request did not answer. | Retry after a short backoff. If it persists, contact support with the request ID. | error | Yes | 503 |
| DALP-12251 | `platform.http.REQUEST_INVALID` | client | Platform request could not be read. | The request contains a field the platform cannot accept for this operation. | Check the request fields against the operation's accepted values, then retry. | info | No | 400 |
| DALP-12252 | `platform.http.ACCESS_DENIED` | permission | Platform access denied. | The caller cannot perform this platform operation. | Sign in and complete any wallet verification the operation asks for, or ask whoever grants the role it needs, then retry. An organization owner grants the owner role that changing an organization's members or their roles needs. Removing a member also needs the identityManager role on your wallet. | info | No | 403 |
| DALP-12253 | `wire.http.SESSION_REQUIRED` | auth | Session required. | The request lacks the authentication or wallet context required for this operation. | Check that the active session or API key has access to the required wallet, then retry. | info | No | 401 |
| DALP-12255 | `compliance.kyc.EVIDENCE_DENIED` | permission | KYC record not found. | No KYC record visible to the current caller matches this request. | Confirm the record belongs to the active organization and use an identifier returned for that organization. | info | No | 404 |
| DALP-12257 | `CUSTODY_ACCOUNT_NOT_FOUND_PUBLIC` | client | Custody account not found. | No custody account or custody lifecycle request visible to the caller in the active organisation matches this identifier. | Refresh the active organization's account list and choose an account returned there. | info | No | 404 |
| DALP-12258 | `AUTH_STORE_UNAVAILABLE` | dependency | The authentication store did not answer. | A read or write against the session, account security, or API key store did not complete. | Retry after a short wait. If the failure persists, contact support with the request id. | error | Yes | 503 |
| DALP-12259 | `SESSION_REVOCATION_NOT_AUTHORIZED` | permission | This session may not revoke sessions. | Revoking a user's sessions needs the identity-manager role on the active organization's system, and none of the caller's wallets holds that role. | Use a session whose active organization grants one of your wallets the identity-manager role, then retry. | info | No | 403 |
| DALP-12260 | `USER_SECURITY_TARGET_NOT_FOUND` | client | The user or session was not found. | The security operation names a user or a session that does not exist, or that the caller may not see. | Check the user or session identifier and confirm the caller may administer that user, then retry. | info | No | 404 |
| DALP-12261 | `MULTISIG_NOT_ENABLED` | client | Multi-signer wallets are switched off on this deployment. | This deployment serves single-signer wallets only, so a signer set with more than one signer or a threshold above one is refused. | Keep the draft at one signer and a threshold of one, or ask an operator to enable multi-signer wallets. | info | No | 403 |
| DALP-12262 | `TRADE_BUST_EXECUTION_REFUSED` | permission | The trade-bust reversal was refused. | A reversal runs only from an approved bust record the caller may execute, and only with the approval, settled batch, and legs that record carries. This request broke one of those rules, or its reversal could not be queued or recorded as busted. The reversal is also refused when another executor already claimed the bust, a reversal leg did not settle, or a bust escrow, parked fill or queue record could not be read. | Re-read the approval and execute exactly the legs it carries. If they already match, read the approval state before you retry. | info | No | 403 |
| DALP-12263 | `MARKET_CALENDAR_INVALID` | client | The instrument calendar cannot produce trading sessions. | The calendar names a timezone the platform cannot resolve, session times or an exception that never open a session, or a private continuous instrument schedules a pre-open. The calendar is also refused when an edit or delete targets a past venue closure or a date with no closure, when a move lands on a date that already has one, or when a collection window overlaps a session that already started. | Use an IANA timezone and session times with pre-open at or before open and open before close. On a private continuous instrument, leave pre-open empty for every weekday and every open exception, then submit the calendar again. Edit or delete only a venue closure that falls on the current day or a later one. | info | No | 422 |
| DALP-12264 | `MARKET_FIELD_IMMUTABLE` | client | The instrument setting cannot be changed. | A listed instrument keeps its matching mode, private flag, sponsorship, reference price, admission figures and go-live schedule. A delisted one keeps its maturity cut-off and its valuation and reference prices. An instrument's valuation is fixed once its first auction runs. A valuation or reference price off the tick grid, a base-token price designation on an instrument with no system address, and a listing approval this operator no longer holds are refused too. | Keep those settings unchanged, or list a new instrument with the settings you need. Send valuation and reference prices on the instrument's tick grid. | info | No | 422 |
| DALP-12265 | `SETTLEMENT_LEG_BLOCKED` | domain | A settlement transfer leg would be refused by the token. | The platform simulates every transfer leg of a settlement batch before it submits the batch, and the token would refuse at least one of them. | Resolve the token's transfer restriction on the blocked leg, then let the batch drain again. | info | No | 409 |
| DALP-12266 | `VENUE_ROLE_REQUIRED` | permission | A role on this venue is required. | Replacing an instrument calendar needs the venue admin role and instrument operations need the venue operator role on this venue's access manager. `data.role` names the one this request needs. None of the caller's wallets holds it, and a role on another venue grants nothing here. Granting or revoking the venue admin role also needs a platform admin. | Ask the venue's admin to grant the role to your wallet on this venue's access manager, then repeat the request. To grant or revoke the venue admin role, act as a platform admin. | info | No | 403 |
| DALP-12267 | `party.participant.WALLET_TYPE_CONFLICT` | client | The requested account type is not the one this organization drives. | An organization drives one account type on a network: a smart account where account abstraction is enabled and reconciled, an EOA everywhere else. The walletType sent names the other one. | Omit walletType and let the organization's own account type stand, or send the type it drives. | info | No | 400 |
| DALP-12268 | `compliance.executor.DEPENDENCY_UNAVAILABLE` | dependency | Compliance authorization temporarily unavailable. | The custody account directory did not resolve the executor needed to check this caller's compliance role. | Retry after a short backoff. If the problem continues, contact support with the X-Request-Id response header. | error | Yes | 503 |
| DALP-12269 | `exec.aa.READ_DEPENDENCY` | dependency | Account-abstraction status temporarily unavailable. | The indexed store or chain behind this gas-sponsorship read could not be reached. | Retry the read after a short backoff. If the problem continues, contact support with the request id. | error | Yes | 503 |
| DALP-12271 | `CUSTODY_PROVIDER_CONFIG_INVALID` | client | The custody provider configuration is not valid here. | The provider or ledger is not enabled on this deployment, the provider lacks a signing capability or does not serve the requested network, the credential fields do not match the provider, the provider identity or exclusivity does not fit the credentials, or no such configuration exists in this organisation. | Choose an enabled provider and ledger that serve the network with the signing capabilities it needs, send the credential fields that provider expects, and name a configuration of your own organisation. | info | No | 422 |
| DALP-12272 | `CUSTODY_PROVIDER_CONFIG_CONFLICT` | domain | The custody provider configuration cannot take this change. | The configuration is in a state that refuses the change: something still references it, its credential source cannot change on a rotation, a newer credential version is already recorded, it holds no managed credential slot, recovery needs a successful probe taken after the quarantine, the configuration is not healthy and enabled for new accounts so it cannot serve investors, its stored credential is missing, or a legacy-wallet reconciliation check failed. | Read the configuration, clear what blocks the change, then send the request again. | info | No | 409 |
| DALP-12274 | `CUSTODY_PROOF_INVALID` | client | The custody proof does not bind this account. | The control proof, external control artifact, provider binding, or step-up confirmation sent with this request does not bind the account on this ledger, or the custody provider does not support the ledger. It also answers when the custody provider refused to sign the operation, for example because signing failed or the wallet cannot pay the fee. | Produce a new proof or confirmation for this account and ledger, then send the request again. | info | No | 422 |
| DALP-12275 | `CUSTODY_APPROVAL_PENDING` | domain | This custody request is waiting for an approval. | The custody provider parked the operation until an approver acts on it, or the lifecycle request still needs its external-message authorization. | Complete the approval with the custody provider, or supply the external-message authorization, then send the request again. | info | No | 409 |
| DALP-12276 | `CUSTODY_APPROVAL_REJECTED` | permission | The custody approval for this request was refused. | The approval this operation waited on was rejected or expired, the wallet's checker refused it, the selected account or provider configuration cannot approve or serve the request, or the session has no active organisation or open invitation. | Start a new request with an account that can approve it, or ask the approver to approve the operation. | info | No | 403 |
| DALP-12278 | `CUSTODY_WALLET_NOT_SIGNER` | permission | The caller is not a signer of this wallet. | The wallet's signer set does not include the caller's account, or that account is not eligible to sign for it. | Send the request from an account the wallet lists as an eligible signer. | info | No | 403 |
| DALP-12283 | `compliance.scope.DENIED` | permission | Compliance module not found for this scope. | The requested compliance module does not apply to the system or token scope in the request. | Address the module through a system or token scope it applies to. | info | No | 404 |
| DALP-12285 | `compliance.module.STATE_INVALID` | domain | This compliance rule cannot take this change. | The rule's current state does not allow this change here: it may already be on or off, removed, locked, or not supported. | Check the rule's current state where you changed it. If it changed, reload and try again; otherwise this change cannot be made here. | info | No | 409 |
| DALP-12286 | `compliance.module.CONFIG_CONTRADICTION` | client | The compliance module settings contradict each other. | Two or more settings in the submitted compliance module configuration cannot hold at the same time. It also answers when a NOT branch excludes holders of a claim topic the system's claim policy manager set to Not allowed. | Submit one consistent module configuration. | info | No | 422 |
| DALP-12287 | `compliance.expression.NOT_NARROWED` | client | The compliance expression is too broad to enforce. | The compliance expression has no positive condition that narrows who it admits, it excludes holders of a claim they can remove themselves without a named acknowledgement, or no topic-scheme registry is indexed to grade that exclusion. | Add a positive condition or narrow the rule. To accept a holder-removable exclusion, send `holderRemovableNot.accepted` as `true` from a session that is not impersonated. | info | No | 422 |
| DALP-12290 | `dapi.identity.CLAIM_TOPIC_EXCLUSION_POLICY_DEPENDENCY_FAILED` | dependency | The claim-topic exclusion policy is temporarily unavailable. | The store that holds the claim-topic exclusion policy did not answer, so the request could not complete. | Retry after a short backoff. If the problem continues, contact support with the X-Request-Id response header. | error | Yes | 503 |
| DALP-12292 | `compliance.provider.CREDENTIALS_INVALID` | auth | The compliance provider rejected its credentials. | The compliance provider refused the credentials, the credentials are for another provider kind, or the provider does not support the requested topic. | Rotate or correct the provider credentials, then send the request again. | info | No | 400 |
| DALP-12293 | `compliance.kyc.DOCUMENT_CONFLICT` | domain | The KYC document changed during this request. | Another request changed the KYC document after this request read it. | Read the current document version, then send the request again. | info | No | 409 |
| DALP-12295 | `core.network.CHAIN_ID_NOT_FOUND` | client | No network is configured for this chain id. | No network in the platform configuration matches the chain id the request named. | Send a chain id the platform has configured, or ask an administrator to add the network. | info | No | 404 |
| DALP-12296 | `core.network.NETWORK_NOT_FOUND` | client | No network is configured under this name. | No network in the platform configuration matches the network name the request named. | Send a network name the platform has configured, or ask an administrator to add the network. | info | No | 404 |
| DALP-12297 | `core.network.NETWORK_DISABLED` | operational | The requested network is disabled. | The network the request named is configured but disabled, so the platform does not serve it. | Choose an enabled network, or ask an administrator to enable this one. | error | No | 409 |
| DALP-12298 | `core.network.INVALID_CONFIG` | operational | The platform could not use this network's configuration. | The platform could not use the configuration of the network this request needs. | Contact support with the X-Request-Id response header so an operator can correct the network configuration. | error | No | 409 |
| DALP-12299 | `core.network.INVALID_CHAIN` | operational | The network's configured chain is not supported. | The network the request resolved to names a built-in chain the platform does not support. | Ask an administrator to configure a supported chain or a custom chain definition for this network. | error | No | 400 |

The previous page is [DALP-12100 to DALP-12199](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference/dalp-12100-12199). The next page is [DALP-12300 to DALP-12399](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference/dalp-12300-12399).


# DALP-12300 to DALP-12399

Source: https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference/dalp-12300-12399
Cause, fix, HTTP status and retry flag for every Platform API error with a code from DALP-12300 to DALP-12399.

This page lists the 78 errors the Platform API can return with a code from DALP-12300 to DALP-12399. Match the `id` in the error envelope to the DALP Code column, then read Retryable and Suggested Fix. The [Platform API error reference](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference#how-to-use-this-reference) explains each column, including Severity, and the [DALP error index](https://docs.settlemint.com/docs/api-reference/errors) lists the page for every code range.

| DALP Code | Machine name | Category | Message | Why | Suggested Fix | Severity | Retryable | HTTP Status |
| --- | --- | --- | --- | --- | --- | --- | --- | --- |
| DALP-12300 | `core.network.RPC_REQUEST_FAILED` | dependency | The blockchain node did not answer. | The blockchain RPC endpoint the network uses did not complete the read this request needs. | Retry after a short backoff. If the problem continues, contact support with the X-Request-Id response header. | error | Yes | 503 |
| DALP-12301 | `core.network.EXECUTOR_CHAIN_NOT_FOUND` | client | No executor network is configured for this chain. | No configured network resolves to the chain the smart-wallet executor was asked to use. | Select a configured chain, or ask an administrator to add the network. | info | No | 404 |
| DALP-12302 | `core.network.EXECUTOR_CHAIN_DISABLED` | operational | Every network for this executor chain is disabled. | The chain the smart-wallet executor was asked to use has configured networks, but all of them are disabled. | Ask an administrator to enable a network for this chain, or select another chain. | error | No | 409 |
| DALP-12303 | `core.network.EXECUTOR_CHAIN_CONFIG_INVALID` | operational | The platform could not read the executor network's configuration. | The smart-wallet executor's network configuration is unusable: it has no RPC endpoint, its RPC URL is invalid or not HTTP or HTTPS, or its enabled networks name different directory contracts. | Contact support with the X-Request-Id response header so an operator can correct the network configuration. | error | No | 409 |
| DALP-12304 | `core.network.EXECUTOR_CHAIN_RPC_FAILED` | dependency | The executor network's node did not answer. | The RPC endpoint or account factory of the smart-wallet executor's network failed during this request. | Retry after a short backoff. If the problem continues, contact support with the X-Request-Id response header. | error | Yes | 503 |
| DALP-12305 | `dapi.runtime.CHAIN_SCOPE_HEADERS_CONFLICT` | client | The request names two networks. | The request carries both X-Chain-Id and X-Network-Id, so it names two networks. | Send only one scope header: X-Chain-Id for an EVM network or X-Network-Id for a Canton network. | info | No | 400 |
| DALP-12306 | `dapi.runtime.NETWORK_ID_HEADER_INVALID` | client | The X-Network-Id header is blank. | The X-Network-Id header is present but blank, so it names no platform network. | Send the stable name of the network you want, or omit the header. | info | No | 400 |
| DALP-12307 | `dapi.runtime.REQUEST_CHAIN_LOOKUP_FAILED` | dependency | The organization's network settings are temporarily unavailable. | The platform could not load the organization's network configuration for this request. | Retry after a short backoff. If the problem continues, contact support with the X-Request-Id response header. | error | Yes | 503 |
| DALP-12308 | `dapi.runtime.INVALID_REQUEST_CUSTODY_ACCOUNT` | client | The X-Custody-Account-Id header is not a custody account identifier. | The X-Custody-Account-Id header value is not a valid custody account identifier. | Send an identifier the custody-account list returns, or omit the header. | info | No | 400 |
| DALP-12309 | `dapi.runtime.REQUEST_CUSTODY_ACCOUNT_EXTERNAL_AUTHORIZATION_REQUIRED` | domain | The custody account needs its external wallet to authorize this request. | The selected custody account is controlled by an external wallet, so the platform cannot sign this operation on its behalf. | Prepare the operation, authorize it with the connected wallet, then finalize the signed artifact. | info | No | 409 |
| DALP-12310 | `dapi.runtime.EXTERNAL_MESSAGE_AUTHORIZATION_REQUIRED` | domain | The external wallet must sign this request. | The selected external custody account has to sign the exact payload the platform prepared for this request. | Connect the selected wallet, sign the returned payload, and send the request again with the signature. | info | No | 409 |
| DALP-12311 | `dapi.runtime.EXTERNAL_MESSAGE_AUTHORIZATION_INVALID` | client | The external wallet signature does not authorize this request. | The external-wallet signature sent with this request does not authorize the prepared signing payload. | Reconnect the selected account and sign the payload returned for this exact request. | info | No | 400 |
| DALP-12312 | `dapi.runtime.SYNC_QUEUE_RESULT_MISSING_DATA` | operational | The completed transaction returned no result for this route. | The transaction completed, but the route could not read back the data its response needs. | Read the transaction request to confirm its outcome, then read the resource it changed. Contact support with the X-Request-Id response header if the data stays missing. | error | No | 503 |
| DALP-12313 | `services.signer.ORGANIZATION_SUBMISSION_SIGNER_NOT_FOUND` | operational | The organization's submission signer is not bound. | The organization's deployment has no managed signer bound for this system and chain, so the platform cannot submit the operation. | Contact support with the X-Request-Id response header so an operator can repair the organization's signer binding. | error | Yes | 404 |
| DALP-12314 | `services.signer.ORGANIZATION_SUBMISSION_SIGNER_STATE_READ_FAILED` | dependency | The organization's submission signer could not be read. | The platform could not read the organization's managed signer binding for this system and chain. | Retry the same operation after a short backoff. If the problem continues, contact support with the X-Request-Id response header. | error | Yes | 503 |
| DALP-12315 | `services.signer.ORGANIZATION_SUBMISSION_SIGNER_PROVIDER_FAILED` | dependency | The organization's signing provider did not answer. | The organisation's signing provider did not answer, or the bound account, provider or signer key no longer matches the organisation's signer binding. | Retry after a short backoff. If the problem continues, contact support with the X-Request-Id response header. | error | Yes | 503 |
| DALP-12316 | `services.signer.ORGANIZATION_SUBMISSION_SIGNER_WALLET_MISMATCH` | operational | The organization's signer does not match its bound wallet. | The wallet the signing provider returns is not the wallet the organization's signer binding records. | Contact support with the X-Request-Id response header so an operator can repair the organization's signer binding. | error | No | 409 |
| DALP-12317 | `services.transaction-processor.DEPENDENCY_FAILED` | dependency | The transaction processor's dependency did not answer. | A service the transaction processor needs failed while it handled this operation. | Retry after a short backoff. If the problem continues, contact support with the X-Request-Id response header. | error | Yes | 503 |
| DALP-12320 | `dalp.workflows.batch.TERMINAL` | domain | The batch cannot proceed. | The batch's payload, chunk sizing, transaction receipt, or token operation state is not valid, so the batch stopped. | Correct the batch payload or the token permissions it needs, then start the batch again. | info | No | 422 |
| DALP-12321 | `dalp.workflows.WORKFLOW_TENANT_NOT_FOUND` | client | Workflow not found. | No workflow visible to the caller's organization matches this identifier. | Use the workflow identifier returned to the organization that started it. | info | No | 404 |
| DALP-12322 | `db.identity-accounts.REPOSITORY_INVARIANT_VIOLATED` | operational | The custody account store returned an inconsistent result. | The custody account store did not return a row this request requires. | Contact support with the X-Request-Id response header. | error | No | 500 |
| DALP-12324 | `settlement.http.PRECONDITION_FAILED` | domain | A settlement precondition is not met. | The settlement cannot run the requested operation until one of its preconditions is satisfied. | Satisfy the precondition, then send the request again. | info | No | 422 |
| DALP-12325 | `settlement.http.SECRET_FAILED` | client | The settlement secret was not accepted. | The settlement secret or its signature failed validation or cryptographic processing. | Send the original secret and a valid signature for this settlement. | info | No | 422 |
| DALP-12326 | `settlement.http.DEPENDENCY_UNAVAILABLE` | dependency | A settlement dependency is temporarily unavailable. | A service the settlement operation needs did not answer, so the operation did not run. | Retry after a short backoff. If the problem continues, contact support with the X-Request-Id response header. | error | Yes | 503 |
| DALP-12328 | `settlement.sale.DOCUMENT_REJECTED` | client | The token-sale document was rejected. | The token-sale document's type, size, visibility, or hash does not meet the upload rules. | Correct the document type, size, visibility, or hash, then upload it again. | info | No | 422 |
| DALP-12331 | `platform.http.REINDEXING` | operational | The indexer is still catching up on this chain. | The indexer for this chain is rebuilding, and the caller asked to be told instead of waiting while it catches up. | Retry after the number of seconds in data.retryAfterSeconds. | info | Yes | 503 |
| DALP-12332 | `platform.http.STORAGE_UNAVAILABLE` | dependency | Platform asset storage is temporarily unavailable. | The object storage that holds platform assets did not answer. | Retry after a short backoff. If the problem continues, contact support with the X-Request-Id response header. | error | Yes | 503 |
| DALP-12334 | `dapi.runtime.REQUEST_SYSTEM_IDENTITY_SCOPE_LOOKUP_FAILED` | dependency | The organization's system scope is temporarily unavailable. | The platform could not load the active organization's system and identity registry scope. | Retry after a short backoff. If the problem continues, contact support with the X-Request-Id response header. | error | Yes | 503 |
| DALP-12335 | `portfolio.polls.SIGNING_PENDING` | operational | The ballot is waiting on a custody approval. | The platform parked signing this ballot until the custody approval it needs is granted. | Approve the pending custody request, then send the ballot again. | info | No | 409 |
| DALP-12336 | `dapi.runtime.AUTHORIZATION_CHECK_FAILED` | dependency | The permission check could not run. | The platform could not read what it needs to decide whether the caller may make this request, so the request did not run. | Retry after a short backoff. If the problem continues, contact support with the X-Request-Id response header. | error | Yes | 503 |
| DALP-12337 | `dapi.identity.CLAIM_TOPIC_READ_DEPENDENCY_FAILED` | dependency | The token's claim topics are temporarily unavailable. | The store that holds the token's claim topics did not answer, so the request could not complete. | Retry after a short backoff. If the problem continues, contact support with the X-Request-Id response header. | error | Yes | 503 |
| DALP-12338 | `dapi.identity.REGISTER_PENDING_DEPENDENCY_FAILED` | dependency | Pending identity registrations are temporarily unavailable. | The store that holds pending identity registrations did not answer, so the request could not complete. | Retry after a short backoff. If the problem continues, contact support with the X-Request-Id response header. | error | Yes | 503 |
| DALP-12340 | `dapi.assets.TOKEN_ACCESS_LAST_ADMINISTRATOR` | domain | The token's last administrator cannot be removed. | The change would leave the token without an administrator, so it is refused. | Grant the administrator role to another participant first, then remove this one. | info | No | 409 |
| DALP-12341 | `dapi.assets.TOKEN_ACCESS_PARTICIPANT_UNAVAILABLE` | dependency | The participant for this role change could not be resolved. | The participant, identity or wallet the role change names does not resolve to one participant with wallets this organisation can act on. The message names the cause. | Name a participant or wallet that this organisation holds and that belongs to one participant, then send the role change again. | error | No | 503 |
| DALP-12342 | `dapi.assets.TOKEN_ACCESS_ROLE_INVALID` | client | The role is not one this token grants. | The role in the request is not a role this token's access manager grants. | Send one of the roles the token's access control lists. | info | No | 400 |
| DALP-12344 | `dapi.assets.TOKEN_CREATE_STREAM_LOOKUP_FAILED` | dependency | The token deployment's progress is temporarily unavailable. | The store that records token deployments did not answer, so the deployment's progress could not be read. | Retry after a short backoff. If the problem continues, contact support with the X-Request-Id response header. | error | Yes | 503 |
| DALP-12345 | `dapi.assets.TOKEN_CREATE_STREAM_NOT_FOUND` | client | No token deployment is recorded under this transaction. | No token deployment visible to the caller is recorded under the transaction in the request. | Use the transaction identifier the token create request returned. | info | No | 404 |
| DALP-12346 | `dapi.assets.TOKEN_CREATE_STREAM_STEP_FAILED` | dependency | A token deployment step could not be read. | The platform could not read a step of the token deployment while streaming its progress. | Reconnect to the deployment stream after a short backoff. | error | Yes | 503 |
| DALP-12347 | `TOKEN_CREATE_WORKFLOW_RESULT_INVALID` | dependency | The deployed token could not be read back. | The token was deployed, but its indexed record could not be read back to complete the response. | Send the same request again with the same Idempotency-Key after a short wait. It answers with the deployed token and does not deploy a second one. Without that key, find the token with `GET /api/v2/tokens` instead of creating it again. | error | Yes | 503 |
| DALP-12353 | `dapi.assets.TOKEN_PRICE_ADMIN_REQUIRED` | permission | Setting the token price needs the token's administrator role. | The caller does not hold the role that may set this token's price. | Send the request as a participant with the token's administrator role, or ask one to set the price. | info | No | 403 |
| DALP-12354 | `dapi.transfer-simulation.UNAVAILABLE` | dependency | The transfer check is temporarily unavailable. | The platform could not simulate the transfer on chain, so it cannot say whether the transfer would succeed. | Retry after a short backoff. If the problem continues, contact support with the X-Request-Id response header. | error | Yes | 503 |
| DALP-12355 | `dapi.identity.CLAIM_ISSUE_DEPENDENCY_FAILED` | dependency | The claim could not be issued right now. | A service the claim issuance needs did not answer, so the claim was not issued. | Retry after a short backoff. If the problem continues, contact support with the X-Request-Id response header. | error | Yes | 503 |
| DALP-12356 | `dapi.assets.CONVERSION_FEATURE_PROBE_READ_FAILED` | dependency | The conversion feature could not be read. | The platform could not read the conversion feature's on-chain state for this request. | Retry after a short backoff. If the problem continues, contact support with the X-Request-Id response header. | error | Yes | 503 |
| DALP-12358 | `dapi.erc20_metadata.PROBE_FAILED` | dependency | The denomination token's metadata could not be read. | The denomination contract's symbol() or decimals() call failed, or its answer cannot be read as a symbol and decimals. | Check that the denomination address is an ERC-20 contract that answers symbol() and decimals(), then send the request with a corrected address. | error | No | 503 |
| DALP-12360 | `dapi.assets.TOKEN_ACCESS_UNAVAILABLE` | dependency | The token's access control could not be resolved. | The token implements neither ERC-3643 nor the SMART interface, or it has no access manager, so the platform cannot target this change. | Use a token that implements ERC-3643 or the SMART interface and has an access manager. If the token has both, contact support with the X-Request-Id response header. | error | No | 503 |
| DALP-12364 | `db.indexer-runtime.INDEXER_LISTENER_CATCH_UP_FAILED` | dependency | The indexer could not read its progress. | The indexer listener could not read its persisted block-progress checkpoint, so the data this route reads is not confirmed current. | Retry after a short backoff. If the problem continues, contact support with the X-Request-Id response header. | error | Yes | 503 |
| DALP-12365 | `platform.write.OUTCOME_UNKNOWN` | dependency | Platform write outcome still unknown. | The platform write may have been recorded or reached the chain, but its outcome could not be read. | When `data.transactionId` is present, read that transaction request. When it is absent, no request could be confirmed. For a proposal change, read the proposal before another write. For a role write, read the held roles before another write. Resending the same role set under the same idempotency key reuses the earlier request only while the held roles are unchanged. After they change, it plans only the changes still missing and can open a new request. | error | No | 503 |
| DALP-12366 | `platform.write.ROLE_BATCH_FAILED` | contract | A role write failed on chain. | A role write failed on chain. In a role set no earlier write is undone; in a role batch the calls sent before it stay applied on a signing-wallet executor. | Read the transaction request by id and the held roles, then send only the changes still missing. | info | No | 422 |
| DALP-12368 | `platform.http.NETWORK_CATALOG_INVALID` | domain | Another network already serves this chain. | Another enabled network in the catalog already serves this chain id. | Disable or remove the network that serves the chain, or give this network a different chain. | info | No | 409 |
| DALP-12369 | `platform.http.NETWORK_DEFINITION_INVALID` | client | The network definition cannot be stored. | The network definition cannot be stored as submitted. | Correct the named field of the network definition, then save it again. | info | No | 400 |
| DALP-12370 | `dapi.assets.TOKEN_ACCESS_ROLE_EXPIRY_INVALID` | client | The role expiry is not allowed. | A time-bound role grant must expire at least one minute after the request, and an administrator whose own role expires cannot grant the administrator role. | Send an expiresAt at least one minute in the future, or ask an administrator without an expiry to grant the administrator role. | info | No | 400 |
| DALP-12371 | `platform.http.NETWORK_IN_USE` | domain | The network still serves deployed organizations. | Organizations have systems deployed on this chain, and this change would leave the chain without an enabled network. | Keep this network enabled on this chain while those systems are on it. A chain cannot have a second enabled network, so this one must keep serving it. You can still change its RPC endpoints and other settings. | info | No | 409 |
| DALP-12372 | `platform.http.NETWORK_HAS_UPSTREAM_POOL` | domain | The network still has RPC upstreams configured. | The network's RPC upstreams were checked against its current chain, and this change would move the network to another chain. | Remove the network's RPC upstreams, make the chain change, then add them again. | info | No | 409 |
| DALP-12373 | `MATURITY_REDEMPTION_UNAVAILABLE` | domain | This redemption cannot be completed. | The asset is not ready to pay out this redemption, or the redemption transaction reverted. | Contact the issuer of the asset, and redeem again once the issuer confirms the redemption can be paid. | info | No | 409 |
| DALP-12374 | `RESOLUTION_FAILED` | operational | The venue signer is unavailable. | The venue could not read or verify the managed signing identity needed for this operation. | Retry after custody and network services recover. If the problem persists, ask a venue operator to check the signer configuration. | error | Yes | 503 |
| DALP-12375 | `ORDER_AMENDMENT_INCOMPLETE` | domain | The original order is cancelled and its replacement was not placed. | The amendment cancelled the original order, but the replacement could not be placed: a fill of the original had not settled yet, so its remainder stays locked until the venue records that settlement and releases it to the wallet's free venue balance, or the escrow or the book refused the replacement itself. | Repeat the same amendment once the original's remainder is released: the venue places that same replacement and never cancels anything twice. If the repeat is refused again, place a new order. | info | Yes | 409 |
| DALP-12377 | `platform.http.INVITATION_ALREADY_ACCEPTED` | domain | The invitation was already accepted. | This invitation was accepted before, so it cannot be accepted again. | Continue with the organization the invitation already joined, or ask an organization owner for a new invitation. | info | No | 409 |
| DALP-12379 | `platform.http.INVITATION_EXPIRED` | domain | The invitation has expired. | The invitation passed its expiry date before it was accepted. | Ask an organization owner to send a new invitation. | info | No | 403 |
| DALP-12380 | `platform.http.INVITATION_CANCELED` | domain | The invitation is no longer open. | The invitation was canceled or declined, so it can no longer be accepted. | Ask an organization owner to send a new invitation. | info | No | 403 |
| DALP-12381 | `platform.http.INVITATION_ORGANIZATION_ARCHIVED` | domain | The inviting organization is archived. | The organization that sent the invitation is archived and accepts no new members. | Ask the organization's owners to restore it, or accept an invitation from another organization. | info | No | 403 |
| DALP-12382 | `platform.http.INVITATION_NATIONAL_ID_CONFLICT` | domain | The organization already holds this national ID. | The organization already has a member with the same national ID as the invitee. | Ask an organization owner to check the existing member's identity before inviting this person again. | info | No | 409 |
| DALP-12383 | `platform.http.INVITATION_ROLES_NOT_AUTHORIZED` | domain | The invitation's roles were never authorized. | The invitation grants on-chain roles that no verified wallet authorized. | Ask an organization owner to authorize the invitation's roles with their wallet, or to send a new invitation. | info | No | 412 |
| DALP-12384 | `WALLET_STEP_UP_CHALLENGE_REFUSED` | permission | The step-up challenge does not match this request. | A wallet-verified request redeems a single-use step-up challenge issued to the caller for the active organization, this route, its target, and this exact payload. The request carried none, or one that is unknown, expired, or issued for another request, so the platform stored nothing. | Request a fresh challenge from `POST /api/v2/step-up-challenges` for this exact request, then send it once with the challenge id in the `X-Step-Up-Challenge` header. | info | No | 403 |
| DALP-12385 | `TOKEN_CLAIM_SIGNING_REFUSED` | domain | The signer refused to sign this claim. | The signer checked the request against custody, authorization, and approval policy and refused it for a reason that will not clear on retry. `data.reason` names which. | Read `data.reason`, resolve the named condition (for example, an unauthorized wallet or a rejected approval), then issue the claim again. | info | No | 409 |
| DALP-12386 | `custody.smart-wallet.EXTERNAL_MESSAGE_AUTHORIZATION_INVALID` | client | The wallet signature was not accepted. | The signature in `externalMessageAuthorization` does not recover to the wallet of the custody account in `data.custodyAccountId` over the deployment payload this request prepared, or its deadline is no longer current. | Send the request again without a signature to read the current payload, sign that exact payload with the account's connected wallet, then send the fresh signature. | info | No | 400 |
| DALP-12387 | `custody.smart-wallet.DEPLOY_REFUSED` | domain | The smart wallet could not be deployed. | A check or step of the deployment refused it, and `data.reason` names which: `account-abstraction-disabled` when the organisation runs no account abstraction on this chain, `controller-unauthorized` when the wallet's controller is another account or an agent wallet has no mandate validator, `factory-missing` when no account factory is registered, `deadline-expired` when the signed deadline passed, `deploy-failed` when the deployment did not land, `wallet-unknown` when the participant holds no active smart wallet with this id, or `prediction-mismatch` when the recorded or factory-predicted address differs from this wallet. | Resolve the reason in `data.reason`, then send the request again. After an expired deadline, request a fresh payload and sign it. | info | No | 409 |
| DALP-12388 | `custody.smart-wallet.EXTERNAL_MESSAGE_AUTHORIZATION_REQUIRED` | domain | The smart wallet needs a signature from its controlling wallet. | The custody account in `data.custodyAccountId` is self custody, so the platform holds no key for it. Its wallet has to sign the account factory payload in `data.signingPayload` before the smart wallet can be deployed. | Sign `data.signingPayload` with that account's connected wallet, then send the same request again with the signature in `externalMessageAuthorization`. | info | No | 409 |
| DALP-12389 | `party.identity.EXTERNAL_MESSAGE_AUTHORIZATION_REQUIRED` | domain | This request needs a signature from the selected wallet. | The custody account in `data.custodyAccountId` is self custody, so the platform holds no key for it. Its wallet has to sign the exact payload in `data.signingPayload` before this request can continue. | Sign `data.signingPayload` with that account's connected wallet, then send the same request again with the signature in `externalMessageAuthorization`. | info | No | 409 |
| DALP-12390 | `party.identity.EXTERNAL_MESSAGE_AUTHORIZATION_INVALID` | client | The wallet signature was not accepted. | The signature in `externalMessageAuthorization` does not recover to the wallet of the custody account in `data.custodyAccountId`, or it covers something other than the payload this request prepared. | Send the request again without a signature to read the current payload, sign that exact payload with the account's connected wallet, then send the fresh signature. | info | No | 400 |
| DALP-12391 | `CORPORATE_ACTION_CAPABILITY_MISSING` | domain | This token's instrument does not carry the capital this Corporate Action needs. | Share actions such as a bonus issue need share capital, and capital actions such as a split or a buyback need share or unit capital. The token carries neither capability, or it has the Booked movements feature, which these Corporate Actions do not run on. | Raise this Corporate Action on a share or unit token, or pick a Corporate Action this instrument offers. | info | No | 409 |
| DALP-12392 | `settlement.sale.TERMS_FIXED` | client | The sale's terms documents are fixed. | A terms document can change only while the sale is in setup and its terms hash is not set yet. This sale has left setup, or its terms hash is set or being set, so the terms investors accept can no longer change. | Keep the current terms documents. Other document types still upload and delete as usual. To offer different terms, create a new sale. | info | No | 409 |
| DALP-12393 | `party.recovery.ATTEMPTS_EXHAUSTED` | domain | Identity recovery has run out of attempts. | This user's recovery failed sixteen times, the most attempts the platform runs for one recovery, or the account lifecycle refused to run it. | Contact support with the X-Request-Id response header before starting another recovery. | error | No | 409 |
| DALP-12394 | `party.recovery.FAILED` | domain | Identity recovery stopped before it finished. | A step of this user's recovery failed, so the recovery stopped before it finished. | Read the recovery status for the step that failed, correct its cause, then execute the recovery again to start a new attempt. | error | No | 409 |
| DALP-12395 | `MULTISIG_THRESHOLD_UNREACHABLE` | client | This signer change leaves the wallet unable to reach its threshold. | After the change, the combined weight of the wallet's signers would be below the threshold, so no transaction could collect enough signatures. Nothing was queued. | Lower the threshold first, keep enough signer weight, or add a signer before removing one, then send the change again. | info | No | 422 |
| DALP-12396 | `MULTISIG_SIGNER_ALREADY_HELD` | client | This address is already a signer of the wallet. | The multisig wallet already counts this address among its signers, so adding it again would change nothing. Nothing was queued. A pending change that already adds this address answers the same way. | Choose a signing key the wallet does not hold yet, then accept the invite again. | info | No | 409 |
| DALP-12397 | `MULTISIG_INVITER_UNAUTHORIZED` | client | The sender of this invite can no longer change the wallet's signers. | Since the invite was sent, its sender stopped holding a seat or the right to act for the multisig wallet. Nothing was queued and no key was bound. | Ask a current signer of the wallet to send a new invite. | info | No | 409 |
| DALP-12398 | `WALLET_CHECKER_IS_OWNER` | client | A wallet's owner cannot be its own checker. | A checker approves the transactions a wallet's owner starts, so the checker must be another person. The email names the wallet's owner. Nothing changed. | Name another member of this organization as the checker. | info | No | 409 |
| DALP-12399 | `WALLET_CHECKER_NOT_MEMBER` | client | The checker must be a member of this organization. | No member of this organization signs in with that email, so nobody could approve the wallet's transactions. Nothing changed. | Invite the person to the organization first, or name an existing member as the checker. | info | No | 409 |

The previous page is [DALP-12200 to DALP-12299](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference/dalp-12200-12299). The next page is [DALP-12400 to DALP-12499](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference/dalp-12400-12499).


# DALP-12400 to DALP-12499

Source: https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference/dalp-12400-12499
Cause, fix, HTTP status and retry flag for every Platform API error with a code from DALP-12400 to DALP-12499.

This page lists the 14 errors the Platform API can return with a code from DALP-12400 to DALP-12499. Match the `id` in the error envelope to the DALP Code column, then read Retryable and Suggested Fix. The [Platform API error reference](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference#how-to-use-this-reference) explains each column, including Severity, and the [DALP error index](https://docs.settlemint.com/docs/api-reference/errors) lists the page for every code range.

| DALP Code | Machine name | Category | Message | Why | Suggested Fix | Severity | Retryable | HTTP Status |
| --- | --- | --- | --- | --- | --- | --- | --- | --- |
| DALP-12400 | `MULTISIG_ACCOUNT_ABSTRACTION_REQUIRED` | client | Multisig wallets need account abstraction, which this organisation does not use on this network. | A multisig wallet is a smart contract wallet, and this organisation does not drive account abstraction on this network, so the draft step was refused before anything was stored. | Use a single-key wallet, or ask an operator to enable account abstraction for this organisation on this network. | info | No | 400 |
| DALP-12401 | `CUSTODY_ONLY_LIVE_KEY` | domain | This is the participant's only live key. | Revoking a key needs approval from another live key of the same participant, and none exists, so the request could never complete. Nothing changed. | If the key is lost or stolen, use lost-wallet recovery, which moves the tokens to a new wallet. If you still hold the key and its wallet is empty, archive it instead. | info | No | 409 |
| DALP-12402 | `REGISTRATION_WALLET_NOT_BOUND` | domain | The participant's new wallet is not bound to its identity yet. | A wallet joins an approved identity's registration only once its key is bound to that identity, and none of the participant's new wallets is bound yet, for example while the key is still waiting for a signature. Nothing changed. | Retry once the wallet's key has been added to the identity. | info | No | 409 |
| DALP-12403 | `CUSTODY_KEY_HOLDS_TOKENS` | domain | This key still holds tokens. | Revoking a key that holds tokens would strand them at an address that can no longer sign. Nothing changed. | Use lost-wallet recovery, which moves the tokens to a new wallet, then revoke the key. | info | No | 409 |
| DALP-12404 | `CUSTODY_ARCHIVE_HOLDS_TOKENS` | domain | A wallet still holds tokens. | A wallet of this participant still holds tokens, and archiving a key before they are moved can leave them at an address nobody manages. Nothing changed. | Transfer the tokens to another wallet, then archive the key. If the key is lost, use lost-wallet recovery. | info | No | 409 |
| DALP-12405 | `CUSTODY_ARCHIVE_LIVE_WALLET` | domain | A smart wallet on this key is still live. | Archiving the key while a smart wallet still uses it would leave that wallet without a signer. Nothing changed. | Archive the smart wallet first, then archive this key. | info | No | 409 |
| DALP-12406 | `CUSTODY_SCOPE_DENIED` | permission | You cannot manage this custody account. | The request names a participant that is not yours, an invitation that is not open to you, or no active organization. Nothing changed. | Only the user a participant belongs to can manage its custody accounts. Switch to one of your own participants in an organization you belong to, or ask that user to make the change. | info | No | 403 |
| DALP-12407 | `platform.addonApprovals.APPROVAL_NOT_REQUIRED` | client | This call needs no checker approval. | The access manager needs no checker approval for this call, so there is nothing to propose. | Send the call to data.target directly from a wallet that holds its role. | info | No | 422 |
| DALP-12408 | `platform.addonApprovals.PROPOSAL_REFUSED` | contract | The access manager refused this proposal change. | The access manager refused this proposal change. Read data.reason for the cause and data.revert for the contract error. | Read data.reason and the proposal, act from a wallet that may make this change, then send it again. | info | No | 422 |
| DALP-12409 | `WALLET_VERIFICATION_STRONGER_FACTOR_REQUIRED` | permission | This action needs the wallet authenticator code. | The account holds a wallet authenticator, so a PIN or recovery code does not confirm this action, and the platform changed nothing. `data.verificationType` names the method that was sent and `data.requiredType` the method that is required. | Enter the wallet authenticator code and send the request again with a fresh step-up challenge. If the authenticator device is lost, recover access from the account Security page first. | info | No | 403 |
| DALP-12410 | `WALLET_PIN_RESET_NOTICE_FAILED` | dependency | The wallet PIN was reset, but the notice email could not be sent. | The member's wallet PIN was removed and every session of the member ended. Only the email that tells the member could not be sent. | Do not repeat the reset: it would run again and can remove a PIN or sessions the member set up since. Tell the member another way. | error | No | 503 |
| DALP-12411 | `platform.addonApprovals.APPROVAL_REQUIRED` | client | This change needs checker approval. | The access manager's checkers must approve this change before it can be sent. | Propose data.calldata to data.target under data.makerRole, collect the approvals, then send the same request again or execute the proposal. | info | No | 422 |
| DALP-12412 | `settlement.sale.APPROVER_SHORTFALL` | client | This organisation has no second owner to approve the request. | Creating, activating, ending or finalizing an offering, or running its allocation, waits for an organisation owner other than the requester to approve it while offerings approval is on, but this organisation has no other owner. | Add another owner to the organisation, then send the request again, or turn offerings approval off in Organisation settings, General. | info | No | 422 |
| DALP-12413 | `CUSTODY_DIRECT_PARTICIPANT_HAS_KEY` | domain | This participant signs with one key. | A participant that signs directly holds one live key, and that key's address is the address its roles and tokens sit on, so a second key could never act for it. Nothing changed. | To replace the key, use lost-wallet recovery, which moves its tokens to the new wallet. If you still hold the key, remove it first, then add the new one. | info | No | 409 |

The previous page is [DALP-12300 to DALP-12399](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference/dalp-12300-12399). The next page is [DALP-13000 to DALP-13999](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference/dalp-13000-13999).


# DALP-13000 to DALP-13999

Source: https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference/dalp-13000-13999
Cause, fix, HTTP status and retry flag for every Platform API error with a code from DALP-13000 to DALP-13999.

This page lists the 2 errors the Platform API can return with a code from DALP-13000 to DALP-13999. Match the `id` in the error envelope to the DALP Code column, then read Retryable and Suggested Fix. The [Platform API error reference](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference#how-to-use-this-reference) explains each column, including Severity, and the [DALP error index](https://docs.settlemint.com/docs/api-reference/errors) lists the page for every code range.

| DALP Code | Machine name | Category | Message | Why | Suggested Fix | Severity | Retryable | HTTP Status |
| --- | --- | --- | --- | --- | --- | --- | --- | --- |
| DALP-13001 | `TOKEN_PERMIT_READ_REFUSED` | dependency | Permit information cannot be read: `{operation}` failed (`{reason}`). | The indexed domain separator is absent, or the permit feature returned a terminal read failure. | Check the permit feature and indexer on the selected network; include the request ID when reporting the failure. | error | No | 422 |
| DALP-13995 | `GATEWAY_CLIENT_FLAGGED` | client | The gateway's client is flagged. | A compliance claim of the gateway's client was revoked or expired, so no move that pays or credits the client runs: no withdrawal can be requested, cleared, collected or exited with its coins, and no deposit can be cleared or retried. | Have the claim issued again, or ask a screener to clear the flag on the gateway. | info | No | 422 |

The previous page is [DALP-12400 to DALP-12499](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference/dalp-12400-12499). The next page is [DALP-14000 to DALP-14049](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference/dalp-14000-14049).


# DALP-14000 to DALP-14049

Source: https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference/dalp-14000-14049
Cause, fix, HTTP status and retry flag for every Platform API error with a code from DALP-14000 to DALP-14049.

This page lists the 48 errors the Platform API can return with a code from DALP-14000 to DALP-14049. Match the `id` in the error envelope to the DALP Code column, then read Retryable and Suggested Fix. The [Platform API error reference](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference#how-to-use-this-reference) explains each column, including Severity, and the [DALP error index](https://docs.settlemint.com/docs/api-reference/errors) lists the page for every code range.

| DALP Code | Machine name | Category | Message | Why | Suggested Fix | Severity | Retryable | HTTP Status |
| --- | --- | --- | --- | --- | --- | --- | --- | --- |
| DALP-14001 | `VENUE_CONFIGURATION_REQUIRED` | domain | The venue configuration is missing. | The venue exists on-chain but its application configuration is missing. | Repeat creation with the same venue name to restore its configuration. | info | Yes | 409 |
| DALP-14002 | `VENUE_DEPLOYMENT_PENDING` | operational | The venue deployment is still being indexed. | The factory state or venue creation transaction cannot be confirmed yet. | Retry the same venue creation request after the chain and indexer are available. | error | Yes | 503 |
| DALP-14003 | `MARKET_LISTING_QUEUE_REFUSED` | domain | The instrument listing was refused. | The venue rejected the listing transaction, so no instrument was listed on-chain. | Use `data.errorName` and `data.selector`, when present, to find the venue rule the listing broke. Review the instrument sizes, fees, and fee account, then request the listing again. | info | No | 422 |
| DALP-14004 | `MARKET_LISTING_PENDING` | operational | The instrument listing outcome is not confirmed. | The listing request may have reached the chain, but its outcome cannot be confirmed yet. | Check the instrument list for this venue and token pair before sending another listing request. | error | No | 503 |
| DALP-14005 | `DISTRIBUTION_WATERFALL_FEATURE_NOT_FOUND` | domain | This token carries no distribution-waterfall feature. | This operation targets the distribution-waterfall feature, and this token has no such feature attached. | Run the operation on the share class that carries the distribution-waterfall feature, or attach the feature to this token first. | info | No | 404 |
| DALP-14006 | `DISTRIBUTION_WATERFALL_DENOMINATION_UNREADABLE` | operational | The distribution-waterfall feature did not answer which asset it pays in. | The allowance is granted on the pool's denomination asset, which is read from the feature on chain. That read returned no asset, so approving anything now risks approving the wrong token. | Restore chain access and confirm the feature is deployed, then grant the allowance again. | error | Yes | 503 |
| DALP-14007 | `DISTRIBUTION_WATERFALL_UNKNOWN_PRIORITY_ROW` | client | The waterfall has no priority row for this determination kind. | Distribution netting applies to a configured priority row. The supplied determination kind does not name one. | Use the determination-kind hash of a priority row configured on this waterfall. | info | No | 400 |
| DALP-14008 | `DISTRIBUTION_WATERFALL_UNKNOWN_CLASS_ROLE` | client | The waterfall has no class with this role. | Distribution netting applies to a configured share class. The supplied role does not name one. | Use a class role configured on this waterfall. | info | No | 400 |
| DALP-14009 | `DISTRIBUTION_WATERFALL_NETTING_LOCKED` | domain | Distribution netting terms are locked for this priority row. | A distribution has already been funded under this priority row, so its netting terms cannot change. | Keep the current netting terms for this row. Configure netting before funding a distribution under a new row. | info | No | 409 |
| DALP-14010 | `MARKET_LISTING_REFUSED` | domain | The venue already lists this security under another trading model. | The venue admits each security under one trading model, and an instrument for this security already runs in a different mode. | List the security in the mode its existing instrument uses, or delist that instrument first. A venue admin can also turn the rule off. | info | No | 409 |
| DALP-14011 | `VENUE_CREATION_REFUSED` | domain | The trading venue could not be created. | A creation precondition failed: the organisation has no deployed system or venue factory, no wallet is selected as the initial venue admin, or the organisation's operations signer is unbound or holds neither the system manager nor the venue manager role. The factory can also refuse the venue itself: it has no venue implementation set, the access manager addon is not registered, the venue key is already used, or its answer could not be read. The reason in the response names the failed check. | Resolve the named reason, then create the venue again. For a missing role, a system admin grants the venue manager role to the account in the response. | info | No | 409 |
| DALP-14012 | `CORPORATE_ACTION_INSTRUMENT_MISSING` | domain | This Corporate Action pays a whole multi-class instrument, and this token is not one class of one. | A coordinated distribution splits one pool across the share classes of one instrument, reading the split from the distribution-waterfall feature on the class that holds the pool. This token either belongs to no paired instrument or carries no waterfall. | Raise it on the share class that carries the distribution-waterfall feature. If the instrument was issued outside a paired run, or predates the waterfall, attach the feature first. | info | No | 409 |
| DALP-14013 | `CORPORATE_ACTION_POOL_UNFUNDABLE` | domain | The executing wallet cannot fund this pool. | Funding a coordinated distribution pulls the whole pool from the wallet that signs the confirm, so that wallet must hold the pool in the denomination asset and must have approved the distribution-waterfall feature to spend it. The executing wallet does not satisfy both. | Send the pool amount to the executing wallet in the denomination asset, approve the distribution-waterfall feature for at least that amount from the same wallet, then confirm again. | info | No | 409 |
| DALP-14014 | `VENUE_OPERATOR_ROLE_REQUIRED` | permission | The platform admin or organization owner role is required. | Creating a trading venue or listing an instrument is restricted to a platform admin or an owner of the organization, and this account holds neither role. | Ask a platform admin or an owner of the organization to make this request. | info | No | 403 |
| DALP-14015 | `MARKET_PAIR_ALREADY_LISTED` | domain | The venue already lists this pair. | An instrument for this base and quote token pair already exists on the venue, so listing it again would create a duplicate. | Use the existing instrument, or list a different pair. | info | No | 409 |
| DALP-14016 | `CORPORATE_ACTION_WATERFALL_CANNOT_RECEIVE` | domain | The denomination asset refuses to pay this pool into the distribution waterfall. | Funding a coordinated distribution transfers the pool from the executing wallet into the distribution-waterfall feature. A simulated transfer of the denomination asset into the waterfall reverts, so funding would revert too. A denomination that gates recipients by identity refuses a waterfall that has no identity, and a paused denomination refuses every transfer. | Read the contract error in the message. For TransferNotCompliant, call ensurePoolReceiver with the class token on the distribution-waterfall factory as the token's governance, which gives a waterfall deployed before that support its identity. Otherwise clear the denomination's refusal, for example by unpausing it, then preview or confirm again. | info | No | 409 |
| DALP-14017 | `MARKET_ADMISSION_REFUSED` | domain | The venue refused this listing or instrument change. | Only a private listing states its sponsorship, and it must. Where the venue sets admission minimums, a private listing also states the value and share count it makes available, at or above those minimums, and the date those figures were established, which cannot be in the future. A private instrument takes limit orders only, good-till-cancelled orders (plus good-till-date and day orders on the continuous book), and shows participants only the top of the book. An instrument group must be one the venue defines. A venue can also limit the order types and time in force every market on it accepts: a market states only entries inside that limit, and the venue cannot set a limit that leaves a live market with no order type or no time in force. The field in the response names what is missing, too low, or not allowed. | Complete the named field, drop the sponsorship from a public listing, raise the stated value or share count to the minimum in the response, state a past date for the figures, narrow a private instrument's order types, time in force, or depth to what a private instrument allows, or pick an instrument group the venue defines, then try again. For a venue limit, state only the order types and time in force the venue allows, widen the venue limit, or first change the market the message names. A venue admin can change the minimums. | info | No | 409 |
| DALP-14018 | `ASSET_TYPE_TEMPLATE_NOT_UNPUBLISHABLE` | domain | The asset type template is not published, so it cannot be unpublished. | The template is still a draft, or your organization already has it unpublished. Unpublishing applies only to a template your organization currently offers for issuance. | Read the template and check `isDraft` and `isPublished`. Publish a draft once it is ready; leave an unpublished template as it is. | info | No | 409 |
| DALP-14019 | `TOKEN_CREATE_TEMPLATE_UNPUBLISHED` | client | The instrument template is unpublished for your organization. | Your organization does not currently offer this instrument template for issuance. A DALP Library template stays unpublished until your organization publishes it, and a published template can be unpublished again. | Publish the template from the Instrument templates overview, or call `PUT /api/v2/settings/asset-type-templates/:assetTypeTemplateId/publication`, then create the token again. | info | No | 409 |
| DALP-14020 | `TOKEN_ISSUANCE_RUN_TEMPLATE_UNPUBLISHED` | client | An instrument template of this issuance is unpublished for your organization. | Your organization does not currently offer the instrument template of one member for issuance. A DALP Library template stays unpublished until your organization publishes it, and a published template can be unpublished again. | Publish the template from the Instrument templates overview, or call `PUT /api/v2/settings/asset-type-templates/:assetTypeTemplateId/publication`, then review and accept the issuance again. | info | No | 409 |
| DALP-14021 | `CORPORATE_ACTION_PAYOUT_INELIGIBLE` | domain | The payout token cannot be transferred to `{ineligibleCount}` of the parties that would receive it. | The payout token refuses a transfer from the treasury to one or more holders that would receive a payout: the holder is not verified in its identity registry or its compliance refuses the payout, the payout token's fee recipient cannot receive the transfer fee on that payout, or the treasury cannot pay the payout token's external transfer fee for that many claims. Those holders would fail when they claim. | Read the dividend's denomination eligibility to see which holders are refused and why, then make those holders or the payout token's fee recipient eligible to receive the payout token, fund the treasury's fee-token balance and allowance, or change the dividend's payout token, and declare again. | info | No | 409 |
| DALP-14022 | `PORTFOLIO_HOLDINGS_PROJECTION_INVALID` | dependency | Indexed holdings data validation failed. | A field in an indexed token row a portfolio read needs (holdings, price, metadata, account, policy, or ownership) does not match the expected format. | Do not retry. Contact support with the X-Request-Id response header so an operator can reindex the affected token data. | error | No | 500 |
| DALP-14023 | `ASSET_TYPE_TEMPLATE_USED_BY_PUBLISHED_STRUCTURE` | domain | A published instrument structure uses the asset type template, so it cannot be unpublished. | Your organization offers an instrument structure that issues this template as one of its members, and the structure stays issuable only while every member template is published. `data.structures` lists each such structure by `id` and `name`. | Unpublish the listed structures with `PUT /api/v2/settings/asset-type-template-structures/:structureId/publication`, then unpublish the template. | info | No | 409 |
| DALP-14024 | `TOKEN_ISSUANCE_RUN_STRUCTURE_UNPUBLISHED` | client | The instrument structure of this issuance is unpublished for your organization. | Your organization does not currently offer this instrument structure for issuance. A DALP Library structure stays unpublished until your organization publishes it, a published structure can be unpublished again, and a structure reads unpublished while one of its member templates is unpublished. | Publish the structure from the Structures tab of Instrument templates, or call `PUT /api/v2/settings/asset-type-template-structures/:structureId/publication`, then review and accept the issuance again. | info | No | 409 |
| DALP-14025 | `PAYER_NOT_FOUND` | client | `{payerAddress}` is not a wallet this organization pays gas from on this network. | Withdrawals move funds out of the organisation's relayer, bundler, operator wallet, bank-rail wallet or paymaster deposit on the request's network. The address is none of them. | Withdraw from a wallet listed under Organisation settings, Transaction funding, for this network. | info | No | 404 |
| DALP-14027 | `PAYER_WITHDRAWAL_EXCEEDS_AVAILABLE` | client | At most `{withdrawableWei}` wei can be withdrawn from this wallet now. | A wallet keeps enough to pay for the withdrawal itself, including a replacement at a raised fee, so a withdrawal cannot take its whole balance. A paymaster's sponsorship reserve can be withdrawn up to its current EntryPoint deposit. A withdrawal of zero is refused the same way. | Withdraw no more than the withdrawable amount, which the withdrawable read of the same wallet returns. | info | No | 422 |
| DALP-14028 | `PAYER_DESTINATION_REFUSED` | client | `{destination}` cannot receive this withdrawal. | The destination is the zero address, the wallet the funds would leave, or an address that reverts a plain native transfer. | Name a different destination address. | info | No | 422 |
| DALP-14029 | `TRANSACTION_WORKFLOW_OWNED` | client | This transaction is owned by a workflow, so an operator cannot retry it on its own. | The transaction request is a workflow status handle or a step of a role set. A status handle has no write to replay. A role-set step, including one that undoes an earlier step, belongs to a role change whose workflow owns its check, undo, and expiry, so sending it again alone could change a role with none of them. | Inspect the owning workflow. To repeat a role change, read the role set's transaction request, and once it has ended, send a new role set. For any other workflow, force-retry only its failed executable transaction request. | info | No | 409 |
| DALP-14030 | `CORPORATE_ACTION_CALL_PROTECTED` | domain | This instrument cannot be called before its first call date. | The instrument's metadata names a first call date, and the issuer may call every holder only on or after it, or from the instrument's long-stop date when that comes first. A long-stop date counts only when the token recorded it as unchangeable at issuance. A calendar date (YYYY-MM-DD) starts that day in UTC. A date in any other format also refuses the call, and so does more than one recorded first call date. | Confirm this call on or after the first call date, or the long-stop date when that comes first. | info | No | 409 |
| DALP-14031 | `TRANSACTION_PREPARATION_NOT_FOUND` | client | Transaction preparation not found. | The platform has no transaction preparation with that id for the calling user in this organization. A preparation another user created, or one that belongs to another organization, is reported the same way as a missing one to prevent enumeration. | Use the preparationId that the prepare call returned to you. If you no longer have it, prepare the operation again and authorize the new preparation. | info | No | 404 |
| DALP-14032 | `TRANSACTION_PREPARATION_ACCOUNT_INELIGIBLE` | client | This custody account cannot authorize a transaction preparation. | A preparation needs an active custody account that you hold in this organization, on the requested network, with a provider that lets you sign yourself. The account this request relies on does not meet those conditions. An account that does not exist, or that another user or organization holds, gets this same answer. | Prepare the operation with an externally signing custody account that you hold in this organization on the requested network. An account whose keys a managed custody provider holds does not use preparations: send its operations through their regular API routes, and the platform signs them. | info | No | 422 |
| DALP-14033 | `TRANSACTION_PREPARATION_BINDING_CONFLICT` | client | The request does not match how the transaction preparation is bound. | A preparation fixes its signing method, executor, custody account and operation when you create it, and every later call must match them. This request sends a claim, user operation or authorization artifact for a different signing method or executor, or an artifact kind this route never accepts. A create request gets this answer when its idempotency key already names a different preparation, or when the smart wallet already has an open operation its owner signs. The request is also refused when a smart wallet cannot prefund the operation, a later step of a chain carries value, or the transaction queue refuses the operation as input. | Read the preparation and send the claim, attachment or artifact that matches its `signingMethod` and `executor`. Use a new idempotency key for a different operation. Finish or let expire the open owner-signed operation before you prepare another on the same smart wallet. | info | No | 409 |
| DALP-14034 | `TRANSACTION_QUEUE_SMART_WALLET_GAS_REQUIRED` | domain | The smart wallet needs gas for this operation. | This wallet signs its own user operations, and nothing sponsors them, so its smart wallet pays the gas. It holds less native currency than the operation needs. | Send at least `shortfallWei` wei of the chain's native currency to `smartWalletAddress`, then submit the request again. | info | No | 422 |
| DALP-14035 | `TRANSACTION_CANCEL_CUSTODY_PARKED` | domain | A custody provider holds this transaction for approval. | A custody provider holds an approval request tied to this cancel. Either the provider held the replacement that the cancel signed and the platform withdrew it, or the provider holds this transaction and the platform could not withdraw it. The platform cannot withdraw a request when the provider does not support withdrawal, did not confirm it, or the request already ended. | Read the transaction status. When `custodyApproval.withdrawable` is true, send the cancel again after the platform next reads the request at the provider. Otherwise send the cancel again, which files a new request if the held replacement was withdrawn. If the provider still holds the request, reject it in the custody provider's approval console or wait for the approvers to decide. | info | No | 409 |
| DALP-14036 | `ORDER_SIGNING_PENDING` | domain | The order signature waits for a custody approval. | A custody approval rule holds the order signature until an approver decides. | Ask an approver to approve the request with this approval reference before it expires. Then sign the same order again with the same fields, salt and expiry. | info | No | 409 |
| DALP-14037 | `TOKEN_PERMIT_SIGNING_PENDING` | domain | The permit signature waits for a custody approval. | A custody approval rule holds the permit signature until an approver decides. | Ask an approver to approve the request with this approval reference before it expires. Then sign the same permit again with the same spender, value and deadline. | info | No | 409 |
| DALP-14038 | `TOKEN_PERMIT_CUSTODY_APPROVAL_CLOSED` | domain | The custody approval for the permit closed. | The custody approver rejected the permit signature, or its approval expired before an approver decided. | Ask the custody approver why the request closed. Then sign a new permit. | info | No | 409 |
| DALP-14039 | `TOKEN_CREATE_WORKFLOW_FAILED` | operational | Token creation workflow ended in a terminal failure. | A step of the token creation workflow failed for a reason other than a contract revert or a temporary outage, so the workflow stopped. Earlier steps may already have landed: the token can exist on chain even though the create did not finish. | Read data.step for the failed step (absent when it is not identified) and data.reason for the kind of failure (transaction-failed, data-invalid, workflow-check-failed, price-feed-not-authorized, price-feed-conflict, price-feed-unavailable, signing-failed or unknown), check the token on chain before creating again, then submit a new create with a new idempotency key. Send the request id to support if the cause is unclear. | error | No | 500 |
| DALP-14040 | `PAYMASTER_SPONSORSHIP_UNAVAILABLE` | client | Paymaster sponsorship is unavailable on this network. | Sponsorship needs the organization to use smart accounts, an active system on the network, a deployed paymaster, and a ready paymaster signing key; `data.blocker` names the first one that is missing. | Resolve the condition `data.blocker` names (enable smart accounts, wait for the network's system and paymaster to finish deploying, or let the paymaster signer finish provisioning), then retry. | info | No | 409 |
| DALP-14041 | `TREASURY_DISCLOSURE_WITHHELD` | permission | Redemption funding is not shared with holders. | This organisation has not allowed holders to see how the issuer funds redemptions, and the caller does not manage this token. | Ask the issuer to share redemption funding with holders in the organisation settings, or use a wallet that manages the token. | info | No | 403 |
| DALP-14042 | `TOKEN_CREATE_PAYOUT_TREASURY_IS_TOKEN` | domain | The `{feature}` treasury `{treasury}` is a token contract, not a wallet. | A token contract cannot pay out the payment currency, so every payout drawn from it reverts. | Pick the wallet that holds the payment currency. | info | No | 422 |
| DALP-14043 | `CORPORATE_ACTION_WATERFALL_CLASS_DIVIDEND` | domain | This share class pays through a distribution waterfall, so it takes no plain dividend. | A class of an instrument that carries a distribution waterfall is paid by the waterfall's coordinated distribution. A plain dividend on that class would pay its holders outside the waterfall's priority order. | Open a coordinated distribution on the instrument instead. It declares each class's dividend in waterfall order. | info | No | 409 |
| DALP-14044 | `CORPORATE_ACTION_COORDINATED_DIVIDEND_HELD` | domain | A coordinated distribution still holds this dividend. | An in-flight coordinated distribution declared this dividend as one of its class legs. Cancelling it alone would leave that run paying the other classes without this one. | Abort the coordinated distribution named in the message. Its abort cancels every dividend it declared. | info | No | 409 |
| DALP-14045 | `settlement.http.PROJECTION_INVALID` | operational | Indexed token data validation failed. | An indexed token row the settlement read needs does not match its expected shape, so the read cannot succeed as asked. | Ask an operator to reindex the affected token range, then request the read again. If it still fails, contact support with the X-Request-Id response header. | error | No | 500 |
| DALP-14046 | `CORPORATE_ACTION_CLASS_TREASURY_MISMATCH` | domain | A share class pays its dividends from a wallet other than the distribution waterfall. | A coordinated distribution pays each class's holders from the money the waterfall holds for that class. A class whose dividend-yield feature pays from another treasury would draw its claims from that treasury, and the money the waterfall holds for the class could never be paid out. | Give the named class a dividend-yield feature whose treasury is the instrument's distribution waterfall, then preview again. | info | No | 409 |
| DALP-14047 | `CORPORATE_ACTION_HOLDER_LIMIT_EXCEEDED` | domain | A share class had more holders on the record date than one dividend can pay. | A class dividend records at most 16,384 holders. The named class had more on the record date, so its dividend could not be recorded and the money funded for it could not be claimed. | Do not fund this distribution. Abort it and pay the class another way. | info | No | 409 |
| DALP-14048 | `CORPORATE_ACTION_UNDECLARED_LEG_UNRELEASED` | domain | An earlier distribution still holds money for a class dividend that was never declared. | One class's leg of an earlier distribution was funded, its dividend was never declared, and its money has not been released. Until it is released, that leg still counts toward the class's recovered capital, so a new priority distribution would pay the class less than it is owed. | Open the earlier corporate action named in the refusal, release that class's money, then preview this distribution again. | info | No | 409 |
| DALP-14049 | `CORPORATE_ACTION_MATURITY_DATE_NOT_REACHED` | domain | This bond matures at `{maturityDate}`, so its maturity redemption cannot be recorded yet. | Recording a maturity redemption matures the bond on chain. The bond accepts that only when the chain time has reached its maturity date, and the chain time is still before that date. | Record the maturity redemption again at or after the maturityDate in this response. | info | Yes | 409 |

The previous page is [DALP-13000 to DALP-13999](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference/dalp-13000-13999). The next page is [DALP-14050 to DALP-14099](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference/dalp-14050-14099).


# DALP-14050 to DALP-14099

Source: https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference/dalp-14050-14099
Cause, fix, HTTP status and retry flag for every Platform API error with a code from DALP-14050 to DALP-14099.

This page lists the 50 errors the Platform API can return with a code from DALP-14050 to DALP-14099. Match the `id` in the error envelope to the DALP Code column, then read Retryable and Suggested Fix. The [Platform API error reference](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference#how-to-use-this-reference) explains each column, including Severity, and the [DALP error index](https://docs.settlemint.com/docs/api-reference/errors) lists the page for every code range.

| DALP Code | Machine name | Category | Message | Why | Suggested Fix | Severity | Retryable | HTTP Status |
| --- | --- | --- | --- | --- | --- | --- | --- | --- |
| DALP-14050 | `CORPORATE_ACTION_BOND_ALREADY_MATURED` | domain | This bond has already matured, so it takes no maturity redemption. | The bond already reads as matured on the index or on chain. Its holders can redeem their own tokens, and the bond refuses a second maturity. | Do not record a maturity redemption for this bond. Its holders can already redeem their tokens. | info | No | 409 |
| DALP-14051 | `TOKEN_FEATURE_ATTACH_START_DATE_IN_FUTURE` | domain | The `{feature}` start date is after the chain's current block time. | The `{field}` value `{startDate}` is later than the next block's timestamp `{blockTimestamp}`, both in Unix seconds, and the feature cannot start in the future. | Set `{field}` to a time at or before the current block time, or leave it out, then attach or replace the feature again. | info | No | 422 |
| DALP-14052 | `TOKEN_FEATURE_ATTACH_PAYOUT_TREASURY_IS_TOKEN` | domain | The `{feature}` treasury `{treasury}` is a token contract, not a wallet. | A token contract cannot pay out the payment currency, so every payout drawn from it reverts. | Pick the wallet that holds the payment currency for `{field}`, then send the attach, replace or update again. | info | No | 422 |
| DALP-14053 | `TOKEN_FEATURE_ATTACH_CREATE_FEATURE_WOULD_REVERT` | domain | Deploying the `{feature}` feature would revert. | A simulation of the feature factory's createFeature or replaceFeature call reverted, so the attach or replace would fail on chain. | Use errorName and selector, when present, to find the configuration value the feature rejects, correct it, then attach or replace the feature again. | info | No | 422 |
| DALP-14054 | `ACCOUNT_KIND_SWITCH_BLOCKED` | client | The switch to smart wallets cannot start yet. | No network can host smart wallets yet, or a write on the organisation relayer has not finished. Starting now would queue writes that cannot land. | Read data.blocker: add a network that supports smart wallets, or let the writes in data.blockingTransactionIds finish (top up the relayer) or cancel them, then start the switch again. | info | No | 409 |
| DALP-14055 | `TOKEN_FEATURE_ATTACH_DEPENDENCY_NOT_ATTACHED` | domain | A feature `{feature}` needs is not attached. | `{feature}` declares other features as dependencies in the feature registry, and the ones listed in missing are not attached to this token. For example dividend yield reads holder balances at the record date, so it needs the historical balances feature. | Attach the features listed in missing first, then attach `{feature}` again. | info | No | 422 |
| DALP-14056 | `TRADING_VENUE_ANNOUNCEMENT_NOT_FOUND` | client | The announcement was not found. | The announcement id does not name a notice on the selected network that this request can read or withdraw. A notice that was withdrawn in the meantime, and a notice you are not allowed to see or withdraw, answer the same way. | Use an announcement id from the announcements list for the selected network. To withdraw a notice, use a wallet that holds the operator or admin role on the venue it belongs to. | info | No | 404 |
| DALP-14057 | `TOKEN_FEATURE_NOT_REPLACEABLE` | domain | This feature cannot be replaced. | The Booked movements feature is never replaced, because its lines and their holds would stay on the old instance. | Change the feature's settings through its settings route instead of replacing it. | info | No | 409 |
| DALP-14058 | `REGISTER_LINE_OPERATION_REJECTED` | domain | The movement could not be acted on. | The token has no Booked movements feature attached, or the movement is no longer waiting for a decision. | List the token's movements, then book or cancel one that is still requested. | info | No | 409 |
| DALP-14059 | `PRICE_BAND_INVALID` | client | The price band is invalid. | A saved configuration must use one price-band mode. Static limits must fit each inheriting instrument's quote-price tick grid exactly. Dynamic bands need a positive reference price that rolls to each official close. A minimum order quantity must be a multiple of the lot size and no larger than the maximum order quantity. A split cannot move an absolute band or push a price below one tick. | Clear the static or the dynamic legacy width, or select a new static or dynamic policy. Use prices on each inheriting instrument's tick grid and a positive rolling reference for dynamic bands. For a split, set the absolute band at the post-split prices in the same change. | info | No | 422 |
| DALP-14060 | `TRANSACTION_QUEUE_INPUT_INVALID` | client | The transaction queue refused the write's input. | The transaction queue checked the write before sending it and found a field it cannot use, so nothing was sent. | Correct the write's input and send it again. | info | No | 400 |
| DALP-14061 | `TRANSACTION_QUEUE_IDEMPOTENCY_CONFLICT` | client | The idempotency key already names a different write. | The transaction queue already holds a write under this idempotency key, and it is not the write in this request. | Send this write under a new idempotency key, or repeat the original write unchanged to read its result. | info | No | 400 |
| DALP-14062 | `TRANSACTION_QUEUE_FUNDING_REQUIRED` | client | The account that pays for this transaction does not hold enough funds. | The platform checks the paying account's balance before it sends a transaction, so it did not send this one and nothing reached the chain. | Fund the paying account, then try again. If a retry answers that the request already settled, send it as a new request. | info | No | 400 |
| DALP-14063 | `TRANSACTION_QUEUE_KEY_RETIRED` | client | The idempotency key is retired. | The transaction queue retired this idempotency key before any write carried it, so no write may run under it. | Do not send the write again under this key. Send it under a new idempotency key. | info | No | 400 |
| DALP-14064 | `TRANSACTION_QUEUE_TRANSACTION_NOT_FOUND` | client | The transaction queue holds no transaction the write refers to. | The write refers to a queued transaction the transaction queue has no record of. | Check the transaction the write refers to, or send the write as a new transaction under a new idempotency key. | info | No | 400 |
| DALP-14065 | `TRANSACTION_QUEUE_FAMILY_UNSUPPORTED` | client | The transaction queue does not run writes for this chain family. | The write names a transaction on a chain family this transaction queue does not drive. | Send the write to the network that serves that chain family. | info | No | 400 |
| DALP-14066 | `TRANSACTION_QUEUE_DUPLICATE_SETTLED` | client | The idempotency key already names a finished transaction. | A transaction under this idempotency key already failed or was cancelled, so the transaction queue did not run it again. | Read the earlier transaction's outcome. To try again, send the write under a new idempotency key. | info | No | 400 |
| DALP-14067 | `TRANSACTION_QUEUE_REFUSED` | client | The transaction queue refused the write. | The transaction queue refused the write before sending it, for a reason it does not publish as its own error. The request itself was read correctly. | Check the signing account and the write's idempotency key, then send it again. If it is refused again, contact support with `data.requestId`. | info | No | 400 |
| DALP-14068 | `TOKEN_REGISTER_LINE_REFUSED` | client | A token with booked movements needs a register reference and one movement per call. | A token with the booked movements feature books every mint, burn, forced transfer and transfer as one movement, and a booked movement carries a register reference. The call omitted the reference, named several movements, or sent a register reference to a token that does not carry the feature. | Send one movement per call and, for a mint, burn or forced transfer, include `registerReference`. | info | No | 422 |
| DALP-14069 | `platform.network.CUSTODY_PROVIDER_MISSING` | domain | No custody provider supports this network. | No healthy managed custody provider enabled for account creation supports this network. | In Organisation settings, open Custody, then Providers. Add missing network coverage, enable account creation, or restore provider health, then retry. | info | No | 409 |
| DALP-14070 | `CORPORATE_ACTION_CLAIM_STILL_OPEN` | domain | This class's dividend must be reclaimed before its money is released; its claim deadline is `{claimDeadline}`. | The class dividend of this distribution is still open for claims, or its claim deadline has passed and it has not been reclaimed, so its remaining money cannot be released yet. | Wait until the claimDeadline in this response has passed, reclaim the class dividend, then release the class's money. | info | No | 409 |
| DALP-14071 | `CORPORATE_ACTION_NOTHING_TO_RELEASE` | domain | There is nothing left to release for this class. | The class's leg of this distribution holds no money, either because nothing was funded to it or because it was already released. | Read the distribution's recovery state; no release is needed for this class. | info | No | 409 |
| DALP-14072 | `CORPORATE_ACTION_RUN_COMPLETED` | domain | A completed Corporate Action cannot be aborted. | The run already completed, so there is nothing left to abort. Reversing a completed run is a new action. | Read the record; start a new Corporate Action if the outcome needs reversing. | info | No | 409 |
| DALP-14073 | `CORPORATE_ACTION_ENTRY_ALREADY_PAID` | domain | This unpaid holder was already marked paid. | The unpaid holder entry already carries a payment record with who paid, when, and the reference. | Read the unpaid holders list. If the mark is wrong, a governance holder can reopen the entry with a reason and mark it paid again. | info | No | 409 |
| DALP-14074 | `REDEMPTION_REQUEST_NOT_FOUND` | domain | The redemption request was not found. | No redemption request with this identifier belongs to your wallets on this token. | List the token's redemption requests and use an identifier from that list. | info | No | 404 |
| DALP-14075 | `REDEMPTION_REQUEST_HOLDER_NOT_CALLER` | domain | The holder is not the wallet that signs the request. | A redemption request can only name the wallet that signs it, and the holder in this request is a different wallet. | Leave the holder out, or send the address of the wallet that signs the request. | info | No | 409 |
| DALP-14076 | `REDEMPTION_REQUEST_TOKEN_NOT_REDEEMABLE` | domain | This token does not take redemption requests. | Redemption requests are open only for fund tokens that can settle a cash buyback and do not use register lines. This token does not meet that rule, or the platform could not read its details. | Send the request for a fund token that meets the rule. If this token should meet it, check its type and features, then try again. | info | No | 409 |
| DALP-14077 | `REDEMPTION_REQUEST_EXCEEDS_AVAILABLE_UNITS` | domain | The amount is above the units available to redeem. | The wallet's available units, after its frozen units and the amount held by its open and settling redemption requests on this token, are fewer than the amount in the request. | Send an amount at or below the available units, or cancel an open request to release its units. | info | No | 409 |
| DALP-14078 | `REDEMPTION_REQUEST_CUT_OFF_PASSED` | domain | The cut-off for this redemption request has passed. | A redemption request can be cancelled only before its cut-off, and the cut-off for this request has passed. | Read the request for its cut-off time. Ask the fund operator to handle a request you cannot cancel. | info | No | 409 |
| DALP-14079 | `REDEMPTION_REQUEST_NOT_OPEN` | domain | The redemption request is not open. | Only an open redemption request can be cancelled, and this request has already left the open status. | Read the request to see its status. Create a new request if you still want to redeem. | info | No | 409 |
| DALP-14080 | `REDEMPTION_REQUEST_IDEMPOTENCY_KEY_REUSED` | domain | The idempotency key belongs to a different redemption request. | This key already created a request for another token or another amount, and a key names one request. | Send the new request with a new idempotency key. To read the earlier request, repeat it with the same token and amount. | info | No | 409 |
| DALP-14081 | `FUND_SUBSCRIPTION_OPERATION_REJECTED` | domain | The fund subscription could not be processed. | The token is not a fund without register lines, it has no subscription terms, the request does not exist or is no longer open, the cut-off has passed, the amount, stablecoin or investor does not meet the terms, or a dealing day cannot be settled: the day is not a weekday, no class NAV was published for it, no request is open through it, the class stablecoin cannot price the requests, or the settlement does not execute from the receiving treasury. | Read the token's subscription terms, its subscription requests and the class NAV for that dealing day, then repeat the call with values they allow: settle from the receiving treasury, on a weekday whose NAV is published. | info | No | 409 |
| DALP-14082 | `PAYMASTER_SIGNING_BINDING_MISSING` | client | The organization has no managed signing binding on this chain. | Reading or rotating the paymaster signer key goes through the organisation's managed custody binding on the paymaster's chain and system. The organisation has none there, or its binding operates another system. | Provision the organization's managed signing binding for this chain's system, then repeat the rotation. | info | No | 422 |
| DALP-14083 | `PAYMASTER_SIGNER_NOT_STAGED` | client | The paymaster has no staged custody signer to rotate. | A key rotation promotes a signer that custody has already staged for the paymaster. The paymaster has none staged, and no current signer from which to stage one. | Provision the paymaster signer in custody so the paymaster has a current signer, then repeat the rotation. | info | No | 409 |
| DALP-14084 | `market-data.feeds.WRITE_SCOPE_INVALID` | operational | The feed write's signer checks could not complete. | An indexed token row the feed write depends on does not match its expected shape, or the chain node refuses the feed signer key read as sent, so the write cannot succeed as asked. | Ask an operator to reindex the affected token range or correct the chain node's RPC configuration, then send the write again. If it still fails, contact support with the X-Request-Id response header. | error | No | 500 |
| DALP-14085 | `reporting.artifact.UNWRITABLE` | operational | The report file could not be written. | The platform read the report's data but could not write it in the requested format, for example because the holders exceed what one XLSX worksheet holds. The same request fails the same way. | Do not retry. Request another format, such as CSV, or contact support with the X-Request-Id response header. | error | No | 500 |
| DALP-14086 | `custody.participant.PROJECTION_INVALID` | operational | Indexed token data validation failed. | An indexed token row the participant wallet read needs does not match its expected shape, so the read cannot succeed as asked. | Reindex the affected token range, then request the read again. If the read still fails, contact support with the X-Request-Id response header. | error | No | 500 |
| DALP-14087 | `CUSTODY_DEPENDENCY_REFUSED` | operational | A custody dependency refused the request. | The custody provider, its credentials or the custody store refused a step this request needs, for a reason a retry does not change. | Do not retry. Contact support with the X-Request-Id response header so an operator can correct the custody configuration. | error | No | 500 |
| DALP-14088 | `reporting.dependency.REFUSED` | operational | A reporting dependency refused the request. | Object storage refused a step this request needs, for a reason a retry does not change. | Do not retry. Contact support with the X-Request-Id response header so an operator can restore the stored file. | error | No | 500 |
| DALP-14089 | `party.dependency.REFUSED` | operational | A party dependency refused the request. | A service the party domain depends on refused the request for a reason a retry does not change. | Do not retry. Contact support with the X-Request-Id response header so an operator can correct the cause. | error | No | 500 |
| DALP-14090 | `compliance.dependency.REFUSED` | operational | A KYC dependency refused the request. | Object storage or the secrets store refused a step the KYC route needs, for a reason a retry does not change. `data.dependency` names the step. | Do not retry. Contact support with the X-Request-Id response header and `data.dependency` so an operator can correct the cause. | error | No | 500 |
| DALP-14091 | `exec.secrets.SLOT_FAILED` | operational | The signer-key store refused the operation. | The signer-key store refused the operation for a reason that retrying will not change, such as a rejected credential, an invalid store configuration, or a malformed stored value. | Do not retry. Contact support with the X-Request-Id response header so an operator can correct the signer-key store. | error | No | 500 |
| DALP-14092 | `settlement.http.WRITE_OUTCOME_UNKNOWN` | dependency | Settlement write outcome still unknown. | The transaction queue may have accepted the settlement write, but its outcome could not be read. | Read the transaction request status using its id. Do not submit a replacement write. | error | No | 503 |
| DALP-14093 | `settlement.http.DOCUMENT_STORE_FAILED` | operational | The token-sale document store refused the operation. | The document store refused the operation for a reason that retrying will not change, such as a missing object or a store configuration fault. | Do not retry. Contact support with the X-Request-Id response header so an operator can check the document store. | error | No | 500 |
| DALP-14094 | `ASSET_TYPE_TEMPLATE_FEATURES_UNRESOLVABLE` | domain | The template's required features are incomplete or conflict: `{reason}`. | A feature in `requiredFeatures` depends on a feature the template does not carry, or two carried features cannot run on the same token. `data.reason` names each feature involved. | Add every named dependency to `requiredFeatures`, or remove one feature from each conflicting pair, then save or publish the template again. | info | No | 422 |
| DALP-14095 | `TOKEN_CREATE_FEATURE_CONFIG_INVALID` | domain | A feature configuration value cannot be deployed: `{reason}`. | Token create encodes each template feature's `featureConfigs` entry into the deploy call before anything is queued, and one value cannot be encoded or breaks a rule of its feature. `data.reason` names the feature and the value. | Correct the named value in the matching `featureConfigs` entry and resubmit the token creation request. | info | No | 422 |
| DALP-14096 | `REGISTER_LINE_NOT_FOUND` | domain | The movement was not found. | No movement with this number is visible to you on this token. | List the token's movements and use a number from that list. | info | No | 404 |
| DALP-14097 | `REGISTER_LINE_SUBSCRIPTION_REQUEST_OPEN` | domain | A subscription request is already open. | A holder can have one open subscription request at a time, and this holder has one that is still waiting. | Wait for the open request to be booked or cancelled, then request again. | info | No | 409 |
| DALP-14098 | `REDEMPTION_REQUEST_NOT_A_DEALING_DAY` | domain | The date is not a dealing day. | A fund settles redemption requests only on its dealing days, which are the weekdays from Monday to Friday. The date in this call falls on a Saturday or a Sunday. | Send a date from Monday to Friday. Use the dealing day of the requests you want to settle. | info | No | 409 |
| DALP-14099 | `REDEMPTION_REQUEST_NAV_UNAVAILABLE` | domain | The fund has no usable NAV for this dealing day. | The platform cannot price a unit for this dealing day. The system has no price feed directory, no NAV was published during the dealing day, or the NAV is too low to give a price above zero in the stablecoin's smallest unit. | Publish the fund's NAV for this dealing day to its price feed, then settle again. If the system has no price feed directory, set one up first. | info | No | 409 |

The previous page is [DALP-14000 to DALP-14049](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference/dalp-14000-14049). The next page is [DALP-14100 to DALP-14199](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference/dalp-14100-14199).


# DALP-14100 to DALP-14199

Source: https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference/dalp-14100-14199
Cause, fix, HTTP status and retry flag for every Platform API error with a code from DALP-14100 to DALP-14199.

This page lists the 41 errors the Platform API can return with a code from DALP-14100 to DALP-14199. Match the `id` in the error envelope to the DALP Code column, then read Retryable and Suggested Fix. The [Platform API error reference](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference#how-to-use-this-reference) explains each column, including Severity, and the [DALP error index](https://docs.settlemint.com/docs/api-reference/errors) lists the page for every code range.

| DALP Code | Machine name | Category | Message | Why | Suggested Fix | Severity | Retryable | HTTP Status |
| --- | --- | --- | --- | --- | --- | --- | --- | --- |
| DALP-14100 | `REDEMPTION_REQUEST_NO_OPEN_REQUESTS` | domain | No redemption request is open for this dealing day. | No investor has an open redemption request on this token for this dealing day or an earlier one. Requests that are cancelled, settled or rejected do not count. | List the token's redemption requests with the status open and read their dealing days. Settle a dealing day that has open requests. | info | No | 409 |
| DALP-14101 | `REDEMPTION_REQUEST_STABLECOIN_UNSUPPORTED` | domain | The settlement asset is not a supported stablecoin. | Redemptions are paid in an indexed ERC-3643 token of the stablecoin type. The denomination asset in this call is not one, or it is the fund token itself. | Send the address of an indexed stablecoin other than the fund token. Read the asset's type in the token catalog before you send it. | info | No | 409 |
| DALP-14102 | `REDEMPTION_REQUEST_CURRENCY_MISMATCH` | domain | The NAV and the stablecoin are priced in different currencies. | The platform pays cash only in the currency the NAV is quoted in. The stablecoin's price feed names another currency, or the NAV or the stablecoin has no currency on its feed. | Choose a stablecoin that is priced in the NAV's currency. If a feed names no currency, add it to that feed, then settle again. | info | No | 409 |
| DALP-14103 | `REDEMPTION_REQUEST_REQUESTS_CHANGED` | domain | The open requests changed while the settlement was prepared. | An investor created or cancelled a request, or another settlement took one, between the moment the platform read the open requests and the moment it recorded the plan. The platform recorded nothing. | Send the same call again. The platform reads the open requests again and settles the list as it stands. | info | Yes | 409 |
| DALP-14104 | `REDEMPTION_REQUEST_SETTLEMENT_KEY_REUSED` | domain | The idempotency key belongs to a different settlement. | This key already settled another dealing day, or paid in another stablecoin or from another treasury. A key names one settlement. | Send the new settlement with a new idempotency key. To read the earlier result, repeat that call with the same dealing day, stablecoin and treasury. | info | No | 409 |
| DALP-14105 | `REPORTING_ACK_RECEIPT_IN_USE` | domain | This authority receipt reference is already recorded on another submission. | Another submission already carries this authority receipt reference. | Enter the receipt reference the authority issued for this submission. | info | No | 409 |
| DALP-14106 | `compliance.provider.ACCESS_TOKEN_ISSUE_FAILED` | dependency | Compliance provider refused to issue an SDK access token. | The provider refused the SDK access token call for this subject, and asking again unchanged will get the same answer. | Check the provider credentials and its verification level for this subject, then request a new token. | error | No | 502 |
| DALP-14107 | `CORPORATE_ACTION_ACKNOWLEDGEMENT_REQUIRED` | domain | Confirm needs an acknowledgement of each consequence of the stored plan. | The stored plan leaves a class undeclared, money in the waterfall, holders out, or a funding shortfall, and the request's acknowledgements omit at least one. A second person's approval of the plan does not acknowledge them for the operator who confirms. | Review the stored plan, then confirm again with every value from data.missingAcknowledgements in acknowledgements. | info | No | 409 |
| DALP-14108 | `core.network.CHAIN_READ_INVALID` | operational | A chain read returned an unusable answer. | A chain read this request needs returned an answer the platform cannot use, so the request cannot succeed as asked. | Do not retry. Contact support with the X-Request-Id response header so an operator can check the chain node and the contract the request named. | error | No | 500 |
| DALP-14109 | `MATURITY_TOKEN_PAUSED` | domain | The token is paused. | A pause blocks maturing, topping up the treasury and redeeming until it is lifted. | Unpause the token, then repeat the maturity operation. | info | No | 409 |
| DALP-14110 | `CORPORATE_ACTION_DIVIDEND_DECLARED` | domain | Dividend `{dividendId}` that this Corporate Action declared is still live on chain, so the action cannot be discarded. | Recording a cash dividend or cash distribution declares its dividend on chain, and discarding the record does not cancel it. The dividend named in this response has not been cancelled. | Cancel the dividend named in this response, then discard the Corporate Action again. A dividend whose snapshot is already recorded can no longer be cancelled; confirm the Corporate Action to complete it instead. | info | No | 409 |
| DALP-14111 | `platform.network.ADD_REFUSED` | domain | The network cannot be added. | The organization cannot add this network in its current state. Read data.reason for the cause. | Read data.reason: already-added means the network is already part of the organization, deploying means its setup is still running, default-network means it is the organization's default network, and not-enabled means the deployment does not offer it. Wait or pick another network, then retry. | info | No | 409 |
| DALP-14112 | `MARKET_LOG_FENCE_LOST` | domain | Another write to this instrument's order log got there first. | Other requests wrote to this instrument's order log at the same moment, and this request lost its turn on every attempt. The same code answers an order whose signed fee limit no longer covers the venue's on-chain VAT, and a price-band change that a new listing's quote token overtook. | Send the request again. If a retried order placement or replacement is refused, place it as a new order. When the venue collects VAT on chain over the order's signed fee limit, sign a new order with a higher fee limit. | error | Yes | 409 |
| DALP-14113 | `bankRail.access.MANAGER_REQUIRED` | permission | Bank rail manager role required. | Only a bank rail manager of the organisation's system can set up or run its bank rail. The request's executor wallet does not hold that role, the organisation has no system on this network, or the request has no executor wallet to check. | Ask an organisation admin to grant you the bank rail manager role. | info | No | 403 |
| DALP-14114 | `bankRail.connection.UNAVAILABLE` | client | Bank connection not found. | No bank connection with this identifier exists in the active organisation. | List the organisation's bank connections and use one of their identifiers. | info | No | 404 |
| DALP-14115 | `bankRail.connection.STALE` | domain | Bank connection changed since it was read. | Another manager changed the bank connection after you read it, so its rowVersion no longer matches. | Read the connection again and repeat the change with its current rowVersion. | info | No | 409 |
| DALP-14116 | `bankRail.connection.SESSION_TAKEN` | domain | CompID pair already in use. | A bank connection with this senderCompId and targetCompId already exists on this platform. | Agree a different CompID pair with the bank, or use the existing connection. | info | No | 409 |
| DALP-14117 | `bankRail.connection.CREDENTIAL_CONFLICT` | domain | Logon password changed since it was read. | The FIX logon password changed after you read the connection, so its credentialVersion no longer matches. | Read the connection again and repeat the change with its current credentialVersion. | info | No | 409 |
| DALP-14118 | `bankRail.connection.CREDENTIAL_MISSING` | domain | Logon password not set. | The connection has no FIX logon password in the secret store, so it cannot be activated. | Set the logon password on the connection, then activate it. | info | No | 422 |
| DALP-14119 | `bankRail.connection.TRANSITION_REFUSED` | domain | Bank connection state change refused. | The connection's current state does not allow this change. Only an active connection can be suspended, and an activation fails when the connection changed state while it was being activated. | Read the connection's state and choose the change that state allows. | info | No | 409 |
| DALP-14120 | `bankRail.tokenLink.UNAVAILABLE` | client | Token link not found. | No token link with this identifier exists on the bank connection on the request's network, or the link is not one the rail wallet rotation suspended. | List the connection's token links and use one of their identifiers. | info | No | 404 |
| DALP-14121 | `bankRail.tokenLink.REFUSED` | domain | Token link refused. | The token cannot back this connection yet, and `data.reason` names the rule it fails: it has neither Booked movements nor the supply delegate feature (`needs-supply-delegate`), it lacks the Hold feature (`needs-hold`), a holder cannot request a redemption (`redemption-not-requestable`), it is not a catalogued custodian token on this chain (`not-custodian`), another organisation issued it (`not-issued`), its decimals cannot represent every minor unit of the currency (`decimals`), the connection already links a token (`currency-linked`), another connection links this token (`token-linked`), it already has supply (`supply-not-zero`), other accounts hold its supply management role (`supply-role-held`, named in `data.accounts`), your wallet cannot grant that role (`supply-role-missing`), accounts other than the rail wallet are its supply delegates (`supply-delegate-held`, named in `data.accounts`), the rail wallet is not a supply delegate that may mint and burn and your wallet cannot add it (`supply-delegate-missing`), its compliance stops the rail wallet holding it (`rail-wallet-ineligible`, with the failing rules in `data.blockers`), the rail wallet has no gas on a priced chain (`rail-wallet-unfunded`), a bank rail manager contained the rail wallet and its rotation is still open (`rail-wallet-contained`), the rail wallet already controls an escrow (`escrow-exists`) or controls more than one (`escrow-ambiguous`), your wallet does not hold the escrow manager role that creates the escrow (`escrow-manager-missing`), the link already has an open request to raise or clear a mint limit (`mint-limit-pending`), a mint cap was set on a link in booked mode, which mints through register lines and has no supply delegation to cap (`mint-cap-booked`), the link already has an open request to allow other supply managers (`supply-managers-pending`), other supply managers were allowed on a link in delegate mode, which has no supply management role holders to allow (`supply-managers-delegate`), the approval service refused the decision, for example because the manager who asked for the change cannot decide it or the request expired (`approval`), the organisation's rail wallet changed since the link was made, the decision names a request the link no longer has open, or an active link cannot be removed (`state`). | Resolve what `data.reason` names, then link, activate, change or remove again: link a token your organisation issued, revoke the role from, or remove as supply delegates, the accounts in `data.accounts`, ask a token admin to grant the role or a token governor to add the rail wallet as a supply delegate that may mint and burn, register the rail wallet's identity or clear the rules in `data.blockers`, fund the rail wallet, use the escrow the rail wallet already controls, ask a role admin to grant you the escrow manager role, follow the open rail wallet rotation: it moves the links to the new rail wallet when it completes, wait for another bank rail manager to decide the open mint-limit or allow-other-supply-managers request, leave the mint cap out on a booked link, change supply managers only on a booked link, or read the link again for its current request. | info | No | 422 |
| DALP-14122 | `bankRail.clientLink.UNAVAILABLE` | client | Client link not found. | No client link with this identifier exists on the bank connection. | List the connection's clients and use one of their identifiers. | info | No | 404 |
| DALP-14123 | `bankRail.clientLink.REFUSED` | domain | Client link refused. | The client cannot be linked, and `data.reason` names the rule it fails: another client of the connection uses this key (`key-taken`), the participant is not a member of the organisation or the wallet is not one of the participant's own unarchived EVM wallets (`wallet-not-owned`), the connection's token blocks the wallet for a reason the client cannot fix (`wallet-blocked`), the connection has no token link on this chain yet (`token-link-required`), a virtual-IBAN connection needs the client's virtual IBAN (`virtual-iban-required`), or a reference connection takes none (`virtual-iban-not-allowed`); a client that still has a proposed or active bank account cannot be removed (`accounts-live`), nor one with a credit still delivering to its custody gateway (`deliveries-open`); a delivery change names a rowVersion the link no longer has (`row-version`), decides a delivery request the link no longer has open (`state`), is decided by the manager who opened the request (`same-actor`), asks for delivery on a booked-supply token (`booked-mode`), asks while a request is already open (`delivery-request-open`), is approved after a check no longer passes (`delivery-stale`), or asks while a check fails (`preconditions-failed`, the message lists each failed check with its fix). | Link the connection's token first, then pick a wallet a member participant owns that the token does not block, with a key no other client uses, and send a virtual IBAN only on a virtual-IBAN connection. Refuse or revoke a client's bank accounts, and wait for its credits to finish delivering to its custody gateway, before removing it. Read the client again and repeat a delivery change with its current rowVersion, fix the checks a delivery request lists, and ask another bank rail manager to decide a delivery request you opened. | info | No | 422 |
| DALP-14124 | `AUTH_STORE_ROW_INVALID` | operational | Stored authentication data validation failed. | A stored authentication row does not have the shape the platform reads, so the request cannot succeed as sent. | Do not retry. Contact support with the X-Request-Id response header so the stored row can be corrected. | error | No | 500 |
| DALP-14125 | `compliance.store.ROW_INVALID` | operational | Stored KYC data validation failed. | A stored compliance record the KYC or user profile route reads does not match its expected shape, so the route cannot complete as asked. | Do not retry. Contact support with the X-Request-Id response header so the stored record can be repaired. | error | No | 500 |
| DALP-14126 | `bankRail.store.ROW_INVALID` | operational | Stored bank rail data is invalid. | A bank rail row in the store, such as a connection, link, operation or reserve balance, does not have the shape the platform reads, so this request cannot succeed until the row is repaired. | Do not retry. Contact support with the X-Request-Id response header so the stored row can be repaired. | error | No | 500 |
| DALP-14127 | `bankRail.credit.UNAVAILABLE` | client | Bank credit not found. | No credit with this identifier exists on the bank connection. | List the connection's credits and use one of their identifiers. | info | No | 404 |
| DALP-14128 | `bankRail.credit.RETRY_REFUSED` | domain | Bank credit cannot be retried. | The credit cannot be retried, and `data.reason` names the cause: only a credit parked with nothing minted, for supply-authority or mint-failed, a minted credit whose send to its custody gateway failed, or one whose coins the gateway paid back to the rail wallet, can be retried (`state`), the bank reversed the credit and its recall decides the tokens (`recall-open`), the failed send may still land or is still being submitted (`delivery-in-flight`), the credit's delivery is not in a state a retry can change (`delivery-not-retryable`), or the gateway paid the coins back to an address other than the current rail wallet (`returned-elsewhere`). | Resolve what `data.reason` names: wait for an in-flight send or the recall to settle, then read the credit and retry it if its delivery still shows send-failed. | info | No | 409 |
| DALP-14129 | `bankRail.clientAccount.UNAVAILABLE` | client | Bank account not found. | No bank account with this identifier exists on the bank connection. | List the connection's bank accounts and use one of their identifiers. | info | No | 404 |
| DALP-14130 | `bankRail.clientAccount.DUPLICATE` | domain | Bank account already registered. | The client already has this bank account, proposed or active. | Use the client's existing account, or refuse or revoke it before registering it again. | info | No | 409 |
| DALP-14131 | `bankRail.clientAccount.REVIEW_REFUSED` | domain | Bank account review refused. | The review does not fit the account, and `data.reason` says why: the account's state does not allow it (`state`), because only a proposed account can be approved or refused and only an active one revoked, or the reviewer proposed the account and cannot approve it (`proposer-cannot-approve`). | Read the account's state; ask another bank rail manager to approve an account you proposed. | info | No | 409 |
| DALP-14132 | `bankRail.reserveAdjustment.UNAVAILABLE` | client | Reserve adjustment not found. | No reserve adjustment with this identifier exists on the bank connection. | List the connection's reserve adjustments and use one of their identifiers. | info | No | 404 |
| DALP-14133 | `bankRail.reserveAdjustment.REFUSED` | domain | Reserve adjustment refused. | The adjustment cannot be recorded or decided, and `data.reason` names the cause: the connection has no active or suspended link to a token (`no-token-link`), the amount has more fraction digits than the token (`amount-precision`), is zero (`amount-zero`) or is larger than the reserve can record (`amount-too-large`), the posting is in the future (`future-posting`), a live adjustment already uses the bank reference (`bank-reference-used`), the deciding manager proposed the adjustment (`proposer-cannot-approve`), an impersonated session tried to decide it (`impersonated-session`), its approval request closed before a decision (`approval-closed`), it changed after it was proposed (`changed-since-request`), it is no longer open for this decision (`state`), or the approval rules refused the decision (`approval`). | Resolve what `data.reason` names, then record or decide the adjustment again. | info | No | 409 |
| DALP-14134 | `bankRail.railWalletRotation.UNAVAILABLE` | client | Rail wallet rotation not found. | No rail wallet rotation with this identifier exists for the organisation on this chain. | Read the rail wallet on the chain and use the rotation it names. | info | No | 404 |
| DALP-14135 | `bankRail.railWalletRotation.REFUSED` | domain | Rail wallet rotation step refused. | The rail wallet rotation cannot take this step, and `data.reason` says why: the organisation has no rail wallet on the chain to contain (`no-rail-wallet`), the rotation's state does not allow the step (`state`), a rotation for a compromised key cannot be abandoned (`compromised`), the manager who made a request cannot also decide it (`requester-cannot-decide`), the request's approval no longer stands (`approval`), a lost key's supply authority already left the contained wallet so the rotation can only complete (`authority-moved`), a compromised key's rotation grants the staged wallet nothing while another account still holds supply authority (`revoke-pending`) or while the contained wallet's escrow still holds tokens (`old-escrow-funded`), or the rotation cannot complete yet (`completion-blocked`). | Read the rotation and its links, then take the step they allow: revoke the contained wallet's authority first, have a custodian evacuate its escrow or the contained wallet, wait for its queued writes, complete instead of abandoning, or ask another bank rail manager to decide a request you made. | info | No | 409 |
| DALP-14136 | `bankRail.creditRecall.UNAVAILABLE` | client | Credit recall not found. | No credit recall with this identifier exists on the bank connection. | List the connection's recalls and use one of their identifiers. | info | No | 404 |
| DALP-14137 | `bankRail.creditRecall.REFUSED` | domain | Credit recall refused. | The recall cannot take this step, and `data.reason` names why: its state does not allow it (`state`), the bank's amount has no token amount (`recall-amount-unknown`), the credit was returned to the payer or is already recalled (`credit-not-recallable`), an allocation or return of the credit is open (`resolution-open`), the credit's mint is being submitted (`mint-in-flight`), the credit's send to the client's custody gateway is being submitted (`delivery-in-flight`), a live cash-out of the client holds the tokens (`cash-out-live`), the rail wallet is contained with no staged wallet (`rail-wallet-contained`), the credit settled into gateway receipts but the rail wallet has no custody gateway of its own, is not its client or is not on its approved payout list (`recall-gateway-missing`), no register line of the credit's mint is indexed (`line-unknown`), what the request bound changed before the decision (`recall-stale`), the transfer is not a forced transfer of the recall's tokens, or the gateway's return of a refused delivery, into the rail wallet after the approval (`claw-mismatch`), the transfer is already recorded (`claw-duplicate`), the transfer's block is not final yet (`claw-unfinalized`), the requester cannot decide it (`requester-cannot-decide`), or its approval no longer stands (`approval`). | Read the recall and its credit, then take the step they allow: wait for the mint, delivery, resolution or cash-out to finish, have a token custodian force-transfer the tokens into the wallet the recall names, record a transfer again once its block is final, request the recall again after a stale decision, or ask another bank rail manager to decide a request you made. For a credit held as gateway receipts, have a custody gateway manager create a gateway for the rail wallet's identity and add the rail wallet to its approved payouts, then request the recall again. | info | No | 409 |
| DALP-14138 | `bankRail.connection.CALENDAR_UNAVAILABLE` | client | Holiday calendar not available. | The holiday calendar is not a base calendar or one of the active organisation's own calendars. | List the holiday calendars the organisation can use and name one of them, or send null for none. | info | No | 422 |
| DALP-14139 | `bankRail.dailyReconciliation.UNAVAILABLE` | client | Daily reconciliation not found. | No daily reconciliation version exists for this connection and date. | List the connection's daily reconciliations, or run the closed date first. | info | No | 404 |
| DALP-14140 | `bankRail.dailyReconciliation.REFUSED` | domain | Daily reconciliation refused. | The date has not closed, its cutoff has no unique instant in its time zone, or the balance report or indexed block is older than the latest version. | Wait until the date closes, use a cutoff that exists once on that date, or restore evidence at least as new as the latest version's pins. | info | No | 409 |

The previous page is [DALP-14050 to DALP-14099](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference/dalp-14050-14099). The next page is [DALP-14200 to DALP-14299](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference/dalp-14200-14299).


# DALP-14200 to DALP-14299

Source: https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference/dalp-14200-14299
Cause, fix, HTTP status and retry flag for every Platform API error with a code from DALP-14200 to DALP-14299.

This page lists the 64 errors the Platform API can return with a code from DALP-14200 to DALP-14299. Match the `id` in the error envelope to the DALP Code column, then read Retryable and Suggested Fix. The [Platform API error reference](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference#how-to-use-this-reference) explains each column, including Severity, and the [DALP error index](https://docs.settlemint.com/docs/api-reference/errors) lists the page for every code range.

| DALP Code | Machine name | Category | Message | Why | Suggested Fix | Severity | Retryable | HTTP Status |
| --- | --- | --- | --- | --- | --- | --- | --- | --- |
| DALP-14207 | `WHITELIST_DESTINATION_IN_USE` | domain | This address cannot be added as a withdrawal destination. | This address is already a withdrawal destination, or another entry for it is still in use. | Use one of your existing destinations for this address, or choose another destination. | info | No | 409 |
| DALP-14208 | `WHITELIST_TRANSITION_REFUSED` | domain | The destination entry does not accept this step. | This destination entry does not accept this step in its current state, or the Idempotency-Key it was sent under already named a different entry. A review from the same user who proved the destination is refused too. | Read the entry as it stands and take the step its current state allows. If a reused Idempotency-Key caused the refusal, send the instruction under a key of its own. Ask another operator to review a destination you proved. | info | No | 409 |
| DALP-14209 | `WHITELIST_ENTRY_UNAVAILABLE` | client | The withdrawal destination was not found. | No destination entry matches this identifier for this participant. | Read the participant's own destinations and use one of their identifiers. | info | No | 404 |
| DALP-14210 | `WHITELIST_DESTINATION_PROOF_INVALID` | domain | The destination control proof is invalid. | The signed proof does not match the challenge the platform issued, the challenge expired, is not valid yet or belongs to an earlier custody reset, or the signature is not the destination address's own canonical signature. | Request a fresh challenge and sign the message it answers. | info | No | 422 |
| DALP-14211 | `WHITELIST_DESTINATION_ACTIVE_ELSEWHERE` | domain | The destination is already active on another entry. | This destination is already active on another whitelist entry in this organization, and a destination may be active on one entry at a time. | Refuse this entry, or have the other entry revoked before clearing this one. | info | No | 409 |
| DALP-14218 | `CUSTODY_PROVIDER_UNAVAILABLE` | dependency | The custody provider or the transaction queue is temporarily unavailable. | The custody provider, its authenticated probe, the custody store, the participant directory, the wallet's chain or the transaction queue did not answer in time, so the custody request could not be completed. | Retry the request. If the failure continues, check the custody provider's status and contact support with the request id. | error | Yes | 503 |
| DALP-14219 | `CUSTODY_LIFECYCLE_CONFLICT` | domain | The custody account changed while this lifecycle step was decided. | The custody account's state refuses this step. Another request moved its lifecycle or claimed your first account on this network, an earlier create request has not finished, the account is inactive or still holds something to release, the wallet cannot carry this policy, or the transaction queue rejected the wallet change. | Read the custody account again and take the step its current state allows. | info | No | 409 |
| DALP-14220 | `CUSTODY_WALLET_NOT_FOUND` | client | Wallet not found. | No wallet visible to the caller matches this identifier, or the participant it belongs to is no longer registered. | Refresh the wallet list and choose a wallet returned there. | info | No | 404 |
| DALP-14221 | `MULTISIG_APPROVAL_CONFLICT` | domain | The multisig approval conflicts with the wallet's state. | The approval expired, is bound to a different user operation than the wallet holds, this controller already signed it, it has not collected the weight its threshold needs, or it reached its threshold on a path that cannot execute it yet. | Read the wallet's pending approval and sign the operation it currently holds, once per controller. | info | No | 409 |
| DALP-14222 | `PARTICIPANT_NOT_FOUND` | client | Participant or contact not found. | No participant, or no contact in the caller's contact book, matches this selection in the acting organization. | Use a participant returned by the participant list, or a contact returned by the contact list. | info | No | 404 |
| DALP-14223 | `IDENTITY_NOT_FOUND` | client | Not found in the identity registries. | No identity, claim topic, trusted issuer or identity recovery matches this request in the identity registries. | Check the wallet, topic, issuer or user the request names; create or register it first if it should exist. | info | No | 404 |
| DALP-14224 | `IDENTITY_SCOPE_NOT_FOUND` | client | The identity registry is not available for this organization and chain. | The requested identity scope or registry is not indexed for this organization and chain. | Deploy the system or register the required identity registry for this chain. | info | No | 404 |
| DALP-14225 | `CLAIM_NOT_FOUND` | client | Claim not found. | No claim is recorded for this identity and topic. | Issue the claim before revoking or reading it. | info | No | 404 |
| DALP-14226 | `PARTICIPANT_CONFLICT` | domain | Another participant already holds this key or user link. | Another participant already holds this natural key or user link. | Read the existing participant and continue from it. | info | No | 409 |
| DALP-14227 | `IDENTITY_REGISTRY_CONFLICT` | domain | The identity registry holds a different state than this write assumed. | The identity registry already holds the requested state, or a different state than this write assumed. | Read the registry entry and continue from it, or send a write matching its current state. | info | No | 409 |
| DALP-14228 | `PARTICIPANT_ACCESS_DENIED` | permission | No capability over this participant. | The caller holds no capability over this participant. | Ask a participant manager for the capability, then retry. | info | No | 403 |
| DALP-14229 | `PARTICIPANT_REGISTRATION_INVALID` | client | The registration request is not valid in its current state. | The registration request is not valid in its current state. | Read the registration list and send a request the state allows. | info | No | 400 |
| DALP-14230 | `CLAIM_INVALID` | client | The claim is not valid for its topic. | The claim topic, value or payload is not valid for this topic scheme. | Send a value matching the topic scheme from the topic catalog. | info | No | 400 |
| DALP-14231 | `MULTISIG_DRAFT_INVALID` | client | The multisig draft does not allow this change. | The draft threshold, seat state or member-set version does not allow this change. | Read the draft and send a change its current member set allows. | info | No | 400 |
| DALP-14232 | `RECOVERY_PRECONDITION_FAILED` | client | The recovery preconditions are not met. | The recovery preconditions on the wallet and its target are not met. | Read the recovery preview and satisfy every precondition it lists. | info | No | 400 |
| DALP-14233 | `IDENTITY_SCOPE_CHAIN_UNAVAILABLE` | dependency | The chain backing this identity scope is unavailable. | The chain backing this identity scope is unavailable. | Retry after a short backoff. If it keeps failing, ask an operator to check the RPC endpoint of the network that backs this identity scope. | error | Yes | 503 |
| DALP-14234 | `IDENTITY_SCOPE_DIRECTORY_UNRESOLVED` | dependency | The chain's Directory could not be resolved. | The Directory that publishes this chain's global registries could not be resolved. | Give the chain exactly one enabled network catalog entry naming a Directory, and register the global registry under its key in that Directory. | error | No | 503 |
| DALP-14235 | `CONTACT_DUPLICATE` | client | A contact for this wallet already exists. | This user already keeps a contact for this wallet. | Rename the existing contact instead of adding a second one. | info | No | 409 |
| DALP-14236 | `TRANSACTION_STATE_CONFLICT` | domain | The transaction's state does not allow this transition. | The transaction already finished, holds signed material, sits on a nonce lane that refused the change, or another actor moved it to a new state first. | Read the current transaction state before choosing another operation. | info | No | 409 |
| DALP-14237 | `TRANSACTION_IDEMPOTENCY_KEY_SETTLED` | client | This idempotency key already names a settled transaction. | The idempotency key already names a transaction that has settled. | Use the prior result, or submit a distinct intent with a new idempotency key. | info | No | 409 |
| DALP-14238 | `TRANSACTION_IDEMPOTENCY_KEY_CONFLICT` | client | This idempotency key already names a different write. | The idempotency key already names a different write from this sender on this chain, or its 24-hour matching window has closed. | Submit this write with a new idempotency key; to retry the original write inside its 24-hour window, resend it unchanged. | info | No | 409 |
| DALP-14239 | `TRANSACTION_CANCELLATION_REFUSED` | domain | The transaction cannot be cancelled now. | The transaction is with the signer, and a cancel is refused while it is being signed. | Wait until the transaction request shows the transaction as broadcast, then send the same cancel again. | info | Yes | 409 |
| DALP-14240 | `TRANSACTION_PREPARATION_CLAIM_CONFLICT` | domain | The transaction preparation has another active claim. | Another client holds an active claim on this transaction preparation. | Resume the active claim or wait for its lease to expire. | info | No | 409 |
| DALP-14241 | `TRANSACTION_PREPARATION_PREIMAGE_MISMATCH` | client | The authorization does not match the prepared transaction. | The authorization artifact does not match the canonical preparation preimage. | Authorize the exact canonical preimage returned by the preparation endpoint. | info | No | 409 |
| DALP-14242 | `AA_VALIDATION_FAILED_RETRYABLE` | domain | The user operation failed ERC-4337 validation for a reason that can clear. | The bundler or entry point refused the user operation with an AA code whose cause can clear on its own, such as a nonce or deposit that is not in yet place. | Wait for the cause to clear, such as a nonce or deposit that is not in yet place, then resubmit the same user operation. | info | Yes | 422 |
| DALP-14243 | `AA_VALIDATION_FAILED` | domain | The user operation failed ERC-4337 validation. | The bundler or entry point refused the user operation with an AA code that resubmitting the same operation cannot clear. | Simulate the user operation to read its AA code, correct the factory, account or paymaster the code names, then build a new user operation. | info | No | 422 |
| DALP-14244 | `EXECUTION_FUNDING_REQUIRED` | domain | Execution ended before its paying account was funded. | The account that pays for this execution held too little. The execution waited for funding, and it ended when the pause was declined, a waiting window closed, or its re-broadcasts ran out. | Fund the paying account under Organisation settings, Transaction funding, then send the write again with a new idempotency key. | info | Yes | 422 |
| DALP-14245 | `PAYMASTER_SPONSORSHIP_DENIED` | permission | Paymaster sponsorship was denied. | The paymaster did not sponsor this operation. The organisation's policy refuses it, no sponsorship paymaster covers it on this network, the paymaster signer is unavailable, or the sponsorship ticket expired. | Use an approved sponsor policy, or submit without sponsorship. | info | No | 403 |
| DALP-14246 | `PAYMASTER_NOT_FOUND` | client | No active paymaster matches the request. | No active indexed paymaster matches the request. | Deploy or index the organization paymaster, then retry. | info | No | 404 |
| DALP-14247 | `WALLET_VERIFICATION_SESSION_REQUIRED` | auth | Wallet verification needs a signed-in session. | The operation needs wallet verification, and the request carries no signed-in session that identifies whose wallet to verify. | Sign in again, then retry with a wallet verification proof. | info | No | 401 |
| DALP-14248 | `SETTLEMENT_NOT_FOUND` | domain | Settlement resource not found. | No settlement, settlement leg or token sale visible in the active scope matches this request. | Use a settlement resource returned in the active scope. | info | No | 404 |
| DALP-14249 | `SETTLEMENT_FORBIDDEN` | permission | The acting party may not perform this settlement operation. | The acting participant or wallet is not a party allowed to perform this operation on the settlement. | Act as a participant or wallet that is a party to the settlement with the needed role. | info | No | 403 |
| DALP-14250 | `SETTLEMENT_STATE_CONFLICT` | domain | The settlement's state does not allow this operation. | The settlement is in a state that does not accept this operation, such as executed, cancelled or expired. It also answers an Idempotency-Key reused for a different request, and a sale write that the sale's funding headroom or mint rules refuse. | Read the settlement and use an operation its current state allows, or send a different request under a new Idempotency-Key. | info | No | 409 |
| DALP-14251 | `CANTON_RESOURCE_NOT_FOUND` | client | Canton resource not found. | The Canton resource is absent, or it is not disclosed to the active organization. | Use a Canton resource returned for the active organization. | info | No | 404 |
| DALP-14252 | `CANTON_ALLOCATION_CONFLICT` | domain | The allocation conflicts with an existing intent. | An allocation intent with different immutable input already exists for this request. | Read the existing allocation before creating another intent. | info | No | 409 |
| DALP-14253 | `CANTON_SUBMISSION_CONFLICT` | client | This submission id already names a different submission. | The submission id already holds different immutable input. | Read the existing submission, or send the new one under a new idempotency key. | info | No | 409 |
| DALP-14254 | `VENUE_SIGNER_UNRESOLVABLE` | operational | The venue signer cannot be resolved. | The venue's signing identity could not be resolved, and the failure does not clear on retry. | Ask a venue operator to check the venue's signer configuration in custody, then send the request again. | error | No | 503 |
| DALP-14255 | `VENUE_CONFIGURATION_CONFLICT` | permission | The venue configuration cannot be claimed in this organization. | The venue configuration is held by another organization, so this organization cannot claim it. | Select the organization that owns this venue, or contact an administrator. | info | No | 409 |
| DALP-14256 | `VENUE_FEE_TIER_SCHEDULE_INVALID` | client | The fee tier schedule breaks the ladder rules. | Each tier's threshold must be greater than zero and greater than the one before, its discount must be at least the one before, the ladder holds at most 8 tiers, and the window must be 1 to 365 days. | Correct the ladder so each tier needs more volume and gives at least the same discount as the one before, then submit again. | info | No | 422 |
| DALP-14257 | `VENUE_FEE_TIER_SCHEDULE_CONCURRENT_EDIT` | client | The fee tier schedule changed while this edit was open. | Another edit recorded a newer version of this fee tier schedule after the version this edit started from. | Reload the current fee tier schedule, reapply the change on top of it, and submit the edit again. | info | No | 409 |
| DALP-14258 | `PORTFOLIO_QUERY_REJECTED` | client | The listing query uses a filter the listing does not publish. | A query member did not match the filter vocabulary this listing publishes. | Send an operator and an operand the column publishes, then request the listing again. | info | No | 400 |
| DALP-14259 | `GOVERNANCE_PROPOSAL_PREFLIGHT_FAILED` | domain | The governance action cannot be taken in the proposal's current state. | The governor refuses this proposal or ballot in its current state: the proposal is not open for voting, the caller lacks the voting power or authority it needs, or a timing condition is not met. | Check that the vote is open, that your wallet has the voting power or authority it needs, and that the vote's dates are still valid. Then try again. | info | No | 422 |
| DALP-14260 | `FILING_ACT_REFUSED` | domain | A filing rule refused this act. | A filing lifecycle rule refused the act. `data.refusal` names it: an act the obligation's fulfilment mode never takes, a maker acting as checker, a missing signature, an enterer approving their own entry, an acknowledgement time out of order, unrecorded or refused coverage, a session acting as another user, or validation findings that still stand. | Read `data.refusal`, satisfy that rule, then repeat the act. | info | No | 409 |
| DALP-14261 | `REQUEST_INVALID` | client | The request does not match the route's schema. | A part of the request, its body, query, path or headers, did not match the published schema for this route. | Correct the fields that data.errors names, or check the request against the route schema, then send it again. | info | No | 400 |
| DALP-14262 | `REQUEST_STATE_CONFLICT` | domain | The write collides with state the platform already holds. | The write collided with state the platform already holds, so the platform did not apply it. | Read the current state and continue from it. | info | No | 409 |
| DALP-14263 | `KYC_VERSION_STATE_INVALID` | domain | The KYC version's state does not allow this transition. | The KYC version or action request cannot take this step: its state does not allow it, a new version cannot be created now, or the national id is already used. | Read the KYC version and use a transition its current state permits. | info | No | 409 |
| DALP-14264 | `PROFILE_FIELDS_REFUSED` | client | Some profile fields were refused. | The request names profile or KYC fields the server refused; `data.errors` lists each field and why. | Correct or remove the fields listed in `data.errors`, then send the request again. | info | No | 400 |
| DALP-14265 | `INVALID_REQUEST_NETWORK_IDENTITY` | client | The X-Network-Id header is not a valid network id. | The X-Network-Id header value is not in network-id form. | Send a network id returned by the networks list, or omit the header to use the default network. | info | No | 400 |
| DALP-14266 | `OFF_CHAIN_ORGANIZATION_PERMISSION_REQUIRED` | permission | The organization does not hold the permission this action needs. | The caller's organization role does not grant the off-chain permission this action requires. | Ask an organization owner or administrator for a role that grants it, then retry. | info | No | 403 |
| DALP-14267 | `OFF_CHAIN_USER_PERMISSION_REQUIRED` | permission | The caller does not hold the permission this action needs. | The signed-in user does not hold the off-chain permission this action requires. | Ask an administrator for a role that grants it, then retry. | info | No | 403 |
| DALP-14268 | `REQUEST_CHAIN_CUSTODY_ACCOUNT_REQUIRED` | permission | This action needs a custody account on the requested chain. | The request acts on a chain where the caller has no custody account to act through. | Select or create a custody account on this chain, then retry. | info | No | 403 |
| DALP-14270 | `TRANSACTION_QUEUE_CONFLICT` | domain | The submission collides with one the queue already holds. | The queue timed out waiting for this submission to settle, or an earlier write for the same request is still being processed. A Canton submission also answers this code when its idempotency key already holds different input. | When the message says the key holds different input, send the new submission under a new idempotency key. Otherwise read the existing submission, then send the same request again once it settles. | info | No | 409 |
| DALP-14271 | `TOKEN_FEE_ACCOUNTING_FEATURE_NOT_FOUND` | client | The token has no transaction fee accounting feature. | Fee accounting acts on the token's transaction fee feature, and the token has none attached. | Attach the transaction fee feature to the token before collecting or reading its fees. | info | No | 404 |
| DALP-14272 | `CLAIM_ISSUE_APPROVAL_PENDING` | operational | The claim issue is waiting for an approval. | Issuing this claim waits for an approval that has not been granted yet. | Approve the pending request, then send the claim issue again. | info | Yes | 409 |
| DALP-14273 | `DATABASE_QUERY_REFUSED` | dependency | A database query failed for a reason a retry does not fix. | The platform's database refused a query this request needs, for a reason such as a constraint, a permission or an invalid query, that sending the same request again does not change. | Do not retry the same request. Contact support with the request id. | error | No | 503 |
| DALP-14274 | `DURABLE_EXECUTION_ENGINE_CALL_MALFORMED` | dependency | A workflow engine request or reply did not match its schema. | A request to the workflow execution service, or its reply, failed to encode or decode against its schema, so sending the same request again fails the same way. | Do not retry the same request. Contact support with the request id. | error | No | 503 |
| DALP-14275 | `CUSTODY_CREDENTIALS_TEMPORARILY_UNAVAILABLE` | dependency | Custody credentials for this organization are temporarily unavailable. | The custody provider, its secrets backend or the custody record store did not answer, the provider could not be set up from the stored configuration, or no credential is stored in its secret slot, so the custody operation could not start. | Check the custody provider and secrets backend, then retry the operation. | error | Yes | 503 |
| DALP-14276 | `WALLET_RESOLUTION_INVALID` | domain | The wallet could not be resolved from its stored data. | The wallet's stored data or the resolver input is inconsistent: a factory, identity or participant is missing, or the multisig members, signers or threshold cannot form a valid wallet. | Repair the wallet data or the resolver input, then retry the operation. | error | No | 503 |
| DALP-14277 | `custody.user.PERSONAL_ACCOUNT_LIMIT` | domain | You already have a managed custody account on this network. | A user holds one managed custody account on each network, and the signed-in user already holds one on the network this request resolved to. Nothing was created. | Use the custody account the network already holds, or switch to a network where you have none. | info | No | 409 |

The previous page is [DALP-14100 to DALP-14199](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference/dalp-14100-14199). The next page is [DALP-14300 to DALP-14399](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference/dalp-14300-14399).


# DALP-14300 to DALP-14399

Source: https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference/dalp-14300-14399
Cause, fix, HTTP status and retry flag for every Platform API error with a code from DALP-14300 to DALP-14399.

This page lists the 97 errors the Platform API can return with a code from DALP-14300 to DALP-14399. Match the `id` in the error envelope to the DALP Code column, then read Retryable and Suggested Fix. The [Platform API error reference](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference#how-to-use-this-reference) explains each column, including Severity, and the [DALP error index](https://docs.settlemint.com/docs/api-reference/errors) lists the page for every code range.

| DALP Code | Machine name | Category | Message | Why | Suggested Fix | Severity | Retryable | HTTP Status |
| --- | --- | --- | --- | --- | --- | --- | --- | --- |
| DALP-14300 | `PLATFORM_NETWORK_NOT_FOUND` | client | The network was not found. | No network is stored under the name or chain in the request, or it has no EVM lifecycle to act on. | List the networks, then request one that exists. | info | No | 404 |
| DALP-14301 | `PLATFORM_ORGANIZATION_NOT_FOUND` | client | The organization was not found. | No organization matches the identifier in the request, or the global theme names an organization that no longer exists. | Check the organization identifier and request it again. | info | No | 404 |
| DALP-14302 | `PLATFORM_USER_NOT_FOUND` | client | The user was not found. | No user matches the identifier in the request. | Check the user identifier and request it again. | info | No | 404 |
| DALP-14303 | `PLATFORM_MEMBER_NOT_FOUND` | client | The member was not found. | The user is not a member of the active organization, so there is no membership to remove or change. | List the organization members, then choose a user who is listed. | info | No | 404 |
| DALP-14304 | `PLATFORM_SYSTEM_NOT_FOUND` | client | The system was not found. | No system matches the address in the request, or none is deployed or indexed for this organization on the chain. | Check the system address and the chain, then request it again. | info | No | 404 |
| DALP-14305 | `PLATFORM_HOLIDAY_CALENDAR_NOT_FOUND` | client | The holiday calendar was not found. | No holiday calendar visible to this organization has the identifier in the request. | List the holiday calendars and use an identifier from the list. | info | No | 404 |
| DALP-14306 | `PLATFORM_INVITATION_NOT_FOUND` | client | The invitation was not found. | No invitation matches the identifier for this caller, or the caller may not see its role status. | Check the invitation identifier and the signed-in account, then request it again. | info | No | 404 |
| DALP-14307 | `PLATFORM_DEPLOYMENT_NOT_FOUND` | client | The deployment was not found. | No deployment or system migration answers to this identifier for the calling organisation, or no run was recorded for it while the stream waited. | Check the deployment identifier and the active organization, then request it again. | info | No | 404 |
| DALP-14308 | `PLATFORM_FACTORY_NOT_FOUND` | client | The factory was not found. | No token or addon factory is registered at the address in the request, or the deployment cannot supply one. | List the factories of the system and use an address from the list. | info | No | 404 |
| DALP-14309 | `PLATFORM_ASSET_CLASS_NOT_FOUND` | client | The asset class was not found. | No asset class definition visible to this organisation matches the identifier, or no system asset class is configured for the requested base asset type. | List the asset class definitions and use an identifier from the list. | info | No | 404 |
| DALP-14310 | `PLATFORM_TEMPLATE_NOT_FOUND` | client | The template was not found. | No asset type or instrument template visible to this organization matches the identifier. | List the templates and use an identifier from the list. | info | No | 404 |
| DALP-14311 | `PLATFORM_COMPLIANCE_TEMPLATE_NOT_FOUND` | client | The compliance template was not found. | No compliance template visible to this caller matches the identifier. Draft templates are hidden from callers who cannot read them in full. | List the compliance templates and use an identifier from the list. | info | No | 404 |
| DALP-14312 | `PLATFORM_TEMPLATE_STRUCTURE_NOT_FOUND` | client | The instrument structure was not found. | No instrument structure visible to this organization matches the identifier. | List the instrument structures and use an identifier from the list. | info | No | 404 |
| DALP-14313 | `PLATFORM_INDEXED_SYSTEM_NOT_FOUND` | client | The new factory's system is not indexed yet. | The factory was created, but its system has not reached the indexed projection, so its view cannot be returned yet. | Read the system again after the indexer catches up. | info | No | 404 |
| DALP-14314 | `PLATFORM_DIRECTORY_NOT_FOUND` | client | The directory was not found. | This chain has no mirrored directory at the requested address, or no system directory is configured for it. | Check the directory address and the chain, then request it again. | info | No | 404 |
| DALP-14315 | `PLATFORM_SETTING_NOT_FOUND` | client | The setting was not found. | No setting is stored under the key in the request, or a target currency change needs a BASE_CURRENCY setting the organisation does not have or a stored TARGET_CURRENCIES list that cannot be read. | List the settings and use a key from the list. | info | No | 404 |
| DALP-14316 | `PLATFORM_PROFILE_SECTION_NOT_FOUND` | client | The profile section was not found. | No participant profile section matches the identifier in the request. | List the profile sections and use an identifier from the list. | info | No | 404 |
| DALP-14317 | `PLATFORM_CATALOG_VERSION_CONFLICT` | domain | The network catalog changed since you read it. | The request was based on an older version of the network catalog than the one stored. | Read the catalog again and resend the change against the current version. | info | No | 412 |
| DALP-14318 | `PLATFORM_NETWORK_EXISTS` | domain | A network with this name already exists. | The catalog already stores a network under the name in the request. | Choose a different network name, or update the existing network. | info | No | 412 |
| DALP-14319 | `PLATFORM_IF_MATCH_REQUIRED` | domain | The request needs a concrete If-Match version. | Writes to a network's indexing lifecycle must name the lifecycle version they were based on, and the If-Match header was missing, `*` or not a version number. | Read the network's indexing state and send its version in the If-Match header. | info | No | 412 |
| DALP-14320 | `PLATFORM_LIFECYCLE_VERSION_STALE` | domain | The indexing lifecycle changed since you read it. | The If-Match version does not match the stored lifecycle version, so another change landed first. | Read the network's indexing state again and resend the change with the current version. | info | No | 412 |
| DALP-14321 | `PLATFORM_EXECUTOR_REFUSED` | domain | The executor cannot act on this request. | The wallet or executor that would send the transaction was refused for this organisation, network or setting, or a deployment retry could not read the organisation's base currency. | Check the executor and wallet configuration for the organization, then retry. | info | No | 412 |
| DALP-14322 | `PLATFORM_SYSTEM_RECREATION_REFUSED` | domain | The system cannot be recreated. | The organisation's settings name a system on this network that the indexer does not know, and the deployment carried no matching recreation decision for it. | Contact support with the `requestId` from the error. | info | No | 412 |
| DALP-14323 | `PLATFORM_GAS_PAYER_REFUSED` | domain | The gas payer cannot be changed. | The requested gas payer needs the organisation on EOA wallets and an active system on this network, or the relayer for this network could not be set up. | Keep the organisation on EOA wallets and wait until the system on this network is active, then retry. | info | No | 412 |
| DALP-14324 | `PLATFORM_WALLET_VERIFICATION_NOT_CONFIGURED` | domain | Wallet verification is not set up for this account. | The account has no wallet verification method configured, or not the one the proof names. | Set up the wallet verification method, then send the write again with a proof. | info | No | 412 |
| DALP-14325 | `PLATFORM_ADMIN_COUNT_NOT_SEEDED` | domain | The system's administrator count is not initialised. | The system's access manager has not counted its administrators yet, so the last administrator cannot be protected. | Upgrade the access manager with initializeV2 and the administrator list, then retry. | info | No | 412 |
| DALP-14326 | `PLATFORM_PLATFORM_SETUP_INCOMPLETE` | domain | Platform setup is not complete. | Setup needs an RPC upstream pool on an enabled network before it can finish. | Add an RPC upstream pool to an enabled network, then complete setup. | info | No | 412 |
| DALP-14327 | `PLATFORM_SYSTEM_NOT_DEPLOYED` | domain | The organization has no deployed system on this chain. | The request needs a deployed system, and the organization has none on the requested chain. | Deploy a system for the organization on this chain, or switch to a chain that has one. | info | No | 412 |
| DALP-14328 | `PLATFORM_WALLET_CANNOT_EXECUTE` | domain | The acting wallet cannot execute in this scope. | The wallet this request acts as is not allowed to execute for the organisation and network. For a system migration, the signing wallet holds no management key on the organisation identity. | Select a wallet that can execute in this scope, then retry. | info | No | 412 |
| DALP-14329 | `PLATFORM_TARGET_CURRENCY_UNSUPPORTED_ON_SYSTEM` | domain | The system does not support this target currency. | The system cannot add exchange-rate feeds: it has no feeds directory, or the organisation's wallet does not hold the feeds manager role on it. | Give the system a feeds directory, or grant the feeds manager role to the organisation's wallet, then retry. | info | No | 412 |
| DALP-14330 | `PLATFORM_GAS_PAYER_UNAVAILABLE` | domain | The gas payer is not available. | The requested gas payer cannot be used on this organization's network right now. | Pick another gas payer, or restore the one you selected, then retry. | info | No | 412 |
| DALP-14331 | `PLATFORM_REQUIRES_GLOBAL_ENABLEMENT` | domain | The feature must be enabled globally first. | The setting can only be turned on for an organization after a platform administrator enables it globally. | Ask a platform administrator to enable the feature, then retry. | info | No | 412 |
| DALP-14332 | `PLATFORM_CONTROLLER_MISMATCH` | domain | The controller does not match the expected account. | The on-chain controller of the account differs from the one the platform expects. | Align the controller with the platform's record, then retry. | info | No | 412 |
| DALP-14333 | `PLATFORM_ADDON_BLOCKED` | domain | This addon type cannot be created here. | This service does not create factories for the Paymaster signer addon type. | Request a different addon type. | info | No | 412 |
| DALP-14334 | `PLATFORM_INVITATION_CREATE_INPUT_INVALID` | domain | The invitation could not be created from this input. | A service involved in creating the invitation rejected the submitted details. | Correct the invitation details and send the request again. | info | No | 412 |
| DALP-14335 | `PLATFORM_INVITATION_INPUT_INVALID` | client | The invitation request cannot be processed. | A service involved in handling the invitation rejected the submitted details. | Correct the invitation details and send the request again. | info | No | 422 |
| DALP-14336 | `PLATFORM_INVITATION_SYSTEM_MISSING` | client | The organization has no deployed system on this chain. | Accepting an invitation needs a deployed system, and the organisation has none on the requested chain. | Deploy a system on this chain, or send the request for a chain that has one. | info | No | 422 |
| DALP-14337 | `PLATFORM_NETWORK_DEFINITION_INVALID` | client | The network definition cannot be used. | The network definition does not satisfy the catalog rules for this organization. | Correct the network definition, then add the network again. | info | No | 422 |
| DALP-14338 | `PLATFORM_FILTER_UNSUPPORTED` | client | The filter operator is not supported. | The named filter only supports the `eq` operator. | Use the `eq` operator for that filter. | info | No | 422 |
| DALP-14339 | `PLATFORM_FACTORY_TYPE_UNUSABLE` | client | The factory type cannot be used. | The requested factory type is deprecated or unsupported, or the chain directory publishes no implementation for it. `data.typeIds` names the refused type when the refusal concerns one type. | Choose a supported factory type, or name an implementation to register for it. | info | No | 422 |
| DALP-14340 | `PLATFORM_FACTORY_TYPE_UNREGISTERED` | client | No factory is registered for this type. | The system has no token factory registered for the requested type, so no address can be predicted. | Create a factory for the type first, or request a type that has one. | info | No | 422 |
| DALP-14341 | `PLATFORM_SLUG_UNUSABLE` | client | The slug is not usable. | The submitted slug, or the slug derived from the name when none is sent, does not match the allowed slug format. | Send a slug of lowercase letters, digits and hyphens, or omit it and use a name with letters or digits to derive one. | info | No | 422 |
| DALP-14342 | `PLATFORM_ROLE_CHANGE_NOT_ATOMIC` | client | The access manager refused the role change. | The role change names no account, names a role the access manager does not administer, grants a role to the zero address, or the wallet that would send it is refused. | Name at least one account and only roles the access manager administers, never the zero address, then send the change again. | info | No | 422 |
| DALP-14343 | `PLATFORM_ROLE_CHANGE_REFUSED` | client | The role change conflicts with a held role or was refused by the queue. | The transaction queue refused the role write, or the grant conflicts with a role the account holds or with the organisation's segregation of duties. No role change was recorded. | Read the held roles, drop any grant that conflicts with them, then send the change again. | info | No | 422 |
| DALP-14344 | `PLATFORM_TARGET_CURRENCY_NOT_SUPPORTED` | client | The target currency is not supported. | The exchange rate provider does not carry one or more of the requested target currencies. | Choose target currencies the exchange rate provider carries. | info | No | 422 |
| DALP-14345 | `PLATFORM_TEMPLATE_NOT_PUBLISHABLE` | client | The template is not ready to publish. | The template has gaps that must be filled before it can be published. | Read the template's readiness gaps, close them, then publish again. | info | No | 422 |
| DALP-14346 | `PLATFORM_PARAMETERS_MISMATCH` | client | The compliance parameters do not match the module. | The submitted parameters do not fit the schema of the selected compliance module. | Send parameters that match the module's schema. | info | No | 422 |
| DALP-14347 | `PLATFORM_NETWORK_FAMILY_DISABLED` | domain | The network family is not enabled. | The network or RPC definition belongs to a chain family that the platform has not enabled. | Enable the chain family, or use a network of an enabled family. | info | No | 409 |
| DALP-14348 | `PLATFORM_ORGANIZATION_ARCHIVE_REFUSED` | domain | The organization cannot be archived. | The organisation is already archived, or the restore names an organisation that is not archived. | Read the organisation's archive state, then send the transition it allows. | info | No | 409 |
| DALP-14349 | `PLATFORM_ONBOARDING_RESET_REFUSED` | domain | The user's onboarding cannot be reset. | The user is in a state that does not allow an onboarding reset. | Read the user's onboarding state, resolve what blocks the reset, then retry. | info | No | 409 |
| DALP-14350 | `PLATFORM_SELF_SESSION_REVOCATION` | domain | You cannot reset your own onboarding. | The request targets the signed-in administrator, which would revoke that session mid-operation. | Ask another platform administrator to run the reset. | info | No | 409 |
| DALP-14351 | `PLATFORM_HOLIDAY_CALENDAR_CYCLE` | domain | The holiday calendar would reference itself. | The calendar's parent chain would loop back to the calendar, or would grow past 8 calendars. | Remove the circular parent reference or pick a parent higher in the chain, then save the calendar again. | info | No | 409 |
| DALP-14352 | `PLATFORM_HOLIDAY_CALENDAR_EXISTS` | domain | A holiday calendar with this name already exists. | A holiday calendar already exists under the requested identifier, and the request asked to create it only if absent. | Choose a different identifier, or send the change without `If-None-Match: *` to update the existing calendar. | info | No | 409 |
| DALP-14353 | `PLATFORM_INVITATION_CONFLICT` | domain | The invitation conflicts with current state. | A service involved in handling the invitation reported that the request conflicts with stored state. | Read the invitation again and apply the change on top of its current state. | info | No | 409 |
| DALP-14354 | `PLATFORM_DEPLOYMENT_WITHOUT_INVITATION` | domain | The deployment is not linked to an invitation. | The deployment named in the request was not started from an invitation. | Use the deployment identifier returned when the invitation was accepted. | info | No | 409 |
| DALP-14355 | `PLATFORM_EXECUTOR_UNAVAILABLE` | domain | No executor is available for this request. | Account abstraction is off at the scope the requested executor needs, or the selected participant has no usable account for the requested executor. | Send the request with the eoa executor, or enable account abstraction and provision the participant's smart wallet, then retry. | info | No | 409 |
| DALP-14356 | `PLATFORM_CUSTODY_PROVIDER_MISSING` | domain | No custody provider supports this network. | No healthy managed custody provider enabled for account creation supports the network being deployed. | In Organisation settings, open Custody, then Providers. Add the network to a managed custody provider, enable account creation on it, or restore its health, then retry. | info | No | 409 |
| DALP-14357 | `PLATFORM_DEPLOY_CONFLICT` | domain | The deployment conflicts with current state. | The organisation's deployment already started or it is already onboarded, another deployment for the organisation is still running, the retried deployment id names no organisation or is not its default deployment, the session has no active organisation, or the Idempotency-Key was already used for a different create request. | Read the organization's deployment state, then change the request to fit it or wait for the running deployment. | info | No | 409 |
| DALP-14358 | `PLATFORM_MEMBERSHIP_CONFLICT` | domain | The member cannot be added. | The user is already a member of the organisation, or the organisation has not finished onboarding. | List the organisation members, or finish the organisation's onboarding, then retry. | info | No | 409 |
| DALP-14359 | `PLATFORM_LAST_OWNER` | domain | The organization's last owner cannot be removed or demoted. | Removing this member or changing their role to member would leave the organization with no owner. | Make another member an owner first, then remove or demote this one. | info | No | 409 |
| DALP-14360 | `PLATFORM_SETTINGS_REFUSED` | domain | Multi-network support is off. | The organisation has not enabled multi-network support, so it cannot add a network. | Enable multi-network support in Organisation settings, then add the network again. | info | No | 409 |
| DALP-14361 | `PLATFORM_BUNDLER_PROVISIONING_REFUSED` | domain | The bundler cannot be provisioned. | Account abstraction is disabled for the organization, the system is unavailable, or the system's access manager is missing. | Enable account abstraction and make sure the system is deployed with an access manager, then retry. | info | No | 409 |
| DALP-14362 | `PLATFORM_ORGANIZATION_NOT_ACTIVE` | domain | The organization is not the active one. | The request names an organization that the session is not active in. | Switch the session to that organization, or send the identifier of the active one. | info | No | 409 |
| DALP-14363 | `PLATFORM_SELF_MEMBERSHIP_REMOVAL` | domain | You cannot remove your own membership. | The member to remove is the caller. | Ask another organization owner to remove you. | info | No | 409 |
| DALP-14364 | `PLATFORM_SYSTEM_ASSET_CLASS_READONLY` | domain | System asset classes cannot be changed. | The asset class is built in, so it cannot be modified or deleted. | Create an asset class of your own, or leave the built-in one as it is. | info | No | 409 |
| DALP-14365 | `PLATFORM_SYSTEM_TEMPLATE_READONLY` | domain | System templates cannot be changed. | The template or instrument structure is built in, so it cannot be modified or deleted, and a built-in compliance template cannot be published. | Copy it into a template of your own and change that copy. | info | No | 409 |
| DALP-14366 | `PLATFORM_LAST_ADMINISTRATOR` | domain | The last system administrator cannot be revoked. | The change would leave the system's access manager with no administrator. | Grant the administrator role to another account first, then revoke this one. | info | No | 409 |
| DALP-14367 | `PLATFORM_ADDON_INSTANCE_WIRING` | domain | The addon factory cannot be wired. | The system's addon registry is too old to wire a factory instance, and the request names no implementation for this addon. | Send the addon's `implementation` address with the request, then retry. | info | No | 409 |
| DALP-14368 | `PLATFORM_TARGET_CURRENCY_REMOVAL_FORBIDDEN` | domain | The target currency cannot be removed. | A price feed is still registered for the target currency in the system's feeds directory, so it cannot be removed. | Keep the target currencies that still have a price feed, and remove only the others. | info | No | 409 |
| DALP-14369 | `PLATFORM_SETTING_CANNOT_BE_DISABLED` | domain | The setting cannot be disabled. | The organisation uses smart wallets, and an organisation on smart wallets cannot switch back to EOA wallets. | Keep account abstraction on for this organisation. | info | No | 409 |
| DALP-14370 | `PLATFORM_IDENTITY_MISMATCH` | domain | The identity does not match the account. | A participant's smart wallet is bound to a different identity than the one on record, or the participant holds more than one identity on wallets no custody account holds. | Leave one identity per participant and bind its smart wallet to that identity, then retry. | info | No | 409 |
| DALP-14371 | `PLATFORM_ACCOUNT_KIND_SWITCH_BLOCKED` | domain | The account kind cannot be switched yet. | No network of the organisation can host smart wallets, the organisation relayer still has unfinished writes, or the switch's own writes have not landed. | Add a network that supports smart wallets, or finish or cancel the open relayer writes, then retry. When the switch's own writes are pending, wait for them to settle, then resend with the same Idempotency-Key. | info | No | 409 |
| DALP-14372 | `PLATFORM_THEME_VERSION_CONFLICT` | domain | The theme changed since you read it. | The request was based on an older version of the theme than the one stored. | Read the theme again and resend the change against the current version. | info | No | 409 |
| DALP-14373 | `PLATFORM_TEMPLATE_EXISTS` | domain | A template with this name already exists. | The organisation already has a template, asset class or instrument structure under the same name or slug, or the slug belongs to a built-in asset class. | Choose a different name, or update the existing template. | info | No | 409 |
| DALP-14374 | `PLATFORM_PROFILE_SECTION_STORAGE_LOCKED` | domain | The profile section can no longer be changed. | A participant holds a value for these fields, or a KYC revision filled them, so they cannot be removed or change storage, audience, type, choices or mutability. | Leave those fields as they are, or add a new field under a new key. | info | No | 409 |
| DALP-14375 | `PLATFORM_TEMPLATE_FEATURE_CONFLICT` | domain | The template's features conflict. | A feature configuration of the template is not allowed by the template or one of its classes. | Check each feature's configuration against what the template and its asset class allow, correct the one that does not fit, then retry. | info | No | 409 |
| DALP-14376 | `PLATFORM_TEMPLATE_STRUCTURE_LOCKED` | domain | The instrument structure is locked. | Deployed instruments were issued from this structure, so its classes cannot change and it cannot be deleted. | Create a new structure instead of changing this one. | info | No | 409 |
| DALP-14377 | `PLATFORM_TEMPLATE_STRUCTURE_REVISION_CONFLICT` | domain | The instrument structure changed since you read it. | The request names an older revision of the structure than the one stored. | Read the structure again and resend the change against its current revision. | info | No | 409 |
| DALP-14378 | `PLATFORM_TEMPLATE_STRUCTURE_DRAFT_MEMBER` | domain | A draft template cannot be a class of a structure. | The instrument template named in the request is still a draft. | Publish the instrument template first, then add it to the structure. | info | No | 409 |
| DALP-14379 | `PLATFORM_TEMPLATE_PUBLICATION_UNCHANGED` | domain | The publication state is already as requested. | The structure is already published or unpublished as the request asks. | Read the structure's state; no change is needed. | info | No | 409 |
| DALP-14380 | `PLATFORM_TEMPLATE_ISSUANCE_IN_PROGRESS` | domain | An issuance from this template is still in progress. | A template or instrument structure cannot be deleted while an issuance that uses it is running. | Delete it after the issuance completes. | info | No | 409 |
| DALP-14381 | `PLATFORM_TEMPLATE_ALREADY_PUBLISHED` | domain | The template is already published. | The template was published before this request. | Read the template's state; no change is needed. | info | No | 409 |
| DALP-14382 | `PLATFORM_TEMPLATE_PUBLICATION_CHANGED` | domain | The template was published or deleted by another request. | Another request changed the template's publication state while this one was in flight. | Read the template again and decide whether the change is still needed. | info | No | 409 |
| DALP-14383 | `PLATFORM_TEMPLATE_IN_STRUCTURE` | domain | The template is a class of an instrument structure. | The template belongs to one or more instrument structures, so it cannot be deleted. | Remove the template from those structures, then delete it. | info | No | 409 |
| DALP-14384 | `PLATFORM_TEMPLATE_VISIBILITY_UNSUPPORTED` | domain | Visibility cannot be set for this kind of template. | Visibility is only writable for asset type templates. | Change visibility on an asset type template. | info | No | 409 |
| DALP-14385 | `PLATFORM_TEMPLATE_VISIBILITY_UNATTRIBUTABLE` | domain | The visibility change has no session to attribute it to. | The request carried no session the platform can record the change against. | Sign in with a user session, then send the change again. | info | No | 409 |
| DALP-14386 | `AUTHENTICATION_REQUIRED` | auth | This request needs a signed-in session or an API key. | The request carries no session or API key the platform accepts, so it cannot tell who is calling. | Sign in, or send a valid API key in the X-Api-Key header, then retry the request. | info | No | 401 |
| DALP-14387 | `IDENTITY_SCOPE_REGISTRY_NOT_INDEXED` | dependency | The system's identity registry is not indexed yet. | The system is deployed, but its identity registry is not indexed yet. | Retry after the indexer catches up with the system's deployment. | error | Yes | 503 |
| DALP-14388 | `PLATFORM_AUTH_PROVIDER_REJECTED` | client | The identity provider refused the request. | The identity provider rejected the organisation or membership change this request asked for, so nothing was changed. | Check the request against the organisation's current members, correct it, then send it again. | info | No | 422 |
| DALP-14389 | `TRADING_VENUE_REPORT_UNAVAILABLE` | client | The venue's reports are not available. | The venue's drop-copy settings are missing or incomplete, its drop-copy session is not enabled, or the trading day has not ended, so the platform cannot regenerate, resend or build the report. | Wait until the trading day has ended. If it has, ask the platform operator to enable the venue's drop copy with its chain, venue address and exchange OMS name, then request the report again. | info | No | 409 |
| DALP-14390 | `TRADING_VENUE_REPORT_FILE_NOT_FOUND` | client | The report file was not found. | The trading day produces no VALCSV or OLC file with this name for the venue, or the day is blocked by an open issue and produces none. | Use a file name from the report files list for the same venue, trading day and format, and resolve the issues that list names if it is empty. | info | No | 404 |
| DALP-14391 | `bankRail.credit.RESOLUTION_REFUSED` | domain | Bank credit resolution refused. | The credit cannot be resolved or decided, and `data.reason` names the cause: the request went to another chain than the credit's token (`wrong-chain`), the credit matched no client and the request names none (`client-required`), the named client is not the one the credit belongs to (`client-mismatch`) or is not linked to the connection (`client-not-linked`), the rail wallet holds no suspense tokens for this credit (`not-suspense`), the connection has no active link to the credit's token (`token-link-inactive`), the token does not admit the client's wallet for the rules in `data.blockers` (`wallet-blocked`), the client's wallet changed after the request (`wallet-changed`), only a parked credit can be allocated or returned to the payer (`phase`), the bank reversed the credit and its recall decides the tokens (`recall-open`), the credit re-credits a returned payout and can only be allocated (`payout-returned`), the manager who made the request cannot decide it (`proposer-cannot-approve`), an impersonated session tried to decide it (`impersonated-session`), the approval request closed before a decision (`approval-closed`), the credit changed after the request (`changed-since-request`), the credit or the approval is no longer open for this request (`state`), or the approval rules refused the decision (`approval`). | Resolve what `data.reason` names, then read the credit and ask again or let another bank rail manager decide. | info | No | 409 |
| DALP-14392 | `FIXED_YIELD_ACCRUAL_EXCLUSION_LIMIT_REACHED` | client | The fixed yield feature has no exclusion slot left. | A fixed treasury yield feature allows eight excluded accounts over its lifetime. A slot stays used after the account is included again, so the ninth distinct account is refused. | Use one of the accounts already excluded on this feature. Excluding a different account needs a new fixed yield feature. | info | No | 400 |
| DALP-14393 | `PARTICIPANT_RESTRICTED` | domain | The participant cannot request a withdrawal. | Withdrawals are blocked while the participant account is `{{status}}`: `{{reason}}`. | Ask an administrator to lift the participant restriction, then request the withdrawal again. | info | No | 422 |
| DALP-14394 | `VENUE_CONFIG_APPROVAL_CONFLICT` | client | The venue configuration approval cannot be applied. | The pending venue configuration is already decided, has expired or is of another kind, another change is pending for the same setting, or the setting changed after the proposal was recorded. Applying it can also be refused: the listing broke a venue rule, the pair is already listed, or the listing outcome is not confirmed. For `listing-pending`, check the instrument list before you resubmit. `data.reason` identifies the conflict. | Refresh the venue configuration and approvals list, then submit a new change against the current setting. | info | No | 409 |
| DALP-14395 | `VENUE_CONFIG_APPROVAL_FORBIDDEN` | permission | This user cannot decide the venue configuration change. | Maker-checker approval requires a different venue administrator to decide the change. Deciding a change to an instrument, such as a listing, bands, fees, limits, order types, closing method, transitions, scheduled or pending changes, participant removal or an emergency halt, also needs the platform admin or organisation owner role for the user who approves it, and the venue operator role on the wallet that applies it. The reason in the response identifies which one is missing. | Ask another venue administrator to decide the pending change. For platform-role-required, ask a platform admin or an organisation owner to approve. For venue-role-required, have the venue admin grant the missing role. Then approve again. | info | No | 403 |
| DALP-14396 | `compliance.kyc.KYC_NOT_APPROVED` | permission | KYC approval is required. | The participant's latest KYC profile is not approved for this operation. | Complete KYC review and retry after the profile status is approved. | info | No | 409 |

The previous page is [DALP-14200 to DALP-14299](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference/dalp-14200-14299). The next page is [DALP-14400 to DALP-14499](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference/dalp-14400-14499).


# DALP-14400 to DALP-14499

Source: https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference/dalp-14400-14499
Cause, fix, HTTP status and retry flag for every Platform API error with a code from DALP-14400 to DALP-14499.

This page lists the 36 errors the Platform API can return with a code from DALP-14400 to DALP-14499. Match the `id` in the error envelope to the DALP Code column, then read Retryable and Suggested Fix. The [Platform API error reference](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference#how-to-use-this-reference) explains each column, including Severity, and the [DALP error index](https://docs.settlemint.com/docs/api-reference/errors) lists the page for every code range.

| DALP Code | Machine name | Category | Message | Why | Suggested Fix | Severity | Retryable | HTTP Status |
| --- | --- | --- | --- | --- | --- | --- | --- | --- |
| DALP-14420 | `TERMS_ACCEPTANCE_REQUIRED` | permission | Current trading terms and risk disclosures have not been accepted. | The participant must accept each current organisation document before placing orders or withdrawing funds. | Read and accept the current terms and risk disclosure, then repeat the request. | info | No | 403 |
| DALP-14421 | `LEGAL_DOCUMENT_NOT_AUTHORIZED` | permission | This session may not administer legal documents. | Publishing legal documents or exporting participant acceptances needs an organization owner, platform admin, or identity-manager role, and the caller has none of those grants. | Use an organization-owner or platform-admin session, or a session whose active organization grants one of your wallets the identity-manager role, then retry. | info | No | 403 |
| DALP-14422 | `bankRail.cashOut.UNAVAILABLE` | client | Cash-out not found. | No cash-out with this identifier exists on the bank connection. | List the connection's cash-outs and use one of their identifiers. | info | No | 404 |
| DALP-14423 | `bankRail.cashOut.REFUSED` | domain | Cash-out refused. | The cash-out cannot be requested or decided, and `data.reason` says why: the connection is not active, sends no payment instructions or has no active token link (`connection`), the bank account is not an active account of the holder (`account`), the line is not a requested redemption of that holder on the token (`line`), the amount is not a whole number of the currency's minor units (`amount`), a delegate-mode request has no Idempotency-Key header (`idempotency-key`), the rail wallet controls no single escrow on the token's chain (`escrow`), the holder has not approved the escrow for the amount or does not hold it (`allowance`), the cash-out is not waiting for a checker (`state`), the checker requested it (`requester-cannot-decide`), its approval no longer stands (`approval`), or an unbooked cash-out has nothing the rail wallet can burn yet: it locked nothing in an escrow, the rail wallet has no next wallet staged, or no forced transfer has moved its lock to that wallet (`recovery`), an open recall of a bank credit takes tokens from the holder (`recall-open`), or the holder's participant account is suspended, closed, terminated or restricted from withdrawals, which refuses a new cash-out and a checker's approval alike (`participant-restricted`). | Read `data.reason` for the cause. In booked mode, request the redemption line from the client's linked wallet. In delegate mode, approve the rail's escrow for the amount from that wallet and send an Idempotency-Key header. Pay it to one of that client's active accounts, and ask another bank rail manager to decide a cash-out you requested. To recover an unbooked cash-out, have a token custodian force-transfer its lock to the rail wallet first. Request a cash-out the recall blocks again once the recall closes, and one a participant restriction blocks once an administrator lifts the suspension, closure or restriction on the participant's account status; a terminated account stays blocked. | info | No | 409 |
| DALP-14424 | `bankRail.cashOut.DUPLICATE` | domain | Redemption line already paid out. | Another cash-out already pays this redemption line to a different bank account, or this Idempotency-Key already requested a different cash-out. | List the connection's cash-outs to find the existing one. A line is paid out once, and a new cash-out needs an Idempotency-Key of its own. | info | No | 409 |
| DALP-14425 | `PLATFORM_ROLE_SEGREGATION_CONFLICT` | domain | The requested roles conflict. | The grant would put the auditor role and an operating role, or a pair of duties the organisation's policy keeps apart, on the same wallet. When present, `data.conflicts` names each pair and `data.reasonRequired` says whether a reason lets the grant through. | Grant the roles to separate wallets, or revoke the conflicting role first. When data.reasonRequired is true, send the same grant with a reason. | info | No | 409 |
| DALP-14426 | `CORPORATE_ACTION_QUOTE_STALE` | domain | The plan changed after this quote was read. | The holders, the balances or the terms behind the quote moved between reading the quote and committing, so the plan the commit would run is not the plan the operator reviewed. Nothing was sent on chain. | Read the quote again, review the new plan, then commit with the quoteFingerprint it returns. The quoteFingerprint in this response is the current one. | info | No | 409 |
| DALP-14427 | `CORPORATE_ACTION_QUOTE_NOT_APPLICABLE` | domain | This Corporate Action has no read-only quote. | Bond coupons, conversions and maturity redemptions complete when they are recorded, and a cash dividend or distribution declares on chain when it is recorded, so none of them has a plan to quote before that. A quote is also refused until the action's record date is reached. | Record the action with the create route. For a cash dividend or distribution, quote the recorded action once its record date has passed. For any other action, quote it again once its record date has passed. | info | No | 409 |
| DALP-14428 | `PLATFORM_THEME_LOGO_NOT_BASE64` | client | The theme logo data is not valid base64. | The `fileData` of the logo upload does not decode as base64, so no logo was stored. | Encode the logo file as base64 and send the request again. | info | No | 422 |
| DALP-14429 | `TRANSACTION_PREPARATION_PREDECESSOR_PENDING` | domain | An earlier step of this transaction chain has not completed yet. | A chained operation, such as an approval followed by a purchase, is authorized one step at a time. This step cannot be claimed until the step before it has been signed, submitted and completed on chain. | Wait for the earlier step to complete, then claim this step again. | info | Yes | 409 |
| DALP-14430 | `TRANSACTION_PREPARATION_PREDECESSOR_FAILED` | domain | An earlier step of this transaction chain failed. | A chained operation is authorized one step at a time and each step needs the one before it to complete on chain. The step before this one failed, was cancelled or was given up on, so this step can never be claimed. | Prepare the operation again to start a new chain. Check the earlier step's transaction request for the reason it failed. | info | No | 409 |
| DALP-14431 | `SETTLEMENT_INSUFFICIENT_BALANCE` | client | The wallet holds less of the payment token than the write spends. | The wallet that would sign this write holds less of the payment token than the write spends, so the payment would revert and any approval signed for it would be wasted. | Fund the wallet with the payment token, or choose a smaller amount, then retry. | info | No | 400 |
| DALP-14432 | `ANCHOR_LABEL_ACKNOWLEDGEMENT_REQUIRED` | client | This document label needs your acknowledgement before it is published. | The document label is written to a public chain with every fulfilled filing and cannot be taken back. `data.reasons` names what the label contains: the organization's name, a period, an id-like value, or a shape no filing would publish. | Choose a label that contains none of them, or send the same request again with `acknowledged` set to true to publish it as written. | info | No | 400 |
| DALP-14433 | `settlement.http.CALLER_WALLETS_REFUSED` | domain | The caller's wallets cannot be resolved. | The wallet set of the caller's account is in a state the platform cannot read, so it cannot tell which settlements belong to the caller. | Ask an administrator to repair the custody account behind the caller's wallets. | info | No | 409 |
| DALP-14434 | `CANTON_PROVIDER_CONFIGURATION_MISSING` | domain | The custody provider configuration behind this Canton party is missing. | The custody provider configuration this Canton party or key was created under no longer exists, so the platform cannot sign for it. | Ask an administrator to restore the custody provider configuration, or allocate the party under an existing one. | info | No | 422 |
| DALP-14435 | `PLATFORM_CHAIN_READ_REFUSED` | domain | A contract this request reads refused the call. | A contract the request reads on chain reverted the call, so the request cannot run as asked; repeating it gives the same answer. | Check that the contract and its configuration on this network match what the request expects, then change the request or the contract setup. | info | No | 412 |
| DALP-14437 | `CANTON_PARTICIPANT_ID_UNAVAILABLE` | dependency | The Canton participant did not report its id. | The platform asks the Canton participant for its own id before it hosts a party, and the participant did not answer. The allocation is marked failed, and an allocation that failed is not retried under the same idempotency key. | Ask an operator to restore the Canton participant connection, then send the request under a new idempotency key. | error | Yes | 503 |
| DALP-14438 | `CANTON_NODE_IDENTITY_CHANGED` | domain | The Canton node on this network changed identity. | The node answering for this network reports a participant id other than the one that hosts the parties already registered on it, so the platform refuses to host another party there. | If the node was replaced on purpose, retire the registered Canton allocations of this network, then allocate again. Otherwise point the network at the original participant. | info | No | 409 |
| DALP-14439 | `BUNDLER_ADMISSION_THROTTLED` | permission | The bundler is not admitting operations from this caller right now. | The organization already has as many operations sent through the bundler routes waiting on this network as the deployment allows, or the bundler refuses this sender for a while after a bundle reverted on chain because one of its operations became invalid after admission. | Send the operation again later. For a sender refusal, wait the retryAfterSeconds the error carries. | info | Yes | 429 |
| DALP-14440 | `PLATFORM_PROPOSAL_NOT_FOUND` | client | The add-on proposal was not found. | No proposal with this id exists on the add-on access manager, the caller holds no role that lets them see its proposals, or no add-on access manager at this address on the system takes proposals. | List the access manager's proposals and use an id from the list. If the address has no add-on access manager, use the add-on's own access manager address. | info | No | 404 |
| DALP-14441 | `TOKEN_DEPLOYMENT_NOT_DISCARDABLE` | domain | The deployment cannot be discarded. | The deploy run does not exist in the active organization, is still running, has already been discarded, or has completed. | Discard only a failed deployment listed on the token list of this organization. | info | No | 409 |
| DALP-14442 | `PLATFORM_TABLE_VIEW_NOT_FOUND` | client | The saved table view was not found. | No saved table view with this identifier belongs to the caller, or it belongs to another person. | List the views of the table and use an identifier from the list. | info | No | 404 |
| DALP-14443 | `PLATFORM_TABLE_VIEW_NAME_EXISTS` | domain | A saved view of this table already has this name. | The caller already keeps another view of the table under the same name, ignoring case. | Choose a different name, or replace the view that already uses it. | info | No | 409 |
| DALP-14444 | `PLATFORM_TABLE_VIEW_LIMIT_REACHED` | domain | The caller saved the most views this table allows. | A person can keep at most 50 saved views of one table. | Delete a view of the table you no longer use, then save the new one. | info | No | 409 |
| DALP-14445 | `FEED_ALREADY_EXISTS` | client | A feed already exists for subject `{subject}` and topic `{topicId}`. | The feed directory holds one feed per subject and topic, and this subject and topic already resolve to a feed. | Choose a topic that has no feed, or replace or remove the existing feed before creating a new one. | info | No | 409 |
| DALP-14446 | `FEED_VALUE_NOT_POSITIVE` | client | Feed `{feedAddress}` accepts only values above zero. | The feed rejects zero and negative values, and the submitted value was zero or below. | Submit a value greater than zero. | info | No | 400 |
| DALP-14447 | `party.registry.WRITE_REVERTED` | domain | The registry contract reverted the write. | The registry contract reverted the write with a contract error this platform has no catalog entry for. | Read the transaction request for the revert data, correct the condition it names, then send the write again. | info | No | 422 |
| DALP-14448 | `PLATFORM_ORGANIZATION_NAME_TAKEN` | domain | Another organization already uses this name. | Organization names are unique among active organizations, compared without case or outer spaces. An archived organization's name is free. | Choose a different name. | info | No | 409 |
| DALP-14449 | `PLATFORM_OWNER_EXPIRY_REFUSED` | domain | The ownership change was refused. | An owner whose ownership expires can only give up their own ownership, and an owner cannot make their own ownership time-bound. | Ask an owner without an expiry to make the change. | info | No | 409 |
| DALP-14450 | `PAYMASTER_SIGNER_UNRESOLVED` | domain | The paymaster signer cannot be used for this request. | Custody refused or could not provide the signing wallet bound to this paymaster, and the same request fails again until that changes. | Resolve the custody refusal (account active, approvals decided) or rotate the paymaster signer, then retry. | info | No | 422 |
| DALP-14451 | `TOKEN_DEPLOYMENT_NOT_FINISHABLE` | domain | The deployment's setup cannot be finished. | The deploy run is not a failed deploy of this organization whose token landed and whose request was stored, or its setup is already being finished. | Finish the setup only of a failed deployment that shows a landed token and no setup in progress. | info | No | 409 |
| DALP-14452 | `TOKEN_DEPLOYMENT_FINISH_FORBIDDEN` | permission | Only the user who started this deployment can finish its setup. | Finishing the setup signs with the wallet that started the deploy, so only the user who started it, still acting from that wallet, can finish it. | Ask the user who started the deploy to finish its setup, or dismiss the deployment. | info | No | 403 |
| DALP-14453 | `TOKEN_PARTICIPANT_RESTRICTED` | domain | The participant cannot transfer securities. | Securities transfers are blocked for the participant account that owns the source wallet. When that account is the caller's own, `data` names its status, restrictions and reason. | Ask an administrator to lift the securities-transfers restriction, then send the transfer again. | info | No | 422 |
| DALP-14454 | `PLATFORM_RPC_POOL_EMPTY` | client | The RPC upstream pool cannot be empty. | The request lists no upstreams, so it would leave the network with no RPC endpoint to call. The stored pool was not changed. | List at least one upstream, or delete the pool to remove it. | info | No | 422 |
| DALP-14480 | `CORPORATE_ACTION_ENTRY_NOT_PAID` | domain | This unpaid holder is not marked paid. | Only an entry that carries a payment mark can be reopened. This entry is unpaid, or someone reopened it already. | Reload the unpaid holders list; the entry can be marked paid if the payment was made. | info | No | 409 |
| DALP-14481 | `CORPORATE_ACTION_ENTRY_MARK_CHANGED` | domain | This unpaid holder's payment mark changed. | The entry now carries a different payment mark than the one the reopen was sent for, because someone else reopened it and marked it paid again. | Reload the unpaid holders list and reopen the current mark if it is still wrong. | info | No | 409 |

The previous page is [DALP-14300 to DALP-14399](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference/dalp-14300-14399). The next page is [DALP-14500 to DALP-14999](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference/dalp-14500-14999).


# DALP-14500 to DALP-14999

Source: https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference/dalp-14500-14999
Cause, fix, HTTP status and retry flag for every Platform API error with a code from DALP-14500 to DALP-14999.

This page lists the 54 errors the Platform API can return with a code from DALP-14500 to DALP-14999. Match the `id` in the error envelope to the DALP Code column, then read Retryable and Suggested Fix. The [Platform API error reference](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference#how-to-use-this-reference) explains each column, including Severity, and the [DALP error index](https://docs.settlemint.com/docs/api-reference/errors) lists the page for every code range.

| DALP Code | Machine name | Category | Message | Why | Suggested Fix | Severity | Retryable | HTTP Status |
| --- | --- | --- | --- | --- | --- | --- | --- | --- |
| DALP-14501 | `TOKEN_FEATURES_YIELD_TOP_UP_INSUFFICIENT_BALANCE` | domain | Your wallet does not hold enough of the denomination asset for this yield treasury top-up. | A top-up transfers the denomination asset from your wallet to the yield treasury. Your wallet holds `{{available}}` base units and the top-up asks for `{{required}}`, so the transfer would fail. | Reduce the amount to at most your balance, or add the denomination asset to your wallet, then retry. | info | No | 409 |
| DALP-14502 | `TOKEN_FEATURES_YIELD_TOP_UP_FROM_TREASURY` | domain | Your wallet is the yield treasury, so a top-up cannot change its coverage. | A top-up transfers the denomination asset from your wallet to the yield treasury. Your wallet is that treasury, so the transfer would only move funds to itself. | As the treasury, hold the denomination asset in your wallet and approve the yield feature to pay claims from it (approve yield treasury allowance). A top-up is for wallets other than the treasury. | info | No | 409 |
| DALP-14503 | `TOKEN_FEATURES_YIELD_TREASURY_UNDERFUNDED` | domain | The yield treasury cannot pay this claim yet. | The claim pays the holder's owed yield from the yield treasury. The treasury's balance, or the allowance it gave the yield feature, cannot cover it, so the payout would fail. | Ask the issuer to fund the yield treasury and, when the treasury is a wallet, to approve the yield feature for at least the owed amount. Retry the claim after that. | info | No | 409 |
| DALP-14504 | `MATURITY_INSUFFICIENT_BALANCE` | domain | Your wallet does not hold enough of the denomination asset for this maturity treasury top-up. | A top-up transfers the denomination asset from your wallet to the maturity treasury. Your wallet holds `{{available}}` base units and the top-up asks for `{{required}}`, so the transfer would fail. | Reduce the amount to at most your balance, or add the denomination asset to your wallet, then retry. | info | No | 409 |
| DALP-14505 | `MATURITY_TOP_UP_FROM_TREASURY` | domain | Your wallet is the maturity treasury, so a top-up cannot change its funding. | A top-up transfers the denomination asset from your wallet to the maturity treasury. Your wallet is that treasury, so the transfer would only move funds to itself. | As the treasury, hold the denomination asset in your wallet and approve the maturity feature to pay redemptions from it. A top-up is for wallets other than the treasury. | info | No | 409 |
| DALP-14506 | `MATURITY_TREASURY_UNDERFUNDED` | domain | The maturity treasury cannot pay this redemption yet. | The redemption is paid from the maturity treasury `{{treasury}}` in the denomination asset `{{denominationAsset}}`. The treasury holds `{{treasuryBalance}}` base units and this redemption requires `{{required}}`, so the payout would fail. | Ask the issuer to fund the maturity treasury with at least the required amount, then retry the redemption. | info | No | 409 |
| DALP-14701 | `market-data.price-source.VERSION_CONFLICT` | client | Price source `{sourceId}` changed since you read it. | The price source changed after this request read it, so the edit was not applied. | Read the source again, review the current settings and send the edit again. | info | No | 409 |
| DALP-14702 | `market-data.price-source.HOST_KEY_CHANGED` | client | The SFTP host key of price source `{sourceId}` changed to `{fingerprint}`. | The SFTP server presented a host key other than the one accepted for this source, so the scheduler refused to connect. | Compare the fingerprint with the one the provider publishes, then accept it on the source. | info | No | 409 |
| DALP-14703 | `market-data.price-source.HEARTBEAT_EXCEEDS_BOUND` | client | The heartbeat needs `{requiredSeconds}` seconds but the staleness bound is `{boundSeconds}` seconds. | The heartbeat plus the expected delivery interval plus the expected lag is not shorter than the staleness bound, so the feed would go stale between publishes. | Shorten the heartbeat, the expected interval or the expected lag, or raise the source's stale-after time. | info | No | 422 |
| DALP-14704 | `market-data.price-source.ENDPOINT_REFUSED` | client | Host `{host}` is not an allowed price source endpoint. | The host is a loopback, link-local, metadata, private or unspecified address that this deployment does not allow price sources to reach. | Use the provider's public host name, or ask an operator to add the address range to the deployment's endpoint allow list. | info | No | 422 |
| DALP-14705 | `market-data.price-source.PLAINTEXT_REFUSED` | client | A FIX session to `{host}` needs TLS. | A FIX session without TLS is allowed only to an address inside the deployment's endpoint allow list. | Turn TLS on and name the certificate's server name, or use an address the deployment's endpoint allow list covers. | info | No | 422 |
| DALP-14706 | `market-data.price-source.CREDENTIAL_KIND_REFUSED` | client | A `{kind}` credential does not fit a `{protocol}` price source. | This kind of credential does not fit the source's protocol. | Send the credential kind the protocol uses: a password or private key for SFTP, a logon for FIX, client credentials for Bloomberg, a password for LSEG. | info | No | 422 |
| DALP-14707 | `market-data.price-source.PROTOCOL_FIXED` | client | Price source `{sourceId}` cannot change protocol from `{protocol}`. | A price source keeps the protocol it was created with, so an edit cannot switch it. | Edit the settings for the source's own protocol, or create a new source for the other protocol. | info | No | 422 |
| DALP-14708 | `market-data.price-source.instrument.FEED_DESCRIPTION_UNPARSEABLE` | client | The price feed `{feedAddress}` is not described as BASE / QUOTE. | A price feed names its currency in a description of the form BASE / QUOTE, and this feed's description does not follow that form. | Map an ISIN to a token whose price feed is described as BASE / QUOTE, or let the mapping create the feed. | info | No | 422 |
| DALP-14709 | `market-data.price-source.instrument.FEED_NOT_ISSUER_SIGNED` | client | The price feed `{feedAddress}` is not issuer-signed. | A price source publishes through the organisation's signer, which only an issuer-signed feed accepts. | Map the ISIN to a token whose price feed is issuer-signed, or replace the token's feed with one. | info | No | 422 |
| DALP-14710 | `market-data.price-source.instrument.FEED_ALREADY_MAPPED` | client | The price feed of token `{tokenAddress}` is already mapped to price source `{mappedSourceId}`. | A token's price feed has at most one active source, and another mapping already feeds it. | Unmap the token from its current source first, then map it here. | info | No | 409 |
| DALP-14711 | `market-data.price-source.instrument.PAR_AMOUNT_REQUIRED` | client | ISIN `{isin}` is quoted as a percentage of par but has no par amount. | A price quoted as a percentage of par becomes a token price only when the token's par amount is known. | Enter the token's par amount, or map the ISIN with a per-unit price basis. | info | No | 422 |
| DALP-14712 | `market-data.price-source.instrument.CURRENCY_MISMATCH` | client | ISIN `{isin}` is mapped in `{currency}` but its price feed is quoted in `{feedCurrency}`. | The mapping's currency differs from the currency the token's price feed is quoted in. | Map the ISIN in the feed's currency. A price in another currency is never converted or published. | info | No | 422 |
| DALP-14713 | `market-data.price-source.instrument.TOKEN_REPEATED` | client | Token `{tokenAddress}` appears more than once in the list. | A token's price feed has one live mapping, so a list cannot map the same token twice. | Keep one item per token in the list. | info | No | 422 |
| DALP-14714 | `market-data.price-source.instrument.TOKEN_NOT_FOUND` | client | Token `{tokenAddress}` is not in the token catalog. | The token is not in the organisation's token catalog, so its price feed cannot be named or created. | Use the address of a token the organisation holds in its catalog. | info | No | 422 |
| DALP-14715 | `market-data.price-source.instrument.NOT_FOUND` | client | Price source instrument `{instrumentId}` not found. | The source has no live mapping with this id, either because it never existed or because it was unmapped. | Use an id from the source's list of live instruments. | info | No | 404 |
| DALP-14716 | `market-data.price-source.instrument.LIST_TOO_LARGE` | client | The list holds `{received}` instruments and one request maps at most `{maximum}`. | One request maps a bounded number of instruments, because each new feed is its own chain workflow. | Split the list into requests of no more than the maximum. | info | No | 422 |
| DALP-14717 | `market-data.price-source.instrument.LIST_REFUSED` | client | Some instruments in the list cannot be mapped. | At least one item of the list cannot be mapped, so none was mapped and no feed was created. | Correct the items named in the refusal and send the whole list again. | info | No | 422 |
| DALP-14720 | `market-data.held-price.NOT_FOUND` | client | Held price `{heldPriceId}` does not exist. | The organisation has no held price with this id that the caller may see. | Use an id returned by the held price list. | info | No | 404 |
| DALP-14721 | `market-data.held-price.SUPERSEDED` | client | Held price `{heldPriceId}` was superseded. | A newer price for the feed has been published since this price was held. | Read the feed's current price. A held price that a newer price replaced needs no decision. | info | No | 409 |
| DALP-14722 | `market-data.held-price.CHANGED_SINCE_REVIEW` | client | Held price `{heldPriceId}` changed after it was reviewed. | The price or its evidence moved beyond the hold tolerance since the approver reviewed it, so the approval would publish a price nobody reviewed. | Reload the held price, review the current price and its evidence, then decide again. | info | No | 409 |
| DALP-14723 | `market-data.held-price.STALE` | client | Held price `{heldPriceId}` is stale. | The held price is older than the feed's staleness bound, so publishing it would put a stale price on chain. | Reject the held price and wait for the source's next delivery. | info | No | 409 |
| DALP-14724 | `market-data.held-price.ALREADY_DECIDED` | client | Held price `{heldPriceId}` is already `{status}`. | The held price is no longer waiting for a decision. | Read the held price to see how it was settled. | info | No | 409 |
| DALP-14725 | `market-data.held-price.VERSION_MOVED` | client | Held price `{heldPriceId}` was decided by someone else first. | Another decision landed on this held price first. | Read the held price again and decide only if it still waits. | info | No | 409 |
| DALP-14726 | `market-data.held-price.APPROVER_EXCLUDED` | permission | You cannot decide held price `{heldPriceId}`. | The caller configured the source, accepted its host key or queued the delivery that produced this price, so a second person must decide it. | Ask another feeds manager, or the governor of the token, to decide the held price. | info | No | 403 |
| DALP-14728 | `market-data.held-price.SOURCE_PAUSED` | client | Price source `{sourceId}` is not active. | A price source that is not active publishes nothing, so its held price cannot be approved. | Activate the source, or reject the held price. | info | No | 409 |
| DALP-14729 | `market-data.held-price.SESSION_REQUIRED` | permission | Held price `{heldPriceId}` needs a signed-in decision. | A held price is decided by a signed-in person with a wallet verification, never by an API key. | Sign in to the Console and decide the held price there. | info | No | 403 |
| DALP-14730 | `market-data.held-price.EVIDENCE_UNAVAILABLE` | client | The evidence for held price `{heldPriceId}` is not available. | The raw message behind this price is no longer stored, or no longer matches its recorded hash. | Reject the held price and wait for the source's next delivery. | info | No | 404 |
| DALP-14731 | `market-data.held-price.DECISION_REFUSED` | client | The decision on held price `{heldPriceId}` was refused (`{violation}`). | The approvals service refused the decision for a reason the held price has no dedicated message for. | Read the held price and its approval, then decide again if it still waits. | info | No | 409 |
| DALP-14732 | `market-data.price-source.observation.NOT_FOUND` | client | Observation `{observationId}` does not exist. | The price source has no observation with this id that the caller may see. | Use an id returned by the source's observation list. | info | No | 404 |
| DALP-14733 | `market-data.price-source.observation.EVIDENCE_UNAVAILABLE` | client | The evidence for observation `{observationId}` is not available. | The raw message behind this observation is no longer stored, or no longer matches its recorded hash. | Read the observation's outcome instead, or wait for the source's next delivery. | info | No | 404 |
| DALP-14734 | `market-data.price-source.SESSION_REQUIRED` | permission | Price source `{sourceId}` needs a signed-in session to `{action}`. | This change steers what the scheduler signs and publishes unattended, so it needs a signed-in person with a wallet verification, never an API key. | Sign in to the Console and make the change there. | info | No | 403 |
| DALP-14735 | `market-data.price-source.NOT_FOUND` | client | Price source, connection test, instrument operation or delivery operation `{resourceId}` not found. | The organisation has no price source, connection test, instrument operation or delivery operation with this id. | Use an id returned by the price source list, the connection test request, the instrument mapping request or the fetch request. | info | No | 404 |
| DALP-14736 | `market-data.price-source.TRANSITION_REFUSED` | client | Price source `{sourceId}` cannot `{action}` while it is `{state}`. | The price source is in a state that does not allow this change. | Read the source's current state and request a change that state allows. | info | No | 409 |
| DALP-14737 | `market-data.price-source.CREDENTIAL_MISSING` | client | Price source `{sourceId}` has no credential. | The price source has no stored credential, so the scheduler could not connect with it. | Set the source's credential, then activate it again. | info | No | 409 |
| DALP-14738 | `market-data.price-source.CREDENTIAL_CONFLICT` | client | Price source `{sourceId}` credential changed since you read it. | Another operator replaced the source's credential after this request read its version, so nothing was stored. | Read the source again to get its current credential version, then replace the credential if it is still needed. | info | No | 409 |
| DALP-14739 | `market-data.price-source.instrument.FEED_WORK_FAILED` | operational | The feed work for this instrument ended without a result. | The work that attaches the instrument or creates or adopts the price feed of the token stopped on a fault the platform does not publish. | Map the instrument again, unmapping it first if the source lists it as mapped. Contact support with the X-Request-Id of the mapping request if it fails again. | error | No | 500 |
| DALP-14740 | `market-data.price-source.CREDENTIAL_IN_USE` | client | Price source `{sourceId}` is active, so its credential cannot be removed. | An active price source connects with its credential on every run, so the credential cannot be removed. | Pause the source, then remove the credential, or replace it with a new one while the source runs. | info | No | 409 |
| DALP-14741 | `market-data.price-source.RETIRED` | client | Price source `{sourceId}` is retired. | A retired price source is closed for good: retirement deleted its secrets, and a credential stored on it afterwards would never be deleted. | Create a new price source and set the credential on it. | info | No | 409 |
| DALP-14742 | `market-data.price-source.FETCH_NOT_SUPPORTED` | client | Price source `{sourceId}` streams over `{protocol}` and cannot be fetched on request. | A FIX source streams prices over its open session, so there is nothing to fetch on request. | Read the source's latest delivery, or fetch from an SFTP, Bloomberg or LSEG source. | info | No | 422 |
| DALP-14743 | `market-data.price-source.FETCH_PENDING` | client | Price source `{sourceId}` already has fetch `{operationId}` queued. | A fetch for this source is queued and the scheduler has not picked it up yet, so a second request would only repeat it. | Read the queued fetch until it finishes, then request another if it is still needed. | info | No | 409 |
| DALP-14744 | `OUTSIDE_PUBLICATION_WINDOW` | client | The announcement goes live outside the publication windows. | The venue blocks issuer announcements outside its publication windows, and this one goes live outside a window of an instrument trading the security. | Set displayFrom to a time inside the publication windows, or submit or approve during a window. | info | No | 422 |
| DALP-14745 | `market-data.held-price.SOURCE_STOPPED` | client | Price source `{sourceId}` has stopped. | The price source stopped after a credential or configuration failure, so it publishes nothing until a feeds manager clears the stop. | Ask a feeds manager to fix the cause and restart the source (pause, then activate), then approve again; or reject the held price. | info | No | 409 |
| DALP-14746 | `CORPORATE_ACTION_CHILD_INELIGIBLE` | domain | Spin-off requires a child token that can carry the new instrument's capital. | A spin-off issues capital in a new instrument, so the child token has to carry share or unit capital and be an instrument of its own. The named child carries neither capability, or it is a class of an existing multi-class instrument. | Issue a standalone share or unit token for the child, then declare the spin-off again. | info | No | 409 |
| DALP-14747 | `TRANSACTION_QUEUE_RETRIES_EXHAUSTED` | dependency | Transaction could not be sent before its retries ran out. | A transient fault, such as a chain node that could not be reached, outlasted every retry the transaction queue allows. The queue released the transaction's nonce, so this request cannot land. | Submit the write again with a new idempotency key. Reusing the same key returns this request's recorded failure. For a write of several chained steps, read `transactionId` first, because an earlier step can have completed. | error | Yes | 503 |
| DALP-14748 | `VENUE_ONCHAIN_APPROVAL_REQUIRED` | domain | The venue requires on-chain approval for this action. | The venue's access manager has an approval count above 0 for this action, so the venue contract accepts the call only with an approved on-chain proposal. The platform has no on-chain proposal step, so it sent nothing and no transaction was queued. | Ask the venue's default admin to set the action's approval count to 0 on the venue's access manager, then repeat the request. | info | No | 409 |
| DALP-14749 | `FUND_SUBSCRIPTION_REQUESTS_CHANGED` | domain | The open requests changed while the settlement was prepared. | An investor created or cancelled a request, or another settlement took one, between the moment the platform read the open requests and the moment it recorded the plan. The platform recorded nothing. | Send the same call again. The platform reads the open requests again and settles the list as it stands. | info | Yes | 409 |
| DALP-14750 | `FEED_ISSUER_NOT_TRUSTED` | permission | The feed does not trust the organisation's issuer identity. | The feed accepts values only from a trusted issuer for its topic, and the organisation's issuer identity is not one, or the feed names no trusted issuers registry the platform can read. | Add the organisation's issuer identity to the feed's trusted issuers registry for the topic, then submit again. | info | No | 403 |
| DALP-14751 | `TRANSACTION_QUEUE_OUTCOME_IN_FLIGHT` | client | Another request for this outcome is still running. | An earlier request for the same one-time outcome, such as this claim, refund, withdrawal, maturity or redemption, is still running. The transaction queue did not send this one, so nothing moved because of it. | Wait for the running request to finish, then read its result. Send this request again only if the running one failed. `data.transactionId` names the running request when the queue could read it. | info | No | 400 |

The previous page is [DALP-14400 to DALP-14499](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference/dalp-14400-14499). The next page is [DALP-15000 to DALP-19999](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference/dalp-15000-19999).


# DALP-15000 to DALP-19999

Source: https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference/dalp-15000-19999
Cause, fix, HTTP status and retry flag for every Platform API error with a code from DALP-15000 to DALP-19999.

This page lists the 18 errors the Platform API can return with a code from DALP-15000 to DALP-19999. Match the `id` in the error envelope to the DALP Code column, then read Retryable and Suggested Fix. The [Platform API error reference](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference#how-to-use-this-reference) explains each column, including Severity, and the [DALP error index](https://docs.settlemint.com/docs/api-reference/errors) lists the page for every code range.

| DALP Code | Machine name | Category | Message | Why | Suggested Fix | Severity | Retryable | HTTP Status |
| --- | --- | --- | --- | --- | --- | --- | --- | --- |
| DALP-16806 | `dapi.assets.TOKEN_ACCESS_ZERO_ADDRESS_HOLDER` | client | The zero address cannot hold a role. | The zero address belongs to no wallet, so a role granted to it can never be used or reversed by its holder. | Grant the role to a wallet that can sign. | info | No | 400 |
| DALP-17440 | `WALLET_VERIFICATION_HELD` | permission | Signing is held after a recent wallet security change. | A wallet PIN, authenticator, recovery-code set or identity-provider authenticator of this account changed recently. Signing waits out the longest cooling-off period among the account's organisations. The platform stored nothing. | Wait until the instant in `data.heldUntil` (or the number of seconds in `data.retryAfterSeconds`), then send the request again. | info | No | 403 |
| DALP-17457 | `WALLET_RESTRICTION_NOT_FOUND` | client | The restriction was not found. | No restriction matches this identifier in this organization, or the caller may not see restrictions. | Use the identifier from the request that created the restriction, or ask the organization owner to list the restrictions. | info | No | 404 |
| DALP-17458 | `WALLET_RESTRICTION_ALREADY_ACTIVE` | domain | The wallet is already restricted. | The wallet already has an active restriction with a different reason or scope. | Send the active restriction's reason and scope again to continue it, or lift it first. The organization owner can read them. | info | No | 409 |
| DALP-17459 | `WALLET_RESTRICTION_TOKENS_EMPTY` | domain | No token is available to restrict. | The wallet holds no token in this organization, or none of the tokens in the request exists in the active system. | List tokens that exist in the active system, or add the wallet to the address block list to stop it from receiving tokens later. | info | No | 422 |
| DALP-17460 | `WALLET_RESTRICTION_FREEZE_IN_FLIGHT` | domain | The restriction still has a freeze in flight. | A freeze on one of the restriction's tokens is queued and has not landed, so it cannot be lifted yet. | Read the restriction until no token is queued, then lift it again. | info | Yes | 409 |
| DALP-18113 | `CUSTODY_PROVIDER_CONFIG_NOT_FOUND` | client | Custody provider configuration not found. | No custody provider configuration visible to the caller in the active organization matches this identifier. | List the organization's provider configurations and use an identifier returned there. | info | No | 404 |
| DALP-18228 | `ACCOUNT_CLOSURE_PROOF_REFUSED` | permission | The account-closure request carried no accepted proof. | Filing an account-closure request needs the account password when the account signs in with one, otherwise a wallet factor (the transaction PIN, the transaction code, a recovery code or a code from the identity provider's authenticator); `data.reason` names which proof was missing or rejected. | Send the proof `data.reason` names, then retry. | info | No | 403 |
| DALP-18229 | `ACCOUNT_CLOSURE_REQUEST_OPEN` | domain | An account-closure request is already open. | The account already has an open account-closure request that waits for an administrator, and one account holds at most one open request. | Read the open request from `GET /api/v2/users/me/account-closure-request`, or withdraw it before filing a new one. | info | No | 409 |
| DALP-18230 | `ACCOUNT_CLOSURE_REQUEST_NOT_FOUND` | client | No account-closure request was found. | The account has never filed an account-closure request. | File a request with `POST /api/v2/users/me/account-closure-request`, then read it. | info | No | 404 |
| DALP-18231 | `ACCOUNT_CLOSURE_REQUEST_NOT_OPEN` | domain | The account-closure request is no longer open. | The account has no open account-closure request: none was filed, it was withdrawn, or an administrator already deleted, closed or declined it. A closed request accepts no further transition or decision. | Read the current request to see its outcome; file a new request when one is still wanted. | info | No | 409 |
| DALP-18232 | `PLATFORM_ACCOUNT_CLOSURE_REQUEST_NOT_OPEN` | domain | The user's account-closure request is no longer open. | The request was withdrawn, or an administrator already deleted, closed or declined it, so it accepts no further decision. | Read the user's current request; a new request from the user opens a new decision. | info | No | 409 |
| DALP-18233 | `PLATFORM_ACCOUNT_CLOSURE_REQUEST_NOT_FOUND` | client | The user has no account-closure request. | The user has never filed an account-closure request, so there is nothing to read or decide. | Read the request again after the user has filed one. | info | No | 404 |
| DALP-18234 | `PLATFORM_ACCOUNT_CLOSURE_SELF_DECISION` | domain | You cannot decide your own account-closure request. | The request names the signed-in administrator as the user whose account-closure request is decided. | Ask another platform administrator to decide it. | info | No | 409 |
| DALP-18235 | `ROUTE_NOT_FOUND` | client | No API route matches this path. | The request's method and path match no route the Platform API publishes. | Correct the method and path against the API reference, then send the request again. | info | No | 404 |
| DALP-18236 | `TOKEN_PROJECTION_DATA_INVALID` | dependency | Indexed data cannot be read. | An indexed token or feature row does not match its declared shape, or the read of the indexed data is invalid, so the read cannot succeed. | Do not retry the request: it fails the same way until the indexed data or the read is repaired. Report the request identifier to the platform operator. | error | No | 500 |
| DALP-18237 | `MULTISIG_DRAFT_DUPLICATE_ADDRESS` | client | This signing address already holds a seat on the multisig draft. | Another seat on the draft already holds this address, and one address takes one seat. Nothing was changed. | Choose a signing address that holds no seat on the draft. | info | No | 409 |
| DALP-18238 | `TOKEN_FEATURE_STORED_ROW_INVALID` | operational | Stored token feature data cannot be read. | A stored record a token feature reads, such as a corporate action or its approval request, does not match its expected shape, or the read of that record is invalid, so the request cannot succeed. | Do not retry the request: it fails the same way until the stored record or the read is repaired. Contact support with the X-Request-Id response header. | error | No | 500 |

The previous page is [DALP-14500 to DALP-14999](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference/dalp-14500-14999). The next page is [DALP-20000 to DALP-29999](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference/dalp-20000-29999).


# DALP-20000 to DALP-29999

Source: https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference/dalp-20000-29999
Cause, fix, HTTP status and retry flag for every Platform API error with a code from DALP-20000 to DALP-29999.

This page lists the 13 errors the Platform API can return with a code from DALP-20000 to DALP-29999. Match the `id` in the error envelope to the DALP Code column, then read Retryable and Suggested Fix. The [Platform API error reference](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference#how-to-use-this-reference) explains each column, including Severity, and the [DALP error index](https://docs.settlemint.com/docs/api-reference/errors) lists the page for every code range.

| DALP Code | Machine name | Category | Message | Why | Suggested Fix | Severity | Retryable | HTTP Status |
| --- | --- | --- | --- | --- | --- | --- | --- | --- |
| DALP-20064 | `PLATFORM_ACCOUNT_CLOSURE_SOLE_OWNER` | domain | The user is still the only owner of an organization. | Closing the account would leave an organization without an owner who can sign in, so the platform refuses it while the user owns any organization alone. | Make another member an owner of each organization the user owns alone, then close the account. | info | No | 409 |
| DALP-20523 | `VENUE_VAT_POLICY_INVALID` | client | The venue VAT policy is invalid. | VAT collected on chain moves each side's VAT to one recipient account in the settlement transaction, so it needs an applicable VAT policy and a recipient. Changing the on-chain switch, the recipient or the zero-rated participants is recorded with a reason. The recipient cannot be the venue or its escrow, and it must be able to receive each quote token. | Set a VAT recipient and keep the VAT policy applicable before enabling on-chain VAT, and send a reason with a change to the on-chain switch, the recipient or the zero-rated participants. | info | No | 422 |
| DALP-20524 | `VENUE_VAT_OPEN_ORDERS_BELOW_CAP` | client | Open orders were signed under a fee limit that does not cover on-chain VAT. | VAT collected on chain counts toward each order's signed fee limit. Open orders signed under the previous limit would fail at settlement with the fee above their signed maximum. | Cancel or let the open orders signed under the previous fee limit close, then switch on on-chain VAT or raise the rate again. | info | No | 409 |
| DALP-20525 | `market-data.feeds.WRITE_CANCELLED` | domain | The feed write was cancelled. | An operator cancelled the feed write in the transaction queue before it settled, so nothing was published and the platform starts no new attempt. | Send the write again with a new idempotency key if it is still wanted. | info | No | 409 |
| DALP-20531 | `platform.module.DISABLED` | domain | This module is switched off for your organization. | The licensed module this write belongs to is switched off for the caller's organization, so the organization can read its records but not change them. | Read data.module for the module, ask an organization admin to switch it on in organization settings, then retry. | info | No | 403 |
| DALP-20540 | `accounting.configuration.UNAVAILABLE` | client | Accounting configuration not found. | The active organisation has not stored an accounting configuration. | Store a configuration with PUT /api/v2/accounting/configuration. | info | No | 404 |
| DALP-20541 | `accounting.configuration.STALE` | domain | Accounting configuration changed since it was read. | The configuration changed after you read it, so expectedVersion is no longer the current version. | Read the configuration again and repeat the write with its current version. | info | No | 409 |
| DALP-20542 | `accounting.configuration.INVALID` | domain | Accounting configuration refused. | The account mapping is invalid, or the rule table cannot post against it, and `data.issues` lists each problem. | Correct every problem in `data.issues` and write the configuration again. | info | No | 422 |
| DALP-20543 | `accounting.store.ROW_INVALID` | operational | Stored accounting configuration is invalid. | A stored accounting configuration version does not have the shape this build reads. | Do not retry. Contact support with the X-Request-Id response header so the stored version can be repaired. | error | No | 500 |
| DALP-20544 | `accounting.xero.CONNECTION_NOT_FOUND` | client | Xero connection not found. | The active organisation has no Xero connection to disconnect. | Read GET /api/v2/accounting/xero/connection; connect Xero with POST on the same path first. | info | No | 404 |
| DALP-20545 | `accounting.posting.NOT_FOUND` | client | Posting record not found. | The active organisation has no posting record with this id. | List the records with GET /api/v2/accounting/postings and use an id from the list. | info | No | 404 |
| DALP-20546 | `accounting.posting.NOT_REPLAYABLE` | domain | Posting record cannot be replayed. | The record is posted, is still being posted, or lost its event payload, as `data.refusal` says, so a replay would change nothing. | Read the record again. Only a failed, unmapped or ignored record that keeps its payload can be replayed. | info | No | 409 |
| DALP-22882 | `PLATFORM_MEMBER_HOLDS_ROLES` | domain | The member still holds on-chain roles. | Removing a member ends their access to the organisation but cannot revoke a role on chain. A system or asset role granted to one of their wallets would keep working after they leave. | Revoke the member's system roles and asset roles, then remove the member again. | info | No | 409 |

The previous page is [DALP-15000 to DALP-19999](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference/dalp-15000-19999). The next page is [DALP-100000 to DALP-199999](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference/dalp-100000-199999).


# DALP-200000 to DALP-299999

Source: https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference/dalp-200000-299999
Cause, fix, HTTP status and retry flag for every Platform API error with a code from DALP-200000 to DALP-299999.

This page lists the 9 errors the Platform API can return with a code from DALP-200000 to DALP-299999. Match the `id` in the error envelope to the DALP Code column, then read Retryable and Suggested Fix. The [Platform API error reference](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference#how-to-use-this-reference) explains each column, including Severity, and the [DALP error index](https://docs.settlemint.com/docs/api-reference/errors) lists the page for every code range.

| DALP Code | Machine name | Category | Message | Why | Suggested Fix | Severity | Retryable | HTTP Status |
| --- | --- | --- | --- | --- | --- | --- | --- | --- |
| DALP-200381 | `TRANSACTION_REPORT_TRANSITION_REFUSED` | domain | The transaction report cannot take that transition. | The transaction report's lifecycle does not permit the requested transition from its current state, or the correction it carries names no trade identity or one the report it corrects does not hold, or a rejection, correction or acknowledgement carries a blank reason, body or regulator reference. `data.refusal` names which. | Read `data.from`, `data.event` and `data.refusal`, then send a transition the report's current state permits: a queued report submits, a submitted report is acknowledged or rejected, and a rejected report is resubmitted under its own trade identity. | info | No | 409 |
| DALP-200382 | `settlement.sale.IMPLEMENTATION_PREDATES_OFFERING_TERMS` | domain | This sale's contract predates greenshoes and lock-ups. | A sale runs the implementation its system's token-sale factory points at, and that factory still points at a sale implementation from before greenshoes and lock-ups. This sale's contract therefore has no greenshoe or lock-up terms to write, however its roles are granted. | Point the system's token-sale factory at the current sale implementation. Every sale of the system then runs it, this sale included, and the greenshoe and lock-up writes work. | info | No | 422 |
| DALP-200383 | `TRANSACTION_FORCE_RETRY_CALL_MAY_LAND` | domain | This transaction may still land, so it cannot be force-retried now. | The original call may still land, so another attempt could execute it twice. | Wait for settlement if the chain shows the call or the nonce slot is unresolved. Otherwise, with no nonce reservation or recorded submitted nonce, independently confirm the original call was stopped (with the provider for custody calls) before setting custodianStopped to true. DALP does not verify the stop. | info | No | 409 |
| DALP-200384 | `WALLET_ROLE_ADMINISTRATION_NEEDS_CONSOLE_SIGN_IN` | auth | Wallet-role administration needs a Console-issued session. | This wallet-role administration request does not carry a session issued by the Console. | Sign in to the Console, then retry the request. | info | No | 403 |
| DALP-200385 | `TOKEN_MIRROR_SUPPLY_REFUSED` | client | A token that mirrors an off-chain holding refused this mint or burn. | A token whose metadata names where the holding sits moves supply one movement at a time through its supply delegate, with the custodian or registrar reference, and for a mint with the collateral rule at 100%. A burn takes only the calling wallet's own units. The call missed one of these; `reason` names which. | Send one movement with `registerReference` from a wallet registered as the token's supply delegate, and complete the mirror setup if `reason` is `setup-incomplete`. | info | No | 422 |
| DALP-200386 | `IMPERSONATED_APPROVAL_DECISION_REFUSED` | auth | An impersonated session cannot approve or reject. Sign in as yourself to decide. | This request approves or rejects a pending item, and its session is an impersonation. Nothing changed. | Stop impersonating, sign in with your own account, then approve or reject again. | info | No | 403 |
| DALP-200387 | `STATEMENT_ROW_CEILING_EXCEEDED` | domain | The statement is too large to produce. | The statement holds more rows than one generation can render before its worker runs out of memory. `data.rows` is the row count the requested range produced and `data.ceiling` the most one statement holds. | Request a shorter range, so the statement holds at most `data.ceiling` rows, and send the request again. | info | No | 422 |
| DALP-206300 | `reporting.daily-transactions.ROW_LIMIT_EXCEEDED` | domain | The date range holds too many rows for one report. | The requested range holds more rows than one daily transaction report carries. The platform refuses the request instead of returning a file that stops partway through the range. | Request a shorter date range and download the report in several parts. | info | No | 422 |
| DALP-207901 | `TOKEN_CREATE_FEATURE_FACTORY_NOT_REGISTERED` | domain | The system has no factory for a feature of this template. | The template in `data.templateId` uses the features in `data.features`, and the organization's system has no feature factory for them. The token cannot deploy without them, so nothing was signed or sent. | Ask a System manager to install the missing feature factories from Factories, with System updates, or with `POST /api/v2/system/addon-factories`, then create the token again. | info | No | 409 |

The previous page is [DALP-100000 to DALP-199999](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference/dalp-100000-199999).


# DALP-9000 to DALP-9099

Source: https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference/dalp-9000-9099
Cause, fix, HTTP status and retry flag for every Platform API error with a code from DALP-9000 to DALP-9099.

This page lists the 16 errors the Platform API can return with a code from DALP-9000 to DALP-9099. Match the `id` in the error envelope to the DALP Code column, then read Retryable and Suggested Fix. The [Platform API error reference](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference#how-to-use-this-reference) explains each column, including Severity, and the [DALP error index](https://docs.settlemint.com/docs/api-reference/errors) lists the page for every code range.

| DALP Code | Machine name | Category | Message | Why | Suggested Fix | Severity | Retryable | HTTP Status |
| --- | --- | --- | --- | --- | --- | --- | --- | --- |
| DALP-9072 | `EXTERNAL_TOKEN_NOT_ERC20` | domain | Token at `{tokenAddress}` must expose readable ERC-20 symbol() and decimals() before registration. | External token registration requires ERC-20 metadata so denomination-quoted price feeds can resolve the asset after token creation. | Register a contract that implements ERC-20 metadata, or verify the address and network before retrying. | info | No | 422 |
| DALP-9073 | `TOKEN_CREATE_DENOMINATION_ASSET_NOT_ERC20` | domain | Denomination asset at `{denominationAsset}` must expose readable ERC-20 symbol() and decimals(). | The address named as the denomination asset has no deployed contract, or it does not answer both ERC-20 symbol() and decimals(), which the platform reads to quote amounts and prices in that asset. | Name a denomination asset that implements ERC-20 metadata, or register the external token with valid ERC-20 metadata, then repeat the request. | info | No | 422 |
| DALP-9077 | `TOKEN_MINT_MATURITY_REDEMPTION_MATURED` | client | Token `{tokenAddress}` matured; minting closed for maturity-redemption tokens. | Maturity-redemption tokens stop ordinary issuance once they are matured. The redemption budget is fixed to the token supply at maturity. | Do not mint this token after maturity. Use the existing maturity treasury top-up path to fund redemptions, or issue a new instrument if new supply is required. | info | No | 409 |
| DALP-9079 | `ERC20_METADATA_PROBE_UNAVAILABLE` | dependency | Couldn't read ERC-20 metadata because the RPC endpoint was temporarily unavailable. | The preflight reads symbol() and decimals() live from the chain; that RPC request failed to reach a usable response (connection error, timeout, or rate limit) rather than the contract reverting. | Retry after the Retry-After interval. If it persists, check the network's RPC endpoint health. | error | Yes | 503 |
| DALP-9080 | `CONVERSION_INTEREST_BACKLOG_PENDING` | operational | The holder's accrued interest is still converting. | Convertible-interest settlement is still advancing through bounded on-chain batches. | Wait for the accepted settlement batch, then retry the conversion with the same idempotency key. | error | Yes | 409 |
| DALP-9084 | `CHAIN_ID_HEADER_INVALID` | client | The `X-Chain-Id` header must be a numeric chain id. | The `X-Chain-Id` header value did not pass the chain-id format check: the value must be a positive decimal integer with no leading zeros, no greater than 2147483647 (the largest supported chain id). | Send a numeric chain id within the supported range (for example 31337), or omit the header to target the organization's default network. | info | No | 400 |
| DALP-9085 | `CHAIN_NOT_AVAILABLE_FOR_ORGANIZATION` | client | The requested network is not available for this organisation. | The `X-Chain-Id` header names a network the active organisation has no active system on, or the organisation has not enabled multi-network support. | Switch to the organisation's default network, or add the network in organisation settings after enabling multi-network support. | info | No | 400 |
| DALP-9086 | `CHAIN_NOT_READY` | client | The requested network is not ready for this organization. | The organization has the requested network registered, but its system is not active: the deployment is still pending or running, has failed, or the network was disabled. | Check the network's status in organization settings; wait for the deployment to finish or retry it, then retry the request. | info | No | 409 |
| DALP-9087 | `GAS_REQUIRED` | dependency | The wallet balance is too low to cover this transaction's gas. | The network rejected the transaction because the signing wallet does not hold enough of the network's gas token to pay for it: the gas the transaction needs multiplied by the gas price, plus any value it sends. On a network where gas is not free, transactions from this wallet stop here until someone tops it up. | Send the network's gas token to the wallet, then submit the transaction again. The error `data` carries `shortfallWei` (the smallest amount to add), `recommendedTotalWei` (a buffered target that also covers the next few operations), the wallet `address`, the `chainId`, and the gas `tokenSymbol` to send. | error | Yes | 422 |
| DALP-9089 | `INVITATION_LIMIT_REACHED` | permission | This organization has reached its limit on pending invitations. | The organisation already has 100 invitations awaiting a response, the most it can hold, so no further invitation can be created. Any invitation that was still pending for this address was cancelled first and was not replaced. | Cancel or accept some of the outstanding invitations, then send this invitation again to restore the cancelled one. | info | No | 403 |
| DALP-9090 | `INVITATION_INVITER_NOT_A_MEMBER` | client | No organization is available to invite this person into. | The membership service could not resolve an organization to invite into: the current session may have no organization selected, or the acting account may no longer hold a membership in the organization it points at. | Select an organization the acting account belongs to and send the invitation again. If one is already selected, ask an organization owner to confirm the acting account is still a member of it. | info | No | 404 |
| DALP-9091 | `BUNDLER_WALLET_UNDERFUNDED` | dependency | The organization's bundler wallet cannot cover this operation. | The bundler wallet that submits this organization's account abstraction operations does not hold enough of the network's gas token. The operation waited for funding and reached its inclusion timeout, so it was not sent to the network. | Send the network's gas token to the bundler wallet, then submit the operation again. The error `data` carries the bundler `address`, the `chainId`, and `requiredWei`, the amount the bundler asked for. The organization dashboard shows the same address with a fund action. | error | Yes | 422 |
| DALP-9093 | `INVITATION_CALLER_CREDENTIAL_REJECTED` | auth | This request's API key was rejected. | The credential presented with this request is unknown, switched off, past its expiry, over its usage allowance, or tied to a blocked account, so the invitation was never attempted. | Rotate to an active API key, or re-enable the existing one, then send the invitation again. | info | No | 401 |
| DALP-9094 | `INVITATION_CALLER_RATE_LIMITED` | client | This request's API key has sent too many requests. | The credential presented with this request has used up the requests its rate limit allows inside the current time window, so the invitation was never attempted. | Wait for the current rate-limit window to pass, then send the invitation again. Space bulk invitations out over a longer period. | info | Yes | 429 |
| DALP-9095 | `INVITATION_RECIPIENT_ALREADY_A_MEMBER` | domain | This person already belongs to this organization. | The organization already has an active member registered under this email address, so a second invitation would create a duplicate membership. | Open the existing member from the participants list to adjust their roles, or send the invitation to a different email address. | info | No | 409 |
| DALP-9096 | `INVITATION_CREATE_NOT_PERMITTED` | permission | This account cannot invite members to this organization. | The organization did not accept this invitation request from the acting account, so no invitation exists for the address. | Ask an organization owner to confirm that the acting account may invite members and that the organization is ready to take new members, then send the invitation again. Check the invitations list as well, because an invitation that was pending for this address may have been cancelled by this attempt and would need re-issuing. | info | No | 403 |

The previous page is [DALP-0700 to DALP-0799](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference/dalp-0700-0799). The next page is [DALP-9100 to DALP-9199](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference/dalp-9100-9199).


# DALP-9100 to DALP-9199

Source: https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference/dalp-9100-9199
Cause, fix, HTTP status and retry flag for every Platform API error with a code from DALP-9100 to DALP-9199.

This page lists the 22 errors the Platform API can return with a code from DALP-9100 to DALP-9199. Match the `id` in the error envelope to the DALP Code column, then read Retryable and Suggested Fix. The [Platform API error reference](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference#how-to-use-this-reference) explains each column, including Severity, and the [DALP error index](https://docs.settlemint.com/docs/api-reference/errors) lists the page for every code range.

| DALP Code | Machine name | Category | Message | Why | Suggested Fix | Severity | Retryable | HTTP Status |
| --- | --- | --- | --- | --- | --- | --- | --- | --- |
| DALP-9140 | `GOVERNANCE_POLL_NOT_FOUND` | client | Governance poll not found. | Platform API could not find the poll in the authenticated tenant scope. | Verify the poll identifier and tenant context before retrying. | info | No | 404 |
| DALP-9141 | `GOVERNANCE_POLL_NOT_OPEN` | client | Governance poll is not accepting ballots. | Ballots are only accepted between the poll's open and close times while the poll status is open. | Check the poll's opensAt and closesAt window; ballots submitted after close are rejected even if signed before close. | info | No | 409 |
| DALP-9143 | `GOVERNANCE_POLL_DEFINITION_MISMATCH` | client | Ballot was signed over a different poll definition. | The definition hash in the signed ballot does not match the poll's current immutable definition, so the signature does not cover this poll. A ballot that picks an option outside the poll definition is refused the same way. | Fetch the poll again, pick one of its options, and re-sign the ballot over its current definitionHash. | info | No | 409 |
| DALP-9144 | `GOVERNANCE_BALLOT_SIGNATURE_INVALID` | client | Ballot signature verification failed. | The signature does not verify against the claimed voter address. Undeployed smart wallets and ERC-6492 wrapped signatures are not accepted. The same code also answers a voter address that is not one of the caller's wallets, and a caller with no wallet that can sign. | Sign the exact PollBallot typed data with the claimed voter wallet and retry. Smart wallets must be deployed on-chain. | info | No | 422 |
| DALP-9146 | `GOVERNANCE_BALLOT_ZERO_WEIGHT` | client | Voter has zero voting power at the poll record date. | Ballot weight resolves from the indexed voting-power snapshot at the poll's record date, and a zero-weight ballot is rejected. A token without the voting-power feature gives every voter zero weight. | Only wallets with delegated voting power at the record date can cast ballots on this poll. | info | No | 422 |
| DALP-9147 | `GOVERNANCE_POLL_OPERATOR_REQUIRED` | client | Caller lacks the governance role on the token. | Creating, closing, or exporting a poll requires the governance role on the token whose holders are polled. | Ask a token admin to grant the governance role to one of your wallets, then retry. | info | No | 403 |
| DALP-9151 | `GOVERNANCE_INSTANCE_NOT_FOUND` | client | Governance instance not found. | No governor and timelock pair is deployed for this token by a factory in the authenticated system. | Install the token-governance add-on on the system, then create the first proposal to deploy the token's governance pair, or verify the governor address. | info | No | 404 |
| DALP-9152 | `GOVERNANCE_PROPOSAL_NOT_FOUND` | client | Governance proposal not found. | The proposal id is not indexed on the given governor within the authenticated system. | Verify the governor address and proposal id; freshly created proposals appear once indexed. | info | No | 404 |
| DALP-9153 | `GOVERNANCE_PROPOSAL_CONFIG_INVALID` | client | Proposal configuration is out of bounds. | Record date, voting period, execution delay, or quorum violates the protocol bounds or the governance instance's quorum floor. | Adjust the schedule parameters to the documented bounds (record date now+24h to now+90d, period 1-30 days, delay 24h-30d, quorum at or above the instance floor) and retry. | info | No | 422 |
| DALP-9154 | `GOVERNANCE_ACTION_NOT_IN_CATALOG` | client | Executable action is not in the curated catalog. | Proposals may only carry curated governance-role single-call operations; the composed action's target or selector is outside the catalog or the feature is not attached to the token. | Compose the proposal from catalog actions on features attached to the token. | info | No | 422 |
| DALP-9155 | `GOVERNANCE_TIMELOCK_MISSING_ROLE` | client | Timelock lacks the governance role on the token. | Executable proposals run through the timelock, which must hold the governance role on the token's access manager before the vote is created. | Grant the governance role to the timelock on the token's access manager, then retry. | info | No | 409 |
| DALP-9158 | `GOVERNANCE_VOTE_ALREADY_CAST` | client | Vote already cast on this proposal. | On-chain governance votes are final; one ballot per wallet per proposal. | No action is available. The recorded ballot stands. | info | No | 409 |
| DALP-9160 | `GOVERNANCE_DETACH_BLOCKED` | client | Voting-power feature cannot be detached during open votes. | The token's governor has proposals that are not executed yet, defeated, or canceled; detaching the voting-power feature would invalidate their electorate. | Wait for open proposals to reach a terminal state (or cancel them), then retry the detach. | info | No | 409 |
| DALP-9164 | `GOVERNANCE_BALLOT_RATE_LIMITED` | client | Poll ballot rate limit exceeded. | Too many ballot submissions arrived from this caller for this poll in a short window. | Wait for the Retry-After interval before submitting another ballot. | info | Yes | 429 |
| DALP-9166 | `VOTING_OPERATION_REJECTED` | dependency | The voting-power operation could not be completed. | The voting-power feature is not attached to the token, the voting wallet is not active in a recognised identity registry, or the delegation signature does not verify. | Attach the voting-power feature, register the voting wallet, or sign a fresh delegation, then send the request again. | error | No | 503 |
| DALP-9167 | `MULTI_NETWORK_ADMIN_REQUIRED` | permission | Multi-network changes require an organization administrator. | Enabling multi-network support and adding networks are organization-admin operations; the calling session is neither a platform admin nor an organization owner. | Use an account that holds the organization owner role (or platform admin), then retry. | info | No | 403 |
| DALP-9169 | `MULTI_NETWORK_DISABLE_BLOCKED` | client | Multi-network support cannot be disabled while additional networks are in use. | At least one non-default network has a system that is pending, deploying or active. Disabling multi-network support would orphan it. `data.blockingChainIds` lists these networks. | Keep multi-network support enabled while any network in `data.blockingChainIds` has a pending, deploying or active system. | info | No | 409 |
| DALP-9175 | `TOKEN_CREATE_REQUIRED_PARAM_MISSING` | domain | The selected template requires additional feature parameters before the token can be created. | The template marks these feature-config params required at deploy time, and the request left them unset or at zero, which the template treats as unset. | Provide a non-zero value for each listed param in the matching `featureConfigs` entry and resubmit the token creation request. | info | No | 422 |
| DALP-9176 | `TOKEN_CREATE_REQUIRED_WINDOW_EXPIRED` | domain | The selected template requires a conversion window that has not already ended. | The template marks the conversion window required at deploy time, and the requested window end is in the past. The instrument would be expired at creation and could never convert. | Set `conversionWindowEnd` to a future time in the `featureConfigs.conversion` entry and resubmit the token creation request. | info | No | 422 |
| DALP-9182 | `TOKEN_FEATURE_DETACH_BLOCKED_BY_DEPENDENTS` | client | This feature cannot be detached while attached features depend on it. | Other features attached to this token declare this feature as a dependency in the feature registry. Detaching it would break their on-chain accounting; for example a dividend or interest feature reads the balance checkpoints that historical-balances records at each record date. | Detach the dependent features first, then retry detaching this feature. | info | No | 409 |
| DALP-9188 | `SESSION_EVIDENCE_INVALID` | auth | Session authentication evidence is incomplete. | The signed-in session has no linked sign-in provider, or its stored session data does not have the shape the platform reads. | Sign in again, then retry the request. | info | No | 401 |
| DALP-9196 | `CUSTODY_OWNER_REQUIRED` | permission | This custody operation requires organization-owner access. | Only an owner of this organisation or a platform administrator may list or manage the organisation's custody provider configurations. The caller is neither. | Retry as an organization owner or platform administrator. | info | No | 403 |

The previous page is [DALP-9000 to DALP-9099](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference/dalp-9000-9099). The next page is [DALP-9200 to DALP-9299](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference/dalp-9200-9299).


# DALP-9200 to DALP-9299

Source: https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference/dalp-9200-9299
Cause, fix, HTTP status and retry flag for every Platform API error with a code from DALP-9200 to DALP-9299.

This page lists the 22 errors the Platform API can return with a code from DALP-9200 to DALP-9299. Match the `id` in the error envelope to the DALP Code column, then read Retryable and Suggested Fix. The [Platform API error reference](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference#how-to-use-this-reference) explains each column, including Severity, and the [DALP error index](https://docs.settlemint.com/docs/api-reference/errors) lists the page for every code range.

| DALP Code | Machine name | Category | Message | Why | Suggested Fix | Severity | Retryable | HTTP Status |
| --- | --- | --- | --- | --- | --- | --- | --- | --- |
| DALP-9243 | `TOKEN_CREATE_INPUT_ENCODING_INVALID` | client | The token creation values cannot be processed. | The token creation input cannot be represented by the durable workflow schema. | Read the message for the field or rule the request broke, correct it, then send the request again. | info | No | 422 |
| DALP-9244 | `TENANT_WALLET_RESOLUTION_FAILED` | dependency | The tenant wallet could not be resolved. | The request could not resolve the tenant wallet required for this operation. | Verify the participant wallet assignment and wallet service availability, then retry. | error | Yes | 503 |
| DALP-9252 | `USER_ASSETS_METADATA_KEY_INVALID` | client | The metadata key cannot be used for this asset query. | The requested metadata key is unknown or is not eligible for the selected filter or grouping operation. | Use one of the available metadata keys that supports this query operation. | info | No | 422 |
| DALP-9253 | `SYSTEM_READ_FAILED` | dependency | The system projection is temporarily unavailable. | The indexed system projection could not be resolved for this request. | Retry after the indexer catches up or verify the organization system setting. | error | Yes | 503 |
| DALP-9259 | `TOKEN_READ_DEPENDENCY_FAILED` | dependency | Token data is temporarily unavailable. | The indexed token projection could not be read for this request. | Retry after the indexer database is available; if the failure persists, inspect its query health. | error | Yes | 503 |
| DALP-9260 | `PORTFOLIO_PERSISTENCE_FAILED` | dependency | Portfolio data is temporarily unavailable. | The indexed portfolio data required by this endpoint could not be read or persisted. | Retry after a short backoff. If the failure continues, ask an operator to check the indexer database. | error | Yes | 503 |
| DALP-9266 | `TOKEN_FEATURE_PERSISTENCE_FAILED` | dependency | Token feature data is temporarily unavailable. | The token-feature data required by this endpoint could not be read or persisted. | Retry after a short wait. If the failure persists, check the token database, the indexer and the chain RPC. | error | Yes | 503 |
| DALP-9267 | `TOKEN_WRITE_PERSISTENCE_FAILED` | dependency | The token write could not be persisted. | A persistence operation required by the token mutation failed. | Retry after a short wait. If the failure persists, check the token database, the indexer and the chain RPC. | error | Yes | 503 |
| DALP-9269 | `COLLECTION_SORT_FIELD_UNKNOWN` | client | The sort field is not supported on this list. | List endpoints accept only the sortable fields declared for that collection. An unknown or non-sortable field name cannot order the page. | Use one of the sortable fields documented for this list endpoint, or omit `sort` to keep the default order. | info | No | 400 |
| DALP-9270 | `COLLECTION_SORT_MULTI_FIELD_UNSUPPORTED` | client | List endpoints accept a single sort field. | The collection query codec supports one sort field per request. Comma-separated multi-field sort is not implemented on the shared list infrastructure. | Send a single field in `sort` (prefix with `-` for descending) and retry. | info | No | 400 |
| DALP-9271 | `COLLECTION_FILTER_FIELD_UNKNOWN` | client | The filter field is not supported on this list. | List endpoints accept only the filterable fields declared for that collection. An unknown or non-filterable field name cannot narrow the page. | Use one of the filterable fields documented for this list endpoint, or remove the unknown filter key. | info | No | 400 |
| DALP-9272 | `COLLECTION_FILTER_OPERATOR_UNKNOWN` | client | The filter operator is not supported. | Each collection filter accepts only the operators defined for that field. An unknown operator cannot be applied safely to the list query. | Use a documented operator for the field (for example `eq`, `iLike`, `inArray`, or `between`) and retry. | info | No | 400 |
| DALP-9273 | `COLLECTION_FILTER_IN_LIST_TOO_LARGE` | client | The membership filter list is too large. | Membership filters (`inArray` and `notInArray`) cap the number of values so SQL `IN` clauses stay bounded and predictable. | Send at most 100 values in the membership list, or split the request across multiple pages or batches. | info | No | 400 |
| DALP-9274 | `COLLECTION_PAGE_LIMIT_OUT_OF_RANGE` | client | The page limit is out of range. | Every collection list bounds page size to an integer between 1 and 200 so a single request cannot pull an unbounded result set. | Set `page[limit]` to an integer from 1 through 200 and use pagination links for additional rows. | info | No | 400 |
| DALP-9275 | `COLLECTION_PAGE_OFFSET_OUT_OF_RANGE` | client | The page offset is out of range. | Collection list offsets must be integers of zero or greater. A negative offset is not a valid start position for a page. | Set `page[offset]` to an integer greater than or equal to 0. | info | No | 400 |
| DALP-9281 | `ORGANIZATION_NOT_FOUND` | client | Organization not found. | The caller is not a member of this organisation and holds no open invitation to it. | Read the organisations this account belongs to or is invited to, then send one of those ids. | info | No | 404 |
| DALP-9288 | `TOKEN_LIST_FACTORY_REGISTRY_UNAVAILABLE` | dependency | Token factory registry is not ready for this system. | The active system has no indexed token-factory registry address, so the token list cannot authorize which factories belong to the system. | Wait for the system token-factory registry to index, then retry the request. | error | Yes | 503 |
| DALP-9289 | `TOKEN_LIST_FILTER_INVALID` | client | Token list request names a sort term or field selection it does not support. | The token list orders only on its published columns and accepts one `sort` term per request, so a term that names no published column, or a comma-separated list of terms, cannot be answered, and ordering by something else would publish a page that was not asked for. The same refusal answers a `fields[token]` selection that names a member the list does not publish, and a sort on a column some holdings do not have. `data.filterId` carries the refused term as it was sent. | Send one `sort` term that names a published column (prefix it with `-` for descending order), or omit `sort` to take the default order. Select only members the list publishes in `fields[token]`. | info | No | 400 |
| DALP-9290 | `TOKEN_CREATE_AMBIGUOUS_INTEREST_PROVIDER` | domain | The conversion feature cannot resolve a usable interest provider. | The conversion feature discovers its interest provider through ERC-165. With both yield features attached it finds two, refuses to auto-select, and every interest-bearing conversion path fails closed after deployment. An explicit provider replaces that discovery, so it must itself be a deployed contract that answers ERC-165 for IConversionInterestProvider and reports the same denomination asset as the conversion. The conversion config is immutable and has no provider setter, so neither case is repairable after creation. | Set `featureConfigs.conversion.interestProvider` to a deployed interest provider that uses the conversion's denomination asset, or attach only one yield feature and leave the provider unset so discovery resolves it. | info | No | 422 |
| DALP-9291 | `TOKEN_CREATE_MARKCONVERTED_YIELD_INCOMPATIBLE` | domain | The MarkConverted debt method cannot be combined with a yield feature. | MarkConverted records a conversion without moving tokens, so it suits instruments whose token is a receipt and whose principal is held in a separate ledger. Yield features pay out on the token balance, which on such an instrument is not the amount owed. After a conversion it no longer reflects active principal either. | Pick the Burn or Lock debt method, which retire the converted principal and keep the balance accurate, or remove the yield feature from the design. | info | No | 422 |
| DALP-9298 | `TRADING_VENUE_MARKET_NOT_FOUND` | client | The instrument was not found. | The id in the request names no venue, instrument or other venue record that this caller can see in the active organisation. A venue record is an approval, trade, bust, parked fill, price alert, watchlist, access profile or calendar. | Use an instrument id from the instruments list of your organization. | info | No | 404 |
| DALP-9299 | `TRADING_VENUE_ORDER_NOT_FOUND` | client | The order was not found. | The order id does not name an order placed by a wallet the selected participant controls, the order is no longer open to cancel, or no open order matches a mass-cancel filter. | Use an order id from the working-orders list of the selected participant. | info | No | 404 |

The previous page is [DALP-9100 to DALP-9199](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference/dalp-9100-9199). The next page is [DALP-9300 to DALP-9399](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference/dalp-9300-9399).


# DALP-9300 to DALP-9399

Source: https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference/dalp-9300-9399
Cause, fix, HTTP status and retry flag for every Platform API error with a code from DALP-9300 to DALP-9399.

This page lists the 19 errors the Platform API can return with a code from DALP-9300 to DALP-9399. Match the `id` in the error envelope to the DALP Code column, then read Retryable and Suggested Fix. The [Platform API error reference](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference#how-to-use-this-reference) explains each column, including Severity, and the [DALP error index](https://docs.settlemint.com/docs/api-reference/errors) lists the page for every code range.

| DALP Code | Machine name | Category | Message | Why | Suggested Fix | Severity | Retryable | HTTP Status |
| --- | --- | --- | --- | --- | --- | --- | --- | --- |
| DALP-9302 | `ORDER_INTAKE_REJECTED` | client | The order was refused before it reached the book. | An intake check failed, for example identity eligibility, the instrument's status, price band or size limits, desk limits, participant standing, the signed fee cap, expiry, the signature, the submission rate, a non-trading good-till-date day, time-locked units or the trading cut-off. `data.reason` names the check. | Correct the order against the rejection reason in the response, then submit a new signed order. When the reason is units-time-locked, sell no more than the unlocked units, or wait the seconds the response gives for the next units to unlock. When the reason is gtd-date-not-trading-day, use the nextTradingDay the response gives, or another trading day from the instrument's trading-days list. | info | No | 422 |
| DALP-9305 | `MARKET_STATE_INVALID` | client | The instrument cannot make this transition. | The requested instrument operation is not valid for the instrument's current status, for example resuming an instrument that is not halted or halting one that is not live. The same code answers a listing or setting that breaks a venue rule. The same token is on both sides. The VWAP window is missing. The lot size is not one whole base token. A fee leg is outside 0 to 10,000 basis points. The revision changed while the request was in flight. | Read the instrument on its venue page, then issue a change its status and the venue rules allow. | info | No | 409 |
| DALP-9306 | `MARKET_STREAM_NOT_FOUND` | client | The market-data stream could not be opened. | The stream request named an instrument this deployment does not serve. | Open the stream against a live instrument id from the instruments list. | info | No | 404 |
| DALP-9311 | `CANTON_PARTY_WALLET_NOT_FOUND` | client | The Canton party wallet was not found. | No Canton party wallet, or no contract or instrument the write names, is visible to the active organisation. | Use a wallet id from the wallets list of the active organization. | info | No | 404 |
| DALP-9313 | `CANTON_NETWORK_NOT_CONFIGURED` | domain | No Canton participant network is configured. | This deployment has no enabled Canton network, or none with the requested id, so the platform cannot allocate a party or submit a DAML command. | Ask an operator to add a Canton network to the platform configuration, then retry. | info | No | 422 |
| DALP-9314 | `CANTON_COMMAND_NO_LONGER_APPLIES` | domain | The approved Canton command no longer applies. | The DAML command was approved, then the target contract or ledger state changed so the same command cannot settle. | Submit a new command. The existing approval is not reopened. | info | No | 409 |
| DALP-9315 | `CANTON_PROVIDER_SIGNING_DENIED` | permission | The custody provider blocked this Canton signature. | The organization's custody provider refused to sign the Canton digest, so the platform stopped the submission. | Resolve the custody provider policy denial, then submit a new Canton command. | info | No | 403 |
| DALP-9318 | `CANTON_SUBMISSION_FAILED` | dependency | Canton command submission failed. | The platform accepted the command, then submission stopped before the ledger settled it. | Read the submission's status. If it did not settle, send the command again with the same submission id. | error | No | 500 |
| DALP-9319 | `CUSTODY_CANTON_SIGNING_UNSUPPORTED` | domain | This custody provider cannot create Canton party wallets. | The selected custody provider configuration cannot create Canton party wallets. Its provider does not offer Ed25519 key generation and digest signing, or the configuration is not managed, healthy, enabled for new accounts and activated for this Canton network. The platform does not substitute another provider. | Select a managed, healthy custody provider configuration that supports Canton signing and is activated for this Canton network. | info | No | 422 |
| DALP-9320 | `REPORTING_UNAVAILABLE` | dependency | The reporting source could not be read. | The reporting store, object storage, Ledger Data or another source this request needs did not answer. A period with no activity is a nil return and never reports this error. | Repeat the request. If it keeps failing, check the platform database, object storage and Ledger Data health. | error | Yes | 503 |
| DALP-9321 | `CANTON_APPROVAL_EXPIRED` | domain | The Canton command's validity window closed. | The command's validity window closed while the intent waited for approval, so the platform never sent it to the ledger. | Submit the command again. The expired intent is terminal and its approval is not reopened. | info | No | 410 |
| DALP-9322 | `CANTON_SIGNER_NOT_ENTITLED` | permission | This custody account is not enabled for Canton signing. | The signing account behind this organization is not enabled for Canton Ed25519 signing, so the platform created nothing. | Use an organization whose custody account is enabled for Canton signing, then submit the request again. | info | No | 403 |
| DALP-9323 | `ASSET_REFERENCE_INVALID` | client | Asset reference names neither a token contract nor a Canton instrument. | The shared asset read addresses an EVM token by its contract address and a Canton instrument by its instrument id plus the `instrumentAdmin` party that completes the key. The path segment is not an address and no `instrumentAdmin` was sent, so the request names nothing the platform can look up. | Send a token contract address, or send the instrument id together with `instrumentAdmin`. | info | No | 400 |
| DALP-9324 | `ASSET_FILTER_FAMILY_MISMATCH` | client | Filter names a column the asset's chain family does not have. | A shared collection under one asset, its holders or its holdings, advertises both families' columns, and the asset decides which family answers. The filter names a column from the other family, and the answering family has no such column to evaluate it against. The refusal names the field, the family, and the columns that family does publish on the collection that was read. | Filter on a column the named asset's family has, or read the asset in the family whose columns you are filtering on. | info | No | 400 |
| DALP-9325 | `CANTON_SETTLEMENT_BATCH_NOT_COVERABLE` | domain | The batch's allocations do not cover its transfer legs exactly. | Every leg of a batch needs both a sender and a receiver side authorised by an allocation, and at least one leg had neither or only one, so no leg executed. The platform released the escrow it could, and `data.unreleasedAllocationContractIds` lists any allocation still escrowed. | Read `data.uncoveredTransferLegIds` and `data.unauthorizedTransferLegSides`, escrow the missing sides, then submit the batch again. | info | No | 409 |
| DALP-9326 | `OPERATION_FAMILY_UNSUPPORTED` | domain | The operation is not available on the selected ledger family. | The request selected a ledger family for which this operation has no serving contract, so the platform stopped before it queried a different ledger. | Select a family from `data.supportedFamilies`, then retry. An empty list means this deployment serves the operation on no family. | info | No | 422 |
| DALP-9328 | `CANTON_NETWORK_NOT_ENABLED` | domain | The Canton network is disabled on this deployment. | The request named a Canton network this deployment is not currently running, so the platform created no intent, recorded no approval, and sent nothing to the ledger. | Ask an operator to enable the Canton network, then submit the request again. Work already accepted stays parked and resumes when the network is enabled. | info | No | 422 |
| DALP-9330 | `CANTON_TOKEN_OPERATION_REQUEST_INVALID` | client | The token operation request does not describe a valid operation. | The request does not describe an operation the ledger can carry out. The transfer window has already passed in ledger time. The transfer is addressed to the party sending it. A contract belongs to a different instrument than the route names, or the caller's scope does not carry it. An addon's operating party is not the instrument admin. The admin does not own the treasury account alone. A feature config cannot build its module. A holding freeze names no holding or account state. The transfer id in the path differs from the body's `transferInstructionContractId`. The platform prepared no command. | Send an executeBefore later than the current ledger time, address a transfer to a party other than the sender, name the contracts of the instrument the route addresses, and operate an addon as its instrument admin with a treasury the admin owns. | info | No | 400 |
| DALP-9355 | `COLLECTION_FILTER_VALUE_INVALID` | client | The filter value does not fit this field. | The filter value does not fit the field's type or the operator's shape, such as an empty list for `inArray` or a `between` value that is not a pair, so the endpoint cannot apply it. | Send a value of the field's type in the shape the operator expects, then retry. | info | No | 400 |

The previous page is [DALP-9200 to DALP-9299](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference/dalp-9200-9299). The next page is [DALP-9400 to DALP-9499](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference/dalp-9400-9499).


# DALP-9400 to DALP-9499

Source: https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference/dalp-9400-9499
Cause, fix, HTTP status and retry flag for every Platform API error with a code from DALP-9400 to DALP-9499.

This page lists the 48 errors the Platform API can return with a code from DALP-9400 to DALP-9499. Match the `id` in the error envelope to the DALP Code column, then read Retryable and Suggested Fix. The [Platform API error reference](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference#how-to-use-this-reference) explains each column, including Severity, and the [DALP error index](https://docs.settlemint.com/docs/api-reference/errors) lists the page for every code range.

| DALP Code | Machine name | Category | Message | Why | Suggested Fix | Severity | Retryable | HTTP Status |
| --- | --- | --- | --- | --- | --- | --- | --- | --- |
| DALP-9414 | `TRADE_BUST_REFUSED` | client | The trade bust was refused before any reversal. | A pre-check failed: the trade is not chain-confirmed, an order on it is still open, the bust window has passed, the trade is already busted or proposed, a counterparty or fee account lacks balance, the compliance path is blocked or unavailable, or the organisation's operations signer is missing or lacks the custodian role the forced transfers need. The reason in the response names the failed check. | Resolve the named reason, then propose the bust again. | info | No | 422 |
| DALP-9415 | `TRADE_BUST_APPROVAL_INVALID` | client | The maker-checker rules refused this decision. | The proposer can never approve or reject their own proposal, a proposal that already carries a decision accepts no second one, a decision route accepts only records of its own kind, and a record whose approval window has lapsed accepts no decision. The violation in the response names the rule. | Ask a different venue operator to decide the proposal, or refresh the approvals list to see its current state. | info | No | 409 |
| DALP-9421 | `EXCHANGE_RATE_FEED_ROW_DECODE_FAILED` | operational | The stored exchange-rate feed could not be read. | A feed row in the platform database does not match the shape the read expects, so the platform stopped rather than publish a rate it cannot stand behind. | Do not retry. Contact support with the `X-Request-Id` response header so an operator can repair the stored feed row. | error | No | 500 |
| DALP-9425 | `SYSTEM_OPERATION_REJECTED` | domain | The system operation requirements were not met. | The target contract could not accept the supplied system input or sender authority. | Check the system addresses and parameters, then use a sender with the required on-chain role. | info | No | 400 |
| DALP-9426 | `SYSTEM_OPERATION_CONFLICT` | domain | The system state already conflicts with this operation. | A system role or resource changed before this operation completed, or the requested change is already applied. | Read the current system roles and resource state, then rebuild the request from that state. | info | No | 409 |
| DALP-9427 | `SYSTEM_OPERATION_UNPROCESSABLE` | domain | The system contract refused the operation. | Contract checks refused the operation after request validation because its authority, address, or state requirement was not met. | Read the target contract state and required roles, correct the failed requirement, then retry. | info | No | 422 |
| DALP-9429 | `SYSTEM_OPERATION_OUTCOME_UNKNOWN` | operational | The system operation outcome is unknown. | Recovery stopped before the platform could confirm whether the underlying write completed. | Do not resubmit the operation. Verify its final on-chain state before taking further action. | error | No | 503 |
| DALP-9430 | `INVALID_REQUEST_EXECUTOR` | client | X-Executor has no matching execution mode. | The X-Executor header does not name a supported execution mode. | Use eoa or smart-wallet, or omit X-Executor to use the organization default. | info | No | 400 |
| DALP-9432 | `REQUEST_EXECUTOR_FAMILY_UNSUPPORTED` | client | This executor does not exist on the selected network. | The eoa and smart-wallet executors are EVM account shapes. The selected chain family uses another signing model. | Omit X-Executor on this network and use its custody-held signing account. | info | No | 400 |
| DALP-9433 | `REQUEST_EXECUTOR_UNAVAILABLE` | client | The selected executor is unavailable. | The selected participant has no usable account for the requested executor. When `data.reason` is present, this organization cannot drive the participant's wallet and the value names the capability it lacks, such as account abstraction not being enabled on this chain. The platform never substitutes the wallet's signer key. | Select an available executor or provision the participant smart wallet, then retry. | info | No | 409 |
| DALP-9438 | `LOGIN_2FA_REQUIRED` | auth | Login two-factor authentication setup is required. | This deployment requires interactive users to enroll login two-factor authentication before calling authenticated APIs. | Open the two-factor setup page, enroll an authenticator app, then retry the request. | info | No | 403 |
| DALP-9439 | `BLOCKCHAIN_ROLE_REQUIRED` | permission | The selected executor cannot act on this route. | The route refused the request before the executor could act. Four conditions cause this. The executor holds none of the indexed blockchain roles the route requires. No usable executor could be selected for the request. The request has no active system on this chain. Account abstraction is off for the executor the request asked for. `data.requiredRoles` lists the roles that authorise the route. | Check the `X-Executor` header and that account abstraction is on for your organisation. Then use an executor with one of the required roles, or grant that role, and try again. | info | No | 403 |
| DALP-9440 | `BLOCKCHAIN_SYSTEM_REQUIRED` | domain | No blockchain system is available for this organization. | The active organization has no indexed system on the selected network, so the requested system-backed profile or operation does not exist there. | Deploy the organization system or select a network where its system is indexed, then retry. | info | No | 404 |
| DALP-9441 | `BLOCKCHAIN_AUTHORIZATION_DEPENDENCY_FAILED` | dependency | Blockchain authorization state is unavailable. | The platform could not load the indexed wallet or account-abstraction state needed to authorize the request. | Retry after the database projections recover. If the failure continues, contact support with the request id. | error | Yes | 503 |
| DALP-9460 | `CONVERSION_WINDOW_NOT_OPEN` | domain | The conversion window has not opened. | The chain timestamp is before the configured conversion start. | Submit the conversion after windowStart. Check the window returned by the conversion feature. | info | Yes | 409 |
| DALP-9461 | `CONVERSION_WINDOW_CLOSED` | domain | The conversion window has closed. | The chain timestamp is after the configured conversion end. | Ask the issuer to review the conversion window; retrying the same request cannot reopen it. | info | No | 409 |
| DALP-9462 | `TOKEN_FEATURE_ALREADY_ATTACHED` | domain | This feature, or one it conflicts with, is already attached. | `{{featureName}}` is already attached to this token, or it cannot be combined with `{{conflictingFeatureName}}`, which is attached. | If `{{featureName}}` is already attached, nothing is left to do. Otherwise detach `{{conflictingFeatureName}}`, or choose a feature that can be combined with `{{featureName}}`. | info | No | 409 |
| DALP-9463 | `TOKEN_FEATURE_CONVERSION_INCOMPATIBLE` | domain | The yield feature conflicts with conversion accounting. | The conversion debt method leaves retired principal in holder balances, so this yield feature would pay against retired principal. | Use a token design whose conversion retires principal through burn or lock before adding this yield feature. | info | No | 409 |
| DALP-9464 | `TOKEN_FEATURE_CONVERSION_PROVIDER_UNRESOLVABLE` | domain | Conversion cannot select one interest provider. | Attaching this feature would leave the immutable conversion configuration without one usable interest provider. | Choose a feature combination with exactly one interest provider supported by the conversion configuration. | info | No | 409 |
| DALP-9465 | `TOKEN_FEATURE_FACTORY_NOT_FOUND` | domain | The feature factory is not installed. | The active system has no factory for the requested token feature. | Install the feature factory on this system, then attach the feature. | info | No | 409 |
| DALP-9466 | `TOKEN_FEATURE_FEATURE_NOT_FOUND` | domain | The requested feature is not attached. | The token has no attached feature matching this operation. | Read the token features and attach the required feature before calling this operation. | info | No | 409 |
| DALP-9467 | `TOKEN_FEATURE_NAME_MISMATCH` | domain | The feature in the body does not match the feature in the path. | The request body names a different feature than the route path. | Send the same feature name in the path and the body. | info | No | 409 |
| DALP-9468 | `TOKEN_FEATURE_STALE_INDEX` | domain | The feature projection is behind the chain. | The indexed feature address does not match the feature currently attached on chain, or the dividend entitlement or proof for the acting wallet is not indexed yet. | Wait for the indexer to catch up, read the attached feature again, and retry. | info | Yes | 409 |
| DALP-9469 | `TOKEN_FEATURE_UNCHANGED_ADDRESS` | domain | The replacement feature address is unchanged. | The replacement configuration predicts the address the token already uses. | Keep the existing feature, or change the replacement configuration. | info | No | 409 |
| DALP-9470 | `FIXED_YIELD_OPERATION_ADDON_NOT_FOUND` | domain | The fixed-yield addon is not installed. | The active system has no fixed-yield addon for this operation. | Install the fixed-yield addon on this system before creating a schedule. | info | No | 409 |
| DALP-9471 | `FIXED_YIELD_OPERATION_DENOMINATION_ASSET_NOT_INDEXED` | domain | The yield denomination is not indexed. | The schedule denomination asset has no indexed token record. | Register the denomination asset and wait for its token projection before retrying. | info | Yes | 409 |
| DALP-9472 | `FIXED_YIELD_OPERATION_DENOMINATION_METADATA_NOT_INDEXED` | domain | Yield denomination metadata is missing. | The indexer has not recorded the denomination metadata needed to interpret payout amounts. | Restore denomination metadata indexing, then retry; do not assume token decimals. | info | Yes | 409 |
| DALP-9473 | `FIXED_YIELD_OPERATION_DEPLOYMENT_NOT_INDEXED` | domain | The fixed-yield deployment is not indexed. | The deployed fixed-yield contract has no corresponding indexed deployment state. | Check the deployment transaction and restore indexer progress before retrying. | info | Yes | 409 |
| DALP-9474 | `FIXED_YIELD_OPERATION_SCHEDULE_NOT_FOUND` | domain | The yield schedule was not found. | The requested schedule is not available in the active system. | Use a schedule returned by this system and verify its address and network. | info | No | 409 |
| DALP-9475 | `FIXED_YIELD_OPERATION_SYSTEM_MISMATCH` | domain | The yield schedule belongs to another token. | The schedule is not linked to the token named in the request. | Use the schedule linked to this token. | info | No | 409 |
| DALP-9476 | `FIXED_YIELD_OPERATION_TOKEN_LINKAGE_NOT_INDEXED` | domain | The schedule token link is not indexed. | The indexer has not linked the yield schedule to its token. | Check the schedule creation transaction and restore indexing before retrying. | info | Yes | 409 |
| DALP-9477 | `MATURITY_STATE_NOT_INDEXED` | operational | Maturity state is not indexed. | The maturity feature state required for this operation is absent from the index. | Check the feature deployment and restore indexer progress before retrying. | info | Yes | 503 |
| DALP-9478 | `MATURITY_NOT_MATURED` | domain | The token has not matured. | Neither indexed nor live chain state marks the token as matured. | Call the maturity operation when the token is eligible, then redeem. Check maturityDate in this response. | info | No | 409 |
| DALP-9479 | `MATURITY_TREASURY_UNCLASSIFIED` | operational | The maturity treasury has not been classified. | The indexer has not determined whether the configured treasury is a wallet or a contract. | Restore treasury classification indexing before redeeming. | info | Yes | 503 |
| DALP-9480 | `MATURITY_TREASURY_WALLET_MISMATCH` | domain | The selected wallet is not the maturity treasury. | This allowance must be approved by the configured treasury wallet. | Select the treasury address returned in this response, then approve the allowance. | info | No | 409 |
| DALP-9481 | `MATURITY_INSUFFICIENT_ALLOWANCE` | domain | The maturity treasury allowance is too small. | The treasury approved `{{allowance}}` denomination base units; this redemption requires `{{required}}`. | Ask the issuer to have the maturity treasury approve at least the required amount for the maturity feature, then retry. | info | No | 409 |
| DALP-9482 | `TOKEN_MUTATION_INSUFFICIENT_BALANCE` | domain | The holder has insufficient available tokens. | The `{{operation}}` requests `{{requested}}` base units from `{{holderAddress}}`, but only `{{available}}` are available. | Reduce the amount to the holder's available balance, or fund the holder, then retry. | info | No | 409 |
| DALP-9483 | `TOKEN_SUPPLY_PAUSED` | domain | Token supply changes are paused. | The token is paused, which prevents this `{{operation}}`. | Have an authorized operator unpause the token before changing its supply. | info | No | 409 |
| DALP-9484 | `TOKEN_MINT_AMOUNT_INVALID` | domain | Mint amounts must be positive. | At least one recipient has a mint amount of zero. | Provide a positive base-unit amount for every recipient. | info | No | 400 |
| DALP-9485 | `TOKEN_ACCESS_UNAUTHORIZED` | permission | The account running this action lacks the asset role it needs. | Only an account that holds the asset role this action needs can run it on this asset. | Ask an asset administrator to grant the role on the asset's Permissions tab, or run the action from an account that already holds it. | info | No | 403 |
| DALP-9486 | `TOKEN_DOCUMENTS_READ_DOCUMENT_NOT_FOUND` | domain | The token document was not found. | No document matching the requested identifier is available on this token. | Use a document identifier returned by the token document list. | info | No | 404 |
| DALP-9487 | `CONVERSION_INTEREST_NOT_CONVERTIBLE` | domain | The holder has no convertible interest to convert. | The conversion feature has no interest provider, or the holder has no unsettled convertible interest on it. | Convert principal instead, or submit the interest conversion after interest accrues to the holder. | info | No | 409 |
| DALP-9488 | `TOKEN_PAUSE_STATE_UNCHANGED` | domain | The token is already in the requested pause state. | The request would set the pause state of `{{tokenAddress}}` to a state it already has, so nothing would change. | Read the token's pause state again. Pause an active token or unpause a paused one; there is nothing to do when it already matches. | info | No | 409 |
| DALP-9495 | `TOKEN_PERMIT_DEADLINE_EXPIRED` | domain | The permit deadline has passed. | The signed permit deadline is earlier than the current chain time. | Create and sign a new permit with a future deadline. | info | No | 422 |
| DALP-9496 | `TOKEN_PERMIT_WALLET_UNAVAILABLE` | domain | No permit signing wallet is available. | The active organization and chain have no executor wallet available for this permit operation. | Configure an executor wallet for this organization and chain, then retry. | info | No | 409 |
| DALP-9497 | `TOKEN_PERMIT_NOT_FOUND` | domain | The signed permit was not found. | No signed permit matches this organization, chain, token, and permit identifier. | Use an identifier returned by the permit signing route, or sign a new permit. | info | No | 404 |
| DALP-9498 | `TOKEN_PERMIT_ALREADY_RELAYED` | domain | The permit was already relayed. | This signed permit was already submitted to the chain. | Read the permit and its transaction result instead of relaying it again. | info | No | 409 |
| DALP-9499 | `TOKEN_PERMIT_NOT_RELAYABLE` | domain | The permit cannot be relayed. | The signed permit is not pending in a state that accepts relay. | Read the permit state. Sign a new permit if the stored permit expired or was already consumed. | info | No | 409 |

The previous page is [DALP-9300 to DALP-9399](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference/dalp-9300-9399). The next page is [DALP-9500 to DALP-9999](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference/dalp-9500-9999).


# DALP-9500 to DALP-9999

Source: https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference/dalp-9500-9999
Cause, fix, HTTP status and retry flag for every Platform API error with a code from DALP-9500 to DALP-9999.

This page lists the 56 errors the Platform API can return with a code from DALP-9500 to DALP-9999. Match the `id` in the error envelope to the DALP Code column, then read Retryable and Suggested Fix. The [Platform API error reference](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference#how-to-use-this-reference) explains each column, including Severity, and the [DALP error index](https://docs.settlemint.com/docs/api-reference/errors) lists the page for every code range.

| DALP Code | Machine name | Category | Message | Why | Suggested Fix | Severity | Retryable | HTTP Status |
| --- | --- | --- | --- | --- | --- | --- | --- | --- |
| DALP-9500 | `TOKEN_PERMIT_NONCE_CONFLICT` | domain | The permit nonce changed. | Another permit reserved the next nonce for this owner before this request could store its signature. | Retry the signing request so the platform can allocate the next available permit nonce. | info | Yes | 409 |
| DALP-9501 | `TOKEN_PERMIT_FEATURE_UNAVAILABLE` | operational | The permit feature is unavailable. | The permit feature state has not finished indexing, or its declared signing domain does not match the indexed one. | Wait for the permit feature state to finish indexing, then retry. | info | Yes | 503 |
| DALP-9502 | `TOKEN_PERMIT_SIGNING_FAILED` | dependency | The permit signature could not be produced. | The configured custody signer did not complete the permit signing request, or a chain read the signing needs failed. | Restore the custody signer, then retry. | error | Yes | 503 |
| DALP-9505 | `TOKEN_PERMIT_PERSISTENCE_FAILED` | dependency | Permit storage is unavailable. | The platform could not read or save the permit state required by this operation. | Restore permit storage, then retry without changing the request scope. | error | Yes | 503 |
| DALP-9506 | `TOKEN_AMOUNT_DENOMINATION_UNAVAILABLE` | dependency | The token denomination is not indexed. | The symbol and decimals needed to encode the submitted amount are not indexed for the token yet. | Wait for the token symbol and decimals to be indexed, then retry with the same idempotency key. | error | Yes | 503 |
| DALP-9510 | `CLAIM_TOPIC_ALREADY_EXISTS` | domain | A claim topic with this name already exists. | A claim topic with this name is already registered in the active system. | Use the existing topic, or choose a different name. | info | No | 409 |
| DALP-9518 | `FEED_TOPIC_CONFLICT` | client | Topic name `{topicName}` does not match topic id `{topicId}`. | The request supplied both a topic name and a topic id, and the id computed from the name differs from the id given. | Use the computed topic id or submit only one topic identifier. | info | No | 409 |
| DALP-9519 | `FEED_CONTRACT_INVALID` | client | Contract `{feedAddress}` does not expose the feed interface. | The contract at the given address did not answer the required feed interface on the selected chain. | Verify the feed address and confirm the contract is deployed on the selected chain. | info | No | 422 |
| DALP-9523 | `ADMINISTRATOR_REQUIRED` | permission | A global platform administrator is required. | The authenticated user is not a global platform administrator. | Authenticate as a global platform administrator and retry the request. | info | No | 403 |
| DALP-9524 | `REQUEST_CHAIN_SYSTEM_REQUIRED` | domain | The organization has no deployed system on chain `{chainId}`. | The active organisation has no deployed system on the network the request selected: the `X-Chain-Id` network, or the organisation's default network. | Deploy the organization system before using system-scoped APIs. | info | No | 404 |
| DALP-9525 | `FINANCIAL_YIELD_OPERATION_REJECTED` | domain | The dividend operation for `{dividendId}` could not be completed. | `data.reason` names the dividend state that refused the operation: the dividend or its snapshot is not indexed, computed or final yet, the snapshot is already recorded, or the confirmation does not match the computed snapshot. | Read `data.reason`. For `dividend-not-indexed`, `snapshot-not-computed` or `snapshot-awaiting-finality`, wait and send the same request again. For `snapshot-already-recorded`, nothing is left to do. For `snapshot-confirmation-mismatch`, preview the current snapshot and confirm or approve it again. | error | Yes | 503 |
| DALP-9526 | `TRANSACTION_QUEUE_DEAD_LETTER` | dependency | The transaction queue stopped work on this transaction before it settled. | The transaction queue moved the transaction to `DEAD_LETTER`: its retries ran out, or the chain or the custody provider gave no answer, before the transaction settled. A call that was broadcast, or filed with a custody provider, can still land on the chain after this answer. | Do not submit the transaction again until it settles. Read the transaction request with its transaction id. Submit again with a new idempotency key only when that read shows `mayStillLand: false`; a read without that key gives no permission. If the transaction never settles, give the transaction id to an Organisation owner, an Organisation admin or a Platform admin. Any of them can force-fail it with `POST /api/v2/transaction-requests/{transactionId}/transitions` and `action: "fail"`; an Organisation owner or a Platform admin can also force-fail it in the Console under Organisation settings, Platform status. | error | No | 422 |
| DALP-9531 | `ASSET_SORT_FAMILY_MISMATCH` | client | Sort names a column the asset's chain family cannot order on. | The holdings collection under one asset advertises both chain families' sort keys, and the asset decides which family answers. The sort names a column that family cannot order on. The refusal names the field, the family, and the columns that family can be ordered on. | Sort the holdings on a column the named family can be ordered on, omit `sort` to take that family's own ordering, or read the asset in the family whose column you are sorting on. | info | No | 400 |
| DALP-9532 | `REQUEST_DEADLINE_EXCEEDED` | operational | The request deadline expired. | The request ran past the deadline the platform gives one request, so the platform stopped the work. The operation that request started may still be running. | Check the status of the operation before you submit the request again, and let the Retry-After interval pass first. | warning | No | 504 |
| DALP-9534 | `SYSTEM_TRUSTED_ISSUER_ID_INVALID` | client | The issuer identifier and the request body name different chain families. | A trusted issuer is named by an address on one family and by a party id on the other, and this request mixed them: the `issuerId` segment and the body must describe the same family. The platform submitted no command and changed nothing. | Send the identifier that matches the body, or send the body that matches the identifier, then retry. | info | No | 400 |
| DALP-9540 | `APPROVAL_NOT_FOUND` | client | Approval request was not found. | No approval request exists under this identifier in the calling organization. | Read the approvals list for the current identifier and state, then decide again. | info | No | 404 |
| DALP-9541 | `APPROVAL_REFUSED` | domain | The approval decision was refused. | The platform's maker-checker rules and the policy version the request was raised under decide who may approve and whether the decision is still valid. The maker cannot approve their own request. A role the pinned policy does not name cannot approve. A signature that leaves the policy's approver floor short is recorded against the request rather than admitting it. A borrowed session cannot approve when the pinned policy sets `operatorMayApprove` to false. A payload that moved invalidates the approval. An expired request accepts no decision. A policy that names no approving role admits any role the platform has already admitted as an approver. A request already decided accepts no second decision. A decision that lost a race to another writer is refused. | Read the request again for its current state and row version, and have a distinct operator decide it. | info | No | 409 |
| DALP-9542 | `OPERATIONS_CASE_NOT_FOUND` | client | Operations case was not found. | No operations case exists under this identifier in the calling organization. | List the cases with `GET /api/v2/operations/cases`, then acknowledge the case with the `caseId` from the list. | info | No | 404 |
| DALP-9543 | `OPERATIONS_CASE_REFUSED` | domain | The operations case refused this acknowledgement or resolution. | A case that lapsed, that somebody already resolved or acknowledged, or whose row version moved under the caller accepts no acknowledgement or resolution. The `reason` field names which: `already-resolved`, `already-acknowledged`, `expired` or `row-version-moved`. | Read the cases list again for the current state and row version. Repeat the call only when `reason` is `row-version-moved`; a case in any other state accepts no further acknowledgement or resolution. | info | No | 409 |
| DALP-9546 | `ADMIN_MUTATION_POLICY_GROUP_UNKNOWN` | client | The administrative mutation policy names an unknown protection group. | Every routeGroups entry must be one of the published protection groups, because a name that matches no route would silently protect nothing. | Send only the protection groups the policy field lists, or use the standard preset. | info | No | 422 |
| DALP-9547 | `ADMIN_MUTATION_ALREADY_HELD` | domain | An identical change is already held for approval. | Another user already submitted exactly this administrative change and it waits for a second user. Holding a second copy would let two requests run the same change. | Read the held approval named in the organisation's approvals inbox and have a second user decide it, or submit a different change. | info | No | 409 |
| DALP-9561 | `WEBHOOK_SYSTEM_SCOPE_REQUIRED` | permission | Webhook request has no deployed system. | The request resolved no deployed system for the endpoint to subscribe to. | Reissue the request under a system the active tenant has deployed. | info | No | 404 |
| DALP-9563 | `TOKEN_CREATE_COMPLIANCE_MODULE_INCOMPATIBLE` | client | V1 compliance modules cannot be installed on a v2 asset: `{modules}`. `{remedies}`. | A DALP asset is a v2 token. A v1 compliance module looks for the older token interface, which a v2 token does not report, so it would reject every mint. `data.typeIds` lists the v1 modules in the request, and `data.remedies` names the v2 module that replaces each one. | Replace each module in `data.typeIds` with its `-v2` module, for example `collateral-v2` instead of `collateral`. A module without a v2 version cannot be used on a DALP asset yet; remove it from `initialModulePairs`. | info | No | 400 |
| DALP-9564 | `TOKEN_COMPLIANCE_MODULE_GENERATION_INCOMPATIBLE` | client | V1 compliance modules cannot be installed on a v2 asset: `{modules}`. `{remedies}`. | A DALP asset is a v2 token. A v1 compliance module looks for the older token interface, which a v2 token does not report, so once installed it would reject every mint. `data.typeIds` lists the v1 module in the request, and `data.remedies` names the v2 module that replaces it. | Install the `-v2` module instead, for example `collateral-v2` instead of `collateral`. A module without a v2 version cannot be installed on a DALP asset yet. | info | No | 400 |
| DALP-9565 | `COLLECTION_PAGE_CURSOR_MISMATCH` | client | The page cursor does not belong to this query. | A page cursor is only valid for the sort and filters of the request that returned it. This cursor was issued for a different sort or filter, or it was altered. | Send the `meta.nextCursor` from the previous page together with the same `sort` and filters, or start again without `page[cursor]`. | info | No | 400 |
| DALP-9590 | `TOKEN_ADDRESS_RESTRICTION_ACTIVE` | domain | An active wallet restriction holds this address frozen. | Wallet restriction `{{restrictionId}}` froze `{{holderAddress}}` on `{{tokenAddress}}` and is still active, so unblocking the address on this one token would undo the restriction's freeze. | Lift the wallet restriction instead. That unblocks the address on every token the restriction covers and records who lifted it. | info | No | 409 |
| DALP-9701 | `ESCROW_NOT_FOUND` | client | The escrow was not found. | The address names no escrow created by your organisation's escrow factory, or your role cannot read escrows. | Use an escrow address from the escrows list, signed in as an organisation owner or platform administrator. | info | No | 404 |
| DALP-9702 | `ESCROW_FORCED_TRANSFER_REFUSED` | client | The forced transfer was refused. | The forced transfer breaks a lock rule, or the escrow or the transaction queue refused it. A listed lock must be an open lock of the owner, and the amount must be greater than zero and within the owner's free balance and listed locks. The amount draws on the owner's free balance first, and only the remainder draws on the listed locks. Paid units go only to the rail wallet, and unpaid units go only back to their owner. A lock whose cash-out the bank may still pay cannot move. A lock that backs an unpaid cash-out cannot move while its rail wallet has no open compromised rotation. | Check the listed locks and the amount against the owner's escrow balance. Return unpaid units to their owner, send paid units to the rail wallet, and retry a cash-out still at the bank once the bank reports. | info | No | 409 |
| DALP-9703 | `ESCROW_CUSTODIAN_REQUIRED` | client | Only a token custodian can force a transfer out of an escrow. | Your wallet does not hold the custodian role on the token, or the token is not one of this organisation's. | Ask a token administrator to grant your wallet the custodian role, then retry. | info | No | 403 |
| DALP-9810 | `REQUEST_CHAIN_SCOPE_CONFLICT` | client | The request names one chain family and reads another. | A shared asset route answers for an EVM token or a Canton instrument, and the request settles which one in more than one place: the X-Chain-Id or X-Network-Id header, `filter[family]`, `instrumentAdmin`, or the route itself. Two of them disagree, or the route serves only the other family, so there is no single family to answer from. The message names the conflict. | Send one family consistently: drop the header or filter that names the other family, or read a Canton instrument with its `instrumentAdmin` on a route that serves Canton instruments. | info | No | 400 |
| DALP-9813 | `GATEWAY_ADDON_NOT_DEPLOYED` | client | The custody gateway add-on is not deployed. | The organisation's system on this network has no custody gateway add-on, or its access manager is not indexed yet. | Deploy the custody gateway add-on on this network, then read it again. | info | No | 404 |
| DALP-9814 | `GATEWAY_NOT_FOUND` | client | The custody gateway was not found. | No gateway of this add-on is indexed at this address, or none serves the wallet you act with. | List the gateways of the add-on and use one of their addresses. | info | No | 404 |
| DALP-9815 | `GATEWAY_TOKEN_ALREADY_ENABLED` | client | The coin is already enabled. | The coin is already enabled on the custody gateway add-on. | List the enabled coins; to change a coin's behaviour, change its defaults. | info | No | 409 |
| DALP-9816 | `GATEWAY_PROFILE_NOT_FOUND` | client | The gateway profile was not found. | No profile with this id exists on the add-on. | List the profiles of the add-on and use one of their ids. | info | No | 404 |
| DALP-9817 | `GATEWAY_PROFILE_IN_USE` | client | The gateway profile is in use. | At least one gateway is assigned to this profile. | Move or retire the gateways of this profile before removing it. | info | No | 409 |
| DALP-9818 | `GATEWAY_ALREADY_EXISTS` | client | The client already has a gateway. | A gateway already exists for this client identity. | Read the existing gateway instead of creating another. | info | No | 409 |
| DALP-9819 | `GATEWAY_SETTING_REFUSED` | client | The gateway setting was refused. | A setting name is unknown or repeated, or its value does not fit the setting or is not greater than zero. The coin's `defaults` omit a required setting, or name a setting the coin cannot take when it is enabled. | Use a setting name the add-on knows once per request, with a value of the type the setting takes. | info | No | 422 |
| DALP-9820 | `GATEWAY_SIGNER_REFUSED` | client | The selected wallet cannot sign this gateway write. | The selected wallet is not an active signer that can send add-on writes on this network. | Select a wallet of the organisation that can sign on this network, then retry. | info | No | 409 |
| DALP-9821 | `GATEWAY_APPROVAL_REQUIRED` | client | The gateway change needs checker approval. | The add-on's checkers must approve this change before it can be sent. | Propose each listed call to the add-on's access manager, collect the approvals, then send the same request again. | info | No | 422 |
| DALP-9822 | `GATEWAY_CANNOT_WAIT_FOR_CUSTODY` | client | The coin cannot wait for custody. | The coin's custody receipt cannot hold deposits while the custodian confirms them. | Give the custody receipt the Hold feature with the gateway add-on as reserver, or leave waiting for custody off. | info | No | 422 |
| DALP-9823 | `GATEWAY_CUSTODY_DESTINATION_REFUSED` | client | Coins must go to a Fireblocks wallet to wait for custody. | Waiting for custody needs coins to go to a wallet of one of the organisation's Fireblocks custody providers. | Set coins-go-to to a Fireblocks wallet of the organisation, or turn waiting for custody off. | info | No | 422 |
| DALP-9824 | `GATEWAY_WRITE_REFUSED` | client | The gateway refused the change. | The add-on refuses this change in its current state, the gateway is closed, or the withdrawal leaves nothing after the fee. | Read `data.revert`, correct the request or the add-on's state, then send it again. | info | No | 422 |
| DALP-9825 | `GATEWAY_SIGNER_NOT_SET_UP` | client | The gateway signer is not set up. | The organisation has no keeper or screener wallet of this kind on this network. | Set up the signer first, then retry. | info | No | 404 |
| DALP-9826 | `GATEWAY_SIGNER_SET_UP_REFUSED` | client | The gateway signer could not be set up with this custody provider. | The custody provider configuration cannot hold a signing wallet for this organisation on this network. | Choose a custody provider configuration of the organisation that can sign on this network, then retry. | info | No | 422 |
| DALP-9827 | `GATEWAY_PAYOUT_NOT_APPROVED` | client | The payout address is not approved. | The payout address is not on the gateway's approved list, or it is suspended. | Ask a gateway manager to approve the address, or name an address that is approved. | info | No | 422 |
| DALP-9828 | `GATEWAY_RECEIPTS_UNAVAILABLE` | client | The wallet holds too few available receipts. | The wallet holds fewer receipts than requested once the receipts held for custody are set aside. | Request no more than the available receipts, or wait for the custodian to answer the held deposits. | info | No | 422 |
| DALP-9829 | `GATEWAY_RECORD_NOT_FOUND` | client | The gateway record was not found. | No deposit, withdrawal request or unsupported record of this gateway is indexed under this id. A receipt token that no coin of the add-on uses answers the same way. | List the gateway's records and use one of their ids. | info | No | 404 |
| DALP-9830 | `GATEWAY_PERMISSION_MANAGER_REQUIRED` | client | The wallet cannot change gateway roles. | Only a holder of the custody gateway permission manager role on the system grants or revokes gateway roles. | Act from a wallet that holds the custody gateway permission manager role, or ask a system administrator to grant it. | info | No | 422 |
| DALP-9831 | `GATEWAY_SIGNER_IN_USE` | client | DALP still signs gateway calls with this wallet. | DALP signs gateway calls with this wallet, so revoking its role here would leave the keeper or screener sending calls the gateway refuses. | Rotate the keeper or screener to a new signer wallet first, then revoke the role from this wallet. | info | No | 409 |
| DALP-9832 | `REGISTRY_UNAVAILABLE` | dependency | The custody provider's destination registry could not complete this step. | The custody provider that keeps its own withdrawal allow list did not register, read or remove this destination, so the platform cannot tell whether the destination is approved there. | Retry the step. The entry keeps the state it already had, and a withdrawal to a destination that is not active is refused in the meantime. | error | Yes | 503 |
| DALP-9833 | `GATEWAY_DEPOSIT_STATE_REFUSED` | client | The deposit is not in a stage that allows this transition. | The deposit is not in a stage that allows this transition. | Read the deposit's stage, then send a transition that stage allows. | info | No | 409 |
| DALP-9834 | `GATEWAY_WITHDRAWAL_STATE_REFUSED` | client | The withdrawal request is not in a stage that allows this transition. | The withdrawal request is not in a stage that allows this transition, or it no longer owes the review step this transition gives. | Read the request's stage, needsScreening and needsApproval, then send a transition they allow. | info | No | 409 |
| DALP-9835 | `GATEWAY_ROLE_REQUIRED` | client | Your wallet does not hold the role this transition needs. | This transition is signed by your own wallet, which does not hold the role the add-on requires for it. | Ask a gateway manager to grant your wallet the named role, then send the transition again. | info | No | 403 |
| DALP-9836 | `EXTERNAL_TOKEN_METADATA_TOO_LONG` | client | The token's name or symbol is longer than DALP registers. | DALP registers a token's name and symbol exactly as the chain reports them and never shortens them, so a token whose name exceeds 50 characters or whose symbol exceeds 24 is not registered. | Register a token whose name and symbol are within the limit. | info | No | 422 |
| DALP-9837 | `REGISTRY_REFUSED` | client | The custody provider's destination registry refused this step. | The custody provider that holds this destination's own allow list refused the request, or the provider configuration that registered the destination is no longer available, so the platform cannot confirm the destination there. | Check the destination and the custody provider configuration, then clear or revoke the entry once the provider reports it. Retrying the same step cannot succeed. | info | No | 409 |
| DALP-9838 | `ASSISTANT_PLAN_NOT_FOUND` | client | Plan not found. | No plan with that identifier was built by the caller in the active organisation. A plan another member built answers the same way, so the reply never confirms that it exists. A step index the plan does not have also answers with this error. | List the plans and use the identifier of a plan the caller built. | info | No | 404 |

The previous page is [DALP-9400 to DALP-9499](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference/dalp-9400-9499). The next page is [DALP-12000 to DALP-12099](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference/dalp-12000-12099).


# Platform API errors

Source: https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference
Cause, fix, HTTP status and retry flag for every catalogued Platform API error, by code range.

Match the `id` in a DALP API error, such as `DALP-12074`, to its row on the page for its code range. The row gives the HTTP status, the retry flag and the step that resolves the error. An `id` that is not on these pages is a [contract error](https://docs.settlemint.com/docs/api-reference/errors/error-code-reference), and a code that is a name, such as `DALP-WORKFLOW-FAILED`, is on [Codes without a number](https://docs.settlemint.com/docs/api-reference/errors/error-code-reference/unnumbered-codes).

On REST, the `id` is in `data.id` of the error envelope and the machine name is in `code`. The TypeScript SDK raises a `DalpApiError` with `id`, `code`, `category`, `retryable`, `message`, `why`, `fix` and `status`. A JSON-RPC error keeps JSON-RPC framing and carries the DALP fields, when present, in `error.data`. [Read and handle DALP errors](https://docs.settlemint.com/docs/api-reference/guides/errors) describes the envelope.

If an error tells you to contact support, include the request id from the API response or the logs. Do not send secrets, raw signatures, private keys, or unredacted identity documents. A compliance-provider error can need a check in the provider's own console.

## How to use this reference [#how-to-use-this-reference]

1. Open the page for the code range that holds the `id` in the error envelope, and match the `id` to its table row.
2. Check the HTTP status and the category to separate request problems from permission, domain, dependency, contract, and operational failures.
3. Use Retryable as the retry gate. `Yes` means the same request can succeed later without a change to the request, after indexing, dependency recovery, workflow completion, or a date passing. `No` means sending the same request again does not succeed until you act on the Suggested Fix, which can be to change the request, to get an approval, or to read the result of a write that already happened.
4. Follow the row's Suggested Fix. For a mutating operation, verify the current resource or transaction state before you retry, so the client does not submit the same operation twice.
5. Read Severity as a default for your own alerting. [Error handling](https://docs.settlemint.com/docs/api-reference/errors/error-handling#criticality-and-escalation) says who handles each level and when to escalate.

Each row's Machine name is the `code` in the envelope. Message is the headline, Why is the condition that failed, and Suggested Fix is the caller's next step. Do not parse the Message, Why or Suggested Fix columns in program logic, because their wording can change. Branch on the `id` together with the `retryable` flag and the HTTP status.

## Pages by code range [#pages-by-code-range]

- [DALP-0000 to DALP-0499](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference/dalp-0000-0499): 100 errors.
- [DALP-0500 to DALP-0599](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference/dalp-0500-0599): 27 errors.
- [DALP-0600 to DALP-0699](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference/dalp-0600-0699): 36 errors.
- [DALP-0700 to DALP-0799](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference/dalp-0700-0799): 38 errors.
- [DALP-9000 to DALP-9099](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference/dalp-9000-9099): 16 errors.
- [DALP-9100 to DALP-9199](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference/dalp-9100-9199): 22 errors.
- [DALP-9200 to DALP-9299](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference/dalp-9200-9299): 22 errors.
- [DALP-9300 to DALP-9399](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference/dalp-9300-9399): 19 errors.
- [DALP-9400 to DALP-9499](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference/dalp-9400-9499): 48 errors.
- [DALP-9500 to DALP-9999](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference/dalp-9500-9999): 56 errors.
- [DALP-12000 to DALP-12099](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference/dalp-12000-12099): 69 errors.
- [DALP-12100 to DALP-12199](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference/dalp-12100-12199): 51 errors.
- [DALP-12200 to DALP-12299](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference/dalp-12200-12299): 52 errors.
- [DALP-12300 to DALP-12399](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference/dalp-12300-12399): 78 errors.
- [DALP-12400 to DALP-12499](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference/dalp-12400-12499): 14 errors.
- [DALP-13000 to DALP-13999](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference/dalp-13000-13999): 2 errors.
- [DALP-14000 to DALP-14049](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference/dalp-14000-14049): 48 errors.
- [DALP-14050 to DALP-14099](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference/dalp-14050-14099): 50 errors.
- [DALP-14100 to DALP-14199](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference/dalp-14100-14199): 41 errors.
- [DALP-14200 to DALP-14299](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference/dalp-14200-14299): 64 errors.
- [DALP-14300 to DALP-14399](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference/dalp-14300-14399): 97 errors.
- [DALP-14400 to DALP-14499](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference/dalp-14400-14499): 36 errors.
- [DALP-14500 to DALP-14999](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference/dalp-14500-14999): 54 errors.
- [DALP-15000 to DALP-19999](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference/dalp-15000-19999): 18 errors.
- [DALP-20000 to DALP-29999](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference/dalp-20000-29999): 13 errors.
- [DALP-100000 to DALP-199999](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference/dalp-100000-199999): 58 errors.
- [DALP-200000 to DALP-299999](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference/dalp-200000-299999): 9 errors.

## Contents [#contents]

- [Client request errors](#client-request-errors): 420 errors.
- [Authentication errors](#authentication-errors): 20 errors.
- [Permission errors](#permission-errors): 68 errors.
- [Domain rule errors](#domain-rule-errors): 461 errors.
- [Operational errors](#operational-errors): 61 errors.
- [Dependency errors](#dependency-errors): 105 errors.
- [Contract errors surfaced at the API](#contract-errors-surfaced-at-the-api): 2 errors.
- [Unclassified errors](#unclassified-errors): 1 error.

## Client request errors [#client-request-errors]

The 420 errors in the `client` category are on these pages:

- [DALP-0000 to DALP-0499](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference/dalp-0000-0499): 44 errors.
- [DALP-0500 to DALP-0599](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference/dalp-0500-0599): 16 errors.
- [DALP-0600 to DALP-0699](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference/dalp-0600-0699): 19 errors.
- [DALP-0700 to DALP-0799](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference/dalp-0700-0799): 11 errors.
- [DALP-9000 to DALP-9099](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference/dalp-9000-9099): 6 errors.
- [DALP-9100 to DALP-9199](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference/dalp-9100-9199): 16 errors.
- [DALP-9200 to DALP-9299](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference/dalp-9200-9299): 13 errors.
- [DALP-9300 to DALP-9399](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference/dalp-9300-9399): 8 errors.
- [DALP-9400 to DALP-9499](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference/dalp-9400-9499): 5 errors.
- [DALP-9500 to DALP-9999](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference/dalp-9500-9999): 39 errors.
- [DALP-12000 to DALP-12099](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference/dalp-12000-12099): 16 errors.
- [DALP-12100 to DALP-12199](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference/dalp-12100-12199): 13 errors.
- [DALP-12200 to DALP-12299](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference/dalp-12200-12299): 17 errors.
- [DALP-12300 to DALP-12399](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference/dalp-12300-12399): 20 errors.
- [DALP-12400 to DALP-12499](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference/dalp-12400-12499): 4 errors.
- [DALP-13000 to DALP-13999](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference/dalp-13000-13999): 1 error.
- [DALP-14000 to DALP-14049](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference/dalp-14000-14049): 13 errors.
- [DALP-14050 to DALP-14099](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference/dalp-14050-14099): 14 errors.
- [DALP-14100 to DALP-14199](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference/dalp-14100-14199): 10 errors.
- [DALP-14200 to DALP-14299](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference/dalp-14200-14299): 24 errors.
- [DALP-14300 to DALP-14399](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference/dalp-14300-14399): 34 errors.
- [DALP-14400 to DALP-14499](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference/dalp-14400-14499): 9 errors.
- [DALP-14500 to DALP-14999](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference/dalp-14500-14999): 39 errors.
- [DALP-15000 to DALP-19999](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference/dalp-15000-19999): 7 errors.
- [DALP-20000 to DALP-29999](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference/dalp-20000-29999): 5 errors.
- [DALP-100000 to DALP-199999](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference/dalp-100000-199999): 16 errors.
- [DALP-200000 to DALP-299999](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference/dalp-200000-299999): 1 error.

## Authentication errors [#authentication-errors]

The 20 errors in the `auth` category are on these pages:

- [DALP-0000 to DALP-0499](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference/dalp-0000-0499): 7 errors.
- [DALP-0500 to DALP-0599](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference/dalp-0500-0599): 1 error.
- [DALP-0600 to DALP-0699](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference/dalp-0600-0699): 1 error.
- [DALP-9000 to DALP-9099](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference/dalp-9000-9099): 1 error.
- [DALP-9100 to DALP-9199](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference/dalp-9100-9199): 1 error.
- [DALP-9400 to DALP-9499](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference/dalp-9400-9499): 1 error.
- [DALP-12000 to DALP-12099](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference/dalp-12000-12099): 1 error.
- [DALP-12200 to DALP-12299](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference/dalp-12200-12299): 2 errors.
- [DALP-14200 to DALP-14299](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference/dalp-14200-14299): 1 error.
- [DALP-14300 to DALP-14399](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference/dalp-14300-14399): 1 error.
- [DALP-100000 to DALP-199999](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference/dalp-100000-199999): 1 error.
- [DALP-200000 to DALP-299999](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference/dalp-200000-299999): 2 errors.

## Permission errors [#permission-errors]

The 68 errors in the `permission` category are on these pages:

- [DALP-0000 to DALP-0499](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference/dalp-0000-0499): 8 errors.
- [DALP-0500 to DALP-0599](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference/dalp-0500-0599): 1 error.
- [DALP-0600 to DALP-0699](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference/dalp-0600-0699): 1 error.
- [DALP-0700 to DALP-0799](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference/dalp-0700-0799): 4 errors.
- [DALP-9000 to DALP-9099](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference/dalp-9000-9099): 2 errors.
- [DALP-9100 to DALP-9199](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference/dalp-9100-9199): 2 errors.
- [DALP-9300 to DALP-9399](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference/dalp-9300-9399): 2 errors.
- [DALP-9400 to DALP-9499](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference/dalp-9400-9499): 2 errors.
- [DALP-9500 to DALP-9999](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference/dalp-9500-9999): 2 errors.
- [DALP-12000 to DALP-12099](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference/dalp-12000-12099): 3 errors.
- [DALP-12100 to DALP-12199](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference/dalp-12100-12199): 2 errors.
- [DALP-12200 to DALP-12299](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference/dalp-12200-12299): 11 errors.
- [DALP-12300 to DALP-12399](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference/dalp-12300-12399): 2 errors.
- [DALP-12400 to DALP-12499](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference/dalp-12400-12499): 2 errors.
- [DALP-14000 to DALP-14049](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference/dalp-14000-14049): 2 errors.
- [DALP-14100 to DALP-14199](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference/dalp-14100-14199): 1 error.
- [DALP-14200 to DALP-14299](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference/dalp-14200-14299): 7 errors.
- [DALP-14300 to DALP-14399](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference/dalp-14300-14399): 2 errors.
- [DALP-14400 to DALP-14499](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference/dalp-14400-14499): 4 errors.
- [DALP-14500 to DALP-14999](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference/dalp-14500-14999): 4 errors.
- [DALP-15000 to DALP-19999](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference/dalp-15000-19999): 2 errors.
- [DALP-100000 to DALP-199999](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference/dalp-100000-199999): 2 errors.

## Domain rule errors [#domain-rule-errors]

The 461 errors in the `domain` category are on these pages:

- [DALP-0000 to DALP-0499](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference/dalp-0000-0499): 18 errors.
- [DALP-0500 to DALP-0599](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference/dalp-0500-0599): 7 errors.
- [DALP-0600 to DALP-0699](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference/dalp-0600-0699): 11 errors.
- [DALP-0700 to DALP-0799](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference/dalp-0700-0799): 19 errors.
- [DALP-9000 to DALP-9099](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference/dalp-9000-9099): 3 errors.
- [DALP-9100 to DALP-9199](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference/dalp-9100-9199): 2 errors.
- [DALP-9200 to DALP-9299](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference/dalp-9200-9299): 2 errors.
- [DALP-9300 to DALP-9399](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference/dalp-9300-9399): 7 errors.
- [DALP-9400 to DALP-9499](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference/dalp-9400-9499): 35 errors.
- [DALP-9500 to DALP-9999](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference/dalp-9500-9999): 8 errors.
- [DALP-12000 to DALP-12099](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference/dalp-12000-12099): 36 errors.
- [DALP-12100 to DALP-12199](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference/dalp-12100-12199): 23 errors.
- [DALP-12200 to DALP-12299](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference/dalp-12200-12299): 10 errors.
- [DALP-12300 to DALP-12399](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference/dalp-12300-12399): 23 errors.
- [DALP-12400 to DALP-12499](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference/dalp-12400-12499): 6 errors.
- [DALP-14000 to DALP-14049](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference/dalp-14000-14049): 27 errors.
- [DALP-14050 to DALP-14099](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference/dalp-14050-14099): 26 errors.
- [DALP-14100 to DALP-14199](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference/dalp-14100-14199): 25 errors.
- [DALP-14200 to DALP-14299](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference/dalp-14200-14299): 24 errors.
- [DALP-14300 to DALP-14399](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference/dalp-14300-14399): 59 errors.
- [DALP-14400 to DALP-14499](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference/dalp-14400-14499): 22 errors.
- [DALP-14500 to DALP-14999](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference/dalp-14500-14999): 9 errors.
- [DALP-15000 to DALP-19999](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference/dalp-15000-19999): 7 errors.
- [DALP-20000 to DALP-29999](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference/dalp-20000-29999): 7 errors.
- [DALP-100000 to DALP-199999](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference/dalp-100000-199999): 39 errors.
- [DALP-200000 to DALP-299999](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference/dalp-200000-299999): 6 errors.

## Operational errors [#operational-errors]

The 61 errors in the `operational` category are on these pages:

- [DALP-0000 to DALP-0499](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference/dalp-0000-0499): 5 errors.
- [DALP-0600 to DALP-0699](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference/dalp-0600-0699): 2 errors.
- [DALP-9000 to DALP-9099](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference/dalp-9000-9099): 1 error.
- [DALP-9400 to DALP-9499](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference/dalp-9400-9499): 4 errors.
- [DALP-9500 to DALP-9999](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference/dalp-9500-9999): 2 errors.
- [DALP-12000 to DALP-12099](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference/dalp-12000-12099): 9 errors.
- [DALP-12100 to DALP-12199](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference/dalp-12100-12199): 3 errors.
- [DALP-12200 to DALP-12299](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference/dalp-12200-12299): 3 errors.
- [DALP-12300 to DALP-12399](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference/dalp-12300-12399): 9 errors.
- [DALP-14000 to DALP-14049](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference/dalp-14000-14049): 5 errors.
- [DALP-14050 to DALP-14099](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference/dalp-14050-14099): 9 errors.
- [DALP-14100 to DALP-14199](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference/dalp-14100-14199): 4 errors.
- [DALP-14200 to DALP-14299](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference/dalp-14200-14299): 2 errors.
- [DALP-14500 to DALP-14999](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference/dalp-14500-14999): 1 error.
- [DALP-15000 to DALP-19999](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference/dalp-15000-19999): 1 error.
- [DALP-20000 to DALP-29999](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference/dalp-20000-29999): 1 error.

## Dependency errors [#dependency-errors]

The 105 errors in the `dependency` category are on these pages:

- [DALP-0000 to DALP-0499](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference/dalp-0000-0499): 17 errors.
- [DALP-0500 to DALP-0599](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference/dalp-0500-0599): 2 errors.
- [DALP-0600 to DALP-0699](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference/dalp-0600-0699): 2 errors.
- [DALP-0700 to DALP-0799](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference/dalp-0700-0799): 4 errors.
- [DALP-9000 to DALP-9099](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference/dalp-9000-9099): 3 errors.
- [DALP-9100 to DALP-9199](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference/dalp-9100-9199): 1 error.
- [DALP-9200 to DALP-9299](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference/dalp-9200-9299): 7 errors.
- [DALP-9300 to DALP-9399](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference/dalp-9300-9399): 2 errors.
- [DALP-9400 to DALP-9499](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference/dalp-9400-9499): 1 error.
- [DALP-9500 to DALP-9999](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference/dalp-9500-9999): 5 errors.
- [DALP-12000 to DALP-12099](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference/dalp-12000-12099): 4 errors.
- [DALP-12100 to DALP-12199](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference/dalp-12100-12199): 10 errors.
- [DALP-12200 to DALP-12299](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference/dalp-12200-12299): 9 errors.
- [DALP-12300 to DALP-12399](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference/dalp-12300-12399): 23 errors.
- [DALP-12400 to DALP-12499](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference/dalp-12400-12499): 1 error.
- [DALP-13000 to DALP-13999](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference/dalp-13000-13999): 1 error.
- [DALP-14000 to DALP-14049](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference/dalp-14000-14049): 1 error.
- [DALP-14050 to DALP-14099](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference/dalp-14050-14099): 1 error.
- [DALP-14100 to DALP-14199](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference/dalp-14100-14199): 1 error.
- [DALP-14200 to DALP-14299](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference/dalp-14200-14299): 6 errors.
- [DALP-14300 to DALP-14399](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference/dalp-14300-14399): 1 error.
- [DALP-14400 to DALP-14499](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference/dalp-14400-14499): 1 error.
- [DALP-14500 to DALP-14999](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference/dalp-14500-14999): 1 error.
- [DALP-15000 to DALP-19999](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference/dalp-15000-19999): 1 error.

## Contract errors surfaced at the API [#contract-errors-surfaced-at-the-api]

The 2 errors in the `contract` category are on these pages:

- [DALP-12300 to DALP-12399](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference/dalp-12300-12399): 1 error.
- [DALP-12400 to DALP-12499](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference/dalp-12400-12499): 1 error.

## Unclassified errors [#unclassified-errors]

The 1 error in the `unknown` category is on this page:

- [DALP-0000 to DALP-0499](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference/dalp-0000-0499): 1 error.


# Accounting feed

Source: https://docs.settlemint.com/docs/api-reference/guides/accounting-feed
How DALP posts money events to an organisation's Xero ledger, how to connect Xero, the posting records and cases, and the rules a custom subscriber follows.

## Overview [#overview]

DALP posts an organisation's final money events to that organisation's Xero ledger. A background job turns each event the organisation's rule table maps, such as a trade settlement, a fee, a bank rail credit or cash-out, a paid dividend or the reversal of one of these, into a balanced Xero manual journal. It posts each journal once and keeps a posting record of what happened to every event.

The same events reach every webhook endpoint the organisation registers. An organisation that keeps its books in another ledger, or that wants its own posting logic, runs a subscriber that receives the signed feed and follows the rules on this page. For endpoint registration and the signature scheme in full, see [Receive DALP webhooks](https://docs.settlemint.com/docs/api-reference/guides/webhooks).

**What stays with the organisation.** DALP never chooses accounts. The rule table, the chart-of-accounts mapping, the posting policy and the Xero organisation to post to are the organisation's own configuration. DALP posts nothing until the organisation stores that configuration and connects its own Xero app. Xero is the only ledger DALP posts to.

## How DALP posts to Xero [#how-dalp-posts-to-xero]

A job that runs once a minute across the deployment reads the organisation's committed events. The platform writes each committed event in the same database transaction as the change it describes, before any webhook delivery. The job needs no webhook endpoint, so an endpoint that is switched off or failing does not hold posting back.

For each event, the job does four things:

1. It copies the event into a posting record, from the creation of the organisation's first stored configuration version onwards. Earlier events are never posted.
2. It decides the event with the rule table of the newest configuration version, as [From event to journal](#from-event-to-journal) describes.
3. It maps the journal's account keys to the Xero account codes in the configuration, checks the journal against the Xero organisation's base currency, and posts it as one manual journal with status `POSTED` and no tax.
4. It records the Xero journal id and the Xero organisation on the posting record.

A journal reaches Xero at most once for each record, across retries, crashes and configuration changes. Each DALP journal carries a narration marker built from the organisation and the event's `source_id`, and DALP sends Xero an idempotency key built the same way. Before DALP sends a journal again, it looks the marker up in Xero, and it records a journal Xero already accepted instead of posting a second one. Once a request may have reached Xero, every later attempt sends exactly that request to the same Xero organisation, even after a configuration change.

Do not edit or delete the narration of a DALP journal in Xero, because DALP finds its journals by it. A correction is a new journal, never an edit of a posted one.

The job works through one organisation after another and posts one record at a time for each organisation.

## Connect Xero [#connect-xero]

Each organisation connects its own Xero app, so the deployment holds no shared Xero credentials. An organisation administrator who holds the `webhook:manage` permission connects it while signed in to the Console. An API key cannot connect, read or disconnect Xero.

1. Create a web app for the organisation in the Xero developer portal, and note its client id and client secret.
2. From a signed-in Console session, send them to `POST /api/v2/accounting/xero/connection`.
3. Add the `redirectUri` that DALP returns to the Xero app's redirect URIs, exactly as returned. It is the Console address followed by `/api/v2/accounting/xero/callback`.
4. Within ten minutes, open `authorizeUrl` in the same browser and consent at Xero for the Xero organisation that holds the books.
5. Xero returns the browser to DALP. DALP completes the connection and redirects to `/org-settings/accounting?xero=<outcome>` on the Console.
6. Read the connection with `GET /api/v2/accounting/xero/connection`, then [store a posting configuration](#store-a-posting-configuration) whose `mapping.xeroTenantId` is one of its `tenantIds`.

The connect request carries the Xero app's credentials. The values below are illustrative:

```http
POST /api/v2/accounting/xero/connection
Content-Type: application/json

{
  "clientId": "6F1C9A2B4D7E40A8B3C5D9E1F2A4B6C8",
  "clientSecret": "<the Xero app's client secret>"
}
```

DALP answers with the Xero consent URL and the redirect URI. It never returns the client secret:

```json
{
  "authorizeUrl": "<Xero consent URL carrying the client id, the redirect URI, the three scopes and a single-use state>",
  "redirectUri": "https://your-instance.example.com/api/v2/accounting/xero/callback"
}
```

DALP asks Xero for four scopes. `offline_access` keeps the connection alive, `accounting.manualjournals` posts and finds manual journals, `accounting.settings.read` reads the Xero organisation's base currency and its chart of accounts, and `accounting.reports.balancesheet.read` reads the client-money balance for the [bank rail daily reconciliation](https://docs.settlemint.com/docs/api-reference/guides/bank-rail#daily-reconciliation). A connection made before DALP asked for the balance-sheet scope keeps posting. Connect Xero again to add the scope.

A new connect replaces any connect still waiting for consent. The callback completes only for the signed-in user who started the connect, while that user still holds `webhook:manage` in the organisation, and each consent URL works once. Opened without a Console session, the callback answers `401` and leaves the consent URL usable until it expires.

| Outcome | What happened |
| --- | --- |
| `connected` | DALP stored the grant and the Xero organisations it connected. |
| `denied` | The administrator declined at Xero, or no longer holds `webhook:manage` in the organisation. |
| `invalid-state` | The consent URL is unknown, expired or already used, or a different user is signed in. |
| `exchange-failed` | Xero refused to exchange the authorisation code, for example because the client secret or the redirect URI does not match the app, or DALP could not read the grant's organisations. |
| `no-organisation` | The grant connected no Xero organisation. |
| `tenant-in-use` | A Xero organisation in the grant is already connected to another DALP organisation. |

On every outcome except `connected`, DALP discards the client secret it stored for the connect and revokes any token Xero issued. The outcome never carries Xero's own error text.

Connecting again with the same Xero user and the same app replaces the stored token. Connecting with a different Xero user or a different app also revokes the earlier grant at Xero.

### Connection status and disconnect [#connection-status-and-disconnect]

`GET /api/v2/accounting/xero/connection` reads the stored connection without calling Xero:

```json
{
  "state": "connected",
  "tenantIds": ["8a3f2c71-5d4e-4b9a-a1c6-2e7f9b0d3c58"],
  "lastRefreshedAt": "2026-11-10T09:15:00.000Z"
}
```

`state` is `connected`, `needs-reconnect` or `disconnected`. `needs-reconnect` means Xero refused the stored grant, for example after someone removed the app's connection in Xero. Posting then pauses, and DALP raises a **Xero connection needs attention** case. Connect again to resume.

While it posts, DALP refreshes the access token about every 30 minutes. It also refreshes a connection that has nothing to post before Xero's 60-day refresh-token expiry. Each refresh rotates the refresh token, and DALP keeps the newest token even when it crashes between Xero's answer and its own write.

`DELETE /api/v2/accounting/xero/connection` disconnects, and posting stops at once. DALP then revokes the grant at Xero, retrying every minute until Xero confirms, and deletes the token and the client secret only after that. After five unconfirmed attempts it raises a **Xero connection needs attention** case. An organisation with no connection gets `404` with `DALP-20544`.

### Who can call what [#who-can-call-what]

| Call | Route | Needs |
| --- | --- | --- |
| Connect | `POST /api/v2/accounting/xero/connection` | A Console session with `webhook:manage`. Never held for a second approver, because its body carries the client secret. |
| Read the connection | `GET /api/v2/accounting/xero/connection` | A Console session with `webhook:manage`. |
| Disconnect | `DELETE /api/v2/accounting/xero/connection` | A fresh Console session with `webhook:manage`. Held for a second approver while the organisation protects **Custody administration** changes. |
| Callback | `GET /api/v2/accounting/xero/callback` | The Console session of the user who started the connect, still holding `webhook:manage`. |
| Store the configuration | `PUT /api/v2/accounting/configuration` | `webhook:manage` from a session or an API key. Held for a second approver while the organisation protects **Custody administration** changes. |
| Read the configuration | `GET /api/v2/accounting/configuration` | `webhook:manage` from a session or an API key. |
| List the posting records | `GET /api/v2/accounting/postings` | A Console session with `webhook:manage`. |
| Replay a posting record | `POST /api/v2/accounting/postings/{postingId}/replays` | A Console session with `webhook:manage`. Never held for a second approver. |

[Approvals](https://docs.settlemint.com/docs/console/organisation-settings/general#approvals) describes how an organisation protects a group of changes.

### Where the credentials live [#where-the-credentials-live]

The refresh token and the client secret never enter an accounting table, a log, an audit record or a response. DALP keeps them in the secret manager the deployment selects with `secretManager.provider`, as [Secrets and key handling](https://docs.settlemint.com/docs/deployment/security-compliance-posture#secrets-and-key-handling) describes:

- With `local`, DALP encrypts each secret under the deployment's master password and stores it in the platform database.
- With `aws`, `gcp`, `azure` or `vault`, each secret lives in your AWS Secrets Manager, Google Secret Manager, Azure Key Vault or HashiCorp Vault, under that store's controls and audit.

Every platform service that reads the secret manager can read these secrets. The organisation in a secret's name is a label, not an access control. On `local`, anyone who holds both database access and the master password can decrypt them. When DALP deletes a secret, Azure Key Vault keeps it recoverable for the vault's retention period, and the version 2 key-value engine of HashiCorp Vault deletes only the latest version. Request audit records redact the callback's `state` and `code` values.

## Posting records [#posting-records]

DALP keeps one posting record for every committed event of a configured organisation, not only for the event types its rules cover, so a rule added later still finds the earlier events. A record carries its status, a reason, the configuration version that decided it, the decided journal, and the Xero journal id and Xero organisation it posted to.

| Status | Meaning |
| --- | --- |
| `pending` | Waiting to be decided or posted. This includes a reversal waiting for its original, a retry after a temporary failure and an organisation whose posting is paused. |
| `sealed` | Decided under the `daily-aggregate` policy and waiting for its day's journal. |
| `posted` | Xero accepted the journal, or the record's daily journal netted to zero. |
| `failed` | Xero refused the journal for good, the payload was pruned before DALP copied the event, or the journal's Xero organisation is no longer connected. |
| `unmapped` | No rule covers the event, or the configuration cannot turn it into a Xero journal. |
| `ignored` | A test event, an event that is not final, or an event the rules mark as having no accounting effect. |

These rules apply to records:

- A newer configuration version decides every `unmapped` record again on the next pass, so a corrected rule or account mapping posts what it blocked.
- A replay returns a `failed`, `unmapped` or `ignored` record to `pending`. A `posted` record is never replayed, and its correction is a new journal.
- A record keeps the event payload until 30 days after it reaches `posted` or `ignored`, so a `pending`, `sealed`, `unmapped` or `failed` record can always be decided again. The decided journal stays for the record's whole life. A replay of an `ignored` record whose payload is gone is refused.
- An event whose payload was pruned before DALP copied it is `failed` with reason `payload-pruned`, because DALP never decides an event from an empty payload.

### Read and retry posting records [#read-and-retry-posting-records]

`GET /api/v2/accounting/postings` lists the active organisation's posting records, newest first. It pages with `page[limit]` and `page[offset]`, 50 records to a page by default, and returns the number of matching records in `meta.total`. `filter[status]` takes one status, as in `filter[status]=failed`, or an `eq`, `ne`, `inArray` or `notInArray` predicate, as in `filter[status][inArray]=failed,unmapped`. The list has one order, so a `sort` other than `-createdAt` answers `400` with `DALP-9355`. That is a caller error: drop `sort` or send `-createdAt`, and do not retry the same request.

Each record carries its `status`, a `reason` code, the last failure message in `detail`, the `journal` the rule table built with its narration, debit total and lines, and the Xero journal it reached: `xeroJournalId` for a record posted on its own, or `dailyJournal` with the day, sequence, status and Xero journal id of the daily journal it joined. `attempts` counts the posting attempts, `replayCount` the replays, and `replayable` says whether a replay would return the record to `pending`. The Console's [Accounting](https://docs.settlemint.com/docs/console/organisation-settings/accounting) page shows the same records, with each `reason` in plain words, and the Xero connection state.

`POST /api/v2/accounting/postings/{postingId}/replays` returns a `failed`, `unmapped` or `ignored` record that still keeps its payload to `pending`. It clears the reason, the last failure and any daily journal the record was in. On its next pass the posting job decides an `unmapped` or `ignored` record again with the newest configuration version. A `failed` record whose journal DALP already sent to Xero keeps that journal: when the last send was less than six minutes ago, DALP sends the same journal again as built. Otherwise DALP first looks the journal up in Xero by its narration marker, records the record as posted when Xero holds it, and builds the journal again from the newest configuration version when Xero does not. Any other `failed` record is decided again with the newest configuration version. The Accounting page's "Retry posting" row action calls this route. The replay has no body, and the platform answers `200` with the record. The response below is illustrative:

```http
POST /api/v2/accounting/postings/4f6b2c1e-8a3d-4e7f-9b25-0c6d1a8e3f72/replays
```

```json
{
  "data": {
    "id": "4f6b2c1e-8a3d-4e7f-9b25-0c6d1a8e3f72",
    "sourceId": "chain:537001:0x3f9c2a7e5b1d84c06e2a9f4b7d3c1e8a5f6b2d9c0e7a4f1b3c5d8e2a6f9b0c4d:3:0:primary-market.subscription.final@1",
    "eventType": "primary-market.subscription.final",
    "eventVersion": 1,
    "lifecycleState": "final",
    "status": "pending",
    "reason": null,
    "detail": null,
    "configurationVersion": 3,
    "postingPolicy": "per-trade",
    "journal": {
      "narration": "primary-market.subscription.final chain:537001:0x3f9c2a7e5b1d84c06e2a9f4b7d3c1e8a5f6b2d9c0e7a4f1b3c5d8e2a6f9b0c4d:3:0:primary-market.subscription.final@1",
      "occurredAt": "2026-10-12T09:15:00.000Z",
      "amount": "24.99",
      "currency": "USD",
      "lines": [
        {
          "side": "debit",
          "amount": "24.99",
          "currency": "USD",
          "accountKey": "investor-cash",
          "classification": "trades",
          "description": "Subscription"
        },
        {
          "side": "credit",
          "amount": "24.99",
          "currency": "USD",
          "accountKey": "subscription-liability",
          "classification": "trades",
          "description": "Subscription"
        }
      ]
    },
    "xeroJournalId": null,
    "xeroTenantId": null,
    "dailyJournal": null,
    "reversedBy": null,
    "attempts": 2,
    "replayCount": 1,
    "replayable": false,
    "createdAt": "2026-10-12T09:16:04.000Z",
    "updatedAt": "2026-11-10T14:02:31.000Z"
  },
  "links": { "self": "/api/v2/accounting/postings" }
}
```

A record that is already `pending` cannot be replayed again, so a second replay while the record is still `pending` answers `409` with `in-progress`. The platform writes an audit record for each replay. A refused replay names its cause:

| Status | Error | `data.refusal` | What the platform observed | What to do |
| --- | --- | --- | --- | --- |
| `404` | `DALP-20545` | None | The active organisation has no posting record with this id. | List the records and use an id from the list. |
| `409` | `DALP-20546` | `posted` | Xero holds the journal, or the record's daily journal netted to zero. | Correct the journal with a new journal in Xero. |
| `409` | `DALP-20546` | `in-progress` | The record is `pending` or `sealed`, so the posting job decides it on its next pass anyway. | Read the record again after the next pass. |
| `409` | `DALP-20546` | `payload-pruned` | The record is `failed`, `unmapped` or `ignored`, but its payload is gone. | Book the event by hand, because DALP cannot decide it again. |

Neither error is retryable, and neither means the record changed: a refused replay leaves the record as it was.

## Posting policies [#posting-policies]

The configuration's `postingPolicy` is `per-trade`, the default, or `daily-aggregate`. DALP stamps the policy on each record when it decides the record, so a policy change affects only records decided after it.

Under `per-trade`, each record posts as its own journal, dated the UTC day of the event's timestamp.

Under `daily-aggregate`, a decided record waits as `sealed` for its UTC day. The day closes at 02:00 UTC the next day. DALP then builds one balanced journal dated that day from the day's sealed records and posts it:

- DALP sums the lines per account, side, tax type and tracking category, and a debit and a credit on one account net to one line.
- A journal that nets to zero is recorded as posted, and nothing is sent to Xero.
- A day whose total would reach ten billion in the ledger currency splits into more than one journal.
- A record decided after its day's journal was built goes into a supplementary journal for that day, with the same date. When Xero refuses it because the period is locked, the journal is `failed` with a case.
- A record that cannot be mapped when the day closes is `unmapped` with a case, and the day's other records still post.
- When Xero refuses a daily journal, the journal and its records are `failed` with a case. A replayed record joins the next journal for its day.

### Reversals [#reversals]

A retraction such as a trade bust posts as the reversal of the journal its original posted. The reversal mirrors the original's lines on the same Xero account codes, even when the account mapping changed after the original posted.

- Under `per-trade`, a reversal waits without a case until its original has posted.
- Under `daily-aggregate`, a reversal of an original in the same day's open journal joins that journal, so the two net out. A reversal on a later day waits until the original's daily journal has posted.
- DALP reverses an original at most once.
- A reversal still waiting after one day of connected time raises an **Accounting event blocked** case. It keeps retrying, at most an hour apart, and posts once its original posts.

## Operations cases [#operations-cases]

DALP raises an operations case whenever an event cannot post, and lists it with the organisation's other cases. [Work an operations case](https://docs.settlemint.com/docs/console/organisation-settings/custody-books#work-an-operations-case) describes how to acknowledge and resolve one.

| Case | Kind | Raised when |
| --- | --- | --- |
| **Accounting event blocked** | `accounting-event-blocked` | An event has no rule, names an asset outside the rule table, is malformed, or carries an amount the ledger cannot take. Also when the configuration cannot turn a journal into a Xero journal, such as an account key with no Xero account code, a tax-bearing line or a journal outside the Xero base currency, and when a reversal has waited more than one day. One case per event type and cause while it is open. A configuration version that fixes the cause posts the blocked records. |
| **Accounting posting failed** | `accounting-posting-failed` | Xero refused a journal for good, a journal could not be built, payloads were pruned before DALP copied the events, or a committed event waited more than an hour before DALP could read it, which points at a stalled event relay. One case per failure class while it is open. |
| **Xero connection needs attention** | `accounting-xero-connection` | One case per organisation. Its reason starts with `needs-reconnect` when Xero refused the grant, `authentication` when Xero refused the posting credentials with a persistent 401 or 403 on a journal post, `tenant-not-connected` when the configured Xero organisation is not among the grant's organisations or a journal's Xero organisation was disconnected, `rate-limited` when Xero asked DALP to wait more than ten minutes, `revocation-pending` when Xero has not confirmed a revocation, or `client-unavailable` when DALP could not build a Xero client, for example because the stored client secret is missing. |

**Accounting event blocked** is a warning. The other two are critical. DALP resolves a `rate-limited` case itself once Xero accepts a journal again.

## Xero limits [#xero-limits]

Xero limits each app by its tier. A Starter tier app allows 1,000 API calls a day and 5 connected organisations, which fits a trial and not a production book. DALP spends about two calls on a post once the access token and the tenant check are cached, so a production organisation needs a higher Xero tier, or the `daily-aggregate` policy. When Xero answers `429`, DALP pauses that organisation until Xero's retry time, 60 seconds when Xero names none, and the other organisations keep posting.

A Xero Demo Company resets every 28 days and gets a new tenant id. Posting then pauses with a **Xero connection needs attention** case until an administrator connects again and stores a configuration version with the new tenant id.

## What DALP does not post [#what-dalp-does-not-post]

- Mirror-token issuance and burn. These events reach subscribed webhook endpoints only, not the organisation's committed events, so the posting job never sees them.
- A completed partial redemption or buyback. No event marks when its cash moves, so such an event ends `unmapped` with an **Accounting event blocked** case.
- Events from before the organisation's first configuration version, and events whose payload was pruned before DALP copied them.
- Tax-bearing journal lines. A rule that produces one ends `unmapped`.

Book these by hand, or through a custom subscriber.

## Run your own subscriber [#run-your-own-subscriber]

A custom subscriber posts what DALP does not: journals for a ledger other than Xero, and the events in [What DALP does not post](#what-dalp-does-not-post) that reach webhook endpoints. It also reconciles the ledger's totals against DALP's read APIs on a schedule. When a subscriber and DALP both post to the same Xero organisation, keep their rules apart, or a movement posts twice.

The rest of this page is the contract for such a subscriber: what is on the feed, how to verify a delivery, the rule table, and the idempotency and replay rules. DALP's own posting job follows the same rule table.

[Figure] A subscriber turns each signed delivery into at most one ledger journal. DALP sends a signed webhook delivery with evt_id, source_id and lifecycle_state. The subscriber verifies the signature and skips test events. It then branches on lifecycle_state. A pending, provisional or recalled event never posts. A final event goes through its posting rule into a balanced debit and credit journal. A retracted event is reversed by its reversal rule when one exists, or by looking up the event its supersedes field names. The reversal mirrors the original journal. A retraction of a pending or provisional event posts nothing. Both kinds of journal post once, keyed on source_id, so a replay builds the same entry. Labels: Signed delivery; Webhook; evt_id, source_id, lifecycle_state; Verify the signature; Subscriber; Skip test events; Branch on lifecycle_state; Lifecycle state; Read it after the signature, never before; Skip; No-op; pending, provisional and; recalled never post; Posting rule; final; Balanced debit and; credit journal; Reversal; retracted; By rule or supersedes; lookup, mirrors original; Post once per source_id; Ledger; A replay builds the same entry.

A signed delivery is verified, branched on `lifecycle_state` and posted once per `source_id`, so a replay builds the same entry.

## What is on the feed [#what-is-on-the-feed]

An endpoint receives the events it subscribes to. Each delivery is one JSON envelope with these fields the ledger side reads:

| Field | Meaning for a subscriber |
| --- | --- |
| `evt_id` | Identifies this recorded event. Retries carry the same `evt_id`, and a replay of the same occurrence carries a new one. |
| `source_id` | Identifies the underlying occurrence. It stays the same across replays. Every event except a test event carries one. |
| `type`, `version` | The event name and its schema version. Match rules on both. |
| `lifecycle_state` | One of `pending`, `provisional`, `final`, `retracted`, `recalled`. |
| `payload` | The typed event data, including amounts and timestamps. |
| `supersedes` | On a retraction, the `evt_id` of the event it replaces. |
| `is_replay` | `true` on an envelope created by a replay request. |
| `is_test` | `true` on a test event. Never post it. |

The [event catalogue](https://docs.settlemint.com/docs/api-reference/webhooks/events) and [market and settlement events](https://docs.settlemint.com/docs/api-reference/webhooks/market-events) list the events the platform sends, their triggers, and the receiver's action. Payload schemas and examples are in the [machine-readable event definitions](https://docs.settlemint.com/.well-known/dalp-events.json) and [TypeScript SDK](https://docs.settlemint.com/docs/api-reference/sdk). The manifest groups the events into these families:

| Family | What it reports |
| --- | --- |
| `token` | Transfers, corporate actions and their retractions, fees, period closes and bond payouts |
| `asset` | Asset creation, issuance, burns, pause and unpause |
| `primary-market` | Token sale subscriptions, deliveries, refunds and proceeds withdrawals |
| `trading-venue` | Orders, trades, trade settlement and their busts |
| `xvp` | Cross-party settlement lifecycle |
| `compliance` | Freezes, unfreezes and verification verdicts |
| `identity` | Registration, claims and status |
| `access-control` | Role grants and revocations |
| `custody` | Account creation, signer changes and custody gateway settlements |
| `funding` | Funding requirements for operations |
| `operations` | Operations cases opened, acknowledged and resolved |
| `reporting` | Wallet confirmations, client statements and filing deadlines |
| `transaction` | Transaction request outcomes, from broadcast to confirmation, failure or cancellation |
| `bank-rail` | Credit and cash-out milestones, bank reversals and returned payouts |

### Bank rail events [#bank-rail-events]

Subscribe explicitly to `bank-rail.credit.*` or `bank-rail.cash-out.*`, because the default state patterns skip their milestone names. These events carry `amount`, `currency` and `occurredAt`, so they are journal candidates when your books have a rule for that milestone. An admitted or requested event records work in progress. Its envelope state `final` means the rail committed that observation, not that the payment completed.

Bank amounts are decimal currency values: `"12.50"` EUR is 12.50 EUR, rather than token base units. Convert them exactly to your ledger's minor units before applying the integer-amount rule below. Never feed a fractional bank amount to a rule that expects token base units.

Choose the posting milestone for each business movement. Posting the credit's admitted and minted events, or posting both its minted event and the token issuance or transfer, can count the same movement twice. A released cash-out can later report paid if the bank settles it late and the rail recovers and burns the tokens. Partial recovery sends no event. A cash-out's paid event can be followed by returned, which means the rail admitted the re-credit, not that it minted. The re-credit's admitted event identifies that cash-out through `provenance.cashOutId`. Wait for its minted event to book the completed mint.

A recall's recovered and written-down amounts, and each recorded claw, appear on the recall sheet on the Console's **Payments** tab. `bank-rail.credit.recalled` arrives only when completed recalls cover the whole credit. Its `amount` is the completing bank reversal's amount, and earlier partial recalls send no credit status event. Read the recall records before constructing a journal for the whole reversal history. Events expose neither recovered amounts nor write-down figures, so they cannot supply those postings on their own. See the [bank rail catalogue](https://docs.settlemint.com/docs/api-reference/webhooks/events#bank-rail) for each trigger.

### Fee events [#fee-events]

Fees arrive as their own events. For each token, post its fees either from the fee events or from the transfers that move them, never from both.

| Event | What it reports | Fee id |
| --- | --- | --- |
| `trading-venue.trade-fee.final` | The venue fee charged to one side of a settled trade, `buyer` or `seller`. | `<tradeId>:<side>` |
| `trading-venue.trade-fee.retracted` | A trade bust reversed that fee. | `<tradeId>:<side>` |
| `token.fee.final` | One token fee charge: transaction, external, AUM, accrual or fund management fee. | `<blockNumber>:<logIndex>:<feeType>` |
| `token.fee-period-close.final` | One accrual period close. | `periodCloseId`, `<blockNumber>:<logIndex>` |

Custody gateway settlements are on the feed too: `custody.gateway-deposit.settled` and `custody.gateway-withdrawal.settled`. The [custody event catalogue](https://docs.settlemint.com/docs/api-reference/webhooks/events#custody) describes their triggers.

A token fee event is `final` only. DALP sends it once the chain finality watermark reaches its block, so the platform never retracts it. The `basis` field is `collected` or `accrued`, and a rule can branch on it with `when`. The `payer` field is withheld from thin payloads. The `fees-and-charges` report row for a token fee has the subject reference `<feeId>:<payer>`, with an empty payer part when the fee has no payer. A fee id is unique within one chain only, so a ledger that takes events from more than one chain keys token fees on `source_id`.

A transaction, AUM or management fee also moves tokens on chain, so `token.transfer.final` or `asset.issuance.final` fires for the same value. An external fee paid in a DALP token fires `token.transfer.final` too. A rule table cannot exclude one transfer leg, so a ledger that maps `token.transfer.final` for a token also books its fees through that event. For each token, map either its fee events or its transfers, not both.

`token.fee-period-close.final` reports the on-chain sum of every accrual since the previous close in `amount`. No tokens or cash move at a close. A ledger that posts accruals to a receivable moves that total on at the close. An accrual refused for not being a whole number of cents leaves the receivable short against the close until someone posts it by hand.

Most token fees are denominated in the token itself. Listing a security token in a rule table's assets values it at par, one token per ledger currency unit. Leave such fees unmapped until a valuation exists. Your subscriber never rounds, so it refuses a fee amount that is not a whole number of cents. Basis-point fees on 18-decimal tokens are usually not whole cents.

An endpoint receives these events from its deployment onward. The next indexer rebuild also sends them for every past fee log at or after the endpoint's start block. Deduplication on `source_id` posts each fee once. A ledger that already booked those fees from the period reports should exclude the earlier period.

### Bond payout events [#bond-payout-events]

A bond pays its coupons and its maturity redemption one holder at a time, when the holder claims or redeems, so the cash reaches the feed as one event per claim or redemption.

| Event | What it reports | Domain key |
| --- | --- | --- |
| `token.coupon-claim.final` | One holder's coupon claim on a fixed treasury yield feature or a legacy fixed yield schedule. | `claimId`, `<blockNumber>:<logIndex>` |
| `token.maturity-redemption.final` | One holder's redemption of matured bond tokens on a maturity redemption feature or a legacy bond. | `redemptionId`, `<blockNumber>:<logIndex>` |

Both events are `final` only. DALP sends each one once the block of its claim or redemption reaches chain finality, so the platform never retracts it, and a replay of the same log sends no second event. `amount` is the cash paid to the holder, in base units of `denominationAddress`. A coupon claim's `amount` can be less than the sum of the periods from `fromPeriod` to `toPeriod`, so post `amount` and not a figure computed from the coupon rate. A redemption also carries `tokenAmount`, the redeemed tokens. `featureAddress` is the contract that paid, which is the bond itself for a legacy bond. The `holder` field is withheld from thin payloads. Converting accrued yield into tokens pays no cash and sends no event.

A bond coupon corporate action completes when it is created, and a maturity redemption completes when no tokens are left, so `token.corporate-action.completed` for either one moves no cash. Post the cash from the bond payout events and treat those completions as booked elsewhere.

When the denomination asset is a DALP token, the payment also fires `token.transfer.final`. For each bond, map either its bond payout events or the denomination transfers that pay its holders, not both.

An endpoint receives these events for claims and redemptions that reach finality after the platform started sending them. Earlier claims and redemptions never get one, and an indexer rebuild does not send them.

If your organisation stores its configuration from the preset described in [Store a posting configuration](#store-a-posting-configuration), the preset posts both events in each quote asset of the ledger currency, with classification `servicing`. A coupon claim debits `servicing.distributions.<suffix>` and a redemption debits `servicing.redemptions.<suffix>`, and both credit `client-money.liability.<suffix>`. An event in another denomination matches no rule, so the subscriber refuses it. The preset ignores `token.corporate-action.completed` for bond coupons and maturity redemptions.

Not every event can become a journal. A journal needs an amount in the payload and an ISO 8601 timestamp for when it happened. For example, `token.transfer.final` carries `amount`, `tokenAddress` and `occurredAt`, the time of the block that holds the transfer, so a rule can post it. A transfer from before `occurredAt` existed has no timestamp field, so your subscriber refuses it as malformed. `primary-market.subscription.final` carries `paymentAmount`, `paymentCurrencyAddress` and `occurredAt` too. Check the event's schema in the [machine-readable event definitions](https://docs.settlemint.com/.well-known/dalp-events.json) before you write a rule for it.

## Verify and accept a delivery [#verify-and-accept-a-delivery]

Treat the signature as the gate before any posting logic runs. Verify every delivery as [Verify the signature](https://docs.settlemint.com/docs/api-reference/guides/webhooks#verify-the-signature) describes, with the SDK's `verifyWebhook` or any Standard Webhooks library. The signed content is the exact raw body, so verify before you parse it. While a secret rotates, `webhook-signature` can hold two signatures. Either one is enough.

Answer with a `2xx` as soon as you have stored the event durably, then post to the ledger afterwards. A reply slower than 20 seconds counts as a failure and triggers a retry of work you may already have done. The [response and retry table](https://docs.settlemint.com/docs/api-reference/webhooks/consuming#retries) and [counter-signed receipt contract](https://docs.settlemint.com/docs/api-reference/webhooks/consuming#counter-signed-receipts) define the delivery response. [Receive DALP webhooks](https://docs.settlemint.com/docs/api-reference/guides/webhooks#rotate-the-signing-secret) covers secret rotation.

A signature proves DALP sent the message and that nobody altered it. It does not tell you the event is final. Read `lifecycle_state` next.

## From event to journal [#from-event-to-journal]

A rule table maps the organisation's events to journals. DALP's posting job reads the one in the organisation's stored configuration, and a custom subscriber keeps its own. Two kinds of rule exist.

A posting rule names an event `type` and `version`, an optional exact-match condition on payload fields, a classification, a debit account key and a credit account key. It also names the payload fields that hold the amount, the asset, the timestamp, an optional stable domain key, and any reference fields to copy into the description. The classification is one of `trades`, `fees`, `servicing` or `corrections`.

A reversal rule names the event type it undoes and the payload field that identifies the original.

An **account key** is a stable, organisation-chosen name such as `investor-cash`. The organisation's account mapping resolves each key to a real ledger account, per classification, in Xero or elsewhere. Rules never carry ledger account codes, so a chart-of-accounts change touches the mapping and not the rules.

A rule table is valid only when all of these hold. Otherwise reject the whole table instead of fixing it up silently.

- Every account key resolves in the account mapping for the rule's classification.
- No two rules can match the same event, and a type does not have both posting and reversal rules.
- Every reversal rule targets a type that has a posting rule, and both key on the same field.
- Every asset's currency is the ledger currency.
- No posting rule targets a pending or provisional event.

### Which events post [#which-events-post]

| Lifecycle state | What the subscriber does |
| --- | --- |
| Test event (`is_test`) | Skip. |
| `pending`, `provisional` | Skip. These can still be retracted, so they never post. |
| `final` | Apply the matching posting rule. |
| `retracted` | Apply the matching reversal rule, if the organisation wrote one. A retraction of a pending or provisional event needs no rule: nothing was posted, so acknowledge it and do nothing. |
| `recalled` | Reserved. The platform sends no new event in this state. A Replay can resend one that DALP 3.1 stored: acknowledge it and post nothing. |

Your subscriber refuses a `final` event with no matching rule, or a `retracted` event that reverses a posted entry but has no rule, with a named error rather than guessing. Treat that refusal as a signal to extend the rule table, and keep the delivery for later. Acknowledge test events, recalled events, and every pending or provisional event as handled no-ops, including the retraction of a pending or provisional event, since nothing was posted for it. Refusing those would only cause retries.

### The journal shape [#the-journal-shape]

A posting produces one balanced entry with two lines.

| Entry field | Value |
| --- | --- |
| `sourceEntryId` | The envelope's `source_id`. |
| `occurredAt` | The rule's timestamp field. |
| `narration` | `<type> <source_id>`. |
| Debit line | The debit account key, the amount, and `sourceLineId` of `<source_id>:debit`. |
| Credit line | The credit account key, the same amount, and `<source_id>:credit`. |

Each line carries the classification, the ledger currency and a description made of the rule's text plus `field=value` pairs for the reference fields. Because both lines carry the same amount, the entry always balances.

### Amounts [#amounts]

Payload amounts for token and asset events are integer strings in the asset's smallest unit. The rule's asset field names an entry in the organisation's asset table, which gives the ledger currency and the asset's decimals. The subscriber converts exactly to cents with integer arithmetic. It never rounds. It refuses any amount that is zero, is not a whole number of cents, or is ten billion or more in the ledger currency. A refused amount needs a human decision: a sub-cent amount in the ledger currency is a rule or asset-table problem, not something to round away.

### Worked example: one subscription [#worked-example-one-subscription]

An investor subscribes to a token sale. DALP sends this event once the chain reaches finality for its block. Fields the rule does not use are omitted:

```json
{
  "evt_id": "evt_7c12e838e3f9a8bafcaa292f86ed41e7",
  "source_id": "chain:537001:0x3f9c2a7e5b1d84c06e2a9f4b7d3c1e8a5f6b2d9c0e7a4f1b3c5d8e2a6f9b0c4d:3:0:primary-market.subscription.final@1",
  "type": "primary-market.subscription.final",
  "version": 1,
  "lifecycle_state": "final",
  "payload": {
    "saleAddress": "0x7777777777777777777777777777777777777777",
    "paymentCurrencyAddress": "0x8888888888888888888888888888888888888888",
    "paymentAmount": "1000000000",
    "occurredAt": "2026-10-12T09:15:00.000Z"
  }
}
```

In the tables of this example, `<source_id>` stands for that `source_id` value. The organisation's rule table holds one posting rule for `primary-market.subscription.final` at version 1. It uses classification `trades`, debit key `investor-cash`, credit key `subscription-liability`, amount field `paymentAmount`, asset field `paymentCurrencyAddress`, timestamp field `occurredAt` and reference field `saleAddress`. Its asset table maps `0x8888…8888` to currency `USD` with 6 decimals.

The subscriber computes the amount: 1,000,000,000 base units at 6 decimals is 1000.00 USD, exactly 100,000 cents. It then builds this entry:

| Field | Value |
| --- | --- |
| `sourceEntryId` | `<source_id>` |
| `occurredAt` | 2026-10-12T09:15:00.000Z |
| `narration` | `primary-market.subscription.final <source_id>` |
| Debit | `investor-cash`, 1000.00 USD, line id `<source_id>:debit` |
| Credit | `subscription-liability`, 1000.00 USD, line id `<source_id>:credit` |

DALP's posting job, or your own ledger connector, then resolves `investor-cash` and `subscription-liability` through the `trades` account mapping and posts the entry. In Xero, that is one manual journal.

## Store a posting configuration [#store-a-posting-configuration]

An organisation keeps its rule table, chart-of-accounts mapping and posting policy in DALP with `PUT /api/v2/accounting/configuration`, and reads the newest version with `GET`. [Who can call what](#who-can-call-what) lists the permission and approval each needs. The body names three things:

- `postingPolicy`: `per-trade`, the default, or `daily-aggregate`, as [Posting policies](#posting-policies) describes.
- `mapping`: the Xero organisation's `xeroTenantId`, its base currency as `defaultCurrency`, the Xero account code for each account key per classification under `accounts`, and any `taxTypes` and `trackingCategories`.
- `rules`: the rule table that [From event to journal](#from-event-to-journal) describes.

Each write creates a new immutable version. Send the version you read as `expectedVersion`, or `null` for the first one. A stale version answers `409`, and repeating a write whose content matches the current version returns that version. A rule table that cannot post against its account mapping answers `422`, with each problem in `data.issues`.

A write sends its rules either as a complete rule table or as preset parameters. The parameters list the organisation's quote assets, mirror assets, other assets and bank rail currencies, and give each quote asset, mirror asset and currency an account suffix. DALP expands them into a rule table that names each asset's accounts with its suffix, such as `client-money.liability.<suffix>`, and stores the expanded table in the version. A version keeps that table, so a change to the preset reaches an organisation only when it writes its configuration again. A version written before the preset covered bond payouts has no rule for `token.coupon-claim.final` or `token.maturity-redemption.final`, so those events are refused until the organisation writes its configuration again. That write needs `servicing.redemptions.<suffix>` in the `servicing` account mapping for every quote asset in the ledger currency, or it answers `422`.

The first version starts the posting record intake: DALP copies the organisation's events from that version's creation onwards and posts them once Xero is connected. A record that may already have reached Xero keeps the version that decided it.

## Reversals and idempotency [#reversals-and-idempotency]

Two keys keep the ledger correct.

**`webhook-id` deduplicates deliveries.** The header carries the envelope’s `evt_id`. A retry repeats the same `webhook-id`, so record the ones you have handled and answer `2xx` for any you recognise.

**`source_id` makes the posting idempotent.** A replay creates a new `evt_id` for the same occurrence, so `evt_id` alone would post it twice. Because the journal's `sourceEntryId` is the `source_id`, a replay produces the identical entry, and a ledger connector that keys on the organisation plus `sourceEntryId` posts it once.

Treat a posted entry as immutable. Never edit it to correct it. A correction is a new entry with a new source id.

### The reversal key [#the-reversal-key]

Each posting also has a **reversal key**. It is `<type>#<value>` where the value is the payload field the rule names as its domain key, for example a trade id. When a posting rule declares no domain key, the key is `<type>#source:<source_id>`. Store the reversal key with the entry you post, because a reversal looks the original up by it.

A reversal event, such as a trade bust, names the original through a payload field that holds the same value as the original's domain key. A rule is only valid when both events use the same field. Many retractions carry only `supersedes`, the `evt_id` of the original, and no such field. A reversal rule cannot express those, because it must name a payload field. Handle them in the subscriber outside the rule table: look up the event named by `supersedes` in your stored deliveries and use its stored reversal key. The subscriber then:

1. Builds the key `<reversed type>#<value read from the retraction's payload>`, or takes the stored key of the event named by `supersedes`.
2. Looks up every entry posted under that key for this organisation.
3. Posts one new entry whose lines mirror the originals: debit becomes credit and credit becomes debit, same account keys, same amounts, line ids `<original line id>:reversal`, and descriptions starting "Reversal of".
4. Uses the retraction's own `source_id` as `sourceEntryId`, with narration `<type> reverses <reversal key>`.

If the lookup finds nothing, decide by whether the original can still arrive. When the event named by `supersedes` is one your endpoint has stored but has not posted, or a delivery may still be in flight, keep the reversal queued and retry it yourself after you acknowledge the delivery, because deliveries can arrive out of order and DALP does not resend one you acknowledged. Once the original turns out to be a pending or provisional event, which never posts, mark the retraction handled and stop retrying. When no such event exists for your endpoint, there is nothing to reverse: keep the retraction, log the missing original, acknowledge with a `2xx` and post nothing. Never post a reversal for another organisation's entry.

## Delivery, retries, ordering and replay [#delivery-retries-ordering-and-replay]

DALP delivers at least once, never exactly once. The [retry contract](https://docs.settlemint.com/docs/api-reference/webhooks/consuming#retries) defines response classes, backoff, and the three-day retry window.

**Ordering is per endpoint.** A later eligible event waits while an earlier event is pending, including during backoff. A linked correction waits until its cause was delivered or can no longer be delivered. Finality waits do not block later events, and Replay can send an older observation after a newer one. Keep the ledger safe when a retraction names an event you never received, or when posting runs after acknowledgement. The [ordering contract](https://docs.settlemint.com/docs/api-reference/webhooks/consuming#ordering) defines those limits.

**Gaps are possible.** While an endpoint is switched off, whether an administrator switched it off or its circuit breaker opened after 30 failed attempts in a row, the platform records no events for it, and neither Resend nor Replay recovers them. Reconcile your ledger totals against DALP's reads on a schedule instead of assuming the feed is complete.

**Replay recovers recorded events.** The [Resend and replay reference](https://docs.settlemint.com/docs/api-reference/webhooks/consuming#resend-and-replay) defines the recovery calls. Replay selects events the platform recorded for an endpoint, by a block range or one `evtId`. A replayed envelope has a new `evt_id`, `is_replay: true` and the original `source_id`, so replaying is safe for a subscriber that keys on `source_id`. Use it after a subscriber outage longer than the three-day retry window, or for a delivery that ended in a terminal failure. The retention cleanup deletes a settled event 30 days after its delivery ended, so replay returns nothing for an event older than that. After a longer outage, rebuild the missing entries from DALP's read APIs instead. Replay cannot help when DALP never recorded a notification for your endpoint, as for the period an endpoint was switched off. If a replay of the affected range returns nothing for an event your reconciliation shows is missing, the ledger stays incomplete until you obtain the data from DALP's read APIs or your DALP contact.

## Frequently asked questions [#frequently-asked-questions]

### Why not post provisional events and correct them later?

A provisional event can be retracted by a chain reorganisation. Posting it means posting a reversal later and showing both in the ledger. A final chain event is sent only after its block reaches the network's [finality depth](https://docs.settlemint.com/docs/api-reference/webhooks/lifecycle#the-states-live-events-carry), so waiting for it avoids the reversal. `trading-venue.trade-settled.final` and `trading-venue.trade-fee.final` are the exception: the platform sends them when the settlement transaction confirms, before that depth, so reconcile trades against the chain before you close a period. A final event can still be undone by a business reversal such as a trade bust, which is what the reversal rules cover.

### What if your rules need a field the thin payload removes? [#what-if-my-rules-need-a-field-the-thin-payload-removes]

An endpoint's default `thin` payload shape strips personal data fields. Amounts and timestamps stay. If a rule reads a field that `thin` strips, the [machine-readable event definitions](https://docs.settlemint.com/.well-known/dalp-events.json) identify it. Follow the [payload shape contract](https://docs.settlemint.com/docs/api-reference/webhooks/consuming#payload-shape) to acknowledge the field and change to the full shape, or choose a different field.

## Next steps [#next-steps]

- [Receive DALP webhooks](https://docs.settlemint.com/docs/api-reference/guides/webhooks) covers endpoint registration, the signature headers and secret rotation.
- [Webhook Delivery](https://docs.settlemint.com/docs/concepts/events-out/webhook-delivery) explains retries, the circuit breaker and delivery evidence.
- [Platform Event](https://docs.settlemint.com/docs/concepts/events-out/platform-event) explains the lifecycle states and the event identifiers.
- [Work an operations case](https://docs.settlemint.com/docs/console/organisation-settings/custody-books#work-an-operations-case) covers acknowledging and resolving the accounting cases.
- [Secrets and key handling](https://docs.settlemint.com/docs/deployment/security-compliance-posture#secrets-and-key-handling) covers the secret manager that holds the Xero credentials.


# Authentication and API keys

Source: https://docs.settlemint.com/docs/api-reference/guides/authentication-api-keys
Authenticate Platform API requests with an X-Api-Key header, or a Console session on session-or-api-key routes, and store the secret when you create it.

## Overview [#overview]

An API key authenticates a script, backend service, or other direct integration with the Platform API. Each key you create belongs to one user and one organisation, carries a `read` or `read-write` scope, and can carry an expiry. A key created before the platform required an organisation can have none, as [Organisation scope](#organisation-scope) describes. Create one key per integration and give it only the access that integration needs. A key is a credential of its own: a password change, a ban, an account closure or an administrator's revoke stops it, but the end of the user's sessions does not, as [What stops a key](#what-stops-a-key) lists.

Send the key as the `X-Api-Key` header. The platform does not accept the key as a bearer token or a query parameter, so a client that copies a bearer-token pattern from another API fails authentication. Many Platform API routes, those whose OpenAPI operation carries `x-dalp-auth: session-or-api-key`, also accept a valid Console session cookie, so a browser client that already has a session does not need a long-lived key for those routes. When a request carries an `X-Api-Key` header, the platform authenticates it with the key alone: a key that fails leaves the request unauthenticated even if a valid session cookie came with it.

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

Some routes accept only a signed-in session. A key on such a route receives `DALP-0036`, HTTP 403. The private file routes under `/dalp/private/*` ignore an API key and answer `401`, the same answer as a request with no credential, as [Files](https://docs.settlemint.com/docs/api-reference/guides/files#api-keys-are-refused-on-private-file-routes) describes. Make those calls with a Console session instead.

## Create a key [#create-a-key]

Create a key in the Console on [API keys](https://docs.settlemint.com/docs/console/my-account/api-keys), run `dalp login` for the browser device-code flow, or call `POST /api/auth/api-key/create`. [Install and set up the command-line tool](https://docs.settlemint.com/docs/api-reference/cli/install) explains the `dalp login` flow, which asks for your wallet code and creates a `read-write` key for the selected organisation that expires after 90 days. The `/api/auth/*` routes are unversioned. The key they create authenticates against the versioned `/api/v2` Platform API. The [v2 API reference](https://docs.settlemint.com/docs/api-reference/v2) lists the complete request and response for each `/api/auth/api-key` route.

The create response is the only time the full secret value appears. Store it when you receive it, because a later read of the same key returns metadata only.

A direct create call needs a signed-in session, and a request authenticated with an API key cannot create a key. A backend service that holds only a key therefore gets its keys from the Console or `dalp login`. The body carries:

- `name`, required, 1 to 32 characters. Spaces at either end are trimmed before the check, and the key stores the trimmed name. A missing name, or one of only spaces, returns 400 `NAME_REQUIRED` and creates no key. The name is checked before `walletVerification`, so a refused name never uses up a recovery or authenticator code.
- `metadata`, required, an object with the `organizationId` of an organisation you are a member of and an optional `scope`, such as `{"organizationId": "<organisation id>", "scope": "read"}`. `GET /api/auth/organization/list` returns the ids of your organisations. The `scope` is `read` or `read-write`, and a key with no `scope` is `read-write`. A call with no `metadata`, or with `metadata` that names no organisation, returns 400 `API_KEY_METADATA_INVALID` and creates no key. The platform checks `metadata` before `walletVerification`, so a call refused for its `metadata` never uses up a recovery or authenticator code.
- `expiresIn` in seconds, at most 365 days. Omit it for a key that never expires. A longer value returns 400 `EXPIRES_IN_IS_TOO_LARGE`.
- `walletVerification`, required, the wallet step-up that also guards signing: proof that the person creating the key controls the account's wallet. Send `{"walletVerification": {"secretVerificationCode": "<code>", "verificationType": "PINCODE"}}`, with `PINCODE` for the wallet PIN, `OTP` for a wallet authenticator code, `OIDC_MFA` for an identity-provider authenticator code or `SECRET_CODES` for a recovery code.

An account that holds an authenticator must send its code: a PIN or recovery code returns 400 `WALLET_STEP_UP_STRONGER_FACTOR_REQUIRED`. Without a proof the call returns 400 `WALLET_STEP_UP_REQUIRED`, or 401 `WALLET_STEP_UP_UNAVAILABLE` when the account has no wallet factor yet. The account password is not accepted in its place. During the cooling-off period after a wallet security change the call returns 403 `WALLET_STEP_UP_HELD` with `heldUntil` and creates no key. When the deployment sets `enforce2fa`, an account without two-factor sign-in gets 403 `LOGIN_TWO_FACTOR_REQUIRED` and no key, unless it signs in only through a configured identity provider with no password or passkey. A key would otherwise let the account reach the API without the second factor. Every new key emails the account holder.

The platform sets the rate-limit, request-budget and permission fields itself. A create or update call that sets `rateLimitEnabled`, `rateLimitMax`, `rateLimitTimeWindow`, `remaining`, `refillAmount`, `refillInterval` or `permissions`, or a create call that sets `prefix`, returns 400 `SERVER_ONLY_PROPERTY`.

A key is 54 characters: `sm_dalp_`, then a random label of 6 characters, then a random secret of 40 characters. Every character after the prefix is a letter `a` to `z` or `A` to `Z`, or a digit `0` to `9`. The platform stores a digest of the full key, plus the key's first 14 characters in clear: the prefix and the label. The label is not part of the secret. `GET /api/auth/api-key/list` and `GET /api/auth/api-key/get` return those 14 characters to identify the key. A key issued before the label existed has a secret of 16 letters, keeps working, and is identified by the prefix alone.

## Scope: read or read-write [#scope-read-or-read-write]

Every key carries a `scope` of `read` or `read-write`. Every Platform API route declares whether it reads or writes. A `read` key can call routes declared as reads. On a route declared as a write, it receives `DALP-0036` `SESSION_POLICY_DENIED`, HTTP 403, before the handler runs. The platform checks the route's declaration and ignores the HTTP method the request sends.

`DALP-0036` is not a transient failure: retrying with the same key returns the same result. Issue a `read-write` key for that integration, or change the key's scope as [Manage keys](#manage-keys) describes. A key stays bounded by its creator's permissions in the organisation. Changing a key from `read` to `read-write` does not give the creator a wider organisation role.

## Organisation scope [#organisation-scope]

A key carries the id of the organisation it was created for in its metadata. You can create a key only for an organisation you are a member of, and an update can move it only to another such organisation. Naming any other organisation returns 400 `API_KEY_METADATA_INVALID` and stores nothing. The platform reads the organisation from the key and scopes every request the key makes to it, so the caller does not repeat an organisation id on each request.

A key with no organisation is one whose `metadata` gives the platform no organisation to read: it is `null` or has no `organizationId`. Only a key created before the platform required an organisation can be one. Such a key works on the [`/api/auth` routes that accept a key](#api-keys-on-apiauth-routes), where its only write is deleting itself. It is not held to one organisation there: on `get-full-organization`, `list-members` and `has-permission` it reads the organisation the request names, which can be any organisation its holder is a member of. A request that names no organisation gets `null` from `get-full-organization` and 400 `NO_ACTIVE_ORGANIZATION` from `list-members` and `has-permission`. On `/api/v2` it does not authenticate: a route that needs a caller answers `DALP-14386`, HTTP 401. A key with no organisation keeps working when its holder leaves an organisation. A ban, an account closure or an administrator's revoke stops it, and a password change turns it off until its holder turns it on again, as [What stops a key](#what-stops-a-key) lists.

A key whose `metadata` names an organisation but has a `scope` other than `read` or `read-write` was created before the platform checked the scope. It has an organisation: on the `/api/auth` routes that accept a key it is held to the organisation its `metadata` names, like any other key, so naming another organisation on `get-full-organization`, `list-members` or `has-permission` answers 403 `YOU_ARE_NOT_ALLOWED_TO_ACCESS_THIS_ORGANIZATION`, and `GET /api/auth/organization/list` and `GET /api/auth/api-key/list` return only that organisation and your keys for it. On `/api/v2` it does not authenticate: a route that needs a caller answers `DALP-14386`, HTTP 401. Set its `scope` to `read` or `read-write` with an update, as [Manage keys](#manage-keys) describes, to make it work on `/api/v2`.

The API keys screen in the Console does not list a key whose `metadata` names no organisation, and it lists one with an unknown `scope` under the organisation its `metadata` names, as Read. Its holder finds a key with no organisation with `GET /api/auth/api-key/list` from a signed-in session, which returns its `metadata` as `null` or without an `organizationId`. The holder deletes it with `POST /api/auth/api-key/delete`, from that session or from the key itself with its id as `keyId`. To keep an integration that uses it working, create a key for the integration's organisation and move the integration to the new key before you delete the old one, as [Store and rotate a key](#store-and-rotate-a-key) describes. On [Platform users](https://docs.settlemint.com/docs/console/platform-admin/users#revoke-a-persons-api-keys), a platform administrator sees it in the holder's "API keys" section with a dash under Organisation, and a key with an unknown `scope` shows a dash there too. **Revoke all API keys** there deletes it with the holder's other keys.

## API keys and delegated authority [#api-keys-and-delegated-authority]

An API key identifies the caller. [Delegated Authority](https://docs.settlemint.com/docs/concepts/compliance-and-identity/delegated-authority) lets an entitled caller act in another participant's context. An API-key request can send `X-Participant`, the header that names the participant to act for, when the key's user holds the required authority. The key does not grant that authority by itself.

Without that header, an API-key request uses the acting participant selected for its user in the key's organisation: the person, organisation or account record whose authority the user acts with. After you select another acting participant, requests with the same key use that selection within 30 seconds.

## What stops a key [#what-stops-a-key]

A key is a credential of its own, separate from the user's sign-in. Most actions that end a person's sessions leave the person's keys working. Each Platform API server keeps a key's resolved identity for up to 30 seconds, so a change that stops a key can take that long to reach every server, or 35 seconds for a change to the holder's memberships.

| Event | Effect on the user's keys |
| --- | --- |
| The key's expiry passes | The key stops authenticating at that instant. |
| The holder turns the key off or deletes it | The key stops authenticating within 30 seconds. |
| A password changes: the holder's own, an emailed-link reset, or one a platform administrator sets | Every key the user holds, in every organisation, is turned off before the new password is stored: its `enabled` field becomes `false`. The holder can enable each one again. When the platform cannot reach the key store to turn them off, it refuses the change with 503, a platform error you can retry, and the old password stays in force. |
| The holder leaves the key's organisation, or is removed from it | The key stops authenticating within 35 seconds. Its record stays unchanged. A key with no organisation is not stopped: it keeps authenticating on the `/api/auth` routes that accept a key, and reads only the organisations its holder still belongs to. |
| A wallet security change starts the holder's cooling-off period | The key keeps authenticating. A request that would need wallet verification returns 403 `WALLET_VERIFICATION_HELD` until the period ends. |
| A platform administrator bans the holder | The key stops authenticating within 30 seconds: `/api/v2` answers 401, and the `/api/auth` routes that accept a key answer 401 `KEY_DISABLED`. It works again within 30 seconds of the ban being lifted or a timed ban ending. Its record stays unchanged. |
| A platform administrator closes the holder's account | The key stops authenticating within 30 seconds, with the same 401 answers as a ban. A closed account stays closed, so the key does not work again. |
| A platform administrator revokes the holder's keys | Every key the user holds, in every organisation, is deleted and stops authenticating within 30 seconds. It cannot be turned on again. The administrator uses **Revoke all API keys** on the user's page under [Platform users](https://docs.settlemint.com/docs/console/platform-admin/users#revoke-a-persons-api-keys), which calls `POST /api/auth/admin/revoke-user-api-keys` with the user's id. |
| A platform administrator ends the holder's sessions | No effect. The key keeps authenticating. For a password the administrator sets, see the password change row. |

A write that a key submits for maker-checker approval runs as the key's holder once it is approved. If by then the key is revoked, turned off, expired or read-only, or its holder is banned or no longer a member of the organisation, the approved write does not run.

## Manage keys [#manage-keys]

| Operation | Route | Notes |
| --- | --- | --- |
| List | `GET /api/auth/api-key/list` | Returns metadata for your keys. Secret values are never included. |
| Read one | `GET /api/auth/api-key/get` | Returns metadata for the key named by id: expiry, `enabled`, rate-limit settings, request count and last request time. |
| Update | `POST /api/auth/api-key/update` | Changes the name, the metadata with its `scope` and organisation, the expiry, or `enabled`. Read the returned record to confirm the change. |
| Delete | `POST /api/auth/api-key/delete` | Deletes the key. It stops authenticating within 30 seconds. Issue a new key if the integration still needs access. |

Create and update need a signed-in session. List and read one also accept an API key. An update that only renames a key or sets `enabled` to `false` needs nothing more, even during the cooling-off period. Any other update, such as enabling a key or changing its scope, organisation or expiry, needs the same `walletVerification` block as create, is refused with the same errors, and emails the account holder. An update that sends no `metadata` keeps the key's organisation and scope. An update can set a new expiry of up to 365 days from the update, or `null` to remove the expiry. It can also enable a key again. Extend a key before it expires: the platform deletes the records of expired keys as keys are listed, read, created, updated or deleted, so an expired key soon has no record to update. For a key that has already expired, issue a new key.

Delete accepts a signed-in session, which can delete any key its user holds, or an API key that names itself as `keyId`. An API key that names any other key gets 403 `API_KEY_DELETES_ONLY_ITSELF`, and that other key keeps working. No user can delete another user's key.

Turning a key off is the reversible way to retire it. The record survives and the secret stops working, and enabling it again restores the same key, so the integration resumes without a redeploy. Deleting is permanent, and the right step once you know the secret has leaked.

The server that handles the change drops its copy of the key's identity at once, and every other server reads the record again when its copy runs out, so nothing has to be restarted for the cut-off to hold. A key turned off or deleted fails with `DALP-14386` no later than 30 seconds after the change lands.

Read a key's own record before you conclude that an integration lost its secret. The caller sees the same `DALP-14386` when a key is expired, turned off or unknown, has no organisation or an unknown `scope`, or has a holder who left its organisation. A turned-off key's record shows `enabled: false`, and a key with no organisation shows `metadata` that is `null` or has no `organizationId`, and a key with an unknown `scope` shows a `scope` other than `read` or `read-write`. An expired key's record is deleted soon after it expires, so a key that `GET /api/auth/api-key/list` does not return has expired or been deleted.

## API keys on `/api/auth` routes [#api-keys-on-apiauth-routes]

The `/api/auth` routes accept an API key on these nine routes only:

- `GET /api/auth/get-session`
- `GET /api/auth/organization/list`
- `GET /api/auth/organization/get-full-organization`
- `GET /api/auth/organization/list-members`
- `POST /api/auth/organization/has-permission`
- `GET /api/auth/api-key/list`
- `GET /api/auth/api-key/get`
- `POST /api/auth/api-key/delete`, for the presenting key only
- `GET /api/auth/passkey/list-user-passkeys`

A key reads only the organisation it was created for on these routes. `GET /api/auth/organization/list` returns that one organisation, and `GET /api/auth/api-key/list` returns only your keys for that organisation, with `total`, `limit` and `offset` counting that list. A signed-in session still lists all of your organisations and keys.

A key on any other `/api/auth` route receives `API_KEY_NOT_SUPPORTED_ON_ROUTE`, HTTP 403, before the route runs. The refusal covers routes that need no sign-in, `POST /api/auth/sign-out`, and any path the [v2 API reference](https://docs.settlemint.com/docs/api-reference/v2) does not list. The same request with a signed-in Console session still works. A key therefore cannot create or update a key, approve a device sign-in, register a passkey or sign in. The API reference lists eight of the nine routes. It leaves out `GET /api/auth/organization/list-members`, which accepts a key, because `GET /api/v2/users` lists the same members.

On `get-full-organization`, `list-members` and `has-permission`, a key with an organisation reads only that organisation. A request that names another organisation by `organizationId`, or by `organizationSlug` on the two `GET` routes, receives `YOU_ARE_NOT_ALLOWED_TO_ACCESS_THIS_ORGANIZATION`, HTTP 403, even when the key's holder is a member of that organisation. A request that names no organisation reads the key's organisation. A key with no organisation reads any organisation its holder is a member of that the request names, as [Organisation scope](#organisation-scope) describes.

## Rate limit [#rate-limit]

A key that the platform creates is not rate limited. Each key stores whether its limit is on, the length of its window, and how many requests that window admits. A key created through the Console, `dalp login` or `POST /api/auth/api-key/create` stores a 60-second window that admits 10,000 requests, with the limit off. No API call switches the limit on, so limit an integration by its scope and expiry instead. Only a key whose record has the limit on is counted. Read the record with `GET /api/auth/api-key/get`: `rateLimitEnabled` says whether the limit is on, `rateLimitMax` and `rateLimitTimeWindow` give the budget and the window in milliseconds, `lastRequest` shows the last accepted request, and `requestCount` counts the requests in the current window only while the limit is on.

The count belongs to that key alone. Separate keys for separate integrations get separate budgets rather than sharing one ceiling across the organisation or the user.

The count resets only after a full window passes with no accepted request, so continuous traffic does not receive a fresh budget every minute. A refused request is not counted and does not extend the window.

A request over the key's limit receives HTTP 429 with this body:

```json
{
  "code": "auth.apikey.THROTTLED",
  "status": 429,
  "message": "This API key filled its request window",
  "data": {
    "id": "DALP-12136",
    "why": "This key used its full request allowance for the current window, so the platform did not authenticate the request.",
    "fix": "Wait for the key's request window to reopen, then send the request again.",
    "retryable": false,
    "category": "permission"
  }
}
```

The body sets `retryable` to `false` because an immediate retry meets the same refusal, not because the key is spent. The response carries no `Retry-After` header. Stop sending requests with that key, then retry once the window has reopened. In the key's record, `lastRequest` plus `rateLimitTimeWindow` marks when that happens.

The platform counts requests in memory on each API server and writes the count to the database in batches, so a request does not wait for a database write. With a limit of N requests, a key admits at most N requests plus 50 for each server beyond the first. Each server can admit up to 50 requests beyond its share before it reconciles with the stored count, and a single server enforces N exactly.

The key's last-used time updates within about a second of an accepted request. It records when the platform wrote the batch, so it can trail the request by up to about a second.

## Store and rotate a key [#store-and-rotate-a-key]

Store the secret value in a secrets manager or environment variable, not in source control or a shared document. Rotate a key by creating a replacement, updating your integration to use it, then deleting the old key once the new one works. The platform does not roll a key's secret value in place: delete and recreate instead.

## Error codes [#error-codes]

Errors a request authenticated with an API key can receive on `/api/v2`:

| Code | HTTP | What the platform observed | What to do |
| --- | --- | --- | --- |
| `DALP-14386` `AUTHENTICATION_REQUIRED` | 401 | No `X-Api-Key` header, or a key that is unknown, deleted, turned off, expired, without an organisation, or held by a user no longer in its organisation. | Do not retry with the same key. Read the key's record with a session, then enable it or issue a new key. |
| `DALP-0036` `SESSION_POLICY_DENIED` | 403 | A `read` key called a route declared as a write, or a key called a route that accepts only a session. | Do not retry. Use a `read-write` key, or call the route with a Console session. |
| `DALP-12136` `auth.apikey.THROTTLED` | 429 | The key filled its own request window. | Stop sending with the key, then retry after `lastRequest` plus `rateLimitTimeWindow`. Retrying at once fails again. |
| `DALP-17440` `WALLET_VERIFICATION_HELD` | 403 | The key's holder is in the cooling-off period after a wallet security change, and the request needs wallet verification. Nothing was stored. | Wait until `data.heldUntil`, or the number of seconds in `data.retryAfterSeconds`, then send the request again. |
| `DALP-0009` `SESSION_RESOLUTION_FAILED` | 503 | The key store did not answer, so the platform could not resolve the caller. | Retry with backoff. The key itself is not at fault. |
| `DALP-14124` `AUTH_STORE_ROW_INVALID` | 500 | A stored user, membership or key row behind the key does not have the expected shape. | Do not retry. Contact support with the `X-Request-Id` response header. |

Errors the key management routes under `/api/auth` return:

| Code | HTTP | When it happens | What to do |
| --- | --- | --- | --- |
| `API_KEY_NOT_SUPPORTED_ON_ROUTE` | 403 | The key called an `/api/auth` route outside the nine that accept a key. | Call that route with a signed-in Console session. |
| `API_KEY_DELETES_ONLY_ITSELF` | 403 | A key asked to delete a key other than itself. | Delete the other key from a signed-in session of its holder. |
| `API_KEY_NEEDS_CONSOLE_SIGN_IN` | 403 | The Console signs in only through an identity provider, and a create was sent with an Investor portal session. | Sign in to the Console and create the key there. Nothing was stored. |
| `API_KEY_METADATA_INVALID` | 400 | The `metadata` is missing from a create, is not an object, lacks a valid organisation id, names an organisation you are not a member of, or has an unknown scope. | Send `metadata` that names an organisation you are a member of, with a `scope` of `read` or `read-write` or no `scope`. Nothing was stored. |
| `NAME_REQUIRED` | 400 | A create sent no `name`, or a name of only spaces. | Send a name that is not blank. Nothing was stored. |
| `INVALID_NAME_LENGTH` | 400 | A name is longer than 32 characters, or an update sent a name of only spaces. | Send a name of 1 to 32 characters. No key was created or changed. |
| `EXPIRES_IN_IS_TOO_LARGE` | 400 | `expiresIn` is longer than 365 days. | Send a shorter expiry, or omit it for a key that never expires. |
| `SERVER_ONLY_PROPERTY` | 400 | The call set a rate-limit, request-budget or permission field. | Remove the field. |
| `WALLET_STEP_UP_REQUIRED` | 400 | A create or power-raising update carried no `walletVerification`. | Send the wallet proof. |
| `WALLET_STEP_UP_STRONGER_FACTOR_REQUIRED` | 400 | The account holds an authenticator, and the proof was a PIN or recovery code. | Send the authenticator code named in `required`. |
| `WALLET_VERIFICATION_INVALID_CODE` | 400 | The wallet code was wrong. `remainingAttempts` says how many tries are left before the lock. | Send the correct code. Nothing was stored. |
| `WALLET_CREDENTIAL_LOCKED` | 429 | Too many wrong wallet codes in a row. | Wait the seconds in `retryAfterSeconds`, then send a correct code. |
| `WALLET_STEP_UP_UNAVAILABLE` | 401 | The account has no wallet factor. | Set up a PIN on the Console's Security page, then retry. |
| `WALLET_STEP_UP_HELD` | 403 | The holder is in the cooling-off period after a wallet security change. | Wait until `heldUntil`, then retry. |
| `LOGIN_TWO_FACTOR_REQUIRED` | 403 | `enforce2fa` is on and the account has not set up two-factor sign-in, unless it signs in only through an identity provider. Applies to a create and a power-raising update. | Set up two-factor on the Console's Security page, then retry. |

These are the auth layer's own codes. They come from the routes under `/api/auth` and carry no `DALP-####` id, so match on the code string. Platform API routes answer with the catalogued `DALP-` codes, whose full entries and recovery copy are on the [DALP error index](https://docs.settlemint.com/docs/api-reference/errors).

## Next steps [#next-steps]

- [Pagination](https://docs.settlemint.com/docs/api-reference/guides/pagination) covers listing resources once you can authenticate.
- [Errors](https://docs.settlemint.com/docs/api-reference/guides/errors) covers the full error envelope and how to branch your integration on it.
- [Install and set up the command-line tool](https://docs.settlemint.com/docs/api-reference/cli/install) covers `dalp login`, which creates a `read-write` key through a browser device-code flow instead of a direct API call.


# Bank rail API

Source: https://docs.settlemint.com/docs/api-reference/guides/bank-rail
The routes that connect a bank over FIX, link the reserve token, resolve parked credits, pay out cash-outs in both supply modes and explain reconciliation gaps.

## Follow payment statuses with webhooks [#follow-payment-statuses-with-webhooks]

An endpoint on the link's System and chain subscribes to `bank-rail.credit.*` and `bank-rail.cash-out.*` to follow committed milestones. The default state subscriptions skip these names. Credits report admission, minting's completed outcome, a hold and its resolution, or a full cancellation or recall. Approvals and submissions send no intermediate event. Cash-outs report requested, instructed, paid, returned or released. See the [event catalogue](https://docs.settlemint.com/docs/api-reference/webhooks/events#bank-rail) for the exact status rules and the [accounting feed](https://docs.settlemint.com/docs/api-reference/guides/accounting-feed#bank-rail-events) for decimal amounts and posting decisions.

## Overview [#overview]

The bank rail keeps a reserve token in step with money at a bank. It credits a client's wallet when a bank transfer reaches the organisation's reserve account, the bank account that backs the token, and pays a client's redemption back to their bank account. The platform talks to the bank over FIX, the Financial Information eXchange messaging protocol. Its FIX counterparty is the bank FIX simulator that runs inside the platform or, in `external` mode, your bank's FIX acceptor, as [Set up a connection](#set-up-a-connection) describes. The bank rail routes sit under `/api/v2/bank-rail/connections`, except the rail wallet routes under `/api/v2/bank-rail/rail-wallet` and the routes a participant calls for their own account under `/api/v2/users/me`. The [Console guide](https://docs.settlemint.com/docs/console/asset-lifecycle/bank-rail) shows the same flows on screen.

Every `/api/v2/bank-rail` route requires the Bank rail manager role on the wallet the request acts through. Paths in the tables are relative to `/api/v2/bank-rail`, and paths that start with `/users/me` are relative to `/api/v2`. The participant's own writes, `POST /users/me/bank-accounts` and `POST /users/me/bank-cash-outs`, need the participant's signed-in session, and an API key is refused.

A client follows their own money in the Investor portal instead of calling these routes: the Deposit dialog's By bank transfer method shows where to pay, Transfers lists each bank payment and cash-out, and Account > Bank accounts, in the Investor portal or the Console account menu, holds the payout accounts. The two participant reads behind those screens are `GET /users/me/bank-deposits` and `GET /users/me/bank-cash-outs`.

The Console shows the same records on the tabs of a bank rail token. Each action calls the route in the tables below, and a refusal appears as its own message.

- **Payments** lists each recall's state and opens a recall sheet with the actions the recall's state allows.
- **Cash-outs** marks a returned payout and links to its re-credit.
- **Settings** shows the credit threshold and the mint cap, and a pending limit request with "Approve" and "Reject".

A bank account always needs a manager other than its proposer to approve it, and so does the execution or abandoning of a recall. The other decisions on this page wait for a second manager only while the `bank-rail` family of the approval policy, the organisation's per-area maker-checker switch, is on. The family is off by default and is set at `PUT /api/v2/operations/approval-policy` or under **Approvals** in the organisation's General settings. It covers:

- a cash-out over the checker threshold
- a credit over the credit threshold
- a parked-credit resolution
- a reserve adjustment
- a raised credit threshold or mint cap
- the completion or abandoning of a rail wallet rotation

With the family off, each of these goes ahead without a second manager, and the platform records that the approval policy waived it. A rotation's abandon or completion then runs on the next read of the rotation, and a raised mint limit still needs your wallet verification. With the family on, the manager who proposed a request cannot decide it, and a decision from an impersonated session is refused with `impersonated-session`. When the family's approval count is greater than 1, that many different people must approve each request, and each of them must be an organisation owner.

The setup writes (connections, the logon password, token and client links, client accounts, escrows and rail wallet rotations) are administration changes in the **Custody administration** group. While the approval policy protects that group, each one is held until another owner approves it, as [General settings](https://docs.settlemint.com/docs/console/organisation-settings/general#approvals) describes.

`POST /connections/{connectionId}/cash-outs`, `POST /users/me/bank-cash-outs`, `POST /rail-wallet/rotations` and `POST /connections/{connectionId}/daily-reconciliations` honour an `Idempotency-Key`, and a cash-out on a `delegate` link, one of the two supply modes that [Link the reserve token](#link-the-reserve-token) describes, requires one. The other writes are not replayed by key. [Idempotency and async settlement](https://docs.settlemint.com/docs/api-reference/guides/idempotency-async-settlement) explains the contract.

The routes form the `bankRail` operation group of the Platform API. The SDK exposes them in the generated route tree, as [Calling routes](https://docs.settlemint.com/docs/api-reference/sdk/calling-routes) describes. The CLI derives a command from each route path by the verb-first rule: `GET /api/v2/bank-rail/connections` is `dalp get bank-rail connections`. Run `dalp get bank-rail --help` to list the commands your build has, as [CLI commands](https://docs.settlemint.com/docs/api-reference/cli/commands) explains. Refusals use the bank rail codes `DALP-14113` to `DALP-14123`, `DALP-14126` to `DALP-14138`, `DALP-14391` for credit resolutions, `DALP-14422` to `DALP-14424` for cash-outs, and `DALP-14139` and `DALP-14140` for [daily reconciliation](#daily-reconciliation) reads and runs. The escrow routes refuse with `DALP-9701` to `DALP-9703`. All are listed in the [error index](https://docs.settlemint.com/docs/api-reference/errors).

Activating a connection shows the three surfaces side by side:

```bash
curl -X POST "https://your-instance.example.com/api/v2/bank-rail/connections/$CONNECTION_ID/transitions" \
  -H "X-Api-Key: sm_dalp_..." -H "Content-Type: application/json" \
  -d '{ "transition": "activate" }'

dalp create bank-rail connections transitions "$CONNECTION_ID" --transition activate
```

```ts
await dalp.api.bankRail.connectionTransition({
  connectionId,
  transition: "activate",
});
const connections = await dalp.api.bankRail.connectionsList();
```

The activation answers `200` with the connection:

```json
{
  "id": "0b7f5c1e-3d2a-4c8e-9f61-5a2e7d4b8c90",
  "organizationId": "org_7Hq2kWm9",
  "senderCompId": "DALP-ISSUER",
  "targetCompId": "RESERVEBANK",
  "reserveAccount": { "accountId": "AE070331234567890123456", "currency": "AED" },
  "matchingMode": "reference",
  "bankName": "Reserve Bank",
  "allowedMessages": {
    "inbound": ["credit", "balance-report", "execution-report"],
    "outbound": ["payment-instruction"]
  },
  "payoutDeadlineSeconds": 604800,
  "settlementWindowSeconds": 86400,
  "holidayCalendarId": "adgm",
  "paymentTimeZone": "Asia/Dubai",
  "paymentCutOffTime": null,
  "state": "active",
  "credentialVersion": 1,
  "rowVersion": 3,
  "createdBy": "usr_4Fp8nQx2",
  "createdAt": "2026-11-02T08:14:05.000Z",
  "updatedAt": "2026-11-02T09:02:41.000Z"
}
```

Every other route follows the same mapping: the operation names, such as `cashOutCreate` and `reserveAdjustmentDecision`, are the SDK method names under `dalp.api.bankRail`, and the path gives the CLI command.

## Set up a connection [#set-up-a-connection]

A deployment serves the bank rail routes only when the DALP Helm chart value `global.dalpApp.config.bankFix.enabled` is true. It defaults to `false`, and the environment variable `BANK_FIX_ENABLED` also sets it, so the rail stays off until the operator turns it on. `bankFix.mode` defaults to `simulator`, which runs a FIX simulator inside the platform. The simulator listens on `bankFix.simulator.listenHost` and `bankFix.simulator.listenPort`, which default to `127.0.0.1:9878`. If another process holds that port, the scheduler logs `The bank FIX simulator cannot listen on <host>:<port>, so no bank connection can log on: <reason>`, and its `/readyz` answers `503` with status `bank-fix-simulator-unavailable` and the same reason. The simulator does not try again: free the port, then restart the scheduler pod.

| Step | Route | What it does |
| --- | --- | --- |
| Create a connection | `POST /connections` | Stores a draft with the two FIX CompIDs, the reserve account and its currency, and how credits match (`reference` or `virtual-iban`). These fields never change |
| Change the timing | `PATCH /connections/{connectionId}` | Replaces the bank name, allowed messages, payout deadline and settlement window when `expectedRowVersion` matches |
| Set the logon password | `PUT /connections/{connectionId}/credential` | Stores the logon password, sent in tag 554, when `expectedCredentialVersion` matches. In `simulator` mode the bank's Logon must carry it. In `external` mode the platform's Logon sends it, so set the password your bank issued, and change it only once the bank accepts the new one. A live session ends. The password is never returned |
| Activate or suspend | `POST /connections/{connectionId}/transitions` | Body `{ "transition": "activate" }` or `"suspend"`. Activation is refused while no password is set. Repeating a transition returns the connection unchanged |
| Read or list connections | `GET /connections`, `GET /connections/{connectionId}` | The list takes `filter[q]` and `filter[state]` (`draft`, `active`, `suspended`), sorts by `createdAt` or `bankName`, and pages |

`POST /connections` requires `payoutDeadlineSeconds` and `settlementWindowSeconds`. The Console fills in 604800 and 86400, which are 7 and 1 business days, because both count business time on the connection's holiday calendar. Each takes 60 to 31536000 seconds, and the window must be shorter than the deadline. The rail sends a payment instruction only while the deadline leaves at least the settlement window.

With `bankFix.mode` set to `external`, the platform dials your bank's FIX acceptor, the server end of the bank's FIX link, instead of running the simulator. The scheduler opens one FIX session per active connection to the bank's FIX acceptor at `bankFix.external.host` and `bankFix.external.port`. Every connection dials the same address, and the bank tells the sessions apart by the connection's two CompIDs. The settings take these variables:

| Setting | Variable | Default | What it controls |
| --- | --- | --- | --- |
| `bankFix.external.host` | `BANK_FIX_EXTERNAL_HOST` | none | The bank's FIX acceptor host |
| `bankFix.external.port` | `BANK_FIX_EXTERNAL_PORT` | none | Its port |
| `bankFix.external.tls` | `BANK_FIX_EXTERNAL_TLS` | `true` | Whether the session runs over TLS |
| `bankFix.external.tlsServerName` | `BANK_FIX_EXTERNAL_TLS_SERVER_NAME` | the host | The name the bank's certificate must carry, when it is not the host itself |
| `bankFix.external.openTimeoutMs` | `BANK_FIX_EXTERNAL_OPEN_TIMEOUT_MS` | `10000` | How long opening the TCP and TLS connection may take |
| `bankFix.external.reconnectMinMs` | `BANK_FIX_EXTERNAL_RECONNECT_MIN_MS` | `1000` | The first wait before the scheduler dials again |
| `bankFix.external.reconnectMaxMs` | `BANK_FIX_EXTERNAL_RECONNECT_MAX_MS` | `60000` | The longest wait between attempts |

With the rail enabled in `external` mode, the platform refuses to start in three cases. A missing host or port logs `the external bank FIX mode needs bankFix.external.host and bankFix.external.port`. A `tls` of `false` for a host other than `localhost`, `127.0.0.1` or `::1` logs `the external bank FIX session may only skip TLS to a loopback host`. A `reconnectMinMs` greater than `reconnectMaxMs` logs `bankFix.external.reconnectMinMs must not exceed reconnectMaxMs`. It never falls back to the simulator.

The scheduler checks the bank's certificate against its default certificate authorities and presents no client certificate. The scheduler pods need outbound access to the bank's host and port. One scheduler pod dials the bank at a time, and its `/readyz` answer carries a `bankFix` object: `sessions` counts the active connections it dials, `loggedOn` counts those whose Logon the bank has answered, and `status` is `logged-on` when the two match and `not-logged-on` otherwise. The other pods leave the object out, and so does the dialling pod while no connection is active. A session that is not logged on leaves the pod ready, with `200` and `status` `ok`, because the scheduler keeps dialling on its own, and a restart fixes neither a bank outage nor a refused logon. The scheduler logs `The bank FIX session to the bank ended; reconnecting.` with the connection id and the reason.

Each session follows the profile in [Bank FIX session](#bank-fix-session). A suspended connection gets a Logout within about 10 seconds and is not dialled again. A connection activated later is dialled within about 10 seconds.

### Bank FIX session [#bank-fix-session]

1. The scheduler connects and sends a Logon with `49` set to the connection's `senderCompId`, `56` to its `targetCompId`, `108=30` and the logon password in `554`. It never asks for a sequence reset.
2. The bank answers with its own Logon, with `49` and `56` swapped and no `554`. A Logon numbered below the one the scheduler expected, without `43=Y`, is refused with a Logout naming both numbers, so the bank must keep its sequence numbers across its own restarts. A Logon with `141=Y` restarts both sequences, and messages the scheduler stored earlier can no longer be resent. If no Logon arrives within 30 seconds of the dial, the scheduler closes the socket and dials again.
3. The scheduler sends a Heartbeat after 30 seconds without sending anything, and answers each TestRequest. It ignores the bank's `108` and sends no TestRequest of its own: when the bank sends nothing for 90 seconds, the scheduler sends a Logout with the reason and closes.
4. After any close, the scheduler waits before it dials again: `reconnectMinMs` the first time, then twice as long after each attempt, up to `reconnectMaxMs`. An attempt that lasted at least `reconnectMaxMs` from its dial starts the wait at `reconnectMinMs` again. Each close logs `The bank FIX session to the bank ended; reconnecting.` with the reason and the attempt number.
5. Sequence numbers in both directions are stored, so a reconnect or a restart carries on from them. When the bank's Logon carries a number higher than the one the scheduler expected, the scheduler sends a ResendRequest from the expected number to `0`, the end of the bank's stream. A later gap gets a ResendRequest from the expected number to the one before the message that arrived. When the bank asks for a resend, the scheduler sends its stored credit acknowledgements, reversal acknowledgements and payment instructions again with `43=Y` and the original sending time in `122`, and covers its session messages with gap fills, `35=4` with `123=Y`. The scheduler keeps the newest 4096 of those messages it sent, up to 16 MiB, for each connection. A resend of an older one gets a gap fill.
6. A change of the logon password ends the session within about 10 seconds. The next Logon carries the new password.

## Link the reserve token [#link-the-reserve-token]

A connection links one token for its reserve currency. A token is linked to one connection.

`GET /connections/{connectionId}/token-link-candidates` lists the tokens this connection can link, each with `token`, `name`, `symbol` and `decimals`. A token is listed when step 1 below would accept it: the connection has no link, no connection of the organisation links the token, the token has no supply, its decimals cover the currency and the rail wallet can mint it. The list is empty for a connection that already has a link.

1. `POST /connections/{connectionId}/token-links` with `token` (the address) and `checkerThreshold`, an amount in the currency's minor units. While the `bank-rail` approval family is on, a cash-out waits for a second manager when it, added to the client's other cash-outs on the link from the last 24 hours that were not released, comes to more than `checkerThreshold`. An optional `creditCheckerThreshold` holds large credits for approval before they mint, as [Approve a credit before it mints](#approve-a-credit-before-it-mints) describes. Creating the link is refused for a token that already has supply. The link starts `pending-role` and changes nothing on the token.
2. Optionally, `POST /connections/{connectionId}/token-links/{tokenLinkId}/activation/preflights` with no body runs the checks activation runs, signs nothing and asks for no wallet verification. It answers `200` with the next `action`: `grant-supply-role` (booked) or `add-supply-delegate` (delegate) when activation would grant the authority, `activate` when the rail wallet already holds it, `reinstate` for a suspended link that passes its checks, and `none` for an active link. Otherwise it answers the same `422` `bankRail.tokenLink.REFUSED` that activation would answer, with the same `data.reason` and `data.accounts`. Call it before you ask for wallet verification, and poll it after a grant until it answers `activate`.
3. `POST /connections/{connectionId}/token-links/{tokenLinkId}/activation` with wallet verification. Your wallet grants the rail wallet the token's supply authority, so you need the token's admin role in `booked` mode or its governor role in `delegate` mode. The call returns the link still `pending-role` while the grant settles. Call it again once DALP sees the grant on the chain, and the link becomes `active`. It is refused when the token has supply, when any other account holds supply authority (another supply management role holder or supply delegate, and in delegate mode any role holder at all), or when the rail wallet has no gas or cannot hold the token. The checks stop at the first failure, so a refusal names one cause and, for holders, the accounts. With reason `supply-role-held`, a token admin revokes the role from the accounts in `data.accounts`. With `supply-delegate-held`, a token governor removes them as delegates.
4. `DELETE /connections/{connectionId}/token-links/{tokenLinkId}` removes a link that is still `pending-role` and has no clients and no open mint-limit request or request to let other accounts manage supply. An `active` or `suspended` link is refused with reason `state`.

On a `booked` link, send `{ "transition": "update-supply-managers", "allowOtherSupplyManagers": true }` to the token link transitions route to let accounts other than the rail wallet that hold the token's supply management role book movements. The link reads `allowOtherSupplyManagers` (off at creation), `supplyManagers` (the other holders, read from the token, each with the time the grant was indexed) and `supplyManagersRequest` while a request is open. Turning it on opens a `bank-rail-supply-managers` approval that another bank rail manager decides on the decisions route. A second change while one is open is refused with reason `supply-managers-pending`. The transition on a `delegate` link is refused with reason `supply-managers-delegate`. While the `bank-rail` approval family is off, turning it on still needs wallet verification, applies at once and stores a waived record. Turning it off applies at once. While it is on, activation, re-activation and the pre-mint check require only that the rail wallet still holds the role. The reconciliation reserve line explains a payout another account booked before the bank paid as `bookedAheadOfPayment` until the payment settles. A cash-out another account booked reads that account as `bookedBy`. When the bank then does not pay, a critical operations case names the account and the amount.

The link's supply mode is fixed at creation from the token's features:

| Token has | Supply mode | Activation does | Cash-outs use |
| --- | --- | --- | --- |
| Booked movements with the Hold feature, and redemptions a holder can request | `booked` | Grants the rail wallet the supply management role | The client's redemption line |
| The supply delegate feature, no booked movements | `delegate` | Adds the rail wallet as the only supply delegate, allowed to mint and burn up to the link's `expectedMintCap`, or with no cap | An escrow the rail wallet controls |

Both modes need a DALP custodian token that the organisation issued. Any other token is refused. The token's decimals must represent every minor unit of the currency exactly, so a EUR token needs at least two decimals. A token that fails these rules is refused with `data.reason` `not-custodian`, `not-issued`, `needs-hold`, `redemption-not-requestable`, `needs-supply-delegate` or `decimals`. A token another connection links is refused with `token-linked`, a second token on the connection with `currency-linked`, and a token with supply with `supply-not-zero`.

## Add clients and bank accounts [#add-clients-and-bank-accounts]

- `POST /connections/{connectionId}/client-links` links a participant and one of its wallets. On a `reference` connection DALP generates the payment reference. On a `virtual-iban` connection send `virtualIban`. `DELETE` on a client link removes it, and is refused while the client has a proposed or active bank account (`accounts-live`) or a credit still delivering to its custody gateway (`deliveries-open`).
- `POST /connections/{connectionId}/client-links/{clientLinkId}/accounts` proposes a payout account: an IBAN, or an account number with the bank's identifier, the holder name and the bank. A participant proposes one for their own client link at `POST /users/me/bank-accounts`.
- `POST /connections/{connectionId}/client-accounts/{accountId}/decisions` takes `{ "action": "approve" }`, or `refuse` or `revoke` with a `reason`. The manager who proposed the account cannot approve it. A refused or revoked account stays listed with its reason. Revoking releases a cash-out the bank has not been instructed to pay.

`GET /connections/{connectionId}/client-links` lists the client links of a connection. `GET /connections/{connectionId}/client-accounts` lists every account of the connection, and `GET .../client-accounts/{accountId}` reads one. A participant lists their own accounts at `GET /users/me/bank-accounts`. Each list pages with `page`.

A cash-out pays only to an `active` account.

A bank rail manager can make the reads that setup needs without also holding the system manager, identity manager or claim issuer role. `GET /api/v2/participants` lists the organisation's members as `person` participants beside the asset and add-on participants. `GET /api/v2/participants/{participantId}/wallets` lists the wallets of a member's participant, and an entity participant's wallets cannot be listed. `GET /api/v2/system/wallets/{wallet}/identity` reads the identity of the organisation's own rail wallet. Registering that identity stays with an identity manager.

## Follow and resolve credits [#follow-and-resolve-credits]

`GET /connections/{connectionId}/credits` lists every credit the bank reported, newest first, and `GET .../credits/{creditId}` reads one. A credit mints once to the matched client. When it matches no client or the token blocks the wallet, it mints to the rail wallet instead and waits there as suspense, a balance held for a manager's decision. A credit that cannot complete is parked, and each parked credit has an operations case, the record of a problem that the platform cannot resolve automatically.

`POST .../credits/{creditId}/transitions` takes one of these bodies:

| Body | Effect |
| --- | --- |
| `{ "action": "retry" }` | Mints again a credit that parked before anything minted, or sends again a failed gateway delivery |
| `{ "action": "allocate", "clientLinkId": "..." }` | Asks to move the suspense to a client. `clientLinkId` is needed when the credit matched no client, or when the link it matched was removed. It must then be a link of the same client, and another client's link is refused with `client-mismatch` |
| `{ "action": "return-to-payer", "refundReference": "..." }` | Asks to burn the suspense under the bank's refund reference |

A manager other than the requester decides the open request with `POST .../credits/{creditId}/decisions` and `{ "action": "approve" }` or `"reject"` with its `approvalId`. A refused request or decision answers `409 bankRail.credit.RESOLUTION_REFUSED`, and `data.reason` names the cause, for example `proposer-cannot-approve` when the requester tries to decide it. While the `bank-rail` approval family is on, an allocation or a return puts the credit in `awaiting-checker`. With it off, the resolution starts at once. Approving moves or burns the tokens exactly once. Rejecting leaves the credit parked. In `delegate` mode an allocation is a plain transfer from the rail wallet, and a return burns through the supply delegate.

### Switch a client to gateway delivery [#switch-a-client-to-gateway-delivery]

A client link delivers to the client's wallet until two bank rail managers switch it. The link read carries `delivery`: the `target` (`wallet` or `gateway`), the open `request` (or `null`), the `lastCheck` and the `rowVersion`.

- `POST /connections/{connectionId}/client-links/{clientLinkId}/transitions` takes `{ "transition": "enable-gateway-delivery", "rowVersion": 3 }`. The rail reads the client's gateway and checks it, stores each check by name in `lastCheck`, and opens a delivery request that another bank rail manager decides. The credits keep minting to the wallet until then. A gateway that fails a check is refused `preconditions-failed`, and each failed check names the fix. A token in booked mode (`booked-mode`), a request already open (`delivery-request-open`) and a `rowVersion` the link has moved past (`row-version`) are refused too. When the gateway cannot be read the call answers a retryable `503`.
- `POST /connections/{connectionId}/client-links/{clientLinkId}/decisions` takes `{ "decision": "approve", "approvalId": "..." }` or `"reject"` with an optional `reason`. The manager who opened the request cannot decide it (`same-actor`). An approval reads the gateway again: when every check still passes, `delivery.target` becomes `gateway`. Otherwise the request is withdrawn and cleared, a warning case is raised and the approval is refused `delivery-stale`. A rejection keeps delivery on the wallet. A request nobody decides in seven days closes the same way.
- The same `transitions` route with `{ "transition": "disable-gateway-delivery", "rowVersion": 4 }` sends the client's future credits back to the wallet at once and withdraws an open request. Credits whose mint already settled keep delivering.

### Credits for a custody gateway client [#credits-for-a-custody-gateway-client]

A credit for a client that takes delivery through a custody gateway mints to the rail wallet, never to the client's wallet, and the credit reads `minted` with a `delivery` object. Before minting, the rail checks the gateway. A failing check parks the credit as `delivery-blocked` with nothing minted, and the case names the check. Fix the gateway, or switch the client to wallet delivery, then send `{ "action": "retry" }`. When the gateway cannot be read, the credit stays `admitted` and the rail tries again on its next pass.

`delivery` is `null` for a credit that mints to the client's wallet. Otherwise it names the `gateway` and its `receiptToken`, the `lastCheck` the rail read before minting, and `state`. `state` is `null` while the mint is being submitted and `minted-undelivered` once the coins wait in the rail wallet to be sent, with `amount` in the token's smallest units. Such a credit counts in the reconciliation as `inTransit`, not as suspense. It cannot be allocated or returned to the payer while it is delivering, and it cannot be recalled while its send is being submitted.

The rail then sends the coins from the rail wallet to the gateway, after checking the gateway again. While the send is submitted `state` reads `sending`. Once it is mined it reads `sent-unreported`, with the `transactionHash` and `logIndex` of the transfer. A gateway the rail cannot read, or one that is only paused, holds the send for the next pass under a `screening-outage` case, and no attempt is spent. Any other failing check, a gateway that changed since the mint, or a send the token refuses, that is dropped or that reverts, leaves `state` at `send-failed` with a critical case.

Send `{ "action": "retry" }` to send a `send-failed` credit again under its next attempt. The credit's `attempts` counts them. The rail first reads the failed send. When its transfer to the gateway landed after all, the credit is recorded as `sent-unreported` and nothing is sent twice. The retry is refused with `409` `RETRY_REFUSED`, and `data.reason` says why:

- `delivery-in-flight`: the last send may still land.
- `recall-open`: the bank's recall of the credit is open.
- `returned-elsewhere`: the gateway paid the coins back to an address other than the current rail wallet, so they cannot be sent again.
- `delivery-not-retryable`: the delivery is in no state a retry can change.

### Where the coins are [#where-the-coins-are]

The rail follows a sent credit to the gateway's deposit, so `delivery.state` tells you where the coins are. It looks the deposit up by the `transactionHash` and `logIndex` of the send, then by its `depositId`. The read also carries `gatewayStage`, the gateway's `gatewayStages` with their transaction hashes, and, once the gateway accepted the credit, `receiptsMinted`, `fee` and `receiptRecipient`. The same deposit appears in the gateway's own records as `custody.gateway-deposit.settled`.

- `sent-unreported`: the gateway's keeper has not reported the deposit yet. After 60 minutes the credit reads `unattributed` and a warning case names the usual causes: the keeper is off, the coin is unsupported, the sender is not a funding source, or the transfer shared a transaction with a deposit event. The rail keeps reading.
- `quarantined`: the gateway holds the deposit for screening. After 24 hours a `screening-freeze` warning case opens.
- `refused`: the gateway's receiving rule refused the mint and holds the coins in escrow. A critical case opens at once and names the cause. After the connection's settlement window an overdue case follows. A gateway manager recovers the deposit to the rail wallet.
- `settled`: the gateway accepted the credit. Every case of the credit is resolved.
- `returned`: the gateway paid the coins back, to `returnedTo`. When that is the rail wallet, `retry` sends the credit again with the returned `amount`. Otherwise a critical case names the address and `retry` is refused with `returned-elsewhere`.

A gateway read that fails changes nothing and opens no case.

### Approve a credit before it mints [#approve-a-credit-before-it-mints]

When the token link has a `creditCheckerThreshold`, the rail adds each matched credit to the client's credits of the last 24 hours before it mints. A credit that matched no client is judged on its own amount. While the `bank-rail` approval family is on, a credit above the threshold shows `awaiting-mint-approval` with `mintApproval`, which carries the `approvalId` and its expiry, seven days after the request. It mints nothing until a bank rail manager approves it.

- Approve with `{ "action": "approve", "approvalId": "..." }` on the credit's decisions. The bank's message opened the request, so any bank rail manager can decide it. The credit mints the next time the rail processes credits. A completed wallet rotation drops the approval of every credit on the old wallet that has not minted, because the approval named that wallet, so such a credit is judged again before it mints. A credit the bank is recalling cannot be approved.
- Reject with `"reject"`. A rejected or expired request parks the credit as `mint-unapproved` with a critical case. `retry` asks again with you as requester, so another manager must approve it. `return-to-payer` closes it without a transaction.
- A credit awaiting approval counts in the reconciliation's `pendingIn` and shows as `awaitingApproval`. It is never overdue.

To change the threshold, send `POST /connections/{connectionId}/token-links/{tokenLinkId}/transitions` with `{ "transition": "update-credit-threshold", "creditCheckerThreshold": "..." }`. Setting a first threshold or lowering one applies at once. Raising it, or removing it with `null`, returns the link with `mintLimitRequest` and keeps the old value in force. `mintLimitRequest.requestedBy` names the manager who asked, and a different manager decides. Another bank rail manager decides with `POST .../token-links/{tokenLinkId}/decisions` and `{ "decision": "approve" }` or `"reject"` with the request's `approvalId`. A rejected request, or one that expires after seven days, keeps the old value. While the `bank-rail` approval family is off, the raise still needs the manager's wallet verification, applies at once and stores a waived record instead of a request. A second change while one is open is refused with reason `mint-limit-pending`. A new threshold applies to credits the rail has not judged. A credit already cleared under the old one still mints.

A `delegate` link can also pin the cap the rail wallet mints under, so a stolen rail wallet key cannot mint past it. Pass `expectedMintCap`, in the token's smallest units, when you create the link, and activation adds the rail wallet with that cap. Without `expectedMintCap` the rail wallet mints without a limit. A `booked` link takes no cap, and a cap on one is refused with reason `mint-cap-booked`, because its rail wallet holds the token's supply management role. For those links, [containing the rail wallet](#contain-the-rail-wallet) is the control after a key exposure.

To change the cap later, send `{ "transition": "update-mint-cap", "expectedMintCap": "..." }` to the same transitions route with wallet verification. Your own wallet removes the rail wallet as supply delegate and adds it again with the new cap, so you need the token's governor role. The rail wallet's re-delegation is a queued transaction, so the answer follows the `Prefer` contract of the [async settlement guide](https://docs.settlemint.com/docs/api-reference/guides/idempotency-async-settlement): `200` when the write landed within your `Prefer: wait`, otherwise `202` with the link, its `mintCapReplacement` (`transactionId` and `previousMintCap`) set, and `Location` pointing at `GET /connections/{connectionId}/token-links`. Reading that list settles the replacement against the transaction queue, and so do credit processing, reconciliation and the rail wallet rotation readiness check: it clears `mintCapReplacement` when the write lands and puts `expectedMintCap` back to `previousMintCap` when it fails. A further cap change while `mintCapReplacement` is set is refused with reason `state`. Read the list, then change the cap again.

A first, lower or unchanged cap applies at once, and credits park as `supply-authority` until DALP sees the new delegate on the chain. Raising the cap, or removing it with `null`, opens the same `mintLimitRequest`, and the approving manager's wallet adds the delegate with the new cap. A cap change during an open rail wallet rotation is refused with `rail-wallet-contained`. A `delegate` link lists `outstandingMint`, the units the rail wallet has minted minus those burned, beside `expectedMintCap`, as of the last indexed block, so a client can size a raise before it asks. It is `null` on a `booked` link or when the rail wallet is not an indexed delegate. A credit the token refuses because it would pass the cap parks as `mint-cap`, and its case names the cap, the amount outstanding and the credit's amount. Raise the cap or wait for burns, then `retry` it.

### Screen credits and cash-outs [#screen-credits-and-cash-outs]

Every confirmed deposit, including an unmatched deposit, and every cash-out before its payment instruction, is sent to the AML provider the connection names, as a fiat transaction with its direction, amount, currency and counterparty. The rail records the provider's verdict and alerts on the credit (`screening`) and on a screening row you can list. Each decision also creates a case linked to the investor, with the verdict and alerts. An unmatched deposit uses its transaction reference as the provider's external subject until the investor is identified. The payer of a credit is on the credit as `payer`: the name, account and BIC the bank sent in the FIX deposit message's tags 5001, 5002 and 5003.

`GET` and `PUT /connections/{connectionId}/screening-settings` read and replace how a connection screens:

| Field | Meaning |
| --- | --- |
| `providerId` | The linked compliance provider that screens the connection. `null` turns provider screening off |
| `levelName` | The provider's level for fiat transactions. `null` uses the provider's default |
| `payerAccountCheck` | `true` (the default) parks a credit whose payer account is not one of the client's active bank accounts |
| `expectedRowVersion` | The `rowVersion` you read, or `0` for a connection that never saved settings. Another version answers `409 bankRail.connection.STALE` |

A credit that fails a check parks, and nothing mints:

- `payer-account-not-verified`: the payer account is not an active account of the client, or the bank sent none.
- `aml-rejected` and `aml-held`: the provider's verdict. A score without a verdict reads as held at or above the provider's auto-clear threshold.

For `payer-account-not-verified`, add the payer account and have a different manager approve it before retrying. A mint approval cannot bypass this check. For an AML hold or rejection, `retry` asks for a mint approval with you as requester, and another bank rail manager approves it with `POST .../credits/{creditId}/decisions`. The approval is never waived, whatever the `bank-rail` approval family says, and it records who released the screening. A cash-out the check rejects or holds goes to `awaiting-checker` with an approval naming the original requester as maker, which a different bank rail manager decides with `POST .../cash-outs/{cashOutId}/decisions`.

`GET /connections/{connectionId}/fiat-screenings` lists the screenings of credits and cash-outs, newest first, with `filter[from]` and `filter[to]` as ISO date-times on when the rail first screened the transaction. A bound that is not a date-time answers `400 wire.http.COLLECTION_FILTER_VALUE_INVALID`. Each row carries the counterparty, `payerCheck` (`verified`, `unverified` or `not-required`), `verdict` (`not-screened`, `pending`, `approved`, `held` or `rejected`), the score, the provider's alerts, the provider's reference, the submission and decision times and who released it.

### Recalls [#recalls]

When the bank reverses a credit, it sends a credit reversal over FIX and the rail records a recall against the credit. Add `credit-reversal` to the connection's allowed inbound messages with `PATCH /connections/{connectionId}`, or the session ends on the first reversal.

`GET /connections/{connectionId}/recalls` lists the recalls, newest first, and takes `filter[state]`. `GET .../recalls/{recallId}` reads one, or answers `404` when the connection has no such recall. Each recall names its credit, the bank's reversal id, the amount the bank reversed, the amount in token units and its state. A new recall is `received`: the credit no longer mints, a retry of it is refused, and a critical operations case names the recall.

The rail refuses a reversal when the credit already has an open recall, when its completed recalls cover its full amount, or when the reversal would take back more than the credit. It records nothing and raises a critical case naming the reversal. A reversal of a credit the rail has not seen yet gets no reply, so the bank's resend is recorded once the credit arrives.

### Execute or abandon a recall [#execute-or-abandon-a-recall]

A recall takes tokens back only under maker-checker. Post the transition to `POST .../recalls/{recallId}/transitions`:

- `{ "transition": "request-execution" }` asks another bank rail manager to approve taking the tokens back. The rail works out what it will do from the credit: cancel a credit that has not minted, burn or book from the rail wallet for suspense, wait for a custodian's forced transfers from a delegate client, book a correction from a booked client, or, for a credit the client's custody gateway holds (sent but unreported, unattributed, quarantined, refused or settled and awaiting custody), wait for the gateway to return the deposit to the rail wallet. A credit minted and still unsent, or whose send failed, burns from the rail wallet and lowers the amount still to send, cancelling the delivery when nothing is left. The request is refused, naming the blocker, while the credit's mint is queued, the credit's send to the client's custody gateway is being submitted (`delivery-in-flight`), a park resolution is open, a live cash-out holds the client's tokens, or the rail wallet is contained. A credit settled into receipts is recalled through its receipts, as [Recall a delivered credit](#recall-a-delivered-credit) describes. While the recall is open, a cash-out of that client's tokens is refused with `data.reason` `recall-open` and can be requested again once the recall closes.
- `{ "transition": "abandon", "reason": "..." }` asks another manager to approve ending the recall without taking anything back. The bank's debit stays a reserve difference until a manager records a reserve adjustment.

Either moves the recall to `awaiting-checker`. Decide it with `{ "action": "approve", "approvalId": "..." }` or `"reject"` on `POST .../recalls/{recallId}/decisions`. The requester cannot decide it. Approve recomputes what the request bound and is refused `recall-stale` when the credit moved in between. The recall then returns to `received` with a case. Reject, or an approval that expires, also returns it to `received`.

An approved delegate recall is `clawing`. A token custodian force-transfers the tokens from the client into the rail wallet, the staged wallet during a rotation, and a manager records each transfer with `{ "transition": "record-claw", "transactionHash": "0x...", "logIndex": 0 }`. A transfer made before the approval, of another token, from another wallet or into another wallet is refused `claw-mismatch`, and one another recall already recorded is refused `claw-duplicate`. A transfer in a block the chain has not finalised yet is refused `claw-unfinalized`. Record it again once the block is final. Recording the same transfer again on the same recall returns the recall unchanged. The recall read lists the recorded claws and what the client still holds, free and on the rail's escrow. Claws reaching the recall amount, or `{ "transition": "close-claw" }`, move the recall to `burning`: the rail burns what it recovered once, writes down the rest and completes the recall, then returns any excess to the client. When the client's wallet refuses that transfer, the excess stays in the rail wallet under a warning case and the rail retries every five minutes. A booked recall books one correction from the client to zero against the line that minted the tokens. For a credit the gateway holds, a manager of the gateway returns or recovers the deposit to the rail wallet, and `record-claw` takes that exit's transaction hash and log index. The rail checks that the gateway reports the deposit returned or recovered, that it paid the rail wallet and that the exit's transfer is mined and final. A payment to another wallet is refused `claw-mismatch`. It records what was paid, up to the recall's amount, and lowers the amount the credit still sends by the same.

### Recall a delivered credit [#recall-a-delivered-credit]

A credit whose delivery settled reads `delivery.state` `settled`: the client's custody gateway took the coins and issued receipts for them, which are another token. The rail cannot burn receipts, so it takes them back from the client and turns them into coins at the rail wallet's own custody gateway, then burns the coins. The bank's amount minus what the gateway pays out is written down, so the gateway's deposit fee and withdrawal fee end in the write-down.

Set the rail wallet up as a client of a custody gateway before you need a recall. `request-execution` on a settled credit is refused with `409` (`DALP-14137`) and `data.reason` `recall-gateway-missing` when the current rail wallet cannot redeem there. That happens when it has no on-chain identity, its identity has no custody gateway, it is not a client of that gateway, or it is not an active approved payout address on it. The refusal opens no approval. A gateway manager fixes the named step, then you send the request again. While the rail has not read which wallet holds the receipts, the request is refused `delivery-in-flight`. Send it again once the delivery read shows `receiptRecipient`.

Once the recall is approved it is `clawing`, and its `receiptToken` names the receipt token it takes back. A custodian of the receipt token force-transfers up to the recall amount of receipts from the wallet in `delivery.receiptRecipient` into the rail wallet, and you record each transfer with `record-claw`. A transfer of the link's coin, of another token or from another wallet is refused `claw-mismatch`. When the client has moved some receipts away, record what the custodian could take and send `close-claw`: the rest is written down.

In `burning` the rail redeems the receipts from the rail wallet. It approves the gateway's escrow for the receipts, requests the redemption on the rail wallet's gateway with the rail wallet as receiver, and takes the request id from that transaction. The recall read shows `redemption` with the `gateway`, the rail `wallet`, the request's `stage`, its `requestId`, the `receiptUnits` it redeems and the `paidUnits` the gateway paid. The gateway handles the request as any withdrawal: its managers review it, screening answers when the gateway screens, and the custodian funds the gateway. The rail follows only its own request id. When the request becomes claimable, because auto-claim is off or the keeper's payout failed, the rail claims it. Once the gateway has paid the rail wallet, the rail burns the coins paid, at most the receipts it recorded, and the recall completes.

A request the gateway freezes, holds for a payout address, rejects or pays to another wallet burns nothing. `redemption.stage` reads `failed`, the recall stays `burning` and a critical operations case names the gateway step. Fix it on the gateway, and the recall completes on the next reading that shows the request paid to the rail wallet. Once a rejected request has returned its receipts to the rail wallet, `redemption.stage` reads `approving` again and the rail requests a new redemption of the same receipts after five minutes, for the gateway's managers to review. When the rail wallet's gateway becomes unusable while the recall is `burning`, a critical case opens and the rail tries again after five minutes.

A completed recall reads `recalled` with `recoveredUnits`, `writtenDownUnits` and the burn's `txHash`. The write-down is a `credit-recall` reserve adjustment the rail creates itself, effective at the reversal. A manager cannot propose one. The credit reads `recalled` once its recalls total its amount, and `recalledAmount` otherwise.

## Pay out a cash-out [#pay-out-a-cash-out]

A cash-out instructs the bank to pay a client's active account, then burns the held tokens when the bank reports the payment settled. A rejected or late payment releases the tokens to the client. The rail builds each instruction once, and the instruction id is the cash-out's id, so a resend carries the same id for the bank to recognise.

### Booked mode [#booked-mode]

The client's wallet requests a redemption on the token, which holds the tokens on a redemption line. A manager lists the open lines with `GET /connections/{connectionId}/client-links/{clientLinkId}/redemption-requests`, then records the cash-out with `POST /connections/{connectionId}/cash-outs` and a `lineId` and a `clientAccountId`. A participant records their own at `POST /users/me/bank-cash-outs` with `connectionId`, `lineId` and `clientAccountId`. Sending the same line and account again returns the stored cash-out. The same line with another account is refused with `409` (`bankRail.cashOut.DUPLICATE`).

Both routes, in both supply modes, refuse a cash-out with `409` `bankRail.cashOut.REFUSED` and `data.reason` `participant-restricted` while the client's participant account is `suspended`, `closed`, `terminated`, or `restricted` with the `withdrawals` restriction. Other restrictions do not block a cash-out. A checker's `approve` is refused the same way, and `reject` still works. A cash-out approved before the restriction is released with reason `participant-restricted` before the rail sends its instruction or locks its tokens.

### Delegate mode [#delegate-mode]

A delegate token has no redemption line, so an escrow holds the tokens.

1. A bank rail manager who also holds the escrow manager role creates the escrow with `POST /connections/{connectionId}/token-links/{tokenLinkId}/escrow` and wallet verification. The caller's own wallet signs the factory call. Another caller gets `escrow-manager-missing`, a system manager included. Any bank rail manager reads the escrow with `GET` on the same path. The rail wallet is the escrow's controller. The route honours `Prefer`: it answers `200` with the state `ready` and the escrow's address when the creation was indexed within your `Prefer: wait`, otherwise `202` with the state `creating`, the transaction when it is known, and `Location` set to `GET .../escrow`. Poll that read until the state is `ready`. Sending the request again re-attaches to the same creation. The route is refused while the rail wallet controls any escrow, and cash-outs are refused while it controls none or more than one.
2. The client approves the escrow, from the linked wallet, to take at least the amount.
3. The client records the cash-out at `POST /users/me/bank-cash-outs` with `connectionId`, `amount` and `clientAccountId`, and an `Idempotency-Key`. The manager route accepts a line only, so a manager cannot record a delegate cash-out for a client.
4. The rail deposits the tokens in the escrow and locks them until the payout deadline. It locks them again with a new deadline after a checker approves.

The request answers while the cash-out is still `locking`. Once the lock settles, it moves on to `awaiting-checker` or `approved`. To wait for that move, follow the cash-out's stream, as [Follow a cash-out](#follow-a-cash-out) describes.

When the bank reports the payment settled, the rail pays the lock to the rail wallet and burns it through the supply delegate. Otherwise it unlocks the tokens, and the client withdraws them from the escrow. A request is refused when the client's approval or balance does not cover the amount. When the approval drops before the rail moves the tokens, the cash-out is released as `not-locked` and an operations case says what to do.

### Read and decide [#read-and-decide]

`GET /connections/{connectionId}/cash-outs` lists cash-outs and takes `filter` and `page`. `GET .../cash-outs/{cashOutId}` reads one. A participant lists their own at `GET /users/me/bank-cash-outs`. A cash-out above the threshold always shows `awaiting-checker` with an `approvalId`. A different manager sends `POST .../cash-outs/{cashOutId}/decisions` with `{ "action": "approve" | "reject", "approvalId": "..." }`. Approving sends the instruction. Rejecting cancels the redemption line or unlocks the tokens.

### Follow a cash-out [#follow-a-cash-out]

`GET .../cash-outs/{cashOutId}/stream` sends the cash-out as server-sent events, with the same role and errors as the read. The first event is the cash-out as it stands. After that, an event arrives each time the cash-out changes. The stream ends after the event of a cash-out the rail has nothing more to do for on its own: `paid`, `released`, `returned`, or `unbooked` with no recovered units left to burn. Otherwise it ends once 180 seconds pass without a change. Open it again to keep following. A cash-out that already rests sends one event and ends.

A bank return after `paid`, a late settlement after `released` or a recover on `unbooked` moves a cash-out on again. After one of those, open a new stream to follow it. In the SDK the stream is `bankRail.cashOutStream`.

### Bank hours and value dates [#bank-hours-and-value-dates]

A connection carries `holidayCalendarId`, `paymentTimeZone` and `paymentCutOffTime`. Left out on create, they default to `adgm`, `Asia/Dubai` and `null`. Left out on `PATCH`, they keep their value. `holidayCalendarId: null` makes every day a business day. `paymentCutOffTime: null` means the whole business day takes payments, and `00:00` is refused. A calendar that is neither a base calendar nor the organisation's own answers `422` with `bankRail.connection.CALENDAR_UNAVAILABLE`.

A cash-out keeps the settings it was requested under and answers `paymentCutOffTime`, `paymentTimeZone`, `expectedValueDate` and `releaseAt`. A cash-out approved at or after the cut-off, or on a closed day, stays `approved` with `releaseAt` at the next opening. `deadlineAt` counts business time from that opening, and closed days never push it more than a year past that point. A closure added later moves `releaseAt` and `expectedValueDate`, and releases the cash-out as `expired` when the deadline no longer leaves the settlement window.

After the rail builds an instruction, the FIX session can resend the stored frame on any day, marked as a possible duplicate.

`GET /api/v2/users/me/bank-links` answers `payoutTiming` with the cut-off, the time zone and the value date a cash-out approved now would get. The reconciliation read names `report.businessDay` and `suspenseOldestAgeBusinessDays`.

### Returned payouts [#returned-payouts]

The bank may return a payout it already settled, for example when the destination account was closed. The rail records each return in the cash-out's `returns` with the bank's `returnId`, `amount`, `valueDate` and the `creditId` of its re-credit. A paid cash-out shows `returning` until every return has a re-credit, then `returned`.

A re-credit is a credit like any other on `GET /connections/{connectionId}/credits`, with `return:<cashOutId>:<returnId>` as `bankTxId` and the cash-out in `returnedCashOutId`. Whatever the link's credit threshold, it asks for mint approval: while the `bank-rail` approval family is on, it waits in `awaiting-mint-approval` for a manager's `approve` on its decisions route, as [Approve a credit before it mints](#approve-a-credit-before-it-mints) describes. With the family off, it mints at once. A parked re-credit cannot be returned to the payer, because the bank already refunded the payee.

A return that arrives before the bank reports the payout settled, while the cash-out is `instructed`, `releasing` or `released`, is held in `returns` with no re-credit and a warning case, and re-credits once the late settlement is booked. A return of a cash-out whose instruction never reached the bank, in another currency, or above what is left of the payout records nothing and raises a critical operations case to settle with the bank.

If a released cash-out settles late, its webhook status stays `released` during recovery. Once the rail recovers and burns the full amount, it sends `bank-rail.cash-out.paid`, including when a pending return starts re-crediting immediately. `bank-rail.cash-out.returned` follows when the re-credit is admitted. Its credit's minted event reports the completed mint separately.

## Contain the rail wallet [#contain-the-rail-wallet]

The rail wallet is the key that mints and burns for every bank connection of the organisation on a chain. A custody provider configuration of the deployment holds that key, and the platform signs the rail's mints and burns with it, with no manager signature. When that key is lost or exposed, a manager contains the wallet so the rail signs nothing more with it.

| Step | Route | What it does |
| --- | --- | --- |
| Read the wallet | `GET /rail-wallet` | Returns the address, generation, state (`active` or `contained`) and the rotation still open on the request's chain |
| Contain the wallet | `POST /rail-wallet/rotations` | Body `{ "reason": "lost" }` or `"compromised"`, with an optional `note`. Suspends every token link on the chain. Repeating the request while a rotation is open returns it |
| Read a rotation | `GET /rail-wallet/rotations/{rotationId}` | Returns the rotation with its state, the contained wallet, any open or rejected request, and for each suspended token link who holds its supply authority, the balances the old key still controls and the `inTransit` credits whose delivery coins still sit on the old wallet |
| Revoke the old key | `POST /rail-wallet/rotations/{rotationId}/transitions` | Body `{ "transition": "revoke-old", "tokenLinkId": "…", "walletVerification": { … } }`. Your wallet revokes the old wallet's supply authority on that token |
| Grant the new key | `POST /rail-wallet/rotations/{rotationId}/transitions` | Body `{ "transition": "grant-new", "tokenLinkId": "…", "walletVerification": { … } }`. Your wallet gives the staged wallet the supply authority on that token once nobody else holds it |
| Ask to abandon | `POST /rail-wallet/rotations/{rotationId}/transitions` | Body `{ "transition": "abandon" }`. Only a `lost` rotation whose supply authority has not moved can be abandoned. While the `bank-rail` family is on, the rotation waits in `abandon-requested` for a second manager |
| Ask to complete | `POST /rail-wallet/rotations/{rotationId}/transitions` | Body `{ "transition": "complete" }`. Refused with reason `completion-blocked` while anything still holds the rotation back. While the `bank-rail` family is on, the rotation waits in `complete-requested` for a second manager |
| Decide the request | `POST /rail-wallet/rotations/{rotationId}/decisions` | Body `{ "decision": "approve" }`, or `"reject"` with a `reason`. The manager who asked cannot decide |

While the wallet is contained, a credit parks as `supply-authority` and mints nothing. A cash-out step the wallet would sign waits with one operations case and does not count as a failed attempt. A cash-out that is not instructed is released with reason `link-inactive`. Activating or removing a token link is refused with reason `rail-wallet-contained`.

An approved abandon makes the wallet `active` again, reinstates the token links the containment suspended that still pass their checks, and resolves the waiting cases. A rejected or expired request returns the rotation to `contained`. A `compromised` rotation is refused with `409` and reason `compromised`, because a key someone else may hold must not sign again.

Containment stages the next rail wallet. To move a token link to it, revoke the old wallet's authority and then grant it to the staged wallet, one token link at a time. You sign both with your own wallet, so the rail never changes who may mint. Each step changes nothing when it is already done, so a retry is safe. Supply authority is the supply management role for a booked link, and the supply delegate entry for a delegate link.

The grant is refused while any account still holds the authority (`422`, reason `supply-role-held` or `supply-delegate-held` with the holders), and when the staged wallet cannot hold the token or has no gas. On a `compromised` rotation it also waits until no account but the staged wallet holds authority on any token link of the rotation (`409`, reason `revoke-pending`) and its escrow holds no tokens (`409`, reason `old-escrow-funded`), because whoever holds the old key controls both. The first revoke or grant a manager submits sets `handoverStartedAt` on the rotation. One the token refuses before anything is queued, such as from a manager without the role, leaves it as it was. From then on, and whenever any authority has left the old wallet, an abandon request or approval is refused with `409` and reason `authority-moved`, because the old wallet may no longer hold what an abandon would hand back to it. While the rotation is open, a delegate link's escrow routes read and create the escrow of the staged wallet.

Complete the rotation when every token link has moved. The request is refused with `409` and reason `completion-blocked`, and the message names every blocker, while any of these is true:

- The old wallet has transactions queued that have not reached a final state.
- The staged wallet does not hold a token link's supply authority alone.
- A delegate link has no escrow that the staged wallet controls.
- The old wallet's escrow still holds tokens.
- The old wallet holds tokens and is not frozen on that token.
- The staged wallet holds less of a token than the connection holds in suspense.
- A grant of supply authority to the old wallet is still queued, submitted or waiting for approval on a token linked to it. The message names the token and the request. This includes the re-delegation of a delegate link's mint cap that has not settled.
- The old wallet holds supply authority on any token linked to it, whatever the rotation's reason, including a link that still waits for activation. Revoke it with `revoke-old` on a suspended link, or ask a token admin or governor to revoke it on a link waiting for activation.
- The indexer is behind the chain, so the platform cannot tell whether a grant landed. Request completion again after a moment.

While a grant to the old wallet is in flight, the refusal also raises one operations case of kind `security` for the rotation, with severity `critical` for a `compromised` rotation and `warning` for a `lost` one. The case resolves when the rotation completes or is abandoned.

The rail stops accounting for the old wallet after the switch, so its tokens must be gone or frozen first. When a second manager approves, or on the next read of the rotation while the `bank-rail` approval family is off, the rail checks the blockers again and then switches in one step. Token links and credits move to the staged wallet, and a credit parked as `supply-authority` since the containment is admitted again. The staged wallet becomes `active` and the old one `retired`, and the rotation becomes `complete`. The rail then reinstates the token links that still pass their checks and resolves the waiting cases. A rejected or expired request returns the rotation to `contained`.

Between the approval and the switch the rotation is `approved`. If the switch fails, for example because the custody binding cannot move, the decision returns `409` with reason `state` and the rotation stays `approved`. Do not decide again: the next read of the rotation or the rail wallet tries the switch again.

If a key reported `lost` turns out to be exposed, send the contain request again with `compromised`. The open rotation becomes `compromised` and any pending request to abandon it is cancelled. A request to complete it stays open. A rotation never goes back from `compromised` to `lost`.

### Empty an escrow the old wallet controls [#empty-an-escrow-the-old-wallet-controls]

In delegate mode the old rail wallet still controls the escrow, so the rail cannot unlock or pay its locks. A wallet holding the token's custodian role moves them with `POST /api/v2/addons/escrows/{escrowAddress}/forced-transfers`, with wallet verification and an `Idempotency-Key` header:

```json
{
  "token": "0x…",
  "from": "0x…holder",
  "to": "0x…",
  "amount": "1000000",
  "lockIds": ["0x…"]
}
```

The escrow takes the holder's free balance first, then the listed locks. For a lock that backs a cash-out, `to` depends on the cash-out:

| Cash-out | `to` | Then |
| --- | --- | --- |
| Before the instruction, or released | The holder (`from`). Only while the rotation is `compromised` | The cash-out releases with reason `escrow-evacuated` |
| Instructed, the bank has not reported | Refused with `cash-out-in-flight` | Retry after the bank's report |
| Paid by the bank (`unbooked`) | The rail wallet: the rotation's staged wallet while one is open. The holder needs no free balance on the escrow | A manager sends `{ "action": "recover" }` to `POST .../cash-outs/{cashOutId}/transitions` |

A refusal is `409 ESCROW_FORCED_TRANSFER_REFUSED` with `data.reason`, and a wallet without the custodian role gets `403 ESCROW_CUSTODIAN_REQUIRED`. Locks of paid and unpaid cash-outs go in separate requests. `POST /api/v2/tokens/{assetId}/forced-transfers` refuses an escrow as `from`.

The Platform API applies these rules, and the escrow contract applies none of them. The contract checks the caller's custodian role on the token and nothing about cash-outs, so a custodian who calls the escrow directly can draw any of the holder's locks, including one behind a cash-out the bank has been instructed to pay, and pay any recipient the token accepts. Send every forced transfer from a rail escrow through this route.

Recover reads the forced transfers of the cash-out's lock to the rail wallet in blocks the chain has finalised, records them in the cash-out's `recovery`, and burns those units from the rail wallet. The cash-out shows `paid` once the burnt units reach its amount. Sending recover again before a new forced transfer returns the cash-out unchanged, including once it shows `paid`. When every transfer is past the finalised block, recover is refused with reason `recovery`. Send it again once they are final.

## Reconcile the reserve [#reconcile-the-reserve]

`GET /connections/{connectionId}/reconciliation` compares the bank's newest balance report with the token's supply, and the rail wallet's balance with the credits it holds as suspense. The token facts must come from an unchanged drained block at or beyond the chain's finalised block. Facts are unavailable while that watermark is missing, moves during the read, or has not reached finality. The rail keeps that report pending and retries it once the facts are available. A value the platform cannot read is `null`, never zero. Send the token's chain in the `X-Chain-Id` header.

A recall the bank sent by the report's time and still open explains the reserve line as `recalledNotBurnt`. Once it has stayed open longer than the settlement window it moves to `overdueRecalls`, no longer explains the line, and raises its own critical case. A recall the bank sent after the report's time that the rail already completed explains it as `recallBurntAfterReport`, less its write-down. Clawed tokens in the rail wallet waiting for their burn, or for an excess to go back to the client, explain the suspense line as `awaitingBurn`. Credits the rail minted to its wallet for a client's custody gateway and has not delivered yet explain it as `inTransit`. The suspense line also shows terms that enter no coin line: `inGateway` (coins that reached the gateway and wait there, including a refused deposit in escrow), `delivered` (`coins` the gateway accepted and the `receipts` it issued for them, the receipts being another token), `returnedElsewhere` (deliveries the gateway paid back to a retired rail wallet, also shown on that wallet's `railWallets` row next to its own `inTransit`), `inRedemption` (receipts a recall took back into the rail wallet that its gateway has not paid out in coins yet, with excess receipts the rail still owes the client. Once the gateway pays, its coins count in `awaitingBurn`) and `deliveryBreakdown` (the count and coins per delivery state). A credit that is `inTransit` while its transfer settles can lower the rail wallet balance before it leaves that term, so a short-lived difference clears on the next report. The daily reconciliation CSV has the columns `inGateway`, `inGatewayCount`, `deliveredCoins`, `deliveredReceipts`, `deliveredCount`, `returnedElsewhere`, `returnedElsewhereCount`, `inRedemption` and `inRedemptionCount`, then the coins and the count of each delivery state as `delivery.<state>` and `delivery.<state>Count` (a state with no credit shows 0). A version stored before they existed shows `unavailable` in all of them, never 0.

During a rail wallet rotation the line covers both keys. `railWallets` lists every wallet that can still hold the token, oldest generation first: the wallet the link is pinned to, the current wallet, the wallet an open rotation staged and every retired wallet. Each entry carries its state, balance and whether it holds the supply authority. `rotation` names the open rotation, or is `null`. The suspense line sums the listed balances, leaving out what a frozen retired wallet holds, so moving tokens from the old wallet to the new one changes nothing. The line breaks when an account other than a rail wallet holds the supply authority, when no listed wallet or more than one holds it, or when a retired wallet the token has not frozen still holds tokens. A frozen retired wallet's holding raises a warning case instead.

### Daily reconciliation [#daily-reconciliation]

A daily version preserves both reconciliation lines so you can reread or export the evidence a run used. Its `line` omits the live reconciliation's `consecutiveBreaks` and `breakSince`: those fields belong to the live report evaluator. Set the connection's `reportCutoff` to a `time` in `HH:MM:SS` form and an IANA `timeZone`. The default is `23:59:59` in `UTC`. The first run or scheduled attempt for a date pins that cutoff, even if you later change the connection's setting.

- `POST /connections/{connectionId}/daily-reconciliations` with `{ "date": "2026-10-24" }` creates a run for a closed civil date. It selects the latest bank balance report at or before the cutoff and current indexed token facts. `pins.balanceReportAsOf` names the report's value time, and `pins.indexedBlock` names the stable drained block read for the token facts. These facts are current when the run executes, rather than historical chain state at the day's cutoff.
- `GET /connections/{connectionId}/daily-reconciliations` lists the latest stored version per date. Use `filter[from]` and `filter[through]` for an inclusive date range, `sort=date` or `sort=-date`, and `page[limit]` and `page[offset]` to page through it.
- `GET /connections/{connectionId}/daily-reconciliations/{date}` reads the latest version. Add `version=1` to read a particular version and `format=csv` to export it. The CSV response contains `filename`, `contentType` (`text/csv`) and `csv`. Every amount has a named column, and unavailable amounts are blank. A stored version exports the same bytes on every read.

Each version carries `runAt`, its `trigger` and manager actor, the two-line `line`, and `unavailableReasons`. A retained report whose denomination differs from the current token link leaves the reserve line unavailable, with a reason. `openCaseCount` counts distinct unresolved reconciliation subjects of the connection, its token links and its daily reports at run time. It excludes cases for individual credits and cash-outs. A failed case read stores `null` and an unavailable reason, rather than a partial count. The CSV calls this column `openReconciliationCases`.

`ledger` is the general-ledger leg of the three-way reconciliation: the bank's reported balance, the token's supply and your organisation's Xero ledger. The reserve line ties the bank balance to the supply, and `ledger` ties the bank balance to the client-money account in Xero. The account is the one your [accounting rules](https://docs.settlemint.com/docs/api-reference/guides/accounting-feed) debit when a bank credit in the connection's currency arrives, read from the Xero Balance Sheet as at the end of the run's `date` in the Xero organisation's base currency. `ledger.balance` is that account's balance, `ledger.accountCode` names it, and `ledger.unexplained` is the ledger balance minus the bank's reported balance. `ledger.status` is `clear` when the two are equal, `break` when they differ, and `unavailable` when no bank report matches the linked token or the ledger could not be read. `ledger` is `null` when your accounting rules post no bank credit in the connection's currency, so the ledger is not part of that reconciliation.

A ledger that cannot be read adds an unavailable reason that says why: Xero is not connected, the connection does not reach the configured tenant, no Xero account is mapped to the client-money account, the ledger is kept in another currency, or Xero refused the read. The scheduled worker retries that day like any other unavailable evidence, and the next run that reads the ledger stores a new version. A Xero connection made before DALP asked for the `accounting.reports.balancesheet.read` scope is refused the read: connect Xero again to grant it. The CSV adds `ledgerStatus`, `ledgerAccountCode`, `ledgerBalance` and `ledger.unexplained`.

The report, connection settings, application totals and case count are read together. Token facts must belong to the same serving deployment at a stable finalised block whose committed work has drained, including a check after the application reads finish. A serving change, undrained work or a submitted token handoff with no recorded outcome leaves token amounts unavailable and the day eligible for retry. An ordinary pending credit that has not submitted its mint remains valid input.

Equal report and block pins return the existing version without writing. A higher pin with neither axis lower creates the next version. An older report time or indexed block is refused with `409` and `data.reason` `evidence-older`. A date whose cutoff has not passed is refused with `date-not-closed`. A cutoff that does not identify one instant, such as a repeated or missing clock time at daylight saving, is refused with `cutoff-unavailable`. A date or version that has not been stored returns `404`.

With bank FIX enabled, the worker checks active and suspended connections every five minutes. It runs the last three closed days, skips complete versions and retries days with unavailable evidence. It retains each attempted closed date even when a rejected cutoff or failed read or write prevents a version from being stored. If an incomplete day leaves that window, it raises one warning reconciliation case naming the date and reasons. A date with no stored version still returns `404`, and the platform invents no snapshot or CSV for it. A failed warning write is retried. You can still request a run for that date by hand.

### Reserve adjustments [#reserve-adjustments]

A bank fee, interest, a refund to a payer or the opening balance of a token moves the bank balance without a credit or a cash-out. A reserve adjustment explains it.

- `POST /connections/{connectionId}/reserve-adjustments` with `reason` (`bank-fee`, `interest`, `refund-to-payer` or `opening-balance`), a signed `amount` in token units, the bank's `bankReference` and `effectiveAt`. It is refused with `409` and `data.reason` when the connection has no linked token (`no-token-link`), the amount has more fraction digits than the token (`amount-precision`) or is too large (`amount-too-large`), the posting is in the future (`future-posting`), or a live adjustment already uses the reference (`bank-reference-used`). A zero amount fails request validation.
- `POST .../reserve-adjustments/{adjustmentId}/decisions` with `{ "action": "approve" }` or `"reject"`. The manager who proposed it cannot decide it, and the `409` carries `data.reason` `proposer-cannot-approve`. While the `bank-rail` approval family is off, a new adjustment is approved at once and needs no decision.
- `GET .../reserve-adjustments` lists them.

Only an approved adjustment applied at or before a balance report's time explains that report. An adjustment approved later takes effect from the next report, and the break case clears when that report reconciles.

## Next steps [#next-steps]

- The [Console guide](https://docs.settlemint.com/docs/console/asset-lifecycle/bank-rail) shows the same flows on screen.
- The [error index](https://docs.settlemint.com/docs/api-reference/errors) lists every bank rail refusal code.
- [Idempotency and async settlement](https://docs.settlemint.com/docs/api-reference/guides/idempotency-async-settlement) explains the `Idempotency-Key` and `Prefer` contracts.


# Investor custody choice

Source: https://docs.settlemint.com/docs/api-reference/guides/choose-investor-custody
Read the custody options an organisation offers after sign-up, then run the managed-account or browser-wallet branch to one account.

## Overview [#overview]

A signed-in investor who joins an organisation picks how they hold: an account an organisation runs and signs for them, or an account whose key stays in a wallet they control. Your front end reads the options the organisation offers, renders them, and then runs one of two call sequences. Both end on one participant, the platform's record of one compliance subject, one custody account on the network, and one on-chain identity, the contract that holds the investor's claims. Where the organisation runs smart wallets, the account is a smart wallet.

**Where this fits.** [Onboard an investor through the API](https://docs.settlemint.com/docs/api-reference/guides/onboard-an-investor) covers an operator creating a user, registering an identity and verifying the investor with a know-your-customer provider. [Embed a Privy wallet in an investor front end](https://docs.settlemint.com/docs/api-reference/guides/embed-a-privy-wallet) covers the embedded-wallet branch in full, including the Privy sign-in and sponsored transfers. This page covers the choice itself and the two other branches, so it does not repeat either.

The custody kind is decided by the provider configuration the investor picks, not by a field your front end sends. The read that offers the choice is per organisation and per network, so an organisation that runs on several networks offers a slightly different list on each, and the `X-Chain-Id` request header names the network.

## The sequence at a glance [#the-sequence-at-a-glance]

[Figure] Read the options, show the choice, then one of two branches to one account. Step 1 reads GET /api/v2/custody/investor-provider, which answers data, the organisation's default, and options, every configuration it offers to investors. Step 2 renders those options as they arrive, each carrying a custody label of managed-account, embedded-wallet or browser-wallet. The branches split. On the managed account, one call to POST /api/v2/participants has the provider create the account and its identity, and when the create outlasts the wait, a 202 answer sends the caller to the statusUrl. On the browser wallet, POST /api/v2/participants answers 201 with a pending participant, the investor signs a control message that POST /api/v2/users/me/custody-accounts/lifecycles turns into an active account, the identity is created with POST /api/v2/identities after the same key signs the identity factory payload, and where the organisation runs smart accounts the smart wallet is deployed with POST /api/v2/users/me/custody-accounts/:custodyAccountId/smart-wallet-deployment, signed by that same key. Both branches rejoin on one participant, one custody account and one identity. Labels: 1 Read what the organisation offers; GET /api/v2/custody/investor-provider answers data and options; 2 Show the choice; each option carries custody: managed-account, embedded-wallet or browser-wallet; managed-account; browser-wallet; 3a Create the participant; POST /api/v2/participants; the provider creates the account and its identity; 3b Create the participant; POST /api/v2/participants; 201: activationStatus pending, no key yet; If it answers 202; follow Location: statusUrl; until the request is terminal; Prove the key; personal_sign the prepared message, then POST; /api/v2/users/me/custody-accounts/lifecycles; Create the identity; POST /api/v2/identities; only when the account holds none; Deploy the smart wallet; POST …/smart-wallet-deployment; sign the factory typed data, then repeat; both branches land here; One outcome; one participant, one account on the network, one on-chain identity; a smart wallet when the organisation runs them.

_Steps 1 and 2 happen before any account exists. Step 3a and step 3b are alternatives, and step 3b runs only for a browser-wallet option._

## Step 1: read the options and the default [#step-1-read-the-options-and-the-default]

**cURL**

```bash
curl "https://your-instance.example.com/api/v2/custody/investor-provider" \
  -H "X-Api-Key: sm_dalp_..."
```

**TypeScript SDK**

```ts
const answer = await dalp.api.custodyProviderConfigurationsV2.investorProvider();

answer.data; // the organisation's default, or null
answer.options; // every configuration offered to investors, the default first
```

The answer carries two fields. `data` is the organisation's designated investor provider, or `null` when no configuration carries that designation. `options` is every configuration the organisation offers to investors, the default first. Each entry in either place holds the same shape:

```json
{
  "data": {
    "id": "019c4d2e-7a10-7b3c-9e21-5f8a6b4c3d2e",
    "provider": "local",
    "custody": "managed-account",
    "capabilities": {
      "accountCreation": "create",
      "accountProof": "provider-attestation",
      "managedSigning": true,
      "externalSigning": false,
      "accountAbstraction": true,
      "ledgerNetworks": [{ "ledger": "evm", "networks": ["31337"] }]
    },
    "clientConfiguration": null
  },
  "options": [
    {
      "id": "019c4d2e-7a10-7b3c-9e21-5f8a6b4c3d2e",
      "provider": "local",
      "custody": "managed-account",
      "capabilities": {
        "accountCreation": "create",
        "accountProof": "provider-attestation",
        "managedSigning": true,
        "externalSigning": false,
        "accountAbstraction": true,
        "ledgerNetworks": [{ "ledger": "evm", "networks": ["31337"] }]
      },
      "clientConfiguration": null
    },
    {
      "id": "019c4d2e-9b31-7c44-a8f2-1d2e3f4a5b6c",
      "provider": "injected-browser",
      "custody": "browser-wallet",
      "capabilities": {
        "accountCreation": "link",
        "accountProof": "interactive-address",
        "managedSigning": false,
        "externalSigning": true,
        "accountAbstraction": true,
        "ledgerNetworks": [{ "ledger": "evm", "networks": ["31337"] }]
      },
      "clientConfiguration": { "kind": "injected-browser" }
    }
  ]
}
```

The response has already dropped every configuration the deployment has switched off, every configuration the organisation does not offer to investors, and every configuration that cannot activate an account on the request's network. Render `options` as it arrives. A front end that recomputes the list from its own configuration table, or picks its own default, disagrees with the platform the moment an operator changes the offer.

The read answers for the network the request names in `X-Chain-Id`, and for the organisation's default network when the request names none. A front end that sends no chain header therefore offers, and onboards on, the organisation's default network even when the organisation runs on several. Send `X-Chain-Id` only when your front end shows a network picker of its own.

`data` being `null` does not mean the investor has no choice. It means no configuration is designated as the default, and `options` can still hold several. An empty `options` means the organisation offers no custody to investors. Show a blocked screen that says an administrator has to offer one in [Custody](https://docs.settlemint.com/docs/console/organisation-settings/custody).

## Step 2: render the choice [#step-2-render-the-choice]

Each entry's `custody` field is the label to show, and it names the branch to run. The platform derives it from the provider, so your front end maps nothing.

| `custody` | What the investor gets | Branch |
| --- | --- | --- |
| `managed-account` | An account the organisation holds the key for and signs with | [Step 3a](#step-3a-run-the-managed-account-branch) |
| `browser-wallet` | An account whose key stays in a wallet the investor connects | [Step 3b](#step-3b-run-the-browser-wallet-branch) |
| `embedded-wallet` | An account whose key sits in an embedded wallet that a provider such as Privy creates inside your front end | [Embed a Privy wallet](https://docs.settlemint.com/docs/api-reference/guides/embed-a-privy-wallet) |

Mark the entry whose `id` matches `data.id` as the default rather than ordering the list yourself. With one option you can skip the choice and run its branch. With none, show the blocked screen.

The `clientConfiguration` field tells an embedded-wallet branch which client SDK to load, and its `kind` decides:

- `privy` carries a `tenant`, an `appId` and, when the configuration sets one, a `clientId`.
- `dynamic` carries a `tenant` and an `environmentId`.
- `injected-browser` carries nothing else, because the wallet is one the investor already holds.

Every managed configuration returns `null` here, because the key sits with a custodian rather than in a front end.

The choice decides the first key, not the only one. A custody account's lifecycle offers `onboard`, `add`, `revoke` and `archive`, and none of them moves an existing account to another provider or swaps the key that controls it. The participant can `add` another custody account later, and where the organisation runs smart wallets, the added account becomes another signer on the same smart wallet. Any one signer can act for the smart wallet alone, and `revoke` removes a signer. Show that consequence on each option.

Before any branch, read the organisation's network and account-abstraction settings:

**cURL**

```bash
curl "https://your-instance.example.com/api/v2/organizations/019c4d2e-1f00-7a11-9c22-3b4c5d6e7f80/joinable-participants" \
  -H "X-Api-Key: sm_dalp_..."
```

**TypeScript SDK**

```ts
const joinable = await dalp.api.party.participantJoins.joinableList({
  organizationId: "019c4d2e-1f00-7a11-9c22-3b4c5d6e7f80",
});

joinable.data.chainId; // the network this investor is created on
joinable.data.aaEnabled; // true when the organisation runs smart wallets
joinable.data.pendingParticipantId; // the participant to resume, or null
```

`aaEnabled` is the flag that decides whether a smart wallet is part of the outcome. `pendingParticipantId` is the participant an interrupted browser-wallet sign-up left behind, and step 3b resumes it instead of creating a second one.

## Step 3a: run the managed-account branch [#step-3a-run-the-managed-account-branch]

One call creates everything. The provider mints the account, and the platform creates the participant's identity with it. The investor's own session sends this call. An identity manager who creates the user for the investor calls `POST /api/v2/users` instead, as [Onboard an investor through the API](https://docs.settlemint.com/docs/api-reference/guides/onboard-an-investor) describes.

**cURL**

```bash
curl -X POST "https://your-instance.example.com/api/v2/participants" \
  -H "X-Api-Key: sm_dalp_..." \
  -H "Idempotency-Key: participant-amara-managed-001" \
  -H "Prefer: wait=60" \
  -H "Content-Type: application/json" \
  -d '{
    "organizationId": "019c4d2e-1f00-7a11-9c22-3b4c5d6e7f80",
    "providerConfigurationId": "019c4d2e-7a10-7b3c-9e21-5f8a6b4c3d2e",
    "walletVerification": { "verificationType": "PINCODE", "secretVerificationCode": "482913" }
  }'
```

**TypeScript SDK**

```ts
const created = await dalp.api.party.participants.create(
  {
    organizationId: "019c4d2e-1f00-7a11-9c22-3b4c5d6e7f80",
    providerConfigurationId: "019c4d2e-7a10-7b3c-9e21-5f8a6b4c3d2e",
    walletVerification: { verificationType: "PINCODE", secretVerificationCode: "482913" },
  },
  { headers: { "Idempotency-Key": "participant-amara-managed-001" } }
);
```

A settled create answers `200` with the participant, the account the provider made and the identity created for it:

```json
{
  "data": {
    "id": "pp_7c2f9a41e8b3d6052f1c4a9e8d7b6c35",
    "kind": "smart",
    "wallet": "0x4F1bE7dB9d2c3aA85f6C1E0b7D9a2C4e6F8b0A1c",
    "identity": "0x9A2c4E6f8B0a1C3d5E7f9A2c4E6f8B0a1C3d5E7f"
  },
  "links": {
    "self": "/v2/participants/pp_7c2f9a41e8b3d6052f1c4a9e8d7b6c35"
  }
}
```

`kind` is `"smart"` when the organisation runs smart wallets on that network and `"eoa"` when it does not, so the managed branch needs no deployment call of its own: `aaEnabled` and `kind` agree, and the account arrives as a smart wallet already. `wallet` is the address the investor holds assets at, `identity` is the identity contract created for the participant.

A create that is still running when the platform's wait ends, or that the provider has not finished provisioning, answers `202` instead. The body carries `requestId`, `state` and `statusUrl`, and the `Location` header holds the same `statusUrl`. The SDK's response type then holds no `id` at all. The create keeps running after that answer: the platform still opens the custody account, deploys the smart wallet where the organisation runs smart wallets, and creates the identity. Follow `statusUrl` until the request reads `succeeded`. A create whose provisioning request has ended `failed` or `expired` answers `DALP-14226`, and its message names the request that ended.

```json
{
  "requestId": "3b7e91c4-52d0-8a6f-9c13-47e2d8a05b6f",
  "state": "awaiting-proof",
  "statusUrl": "/api/v2/participants/pp_7c2f9a41e8b3d6052f1c4a9e8d7b6c35/custody-account-requests/3b7e91c4-52d0-8a6f-9c13-47e2d8a05b6f"
}
```

Read `statusUrl` until its `data.state` is `succeeded`, `failed` or `expired`. While the create runs, the state is `awaiting-proof` or the custody account's own progress, such as `claimed`. On this branch `awaiting-proof` only means that the create is still running, because a managed account needs no proof from the investor. The state is `succeeded` only once the identity exists as well, and then the same create with the same `Idempotency-Key` answers the `200` with the participant. A failed create reads `failed` with the `terminalCode` `PARTICIPANT_CREATE_FAILED`. When the custody account request itself ended `failed` or `expired`, the status keeps that request's own `terminalCode`.

A create that finishes inside the wait while its custody account request has not settled also answers `202`, with that request's state, such as `claimed`, in place of `awaiting-proof`. A create whose custody account request ended `failed` or `expired` answers `DALP-14226`.

Unlike most writes, which answer `202` at once without a `wait` directive, this create waits by default. Without a `wait` directive in the `Prefer` header, `Prefer: respond-async` included, the platform holds the answer for the longest wait, 99 seconds. `Prefer: wait=N` sets that wait to `N` seconds instead, clamped between 5 and 99. Every wait also ends five seconds before the request deadline that the deployment configures, so the platform answers `202` before that deadline cuts the request off with an error. With the default 60 second deadline, the answer is therefore held for up to 55 seconds. The wait never changes the outcome of the create, only whether the participant arrives in a `200` or behind a `202`.

The `Idempotency-Key` makes a retry safe and lets the investor resume a create their browser abandoned: the same key joins the same run and answers the same participant instead of a second one. A create sent without the header gets a new key from the platform on every attempt, so its retry cannot join the earlier run. [Idempotency and async settlement](https://docs.settlemint.com/docs/api-reference/guides/idempotency-async-settlement) covers both headers.

A `403` with [DALP-14228](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference#permission-errors) on this call means the caller may not create this participant. The investor's own session creates its own participant. To name another user in `forUserId`, the caller signs in through the browser as themselves and holds the identity-manager role, and that user must be a member of the organisation. An API key or an impersonated session cannot name another user. Once the organisation offers at least one configuration to investors, choosing a configuration it does not offer also needs the identity-manager role. When that configuration cannot hold a managed account, such as a browser wallet, the platform refuses it for every caller, because its key could never be proven.

## Step 3b: run the browser-wallet branch [#step-3b-run-the-browser-wallet-branch]

The branch takes up to three signatures from the investor's wallet: the control message, the identity factory payload and, where the organisation runs smart wallets, the account factory payload. The control message is a personal message. The two factory payloads are EIP-712 typed data that the wallet signs with `eth_signTypedData_v4`, and [When the wallet cannot sign typed data](#when-the-wallet-cannot-sign-typed-data) covers a wallet that cannot. The participant exists first and cannot act anywhere until its key is proven.

### 1. Create the participant in a pending state [#1-create-the-participant-in-a-pending-state]

Use the same call as the managed branch, with the browser-wallet configuration's `id`. It answers `201` with a pending participant:

```json
{
  "data": {
    "id": "pp_4e8a1d6c93b2f075a1c8e4d9b7f20a63",
    "activationStatus": "pending",
    "proofUrl": "/api/v2/users/me/custody-account-control-preparations"
  },
  "links": {
    "self": "/v2/participants/pp_4e8a1d6c93b2f075a1c8e4d9b7f20a63"
  }
}
```

`activationStatus` is always `pending` here: the key is not proven, so the participant holds no wallet and the organisation can drive nothing for it. Never render that as a failure. It is the state the next call resolves, and a sign-up that stops now resumes as `pendingParticipantId` on the joinable read. Prove the key with the two calls below. `proofUrl` names the first of them, `POST /api/v2/users/me/custody-account-control-preparations`, which the participant's owner calls in a session of their own.

### 2. Prepare the control message and sign it [#2-prepare-the-control-message-and-sign-it]

**cURL**

```bash
curl -X POST "https://your-instance.example.com/api/v2/users/me/custody-account-control-preparations" \
  -H "X-Api-Key: sm_dalp_..." \
  -H "Content-Type: application/json" \
  -d '{
    "providerConfigurationId": "019c4d2e-9b31-7c44-a8f2-1d2e3f4a5b6c",
    "participantId": "pp_4e8a1d6c93b2f075a1c8e4d9b7f20a63",
    "signingAddress": "0x71C7656EC7ab88b098defB751B7401B5f6d8976F"
  }'
```

**TypeScript SDK**

```ts
const prepared = await dalp.api.custodyUserAccountsV2.prepareControl({
  providerConfigurationId: "019c4d2e-9b31-7c44-a8f2-1d2e3f4a5b6c",
  participantId: "pp_4e8a1d6c93b2f075a1c8e4d9b7f20a63",
  signingAddress: "0x71C7656EC7ab88b098defB751B7401B5f6d8976F",
});

prepared.data.message; // the text to sign
prepared.data.binding; // echo this back against the proof
prepared.data.account; // the account facts the proof binds
```

```json
{
  "data": {
    "binding": {
      "operation": "onboard",
      "actorUserId": "019c4d2e-2b9f-7d51-8a4e-1c0d2e3f4a5b",
      "participantId": "pp_4e8a1d6c93b2f075a1c8e4d9b7f20a63",
      "organizationId": "019c4d2e-1f00-7a11-9c22-3b4c5d6e7f80",
      "providerConfigurationId": "019c4d2e-9b31-7c44-a8f2-1d2e3f4a5b6c",
      "ledger": "evm",
      "network": "31337",
      "domain": "your-instance.example.com",
      "origin": "https://portal.example.com",
      "audience": "dalp",
      "participantResetEpoch": 0,
      "nonce": "4b1d2f3a5c6e7d8b9a0f1e2d3c4b5a69788796a5b4c3d2e1f0a9b8c7d6e5f4a",
      "proofDigest": "0x8a1b2c3d4e5f60718293a4b5c6d7e8f90a1b2c3d4e5f60718293a4b5c6d7e8f9",
      "expiresAt": "2026-11-05T10:22:14.000Z"
    },
    "account": {
      "_tag": "EvmCustodyAccountFacts",
      "ledger": "evm",
      "signingAddress": "0x71C7656EC7ab88b098defB751B7401B5f6d8976F",
      "managedSignerKeyId": null
    },
    "message": "DALP custody-account control proof\n0x8a1b2c3d4e5f60718293a4b5c6d7e8f90a1b2c3d4e5f60718293a4b5c6d7e8f9"
  },
  "links": {
    "self": "/v2/users/me/custody-account-control-preparations"
  }
}
```

Sign `message` exactly as it arrives, as a personal message: `personal_sign` over its UTF-8 bytes, with the address in `account.signingAddress`. The text is two lines, the label `DALP custody-account control proof` and the `proofDigest`, and the platform rebuilds it from the binding and the account to check your signature. A browser wallet signs it with `personal_sign`, the message as hex-encoded UTF-8 bytes and the account address:

```ts
await provider.request({ method: "personal_sign", params: [toHex(message), address] });
```

A wallet that signs a hash of the text, or an `eth_sign` digest instead, produces a signature that recovers to nobody and the platform refuses it.

A prepared control expires 15 minutes after the platform issues it, so prepare and sign in one flow rather than resuming a stored one.

### 3. Hand the proof back [#3-hand-the-proof-back]

**cURL**

```bash
curl -X POST "https://your-instance.example.com/api/v2/users/me/custody-accounts/lifecycles" \
  -H "X-Api-Key: sm_dalp_..." \
  -H "Idempotency-Key: custody-proof-amara-001" \
  -H "Content-Type: application/json" \
  -d '{
    "proof": {
      "binding": {
        "operation": "onboard",
        "actorUserId": "019c4d2e-2b9f-7d51-8a4e-1c0d2e3f4a5b",
        "participantId": "pp_4e8a1d6c93b2f075a1c8e4d9b7f20a63",
        "organizationId": "019c4d2e-1f00-7a11-9c22-3b4c5d6e7f80",
        "providerConfigurationId": "019c4d2e-9b31-7c44-a8f2-1d2e3f4a5b6c",
        "ledger": "evm",
        "network": "31337",
        "domain": "your-instance.example.com",
        "origin": "https://portal.example.com",
        "audience": "dalp",
        "participantResetEpoch": 0,
        "nonce": "4b1d2f3a5c6e7d8b9a0f1e2d3c4b5a69788796a5b4c3d2e1f0a9b8c7d6e5f4a",
        "proofDigest": "0x8a1b2c3d4e5f60718293a4b5c6d7e8f90a1b2c3d4e5f60718293a4b5c6d7e8f9",
        "expiresAt": "2026-11-05T10:22:14.000Z"
      },
      "account": {
        "_tag": "EvmCustodyAccountFacts",
        "ledger": "evm",
        "signingAddress": "0x71C7656EC7ab88b098defB751B7401B5f6d8976F",
        "managedSignerKeyId": null
      },
      "artifact": "{\"kind\":\"evm-self-custody-control\",\"signature\":\"0x8f2a...c41d\"}"
    }
  }'
```

**TypeScript SDK**

```ts
const started = await dalp.api.custodyUserAccountsV2.runLifecycle(
  {
    proof: {
      binding: prepared.data.binding,
      account: prepared.data.account,
      artifact: JSON.stringify({ kind: "evm-self-custody-control", signature }),
    },
  },
  { headers: { "Idempotency-Key": "custody-proof-amara-001" } }
);
```

`binding` and `account` go back exactly as step 2 returned them. They are the values the signature covers. `artifact` is a JSON string rather than an object, in this shape:

```json
{ "kind": "evm-self-custody-control", "signature": "0x8f2a...c41d" }
```

A signature that does not bind the participant, the organisation and the prepared nonce is refused with [DALP-12274](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference#client-request-errors), and the fix is a fresh preparation.

The answer is the lifecycle request: `200` with the request body and its `requestId`, or `202` with `{ requestId, state, statusUrl }`. Follow it.

```bash
curl "https://your-instance.example.com/api/v2/users/me/custody-account-requests/019c4d2e-c3d4-7f56-8a78-9b0c1d2e3f40" \
  -H "X-Api-Key: sm_dalp_..."
```

```json
{
  "data": {
    "requestId": "019c4d2e-c3d4-7f56-8a78-9b0c1d2e3f40",
    "custodyAccountId": "019c4d2e-d9e0-7a12-8b34-9c560d1e2f3a",
    "organizationContextId": "019c4d2e-e5f6-7b78-8c90-9d120e1f2a3b",
    "operation": "onboard",
    "state": "succeeded",
    "externalPreparationId": null,
    "externalAuthorizingCustodyAccountId": null,
    "externalMessageDigest": null,
    "terminalResult": "succeeded",
    "terminalCode": null
  },
  "links": {
    "self": "/v2/users/me/custody-account-requests/019c4d2e-c3d4-7f56-8a78-9b0c1d2e3f40"
  }
}
```

A request moves through working states such as `awaiting-proof`, `claimed` and `reconciling`, and ends `succeeded`, `failed` or `expired`. The same path with `/stream` appended reports each change instead of you polling, and it answers only a same-origin request. A request that ends `failed` or `expired` names why in `terminalCode`, and `DALP-14219` on a repeated attempt means another request moved the account under you.

The account is live when the participant's custody account list shows both `accountLifecycle` and `contextLifecycle` as `active`. Its `signingAddress` is the wallet the investor just proved.

### 4. Create the identity [#4-create-the-identity]

Read first. `GET /api/v2/system/identities/me` answers whether the participant already holds an identity on this network, and a `404` with `IDENTITY_SCOPE_NOT_FOUND`, [DALP-14224](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference#client-request-errors), means the network's registry is not indexed yet, not that the call failed.

**cURL**

```bash
curl "https://your-instance.example.com/api/v2/system/identities/me" \
  -H "X-Api-Key: sm_dalp_..." \
  -H "X-Participant: pp_4e8a1d6c93b2f075a1c8e4d9b7f20a63" \
  -H "X-Custody-Account-Id: 019c4d2e-d9e0-7a12-8b34-9c560d1e2f3a" \
  -H "X-Chain-Id: 31337"
```

**TypeScript SDK**

```ts
const identity = await dalp.api.party.identities.me(
  {},
  {
    headers: {
      "X-Participant": "pp_4e8a1d6c93b2f075a1c8e4d9b7f20a63",
      "X-Custody-Account-Id": "019c4d2e-d9e0-7a12-8b34-9c560d1e2f3a",
      "X-Chain-Id": "31337",
    },
  }
);
```

An answer with `status: "NOT_PROVISIONED"` and `reason: "NO_IDENTITY"`, or a `404` with `IDENTITY_SCOPE_NOT_FOUND`, both mean no identity yet. Then create it with the account's `signingAddress`:

```bash
curl -X POST "https://your-instance.example.com/api/v2/identities" \
  -H "X-Api-Key: sm_dalp_..." \
  -H "X-Participant: pp_4e8a1d6c93b2f075a1c8e4d9b7f20a63" \
  -H "X-Custody-Account-Id: 019c4d2e-d9e0-7a12-8b34-9c560d1e2f3a" \
  -H "X-Chain-Id: 31337" \
  -H "Idempotency-Key: identity-amara-001" \
  -H "Content-Type: application/json" \
  -d '{
    "wallet": "0x71C7656EC7ab88b098defB751B7401B5f6d8976F",
    "walletVerification": { "verificationType": "PINCODE", "secretVerificationCode": "482913" }
  }'
```

```ts
await dalp.api.party.identities.create(
  {
    wallet: "0x71C7656EC7ab88b098defB751B7401B5f6d8976F",
    walletVerification: { verificationType: "PINCODE", secretVerificationCode: "482913" },
  },
  {
    headers: {
      "Idempotency-Key": "identity-amara-001",
      "X-Participant": "pp_4e8a1d6c93b2f075a1c8e4d9b7f20a63",
      "X-Custody-Account-Id": "019c4d2e-d9e0-7a12-8b34-9c560d1e2f3a",
      "X-Chain-Id": "31337",
    },
  }
);
```

The platform holds no key for this account, so the first create is refused on purpose. It answers `409` with [DALP-12389](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference#domain-rule-errors), and `data.signingPayload.typedData` carries the identity factory's EIP-712 payload for that wallet. Sign it with `eth_signTypedData_v4` on the wallet in `account.signingAddress`, then repeat the same call with the signature added to the body:

```json
{
  "wallet": "0x71C7656EC7ab88b098defB751B7401B5f6d8976F",
  "walletVerification": { "verificationType": "PINCODE", "secretVerificationCode": "482913" },
  "externalMessageAuthorization": { "signature": "0x9b3e…41c7" }
}
```

A signature that does not recover to that wallet over the payload this request prepared answers [DALP-12390](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference#client-request-errors): send the call once more with no signature and sign the fresh payload. A wallet that already holds an identity contract answers [DALP-14227](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference#domain-rule-errors), so read the identity rather than repeating the create. Registering the identity on the network and verifying the investor with a know-your-customer provider continue in [Onboard an investor through the API](https://docs.settlemint.com/docs/api-reference/guides/onboard-an-investor) from step 3.

### 5. Deploy the smart wallet [#5-deploy-the-smart-wallet]

Skip the step when `aaEnabled` is `false`. Otherwise:

**cURL**

```bash
curl -X POST "https://your-instance.example.com/api/v2/users/me/custody-accounts/019c4d2e-d9e0-7a12-8b34-9c560d1e2f3a/smart-wallet-deployment" \
  -H "X-Api-Key: sm_dalp_..." \
  -H "X-Participant: pp_4e8a1d6c93b2f075a1c8e4d9b7f20a63" \
  -H "X-Custody-Account-Id: 019c4d2e-d9e0-7a12-8b34-9c560d1e2f3a" \
  -H "X-Chain-Id: 31337" \
  -H "Prefer: wait=30" \
  -H "Content-Type: application/json" \
  -d '{}'
```

**TypeScript SDK**

```ts
const headers = {
  "X-Participant": "pp_4e8a1d6c93b2f075a1c8e4d9b7f20a63",
  "X-Custody-Account-Id": "019c4d2e-d9e0-7a12-8b34-9c560d1e2f3a",
  "X-Chain-Id": "31337",
};

const deployment = await dalp.api.custodyUserAccountsV2.deploySmartWallet(
  { custodyAccountId: "019c4d2e-d9e0-7a12-8b34-9c560d1e2f3a" },
  { headers }
);

deployment.data.deployed; // false until the wallet's code is on the network and indexed
```

The first call is refused on purpose. It answers `409` with [DALP-12388](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference#domain-rule-errors), whose `data` carries the account and the payload to sign:

```json
{
  "code": "custody.smart-wallet.EXTERNAL_MESSAGE_AUTHORIZATION_REQUIRED",
  "status": 409,
  "message": "The smart wallet needs a signature from its controlling wallet",
  "data": {
    "id": "DALP-12388",
    "category": "domain",
    "retryable": false,
    "why": "The custody account in `data.custodyAccountId` is self custody, so the platform holds no key for it. Its wallet has to sign the account factory payload in `data.signingPayload` before the smart wallet can be deployed.",
    "fix": "Sign `data.signingPayload` with that account's connected wallet, then send the same request again with the signature in `externalMessageAuthorization`.",
    "custodyAccountId": "019c4d2e-d9e0-7a12-8b34-9c560d1e2f3a",
    "signingPayload": {
      "_tag": "TypedDataSigningPayload",
      "kind": "eip-712",
      "typedData": {
        "domain": {
          "name": "DALPAccountFactory",
          "version": "1",
          "chainId": 31337,
          "verifyingContract": "0x0000000000000000000000000000000000000fac"
        },
        "types": {
          "EIP712Domain": [
            { "name": "name", "type": "string" },
            { "name": "version", "type": "string" },
            { "name": "chainId", "type": "uint256" },
            { "name": "verifyingContract", "type": "address" }
          ],
          "CreateAccount": [
            { "name": "owner", "type": "address" },
            { "name": "validator", "type": "address" },
            { "name": "onchainID", "type": "address" },
            { "name": "salt", "type": "bytes32" },
            { "name": "deadline", "type": "uint256" },
            { "name": "validatorInitDataHash", "type": "bytes32" }
          ]
        },
        "primaryType": "CreateAccount",
        "message": {
          "owner": "0x71C7656EC7ab88b098defB751B7401B5f6d8976F",
          "validator": "0x0000000000000000000000000000000000000000",
          "onchainID": "0x0000000000000000000000000000000000000000",
          "salt": "0x3f1c5a7e9b2d4f6a8c0e1b3d5f7a9c2e4b6d8f0a1c3e5b7d9f2a4c6e8b0d1f3a",
          "deadline": 1900000000,
          "validatorInitDataHash": "0xc5d2460186f7233c927e7db2dcc703c0e500b653ca82273b7bfad8045d85a470"
        }
      }
    }
  }
}
```

Sign the typed data in `signingPayload` with `eth_signTypedData_v4` on the wallet its `message.owner` names, then repeat the same call with the signature:

```json
{ "externalMessageAuthorization": { "signature": "0x4c1d…8f2a" } }
```

Repeat the same signature while `deployed` is `false`. Check the account `data` names before you sign: a challenge for another custody account is a challenge you must not sign, and signing it hands a signature over a second account's deployment to whichever page asked.

```json
{
  "data": {
    "walletId": "019c4d2e-f7a8-7c90-8d12-9e340f1a2b3c",
    "address": "0x4F1bE7dB9d2c3aA85f6C1E0b7D9a2C4e6F8b0A1c",
    "deployed": true
  },
  "links": {
    "self": "/v2/users/me/custody-accounts/019c4d2e-d9e0-7a12-8b34-9c560d1e2f3a/smart-wallet-deployment"
  }
}
```

`address` is the smart wallet the investor holds assets at. The wallet has code on the network only when `deployed` is `true`, so read this field rather than the response arriving at all. `Prefer: wait=N` holds the answer up to `N` seconds until the network confirms.

## When the wallet cannot sign typed data [#when-the-wallet-cannot-sign-typed-data]

A browser wallet can connect, hold its key and sign the control message, which is a personal message, and still be unable to produce the EIP-712 signatures that step 4 and step 5 need. The investor is then half set up.

- **Only that account's own key can sign.** Both signatures must recover to the wallet address the investor proved in step 3b.2. A second wallet cannot sign for it, and no route swaps the key of an existing account.
- **The participant and the account are already real.** Steps 3b.1 to 3b.3 succeeded, so the investor keeps their participant and an active custody account. A refused signature does not undo them, and the investor does not start again.
- **The identity step needs typed data on every network.** Without an identity the wallet cannot be registered, so it cannot hold a regulated token. The deployment step adds a second typed-data signature only where `aaEnabled` is `true`.

So the sequence for a wallet that does not sign typed data is:

1. Send the identity or deployment call with no signature. Read `signingPayload` from the [DALP-12389](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference#domain-rule-errors) or [DALP-12388](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference#domain-rule-errors) refusal.
2. Attempt the `eth_signTypedData_v4` signature. If the wallet raises "method not supported", declines, or returns something that is not a 65-byte hex string, stop there: do not retry the signature, and do not ask the investor to connect a different wallet for this step.
3. Leave the participant and the account alone, and tell the investor which step waits on their wallet. An account with no identity cannot hold a regulated token. An account with an identity and no smart wallet lacks the smart wallet the organisation's feature set assumes.
4. Recover later by getting a signature from that same key. A wallet that gained EIP-712 support in an update, or the same key restored in a wallet that supports it, can sign a fresh payload, and the step completes against the account that already exists.

Prevent the failure at the choice step. A wallet announces itself with a name, an icon and a reverse DNS identifier, and none of those says whether it signs typed data, so there is nothing to read in advance. Probe when the investor chooses: ask the wallet to sign a typed-data payload whose domain names your own app and no DALP contract, tell the investor on screen that the signature moves nothing, and offer only the wallets that answered. Never reuse a payload from a DALP-12388 or DALP-12389 refusal as the probe. For a wallet that does not, show the `managed-account` option instead, where the organisation offers one. That costs the investor a decision at a moment when nothing is created, rather than a broken outcome afterwards.

## The refusals each step returns [#the-refusals-each-step-returns]

| Code | Where it appears | What it means and what to do |
| --- | --- | --- |
| [DALP-12271](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference#client-request-errors) (422) | Either branch, on the create | The configuration does not exist in this organisation, or the deployment does not enable its provider or ledger. Read the options again and use an offered `id`. |
| [DALP-14226](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference#domain-rule-errors) (409) | Either branch, on the create | Another participant holds that key or user link, the configuration is switched off for new accounts or not healthy, a bring-your-own-key create asked for a `smart` wallet type, or the provisioning request ended `failed` or `expired`. Read the message. If the provisioning request ended `failed` or `expired`, repeat the create with a new `Idempotency-Key`. Otherwise read the participant or the options and continue from there. |
| [DALP-12274](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference#client-request-errors) (422) | Browser wallet, returning the proof | The proof, the account facts or the artifact does not bind this participant and ledger. Prepare a new control and sign it. |
| [DALP-14219](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference#domain-rule-errors) (409) | Browser wallet, the lifecycle call or the deployment | Another request moved this account's lifecycle. Read the account and take the step its current state allows. Do not repeat the call. |
| [DALP-14227](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference#domain-rule-errors) (409) | Browser wallet, creating the identity | An identity contract already exists, another write on that wallet is in flight, or the participant already holds or is creating a registry entry for another wallet. Read the identity instead of creating it. |
| [DALP-12389](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference#domain-rule-errors) (409) | Browser wallet, creating the identity | The account's wallet must sign the identity factory payload. Sign the typed data in `signingPayload` and repeat the call with the signature. |
| [DALP-12390](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference#client-request-errors) (400) | Browser wallet, creating the identity | The signature does not recover to the account's wallet over the payload this request prepared. Send once more with no signature, sign the payload you get back, and repeat. |
| [DALP-12388](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference#domain-rule-errors) (409) | Browser wallet, deploying the smart wallet | The account's controller must sign the factory payload. Sign the typed data in `signingPayload` and repeat the call with the signature. |
| [DALP-12386](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference#client-request-errors) (400) | Browser wallet, deploying the smart wallet | The signature does not recover to the controller over the payload this request prepared, or its deadline passed. Send once more with no signature, sign the payload you get back, and repeat. |
| [DALP-12387](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference#domain-rule-errors) (409) | Browser wallet, deploying the smart wallet | A deployment check refused it and `data.reason` names which. The reasons are below. |
| [DALP-14228](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference#permission-errors) (403) | Either branch, on the create | The caller may not create this participant: it named another user without signing in through the browser as itself with the identity-manager role, or it chose a configuration the organisation does not offer to investors. Create with the investor's own session and an offered `id`. |

`data.reason` on [DALP-12387](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference#domain-rule-errors) is one of:

- `account-abstraction-disabled`: the organisation runs no smart wallets on this network. Nothing is wrong, so treat the investor as set up and stop.
- `factory-missing`: the network's directory publishes no account factory, or provisioning the wallet failed for that reason. Report it, because no signature clears it and every browser-wallet investor on that network stops at the same step.
- `controller-unauthorized`: the participant already holds a smart wallet on this network, or its signing key, and another account controls it. Read the participant's smart wallet before retrying, because a repeat cannot make this account the controller.
- `prediction-mismatch`: the factory predicts another address for this wallet, or the recorded smart wallet sits somewhere else. Read the account instead of retrying, because the address the investor would end up with is not the one on record.
- `deadline-expired`: the deployment was still pending when its authorisation expired. Request a fresh payload and sign it again.
- `deploy-failed`: the deployment settled and the wallet still has no code on the network. Retry with the same signature, and if it repeats, report the network's answer rather than looping.

A refused deployment is not worth more than a few attempts in one session. `deploy-failed` and an unconfirmed deployment look identical from a polling loop, and neither changes by polling faster.

## Next steps [#next-steps]

- [Embed a Privy wallet in an investor front end](https://docs.settlemint.com/docs/api-reference/guides/embed-a-privy-wallet) takes the `embedded-wallet` branch through the Privy sign-in and a sponsored transfer.
- [Onboard an investor through the API](https://docs.settlemint.com/docs/api-reference/guides/onboard-an-investor) registers the identity and verifies the investor once the account exists.
- [Custody Provider](https://docs.settlemint.com/docs/concepts/custody-and-signing/custody-provider) explains what a managed configuration holds and what a self-custody configuration never holds.
- [Smart Wallet](https://docs.settlemint.com/docs/concepts/custody-and-signing/smart-wallet) explains what the account step 5 deploys, and what it enforces.


# Corporate actions catalogue

Source: https://docs.settlemint.com/docs/api-reference/guides/corporate-actions-catalog
The thirteen corporate action types grouped by mechanism, with the status lifecycle, the in-flight limit, and the allocation records used by each mechanism.

The corporate actions catalogue is one collection, `/tokens/{assetId}/corporate-actions`, that names thirteen lifecycle event types and applies each through one of four mechanisms: a chunked mint or burn against a holder snapshot, a declared dividend, a link to an attached program, or one pool split across share classes. Use this page to look up which mechanism a type uses and what a status or a holder-state value means. For the create, preview, confirm, and abort sequence itself, read [Corporate actions](https://docs.settlemint.com/docs/api-reference/guides/corporate-actions). For request and response fields, use [the v2 API explorer](https://docs.settlemint.com/docs/api-reference/v2).

## Type directory [#type-directory]

| Type | Mechanism | Completes on create |
| --- | --- | --- |
| `cashDividend` | Declares a dividend-yield dividend. Paid in kind (a stock dividend), it is the same chunked mint as an in-kind coupon | No |
| `bondCoupon` | Names an attached fixed-treasury-yield program. Paid in kind, it is a chunked mint of the floored ratio amount to every holder | Yes, or No when paid in kind |
| `bonusIssue` | Chunked mint of `floor(balance × numerator / denominator)` to every snapshot holder | No |
| `rightsIssue` | Chunked mint of the floored ratio amount to entitled holders, whole rights into an existing rights token named in `rightsTokenAddress`, paging a token sale whitelist (sent with no ratio, it adds every holder and mints nothing), or closing a tradable issue by minting the new shares for the exercised rights and burning every right. A second operator approves before confirm when the organisation turns on the approval | No |
| `capitalDecrease` | Chunked burn of announced per-holder amounts. A second operator approves before confirm when the organisation turns on the approval | No |
| `stockSplit` | Chunked mint (forward) or chunked burn (reverse) of the difference between the rounded ratio amount and the current balance. A reverse split can also mint a holder up to one share and pay cash in lieu, as [Stock split direction](#stock-split-direction) describes. A second operator approves before confirm when the organisation turns on the approval | No |
| `spinOff` | Chunked mint of the same floored ratio amount on a separate, existing child token | No |
| `maturityRedemption` | Names an attached maturity-redemption program and calls its `mature()`. The record reads `redemptionOpen` once it lands, `completed` when no token is left | No |
| `distribution` | Declares a dividend-yield dividend under the distribution name. Paid in kind, it is the same chunked mint as an in-kind coupon | No |
| `partialRedemption` | Chunked burn of announced per-holder amounts, optionally with a cash leg. A second operator approves before confirm when the organisation turns on the approval | No |
| `conversion` | Names an attached conversion program | Yes |
| `buyback` | Chunked burn of announced per-holder amounts, or of every holder's full balance, optionally with a cash leg. A buyback needs a second operator's approval before confirm when the organisation turns on the approval, whether or not it has a cash leg | No |
| `coordinatedDistribution` | Funds the instrument's distribution waterfall once from one pool, then declares one dividend-yield dividend per share class in rank order. A second operator approves before confirm when the organisation turns on the approval | No |

Seven composition types share a computed or announced holder snapshot: `bonusIssue`, `rightsIssue`, `capitalDecrease`, `stockSplit`, `spinOff`, `partialRedemption`, and `buyback` orchestrate a chunked mint or burn against it, and they share the [in-flight limit](#in-flight-limit). A `cashDividend` or `distribution` paid in cash stores allocations for its linked dividend snapshot instead. Creating either record already declares the dividend on chain, and Confirm later commits the reviewed snapshot. A bond coupon paid in cash and a conversion complete on create, and a maturity redemption reads `redemptionOpen` when its `mature()` transaction lands, then `completed` once every holder has redeemed. `coordinatedDistribution` stores no holder allocations: it is raised on the share class that carries the `distribution-waterfall` feature and pays every class of the instrument, as [Coordinated distributions across share classes](https://docs.settlemint.com/docs/api-reference/guides/corporate-actions#coordinated-distributions-across-share-classes) describes.

## Status lifecycle [#status-lifecycle]

| Status | Meaning |
| --- | --- |
| `drafted` | Recorded and awaiting preview. A `cashDividend` or `distribution` paid in cash has already been declared on chain |
| `previewed` | Has a stored allocation snapshot. A partial redemption, stock split, bonus issue, rights issue, spin-off, capital decrease, coordinated distribution, buyback, dividend or distribution paid in cash or in kind, or bond coupon paid in kind waits here for a second operator's decision when the organisation has turned on the approval |
| `approved` | Cleared for execution and not running: a second operator approved the plan, or confirm cleared a record that needs no approval |
| `executing` | Submitted transactions are still being reconciled |
| `redemptionOpen` | A maturity redemption whose `mature()` transaction landed. Holders redeem their own tokens. Not in flight, and abort is refused |
| `completed` | The selected mechanism has completed: a composition applied its allocation, a dividend snapshot was confirmed, or an existing program was linked |
| `aborted` | The run is closed to further submission. Already submitted transactions still need reconciliation |
| `releasing` | An action that marked custodial contracts and has ended (aborted, rejected, lapsed or finished) while a contract may still carry its freeze. Holds new compositions and in-kind payouts, not mint or burn. `releasingTo` names the end it waits for. A supply manager releases it with abort, and it ends once no contract carries the freeze |

The second operator's decision applies once the organisation turns on the `corporate-actions` row of its approval policy. Until then, or while no second operator can staff it, the record confirms without a decision and `approval.waiver` names the reason. Turning the row on, or adding an approver, puts a waived record back under the gate when it is confirmed, except a `cashDividend` or `distribution` paid in cash, which keeps its waiver. A rejected or expired approval ends the record `aborted`, through `releasing` when it marked custodial contracts, and its `approval.state` reads `denied` or `expired`. See [Approve or reject a plan](https://docs.settlemint.com/docs/api-reference/guides/corporate-actions#approve-or-reject-a-partial-redemption).

A completed dividend or program-link record does not mean holders have claimed. Holders claim through the attached feature.

Snapshot drift refuses confirm with `CORPORATE_ACTION_SNAPSHOT_DRIFT` (DALP-12056) and leaves the record open, so abort it before you raise another action on the token. A refusal before execution applies nothing. A rights-issue close refused during its burn keeps the shares it minted, so raise a follow-up with `followsUpOn` instead of a new close. A staged supply run whose batch reverts or stops after sending ends `aborted`. A batch the transaction queue never accepted is handed back, and the next confirm sends it again. An aborted run cannot resume or roll back applied holders. A follow-up composition can link to it with `followsUpOn`, so preview excludes holders already applied in the linked sequence. See [Corporate actions](https://docs.settlemint.com/docs/api-reference/guides/corporate-actions#create-preview-confirm) for retry and reconciliation behaviour.

## In-flight limit [#in-flight-limit]

A token accepts only one composition-type record in flight at a time. A record is in flight until it reaches `completed` or `aborted`, so a record waiting for approval holds the slot. The same limit blocks primitive mint and burn on that token while the record is in flight. A `cashDividend`, `bondCoupon` or `distribution` paid in kind (`paymentKind: "inKind"`) is a composition for this limit. `maturityRedemption`, `conversion`, and a `cashDividend`, `bondCoupon` or `distribution` paid in cash do not count toward it.

A `coordinatedDistribution` has its own limit, across the instrument rather than the token: an instrument accepts one open coordinated distribution at a time. While it is open, no cash `cashDividend` or `distribution` can be created on any of the instrument's share classes, and it cannot be created while one of them is open. A completed or aborted run stays visible in the asset's in-flight strip while a class waits for reclaim or release, and leaves it once nothing waits. Each class on the record reports `state` (it adds `releasing` and `released`), `dividend`, and `recovery`, and the split reports `distributionId`. [Reclaim and release a class's money](https://docs.settlemint.com/docs/api-reference/guides/corporate-actions#reclaim-and-release-a-classs-money) describes the two routes that act on them. Once a class is reclaimed or released, the platform keeps a record of each holder that class owed and did not pay. [Holders a class did not pay](https://docs.settlemint.com/docs/api-reference/guides/corporate-actions#holders-a-class-did-not-pay) describes how to list that record and mark a holder paid off-chain.

## Holder state [#holder-state]

The record's `holders` field is an array, empty before an allocation is stored. Each entry contains `holder`, `amount` and `state`, and optionally `transactionHash`, `direction` (`burn` or `mint`), `classToken`, `balance`, `residual` and `roundingAdjustment`.

| Holder state | Meaning |
| --- | --- |
| `remaining` | Allocation still to apply |
| `applied` | The action's on-chain operation has applied this allocation |
| `skipped` | The execution isolated this holder from the applied allocation |
| `zeroAfterFloor` | The computed amount is zero and needs no transaction |

Composition amounts use token base units. Cash-dividend and distribution amounts use denomination-asset base units. For those two types, `applied` records commitment of the dividend snapshot, not the holder's later payment claim. The record has no separate per-holder skip-reason field. When a batch stopped before reaching some holders, `snapshot.batchFailure` carries the `reason` the transaction queue gave and the `unreached` holders.

Derive counts from these states when presenting progress. Do not treat the array as an aggregate count object.

## Stock split direction [#stock-split-direction]

`stockSplit` takes a `direction` of `forward` or `reverse`. Forward mints `floor(balance × numerator / denominator) − balance` to each holder when that delta is positive. Reverse burns `balance − floor(balance × numerator / denominator)`. Both directions apply through chunked mint or burn, never an atomic on-chain rebase, so the token must stay unpaused for the entire run: see [How a stock split applies](https://docs.settlemint.com/docs/api-reference/guides/corporate-actions#how-a-stock-split-applies).

These formulas use the default `fractionPolicy`, `floor`, which drops the part of each result below one base unit of the token. A reverse split can set `fractionPolicy` to `wholeShareFloor`, which drops the part below one whole share, so a holder whose result is less than one share ends with none. `roundUpToOne` rounds the same way, but a holder whose result is more than zero and less than one share ends with exactly one share. If that holder held less than one whole share before the split, the platform mints the difference, so one reverse split run can burn from some holders and mint to others. A forward split refuses `wholeShareFloor` and `roundUpToOne`, because it only mints and cannot take back the part of a holding below one whole share.

Cash in lieu pays each holder for the part of the holding that a reverse split does not convert to a whole share. Send `denominationAsset`, `pricePerUnit` and `payingTreasury` together, with a `fractionPolicy` of `wholeShareFloor` or `roundUpToOne`. `denominationAsset` is the ERC-3643 token indexed in the platform that pays, such as a deposit token. `pricePerUnit` is the cash for one whole pre-split share, in base units of that token, and must be greater than zero. `payingTreasury` is the smart-account wallet that pays and the wallet the confirm runs from. Each unit of up to ten holders is burned and paid in one transaction, so a holder is burned and paid together or not at all. A holder's cash is the pre-split shares the split did not convert, times `pricePerUnit`, rounded down to one base unit of `denominationAsset`. A holder rounded up to one share is paid nothing, and so is a holder whose cash rounds down to zero.

Confirm is refused while the treasury holds less than the total cash. It is also refused when the confirm does not run from `payingTreasury`, when that wallet is not a smart wallet, when `denominationAsset` is the split token or is not an ERC-3643 token indexed in the platform, or when the token charges a burn fee. Every other ratio event, including a forward split, a bonus issue, a spin-off and a rights issue, pays no cash for a fraction: each result is rounded down and the remainder is dropped.

## What the catalogue does not do [#what-the-catalogue-does-not-do]

The catalogue has no atomic on-chain rebase, no instrument halt, and no capital-account ledger. The only cash it pays for a fraction is cash in lieu on a reverse split, as [Stock split direction](#stock-split-direction) describes.

## Tradable rights, cash legs and issuer calls [#tradable-rights-cash-legs-and-issuer-calls]

A rights issue with `path: "tradable"` mints rights into an existing rights token and names a `payee`, the account that receives every exercise payment and the exercised rights. The payee must be an account registered to the organisation's on-chain identity on the token's network, such as one of the organisation's executor wallets. It cannot be a member's wallet, another organisation's account, an unregistered account, an account on another network, or the wallet the rights issue is declared from. The payee is part of the approved plan, is checked again at every exercise, and an account that does not qualify or cannot receive them is refused with `CORPORATE_ACTION_RIGHTS_PAYEE_INVALID`. Holders trade the rights on the venue and exercise whole rights during the subscription period with `POST /api/v2/tokens/{assetId}/corporate-actions/{corporateActionId}/rights-exercises`, paying the subscription price in the denomination asset. After the period ends, a rights issue with `path: "close"` mints one new share for every exercised right to the exercising holders and, once those shares have landed, burns every right, the exercised ones and the lapsed ones, in the same approved confirm. Its plan lists the rights it burns as `snapshot.rightsBurn`, and a second operator approves it before confirm when the organisation turns on the approval. A holder who exercised every right can also apply for excess shares with `POST .../rights-excess-applications`, paying into escrow with the organisation's operations signer. The close allots the lapsed rights to those applicants pro-rata to excess demand, rounded down to whole shares, mints the allotted shares with the exercised ones, and in the same confirm pays the payee for them and refunds the rest. Its plan lists each applicant in `snapshot.rightsExcess`. The Console close review shows the same list as an Excess applications table to the operator and the approver. See [Apply for excess shares](https://docs.settlemint.com/docs/api-reference/guides/corporate-actions#apply-for-excess-shares). A partial redemption may declare a cash leg: each unit of up to ten holders is paid on the denomination asset and burned in one smart-account transaction, so a holder is settled whole or left untouched, and a unit that fails ends the run `aborted` with the remaining holders still open for a second run. A cash leg needs a smart-account executor. A buyback takes the same cash leg, and every buyback, with or without one, needs a second operator's approval before confirm when the organisation turns on the approval. A buyback sent with `call: "all"` and no `holders` is an issuer call: preview reads the holder book and burns every holder's full balance, and the cash leg is required. Confirm is refused with `CORPORATE_ACTION_SNAPSHOT_DRIFT` if any holder's balance moved since preview, so the call always covers all holders and never some. When the token's metadata records a `firstCallDate`, confirm is refused with `CORPORATE_ACTION_CALL_PROTECTED` before that date. A `longStopDate` in the metadata opens the call on that date when it comes first, so every holder can be redeemed on the long-stop date whatever the first call date says. It counts only when the token recorded it as immutable at issuance, with the first call date. A long-stop date added later, or one that can still be edited, leaves the call protected until the first call date. A calendar date (`YYYY-MM-DD`) starts that day in UTC, and a value that is neither a calendar date nor a date and time with a UTC offset is refused the same way.

## Next steps [#next-steps]

- [Corporate actions](https://docs.settlemint.com/docs/api-reference/guides/corporate-actions) for the create, preview, confirm, and abort sequence and the stock split pause caution.
- [Corporate actions in the Console](https://docs.settlemint.com/docs/console/asset-management/manage/corporate-actions) for the same catalogue driven from screens.


# Corporate actions

Source: https://docs.settlemint.com/docs/api-reference/guides/corporate-actions
Declare a corporate action, preview its effect on holders, then confirm or abort. Covers chunked mint or burn, the in-flight limit, and redemption approval.

## Overview [#overview]

The corporate actions catalogue is one collection, `/tokens/{assetId}/corporate-actions`, that records a named lifecycle event on an issued security, then runs the mechanism that applies it to holders. `type` names the legal event: a cash dividend, a bond coupon, a bonus issue, a rights issue, a capital decrease, a stock split, a spin-off, a maturity redemption, a distribution, a partial redemption, a conversion, a buyback, or a coordinated distribution across share classes. A supply change runs as create, preview and confirm, with abort to stop it, in place of minting or burning to each holder yourself. For the status lifecycle and the in-flight rule across all thirteen types, read [the corporate actions catalogue reference](https://docs.settlemint.com/docs/api-reference/guides/corporate-actions-catalog). For the request and response fields of each route, use [the v2 API explorer](https://docs.settlemint.com/docs/api-reference/v2).

Create checks what the token carries before it records anything, and the asset type plays no part. A missing feature is refused with `CORPORATE_ACTION_PROGRAM_MISSING`. Missing capital, or a type the `register-lines` feature excludes, is refused with `CORPORATE_ACTION_CAPABILITY_MISSING`.

| Type | Feature the token needs | Capital the token needs | On a `register-lines` token |
| --- | --- | --- | --- |
| `cashDividend` or `distribution` paid in cash | `dividend-yield` | None | Accepted |
| `cashDividend` or `distribution` paid in kind | None | `share-capital` or `unit-capital` | Refused |
| `bondCoupon` paid in cash | `fixed-treasury-yield` | None | Accepted |
| `bondCoupon` paid in kind | `maturity-redemption` | None | Refused |
| `maturityRedemption` | `maturity-redemption` | None | Accepted |
| `partialRedemption` | `maturity-redemption` | None | Refused |
| `conversion` | `conversion` | None | Accepted |
| `coordinatedDistribution` | `distribution-waterfall` and `dividend-yield` | None | Accepted |
| `bonusIssue`, `rightsIssue` | None | `share-capital` | Refused |
| `capitalDecrease`, `stockSplit`, `spinOff`, `buyback` | None | `share-capital` or `unit-capital` | Refused |

The token read's `capabilities` lists what a token carries. A token linked to a template keeps the capabilities that template declared when the token was issued. A token with no template link gets them derived when it is read, from its asset type and its attached features: equity without an attached `conversion` feature has `share-capital`, fund and real-estate have `unit-capital`, and any other type has none. `cashDividend` and `distribution` are the same payout and are both accepted on any token with `dividend-yield`. A token with the `register-lines` feature, which the Console calls Booked movements, refuses the types the table marks, because its units move only through a booked movement.

Creating a `cashDividend` record, or a `distribution` paid in cash, already declares the dividend on chain through the dividend-yield feature. Review the approved terms before create. Preview and confirm happen after that declaration, and the [payout eligibility check](#check-payout-eligibility-before-declaring) runs before it. Preview of a cash dividend is refused with `snapshot-not-ready` (HTTP 409, DALP-12051) until the record date has passed on chain and its block is final. Send it again after that. A declared dividend can still be cancelled until its record-date snapshot is recorded.

`GET /api/v2/tokens/{assetId}/features/issuer-stats?feature=dividend-yield` reports the payout asset's available funding, the unclaimed amount already payable, and the projected amount committed to other dividends. When you read it for a corporate-action plan, add `excludeDividend` with that plan's dividend id so the projection does not count the plan itself.

Three types name an attached feature program (bond coupon, maturity redemption, conversion): a holder claims yield, redemption, or conversion on that feature's own routes afterward, not through this catalogue. A bond coupon and a conversion complete the moment you create them. A maturity redemption calls the bond's `mature()` on create. The record stays `executing` until that transaction lands, then reads `redemptionOpen`. Create answers `202` with the `executing` record while `mature()` is queued, unless `Prefer: wait` let it land within the request. Read the record, or replay the same `Idempotency-Key`, to see it settle. Holders then redeem their own tokens. Nothing is paid to them automatically. The record stays `redemptionOpen` while any token of the bond is outstanding, and reads `completed` once every holder has redeemed and the bond's supply is zero. A bond with no supply left when `mature()` lands reads `completed` at once. Create is refused with `maturity-date-not-reached` (HTTP 409, `CORPORATE_ACTION_MATURITY_DATE_NOT_REACHED`, DALP-14049) before the maturity date on chain, and with `bond-already-matured` (HTTP 409, `CORPORATE_ACTION_BOND_ALREADY_MATURED`, DALP-14050) once the bond has matured. Both carry `data.maturityDate`. Abort of an `executing` maturity redemption is refused while its transaction may still land, and returns the record `redemptionOpen` when the bond has matured. Abort of a `redemptionOpen` record is refused, because the bond has already matured. A `redemptionOpen` record is not in flight and raises no webhook event. A `completed` record raises the usual completion event.

Seven types use stored holder allocations, and this page calls them the composition types: bonus issue, rights issue, capital decrease, stock split, spin-off, partial redemption, and buyback. Most apply mint or burn batches. A rights issue sent with `path: "tokenSale"` instead adds holders to the whitelist of the token sale named by `tokenSaleId`. With no `numerator` and `denominator` it adds every holder on the book and mints nothing: quote, preview and confirm list each holder with an amount of `0`, and `filter[receives]=true` keeps all of them. With a ratio it adds the holders the ratio entitles. Half a ratio is refused. A bonus issue, an allotment rights issue, and a spin-off mint the floored ratio amount itself.

A rights issue sent with `path: "tradable"` mints whole rights, in proportion to the holders on the `recordDate`, into an existing rights token. The share balances do not change. The terms name the `rightsTokenAddress`, the ratio, `exDate`, `recordDate`, `tradingEnd`, the `denominationAsset` and `subscriptionPrice` a holder pays later, the `payee` wallet that receives each payment and the exercised rights, and the subscription window `subscriptionStart` to `subscriptionEnd`. `referencePrice` is optional. `recordDate` is required, and the dates must run in this order: `exDate` before `recordDate`, `recordDate` before `tradingEnd`, `tradingEnd` before `subscriptionEnd`, and `subscriptionStart` on or after `recordDate` and before `subscriptionEnd`. The end of the subscription window is when the rights expire. The rights token must be empty, carry the hold feature, and use the same decimals as the share token. The subscription asset must be a token indexed in this system. Create, preview, and confirm refuse a subscription asset that is the share token or the rights token with `rights-subscription-asset-invalid` (HTTP 409, `CORPORATE_ACTION_RIGHTS_SUBSCRIPTION_ASSET_INVALID`, DALP-184651). Each holder receives the balance times the ratio, rounded down to a whole right. The record's `childTokenAddress` is the rights token. Create, preview, and confirm refuse a rights issue once `tradingEnd` has passed with `rights-trading-ended` (HTTP 409, `CORPORATE_ACTION_RIGHTS_TRADING_ENDED`, DALP-184652). Abort the rights issue and declare a new one to correct either terms field. A second operator approves the plan before confirm when the organisation has turned on the `corporate-actions` approval, as [Approve or reject a plan](#approve-or-reject-a-partial-redemption) describes. A spin-off adjusts the ratio for any difference between parent and child token decimals. A stock split mints or burns the difference between that amount and the holder's current balance. A capital decrease, a partial redemption, and a buyback burn the amount you announce per holder.

A bonus issue, a rights issue, a stock split, and a spin-off count holders when preview runs, and accept an optional `recordDate`. Without it, preview reads the holder book at the moment it runs. With one, preview is refused while that date is still ahead of the chain time the indexer has reached. Once the date is reached, preview reads the holders at that date from the token's historical-balances feature. A date before the feature began is refused. For a token without that feature, preview reads the current holder book while the indexed chain time is within one minute after the date, and is refused later. A preview that reads the current holder book waits until the indexer has caught up with chain finality as it stood when the preview started, and is refused as unavailable only if that takes longer than 30 seconds. The stored snapshot `recordDate` is the instant whose holders were counted: the record date when preview read the holders at it, otherwise the instant preview read the book. Preview reads the whole holder book whatever its size, and refuses rather than plan from a partly read one.

On a mirror token, preview of any corporate action is refused with `reconciliation-break-open` (`CORPORATE_ACTION_RECONCILIATION_BREAK_OPEN`, HTTP 409, DALP-184676) while a reconciliation break on the token, first seen on or before the record date, is open or under investigation. Without a record date, the day preview runs counts as the record date. Nothing is stored. Resolve the break, or write it off through its approval, then send preview again. See [Mirror tokens](https://docs.settlemint.com/docs/concepts/records-and-evidence/mirror-tokens#corporate-actions-wait-for-reconciliation).

A `cashDividend`, `bondCoupon` or `distribution` sent with `paymentKind: "inKind"` pays holders in new units of the token instead of cash. An in-kind `cashDividend` is a stock dividend. It carries `numerator`, `denominator`, and an optional `recordDate`, and none of the cash terms. It then runs as a composition type: it mints the floored ratio amount to every snapshot holder, takes the token's in-flight slot, and needs a second operator's approval before confirm when the organisation has turned on the `corporate-actions` approval. Its `recordDate` follows the same rule as a bonus issue. Omitting `paymentKind` means `cash`, which keeps the behaviour described above.

### Check payout eligibility before declaring [#check-payout-eligibility-before-declaring]

Declaration is refused with `CORPORATE_ACTION_PAYOUT_INELIGIBLE` (DALP-14021) when the check finds a holder with a positive payout whose claim would fail because the payout token refuses the transfer from the treasury. A holder fails when it is not verified in the payout token's identity registry, or when the payout token's compliance refuses that holder's payout. On a V1 payout token, or a registry that only records membership, the registry test is whether the holder is registered. When the payout token charges a transfer fee, the net payout and the fee leg to the fee recipient are each checked.

A record date in the future is checked against current holders and balances, and a past record date against the holders and balances on that date. Holders whose identity is marked lost are skipped, because the snapshot pays them nothing. The treasury and venue fee accounts block a declaration only when they also hold the dividend token at the record date and so receive a payout. The check probes the largest 250 holders, by balance and then address. A probe that gets no answer in time does not block. A declaration that passes can therefore still leave holders whose claims fail: a holder outside the largest 250, a holder whose probe timed out, or a holder whose verification changes after declaration.

When the payout token charges an external transfer fee in a separate fee token, the treasury pays it on every claim, so its fee-token balance and its allowance to the fee feature must cover one fee per paying holder, including paying holders beyond the largest 250. The claims beyond that capacity are refused. What is left for the new dividend excludes what the same treasury's other open dividends still need. An open dividend that charges its fee in the same fee token reduces the available balance, unless the treasury itself receives that fee. One that uses the same fee feature reduces the available allowance. When an open dividend pays out in the fee token itself, its unclaimed payouts reduce the available balance.

The refusal's `ineligibleCount` says how many holders failed. To see each party's reason, call the denomination eligibility read, `GET /api/v2/tokens/{assetId}/features/dividend-yield/denomination-eligibility`, which asks for the token's governance role. It lists the largest 250 holders and sets `holdersTruncated` when there are more. It also lists the treasury and venue fee accounts, even when they do not block. Because the fee count covers every paying holder, `ineligibleCount` can exceed the parties the read lists.

## Create, preview, confirm [#create-preview-confirm]

A composition type follows four steps: create, preview, confirm, and, if needed, abort. A partial redemption, a stock split, a bonus issue, a rights issue, a spin-off, a capital decrease, a buyback, and a dividend, bond coupon or distribution paid in kind, add a fifth between preview and confirm when the organisation has turned on the `corporate-actions` approval: a second operator approves or rejects the previewed plan, as [Approve or reject a plan](#approve-or-reject-a-partial-redemption) describes.

```bash
curl -X POST "https://your-instance.example.com/api/v2/tokens/0x8a791620dd6260079bf849dc5567adc3f2fdc318/corporate-actions" \
  -H "X-Api-Key: sm_dalp_..." \
  -H "Idempotency-Key: split-2026-09-03-001" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "stockSplit",
    "direction": "forward",
    "numerator": 3,
    "denominator": 1
  }'
```

The returned record includes the fields below. This excerpt omits timestamps, related identifiers, `approval` and `appliedSplit`:

```json
{
  "id": "0198f1a2-3c4d-7e8f-9a0b-1c2d3e4f5a6b",
  "tokenAddress": "0x8a791620dd6260079bf849dc5567adc3f2fdc318",
  "type": "stockSplit",
  "status": "drafted",
  "terms": {
    "type": "stockSplit",
    "direction": "forward",
    "numerator": 3,
    "denominator": 1
  },
  "snapshot": null,
  "holders": [],
  "transactionHashes": []
}
```

For a composition type, create stores the event as `drafted` without applying the supply change. A composition type takes only one in-flight record per token: creating a second composition record while the first is not `completed` or `aborted` is refused with `CORPORATE_ACTION_IN_FLIGHT` (HTTP 409, DALP-12067), and the same code refuses a primitive mint or burn on that token while the record is in flight. Wait for the open record to reach `completed`, or abort it, then send the call again. A second spin-off or tradable rights issue that would mint into the same token as an open one is refused with the same code. Send `Idempotency-Key` on create so a retried request replays the same record instead of declaring the event twice. See [Idempotency and async settlement](https://docs.settlemint.com/docs/api-reference/guides/idempotency-async-settlement) for the header contract that every mutating route on this catalogue shares. Reusing a key with different terms is refused with `CORPORATE_ACTION_IDEMPOTENCY_CONFLICT` (HTTP 409, DALP-12065), because replaying would change what the first request created. Send a new key for a new create, or repeat the original request unchanged.

Preview computes and stores the allocation snapshot without applying anything:

```bash
curl -X POST "https://your-instance.example.com/api/v2/tokens/0x8a791620dd6260079bf849dc5567adc3f2fdc318/corporate-actions/0198f1a2-3c4d-7e8f-9a0b-1c2d3e4f5a6b/preview" \
  -H "X-Api-Key: sm_dalp_..." \
  -H "Content-Type: application/json" \
  -d '{}'
```

Ratios travel as two positive integers, `numerator` and `denominator`, on every write and read. The API takes no percentage. To send a ratio announced as a percentage, write the percentage as an integer over a power of ten and reduce it: 10.59% is 1059 / 10000, so send `numerator: 1059` and `denominator: 10000`, and 20% is 1 / 5. The Console accepts a percentage with up to four decimal places and converts it the same way before it calls the API.

The preview response contains `corporateAction`, including its snapshot and `holders` array. Each holder entry has an address, amount, state, and `balance`, the holder's balance at the snapshot. A plan stored before `balance` existed answers `balance: null`. Nonzero allocations start as `remaining`. Amounts that floor to zero start as `zeroAfterFloor`. Per-holder amounts round down: a ratio type computes `floor(balance × numerator / denominator)` for each holder, and the record's `remainder` is the sum over holders of `(balance × numerator) mod denominator`, counted in denominator-ths of a base unit rather than in whole base units. A holder whose amount floors to zero is stored as `zeroAfterFloor` and never receives a chunk. Read the computed snapshot against the approved terms before you confirm. Nothing has moved yet.

Confirm applies the stored preview. It fails without one for a composition type. Confirm answers `200` with the record when nothing it sent is still in flight, and `202` with the same record and `Location` set to the record read while the record is `executing`. See [Idempotency and async settlement](https://docs.settlemint.com/docs/api-reference/guides/idempotency-async-settlement#prefer-choose-sync-or-async) for how `Prefer: wait` changes that. A partial redemption or buyback with a cash leg sends one unit at a time, each unit paying and burning together: when a unit is still queued at the end of the request, send the same confirm again once it lands, and the run continues from the next unit. A supply change can require multiple on-chain batches. Follow an accepted transaction handle and read the corporate-action record to reconcile the holder states. A plain read of a record that is still `executing`, whether a get or a list, reconciles it against the batches that landed: the record reads `completed` once every batch has settled, and `aborted` when a batch failed. A record that marked custodial contracts reads `releasing` first, as described below. A completed mint or burn composition has applied every snapshot holder, recorded a zero allocation, or skipped a holder whose election takes nothing. A pause or missing historical-balance watermark blocks confirmation. A record whose batch failed ends `aborted` and cannot resume. Review any applied holders before starting another action. A buyback sent with `call: "all"` is refused with `CORPORATE_ACTION_SNAPSHOT_DRIFT` (DALP-12056) when holder balances have moved since preview, so abort it and raise a new call.

Some plans leave value behind, so confirm needs `acknowledgements`, one entry for each consequence the stored plan has: `not-declared` for a class whose dividend is not declared, `residue` for money a declared class leaves in the waterfall, `excluded-holders` for a holder left out or rounded to zero, and `underfunded` for a funding shortfall. The platform reads these consequences from the stored plan, not from the request. When an entry is missing, confirm is refused with `CORPORATE_ACTION_ACKNOWLEDGEMENT_REQUIRED` (HTTP 409, DALP-14107) and `data.missingAcknowledgements` lists the missing entries. The rule is the same for a plan a second operator approved: that approval does not acknowledge anything for the operator who confirms. A record that is already executing or settled is not checked again, so a confirm that resumes a run does not need them.

Abort stops a `drafted`, `previewed`, `approved`, or `executing` record. Status becomes `aborted`, or `releasing` first for a record that marked custodial contracts, and the platform submits no further chunk. A chunk already submitted when abort lands can still apply, so read the record's `holders` before you raise a follow-up. Holders already applied when abort lands keep their change: abort does not roll back. For a composition type, confirm of a `completed` record answers that record, and so does confirm of an `aborted` record, so replaying the confirm `Idempotency-Key` after an abort returns the aborted record and runs nothing. A record that a rejection or a lapsed approval ended is the exception: confirm refuses it.

An action with a custodial step can mark custodial contracts with a freeze when it is created: a `stockSplit`, a `bonusIssue`, a non-tradable `rightsIssue`, and a `cashDividend`, `distribution` or `bondCoupon` paid in kind. A record that marked custodial contracts, or whose plan re-sizes a custodian's records, never ends straight from an open status: an abort, a rejection, a lapsed approval and a finished run all move it to `releasing` first. `releasing` keeps the token's one open composition slot, so a create of a composition or an in-kind payout on the token answers `409` naming the releasing record. Mint, burn and cash payouts are not held. The record leaves `releasing` only once a chain read of every marked contract finds none carrying the freeze and no freeze request the record queued can still land. A freeze request that failed, or was dead-lettered before it reached the chain, cannot land and does not hold the record. A freeze that lands after the record ended `aborted` takes it back to `releasing`, and the next abort of it releases it. Its `releasingTo` field names where it goes: `aborted` after an abort, a rejection or a lapsed approval, and `completed` after a finished run. A get or list of the record runs that check, and so does the Actions inbox. A chain or queue read that fails leaves the record `releasing`.

Once a run has started moving the units behind custodial records, abort refuses it with `run-completed` (`CORPORATE_ACTION_RUN_COMPLETED`, DALP-14072) and lifts no freeze: the records stay frozen until the run finishes, so confirm the action again to finish it. This also holds when the abort arrives while confirm is starting that run.

Any wallet that holds the token's supply management role releases the record by sending abort on it with wallet verification. On a record bound for `aborted`, that call writes the custodial step to each contract whose own units the run already moved, and queues a lift of every other freeze the record marked, including one on a contract that drained before the record date. A run whose holder batch failed part way is bound for `aborted`, never `completed`, and a contract whose units never arrived takes no step. On a record bound for `completed`, it sends again every custodial step that has not landed and lifts the freeze only on a contract that took no step, because a step that lands clears its contract's freeze. Abort sends no second step, catch-up or lift whose same call still waits in the queue or for a custody approval. Every record response carries `releaseInFlight`: `true` while a lift, custodial step or catch-up of the release waits, `false` when none does or the record is not `releasing`, and `null` when the queue could not be read, so whether one waits is unknown. Each abort sends its calls under idempotency keys of its own, so an abort after a failed or dead-lettered request sends it again, and a step that cannot be sent does not stop the lifts. Until the chain is clear, abort answers the `releasing` record. With `Prefer: respond-async` the lift is queued and the record stays `releasing` until it lands. The next read, or another abort, ends it. A lift that fails or is cancelled leaves the record `releasing`, and another abort sends a new lift. Abort of a `releasing` record whose freezes are already lifted answers the ended record, and two aborts at once end it once and both answer the record. A record whose create never placed a freeze on chain, with no freeze request left in the queue, ends in the same call. An abort sent while the create is still queueing its freezes answers a `releasing` record that keeps the token until those freezes are queued and lifted. A record whose create stopped before it recorded its freezes stops waiting for them 30 minutes after it was created. When a freeze lands after a record already ended `aborted` and a newer action holds the token, abort lifts it once it has landed and is refused while it still waits in the queue.

A cash dividend or cash distribution declares its dividend on chain when you create it, and abort does not cancel that dividend. Abort of such a `drafted`, `previewed`, or `approved` record is refused with `409 CORPORATE_ACTION_DIVIDEND_DECLARED` while the dividend is not cancelled. The error's `data.dividendId` names it. Cancel it with `POST /api/v2/tokens/{assetId}/features/dividend-yield/dividends/{dividendId}/transitions` and `{"transition": "cancel"}`, then abort again. A dividend whose snapshot is already recorded can no longer be cancelled, so confirm that record to complete it instead.

## Approve or reject a plan [#approve-or-reject-a-partial-redemption]

An organisation can require a second operator before confirm for a `partialRedemption`, a `stockSplit` (forward or reverse), a `rightsIssue`, a `capitalDecrease`, a `coordinatedDistribution`, a `buyback` that declares a cash leg, a `cashDividend` or `distribution` paid in cash or in kind, and a `bondCoupon` paid in kind, because none of them can be undone after confirm. The requirement starts off: it applies once the organisation turns on the `corporate-actions` row of its approval policy, and it is waived while the organisation has no owner other than the author. Every record carries an `approval` block. Its `policy` reads `required` when the record waits for that decision. Its `state` reads `pending` until someone decides. Its `proposerUserId` is the user who opened the approval, and its `lastPreviewedBy` is the user who previewed the plan last. Neither can approve it. Its `planDigest` identifies the plan the record holds now. Its `approvedByViewer` is `true` when the caller's own approval is already recorded on the record's current approval request. With an approval policy that needs more than one approver, `state` stays `pending` after that approval until enough others approve, and the caller does not decide again. Its `approvalsNeeded` counts the approvals the pending approval request still needs, and reads `null` when no approval request is pending. Other types read `not_required` or `not_applicable` and confirm exactly as [Create, preview, confirm](#create-preview-confirm) describes.

After preview, a different person reads the stored plan and sends its `planDigest` back as `reviewedDigest` to `POST .../corporate-actions/{corporateActionId}/decisions` with `decision: "approve"`:

```json
{ "decision": "approve", "reviewedDigest": "3b8f1d2c4a5e6f708192a3b4c5d6e7f8091a2b3c4d5e6f708192a3b4c5d6e7f8" }
```

Approve moves the record to `approved`, and confirm can then run it. Reject, on `.../decisions`, takes the same digest and a required, non-empty `reason`. It ends the record `aborted` with approval state `denied` (`releasing` first when it marked custodial contracts, see abort) and keeps the reason on the record. Neither call signs or queues a transaction for the action itself, but each needs a wallet step-up, like every other corporate action write. A cash dividend or cash distribution is the exception: rejecting it, or sending a decision after its approval window closed, first cancels the dividend it declared, through the same `dividend-yield` cancel and with the checker's wallet, so the checker needs the token's governance role for that cancel. While the cancel is refused or still queued, the record stays `previewed`, the rejection stays recorded, and the decision answers `409 CORPORATE_ACTION_DIVIDEND_DECLARED` with `data.dividendId`. A rejected record cannot be previewed again. It ends once that dividend is cancelled. A decision without a wallet step-up is refused before anything is decided. A decision sent with an API key needs no step-up.

The rules a decision must pass:

- The checker is an organisation owner or a platform administrator. The checker can decide from a signed-in session or with their own API key. An impersonated session cannot decide.
- The checker did not create the record and did not run its last preview.
- The digest still matches the stored plan. A plan that moved since the checker read it is refused.
- Approve is refused when the stored preview shows the paying treasury short of the cash leg.

A refused decision answers [DALP-12165](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference#domain-rule-errors), and `data.violation` names the rule that failed.

A decision stays open for 72 hours from the last preview, or until the holder election's deadline when that is later. Each new preview replaces the plan, clears any earlier decision, and restarts that window. A late decision from an eligible decider ends the record `aborted` (`releasing` first when it marked custodial contracts) with approval state `expired`. A create on the same token does the same to a record whose window has closed, so a forgotten decision does not hold the in-flight slot. On a cash dividend or cash distribution, the dividend is cancelled first with the wallet proof of that decision, of an abort of the record, or of a coordinated distribution create on the same token. If that cancel is refused or still in flight the record stays open: a decision or an abort answers `dividend-declared`, and a create answers its conflict. Reads never send a transaction, so a lapsed record nobody acts on stays `previewed` and its dividend stays declared. The first read after the dividend is cancelled ends the record.

Confirm answers [DALP-12052](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference#domain-rule-errors) when the record holds no preview it can confirm: a record in `drafted`, such as a coordinated distribution whose new preview started and has not finished, or a confirm of a previewed cash dividend sent without the root and totals its preview returned. Preview again, then confirm.

Confirm refuses a buyback with `call: "all"` whose balances moved since preview, and a rights close whose exercises or rights held changed, with `CORPORATE_ACTION_SNAPSHOT_DRIFT` (HTTP 409, DALP-12056). It refuses a stock split whose share price moved with `CORPORATE_ACTION_PREVIEW_MISMATCH` (HTTP 409, DALP-12053). The record keeps its status and the token's in-flight slot. A refusal before execution applies nothing: preview a `previewed` record again. An approved record cannot be previewed again, so abort it and raise a new action, which needs a new approval while the gate is on. A rights-issue close refused after its new shares were minted keeps them, so abort it and raise the next close with `followsUpOn` set to the aborted one, which mints no share again.

The gate follows the `corporate-actions` row of the organisation's approval policy (`PUT /api/v2/operations/approval-policy`), and that row starts off, so an organisation turns the gate on there. Turning it off again needs the caller's wallet verification. While the organisation has the Administration approval or any protection group on, the change also waits for another owner's or a platform administrator's approval. The `CORPORATE_ACTION_MAKER_CHECKER_ENABLED` setting reads and writes the same row. An organisation with no owner other than the author cannot staff the gate either. In both cases the record opens with `policy` `not_required` and `state` `not_required`, and `waiver` names the reason: `organization-disabled` or `too-few-approvers`. Confirm checks that answer again, except on a cash dividend or cash distribution, which keeps its waiver. When the organisation can staff the gate at that point, confirm opens a pending decision on the record, which stays `previewed`, and refuses the run until a second operator approves.

A partial redemption can also declare a cash leg. Send `denominationAsset`, `pricePerUnit`, and `payingTreasury` together on create, and confirm from the paying treasury. [Tradable rights, cash legs and issuer calls](https://docs.settlemint.com/docs/api-reference/guides/corporate-actions-catalog#tradable-rights-cash-legs-and-issuer-calls) describes how the cash and the burn settle.

## Holder elections [#holder-elections]

A supply change can let each holder choose whether to take part. Send `election` in the create or quote body, or inside `terms` on commit, with a `deadline` in the future, at least two `options`, and a `defaultOption` for holders who do not choose. Each option has a `key`, a `label` and a `settlementLeg`: exactly one option is `primary`, which takes the allocation, and the others are `none`, which take nothing. Create refuses a deadline that has passed with `election-deadline-invalid` (DALP-12175). Only a type with one settlement leg can carry an election, so create refuses one on a type with no stored allocation, on any action with a cash leg (a partial redemption or buyback that pays cash, or a reverse split that pays cash for fractions), or on a rights issue through a token sale, with `election-shape-invalid` (DALP-12176). An election with fewer than two options, duplicate keys, no `primary` option or more than one, or a `defaultOption` that names no option fails request validation instead. An illustrative election:

```json
{
  "election": {
    "deadline": "2026-12-01T12:00:00Z",
    "options": [
      { "key": "take-part", "label": "Take part", "settlementLeg": "primary" },
      { "key": "decline", "label": "Decline", "settlementLeg": "none" }
    ],
    "defaultOption": "take-part"
  }
}
```

Holders choose between the preview and the deadline:

- `GET .../corporate-actions/{corporateActionId}/election` returns the `deadline`, the `options` and the `defaultOption`. An action without an election answers `election-absent` (DALP-12179).
- `POST .../corporate-actions/{corporateActionId}/election` records a holder's choice, with `holder`, `option`, the `walletVerification` and an `Idempotency-Key`. The verified wallet must be the holder named in the body, and the holder must be in the stored plan with a positive amount. A second submission before the deadline replaces the first. It is refused with `election-closed` (DALP-12171) when the record is not `previewed` or `approved` or the deadline has passed, `election-option-invalid` (DALP-12172) for an unknown option, `election-holder-ineligible` (DALP-12173) for a holder outside the plan, and `election-holder-unauthorized` (DALP-12174) when the verified wallet is not that holder.
- `GET .../corporate-actions/{corporateActionId}/election/choice/{holder}` returns the holder's recorded choice, or `choice: null` before they choose. The holder must be one of the caller's own wallets. Another address answers `election-holder-unauthorized` (DALP-12174).

The operator follows the vote with two reads, which need the role that runs the action on the token, supply management for a supply change or a payment in kind:

- `GET .../election/tally` counts the eligible holders, those who chose and those left on the default, and per option the holders and the amount. `entries` counts holders who did not choose under the default option, so it matches what confirm applies. `submittedEntries` counts submitted choices only. An option with `settlementLeg` `none` totals an amount of `0`, the change it causes, the same as in the outcome.
- `GET .../election/outcome` lists each holder with the option that applies, whether it is the default, and whether the holder stays `remaining` or is `skipped`. `final` is false before the deadline, when the outcome is still provisional. A person who may decide the action's approval, or who decided it, can read the outcome without the action's role.

Once a holder has chosen, or once the deadline has passed, preview is refused with `election-locked` (DALP-12178), so the plan the holders chose against stays fixed. A lapsed approval on such an action therefore cannot be reopened by previewing again: abort the record and record a new one. Confirm is refused with `election-open` (DALP-12177) until the deadline has passed. Confirm then skips every holder whose choice, or default, is an option that takes nothing. All `election-*` refusals answer HTTP 409.

## Exercise and close tradable rights [#exercise-and-close-tradable-rights]

Once a tradable rights issue reads `completed`, its rights exist, and a holder can exercise them during the subscription window. The exercise pays for new shares. The shares are minted when the issuer closes the issue. `POST .../corporate-actions/{corporateActionId}/rights-exercises` takes `rights`, the rights to exercise in the rights token's base units, with the `walletVerification` and an `Idempotency-Key`. `rights` must be a whole number of rights, so 5 rights on an 18-decimal rights token is `"5000000000000000000"`. The exercise runs from the caller's own wallet. One transaction moves the subscription price for each whole right, in the subscription asset, and the exercised rights, from the holder to the `payee`. The answer carries the `rights`, the `cashAmount`, the `denominationAsset` and a `status` of `submitted`, `settled` or `failed`. A repeated request with the same key returns the same exercise and moves nothing twice. The same key with a different wallet, issue or amount is refused with `CORPORATE_ACTION_IDEMPOTENCY_CONFLICT`. When the earlier exercise under that key failed, the replay is refused with `rights-exercise-invalid`, and a new key starts a new exercise. An exercise needs no second approver.

The exercise is refused with `rights-window-closed` (DALP-184671) outside the subscription window, with `rights-exercise-invalid` (DALP-184672) for more rights than the holder holds, too little of the subscription asset to pay for them, a fraction of a right, a record that is not a completed tradable rights issue, an issue that names no payee, or the payee exercising itself, with `rights-exercise-ineligible` (DALP-184673) when the holder cannot receive the new shares, and with `rights-payee-invalid` (DALP-184675) when the payee no longer qualifies to receive the payment. All of them answer HTTP 409.

`GET .../corporate-actions/{corporateActionId}/rights-exercises/{holder}` returns what that holder has exercised and settled: `rights`, `cashAmount`, `denominationAsset`, the `shares` those rights buy, and `sharesIssued`, the shares already minted to the holder. It also returns the excess shares the holder applied for (`excessShares`), what they paid for them (`excessCashAmount`), and, once a close has been confirmed, the excess shares allotted (`excessAllocated`) and the refund (`excessRefund`). Both are null before then. The holder must be one of the caller's own wallets. Another address answers not found.

### Apply for excess shares [#apply-for-excess-shares]

A holder who has exercised every right they hold can apply for more shares than their rights buy. `POST .../corporate-actions/{corporateActionId}/rights-excess-applications` takes `shares`, the excess shares in the share token's base units, with the `walletVerification` and an `Idempotency-Key`. `shares` must be a whole number of shares. The application pays the subscription price for each share, in the subscription asset, into escrow with the organisation's operations signer, not to the `payee`. The answer has the same shape as an exercise, with `kind: "excess"` and the shares applied for in `rights`. A holder can apply more than once during the subscription window. Their applications are added together.

In the Investor portal, the rights issue card on the holding page offers **Apply for excess shares** to a holder that has exercised every right while the subscription window is open. The sheet takes a whole number of shares, shows the price in the subscription asset and confirms with the wallet PIN. After the application the card shows the excess shares applied for and what the holder paid, and once the close is confirmed, the shares allotted and the refund.

An application is refused with `rights-exercise-invalid` when the holder still holds a right or never exercised one, for a fraction of a share, or for too little of the subscription asset. It is refused with `rights-window-closed` outside the subscription window and with `rights-exercise-ineligible` when the holder cannot receive new shares.

Excess shares come only from lapsed rights: the rights still held when the close is previewed, less the exercised rights the payee holds. The close shares them out like this:

- When the lapsed rights cover every application, each applicant gets every share they applied for.
- Otherwise each applicant gets the lapsed rights times their share of total excess demand, rounded down to a whole share. The shares left over by rounding are not issued.
- The quote's `rightsExcess` lists each applicant with the shares `applied` and `allocated`, the amount `paid` into escrow, and the `refund`, so the approver sees each holder's allotment before approving. The approval covers every entry.

Confirm mints the allotted excess shares with the exercised shares, in the same approved batch. The issuer's maker raises the close, and when the organisation turns on the corporate-action approval a second operator approves it, so issuing excess shares sits under the same maker-checker as the rest of the close. Once the mint and the burn have landed, the same confirm has the escrow pay the allotted shares' price to the `payee` and refund the rest to each applicant, in the subscription asset. Each entry in `snapshot.rightsExcess` reads `remaining` until then and `applied` after. When the escrow transfer is still in the queue, or the escrow cannot send it, the close stays `executing`, and confirming it again finishes the refund. When the applications or the lapsed rights change after preview, confirm refuses the close with `snapshot-drift`.

After the subscription window ends, close the issue with a new rights issue on the share token sent with `path: "close"` and the `rightsIssueId` of the tradable issue. Its plan lists each exercising holder with the shares they receive, and the quote's `rightsBurn` lists the rights it burns. Confirm mints one new share per exercised right, then burns every right, exercised or lapsed. Create, preview and confirm refuse a close with `rights-close-not-ready` (DALP-184674) before the window ends, while an exercise is still settling, or when another close of the same issue is open or finished. Raise a close after an aborted close that already minted shares as a follow-up of it, so the holders already minted are skipped. When the exercises or the rights held change after the close is previewed, confirm refuses it with `snapshot-drift`.

## Check a create before sending it [#check-a-create-before-sending-it]

`POST /api/v2/tokens/{assetId}/corporate-actions/preflights` takes the same body as create and answers `{ "action": "createCorporateAction" }` when the platform would accept it now. It stores nothing, queues nothing and needs no wallet verification or `Idempotency-Key`. When the state refuses the action, it answers the refusal create would return for the same state: a run already in flight for an action that settles by composition, a token that cannot run the action, a missing token role, or terms that do not fit the type. A cleared check does not guarantee the create, because the state can change before you send it, and create then returns its own refusal. The Console calls it while an operator fills the declaration and program-link sheets.

## Quote, then commit in one call [#quote-then-commit-in-one-call]

A quote shows what an action would do before you record it. A commit then records, previews and confirms it in one call, with one wallet verification instead of one per step.

`POST /api/v2/tokens/{assetId}/corporate-actions/quote` takes the same body as create and stores nothing. It needs no wallet verification and no `Idempotency-Key`, and it asks for the same token role as create. The answer lists the plan:

- `holderCount`, `totalAmount`, `remainder` and `denominationShortfall`.
- `treasuryUnitsExcluded`, the units the treasury held at the record date that a cash dividend or distribution leaves out, or null.
- `rightsBurn`, only on the first page of a rights close: the rights the close burns once it has minted the new shares.
- `priceAdjustment`, which is null except for a stock split of a share that has a reference price. It carries the `currency` and the price `before` and `after` the split. The split multiplies the price by the denominator and divides it by the numerator, rounded half away from zero at 8 fraction digits, the precision of the price feeds, so an 18:1 reverse split moves 6.00 AED to 108.00 AED and a 3:1 split of 10 AED plans 3.33333333 AED. Quote and preview need only the role the split needs, and refuse a feed that cannot be re-priced with `price-unadjustable` (HTTP 409, `CORPORATE_ACTION_PRICE_UNADJUSTABLE`, DALP-184653). Confirm needs the token `admin` role on top of the supply role, refuses with `preview-mismatch` when the share's price moved since the preview (abort the split and raise it again), and sets exactly this price once every chunk of holder units has landed. The record's `snapshot.priceStep` carries `state` (`pending`, `submitted`, `settled` or `failed`), `attempt`, `transactionRequestId` and, when the step failed, a `failure` that names why and a `failureCode` (`drifted`, `refused`, `queue-failed` or `stored-unreadable`). The action stays `executing` until the price settles. Confirming a `failed` step sends the price again once the share's price is back at the approved `before`, or already at the approved `after`. While the price is anywhere else, confirm refuses with `price-drifted` (HTTP 409, `CORPORATE_ACTION_PRICE_DRIFTED`, DALP-184654), and the message names the price to set. Once every chunk of holder units has landed, abort refuses with `run-completed`, because only the price update remains. If an abort raced the last chunk and that chunk landed anyway, the action stays `aborted` while the price update is sent, and a `failed` step on it is confirmed again the same way: the step moves on and the status stays `aborted`. On an `aborted` action, confirm does nothing but that retry: unless the step is `failed` and every holder update landed, it answers with the record unchanged. A split whose ratio leaves the price unchanged at 8 fraction digits is refused with `price-unadjustable`. The price history stays as it is. The venue keeps its own price-band anchors.
- `data`, a page of holder rows with `holder`, `balance`, `amount` and `state`. Page it with `page[offset]` and `page[limit]`, up to 200.
- `acknowledgements`, the consequences the commit has to acknowledge.
- `approval`, with `requirement` set to `required`, `not-needed` or `waived`. `waived` comes with the reason.
- `quoteFingerprint`, which equals the `planDigest` the stored preview of the same plan gets.
- `coordinated`, only for a coordinated distribution: every class dividend the commit will declare. It names the `waterfallFeature`, the `denominationAsset` of the pool, the `appliedDeterminationKind` (null for the ordinary split), the `poolAmount` it moves, and one entry per class with `classToken`, `role`, `rank`, `allocation` (the slice the waterfall split gives it), `amountPerShare` (what its class dividend pays), `included`, `holderCount` on the record date and a `notDeclared` reason when it pays nothing. `totalAmount` is the `poolAmount`, and each holder row carries the `classToken` that pays it, so one holder appears once per class.

`GET .../corporate-actions/{corporateActionId}/quote` reads a record that exists. An approved record answers its stored plan, with the `balance` the preview kept for each holder, or null for a plan stored before it did and for a cash dividend or distribution. A drafted or previewed record answers a fresh computation. A cash dividend or distribution can only be quoted this way, once its record date has passed. The terms of a bond coupon, a maturity redemption, a conversion, or a cash dividend or distribution have no quote before the record exists. A quote of them is refused with `CORPORATE_ACTION_QUOTE_NOT_APPLICABLE` (HTTP 409, DALP-14427). A coordinated distribution is quoted before it is recorded, once its record date has passed. Before that it keeps the preview's refusal, `CORPORATE_ACTION_WRONG_STATUS` (HTTP 409). Its fingerprint covers the split every class dividend will run and the pool it moves, not the per-holder amounts, which each class dividend recomputes from the record-date book when it is declared.

```bash
curl -X POST "https://your-instance.example.com/api/v2/tokens/0x8a791620dd6260079bf849dc5567adc3f2fdc318/corporate-actions/commit" \
  -H "X-Api-Key: $DALP_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "terms": { "type": "bonusIssue", "numerator": 1, "denominator": 10 },
    "quoteFingerprint": "3b8f1d2c4a5e6f708192a3b4c5d6e7f8091a2b3c4d5e6f708192a3b4c5d6e7f8",
    "acknowledgements": ["excluded-holders"]
  }'
```

Commit takes `terms`, the `quoteFingerprint` from the quote, the `acknowledgements`, the `walletVerification` and an `Idempotency-Key`. It checks the wallet verification once and runs each step as the verified caller. If the plan it computes no longer has the fingerprint you sent, it stops before anything moves on chain and answers `CORPORATE_ACTION_QUOTE_STALE` (HTTP 409, DALP-14426). The error carries the current `quoteFingerprint` in `data`. Read the quote again, review the new plan, and commit with that value.

If the holders move after the commit has saved its record, the platform aborts the record before it answers `CORPORATE_ACTION_QUOTE_STALE`, so the supply is free again. Send your next attempt with a new `Idempotency-Key`. The old key finds the aborted record and answers `CORPORATE_ACTION_WRONG_STATUS` with HTTP 409. A commit of any aborted record answers the same way, including a cash dividend or distribution that an operator cancelled.

What the commit does next depends on the quote's `approval`:

- With no approval needed, it confirms. It answers `202` while the record is `executing`, as a confirm does. Read the record at `Location` until it settles.
- With approval needed, it stops at `previewed`, opens the approval and notifies the checkers. A second operator approves it, as [Approve or reject a plan](#approve-or-reject-a-partial-redemption) describes. Then `POST .../corporate-actions/{corporateActionId}/commit` confirms the approved plan without previewing again, after the same fingerprint check. A commit sent again while the record still waits for approval checks the fingerprint too, and answers `quote-stale` when it differs from the stored plan.
- A cash dividend or distribution stops after it is recorded and answers `drafted` with `previewAvailableAt`, set to its record date. While its dividend declaration is still queued, the answer is `202` and `dividendId` is `null`. Read the record until `dividendId` is set before you quote it. Send no `quoteFingerprint` on that first commit, because the plan cannot be quoted before the record exists. When the record date has passed, `previewAvailableAt` is in the past and you can quote and commit the record now. If the snapshot is not final yet, the preview answers `snapshot-not-ready` and the record stays `drafted`.

## Cash dividends and distributions [#cash-dividends-and-distributions]

Create already declares the dividend on chain. Preview then stores the holder allocations and returns `dividendConfirmation`: `merkleRoot`, `totalEntitled`, and `totalRequired`. Send all three values together when confirming the reviewed allocation. `totalEntitled` is a holder count. `totalRequired` is an amount in denomination-asset base units.

Confirm rejects a missing or mismatched confirmation group. A completed corporate action means the dividend snapshot was committed. Holders still claim payment through the dividend-yield feature.

The dividend itself is paid and managed on the dividend-yield feature's routes, not on this collection. Each route sits under `/api/v2/tokens/{assetId}/features/dividend-yield/dividends/{dividendId}`:

- `POST .../claims` pays the calling holder's entitlement. It asks for no token role.
- `POST .../transitions` with `{"transition": "cancel"}` cancels a declared dividend. It asks for the token's governance role.
- `POST .../top-ups` with a positive `amount` adds that much of the denomination asset to the dividend's treasury. When the calling wallet is the treasury itself, it raises the treasury's allowance to the feature by `amount` instead. It asks for no token role.

The feature numbers its dividends from 0, and `{dividendId}` is that on-chain number. The Console counts from 1, so the dividend it shows as Dividend #1 has `dividendId` 0.

The `interest-yield` feature accrues interest instead of declaring dividends, and has its own routes under `/api/v2/tokens/{assetId}/features/interest-yield`: `POST .../claims` pays the calling holder, and `POST .../top-ups` with a positive `amount` funds the interest treasury. Neither asks for a token role.

## Coordinated distributions across share classes [#coordinated-distributions-across-share-classes]

A `coordinatedDistribution` pays every share class of a multi-class instrument from one pool, at one record date. Raise it on the class token that carries the `distribution-waterfall` feature. A token that is not a class of a multi-class instrument, or a class without that feature, is refused. The instrument's waterfall decides the split from each class's rank and contribution basis. Classes at the same rank share their part of the pool pro rata.

Create takes `poolAmount` in base units of the waterfall's denomination asset, `denominationAsset` (the address of that asset: preview refuses any other), and `exDate`, `recordDate` and `paymentDate` in that order. `claimDeadline`, when set, falls on or after the payment date. `determinationKind` is optional: it asks for the waterfall's priority order for that issuer event, and the waterfall applies it only when a valid determination claim of that kind is in force. Create stores the record as `drafted` and moves no money.

A priority row can owe a class its contribution basis less every distribution the class has already received, instead of its basis less the capital it has had back. This is called netting, and it is off by default. `POST /api/v2/tokens/{assetId}/features/distribution-waterfall/distribution-netting` turns it on or off for one class under one row. Send `determinationKind` as the row's hash from the waterfall's `priorityRows` in the feature list (the keccak-256 hash of the row's text label), `role` as the class role, and `nets`. The executing wallet needs governance on the class token. The change is refused with `DISTRIBUTION_WATERFALL_NETTING_LOCKED` (409) once a distribution was funded under that row, and with `DISTRIBUTION_WATERFALL_UNKNOWN_PRIORITY_ROW` or `DISTRIBUTION_WATERFALL_UNKNOWN_CLASS_ROLE` (400) for a row or role the waterfall does not have. The feature list reports each row's `nets`, one entry per class in class order, and `locked`. `POST /api/v2/tokens/{assetId}/features/distribution-waterfall/allocation-sync` folds up to `maxDistributions` recorded distributions into the running totals that netting reads. Only a waterfall that was upgraded after distributions were funded needs it, any account can send it, and it changes no split.

Preview is refused until the record date has passed on chain. It is also refused with `waterfall-cannot-receive` (DALP-14016) when the denomination asset refuses a transfer from the executing wallet into the waterfall, for example a paused asset or an identity-gated asset and a waterfall that has no registered identity. The distribution-waterfall factory registers an identity for each waterfall it deploys. For a waterfall deployed before that, the token's governance calls `ensurePoolReceiver` with the class token on that factory. Preview returns `coordinatedSplit`: the `ordinary` legs, and the `priority` legs when you named a `determinationKind`. Each leg names the class token, its role, its rank and its amount. Preview then declares one dividend per class the pool reaches, at a rate of that class's leg divided by its supply on the record date, rounded down, and waits for each class's record-date snapshot. Until every class is declared and its snapshot is computed, preview is refused with `snapshot-not-ready`. Send it again. When a class declaration is refused because the paying wallet cannot pay for gas, preview answers `TRANSACTION_QUEUE_FUNDING_REQUIRED` (HTTP 400, DALP-14062) instead. Fund the wallet that the transaction request in `data.transactionId` names, then send preview again. Once they are, the record is `previewed` and its `holders` list every holder of every class with the amount they can claim, each entry tagged with its `classToken`. Declaring moves no money. A second operator then approves the plan, as [Approve or reject a plan](#approve-or-reject-a-partial-redemption) describes. The approval covers the split, each class's dividend and rate, and every holder amount. If the split moved since an earlier preview, preview cancels the class dividends it declared for the old split before declaring new ones.

Confirm is refused until the record date has been reached on chain. It is also refused before any money moves when the claim deadline has passed, the waterfall or its split changed since the approved preview, a class can no longer serve the record date, a class dividend is no longer declared or its snapshot no longer matches the approved holder amounts, a class carries another declared dividend that was never recorded, a class's dividend-yield feature pays in another asset than the pool, the denomination asset refuses a transfer into the waterfall, or the confirming wallet lacks governance on any class. When the approval no longer covers the run, abort it and declare a new one. The executing wallet must hold the pool and approve the waterfall to spend it. `POST /api/v2/tokens/{assetId}/features/distribution-waterfall/treasury-allowance` sends that approval. Its `amount` is in base units of the denomination asset, like `poolAmount`, and sets the whole approval, so send at least the pool. Confirm then funds the waterfall once, bound to the approved split, and records each class's approved snapshot in rank order. The record is `completed` when every class it pays is recorded, which is when its holders can claim through that class's dividend-yield feature.

The record stays `executing` while the funding or a class record is still queued. Send confirm again to resume it. It records each class once its transaction lands. A funding transaction that fails, for example because it reverts, moves no money. Confirm returns that failure and puts the record back to `approved`, so the next confirm funds the pool again. When confirm finds that a queued funding failed, it funds the pool again in the same call. Abort cancels every class dividend the run declared and did not record, including on a record a reject or an approval expiry already ended: abort that record again to cancel its class dividends. The record's `appliedSplit.classDividendsOpen` is `true` while any class dividend of the run is still declared or being cancelled. Its `appliedSplit.fundingSent` is `true` once the run sent a funding transaction, so an aborted run with it set had a funding that failed and moved no money. To know when to send preview or confirm again, read the record: each `appliedSplit.legs[]` entry carries `requestId`, the transaction request its class is waiting on, and `appliedSplit.fundingRequestId` is the latest funding attempt's transaction request. Wait on each one through the transaction status route or its stream, then send the call again. A funding request that ended `FAILED` is answered by sending confirm again, which funds the pool in a new attempt. Abort is allowed after the pool is funded. Classes already open for claims stay open until their claim deadline, and the rest are cancelled. Abort is refused while a class is still being recorded (abort once it settles) and while a sent funding may still land.

### Reclaim and release a class's money [#reclaim-and-release-a-classs-money]

Read each class's money on the record. Every `appliedSplit.legs[]` entry reports `state` (it adds `releasing` and `released`), `dividend` (the dividend-yield feature address and the dividend id), and `recovery` (`state`, `remaining`, `funder`, and `claimDeadline`). The split also reports its `distributionId`.

- `POST /api/v2/tokens/{assetId}/features/dividend-yield/dividends/{dividendId}/reclaim` takes back the unclaimed rest of a class dividend after its claim deadline. Use the class token as `assetId` and send the feature address as the `featureAddress` query parameter. The operation is `v2/token/reclaimDividend`.
- `POST /api/v2/tokens/{assetId}/corporate-actions/{corporateActionId}/legs/{classToken}/release` returns what the class still holds in the waterfall to the wallet that funded the run. The operation is `v2/token/releaseCorporateActionLeg`. It is refused while holders can still claim, once released, and when nothing is left. A release that fails can be sent again.

Both need the governance role on the class token and a wallet step-up.

### Holders a class did not pay [#holders-a-class-did-not-pay]

Once a class's claims can no longer pay, because its dividend was reclaimed or paid or its money was released, the record keeps each holder the class owed and did not pay.

- `GET /api/v2/tokens/{assetId}/corporate-actions/{corporateActionId}/unpaid-entitlements` (`v2/token/listUnpaidEntitlements`) lists them one page at a time, ordered by class, then holder. Send `page[limit]` (1 to 200, default 50) and `page[offset]` to move through the list. `data` holds the page, `meta.total` counts every unpaid holder, and `links` gives the first, previous, next, and last page. Each entry carries `id`, `classToken`, `holder`, `amount` in base units of the pool asset, `reason` (`unclaimed`, or `lost-identity` for a holder left out of the snapshot), `recordedAt`, `payment`, which is `null` until the holder is marked paid, and `reopens`, the earlier payment marks governance cleared, oldest first. `pendingClasses` names closed classes whose claims are not indexed yet, whichever page you ask for. Read again later to see their holders. The caller needs the governance role or the auditor role.
- `POST /api/v2/tokens/{assetId}/corporate-actions/{corporateActionId}/unpaid-entitlements/{entryId}/paid` (`v2/token/markUnpaidEntitlementPaid`) records that you paid the holder outside the platform. Send `paymentReference`, for example the bank transfer reference. It needs the governance role and a wallet step-up. The entry's `payment` then carries `paidAt`, `paidBy`, and `reference`. A second mark of the same entry is refused, and an entry is never removed.
- `POST /api/v2/tokens/{assetId}/corporate-actions/{corporateActionId}/unpaid-entitlements/{entryId}/reopen` (`v2/token/reopenUnpaidEntitlementPayment`) clears a payment mark you made by mistake. Send `reason` (1 to 500 characters) and `paidAt`, the `payment.paidAt` you read. It needs the governance role and a wallet step-up. The entry becomes unpaid and can be marked again, and each `reopens` item keeps the cleared `paidAt`, `paidBy` and `reference` with `reopenedAt`, `reopenedBy` and `reason`. An entry that is not paid is refused as `CORPORATE_ACTION_ENTRY_NOT_PAID`. A `paidAt` that no longer matches the current mark is refused as `CORPORATE_ACTION_ENTRY_MARK_CHANGED`. Read the list again.

## Continuing a partial run [#continuing-a-partial-run]

Abort leaves applied holders unchanged. When a new composition continues an earlier run, set `followsUpOn` to the earlier corporate-action identifier. Preview excludes holders already applied by that linked sequence. Review the remaining allocations before confirming the new run.

## How a stock split applies [#how-a-stock-split-applies]

A stock split (`direction: "forward"`) or reverse split (`direction: "reverse"`) is not a single on-chain rebase of every balance. It applies the ratio through the same chunked mint or burn every other composition type uses. A reverse split can instead round each result to whole shares with `fractionPolicy`, lift a holder whose result is below one share up to one, and pay cash in lieu of the part below one whole share from a smart-account treasury. A forward split pays nothing for a fraction. [Stock split direction](https://docs.settlemint.com/docs/api-reference/guides/corporate-actions-catalog#stock-split-direction) lists the fields and how the cash is computed.

Do not pause the token before or during a stock split. Pause blocks mint and burn at the contract level, and a stock split applies through mint or burn: a paused token fails every chunk of the split, not only the ones already queued. Confirm the token is unpaused before you create or confirm a stock split, and leave it unpaused until status reads `completed` or `aborted`.

A split processes holders in chunks, so some balances can remain unchanged while the run advances. Inspect entries whose `state` is `remaining` to identify holders whose chunks have not completed.

## Contracts that hold the token for their owners [#contracts-that-hold-the-token-for-their-owners]

An escrow (a trading venue's or a custody gateway's), a token sale, an XvP settlement and an airdrop hold units for other people. For an action that changes every holder's units by a ratio, the platform sizes each contract's units from the owners' balances at the record date, mints or burns that sum, and writes the action's step to the contract so its per-owner records follow. The snapshot lists each contract under `custodialSteps` (`contract`, `kind`, `index`).

The contracts are frozen for the action from its record date until its step lands. A movement of the token that the freeze refuses (an escrow deposit or lock, a sale purchase or claim, a new XvP deposit or settle, an airdrop claim, a new gateway request or claim) reverts and names the token and the action. The freeze needs a record date that is still ahead when you create the action, and it covers the contracts that hold the token at that time.

- Create with no record date, or one that has passed, and confirm when a contract started holding the token after the action was created, are refused as `CORPORATE_ACTION_CUSTODIAN_FREEZE_REQUIRED` (409, `DALP-184677`, not retryable). Create the action again with a record date that is still ahead. If a contract began holding the token after the action was created, abort the action first.
- Confirm cancels the resting venue orders, mints or burns each contract's units, then writes each step. Writing the step lifts that contract's freeze in the same call. A run that stops between the units and the steps keeps the contracts frozen. Confirm again to finish it.
- Abort clears the freeze while no unit chunk and no step has been sent. After either, abort is refused as `CORPORATE_ACTION_RUN_COMPLETED`, and the way forward is to confirm again.
- A custody gateway request that the action rounds to zero shares ends as returned with the reason `corporate-action`. It holds no receipts, so nothing is paid or returned. The pending and claimable redeem views of a request already show it on the new basis before anything touches it.

## Next steps [#next-steps]

- [Corporate actions catalogue reference](https://docs.settlemint.com/docs/api-reference/guides/corporate-actions-catalog) for the status lifecycle, the in-flight rule, and the stored holder-state shape across all thirteen types.
- [Idempotency and async settlement](https://docs.settlemint.com/docs/api-reference/guides/idempotency-async-settlement) for the `Idempotency-Key` and `Prefer` contract every mutating route on this catalogue shares.
- [Corporate actions in the Console](https://docs.settlemint.com/docs/console/asset-management/manage/corporate-actions) for the same catalogue driven from screens.


# 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)


# 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.


# Embed a Privy wallet

Source: https://docs.settlemint.com/docs/api-reference/guides/embed-a-privy-wallet
Embed the Privy SDK in your investor front end, sign investors in with the token DALP issues, and send a gas-sponsored transfer from their wallet.

## Overview [#overview]

An investor can hold their own key in an embedded wallet from Privy, a third-party wallet provider. Your front end embeds the Privy SDK, signs the investor in to Privy with a token that DALP issues, and then calls the Platform API to link the wallet, create the identity, deploy the smart wallet and send transfers. DALP never holds the key: the investor's Privy wallet signs, and DALP prepares and submits what it signs.

The investor signs in to DALP, and Privy trusts the DALP token. Your front end needs no second login and no Privy account system of its own. Because Privy signs the investor in on that token, anyone who can sign in to DALP as the investor can also sign in to their Privy wallet, so protect the DALP sign-in as you would the wallet.

The embedded-wallet path applies to an investor who joins an organisation. [Onboard an investor through the API](https://docs.settlemint.com/docs/api-reference/guides/onboard-an-investor) covers managed custody, where the platform holds the key. [Let an investor choose custody](https://docs.settlemint.com/docs/api-reference/guides/choose-investor-custody) covers the choice between custody kinds and the browser-wallet path. [Custody Provider](https://docs.settlemint.com/docs/concepts/custody-and-signing/custody-provider) describes both kinds.

Gas is sponsored when the organisation's gas payer is the paymaster. The smart wallet then needs no native currency, so an investor with an empty wallet can still transfer. When the organisation pays gas another way, the smart wallet pays its own gas and preparing a transfer from an empty wallet is refused with DALP-14034, which names the smart wallet and the `shortfallWei` it is missing. On and off ramps stay a Privy feature in your front end. The flow on this page has no fiat step.

## The sequence at a glance [#the-sequence-at-a-glance]

[Figure] Seven steps from the offered provider to a sponsored transfer signed in Privy. Step 1 reads the offered providers and the Privy app id with GET /api/v2/custody/investor-provider. Step 2 signs the investor in to Privy with the token from GET /api/auth/token, which Privy checks against GET /api/auth/jwks. Step 3 creates the participant and proves the Privy key. Step 4 creates the identity. Step 5 deploys the smart wallet when the organisation uses account abstraction. Step 6 prepares the transfer with POST /api/v2/transaction-preparations. Step 7 signs the user operation typed data in Privy and finalises it, and the organisation's paymaster pays the gas. Labels: 1 Read the offered providers; GET /api/v2/custody/investor-provider returns the Privy app id; 2 Sign the investor in to Privy; GET /api/auth/token, checked by Privy against GET /api/auth/jwks; 3 Create the participant and prove the key; POST /api/v2/participants, then the control preparation and lifecycle calls; 4 Create the identity; GET /api/v2/system/identities/me, then POST /api/v2/identities when it is missing; 5 Deploy the smart wallet; POST /api/v2/users/me/custody-accounts/:custodyAccountId/smart-wallet-deployment; 6 Prepare the transfer; POST /api/v2/transaction-preparations returns the user operation to sign; 7 Sign in Privy and finalise; POST /api/v2/transaction-preparations/:preparationId/transitions (finalise), paid by the paymaster.

_Steps 1 and 2 happen before any wallet exists, and steps 3 to 5 repeat only until the investor is set up._

## Embed the Privy SDK [#embed-the-privy-sdk]

Embed `@privy-io/react-auth`. The DALP Investor portal pins version 3.51.3, so match that version unless you have tested another. Wrap your application in `PrivyProvider` and set these options:

- `appId` is the value DALP returns for the offered provider, and step 1 reads it. You do not choose it. A Privy configuration runs on the deployment's own Privy credentials or on the organisation's, so the Privy app behind `appId`, and its dashboard settings in [Set up Privy to trust DALP](#set-up-privy-to-trust-dalp), belong to the deployment operator or to the organisation.
- `clientId` is set when DALP returns one.
- `externalWallets.disableAllExternalWallets` is `true`, because the investor signs with the embedded wallet only.
- `embeddedWallets.ethereum.createOnLogin` is `"off"`. Create the wallet when the investor reaches that step, with the SDK's create wallet hook.
- `supportedChains` and `defaultChain` name the organisation's network, which `GET /api/v2/organizations/:organizationId/joinable-participants` returns as `chainId`.

## Set up Privy to trust DALP [#set-up-privy-to-trust-dalp]

The Privy dashboard needs custom authentication, which Privy calls JWT-based auth. The values are:

| Privy setting | Value |
| --- | --- |
| JWT-based auth | On |
| User id claim | `sub` |
| JWKS endpoint | `<platform URL>/api/auth/jwks` |
| Allowed origin | The origin that serves your investor front end |

`<platform URL>` is the public URL of your DALP deployment. Privy fetches the JWKS from that address, so the deployment must be reachable from the internet. The `sub` claim of the token is the investor's DALP user id.

## Step 1: read the offered providers [#step-1-read-the-offered-providers]

Call `GET /api/v2/custody/investor-provider`. The response answers `data`, the organisation's designated investor provider or `null`, and `options`, every configuration the organisation offers to investors on the request's network, the default first. Each entry carries its `id`, its `provider`, its `custody` label and its `clientConfiguration`. Render `options` as they arrive: the platform has already dropped what the organisation does not offer and what does not serve the network, so a front end derives no label, default or network filter of its own. An entry for a Privy configuration carries `clientConfiguration` with `kind` set to `privy`, the `tenant`, the `appId` and, when set, the `clientId`. Take the Privy app id from there.

If no option offers Privy, do not show the Privy option. Which providers are offered is a setting, covered in [Which provider is offered](#which-provider-is-offered).

## Step 2: sign the investor in to Privy [#step-2-sign-the-investor-in-to-privy]

The investor is signed in to DALP already. Call `GET /api/auth/token` with that session, and DALP answers `{ "token": "<jwt>" }`. Hand the token to Privy as the external JWT: with `@privy-io/react-auth`, pass a function that returns it to `useSubscribeToJwtAuthWithFlag` as `getExternalJwt`, together with `isAuthenticated` (true once the DALP session names a user) and `isLoading` (true while that session is still loading). Privy verifies the token against `GET /api/auth/jwks` and signs the investor in. Call the token route again each time Privy asks, because the token expires.

Create the embedded Ethereum wallet once Privy reports the investor as authenticated. The wallet address is the signing address you link in step 3.

## Step 3: create the participant and prove the key [#step-3-create-the-participant-and-prove-the-key]

These calls run in this order, with the investor's DALP session:

1. `GET /api/v2/organizations/:organizationId/joinable-participants` reads the organisation's network and whether it uses account abstraction (`aaEnabled`). It also lists participants the investor can reuse.
2. `POST /api/v2/participants` with `organizationId`, the `providerConfigurationId` from step 1 and `walletVerification` creates a pending participant. Skip it when you resume an existing one.
3. `GET /api/v2/users/me/custody-accounts` with `participantId` lists the participant's custody accounts. If one already links the Privy configuration on this network, reuse it and connect the same wallet.
4. `POST /api/v2/users/me/custody-account-control-preparations` with `providerConfigurationId`, `participantId` and the wallet address as `signingAddress` returns a `message`, a `binding` and an `account`.
5. The investor signs `message` with their Privy wallet as a personal message.
6. `POST /api/v2/users/me/custody-accounts/lifecycles` with `proof` set to `binding`, `account` and an `artifact` returns a `requestId`. The `artifact` is the JSON string `{"kind":"evm-self-custody-control","signature":"<signature>"}`.
7. `GET /api/v2/users/me/custody-account-requests/:requestId` with `participantId` reads the request. Follow it until its state is `succeeded`. The stream at the same path with `/stream` appended reports each change.

The account is ready when `GET /api/v2/users/me/custody-accounts` shows `accountLifecycle` and `contextLifecycle` both `active`. [Step 3b of Let an investor choose custody](https://docs.settlemint.com/docs/api-reference/guides/choose-investor-custody#step-3b-run-the-browser-wallet-branch) shows calls 4 to 7 with their requests and responses.

## Step 4: create the identity [#step-4-create-the-identity]

Call `GET /api/v2/system/identities/me` with the participant, custody account and network in the request context headers. It answers `200` with `status` set to `NOT_PROVISIONED` for a wallet with no identity, and `404` with `IDENTITY_SCOPE_NOT_FOUND` while the network's identity registry is not indexed yet. Treat both as no identity. In that case call `POST /api/v2/identities` with the wallet address and `walletVerification`. The first call is refused with a `409`, [DALP-12389](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference#domain-rule-errors), whose `data.signingPayload.typedData` holds the identity factory's typed data. The investor signs it with their Privy wallet through `eth_signTypedData_v4`. Repeat the call with `externalMessageAuthorization: { "signature": "<signature>" }`, then wait for the write to settle. [Idempotency and async settlement](https://docs.settlemint.com/docs/api-reference/guides/idempotency-async-settlement) covers the settlement signal. Registration and verification follow [Onboard an investor through the API](https://docs.settlemint.com/docs/api-reference/guides/onboard-an-investor) from step 3.

## Step 5: deploy the smart wallet [#step-5-deploy-the-smart-wallet]

Skip this step when `aaEnabled` is false. Otherwise call `POST /api/v2/users/me/custody-accounts/:custodyAccountId/smart-wallet-deployment` with no body fields. The first call is refused with a 409 whose `data.signingPayload.typedData` holds the typed data to sign. The investor signs that typed data with their Privy wallet. Repeat the call with `externalMessageAuthorization: { "signature": "<signature>" }`. The response names the smart wallet `address`. The wallet needs no native currency for this step.

## Step 6: send a sponsored transfer [#step-6-send-a-sponsored-transfer]

A transfer is three calls. First prepare it: `POST /api/v2/transaction-preparations` with the `custodyAccountId`, `executionMode` set to `prefer-aa`, a `summary` and the `operation` (`kind`, `contractAddress`, `callData` and an optional `value`). The response carries `preparedUserOperation` with a `userOperationHash` and the `previewData` of the operation. Where the organisation's gas payer is the paymaster, `previewData` names the `paymaster` and carries its `paymasterData`, so the smart wallet pays nothing. The paymaster ticket in `paymasterData` expires after a window the deployment operator sets, 300 seconds by default, so sign and finalise within that window or prepare again.

Then the investor signs. Build the EIP-712 typed data of the user operation from `previewData` for the EntryPoint in `previewData.entryPointAddress` (the viem `getUserOperationTypedData` helper builds it), check that its hash equals `userOperationHash`, and sign it with `eth_signTypedData_v4` in Privy. A plain message signature fails, because it adds a text prefix.

Last, finalise: `POST /api/v2/transaction-preparations/:preparationId/transitions` with the `finalize` action and this artifact in its body.

```json
{
  "action": "finalize",
  "artifact": {
    "_tag": "Eip4337UserOperationAuthorization",
    "kind": "eip-4337-user-operation",
    "userOperationHash": "0x...",
    "signature": "0x..."
  }
}
```

The response carries a `transactionRequestId`. Follow it on the transaction status stream, `GET /api/v2/transaction-requests/:transactionId/stream`, until it reaches a terminal state.

## Which provider is offered [#which-provider-is-offered]

The deployment decides which providers exist. The switch `custody.providers.<kind>.enabled` turns a provider on for the whole deployment. Each organisation then decides which enabled providers its investors see: a provider configuration is offered when its `offeredToInvestors` flag is set, and the configuration with the `investorProvider` flag is the default. Offering Privy alone is a configuration change and needs no code.

## Errors [#errors]

Steps 3 to 5 return the refusals in [The refusals each step returns](https://docs.settlemint.com/docs/api-reference/guides/choose-investor-custody#the-refusals-each-step-returns).

| Code | Status | When it appears | What to do |
| --- | --- | --- | --- |
| [DALP-14034](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference#domain-rule-errors) | 422 | The organisation does not sponsor gas and the smart wallet holds too little to pay for the prepared transfer | Send at least `shortfallWei` of native currency to the smart wallet, then prepare the transfer again |
| [DALP-12033](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference#client-request-errors) | 400 | A signing request carried no `walletVerification` block | Add `walletVerification` and repeat the request |
| [DALP-14033](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference#client-request-errors) | 409 | The request conflicts with how the preparation is bound, its idempotency key names another preparation, or the smart wallet already has an open owner-signed operation | Read the preparation and send the claim, attachment or artifact that matches it. Use a new idempotency key for a different operation, or finish or expire the open one |

[DALP error index](https://docs.settlemint.com/docs/api-reference/errors) lists every code. [Read and handle DALP errors](https://docs.settlemint.com/docs/api-reference/guides/errors) covers the envelope these codes arrive in.

## Next steps [#next-steps]

- [Onboard an investor through the API](https://docs.settlemint.com/docs/api-reference/guides/onboard-an-investor) registers the identity and verifies the investor.
- [Idempotency and async settlement](https://docs.settlemint.com/docs/api-reference/guides/idempotency-async-settlement) covers the headers and status URLs these writes use.
- [Custody Provider](https://docs.settlemint.com/docs/concepts/custody-and-signing/custody-provider) explains what each provider holds.


# Errors

Source: https://docs.settlemint.com/docs/api-reference/guides/errors
Read the DALP-#### id, category and retryable flag on every Platform API error, branch your integration on those fields, and never parse the message text.

## Overview [#overview]

DALP error responses include a stable identifier, a reason, a recovery step, and a retry flag. Use those fields to distinguish a request you must correct from a temporary failure. HTTP status alone does not identify the cause.

Versioned REST routes use this envelope: a stable `code`, an HTTP status, a headline `message`, and a `data` object carrying `id`, `why`, `fix`, `retryable`, and `category`. The same registry backs JSON-RPC error responses and Server-Sent Events streams, framed for each transport, so the fields you branch on are the same on every transport.

```json
{
  "code": "USER_EMAIL_ALREADY_EXISTS",
  "status": 409,
  "message": "A user with this email already exists.",
  "data": {
    "id": "DALP-0670",
    "why": "Each platform user must have a unique email address.",
    "fix": "Use a different email or open the existing user in User management.",
    "retryable": false,
    "category": "client",
    "requestId": "req_2c8f1a4e0b7d4e11"
  }
}
```

## Fields to branch on [#fields-to-branch-on]

| Field | Use it to... |
| --- | --- |
| `code` | Identify the error by its machine name, such as `USER_EMAIL_ALREADY_EXISTS`. It is stable like `data.id`, and new clients prefer `data.id`. |
| `data.id` | Identify the exact error, using its stable identifier. Look it up in the [DALP error index](https://docs.settlemint.com/docs/api-reference/errors). |
| `data.category` | Route the error to the right handling path: `client`, `auth`, `permission`, `domain`, `contract`, `dependency`, `operational`, `vendor-boundary`, or `unknown`. |
| `status` | Match your HTTP client's error handling. The value is always 400 through 599. |
| `data.retryable` | Decide whether a retry can succeed once you resolve the cause. `true` never means send the same request in a loop. It means a retry can succeed after the underlying condition clears, such as a dependency recovering. |
| `data.requestId` | Attach to a support ticket. The `X-Request-Id` response header carries the same value. Not every error body carries it. |

Never branch on `message` or `data.why`. Both are copy DALP can reword between releases. `code`, `data.id`, `data.category`, `data.retryable` and `status` are the stable contract.

## Decide what to do [#decide-what-to-do]

These fields lead to one of three decisions. Retry when `data.retryable` is `true` and the condition the error names has cleared. Fix the request when `data.retryable` is `false` and `data.fix` names a step you control. Escalate when neither applies, because no field marks escalation. [Error handling](https://docs.settlemint.com/docs/api-reference/errors/error-handling#decide-whether-to-retry) walks through the retry decision for each kind of failure.

`data.category` groups errors by class for coarse handling and support routing. It is not a retry signal by itself: two errors in the same category can differ on `data.retryable`. Decide retry or fix from `data.retryable` and `data.fix`, and use `data.category` to route logging, alerting, or a support ticket to the right team.

A `data.retryable` of `false` does not always mean never resend. A few errors set it to `false` while their `data.fix` copy still recommends trying the request once more by hand. The flag tells an automated retry loop whether to re-drive the request on its own. It does not settle whether a person should try again. Read `data.fix` before turning the flag into a blanket policy.

A `data.retryable` of `true` does not mean the SDK retries automatically or that the route is safe to replay. Apply a bounded retry policy only where the route documents replay safety. For an uncertain write, inspect the original instruction's state before creating another attempt.

## Which failures deserve a person [#which-failures-deserve-a-person]

The error response carries no severity, and the platform's own logs do. The registry marks an entry as an expected client error when a caller routinely and legitimately triggers it, such as a compliance-blocked transfer or a validation rejection, and the platform logs that failure at informational severity rather than error. An operator who alerts on those logs builds the alert on the severity field rather than on the presence of a log line, so a routine compliance rejection does not page anyone while the refusal is still counted and still visible on a dashboard.

Two identifiers matter. The error code names the kind of failure. It stays stable across releases and matches the string the registry, this reference and the logs use, so triage searches on it. The request identifier names one call, and a response carries it where the route can supply one. Include both, and the affected resource, in a support request.

## Licensed module refusals [#licensed-module-refusals]

A licensed module is a capability the deployment offers and each organisation chooses to use. A write to a module that the caller's organisation switched off is refused with `LicensedModuleDisabled`: HTTP status 403, `code` `platform.module.DISABLED`, `data.id` `DALP-20531`, category `domain`, and `data.retryable` `false`. `data.module` names the module, for example `tradingVenue`. Session and API-key callers get the same refusal, and the read routes of the module keep answering.

```json
{
  "code": "platform.module.DISABLED",
  "status": 403,
  "message": "This module is switched off for your organization",
  "data": {
    "id": "DALP-20531",
    "retryable": false,
    "module": "tradingVenue"
  }
}
```

The example shows the fields to branch on. The response also carries `why`, `fix`, `category` and `requestId`. Do not retry: the refusal holds until an organisation owner switches the module on in Organisation settings. The error does not mean the caller lacks a role or that the route is unavailable to the deployment.

A module that the deployment itself has switched off gives a different answer. Its routes return the ordinary `404` for a route that does not exist, with no `platform.module.DISABLED` code, so a caller cannot tell the module apart from a route that was never there.

The Canton wallet routes (`/api/v2/wallets` and everything under it) answer the same way while the deployment has `features.canton` switched off, which is the default and how release 3.2 ships. Canton is a deployment switch, not a licensed module, so no organisation can switch it off or on. The OpenAPI document and the SDK still list the routes, because they ship once for every deployment, and each operation's description says that it is available only with `features.canton` on. The CLI turns the `ROUTE_NOT_FOUND` answer to one of its Canton commands into `FEATURE_NOT_ENABLED`, "Canton is not enabled on this deployment."

A route that also serves EVM tokens keeps answering while Canton is off, so it refuses the Canton selection instead of answering `404`. `GET /api/v2/tokens` with `filter[family]=canton`, a `filter[network]` that names a Canton network, or the `X-Network-Id` header answers `400 COLLECTION_FILTER_VALUE_INVALID`, and `data.errors` says that Canton is not enabled. Filter by `evm` or leave the selection out.

## Request bodies that serve two families [#request-bodies-that-serve-two-families]

A write route that serves both EVM tokens and Canton instruments, such as `POST /api/v2/tokens/{assetId}/mints`, reads the body's `instrumentAdmin` to pick the family. A body without it is checked as an EVM body, and a body with it as a Canton body. A `400 REQUEST_INVALID` lists in `data.errors` only the keys of that family, so an EVM mint never names `instrumentAdmin` among its missing keys, and a Canton mint never names `recipients`.

## Where to look up a code [#where-to-look-up-a-code]

- [DALP error index](https://docs.settlemint.com/docs/api-reference/errors) lists every `DALP-####` id with its machine name, category, HTTP status, retryable flag, and a link to the page that explains it.
- [Platform API error reference](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference) documents REST and workflow errors by domain.
- [Smart contract error code reference](https://docs.settlemint.com/docs/api-reference/errors/error-code-reference) documents on-chain revert reasons for compliance, settlement, and system contracts.

These three pages are generated from the registry that produces the errors you receive.

## Contract errors carry extra fields [#contract-errors-carry-extra-fields]

An error raised by a reverted smart contract call adds `dalpCode`, the reverting function `selector`, and the Solidity `solidityError` name alongside the standard fields. Use these to correlate a DALP error with the on-chain revert your transaction explorer shows. When the platform recorded a transaction request for the reverted write, `transactionId` names it, and that request keeps the full failure detail.

A revert reaches the platform at gas estimation or broadcast, in a transaction receipt, as an account-abstraction execution failure that the bundler reports, or as a raw revert with no interface to decode its arguments. On each route the platform resolves the revert's four-byte selector against one contract error catalogue, so the same on-chain failure returns the same identifier and copy, never a bare Solidity error.

A catalogue entry's copy can carry placeholders that decoded Solidity arguments fill in, so a message can name the actual wallet or the actual module. When a placeholder cannot be resolved, because decoding failed or the argument is absent, the platform leaves it out instead of printing a raw token or raising, and the message falls back to its general form.

### Compliance reverts carry a reason [#compliance-reverts-carry-a-reason]

For a mint or a transfer blocked by compliance, `data.args.reason` can classify the refusal with one of five values, and each points at a different owner:

- `identity-not-registered`: the party's identity is not registered. This is an onboarding task.
- `identity-not-verified`: the identity is registered but is missing a required claim, which belongs to a trusted issuer.
- `module-blocked`: a compliance module rejected the operation. This is a policy question about the token's rules rather than about the investor.
- `stale-price`: the module needed a price feed that has gone stale. This is an infrastructure question for whoever operates the feed.
- `classification-unavailable`: the token's trusted issuer registry or topic scheme registry is not set, so the platform could not classify the refusal.

`data.args` also names the `party`, `sender` or `recipient`, and the `wallet`, and for a module refusal the module. Branch on `reason`. The message that accompanies it can name the blocking module and can change between releases.

Two caveats apply. Classification is best effort, so not every compliance failure carries `data.args.reason`. Key your control flow off the error code first and treat the extra detail as present when available. A missing `reason` has two causes that look identical on the wire: the decoding of the revert arguments failed, or the executing wallet lacks the role described next. Treat absence as normal rather than as a malformed response.

Disclosure depends on the system roles of the wallet that executes the request. On a transfer, the platform returns the classification only when that wallet holds the system manager, identity manager or claim issuer role. A mint also returns it to a wallet that holds the system-level supply management role. Any other caller receives the general refusal, with no `reason`, wallet or module detail, so the classification helps remediation without turning an error response into a way to probe another party's compliance state. A forced transfer, which needs the token's custodian role, returns the classification without that role check, and only as `identity-not-registered` or `classification-unavailable`.

## Present errors to a user [#present-errors-to-a-user]

Show `message` as the headline, `data.why` as the explanation, and `data.fix` as the next step. Do not build your own copy from `data.id` alone. The registry's `why` and `fix` are written for the person seeing the error, and DALP updates that copy without changing the id.

## Next steps [#next-steps]

- [Idempotency and async settlement](https://docs.settlemint.com/docs/api-reference/guides/idempotency-async-settlement) covers the `409 Conflict` responses an idempotent write can return.
- [Authentication and API keys](https://docs.settlemint.com/docs/api-reference/guides/authentication-api-keys) covers `DALP-14386` and `DALP-0036`, the authentication and scope errors.


# Feeds

Source: https://docs.settlemint.com/docs/api-reference/guides/feeds
Read the on-chain price-feed directory, latest values, rounds, and staleness windows, and submit a signed observation as a trusted issuer on V1 or V2.

## Overview [#overview]

A feed is an on-chain series of values, usually the price of an asset or an exchange rate, that DALP reads for valuation and settlement. It maps a `subject` address, the asset the value is about, and a `topic`, the kind of value, to one governed source of observations. An observation is a value with the time it was seen. The API reads the directory, feed configuration, values, and staleness policy, and authorised issuers can submit observations. [Price sources](#feed-prices-from-a-provider) publish prices into feeds from a provider, keyed by ISIN, the International Securities Identification Number. Read [Market data](https://docs.settlemint.com/docs/concepts/records-and-evidence/market-data) for the governance model and the [V1](https://docs.settlemint.com/docs/api-reference/v1) or [V2](https://docs.settlemint.com/docs/api-reference/v2) reference for complete schemas.

Use V2 for a new integration. V1 routes use `/api/v1/system/feeds/*` and have no staleness-window or price-source routes. V2 routes use `/api/v2/system/feeds/*`. Both accept a session cookie or `X-Api-Key`, including on submission routes.

Call `GET /api/v2/system/feeds/capabilities` before using a feed capability. The directory, issuer-signed factory, or adapter factory can be absent from an organisation. An unavailable capability returns an error, not an empty feed list.

## Two ways a feed gets registered [#two-ways-a-feed-gets-registered]

An issuer-signed feed is created through the platform's factory. The create request sets its decimals, subject, topic, and description. The platform fixes its retention to the latest round on-chain, requires every submitted value to be greater than zero, and allows no future drift from chain time in the feed contract. The create request does not expose those three settings. A rate or exchange-rate movement that can be zero or negative is unsupported by native feed creation. The indexed API can still serve past accepted observations. Read the feed's configuration with `GET /api/v2/system/feeds/{feedAddress}/configuration` before using it for valuation or settlement.

An external feed, such as a Chainlink-compatible aggregator already deployed on chain, is registered rather than created: `POST /api/v2/system/feeds/external-registrations` maps an existing contract into the directory at a subject and topic. Replacing the feed at that key with `PUT /api/v2/system/feeds/registrations` retires the previous address once the queued write settles. Removing it with `DELETE /api/v2/system/feeds/registrations` only deletes the directory mapping. The feed contract itself stays deployed and readable at its own address. Neither the old feed's history nor its own contract state changes.

A stable adapter gives consumers one address that survives a feed replacement underneath it. `POST /api/v2/system/feeds/adapters` deploys one for a subject and topic. Hold onto `adapterAddress` from the response, not the feed address behind it, especially from a smart contract or any long-lived integration.

An adapter on an issuer-signed feed changes its `kind` but not its `origin`. `kind` reads `aggregator-adapter` as soon as an adapter exists for the feed, so it no longer says who feeds it. `origin` says whether the platform's factory created the feed and, for any other feed, whether it has an adapter:

- `issuer-signed`: the platform's factory created the feed and a trusted issuer signs its values, with or without an adapter.
- `aggregator-adapter`: a feed that the factory did not create, such as a Chainlink-compatible aggregator, and that has an adapter.
- `external`: a feed that the factory did not create and that has no adapter. This includes a DALP feed registered in the directory without the factory.

Read `origin`, not `kind`, to tell whether the platform treats a feed as issuer-signed. The platform does the same: an issuer-signed feed that has an adapter can be mapped to a price source, the source publishes to it, and that feed's item on `GET /api/v2/system/feeds` names the source in `provenance`. `origin` is on `GET /api/v2/system/feeds`, `GET /api/v2/system/feeds/{feedAddress}`, and `GET /api/v2/system/feeds/{feedAddress}/configuration`, and the list filters on it with `filter[origin]`.

## Decide who may submit a value [#decide-who-may-submit-a-value]

A submission passes two checks before the platform queues it. The role check does not depend on the feed's topic.

The caller must hold the `feedsManager` role on the system, or the `governance` role on the feed's subject. The check runs against the wallet that executes the request, so a caller who holds neither is refused with `403` and `FEED_MANAGER_PERMISSION_REQUIRED`.

Registering an external feed with `POST /api/v2/system/feeds/external-registrations`, replacing a feed with `PUT /api/v2/system/feeds/registrations` and removing one with `DELETE /api/v2/system/feeds/registrations` need the `feedsManager` role on the system. The feeds directory contract accepts these writes only from that role, so a holder of the `governance` role on the subject is refused with the same `403` before any gas is spent. The Console hides Replace feed and Remove feed from that holder.

The platform then signs the update itself, for the organisation's own operations account, and that account carries the organisation's issuer identity. The identity must be a trusted issuer for the feed's topic in the feed's `trustedIssuersRegistry`, or the submission is refused with `403` and `FEED_ISSUER_NOT_TRUSTED`. Read the registry address from the feed's configuration response, and add the organisation's issuer identity to it for the topic before you submit.

Both checks run before the platform queues the write, so a caller refused by either one spends no gas. The trusted-issuer check reads the indexed registry, so while the index trails a recent change to the registry, the feed contract can still refuse the update on chain with the same `FEED_ISSUER_NOT_TRUSTED`. A custody policy that refuses to sign the update answers with `403` and `FEED_SUBMISSION_NOT_AUTHORIZED` instead: review the policy for the issuer key, not the registry.

## Read the latest value and staleness [#read-the-latest-value-and-staleness]

Each feed has one source for its latest round, and the platform picks it per feed, not per request. A feed that the indexer follows as a DALP scalar feed, such as an issuer-signed feed, is read from the index, whether or not an adapter sits in front of it. Every other feed, such as an externally registered aggregator, is read from the feed contract when you call. The feed kind and an adapter address do not decide the source, so read `latestRound` rather than inferring it. `latestRound` on `GET /api/v2/system/feeds` and `GET /api/v2/system/feeds/{feedAddress}` names the source for each feed: `indexed`, `chain`, or `none` when the index follows the feed but holds no round yet.

```bash
curl "https://your-instance.example.com/api/v2/system/feeds/0x71C7656EC7ab88b098defB751B7401B5f6d8976F/latest" \
  -H "X-Api-Key: sm_dalp_..."
```

An indexed feed answers:

```json
{
  "data": {
    "feedAddress": "0x71C7656EC7ab88b098defB751B7401B5f6d8976F",
    "roundId": "42",
    "answer": "108420000",
    "decimals": 8,
    "formattedAnswer": "1.0842",
    "startedAt": "2026-03-11T16:02:08.000Z",
    "updatedAt": "2026-03-11T16:02:08.000Z",
    "recordedAt": "2026-03-11T16:02:20.000Z",
    "answeredInRound": "42",
    "description": "EUR / USD",
    "version": "1",
    "asOfBlockNumber": "18445240"
  },
  "links": {
    "self": "/api/v2/system/feeds/0x71C7656EC7ab88b098defB751B7401B5f6d8976F/latest"
  }
}
```

| Read | Source | Freshness |
| --- | --- | --- |
| `GET /api/v2/system/feeds/{feedAddress}/latest`, feed with `latestRound` of `indexed` | The index. | `recordedAt` is the block time of the write the index read, and `asOfBlockNumber` is the block the index has processed. The value can trail the chain by the indexer's lag. |
| `GET /api/v2/system/feeds/{feedAddress}/latest`, feed with `latestRound` of `chain` | The feed contract, read when the request runs. | `recordedAt` and `asOfBlockNumber` are `null`. The value is what the contract reports when the request runs. |
| `GET /api/v2/system/feeds/{feedAddress}/latest`, feed with `latestRound` of `none` | The index. | Answers `404` [DALP-0131](https://docs.settlemint.com/docs/api-reference/errors) (`FEED_ROUND_NOT_FOUND`) until the index reads a round. |
| `GET /api/v1/system/feeds/{feedAddress}/latest` and `GET /api/v1/system/feeds/{feedAddress}/round/{roundId}` | The feed contract, for every feed. | Always live. V1 has no `recordedAt`. |
| `GET /api/v1/system/feeds/{feedAddress}/staleness` | The index for the latest answer, and the chain head for the current time. | The age is the chain head time minus the indexed update time. A feed with no indexed answer yet is refused. |
| `GET /api/v2/system/feeds` and `GET /api/v2/system/feeds/{feedAddress}` | The index. | Directory data only, so it trails the chain by the indexer's lag. Use `latestRound` to decide where to read the value. |

For an indexed feed, `updatedAt` is the time the value was observed and `recordedAt` is when the chain recorded it. Apply a freshness rule to `updatedAt` for either source, and check `asOfBlockNumber` when you need to know how far the index has read. For a valuation, compare the age of `updatedAt` with the effective staleness window.

Staleness is a governed policy, and only V2 exposes it. `GET /api/v2/system/feeds/staleness-windows/effective?subject=...&topicId=...` resolves the same window the platform's own price-age checks enforce elsewhere, such as before a mint. Two governed inputs feed that resolution, and exactly one effective value comes out:

[Figure] How DALP resolves the effective staleness window. The global default and per-feed override resolve to one effective window. An override can set a seconds value, mark the feed as never expiring, or inherit the global default. The effective source and age limit determine whether a value is stale. Labels: Staleness policy; Global default; System-wide age limit; Per-feed override; Seconds, never expires,; or inherit the global default; Age limit + source; Effective window; Stale if age exceeds the limit.

_Two governed inputs resolve to one effective window, tagged with its `source`. The platform's own staleness checks, including the one that gates a mint, use that resolved value_.

Read the effective window rather than inferring it, because the default depends on how the resolver was set up. A resolver that has no observed global-window event keeps the on-chain default of one day. The platform initialises a new resolver to never-expires only when the account that creates it holds the Feeds Manager role, and the effective window is never-expires once an event setting it has been observed. The response's `source` field tells you which input won: `"feed-override"` or `"global-default"`.

A bare `maxAgeSeconds: 0` on the setter routes cannot express both "clear this feed's override" and "reject every value as stale." That ambiguity is why the override is a tagged choice rather than a number. `PUT /api/v2/system/feeds/staleness-windows` takes `subject`, `topicId` and a `policy` of `{"mode": "seconds", "seconds": N}`, `{"mode": "never"}`, or `{"mode": "inherit"}` for one feed, with an optional `walletVerification`. `PUT /api/v2/system/feeds/staleness-windows/global` sets the system-wide default with `{"mode": "seconds", "seconds": N}` or `{"mode": "never"}`, and has no inherit option. `GET /api/v2/system/feeds/staleness-windows/global` reads that default back in the same shape, so a client can read it, change it, and write it back.

V1 has no equivalent to any of the three staleness-window routes. A V1-only integration can read a feed's raw age against a threshold it supplies on each call, but it cannot read or set the platform's governed window, and a staleness-window call on V1 returns `404`.

## Submit a signed value [#submit-a-signed-value]

The submission route resolves the issuer's nonce and signs for you, so an integration never reads or tracks nonces itself.

`POST /api/v2/system/feeds/{feedAddress}/submissions` takes the human value as a decimal string, such as `"1.08"`. The platform converts it to on-chain units using that feed's `decimals`. A value with more decimal places than the feed stores is refused with `400`, `FEED_PRICE_NOT_REPRESENTABLE` (`DALP-12245`), before anything is signed. Round the value to the feed's `decimals` and submit it again. It also takes `observedAt` as a Unix-seconds timestamp. The platform clamps `observedAt` into the window from the feed's latest observation to the current chain time, so a future timestamp is published at chain time. It refuses the submission with `400`, `FEEDS_SUBMIT_OBSERVED_AT_TOO_FAR_IN_FUTURE` (`DALP-0639`), only when the feed already holds an answer newer than chain time. The submit route resolves a signer rather than an executing wallet: the platform signs with the organisation's operations account, while the wallet that executes the request carries the role check. It answers like other queue-backed writes: `200` when the write lands within the wait that `Prefer` asks for, otherwise `202` with `Location` set to the transaction's status URL. This route also declares an `X-Transaction-Hash` header on both answers, and `Preference-Applied` echoes only the `Prefer` directives the platform honoured. See [Idempotency and async settlement](https://docs.settlemint.com/docs/api-reference/guides/idempotency-async-settlement) for the retry and polling discipline. This route follows it exactly, with no feed-specific exception.

## Feed prices from a provider [#feed-prices-from-a-provider]

A price source maps the ISINs a provider delivers to the price feeds of your tokens. The platform checks each delivered price and publishes the ones that pass through the organisation's operations signer. When the `prices` family of the organisation's approval policy is on, a price the checks flag waits for a second person, as [Review a held price](#review-a-held-price) describes. Use a price source when a custodian or market-data vendor, not a person, is the origin of a token's price. The V2 routes are under `/api/v2/price-sources`, which needs the Feeds Manager role, and `/api/v2/held-prices`, which accepts the Feeds Manager role or the governance role of the held price's token.

Price sources support five protocols: an SFTP CSV file, an SFTP ISO 20022 `reda.001` file, FIX market data over FIXT.1.1 or FIX.4.4, Bloomberg Data License, and LSEG DataScope Select. The Bloomberg and LSEG requests are built from each vendor's public documentation and have not run against the live service. The routes store a source's settings and credential, map instruments, and run the checks, review, and stale alert described here. The platform fetches each delivery itself, because no route accepts a pushed one. It polls an SFTP source for files, keeps one session open to a FIX source and reads its market data messages, and sends a Bloomberg or LSEG source's request at the clock times the source names. A vendor request names only the source's mapped ISINs and the source holds no instrument list of its own, so mapping an ISIN is what puts it on the request.

Set a source up in this order:

1. `POST /api/v2/price-sources` creates a draft source with its connection settings, publish threshold, hold tolerance, and timing. The platform rejects a host on a loopback, link-local, metadata, or private address unless the deployment's allow list covers its range, and no allow list lifts a cloud metadata address ([DALP-14704](https://docs.settlemint.com/docs/api-reference/errors)). An operator sets the allow list, the caps on each delivery, and the network paths described in [Price source prerequisites](https://docs.settlemint.com/docs/deployment/price-source-prerequisites).
2. `PUT /api/v2/price-sources/{sourceId}/credential` stores the credential. The credential is write-only: no response returns it, only `credentialSet` and a `credentialHint`. The hint holds the last characters of the secret so an operator can tell which credential is stored: up to three, fewer for a secret under nine characters, and an empty string for a secret of one or two characters. For a private key it holds the last characters of the hex SHA-256 digest of the key text, never of the key. Send the `expectedCredentialVersion` you read, or a concurrent change answers 409 ([DALP-14738](https://docs.settlemint.com/docs/api-reference/errors)). A retired source takes no new credential and answers 409 ([DALP-14741](https://docs.settlemint.com/docs/api-reference/errors)): create a new source instead.
3. For an SFTP source, `PUT /api/v2/price-sources/{sourceId}/host-key` accepts the server's host key fingerprint after you check it with the provider.
4. `POST /api/v2/price-sources/{sourceId}/instruments` maps up to 50 ISINs to tokens in one request. A token with no price feed gets an issuer-signed feed in the same operation. The response is a stored operation with a `links.self` link. Poll `GET /api/v2/price-sources/{sourceId}/instrument-operations/{operationId}` until its `status` is no longer `in_progress`. Each item reads `pending`, `mapped`, `completed`, or `failed`, and a failed item carries the `code` and `message` of its error. The operation is `failed` when it has finished and any item failed.
5. `POST /api/v2/price-sources/{sourceId}/transitions` with `activate` starts the source. The same route takes `pause` and `retire`.

After step 2 you can check the connection before you activate. `POST /api/v2/price-sources/{sourceId}/connection-tests` queues a test for any protocol, and `GET /api/v2/price-sources/{sourceId}/connection-tests/{testId}` returns its result. The test runs from the scheduler host and reads no price. It lists the remote path for SFTP, opens the connection without logging on and, for TLS, checks the provider's certificate for FIX, lists the account's catalogues for Bloomberg, and asks for a fresh token for LSEG. A test that does not finish within 30 seconds fails.

An active SFTP, Bloomberg, or LSEG source can fetch before its next scheduled run. `POST /api/v2/price-sources/{sourceId}/deliveries` queues the fetch and answers with an operation, and `GET /api/v2/price-sources/{sourceId}/delivery-operations/{operationId}` returns it until its `status` is `succeeded` or `failed`. The operation records the user who asked, and `links.self` points at it. A Feeds Manager can call both routes, with a signed-in session or an API key and no wallet verification. The `POST` declares no idempotency and reads no `Idempotency-Key`. A retry while the first request still waits answers 409 with [DALP-14743](https://docs.settlemint.com/docs/api-reference/errors), but a retry after the scheduler claimed the request queues another fetch, and for Bloomberg or LSEG that is another vendor request. Read the operation, or the source, before you repeat the request. The scheduler host that holds the source's lease picks the request up within 10 seconds. An SFTP source then polls its remote path at once. A Bloomberg or LSEG source starts one request and collects its result as it does on schedule. A successful operation reports how many deliveries the fetch produced. A failed one carries the reason.

- A FIX source streams its prices and answers 422 with [DALP-14742](https://docs.settlemint.com/docs/api-reference/errors).
- A source that is not active answers 409 with [DALP-14736](https://docs.settlemint.com/docs/api-reference/errors). Activate it first.
- A source with a fetch still waiting for the scheduler answers 409 with [DALP-14743](https://docs.settlemint.com/docs/api-reference/errors) and names the waiting operation. Read that operation instead of asking again.

Every delivery from the fetch names the user who asked. If one of its prices is held, that user cannot approve it, and another Feeds Manager or the token's governor can. A delivery from the schedule names no one.

To remove a credential, send `POST /api/v2/price-sources/{sourceId}/credential/transitions` with `{"transition": "remove", "expectedCredentialVersion": 3, "walletVerification": {"secretVerificationCode": "123456", "verificationType": "PINCODE"}}`. The platform deletes the secret, clears the hint, advances `credentialVersion` and answers the source. An active source answers 409 ([DALP-14740](https://docs.settlemint.com/docs/api-reference/errors)), so pause it first. A `credentialVersion` that moved since you read it answers 409 with DALP-14738 and removes nothing. A source that already holds no credential answers 200 whatever version you send. Removal also clears the credential of a retired source, whose secret retirement already deleted. Activation answers 409 ([DALP-14737](https://docs.settlemint.com/docs/api-reference/errors)) for a source without a credential, including one whose credential a concurrent removal took.

Activation, editing a source with `PATCH`, setting or removing the credential, the host key, and instrument mapping each need a signed-in session and a wallet verification. An API key answers 403 ([DALP-14734](https://docs.settlemint.com/docs/api-reference/errors)). Pause, retire, create, and the reads work with an API key. Because these writes carry a wallet verification or a secret, they declare no idempotency, so read the source again before you repeat one. When the organisation lists the `platform-settings` protection group, creating or editing a source, a source transition, setting or removing the credential, the host key, and instrument mapping answer 202 and wait as a pending approval until a second person decides them, as [Actions](https://docs.settlemint.com/docs/console/essentials/actions) describes.

The platform rejects a heartbeat that cannot fit the staleness bound. The heartbeat plus the source's expected delivery interval plus its expected lag must be shorter than the bound, which is the feed's effective staleness window when it is finite and otherwise the source's `staleAfterSeconds`. A request that breaks the rule answers 422 with [DALP-14703](https://docs.settlemint.com/docs/api-reference/errors).

### What happens to a delivered price [#what-happens-to-a-delivered-price]

Each price becomes an observation with its ISIN, price, currency, price type, and observed time. The platform applies these gates in order and records the outcome on the observation:

| Outcome | Meaning |
| --- | --- |
| `duplicate` | The same source, instrument, price type, observed time, and value arrived before. |
| `invalid`, `unmapped`, `currency_mismatch` | The price is not positive or cannot be written at the feed's decimals, the ISIN has no live mapping, or the currency differs from the feed's quote currency. |
| `out_of_order`, `future_dated` | The observed time is earlier than the feed's latest, or more than 60 seconds ahead of the chain head timestamp. The platform never moves an observed time to make it fit. |
| `correction_held` | The same observed time and price type arrived with a different value. With the `prices` approval family on, the price is held. With it off, the price publishes and the observation never shows this outcome. |
| `held` | The price differs from the last published price by more than the source's hold tolerance. With the `prices` approval family on, the price is held. With it off, the price publishes and the observation never shows this outcome. |
| `skipped_policy` | The price did not move by the publish threshold, and no heartbeat interval has elapsed. |
| `published`, `superseded`, `publish_failed` | The price reached the feed, a newer observation replaced it in the queue for that feed, or the publish did not complete. |

The platform judges time on the chain head timestamp, not the server clock. Read an observation with `GET /api/v2/price-sources/{sourceId}/observations`, filtered by `filter[status]` and `filter[isin]`. The list is newest first, so with `filter[isin]` its first row is the latest observation of that ISIN. Read the source's files and messages with `GET /api/v2/price-sources/{sourceId}/deliveries`. Each delivery carries `outcomes`, the counts of how its observations settled: `accepted`, `rejected`, `dropped`, `held` and `published`. `accepted` overlaps `held` and `published`, and an unsettled observation is in no group.

`GET /api/v2/price-sources` and `GET /api/v2/price-sources/{sourceId}` take `include=metrics`, which adds a `metrics` block to each source: the live `instruments`, the observations `publishedToday` since 00:00:00 UTC of the current UTC day, the open `held` prices, and `lastDeliveryAt`, which is null before the first delivery. `include=latestDelivery` adds the most recent delivery, and the two includes combine in one request. `GET /api/v2/price-sources/{sourceId}/unmatched-isins` lists the ISINs a source delivered that no mapping covers, and takes `page[limit]` and `page[cursor]` to page through them.

### Review a held price [#review-a-held-price]

The platform holds a flagged price only when the `prices` family of the organisation's approval policy (`PUT /api/v2/operations/approval-policy`) is on at that moment. A price already held keeps waiting for a decision if the family is turned off later. Every family starts off. With it off, a price the checks flag publishes without review, the platform records a waived approval for that observation, and it creates no held price.

With the family on, a held price waits for a decision by a Feeds Manager or by the governor of that token. `GET /api/v2/held-prices` lists only the held prices the caller may decide, and takes `filter[status]` and `filter[sourceId]`. With both, `meta.total` is the open-hold count of that source. Each held price carries `source`, which holds the name of the source that delivered it and the hold tolerance in force at the time of the read, the one a decision checks against. A later edit of the source changes it. A user who created the source, edited its settings or mappings, accepted its host key, or queued the delivery that produced the hold cannot decide it. The platform checks that group again at every decision, so a user who edits the source after the hold joins it.

Read the evidence before you decide. `GET /api/v2/held-prices/{heldPriceId}/evidence` returns the full delivery to a Feeds Manager and only the record that produced the observation to a governor.

`POST /api/v2/held-prices/{heldPriceId}/decisions` approves or rejects. The request names `reviewedObservationId`, the `evidenceDigest` from the held price, and a wallet verification, and it needs a signed-in session. The platform checks the caller's authority again at decision time.

| Answer | Cause |
| --- | --- |
| 409 [DALP-14722](https://docs.settlemint.com/docs/api-reference/errors) | The latest candidate moved beyond the hold tolerance after you reviewed it. Read it again. |
| 409 [DALP-14721](https://docs.settlemint.com/docs/api-reference/errors) | A newer price was published for the feed. |
| 409 [DALP-14723](https://docs.settlemint.com/docs/api-reference/errors) | The candidate is past the staleness bound. |
| 409 [DALP-14728](https://docs.settlemint.com/docs/api-reference/errors) | The source is paused. A rejection is still allowed. |
| 409 [DALP-14745](https://docs.settlemint.com/docs/api-reference/errors) | The source is stopped. [Restart it](#restart-a-stopped-source), then approve again. A rejection is still allowed. |
| 403 [DALP-14726](https://docs.settlemint.com/docs/api-reference/errors) | You are in the group that cannot decide this held price. |

Retiring the source cancels each of its held prices that still waits for a decision and withdraws its approval, so the held price reads `cancelled`. A retired source holds no new price.

An approved price goes to the feed through the feed's publish lane. Manual submissions, batch submissions, source publications, and token price writes to one feed take turns on that lane, one write at a time, because a feed accepts an issuer's updates only with strictly sequential nonces. If that publish fails, `POST /api/v2/held-prices/{heldPriceId}/transitions` with `retry_publish` and a wallet verification tries again.

### Restart a stopped source [#restart-a-stopped-source]

A source stops publishing after a credential or configuration failure. `GET /api/v2/price-sources/{sourceId}` returns the source's `failureClass`, which reads `credential` or `config` while the source is stopped. Its observations settle as `publisher_not_authorized` with the reason `source_stopped`. A transient failure retries on its own and does not stop the source.

Fix the cause first. A `config` failure means the organisation's identity is not deployed or is not an identity contract, or the organisation has no operations signer. A `credential` failure means the operations signer holds no claim key, the key an identity contract accepts for signing claims, or the organisation is not a trusted issuer for the price topic, as [Decide who may submit a value](#decide-who-may-submit-a-value) describes. No price-source route changes the identity, the signer, or the trust.

The platform also stops a source when its fetch from the provider is refused three times in a row for a credential or configuration cause. A credential failure is a refused login or logon, a vendor answer of 401 or 403 other than a Bloomberg 403 that reports clock skew, a stored credential that is missing or of the wrong kind, or a Bloomberg credential past its expiry date. A configuration failure is a refused endpoint, a source setting the provider cannot serve, an SFTP host key problem, a FIX certificate or sequence-number problem, or a Bloomberg refusal of the scheduler's egress address. An unreachable provider, a timeout, and a vendor answer of 408, 429, or 5xx are transient, so the platform retries them. Fix a provider cause with the provider, in the source's settings, or by replacing the credential.

Then clear the stop. Send `pause` and then `activate` to `POST /api/v2/price-sources/{sourceId}/transitions`. Activation clears the failure class and rechecks the endpoint and heartbeat rules against the current settings. For a credential failure, `PUT /api/v2/price-sources/{sourceId}/credential` with a new credential also clears the stop, and a `config` failure stays until you activate. The new credential does not repair the signer or the trust, so the next publication stops the source again while those causes stand. Pause accepts an API key. Activation and the credential change need a signed-in session and a wallet verification.

Clearing a stop does not prove the cause is gone. The next publication or provider fetch checks again and stops the source again if the cause remains. A paused source publishes nothing, so a feed it maps can go stale until you activate it.

### Stale feeds and provenance [#stale-feeds-and-provenance]

A mapped feed that is older than its staleness bound at the chain head raises one operations case of kind `stale-feed` for each stale episode. The case names the source and the likely cause, such as a paused source or a held price, and resolves when a fresh price lands, the feed is unmapped, or the source is retired. Platform operators also get the metric `dalp_market_data_stale_price_feeds` and an alert rule on it. While the indexer trails the chain head by more than the configured bound, the platform makes no stale judgement and reports the lag.

Each item of `GET /api/v2/system/feeds` includes `provenance`. It names the source with its `protocol`, and its `vendor` for a Bloomberg or LSEG source, which is null for an SFTP or FIX source. It also gives the price field and type, the `observationId` that produced the latest published price, and that price's observed, recorded and published times. `signedBy` is the operations signer that signed the price, read from the on-chain event, so it stays null until the indexer has seen the transaction. `approvedBy` is the approver when a held price carried the price. A feed maintained by hand returns `null`.

## Feed errors and retries [#feed-errors-and-retries]

Most feed errors are caller mistakes: a bad address, a topic name and topic id that disagree, or a malformed request body. Check the error's `retryable` flag and the current instruction state before deciding whether another write is needed. Apart from a feed create, which returns its first result for a repeated idempotency key, the feed routes do not document request-level replay safety. Retaining the original key alone does not make an API retry safe:

- The directory has no mapping yet for a subject and topic you expect to be registered. This happens when a registration transaction has confirmed but Ledger Data has not caught up. Confirm the registration, then retry once the index catches up.
- The feed provider, or the organisation's price-feed signer, does not answer. Once the dependency recovers, inspect the original operation before deciding whether to submit again.
- A queued write returns a transaction reference the platform cannot confirm. Check the original request status before submitting again.

Five failures are never worth retrying as sent: a topic name and topic id that resolve to different topics, a submission to a feed that already holds an answer newer than chain time (`400`, `FEEDS_SUBMIT_OBSERVED_AT_TOO_FAR_IN_FUTURE`, `DALP-0639`), a value with more decimal places than the feed stores (`400`, `FEED_PRICE_NOT_REPRESENTABLE`, `DALP-12245`), a submitted value of zero or below (`400`, `FEED_VALUE_NOT_POSITIVE`, `DALP-14446`), and an issuer-signed create for a subject and topic that already has a feed (`409`, `FEED_ALREADY_EXISTS`, `DALP-14445`). Each needs a corrected request, not a repeated one. The platform refuses the last three before it queues a transaction, so they cost no gas. A create repeated with its original idempotency key returns its first result, not the `409`. A write that an operator cancels in the transaction queue before it settles answers `409`, `market-data.feeds.WRITE_CANCELLED` ([DALP-20525](https://docs.settlemint.com/docs/api-reference/errors)). It is not retryable as sent: nothing was published and the platform starts no new attempt, so send the write again with a new idempotency key if it is still wanted. A strict submission from a price source ends the same way and does not retry the cancelled write.

A write the queue has accepted and has not settled is checked every five seconds for its first minute, then at growing intervals: 90 seconds, doubling to a 15-minute cap. Its answer can therefore arrive up to 15 minutes after the write settles on a stalled sender.

## Next steps [#next-steps]

- [V1 API reference](https://docs.settlemint.com/docs/api-reference/v1) and [V2 API reference](https://docs.settlemint.com/docs/api-reference/v2) for every feed route's full parameters, filters, and response schema.
- [Idempotency and async settlement](https://docs.settlemint.com/docs/api-reference/guides/idempotency-async-settlement) for the sync-versus-queued response shape every feed mutation and submission uses.
- [Errors](https://docs.settlemint.com/docs/api-reference/guides/errors) for the `retryable` flag and category on every feed error code.
- [Authentication and API keys](https://docs.settlemint.com/docs/api-reference/guides/authentication-api-keys) for the session-or-API-key credential every feed route accepts.


# Files

Source: https://docs.settlemint.com/docs/api-reference/guides/files
Read public branding assets with no credential, KYC and asset documents through their own routes, and any private file as a platform administrator.

## Overview [#overview]

A backend integration reads and writes DALP files through domain routes that accept an API key: the [asset document routes](#asset-documents) under `/api/v2/tokens/{assetId}/documents`, and the KYC document upload and download routes. The `/dalp/*` routes serve public branding assets to anyone, and `/dalp/private/*` serves stored private files to a platform administrator's signed-in Console session only and refuses an API key.

## Choose public or private [#choose-public-or-private]

Public assets need no credential. DALP allows public responses to be cached for one year. Private responses require a session and use headers that forbid caching. Keep KYC evidence and other sensitive documents private.

Deleting or moving a public asset cannot recall copies that clients already downloaded. If a sensitive file was exposed, treat those copies as outside the platform's control.

## Tenancy in object storage [#tenancy-in-object-storage]

Object storage is one bucket per deployment. Writes made through an organisation's storage scope carry the key prefix `org_{organizationId}/`, and an organisation's public branding assets sit under it too: a logo is stored at `org_{organizationId}/logos/...` and served from `/dalp/org_{organizationId}/logos/...`. KYC documents, stored under `kyc/{participantId}/...`, and the platform-reserved `platform/...` namespace sit outside that prefix. For a file outside the prefix, the route that serves it decides who may read it.

One interface sits in front of the provider implementations a deployment can select: S3, GCP Cloud Storage, Azure, any S3-compatible backend, and a filesystem provider for a self-hosted or air-gapped deployment. A caller sees the same upload-and-download URL contract on all of them, so an integration written against one deployment's storage backend does not need to change for another's.

## Public assets [#public-assets]

`GET /dalp/*` and `HEAD /dalp/*` serve public assets with no authentication. The object key is everything after `/dalp/`, and DALP only serves keys under a small set of prefixes, after an optional `org_{organizationId}/` organisation prefix: `logos/`, `auth/`, `backgrounds/`, `favicons/`, `icons/`. The API cannot add a new public prefix. A key outside the allowed prefixes, or one containing a `.` or `..` path segment, returns `404 Not Found` instead of a listing or an error that reveals why the request failed.

```bash
curl "https://your-instance.example.com/dalp/org_<organizationId>/logos/light/<id>-icon.svg"
```

DALP sets `Cache-Control: public, max-age=31536000, immutable` on a public asset response: a one-year cache lifetime that tells every intermediary the bytes at this URL never change. Cache it on your side too. The cost is that a file stored under a public key by mistake stays in caches for a year, because the header tells them not to re-check it. A response also carries `ETag` and `Last-Modified` when the stored object has them.

## Private files [#private-files]

`GET /dalp/private/*` and `HEAD /dalp/private/*` serve a stored private file to a platform administrator only. The object key is everything after `/dalp/private/`, and it needs at least two segments, such as `kyc/{participantId}/...`. A signed-in caller without the platform `admin` role receives `403 Forbidden` for every key, whatever resource type or id the key names. Every other caller reads a file through the route of the resource it belongs to:

| File | Route |
| --- | --- |
| A KYC document | The [KYC document download route](#read-a-kyc-document-through-its-domain-route). |
| An investor's statement | `GET /api/v2/reporting/statements/{statementId}/download`, which checks that the statement belongs to one of the caller's wallets. |
| An asset document | The [asset document routes](#asset-documents), which check the caller's organisation and the document's visibility. |

`admin` is a single role on the caller's session, not a per-organisation membership: a user is `admin` or `member` platform-wide, separate from whatever role they hold inside any one organisation. A platform administrator reads every valid private key, whatever its resource type and whatever id it names. Grant the `admin` role deliberately, because besides the administrative controls it gives its holder read access to every stored KYC document and every organisation's private files on the deployment.

A private file request does not accept an API key. A platform administrator authenticates with a signed-in Console session (cookie) instead. A backend service has no session cookie to send, so it reads each file through the route of its resource.

```bash
curl "https://your-instance.example.com/dalp/private/kyc/user_123/passport.pdf" \
  -H "Cookie: <your session cookie>"
```

This request returns the stored object only when the session belongs to a platform administrator. Any other signed-in caller receives `403 Forbidden`, whether or not an object exists at that key, and reads the document through the [KYC document download route](#read-a-kyc-document-through-its-domain-route).

DALP sets `Cache-Control: no-cache, no-store, must-revalidate`, plus `Pragma: no-cache` and `Expires: 0`, on every private file response. Do not cache a private file in a shared cache or CDN.

### Read a KYC document through its domain route [#read-a-kyc-document-through-its-domain-route]

Do not build a `/dalp/private/kyc/...` URL by hand from a backend integration. KYC documents have their own route that accepts an API key: the [KYC document download endpoint](https://docs.settlemint.com/docs/api-reference/v2). It is a POST because each call issues a new time-limited link rather than reading a fixed one. Call it with `X-Api-Key`, and it returns a scoped link instead of the file itself:

```json
{
  "data": {
    "downloadUrl": "/api/v2/kyc-profile-versions/.../documents/.../download",
    "fileName": "proof-of-address.pdf",
    "mimeType": "application/pdf",
    "expiresAt": "2027-01-05T15:05:00.000Z"
  },
  "links": { "self": "/api/v2/kyc-profile-versions/.../documents/.../downloads" }
}
```

The fields you want are under `data`, as on every other v2 single-resource response.

`downloadUrl` is always a relative path starting `/api/v2/`. The path stays gated by a session or API key after `expiresAt`, so send your credential each time you fetch it. `expiresAt` is always one hour after the call that issued the link, and it bounds the link only, not your credential. No KYC document is served through a link that anyone holding it can use.

A document that the v1 KYC upload stored before 3.2 as unencrypted is encrypted in place by a background job on the runner, which also deletes the unencrypted object. Until the job reaches it, the same `/api/v2/` path serves that document straight from storage, still behind your credential.

Request a fresh link if one stops working rather than assuming it is permanently dead.

For other files, use the download or export operation documented for the owning resource. Do not infer a supported integration route from an object-key prefix alone.

### API keys are refused on private file routes [#api-keys-are-refused-on-private-file-routes]

If you send only an `X-Api-Key` header directly on `/dalp/private/*`, with no session cookie, you get `401 Unauthorized`, the same response as sending no credential at all. The route does not evaluate API keys, so its response is the same for "your key is invalid" and "you sent no key". If your integration authenticates every other call with an API key, expect this one route to need a different credential path.

## Upload with a presigned URL [#upload-with-a-presigned-url]

An asset or token document upload is a two-step, presigned flow. Request an upload URL first. The response carries a `PUT` method, an `objectKey`, headers to send with the upload, and an `expiresAt` fifteen minutes out. Send the file bytes directly to that URL, then confirm with the returned `objectKey` so DALP records the file against its owning record. An Azure-backed deployment needs one provider-specific header on the direct upload, `x-ms-blob-type: BlockBlob`. Other providers need none. Request a fresh upload URL if `expiresAt` passes or storage rejects the headers you sent.

A KYC document upload does not use a presigned URL. Send it to `POST /api/v2/kyc-profile-versions/{versionId}/documents` with `documentType`, `fileName`, `fileSize`, `mimeType` and the file as base64 in `fileData`, so the platform can validate and encrypt the document before object storage receives it.

The v1 KYC API still offers a presigned upload. Its link points at an object key that ends in `/upload` under the version, and the client sends the file there unencrypted. The confirm call must name that upload key, and any other key is refused. The platform requires a draft version, reads the uploaded object and refuses it when it is over 25 MiB, when its size differs from the declared size, or when its bytes are not the declared type. It then encrypts the file and stores the encrypted copy the same way as a v2 upload, so the document downloads through a relative `/api/v2/` path. The platform deletes the uploaded object at the end of that confirm, whether the confirm stored the document, refused it or failed. After a refused or failed confirm, request a new upload link and send the file again. If you never confirm, a job on the runner deletes the uploaded object 30 minutes after the link was issued, which is the 15 minutes the link lasts plus 15 minutes of margin. The file sits unencrypted in object storage until the confirm or that deletion, so upload KYC documents through the v2 route.

A v2 KYC upload repeated with the same `Idempotency-Key` header replays the first one. The platform derives the document's id from the organisation, the version, the calling user and the key. A retry with the same key, from the same user, on the same version answers with the document the first request stored and stores nothing again, including when two attempts arrive at the same time. A retry with the same key and a different file, whether its bytes, document type, filename, size or media type differ, answers `400`, and `data.errors` names `Idempotency-Key`. Send a new key for each new file. Without the header, each request stores a new document.

This replay differs from the transaction queue's rules in [Idempotency and async settlement](https://docs.settlemint.com/docs/api-reference/guides/idempotency-async-settlement). It has no 24-hour window: it holds as long as the document exists. After the document is deleted, the same key stores the file again. The replay answers with the stored document's details, not a stored copy of the first response.

## Asset documents [#asset-documents]

An asset's documents, such as its prospectus, term sheet and holder notices, use the [presigned flow](#upload-with-a-presigned-url). The file goes between the client and object storage, and the Platform API hands out the links and records the document.

| Step | Route | Who can call it |
| --- | --- | --- |
| List the documents | `GET /api/v2/tokens/{assetId}/documents` | A caller in the issuing organisation. The list holds only what they may read. |
| Request an upload link | `POST /api/v2/tokens/{assetId}/document-uploads` | A wallet with the governance role on the asset. |
| Confirm the upload | `POST /api/v2/tokens/{assetId}/documents` | A wallet with the governance role on the asset. |
| Request a download link | `POST /api/v2/tokens/{assetId}/documents/{documentId}/downloads` | A caller in the issuing organisation whose level includes the document's visibility. |
| Delete a version | `DELETE /api/v2/tokens/{assetId}/documents/{documentId}` | A wallet with the governance role on the asset. |

The upload link response sets `expiresAt` 15 minutes out, and the download link response one hour out. A file is at most 52,428,800 bytes, which is 50 MiB, and is a PDF, JPEG, PNG, WebP, DOCX, XLSX or CSV file. A `brand_logo` document is a PNG, JPEG or WebP image of at most 5,242,880 bytes, which is 5 MiB. An upload link request for any other file type or size is refused with `400` `REQUEST_INVALID` (`DALP-14261`), and `data.errors` names the rule. The platform stores a brand logo as `public` whatever visibility the request names. The confirm call also refuses and deletes a `brand_logo` whose stored size differs from the declared size, whose stored bytes are not the declared image type, or that is over 2048 pixels on either side. The document type must fit the asset type.

The confirm call names the `objectKey`, the filename, size and type, the document type, the `visibility`, which is `public`, `holders` or `restricted`, and an optional title and description. To publish a new version of a document, send the document's `groupId` as `replaceGroupId` and the same `documentType`. A confirm that names another `documentType` answers `404` `DALP-0322`, the same answer as an unknown group. The platform reads the stored file back, refuses it when its size differs from the size the request declared, computes the SHA-256 fingerprint from the stored bytes and records the document. A confirmed `holders` document emits the `token.document.published` webhook event.

Only callers in the issuing organisation, or in the organisation whose own system registers the asset, reach its documents. Within that scope, visibility decides who reads a document. Every caller reads `public` documents. A caller whose wallet holds the asset, has units allocated or money contributed in one of its primary offerings that were not withdrawn or refunded, or holds any role on the asset also reads `holders` documents. A caller with the governance or admin role on the asset also reads `restricted` documents. A download request beyond the caller's level answers `404` with `DALP-9486`, the same answer as a missing document, so the response does not reveal that the document exists. A superseded or deleted version answers the same way.

| Status | Error id | Code | Meaning |
| --- | --- | --- | --- |
| `400` | `DALP-0324` | `TOKEN_DOCUMENTS_DOCUMENT_TYPE_NOT_VALID_ASSET` | The document type does not fit the asset type. A caller error: pick a type the asset offers. |
| `400` | `DALP-0327` | `TOKEN_DOCUMENTS_INVALID_OBJECT_KEY` | The `objectKey` does not name an object under this asset. A caller error: confirm the key the upload link returned. |
| `403` | `DALP-9485` | `TOKEN_ACCESS_UNAUTHORIZED` | The wallet that signs the request does not hold the governance role on the asset. Returned by the upload link, confirm and delete routes. A delete answers it whether or not the document exists. |
| `404` | `DALP-0322` | `TOKEN_DOCUMENTS_DOCUMENT_GROUP_NOT_FOUND_REPLACEMENT` | The `replaceGroupId` names no document of the requested type on this asset. A caller error. |
| `404` | `DALP-0326` | `TOKEN_DOCUMENTS_FILE_NOT_FOUND_STORAGE_UPLOAD_FAILED` | The platform could not read the stored object. On a confirm, upload the file again with a new link. On a download, try again, and contact support if it recurs. |
| `404` | `DALP-9486` | `TOKEN_DOCUMENTS_READ_DOCUMENT_NOT_FOUND` | A download names no live latest version the caller may read. A missing, superseded, deleted or higher-visibility document answers the same way. |
| `404` | `DALP-0323` | `TOKEN_DOCUMENTS_DOCUMENT_NOT_FOUND` | A delete names no live version on this asset. |
| `422` | `DALP-0321` | `TOKEN_DOCUMENTS_DECLARED_FILE_SIZE_DOES_NOT_MATCH_ACTUAL_STORAGE` | The stored object is not the size the request declared, for any type other than `brand_logo`. The platform deletes it. Upload again. |
| `422` | `DALP-12131` | `TOKEN_BRAND_LOGO_REJECTED` | On confirm, a `brand_logo` whose stored size differs from the declared size, whose stored bytes are not the declared PNG, JPEG or WebP type, or that exceeds 2048 pixels on a side. The platform deletes it. |
| `503` | `DALP-9267` | `TOKEN_WRITE_PERSISTENCE_FAILED` | The platform could not record the document. The error is retryable: retry the confirm call once the platform recovers. |

[Asset documents and holder notices](https://docs.settlemint.com/docs/console/asset-management/manage/documents) describes the same flow in the Console.

## Status codes [#status-codes]

These routes answer an error with a short plain-text body, such as `Forbidden`, and no DALP error envelope or `DALP-` id, so branch on the HTTP status.

| Status | Meaning |
| --- | --- |
| `200` | The object exists and the caller can read it. |
| `400` | The path could not be parsed into an object key. |
| `401` | No signed-in session on the request. |
| `403` | On `/dalp/private/*`: the session's user is not a platform administrator, or the key has a `.` or `..` segment or fewer than two segments. |
| `404` | No object exists at that key. Also returned for a public request whose key is outside the allowed prefixes. |
| `405` | A method other than `GET` or `HEAD`. |
| `500` | An unclassified storage read failure. DALP gives no retry guarantee for it. Investigate a `500` that recurs on the same key. |
| `503` | DALP could not reach object storage. Retry once the service recovers. |

`/dalp/*` and `/dalp/private/*` have no route-specific rate limit. The per-key limit on [Authentication and API keys](https://docs.settlemint.com/docs/api-reference/guides/authentication-api-keys) does not apply, because these routes reject API keys or never require one.

## Tell a session problem from a scope problem [#tell-a-session-problem-from-a-scope-problem]

A `401` and a `403` have different causes. `401` means DALP found no valid session at all: no cookie, an expired one, or a request sent from a context that never signed in. `403` means the session is real and DALP knows who you are, but your user does not hold the platform `admin` role, or the key has a `.` or `..` segment or fewer than two segments. The platform checks this before it reads storage, so a refused key answers `403` whether or not an object exists there.

A caller without the platform `admin` role, an organisation owner included, receives `403` on every private key, including a key that names their own user or organisation. Switching the active organisation or signing in again does not change the answer. Read the file through the route of its resource instead: the KYC document download route, the statement download route or the asset document routes.

## Next steps [#next-steps]

- [Errors](https://docs.settlemint.com/docs/api-reference/guides/errors) covers the error envelope of the Platform API routes, which the file routes do not use.
- [Authentication and API keys](https://docs.settlemint.com/docs/api-reference/guides/authentication-api-keys) covers API-key authentication and its scope, which private file routes do not accept.


# Governance votes

Source: https://docs.settlemint.com/docs/api-reference/guides/governance
Create a holder vote on a token, cast ballots, queue and execute the result, and run signed off-chain polls with the governance routes of the Platform API.

The governance routes run a holder vote on a token and the execution that follows. They sit under `/api/v2/addons/governance`. A resolution (`mode: "binary"`) asks holders to approve or reject one decision, a multi-option vote (`mode: "multiOption"`) asks them to choose between named options, and a poll records signed ballots off the ledger. Only a resolution can carry token changes. The token needs the voting-power feature attached before it can carry a vote. [Governance votes in the Console](https://docs.settlemint.com/docs/console/my-assets/votes) drives the same routes from screens.

## Routes [#routes]

| Route | Use |
| --- | --- |
| `GET /proposals` and `POST /proposals` | List votes, or create one. |
| `GET /governors/{governorAddress}/proposals/{proposalId}` | Read one vote. |
| `GET .../proposals/{proposalId}/ballots`, `.../turnout`, `.../export` | Read the ballots, the turnout over time, or an export of the ballots. |
| `POST /votes` | Cast a ballot on a vote. |
| `POST /queue-operations`, `POST /executions`, `POST /cancellations` | Queue a succeeded vote, execute a queued one, or cancel a vote. |
| `GET /instances/{assetId}`, `POST /preflights` | Read a token's governor and timelock, or check a vote before creating it. |
| `POST /document-uploads`, `POST /document-downloads` | Get a signed URL to upload a vote document, or to download one. |
| `POST /polls` and `GET /polls`, `GET /polls/{pollId}`, `POST /polls/{pollId}/close`, `GET .../export` | Create, list, read, close, and export a poll. |
| `POST /polls/{pollId}/ballots`, `POST /polls/{pollId}/ballots/sign` | Record a signed ballot, or sign and record one with the caller's wallet. |

Creating, casting, queueing, executing and cancelling a vote each send a transaction. Each returns the settled result, or an accepted answer to follow while the transaction is still queued, like the other writes on the [idempotency and async settlement](https://docs.settlemint.com/docs/api-reference/guides/idempotency-async-settlement) contract. From a signed-in session each also needs a `walletVerification` block. A request sent with an API key needs none, because creating the key took one, as [API keys](https://docs.settlemint.com/docs/api-reference/guides/authentication-api-keys) describes. The governor checks the governance role on the token, so creating or cancelling a vote needs that role. Queueing and executing a vote need no role. A create that breaks the rules below, or a step the vote's current state does not allow, is refused with `422` [DALP-14259](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference#domain-rule-errors). A refused create names the rule it broke in `data.reason`: `recordDateTooEarly`, `recordDateTooLate`, `votingPowerMissing`, `documentNotOwned`, `optionsInvalid`, `votingPeriodOutOfRange`, `executionDelayOutOfRange`, `quorumOutOfRange`, `approvalThresholdOutOfRange`, `treasuryIsToken` or `metadataKeyLocked`. A refusal of a later step carries no `reason`. `metadataKeyLocked` means a `setMetadata` entry sets a key the token has locked, a key the token's template keeps off chain, or a key an earlier entry in the same vote locks. `POST /preflights` lists each such entry in `metadataKeyLocks`, by `actionIndex` and `entryIndex`, before you create the vote.

## Create a vote [#create-a-vote]

`POST /api/v2/addons/governance/proposals` takes the `tokenAddress`, the `mode`, a `title`, a `descriptionRichText`, the `recordDateAt`, and `quorumBps`. It also takes an optional `approvalThresholdBps`, `votingPeriodSeconds`, and `executionDelaySeconds`, the `options` of a multi-option vote, the `actions` of a resolution that carries token changes, and `documents`. A document's `objectKey` must come from an upload grant issued to you. Quorum and threshold are in basis points. The platform refuses a record date less than 1 day or more than 90 days ahead, and a voting period or execution delay outside 1 to 30 days. It also refuses a multi-option vote whose `options` repeat a label, compared without case and surrounding spaces, with `portfolio.governance.PREFLIGHT_FAILED` and a message that names both options. Without a value, the voting period is 7 days and the execution delay 2 days. The Console offers a fixed set of these lengths, which [Create a vote](https://docs.settlemint.com/docs/console/my-assets/votes#create-a-vote) lists.

```bash
curl -X POST "https://your-instance.example.com/api/v2/addons/governance/proposals" \
  -H "X-Api-Key: sm_dalp_..." \
  -H "Prefer: wait=30" \
  -H "Content-Type: application/json" \
  -d '{
    "tokenAddress": "0x8a791620dd6260079bf849dc5567adc3f2fdc318",
    "mode": "binary",
    "title": "Approve the 2027 dividend policy",
    "descriptionRichText": "Holders approve paying 40 percent of 2026 net profit as a dividend in 2027.",
    "recordDateAt": "2026-11-23T00:00:00.000Z",
    "quorumBps": 2000
  }'
```

A settled create answers `200` with the token's governor and timelock and the vote's `proposalId`, which the cast, queue, execute and cancel calls take:

```json
{
  "data": {
    "transactionHash": "0x7d1e4b2a9c3f5e6d8a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e2f",
    "governorAddress": "0x3Aa5ebB10DC797CAC828524e59A333d0A371443c",
    "timelockAddress": "0xc6e7DF5E7b4f2A278906862b61205850344D4e7d",
    "proposalId": "48219370651823409171526401837265940018273645501928374650192837465019283746"
  },
  "meta": {
    "txHashes": ["0x7d1e4b2a9c3f5e6d8a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e2f"],
    "transactionId": "0198f3c2-5a1b-7c4d-8e9f-0a1b2c3d4e5f"
  },
  "links": { "self": "/api/v2/addons/governance/proposals" }
}
```

Without `Prefer: wait` the create answers `202` with `transactionId`, `status: "queued"` and `statusUrl`.

The first vote on a token also deploys the token's governor, the contract that counts its votes, and its timelock, the contract that holds a passed vote's actions for the execution delay and then executes them. The body of that first vote can carry `quorumFloorBps`, 500 by default, and `approvalThresholdFloorBps`, 0 by default. These floors are the lowest quorum and approval threshold that this vote and every later vote on the token can set.

The token's timelock executes a vote's `actions`. Create is refused with `409` [DALP-9155](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference#client-request-errors), `GOVERNANCE_TIMELOCK_MISSING_ROLE`, while the timelock lacks the governance role on the token's access manager. Grant that role to the timelock, then send the create again. A vote without `actions` needs no timelock role.

## How a vote is counted [#how-a-vote-is-counted]

The weight of a ballot is the holder's voting power at the record date. Voting power counts only when the holder has activated it and has not delegated it away. `GET /api/v2/tokens/{assetId}/voting-power/snapshot-weights` returns voting power per holder as it stood at a past block.

- **Quorum** is `ceil(quorumBps × total supply at the record date / 10000)`. A basis point is a hundredth of a percent, so `quorumBps: 2000` is 20 percent of the supply. It counts every ballot cast, abstentions included, and it is met at exactly that figure. The supply is the token's whole supply at the record date, not only the activated voting power.
- **Approval** applies to a resolution. The `for` total must exceed the `against` total. When `approvalThresholdBps` is set, `for` must also reach `ceil(approvalThresholdBps × (for + against) / 10000)`. Abstentions are outside both terms, and the threshold can only tighten the simple majority.
- **A multi-option vote** succeeds on quorum alone. The winning option is read from the tallies, and a tie reports no winner.

## Cast, queue, and execute [#cast-queue-and-execute]

`POST /api/v2/addons/governance/votes` takes the `tokenAddress`, the `governorAddress`, the `proposalId`, and either `support` (`for`, `against`, or `abstain`) or `optionIndex` for a multi-option vote, never both. An optional `reason` travels with the ballot. The vote must be open, and the wallet must hold voting power at the record date. A ballot is final once cast.

`GET .../ballots` lists each ballot with its `voter`, `weight`, `reason`, and `castAt`. On a resolution, `support` is `for`, `against`, or `abstain`, and `optionIndex` and `optionLabel` are `null`. On a multi-option vote, `support` is `option`, `optionIndex` is the chosen option's position counted from zero, and `optionLabel` is that option's text. `GET .../export` returns the same ballots as CSV, with an `optionLabel` column after `castAt`. The lines above the ballots give a resolution's `forVotes`, `againstVotes`, and `abstainVotes` totals, or one `optionVotes` line per option of a multi-option vote: its position, its text, and its votes.

When the vote has succeeded, `POST /queue-operations` queues it on the timelock, which starts the execution delay. After the delay, `POST /executions` applies everything the vote holds in one transaction. `POST /cancellations` cancels a vote while it is pending or queued. Any current holder of the token's governance role can cancel, not only the person who created the vote, so the role can stop a vote the holders passed before it executes. All three take the `tokenAddress`, the `governorAddress`, and the `proposalId`. Read the vote before each step to see its status.

## Polls [#polls]

`POST /api/v2/addons/governance/polls` takes the `tokenAddress`, a `title`, an optional `description`, the `options`, and the `recordDateAt`, `opensAt`, and `closesAt` times. The record date must come before `opensAt`, and `opensAt` before `closesAt`. Each option must differ from the others in the same way as a multi-option vote's, or the create fails with `portfolio.governance.PREFLIGHT_FAILED`. Creating, closing and exporting a poll need the governance role on the token. A poll ballot names the `voter`, the `optionIndex`, and the poll's `definitionHash`, and carries the voter's signature. The platform refuses a ballot whose hash differs from the poll's definition, whose voter is not one of the caller's wallets, or whose signature does not verify as the voter's. It also refuses a voter with no voting power at the record date. `GET /polls/{pollId}` returns `callerWalletVotes`, each of the caller's wallets that held voting power at the record date with that power, largest first, so a client can tell before signing whether the caller can vote: an empty list means none of their wallets can. A poll never reaches the queue and execute routes.

## Next steps [#next-steps]

- [Governance votes in the Console](https://docs.settlemint.com/docs/console/my-assets/votes) for the screens, the statuses, and the rules a vote follows.
- [Platform API error reference](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference) for the refusal codes.
- [Idempotency and async settlement](https://docs.settlemint.com/docs/api-reference/guides/idempotency-async-settlement) for the header contract every write shares.


# Idempotency and async settlement

Source: https://docs.settlemint.com/docs/api-reference/guides/idempotency-async-settlement
Where Idempotency-Key deduplicates queued transactions, and how Prefer waits for on-chain settlement or returns at once.

## Overview [#overview]

Send an `Idempotency-Key` on a write so that a retry after a timeout attaches to the original transaction instead of moving value twice, and send `Prefer: wait=N` to receive the settled result in the same response instead of polling a status URL. An on-chain write can continue after its HTTP request ends, and the transaction queue deduplicates only the work that reaches it, so a route can do other work first. The money-moving v2 writes echo the key and are safe to replay. On any other route, read the original request's status before you retry.

Transaction-writing requests are asynchronous by default. DALP queues the instruction and returns `202 Accepted` with a status URL. A timeout does not cancel the queued work.

A mint sent with `Prefer: wait=30` that has not settled within the wait answers with the queue handle. The values are illustrative:

```http
HTTP/1.1 202 Accepted
Content-Type: application/json
Location: /api/v2/transaction-requests/0198f1a2-3c4d-7e8f-9a0b-1c2d3e4f5a6b
Idempotency-Key: 6f1c2a9e-4b7d-4e2a-9c3f-1a2b3c4d5e6f
Preference-Applied: wait=30

{
  "transactionId": "0198f1a2-3c4d-7e8f-9a0b-1c2d3e4f5a6b",
  "status": "QUEUED",
  "statusUrl": "/api/v2/transaction-requests/0198f1a2-3c4d-7e8f-9a0b-1c2d3e4f5a6b"
}
```

When the mint settles within the wait, the answer is `200` with the route's settled body, and `meta.transactionId` names the same transaction request.

## Idempotency-Key [#idempotency-key]

`Idempotency-Key` identifies one client-side instruction. The queue can attach a matching submission to the same transaction request, but this does not prove that the entire API route is replay-safe. A route promises the same outcome on replay only when its contract says so and its response echoes the effective key.

The money-moving v2 writes echo the key: token mints, burns, transfers, forced transfers, transfer acceptances and approvals, claims, redemptions, yield, interest, dividend and maturity claims and top-ups, the fixed-yield schedule writes, the XvP settlement writes, the token-sale writes, the airdrop writes, the paymaster deposit and the bank-rail cash-out create. On each of them a replay with the same key and body never moves value twice. A write checks its preconditions, such as a balance, headroom or a claimable amount, before it reaches the queue. A replay sent after the original settled can therefore answer that precondition's refusal instead of the original result, because the original already used what it checked. A token-sale fund sent again without an `amount` tops up only what the sale can still accept, so after the original landed it mints nothing. Read the original operation's status before you treat such a refusal as a failure.

Use a new key for each distinct instruction. On a route that documents replay safety, retain that key across retries. A duplicate mint or transfer moves value twice.

DALP reads the `Idempotency-Key` header in any letter case, and strips one pair of surrounding double quotes from its value. An empty value counts as no key at all, whether you send it bare or as a pair of quotes. If you omit the header, DALP generates one for that request, but you have nothing to retry with if the response is lost. Send your own key on a route that documents replay safety.

The transaction queue keys retry identity to your `Idempotency-Key` and to the write it names for 24 hours after the first request: the wallet selection (`accountWalletId`, `smartWalletAddress`, `forceEoa`) and the call itself (operation, target contract, call data, and value). An omitted value and a value of `0` are the same value. The comparison also covers the user who sends the write and whether the request declined the funding pause with `Prefer: dalp-no-funding-pause`, so a retry that adds or drops that directive is a different write. A retry that only changes `Prefer: wait` is the same write. The queue rejects a different write under the same key with `409 Conflict` and the route's own conflict code, such as `TRANSACTION_IDEMPOTENCY_KEY_CONFLICT` (`DALP-14238`). A token or token-feature write the queue refuses for this reason answers `400 Bad Request` with code `TRANSACTION_QUEUE_IDEMPOTENCY_CONFLICT` (`DALP-14061`) and `data.refusal` set to `QueueIdempotencyConflict`. A v2 compliance write that installs, configures, scopes, or removes a compliance module, sets or clears a holder lock, or replaces a token's compliance expression, answers `409 Conflict` with code `REQUEST_STATE_CONFLICT` (`DALP-14262`) when the queue refuses it for this reason. Creating system compliance modules is not covered by this answer.

| Situation | DALP behaviour |
| --- | --- |
| Same key, same write, within 24 hours | Attaches to the original instruction and returns its current transaction id, state, and result fields, whether or not the original request has finished processing. Never submits a second transaction for a write that could have reached the chain. |
| Same key, different call (operation, target contract, call data, or value), within 24 hours | Rejected with the route's conflict answer, not retryable. Send a new key for the changed instruction. |
| Same key, different wallet selection (`accountWalletId`, `smartWalletAddress`, or `forceEoa`), within 24 hours | Rejected with the route's conflict answer, not retryable. Send a new key for the changed wallet selection. |
| Same key, reused after the 24-hour window | Rejected with the route's conflict answer, not retryable. Confirm the earlier instruction's outcome, then retry with a new key. |
| Same key, sent again after a `TRANSACTION_QUEUE_FUNDING_REQUIRED` refusal | Fund the paying account first. The queue then enqueues a fresh attempt, or answers `400` with `TRANSACTION_QUEUE_DUPLICATE_SETTLED` when the refused attempt still holds the key. On that answer, send the write under a new key. |
| Same key, sent again after a `TRANSACTION_QUEUE_RETRIES_EXHAUSTED` answer | Returns that request's recorded failure. This `503` means a transient fault outlasted every retry the queue allows and the request cannot land. Wait for a short backoff, then send the write under a new key. For a write of several chained steps, read `transactionId` first, because an earlier step can have completed. |

Token and token-feature writes publish that spent retry budget as `TRANSACTION_QUEUE_RETRIES_EXHAUSTED`. Other queued writes, such as a compliance module change, a governance proposal, a role change, a market listing, a smart-wallet mutation, a forced escrow transfer or a token-sale mint, answer their route's own dependency-unavailable refusal with `retryable: true`. Treat both the same way: wait for a short backoff, then send the write under a new key, because the same key returns the recorded failure.

After a timeout, inspect the original operation's status before sending another write. The first may still complete. Retry with the original `Idempotency-Key` only when the route documents replay safety.

## Concurrent requests and changed bodies [#concurrent-requests-and-changed-bodies]

Concurrent transaction requests that send the same write, as the identity rule in the previous section defines it, on the same chain under the same idempotency key attach to one instruction. A retry can return an in-flight state. It need not wait for the original request to finish before being recognised.

A reused key is compared against the write it first named, not only the wallet selection. Reusing a key with a different recipient or amount changes the call data, so DALP rejects it with the route's conflict answer instead of returning the earlier instruction. A token mint sent again under its key with another amount, for example, answers `400 Bad Request` with `TRANSACTION_QUEUE_IDEMPOTENCY_CONFLICT` (`DALP-14061`). Assign a distinct key to every distinct instruction.

A one-time outcome, such as a bond's maturity, a redemption of a holder's whole balance, a holder's yield claim, or a buyer's refund or token withdrawal on a token sale, takes one running request at a time, whatever its key. A second request for the same outcome under another key answers `400 Bad Request` with `TRANSACTION_QUEUE_OUTCOME_IN_FLIGHT` (`DALP-14751`) and `data.refusal` set to `QueueOutcomeInFlight`, before anything is sent, so nothing moves because of it. `data.transactionId` names the running request when the queue could read it. Read that request's result. Send the write again only if it failed. A retry under the running request's own key still attaches to it.

At the queue, one reuse is allowed on purpose: when the earlier write failed before anything was signed, a matching submission under the same key enqueues a fresh attempt. The failed attempt keeps its own transaction id and no longer answers that key.

A retry retains the original transaction-request identity. Reconcile by that identity and the resulting chain transaction. Request logs, workflow attempts, and settlement records describe different stages. Do not assume they all have one row per instruction.

## Prefer: choose sync or async [#prefer-choose-sync-or-async]

Transaction routes default to asynchronous: DALP queues the operation and returns `202 Accepted` immediately. Use `Prefer` to change that per request. The API reference lists the `Prefer` header only on the writes that can honour it: every queue-backed write, and each write that settles within the request but reads a directive, with the directives it reads. A write without it answers once its work is done and ignores the header.

| You send | Mode | What DALP does |
| --- | --- | --- |
| Nothing | Async (the default) | Returns `202 Accepted` with the queued transaction's `transactionId`, `status` and `statusUrl` immediately, and the status URL in `Location`. Poll it until the operation reaches a terminal state. |
| `Prefer: respond-async` | Async | Same as the default, sent explicitly. |
| `Prefer: wait` | Sync | Holds the response for up to the default wait of 99 seconds. Returns the settled result if the operation finishes in time. Otherwise returns the same `202 Accepted` as async. |
| `Prefer: wait=N` | Sync | Same, with the wait set to `N` seconds, clamped between 5 and 99. |
| `Prefer: respond-async, wait=N` | Sync | Same as `wait=N`. The explicit `respond-async` only names the answer you already get when the wait runs out. |

The wait also ends a few seconds before the request's own deadline, which the deployment sets, so DALP answers before the gateway in front of it times out. A wait that would run past that deadline degrades to `202 Accepted` there.

A few writes answer `202 Accepted` with their own resource instead of a queued transaction handle. Creating or lifting a wallet restriction (`POST /api/v2/restrictions`, `PATCH /api/v2/restrictions/{restrictionId}`) returns the restriction as stored, with `Location` set to the restriction's own URL. While any token's freeze or lift is still `queued` or `lift-queued`, the answer is `202`. Once every token has landed, it is `200`. Poll `Location` until no token is queued: each read settles queued tokens against the transaction queue. Without `Prefer`, these routes answer `202` as soon as the freezes or lifts are queued. A lift sent while one of the restriction's freezes is still queued is refused with `409` (`WALLET_RESTRICTION_FREEZE_IN_FLIGHT`). Read the restriction until no token is queued, then lift again. A lift whose unfreezes are still queued finishes on its own: the read that settles the last one marks the restriction lifted.

Exercising tradable rights (`POST /api/v2/tokens/{assetId}/corporate-actions/{corporateActionId}/rights-exercises`) works the same way. The answer is the exercise as recorded: `200` with status `settled` once the payment and the rights movement landed, `202` with status `submitted` while the queue holds them. `Location` is this wallet's exercised total for the rights issue (`GET …/rights-exercises/{holder}`), and each read settles a submitted exercise against the queue. Retrying the exercise with the same `Idempotency-Key` also returns its outcome.

Settling a fund's subscriptions for a dealing day (`POST /api/v2/tokens/{assetId}/subscription-settlements`) answers `200` once every batch has landed, and `202` with the same settlement body while any batch is still queued: `pendingCount` counts the requests whose mint and cash pull sit in the queue without a receipt. Retry the request with the same `Idempotency-Key` to record the batches that have landed. The answer turns `200` when `pendingCount` reaches zero. A batch the chain refuses is reopened, together with the batches the settlement did not send, so its requests settle on a later dealing day. A batch the queue already holds is never reopened.

Without `Prefer`, both routes answer as soon as the work is queued.

Three more writes follow the same pattern. Creating the bank rail escrow (`POST /api/v2/bank-rail/connections/{connectionId}/token-links/{tokenLinkId}/escrow`) answers `200` with the escrow once it is indexed and `202` with state `creating` and `Location` set to the escrow read. That read reports `ready` when the escrow is indexed. The token link transition and decision routes (`.../transitions`, `.../decisions`) answer `202` with the link and its `mintCapReplacement` while the rail wallet's re-delegation for a mint cap change is queued, with `Location` set to the connection's token-link list. Each read of the list settles the replacement and restores the previous cap if the write fails. Switching the account kind to smart wallets (`POST /api/v2/settings` with `ACCOUNT_KIND` set to `smart-account`) uses your `Prefer` for the synchronisation writes, and while any has not landed the answer is `202` with the first write's transaction handle and `Location` set to its status URL. Read the transaction requests until they settle, then send the same request again with the same `Idempotency-Key`. The queue attaches to the landed writes and the switch finishes. The frozen v1 route keeps its single wait.

Corporate-action writes follow the same rule. Creating a corporate action (`POST /api/v2/tokens/{assetId}/corporate-actions`), confirming it (`POST .../corporate-actions/{corporateActionId}/confirm`) and the two commit routes (`POST .../corporate-actions/commit`, `POST .../corporate-actions/{corporateActionId}/commit`) answer with the corporate action as recorded. The answer is `200` once nothing the request sent is still in flight, and `202` with the same body while a transaction has not landed: the record is `executing`, or a cash dividend or distribution is still `drafted` with no `dividendId` because its declaration is queued. `Location` is the corporate action read, and each read settles the record against the queue. Without `Prefer`, these routes answer `202` as soon as the transaction that declares a dividend, matures a bond, sends a redemption or cash-leg unit, or burns lapsed rights is queued. With `Prefer: wait` they hold up to the wait and answer `200` when everything landed in time. A redemption or cash-leg run that stopped after a queued unit continues from the first unit it has not sent when you send the same confirm again, and a rights issue close continues its burn the same way.

Trading venue order writes follow the same rule. Without `Prefer`, `POST /api/v2/addons/trading-venues/{venueAddress}/orders` and `PATCH /api/v2/addons/trading-venues/{venueAddress}/orders/{orderId}` (a replacement) answer `202` with the order placement and its URL in `Location`: the order is signed, checked and committed to escrow after the answer, and rests on the book only once its escrow commitment has landed. With `Prefer: wait` they hold up to the wait and answer `200` with the placed order, or the same `202` if the wait ends first. The wallet step-up and a self custody wallet's signature request (`OrderExternalAuthorizationRequired`) are still answered in the request. Poll `GET /api/v2/addons/trading-venues/{venueAddress}/order-placements/{orderId}` until `status` is `placed` or `failed`. `signing_pending` carries the custody `approvalReference` and `approvalExpiresAt`, and repeating the same request with the same `Idempotency-Key` after an approver decides places the order. Cancelling an order or every order of a participant answers `202` while an escrow refund is still queued (`escrowRefund: queued`, or `refundsQueued` above zero). The orders are off the book either way, and reading the order settles the refund from the queue. Callers that need the settled answer send `Prefer: wait`.

Trading venue administration writes work the same way. Without `Prefer`, `POST /api/v2/addons/trading-venues` answers `202` with the new venue address and `status: deploying`, and `Location` points at the venue read, which keeps answering `deploying` until the venue exists on chain. `POST /api/v2/addons/trading-venues/{venueAddress}/markets`, `PUT .../markets/{marketId}` when it sets a holding period, and `POST .../markets/{marketId}/transitions` answer `202` with the `marketId` and `status: processing`, and `Location` points at the market read. The chain write is submitted and the market row is committed after the answer, by a durable workflow that resumes by itself after a restart, so repeating the request with the same `Idempotency-Key` attaches to the running work instead of starting a second one. With `Prefer: wait` the same routes hold up to the wait and answer `200` with the settled result, or the same `202` if the wait ends first.

Creating a managed participant is an exception to the default. `POST /api/v2/participants` holds the request for your `Prefer: wait`, or for the default wait when you send no `Prefer`, and answers `202` with `requestId`, `state` and `statusUrl` when the custody and identity steps run longer, with `Location` set to the custody request's status URL. The create keeps running, and repeating the request with the same `Idempotency-Key` attaches to the same run and never starts a second participant.

A synchronous wait never changes the outcome of the operation, only whether DALP returns the settled result inline or hands you a status URL. DALP echoes the directives it honoured in the `Preference-Applied` response header, per RFC 7240: `wait=N` with the wait it applied after clamping, and `respond-async` when you sent it. A request with neither `wait` nor `respond-async` gets no `Preference-Applied` header, even when it sends `dalp-no-funding-pause`.

For example, `Prefer: wait=30` waits up to 30 seconds for settlement. If the wait expires first, DALP returns the queued handle. See the [V2 mint endpoint](https://docs.settlemint.com/docs/api-reference/v2) for the complete mint request and response schema.

Send `Idempotency-Key` alongside `Prefer` on a replay-safe synchronous route.

A settled response names the transaction request behind the write in `meta.transactionId`. On a replay-safe route whose `202 Accepted` handle names that same request as `transactionId`, a retry that returns `200 OK` after the work finished answers with the id you already hold. Read the request with `GET /api/v2/transaction-requests/{transactionId}`, and retry a failed one with `POST /api/v2/transaction-requests/{transactionId}/transitions` and `action: retry`.

The field is present when the settled body was built from a queue result that still holds the request, including one that completed without submitting a chain transaction, where `meta.txHashes` is empty and `meta.transactionId` still names the request. It is absent otherwise, so treat a missing key as no id to correlate with rather than as proof that no request exists. Read the key rather than assuming a position: one transaction request can submit several chain transactions, so the hash count says nothing about the request count.

## Terminal states and retrying a failed transaction [#terminal-states-and-retrying-a-failed-transaction]

Whether you poll the status URL or wait synchronously, the wait ends when a transaction request reaches `COMPLETED`, `FAILED` or `CANCELLED`, or `DEAD_LETTER` with `mayStillLand` set to `false`. A `DEAD_LETTER` request whose `mayStillLand` is `true` is not terminal: the synchronous wait keeps going, and so does the status stream. Only `COMPLETED` and `CANCELLED` are immutable. A `DEAD_LETTER` request can still settle as `COMPLETED`, `FAILED` or `CANCELLED`, as this section explains. An organisation owner or a platform administrator can force-retry a `FAILED` or `DEAD_LETTER` request to move it back to `QUEUED`. Force-retry refuses a `DEAD_LETTER` request whose `mayStillLand` is `true` with `409` and `TRANSACTION_FORCE_RETRY_CALL_MAY_LAND` (`DALP-200383`) while the chain shows the call or its nonce slot is unresolved, because another attempt could run the call twice. When the chain does not show the call and no nonce reservation remains, the caller can override that refusal by sending `custodianStopped: true`, which records their statement that they confirmed the original call stopped, with the custody provider for a custody call. The platform does not verify that statement, and a wrong one can run the call twice. Force-retry refuses a request that only reports the outcome of a multi-step workflow, such as a token creation, and a step of a role set, with `409` and `TRANSACTION_WORKFLOW_OWNED` (`DALP-14029`). Send a new role set to repeat a role change. If the requeued request remains unclaimed because dispatch failed, repeating force-retry resumes that attempt. If its run already ended, it starts a new attempt.

`FAILED` and `DEAD_LETTER` both carry `errorMessage`, a plain-text description such as `"Execution reverted"`. When the failure maps to a known catalogue entry, the response also carries `contractError`, with the same `id`, `why`, `fix` shape the [error envelope](https://docs.settlemint.com/docs/api-reference/guides/errors) uses elsewhere. Read `errorMessage` when `contractError` is absent. `errorMessage` is null for a caller who can read the request only because it was recorded on behalf of their wallet, unless they are an organisation owner or a platform administrator. That caller also gets no `custodyApproval`, and `activeRequirement` without `shortfall` and `recommendedTotal`.

A `FAILED` request has a proved end: the call did not land, or it reverted. A `DEAD_LETTER` request stopped before a final result, and its call may still reach the chain. Read `mayStillLand` on the transaction request. While it is `true`, do not send the call again: wait, because a later `COMPLETED`, `FAILED` or `CANCELLED` can follow for the same request. If it never settles, ask an organisation owner or a platform administrator, to resolve it through the transaction-request repair actions, and give them the `transactionId`.

A failed transaction does not retry itself. The queue matches the same key to its existing transaction request. Replaying the API route may run other work before that match. An organisation owner or a platform administrator can requeue a `FAILED` or `DEAD_LETTER` request through the [transaction-request retry endpoint](https://docs.settlemint.com/docs/api-reference/v2). After this recovery, poll for the active state or result. If you submit a separate write instead, first read `errorMessage` or `contractError.fix` to decide whether retrying can succeed, then use a new `Idempotency-Key`. Use a new key for a `DEAD_LETTER` request only when its `mayStillLand` is `false`.

A write can also return `504` with `INDEXER_BARRIER_TIMEOUT` (`DALP-12074`). The transaction succeeded on chain, but [Ledger Data](https://docs.settlemint.com/docs/concepts/records-and-evidence/ledger-data), the platform's index of chain records, did not finish indexing its block before the request deadline. The error's `retryable` flag is `false`, so a client that resends retryable failures does not repeat the write, which has already happened. Only the read can be repeated. Read the transaction request with `data.transactionId` to confirm it, then repeat the read that needs the indexed result. If the index stays behind, ask an operator to inspect the indexer errors for `data.chainId` at or before `data.blockNumber`.

## Next steps [#next-steps]

- [Errors](https://docs.settlemint.com/docs/api-reference/guides/errors) covers the full error contract, including how a `409 Conflict` response is structured.
- [Webhooks](https://docs.settlemint.com/docs/api-reference/webhooks) covers the events the platform sends and how their outcomes relate to accepted writes.


# Statements and confirmations

Source: https://docs.settlemint.com/docs/api-reference/guides/investor-statements
Set statement policy, generate a statement for a final date range, and download statements, daily contract notes and trade confirmations for your own wallets.

## Overview [#overview]

A statement is one wallet's record of its holdings, movements, fees and profit and loss over a period, in CSV, XLSX or PDF, which an investor app downloads instead of rebuilding the figures itself. The platform produces scheduled statements per wallet and network, at the cadence set by the organisation's policy, and you can also request one for a specific date range. The policy selects which sections appear: opening and closing positions, the portfolio at close, movements, fees, realised and period-end unrealised profit and loss per security, custody deposits and withdrawals, and corporate actions.

Listing and downloading follow the same permission as generating. A caller sees the statements of their own wallets in the request's organisation and network, and a statement for another wallet answers `404` rather than revealing that it exists. An organisation owner or a platform administrator sees every holder's statements in the request's organisation and network, so the statement they generate for another holder is listed and downloads for them as well as for the holder. A platform administrator can also read a stored statement file through the [private file route](https://docs.settlemint.com/docs/api-reference/guides/files#private-files).

## Read or replace the statement policy [#read-or-replace-the-statement-policy]

An organisation owner or a platform administrator can read the organisation's policy with `GET` and replace it with `PUT`. Other members receive `404`.

```bash
curl "https://your-instance.example.com/api/v2/reporting/statements/policy" \
  -H "X-Api-Key: <your api key>"
```

The cadence is `daily`, `weekly`, `monthly`, or `quarterly`. The sections are a non-empty selection of `positions`, `portfolio`, `movements`, `pnl`, `fees`, `deposits-withdrawals`, and `corporate-actions`. The formats are a non-empty selection of `csv`, `xlsx`, and `pdf`. Without a saved policy, the platform uses monthly statements with all sections in CSV and PDF.

`PUT` replaces the complete policy. For example, this request selects weekly statements with positions and movements in CSV only.

```bash
curl -X PUT "https://your-instance.example.com/api/v2/reporting/statements/policy" \
  -H "X-Api-Key: <your api key>" \
  -H "Content-Type: application/json" \
  -d '{
    "cadence": "weekly",
    "sections": ["positions", "movements"],
    "formats": ["csv"]
  }'
```

Both policy routes return the policy in `data`.

## When a scheduled statement appears [#when-a-scheduled-statement-appears]

By default the platform checks once an hour for the last three closed periods at the organisation's chosen cadence, with periods counted in UTC. The schedule does not write an older period, so generate it on demand. It writes statements only after the network is final past the period's end. A scheduled statement covers a wallet that held an opening or closing balance, moved units, paid fees, made a custody deposit or withdrawal, or held a corporate action entitlement during the period. The last two count only when the policy selects their section. Other wallets are skipped.

## Generate a statement for a date range [#generate-a-statement-for-a-date-range]

A caller can generate a statement for one of their own wallets. An organisation owner or a platform administrator can also generate one for another holder within the request's organisation and network. Other members receive `404` if `holder` is not one of their wallets.

```bash
curl -X POST "https://your-instance.example.com/api/v2/reporting/statements" \
  -H "X-Api-Key: <your api key>" \
  -H "Content-Type: application/json" \
  -d '{
    "holder": "0x1234567890abcdef1234567890abcdef12345678",
    "start": "2026-09-10T00:00:00.000Z",
    "end": "2026-09-20T00:00:00.000Z"
  }'
```

`start` is inclusive and `end` is exclusive. The start must precede the end, and the range can cover at most 366 days. Otherwise the request returns `400`. The example covers 10 to 19 September 2026 in UTC. The stored period and response use an inclusive `periodEnd` of `2026-09-19T23:59:59.999Z`.

A successful request returns `200` with the statement summary in `data`:

```json
{
  "data": {
    "id": "0198f3a1-4b2c-7d5e-8f60-1a2b3c4d5e6f",
    "chainId": 11155111,
    "account": "0x1234567890abcdef1234567890abcdef12345678",
    "periodStart": "2026-09-10T00:00:00.000Z",
    "periodEnd": "2026-09-19T23:59:59.999Z",
    "openingBlock": "8123456",
    "closingBlock": "8187021",
    "reconciled": true,
    "formats": ["csv", "pdf"],
    "createdAt": "2026-09-21T08:14:03.000Z"
  },
  "links": { "self": "/api/v2/reporting/statements" }
}
```

Generation uses the policy's sections and formats and produces a statement even when the wallet has no activity. Repeating the same holder and range within the same organisation and network returns the existing statement. It does not regenerate it under a changed policy.

| Error | HTTP status | Meaning |
| --- | --- | --- |
| `DALP-0754` | `422` | `StatementRangeRefused` with reason `range-not-final`: the requested period end is not final on the network. Wait for finality before retrying. |
| `DALP-200387` | `422` | `StatementRowCeilingExceeded`: the range holds more rows than one statement can hold. `data.rows` is the count the range produced and `data.ceiling` the most a statement holds. Request a shorter range. |

The error's `periodEnd` uses the same inclusive end as the stored statement. The refused request writes no statement.

## List the caller's statements [#list-the-callers-statements]

```bash
curl "https://your-instance.example.com/api/v2/reporting/statements" \
  -H "X-Api-Key: <your api key>"
```

The list includes scheduled and on-demand statements. Each entry includes the statement `id`, the `account` it covers, `periodStart` and inclusive `periodEnd`, the `openingBlock` and `closingBlock` the balances were read at, the available `formats`, and `reconciled`. `reconciled` is true when, for every security whose balances the platform can read, the opening balance plus the movements listed equals the closing balance. A registered external token that the indexer has stopped following is left out of this check, so it does not make `reconciled` false. Treat a statement with `reconciled: false` as incomplete and raise it with the operator.

## Download one edition [#download-one-edition]

```bash
curl "https://your-instance.example.com/api/v2/reporting/statements/<statementId>/download?format=pdf" \
  -H "X-Api-Key: <your api key>"
```

`format` is `csv`, `xlsx`, or `pdf` and must be one of the statement's available `formats`. Requesting an edition that was not generated returns `404`. The response holds a `downloadUrl` that stays valid for 15 minutes, the file's `mimeType` and `contentLength`, and `digest`, the SHA-256 of the file:

```json
{
  "data": {
    "statementId": "0198f3a1-4b2c-7d5e-8f60-1a2b3c4d5e6f",
    "format": "pdf",
    "downloadUrl": "https://storage.example.com/statements/0198f3a1-4b2c-7d5e-8f60-1a2b3c4d5e6f.pdf?X-Amz-Expires=900&X-Amz-Signature=5f2c...",
    "expiresAt": "2026-09-21T08:29:03.000Z",
    "digest": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08",
    "contentLength": 48213,
    "mimeType": "application/pdf"
  },
  "links": { "self": "/api/v2/reporting/statements/0198f3a1-4b2c-7d5e-8f60-1a2b3c4d5e6f/download" }
}
```

Fetch the file from `downloadUrl` and compare its SHA-256 with `digest` before you store or forward it. Request a new link when one expires. A scheduled or on-demand statement's files never change once it is written. A contract note written again after a change keeps its statement `id` and gets new files, so a later link for that `id` downloads the amended note, and the earlier note is no longer available from this route. Store the `digest` with every file you keep.

## What a statement contains [#what-a-statement-contains]

Position rows carry a closing valuation at the period's inclusive end and indexed closing block. CSV adds `price`, `priceCurrency`, `valuationSource`, `valuationSourceId`, `priceTimestamp`, `valuationDate`, `marketValue`, `valuationBaseCurrency`, `baseCurrencyValue`, `fxSourceIds`, `fxValuationDate`, `valuationStatus`, `valuationFlags`, and `valuationReason` after `reconciled`. PDF positions show compact price, market value, base value, and valuation columns. Market value is in the historical quote currency. Base-currency value uses the historical base currency and FX route at the same point. Market value, base-currency value and the totals are rounded half away from zero to the minor unit of their currency, such as two decimal places for EUR and none for JPY. The total adds the unrounded values before it is rounded. The request has no separate valuation-date override.

When no valid historical price exists, the row is `unpriced` and its price and value cells are empty. Those rows are left out of the base-currency total. The total closes the positions section. The PDF shows it as a `Total` row and the CSV shows it as a `position-total` row. Both say how many positions they left out. The PDF shows each price time to the minute and the other valuation dates as dates. The CSV carries the full timestamps. Stale token prices or FX routes remain visible with `stale-price` or `stale-fx`. When the FX route is missing, market value remains available and the row is `missing-fx` with an empty base-currency value.

When selected, the portfolio section states every holding at the closing block: its quantity, weighted-average cost and the cost basis currency, its valuation price with its source, market value, base-currency value, unrealised profit and loss with its currency, and its share of the base-currency total. The share is truncated to four decimal places and is calculated over the section's own total. A holding whose cost basis still counts an acquisition without a price shows no average cost, and one whose price or FX route is missing shows no share and is left out of the table total. The PDF prints the section as a portfolio table with a per-currency total and states the portfolio value in its summary. The CSV writes one `portfolio` row per holding, with `averageCost`, `averageCostCurrency`, and `shareOfTotalPercent` as its own columns.

When selected, profit and loss uses weighted-average cost. The platform skips that calculation when the policy omits the section. Trading fees are excluded from profit and loss and appear only when the Fees section is selected. A figure is marked incomplete when the cost basis or an indexed price is missing, such as a held position with no cost-basis history. A line has no unrealised figure when the period-end holding has no cost basis or no indexed price, or when the indexer has stopped following a registered external token so its closing amount is unknown: the CSV cell is empty, the PDF reads n/a, and the line is marked incomplete.

The deposits and withdrawals section lists the wallet's custody deposits and withdrawals in the period: date, asset, amount, fee, status, transaction hash, and the sending or receiving address. A withdrawal that had not reached a final state by the end of the period is listed as `pending`. The section appears only when custody operations are switched on.

The corporate actions section lists each corporate action that entitled the wallet in the period: the event type, record and payment dates, entitlement, amount paid, status, and the corporate action's reference. When the policy selects this section, a mint or burn that a corporate action settled carries the same reference in the movements: the CSV puts it in the `reference` column and the PDF labels the movement with the event.

The platform produces only the formats selected in the policy. CSV, XLSX, and PDF editions contain the same figures. XLSX uses one worksheet per selected section, from positions, portfolio, movements, fees, profit and loss, deposits and withdrawals, and corporate actions. Its cells are typed numbers, and it supports exports above 1,000 rows. The CSV keeps full addresses and transaction hashes, which the PDF shortens to fit the page. The same figures are also available as CSV from `GET /api/v2/user-pnl/export`. A statement with more than 120,000 rows across its sections is not generated in any format: an on-demand request for it answers `422` `DALP-200387`, and the refused request writes no statement.

The PDF is rendered inside the platform with no external calls, using the organisation's logo, colours and fonts from [Organisation theme](https://docs.settlemint.com/docs/console/organisation-settings/theme). The PDF footer prints the minute the file was generated, so a PDF rendered at another minute has another digest, even for the same statement and theme.

## Daily contract notes [#daily-contract-notes]

A contract note lists one holder wallet's trades on the organisation's trading venue for one trading day. A trading day runs from the first session open to the last session close of the organisation's venue instruments on that day. The hourly statement pass that follows the last session close writes a note for each holder wallet that traded that day, and each pass reads the three most recent closed trading days. A wallet with no trade that day gets no note. The note is a statement with its own layout, so it appears in the statements list and downloads through the same route as any other statement.

A note comes in CSV and PDF. The CSV has one row per trade with `tradeDate`, `tradeId`, `time`, `instrument`, `side`, `quantity`, `price`, `value`, `feeType`, `fee`, `vat`, `netAmount`, `settlementStatus`, `transaction` and `amended`, then one `total` row per value currency with the total value and the total net amount. A `total` row puts the currency symbol in the `transaction` column. Dates and times are in the instrument's time zone. The PDF is titled "Contract note" with the status "Final".

When a trade on a note changes after the note was written, for example when it settles or is busted, and the trading day is still one of the three the pass reads, the next pass writes the note again under the same statement `id` with the trade's new state. A note with a busted trade reads "Amended contract note" with the status "Amended", and its rows carry `amended` as `yes`. A rewrite whose files differ from the earlier ones emails the holder again. The statements list does not label a statement as a contract note. A note's `periodStart` and `periodEnd` are the first session open and the last session close of its trading day, while a scheduled daily statement runs from midnight to midnight UTC.

## List and download trade confirmations [#list-and-download-trade-confirmations]

Each confirmation covers one final token movement on one of the caller's wallets: a mint, a burn or a transfer, including each leg of a settled venue trade. A movement appears only once its block is at or below the network's final indexed block, so a movement a chain reorganisation can still undo has no confirmation.

```bash
curl "https://your-instance.example.com/api/v2/reporting/confirmations?transactionHash=<transactionHash>" \
  -H "X-Api-Key: <your api key>"
```

The list returns the caller's confirmations, newest first. Each entry carries the confirmation `id`, the `chainId`, the `account`, the `kind`, which is `mint`, `burn` or `transfer`, the `direction`, which is `in`, `out` or `self`, the `counterparty`, the `token`, its `symbol` and `decimals`, the `amount` in base units, the fee lines with VAT, the `blockNumber`, `logIndex`, `transactionHash` and `occurredAt`. `transactionHash` narrows the list to one transaction, such as the one that settled a venue fill, which can hold several movements. To read the next page, pass the `meta.nextCursor` value of the previous page as `page[cursor]`. `GET /api/v2/reporting/confirmations/<confirmationId>` reads one confirmation.

```bash
curl "https://your-instance.example.com/api/v2/reporting/confirmations/<confirmationId>/artifacts?format=xlsx" \
  -H "X-Api-Key: <your api key>" \
  -o confirmation.xlsx
```

`format` is `csv` or `xlsx`, and the response is the file itself. Both carry the confirmation ID, account, chain ID, event type, direction, token, symbol, quantity, amount in base units, fee sides, types, amounts and VAT amounts, decimals, counterparty, UTC timestamp, block, transaction hash and log index. The quantity is the amount scaled by the token's decimals.

Every confirmation read is limited to the caller's own wallets in the request's organisation and network. A confirmation of any other wallet answers `404`, for organisation owners and platform administrators too. In the Console, the "Confirmations" tab of Activity lists the same confirmations with "Download confirmation (CSV)" and "Download confirmation (XLSX)" in each row's menu.


# Issuer shareholder list

Source: https://docs.settlemint.com/docs/api-reference/guides/issuer-shareholder-list
Produce one security's shareholder list at a record block, send it to the issuer, and exchange the register with the Registrar in its own layout.

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

- The security must have the historical-balances feature, attached when the security was created. DALP reads holders from the balance history that feature records. A security without it, a record block before the feature was attached, or a security that already had supply when the feature was attached is rejected with `DALP-0753`, because its balance history is incomplete. [When DALP cannot produce the list](#when-dalp-cannot-produce-the-list) lists the reasons.
- Reading the list, the Registrar file and the deliveries needs the Permission manager, Auditor, Compliance manager or System manager role on the organisation's system, or an organisation owner or a platform administrator. Scheduling a delivery needs an owner of the issuing organisation, or a platform administrator acting in it.
- For the Platform API, use an API key from the organisation that holds the security. Send it as `X-Api-Key`.

## Overview [#overview]

DALP produces an issuer's shareholder list itself: after every trade of an auction cycle is final, at the close of the last trading day of each month for securities that trade continuously, and again after a bust. It stores the list for the issuing organisation and emails the issuer's owners, as [Have the platform deliver the list to the issuer](#have-the-platform-deliver-the-list-to-the-issuer) describes. Each list covers one security at one record block, the chain block whose balances the list reports. Every holder's balance in the list is the on-chain balance after that block.

Use the manual export to read a list on demand, or to produce the month-end list yourself on a deployment that switched the month-end trigger off.

## Choose when to run it [#choose-when-to-run-it]

| Trading model | When the platform runs it | Record block | When you run it |
| --- | --- | --- | --- |
| Auction | After every trade of the auction cycle is final. | The block that holds the cycle's last settlement, or any later block before the next trade of that security. | When the auction trigger does not apply to the security, for example an instrument that is not auction-only. |
| Continuous trading | On the last trading day of the month, after the session closes and the cut-off passes, with the settings in [Month-end lists and defaults](#month-end-lists-and-defaults). | The final block at the cut-off, or the last settled trade block of that session when it is later. | Only when `REPORTING_SHAREHOLDER_LIST_MONTH_END` is `false`. Take the last trading day from the venue calendar, then post the last block of that day. |

The record block must be final. DALP returns an error for a block later than the newest final block, so the balances at the record block do not change after you send the list. A later bust can still supersede the list, as [Corrections](#corrections) describes. Leave the record block out to use the newest final block. The answer names the block it used.

## Export from the Console [#export-from-the-console]

1. Open the security, go to "Holders" and select **Export** in the table toolbar.
2. Select **Holder register…**. The sheet opens at the block entered in "As of" on the Holders tab. For a past date it opens at the last final block at or before that date, and shows both. Otherwise it opens at the newest final block. Choose "Block" to enter another record block.
3. Read the record block and its time, the number of holders, the units held and the total supply. The sheet uses the class-neutral words holder and units because it also lists stablecoins and deposit tokens.
4. Check that **Adds up** shows "Yes".
5. Choose the **Format**, which is CSV by default. The download button names the format, as in "Download CSV", "Download XLSX" or "Download PDF". The file is read at the record block shown in the summary.

**Export** shows the register only to organisation owners, platform administrators, and accounts with the Permission manager, Auditor, Compliance manager or System manager role. Everyone else sees "This table as CSV", which exports the rows and filters on screen.

## Export with the Platform API [#export-with-the-platform-api]

Read the totals first:

```bash
curl "https://your-instance.example.com/api/v2/reporting/shareholder-lists/<tokenAddress>?atBlock=<recordBlock>" \
  -H "X-Api-Key: <your api key>"
```

The answer carries the totals at the record block:

```json
{
  "data": {
    "chainId": 1,
    "tokenAddress": "0x71C7656EC7ab88b098defB751B7401B5f6d8976F",
    "name": "Example Share",
    "symbol": "EXS",
    "decimals": 18,
    "recordBlock": "1200",
    "finalBlock": "1240",
    "recordedAt": "2026-09-30T23:59:48.000Z",
    "balancesSince": "2026-01-15T09:30:00.000Z",
    "holderCount": 12,
    "sharesHeld": "1000",
    "totalSupply": "1000",
    "reconciled": true,
    "ownershipBasis": "on-chain-register",
    "formats": ["csv", "xlsx", "pdf"]
  },
  "links": {
    "self": "/api/v2/reporting/shareholder-lists/0x71C7656EC7ab88b098defB751B7401B5f6d8976F?atBlock=1200"
  }
}
```

`data.reconciled` is `true` when the holders' balances add up to `data.totalSupply`. `data.recordBlock` is the block the list is read at, and `data.finalBlock` is the newest final block. `data.holderCount` counts the holders, and `data.sharesHeld` is the units they hold. A refused read answers `DALP-0753`, with the reasons in [When DALP cannot produce the list](#when-dalp-cannot-produce-the-list).

Then download the file at that same block. `format` is `csv`, `xlsx` or `pdf`:

```bash
curl "https://your-instance.example.com/api/v2/reporting/shareholder-lists/<tokenAddress>/download?atBlock=<recordBlock>&format=csv" \
  -H "X-Api-Key: <your api key>" \
  -o shareholder-list.csv
```

To read a list as of a date, first resolve the date to a block. The call answers with the last final block whose time is at or before the time you give, on the network of the request. A time after the newest final block gives the newest final block. A time before the network's first block gives `recordBlock: null`.

```bash
curl "https://your-instance.example.com/api/v2/reporting/record-blocks?at=2026-09-30T23:59:59Z" \
  -H "X-Api-Key: <your api key>"
```

```json
{
  "data": {
    "chainId": 1,
    "at": "2026-09-30T23:59:59.000Z",
    "recordBlock": "1200",
    "recordedAt": "2026-09-30T23:59:48.000Z",
    "finalBlock": "1240"
  },
  "links": {
    "self": "/api/v2/reporting/record-blocks?at=2026-09-30T23%3A59%3A59.000Z"
  }
}
```

The answer carries `recordBlock`, `recordedAt`, which is the time of that block, `finalBlock` and `chainId`. Pass `recordBlock` as `atBlock` on the totals and download calls.

Pass `atBlock` on the download even when you left it out of the first request. The newest final block moves as the chain grows, and a fixed block keeps the file equal to the totals you checked.

## Check the list before you send it [#check-the-list-before-you-send-it]

- **Adds up** must be "Yes", or `reconciled` must be `true`. A "No" means the holders' units do not add up to total supply at the record block, so the list is incomplete or the balance history has not caught up. Do not send it. Read the list again later, and contact support with the security and the record block if it still shows "No".
- The number of holders should match the investors you expect after the auction or month.

## Send the list [#send-the-list]

Deliver the CSV or XLSX file through the channel agreed with the issuer, with the PDF as the record of what was sent. Keep the security address and the record block with the sent file, so that the same list can be produced again.

## Exchange the register with the Registrar [#exchange-the-register-with-the-registrar]

The Registrar is the issuer's registrar or transfer agent, the party outside DALP that keeps the issuer's register of members. DALP writes the holders in the Registrar's layout and compares the Registrar's own file with the chain. Both steps run on the "Registrar file" tab of the Console's export sheet or through the Platform API, and both read one record block.

**Export** shows the Registrar file only to organisation owners, platform administrators, and accounts with the Permission manager, Auditor, Compliance manager or System manager role. Every other account sees only "This table as CSV" in the menu.

### Export the Registrar file from the Console [#export-the-registrar-file-from-the-console]

1. Open the security, go to "Holders", and select "Export" › **Registrar file…**. The sheet "Export holder register" opens on its "Registrar file" tab.
2. Set the record block on the **Register** tab, where "As of" offers "Newest final block", "Block" with a block number field, and "Date". The Registrar file tab exports the block the register was read at. Both buttons on the Registrar file tab stay unavailable until the register answers for a block.
3. Return to the "Registrar file" tab and select **Export registrar file**. The browser saves `registrar-file-<symbol>-<block>.csv`.

The file has the columns `holderWallet`, `identityReference`, `jurisdiction` and `quantity`, one row per wallet holding a balance, sorted by wallet. The holder is identified by wallet address, and `quantity` is in the security's own units, for example `250.5` for a security with two decimals.

### Export the Registrar file with the Platform API [#export-the-registrar-file-with-the-platform-api]

Download it at a fixed block:

```bash
curl "https://your-instance.example.com/api/v2/reporting/shareholder-lists/<tokenAddress>/registrar-file?atBlock=<recordBlock>" \
  -H "X-Api-Key: <your api key>" \
  -o registrar-file.csv
```

Leave `atBlock` out to read the newest final block. Pass it to keep the file equal to the register you checked, because the newest final block moves as the chain grows.

### Reconcile a Registrar file from the Console [#reconcile-a-registrar-file-from-the-console]

1. Set the record block on the "Register" tab the same way, then open **Registrar file**.
2. Select **Reconcile registrar file** and choose the Registrar's CSV file.
3. Read the answer. The badge reads "Matches the chain at block" or "Does not match the chain at block" with the block, and beneath it the count of each result and the totals "Registrar file total", "On-chain total" and "Total supply" in the security's units.
4. The table under the summary lists every wallet that did not match, with the result, the quantity the file lists and the quantity on chain. A matched wallet opens no row.

An organisation owner or a platform administrator also writes each difference to the custody reconciliation break register. Any other reader gets the same comparison and records nothing.

When the file cannot be read, the alert "The registrar file could not be read" names the problem and the line, and nothing is compared.

### Reconcile a Registrar file with the Platform API [#reconcile-a-registrar-file-with-the-platform-api]

Send the Registrar's file back to compare it with the chain at a block. The `fileData` field is the CSV text, with a header row that names at least `holderWallet` and `quantity`:

```bash
curl -X POST "https://your-instance.example.com/api/v2/reporting/shareholder-lists/<tokenAddress>/registrar-reconciliations" \
  -H "X-Api-Key: <your api key>" \
  -H "Content-Type: application/json" \
  -d '{"atBlock": "<recordBlock>", "fileData": "holderWallet,quantity\n0x1111111111111111111111111111111111111111,600\n"}'
```

When the file is read, `data._tag` is `Reconciled` and every wallet has an `outcome`:

| `outcome` | Console result | What it means |
| --- | --- | --- |
| `matched` | No row | The file and the chain list the same quantity for the wallet. |
| `quantity-mismatch` | Different quantity | Both list the wallet, with different quantities. |
| `missing-on-chain` | Missing on chain | The file lists the wallet, but it holds nothing at the record block. |
| `missing-in-register` | Missing in the file | The wallet holds a balance on chain, but the file does not list it. |

`data.reconciled` is `true` only when every row matched and the file total and the on-chain total both equal `data.totalSupply`.

When the file cannot be read, `data._tag` is `Rejected`, nothing is compared, and `data.refusal` names the problem (`empty-file`, `unterminated-quote`, `malformed-quote`, `missing-column`, `invalid-wallet`, `invalid-quantity` or `duplicate-wallet`) with `data.line` and `data.value`. Fix the file and send it again.

## Look through nominee wallets to their beneficial owners [#look-through-nominee-wallets-to-their-beneficial-owners]

A nominee, custodian or broker can hold a security in one wallet for many beneficial owners. On chain that wallet is one holder. The nominee declares the owners behind the wallet, and readers of the shareholder list can then read the register looked through to those owners. Deliveries, the Registrar file and dividend payouts keep counting the on-chain register. A dividend read can still report each owner's share of the nominee's payout.

### Declare and read them in the Console [#declare-and-read-them-in-the-console]

1. Open the security, go to "Holders" and select "Export" › **Beneficial owners…**. The sheet "Export holder register" opens on its "Beneficial owners" tab. Set the record block on the "Register" tab first: the tab declares and reads at that block, and "File declaration" stays unavailable until the register answers for a block.
2. Under "Declare beneficial owners", enter the "Nominee wallet", select "Choose CSV file" and pick a file with the columns that [Declare the owners behind a wallet](#declare-the-owners-behind-a-wallet) lists. Select **File declaration**.
3. A filed declaration shows **Declaration filed at block** with the nominee wallet, the owners and units declared, and whether the identities were stored encrypted or were not in the file. A refused one shows "The declaration was not filed" with the reason, the line and the column of the problem. Nothing is stored. A wallet that is not an address is refused before anything is sent.
4. Under **Register by beneficial owner**, read the register at the record block: whether it adds up to the total supply, the number of entries, the wallets looked through and the stale wallets. The table has one row per direct holder, declared owner or stale wallet, and "Holding" filters to one kind. The identity columns ("Legal name", "ID type", "ID number", "Investor category") show only when the register returned them. A stale wallet shows "Stale" on a highlighted row, listed whole, with a notice that a new declaration at a later block looks through it again.
5. Select **Export** in the table toolbar to download the rows on screen as CSV, including the identity columns when they are shown.

The Console reads the register only while the "Beneficial owners" tab is open, because every read is recorded in the audit trail. A member files a declaration for a wallet it holds. The organisation owner or a platform administrator can file for any wallet.

### Declare the owners behind a wallet [#declare-the-owners-behind-a-wallet]

The nominee sends one declaration per security and wallet, for one block. `fileData` is CSV text with the header `ownerReference,jurisdiction,quantity`:

- `ownerReference` is the nominee's own reference for the owner: 1 to 64 printable characters without spaces, unique in the file.
- `jurisdiction` is the owner's ISO 3166-1 alpha-2 country, such as `AE`.
- `quantity` is the units held for the owner, in the security's own units, above zero.

Four optional columns add each owner's identity. Leave them all out and the declaration is exactly `ownerReference`, `jurisdiction` and `quantity`. If the header has any of them it must have `legalName`, and then every row needs a `legalName`:

- `legalName` is the owner's legal name, at most 200 characters, with no control characters.
- `idType` is one of `passport`, `national_id`, `drivers_license`, `tax_id`, `company_registration` or `lei`. Leave it empty for a row without an ID. A row with an `idType` needs an `idNumber`, and the other way round.
- `idNumber` is the number or registration code, 1 to 64 printable characters without spaces.
- `investorCategory` is one of `retail`, `professional`, `institutional` or `eligible_counterparty`, or empty.

```bash
curl -X POST "https://your-instance.example.com/api/v2/reporting/shareholder-lists/<tokenAddress>/beneficial-owner-declarations" \
  -H "X-Api-Key: <your api key>" \
  -H "Content-Type: application/json" \
  -d '{"nomineeWallet": "<wallet>", "atBlock": "<block>", "fileData": "ownerReference,jurisdiction,quantity\nC-1,AE,600\nC-2,SA,400\n"}'
```

Leave `atBlock` out to declare at the newest final block. A file holds at most 5000 owners.

A member of the organisation declares for a wallet it holds. The organisation owner or a platform administrator can declare for any wallet, for example from a file the nominee sent. Any other caller is answered as not found.

The declaration is stored only when its quantities add up to the wallet's balance at the block. Then `data._tag` is `Declared`, with the declaration's `id`, `asOfBlock`, `ownerCount` and `total`. Otherwise `data._tag` is `Rejected`, nothing is stored, and `data.refusal` names the problem:

| `refusal` | What it means |
| --- | --- |
| `total-mismatch` | The owners do not add up to the wallet's balance. `data.declaredTotal` and `data.onChainBalance` give both. |
| `already-declared` | A different declaration for this wallet at this block is stored. Declare the correction at a later block. |
| `empty-file`, `too-many-lines`, `unterminated-quote`, `malformed-quote`, `missing-column` | The file cannot be read as a declaration. For `missing-column`, `data.column` names the column. |
| `invalid-owner-reference`, `invalid-jurisdiction`, `invalid-quantity`, `duplicate-owner-reference` | A row is wrong. `data.line` and `data.value` point at it. |
| `invalid-legal-name`, `invalid-id-type`, `missing-id-type`, `missing-id-number`, `invalid-id-number`, `invalid-investor-category` | An identity cell is wrong. `data.line`, `data.value` and `data.column` point at it. |

Declarations are never changed. Sending the same file for the same wallet and block again answers with the stored declaration. A file that differs only in its identity columns counts as a different declaration.

### How the identities are kept [#how-the-identities-are-kept]

The identity columns are sealed with envelope encryption in the platform database, as one envelope per declaration. They never go on chain, into email, webhooks or indexer data. The declaration's answer does not repeat them: `data.withIdentities` says whether the file carried them. The owner reference, country and units stay readable as before.

Only reporting readers can read the identities back, through the [looked-through register](#read-the-looked-through-register): the organisation owner, holders of the Permission manager, Auditor, Compliance manager or System manager role, and a platform administrator, who runs the platform and reaches every organisation. A member who only files for its own wallet cannot read the identities back, and every read is recorded in the audit trail.

### Read the looked-through register [#read-the-looked-through-register]

```bash
curl "https://your-instance.example.com/api/v2/reporting/shareholder-lists/<tokenAddress>/beneficial-owners?atBlock=<recordBlock>" \
  -H "X-Api-Key: <your api key>"
```

Reading needs the same access as the shareholder list, and every read is recorded in the audit trail. Each row has a `basis`:

| `basis` | What the row is |
| --- | --- |
| `direct` | A wallet with no declaration at or before the block, at its whole balance. |
| `declared` | One owner of a wallet whose newest declaration at or before the block still adds up to its balance, with its reference and country. |
| `stale` | A wallet whose newest declaration no longer adds up to its balance, at its whole balance. Ask the nominee for a new declaration. |

A `declared` row also carries `legalName`, `idType`, `idNumber` and `investorCategory` when its declaration had identity columns. They are `null` on `direct` and `stale` rows, on declarations filed without identities, and for an `idType`, `idNumber` or `investorCategory` the file left empty.

`data.reconciled` is `true` when the rows add up to `data.totalSupply`. `data.ownerCount` counts the rows, so two nominees' owners count separately even when they are the same person. `data.lookedThroughWallets` and `data.staleWallets` count the wallets split into owners and the wallets left whole as stale.

### Read a dividend's entitlements per beneficial owner [#read-a-dividends-entitlements-per-beneficial-owner]

To see what each declared owner of a nominee wallet is due from a dividend, name the dividend instead of a block:

```bash
curl "https://your-instance.example.com/api/v2/reporting/shareholder-lists/<tokenAddress>/beneficial-owners?dividendId=<dividendId>" \
  -H "X-Api-Key: <your api key>"
```

The register is read at the dividend's record block, so `atBlock` is not accepted together with `dividendId`. The dividend must have its record-date snapshot computed. Otherwise the call answers not found, with the resource `dividend`. A dividend of another security answers the same way.

Each row gains `entitlement`, in the payout asset's own units (`data.dividend.payoutAsset` and `data.dividend.payoutDecimals`):

- A `declared` row holds the owner's share. It applies the dividend's own per-unit rule, `units × amountPerShare ÷ one whole unit` rounded down, to the owner's units from the declaration.
- A `direct` or `stale` row holds the wallet's own entitlement, exactly what the dividend pays that wallet.

`data.dividend.nominees` lists each wallet that was split. Its `entitlement` is the one amount the dividend pays the wallet on chain, `allocated` is the owners' shares added up, and `unallocated` is the rounding remainder. The owners' shares plus `unallocated` always equal `entitlement`, to the unit. A wallet with a stale or no declaration is not split and not listed. When the dividend pays the wallet less than the owners' shares add up to, as for units the issuer's treasury holds, no owner gets a share and the whole amount is `unallocated`.

This is a report only. The nominee is still paid on chain as one entitlement and claims it once. The dividend's Merkle root, its approval fingerprint and its payout do not change, and nothing is claimed per owner. Without `dividendId`, `entitlement` and `data.dividend` are `null`.

## Have the platform deliver the list to the issuer [#have-the-platform-deliver-the-list-to-the-issuer]

With the triggers on, skip the export and the handoff. The platform produces the list itself, stores the CSV, XLSX and PDF editions, and mails the issuing organisation that the list arrived. Each delivery is bound to one record block.

### What starts a delivery [#what-starts-a-delivery]

Four triggers create a delivery:

- `auction-settled`: the platform opens it once every auction trade of the security has settled, no fill is still waiting to settle, and no settled trade still waits for delivery, at the highest settled fill block or later delivery block. This covers auction-only instruments, including those with a holding period.
- `month-end`: the platform opens it for each continuous-book security after the last trading day of a month closes. The delivery records that trading day. [Month-end lists and defaults](#month-end-lists-and-defaults) lists the settings.
- `correction`: the platform opens it after a bust reverses a settled trade that a delivered list counted. See Corrections.
- `scheduled`: you open it when you post a record block through the Console or the Platform API.

A delivery stays `pending` until its record block is final. A scheduled pass produces each delivery whose block is final. One record block holds one delivery: posting a block that already has one returns that delivery, whichever trigger created it. A delivery whose holders' balances do not add up to total supply also stays `pending`: the pass records an attempt and a last error, writes no files, sends no mail, and writes no outcome audit until the projection reconciles.

### Month-end lists and defaults [#month-end-lists-and-defaults]

A continuous-book security gets its month-end list without any action from you. The platform finds the last trading day of the month, waits for the cut-off, and opens a delivery at the record block. A month stays eligible for 35 days plus the cut-off grace period, so a month missed during a platform outage is still delivered when the platform recovers. After that window the platform opens no month-end delivery for the month. Post its record block yourself, as [Schedule with the Platform API](#schedule-with-the-platform-api) describes. A month that already has a delivery opens no second one.

The last trading day is the last `session` occurrence in the instrument's local calendar month. Collection windows do not count. The cut-off is the session close plus a grace period. The platform opens the delivery only when the session is closed, no trade is waiting to settle, and no fill is queued.

| Setting | Default | Config |
| --- | --- | --- |
| Month-end list | On | `REPORTING_SHAREHOLDER_LIST_MONTH_END` |
| Last trading day | The last session in the instrument's local month, with collection windows excluded | None |
| Cut-off | The session close plus 10 minutes | `REPORTING_SHAREHOLDER_LIST_MONTH_END_GRACE` |
| Timezone | The instrument's or venue's calendar timezone, else `Asia/Dubai` | `REPORTING_SHAREHOLDER_LIST_FALLBACK_TIMEZONE` |
| Correction after a bust | On, automatic | `REPORTING_SHAREHOLDER_LIST_CORRECTIONS` |
| Correction lookback | 7 days | `REPORTING_SHAREHOLDER_LIST_CORRECTION_LOOKBACK` |
| Ownership basis | On-chain register | None |

Set a boolean setting to `false` to switch the trigger off. The auction trigger has no setting and is always on. The grace period and the lookback take durations. The timezone takes an IANA name such as `Asia/Dubai`. When you switch the month-end trigger off, run it by hand as the Choose when to run it table describes. Corrections have no manual equivalent.

### Corrections [#corrections]

A bust can reverse a trade that an earlier list counted. When it does, the platform opens a correction delivery on its own. You do not post it.

- The correction supersedes the newest delivered list that counted the trade. It is recorded at the latest final block and carries the reason `bust`.
- Only a bust inside the lookback window is considered, and only a trade settled at or before the list's record block and busted after it. The correction waits until the final block is newer than the bust.
- The earlier edition stays downloadable. Its row shows **Superseded** and names the list that replaces it. The correction row shows "Correction", "Reason: trade bust", and the block it replaces.
- In the API, `supersedesId` on the correction and `supersededById` on the earlier list point at each other. `correctionReason` is `bust`.
- A newer bust against a correction supersedes that correction in turn. One correction exists per superseded list.
- The issuer's owners get the usual delivery email. It names the corrected record block and the reason, and carries no holder data.

When `REPORTING_SHAREHOLDER_LIST_CORRECTIONS` is `false`, the platform opens no correction, and no manual step creates one. A list you schedule is an ordinary `scheduled` list: it does not carry the `correction` trigger or the reason `bust`, and it does not mark the earlier list as superseded. If you still want the issuer to have a list after a bust, schedule one at the newest final block that is later than the bust, and tell the issuer which list replaces which.

### Ownership basis [#ownership-basis]

The list is the on-chain register: every wallet that holds the security at the record block. Each delivery is stamped with `ownershipBasis` `on-chain-register`, and the PDF prints it under the record block. The summary of an on-demand read carries the same field. A custodian's shared wallet appears as one holder under the custodian's wallet. The list does not look through to the custodian's investors, so the issuer needs the custodian's own records for those.

### Schedule from the Console [#schedule-from-the-console]

1. Open the security, go to "Holders" and select "Export" › **Holder register…**.
2. Choose **Block** and enter the record block, or keep the newest final block.
3. Select **Deliver to issuer**. The sheet moves to "Deliveries".

"Export" › **Issuer deliveries…** opens the same tab. The table shows each delivery with its record block, trigger, status, delivered time, holder count and downloads. The trigger reads "After auction", "Requested", "Month end" or "Correction". "Requested" is a list an operator asked for by hand, which the API calls the `scheduled` trigger. A `pending` row reads "Waiting" and refreshes while the pass produces it. A `delivered` row offers one download per format. A `refused` row names the reason.

### Schedule with the Platform API [#schedule-with-the-platform-api]

Post the record block as a string:

```bash
curl -X POST "https://your-instance.example.com/api/v2/reporting/shareholder-lists/<tokenAddress>/deliveries" \
  -H "X-Api-Key: <your api key>" \
  -H "Content-Type: application/json" \
  -d '{"recordBlock": "1200"}'
```

The platform answers with the delivery. A block past the newest final block stays `pending` until the block is final.

A security your organisation does not hold answers `404` with code `reporting.register.SHAREHOLDER_LIST_NOT_FOUND`. That answer covers a missing security, a security of another organisation, and a security with no resolvable issuer. Your organisation learns nothing about other organisations from it.

### List deliveries [#list-deliveries]

```bash
curl "https://your-instance.example.com/api/v2/reporting/shareholder-lists/<tokenAddress>/deliveries?offset=0&limit=50" \
  -H "X-Api-Key: <your api key>"
```

The newest record block comes first. `limit` takes 1 to 200 and defaults to 50, and a larger value is refused as invalid. `meta.total` counts every delivery of the security in your organisation, `meta.canSchedule` says whether you may schedule one, and `links` pages through the list:

```json
{
  "data": [
    {
      "id": "0199b2d1-8a19-7a08-8d21-4d33e3c1a111",
      "chainId": 1,
      "tokenAddress": "0x0000000000000000000000000000000000000001",
      "recordBlock": "900",
      "trigger": "auction-settled",
      "ownershipBasis": "on-chain-register",
      "supersedesId": null,
      "supersededById": null,
      "tradingDay": null,
      "correctionReason": null,
      "status": "delivered",
      "requestedBy": null,
      "attempts": 1,
      "lastError": null,
      "createdAt": "2026-10-10T08:05:00.000Z",
      "settledAt": "2026-10-10T08:10:00.000Z",
      "holderCount": 12,
      "refusal": null,
      "notice": "sent",
      "noticeAttempts": 1,
      "parts": {
        "csv": {
          "objectKey": "shareholder-lists/org_a/0199b2d1-8a19-7a08-8d21-4d33e3c1a111.csv",
          "digest": "9f2c4a7e1b5d83f06a2c9e4b7d105f3a8c6e2d4b9f105a3c7d2e6b8a1f4c5d6",
          "contentLength": 1840
        },
        "xlsx": {
          "objectKey": "shareholder-lists/org_a/0199b2d1-8a19-7a08-8d21-4d33e3c1a111.xlsx",
          "digest": "41bd9c0e77f2a5d18c3e6b0a4f9d2c7e5b8a1f306d4c5e9b8a7f1c2d3e4a5b6c",
          "contentLength": 6231
        },
        "pdf": {
          "objectKey": "shareholder-lists/org_a/0199b2d1-8a19-7a08-8d21-4d33e3c1a111.pdf",
          "digest": "c7e30bd4a19f6c2d5e8b40a173f5c9d6e2b80417f6a3c5e9d0b2f486a1c7d3e5",
          "contentLength": 12904
        }
      }
    }
  ],
  "meta": { "total": 1, "canSchedule": true },
  "links": {
    "self": "/api/v2/reporting/shareholder-lists/0x0000000000000000000000000000000000000001/deliveries?offset=0&limit=50",
    "first": "/api/v2/reporting/shareholder-lists/0x0000000000000000000000000000000000000001/deliveries?offset=0&limit=50",
    "prev": null,
    "next": null,
    "last": "/api/v2/reporting/shareholder-lists/0x0000000000000000000000000000000000000001/deliveries?offset=0&limit=50"
  }
}
```

### Download a stored edition [#download-a-stored-edition]

```bash
curl "https://your-instance.example.com/api/v2/reporting/shareholder-lists/<tokenAddress>/deliveries/<deliveryId>/download?format=csv" \
  -H "X-Api-Key: <your api key>" \
  -o shareholder-list-900.csv
```

`format` is required: `csv`, `xlsx` or `pdf`. The platform returns the stored bytes. A download of a `pending` delivery answers `503`, as does a file whose bytes no longer match the recorded digest or length. A `refused` delivery never becomes available: a `security-not-found` or `not-issuer` refusal answers `404`, a feature or history refusal answers `422` with code `reporting.register.SHAREHOLDER_LIST_REFUSED`, a `file-unwritable` refusal answers `500` with code `reporting.artifact.UNWRITABLE` (`DALP-14085`), a `storage-refused` refusal answers `500` with code `reporting.dependency.REFUSED` (`DALP-14088`), and a `chain-read-invalid` refusal answers `500` with code `core.network.CHAIN_READ_INVALID` (`DALP-14108`). None of these `500` answers is retryable. A delivery of another organisation answers `404`.

### How the issuer learns that the list arrived [#how-the-issuer-learns-that-the-list-arrived]

The platform emails every owner of the issuing organisation when a delivery is delivered or refused. The mail names the security, the record block and the trigger, states the reason when refused, and links to the security page in the Console. It carries no holder data.

A notice that fails to send retries on later passes after a backoff, up to three attempts, then stays `failed`. The wait is 10 minutes after the first failure and 20 minutes after the second. A retry only emails the owners who have not received that notice. Recipients who already received it are not emailed again. When mail is not configured, the notice stays `not-configured`. If the platform crashes after the mail transport accepts a notice but before that acceptance is recorded, the next pass may email that recipient again, so a recipient can receive the same notice twice.

### Audit and retry [#audit-and-retry]

Each delivered delivery, refused delivery, sent notice and failed notice writes an operations audit row for the issuing organisation. You read those rows through the reporting audit trail. The audit trail also records who made the schedule call and each download.

A short-lived failure leaves the delivery `pending` with an attempt count and a last error, and a later pass retries it after a backoff. The wait starts at 5 minutes and doubles with each attempt, up to 24 hours. An unreconciled list waits the same way: it stays `pending` with an attempt and a last error, and a later pass delivers it once the holders add up to total supply. A failure that gives the same result on every attempt does not wait: a list that cannot be written in one of its formats is refused as `file-unwritable` on the first attempt. A `refused` delivery is terminal and never retries.

A delivery whose stored record is damaged is skipped and counted, and the pass carries on with the other deliveries. The damaged delivery is neither produced nor emailed, and a read that needs it answers temporarily unavailable rather than returning partial data. An audit event whose stored record is damaged is skipped the same way and is missing from the reporting audit trail, while the delivery's other audit events are still recorded. Contact support with the security and the record block.

### When a delivery is refused [#when-a-delivery-is-refused]

| `refusal` | What it means | What to do |
| --- | --- | --- |
| `feature-not-attached` | The security had no historical-balances feature at the record block. | See the matching row under the on-demand refusals. |
| `feature-detached` | The historical-balances feature was detached at or before the record block. | Choose a record block before the detachment block. |
| `enablement-after-record-block` | The feature was attached after the record block. | Choose a record block at or after the attachment block. |
| `history-incomplete` | The security had supply before the feature was attached. | No record block can be delivered. |
| `security-not-found` | The security was missing at the record block. | Check the address and the block. |
| `not-issuer` | The organisation no longer issues the security. | No block can be delivered to it. |
| `file-unwritable` | One of the files could not be written, for example because the holders exceed what one XLSX worksheet holds. | Download the list on demand in another format, such as CSV, or contact support. |
| `storage-refused` | File storage refused the edition's files, so they were never stored. | Contact support, then schedule a new delivery. |
| `chain-read-invalid` | The chain reverted or answered unusable data when the record block's time was read. | Contact support with the security and the record block. |

A block past the newest final block never refuses a delivery, and neither does an unreconciled list. Both wait as `pending`: the delivery for a block past the newest final block until that block is final, and the delivery for an unreconciled list until the projection reconciles.

### Systems that organisations share [#systems-that-organisations-share]

The platform names the issuing organisation from the system the security lives in. When one organisation holds the system, that organisation is the issuer. When organisations share the system, the recorded issuer is the issuer only while it still holds the system. A missing recorded issuer, or one that no longer holds the system, names no issuer: the security gets no auction delivery, and scheduling answers not found.

## What the file contains [#what-the-file-contains]

The CSV and XLSX files have one row per wallet that holds the security after the record block, largest holding first. A wallet with a zero balance is left out. The PDF shows the same holders with the network and its chain ID, the record block and its time, and the reconciliation result. Its holders table ends with a totals row: the number of holders, the units they hold, and the share of supply those units are.

Where the chain records a field, the column maps to its field in the shareholder response of Commission Implementing Regulation (EU) 2018/1212, Annex Table 2, and to its entry in the register of members under section 118 of the ADGM Companies Regulations 2020. The file alone is not a complete shareholder response or register of members: it carries the contract address in place of an ISIN and no names or addresses, which the issuer completes from its own records.

| Column | Content | Table 2 field | Section 118 entry |
| --- | --- | --- | --- |
| `security` | The security's contract address, in place of an ISIN. | A.4 | Shares held, by class |
| `symbol` | The security's symbol. |  |  |
| `recordDate` | The date of the record block, as `YYYYMMDD` in UTC. | A.5 |  |
| `recordBlock` | The record block. |  |  |
| `account` | The holder's wallet, the account the shares are held in. | B.7 |  |
| `identity` | The holder's registered OnchainID identity. Empty when the wallet has no registered identity. | C.1 | Member |
| `country` | The holder's registered country as an ISO 3166-1 alpha-2 code. | C.6 |  |
| `shares` | The holder's balance in the security's own units. | C.11 | Shares held |
| `percentOfSupply` | The holder's share of total supply, cut to four decimal places and not rounded, so the column never adds up to more than 100. |  |  |

In the XLSX file, `recordDate` and `percentOfSupply` are numbers. `recordBlock` is a number when it fits spreadsheet precision exactly, and text otherwise, so the block identifier cannot change. `shares` is a number only when every holder's balance and their sum fit a spreadsheet number exactly, which is 15 significant digits. Otherwise the whole column is text, so that no amount is rounded. A spreadsheet total of a text column is 0, so check the column type before you add it up. The CSV file holds text in every column.

The file does not hold names or postal addresses. The issuer matches each identity to the member's name and address in its own records.

## When DALP cannot produce the list [#when-dalp-cannot-produce-the-list]

A refused list returns `DALP-0753` with a reason in `data.reason`:

| `data.reason` | What it means | What to do |
| --- | --- | --- |
| `feature-not-attached` | The security had no historical-balances feature at the record block, so there is no balance history to list. | No past block can be listed for a security created without the feature. The Console attaches the feature only when it creates a security. A feature attached later through the Platform API does not help a security that already had supply, because its listing is then refused with `history-incomplete`. Issue new securities with the feature. For a security whose feature was detached, choose a record block from before the detachment. |
| `feature-detached` | The feature was detached at `data.boundaryBlock`. The record block is at or after it. | Choose a record block before `data.boundaryBlock`. |
| `enablement-after-record-block` | The feature was attached after the record block. `data.boundaryBlock` is the block it was attached at. | Choose a record block at or after `data.boundaryBlock`. |
| `history-incomplete` | The security had supply before the feature was attached, so the balance history is incomplete. `data.boundaryBlock` is the block the feature was attached at. | No record block can be listed. |
| `record-block-not-final` | The record block is later than the newest final block, `data.boundaryBlock`. | Wait until the block is final, or leave the record block out. |


# Onboard an investor

Source: https://docs.settlemint.com/docs/api-reference/guides/onboard-an-investor
Onboard and verify an investor end to end: participant and wallet, identity registration, KYC review and the claim, then the same steps through the API.

## Overview [#overview]

Onboarding an investor through the API prepares them to hold a regulated token, in a sequence of calls: create the user, resolve the wallet that carries the identity, register the identity under a country, and verify the investor with a know-your-customer provider such as Sumsub. Each write needs a role. A write sent from a signed-in session also carries `walletVerification`, the step-up proof such as a PIN code, when the caller's wallet is protected by a code. A write sent with an API key needs no proof, because creating the key took one, so anyone who holds the key can sign as its holder until the key is disabled or expires. To create many participants at once, [Bulk participant import](https://docs.settlemint.com/docs/concepts/compliance-and-identity/participant-import) takes up to 500 rows in one background batch and opens a registration request for each row that passes, which an identity manager then accepts.

The sequence covers a participant created on a managed custody provider configuration, where the platform holds the key and signs on the participant's behalf. A bring-your-own-key configuration leaves the participant pending with a null `custodyAccountId` and a null `identity` until its owner proves the key at first sign-in, as [From first sign-in to a verified holder](#from-first-sign-in-to-a-verified-holder) describes. [Let an investor choose custody](https://docs.settlemint.com/docs/api-reference/guides/choose-investor-custody) covers the investor who picks between a managed account and their own wallet after sign-up. [Custody Provider](https://docs.settlemint.com/docs/concepts/custody-and-signing/custody-provider) describes both kinds and how a configuration is chosen.

Creating a user deploys an identity contract for a managed participant, but it never registers it. Registration is a separate on-chain write, and a token reads the registration before it lets the wallet hold value, so a deployed but unregistered identity is not enough. An on-chain identity is the ledger record a regulated token checks. A token's compliance rules cannot check a wallet that has none, so the token refuses that wallet.

## From first sign-in to a verified holder [#from-first-sign-in-to-a-verified-holder]

An investor can hold a regulated token once four things are true:

1. They have a participant, the platform's record for one compliance subject, with a wallet the organisation can act through.
2. That wallet has an on-chain identity, the contract that holds the investor's claims.
3. The identity is registered in the organisation's identity registry under a country.
4. The identity carries every verification, or claim, that the token's compliance rules require, added by an issuer the token trusts.

The KYC profile review comes before the fourth condition, the claims. It is the organisation's own record of who the investor is, and it decides whether an issuer adds the KYC claim. Six stages follow an investor through the Console and the Investor portal, and the numbered steps from [Step 1](#step-1-create-the-user) run the same work through the Platform API.

**Stage 1. The person gets a participant and a wallet.** There are two ways in.

- An identity manager creates the user. In the Console this is "Create or invite user" with "Send invitation email" off, described on [Users](https://docs.settlemint.com/docs/console/participants/users). Through the API it is [Step 1](#step-1-create-the-user). The platform creates the login, a person participant, a wallet on the organisation's managed custody provider, and the identity contract, in one request. An API request names the provider configuration it uses.
- The organisation owner invites the person by email, and the investor sets up their own wallet. After sign-in, the [Investor portal](https://docs.settlemint.com/docs/concepts/operating/investor-portal) opens the "Wallet setup" wizard until the participant the investor acts as is one the organisation can act through and holds a wallet the organisation can act through. For an embedded or browser wallet, the wizard also stays open until that wallet has its identity contract and, in an organisation that uses smart wallets, its smart wallet.

In the "Wallet setup" wizard, the portal decides what the investor sees in this order:

1. A participant that still waits for its key proof comes first, when the organisation offers an embedded or browser wallet to prove it with. The portal returns the investor to "Connect and sign" for that same participant.
2. When the investor owns a participant the organisation can act through, the portal asks them to pick it. Picking it needs no wallet verification.
3. Otherwise, when the organisation offers investors more than one custody provider, the investor picks one on "Wallet type": "Embedded wallet", "Browser wallet" or "Managed account".
4. On "Your wallet", "Create wallet" makes a managed account that the organisation holds. "Connect and sign", for an embedded or browser wallet, signs a message that proves the investor controls the key. Each create or connect asks for the investor's wallet verification first. A managed account gets its identity contract in the same step.
5. Until the proof succeeds, the participant is pending and cannot act in any organisation. A declined signature leaves it pending and the investor can sign again. A pending participant not proven within 30 days stops appearing.
6. For an embedded or browser wallet, the portal creates the identity contract once the key is proven, and the investor's wallet signs the identity factory's authorisation for it. When the investor's wallet verification is a one-time code that creating the participant already used, the portal asks for a new one. In an organisation that uses smart wallets, the portal then deploys the smart wallet, and the investor's wallet signs the account factory's authorisation for it.

The portal says "This organisation has not chosen an investor wallet yet" when the investor owns no participant to reuse and the organisation offers no wallet they can use: no provider at all, or, for a participant waiting for its key proof, no embedded or browser wallet. An administrator designates one in [Custody](https://docs.settlemint.com/docs/console/organisation-settings/custody).

**Stage 2. An identity manager registers the identity.** A new identity has no registration, so the user's page reads "Identity registration: pending". The identity manager registers it under a country from the user's page with "Register identity", from [Entities](https://docs.settlemint.com/docs/console/participants/entities) with "Register existing identity" or by accepting a registration request, or through the API in [Step 3](#step-3-register-the-identity). Registration covers every active wallet of the participant on the network. Country allow and block lists read the country it records.

**Stage 3. The investor completes the KYC profile.** The investor opens Profile in the Investor portal, fills in first name, last name, country, national ID and the fields the organisation's [profile sections](https://docs.settlemint.com/docs/console/participants/profile-sections) add, uploads supporting documents of up to 25 MiB each, and selects "Submit for review". Each save adds a version, and each organisation keeps its own profile for the investor.

**Stage 4. A reviewer decides the profile.** An identity manager or verification issuer opens the user's "KYC" tab in the Console and selects "Approve", "Reject" or "Request update". The person who submitted a version cannot decide it, and neither can an identity manager who corrected one of its fields, so the review is maker-checker: a correction waits for a different reviewer. A platform administrator who submitted or corrected the version while acting as the investor cannot decide it either. When the platform sends mail and the investor has an email address, the investor receives the outcome by email. A requested update shows as an action in the Investor portal. [Users](https://docs.settlemint.com/docs/console/participants/users#review-a-users-kyc-profile) describes the review.

**Stage 5. An issuer adds the KYC claim.** Approving the profile adds no KYC claim. When the identity is registered and the approved profile has a country, the platform adds a residence claim for that country, issued by the organisation's identity. The KYC claim a token checks comes from one of two places. A verification issuer adds it by hand, which the user's checklist prompts with "Issue KYC verification" and [Verify a participant](https://docs.settlemint.com/docs/console/participants/verify-a-participant) describes. Or a compliance provider such as Sumsub issues it when its signed verdict approves the investor, which [Step 4](#step-4-verify-the-investor-with-sumsub) covers. Either way, the issuer must be listed in [Trusted issuers](https://docs.settlemint.com/docs/console/compliance/trusted-issuers) for the topic, or the token ignores the claim.

**Stage 6. The token checks at transfer time.** The investor's wallet can receive the token when it passes that token's compliance rules: the required claims, and any country, list or limit rules the token has. The check runs when the transfer runs, so a claim revoked later stops the next transfer. The user's "Global eligibility" panel shows the organisation-level verdict, and "Recheck now" runs it live.

## The sequence at a glance [#the-sequence-at-a-glance]

[Figure] Four calls in one order, two side paths that rejoin, and a Sumsub verdict that decides the claim. Step 1 creates the user with POST /api/v2/users. A 200 means the custody account settled. A 202 sends you to poll the returned statusUrl until the state is terminal, then rejoin. Step 2 reads the custody accounts with GET /api/v2/participants/:participantId/custody-accounts. When the wallet has no identity contract you create it with POST /api/v2/identities and wait for the identity read, then rejoin. Step 3 registers the identity with POST /api/v2/system/identity-registrations. Step 4 requests the SDK token with POST /api/v2/compliance/subjects/sdk-access-token, and the investor completes the Sumsub checks. Sumsub's signed verdict then decides the claim: approved issues it, rejected revokes it, and an on-hold monitoring alert can revoke the claim when its severity reaches the topic's revocation threshold. Labels: 1 Create the user; POST /api/v2/users; 202: still settling; Poll the statusUrl; until the state is terminal; 200: settled; 2 Read the custody accounts; GET /api/v2/participants/; :participantId/custody-accounts; no identity contract; Create the identity; POST /api/v2/identities; then wait for the identity read; identity indexed; 3 Register the identity; POST /api/v2/system/; identity-registrations; 4 Request the SDK token; POST /api/v2/compliance/subjects/; sdk-access-token; signed Sumsub verdict; Claim issued; Approved; on the identity; Claim revoked; Rejected; on the identity; May revoke claim; On hold; at topic threshold.

You create the user with `dalp.api.party.users.create`. When that call settles, you read the participant's custody accounts with `dalp.api.participants.custodyAccountsList` and take the identity subject wallet from the account. When the call outlasts the synchronous wait, you poll the `statusUrl` the create response returned until the create settles, then read the accounts. With a wallet in hand, you register the identity with `dalp.api.party.identities.register`, and you verify the investor with Sumsub by requesting an SDK access token, then wait for the signed verdict. Only an approved verdict issues the claim the token requires. A rejected verdict revokes it, and an on-hold monitoring alert can revoke it when its severity reaches the topic's revocation threshold. A wallet that has no identity contract at all takes one extra call first, `dalp.api.party.identities.create`, and you wait for the identity read to answer before registering.

## How the systems call each other [#how-the-systems-call-each-other]

One request from you starts work in several systems. The figure shows who calls whom for a managed Fireblocks configuration and a Sumsub verification provider. Each numbered arrow from your backend is one of steps 1 to 4.

[Figure] The backend drives the platform, the platform calls Fireblocks and Sumsub, and a signed verdict closes the loop. Five lifelines: your backend, the platform API, Fireblocks, Sumsub and the investor app. The backend creates the user, reads the custody accounts and registers the identity, each time through the platform API. At create, the platform mints the investor's key in Fireblocks and has it sign. Registration is signed by your own identity-manager key, which reaches Fireblocks only when that key is held there. The backend then requests an SDK access token in one call, during which the platform creates a Sumsub applicant if the identity has none. The backend hands the token to the investor app. The investor submits documents to Sumsub. Sumsub sends a signed verdict webhook to the platform API, which issues the claim for an approved verdict and revokes it for a rejected one. An on-hold alert revokes the claim only when its severity reaches the topic's revocation threshold. Labels: Your backend; Platform API; Fireblocks; Sumsub; Investor app; 1 create user; mint key and sign; 2 read custody accounts; 3 register identity; only if your key is here; 4 request SDK token; create applicant if none; applicant and token; token and expiry; hand over the token; documents; and checks; signed verdict webhook; Platform applies the verdict; approved: issue the claim from the provider's issuer identity; rejected: revoke the claim; on hold: revoke at topic threshold.

_The investor talks to Sumsub directly, and a returned token is not a verification: a signed Sumsub verdict or on-hold alert determines the claim change._

Registration in step 3 is a write by the identity manager that calls it, so the platform signs it with that caller's own key, not with the investor's Fireblocks configuration. It reaches Fireblocks only when the caller's key is held in a Fireblocks configuration as well. In the default provider-native mode the platform files each transaction with Fireblocks and Fireblocks broadcasts it.

## Step 1: create the user [#step-1-create-the-user]

You call `POST /api/v2/users` with the user's `email`, an optional `name`, and the `providerConfigurationId` of an enabled managed provider configuration in the active organisation, which `GET /api/v2/custody/provider-configurations` lists for the request's network. The configuration is required, and naming it is what creates the participant, mints the key, and deploys the identity contract, so the rest of this sequence has a wallet to carry. The call needs the identity-manager role.

The create response names no wallet address. Read `custodyAccountId` and `identity` from a settled response, and resolve the wallet in step 2.

**cURL**

```bash
curl -X POST "https://your-instance.example.com/api/v2/users" \
  -H "X-Api-Key: sm_dalp_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: create-user-amara-001" \
  -H "Prefer: wait=55" \
  -d '{
    "email": "amara.okafor@northwind.example",
    "name": "Amara Okafor",
    "providerConfigurationId": "0198f2f0-6d0b-7f86-8f24-c5e1ef9f9d10"
  }'
```

**TypeScript SDK**

```ts
const user = await dalp.api.party.users.create(
  {
    email: "amara.okafor@northwind.example",
    name: "Amara Okafor",
    providerConfigurationId: "0198f2f0-6d0b-7f86-8f24-c5e1ef9f9d10",
  },
  { headers: { "Idempotency-Key": "create-user-amara-001" } }
);
```

Note (Fireblocks configurations): When `providerConfigurationId` names a Fireblocks configuration, the platform mints the investor's key in your Fireblocks workspace at create, and that key signs at create and for the investor's own actions. Step 3 registration is signed by the calling identity manager's key instead. The workspace must accept the typed-message and contract-call operations the platform sends. By default the platform does not ask a Fireblocks workspace for a raw signature on an EVM key, so a workspace policy that blocks raw signing needs no change. A deployment operator can turn raw signing on, and the workspace policy then has to allow it. You add the Fireblocks configuration once in the Console.

A settled call answers `200` with the user and its participant:

```json
{
  "data": {
    "id": "0193fa5c-9c31-7a4d-b0e2-3f6c9d1a7b45",
    "name": "Amara Okafor",
    "email": "amara.okafor@northwind.example",
    "participantId": "pp_0198f2f0-6d0b-7f86-8f24-c5e1ef9f9d12",
    "activationStatus": "active",
    "custodyAccountId": "0198f2f0-6d0b-7f86-8f24-c5e1ef9f9d11",
    "identity": "0x8ba1f109551bD432803012645Ac136ddd64DBA72"
  },
  "links": { "self": "/v2/users/0193fa5c-9c31-7a4d-b0e2-3f6c9d1a7b45" }
}
```

The request sends `Prefer: wait=55`, so the platform holds the answer for up to 55 seconds while the create settles. Without a `Prefer` header the route answers `202` at once. A `200` means the user and its custody account settled. If user creation exceeds the wait you asked for, the call answers `202` with a durable handle. The `Location` header and `statusUrl` name the same authenticated status resource:

```json
{
  "requestId": "c02402c036a8e8e85bcf7d80208a3281",
  "state": "running",
  "statusUrl": "/api/v2/user-create-requests/c02402c036a8e8e85bcf7d80208a3281"
}
```

Poll that URL with the same `X-Api-Key`, and with the same `X-Chain-Id` header when the create call sent it. A `202` with `state: "running"` means creation is still in progress. A `200` returns the created user in `data`. A failed create returns its named error, including an identity deployment failure. Keep the original handle. Do not submit another create while it is pending. When the organisation's approval policy holds the create for a second user's approval, the `202` carries `approvalId`, `status: "pending-approval"` and a `statusUrl` that reads the approval instead, and the create has not run.

The create waits for the user's custody account to settle before it answers, so the same `202` also covers a custody account that is still settling. A custody account that ends `failed` or `expired` fails the create with a `409` and keeps no user. When the user exists and its custody account is still settling, the route answers a `202` that carries a custody lifecycle handle instead:

```json
{
  "requestId": "0198f1a2-3c4d-7e8f-9a0b-1c2d3e4f5a6b",
  "state": "awaiting-aa-reconciliation",
  "statusUrl": "/api/v2/participants/pp_0198f2f0-6d0b-7f86-8f24-c5e1ef9f9d12/custody-account-requests/0198f1a2-3c4d-7e8f-9a0b-1c2d3e4f5a6b"
}
```

Poll the `statusUrl` the response returned, and follow it rather than building a URL of your own. The lifecycle request belongs to the participant the call created, so the read is participant-scoped at `/api/v2/participants/:participantId/custody-account-requests/:requestId`. A `/users/me` path does not reach it, because the caller is not that participant. Poll until the state is `succeeded`, `failed`, or `expired`. A terminal `failed` or `expired` state means the custody account is unusable, and you must resolve that before continuing.

The create call, the registration in step 3 and the identity create in [Recover a wallet with no identity contract](#recover-a-wallet-with-no-identity-contract) accept `Idempotency-Key` and treat a repeated key as a retry of the original submission. [Idempotency and async settlement](https://docs.settlemint.com/docs/api-reference/guides/idempotency-async-settlement) covers the key's lifetime and the `Prefer` header that decides whether a write settles inline.

## Step 2: resolve the identity wallet [#step-2-resolve-the-identity-wallet]

You call `GET /api/v2/participants/:participantId/custody-accounts` with the `participantId` from step 1. Each item carries its ledger and network, its lifecycle, its `signingAddress`, and an optional `smartWalletAddress`.

Take the identity subject wallet as the smart wallet address when the account has one, and otherwise as the signing address of the account marked primary. That is the address the Console carries through its own identity actions, and it is the address every following call in this sequence must use. The response below is an excerpt with the fields this step reads. Each item also carries the organisation context, the provider configuration with its capabilities, the account's eligibility and execution health, wallet ids and timestamps, which [the v2 API explorer](https://docs.settlemint.com/docs/api-reference/v2) lists in full.

**cURL**

```bash
curl "https://your-instance.example.com/api/v2/participants/pp_0198f2f0-6d0b-7f86-8f24-c5e1ef9f9d12/custody-accounts" \
  -H "X-Api-Key: sm_dalp_..."
```

**TypeScript SDK**

```ts
const accounts = await dalp.api.participants.custodyAccountsList({
  participantId: "pp_0198f2f0-6d0b-7f86-8f24-c5e1ef9f9d12",
});
```

```json
{
  "data": [
    {
      "custodyAccountId": "0198f2f0-6d0b-7f86-8f24-c5e1ef9f9d11",
      "participantId": "pp_0198f2f0-6d0b-7f86-8f24-c5e1ef9f9d12",
      "ledger": "evm",
      "network": "11155111",
      "accountLifecycle": "active",
      "contextLifecycle": "active",
      "isPrimary": true,
      "signingAddress": "0x71C7656EC7ab88b098defB751B7401B5f6d8976F",
      "smartWalletAddress": null
    }
  ],
  "links": { "self": "/v2/participants/pp_0198f2f0-6d0b-7f86-8f24-c5e1ef9f9d12/custody-accounts" }
}
```

Read `signingAddress` and `smartWalletAddress` only from an account whose `accountLifecycle` and `contextLifecycle` are `active`. A participant can hold accounts on more than one network, so select the account on the network you are registering on rather than the first row. When the accounts on that network do not agree on one smart wallet address, or none of them is marked primary, the subject wallet is ambiguous. Resolve the account selection before you continue, because the platform does not choose one for you.

## Step 3: register the identity [#step-3-register-the-identity]

You call `POST /api/v2/system/identity-registrations` with the `country` to record and the `wallet` from step 2. The country is an ISO 3166-1 alpha-2 code such as `BE`, and the platform normalises it before the write. Send `wallet` explicitly: omitting it registers the effective wallet of the caller, which is the operator's wallet and not the investor's.

The call needs the identity-manager role. It also accepts `walletVerification`, which proves the caller's own wallet rather than the wallet being registered.

**cURL**

```bash
curl -X POST "https://your-instance.example.com/api/v2/system/identity-registrations" \
  -H "X-Api-Key: sm_dalp_..." \
  -H "Idempotency-Key: register-identity-amara-001" \
  -H "Content-Type: application/json" \
  -d '{
    "wallet": "0x71C7656EC7ab88b098defB751B7401B5f6d8976F",
    "country": "BE"
  }'
```

**TypeScript SDK**

```ts
const registered = await dalp.api.party.identities.register({
  wallet: "0x71C7656EC7ab88b098defB751B7401B5f6d8976F",
  country: "BE",
});
```

A settled call answers `200` with the identity, the transaction hashes, and the transaction request behind them:

```json
{
  "data": {
    "id": "0x8ba1f109551bD432803012645Ac136ddd64DBA72",
    "account": { "id": "0x71C7656EC7ab88b098defB751B7401B5f6d8976F", "contractName": null },
    "isContract": false,
    "hasIdentity": true,
    "registered": { "isRegistered": true, "country": "BE" },
    "claims": []
  },
  "meta": {
    "txHashes": ["0x5c73a1e94b0d268fa37e15c8b02d94f6a1e7835c0b96d2f4e83a17c5d602b9f4"],
    "transactionId": "0198f1a2-3c4d-7e8f-9a0b-1c2d3e4f5a6b"
  },
  "links": { "self": "/v2/system/identity-registrations" }
}
```

`registered` appears only once the registry entry is active. The route also answers `202` with a queue handle when the write is queued rather than settled:

```json
{
  "transactionId": "0198f1a2-3c4d-7e8f-9a0b-1c2d3e4f5a6b",
  "status": "QUEUED",
  "statusUrl": "/api/v2/transaction-requests/0198f1a2-3c4d-7e8f-9a0b-1c2d3e4f5a6b"
}
```

Poll that `statusUrl` until the request reports a terminal state. When the organisation's approval policy holds the registration for a second user's approval, the `202` carries `approvalId`, `status: "pending-approval"` and a `statusUrl` that reads the approval instead. When the wallet belongs to one participant of the organisation, the call registers every wallet that participant holds and has not archived, together with its smart wallet on that network, and submits only the addresses whose registration is not active. A repeated registration is safe: when every one of those addresses is already active, the route answers with the identity and submits no transaction.

Until an identity contract exists for the wallet, the route answers `404` with [DALP-14223](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference#client-request-errors), whose fix says to create or register the identity first, which for this wallet means `POST /api/v2/identities`. Do not retry the same registration. Follow [Recover a wallet with no identity contract](#recover-a-wallet-with-no-identity-contract).

## Step 4: verify the investor with Sumsub [#step-4-verify-the-investor-with-sumsub]

Registration makes the wallet addressable to every token's rule check. It proves nothing about what the participant may hold, so a registered identity that carries no required claim is still refused by a token that requires one. This step collects that claim through Sumsub. Sumsub runs the checks its configured level defines, such as documents and liveness. DALP turns the result into an on-chain claim.

You need a Sumsub compliance provider with an active claim topic, the named verification a token checks for, such as `knowYourCustomer`, before you start. A permission manager, system manager or compliance manager adds it once in the Console. [Compliance providers](https://docs.settlemint.com/docs/console/compliance/compliance-providers) covers the setup. Your integrator backend passes the configured `providerId` to the investor app. A backend that looks it up with `GET /api/v2/compliance/providers` needs the "Permission manager", "System manager" or "Compliance manager" role. The investor's own session does not need those roles to request an SDK token. The call below refuses an identity that has no registration in the system's identity registry, so run it after step 3.

### Issue an SDK access token [#issue-an-sdk-access-token]

You call `POST /api/v2/compliance/subjects/sdk-access-token` to let the investor's app run the Sumsub check without holding Sumsub credentials. Send the `providerId` and `topicName`. Omit `identityAddress` to use the caller's own registered identity. A backend that acts for the investor names the investor's `identityAddress`. The platform creates the Sumsub applicant first when the identity has none, and binds it to that identity.

**cURL**

```bash
curl -X POST "https://your-instance.example.com/api/v2/compliance/subjects/sdk-access-token" \
  -H "X-Api-Key: sm_dalp_..." \
  -H "Content-Type: application/json" \
  -d '{
    "providerId": "b6f2c0a4-1d83-4f1e-9c47-2a5e8d0b7311",
    "topicName": "knowYourCustomer",
    "identityAddress": "0x8ba1f109551bD432803012645Ac136ddd64DBA72"
  }'
```

**TypeScript SDK**

```ts
const session = await dalp.api.complianceSubjectsV2.complianceSubjectIssueSdkAccessToken({
  providerId: "b6f2c0a4-1d83-4f1e-9c47-2a5e8d0b7311",
  topicName: "knowYourCustomer",
  identityAddress: "0x8ba1f109551bD432803012645Ac136ddd64DBA72",
});
```

```json
{
  "data": {
    "token": "_act-sbx-example-access-token",
    "expiresAt": "2026-09-28T16:10:00.000Z",
    "levelName": "id-and-liveness"
  },
  "links": { "self": "/api/v2/compliance/subjects/sdk-access-token" }
}
```

Pass `token` to the Sumsub WebSDK or MobileSDK in the investor's app. The token is short-lived, so request a new one after `expiresAt` instead of storing it. Naming an identity other than the caller's own needs a compliance provider role, and a missing role answers `404` with DALP-12283, the scope-denied error, not `403`. The same code covers the other scope failures in [Step 4 failures](#step-4-failures).

### Handle verdicts and on-hold alerts [#handle-verdicts-and-on-hold-alerts]

Sumsub reviews the submission and sends a signed webhook to the platform. The platform checks the signature against the webhook secret of the provider. You enter that secret on the provider in the Console. The Console then shows a delivery URL for each topic, and you copy that URL into the Sumsub dashboard so Sumsub sends its webhooks there. [Compliance providers](https://docs.settlemint.com/docs/console/compliance/compliance-providers) covers both. For the provider's claim topic, such as `knowYourCustomer`, the platform handles Sumsub events as follows:

| Sumsub event | Claim on the identity |
| --- | --- |
| `applicantReviewed` with `GREEN` (`approved`) | The platform issues the claim from the provider's issuer identity |
| `applicantReviewed` with `RED` (`rejected`) | The platform revokes the claim |
| `applicantOnHold` | The platform records a monitoring alert and revokes the claim when its severity is at or above the topic's revocation threshold. Below that threshold, nothing changes on chain. |

An on-hold alert has severity `50` for `reviewRejectType: RETRY`, `100` for `FINAL`, and `70` otherwise. Sumsub emits only `approved` and `rejected` verdicts through this integration. An on-hold alert is not an `under_review` verdict. Subscribe to the [compliance.verification-verdict.final](https://docs.settlemint.com/docs/api-reference/webhooks/events#compliance) event for approved and rejected verdicts. On-hold alerts do not emit this event. Confirm the current claim on the identity before a transfer. A token whose compliance rules require the topic reads the claim when a transfer runs. An earlier approval does not guarantee the claim is still present.

### Step 4 failures [#step-4-failures]

| Symptom | Cause | What to do |
| --- | --- | --- |
| `404` DALP-12283 | The call named another identity without a compliance provider role | Retry with the role, or omit `identityAddress` for the caller's own identity |
| `404` DALP-12283 | The call omitted `identityAddress`, and the caller holds neither an active identity nor a pending registration of its own in the system's identity registry | Register the caller's identity first, or name the identity the session is for |
| `404` DALP-12283 | The call omitted `identityAddress`, and the caller holds more than one active identity | Name the identity in `identityAddress` |
| `404` DALP-12283 | A caller with the role named an identity that has no registration in the system's identity registry | Register that identity in step 3, then request the token again |
| The SDK reports an expired token | The access token passed `expiresAt` | Request a new token |
| No event after the investor submits | Sumsub is not sending to the topic's delivery URL, or the signing secret differs between Sumsub and the provider | Copy the delivery URL from the provider's "Webhooks" table into the Sumsub dashboard, and check that both sides use the same secret |

[Verify a participant](https://docs.settlemint.com/docs/console/participants/verify-a-participant) covers the remaining work in the Console: confirm the claim on the identity, add an issuer-signed verification by hand when a topic has no provider, and run the token's pre-check before you submit a transfer.

## Recover a wallet with no identity contract [#recover-a-wallet-with-no-identity-contract]

One state leads here: a later `GET /api/v2/system/wallets/:wallet/identity` for the step 2 wallet answers `404` with [DALP-14223](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference#client-request-errors). That says the wallet has no identity contract. The user create deploys the identity before it answers, so this state follows a create that answered [DALP-12107](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference#operational-errors): the user was kept but the outcome of its identity deployment is unknown, and this call completes it against the network. A create whose deployment the chain failed answers [DALP-12115](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference#domain-rule-errors) and keeps no user, so repeat that create with a new `Idempotency-Key` instead. A create response whose `identity` is `null` is a different case that this recovery does not cover.

You call `POST /api/v2/identities` with the step 2 `wallet`, plus `walletVerification` from a signed-in session, then run step 3 once the identity read answers.

**cURL**

```bash
curl -X POST "https://your-instance.example.com/api/v2/identities" \
  -H "X-Api-Key: sm_dalp_..." \
  -H "Idempotency-Key: create-identity-amara-001" \
  -H "Content-Type: application/json" \
  -d '{
    "wallet": "0x71C7656EC7ab88b098defB751B7401B5f6d8976F"
  }'
```

**TypeScript SDK**

```ts
const identity = await dalp.api.party.identities.create({
  wallet: "0x71C7656EC7ab88b098defB751B7401B5f6d8976F",
});
```

A caller that does not own the wallet needs the identity-manager role for this call. An operator onboarding another user does not own that user's wallet, so it needs the role, and a refusal answers `403` with [DALP-14228](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference#permission-errors).

Wait for the identity read to answer before you register. Reads serve indexed state, so a contract that has just been deployed can still read as missing for a short window, and a registration sent inside that window answers `DALP-14223` again. `GET /api/v2/system/identity-registration-statuses` reports one of `NO_SYSTEM`, `NO_IDENTITY`, `NOT_REGISTERED`, `PENDING`, or `ACTIVE` for one wallet, which is one read to branch on instead of combining several.

A create for a wallet that already has an identity contract is refused with [DALP-14227](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference#domain-rule-errors). So is a create for a participant whose registry entry exists or is being created for another wallet, and so are the participant, user and multisig creates that hit the same case. A user create keeps the user it made. Read the identity's current state rather than repeating the call.

### Recover a user whose create failed [#recover-a-user-whose-create-failed]

A create that failed outright and now answers [DALP-14226](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference#domain-rule-errors) on retry is a duplicate email: a user with that address already exists. List the organisation's users, locate the record carrying that email, and read its `participantId`. Then run this same recovery from step 2 with that participant's custody account. The email is unique across the platform, so the retry cannot create a second user. When the list shows no such user, the address belongs to a user outside this organisation, and you need a different address.

## Roles and wallet verification [#roles-and-wallet-verification]

Each write in the sequence checks the caller before it queues work.

| Call | Role the caller needs | Wallet verification |
| --- | --- | --- |
| `POST /api/v2/users` | Identity manager | When the calling wallet is protected by a code |
| `GET /api/v2/participants/:participantId/custody-accounts` | Access follows participant access in the active organisation | Not applicable. A read submits no transaction |
| `POST /api/v2/system/identity-registrations` | Identity manager | When the calling wallet is protected by a code |
| `POST /api/v2/compliance/subjects/sdk-access-token` | The session alone for the caller's own identity. A compliance provider role for another identity | Not applicable. The call submits no transaction |
| `POST /api/v2/identities` | Identity manager when the caller does not own the wallet. The session alone when it does | When the calling wallet is protected by a code |

The SDK-token route is the exception: it answers `404` with DALP-12283 for a caller who names another identity without the role. Every other missing role answers `403` with [DALP-14228](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference#permission-errors). `walletVerification` carries the step-up proof for the caller's own wallet: the method and its secret, such as a pin code, a one-time password, a recovery code, or an identity-provider code. A request sent with an API key skips the proof, but a cooling-off period after a wallet security change still refuses it with `WALLET_VERIFICATION_HELD`.

## Errors [#errors]

| Code | Status | When it appears | What to do |
| --- | --- | --- | --- |
| [DALP-14226](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference#domain-rule-errors) | 409 | A user with the email already exists, the organisation has no seat left for the user, or the user's custody account ended `failed` or `expired` | For a duplicate email, follow [Recover a user whose create failed](#recover-a-user-whose-create-failed). For a full organisation, free a seat, then repeat the create with a new `Idempotency-Key`. For an ended custody account, repeat the create with a new `Idempotency-Key` |
| [DALP-12115](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference#domain-rule-errors) | 409 | The chain failed the created user's identity deployment, so no user was kept | Repeat the create with a new `Idempotency-Key` |
| [DALP-12107](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference#operational-errors) | 503 | The user was created but the outcome of its identity deployment is unknown | Run [Recover a wallet with no identity contract](#recover-a-wallet-with-no-identity-contract) for the user's wallet |
| [DALP-12116](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference#dependency-errors) | 503 | The binding read of the created user's identity never resolved, so no user was kept | Repeat the create with a new `Idempotency-Key` after a short backoff |
| [DALP-9524](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference#domain-rule-errors) | 404 | The organisation has no deployed system on the chain yet | Deploy the system, then repeat the request |
| [DALP-14223](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference#client-request-errors) | 404 | Neither the identity read nor a registration finds an identity for the wallet | Treat the wallet as having no identity contract and run [Recover a wallet with no identity contract](#recover-a-wallet-with-no-identity-contract), which creates it with `POST /api/v2/identities`, waits for it to index, then registers |
| [DALP-14227](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference#domain-rule-errors) | 409 | An identity contract already exists, another write on the wallet is in flight, or the participant already holds or is creating a registry entry for another wallet | Read the identity's current state before sending the operation again |
| [DALP-14228](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference#permission-errors) | 403 | The caller holds none of the roles the route requires for this participant | Retry as an identity manager, or grant the role before retrying |
| [DALP-12033](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference#client-request-errors) | 400 | A signing request from a session carried no `walletVerification` block | Add `walletVerification` with an enrolled method and repeat the request |
| [DALP-12034](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference#authentication-errors) | 401 | The request named a verification method the account has never enrolled | Enrol the method in [wallet security settings](https://docs.settlemint.com/docs/console/my-account/security), or send one the account already holds |
| [DALP-12035](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference#permission-errors) | 403 | The verification credential does not match, or it was already used | Send a current credential, and use a fresh recovery code because a recovery code works once |
| [DALP-12036](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference#permission-errors) | 429 | Repeated verification failures locked verification for a cooldown | Wait the seconds in `data.retryAfterSeconds`, then verify again |

[DALP error index](https://docs.settlemint.com/docs/api-reference/errors) lists every code with its machine name, category, and retry flag. [Read and handle DALP errors](https://docs.settlemint.com/docs/api-reference/guides/errors) covers the envelope these codes arrive in.

## Next steps [#next-steps]

- [Idempotency and async settlement](https://docs.settlemint.com/docs/api-reference/guides/idempotency-async-settlement) covers the `Idempotency-Key` and `Prefer` headers on these writes, and the status URL a queued write returns.
- [Verify a participant](https://docs.settlemint.com/docs/console/participants/verify-a-participant) completes the eligibility work a registered identity still needs.
- [Custody Provider](https://docs.settlemint.com/docs/concepts/custody-and-signing/custody-provider) explains what a managed configuration holds, and what a bring-your-own-key participant still has to prove.


# Pagination

Source: https://docs.settlemint.com/docs/api-reference/guides/pagination
Page DALP list endpoints with JSON:API sort, page, and filter query parameters, read the response links object, and stay inside the 200-item page-size cap.

## Overview [#overview]

Most v2 collection endpoints return an offset-and-limit page with links to neighbouring pages. Page one with `page[offset]`, `page[limit]`, `sort` and `filter[<field>]`, and follow `links.next` until it is `null`. Those endpoints refuse the flat keys `limit`, `offset`, `sortBy`, `sortDirection` and `filters` with a 400. Other endpoints declare their own flat `limit`, with `offset` or `cursor`, or stream events instead: read the route schema, and see [other pagination shapes](#other-pagination-shapes-in-the-api).

Offset-based responses contain `data`, `meta.total`, and navigation `links`. This request is illustrative. Replace the host and API key with your deployment values.

```bash
curl --globoff "https://your-instance.example.com/api/v2/tokens?sort=-createdAt&page[offset]=0&page[limit]=50" \
  -H "X-Api-Key: sm_dalp_..."
```

## Read the response [#read-the-response]

The response to that request looks like this. The example leaves out the 50 rows in `data`:

```json
{
  "data": [],
  "meta": { "total": 214 },
  "links": {
    "self": "/api/v2/tokens?sort=-createdAt&page%5Boffset%5D=0&page%5Blimit%5D=50",
    "first": "/api/v2/tokens?sort=-createdAt&page%5Boffset%5D=0&page%5Blimit%5D=50",
    "prev": null,
    "next": "/api/v2/tokens?sort=-createdAt&page%5Boffset%5D=50&page%5Blimit%5D=50",
    "last": "/api/v2/tokens?sort=-createdAt&page%5Boffset%5D=200&page%5Blimit%5D=50"
  }
}
```

The platform percent-encodes the brackets in each link, so `page[offset]` reads `page%5Boffset%5D`. Follow a link as it is rather than matching its text.

Follow `links.next` and `links.prev` instead of computing the next offset by hand. Each link already carries the active sort and filters, so following them retains the query parameters from that response. Changing filters starts a different walk.

`links.next` follows one rule: it is present exactly when `page[offset] + page[limit]` is less than `meta.total`, and `null` on exactly the last page. That makes it the only correct end-of-walk signal. A short page or an empty `data` array is not a substitute: `data.length` and `links.next` come from separate parts of the response, and treating `data.length < page[limit]` as your end-of-walk check is a bug that a page walk under concurrent writes eventually triggers, as [A page walk is not a consistent read](#a-page-walk-is-not-a-consistent-read) describes. Stop when `links.next` is `null`, never before.

## Sort [#sort]

Send `sort` with a field name to sort ascending, or a field name prefixed with `-` to sort descending. DALP accepts exactly one sort field per request, and a comma-separated list of fields is not a supported sort. Each list endpoint documents its own sortable fields on its spec-rendered page. A list can refuse a field it does not publish with a 400, or ignore it and answer in its default order. The token list refuses with a 400 `TOKEN_LIST_FILTER_INVALID` ([DALP-9289](https://docs.settlemint.com/docs/api-reference/errors)), and `data.filterId` carries the refused term as you sent it. The same code answers a `fields[token]` member the list does not publish. When a list ignores the field, the `links` in the response still repeat the `sort` you sent, so send only fields the route's reference lists as sortable.

Each collection defines its own default sort, and they differ: some order by newest first, others by a name or a display field ascending. Do not assume `-createdAt`. If order matters to your integration, send `sort` explicitly rather than relying on the default, and read the generated contract for the endpoint you are calling.

Deterministic ordering comes from tiebreaker columns the route appends to the field you sorted by, not from the sort field alone. A `createdAt` sort orders by `createdAt` first and then by a stable secondary column the route itself declares, so two rows sharing an identical `createdAt` value still resolve to one deterministic order across repeated identical queries. That guarantee is about tie-breaking within one fixed data state. It says nothing about two requests separated by an insert or a delete.

## Page window [#page-window]

`page[offset]` is the zero-based index of the first item to return. `page[limit]` is the page size. Omit either to get the default: offset `0`, limit `50`. `page[limit]` accepts 1 through 200. To read more than 200 items, follow `links.next`.

`page[offset]` has no upper bound, only a lower one: it must be an integer of zero or greater. A negative or fractional offset, and a `page[limit]` outside 1 through 200, fail with a 400 `REQUEST_INVALID` ([DALP-14261](https://docs.settlemint.com/docs/api-reference/errors)) whose `data.errors` names the parameter. Neither refusal clamps the value for you or returns an empty page, so fix the request and resend.

An offset makes the database count past every skipped row, so a page deep in a large collection costs more than the first page. To read a collection of any size at a steady cost per page, use the cursor described next.

## Read deep pages with a cursor [#read-deep-pages-with-a-cursor]

A list endpoint with cursor support returns `meta.nextCursor`: an opaque string that marks the position after the last row of the page, or `null` on the last page. Send it back as `page[cursor]` together with the same `sort` and filters to read the next page. The database seeks straight to that position, so page 1 and page 50,000 cost about the same. Among the lists that support it are `GET /api/v2/webhooks`, `GET /api/v2/webhooks/{webhookId}/deliveries`, `GET /api/v2/webhook-receipts`, `GET /api/v2/operations/cases`, `GET /api/v2/users/me/events`, `GET /api/v2/tokens/{assetId}/transfers` and the reporting statement, confirmation and transaction-report lists. A list that supports it declares `page[cursor]` in its route schema.

```bash
curl --globoff "https://your-instance.example.com/api/v2/webhook-receipts?sort=-receivedAt&page[limit]=200&page[cursor]=eyJ..." \
  -H "X-Api-Key: sm_dalp_..."
```

On a cursor walk, `links.self` repeats the cursor you sent and `links.next` carries `meta.nextCursor`, so following `links.next` keeps the walk on the cursor. `links.prev` is `null`, because a cursor reads forward only.

Treat the cursor as a value to pass back unchanged, not one to build or read. It is bound to the `sort` and filters of the request that returned it. A cursor sent with a different `sort`, different filters or a different search term, or one that has been altered, fails with a 400, `COLLECTION_PAGE_CURSOR_MISMATCH` ([DALP-9565](https://docs.settlemint.com/docs/api-reference/errors)). Every list that declares `page[cursor]` lists this code among its 400 responses. The cursor only names a position: it never widens what your key may read. When `page[cursor]` is present, `page[offset]` is ignored. Stop when `meta.nextCursor` is `null`.

## A page walk is not a consistent read [#a-page-walk-is-not-a-consistent-read]

DALP takes no snapshot when you start paging. Every request re-runs the query live against current state, `meta.total` included, so a page and the total it came with can both shift while a caller is still walking. A row can move between offsets, drop off the page it was on, or appear twice across two pages, purely because a write landed between two of your requests. Nothing in the response marks that it happened.

For a display list refreshed on a schedule, live re-query is what you want: later pages reflect the latest writes. A reconciliation job or an export needs the opposite guarantee, accounting for every row exactly once, and live re-query alone cannot give it that. For that case, page inside a filter range that does not admit new rows while you walk, such as a fixed creation-time window: on `GET /api/v2/tokens`, send `filter[createdAt][lt]` set to the time the walk started. A fixed window reduces drift but does not stop rows from being updated or deleted. Deduplicate by resource id and reconcile against a later read when completeness matters. A cursor keeps your place in the sort order, so a row whose sort value does not change during the walk is returned once. A row whose sort value changes mid-walk can be skipped or returned twice, and rows written or deleted during the walk can appear or vanish.

`meta.total` inherits the same caveat: it is recomputed on every single request as a live count on the same query, not carried over from the first page. A walk that needs a defensible row count for reconciliation must reconcile the returned resource identifiers. Recording the first total provides context but cannot prove that the walk saw every row.

## Filter [#filter]

`filter[<field>]` filters on a field the endpoint declares as filterable. The shorthand `filter[status]=active` applies the field's default operator, usually equality. Name an explicit operator when you need one: `filter[status][inArray]=active,paused` matches either value.

Filtering supports these operators. `eq`, `ne`, `gt`, `gte`, `lt`, and `lte` cover equality and ordering. `iLike` and `notILike` cover case-insensitive substring matching. `inArray` and `notInArray` cover membership. `between` covers an inclusive two-value range. `isEmpty` and `isNotEmpty` take no value at all. `inArray` and `notInArray` take 1 to 100 members, and a blank member is refused. A longer list fails with a 400 `REQUEST_INVALID` ([DALP-14261](https://docs.settlemint.com/docs/api-reference/errors)) rather than being silently truncated. The same code answers a field the endpoint does not declare and an operator the field does not support, rather than ignoring them, and `data.errors` names the key. A value outside the options of an enum-backed field fails with a 400 `COLLECTION_FILTER_VALUE_INVALID` ([DALP-9355](https://docs.settlemint.com/docs/api-reference/errors)), because dropping the filter would answer a wider page than you asked for.

When an endpoint enables global search, `filter[q]=<term>` searches across that endpoint's default text fields.

## No flat aliases [#no-flat-aliases]

The collection parameters are `sort`, `page[offset]`, `page[limit]`, `page[cursor]`, `filter[<field>]` and, on a list that declares it, `fields[<type>]`. A list that takes these parameters refuses the flat keys `sortBy`, `sortDirection`, `limit`, `offset`, and `filters` with a 400 `REQUEST_INVALID` that names the key and the parameter to send instead. A list that declares its own flat `limit`, with `offset` or `cursor`, accepts the keys it declares, as [other pagination shapes](#other-pagination-shapes-in-the-api) describes. DALP refuses them rather than ignoring them, because an ignored `limit` or `filters` would return the unfiltered first page and look like a correct answer.

## Other pagination shapes in the API [#other-pagination-shapes-in-the-api]

This offset and limit contract covers the list endpoints that take `page[...]`. Other lists in the Platform API page another way, so read the route's schema rather than assuming this one.

The request-log list, `GET /api/v2/monitoring/api/request-logs`, and the health-snapshot list, `GET /api/v2/blockchain-monitoring/health-snapshots`, page with top-level `cursor` and `limit` parameters instead of `page[...]`: send the previous response's `nextCursor` back as `cursor`, and stop when `nextCursor` comes back `null`. Their envelope is `items`, `nextCursor`, `totalCount` and `facets`, not `data`, `links` and `meta.total`.

Other lists declare a flat `limit`, with `offset` or `cursor`, as their own query parameters and take no `page[...]` parameter. Among them are `GET /api/v2/transaction-requests`, the trading venue lists, the kept custody operations lists under `/api/v2/custody-ops` and the reporting trail at `GET /api/v2/reporting/trail`. Send the keys the route's schema declares, and read the envelope from the same schema, because it differs between these routes: `GET /api/v2/transaction-requests` answers `data`, `nextCursor` and `total`, and `GET /api/v2/custody-ops/reconciliation/breaks` answers `data`, `links` and `meta`.

Event streams, such as the request-log and health-snapshot SSE feeds, carry no pagination contract at all. Connecting starts a live feed from that point forward. It does not replay history and gives no resume cursor, so a dropped connection loses whatever it missed. Use the matching list endpoint for a historical page, and the stream only for events while it stays connected.

## Next steps [#next-steps]

- [Errors](https://docs.settlemint.com/docs/api-reference/guides/errors) covers what an out-of-range page size or an unknown filter field returns.
- Each resource's spec-rendered page in the [API reference](https://docs.settlemint.com/docs/api-reference) lists that endpoint's sortable and filterable fields.


# Conditional reads

Source: https://docs.settlemint.com/docs/api-reference/guides/response-caching
Which Platform API reads carry an ETag, how to send it back in If-None-Match, what a 304 Not Modified means, and when a read carries no tag.

The platform caches successful responses to cacheable `GET` reads for each caller and tags them. A cacheable read answers with an `ETag`, a tag that identifies that exact response body. Send the tag back in `If-None-Match` on your next request for the same resource. If nothing changed, the platform answers `304 Not Modified` with no body. If something changed, it answers `200` with the new body and a new tag. A client that never sends `If-None-Match` receives the full response every time.

Polling with a tag replaces a full download with a status line. If you need to react to changes instead of polling for them, subscribe with [webhooks](https://docs.settlemint.com/docs/api-reference/webhooks).

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

Make the read once and keep the `ETag` header from the response. This request is illustrative: replace the host and API key with your deployment values. See [Authentication](https://docs.settlemint.com/docs/api-reference/guides/authentication-api-keys) for the key.

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

```http
HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: private, no-cache
ETag: "84e2cdb7a166d1671bc5e2abc1e78b59777dd1f863d3c5b05d09c2dd088444c2"
Vary: Accept-Encoding, X-Participant, X-Executor, X-Custody-Account-Id, X-Chain-Id, X-Network-Id, Origin
```

The example leaves out the route's ordinary body, which the [API reference](https://docs.settlemint.com/docs/api-reference/v2) describes. The route supplies `Content-Type`, cross-origin handling adds `Origin` to `Vary`, and the response cache sets the other headers. A real response carries more headers. Send the tag back on the next read:

```bash
curl -i "https://your-instance.example.com/api/v2/tokens" \
  -H "X-Api-Key: sm_dalp_..." \
  -H 'If-None-Match: "84e2cdb7a166d1671bc5e2abc1e78b59777dd1f863d3c5b05d09c2dd088444c2"'
```

```http
HTTP/1.1 304 Not Modified
Cache-Control: private, no-cache
ETag: "84e2cdb7a166d1671bc5e2abc1e78b59777dd1f863d3c5b05d09c2dd088444c2"
Vary: Accept-Encoding, X-Participant, X-Executor, X-Custody-Account-Id, X-Chain-Id, X-Network-Id, Origin
```

The `304` has no body. Keep the body you already hold and reuse it. Request the same URL, including the same query string, because a different URL is a different response.

The `If-None-Match` header follows these rules:

- It accepts one tag or a comma-separated list. The platform answers `304` when any tag in the list matches.
- `*` matches when the read has any current response that carries a tag.
- The platform compares tags strongly, so a weak tag, which starts with `W/`, never matches. A proxy that weakens tags therefore causes full responses.
- On a read that carries no tag, `If-None-Match` has no effect and the platform answers as if you had not sent it.

## Poll with conditional requests [#poll-with-conditional-requests]

For a client that watches a resource, send `If-None-Match` on every poll and replace your stored copy only on a `200`:

1. Make the first read and store the body with its `ETag`.
2. On each poll, send the stored tag in `If-None-Match`.
3. On `304`, keep the stored body.
4. On `200`, replace the stored body and tag with the new ones.
5. On any other status, handle it as an error as [Errors](https://docs.settlemint.com/docs/api-reference/guides/errors) describes and keep the stored pair.

On a `200` without an `ETag`, store the new body and drop the tag, so the next poll sends no `If-None-Match`.

## Use the SDK [#use-the-sdk]

The TypeScript SDK does this for you. It stores the tag from each successful read, sends it on the next read of the same URL for the same organisation and participant, and turns a `304` back into the stored body, so your code receives a normal response either way. It keeps at most 64 responses of at most 1 MiB each. It clears them when the organisation or the `X-Participant` header changes, and you must call `dalp.conditionalRequests.clear()` yourself when you switch identity through a separate authentication client. [Calling routes](https://docs.settlemint.com/docs/api-reference/sdk/calling-routes#conditional-reads) shows the call.

## What a `304` means [#what-a-304-means]

A `304` on a tag the response cache set says the body the platform would send now is byte for byte the body that your tag identifies. It is not a statement about the resource's history. A tag the response cache sets is a SHA-256 hash of the response body before compression, so a resource that changed and then changed back gives the same tag again, and the response encoding you negotiated with `Accept-Encoding` does not change the tag. When an operation sets its own `ETag`, such as the version of a stored record, the cache keeps that tag instead of replacing it with the body hash and matches `If-None-Match` against it, so a `304` on that read means the tag still matches. Treat every tag as opaque.

## Which reads carry a tag [#which-reads-carry-a-tag]

The response cache tags a read when all of these hold:

- The operation is a `GET` read and not an event stream. The cache does not apply to writes.
- The operation has not opted out of caching. Some reads, such as custody reconciliation and deposits, opt out and answer without a tag.
- The request does not set `live=true`. On a read whose reference lists a `live` query parameter, `live=true` skips the cache and returns the live result. Do not add it to other reads, because some reject unknown query parameters.
- The response has a `2xx` or `3xx` status, fits in 1 MiB, and is not streamed, so an error carries no cache tag.
- The operation does not itself set `Cache-Control: no-store` or `no-cache`, a cookie, or an `Authorization` header on its response.
- The platform can resolve which participant the request acts as, which `X-Participant` selects, or the read gives the same answer for every participant. A read that depends on the participant and cannot be resolved is served without a tag. A read that does not depend on the participant is tagged even then.
- The request URL and the caller's identity together stay within 16 KiB. A longer request is not cached.
- Response caching is on, which is the default. A self-hosting operator can turn it off with the `CACHE_VERSIONED_ENABLED` environment variable. That switch turns off the versioned cache that response caching builds on, and then the cache tags no read.

A read that skips the cache, for example after a cache fault or when catch-up after your own write cannot complete, answers without a cache tag. A response without an `ETag` is not an error. Store its body without a tag. A few operations set their own `ETag` and `Cache-Control`, so they answer with their own tag whether or not the cache stores the response. The cache does not store a `304` that an operation answers itself. The operation's reference says whether it answers `304`. The OpenAPI contract does not list the tag on every read that carries one, so check the response.

A browser app can read the tag and send `If-None-Match`: the API allows the request header and exposes the response header to cross-origin callers. A browser's HTTP cache also stores tagged responses and revalidates them by itself, so a browser app saves the transfer even if its code never sends the header. The code still receives the full response.

## Who shares a cached response [#who-shares-a-cached-response]

The platform keeps cached responses apart per caller. A cached response is keyed to the organisation, the user, how the caller signed in, the caller's platform role, whether the caller owns the organisation, the chain the request resolved to, the participant the request acts as, and the values of the `X-Executor`, `X-Custody-Account-Id`, `X-Chain-Id` and `X-Network-Id` request headers. A participant is the person, organisation or account record a request acts for, which `X-Participant` selects. For a read whose answer depends on the participant, the key holds the participant the platform resolved, not the raw header value. The platform learns which reads do not depend on the participant, such as the public configuration and the enabled languages. It keys those on the raw `X-Participant` header value instead and serves them without resolving the participant. A read that writes an audit record always resolves it. The key holds no asset role or on-chain role. The response `Vary` header lists `X-Participant` and the other four headers. Keep one stored tag per caller and per combination of those headers.

## How fresh a cached read is [#how-fresh-a-cached-read-is]

The platform invalidates cached responses when the data behind them changes. By default, a cached copy also expires five minutes after it is stored.

After you write, the platform makes your next reads wait for the cache to catch up with that write. This applies for a configurable window after you write, 60 seconds by default. A read in that window does not return a copy from before the write. If the catch-up cannot complete, the read skips the cache and carries no tag. This applies to reads by the same user who wrote. Other callers see the change when the cache invalidates.

`Cache-Control: private, no-cache` on a response the cache tags tells a client it can store the response but must revalidate before it reuses it. Revalidating means sending `If-None-Match`.

## Next steps [#next-steps]

- [Pagination](https://docs.settlemint.com/docs/api-reference/guides/pagination) for the page parameters that change the URL, and with it the cached response.
- [Errors](https://docs.settlemint.com/docs/api-reference/guides/errors) for the answers a poll can get besides `200` and `304`.
- [Versioning and deprecation](https://docs.settlemint.com/docs/api-reference/guides/versioning-and-deprecation) for how long a version stays supported.
- [Response caching in DALP 3.2](https://docs.settlemint.com/docs/changelog/dalp-3-2/developer-platform) for the release note.


# Sale terms and acknowledgement

Source: https://docs.settlemint.com/docs/api-reference/guides/sale-terms-and-acknowledgement
Upload a Primary Offering's terms documents, record their hash once during setup, then list, download, acknowledge and buy as an investor.

## Overview [#overview]

A Primary Offering, the contract-governed first sale of a new asset to investors, binds its terms to one hash. The platform derives that hash from the terms documents the issuer uploaded, so no caller supplies it. When a sale has a terms hash, an investor must acknowledge it on chain before the first purchase, and a purchase without that acknowledgement reverts with `TermsNotAccepted`. A sale without terms documents has no acknowledgement step.

The hash is fixed during setup. The sale contract accepts it once, so a second set call reverts with `TermsAlreadySet`. Upload every terms document before you set the hash.

For the request and response fields of each route, use [the v2 API explorer](https://docs.settlemint.com/docs/api-reference/v2).

## How the terms hash is derived [#how-the-terms-hash-is-derived]

The terms set of a sale is its latest documents with `documentType` `terms`. A terms document is always public, so an investor can read it before they have any other access to the sale.

1. Each document has a SHA-256 file hash, computed when the upload is confirmed. The sale document list returns it as `fileHash`.
2. The platform sorts the lowercase hex file hashes in ascending order and concatenates their 32-byte values.
3. The terms hash is the keccak256 of those concatenated bytes, not of the hex text.

The order of upload does not change the result. You can compute the same hash from the same files outside the platform.

The sale read returns three terms fields:

| Field | Meaning |
| --- | --- |
| `termsDocuments` | The current terms documents: `id`, `fileName`, `title` and `fileHash`. |
| `termsDocumentsHash` | The hash the platform derives from `termsDocuments` now. It is `null` when there is no terms document. |
| `termsHash` | The hash recorded on the sale contract. It is `null` until the issuer sets the terms. |

Once `termsHash` is set, the platform refuses to add or remove a terms document, so `termsDocumentsHash` stays equal to `termsHash`.

## Issuer flow [#issuer-flow]

The issuer needs the Offering admin role on the sale. Create the sale first: a document belongs to a sale address, which exists only after create. The create body takes no `termsHash`.

1. `POST /api/v2/addons/token-sales` creates the sale in setup.
2. `POST /api/v2/addons/token-sales/{saleAddress}/document-uploads` returns a presigned upload URL. Send `documentType: "terms"` and `visibility: "public"`. Upload the file to that URL.
3. `POST /api/v2/addons/token-sales/{saleAddress}/documents` confirms the upload and stores the file hash.
4. Repeat steps 2 and 3 for each terms document.
5. `PUT /api/v2/addons/token-sales/{saleAddress}/terms` sends the derived hash to the sale contract. From a signed-in session the call needs wallet verification, like other sale writes. A call sent with an API key needs none. Send `expectedTermsHash`, the `termsDocumentsHash` you showed the signer. The field is optional, and when you send it and the documents changed since, the call is refused with `422` and records nothing.

```bash
curl -X PUT "https://your-instance.example.com/api/v2/addons/token-sales/0x5FbDB2315678afecb367f032d93F642f64180aa3/terms" \
  -H "X-Api-Key: sm_dalp_..." \
  -H "Prefer: wait=30" \
  -H "Content-Type: application/json" \
  -d '{
    "expectedTermsHash": "0x6c1f0e4a9b2d7c38e5f1a0b4d9c2e7f3a8b6d1c4e9f2a7b3c8d5e0f1a6b2c9d4"
  }'
```

A settled call answers `200` with the transaction that recorded the hash:

```json
{
  "data": { "transactionHash": "0x2b7e9c4d1a6f3e8b5c0d7a2f9e4b1c6d3a8f5e2b9c4d7a1e6f3b8c5d2a9e4f7b" },
  "meta": {
    "txHashes": ["0x2b7e9c4d1a6f3e8b5c0d7a2f9e4b1c6d3a8f5e2b9c4d7a1e6f3b8c5d2a9e4f7b"],
    "transactionId": "0198f4b2-7c3d-7e1a-9b5f-2d4c6e8a0b1c"
  },
  "links": { "self": "/v2/addons/token-sales/0x5FbDB2315678afecb367f032d93F642f64180aa3/terms" }
}
```

Without `Prefer: wait` the call answers `202` with `transactionId`, `status` and `statusUrl`. Follow `statusUrl` until the transaction is final.

Uploading, replacing and removing a terms document needs the Offering admin role. Other sale documents only need a sale management role, so a Funds manager can still manage the brochure or FAQ.

The set-terms call is refused when the sale has no terms document, when the terms are already set or a set-terms transaction is still in flight, and after the sale leaves setup. Adding or removing a terms document is refused with `409 settlement.sale.TERMS_FIXED` once the terms are set, while a set-terms or activation transaction is in flight, and after the sale leaves setup. A terms group can only be replaced by another terms document.

Activate the sale only after the terms are set. Activating a setup sale whose uploaded terms documents have no recorded hash is refused with `422`.

In the Console, upload the terms documents on the sale's "Marketing" tab and choose **Set terms** in the Actions menu or on the overview's terms tile. The create form takes no terms document.

## Investor flow [#investor-flow]

An integration, such as an investor portal, follows four calls.

1. **List.** `GET /api/v2/addons/token-sales/{saleAddress}/documents` lists the sale documents the caller may see. Keep the items with `documentType` `terms` and `isLatest` true. The sale read returns the same set as `termsDocuments`.
2. **Download.** `POST /api/v2/addons/token-sales/{saleAddress}/documents/{documentId}/downloads` returns a download URL for one document, valid for one hour, with its `expiresAt`.
3. **Acknowledge.** `POST /api/v2/addons/token-sales/{saleAddress}/term-acknowledgements` records the acknowledgement on chain for the caller's wallet. The sale read then returns `hasAcknowledgedTerms: true`.
4. **Buy.** `POST /api/v2/addons/token-sales/{saleAddress}/purchases` submits the purchase.

The acknowledgement takes no field other than `walletVerification`, which a signed-in session sends and an API-key request leaves out:

```bash
curl -X POST "https://your-instance.example.com/api/v2/addons/token-sales/0x5FbDB2315678afecb367f032d93F642f64180aa3/term-acknowledgements" \
  -H "X-Api-Key: sm_dalp_..." \
  -H "Prefer: wait=30" \
  -H "Content-Type: application/json" \
  -d '{}'
```

```json
{
  "data": { "transactionHash": "0x9d4a1f6c3e8b2d7a5f0c9e4b1a6d3f8c5e2b7a9d4f1c6e3b8a5d2f9c4e7b1a6d" },
  "meta": {
    "txHashes": ["0x9d4a1f6c3e8b2d7a5f0c9e4b1a6d3f8c5e2b7a9d4f1c6e3b8a5d2f9c4e7b1a6d"],
    "transactionId": "0198f4b3-1a2b-7c3d-8e4f-5a6b7c8d9e0f"
  },
  "links": { "self": "/v2/addons/token-sales/0x5FbDB2315678afecb367f032d93F642f64180aa3/term-acknowledgements" }
}
```

Wait for the terminal settlement verdict of the acknowledgement before you submit the buy, as [Idempotency and async settlement](https://docs.settlemint.com/docs/api-reference/guides/idempotency-async-settlement) describes.

Both writes refuse when the documents and the recorded hash do not line up:

- The acknowledgement is refused with `422` when the sale's current terms documents differ from the hash recorded on the sale contract. The investor would otherwise accept terms that are not the documents shown.
- The purchase is refused with `422` when the sale has terms documents but no recorded hash.
- Either call answers with a retryable `503` when the terms documents or the recorded hash cannot be read.

A sale without terms documents is not affected by these checks.

The platform does not check that the investor opened a document before they acknowledge. The acknowledgement proves that the wallet accepted the hash, not that the investor read the files. An integration that must show the documents first enforces that in its own flow.

## Errors [#errors]

| Code or revert | Cause |
| --- | --- |
| `TermsNotSet` | An acknowledgement came before the issuer set the terms. |
| `TermsAlreadySet` | The issuer set the terms a second time. The hash is fixed. |
| `TermsNotAccepted` | The buyer has not acknowledged the terms hash. |
| `settlement.sale.TERMS_FIXED` (409) | A terms document was added, replaced or removed after the terms were fixed. |
| `SETTLEMENT_NOT_FOUND` (404) | A download or delete named a document id the sale does not hold: an unknown id, a deleted document or another sale's document. A download of a document above the caller's visibility answers the same way. |

## Next steps [#next-steps]

- [Primary Offering](https://docs.settlemint.com/docs/concepts/issuing-and-markets/primary-offering) for the sale lifecycle the terms belong to.
- [Idempotency and async settlement](https://docs.settlemint.com/docs/api-reference/guides/idempotency-async-settlement) for waiting on the acknowledgement's settlement before the purchase.
- [Files](https://docs.settlemint.com/docs/api-reference/guides/files) for how the platform serves stored files.


# Upgrade an integration to 3.2

Source: https://docs.settlemint.com/docs/api-reference/guides/upgrade-to-3-2
Every change in DALP 3.2 that can break a client built against 3.1 or 3.0: removed operations, new required fields, new refusals, the SDK and the CLI.

DALP 3.2 changes the Platform API, the TypeScript SDK and the CLI in ways that can break a client written for DALP 3.1 or 3.0. Each change lists what changed, who is affected, how to detect it and what to do. The steps for the people who run the platform, such as the Helm upgrade, are on [Upgrade a deployment to DALP 3.2](https://docs.settlemint.com/docs/deployment/upgrade-to-3-2).

The v2 API is stable from DALP 3.2. Before 3.2, v2 could change between releases, and this page lists the changes it took up to 3.2. From 3.2 onward a breaking change to v2 ships only on a new API version, after a deprecation with at least 90 days' notice, as [Versioning and deprecation](https://docs.settlemint.com/docs/api-reference/guides/versioning-and-deprecation) describes.

## Start here [#start-here]

Regenerate your client from the 3.2 OpenAPI document and compile it before you read the rest of this page. The [V2 API reference](https://docs.settlemint.com/docs/api-reference/v2) serves the 3.2 document. A typed client then reports most of the changes below as compile errors: a removed operation, a field that is now required, a removed response field and a renamed path parameter. The changes in [New refusals on existing operations](#new-refusals-on-existing-operations) do not show up at compile time, because they are new error responses on operations whose shape did not change. Read that section whatever your client is built with.

| Change | Affects | Detected at |
| --- | --- | --- |
| [The TypeScript SDK changed its client](#the-typescript-sdk) | Every SDK user | Compile time |
| [The CLI commands are verb-first](#the-cli) | Scripts and agents that call `dalp` | Run time |
| [Error bodies drop `defined`](#error-bodies-drop-defined) | Clients that read `defined` on an error | Run time |
| [187 v2 operations are removed](#removed-v2-operations) | Clients that call one of them | Compile time |
| [Required fields added to v2 requests](#required-fields-added-to-v2-requests) | Freezes, user creation, invitations, organisations | Compile time |
| [v2 response rows changed shape](#v2-response-shapes-that-changed) | Strict response decoders | Compile time |
| [Flat collection keys are refused](#flat-collection-keys-are-refused) | v2 list calls that send `limit`, `offset`, `sortBy`, `sortDirection` or `filters` | Run time |
| [Gas refusals answer `TRANSACTION_QUEUE_FUNDING_REQUIRED`](#gas-refusals) | Token and token-feature writes | Run time |
| [Mint and burn are refused while a corporate action runs](#mint-and-burn-during-a-corporate-action) | Mint and burn callers | Run time |
| [Burns and forced transfers refuse a frozen address](#burns-and-forced-transfers-on-a-frozen-address) | Burn and forced-transfer callers | Run time |
| [A fee recipient change pays the old recipient first](#fee-recipient-changes) | Clients that change a management fee recipient | Run time |
| [Pause and resume answer swapped contract codes](#pause-and-resume-codes) | Clients that branch on `DALP-1109` or `DALP-9059` | Run time |
| [A price with too many decimals is refused](#prices-with-too-many-decimals) | Price writes | Run time |
| [Shipped asset class slugs are reserved](#shipped-asset-class-slugs) | Asset class create and rename | Run time |
| [The original asset families answer new codes](#original-asset-families) | Token creation and factory installation | Run time |
| [Templates must be published before issuance](#template-publication) | Token creation and issuance runs | Run time |
| [v1 writes a maker-checker group protects are refused](#v1-writes-under-maker-checker) | v1 clients in an organisation that protects changes | Run time |
| [Asset document and template deletes answer new codes](#asset-documents) | Document replace and delete, template delete | Run time |
| [Venue event reads hide the counterparty](#trading-venue-reads) | Clients that read venue trades or session states | Run time |
| [Webhook registration replays on the same key](#webhook-registration-replays) | Clients that retry `POST /api/v2/webhooks` | Run time |
| [v1 reads drop wallet and gas fields](#v1-reads-drop-wallet-and-gas-fields) | v1 clients that read a user's `wallet` or an event's gas fields | Compile time |
| [Three v1 operations are removed](#removed-v1-operations) | v1 clients | Run time |
| [v1 writes are refused while maker-checker protects them](#v1-writes-under-maker-checker) | v1 clients that change roles, freezes, transfers or settings | Run time |
| [Changes for clients built against 3.0](#upgrading-from-30) | Clients built against DALP 3.0 | Both |

A client without generated types meets every change in the table as a failing request.

## Client libraries and tools [#client-libraries-and-tools]

### The TypeScript SDK [#the-typescript-sdk]

**What changed.** The 3.2 SDK, `@settlemint/dalp-sdk`, builds its client from the generated route tree:

- You create the client with `createDalpClient({ baseUrl, apiKey })`. 3.1 took `url` and a top-level `organizationId`. 3.2 has no organisation option, because the credential names the organisation: an API key acts in the organisation it was issued for, and a session in its active organisation.
- Routes sit under `dalp.api.*` and take one flat argument object instead of `{ params, query, body }`.
- Token routes name their path value `assetId`, where 3.1 named it `tokenAddress`.
- Helpers that the 3.1 package exported from its root, such as `waitForTransaction`, the auth client and the webhook verifier, move to subpaths such as `@settlemint/dalp-sdk/wait-for-transaction`.
- The `requestValidation` and `responseValidation` options are gone, because the client checks every success response against the route's schema.
- A queue-backed write sends `Prefer: wait=15` unless you set `settlementTimeoutMs`. The 3.1 client sent `Prefer: wait=99` on every write.

**Who is affected.** Every application that imports `@settlemint/dalp-sdk`.

**How to detect it.** Upgrade the package and compile. Each changed call, import and option fails to type-check.

**What to do.** Follow the call-by-call [TypeScript SDK migration guide](https://docs.settlemint.com/docs/api-reference/sdk/migration). Set `settlementTimeoutMs` if your code relied on the longer 99-second wait, and handle the `{ transactionId, status, statusUrl }` handle that a write returns when it has not settled within that wait. [Calling routes](https://docs.settlemint.com/docs/api-reference/sdk/calling-routes) covers the 3.2 client.

### The CLI [#the-cli]

**What changed.** The 3.1 CLI was a hand-written tree of noun-first commands, such as `dalp contacts list`. The 3.2 CLI generates its commands from the v2 API and puts the verb first: `dalp get contacts`. The verb comes from the HTTP method: `get` for GET, `create` for POST, `patch` for PATCH, `replace` for PUT and `delete` for DELETE. Only `login`, `logout`, `whoami`, `config` and `org` stay hand-written. `dalp --mcp` still starts the Model Context Protocol server, but it no longer registers one tool for each command. It offers four tools instead: `search_tools`, `get_tool_details`, `call_read_tool` and `call_write_tool`. `call_read_tool` runs only read commands, which are HTTP GETs, and refuses any other with `Tool is not read-only: <tool name>`. `call_write_tool` runs only the others and refuses a read command with `Tool is read-only: <tool name>`.

**Who is affected.** Shell scripts, CI jobs and AI agents that call `dalp`.

**How to detect it.** A 3.1 command name fails as an unknown command. An agent that calls a command through the wrong tool receives `Tool is not read-only` or `Tool is read-only`.

**What to do.** Run `dalp --help` and rewrite each command in the verb-first form. Point agents at `call_read_tool` for reads and `call_write_tool` for writes. [CLI commands](https://docs.settlemint.com/docs/api-reference/cli/commands) describes the pattern, and [AI agents](https://docs.settlemint.com/docs/api-reference/cli/ai-agents) describes the MCP server.

## Changes to every error response [#changes-to-every-error-response]

### Error bodies drop `defined` [#error-bodies-drop-defined]

**What changed.** A 3.1 error body carried five top-level fields: `defined`, `code`, `status`, `message` and `data`. The 3.2 body carries four: `code`, `status`, `message` and `data`. `defined` is gone from both v1 and v2 error responses. `data` always holds `id`, the `DALP-` identifier of the failure, together with `why`, `fix`, `retryable` and `category`, plus any fields specific to that failure.

**Who is affected.** Clients that branch on `defined` to tell a declared error from an unexpected one.

**How to detect it.** `defined` is missing from every error body.

**What to do.** Identify a failure by `data.id`, decide on a retry from `data.retryable`, and show `data.fix` to the person who has to act. [Errors](https://docs.settlemint.com/docs/api-reference/guides/errors) describes the envelope.

## Removed v2 operations [#removed-v2-operations]

**What changed.** 187 operations that the DALP 3.1 v2 API published are not in the 3.2 v2 API. 145 of them have a 3.2 successor. Most successors fold several narrow operations into one: role grants and revokes become one role-set call, state changes become one `transitions` call, smart wallet operations move under `/custody/wallets`, and statistics move behind one operation with a `metric` parameter. The other 42 have no v2 successor. A v1 operation still serves eight of those, and the other 34 have no replacement. The full list is in [Removed v2 operations and their successors](#removed-v2-operations-and-their-successors).

**Who is affected.** Any client that calls one of the removed operations.

**How to detect it.** A generated client no longer has the operation and fails to compile. A hand-written client receives HTTP 404 with code `ROUTE_NOT_FOUND` and `data.id` `DALP-18235`.

**What to do.** Move each call to the successor the table names, and read the successor's request schema in the API reference, because a successor often takes the old operation's intent as a field, such as `to` on a `transitions` call. Where the table names no successor, drop the call or move it to the v1 operation the table names.

## Required fields added to v2 requests [#required-fields-added-to-v2-requests]

**What changed.** These v2 operations refuse a request that leaves out a field 3.1 did not ask for:

| Operation | Field now required |
| --- | --- |
| `PUT /api/v2/tokens/{assetId}/address-freezes` | `reason` |
| `POST /api/v2/tokens/{assetId}/partial-freezes` | `reason`, for holdings on an EVM network |
| `POST /api/v2/tokens/{assetId}/partial-unfreezes` | `reason` |
| `POST /api/v2/invitations` | `custodyAccountId` |
| `POST /api/v2/invitation-acceptances` | `custodyAccountId` |
| `POST /api/v2/organizations` | `custodyAccountId`. The 3.1 fields `name` and `custody` are refused |
| `POST /api/v2/users` | `providerConfigurationId`, the custody provider configuration for the new user, which `GET /api/v2/custody/provider-configurations` lists |
| `PATCH /api/v2/users/me` | `language`, which is now the only field the body takes |

A freeze or unfreeze `reason` is an object with a `code` and an optional `text`. The code is one of `aml-review`, `sanctions-screening`, `fraud-investigation`, `court-order`, `regulatory-request`, `client-request` or `other`, and `other` needs a `text` of 1 to 500 characters. The platform records the reason in the audit trail beside the freeze. `custodyAccountId` binds the invitation, the acceptance or the new organisation to one exact custody account. `PATCH /api/v2/users/me` sets the person's language. The bodies of `PATCH /api/v2/users/me` and `POST /api/v2/organizations` accept no field beyond those they declare, so a 3.1 body that still carries `onboardingKycVisited`, or `name` and `custody`, is refused with `REQUEST_INVALID`.

**Who is affected.** Clients that freeze or unfreeze holdings, invite people or accept invitations, create organisations or users, or update the signed-in user.

**How to detect it.** A generated client fails to compile without the field, or with a field the 3.2 body does not take. At run time the platform answers HTTP 400 with code `REQUEST_INVALID`, and `data.errors` names the field.

**What to do.** Send the new field and drop the refused ones. For `custodyAccountId`, read the participant's custody accounts first, from `GET /api/v2/participants/{participantId}/custody-accounts`, and pass the one the action should use.

## v2 response shapes that changed [#v2-response-shapes-that-changed]

**What changed.** Some v2 responses changed shape:

- Several list rows became a union that a `family` field tells apart, among them the rows of `GET /api/v2/transaction-requests`, `GET /api/v2/users/me/events` and `GET /api/v2/addons/xvp-settlements`. A field such as `transactionHash` or `createdAt` no longer sits at the top level of the row schema. Every field is still present on a row whose `family` is `evm`. A `GET /api/v2/tokens` row is `{ ref, token }`, and `token._tag`, which is `evm`, `canton` or `deploying`, tells its variants apart.
- User wallet projections, `executorAddress`, `signingAddress` and, on `GET /api/v2/users/me`, `effectiveWallet`, are replaced by collections of the participant's custody accounts, and user asset balances no longer group by one wallet (`byWallet`).
- `dob` leaves the rows of `GET /api/v2/users` and `GET /api/v2/admin/users`. `GET /api/v2/users` still accepts `filter[dob]`. An organisation that records a date of birth declares it as a profile field, which `GET /api/v2/users/{userId}/profile` returns.
- The member list returns a union of the full row and a narrowed row when the request names a `view=summary` or a `fields[user]` projection.
- An asset type template's `featureConfig` is `null` or an array with one attachment for each feature, on read and on create and update. It was an object.
- A queued transaction write that answers `202 Accepted` carries the queue handle, `transactionId`, `status` and `statusUrl`, instead of a copy of the `200` body. Other `202` responses have their own body, which each route's reference documents.
- Some optional response fields are now declared nullable.
- `funding` in the `POST /api/v2/organizations/networks/bundler` response is `funded` or `ask-raised`. It is no longer `unknown`.

**Who is affected.** Clients with strict response types or strict decoders, and clients that send `featureConfig` as an object.

**How to detect it.** A client generated from the 3.2 document fails to compile where it reads a moved field without first narrowing on `family`, or where it reads a removed field.

**What to do.** Narrow on `family`, or on `token._tag` for a token row, before reading an EVM row's fields. Read custody accounts instead of the removed wallet fields. Send `featureConfig` in the attachment form the API reference shows. On a `202`, poll `statusUrl` until the transaction settles instead of reading the result from the body.

## New refusals on existing operations [#new-refusals-on-existing-operations]

These operations keep their shape in 3.2 but refuse requests they used to accept, or answer a refusal with a different code. A typed client does not see them at compile time.

### Flat collection keys are refused [#flat-collection-keys-are-refused]

**What changed.** v2 list operations that take the collection parameters `page`, `sort` and `filter` refuse the flat query keys `limit`, `offset`, `sortBy`, `sortDirection` and `filters`. 3.1 accepted them and converted them to the canonical form. A list that declares its own flat `limit`, with `offset` or `cursor`, such as `GET /api/v2/transaction-requests`, accepts the keys it declares. The platform answers HTTP 400 with code `REQUEST_INVALID` and `data.id` `DALP-14261`, and `data.errors` names the key: `Collection query key "limit" is not supported: send sort, page[offset], page[limit], and filter[<field>]`. The refusal is not retryable.

**Who is affected.** Any client that pages, sorts or filters such a list with the flat keys.

**How to detect it.** A list call answers HTTP 400 where it used to answer 200.

**What to do.** Send `page[limit]`, `page[offset]`, `sort` and `filter[<field>]`, as [Pagination](https://docs.settlemint.com/docs/api-reference/guides/pagination) describes. Correct the request before you send it again, because an unchanged retry fails the same way.

### Gas refusals [#gas-refusals]

**What changed.** When the platform refuses a token or token-feature write because the account that pays for it cannot pay the gas, the operation answers HTTP 400 with code `TRANSACTION_QUEUE_FUNDING_REQUIRED` and `data.id` `DALP-14062`. This covers a direct token or token-feature write, a token role change, a token creation or a token price update that waits for its result, and the coordinated corporate-action steps: preview, confirm, abort and leg release. `data.refusal` is `FundingRequired`, and `data.transactionId` names the transaction request when the platform recorded one. The new refusal is not retryable. A step whose smart wallet pays its own gas and holds too little answers HTTP 422 `TRANSACTION_QUEUE_SMART_WALLET_GAS_REQUIRED` (`DALP-14034`), with `smartWalletAddress` and `shortfallWei` in `data`.

**Who is affected.** Clients that write to tokens or token features, change token roles, create tokens, update prices or run coordinated corporate actions, and that handle a gas shortfall.

**How to detect it.** The write answers HTTP 400 with `data.refusal` set to `FundingRequired`.

**What to do.** Fund the paying account, then send the write again. If the retry answers `TRANSACTION_QUEUE_DUPLICATE_SETTLED` (`DALP-14066`), the idempotency key already names the refused transaction: read that transaction's outcome and send the write under a new `Idempotency-Key`. Do not retry this code automatically. [Error handling](https://docs.settlemint.com/docs/api-reference/errors/error-handling#funding-and-custody-failures) covers recovery.

### Bundler wallet without a fee quote [#bundler-wallet-without-a-fee-quote]

**What changed.** `POST /api/v2/organizations/networks/bundler` sizes the bundler wallet's funding request from the network's live fee quote. When the network has no fresh fee quote, it answers HTTP 503 with `data.id` `DALP-12250`, a retryable dependency failure. When the platform cannot record the funding request, it answers a retryable failure too. 3.1 answered both cases with HTTP 200 and `funding` set to `unknown`.

**Who is affected.** Clients that create or repair a bundler wallet and treat `funding: "unknown"` as a success.

**How to detect it.** The call answers HTTP 503 where it used to answer 200.

**What to do.** Retry the call later. The answer is retryable, and the call reuses the bundler wallet that exists.

### Mint and burn during a corporate action [#mint-and-burn-during-a-corporate-action]

**What changed.** A mint or a burn on an asset is refused while a corporate action run is in flight on the same asset. A run is in flight from the moment it starts until it completes or someone aborts it. The platform answers HTTP 409 with code `CORPORATE_ACTION_IN_FLIGHT` and `data.id` `DALP-12067`, and `data.corporateActionId` names the run that holds the asset.

**Who is affected.** Every client that mints or burns, including one whose own operator did not start the corporate action.

**How to detect it.** The mint or burn answers HTTP 409 with `CORPORATE_ACTION_IN_FLIGHT`.

**What to do.** Wait until the run named in `data.corporateActionId` completes, or abort it, then send the mint or burn again. [Corporate actions](https://docs.settlemint.com/docs/api-reference/guides/corporate-actions) describes the run.

### Burns and forced transfers on a frozen address [#burns-and-forced-transfers-on-a-frozen-address]

**What changed.** An asset on the DALP 3.2 token contract refuses a burn from an address frozen as a whole, with `DALP-1076` ("Sender address frozen"), and a forced transfer into one, with `DALP-1074` ("Recipient address frozen"). A request that names several holders fails as a whole when one of them is frozen. 3.1 burned from a frozen address and delivered a forced transfer into one. A freeze of part of a balance still stops neither: the write releases the frozen units it needs. An asset issued from an instrument template moves to the DALP 3.2 token contract when its organisation runs [System updates](https://docs.settlemint.com/docs/console/organisation-settings/system-updates). An asset of the seven original asset families, such as a bond or an equity from its type-specific factory, keeps the 3.1 behaviour.

**Who is affected.** Clients that call `POST /api/v2/tokens/{assetId}/burns` or `POST /api/v2/tokens/{assetId}/forced-transfers` for a holder whose address may be frozen.

**How to detect it.** The Platform API does not check the address freeze before it queues the write, so the request still answers `202 Accepted`. Its transaction then ends `FAILED`, with `contractError.id` `DALP-1076` or `DALP-1074`. A request sent with `Prefer: wait` answers HTTP 422 `CONTRACT_ERROR` with that code in `data.id`.

**What to do.** Read `data.holder.balance.isFrozen` from `GET /api/v2/tokens/{assetId}/holder-balances?holderAddress=<address>` before you burn from or force a transfer into an address. Lift the freeze first with `PUT /api/v2/tokens/{assetId}/address-freezes`, sending `userAddress` and `freeze: false`. To burn a frozen holder's units and keep the freeze, move them with a forced transfer to an eligible wallet, which a freeze on the sender does not stop, and burn them there.

### Fee recipient changes [#fee-recipient-changes]

**What changed.** On the DALP 3.2 management fee feature, a recipient change through `PATCH /api/v2/tokens/{assetId}/features/aum-fee` first pays the fees accrued so far to the old recipient, as a rate change already did. It fails, and changes nothing, while the asset refuses that payment: the asset is halted (`DALP-1109`), the old recipient's address is frozen (`DALP-1074`), or the old recipient no longer passes the asset's compliance rules (`DALP-1110`). 3.1 switched the recipient without paying, so the new recipient's first collection included the period the old recipient earned. A management fee moves to the 3.2 feature when its organisation runs [System updates](https://docs.settlemint.com/docs/console/organisation-settings/system-updates).

**Who is affected.** Clients that change a management fee recipient.

**How to detect it.** The request still answers `202 Accepted`, and its transaction ends `FAILED` with one of those codes in `contractError.id`, or, with `Prefer: wait`, HTTP 422 `CONTRACT_ERROR` with the code in `data.id`. A successful change records a fee payment to the old recipient.

**What to do.** Resume the asset, or unfreeze or re-verify the old recipient, before you change the recipient. Reconcile the payment to the old recipient that the change makes.

### Pause and resume codes [#pause-and-resume-codes]

**What changed.** The DALP 3.2 token contract refuses a halt of an asset that is already halted with `DALP-1109`, and a resume of an active asset with `DALP-9059`. Every other token contract answers the reverse. `PATCH /api/v2/tokens/{assetId}/pause-state` compares the request with the indexed pause state and refuses a match with `DALP-9488`. A contract code reaches a client when the chain holds a state the platform has not indexed yet, such as a second halt sent before the first is indexed. It arrives as `contractError.id` on the failed transaction, or in `data.id` of an HTTP 422 `CONTRACT_ERROR` with `Prefer: wait`.

**Who is affected.** Clients that branch on `DALP-1109` or `DALP-9059` after a halt or a resume.

**How to detect it.** A halt answers `DALP-1109` where it used to answer `DALP-9059`, or a resume the reverse.

**What to do.** After a halt or a resume, read `DALP-9488`, `DALP-1109` and `DALP-9059` as "the asset already has the state you asked for", whichever action you sent.

### v1 writes under maker-checker [#v1-writes-under-maker-checker]

**What changed.** When an organisation protects a group of changes with [maker-checker](https://docs.settlemint.com/docs/concepts/custody-and-signing/maker-checker), a v2 write in that group is held for a second user's approval. The v1 API cannot hold a request, so a v1 write whose v2 route the protected group would hold is refused before anything runs. The refusal is HTTP 403 with the v1 code `FORBIDDEN`, and `data.id` is the id that route already answers for a refused caller: `DALP-9485` on token routes, `DALP-12252` on platform routes and `DALP-0003` on identity, compliance and user routes. Four v1 writes had no 403 in 3.1 and gain one in 3.2, answering `DALP-12252`: `POST /api/v1/external-token/register`, `POST /api/v1/kyc-profile-versions/{versionId}/request-update`, `POST /api/v1/user/create` and `POST /api/v1/user/admin/session/revoke`. The refusal is not retryable.

**Who is affected.** v1 clients in an organisation that protects a group, such as Token administration or System administration.

**How to detect it.** A v1 write answers HTTP 403 whose `message` says the organisation holds the change for a second user's approval.

**What to do.** Send the change to the v2 route that `data.fix` names. It answers `202` and holds the change until a second user approves it.

### Prices with too many decimals [#prices-with-too-many-decimals]

**What changed.** A price write that holds more decimal places than the price feed stores is refused. This covers a token price update, a price feed submission, and the initial price of a token creation. The platform answers HTTP 400 with code `FEED_PRICE_NOT_REPRESENTABLE` and `data.id` `DALP-12245`, and the message names the price and the feed's decimals. 3.1 accepted the value and cut the extra digits off, rounding toward zero.

**Who is affected.** Clients that send prices with more precision than the feed stores.

**How to detect it.** The price write answers HTTP 400 with `FEED_PRICE_NOT_REPRESENTABLE`.

**What to do.** Round or format the price to the feed's decimals before you send it. The refusal is not retryable unchanged.

### Shipped asset class slugs [#shipped-asset-class-slugs]

**What changed.** Creating a custom asset class, or renaming one, onto the slug of an asset class that DALP ships is refused. The shipped slugs are `fixed-income`, `equity`, `funds`, `cash`, `real-assets`, `structured`, `derivatives`, `yield-instruments` and `digital-assets`. The platform answers HTTP 409 with code `SETTINGS_TEMPLATE_NAME_ALREADY_EXISTS`, `data.id` `DALP-0463` and the message `The slug "<slug>" belongs to a system asset class. Choose a different name.`

The upgrade also resolves an organisation's own class that already uses the slug of a shipped class. Each shipped class allows these base types:

| Shipped class | Allowed base types |
| --- | --- |
| `fixed-income` | `bond` |
| `equity` | `equity` |
| `funds` | `fund` |
| `cash` | `stablecoin`, `deposit` |
| `real-assets` | `real-estate`, `precious-metal` |
| `structured` | `bond`, `fund` |
| `derivatives`, new in 3.2 | `equity` |
| `yield-instruments`, new in 3.2 | `equity` |
| `digital-assets` | every base type |

If every template in the organisation's own class has a base type the shipped class allows, the shipped class adopts its templates, and the organisation's own class row is deleted, so its identifier no longer exists. Otherwise the class stays the organisation's own and moves to the slug `<old slug>-<first eight letters and digits of its identifier, in lower case>`, with its name, identifier and templates unchanged. For `derivatives` and `yield-instruments`, a template whose own class row was already deleted follows the same split: an `equity` template joins the shipped class, and any other template moves to `<old slug>-custom`.

**Who is affected.** Clients that create or rename asset classes, and clients that look up or store an organisation's own class under the slug of a shipped class.

**How to detect it.** A create or rename answers HTTP 409 with `DALP-0463`. After the upgrade, a lookup by the old slug returns the shipped class, or a class identifier stored before the upgrade no longer resolves.

**What to do.** Choose another slug. Key asset classes by identifier, and read the class list again after the upgrade.

### Original asset families [#original-asset-families]

**What changed.** The seven asset families of the original catalogue, `bond`, `equity`, `fund`, `stablecoin`, `deposit`, `real-estate` and `precious-metal`, cannot be created or installed unless the deployment turns legacy asset creation on, and it is off by default. The 3.1.19 patch release introduced this refusal, and 3.2 answers it with different codes. A v2 token creation of one of these types answers HTTP 422 with code `TOKEN_CREATE_ASSET_FAMILY_DEPRECATED` (`DALP-12075`), where 3.1 answered HTTP 400 with `DALP-9103`. A v2 factory installation for one of them answers HTTP 422 with code `PLATFORM_FACTORY_TYPE_UNUSABLE` (`DALP-14339`), where 3.1 answered with `DALP-9104`. The v1 token creation answers HTTP 422 with the v1 code `INPUT_VALIDATION_FAILED` and `data.id` `DALP-9243`. None is retryable. The refusal applies to new creations and factory installations, and the platform removes no factory that a system already has. 3.0 had no such refusal.

**Who is affected.** Clients that still create tokens of these seven types, and clients that branch on the 3.1 status or identifiers.

**How to detect it.** Read `data.features.legacyAssetCreation` from `GET /api/v2/settings/public-config`. When it is `false`, a create or install of those seven families is refused.

**What to do.** Create the asset from a current instrument template, or ask the platform operator to turn legacy asset creation on, as [Upgrade a deployment to DALP 3.2](https://docs.settlemint.com/docs/deployment/upgrade-to-3-2#decide-on-legacy-asset-creation) describes. Match the 3.2 `data.id` values above. A client that branches on `code` replaces the 3.1 codes `TOKEN_CREATE_TYPE_DEPRECATED` and `TOKEN_FACTORY_TYPE_DEPRECATED`.

### Template publication [#template-publication]

**What changed.** An organisation issues only from instrument templates and structures that are published. The templates an organisation creates itself count as published. Of the templates that DALP ships, Equity, Bond and Stablecoin start published in every organisation, and every other one starts unpublished. A v2 token creation from an unpublished template answers HTTP 409 with code `TOKEN_CREATE_TEMPLATE_UNPUBLISHED` (`DALP-14019`). An issuance run answers HTTP 409 with `TOKEN_ISSUANCE_RUN_TEMPLATE_UNPUBLISHED` (`DALP-14020`) for an unpublished member template, or `TOKEN_ISSUANCE_RUN_STRUCTURE_UNPUBLISHED` (`DALP-14024`) for an unpublished structure. The v1 token creation answers HTTP 422 with the v1 code `INPUT_VALIDATION_FAILED` and `data.id` `DALP-0316`. None is retryable unchanged.

**Who is affected.** Clients that create tokens or start issuance runs from templates other than Equity, Bond and Stablecoin.

**How to detect it.** The template's `isPublished` field is `false`.

**What to do.** Publish the template with `PUT /api/v2/settings/asset-type-templates/{assetTypeTemplateId}/publication`, or ask an organisation owner to publish it in the Console, then send the request again.

### Asset documents [#asset-documents]

**What changed.** A document confirm whose `replaceGroupId` names a document group of another document type answers HTTP 404 with `DALP-0322`, where it used to add a version of the new type to that group. A document delete by a wallet without the governance role answers HTTP 403 with `DALP-9485` whether or not the document exists, where it used to answer 404 for a document it could not find. Deleting an instrument template that tokens were issued from answers HTTP 409 with `DALP-181131`, where it used to answer 500.

**Who is affected.** Clients that replace asset documents or delete them, and clients that delete instrument templates.

**How to detect it.** A response that carries one of the `data.id` values this change names.

**What to do.** Replace a document only within a group of the same type. Treat a 403 on delete as a missing role, not a missing document. A template that tokens were issued from cannot be deleted.

### v1 KYC document uploads and downloads [#v1-kyc-document-uploads-and-downloads]

**What changed.** The v1 KYC document confirm validates the uploaded file (declared size, a 25 MiB bound and the file's real type) and stores it encrypted, as the v2 upload does. 3.1 stored it unencrypted and unvalidated. A confirm that fails validation answers a refusal and deletes the uploaded object, so request a new upload link and send the file again. The v1 and v2 document download calls always return a relative `/api/v2/` path that needs your credential. 3.1 returned an absolute object-storage URL, usable by anyone who held it, for a document that the v1 upload had stored unencrypted. The platform now encrypts those documents in the background. A presigned upload that is never confirmed is deleted 30 minutes after the link was issued.

**Who is affected.** Clients that upload KYC documents through the v1 presigned upload, and clients that fetch a KYC document from the `downloadUrl` it returns.

**How to detect it.** A `downloadUrl` that starts with `/api/v2/` where it used to start with `https://`, and a confirm that answers a refusal for a file whose type differs from the declared one.

**What to do.** Send your session or API key when you fetch `downloadUrl`, and resolve a relative path against your DALP base URL. Declare the file's real size and type on the confirm. Prefer the v2 upload, which sends the file to the platform and never leaves it unencrypted in object storage.

## Trading venue reads [#trading-venue-reads]

**What changed.** `GET /api/v2/users/me/events` and `GET /api/v2/tokens/{assetId}/events`, and the v1 token events, name only the caller's own side of a trade a venue settled. In the Swap row, `swap.buyer`, `swap.seller`, and a transfer's `from` and `to` can be `null`, and the decoded `buyer`, `seller`, `buyOrderHash` and `sellOrderHash` values and `involved` follow the same rule. A venue operator still reads both sides. An instrument's `sessionState`, and a calendar occurrence's `appliedState`, can be `trade-at-last`, and calendar days, exceptions and venue calendars accept an optional `tradeAtLastTime`.

**Who is affected.** Clients that read the counterparty of their own trade from the event reads, and clients that list session states.

**How to detect it.** A null counterparty on a venue trade, or a session state the client does not know.

**What to do.** Read the counterparty from the venue's operator reads, with an operator's credentials. Treat an unknown session state as not tradable rather than open.

## Webhook registration replays [#webhook-registration-replays]

**What changed.** `POST /api/v2/webhooks` treats a retry with the same `Idempotency-Key` and the same body as a replay. It returns the endpoint the first request registered, with `signingSecret` set to `null`, and registers no second endpoint. The operation returns the key it used in the `Idempotency-Key` response header, including a key the platform generated because the request sent none. A reused key with a different body, a key whose endpoint was deleted, or a key whose registration never completed answers HTTP 409 `WEBHOOK_IDEMPOTENCY_KEY_REUSED` (`DALP-0537`), which is not retryable. A retry while the first request is still registering answers HTTP 409 `WEBHOOK_CREATE_IN_PROGRESS` (`DALP-0538`), which is retryable.

Every write under `/api/v2/webhooks`, and `POST /api/v2/webhook-receipts`, no longer declares a `202` response in the contract: each finishes before it responds and returns `200`.

**Who is affected.** Clients that retry webhook registration, and clients that expect the signing secret on every successful registration response.

**How to detect it.** A replayed registration returns `signingSecret: null`.

**What to do.** Store the signing secret from the first successful response, because a replay does not return it. Keep the `Idempotency-Key` response header so that a client that lost the response can replay it. On `WEBHOOK_CREATE_IN_PROGRESS`, send the same request again after a short wait. On `WEBHOOK_IDEMPOTENCY_KEY_REUSED`, register under a new key. If the secret is lost, rotate it, as [Webhooks](https://docs.settlemint.com/docs/api-reference/guides/webhooks#rotate-the-signing-secret) describes.

## Removed v1 operations [#removed-v1-operations]

**What changed.** 3.2 removes three v1 operations without the 90-day deprecation notice that [Versioning and deprecation](https://docs.settlemint.com/docs/api-reference/guides/versioning-and-deprecation) describes. The rest of the v1 structure stays, apart from the fields that [v1 reads drop wallet and gas fields](#v1-reads-drop-wallet-and-gas-fields) lists:

| 3.1 v1 operation | 3.2 replacement |
| --- | --- |
| `GET /api/v1/user/by-wallet/{wallet}` | `GET /api/v2/users`, filtered by wallet. A wallet can match more than one user. |
| `POST /api/v1/user/create-wallet` | `POST /api/v2/custody/accounts/lifecycle` |
| `PATCH /api/v1/user/me` | None. The onboarding flag it set no longer exists, and `PATCH /api/v2/users/me` sets only the language. |

**Who is affected.** v1 clients that call one of the three.

**How to detect it.** The call answers HTTP 404 with the body `{"code":"NOT_FOUND","status":404,"message":"The request could not be completed"}` and the content type `text/plain`. The body has no `data` object.

**What to do.** Move the call to the v2 replacement. v1 error bodies change as described in [Error bodies drop `defined`](#error-bodies-drop-defined).

## v1 reads drop wallet and gas fields [#v1-reads-drop-wallet-and-gas-fields]

**What changed.** The v1 user reads no longer return the user's single-wallet fields `wallet`, `executorAddress` and `signingAddress`: `GET /api/v1/user/me`, `GET /api/v1/user/by-id/{userId}`, `GET /api/v1/user/list`, `GET /api/v1/user/list/admins`, `GET /api/v1/user/search`, the user results of `GET /api/v1/search`, and the response of `POST /api/v1/user/create`. `GET /api/v1/user/me` also no longer returns `effectiveWallet`. A user can hold more than one custody account, so one wallet field cannot describe it. `GET /api/v1/user/events` no longer returns `gasPrice` or `gasUsed`, because the platform does not index the gas a transaction used.

**Who is affected.** v1 clients that read a user's wallet from these responses, or the gas fields of a user event.

**How to detect it.** A client generated from the 3.2 document fails to compile where it reads the fields. At run time the fields are absent, with no error.

**What to do.** Read the user's custody accounts from `GET /api/v2/participants/{participantId}/custody-accounts`, with the `participantId` that `GET /api/v1/user/by-id/{userId}` and `GET /api/v1/user/list` return. Treat `gasPrice` and `gasUsed` as absent.

## v1 writes under maker-checker [#v1-writes-under-maker-checker-1]

**What changed.** A v1 client cannot read the `202` answer that holds a request for a second approver. A v1 write whose v2 route an organisation holds under maker-checker, the control in which a second approver must approve a change before it runs, is therefore refused before anything runs. The refusal is the `403` that the v1 route already declares for a caller who lacks access, with a message that names the protection group and a `data.fix` that names the v2 route to send the change to. A v1 write whose v2 route is never held, such as a mint, runs as before.

**Who is affected.** v1 clients that change roles, freeze addresses, force transfers or edit settings in an organisation that protects the matching group.

**How to detect it.** The `403` carries a message that names the protection group.

**What to do.** Send the change to the v2 route that `data.fix` names. [Maker-checker approval](https://docs.settlemint.com/docs/concepts/custody-and-signing/maker-checker) describes the groups and the second approval.

## Upgrading from 3.0 [#upgrading-from-30]

A client built against DALP 3.0 needs every change on this page and nothing more. Every v1 and v2 operation that 3.0 published is still in 3.1, so 3.1 removed nothing that a 3.0 client calls. The refusal of the [original asset families](#original-asset-families) arrived in the 3.1.19 patch release, so a 3.0 client meets it for the first time on this upgrade.

## Removed v2 operations and their successors [#removed-v2-operations-and-their-successors]

Each row is an operation that the DALP 3.1 v2 API published and the 3.2 v2 API does not. Paths are relative to `/api/v2`. Path parameters keep their position when a successor renames them, such as `{tokenAddress}` to `{assetId}`.

| 3.1 operation | 3.2 operation | Note |
| --- | --- | --- |
| `GET /actions` | None | No 3.2 operation. |
| `POST /addons/token-sale-activations` | `POST /addons/token-sales/{saleAddress}/transitions` | Send the target state in `to`. |
| `POST /addons/token-sale-closures` | `POST /addons/token-sales/{saleAddress}/transitions` | Send the target state in `to`. |
| `POST /addons/token-sale-finalizations` | `POST /addons/token-sales/{saleAddress}/transitions` | Send the target state in `to`. |
| `POST /addons/token-sale-fund-withdrawals` | `POST /addons/token-sales/{saleAddress}/fund-withdrawals` |  |
| `DELETE /addons/token-sale-pauses` | `POST /addons/token-sales/{saleAddress}/transitions` | Send the target state in `to`. |
| `POST /addons/token-sale-pauses` | `POST /addons/token-sales/{saleAddress}/transitions` | Send the target state in `to`. |
| `DELETE /addons/token-sale-payment-currencies` | `POST /addons/token-sales` | Set at sale creation. No later change. |
| `POST /addons/token-sale-payment-currencies` | `POST /addons/token-sales` | Set at sale creation. No later change. |
| `DELETE /addons/token-sale-presale-whitelist-entries` | `DELETE /addons/token-sales/{saleAddress}/presale-whitelist-entries` |  |
| `POST /addons/token-sale-presale-whitelist-entries` | `POST /addons/token-sales/{saleAddress}/presale-whitelist-entries` |  |
| `PATCH /addons/token-sale-purchase-limits` | `POST /addons/token-sales` | Set at sale creation. No later change. |
| `POST /addons/token-sale-purchases` | `POST /addons/token-sales/{saleAddress}/purchases` |  |
| `POST /addons/token-sale-refund-claims` | `POST /addons/token-sales/{saleAddress}/refund-claims` |  |
| `PATCH /addons/token-sale-soft-caps` | `POST /addons/token-sales` | Set at sale creation. No later change. |
| `POST /addons/token-sale-term-acknowledgements` | `POST /addons/token-sales/{saleAddress}/term-acknowledgements` |  |
| `PATCH /addons/token-sale-terms` | `POST /addons/token-sales` | Set at sale creation. No later change. |
| `POST /addons/token-sale-token-withdrawals` | `POST /addons/token-sales/{saleAddress}/token-withdrawals` |  |
| `POST /addons/token-sale-unsold-token-withdrawals` | `POST /addons/token-sales/{saleAddress}/unsold-token-withdrawals` |  |
| `PATCH /addons/token-sale-vesting-configurations` | `POST /addons/token-sales` | Set at sale creation. No later change. |
| `DELETE /addons/xvp-approvals` | `DELETE /addons/xvp-settlements/{settlementAddress}/approvals` |  |
| `POST /addons/xvp-approvals` | `POST /addons/xvp-settlements/{settlementAddress}/approvals` |  |
| `DELETE /addons/xvp-cancellation-requests` | None | No v2 operation. The v1 operation `PUT /api/v1/xvp/withdraw-cancel` serves it. |
| `POST /addons/xvp-cancellation-requests` | `POST /addons/xvp-settlements/{settlementAddress}/cancellation-requests` |  |
| `POST /addons/xvp-executions` | `POST /addons/xvp-settlements/{settlementAddress}/executions` |  |
| `POST /addons/xvp-expiry-withdrawals` | `POST /addons/xvp-settlements/{settlementAddress}/expiry-withdrawals` |  |
| `POST /addons/xvp-secret-decryptions` | `POST /addons/xvp-settlements/{settlementAddress}/secret-decryptions` |  |
| `POST /addons/xvp-secret-revelations` | `POST /addons/xvp-settlements/{settlementAddress}/secret-revelations` |  |
| `POST /addons/xvp-secrets` | `POST /addons/xvp-settlements/{settlementAddress}/secrets` |  |
| `GET /admin/custody/{organizationId}` | None | Replaced by custody provider configurations under `/api/v2/admin/custody/provider-configurations`. |
| `DELETE /admin/custody/{organizationId}/credentials` | None | Replaced by custody provider configurations under `/api/v2/admin/custody/provider-configurations`. |
| `POST /admin/organizations/{id}/archive` | `POST /admin/organizations/{id}/transitions` | Send the target state in `to`. |
| `POST /admin/organizations/{id}/restore` | `POST /admin/organizations/{id}/transitions` | Send the target state in `to`. |
| `GET /blockchain-monitoring/service-health-metrics` | None | No 3.2 operation. |
| `POST /compliance/providers/{providerId}/cancel-secret-rotation` | `DELETE /compliance/providers/{providerId}/secret-rotations/pending` |  |
| `POST /compliance/providers/{providerId}/pause` | `POST /compliance/providers/{providerId}/transitions` | Send the target state in `to`. |
| `POST /compliance/providers/{providerId}/promote-secret` | `POST /compliance/providers/{providerId}/secret-rotations/promotions` |  |
| `POST /compliance/providers/{providerId}/resume` | `POST /compliance/providers/{providerId}/transitions` | Send the target state in `to`. |
| `POST /compliance/providers/{providerId}/retry-provisioning` | None | No 3.2 operation. |
| `POST /compliance/providers/{providerId}/revoke` | `POST /compliance/providers/{providerId}/transitions` | Send the target state in `to`. |
| `POST /compliance/providers/{providerId}/rotate-secret` | `POST /compliance/providers/{providerId}/secret-rotations` |  |
| `POST /compliance/providers/{providerId}/webhooks/{webhookId}/pause` | `POST /compliance/providers/{providerId}/webhooks/{webhookId}/transitions` | Send the target state in `to`. |
| `POST /compliance/providers/{providerId}/webhooks/{webhookId}/reactivate` | `POST /compliance/providers/{providerId}/webhooks/{webhookId}/transitions` | Send the target state in `to`. |
| `POST /compliance/providers/{providerId}/webhooks/{webhookId}/resume` | `POST /compliance/providers/{providerId}/webhooks/{webhookId}/transitions` | Send the target state in `to`. |
| `POST /compliance/providers/{providerId}/webhooks/{webhookId}/revoke` | `POST /compliance/providers/{providerId}/webhooks/{webhookId}/transitions` | Send the target state in `to`. |
| `POST /compliance/providers/{providerId}/webhooks/{webhookId}/rotate-secret` | `POST /compliance/providers/{providerId}/webhooks/{webhookId}/secret-rotations` |  |
| `GET /custody` | None | Replaced by custody provider configurations under `/api/v2/admin/custody/provider-configurations`. |
| `PUT /custody/credentials` | None | Replaced by custody provider configurations under `/api/v2/admin/custody/provider-configurations`. |
| `POST /custody/test-credentials` | None | Replaced by custody provider configurations under `/api/v2/admin/custody/provider-configurations`. |
| `POST /kyc-profile-versions/{versionId}/approvals` | `POST /kyc-profile-versions/{versionId}/decisions` | Send `decision: approve`. |
| `POST /kyc-profile-versions/{versionId}/rejections` | `POST /kyc-profile-versions/{versionId}/decisions` | Send `decision: reject` with a reason. |
| `GET /monitoring/api/endpoint-metrics` | None | No 3.2 operation. |
| `GET /monitoring/api/request-metrics/summary` | None | No 3.2 operation. |
| `GET /monitoring/api/request-metrics/timeline` | None | No 3.2 operation. |
| `GET /monitoring/api/request-metrics/top-errors` | None | No 3.2 operation. |
| `GET /participants/{participantId}/smart-wallet` | `GET /participants/{participantId}/custody-accounts` | Read each account record. |
| `GET /platform-status/data-freshness` | `GET /platform-status` | All panels in one read. |
| `GET /platform-status/platform-api` | `GET /platform-status` | All panels in one read. |
| `GET /platform-status/snapshot` | None | Not in the published 3.2 contract. |
| `GET /platform-status/stat-cards` | `GET /platform-status` | All panels in one read. |
| `GET /platform-status/transactions` | `GET /platform-status` | All panels in one read. |
| `GET /platform-status/workflows` | `GET /platform-status` | All panels in one read. |
| `PUT /settings/asset-type-templates/{id}/publish` | `PUT /settings/asset-type-templates/{assetTypeTemplateId}/publication` | Send `{"published": true}`. |
| `GET /smart-wallets` | `GET /custody/wallets` |  |
| `POST /smart-wallets` | `POST /custody/wallets` |  |
| `GET /smart-wallets/{address}` | `GET /custody/wallets/{walletId}` | Keyed by wallet id, not address. |
| `PATCH /smart-wallets/{address}` | `PATCH /custody/wallets/{walletId}` | Keyed by wallet id, not address. |
| `GET /smart-wallets/{address}/approvals` | `GET /custody/wallets/{walletId}/approvals` | Keyed by wallet id, not address. |
| `POST /smart-wallets/{address}/approvals` | `POST /custody/wallets/{walletId}/approvals` | Keyed by wallet id, not address. |
| `GET /smart-wallets/{address}/approvals/{userOpHash}` | `GET /custody/approvals/{approvalId}` |  |
| `POST /smart-wallets/{address}/approvals/{userOpHash}/sign` | `POST /custody/approvals/{approvalId}/signatures` |  |
| `GET /smart-wallets/{address}/gas-status` | `GET /custody/wallets/{walletId}/gas` | Keyed by wallet id, not address. |
| `POST /smart-wallets/{address}/modules` | `POST /custody/wallets/{walletId}/mutations` | One operation for each wallet change. |
| `DELETE /smart-wallets/{address}/modules/{moduleAddress}` | `POST /custody/wallets/{walletId}/mutations` | One operation for each wallet change. |
| `GET /smart-wallets/{address}/signers` | `GET /custody/wallets/{walletId}/signers` | Keyed by wallet id, not address. |
| `POST /smart-wallets/{address}/signers` | `POST /custody/wallets/{walletId}/mutations` | One operation for each wallet change. |
| `DELETE /smart-wallets/{address}/signers/{signer}` | `POST /custody/wallets/{walletId}/mutations` | One operation for each wallet change. |
| `PUT /smart-wallets/{address}/threshold` | `POST /custody/wallets/{walletId}/mutations` | One operation for each wallet change. |
| `GET /smart-wallets/custody/gas-balance` | None | Not in the published 3.2 contract. |
| `DELETE /system/accounts/{address}/role-grants` | `POST /system/role-sets` | One call grants and revokes. |
| `POST /system/accounts/{address}/role-grants` | `POST /system/role-sets` | One call grants and revokes. |
| `GET /system/feeds/{feedAddress}/config` | `GET /system/feeds/{feedAddress}/configuration` |  |
| `GET /system/feeds/{feedAddress}/nonce/{issuerIdentity}` | None | No 3.2 operation. |
| `GET /system/feeds/{feedAddress}/round/{roundId}` | None | No 3.2 operation. |
| `GET /system/feeds/{feedAddress}/staleness` | None | No 3.2 operation. |
| `POST /system/feeds/{feedAddress}/submit` | `POST /system/feeds/{feedAddress}/submissions` |  |
| `GET /system/feeds/adapters` | None | No 3.2 operation. |
| `POST /system/feeds/adapters/create` | `POST /system/feeds/adapters` |  |
| `GET /system/feeds/issuer-signed` | None | No 3.2 operation. |
| `POST /system/feeds/issuer-signed/create` | `POST /system/feeds/issuer-signed` |  |
| `POST /system/feeds/register-external` | `POST /system/feeds/external-registrations` |  |
| `DELETE /system/feeds/remove` | `DELETE /system/feeds/registrations` |  |
| `PUT /system/feeds/replace` | `PUT /system/feeds/registrations` |  |
| `GET /system/feeds/resolve` | `GET /system/feeds/resolutions` |  |
| `GET /system/migration/{migrationId}/stream` | `GET /system/migrations/{migrationId}/stream` |  |
| `GET /system/migration/active` | `GET /system/migrations/active` |  |
| `GET /system/migration/compare` | `GET /system/migration-comparison` |  |
| `POST /system/migration/start` | `POST /system/migrations` |  |
| `POST /system/participants/role-grants` | `POST /system/role-sets` | One call grants and revokes. |
| `POST /system/participants/role-revocations` | `POST /system/role-sets` | One call grants and revokes. |
| `PUT /system/refund-splitter/bps` | `PATCH /system/refund-splitter` |  |
| `POST /system/refund-splitter/recover-erc20` | None | No 3.2 operation. |
| `POST /system/refund-splitter/recover-native` | None | No 3.2 operation. |
| `PUT /system/refund-splitter/sponsorship` | None | No 3.2 operation. |
| `GET /system/refund-splitter/status` | `GET /system/refund-splitter` |  |
| `GET /system/refund-splitter/thresholds` | `GET /system/refund-splitter` |  |
| `PUT /system/refund-splitter/thresholds` | `PATCH /system/refund-splitter` |  |
| `GET /system/stats/asset-activity-range-presets/{preset}` | `GET /system/stats/{metric}` | One statistic per `metric`. |
| `GET /system/stats/asset-activity-ranges` | `GET /system/stats/{metric}` | One statistic per `metric`. |
| `GET /system/stats/asset-lifecycle-range-presets/{preset}` | `GET /system/stats/{metric}` | One statistic per `metric`. |
| `GET /system/stats/asset-lifecycle-ranges` | `GET /system/stats/{metric}` | One statistic per `metric`. |
| `GET /system/stats/assets` | `GET /system/stats/{metric}` | One statistic per `metric`. |
| `GET /system/stats/claim-stat-range-presets/{preset}` | `GET /system/stats/{metric}` | One statistic per `metric`. |
| `GET /system/stats/claim-stat-ranges` | `GET /system/stats/{metric}` | One statistic per `metric`. |
| `GET /system/stats/claim-stat-snapshots/current` | `GET /system/stats/{metric}` | One statistic per `metric`. |
| `GET /system/stats/country-asset-count` | `GET /system/stats/{metric}` | One statistic per `metric`. |
| `GET /system/stats/identity-count` | `GET /system/stats/{metric}` | One statistic per `metric`. |
| `GET /system/stats/identity-stat-timeseries` | `GET /system/stats/{metric}` | One statistic per `metric`. |
| `GET /system/stats/identity-stat-timeseries/presets/{preset}` | `GET /system/stats/{metric}` | One statistic per `metric`. |
| `GET /system/stats/portfolio-breakdowns` | `GET /system/stats/{metric}` | One statistic per `metric`. |
| `GET /system/stats/portfolio-stat-range-presets/{preset}` | `GET /system/stats/{metric}` | One statistic per `metric`. |
| `GET /system/stats/portfolio-stat-ranges` | `GET /system/stats/{metric}` | One statistic per `metric`. |
| `GET /system/stats/system-value-histories` | `GET /system/stats/{metric}` | One statistic per `metric`. |
| `GET /system/stats/system-value-histories/presets/{preset}` | `GET /system/stats/{metric}` | One statistic per `metric`. |
| `GET /system/stats/topic-scheme-claims-coverage` | None | No v2 operation. The v1 operation `GET /api/v1/system/stats/topic-scheme-claims-coverage` serves it. |
| `GET /system/stats/topic-scheme-stat-range-presets/{preset}` | `GET /system/stats/{metric}` | One statistic per `metric`. |
| `GET /system/stats/topic-scheme-stat-ranges` | `GET /system/stats/{metric}` | One statistic per `metric`. |
| `GET /system/stats/topic-scheme-stat-snapshots/current` | None | No v2 operation. The v1 operation `GET /api/v1/system/stats/topic-schemes-stats-state` serves it. |
| `GET /system/stats/transaction-count` | None | No v2 operation. The v1 operation `GET /api/v1/system/stats/transaction-count` serves it. |
| `GET /system/stats/transaction-history` | None | No v2 operation. The v1 operation `GET /api/v1/system/stats/transaction-history` serves it. |
| `GET /system/stats/trusted-issuer-stat-range-presets/{preset}` | `GET /system/stats/{metric}` | One statistic per `metric`. |
| `GET /system/stats/trusted-issuer-stat-ranges` | `GET /system/stats/{metric}` | One statistic per `metric`. |
| `GET /system/stats/trusted-issuer-stat-snapshots/current` | `GET /system/stats/{metric}` | One statistic per `metric`. |
| `GET /system/stats/value` | `GET /system/stats/{metric}` | One statistic per `metric`. |
| `GET /tokens/{tokenAddress}/external-transaction-fee/collection-events` | None | No 3.2 operation. |
| `PATCH /tokens/{tokenAddress}/features/aum-fee/bps` | `PATCH /tokens/{assetId}/features/{name}` | Send only the settings that change. |
| `PATCH /tokens/{tokenAddress}/features/aum-fee/recipient` | `PATCH /tokens/{assetId}/features/{name}` | Send only the settings that change. |
| `PATCH /tokens/{tokenAddress}/features/conversion-minter/window` | `PATCH /tokens/{assetId}/features/{name}` | Send only the settings that change. |
| `PATCH /tokens/{tokenAddress}/features/external-transaction-fee/amounts` | `PATCH /tokens/{assetId}/features/{name}` | Send only the settings that change. |
| `PATCH /tokens/{tokenAddress}/features/external-transaction-fee/recipient` | `PATCH /tokens/{assetId}/features/{name}` | Send only the settings that change. |
| `PATCH /tokens/{tokenAddress}/features/external-transaction-fee/token` | `PATCH /tokens/{assetId}/features/{name}` | Send only the settings that change. |
| `PATCH /tokens/{tokenAddress}/features/fixed-treasury-yield/treasury` | `PATCH /tokens/{assetId}/features/{name}` | Send only the settings that change. |
| `PATCH /tokens/{tokenAddress}/features/maturity-redemption/treasury` | `PATCH /tokens/{assetId}/features/{name}` | Send only the settings that change. |
| `PATCH /tokens/{tokenAddress}/features/transaction-fee-accounting/rates` | `PATCH /tokens/{assetId}/features/{name}` | Send only the settings that change. |
| `PATCH /tokens/{tokenAddress}/features/transaction-fee-accounting/recipient` | `PATCH /tokens/{assetId}/features/{name}` | Send only the settings that change. |
| `PATCH /tokens/{tokenAddress}/features/transaction-fee/rates` | `PATCH /tokens/{assetId}/features/{name}` | Send only the settings that change. |
| `PATCH /tokens/{tokenAddress}/features/transaction-fee/recipient` | `PATCH /tokens/{assetId}/features/{name}` | Send only the settings that change. |
| `POST /tokens/{tokenAddress}/features/voting-power/delegations/by-signature` | None | No 3.2 operation. |
| `POST /tokens/{tokenAddress}/participant-role-grants` | `POST /tokens/{assetId}/role-sets` | One call grants and revokes. |
| `POST /tokens/{tokenAddress}/participant-role-revocations` | `POST /tokens/{assetId}/role-sets` | One call grants and revokes. |
| `DELETE /tokens/{tokenAddress}/pause-state` | `PATCH /tokens/{assetId}/pause-state` | Send `paused: false`. |
| `POST /tokens/{tokenAddress}/role-grants` | `POST /tokens/{assetId}/role-sets` | One call grants and revokes. |
| `POST /tokens/{tokenAddress}/role-revocations` | `POST /tokens/{assetId}/role-sets` | One call grants and revokes. |
| `GET /tokens/{tokenAddress}/stats/bond-status` | `GET /tokens/{assetId}/stats` | Set `metric=bondStatus`. |
| `GET /tokens/{tokenAddress}/stats/collateral-ratio` | `GET /tokens/{assetId}/stats` | Set `metric=collateralRatio`. |
| `GET /tokens/{tokenAddress}/stats/supply-changes` | `GET /tokens/{assetId}/stats` | Set `metric=supplyChanges`. |
| `GET /tokens/{tokenAddress}/stats/total-supply` | `GET /tokens/{assetId}/stats` | Set `metric=totalSupply`. |
| `GET /tokens/{tokenAddress}/stats/volume` | `GET /tokens/{assetId}/stats` | Set `metric=volume`. |
| `GET /tokens/{tokenAddress}/stats/wallet-distribution` | `GET /tokens/{assetId}/stats` | Set `metric=walletDistribution`. |
| `GET /tokens/{tokenAddress}/stats/yield-coverage` | `GET /tokens/{assetId}/stats` | Set `metric=yieldCoverage`. |
| `GET /tokens/{tokenAddress}/stats/yield-distribution` | `GET /tokens/{assetId}/stats` | Set `metric=yieldDistribution`. |
| `GET /tokens/{tokenAddress}/transaction-fee-accounting/accrual-events` | `GET /tokens/{assetId}/features/transaction-fee-accounting/accrual-events` |  |
| `GET /tokens/{tokenAddress}/transaction-fee-accounting/exemptions` | `GET /tokens/{assetId}/features/transaction-fee-accounting/exemptions` |  |
| `GET /tokens/{tokenAddress}/transaction-fee-accounting/payers/{payer}` | None | No 3.2 operation. |
| `GET /tokens/{tokenAddress}/transaction-fee-accounting/reconciliations` | `GET /tokens/{assetId}/features/transaction-fee-accounting/reconciliations` |  |
| `GET /tokens/{tokenAddress}/transaction-fee/collections` | `GET /tokens/{assetId}/features/transaction-fee/collections` |  |
| `GET /tokens/{tokenAddress}/transaction-fee/payers/{payer}` | None | No 3.2 operation. |
| `DELETE /transaction-requests/{transactionId}` | None | No 3.2 operation. |
| `POST /transaction-requests/{transactionId}/failures` | `POST /transaction-requests/{transactionId}/transitions` | Send `action: fail` with a reason. |
| `PATCH /transaction-requests/{transactionId}/nonce-tracker` | `POST /transaction-requests/{transactionId}/transitions` | Send `action: nonce` with a reason and nonce. |
| `POST /transaction-requests/{transactionId}/retries` | `POST /transaction-requests/{transactionId}/transitions` | Send `action: retry` with a reason. |
| `GET /user-count-metrics` | None | No v2 operation. The v1 operation `GET /api/v1/user/stats/user-count` serves it. |
| `GET /user-growth-metrics` | None | No v2 operation. The v1 operation `GET /api/v1/user/stats/growth-over-time` serves it. |
| `GET /user-metrics` | None | No v2 operation. The v1 operation `GET /api/v1/user/stats` serves it. |
| `DELETE /users/{userId}/multi-factor-authentication` | `POST /users/{userId}/security/transitions` |  |
| `DELETE /users/{userId}/sessions` | `POST /users/{userId}/security/transitions` |  |
| `POST /users/me/wallets` | `POST /custody/accounts/lifecycle` | Wallets are custody accounts. |
| `GET /wallets/{wallet}/user` | `GET /users` | Filter the list by wallet. A wallet can match more than one user. |
| `POST /webhooks/events/{evtId}/recall` | None | No 3.2 operation. |
| `POST /webhooks/{id}/revoke-previous-secret` | `DELETE /webhooks/{webhookId}/secret-rotations/previous` |  |
| `POST /webhooks/{id}/rotate-secret` | `POST /webhooks/{webhookId}/secret-rotations` |  |

## Next steps [#next-steps]

- [Upgrade a deployment to DALP 3.2](https://docs.settlemint.com/docs/deployment/upgrade-to-3-2) lists the steps for the people who run the platform.
- [Versioning and deprecation](https://docs.settlemint.com/docs/api-reference/guides/versioning-and-deprecation) states how v2 changes from 3.2 onward.
- [Errors](https://docs.settlemint.com/docs/api-reference/guides/errors) describes the error envelope and how to decide on a retry.


# Smart wallet user operations

Source: https://docs.settlemint.com/docs/api-reference/guides/user-operations
Estimate, send, replace and track ERC-4337 user operations for a smart wallet through the Platform API or the bundler JSON-RPC endpoint.

A user operation is the signed instruction your client sends for a smart wallet in place of a raw transaction, as the ERC-4337 account-abstraction standard defines it. Most integrations never call these routes: an ordinary platform write from a smart wallet makes the platform build and bundle the user operation itself, as [User operations](https://docs.settlemint.com/docs/concepts/custody-and-signing/user-operations) describes. Use these routes when your client builds and signs user operations itself. A bundler is the service that packs user operations into one transaction and submits it. The platform runs the bundler for your organisation, so you do not run one yourself. You estimate gas, sign the operation and send it. The platform then bundles it, pays for the bundle from the organisation's bundler wallet and records the outcome.

Two interfaces reach the same bundler: the REST routes under `/api/v2/bundler/{chainId}` and the ERC-4337 JSON-RPC endpoint at `/bundler/{chainId}`. `chainId` is the decimal chain ID of the network.

Every read is scoped to the organisation and the network in the path. An operation stored for another organisation or another network reads as `null`.

The examples on this page read `DALP_URL` as your instance's base URL, `CHAIN_ID` as the network's decimal chain ID and `DALP_API_KEY` as a read-write key.

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

- An [API key](https://docs.settlemint.com/docs/api-reference/guides/authentication-api-keys) in the `X-Api-Key` header, for a member of an active organisation. The estimate, send and paymaster routes are declared as writes, so a `read` key receives `DALP-0036` and they need a `read-write` key. The `GET` reads accept either scope.
- A smart wallet the organisation can use on the network. The estimate, send and paymaster routes refuse a sender outside the organisation.
- A network the organisation can use. Its default network qualifies when it is an enabled EVM network. Another network also needs multi-network access and an active deployment on that network. Every route, REST and JSON-RPC, refuses any other network.
- The EntryPoint address for the network, which `GET /api/v2/bundler/{chainId}/supported-entry-points` returns.

## Read the EntryPoint [#read-the-entrypoint]

The EntryPoint is the shared ERC-4337 contract that validates and executes each user operation. Each network has one, and the signature is collected over it, so read it before you prepare an operation.

```bash
curl "$DALP_URL/api/v2/bundler/$CHAIN_ID/supported-entry-points" \
  --header "x-api-key: $DALP_API_KEY"
```

The response is an array with exactly one address. This address is illustrative:

```json
["0x2222222222222222222222222222222222222222"]
```

Submission accepts only that address and refuses any other. Gas estimation and paymaster data also accept the network's configured Directory contract, the platform's registry of system contracts on the network, in its place, and refuse any other address.

## Estimate gas before signing [#estimate-gas-before-signing]

`POST /api/v2/bundler/{chainId}/estimate` takes the EntryPoint and the unsigned operation. The platform simulates the operation and returns the gas limits to put into it before you sign. In the example, `callData` is a placeholder: replace it with the encoded call your smart wallet executes.

```bash
curl --request POST "$DALP_URL/api/v2/bundler/$CHAIN_ID/estimate" \
  --header "x-api-key: $DALP_API_KEY" \
  --header "content-type: application/json" \
  --data '{
    "entryPoint": "0x2222222222222222222222222222222222222222",
    "userOperation": {
      "sender": "0x1111111111111111111111111111111111111111",
      "nonce": "0x0",
      "callData": "0x<encoded call>"
    }
  }'
```

The response holds three gas values. For an operation that names a paymaster, a contract that pays gas for the sender, it also holds `paymasterVerificationGasLimit` and `paymasterPostOpGasLimit`. These numbers are illustrative:

```json
{
  "preVerificationGas": "0x1d4c0",
  "verificationGasLimit": "0x30d40",
  "callGasLimit": "0x186a0"
}
```

The platform simulates the call at the call gas limit it returns, so the call finishes within that limit. A call that does not fit inside one transaction on the network is refused. Over JSON-RPC the message names the gas the call needs and the gas one transaction leaves for it.

The returned `preVerificationGas` is the price `send` checks the signed operation against, so sign that value or a higher one. The price counts the signature, the paymaster data and the fixed-width nonce, gas limit and fee fields at the non-zero rate whatever they hold, so it depends only on the sender, the `initCode`, the `callData` and the lengths of the paymaster data and the signature. A stub signature priced at estimation costs the same as the real signature of the same length, and a nonce, fee or gas limit that changes after the estimate does not move the price. Estimate with a stub as long as the signature you will send, because a longer signature raises the price.

Quantity fields accept a decimal string, a hexadecimal quantity or a non-negative integer. The examples on this page use hexadecimal quantities. The platform reads the upper 192 bits of `nonce` as the nonce key and the lower 64 bits as the sequence within that key.

## Sign the operation [#sign-the-operation]

The platform identifies an operation by its ERC-4337 hash: the EIP-712 hash of the packed operation under the domain name `ERC4337`, version `1`, the network's chain ID and the EntryPoint address. Your client computes this hash itself and signs it before it calls `send`, which returns the same hash. A signature over any other EntryPoint does not match it. The signature format is the one the smart wallet's validator expects, which [Smart Wallet](https://docs.settlemint.com/docs/concepts/custody-and-signing/smart-wallet) describes.

## Send a signed operation [#send-a-signed-operation]

`POST /api/v2/bundler/{chainId}/send` takes the EntryPoint and the signed operation. The operation must carry `callGasLimit`, `verificationGasLimit`, `preVerificationGas`, `maxFeePerGas`, `maxPriorityFeePerGas` and `signature`. A request without one of them is refused. The values in this example are illustrative, and a real signature is longer.

```bash
curl --request POST "$DALP_URL/api/v2/bundler/$CHAIN_ID/send" \
  --header "x-api-key: $DALP_API_KEY" \
  --header "content-type: application/json" \
  --data '{
    "entryPoint": "0x2222222222222222222222222222222222222222",
    "userOperation": {
      "sender": "0x1111111111111111111111111111111111111111",
      "nonce": "0x0",
      "callData": "0x<encoded call>",
      "callGasLimit": "0x186a0",
      "verificationGasLimit": "0x30d40",
      "preVerificationGas": "0x1d4c0",
      "maxFeePerGas": "0x3b9aca00",
      "maxPriorityFeePerGas": "0x5f5e100",
      "signature": "0x4f2a"
    }
  }'
```

The response is the user operation hash:

```json
"0x8c1f0b7a3e5d4c2b1a0f9e8d7c6b5a4f3e2d1c0b9a8f7e6d5c4b3a2f1e0d9c8b"
```

The platform stores the operation and answers with its hash before any bundle exists. Keep the hash for the status and receipt reads. Before it stores the operation, the platform runs these checks in order:

1. The priority fee must reach the deployment's configured minimum. A lower fee is refused. A network whose fee quote is zero for both fee components skips this check.
2. `maxFeePerGas` must reach 1.5 times the base fee of the network's latest block, zero on a network whose blocks carry none, plus the operation's own `maxPriorityFeePerGas`, the same headroom the bundler signs its bundle with. A lower value is refused with `UserOperation maxFeePerGas <signed> is below <floor>, 1.5 times the chain's base fee plus the operation's maxPriorityFeePerGas`, or, on a network whose blocks carry no base fee, `UserOperation maxFeePerGas <signed> is below its own maxPriorityFeePerGas <tip>`. An operation that signs zero for both fee fields on a network whose fee quote is zero for both fee components skips this check and the next one.
3. `preVerificationGas` must reach the gas the bundler pays to carry the operation, the price the estimate returns. The price is 21,000 plus the larger of two sums, over the operation's ABI-encoded bytes with the signature, the paymaster data and the fixed-width nonce, gas limit and fee fields counted as non-zero. The first is 85,800 plus those bytes at 4 gas a zero byte and 16 a non-zero byte, plus 10 gas a 32-byte word. The second is the network's calldata floor over those bytes plus the 132 bytes of the `handleOps` call around them, priced at the floor's non-zero rate. From the Prague fork that floor is 10 gas a zero byte and 40 a non-zero byte (EIP-7623). On the Amsterdam fork it is 64 gas a byte (EIP-7976). A lower value is refused with `UserOperation preVerificationGas <signed> is below <price>, the gas the bundler pays to carry it on this chain`. Both messages print each value as a hexadecimal quantity followed by its decimal value.
4. On a network whose blocks carry a calldata floor, the operation's packed, ABI-encoded size must not exceed the deployment's limit, 8,192 bytes by default, the ERC-7562 limit. A larger operation is refused with `UserOperation is <size> bytes ABI-encoded, above the <limit> bytes the bundler accepts on a chain that charges a calldata floor`. An operation exempt from steps 2 and 3 skips this check too.
5. Validation is simulated with the operation's own paymaster fields, so a sponsored operation is checked as sponsored. A failed simulation is refused, and so is an operation whose account or paymaster keeps it valid for less than 60 seconds from now (`validUntil`): the bundler could not include it in time.
6. The payer must hold enough funds for the prefund: the sum of the operation's gas limits multiplied by its `maxFeePerGas`. A self-paid operation counts the sender's native balance plus its deposit at the EntryPoint. A sponsored operation counts the paymaster's deposit at the EntryPoint. The check adds this operation's prefund to the prefund of the payer's other operations still in flight. A sender that falls short is refused with `AA21`, and a paymaster with `AA31`. To see the shortfall, read the sender's balance and its deposit at the EntryPoint, or the paymaster's deposit. The check is skipped on a network that charges no gas, for an operation whose prefund is zero, and when the platform cannot read the payer's funds.

Two limits answer `429` with code `BUNDLER_ADMISSION_THROTTLED` (`DALP-14439`), or JSON-RPC error `-32504`. Both are worth retrying unchanged:

| `limit` | When | Retry |
| --- | --- | --- |
| `sender-penalty` | A bundle reverted on chain because an operation from this sender became invalid after the platform admitted it, for example because the sender spent the nonce or its funds elsewhere. Checked before the steps above, for every new operation from the sender. | After `retryAfterSeconds`. The window is 24 hours by default. |
| `pending-operations` | The organisation already has the deployment's limit of operations sent through these routes waiting on this network, 256 by default. Checked when the operation is stored. A replacement is not a new operation and is never refused for it. | Once some of the organisation's pending operations have been bundled. |

A sender refusal applies only on the organisation and network whose bundle reverted, and only to the sender of the operation the revert names. The other senders in that bundle are not refused, and their operations go back to waiting. The sender's own other waiting operations fail with an error that names the refusal. Only a revert that names the account's own validation (`AA21`, `AA23`, `AA24`), a nonce another operation already used (`AA25`), or a paymaster the platform does not run (`AA31`, `AA33`, `AA34`) refuses the sender. A revert on the platform's own paymaster refuses no one. To stay clear of it, keep a sender's nonce, balance and EntryPoint deposit unchanged while its operations wait, and do not send the same operation to another bundler.

An operation that signs zero for both fee fields on a network whose fee quote is zero for both fee components skips checks 2, 3 and 4 while the network's latest block carries no base fee. When that block charges a base fee, the operation is refused with `UserOperation signs no fee, but the chain charges a base fee of <fee>`, because no bundle can carry it.

When the bundler builds a bundle, it runs checks 2 and 3 again on each signed operation, against the block it builds on, because the base fee or the network's fork can change after `send` stored the operation:

- An operation whose `maxFeePerGas` is below 1.5 times that block's base fee plus its own `maxPriorityFeePerGas` stays `PENDING` and is checked again at every new block. It joins a bundle once the base fee falls far enough for its `maxFeePerGas` to reach that floor. Later operations from the same sender and nonce key wait behind it. To send it sooner, [replace it](#replace-a-pending-operation) with higher fees. An operation still below the floor an hour after the platform last stored it (when it was sent, replaced, released from `BLOCKED`, or returned by a dropped bundle) becomes `FAILED`.
- An operation whose `preVerificationGas` is below the price at that block can never be carried, for example one stored before the network moved to a fork with a higher calldata floor. It becomes `FAILED`.
- An operation whose `maxFeePerGas` is below its own `maxPriorityFeePerGas` cannot pay at any base fee, and an operation that signs zero for both fee fields cannot be carried on a network whose blocks charge a base fee. Both become `FAILED`.

Each of these failures reads with `error` set to `PRE_FLIGHT_REJECTED`, the code the bundler also uses for an operation it refuses for its size or for a failed bundle simulation. Send a new operation with the estimate's `preVerificationGas` and fees that reach the current floor. An operation that signs zero for both fee fields on a network whose blocks carry no base fee skips the `preVerificationGas` check, because a bundle that carries it is filed at zero fees. Operations the platform prepares itself are priced when they are prepared and are not checked again.

Sending the same signed operation again returns the same hash and stores nothing new. When the stored operation is `PENDING`, the repeat hands it to the bundler again, and the bundler checks it as above. In every other state the repeat returns the hash and changes nothing, so a retry after a lost response is safe. A repeat does not resubmit an operation that failed. Send a new operation with a new signature instead.

## Replace a pending operation [#replace-a-pending-operation]

To reprice an operation that is waiting, send a new signed operation from the same sender with the same nonce to the same `send` route. Both `maxFeePerGas` and `maxPriorityFeePerGas` must reach the original value multiplied by 1.1, rounded down to a whole wei. A successful replacement swaps the stored operation for the new one, and the original hash then reads as `null`.

The platform refuses a replacement in three cases. The JSON-RPC message names each one:

| Case | JSON-RPC message |
| --- | --- |
| The original is already in a bundle. | `A UserOperation for this sender and nonce is already included in a bundle, so it can no longer be replaced` |
| A fee is below 1.1 times the original. | `A replacement UserOperation must raise both maxFeePerGas and maxPriorityFeePerGas by at least 10%` |
| The original was not sent through these routes, or it is `BLOCKED`. | `A UserOperation is already pending for this sender and nonce and cannot be replaced` |

The original's prefund does not count against the payer's funds when the platform checks the replacement.

## Read the status [#read-the-status]

`GET /api/v2/bundler/{chainId}/user-operations/{userOperationHash}` reads the stored operation.

```bash
curl "$DALP_URL/api/v2/bundler/$CHAIN_ID/user-operations/$USER_OPERATION_HASH" \
  --header "x-api-key: $DALP_API_KEY"
```

This response is illustrative. `transactionHash`, `blockNumber` and `error` appear only when the platform has recorded them. In this response `blockNumber`, when present, is a JSON number, while the receipt carries it as a hexadecimal quantity.

```json
{
  "id": "0192f6c0-7b4d-7f2a-9c6e-3f1a2b3c4d5e",
  "userOpHash": "0x8c1f0b7a3e5d4c2b1a0f9e8d7c6b5a4f3e2d1c0b9a8f7e6d5c4b3a2f1e0d9c8b",
  "sender": "0x1111111111111111111111111111111111111111",
  "nonce": "0x0",
  "nonceKey": "0x0",
  "callData": "0x<encoded call>",
  "status": "BUNDLED",
  "createdAt": 1794000000000,
  "updatedAt": 1794000004000,
  "idempotencyKey": "0192f6c0-7b4d-7f2a-9c6e-3f1a2b3c4d5e",
  "transactionHash": "0x3a9e7c1d5b2f4a6e8c0d2b4f6a8e0c2d4b6f8a0e2c4d6b8f0a2e4c6d8b0f2a4e"
}
```

| Status | Meaning |
| --- | --- |
| `PENDING` | The platform has stored the operation and it is not in a bundle. |
| `BLOCKED` | The operation waits, for example on an approval or on funds. |
| `BUNDLED` | The operation is in a bundle the platform has built. The bundle may still be on its way to the network. |
| `MINED` | The bundle is on chain. The operation either succeeded or reverted, and the receipt tells you which. |
| `FAILED` | The operation does not execute. `error` holds the reason when the platform recorded one. |

Stop polling at `MINED` or `FAILED`. The schema in the API explorer also lists `PREPARING`, `SUBMITTING`, `CONFIRMED` and `EXPIRED`, which this route does not return. A `MINED` operation whose call reverted carries the revert data in `error`. The platform does not re-sign it with more gas, so send a new operation instead.

An operation can stay `BUNDLED` while an earlier transaction of the bundler wallet is missing, because the chain mines the wallet's transactions in order. The platform fills a skipped nonce itself with a zero-value transfer from the wallet to itself, so a skipped nonce does not block later bundles permanently. No call on your side is needed, and resending the operation does not speed it up. See [what happens to a nonce the bundler skipped](https://docs.settlemint.com/docs/concepts/custody-and-signing/user-operations#what-happens-to-a-nonce-the-bundler-skipped).

## Read the receipt [#read-the-receipt]

`GET /api/v2/bundler/{chainId}/user-operations/{userOperationHash}/receipt` returns the on-chain outcome.

```bash
curl "$DALP_URL/api/v2/bundler/$CHAIN_ID/user-operations/$USER_OPERATION_HASH/receipt" \
  --header "x-api-key: $DALP_API_KEY"
```

The response is `null` until the operation has settled on chain as confirmed or reverted. It is also `null` for a hash the organisation does not hold on that network. This response is illustrative:

```json
{
  "userOpHash": "0x8c1f0b7a3e5d4c2b1a0f9e8d7c6b5a4f3e2d1c0b9a8f7e6d5c4b3a2f1e0d9c8b",
  "sender": "0x1111111111111111111111111111111111111111",
  "nonce": "0x0",
  "success": true,
  "transactionHash": "0x3a9e7c1d5b2f4a6e8c0d2b4f6a8e0c2d4b6f8a0e2c4d6b8f0a2e4c6d8b0f2a4e",
  "blockHash": "0x5d7f9b1e3c5a7d9f1b3e5c7a9d1f3b5e7c9a1d3f5b7e9c1a3d5f7b9e1c3a5d7f",
  "blockNumber": "0x1a2b3c"
}
```

`success` is `false` when the call reverted, and `reason` then carries the revert data. Your operation succeeded when the receipt is present and `success` is `true`.

## Use the ERC-4337 JSON-RPC endpoint [#use-the-erc-4337-json-rpc-endpoint]

`POST /bundler/{chainId}` speaks the ERC-4337 bundler protocol. It takes the same `X-Api-Key` header and applies the same sender, EntryPoint and network rules as the REST routes. Every method needs a read-write key, the reads and `eth_chainId` included: the endpoint refuses a `read` key with HTTP 403, a JSON-RPC error whose `data.id` is `DALP-0036`, and `data.retryable` set to `false`.

It supports these methods:

- `eth_chainId`
- `eth_supportedEntryPoints`
- `eth_estimateUserOperationGas`
- `eth_sendUserOperation`
- `eth_getUserOperationByHash`
- `eth_getUserOperationReceipt`
- `pm_getPaymasterStubData`
- `pm_getPaymasterData`

```bash
curl --request POST "$DALP_URL/bundler/$CHAIN_ID" \
  --header "x-api-key: $DALP_API_KEY" \
  --header "content-type: application/json" \
  --data '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "eth_getUserOperationReceipt",
    "params": ["0x8c1f0b7a3e5d4c2b1a0f9e8d7c6b5a4f3e2d1c0b9a8f7e6d5c4b3a2f1e0d9c8b"]
  }'
```

The answer is a JSON-RPC 2.0 envelope whose `result` holds the receipt from the receipt route, or `null`. The two read methods return the shapes this page shows for the REST reads. The receipt has no gas-used, gas-cost or log fields, and `eth_getUserOperationByHash` returns the stored operation, so a standard ERC-4337 client library that parses the full receipt or operation object does not parse these shapes. Map them in your client.

`eth_sendUserOperation` and `eth_estimateUserOperationGas` take the user operation and the EntryPoint address as their two parameters. The two paymaster methods take the user operation, the EntryPoint, the chain ID and a context value. Their chain ID must match the network in the path. They answer only when the organisation pays gas on that network through a paymaster, and otherwise refuse with `Paymaster sponsorship is not enabled`. The REST route `POST /api/v2/bundler/{chainId}/paymaster-data` returns the same paymaster data as `pm_getPaymasterData`. `pm_getPaymasterStubData` returns the same fields with a placeholder signature, for gas estimation only: an operation sent with it fails validation. Only `pm_getPaymasterData` and the REST route sign a ticket.

A batch holds 1 to 100 requests. A request or batch that holds only notifications answers HTTP 204 with no body. A `GET` on the endpoint answers HTTP 405.

## Refusals [#refusals]

The two interfaces report the same refusal in different detail. A REST route answers with the platform's error envelope: an HTTP status, a stable `code` and the catalogue message for that code. The JSON-RPC endpoint answers with a JSON-RPC error whose `message` carries the specific reason. The messages this page quotes are JSON-RPC messages. Over REST, branch on the HTTP status and `code`:

| Refusal | REST answer | JSON-RPC answer |
| --- | --- | --- |
| A missing field, a priority fee below the minimum, a `maxFeePerGas` below its floor, pre-verification gas below its price, the EntryPoint, the sender, a network the organisation cannot use, a replacement, an unsponsored paymaster call, or a simulation failure with no ERC-4337 code | HTTP 400 `TRANSACTION_QUEUE_INPUT_INVALID` | The specific reason in `error.message` |
| A simulation or prefund failure with an ERC-4337 code such as `AA21` | HTTP 422 `AA_VALIDATION_FAILED` | `error.message` is "Failed op" or "Failed op with revert", and `error.data.aaCode` holds the code |
| The organisation's sponsorship policy refuses the paymaster data, or the sponsorship ticket expired | HTTP 403 `PAYMASTER_SPONSORSHIP_DENIED` | `error.code` is `-32501` and `error.message` carries the reason |

The REST answer does not name the ERC-4337 code. To read it, send the same operation to `eth_sendUserOperation` on the JSON-RPC endpoint. If the operation passes this time, that call stores and bundles it.

Most of these refusals are caller errors: fix the field before you send again. Two can clear without a change to the request. A prefund refusal counts the payer's other operations still in flight, so it can pass once those settle or once you fund the payer. A network whose deployment is not active refuses until the deployment finishes. The REST routes answer that case with HTTP 400 `TRANSACTION_QUEUE_INPUT_INVALID`. The JSON-RPC endpoint answers it with HTTP 409 and a JSON-RPC error whose `data.retryable` is `false`: a retry does not help, so check the network's status in organisation settings and send again once it is active.

## Next steps [#next-steps]

- [User operations](https://docs.settlemint.com/docs/concepts/custody-and-signing/user-operations) explains how the platform bundles and settles operations, including one a bundle did not execute.
- [Smart Wallet](https://docs.settlemint.com/docs/concepts/custody-and-signing/smart-wallet) explains the validators, signer weights and threshold that authorise an operation.
- [Operator Wallet](https://docs.settlemint.com/docs/concepts/custody-and-signing/operator-wallet) explains the bundler wallet that pays for each bundle.
- [The v2 API explorer](https://docs.settlemint.com/docs/api-reference/v2) holds the full request and response schema for each route.


# Versioning and deprecation

Source: https://docs.settlemint.com/docs/api-reference/guides/versioning-and-deprecation
Breaking API changes ship only on a new /api version, and a deprecated operation answers with Deprecation and Sunset headers for at least 90 days.

## The policy [#the-policy]

An integration built against a released Platform API version keeps working when you upgrade the platform. From DALP 3.2, DALP does not remove an operation from a released version, or change one incompatibly, inside that version. A breaking change ships only on a new version, such as `/api/v3`, next to the version you already call. An operation or a whole version is removed only after a deprecation announcement that gives at least 90 days' notice. `/api/v2` became a released version in DALP 3.2, so the v2 changes that 3.2 made fall outside this policy. DALP 3.2 also changed v1 without that notice: it removed three operations, the `wallet` field of v1 user reads, the `gasPrice` and `gasUsed` fields of v1 user events and the `defined` field of error bodies, as [Upgrade an integration to DALP 3.2](https://docs.settlemint.com/docs/api-reference/guides/upgrade-to-3-2) lists.

Each version path is a separate contract:

| Version | Status | Contract rule |
| --- | --- | --- |
| `/api/v1` | Stable since DALP 3.0 | Structure frozen: paths, methods, inputs and success responses, apart from the DALP 3.2 changes that [Upgrade an integration to DALP 3.2](https://docs.settlemint.com/docs/api-reference/guides/upgrade-to-3-2) lists |
| `/api/v2` | Stable from DALP 3.2 | The same rule as v1 from the 3.2 release |

Before a version is released, it can still change between development builds, and every such change is listed in the release notes. From its first release onward, the rule on this page holds for as long as the version is served. [Upgrade an integration to DALP 3.2](https://docs.settlemint.com/docs/api-reference/guides/upgrade-to-3-2) lists the v2 changes between DALP 3.1 and the 3.2 release.

## What counts as a breaking change [#what-counts-as-a-breaking-change]

A change is breaking when a client that worked against the previous release can fail against the new one without changing its own code. A released version does not take these changes:

- Removing a path, or a method on a path.
- Adding a required input: a path, query, or header parameter, or a request body field.
- Removing or narrowing an accepted input, such as dropping an enum value or tightening a format.
- Removing a field from a success response, or changing its type.

Before each release, DALP compares the paths, methods, inputs and success responses of version 1 with a sealed copy of its contract. For version 2, it compares the contract it publishes with the contract already served, and refuses a removed path or method, a removed parameter, an input that becomes required, and a removed response status. Either comparison lets a difference through only when the maintainers record it as an accepted change with its reason, which is how the DALP 3.2 changes to version 1 shipped. The version 2 comparison does not read the values an input accepts or the fields of a response, so those two rules depend on review.

These changes are not breaking, and ship inside a released version:

- A new operation, or a new optional input on an existing one.
- A new field in a success response. Ignore response fields your client does not know. A strict decoder that rejects unknown fields breaks on a change DALP treats as compatible.
- A new error on an existing operation, for example a new rejection when a request conflicts with platform state. Handle errors by their class and the `retryable` flag, as [Errors](https://docs.settlemint.com/docs/api-reference/guides/errors) describes, so a new error code reaches a branch your client already has.
- Changes to descriptions, examples, summaries, and operation tags in the OpenAPI document.

## How a deprecation is announced [#how-a-deprecation-is-announced]

A deprecated operation keeps working until its sunset date, and tells you on every response that it is going away. DALP announces a deprecation in two places at the same time: on the wire, and in the OpenAPI contract.

On the wire, every response from a deprecated operation carries three headers. That includes error responses, such as a rate-limit refusal, so a client sees the notice whatever the request outcome.

| Header | Standard | Value |
| --- | --- | --- |
| `Deprecation` | RFC 9745 | The date the deprecation was announced, as `@` and Unix seconds: `@1799971200` |
| `Sunset` | RFC 8594 | The first day the operation can stop answering, as an HTTP date: `Thu, 15 Apr 2027 00:00:00 GMT` |
| `Link` | RFC 8288 | This policy as `rel="deprecation"`, and each replacement path as `rel="successor-version"` |

An illustrative full set of headers on one response:

```http
Deprecation: @1799971200
Sunset: Thu, 15 Apr 2027 00:00:00 GMT
Link: <https://docs.settlemint.com/docs/api-reference/guides/versioning-and-deprecation>; rel="deprecation"; type="text/html", </api/v2/example-operation-next>; rel="successor-version"
```

`Sunset` is omitted while no sunset date is set. The API exposes all three headers to browser clients through cross-origin resource sharing (CORS), so a web application can read them as well as a server integration.

In the OpenAPI contract, the operation carries `deprecated: true`, documents the same headers on its success responses (`Sunset` only when a sunset date is set), and holds the announcement in the `x-dalp-deprecation` extension:

```json
{
  "deprecated": true,
  "x-dalp-deprecation": {
    "deprecatedAt": "2027-01-15",
    "sunsetAt": "2027-04-15",
    "successors": ["/api/v2/example-operation-next"]
  }
}
```

Check how the client generator you use treats `deprecated: true`. The contract flag, the announcement and the headers come from one declaration, so they never disagree.

## The notice window [#the-notice-window]

The sunset date is at least 90 days after the deprecation date. DALP refuses a deprecation declared with a sunset date less than 90 days after its announcement date, so no release can announce a shorter window. The rule covers a declared deprecation: the DALP 3.2 changes to version 1 shipped without one.

[Figure] The lifecycle of a deprecated API operation. A current operation is deprecated on an announced date. From then on every response carries the Deprecation, Sunset, and Link headers, and the contract marks it deprecated. At least 90 days later, on the sunset date, a release can remove it. A breaking replacement ships on a new API version. Labels: Operation lifecycle; Current; Changes stay compatible; Headers on every answer; Deprecated; Deprecation, Sunset, Link; At least 90 days; Sunset; A release can remove it; Replacement lives on its successor path.

_An operation moves from current to deprecated on the announcement date, and cannot be removed until its sunset date, at least 90 days later._

The 90-day window is a minimum. DALP can keep a deprecated operation past its sunset date, and a later release can move the sunset further out. It never moves it closer than 90 days after the announcement.

The same window applies to a whole version. When a version is deprecated, every operation it serves answers with the headers. Routes under `/api/auth`, which each version's OpenAPI document also lists, do not carry them. The version path is removed only after its own sunset date.

## Find deprecated operations [#find-deprecated-operations]

The OpenAPI document of a version marks every deprecated operation of that version `deprecated: true`. The `/api/auth` routes it also lists are not marked, even when the version is deprecated, so the command omits them. This command prints one line per deprecated operation, with its sunset date and replacement paths. The request is illustrative: replace the host with your deployment.

```bash
curl -s "https://your-instance.example.com/api/v2/spec.json" | jq -r '
  .paths | to_entries[] | .key as $path | .value | to_entries[]
  | select(.value | type == "object" and .deprecated == true)
  | "\(.key | ascii_upcase) \($path) sunset \(.value["x-dalp-deprecation"].sunsetAt // "none") successors \((.value["x-dalp-deprecation"].successors // []) | join(","))"'
```

For example, with an illustrative operation:

```text
GET /api/v2/example-operation sunset 2027-04-15 successors /api/v2/example-operation-next
```

The command prints nothing when the version has no deprecated operation. Run it with `/api/v1/spec.json` to check the first version too.

## What your integration should do [#what-your-integration-should-do]

Watch for the `Deprecation` header in the client you use against DALP, and treat it as a work item rather than an error. Log the method, path, and `Sunset` value once per operation, so the notice reaches a person before the sunset date.

When you see the headers:

1. Read the `successor-version` links for the replacement path.
2. Check the release notes for the release that announced the deprecation. Its compatibility section names the operation and the change.
3. Move your calls to the successor before the sunset date, and test against a DALP build that still serves both.

After the sunset date, a release can remove the operation. A call to a removed path fails as a route that does not exist.

## How releases record API changes [#how-releases-record-api-changes]

Every release entry has a compatibility section, which DALP 3.0 calls Breaking changes and migration. It names each deprecation the release announces, with its sunset date and replacement, and each operation or version the release removes after its sunset. A new version is announced in the release that makes it stable. See the [changelog](https://docs.settlemint.com/docs/changelog) for each release.

## Next steps [#next-steps]

- [Upgrade an integration to 3.2](https://docs.settlemint.com/docs/api-reference/guides/upgrade-to-3-2) for every v2 change 3.2 made that can break a 3.1 or 3.0 client, including the reads it widened and what a strict decoder needs.
- [Errors](https://docs.settlemint.com/docs/api-reference/guides/errors) for the error class and `retryable` flag that keep a client working when an operation gains a new error.
- [V2 API reference](https://docs.settlemint.com/docs/api-reference/v2) and [V1 API reference](https://docs.settlemint.com/docs/api-reference/v1) for each operation's contract, including its deprecation status.


# Receive webhooks

Source: https://docs.settlemint.com/docs/api-reference/guides/webhooks
Register an HTTPS endpoint, verify signed DALP webhook deliveries, send a test event, rotate signing secrets, and update, switch off or delete an endpoint.

## Overview [#overview]

Webhooks send DALP platform events as signed POST requests to an HTTPS endpoint, an address your integration registers to receive them, so your system learns of each event without polling the Platform API. The routes on this page register an endpoint, verify its signatures, send test events, rotate the signing secret, and update, switch off or delete the endpoint. The [webhooks reference](https://docs.settlemint.com/docs/api-reference/webhooks) covers which events the platform sends and how to consume them. The Console offers the same endpoint controls under [Webhooks](https://docs.settlemint.com/docs/console/organisation-settings/webhooks).

DALP uses [Standard Webhooks](https://www.standardwebhooks.com) headers and signing. Verify the signature before you trust a delivery. Deliveries can repeat, and the [consumer contract](https://docs.settlemint.com/docs/api-reference/webhooks/consuming#identifiers-and-deduplication) defines the identifiers to store and deduplicate.

Every route on this page needs a caller with webhook management permission, which the Owner role holds, and an active organisation. The [authentication guide](https://docs.settlemint.com/docs/api-reference/guides/authentication-api-keys) describes the accepted credentials.

## Register an endpoint [#register-an-endpoint]

`POST /api/v2/webhooks` creates an endpoint. The URL must be a public HTTPS address unless the deployment operator has configured an exception for private-network receivers. The platform refuses private or loopback destinations without that exception. The [webhook management API](https://docs.settlemint.com/docs/api-reference/v2) defines the complete request and response.

```bash
curl -X POST "https://your-instance.example.com/api/v2/webhooks" \
  -H "X-Api-Key: sm_dalp_..." \
  -H "Idempotency-Key: webhook-create-001" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://webhooks.example.com/dalp",
    "displayName": "Settlement notifications"
  }'
```

The platform answers `200` with the endpoint:

```json
{
  "data": {
    "id": "0199c4e2-5b7a-7d10-9a3e-2f61c8b04d17",
    "tenantId": "org_7Hq2kWm9",
    "systemId": "0x5fbdb2315678afecb367f032d93f642f64180aa3",
    "url": "https://webhooks.example.com/dalp",
    "displayName": "Settlement notifications",
    "subscriptions": ["*.provisional", "*.final", "*.retracted"],
    "defaultPayloadShape": "thin",
    "counterSignedReceipts": false,
    "receiptTimeoutSeconds": 30,
    "breakerState": "closed",
    "disabledAt": null,
    "disabledReason": null,
    "fatEventsAcknowledgment": null,
    "secret": {
      "activeVersion": 1,
      "previousVersion": null,
      "previousRevokesAt": null,
      "lastUsedAt": null
    },
    "createdAt": "2026-11-09T08:14:05.000Z",
    "updatedAt": "2026-11-09T08:14:05.000Z",
    "version": 1,
    "createdByUserId": "usr_4Fp8nQx2",
    "signingSecret": "dalp_whsk_sample_not_a_live_secret"
  },
  "links": {
    "self": "/api/v2/webhooks/0199c4e2-5b7a-7d10-9a3e-2f61c8b04d17"
  }
}
```

`data.id` is the `{webhookId}` that every later route on this page takes. The first response includes `signingSecret`. Store it immediately, because a later endpoint read never returns it. Retrying the same registration body with the same `Idempotency-Key` returns the existing endpoint with `signingSecret: null`, not a second endpoint. A changed body under that key returns `409 WEBHOOK_IDEMPOTENCY_KEY_REUSED`. A repeat while registration is still running returns `409 WEBHOOK_CREATE_IN_PROGRESS`. If the original response was lost, read the endpoint and rotate its secret to obtain a new one.

A System is an organisation's on-chain DALP deployment. Without a deployed System the platform answers `404 WEBHOOK_SYSTEM_SCOPE_REQUIRED`. An organisation can hold at most 1,000 endpoints across all its networks, and a further registration answers `409 WEBHOOK_ENDPOINT_LIMIT_REACHED`. An endpoint that is switched off still counts toward that limit, and a deleted endpoint does not. A new endpoint receives only events that happen after its creation: for chain events, the blocks from the chain head at that moment onwards. Earlier history is never sent to it.

When `subscriptions` is omitted, the platform applies the [default subscriptions](https://docs.settlemint.com/docs/api-reference/webhooks/subscriptions#default-subscriptions). Those patterns match event name suffixes, not lifecycle states. Check the [events the defaults skip](https://docs.settlemint.com/docs/api-reference/webhooks/subscriptions#events-the-default-subscriptions-do-not-deliver) before choosing the full subscription list for your integration.

To track an on-chain write from broadcast to its outcome, subscribe to `transaction.request.*`. The default subscriptions skip this family, because its names, such as `transaction.request.confirmed`, do not end in `.final`. The [transaction request catalogue](https://docs.settlemint.com/docs/api-reference/webhooks/events#transaction-request) describes its five events.

Every new endpoint starts with the `thin` payload shape, which removes personal data fields. To receive those fields, register the endpoint first, then update it to `fat` with the required acknowledgement. The [payload shape contract](https://docs.settlemint.com/docs/api-reference/webhooks/consuming#payload-shape) defines that acknowledgement.

## The event envelope [#the-event-envelope]

Every delivery contains an event envelope with `evt_id`, `type`, `version`, `lifecycle_state`, `related` resource references and a typed `payload`, and every delivery except a test event carries `source_id`. A retraction adds `supersedes`, a Replay sets `is_replay`, and a test event sets `is_test`. `request.idempotency_key` appears when the platform can attribute the transaction to one caller key. The [consumer contract](https://docs.settlemint.com/docs/api-reference/webhooks/consuming#identifiers-and-deduplication) defines each identifier. The [machine-readable event definitions](https://docs.settlemint.com/.well-known/dalp-events.json) and [TypeScript SDK](https://docs.settlemint.com/docs/api-reference/sdk) define the payloads. The [event catalogue](https://docs.settlemint.com/docs/api-reference/webhooks/events) explains when each event is sent and what your receiver does with it.

A `token.transfer.final` delivery for one leg of a venue trade carries this body:

```json
{
  "evt_id": "evt_a4eac9d5432394cd91b380838ddbd4a5",
  "source_id": "chain:537001:0xcccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc:7:0:token.transfer.final@2",
  "type": "token.transfer.final",
  "version": 2,
  "lifecycle_state": "final",
  "payload": {
    "tokenAddress": "0x5555555555555555555555555555555555555555",
    "chainId": 537001,
    "from": "0x6666666666666666666666666666666666666666",
    "to": "0x7777777777777777777777777777777777777777",
    "amount": "250000000000000000000",
    "transactionHash": "0xcccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc",
    "blockNumber": 18445240,
    "logIndex": 7,
    "occurredAt": "2026-09-28T09:18:00.000Z",
    "venueTrade": {
      "tradeId": "0x2222222222222222222222222222222222222222222222222222222222222222",
      "leg": "base",
      "marketId": "0x1111111111111111111111111111111111111111111111111111111111111111",
      "venueAddress": "0x9999999999999999999999999999999999999999"
    }
  },
  "related": {
    "idxr_token": "0x5555555555555555555555555555555555555555"
  }
}
```

To follow bank payments, subscribe to `bank-rail.credit.*` or `bank-rail.cash-out.*`. The defaults skip these milestone names. Events report committed statuses with decimal bank amounts, currency and `occurredAt`. Approval and loss-accounting details stay private. See the [bank rail catalogue](https://docs.settlemint.com/docs/api-reference/webhooks/events#bank-rail) for the credit, recall and payout return rules.

## Verify the signature [#verify-the-signature]

The platform sends three Standard Webhooks headers and two DALP headers:

| Header | Contents |
| --- | --- |
| `webhook-id` | The event id, equal to `evt_id`. |
| `webhook-timestamp` | Unix seconds when the platform signed the request. |
| `webhook-signature` | The signature over `webhook-id`, `webhook-timestamp`, and the raw body. |
| `webhook-delivery-id` | The identifier of this delivery attempt. |
| `webhook-endpoint-id` | The endpoint this delivery targets. |

Verify the exact raw body against your stored signing secret before you parse or trust the payload. The verifier is exported as `verifyWebhook` from `@settlemint/dalp-sdk/verify-webhook`. It accepts timestamps within five minutes of your clock by default, and its `timestampToleranceSeconds` option changes that tolerance. The platform re-signs a stored envelope before an attempt when its signature is at least four minutes old, so a delivery that waited in backoff still arrives inside the five-minute window. Keep your receiver's clock synchronised.

A receiver verifies the request, stores the event, and answers `2xx`. Here `secrets` holds the active signing secret, and the previous one during a rotation, and `storeEvent` stands for your own durable store:

```ts
import { verifyWebhook } from "@settlemint/dalp-sdk/verify-webhook";

export async function receive(request: Request, secrets: ReadonlyArray<string>): Promise<Response> {
  const result = await verifyWebhook({
    rawBody: await request.text(),
    headers: request.headers,
    secret: secrets,
  });
  if (!result.ok) {
    return new Response(result.code, { status: 401 });
  }
  await storeEvent(result.event);
  return new Response(null, { status: 204 });
}
```

On success `verifyWebhook` returns `{ ok: true, event, release }`. On failure it returns `{ ok: false, code }`, where `code` is `TIMESTAMP_SKEW`, `SECRET_MISMATCH`, `BODY_HASH_MISMATCH` or `MALFORMED_BODY`. With a replay store, `code` can also be `REPLAYED_EVENT` or `REPLAY_STORE_FAILURE`. The verifier strips the `dalp_whsk_` prefix from each secret itself. A `4xx` answer other than `408` or `429` ends delivery of the event, so a receiver whose clock drifts, or that drops the previous secret too early, loses events until you recover them with Resend or Replay.

### Refuse a repeated delivery [#refuse-a-repeated-delivery]

The platform can send one event more than once. A retry and a Resend keep the `webhook-id` of the first attempt. With the optional `replayStore`, the verifier accepts each `webhook-id` once and refuses the copies that follow.

A store has two methods. The verifier makes a new claim id for each request and gives it to both methods. `claim(eventId, claimId)` records the event id with the claim id. It returns `true` only when no record for that event id exists. `release(eventId, claimId)` removes the record only while the record still holds that claim id. The verifier adds no locking of its own. Your `claim` must check and record the id in one atomic write, such as a Redis `SET` with `NX` that stores the claim id. A read followed by a separate write lets two copies that arrive together both pass. Your `release` must compare the claim id and delete the record in one atomic step, such as a short Lua script in Redis. Keep each record for at least the three-day retry window. A record that expires sooner lets a later retry run your handler again. A Resend also keeps the `webhook-id`, and an operator can send one until the platform deletes the delivery history, 30 days after delivery ended. When a Resend must not run your handler again, keep each record for that long.

The verifier checks the timestamp, the signature and the JSON body first. A request that fails one of these checks never reaches the store, so a request without a valid signature never answers `REPLAYED_EVENT`. The verifier then claims the event id:

- When the id is already claimed, the verifier returns `REPLAYED_EVENT`. Answer with a `2xx`, so the platform stops sending that copy. When your endpoint requires counter-signed receipts, submit a receipt for that delivery too.
- When `claim` throws, the verifier tries to release its claim id, ignores an error from that call, and returns `REPLAY_STORE_FAILURE`. Answer with a `5xx`, so the platform retries. When that release works, a claim that the store recorded before it threw is removed, and the retry can verify. When that release also fails, the claim stays.

When your handler fails, call `release` on the verified result before you answer `5xx`. It removes the claim of this request only. The platform retries with the same `webhook-id`, and the retry verifies again. Call `release` only when you answer with a status that the platform retries. When you answer `2xx`, keep the claim, so a later copy does not run your handler again. Without a replay store, `release` does nothing.

```ts
import { verifyWebhook, type WebhookReplayStore } from "@settlemint/dalp-sdk/verify-webhook";

export async function receive(
  request: Request,
  secrets: ReadonlyArray<string>,
  replayStore: WebhookReplayStore
): Promise<Response> {
  const result = await verifyWebhook({
    rawBody: await request.text(),
    headers: request.headers,
    secret: secrets,
    replayStore,
  });
  if (!result.ok) {
    if (result.code === "REPLAYED_EVENT") {
      return new Response(null, { status: 204 });
    }
    return new Response(result.code, { status: result.code === "REPLAY_STORE_FAILURE" ? 503 : 401 });
  }
  try {
    await storeEvent(result.event);
  } catch {
    await result.release();
    return new Response(null, { status: 503 });
  }
  return new Response(null, { status: 204 });
}
```

A claim holds while your handler runs. The platform ends an attempt that gets no answer within 20 seconds and retries it later. A retry that arrives while your handler still runs returns `REPLAYED_EVENT`, and your `2xx` acknowledges it even when the handler then fails. A claim also stays when your process stops before it calls `release`, when `release` throws, or when the verifier cannot release its claim after `claim` throws. The next copy of that event is then acknowledged without being processed. Log the `webhook-id` before you answer `5xx` for `REPLAY_STORE_FAILURE` or after a `release` that throws.

To recover such an event, delete its id from your store and then Resend the delivery. A Resend keeps the `webhook-id`. A Replay also recovers the event, because it sends the event under a new `webhook-id`. When you cannot accept these cases, do not use a replay store. Record the `webhook-id` in the same transaction as your own writes, and acknowledge an id that is already there.

## Send a test event [#send-a-test-event]

`POST /api/v2/webhooks/{webhookId}/test-events` queues a test event for one endpoint, whatever its subscriptions. The optional body field `eventType` names the event, and it defaults to `webhook.test.final`. The envelope carries `is_test: true` and the payload `{ "test": true }`, so your receiver can check its signature verification without acting on a real event.

A test event also reaches an endpoint that is switched off. It never counts toward the circuit breaker, which switches an endpoint off after 30 failed attempts in a row. Each API server accepts at most 10 test events a minute for an endpoint and at most 100 for an organisation, because each server counts its own requests. A request over either limit answers `429 WEBHOOK_REPLAY_RATE_LIMITED`, the code the replay limit also uses.

## Rotate the signing secret [#rotate-the-signing-secret]

`POST /api/v2/webhooks/{webhookId}/secret-rotations` returns a new `signingSecret` and keeps the previous secret valid for 24 hours. During that overlap, the platform signs deliveries with both secrets, and `webhook-signature` holds both signatures. Store the new secret immediately, then accept either secret until `previousRevokesAt` passes.

Rotation does not replay its original response for the same `Idempotency-Key`. Another rotation creates another secret and revokes any older previous secret immediately. After an uncertain rotation response, read the endpoint with `GET /api/v2/webhooks/{webhookId}` before deciding whether to rotate again. Its `secret` object returns `activeVersion`, `previousVersion` and `previousRevokesAt`, never secret material.

`DELETE /api/v2/webhooks/{webhookId}/secret-rotations/previous` ends the overlap early. The platform refuses it until a delivery signed with the new secret has succeeded, so send a test event first.

## Update an endpoint [#update-an-endpoint]

`PATCH /api/v2/webhooks/{webhookId}` changes `url`, `displayName`, `subscriptions`, `defaultPayloadShape`, `fatEventsAcknowledgment`, `counterSignedReceipts`, `receiptTimeoutSeconds`, `disabled` and `disabledReason`. Every field is optional, and the platform leaves an omitted field untouched. Supplying `subscriptions` replaces the full stored list. The [subscriptions reference](https://docs.settlemint.com/docs/api-reference/webhooks/subscriptions) defines valid patterns.

A switch to `fat`, or a subscription change on a fat endpoint, requires `fatEventsAcknowledgment` to cover every personal data field the resulting subscriptions imply. Payload shape changes affect new events only. The [payload shape contract](https://docs.settlemint.com/docs/api-reference/webhooks/consuming#payload-shape) covers the fields and stored payloads.

Changing `url` retargets pending deliveries. The platform refuses the change while deliveries are pending unless you send `?acknowledgePending=true`. A subscription-only change does not require that acknowledgement.

To keep an update from overwriting a change saved after you read the endpoint, send the endpoint's `version` as `expectedVersion`. Every endpoint response carries it as the top-level `version`, which starts at 1 and rises by one with each update that sets at least one field, even to the value already stored. It is not `secret.activeVersion`, which numbers the signing secret. Rotating the signing secret and the circuit breaker switching the endpoint off or back on leave `version` unchanged, so a matching `version` does not prove the endpoint is still on or off: read `breakerState` and `disabledAt` again before you send `disabled`. Without `expectedVersion` the platform applies the update to whatever is stored, so the last update wins.

When `expectedVersion` differs from the stored `version`, the platform refuses the update with `409 WEBHOOK_ENDPOINT_VERSION_CONFLICT` (DALP-0542) and changes nothing. The response does not include the stored `version`, and sending the same request again fails the same way. Read the endpoint, apply your change to what it returns, and send its `version` as `expectedVersion`. The Console's "Edit endpoint" sheet always sends `expectedVersion`.

## Switch off or delete an endpoint [#switch-off-or-delete-an-endpoint]

Setting `disabled` to `true` cancels the endpoint's queued deliveries and needs `?acknowledgePending=true` while deliveries are pending. Events that happen while the endpoint is off are not queued for it, and neither Resend nor Replay recovers them later. Setting `disabled` to `false` enables the endpoint again and resets its circuit breaker.

`DELETE /api/v2/webhooks/{webhookId}` switches the endpoint off permanently and cancels its queued deliveries, including scheduled retries. Its delivery history stays readable until the [retention cleanup](https://docs.settlemint.com/docs/api-reference/webhooks/consuming#delivery-history-retention) removes it.

## Next steps [#next-steps]

- [Retries](https://docs.settlemint.com/docs/api-reference/webhooks/consuming#retries) defines response classes, backoff, and the retry window.
- [Resend and replay](https://docs.settlemint.com/docs/api-reference/webhooks/consuming#resend-and-replay) covers recovery after an endpoint failure.
- [Counter-signed receipts](https://docs.settlemint.com/docs/api-reference/webhooks/consuming#counter-signed-receipts) defines the optional signed acknowledgement.
- [Chain of custody](https://docs.settlemint.com/docs/api-reference/webhooks/consuming#chain-of-custody) reads the recorded dispatch history of one event.
- [Errors](https://docs.settlemint.com/docs/api-reference/guides/errors) covers the error envelope a failed webhook management call returns.


# Overview

Source: https://docs.settlemint.com/docs/api-reference
Authenticate, generate a client, and integrate the DALP Platform API through guides, the CLI, the OpenAPI explorer, and the error catalogue.

The DALP Platform API lets integrations manage assets, participants, compliance, and settlement. Call it directly, use the [TypeScript SDK](https://docs.settlemint.com/docs/api-reference/sdk), or run CLI commands. An integration sends an API key in the `X-Api-Key` header, and [Authentication and API keys](https://docs.settlemint.com/docs/api-reference/guides/authentication-api-keys) covers creating one. These pages cover authentication, retries, errors, and event handling. The API explorer supplies request and response schemas for each route.

The asset issuance routes create a [composable token](https://docs.settlemint.com/docs/concepts/modeling-assets/composable-token): one token contract on an EVM network, composed from extensions and token features.

## Public API paths [#public-api-paths]

DALP serves the current REST API at `/api/v2`, with its OpenAPI contract at `/api/v2/spec.json`. Point new integrations at `/api/v2`. Only the bare `/api` root redirects there. A path under `/api` with no version segment, such as `/api/tokens`, is served as `/api/v1/tokens`, so always write `/api/v2` in the base URL. Use `/api/v1` and `/api/v1/spec.json` only for an existing v1 client. Browse the full contract and generate a client from [the v2 API explorer](https://docs.settlemint.com/docs/api-reference/v2), or [the v1 API explorer](https://docs.settlemint.com/docs/api-reference/v1) for the legacy surface. The explorers read the contract. They do not send requests, so test a call against your own deployment with the CLI or your generated client.

Token, wallet, compliance, settlement, trading-venue, offering, observability, and administration endpoints are documented in full only in that generated contract. The guides walk through selected workflows with example calls and responses, and the explorer is the source of truth for every field, header, and status code.


  - [Guides](https://docs.settlemint.com/docs/api-reference/guides/authentication-api-keys): Authenticate, page results, retry safely, receive webhooks and plan for deprecations.
  - [Webhooks](https://docs.settlemint.com/docs/api-reference/webhooks): Find your events, choose subscriptions and handle states, retries, replay and retractions.
  - [TypeScript SDK](https://docs.settlemint.com/docs/api-reference/sdk): Call every v2 route through a typed client with TanStack Query and Effect surfaces.
  - [CLI](https://docs.settlemint.com/docs/api-reference/cli/install): Install the `dalp` command-line client and script the public API from a terminal.
  - [Errors](https://docs.settlemint.com/docs/api-reference/errors): Map an API error code or contract revert to its cause and the retry rules.
  - [API explorer](https://docs.settlemint.com/docs/api-reference/v2): Browse request and response schemas in the OpenAPI contract for the current API version.
  - [Docs for AI agents](https://docs.settlemint.com/docs/api-reference/docs-for-agents): Read the docs from an AI agent through llms.txt, page markdown, search and MCP.



# Browser apps with user sessions

Source: https://docs.settlemint.com/docs/api-reference/sdk/browser-apps
Keep DALP session cookies on your browser app's own origin with the SDK proxy.

A browser session cookie belongs to the host that set it. If your application loads at `https://portal.example` but sends sign-in to `https://api.example`, the browser stores the cookie for `api.example`. Requests rendered by `portal.example` cannot send it. The sign-in response can be successful while the next page load sees no session and returns to the login page.

Keep the Platform API behind your application's own origin. The browser calls `/api` on the app host, and your server forwards that path to the private Platform API URL. The SDK supplies the proxy so every app applies the same cookie, header, origin, stream, and failure rules.

## Mount the proxy [#mount-the-proxy]

Install the SDK and export a handler from a server route. This TanStack Start example accepts the methods a Platform API route can receive:

```ts
import { createFileRoute } from "@tanstack/react-router";
import { createDalpProxy } from "@settlemint/dalp-sdk/server-proxy";

const proxy = createDalpProxy({
  upstream: process.env.DALP_API_INTERNAL_URL!,
  origin: process.env.APP_PUBLIC_ORIGIN,
  trustedProxyProfile: (() => {
    const profile = process.env.TRUSTED_PROXY_PROFILE?.trim();
    return profile === "envoy" || profile === "nginx" || profile === "openshift" ? profile : "none";
  })(),
});

export const Route = createFileRoute("/api/$")({
  server: {
    handlers: {
      GET: ({ request }) => proxy(request),
      HEAD: ({ request }) => proxy(request),
      POST: ({ request }) => proxy(request),
      PUT: ({ request }) => proxy(request),
      PATCH: ({ request }) => proxy(request),
      DELETE: ({ request }) => proxy(request),
      OPTIONS: ({ request }) => proxy(request),
    },
  },
});
```

The returned function is a standard `(request: Request) => Promise<Response>` handler. In a server route, pass the incoming Fetch `Request` directly to it and return its `Response`. Mount `/dalp` through the same handler if your app serves Platform API assets such as organisation logos. `DALP_API_INTERNAL_URL`, `APP_PUBLIC_ORIGIN` and `TRUSTED_PROXY_PROFILE` are your app's own variable names: `upstream` is the private Platform API address and `origin` is your app's public URL, for example `https://portal.example`.

In the browser, construct the SDK client against the current origin:

```ts
import { createDalpClient } from "@settlemint/dalp-sdk";

const dalp = createDalpClient({
  baseUrl: window.location.origin,
  runtime: "browser",
});
```

Do not give the browser a public Platform API URL. Keep `DALP_API_INTERNAL_URL` server-only, because it is the address your app server uses to reach the Platform API inside your network.

To check the setup, sign in through the auth client on the same origin and read the signed-in user:

```ts
import { createDalpAuthClient } from "@settlemint/dalp-sdk/auth";

const auth = await createDalpAuthClient({ url: window.location.origin });
const { error } = await auth.signIn.email({ email, password });
const me = await dalp.api.party.users.me();
```

With no `error` from the sign-in, a `me` response that carries your user's `data.id` shows that the session cookie lands on your app host and travels with each call.

## What the handler forwards [#what-the-handler-forwards]

- It forwards the request method, path, query, body, cookies, auth-surface header, and `Set-Cookie` response headers. Cookies therefore land on the app host.
- It streams `text/event-stream` and `application/x-ndjson` responses and buffers all others. It preserves redirects and no-content statuses.
- It asks the platform for an uncompressed response. With `acceptEncoding: "forward"`, it passes the browser's `Accept-Encoding` on instead and returns the compressed bytes unchanged. Set it only when your server's `fetch` honours `decompress: false`. Otherwise the browser receives a decoded body that is still labelled as compressed.
- It removes hop-by-hop headers, `host`, `content-length`, and every client-forwarding header before the upstream request.
- It passes on one client address, chosen by `trustedProxyProfile`. For `envoy` it takes a valid `x-envoy-external-address`, or else the last `x-forwarded-for` entry. For `nginx` and `openshift` it takes the last `x-forwarded-for` entry. It passes nothing when that entry is not a valid IP address, and never reads an earlier entry. Under `envoy` it sends the address upstream as `x-envoy-external-address`. `none` passes no address.
- When the incoming request has no `Origin`, it stamps the configured public origin, so the platform treats a request that reaches the proxy without an `Origin` as one from your app. An incoming origin is preserved for the Platform API's auth-surface checks.
- A failed upstream request returns `502 UPSTREAM_UNAVAILABLE`, also when the platform answered but the handler could not read the body. For a write, a 502 therefore does not show that the platform did not receive it: read the operation's status before you send it again.
- A GET or HEAD request retries once after a connection reset. A request with a body is never replayed.
- When the browser has already abandoned the request, the handler answers `499` with no body.

`onUpstreamFailure` receives the method, path, upstream origin, and error details of each failure, so you can log it. `upstreamFailureMessage` replaces the message in the 502 body, and `fetch` replaces the upstream fetch, for example in tests.

Set `TRUSTED_PROXY_PROFILE` to match the edge that overwrites forwarding headers. An unknown or missing value is treated as `none`. Choose a profile other than `none` only when your ingress overwrites the header that profile reads, or a browser can supply the client address itself. Under `envoy`, the edge must set or remove `x-envoy-external-address` on every request. Envoy Gateway in `xForwardedFor` mode does neither by itself, so remove the header in its `ClientTrafficPolicy` as [Count readers separately behind Cloudflare](https://docs.settlemint.com/docs/deployment/install/values-secrets#count-readers-separately-behind-cloudflare) shows.

## Deployment note [#deployment-note]

When several apps run on separate hosts, each host serves its own `/api` and `/dalp` paths and forwards them to the same private Platform API address. The browser never needs a public Platform API URL. [Same-origin app deployment](https://docs.settlemint.com/docs/deployment/install/browser-apps) shows how an operator configures the Console and the Investor portal this way, with Helm and OpenShift examples.

## Auth redirects stay on your deployment's origins [#auth-redirects-stay-on-your-deployments-origins]

Every URL you pass to the auth client for the user's next page must be on an origin your deployment lists. The platform checks each URL before it sends an email or redirects the browser, so a reset or verification link never hands its token to an unlisted origin.

The check covers these fields:

- `redirectTo` on a password-reset request.
- `callbackURL` on sign-up, sign-in, sign-out, verification, email-change, account-deletion and account-linking requests.
- `errorCallbackURL` and `newUserCallbackURL` on a single sign-on request.

The listed origins are the Console URL, `global.dalpApp.config.app.http.url`, and each URL in `global.dalpApp.config.auth.consoleUrls` and `global.dalpApp.config.auth.portalUrls`. An origin includes its scheme, so on a deployment whose URLs use `https://`, an `http://` URL on any listed host is refused. A path such as `/reset-password` resolves on the Console URL, not on your app, so an app on its own origin passes its full URL, such as `https://portal.example/reset-password`.

```ts
const { error } = await auth.requestPasswordReset({
  email,
  redirectTo: new URL("/reset-password", window.location.origin).href,
});
```

The platform answers HTTP 403 when a URL is on any other origin, or is a path that a browser reads as another host, such as `//example.com`. The code names the field: `INVALID_REDIRECT_URL` for `redirectTo`, `INVALID_CALLBACK_URL` for `callbackURL`, `INVALID_ERROR_CALLBACK_URL` for `errorCallbackURL` and `INVALID_NEW_USER_CALLBACK_URL` for `newUserCallbackURL`. A refused password-reset or verification request sends no email. The refusal is a caller error, and a retry with the same URL gets the same answer: pass a listed URL, or ask your operator to list your app's origin. When someone opens a reset or verification link whose `callbackURL` names an unlisted origin, the platform also answers HTTP 403 and does not pass the token on.

A listed origin also receives a session. The Console session, administrators' included, goes to every origin in `consoleUrls`, and the Investor portal session to every origin in `portalUrls`. Both may call the Platform API from the browser. List an app that serves investors under `portalUrls`, and list only apps your team runs.

The chart's default lists read `DAPP_E2E_URL` into `consoleUrls`, and `INVESTOR_PORTAL_URL` and `CLIENT_PORTAL_URL` into `portalUrls`. Leave each one you do not use unset. A list you set in your values replaces the chart's list, so repeat the entries you keep, such as the Investor portal URL, beside your app's URL. [Same-origin app deployment](https://docs.settlemint.com/docs/deployment/install/browser-apps) shows how to set the Console and Investor portal URLs.

## Troubleshooting: sign-in succeeds but returns to the login page [#troubleshooting-sign-in-succeeds-but-returns-to-the-login-page]

Inspect the sign-in response and the next session request. If the response sets a cookie for the Platform API host while the page is on your application host, the browser is doing the correct host-only cookie isolation. Mount `createDalpProxy` at `/api`, set the browser SDK `baseUrl` to `window.location.origin`, and remove any public Platform API URL from the app. Then sign in again so the cookie is issued by the application host.


# Calling routes

Source: https://docs.settlemint.com/docs/api-reference/sdk/calling-routes
Every route is a node on one namespaced tree, called with one flat object the SDK splits into path, query, and body, returning the response envelope unchanged.

## Overview [#overview]

The SDK maps route identifiers to a namespaced client. `GET /tokens` is `dalp.api.token.list()`. `POST /tokens/{assetId}/transfers` is `dalp.api.token.transfer({ assetId, transfers })`. The client uses the routes included in its installed SDK version.

A call takes one flat argument and returns the response envelope. [Mutations and settlement](https://docs.settlemint.com/docs/api-reference/sdk/mutations) covers writes and retries.

## One flat argument [#one-flat-argument]

Each call takes one object:

```ts
await dalp.api.token.transfer({
  assetId: "0x1234...",
  transfers: [{ recipient: "0xabcd...", amount: "1000" }],
});
```

The route declaration identifies the path parameters. The SDK puts `assetId` in the URL and the remaining input in the body. A route that declares no request body sends everything that is not a path parameter as query parameters, whatever its method, and a route with a body sends only the query parameters it declares as query and the rest in the body.

For the transfer call above, the SDK splits the input like this:

| Key | Where the SDK puts it | Why |
| --- | --- | --- |
| `assetId` | The URL: `POST /api/v2/tokens/0x1234.../transfers` | The route's path template, `/tokens/:assetId/transfers`, names it. |
| `transfers` | The JSON body: `{ "transfers": [...] }` | The route declares a body, and `transfers` is not a path or query key. |

A route with no required input takes no argument at all:

```ts
const me = await dalp.api.party.users.me();
const tokens = await dalp.api.token.list();
```

A missing path parameter rejects the call with a `TypeError` naming the parameter and the route, rather than sending a request to a URL with a literal `:assetId` in it.

## Discovering routes [#discovering-routes]

In an editor, `dalp.api.` lists the namespaces. Each namespace lists its operations, and each operation shows its request and response types.

A namespace can also be an operation. `dalp.api.token.read` is a call, and routes that sit beneath it are still reachable as properties on the same node.

When you are building a command surface of your own and hold a route id as a string rather than a path, use `execute`:

```ts
const result = await dalp.execute("token/list", { page: { limit: 50 } });
```

`execute` uses the same dispatch and transport as `dalp.api` and fails with the same errors. An unknown route id rejects with a `TypeError` naming it. Import the route table to enumerate the routes in your installed SDK:

```ts
import { routeTable } from "@settlemint/dalp-sdk/routes";

const routeIds = Object.keys(routeTable.routes);
```

## What comes back [#what-comes-back]

A call resolves to the platform's response envelope, unchanged. A single-resource read resolves to `{ data, links }`, plus any extra top-level fields that route declares. A collection resolves to `{ data, meta, links }`. `links` on a collection holds `self`, `first`, `prev`, `next`, and `last`.

```ts
const tokens = await dalp.api.token.list({ page: { limit: 50 } });

tokens.data; // the rows
tokens.meta.total; // how many exist in total, not how many came back
tokens.links.next; // the next page's URL, or null on the last page
```

The SDK returns the full envelope with compile-time response types. It also checks each JSON and event-stream success response against the route's declared response, and a body that does not match throws `sdk.response.MALFORMED_SUCCESS` rather than reaching your code. A binary download is returned unchecked.

A non-2xx response throws rather than resolving. That is covered under [Errors](https://docs.settlemint.com/docs/api-reference/sdk/mutations#errors).

## Paging and filtering [#paging-and-filtering]

Most collection routes take the same parameters the API documents: `sort`, a `page` object, and a `filter` object. `page.limit` takes 1 to 200 and defaults to 50, and `page.offset` starts at 0. Prefix the `sort` field with `-` to sort descending.

A route that returns `meta.nextCursor` also takes `page.cursor`. Pass the cursor from the previous page together with the same `sort` and filters. A cursor read at any depth costs the same as the first page, and `page.offset` is ignored when a cursor is present. `meta.nextCursor` is `null` on the last page.

```ts
const page = await dalp.api.token.list({
  sort: "name",
  page: { limit: 50, offset: 0 },
});
```

On a route that takes a `page` object, the flat keys `limit`, `offset`, `sortBy`, `sortDirection`, and `filters` are not part of the client's types, so passing one fails to compile. A call that sends one anyway, for example through `sendParts`, is refused by the platform with a 400 that names the key. A route that declares its own flat `limit`, with `offset` or `cursor`, such as `GET /api/v2/transaction-requests`, types the keys it declares as input fields instead, as [Pagination](https://docs.settlemint.com/docs/api-reference/guides/pagination#other-pagination-shapes-in-the-api) lists.

To walk every page, stop when `links.next` is `null`. A short or empty page is not the end signal, and `meta.total` counts the rows at the time of each request, so a collection that changes mid-walk can keep your row count below it:

```ts
const rows = [];
let offset = 0;

for (;;) {
  const page = await dalp.api.token.list({ page: { limit: 100, offset } });
  rows.push(...page.data);
  if (page.links.next === null) break;
  offset += 100;
}
```

A collection can change while you page through it, so offset pagination can repeat or omit rows. Filter to a stable range when consistency matters. Narrow large result sets to limit request volume. [Pagination](https://docs.settlemint.com/docs/api-reference/guides/pagination) defines the query parameters.

## Conditional reads [#conditional-reads]

The SDK holds the `ETag` the platform returns on a cacheable read, sends it back as `If-None-Match` on the next read of the same resource, and turns a `304 Not Modified` answer back into the cached body. You get a normal response object either way. An unchanged response transfers no response body.

This is on by default and needs no configuration. The client holds up to 64 responses of at most 1 MiB each, drops them when a request carries a different organisation or participant header from the one before, and never holds an event stream. It also drops them after a sign-out, a session revocation or an organisation switch that it sends itself. Clear them yourself when you sign out or switch organisation through a separate authentication client:

```ts
dalp.conditionalRequests.clear();
```

A version tag identifies a response as seen by one identity acting for one organisation. A client that keeps tags across a change of either can serve one organisation's cached rows to another, so clear them in the same step as the switch.

## Per-call options [#per-call-options]

The second argument to any call is options.

```ts
await dalp.api.token.list({ page: { limit: 50 } }, { signal: controller.signal });
```

| Option | Type | What it does |
| --- | --- | --- |
| `signal` | `AbortSignal` | Cancels the request. On a settled write it also stops the wait. |
| `headers` | `Record<string, string>` or a function returning one | Extra headers for this call. A function is evaluated per request. |
| `settlementTimeoutMs` | `number` | How long the platform holds this write's response before answering with a 202 handle. Ignored unless the route is queue-backed. |

Use the same `Idempotency-Key` when retrying one instruction. Generate a new key only for a new instruction. A header function runs for each request, so keep a retry key outside that function. See [Retry safety](https://docs.settlemint.com/docs/api-reference/sdk/mutations#retry-safety).

## Cancellation [#cancellation]

Pass an `AbortSignal` and the request aborts with it. In React, wire it to the effect's cleanup, or let the TanStack Query factories do it for you, since they pass the query's own signal through.

```ts
const controller = new AbortController();
const promise = dalp.api.token.list({ page: { limit: 50 } }, { signal: controller.signal });
controller.abort();
```

An aborted request rejects with the abort reason rather than a `DalpApiError`, because nothing came back from the platform to build one from.

## Next [#next]

Writes, retry safety, and settlement: [Mutations and settlement](https://docs.settlemint.com/docs/api-reference/sdk/mutations).


# Effect

Source: https://docs.settlemint.com/docs/api-reference/sdk/effect
The same namespaced route tree returning Effect values instead of promises, with a tagged failure channel and interruption wired to the request.

## Overview [#overview]

The Effect entry has the same route tree and transport as the promise client. Calls return `Effect<A, DalpRequestError<Code>>` instead of `Promise<A>`, where `Code` is the union of error codes that operation can return. Interrupting a fibre aborts a request that uses the client-provided signal.

```ts
import { createDalpEffectClient } from "@settlemint/dalp-sdk/effect";
import * as Effect from "effect/Effect";

const dalp = createDalpEffectClient({
  baseUrl: process.env.DALP_API_URL!,
  apiKey: process.env.DALP_API_KEY!,
  runtime: "server",
});

const program = Effect.gen(function* () {
  const tokens = yield* dalp.api.token.list({ page: { limit: 50 } });
  return tokens.data;
});

const rows = await Effect.runPromise(program);
```

`effect` is an optional peer dependency, and this entry supports Effect 4. Install the latest Effect 4 release only if you use this entry.

```bash
npm install effect@4
```

## Why it is a separate entry [#why-it-is-a-separate-entry]

The root package does not import Effect. Import `@settlemint/dalp-sdk/effect` when your application uses Effect.

## The failure channel [#the-failure-channel]

Every call fails with one type, `DalpRequestError<Code>`, carrying the platform's error contract. Let the compiler infer the type from the call so `Code` stays the operation's own codes:

```ts
const program = dalp.api.token
  .list({ page: { limit: 50 } })
  .pipe(Effect.retry({ times: 3, while: (error) => error.retryable }));
```

| Field | What it holds |
| --- | --- |
| `_tag` | `"DalpRequestError"`, so `Effect.catchTag` matches it by tag. |
| `code` | The machine-readable code. A failure with no structured response carries `sdk.transport.REQUEST_FAILED`. |
| `id` | The stable DALP identifier when the platform supplied one, otherwise the SDK's own code. |
| `data` | The error's detail map when the platform or the SDK supplied one, for example `approvalId` on a held write. |
| `status` | The HTTP status, when there was a response. |
| `retryable` | Whether retrying can succeed. A platform or SDK error carries its own flag, and a 5xx response without one is `true`. A network failure before any response is `true`. A missing path parameter, an unknown route id and an aborted request are `false`. |
| `retryAfterSeconds` | How long the platform asked you to wait, from `Retry-After`, when it named a delay. |
| `routeId` | Which route failed, which matters when several are composed in one program. |

A bare `DalpRequestError` types `code` as the union of every published API and SDK error code (`DalpApiErrorCode`), never plain `string`. Each route's own call narrows it further to the error codes that route declares. A failure that never reaches a declared response, such as a network error, carries an SDK code like `sdk.transport.REQUEST_FAILED` that the route's type does not list, so branch on `error.retryable` for those and keep the operation's inferred error type instead of annotating a bare `DalpRequestError`.

Branch on `error.id` for domain handling and on `error.retryable` for retry policy. Success responses are checked at runtime as well as typed: a body that does not match the route's schema fails with `sdk.response.MALFORMED_SUCCESS` instead of arriving as a value the type promises.

## Interruption [#interruption]

Interrupting a fibre aborts the request. The abort controller is wired to the fibre rather than handed to you, so a cancelled fibre does not leave a socket open:

```ts
import * as Fiber from "effect/Fiber";

const program = Effect.gen(function* () {
  const fiber = yield* Effect.forkChild(dalp.api.token.list({ page: { limit: 50 } }));
  yield* Effect.sleep("2 seconds");
  yield* Fiber.interrupt(fiber); // the HTTP request is aborted
});
```

If you pass your own `signal`, manage its cancellation yourself.

## Composition [#composition]

Concurrency, retry, and timeout are Effect's, not the SDK's:

```ts
const program = Effect.gen(function* () {
  const [tokens, users] = yield* Effect.all(
    [dalp.api.token.list({ page: { limit: 50 } }), dalp.api.party.users.list({ page: { limit: 50 } })],
    {
      concurrency: 2,
    }
  );
  return { tokens: tokens.data, users: users.data };
});
```

```ts
dalp.api.token
  .list({ page: { limit: 50 } })
  .pipe(
    Effect.timeout("5 seconds"),
    Effect.retry({ times: 3, while: (error) => error._tag === "TimeoutError" || error.retryable })
  );
```

An `Effect.timeout` around a call interrupts it, which aborts the request. That composes correctly with settlement: a queue-backed write interrupted mid-wait stops waiting, and the instruction it submitted stays live on the platform exactly as it would if the platform's own wait had run out and answered with a 202 handle. Interrupting the wait is not cancelling the transaction.

## Route ids [#route-ids]

Dispatch by id, for code that builds its own command surface:

```ts
const program = dalp.execute("token/list", { page: { limit: 50 } });
```

An unknown id fails with a `DalpRequestError` in the error channel rather than throwing, so the failure stays in the type system with every other failure.

## What is the same [#what-is-the-same]

The Effect client matches the promise client in the flat argument split, the response envelope, settlement, the acting-context headers and the per-call options, and the pages on the promise surface document each of them once.

The Effect client differs in what the call hands back and in what it leaves out: it exposes only `api` and `execute`, with no `conditionalRequests` handle and no `sendParts`, `streamParts` or `downloadParts`. An Effect program that switches organisation or participant therefore builds a new client rather than clearing held tags.

A [streaming route](https://docs.settlemint.com/docs/api-reference/sdk/streaming) returns an effect that succeeds at once with the async iterable of frames. The request opens on the first iteration, so a refusal or a stream failure is thrown as a `DalpApiError` while you iterate, not in the effect's error channel. Break out of the loop, or abort a `signal` you pass, to close the stream.

## Next [#next]

Command-line access to the same routes: [CLI](https://docs.settlemint.com/docs/api-reference/cli/install).


# TypeScript SDK

Source: https://docs.settlemint.com/docs/api-reference/sdk
A typed, namespaced client for every published v2 route, generated from the platform's declaration, with TanStack Query factories and an Effect surface.

## Overview [#overview]

`@settlemint/dalp-sdk` is the TypeScript client for the DALP Platform API, the HTTP API a DALP instance serves under `/api/v2`. Every published v2 route is a typed method on one object: `GET /tokens` is `dalp.api.token.list()` and `GET /users/me` is `dalp.api.party.users.me()`.

The SDK and OpenAPI contract are generated from the same route declaration for a release. Match the SDK version to the deployment version: a newer client can name a route an older deployment does not serve.

[Figure] One declaration feeds the client, its types, and the CLI. The platform's route declaration is the single source. Generation reads it once and emits two artifacts: a route table carrying each route's path, method, and settlement behaviour, and a type registry keyed by route id carrying each route's request and response types. Three consumers are built from those artifacts rather than maintained by hand: the namespaced promise client a browser or server application calls, the Effect client with the same routes and a typed failure channel, and the command-line interface. Because all three read the same two artifacts, a route the platform adds or changes reaches every one of them through regeneration, and their route definitions match the release used to generate them. Labels: Route declaration; every v2 route, in the platform; Generated; Route table; path, method, settlement; Type registry; keyed by route id; Built from it; Promise client; Effect client; Command line; A route the platform adds reaches all three through regeneration.; Match the SDK version to the deployment version.

One declaration, read once, emits the route table and type registry that generate the promise client, the Effect client and the CLI.

The SDK runs in browser, server and React Native applications. A browser or React Native client authenticates with the session cookie and refuses an API key, and a server client authenticates with an API key. It has no framework dependency: React, TanStack Start, Next.js, and a worker all use the same client, and the framework-shaped conveniences are opt-in.

Start with [Install and configure](https://docs.settlemint.com/docs/api-reference/sdk/install). To call the API from another language, or to read the endpoint schemas themselves, use the [API reference](https://docs.settlemint.com/docs/api-reference), which renders every route from the spec. The [integration guides](https://docs.settlemint.com/docs/api-reference/guides/authentication-api-keys) cover the header contracts every client shares.


  - [Migrate from SDK 3.1 to 3.2](https://docs.settlemint.com/docs/api-reference/sdk/migration): Move from the 3.1 client to 3.2: route calls, settlement handling and imports.
  - [Install and configure](https://docs.settlemint.com/docs/api-reference/sdk/install): Install the package, construct a client and pick the credential for your runtime.
  - [Calling routes](https://docs.settlemint.com/docs/api-reference/sdk/calling-routes): How a route call is shaped, what comes back, and how paging and caching work.
  - [Mutations and settlement](https://docs.settlemint.com/docs/api-reference/sdk/mutations): Writes: retry safety, on-chain settlement, acting context headers and errors.
  - [Streaming routes](https://docs.settlemint.com/docs/api-reference/sdk/streaming): Routes that push a sequence of events instead of returning one body.
  - [TanStack Query](https://docs.settlemint.com/docs/api-reference/sdk/react-query): Query and mutation factories, cache keys and invalidation after a write.
  - [Browser apps with user sessions](https://docs.settlemint.com/docs/api-reference/sdk/browser-apps): Keep host-only cookies on your app origin with `createDalpProxy`.
  - [Server-side rendering](https://docs.settlemint.com/docs/api-reference/sdk/server-rendering): Where the client lives, how the session travels and what to hydrate.
  - [Effect](https://docs.settlemint.com/docs/api-reference/sdk/effect): The same routes, returning Effect values instead of promises.


## Settlement, credentials, and caching [#settlement-credentials-and-caching]

**A write can resolve before the chain does.** `dalp.api.token.transfer(...)` asks the platform to wait for a bounded time, set through `settlementTimeoutMs`. The call returns either the settled record or a handle, `{ transactionId, status, statusUrl }`, for an instruction still in progress. A handle is not a failed write, and treating it as one tells a user their transfer was rejected while it is still in flight. [Mutations and settlement](https://docs.settlemint.com/docs/api-reference/sdk/mutations) covers both shapes and how to follow a handle.

**The SDK refuses an API key in a browser client.** A client whose `runtime` resolves to `browser` or `react-native` throws at construction when it is given a key, rather than at the first request. A key acts as the user it belongs to, in the one organisation it was issued for, up to its `read` or `read-write` scope. A key in a browser bundle is readable by every visitor. The check trusts `runtime`: a client built with `runtime: "server"`, or a call that sets `X-Api-Key` in its own headers, sends the key wherever the code runs. [Install and configure](https://docs.settlemint.com/docs/api-reference/sdk/install#choose-the-credential) covers which credential belongs where.

**Cache keys are derived, not written.** `queryOptions` builds its key from route identity plus canonicalised input, so two callers passing the same parameters in different key order share one cache entry. A hand-written key that differs by one character creates a second entry that never invalidates, and a colliding key makes one entry serve two different requests. [TanStack Query](https://docs.settlemint.com/docs/api-reference/sdk/react-query) covers the key shape and invalidation.

## Validation and state [#validation-and-state]

The platform validates every request on the way in and every response on the way out. The SDK checks each JSON and event-stream success response against the route's declared response and throws `sdk.response.MALFORMED_SUCCESS` on a mismatch. Binary downloads are not checked. The check is strict about enum members, so an SDK older than the platform can throw this error on a value the platform added later. It loads those response schemas on the first call rather than at import, and it does not validate input. Validating user input before you send it stays your choice of library, and the [Console's own approach](https://docs.settlemint.com/docs/api-reference/sdk/react-query#validating-input-before-a-write) is one worked example.

The SDK is not a state manager. It returns promises and, for the routes that stream, async iterables. The TanStack Query factories are plain objects in the shapes that library expects.


# Install and configure

Source: https://docs.settlemint.com/docs/api-reference/sdk/install
Install the SDK, construct a client against your instance, and choose the credential for where the code runs: a session cookie or an API key.

## Overview [#overview]

A DALP client holds the instance URL, credential, and acting context for API calls. Use a session cookie in a browser and an API key on a server.

An API key grants the access allowed by its scope and the identity it belongs to. A key included in browser or app code is exposed to every user. The SDK rejects an API key on a client whose `runtime` is `browser` or `react-native`. It trusts the `runtime` you pass, so never set `runtime: "server"` in code that ships in a browser or app bundle.

## Install [#install]

The SDK is published as `@settlemint/dalp-sdk`. It supports browser applications, server applications on a runtime version that the package's `engines` field accepts, and React Native apps that pass `fetch` from `expo/fetch`, which [React Native](https://docs.settlemint.com/docs/api-reference/sdk/react-native) covers.

Each DALP release publishes the SDK under the release's own version number. Install the release line that matches your instance's major and minor version:

**`npm`**

```bash
npm install @settlemint/dalp-sdk@<major>.<minor>
```

**`pnpm`**

```bash
pnpm add @settlemint/dalp-sdk@<major>.<minor>
```

**`yarn`**

```bash
yarn add @settlemint/dalp-sdk@<major>.<minor>
```

Replace `<major>.<minor>` with your instance's version, then set the range in `package.json` to `~<major>.<minor>.0` so a later install stays inside that minor version. An install with no version takes the `latest` tag, which moves to each tagged release as it is published, including a patch to an older release line, so it does not match your instance by itself. To list the published versions and read the `engines` field:

```bash
npm view @settlemint/dalp-sdk versions
npm view @settlemint/dalp-sdk engines
```

The route surface is generated from the instance's own declaration, so a client from a later release knows about routes an older instance does not serve. Calling one fails when the call runs, not as a type error at build time.

The client these pages describe, with `baseUrl` and `dalp.api`, replaces the 3.1 client. An instance on DALP 3.1 takes the 3.1 client, and [Migrate from SDK 3.1 to 3.2](https://docs.settlemint.com/docs/api-reference/sdk/migration) maps one to the other.

Three peer dependencies are optional and none is installed for you. Add `@tanstack/react-query` only if you use the [query factories](https://docs.settlemint.com/docs/api-reference/sdk/react-query). Add `effect` only if you use the [Effect surface](https://docs.settlemint.com/docs/api-reference/sdk/effect). Add `zod` only if you use the auth subpath, whose Better Auth client types reference it. A project that uses none of the three needs none of them installed, and the package imports no schema library at run time.

## Construct a client [#construct-a-client]

```ts
import { createDalpClient } from "@settlemint/dalp-sdk";

const dalp = createDalpClient({
  baseUrl: process.env.DALP_API_URL!,
  apiKey: process.env.DALP_API_KEY!,
  runtime: "server",
});

const me = await dalp.api.party.users.me();
```

`createDalpClient` returns six members. Three of them cover most code:

| Member | What it is |
| --- | --- |
| `api` | The namespaced route tree. `dalp.api.token.list()`, `dalp.api.governanceV2.v2.governance.votes.cast({ ... })`. |
| `execute` | The same dispatch reached by route id: `dalp.execute("token/list", { page: { limit: 50 } })`. For code that builds its own command surface. |
| `conditionalRequests` | The held response-version tags. Call `.clear()` on sign-out and on an organisation switch. |

The other three dispatch by raw request parts rather than by flat arguments, for callers that assemble the path, query and body themselves: `sendParts`, `streamParts` and `downloadParts`. Each takes a route id and a `params`, `query` and `body` object, and `downloadParts` answers the response body as a stream of bytes.

### Options [#options]

| Option | Type | What it does |
| --- | --- | --- |
| `baseUrl` | `string \| URL` | Your instance's origin. Required. The SDK appends `/api/v2` itself, so pass the origin. A path prefix on the URL stays in front of `/api/v2`. |
| `apiKey` | `string \| Secret` | A server or CLI credential. The client trims it. Rejected when `runtime` resolves to `browser` or `react-native`. |
| `authSurface` | `"console" \| "portal"` | Names the app the calls act for. The client sends the value in `X-Dalp-Auth-Surface` on every call and sends no such header when you leave it out. The platform derives the app from the request's origin and treats a declared value that disagrees as a conflict, so the header cannot move a call to the other app. |
| `context` | `DalpClientContext` | The acting context, sent as headers on every request. See [The acting context](#the-acting-context). |
| `runtime` | `"browser" \| "server" \| "react-native"` | Decides credential rules and cookie behaviour. Inferred as `react-native` when `navigator.product` is `ReactNative`, otherwise from whether `globalThis.window` exists. Pass it explicitly wherever that inference is not obviously right. |
| `fetch` | `(input: RequestInfo \| URL, init?: RequestInit) => Promise<Response>` | Your own fetch. Useful for tests, for a proxy, and for a runtime whose fetch you want to control. |
| `ssr` | `DalpSsrOptions` | Forwards an incoming request's headers on a server render. See [Server-side rendering](https://docs.settlemint.com/docs/api-reference/sdk/server-rendering). |
| `settlementTimeoutMs` | `number` | How long the platform holds a queue-backed write's response before answering with a 202 handle. A single call may override it. See [Mutations](https://docs.settlemint.com/docs/api-reference/sdk/mutations#settlement). |

## Choose the credential [#choose-the-credential]

Two credentials reach the Platform API.

**Session cookie, in a browser**

The user signed in and the browser holds the session. Construct the client with no credential at all. It sends the cookie because it runs on your origin. This is what the Console and the Investor portal do.



**API key, on a server**

A backend service, a scheduled job, a CLI. The key acts in one organisation, up to its `read` or `read-write` scope. Keep it in your infrastructure and send it only to your DALP instance.

### In a browser [#in-a-browser]

```ts
export const dalp = createDalpClient({
  baseUrl: window.location.origin,
  runtime: "browser",
});
```

No credential is passed. The client sends credentials with each request, so a session cookie set on the page's own origin travels automatically, without an API key in the bundle. A `baseUrl` on another origin throws at construction, because the session cookie is host-only. Mount [`createDalpProxy`](https://docs.settlemint.com/docs/api-reference/sdk/browser-apps) on your app origin and keep `baseUrl` at `window.location.origin`.

Passing an `apiKey` here throws at construction with a configuration error that names the problem. The check runs at construction, so a key in a bundle fails when the client is built, before any request goes out.

If a key reaches a browser bundle, revoke it on the platform and replace it wherever it is used. Removing it from the next bundle does not invalidate copies already downloaded.

### On a server [#on-a-server]

```ts
import { createDalpClient } from "@settlemint/dalp-sdk";

const dalp = createDalpClient({
  baseUrl: process.env.DALP_API_URL!,
  apiKey: process.env.DALP_API_KEY!,
  runtime: "server",
});
```

Read the key from the environment or a secret manager while the application runs. In Next.js, name the variable without the `NEXT_PUBLIC_` prefix so the bundler cannot inline it into a client component. In Vite, keep it off the `VITE_` prefix for the same reason. Create the key with the `read` or `read-write` scope the integration needs, as [Authentication and API keys](https://docs.settlemint.com/docs/api-reference/guides/authentication-api-keys) describes.

To keep the key out of stack traces and logs, wrap it:

```ts
import { createDalpClient, secret } from "@settlemint/dalp-sdk";

const dalp = createDalpClient({
  baseUrl: process.env.DALP_API_URL!,
  apiKey: secret(process.env.DALP_API_KEY!),
  runtime: "server",
});
```

A `Secret` prints as a redaction marker wherever something stringifies it, and the SDK unwraps it only at the moment it sets the header. This protects against accidental disclosure, not against an attacker: a thrown error whose message interpolates the config, a structured log that serialises it, or a crash reporter that captures locals. Each of these stringifies the value, so each prints the marker.

## The acting context [#the-acting-context]

Some requests also need an acting context, such as the network or the signing wallet. The SDK sends it as request headers. The organisation is not one of them: a session acts in its active organisation, which the auth client's `organization.setActive` call changes, and an API key in the organisation it was issued for.

```ts
const dalp = createDalpClient({
  baseUrl,
  runtime: "browser",
  context: {
    chainId: 137,
  },
});
```

| Field | Header | When you set it |
| --- | --- | --- |
| `participant` | `X-Participant` | When acting on behalf of a participant rather than as yourself. |
| `executor` | `X-Executor` | To force a signing route: the caller's own externally owned account, or their smart wallet. |
| `chainId` | `X-Chain-Id` | On a multi-chain instance, to name the EVM network the request speaks to. |
| `selectedSigners` | `X-Selected-Signers` | On a multisig write, to name which signers this submission counts toward. |
| `networkId` | `X-Network-Id` | On an instance that serves more than one network family, to name the Canton network the request speaks to. |
| `custodyAccountId` | `X-Custody-Account-Id` | To name the custody account a read or write acts on, instead of the caller's default. |
| `idempotencyKey` | `Idempotency-Key` | Rarely at client level. A key is per instruction, not per client, so set it [per call](https://docs.settlemint.com/docs/api-reference/sdk/mutations#retry-safety). |

The context is fixed for the life of the client. When it changes, for example because the user switched organisation, build a new client and discard the old one. If you keep the old client, clear its held response tags, because a version tag from the old organisation means nothing under the new one:

```ts
dalp.conditionalRequests.clear();
```

The client also drops its held responses on its own when the `X-Organization-Id` or `X-Participant` header of a request differs from the previous request, so a client that forwards a tenant header per call never answers one tenant with another tenant's held body.

A single call can add headers of its own without rebuilding anything. See [Per-call options](https://docs.settlemint.com/docs/api-reference/sdk/calling-routes#per-call-options).

## Sign in and manage sessions [#sign-in-and-manage-sessions]

`createDalpClient` calls Platform API routes. Sign-in, sessions, organisations, invitations, API keys, passkeys, two-factor codes, and wallet verification go through a second client from the `@settlemint/dalp-sdk/auth` entry. The entry is separate because it loads the authentication library, which code that only calls routes does not need.

```ts
import { createDalpAuthClient } from "@settlemint/dalp-sdk/auth";

const auth = await createDalpAuthClient({ url: "https://your-instance.example.com" });
const session = await auth.getSession();
```

`createDalpAuthClient` is asynchronous and takes `url`, not `baseUrl`. Every operation resolves to `{ data, error }` and does not throw for a refused request, so check `error` before you read `data`.

The client takes one credential source: an API key, a cookie header in `cookie`, or a `cookieStore`. It rejects an API key together with a cookie header or with a cookie store that already holds cookies, and a browser or React Native client rejects an API key, as `createDalpClient` does. With no source, it creates an in-memory cookie store, so the session lasts as long as that client. It also takes `authSurface`, extra `headers` that cannot replace the credential headers, `fetch`, `runtime`, and a `passkey` ceremony, and it has no organisation option: it signs in to the organisation the session's active organisation names, and `organization.setActive` changes that. A configuration it cannot accept rejects with a `DalpSdkError`.

With an API key, the auth client reaches only the nine routes that [Authentication and API keys](https://docs.settlemint.com/docs/api-reference/guides/authentication-api-keys) lists, such as the session, organisation and key lookups. Every other auth route answers 403 `API_KEY_NOT_SUPPORTED_ON_ROUTE`, so sign-in, key creation and passkey registration need a session.

The auth client does not share its held responses with `createDalpClient`. After you sign out or switch organisation through the auth client, call `dalp.conditionalRequests.clear()` on the route client.

## Verify the setup [#verify-the-setup]

Check the setup with a read that needs only authentication:

```ts
const me = await dalp.api.party.users.me();
console.log(me.data.id);
```

A `DalpApiError` with status 401 means the credential did not arrive or the platform did not accept it. In a browser, the session is missing or expired. On a server, the key is absent or not valid. Status 403 means the platform accepted the credential and refused the request. That can be a role question, a `read` key on a write route, or a missing acting context such as no active organisation. Read `error.id` to tell them apart. [Errors](https://docs.settlemint.com/docs/api-reference/sdk/mutations#errors) covers the other failures.

## Next [#next]

Route calls, paging, and what comes back: [Calling routes](https://docs.settlemint.com/docs/api-reference/sdk/calling-routes).


# Migrate from SDK 3.1 to 3.2

Source: https://docs.settlemint.com/docs/api-reference/sdk/migration
Move a 3.1 TypeScript SDK integration to 3.2: client options, flat route calls, write handles, idempotency keys, summary responses, imports, and errors.

The 3.2 TypeScript SDK changes how you construct the client, call routes, handle writes, and import helpers. Code written against 3.1 does not compile against 3.2. The [TypeScript SDK reference](https://docs.settlemint.com/docs/api-reference/sdk) describes the 3.2 client in full. Work through these steps in order:

1. [Install the 3.2 package](#install-the-32-package).
2. [Update the client options](#update-the-client-options).
3. [Flatten route calls](#flatten-route-calls).
4. [Handle write results](#handle-write-results).
5. [Move idempotency keys onto the call](#move-idempotency-keys-onto-the-call).
6. [Handle summary responses](#handle-summary-responses).
7. [Update imports and webhook verification](#update-imports-and-webhook-verification).
8. [Update error handling](#update-error-handling).

## Install the 3.2 package [#install-the-32-package]

Install the `@settlemint/dalp-sdk` release whose major and minor version match your DALP instance. Move to the 3.2 client when the instance runs DALP 3.2. A 3.2 client against a 3.1 instance can name routes the instance does not serve. [Install and configure the SDK](https://docs.settlemint.com/docs/api-reference/sdk/install#install) has the install command and explains why the versions must match, and [Upgrade an integration to DALP 3.2](https://docs.settlemint.com/docs/api-reference/guides/upgrade-to-3-2) covers the platform changes.

## Update the client options [#update-the-client-options]

```ts
// 3.1
const dalp = createDalpClient({
  url: "https://dalp.example.com",
  apiKey: process.env.DALP_API_KEY!,
  organizationId: "org_01J00000000000000000000000",
});
```

```ts
// 3.2
import { createDalpClient, secret } from "@settlemint/dalp-sdk";

const dalp = createDalpClient({
  baseUrl: "https://dalp.example.com",
  apiKey: secret(process.env.DALP_API_KEY!),
  runtime: "server",
});
```

| 3.1 option | 3.2 option |
| --- | --- |
| `url` | `baseUrl`. |
| `apiKey` | `apiKey`. It accepts a string or a `Secret`. The client wraps a string itself. Pass `secret()` to keep the key redacted in your own code as well. |
| `organizationId` | No option. A credential names the organisation: an API key acts in the organisation it was issued for, and a session in its active organisation, which `organization.setActive` changes. `context` takes only the acting-context fields the platform reads, listed in [The acting context](https://docs.settlemint.com/docs/api-reference/sdk/install#the-acting-context). |
| `headers` | No client option. Pass `headers` per call in the second argument, as an object or a synchronous function. Per-call headers override the credential and context headers. For a header every request needs, wrap `fetch`. See [Per-call options](https://docs.settlemint.com/docs/api-reference/sdk/calling-routes#per-call-options). |
| `idempotencyKey` | A per-call `Idempotency-Key` header. See [Move idempotency keys onto the call](#move-idempotency-keys-onto-the-call). |
| `requestValidation` and `responseValidation` | No option. See [Update error handling](#update-error-handling). |
| `fetch` | `fetch`. |
| `DalpClientConfig` type | `CreateDalpClientOptions`. |
| None | `runtime`: `"server"`, `"browser"`, or `"react-native"`. Optional. The SDK detects it when you leave it out. |

`runtime` tells the client where it runs. A `"server"` client authenticates with the API key. A browser client authenticates with the session cookie. Browser and React Native clients both refuse an API key. [Choose the credential](https://docs.settlemint.com/docs/api-reference/sdk/install#choose-the-credential) explains both.

`createDalpPlatformClient` is removed. It returned a route client, an auth client, and a cookie store from one call. Create the route client with `createDalpClient` and the auth client with `createDalpAuthClient` from `@settlemint/dalp-sdk/auth`. The auth client still takes `url`, not `baseUrl`. Its `sessionToken` option is removed, and its `cookieStore` option takes the `CookieStoreShape` that `makeCookieStore()` returns.

`DalpCookieStore` is replaced by `makeCookieStore()`, which returns a `CookieStoreShape`. In 3.1, `header` and `isEmpty` were getters. In 3.2 they are methods, so call `store.header()` and `store.isEmpty()`. `createCookieStoreFetch` still comes from the package root and accepts the new store.

## Flatten route calls [#flatten-route-calls]

```ts
// 3.1
const token = await dalp.token.read({ params: { tokenAddress: "0x1234" } });
const tokens = await dalp.token.list({ query: {} });
```

```ts
// 3.2
const token = await dalp.api.token.read({ assetId: "0x1234" });
const tokens = await dalp.api.token.list({
  page: { limit: 50, offset: 0 },
  sort: "-name",
});
```

In 3.2, routes sit under `dalp.api`. A 3.1 call wrapped its arguments in `params`, `query`, and `body` objects. A 3.2 call takes one flat object, and the client puts each field in the URL path, the query string, or the request body as the route declares. Argument names follow the 3.2 route, so some change: token read takes `assetId` where 3.1 took `tokenAddress`. Your editor shows each route's argument names.

A list call takes flat `page`, `sort`, and `filter` fields. Prefix a sort field with `-` for descending order. [Paging and filtering](https://docs.settlemint.com/docs/api-reference/sdk/calling-routes#paging-and-filtering) covers the filter syntax.

## Handle write results [#handle-write-results]

A write that submits a blockchain transaction still resolves in one of two shapes, as in 3.1. If the transaction settles within the settlement wait that `settlementTimeoutMs` sets, the call returns the route's result. If it does not, the call returns a handle: `{ transactionId, status, statusUrl }`. Check for `transactionId` to tell them apart.

The default wait is shorter. The 3.1 client sent `Prefer: wait=99` on every non-GET request. The 3.2 client sends `Prefer: wait=15`, only on queue-backed writes, and never when you set `Prefer` yourself. Migrated code therefore receives handles more often. Set `settlementTimeoutMs: 99_000` to keep the 3.1 timing.

```ts
import { createDalpClient, secret } from "@settlemint/dalp-sdk";
import { fiatCurrency } from "@settlemint/dalp-sdk/scalars";
import { waitForTransaction } from "@settlemint/dalp-sdk/wait-for-transaction";

const dalp = createDalpClient({
  baseUrl: "https://dalp.example.com",
  apiKey: secret(process.env.DALP_API_KEY!),
  runtime: "server",
  settlementTimeoutMs: 30_000,
});

const result = await dalp.api.token.create(
  {
    name: "Northwind Coffee",
    symbol: "NWC",
    type: "deposit",
    decimals: "2",
    countryCode: "528",
    priceCurrency: fiatCurrency("USD"),
    basePrice: "1.00",
  },
  { headers: { "Idempotency-Key": crypto.randomUUID() } }
);

if ("transactionId" in result) {
  await waitForTransaction(dalp, result.transactionId, { timeoutMs: 120_000 });
} else {
  console.log(result.links.self);
}
```

Do not submit the write again when you receive a handle. The platform already has the instruction. A second request can perform the action twice, even with the same idempotency key, when the route does other work before it queues the instruction. Follow the handle until it reports a final status.

The example sets two timeouts, both in milliseconds:

- `settlementTimeoutMs` is how long the platform holds each queue-backed write response before it returns a handle. The SDK sends it as a `Prefer` header, rounded up to whole seconds and clamped to 5 to 99 seconds. Without it, the SDK sends `Prefer: wait=15`. A value of zero or less sends `Prefer: respond-async`, which returns the handle at once. A single call can override it with `settlementTimeoutMs` in its second argument.
- `timeoutMs` is how long `waitForTransaction` polls the status route without progress before it gives up. While a write is parked on a gas payment or an indexer rebuild, the helper restarts that budget on every poll, so the total wait has no upper limit. Pass `signal: AbortSignal.timeout(ms)` for a hard limit, or set `holdWhilePaused: false` and `holdWhileRebuilding: false` to stop at the first pause.

`waitForTransaction` resolves with the transaction status once it reports `COMPLETED`. It throws a `DalpTransactionWaitError` when the wait runs out, is aborted, or ends in a failed status. On the settled branch, `result.data` is the created token and `result.links.self` is the URL that reads it again. Instead of the helper, you can read a handle's status with `dalp.api.transactionsV2.status({ transactionId })` or follow it with `dalp.api.transactionsV2.statusStream({ transactionId })`. [Mutations and settlement](https://docs.settlemint.com/docs/api-reference/sdk/mutations) covers both.

In 3.1, `waitForTransaction` came from the package root. In 3.2, import it from `@settlemint/dalp-sdk/wait-for-transaction`. Its options also changed:

- `intervalMs` is now `pollIntervalMs`, and the default poll interval is 1,000 ms instead of 2,000 ms.
- `resolveOnPendingApproval` is removed. The 3.1 helper returned at `PENDING_APPROVAL` by default. The 3.2 helper returns only at `COMPLETED`, so a transaction that waits for approval runs until the timeout and throws `DalpTransactionWaitError`.

A write the organisation holds for a second user's approval does not return a handle. The client throws a `DalpApiError` with code `sdk.transport.APPROVAL_HELD`. Do not repeat the request. The second approver approves it, and you read the approval at the `statusUrl` in the error's `data`.

## Move idempotency keys onto the call [#move-idempotency-keys-onto-the-call]

An idempotency key is a unique id for one instruction. The platform uses it to recognise a repeated request for the same instruction.

3.1 accepted a key in three places. The `idempotencyKey` client option sent the same key on every request from that client. A call could also pass `{ context: { idempotencyKey } }` as its second argument, or a `headers: { "Idempotency-Key": key }` field inside its input. In 3.2, all three become the `Idempotency-Key` header in the call's second argument. The per-call `context` and its `skipLoggingFor` field are removed. Generate one key per instruction, and reuse it only when you retry that same instruction on a route that documents replay safety. `token.create` does not, so read the operation's status before you send it again:

```ts
const idempotencyKey = crypto.randomUUID();
const options = { headers: { "Idempotency-Key": idempotencyKey } };

await dalp.api.token.create(input, options);
```

`context.idempotencyKey` also exists, but it sends one key on every request from the client, like the 3.1 option did. Use it only for a client that submits a single instruction. [Retry safety](https://docs.settlemint.com/docs/api-reference/sdk/mutations#retry-safety) explains when a retry with the same key is safe.

## Handle summary responses [#handle-summary-responses]

Some read routes accept a `view: "summary"` argument or a `fields` projection. Their 3.2 response type is a union of the full record and a summary record. The summary record has the same fields with every field optional, so the union has no tag to switch on. A field read on the union has type `T | undefined`, and 3.1 code that uses it as a defined value no longer compiles. Check that a field is defined before you use it. The platform sends the full record when you pass neither `view` nor `fields`, but the type stays the union, so the check is still required.

| Response type | Full record | Summary record |
| --- | --- | --- |
| `PlatformSystemReadRecord` | `PlatformSystemView` | `PlatformSystemSummaryView` |
| `AssumableParticipantRead` | `AssumableParticipant` | `AssumableParticipantSummary` |
| `UserListReadItem` | `UserListMember` | `UserListSummaryItem` |
| `HeldPriceRead` | `HeldPriceView` | `HeldPriceSummary` |
| `PriceSourceRead` | `PriceSourceView` | `PriceSourceSummary` |
| `ReportingSubmissionRead` | `ReportingSubmission` | `ReportingSubmissionSummary` |
| `TradingVenueOrderRead` | `TradingVenueOrder` | `TradingVenueOrderSummary` |
| `TokenListReadItem` | `TokenListDeploymentItem` or a deployed token item | `TokenListSummaryItem` |

A token list item also needs a second check. Its `ref` carries a `_tag` that says which identifier it holds. Only `ref._tag === "evm"` carries an `address`. A token that is still deploying has `ref._tag === "deployment"` and a `runKey`. Check the tag before you read the address:

```ts
const tokens = await dalp.api.token.list();

for (const item of tokens.data) {
  if (item.ref?._tag === "evm") {
    console.log(item.ref.address);
  }
}
```

## Update imports and webhook verification [#update-imports-and-webhook-verification]

The route client stays at the package root. The Effect client is at `@settlemint/dalp-sdk/effect`, which [The Effect surface](https://docs.settlemint.com/docs/api-reference/sdk/effect) describes.

| 3.1 import from the package root | 3.2 import |
| --- | --- |
| `waitForTransaction`, `DalpTransactionWaitError`, `WaitForTransactionOptions`, `WaitForTransactionStatus` | `@settlemint/dalp-sdk/wait-for-transaction`. |
| `createDalpAuthClient`, its types, and `WalletAuthEndpointPath` | `@settlemint/dalp-sdk/auth`. |
| `verifyWebhook`, `toStandardWebhookSecret`, and their types | `@settlemint/dalp-sdk/verify-webhook`. |
| `createDalpPlatformClient`, `DalpPlatformClient`, `DalpPlatformClientConfig` | `createDalpClient` from the root and `createDalpAuthClient` from `@settlemint/dalp-sdk/auth`. |
| `DalpCookieStore` | `makeCookieStore` from the root. |
| `createDalpBundlerClient` and the other bundler exports | No SDK client. Call the bundler routes under `/api/v2/bundler/{chainId}` described in [Smart wallet user operations](https://docs.settlemint.com/docs/api-reference/guides/user-operations), or send JSON-RPC to `POST <baseUrl>/bundler/{chainId}`. |
| `bigDecimalSerializer`, `bigIntSerializer`, `timestampSerializer`, `dalpSerializers` | No serialiser setting. From `@settlemint/dalp-sdk/scalars`, `decodeBigInt` and `decodeBigDecimal` turn a wire string into a value, and `encodeBigDecimal` turns a value back into a wire string. |
| `DALP_CONTRACT_ERROR_CODES`, `DalpContractErrorCode` | `DalpErrorCode` and `dalpErrorCatalog` at the root. |
| `RequestValidationPlugin`, `ResponseValidationPlugin`, `BatchLinkPlugin` from the removed `plugins` subpath of `@settlemint/dalp-sdk` | No replacement. Response checking is built in. Request validation and request batching are removed. |

In 3.2, `verifyWebhook` returns a promise, so `await` it. A 3.1 receiver that reads `.ok` on the result without `await` does not compile, and in plain JavaScript it rejects every event.

The function also takes an optional `replayStore` with two methods, `claim(eventId, claimId)` and `release(eventId, claimId)`. `claim` records the event id with the claim id in one atomic write and returns `true` only when no record for that event id exists. `release` removes the record only while it still holds that claim id. With a store, the function claims the event id once the signature verifies and refuses a delivery whose id is already claimed with `REPLAYED_EVENT`. A platform retry carries the same id, so call `release` on the verified result when your handler fails, or the retry is refused. Answer `REPLAYED_EVENT` with a `2xx` and `REPLAY_STORE_FAILURE` with a `5xx`, because a `401` ends delivery of the event. [Refuse a repeated delivery](https://docs.settlemint.com/docs/api-reference/guides/webhooks#refuse-a-repeated-delivery) explains the store. Without a store, a copy of a delivery resent within the timestamp tolerance, five minutes by default, verifies again. The function returns three new failure codes: `REPLAYED_EVENT`, `MALFORMED_BODY` and `REPLAY_STORE_FAILURE`.

A receiver without a store answers every failure with `401`:

```ts
import { verifyWebhook } from "@settlemint/dalp-sdk/verify-webhook";

const result = await verifyWebhook({ rawBody, headers, secret });
if (!result.ok) {
  return new Response(null, { status: 401 });
}
```

## Update error handling [#update-error-handling]

The 3.1 root exported four helpers that decode an error body: `isDapiPublicError`, `decodeDapiErrorResponseBody`, `getDapiPublicErrorFromResponseBody`, and `createDalpSdkErrorFromDapiPublicError`. It also exported two code lists, `CUSTOM_ERROR_CODES` and `DAPI_ERROR_IDS`, and the types `ErrorCode`, `DapiErrorId` and `DapiPublicError`. The 3.2 SDK removes all of them.

In 3.2, every non-2xx response throws a `DalpApiError`, and so does a 2xx response whose body the SDK cannot accept. Check for it with `isDalpApiError`, then read its `code`, `id`, `status`, and `data`:

```ts
import { isDalpApiError } from "@settlemint/dalp-sdk";

try {
  await dalp.api.token.read({ assetId: "0x1234" });
} catch (error) {
  if (isDalpApiError(error)) {
    console.error(error.code, error.id, error.status);
  }
}
```

Do not assume that a code you stored under 3.1 still exists. Check it with `isDalpErrorCode`. The [error reference](https://docs.settlemint.com/docs/api-reference/errors) lists the platform codes.

The SDK no longer checks request input, so invalid input reaches the platform and comes back as a `DalpApiError`. The SDK does check each JSON success response against the route. A body that does not match throws a `DalpApiError` with code `sdk.response.MALFORMED_SUCCESS`. A non-JSON body, or an empty body where the route declares one, throws code `sdk.transport.MALFORMED_RESPONSE`. Binary routes skip the check.

## Next [#next]

- [Install and configure the SDK](https://docs.settlemint.com/docs/api-reference/sdk/install)
- [Call routes, page collections, and read responses](https://docs.settlemint.com/docs/api-reference/sdk/calling-routes)
- [Handle mutations and settlement](https://docs.settlemint.com/docs/api-reference/sdk/mutations)
- [Use the Effect surface](https://docs.settlemint.com/docs/api-reference/sdk/effect)


# Mutations and settlement

Source: https://docs.settlemint.com/docs/api-reference/sdk/mutations
A write that touches the chain returns the settled resource or the platform's 202 handle. Retry safety, the acting context, and errors are yours to handle.

## Overview [#overview]

Minting, transferring, freezing, and voting submit on-chain transactions. API acceptance and ledger settlement are separate events. The SDK asks the platform to wait for settlement and returns a settled result or a pending handle.

Show a pending handle as pending. Resubmitting an instruction can create a duplicate transfer, even with the original idempotency key when the API route does other work before queue admission. Keep the handle and follow its status until the platform reports a terminal outcome.

Set the wait duration, acting identity, and retry policy for your application. The SDK sends the settlement preference and returns the platform response. It does not poll on your behalf.

## A write is one call [#a-write-is-one-call]

```ts
const result = await dalp.api.token.transfer({
  assetId: "0x1234...",
  transfers: [{ recipient: "0xabcd...", amount: "1000" }],
});
```

If settlement completes within the requested wait, `result` contains the route result. Otherwise, it contains a pending handle.

## Settlement [#settlement]

The platform decides whether a write settles inside the requested wait.

A queue-backed write carries a `Prefer` header that the SDK derives from `settlementTimeoutMs`, as [Choosing the wait](#choosing-the-wait) describes. The platform does the waiting. The SDK sends the header, reads back whatever status comes, and decodes the body.

If the write settles inside that wait, the response is `200` with the route's declared resource. If it does not, the response is `202` with a handle, and the call resolves with that handle instead. The SDK never polls a status URL on your behalf, and a `202` reaching your code is not a failure: the platform has the instruction and is still working on it.

### Following a handle yourself [#following-a-handle-yourself]

The handle's shape says which kind of write produced it. A transaction write hands back `{ transactionId, status, statusUrl }`. A custody lifecycle write hands back `{ requestId, state, statusUrl }`. Branch on which key the body carries, not on a status code the SDK does not expose.

The loop below follows a transaction handle over the status stream, which a client that authenticates with an API key can always open. A client that authenticates with a session cookie must send the request from the same origin or from an origin the deployment trusts. Any other cookie-authenticated request receives `404` before the first event. Use `waitForTransaction` or repeated `dalp.api.transactionsV2.status({ transactionId })` reads when the browser cannot open the stream.

```ts
const TERMINAL = new Set(["COMPLETED", "FAILED", "DEAD_LETTER", "CANCELLED"]);

const result = await dalp.api.token.transfer({ assetId: tokenAddress, transfers });

if ("transactionId" in result) {
  // Still queued. Follow it, or resume later with the same id.
  const { transactionId } = result;
  let terminal;
  while (terminal === undefined) {
    for await (const frame of dalp.api.transactionsV2.statusStream({ transactionId })) {
      if (frame.family !== "evm") {
        // Another network family sends one frame and closes. Read its submissionStatus.
        terminal = frame;
        break;
      }
      // A dead letter that may still land is not an answer yet: keep following it.
      if (TERMINAL.has(frame.status) && frame.mayStillLand !== true) {
        terminal = frame;
        break;
      }
    }
    // Falling out without a terminal frame is the stream's 180-second
    // lifetime, not an answer. Reopen; the first frame is the current state.
    if (terminal === undefined) {
      await new Promise((resolve) => setTimeout(resolve, 1000));
    }
  }
} else {
  // Already settled.
}
```

The stream can close after 180 seconds while the transaction remains pending. Reopen it to receive the current state. Wait between attempts so an immediate close cannot create a tight reconnect loop.

`waitForTransaction(client, transactionId)`, from `@settlemint/dalp-sdk/wait-for-transaction`, follows one handle without the stream. It polls the status route, so it has no 180-second close to handle, and it works for a caller that authenticates with a session cookie from an origin the deployment does not trust, which the stream refuses. Prefer it unless you want each intermediate frame. A custody lifecycle handle has no such helper: follow it with a `GET` on `statusUrl`, and read `state` until it reaches a terminal value.

Do not resubmit while a handle is outstanding, because the instruction is live and a repeated API request can perform a second effect before it reaches the transaction queue. The exception is a route whose contract tells you to retry with the same `Idempotency-Key`, such as a corporate action commit that is still `executing`.

A `DEAD_LETTER` status with `mayStillLand: true` is not terminal yet. The platform could not confirm the call, and the call can still reach the chain, so the stream stays open on it. `waitForTransaction` keeps polling such a row and ends with reason `timeout`, not `terminal-failure`. Do not resend while `mayStillLand` is `true`.

Inspect the terminal status and failure details before deciding whether to submit another instruction. `FAILED`, `CANCELLED`, and `DEAD_LETTER` require different responses. A rejected input needs correction, a cancellation needs an authorised decision, and exhausted retries need investigation. Read the transaction-request record through the returned status URL to determine the next step.

An organisation owner or a platform administrator can requeue a `FAILED` or `DEAD_LETTER` request under the same transaction id, and can move an active request to `FAILED` with a reason. Keep watching a failed request's status before you send a replacement instruction, because a requeued attempt can still settle.

A write waits when a wallet it needs cannot pay the network fee, called gas. The platform parks the write until that wallet is funded, and the write reads as still queued meanwhile. Its status row carries the open funding requirement as `activeRequirement`. `waitForTransaction` restarts its timeout on every poll that reports one, so it keeps waiting for as long as the requirement stays open. Pass an `AbortSignal` for a hard limit, or `holdWhilePaused: false` to stop with reason `funding-paused`. A caller reading `statusUrl` directly sees the same field and can apply the same rule.

### Choosing the wait [#choosing-the-wait]

When `settlementTimeoutMs` is not set, the SDK asks the platform to hold the response for 15 seconds. Zero or a negative number sends `respond-async`, which returns the handle immediately with no hold at all. Any other value asks for that many milliseconds. The SDK rounds the request up to whole seconds and clamps it to between 5 and 99, and the platform applies the same 5 to 99 second range to the `Prefer` header it receives.

```ts
const dalp = createDalpClient({ baseUrl, runtime: "browser", settlementTimeoutMs: 30_000 });
```

or per call:

```ts
await dalp.api.token.transfer({ assetId: tokenAddress, transfers }, { settlementTimeoutMs: 15_000 });
```

The [mutation factories](https://docs.settlemint.com/docs/api-reference/sdk/react-query) set a 30-second bound of their own, for a mutation hook that holds a spinner while it waits.

A short wait does not fail the write. It returns the handle sooner. The outcome, including a failure, then reaches you only through the handle's status, so keep the handle.

## Retry safety [#retry-safety]

Send an `Idempotency-Key` on any write your client might retry. On a route that documents replay safety and echoes the key, such as `token.transfer`, a retry with the same key after a timeout or a dropped connection is a retry of that one instruction. On any other route, a repeated request can act a second time before the instruction reaches the queue, so read the original operation's status before you send it again.

```ts
await dalp.api.token.transfer(
  { assetId: tokenAddress, transfers },
  { headers: { "Idempotency-Key": crypto.randomUUID() } }
);
```

The header contract, retention window, and duplicate handling are on [Idempotency and async settlement](https://docs.settlemint.com/docs/api-reference/guides/idempotency-async-settlement). Two things are specific to the SDK.

**A key identifies one instruction, not one call site.** If a user submits the same form twice deliberately, those are two instructions and want two keys. If your code retries one submission, that is one instruction and wants one key across both attempts.

**Reuse a key for every retry of one instruction on a replay-safe route.** Generate it before the request and keep it until the instruction has a known outcome:

```ts
const idempotencyKey = crypto.randomUUID();
const options = { headers: () => ({ "Idempotency-Key": idempotencyKey }) };
```

Reuse `options` for retries of the same submission on a replay-safe route, and read the transaction status first after a dropped connection.

## The acting context on a write [#the-acting-context-on-a-write]

A write needs to know who it acts for and which wallet signs. The client-level `context` covers the steady state. A single call overrides it through headers.

```ts
await dalp.api.token.transfer({ assetId: tokenAddress, transfers }, { headers: { "X-Executor": "smart-wallet" } });
```

The field names, their headers, and when each applies are in [Install and configure](https://docs.settlemint.com/docs/api-reference/sdk/install#the-acting-context). On a multisig, `X-Selected-Signers` names which signers this submission counts toward. The platform accepts only signers whose keys the caller controls in the organisation and refuses any other. Naming the wrong one of your own signers produces a valid submission that counts toward that signer.

## Errors [#errors]

Any non-2xx response throws a `DalpApiError`. It carries the platform's error contract rather than a status code you then look up.

```ts
import { isDalpApiError } from "@settlemint/dalp-sdk";

try {
  await dalp.api.token.transfer({ assetId: tokenAddress, transfers });
} catch (error) {
  if (isDalpApiError(error)) {
    error.id; // stable DALP-NNNN identifier, when the platform supplied one
    error.code; // the machine-readable code
    error.status; // the HTTP status
    error.retryable; // whether retrying this exact request can succeed
    error.why; // what happened, in a sentence
    error.fix; // what to do about it
    error.retryAfterSeconds; // present when the platform asked you to wait
  }
  throw error;
}
```

Branch on `error.id` rather than on the message. The identifier is a stable contract and the message is prose that can be reworded. The identifiers and what each means are in the [error reference](https://docs.settlemint.com/docs/api-reference/errors).

Check `retryable` before retrying. Use the error identifier and recovery guidance to decide what to correct, and respect `retryAfterSeconds` when present. Keep retries bounded. For an uncertain write, inspect the original operation's state. Repeat the API request with its original idempotency key only when the route documents replay safety.

Show `why` and `fix` in the operator's error view to explain the failure and the suggested recovery. Keep the error identifier available for support and automation.

### Other errors [#other-errors]

One 202 throws instead of resolving with a handle. When the platform holds a write for a second approver, the 202 body carries `status` of `pending-approval`, an `approvalId` and a `statusUrl`, and the SDK throws a `DalpApiError` with the code `sdk.transport.APPROVAL_HELD` and `retryable` false. Do not repeat that write: the approval is the next step, and `error.data.approvalId` and `error.data.statusUrl` tell you which one to follow.

`DalpSdkError` reports a failure inside the SDK rather than an answer from the platform. Constructing a browser client with an API key throws one, and so does a scalar value the SDK cannot decode. Read its `category`, `why` and `fix` fields.

`waitForTransaction`, from the `wait-for-transaction` subpath, throws `DalpTransactionWaitError`. Its `reason` is `terminal-failure`, `timeout`, `aborted`, `funding-paused` or `indexer-rebuild`. By default the helper allows 120 seconds without progress and polls every 1000 milliseconds. It restarts that budget while it holds through a funding pause or an indexer rebuild.

## Application responsibilities [#application-responsibilities]

Validate input before sending a write so the user can correct a form without waiting for an API response.

Refresh the affected reads after settlement. With TanStack Query, invalidate the query keys described in [React Query](https://docs.settlemint.com/docs/api-reference/sdk/react-query#after-a-write).

## Next [#next]

Routes that stream a sequence of events: [Streaming routes](https://docs.settlemint.com/docs/api-reference/sdk/streaming).


# React Native

Source: https://docs.settlemint.com/docs/api-reference/sdk/react-native
Use the DALP TypeScript SDK from an Expo app: supported versions, the transport to pass, where the session lives, and how passkeys reach the device.

## Overview [#overview]

An app talks to the platform the way a server does: it holds the session itself and sends it on every request. A phone has no WebAuthn, its built-in `fetch` cannot read a response as it arrives, and anything in the app bundle ships to every user.

The SDK detects React Native from `navigator.product` and adjusts for all three. It keeps the session in its own cookie store rather than the operating system's cookie jar, it refuses an API key, and it accepts a passkey ceremony you supply. Passkey sign-in works on iOS and fails verification on Android, as [Passkeys](#passkeys) explains.

## Supported runtimes [#supported-runtimes]

| Runtime | Status |
| --- | --- |
| An Expo app | Supported in the SDK's test harness. Pass `fetch` from `expo/fetch`. Passkey sign-in works on iOS only. |
| Bare React Native | Calls and sign-in work on the built-in `fetch`. Streams do not, as [Transport](#transport) explains. |
| Hermes, a simulator, a device | Not exercised in the SDK's own tests. See [What is tested](#what-is-tested). |

## Transport [#transport]

Pass `fetch` from `expo/fetch` to both clients, and share one cookie store between them:

```ts
import { createCookieStoreFetch, createDalpClient, makeCookieStore } from "@settlemint/dalp-sdk";
import { createDalpAuthClient } from "@settlemint/dalp-sdk/auth";
import { fetch as expoFetch } from "expo/fetch";
import * as SecureStore from "expo-secure-store";

type Fetch = (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
const fetch = expoFetch as unknown as Fetch;

const url = "https://dalp.example.com";
const cookieStore = makeCookieStore((await SecureStore.getItemAsync("dalp.session")) ?? "");

const auth = await createDalpAuthClient({ url, cookieStore, fetch, passkey });
const dalp = createDalpClient({ baseUrl: url, fetch: createCookieStoreFetch(cookieStore, fetch) });
```

The type of `expo/fetch` differs from the fetch type the SDK accepts, so the sample casts it. `passkey` is the ceremony that [Passkeys](#passkeys) defines.

The SDK sends `credentials: "omit"` on React Native, so the operating system's cookie jar never holds a second copy of the session that a sign-out would leave behind.

React Native's built-in `fetch` is a polyfill over `XMLHttpRequest`. It resolves only once the whole response has arrived, so a [streaming route](https://docs.settlemint.com/docs/api-reference/sdk/streaming) cannot run on it. The SDK recognises that `fetch`, passed directly or through `createCookieStoreFetch`, and fails the stream with `sdk.stream.UNREADABLE_BODY` before sending the request. A wrapper you write yourself hides it: the error then arrives only when the response ends, and a stream that stays open never ends. `expo/fetch` streams the body, so every route works on it.

## Keeping the session [#keeping-the-session]

The cookie store lives in memory. To survive an app restart, write its header to secure storage after sign-in, sign-out, and any call that may rotate the session, and read it back at launch:

```ts
const saveSession = () =>
  cookieStore.isEmpty()
    ? SecureStore.deleteItemAsync("dalp.session")
    : SecureStore.setItemAsync("dalp.session", cookieStore.header());
```

The header is the session credential. Keep it in the operating system's secure storage through `expo-secure-store`, never in `AsyncStorage` or a log.

## Passkeys [#passkeys]

React Native has no `navigator.credentials`, so the auth client cannot run the WebAuthn ceremony itself. Pass a `passkey` ceremony instead. It has two functions, each taking the options JSON the platform issued and returning the credential JSON the operating system produced:

```ts
import type { DalpPasskeyCeremony } from "@settlemint/dalp-sdk/auth";
import { Passkey } from "react-native-passkey";

const passkey: DalpPasskeyCeremony = {
  authenticate: async (options) =>
    toAssertion(await Passkey.get({ ...options, rpId: options.rpId ?? new URL(url).hostname })),
  register: async (options) => toAttestation(await Passkey.create(options)),
};
```

`toAssertion` and `toAttestation` are yours to write. They copy the module's result into the WebAuthn JSON shape: `id`, `rawId`, `type: "public-key"`, `response`, and `clientExtensionResults`.

`auth.signIn.passkey()` and `auth.passkey.addPasskey()` then work as they do in a browser: the SDK fetches the options, your ceremony talks to the operating system, and the SDK sends the result for verification. A ceremony that throws, for example because the user cancelled, comes back as an `AUTH_CANCELLED` or `REGISTRATION_CANCELLED` error carrying the ceremony's own message, and nothing is sent for verification.

React Native sends no `Origin` header of its own, so the SDK sends your instance's origin on every call. Passkey verification reads it, and the platform serves a stream on a session only to a caller from the instance's own origin. Pass an `origin` entry in the auth client's `headers` to override it there.

The operating system only releases a passkey to an app the domain vouches for:

- **iOS.** Add `webcredentials:<host>` to the app's associated domains and publish `/.well-known/apple-app-site-association` on the host. iOS signs the assertion for the instance's own origin, which the platform accepts.
- **Android.** Publish `/.well-known/assetlinks.json` on the host for the app's package and signing certificate. Android signs the assertion for `android:apk-key-hash:<hash>`, which the platform does not accept, so passkey sign-in on Android fails verification. On Android, sign in with a password.

## What is tested [#what-is-tested]

The SDK's unit suite runs a React Native harness: the `whatwg-fetch` and `abort-controller` polyfills React Native ships, a native HTTP stack with its own cookie jar, a `FileReader`, no WebCrypto, and a model of `expo/fetch`. On that harness it covers password and passkey sign-in, passkey registration, a cached read replayed from a 304, a wallet-verified write, a stream on `expo/fetch` that the platform serves only to the instance's origin, the refused stream on the built-in `fetch`, and the refused API key.

The harness runs in the SDK's unit test runner, not on Hermes, the React Native JavaScript engine, and nothing runs on a simulator or a device.

## Next [#next]

[Effect](https://docs.settlemint.com/docs/api-reference/sdk/effect) covers the same client as an Effect surface.


# TanStack Query

Source: https://docs.settlemint.com/docs/api-reference/sdk/react-query
Every route carries its own query and mutation factories, so a cache key derives from route identity and canonicalised input instead of hand-written keys.

## Overview [#overview]

Every route node on the SDK client carries `queryOptions` and `mutationOptions` beside the call. They return the plain objects `useQuery` and `useMutation` take, with a cache key derived from the route and its input, so no call site writes a key by hand. Nothing here imports TanStack, so the library stays an optional peer a non-React consumer never resolves.

```bash
npm install @tanstack/react-query
```

## Reads [#reads]

```tsx
import { useQuery } from "@tanstack/react-query";
import { dalp } from "./dalp-client";

function TokenList() {
  const { data, isPending, error } = useQuery(dalp.api.token.list.queryOptions({ page: { limit: 50 } }));

  if (isPending) return <Spinner />;
  if (error) return <ErrorState error={error} />;
  return <Table rows={data.data} total={data.meta.total} />;
}
```

`dalp` is the browser client from [Install and configure](https://docs.settlemint.com/docs/api-reference/sdk/install#in-a-browser), exported from `./dalp-client`, and `Spinner`, `ErrorState` and `Table` stand for your own components. `queryOptions` takes the same flat input the call takes and returns `{ queryKey, queryFn }`. The query's own abort signal is passed through to the request, so a component that unmounts cancels its fetch without you wiring anything. Add whatever TanStack options you want by spreading:

```tsx
useQuery({
  ...dalp.api.token.list.queryOptions({ page: { limit: 50 } }),
  staleTime: 30_000,
  placeholderData: keepPreviousData,
});
```

## Cache keys [#cache-keys]

A cache key must distinguish different requests and match equivalent requests. A mismatch can leave stale data. A collision can return data for the wrong input.

A key is the route id, then the canonicalised input:

```ts
["dalp", "token/list", { page: { limit: 50 } }];
```

`canonicalize` sorts object keys recursively and drops undefined values before the key is built. That is what makes two callers passing `{ page: { limit: 50, offset: 0 } }` and `{ page: { offset: 0, limit: 50 } }` share one cache entry instead of fetching twice. Dropping `undefined` matters for the same reason: `{ page: { limit: 50 } }` and `{ page: { limit: 50 }, filter: undefined }` describe the same request, and a literal key would treat them as two.

A route with no input has a two-element key:

```ts
["dalp", "party.users.me"];
```

Because the route id comes before the input, a prefix match invalidates a whole route regardless of its parameters, and the `"dalp"` head keeps DALP entries from colliding with anything else in the same cache.

The key holds no acting context and no credential. When the user switches organisation or signs out, remove the DALP entries with `queryClient.removeQueries({ queryKey: ["dalp"] })` as well as calling `dalp.conditionalRequests.clear()`, or the next screen can show the previous organisation's rows.

To build a key without building options, import the helper:

```ts
import { queryKeyFor } from "@settlemint/dalp-sdk/react-query";

queryKeyFor("token/list", { page: { limit: 50 } });
```

The key has no version segment, because this SDK targets v2 only.

## Writes [#writes]

```tsx
import { useMutation, useQueryClient } from "@tanstack/react-query";

function TransferButton({ tokenAddress }: { tokenAddress: string }) {
  const queryClient = useQueryClient();

  const transfer = useMutation({
    ...dalp.api.token.transfer.mutationOptions(),
    onSuccess: async () => {
      await queryClient.invalidateQueries({ queryKey: ["dalp", "token/list"] });
    },
  });

  return (
    <Button
      disabled={transfer.isPending}
      onClick={() => transfer.mutate({ assetId: tokenAddress, transfers: [{ recipient, amount }] })}
    >
      Transfer
    </Button>
  );
}
```

`mutationOptions` takes call options rather than input, because the input arrives at `mutate` time. It returns `{ mutationKey, mutationFn }`.

The mutation factory sets its own settlement bound of 30 seconds, because a mutation hook holds a spinner for the whole wait. `UI_SETTLEMENT_TIMEOUT_MS` from `@settlemint/dalp-sdk/react-query` exports the value. Override it if your case differs:

```ts
dalp.api.token.transfer.mutationOptions({ settlementTimeoutMs: 60_000 });
```

`isPending` is true for the whole wait, not only the request, and stays true until the mutation resolves with the settled result or a 202 handle.

### Idempotency keys for separate submissions [#idempotency-keys-for-separate-submissions]

A mutation binds its options once and can fire many times. A literal header object is therefore evaluated once, which pins every submission to the first key it produced. Pass a function so each new submission gets a key:

```ts
dalp.api.token.transfer.mutationOptions({
  headers: () => ({ "Idempotency-Key": crypto.randomUUID() }),
});
```

Use this factory for separate submissions with automatic mutation retry disabled. To retry one submission, generate the key once outside the factory and retain it across attempts.

## After a write [#after-a-write]

A settled write changes what reads return. Invalidate by prefix, which is why the key shape matters:

```ts
// One route, every parameter combination.
await queryClient.invalidateQueries({ queryKey: ["dalp", "token/list"] });

// One route with one specific input.
await queryClient.invalidateQueries({ queryKey: dalp.api.token.read.queryOptions({ assetId: tokenAddress }).queryKey });

// Everything DALP.
await queryClient.invalidateQueries({ queryKey: ["dalp"] });
```

`onSuccess` runs for both a settled result and a 202 handle. Check which one it received before invalidating reads that require the settled state. For a pending handle, follow its status and invalidate those reads after settlement.

Prefer the narrowest invalidation that is still correct. Invalidating everything is correct and expensive, and on a busy screen it is visible as a wave of refetches.

## Errors in components [#errors-in-components]

The error a query or mutation surfaces is the same `DalpApiError` a direct call throws, so `error.why` and `error.fix` are available to render and `error.id` is what to branch on. The full contract is under [Errors](https://docs.settlemint.com/docs/api-reference/sdk/mutations#errors).

For retry behaviour, defer to `retryable` rather than to a status code:

```ts
useQuery({
  ...dalp.api.token.list.queryOptions({ page: { limit: 50 } }),
  retry: (failureCount, error) => isDalpApiError(error) && error.retryable && failureCount < 3,
});
```

Do not turn on automatic retry for mutations. A stable idempotency key alone does not make a route replay-safe, and TanStack Query does not retry a mutation by default.

## Validating input before a write [#validating-input-before-a-write]

The SDK does not validate request input, so validating a form before submitting it is your choice of library rather than something the client imposes. Success responses are different: the client checks each one against the route's schema. Validate the shape you are about to send, then send it:

```ts
const parsed = TransferForm.safeParse(formValues);
if (!parsed.success) return showFieldErrors(parsed.error);
await transfer.mutateAsync({ assetId: tokenAddress, ...parsed.data });
```

The platform validates the input again on arrival, and its check decides. Client-side validation gives the user an answer without a round trip.

## Next [#next]

Rendering on a server: [Server-side rendering](https://docs.settlemint.com/docs/api-reference/sdk/server-rendering).


# Server-side rendering

Source: https://docs.settlemint.com/docs/api-reference/sdk/server-rendering
On a server render the browser holds the session and the server does not, so the SDK forwards the request's headers under an origin allow list.

## Overview [#overview]

A server render has no session cookie of its own. A server-side `createDalpClient` either forwards the signed-in user's session from the incoming request with `ssr.requestHeaders`, or acts as your service with an API key.

Forwarding the session renders what this user is allowed to see. An API key renders what your service is allowed to see. Choosing the wrong one is an authorisation mistake, and on a platform that hosts several organisations it can leak one organisation's data to another.

## The choice [#the-choice]

**Forward the user's session**

The render sees exactly what the signed-in user sees. Correct for any page whose content is that user's data: their portfolio, their organisation's assets, their action list. Requires the incoming request's headers.



**Use a server API key**

The render acts as your service. Correct for content that is the same for everyone: a public asset page, a marketing figure, a scheduled export. Never correct for per-user content, because the key's authority is not the user's. Issue that key with the `read` scope, so a render credential cannot write.

If two different users who load this page should see different content, forward the session. Rendering per-user content with a service key is how a page shows data meant for one user or organisation to someone else, and it does not surface in testing where everyone shares an account.

## Forwarding a session [#forwarding-a-session]

Pass the incoming request's headers as `ssr.requestHeaders` and the SDK builds a fetch that forwards the incoming request's whole `Cookie` header to your instance, with its `Origin` and tracing headers. Every cookie the browser sent to your app therefore reaches the instance, not only the DALP session.

```ts
import { createDalpClient } from "@settlemint/dalp-sdk";

function serverClient(request: Request) {
  return createDalpClient({
    baseUrl: process.env.DALP_API_URL!,
    runtime: "server",
    ssr: { requestHeaders: request.headers },
  });
}
```

Build one per request. A client built once at module scope and shared holds the first request's headers and serves that user's session to everyone who arrives after, which is the same leak as the wrong credential arriving by a different route.

### What the forwarding does for you [#what-the-forwarding-does-for-you]

The SDK limits where a forwarded cookie can go and which writes it can carry.

**Destinations are on the allow list.** The first request may only go to your instance's origin or to one you name in `ssr.allowedOrigins`. An unapproved destination throws before the request goes out, so a mistyped base URL fails rather than carrying a session somewhere else. A redirect can still lead a read to another origin, without the session.

**Redirects lose credentials on the way out.** Redirects are followed manually, up to five. A sixth redirect throws an error with the name `DalpSsrSecurityError` and the message "DALP SDK: SSR fetch exceeded the redirect limit." The SDK does not export that class, so match on `error.name`. As long as each hop stays inside the allow list, the cookie and context headers travel with it. The first hop outside strips them: the cookie, authorisation, the API key, the idempotency key, the tenant and acting-context headers (`X-Organization-Id`, `X-Participant`, `X-Executor`, `X-Chain-Id`, `X-Selected-Signers`, `X-Network-Id` and `X-Custody-Account-Id`), the `Origin` and `Referer` headers, and the tracing headers. The SDK refuses a redirect that would carry a write method outside the allow list, because the write would arrive without its acting context.

**Cookie-authenticated writes need a trusted origin.** A mutation carrying a forwarded cookie is refused unless the incoming request's `Origin` is your instance's origin or one you list in `ssr.allowedOrigins`, and the request does not declare itself cross-site. When your app is served from a different origin than `baseUrl`, add the app's public origin to `ssr.allowedOrigins`, or every server action that writes is refused. That is cross-site request forgery protection inside the SDK, and it is why a server action that writes needs the real request headers rather than a hand-built set.

## TanStack Start [#tanstack-start]

Build the client inside the server function or loader that has the request, and let the router's dehydration carry the result to the browser.

```ts
// app/lib/dalp.server.ts
import { createDalpClient } from "@settlemint/dalp-sdk";
import { getRequest } from "@tanstack/react-start/server";

export function dalpServer() {
  const request = getRequest();
  return createDalpClient({
    baseUrl: process.env.DALP_API_URL!,
    runtime: "server",
    ssr: { requestHeaders: request.headers },
  });
}
```

```ts
// app/routes/tokens.tsx
export const Route = createFileRoute("/tokens")({
  loader: async ({ context }) => {
    await context.queryClient.ensureQueryData({
      ...tokenListOptions,
      queryFn: () => dalpServer().api.token.list({ page: { limit: 50 } }),
    });
  },
  component: TokenList,
});

function TokenList() {
  const { data } = useSuspenseQuery(tokenListOptions);
  return <Table rows={data.data} />;
}
```

The loader and the component share one cache key and use different fetches. On the server, the fetch is the session-forwarding client. In the browser, it is the ordinary browser client. Reusing `queryOptions` for the key on both sides is what makes the hydrated entry the one the component reads, instead of a second fetch on mount.

Keep the server client out of any module a component imports. A `.server.ts` suffix or an equivalent rule in your build is what stops a server-only import from being pulled into the browser bundle.

## Next.js [#nextjs]

### Server components [#server-components]

A server component has no request object, so read the headers from `next/headers`:

```tsx
// app/tokens/page.tsx
import { headers } from "next/headers";
import { createDalpClient } from "@settlemint/dalp-sdk";

export default async function TokensPage() {
  const dalp = createDalpClient({
    baseUrl: process.env.DALP_API_URL!,
    runtime: "server",
    ssr: { requestHeaders: await headers() },
  });

  const tokens = await dalp.api.token.list({ page: { limit: 50 } });
  return <TokenTable rows={tokens.data} />;
}
```

Calling `headers()` opts the route out of static rendering, which is correct here: a page rendered from a user's session cannot be a shared static artifact.

Read `DALP_API_URL` and `DALP_API_KEY` without the `NEXT_PUBLIC_` prefix. A prefixed variable is inlined into the client bundle at build time, and a prefixed API key is a published API key.

### Route handlers and server actions [#route-handlers-and-server-actions]

Both have the request, directly or through `headers()`:

```ts
// app/api/tokens/route.ts
export async function GET(request: Request) {
  const dalp = createDalpClient({
    baseUrl: process.env.DALP_API_URL!,
    runtime: "server",
    ssr: { requestHeaders: request.headers },
  });

  const tokens = await dalp.api.token.list({ page: { limit: 50 } });
  return Response.json(tokens);
}
```

```ts
// app/actions.ts
"use server";

import { headers } from "next/headers";
import { createDalpClient } from "@settlemint/dalp-sdk";

export async function transfer(input: { assetId: string; recipient: string; amount: string }) {
  const dalp = createDalpClient({
    baseUrl: process.env.DALP_API_URL!,
    runtime: "server",
    ssr: { requestHeaders: await headers(), allowedOrigins: [process.env.APP_PUBLIC_ORIGIN!] },
  });

  const { assetId, recipient, amount } = input;
  return dalp.api.token.transfer(
    { assetId, transfers: [{ recipient, amount }] },
    {
      headers: { "Idempotency-Key": crypto.randomUUID() },
    }
  );
}
```

Pass the real request headers to a server action that writes. A hand-built header set with no `Origin` is refused.

The action resolves once the platform's wait ends, with the settled resource, or with a 202 handle if settlement outlasts the wait. Call `revalidatePath` or `revalidateTag` after a settled result and the revalidated render reads data that reflects the write. A handle means the action should report the write as pending instead. Set a settlement bound the action's own timeout can accommodate, since a serverless function that is killed mid-wait leaves the instruction live with nobody watching it.

### Hydrating the browser cache [#hydrating-the-browser-cache]

Fetching on the server and continuing in the browser without a second fetch on mount takes two steps. Dehydrate a query client in the server component, then hydrate it around the tree:

```tsx
// app/tokens/page.tsx
import { dehydrate, HydrationBoundary, QueryClient } from "@tanstack/react-query";

export default async function TokensPage() {
  const dalp = createDalpClient({
    baseUrl: process.env.DALP_API_URL!,
    runtime: "server",
    ssr: { requestHeaders: await headers() },
  });

  const queryClient = new QueryClient();
  await queryClient.prefetchQuery(dalp.api.token.list.queryOptions({ page: { limit: 50 } }));

  return (
    <HydrationBoundary state={dehydrate(queryClient)}>
      <TokenTableClient />
    </HydrationBoundary>
  );
}
```

```tsx
// app/tokens/token-table-client.tsx
"use client";

export function TokenTableClient() {
  const { data } = useSuspenseQuery(browserDalp.api.token.list.queryOptions({ page: { limit: 50 } }));
  return <Table rows={data.data} />;
}
```

The two clients differ, but the keys match. `queryOptions` derives its key from route identity and canonicalised input, with nothing about the base URL or the credential in it, so the server-side entry and the browser-side query name the same thing. A refetch on mount can also follow TanStack Query's staleness policy. Check `staleTime` and `refetchOnMount`, as well as matching parameters and query keys.

Create the server-side `QueryClient` per request. A shared one caches one user's data across requests, which is the same class of mistake as a shared client.

## Services and jobs outside a framework [#services-and-jobs-outside-a-framework]

Outside a rendering framework no session exists to forward. Use an API key and build the client once:

```ts
import { createDalpClient, secret } from "@settlemint/dalp-sdk";

export const dalp = createDalpClient({
  baseUrl: process.env.DALP_API_URL!,
  apiKey: secret(process.env.DALP_API_KEY!),
  runtime: "server",
  settlementTimeoutMs: 90_000,
});
```

Choose a settlement wait that fits the job timeout. The platform holds a response for 5 to 99 seconds, and the SDK clamps a larger value to 99. A longer wait can reduce pending handles. A shorter wait returns control sooner. The job acts in the organisation its API key was issued for, so issue one key per organisation the job serves.

## Next [#next]

The Effect surface: [Effect](https://docs.settlemint.com/docs/api-reference/sdk/effect).


# Streaming routes

Source: https://docs.settlemint.com/docs/api-reference/sdk/streaming
Read streaming routes as async iterables through the DALP TypeScript SDK, with decoded events, cancellation, and error handling.

## Overview [#overview]

A streaming route answers with a stream of server-sent events instead of one body. A deployment reports progress across several minutes, a transaction moves through states, and an activity feed has no last item, so their routes stream.

In the SDK they are ordinary nodes on the same tree. What differs is what comes back: an async iterable of frames, one decoded frame per server-sent event, instead of a promise of one payload.

```ts
for await (const frame of dalp.api.transactionsV2.statusStream({ transactionId })) {
  console.log(frame);
}
```

## Reading a stream [#reading-a-stream]

Frames arrive in order and are parsed as JSON when they carry JSON.

```ts
async function watchDeployment(deploymentId: string) {
  for await (const frame of dalp.api.platform.organizations.organizationsDeployStream({ deploymentId })) {
    render(frame);
  }
  // The loop ends when the platform closes the stream.
}
```

When the platform ends a stream with its reserved failure event, the loop throws a `DalpApiError` with the code `sdk.stream.FAILED` and `retryable` true. A client whose fetch cannot expose a streamed response body throws `sdk.stream.UNREADABLE_BODY` instead, and that error is not retryable. [React Native](https://docs.settlemint.com/docs/api-reference/sdk/react-native) covers the fetch that fixes it.

Breaking out of the loop closes the connection. So does an early `return` or a thrown error inside the body, because the iterator's cleanup runs either way and cancels the underlying read. You do not need to close anything by hand.

## Cancelling [#cancelling]

Pass an `AbortSignal` the same way you would on any other call:

```ts
const controller = new AbortController();

for await (const frame of dalp.api.assetPortfolioV2.v2.actions.stream({}, { signal: controller.signal })) {
  render(frame);
}
```

In React, abort in the effect's cleanup so a component that unmounts mid-stream does not hold a connection open:

```tsx
useEffect(() => {
  const controller = new AbortController();

  void (async () => {
    try {
      for await (const frame of dalp.api.assetPortfolioV2.v2.actions.stream({}, { signal: controller.signal })) {
        setLatest(frame);
      }
    } catch (error) {
      if (!controller.signal.aborted) setError(error);
    }
  })();

  return () => controller.abort();
}, []);
```

The `aborted` check matters. An aborted stream rejects with the abort reason, and treating your own cleanup as a failure is how an unmount shows an error toast.

## What the SDK does not do [#what-the-sdk-does-not-do]

**It does not reconnect.** One call opens one connection. When the stream ends, it has ended, and if it ended before the terminal event you were waiting for, that is a fact your code sees rather than a gap it never learns about.

If the connection ends before a terminal event, read the current status before deciding whether to reconnect. A missed event does not establish the transaction outcome.

The deployment, invitation, migration and token-creation streams send a `complete` frame only with the run's real verdict. When the server cannot read the run's progress, or no run is recorded for the id, the stream ends with its declared failure event instead. The deployment, invitation and migration streams wait up to two minutes for a run to appear before they end this way. On that event the SDK throws an error with the code `sdk.stream.FAILED`. That error means the outcome is not known, not that the run failed. Read the status route, then open the stream again if the run is still going.

On a settlement stream, a reconnect that resumed from the live edge would miss a `COMPLETED` sent while the connection was down, and the caller would wait forever. A status stream therefore sends the current row as its first frame on every subscription instead of resuming from a cursor. Use the stream to watch progress and the status route for the verdict. A status stream also closes after 180 seconds while the transaction is still in flight. Reopen it, and its first frame is the current state.

**It does not classify frames.** A frame is data. Whether a given frame is terminal, and whether terminal means success, is domain knowledge the route defines and your code applies.

## Reconnecting [#reconnecting]

When you want a stream that survives a dropped connection, wrap the call. The SDK ships the wrapper the Console uses:

```ts
import { consumeSseUntilTerminal, SseLifecycleError } from "@settlemint/dalp-sdk";

const outcome = await consumeSseUntilTerminal({
  connect: async (signal) => ({
    stream: dalp.api.transactionsV2.statusStream({ transactionId }, { signal }),
  }),
  classify: (frame) => {
    if (frame.family !== "evm") {
      if (frame.submissionStatus === "settled") return "success";
      return frame.submissionStatus === "failed" || frame.submissionStatus === "expired" ? "failure" : "continue";
    }
    if (frame.status === "COMPLETED") return "success";
    // A dead letter that may still land is not an answer yet: keep following it.
    if (frame.status === "DEAD_LETTER" && frame.mayStillLand === true) return "continue";
    if (frame.status === "FAILED" || frame.status === "DEAD_LETTER" || frame.status === "CANCELLED") {
      return "failure";
    }
    return "continue";
  },
  signal: outerSignal,
});
```

It reconnects with backoff while frames are non-terminal, stops on the verdict `classify` returns, and throws `SseLifecycleError` when it gives up, with a `reason` distinguishing an abort from a terminal failure from a transport failure.

The reconnect budget is a wall-clock window rather than a count of attempts. When every failure is instant, a fixed count is spent in a few seconds, so a backend that stalls for longer exhausts the budget before it has recovered. The default window is 60 seconds. It is anchored at the first failure of a run, and restarts only once a connection has stayed up for 20 seconds, which counts as recovered. The wait between attempts starts at 250 milliseconds, doubles each time, and stops growing at 5 seconds. `reconnectWindowMs`, `healthyConnectionMs`, `initialBackoffMs`, and `maxBackoffMs` change these defaults, and `maxReconnects` replaces the window with a plain attempt count. A long-lived stream that dies late therefore gets a full window, rather than the remains of one spent hours earlier.

Receiving events does not count as recovery, because a stream that replays its opening frame on every subscription would then clear the failure streak on each attempt and reconnect forever.

## Which routes stream [#which-routes-stream]

A streaming route is typed as returning an async iterable, so awaiting one as a body is a type error. Streams exist for organisation and invitation deployment progress, migration progress, transaction status, the action inbox, API request logs, chain-health snapshots, token creation, the trading venue's market and operator order feeds, and custody account-request lifecycle.

The full list, with each route's frames, is in the [API reference](https://docs.settlemint.com/docs/api-reference), where every streaming route is documented beside the routes that return a body.

## Funding requirement roles in stream frames [#funding-requirement-roles-in-stream-frames]

The deployment, invitation, migration and token-creation streams can carry a funding requirement: a wallet that needs gas before the work can go on. A frame with `type` set to `requirement-required` carries a `role` at `frame.payload.role`. The `role` is the funding purpose of the requirement. The wallet that is short is `frame.payload.address`. Several requirements can share one role, so do not key requirements by `role` alone. A `requirement-resolved` frame has no `role`, so narrow on `frame.type === "requirement-required"` before you read `frame.payload.role`.

The stream sends a `requirement-required` frame again, under the same `requirementId`, when the requirement's amounts change or when the balance the wallet already holds, `frame.payload.alreadySent`, changes. Replace the requirement you hold with the newer frame.

The set of roles can grow, and the published API document lists the roles as a closed `enum`. The SDK checks every stream frame against that `enum`. A frame with a role that your SDK version does not know throws `sdk.response.MALFORMED_SUCCESS` before your loop sees the frame. The route methods of the SDK have no option to skip this check. You have two ways to handle a new role:

- Upgrade the SDK when a new role ships. Each SDK release is built from the API document of that release.
- Call the stream route yourself with an HTTP client. Send the same URL, credentials, and `Accept: text/event-stream` header that the SDK sends, then pass the response body (a `ReadableStream<Uint8Array>`) to `decodeEventStream` without a frame decoder. It parses each frame as JSON and does not check the `enum`. You handle request errors yourself on this path.

If you decode frames without the `enum` check, handle an unknown role like this:

- Read `role` as a string.
- Use the known values only to choose a label.
- Show an unknown role as a generic funding requirement. Never drop the row. A wallet that is short is still short, and the operator needs to see it.

| Role | Funding purpose |
| --- | --- |
| `org-creator-eoa` | Organisation creator wallet |
| `member-admission-eoa` | Wallet of the member being admitted |
| `token-creator-eoa` | Token creator wallet |
| `org-vault-eoa` | Organisation vault wallet |
| `org-bundler-eoa` | Bundler wallet that submits account abstraction operations |
| `org-relayer-eoa` | Relayer wallet |
| `aa-runway-eoa` | Account abstraction runway wallet |
| `queued-write-eoa` | Wallet that signs a queued write |
| `smart-account` | Smart account that needs a prefund |
| `paymaster-deposit` | Paymaster deposit at the EntryPoint |

The funding requirements list route, `GET /api/v2/organizations/funding-requirements`, publishes `role` as a nullable open string. A stored requirement with no known role carries `null`, so treat `null` like an unknown role: show it as a generic funding requirement.

## Next [#next]

Wiring calls into a React application: [TanStack Query](https://docs.settlemint.com/docs/api-reference/sdk/react-query).


# Consuming events

Source: https://docs.settlemint.com/docs/api-reference/webhooks/consuming
How a receiver reads DALP webhook deliveries: outcomes, identifiers, ordering, retries, Resend, Replay, chain of custody, receipts and retractions.

The platform attempts each event it records for an endpoint at least once, and can send one event more than once. A Replay sends an earlier outcome again under a new event id. Automatic delivery stops at a terminal failure or after three days, and the platform records no events for an endpoint while it is switched off. Endpoint registration and signature verification are in the [setup guide](https://docs.settlemint.com/docs/api-reference/guides/webhooks).

## Outcome model [#outcome-model]

An API response that accepts a write request does not mean the transaction is final on chain. Many write routes queue the transaction, so the response confirms only that the platform accepted the instruction. The lifecycle state of an event tells you how far the fact has progressed. The [lifecycle page](https://docs.settlemint.com/docs/api-reference/webhooks/lifecycle) defines each state. The [idempotency and async settlement guide](https://docs.settlemint.com/docs/api-reference/guides/idempotency-async-settlement) covers the write response.

A chain reorganisation replaces recent blocks with a competing set of blocks. The platform sends a `final` event for a chain log only after the block passes the network's finality depth, which [Lifecycle states](https://docs.settlemint.com/docs/api-reference/webhooks/lifecycle#the-states-live-events-carry) defines.

| Signal | What it tells you | What it does not tell you |
| --- | --- | --- |
| A write response that accepted the request | The platform accepted the instruction. | That the transaction reached the chain or is final. |
| A `provisional` event | The platform reports a fact that can still change. A chain reorganisation can still remove the block of a chain log. | That the fact is complete. |
| A `final` event | The platform reports the fact as complete. The block of a chain log passed the finality depth. | That no retraction can follow. A trade bust retracts a settled trade that the platform already reported as `final`. |
| A `retracted` event | An earlier event no longer stands. | That your endpoint received the earlier event. [Retractions](#retractions) covers this case. |

## Identifiers and deduplication [#identifiers-and-deduplication]

Verify the exact raw body and its signature before trusting an event or using its identifiers. The [setup guide](https://docs.settlemint.com/docs/api-reference/guides/webhooks#verify-the-signature) documents verification. A lost response can cause a duplicate delivery, so a successful verification does not mean the event is new.

| Identifier | Where it appears | Same across attempts | Use it to |
| --- | --- | --- | --- |
| `webhook-id` header and `evt_id` body field | Every delivery. Both hold the same value, the id of the event. | Yes. A retry and a Resend keep it. A Replay mints a new one. | Deduplicate deliveries of one event. |
| `webhook-delivery-id` header | Every delivery. | No. Each attempt gets a new value. | Identify one attempt, and name it in a counter-signed receipt. |
| `source_id` body field | Every event except a test event. | Yes. A Replay keeps it. | Recognise the same outcome of one event name when it returns under a new event id. |
| `request.idempotency_key` body field | Request correlation metadata when the transaction's caller attribution is unambiguous. | Yes, when present. | Correlate with a request when the stored event supplies a key. Never deduplicate deliveries on it. |

The platform adds the headers `webhook-delivery-id` and `webhook-endpoint-id` to the three headers of the open Standard Webhooks specification: `webhook-id`, `webhook-timestamp` and `webhook-signature`. The `webhook-endpoint-id` header names your endpoint and stays the same for it. The [setup guide](https://docs.settlemint.com/docs/api-reference/guides/webhooks) lists every header.

Deduplicate deliveries on `webhook-id`. A retry, a Resend, and a send that the platform repeats when it stopped before recording the attempt all keep the `webhook-id` of the first attempt. Answer a `webhook-id` you already handled with a 2xx response.

A Replay is a new event with a new `evt_id`, so `webhook-id` does not match it. Its `source_id` and its payload identifiers match the original. When you recover through a Replay, deduplicate outcomes on `source_id`, or on payload identifiers such as the `transactionHash` and `logIndex` of a token transfer.

For each endpoint, the platform stores at most one event with a given `source_id`, excluding Replay and test events. A `provisional` event and the `final` event for the same fact have different `source_id` and `evt_id` values, because the `source_id` includes the event name and version. Match them through the payload identifiers.

The optional `request.idempotency_key` is a correlation field, not a delivery deduplication key. A chain-sourced event includes the caller's key when the transaction can be attributed to one organisation and one nonempty caller key, and that organisation owns the endpoint. Conflicting attribution, a missing key or an endpoint in another organisation leaves the field absent. A Replay or retraction preserves a key already present in the stored event. When the field is absent, correlate through the payload identifiers rather than inventing a key.

The helper `verifyWebhook` in `@settlemint/dalp-sdk/verify-webhook` accepts an optional `replayStore`. With a store, it claims the `webhook-id` of each delivery whose signature verifies and returns `REPLAYED_EVENT` for an id that is already claimed. Answer `REPLAYED_EVENT` with a 2xx response. When your handler fails, call `release` on the verified result, so the platform's retry of that `webhook-id` verifies again. Your store must claim each id in one atomic write. [Refuse a repeated delivery](https://docs.settlemint.com/docs/api-reference/guides/webhooks#refuse-a-repeated-delivery) in the setup guide explains the store methods and the cases a store does not cover.

## Ordering [#ordering]

The platform assigns each event a position in its endpoint's delivery sequence. A later eligible event waits while an earlier event remains pending, including during backoff. A successful attempt, a terminal failure, or exhaustion of the retry window releases the later events. A missing counter-signed receipt can reopen an event for retry.

A linked correction waits for its cause. The platform sends it after the event it replaces is delivered, or after that event can no longer be delivered. This permits a correction to identify an event your system never received.

The platform gives no guarantee of:

- Order between endpoints. Each endpoint has its own sequence.
- Delivery of a chain `final` event before the events recorded after it. An event that waits for chain finality does not hold back later events, so its delivery can follow theirs.

A Replay takes the next place in the endpoint's sequence, after every event the platform already recorded.

## Retries [#retries]

Your response decides what the platform does next.

| Your endpoint answers | The platform |
| --- | --- |
| A `2xx` status | Marks the attempt delivered and does not retry. |
| `408` or `429` | Retries. Use these statuses to ask for a later attempt. |
| Any other `4xx` status | Treats the response as terminal, does not retry, and ends delivery of the event. |
| A `5xx` status | Retries. |
| A redirect or any other status. The platform follows no redirects. | Retries. |
| No answer within 20 seconds, a refused or reset connection, a Domain Name System (DNS) lookup failure, or a Transport Layer Security (TLS) handshake failure | Retries. |

The [receipt rules](#counter-signed-receipts) also apply after a 2xx response when receipts are enabled.

When your receiver cannot process an event at that moment, answer `503` or `429`, not another `4xx`. A `4xx` ends delivery of the event, and only a Resend recovers it.

The platform also checks the endpoint address before each attempt. When the address falls outside the destination policy, for example because its hostname now resolves to a private address, the platform sends nothing. It marks the attempt `TARGET_REFUSED`, does not retry, and ends delivery of the event. Correct the endpoint URL, then use Resend.

The platform waits before each retry. The base wait doubles with each failed attempt: 30 seconds after attempt 1, 60 seconds after attempt 2, 2 minutes after attempt 3, and so on, limited only by the retry window. The platform multiplies the base wait by a random factor from 0.7 to 1.3. When a failed response carries a `Retry-After` header, the platform waits at least that long. The wait never exceeds the time left in the retry window. An attempt times out after 20 seconds.

The retry window is three days. It starts when the platform records the event, not at the first attempt.

At exhaustion, the platform abandons automatic delivery, writes a warning log, and records a failed trace span. Later eligible events can proceed. The recorded attempts remain available in the endpoint's delivery history, under Event deliveries in the Console. A terminal failure also stops automatic delivery. Resend and Replay provide recovery actions after the receiver is repaired.

A run of failed attempts can also switch the endpoint off. After 30 consecutive failed attempts, test events excluded, the platform opens the endpoint's circuit breaker and switches the endpoint off. The platform queues no new events for an endpoint that is off, and no Replay recovers them later. It probes the endpoint and resumes delivery after two successful probes. Enabling the endpoint with `PATCH /api/v2/webhooks/{webhookId}` and `disabled: false` resets the breaker at once. The [Webhook Delivery concept](https://docs.settlemint.com/docs/concepts/events-out/webhook-delivery) describes the circuit breaker in full.

## Resend and replay [#resend-and-replay]

Resend and Replay are authenticated Platform API requests. The [authentication guide](https://docs.settlemint.com/docs/api-reference/guides/authentication-api-keys) describes the accepted credentials. The [v2 API reference](https://docs.settlemint.com/docs/api-reference/v2) defines their request, response and error bodies. The event-delivery signing secret is not a replacement for API authentication.

Both actions send an event again. They differ in what they keep.

| Property | Resend | Replay |
| --- | --- | --- |
| Request | `POST /api/v2/webhooks/{webhookId}/deliveries/{deliveryId}/retries` | `POST /api/v2/webhooks/{webhookId}/replays` |
| What it selects | One attempt, which must be the latest attempt of its event. | A block range on one chain, or one event by `evt_id`. |
| Event id | The same `evt_id` and `webhook-id`. | A new `evt_id` for each event. |
| `source_id` | The same. | The same. |
| Attempt history | Adds one attempt to the event. Earlier attempts keep their recorded outcome. | Creates a new event with its own attempt history. |
| `is_replay` | Unchanged. | `true` on every replayed event. A live event has no `is_replay` field. |

A Resend queues one more attempt. It runs even when an earlier attempt succeeded, so your endpoint can receive an event it already acknowledged. The call returns `deliveryId` and `scheduled`. The value `scheduled` is `false`, and the platform changes nothing, when any of these holds:

- The attempt is not the latest attempt of its event.
- The event was replaced or cancelled after a chain reorganisation, so the platform no longer delivers it.
- A newer attempt is already claimed, or an earlier Resend has not produced an attempt.

A retry waiting in backoff does not block a Resend.

A Resend does not restart the retry window. The platform measures the window from when it recorded the event. A failed Resend attempt on an event older than three days gets no retry.

A Replay takes either a block range or one event. The block range holds `fromBlock`, an optional `toBlock`, and `chainId`. Without `toBlock`, the range ends at the highest block of an event recorded for the endpoint on that chain. The single event holds `evtId` and an optional `chainId`. The response returns `replayId`, `eventsEnqueued` and `snapshotToBlock`, the last block the range covered. The platform resends the stored payload with its lifecycle state, so a replayed `provisional` event is still `provisional`.

Do not use Replay arrival order or a global ranking of `lifecycle_state` values to replace a business record. Follow the event family's correlation and transition rules in the [catalogue](https://docs.settlemint.com/docs/api-reference/webhooks/events). A replayed provisional transfer does not undo its final confirmation. Retain explicit `supersedes` relationships so that an older observation cannot restore a fact already withdrawn. If the Replay's relationship to your record is unclear, reconcile the resource before overwriting that record.

A Replay is subject to these rules:

- The platform rejects it while the endpoint is switched off or its circuit breaker is open.
- A range whose `toBlock` is before its `fromBlock` is rejected with `WEBHOOK_REPLAY_RANGE_REVERSED`.
- A range wider than 10,000 blocks needs `confirmLargeRange` set to `true`. Without it, the platform rejects the range with `WEBHOOK_REPLAY_RANGE_TOO_LARGE`.
- A `chainId` the organisation has no network for is rejected with `WEBHOOK_REPLAY_CHAIN_NOT_AVAILABLE`, before anything is queued. A network that the organisation registered can still be replayed after it is turned off.
- An organisation can start at most 10 Replays per minute on each API server, because each server counts its own requests.
- The platform does not replay an event that a chain reorganisation replaced or cancelled.

If a Replay response is lost, repeating the request can queue the same outcomes again with new event ids. Deduplicate those outcomes by `source_id`, and do not assume the second request repeats the first response. The Resend conditions still apply to its original `deliveryId`. Treat neither Resend nor Replay as safe to repeat after an API failure.

## Chain of custody [#chain-of-custody]

`GET /api/v2/webhooks/events/{evtId}/chain-of-custody` returns the recorded dispatch history of one event. The record is the platform's own account of what it sent. It is not signed, it is stored with the event, and the [retention cleanup](#delivery-history-retention) deletes it 30 days after delivery ends. Keep your own copy of evidence you must retain, or enable [counter-signed receipts](#counter-signed-receipts). The route needs webhook management permission. The Console shows the same record under "Chain of custody" in the "Webhook event" sheet.

| Field | Contents |
| --- | --- |
| `hops` | One hop for each successful delivery attempt, with `stage` set to `dispatch-attempt`, `contentHash`, `signedBy` holding the endpoint id, and `recordedAt`. `contentHash` is `sha256:` followed by the SHA-256 digest of the exact body the platform sent. |
| `merkleRoot` | The SHA-256 digest of the hops' `contentHash` values joined with `:`, in hexadecimal. |
| `platformSignature` | `dalp-platform:` followed by `merkleRoot`. It labels the root and is not a cryptographic signature. |

A hop's `contentHash` equals the body hash a [counter-signed receipt](#counter-signed-receipts) submits for the same body, so the two records can be matched. An event with no successful attempt has no hops.

## Delivery history retention [#delivery-history-retention]

The platform periodically deletes settled delivery history more than 30 days old. It measures the age from when delivery ended, not from when the event was recorded. The event's delivery attempts and counter-signed receipts are removed with it.

This cleanup includes final and retracted events. It also includes provisional events recorded inside the platform, such as `trading-venue.order-status.provisional` and `trading-venue.price-alert.triggered`: those events do not become final. Pending deliveries, test events and provisional observations from chain logs are outside this cleanup.

The 30-day retention period does not extend the three-day retry window. Keep your receiver's business records and acknowledgements for as long as your audit policy requires. The platform's delivery history is not a permanent archive.

## Counter-signed receipts [#counter-signed-receipts]

The platform signs each delivery over `webhook-id`, `webhook-timestamp` and the exact body, as the [setup guide](https://docs.settlemint.com/docs/api-reference/guides/webhooks#verify-the-signature) describes. A 2xx response records that your endpoint answered. A counter-signed receipt records your system's acknowledgement of the exact body, signed with the endpoint's webhook signing secret. The endpoint setting `counterSignedReceipts` enables this acknowledgement. Enable it when you must show that your system, not only a proxy in front of it, accepted the exact body. Your receiver then posts a receipt within the receipt window after each 2xx response, or the platform retries the event. After a successful attempt, the platform schedules a deadline for the receipt.

Receipt submission requires [Platform API authentication](https://docs.settlemint.com/docs/api-reference/guides/authentication-api-keys) as well as the consumer signature. The [v2 API reference](https://docs.settlemint.com/docs/api-reference/v2) defines the request and response contract for `POST /api/v2/webhook-receipts`.

A successful submission returns the receipt resource. A repeated valid submission within the receipt window updates the receipt for that delivery, including its verification timestamp. The response need not be identical. A delivery already marked as receipt-timed-out is rejected rather than reopened.

You post the receipt to `POST /api/v2/webhook-receipts` with `deliveryId`, `evtId`, `endpointId`, `consumerSignature` and `innerEventHash`. The platform accepts a valid signature made with the endpoint's active secret or its previous secret during rotation. The signing string has five lines, joined with `\n`, with no trailing newline.

| Line | Value |
| --- | --- |
| 1 | The scheme name `dalp.whr.v1`. |
| 2 | The `webhook-delivery-id` of the delivery you answer. |
| 3 | The `webhook-endpoint-id` of the delivery. |
| 4 | The `webhook-id` of the delivery. |
| 5 | The body hash: `sha256:` followed by the lowercase hexadecimal SHA-256 digest of the exact body you received. |

SHA-256 means Secure Hash Algorithm 256. The receipt signature is a keyed-hash message authentication code (HMAC) with SHA-256 over the signing string, written in hexadecimal. The key is the endpoint signing secret without its `dalp_whsk_` prefix, decoded from base64. The SDK functions `signWebhookReceipt` and `buildReceiptSigningString` in `@settlemint/dalp-sdk/sign-webhook-receipt` produce the signature and the string.

The receipt window is 30 seconds by default. The endpoint field `receiptTimeoutSeconds` sets it to a whole number from 1 to 60. The window starts after your 2xx response.

| Receipt | The platform |
| --- | --- |
| Verifies and matches the body | Records the receipt. |
| Has a signature that does not verify | Rejects it with status 401 and the failure class `RECEIPT_INVALID_SIG`. |
| Arrives after the window closed | Rejects it with status 401 and the failure class `RECEIPT_WINDOW_CLOSED`. |
| Has a hash that differs from the sent body | Rejects it with status 401 and `RECEIPT_HASH_MISMATCH`. It marks the attempt `RECEIPT_HASH_MISMATCH`, schedules no retry, settles the event, and counts the attempt toward the circuit breaker. |
| Does not arrive within the window | Marks the attempt `RECEIPT_TIMEOUT` and retries on the normal backoff. The retry repeats the same `webhook-id`. |

An invalid signature rejects the receipt submission without settling the event or scheduling a new delivery. Correct the signature and submit it again while the receipt window is open. If no valid receipt arrives by the deadline, the receipt-timeout path retries delivery within the event's retry window.

A correctly signed receipt with the right hash can still replace a hash-mismatched receipt for the same delivery. The platform then records the receipt and restores the attempt as delivered, as long as the attempt has no recorded receipt timeout.

`GET /api/v2/webhook-receipts` lists the stored receipts, and `GET /api/v2/webhook-receipts/{id}` reads one. Both need webhook management permission. A receipt submission for a delivery that did not require a receipt when the platform sent it answers status 404 with `WEBHOOK_DELIVERY_NOT_FOUND`.

A late submission does not reopen its receipt window or schedule another attempt. Submit a receipt for the next delivery if the platform retries it. A rejected receipt submission and a retry of the webhook delivery are separate operations.

## Payload shape [#payload-shape]

Use the [machine-readable event definitions](https://docs.settlemint.com/.well-known/dalp-events.json) or the SDK's `Webhook` types for each event's envelope and payload schema. Those schemas do not hold the consent field-path list.

Each endpoint has a payload shape. The shape controls whether the personal data fields of an event reach your endpoint. Each event defines its own personal data fields, such as the payer address of a trade fee.

| Shape | Personal data fields | How an endpoint gets it |
| --- | --- | --- |
| `thin` | The platform removes them from the payload before it signs the payload. | Every new endpoint starts thin. |
| `fat` | The platform keeps only the fields you acknowledged by name. | An update sets `defaultPayloadShape` to `fat` and lists the fields in `fatEventsAcknowledgment`. |

A removed field is absent from the payload. It is not `null`, so read personal data fields as optional. The platform shapes the payload when it records the event for the endpoint. A later change of shape affects new events only, and a Replay sends the stored payload.

The platform rejects a request that creates an endpoint as `fat`. A switch to `fat` needs `fatEventsAcknowledgment.fieldsAcknowledged` to list every personal data field of the events the subscriptions match, written as `<eventType>.<fieldPath>`. The list includes the fields of the retractions of those events. A list that misses a field is rejected with status 422 and the error `WEBHOOK_FAT_ACK_INCOMPLETE`, id `DALP-0517`. The same check runs when an update changes the subscriptions of a fat endpoint. The platform records who acknowledged the fields, and when.

The [Console endpoint editor](https://docs.settlemint.com/docs/console/organisation-settings/webhooks) prepares and records the required acknowledgement for the selected subscriptions. An endpoint read returns its stored `fatEventsAcknowledgment.fieldsAcknowledged`, not a computed list for a proposed subscription change. The event manifest and the public `DALP-0517` error body do not supply that complete consent list. Do not infer consent paths from a sample payload.

## Retractions [#retractions]

A retraction withdraws an earlier reported fact. When present, `supersedes` holds the `evt_id` of the event it replaces. The named event can be one your endpoint never received.

- After a chain reorganisation removes a block, the platform retracts only an event for which it recorded a successful delivery to your endpoint. Otherwise, it cancels the event and sends no retraction.
- For committed-state retractions such as `trading-venue.trade-settled.retracted`, the platform looks up the earlier event id created for your endpoint. This lookup does not require a successful delivery. The `supersedes` field is absent when no earlier endpoint event id exists, for example because the endpoint did not exist.
- When the platform recorded the earlier event but could not deliver it, the retraction names an event you never received. The platform sends the retraction once the earlier event can no longer be delivered.

Your handler can have applied a chain observation even when its HTTP acknowledgement was lost. Without a recorded successful delivery, the platform can cancel that observation without sending a retraction. Absence of a correction is therefore not confirmation of the canonical chain state. Keep uncertain effects provisional and reconcile them before confirming your business record.

Consumer handling follows these rules:

- Match by `supersedes`. If it is absent or unknown, use the payload identifiers, such as `tradeId`. Reverse only effects your system applied.
- Retain the retraction and audit-log any unknown `supersedes` reference. An unknown reference alone is not a processing failure. Do not invent a reversal for an action your system never applied.
- Keep the superseding state if the original arrives later. A Replay can deliver an older observation after a newer one.

The `.retracted` name suffix does not always mean a `retracted` lifecycle state. For example, `token.corporate-action.retracted` has state `final` and no envelope `supersedes` link. Match this event through its payload identifiers. Read the event's `type` as well as `lifecycle_state`.

The lifecycle state `recalled` is reserved. The platform sends no new event with this state, and a Replay resends one only when DALP 3.1 stored it. Acknowledge such an event and change nothing.

## Related [#related]

- [Event catalogue](https://docs.settlemint.com/docs/api-reference/webhooks/events): the events of every domain except token sales, trading venues and XvP settlements, when the platform sends each one and what to do with it.
- [Market and settlement events](https://docs.settlemint.com/docs/api-reference/webhooks/market-events): the events of token sales, trading venues and XvP settlements, when the platform sends each one and what to do with it.
- [Lifecycle states](https://docs.settlemint.com/docs/api-reference/webhooks/lifecycle): what each state means, with worked sequences.
- [Subscriptions](https://docs.settlemint.com/docs/api-reference/webhooks/subscriptions): the patterns that select events, and the events the default subscriptions skip.
- [Setup guide](https://docs.settlemint.com/docs/api-reference/guides/webhooks): endpoint registration, headers and signature verification.
- [Webhook Delivery](https://docs.settlemint.com/docs/concepts/events-out/webhook-delivery): the delivery model and endpoint recovery.


# Event catalogue

Source: https://docs.settlemint.com/docs/api-reference/webhooks/events
Webhook events by domain, with each event's lifecycle state, trigger and the action your endpoint takes. Market and settlement events have their own page.

For each webhook event, the tables give its lifecycle state, when the platform sends it and what your endpoint does with it. The events for token sales, trading venues and XvP settlements are on [Market and settlement events](https://docs.settlemint.com/docs/api-reference/webhooks/market-events). Payload fields, schemas and examples are not here. They live in the [machine-readable event definitions](https://docs.settlemint.com/.well-known/dalp-events.json) and in the `Webhook` types of `@settlemint/dalp-sdk`. [Subscriptions](https://docs.settlemint.com/docs/api-reference/webhooks/subscriptions), [lifecycle states](https://docs.settlemint.com/docs/api-reference/webhooks/lifecycle) and [consuming rules](https://docs.settlemint.com/docs/api-reference/webhooks/consuming) have their own pages.

In a State cell, `beta` is an event-contract maturity label. It is not a value of the envelope's `lifecycle_state` field.

## Before using payload fields [#before-using-payload-fields]

New endpoints use `thin` payloads, which omit personal data fields. Some actions in the tables need fields that thin payloads remove, such as `accountAddress`, `subjectAddress`, `confirmationId` or `statementId`. Configure `fat` payloads and acknowledge the required fields before the platform records those events if your receiver needs those fields. The [payload-shape rules](https://docs.settlemint.com/docs/api-reference/webhooks/consuming#payload-shape) describe this change. Replay sends the stored payload, so it cannot recover fields already removed from a thin event.

## Find the event for your question [#find-the-event-for-your-question]

| Question | Go to |
| --- | --- |
| Did a transfer settle, or did a chain reorganisation undo it? | [Token](#token) |
| Did a mint or burn happen, or was an asset paused? | [Asset](#asset) |
| Was a corporate action announced or completed, a fee charged, or a document published? | [Token](#token) |
| Was a holder's balance frozen or released, or did a provider return a verification verdict? | [Compliance](#compliance) |
| Was a role granted or revoked, or is a time-bound role about to end? | [Access control](#access-control) |
| Was an identity registered or recovered, or a claim issued or revoked? | [Identity](#identity) |
| Does an address need gas funding before a write can run? | [Funding](#funding) |
| Did a deposit or withdrawal change a custody participant's balance, or did a smart wallet change? | [Custody](#custody) |
| Does something need an operator, such as a reconciliation break or a parked bank credit? | [Operations](#operations) |
| Did a token sale open, take a purchase, pay a refund or close? | [Primary market](https://docs.settlemint.com/docs/api-reference/webhooks/market-events#primary-market) |
| Was an exchange-versus-payment settlement approved, executed, cancelled or expired? | [XvP settlement](https://docs.settlemint.com/docs/api-reference/webhooks/market-events#xvp-settlement) |
| Did an order change, a trade settle, or a bust reverse a trade? | [Trading venue](https://docs.settlemint.com/docs/api-reference/webhooks/market-events#trading-venue) |
| Is there a confirmation of a token movement for one wallet? | [Reporting](#reporting) |

## Access control [#access-control]

An access manager is the contract that records which accounts hold which roles. A role change has no `final` event: apply it when the `provisional` event arrives, and undo it when the matching `retracted` event arrives. A chain reorganisation replaces recent blocks. After a chain reorganisation removes the block of a role change, the platform sends a `retracted` event only when it recorded a successful delivery of the `provisional` event. If your acknowledgement was lost, the platform can cancel the event and send no retraction. Reconcile an uncertain role against the current canonical transaction receipt and its logs. [Retractions](https://docs.settlemint.com/docs/api-reference/webhooks/consuming#retractions) states the rule.

| Event | State | Sent when | What to do |
| --- | --- | --- | --- |
| `access-control.role-granted.provisional` | `provisional` | The platform reads a role grant on an access manager in a block that has not reached chain finality. | Add the role for `accountAddress` on `accessManagerAddress`. A role applies to that access manager only, not to the account on other managers. |
| `access-control.role-granted.retracted` | `retracted` | A chain reorganisation removes the block of a role grant after the platform recorded a successful delivery of `access-control.role-granted.provisional` to your endpoint. | Remove the role that the event named in `supersedes` added. |
| `access-control.role-revoked.provisional` | `provisional` | The platform reads a role revocation on an access manager in a block that has not reached chain finality. | Remove the role for `accountAddress` on `accessManagerAddress`. Roles on other access managers stay as they are. |
| `access-control.role-revoked.retracted` | `retracted` | A chain reorganisation removes the block of a role revocation after the platform recorded a successful delivery of `access-control.role-revoked.provisional` to your endpoint. | Restore the role that the event named in `supersedes` removed. |

A role granted with an expiry is time-bound: the platform revokes it at `expiresAt`. The role can be a token role, which names `tokenAddress` and `account`, or the organisation owner role, which names `userId`. Two events announce the end of a time-bound grant. The platform's expiry sweep sends them rather than a chain log, so they arrive as `final` without a provisional event. Match them by `grantId`. A token role revocation also produces `access-control.role-revoked.provisional` when the revoke lands on chain. An owner role goes out on the organisation's default chain, so an organisation with no default chain receives neither event for it.

| Event | State | Sent when | What to do |
| --- | --- | --- | --- |
| `access-control.role-grant.expiring` | `final beta` | A time-bound grant ends within 24 hours. The platform sends the event once for each expiry time. Re-issuing the grant with a later `expiresAt` sends it again, and a grant shorter than 24 hours sends it on the next sweep. A grant that is already past its end when the sweep first sees it sends only `access-control.role-grant.expired`. | Warn the holder or the person who granted it, and re-issue the grant before `expiresAt` if the role must stay. |
| `access-control.role-grant.expired` | `final beta` | The platform revoked the grant at its expiry. The platform sends the event once for each revoked grant, with `revokedAt` set. A grant that was extended, made permanent or revoked through the platform sends no event. | Remove the role from your records for the holder named in the event. |

## Asset [#asset]

Asset events report changes to a tokenised asset, read from chain logs. A block reaches chain finality once the chain head is the network's finality depth past it, as [Lifecycle states](https://docs.settlemint.com/docs/api-reference/webhooks/lifecycle#the-states-live-events-carry) defines. The platform sends a `final` asset event at that point and never retracts it.

| Event | State | Sent when | What to do |
| --- | --- | --- | --- |
| `asset.burn.final` | `final` | Token units are burned from a holder on chain. | `token.transfer.final` also reports the burn. Match `transferSourceId` to that event's `source_id` and book the burn once. |
| `asset.created.final` | `final` | An asset factory deploys a new asset token, and the platform indexes the token for the first time. | Register the asset by `assetAddress`. The event reports no supply: each mint arrives as an `asset.issuance.final` event. |
| `asset.issuance.final` | `final` | New token units are minted to a recipient on chain. | `token.transfer.final` also reports the mint, with the all-zero address as sender. Match `transferSourceId` to that event's `source_id` and book the issuance once. |
| `asset.issuance.provisional` | `provisional` | The platform indexes a block that holds a mint of token units, before the block reaches chain finality. | `asset.issuance.final` confirms the mint. If a chain reorganisation removes the block, `asset.issuance.retracted` replaces this event. |
| `asset.issuance.retracted` | `retracted` | A chain reorganisation removes the block of a mint after the platform recorded a successful delivery of `asset.issuance.provisional` to your endpoint. | Reverse the issuance you recorded for the event named in `supersedes`. |
| `asset.pause.final` | `final` | A token contract logs a pause. | The pause already took effect on chain. Stop submitting transfers for the asset until `asset.unpause.final` arrives. |
| `asset.unpause.final` | `final` | A token contract logs an unpause. | Allow transfers for the asset again. |

## Compliance [#compliance]

Freeze events report that a holder's balance of an asset was frozen or released, and the platform reads them from the logs of the asset contract. The verification verdict event reports a connected provider's decision and has no chain log behind it.

| Event | State | Sent when | What to do |
| --- | --- | --- | --- |
| `compliance.freeze.final` | `final` | The block that froze a holder's balance of an asset reaches chain finality. `scope` is `address` when the whole address is frozen and `amount` when a set number of token units is frozen. | Treat the freeze as confirmed: the platform does not retract a `final` event. Skip it if you already applied `compliance.freeze.provisional` with the same `transactionHash` and `logIndex`. |
| `compliance.freeze.provisional` | `provisional` | The platform reads a freeze on a holder's balance of an asset in a block that has not reached chain finality. | Apply the freeze. `compliance.freeze.final` confirms it after chain finality, and `compliance.freeze.retracted` replaces it if a chain reorganisation removes the block. |
| `compliance.freeze.retracted` | `retracted` | A chain reorganisation removes the block of a freeze after the platform recorded a successful delivery of `compliance.freeze.provisional` to your endpoint. | Reverse the freeze that the event named in `supersedes` applied. |
| `compliance.unfreeze.final` | `final` | The block that released a freeze on a holder's balance reaches chain finality. `scope` is `address` when a whole-address freeze is released and `amount` when a set number of token units is released. | Lift the freeze only on this event: the platform sends no `provisional` event for a release. |
| `compliance.verification-verdict.final` | `final beta` | The platform applies a connected provider's verdict on a subject, such as a know-your-customer (KYC) check, and completes any claim write the verdict needs. A verdict that the platform does not apply, such as an out-of-date one, sends nothing. | Read `status` for the verdict and `claimEffect` to see whether the platform issued a claim, revoked one or changed none. The claim change reaches you later as `identity.claim-issued.final` or `identity.claim-revoked.final`. |

## Bank rail [#bank-rail]

Subscribe to `bank-rail.credit.*` and `bank-rail.cash-out.*` to follow bank payments on your endpoint's System and chain. The default state subscriptions skip these names. Every event below has envelope state `final` and version 1. A bank recall is a credit status event, separate from the envelope's reserved recall lifecycle.

The Console's **Payments** tab lists every recall, including the partial ones that send no credit event, so read it when a recall changes a credit and no event arrives.

Amounts are decimal strings in the bank currency: `"12.50"` with `currency: "EUR"` means 12.50 EUR. `occurredAt` is the time the rail stored the milestone. A thin payload omits `participantId`. Approval identities, thresholds, park reasons, recovered amounts and write-down figures stay private in every payload shape.

| Event | State | Sent when | What to do |
| --- | --- | --- | --- |
| `bank-rail.credit.admitted` | `final beta` | The rail first records a credit, with status `processing`. A returned payout's re-credit also sends this event. | Track the credit by `creditId`. `provenance.cashOutId` identifies a returned payout. |
| `bank-rail.credit.minted` | `final beta` | The credit's mint settles, with status `minted`. | Mark the client credit complete. |
| `bank-rail.credit.parked` | `final beta` | The credit enters status `held`. A retry that parks again sends another event. | Keep the credit open for resolution. A checker step while held sends no event. |
| `bank-rail.credit.allocated` | `final beta` | A held credit's allocation to a client settles, with status `allocated`. | Mark the held credit allocated to the client. |
| `bank-rail.credit.returned-to-payer` | `final beta` | The bank refunds the payer and any held tokens are burnt, with status `returned-to-payer`. | Close the credit as refunded. |
| `bank-rail.credit.cancelled` | `final beta` | A full bank reversal cancels a credit before minting, with status `cancelled`. | Close the unminted credit. No recalled event accompanies this cancellation. |
| `bank-rail.credit.recalled` | `final beta` | Completed recalls cover the whole credit, with status `recalled`. | Record `amount` as the completing reversal's bank amount. Earlier partial recalls send no credit status event. Read the recall records for the full history. |
| `bank-rail.cash-out.requested` | `final beta` | The rail records a cash-out, with status `requested`, before approval or escrow completes. | Track the request by `cashOutId`. |
| `bank-rail.cash-out.instructed` | `final beta` | The bank receives the payout instruction, with status `instructed`. | Track the payout as instructed. Settlement and an unbooked payout send no duplicate. |
| `bank-rail.cash-out.paid` | `final beta` | The payout's tokens are burnt, with status `paid`, including recovery after a released payout settles late or a direct move into re-crediting for a pending return. | Mark the payout paid. A returned event can follow. |
| `bank-rail.cash-out.released` | `final beta` | The rail releases the holder's tokens without completing the payout, with status `released` and a release `reason`. | Record the release. A late bank settlement can lead to a paid event after recovery and burn. Partial recovery and starting the release send no event. |
| `bank-rail.cash-out.returned` | `final beta` | The bank returns the payout and the rail admits its re-credit, with status `returned`. | Match the re-credit's admitted event by `provenance.cashOutId`. Further returns create new credits without repeating this cash-out event. |

Mint approval, mint submission and resolution submission send no intermediate credit event. Cash-out events advance once through requested, instructed, paid and returned, or report released. A released request can later report paid after late settlement, full recovery and burn, then returned once its re-credit is admitted. Remove delivery duplicates by `evt_id`, and use `source_id` to identify the same occurrence across replays.

## Custody [#custody]

A System is an organisation's on-chain DALP deployment, and its account factory creates smart wallets, which are contract wallets. Custody events report those accounts, including changes to their signing rules, and the cash balances of custody participants. The account events reach only endpoints on the System that owns the account. The deposit, withdrawal and fee events give `amount` as a decimal string in base units, the smallest unit of the asset that `assetKey` names.

| Event | State | Sent when | What to do |
| --- | --- | --- | --- |
| `custody.account-created.final` | `final` | A System's account factory creates a smart wallet, and its block reaches chain finality. The platform sends nothing when it cannot match the factory to a System. | Record `accountAddress` and its first owner, `ownerAddress`. `identityAddress` is `null` when the account has no identity bound at creation. |
| `custody.gateway-deposit.settled` | `final beta` | A deposit into a custody gateway settles on chain and the client holds the custody receipts. When the receipts wait for the custodian to accept the forwarded coins, the platform sends the event once the custodian confirms. | Credit the client by `depositId`. `forwardedTo` is `null` when the coins stayed with the gateway as funding. A reindex sends the same event again with the same id, so dedupe by the event id. |
| `custody.gateway-withdrawal.settled` | `final beta` | A withdrawal request on a custody gateway is claimed on chain: the coins are paid to the payout address and the custody receipts are burned. The client or the keeper claims it, and both send the event. | Close the request by `requestId`. `fee` is `null` when no fee applied. A reindex sends the same event again with the same id, so dedupe by the event id. |
| `custody.signer-changed.final` | `final` | The signing rules of a System smart wallet change: a signer is added or removed, a signer's weight or the signing threshold changes, or the owner is replaced. The platform sends one event for each change, once its block reaches chain finality. | Branch on `change`: `weight` is set only for `signer-weight-changed`, `threshold` only for `threshold-changed` and `previousSignerHash` only for `owner-changed`. A signer appears only as `signerHash`, the keccak-256 hash of the signer bytes. |

## Funding [#funding]

A funding requirement records that an address needs more of the chain's native currency to pay gas, the fee for a transaction. The platform opens one when a write, a transaction it sends to the chain, pauses for lack of gas, and closes it when the address is funded or the wait ends. Match the events of one requirement by `requirementId`, and read `requiredWei` as an amount in wei, the smallest unit of the native currency. `observedWei`, when present, is the balance the platform read for the address: on `funding.requirement.raised` the balance when the requirement opened, on `funding.requirement.resolved` the balance that settled it.

| Event | State | Sent when | What to do |
| --- | --- | --- | --- |
| `funding.requirement.expired` | `final` | A funding requirement ends unfunded: its deadline passes before the address holds the required amount, or the last write waiting on it is cancelled. | Treat the writes that waited on the requirement as not executed. Fund the address and submit them again. |
| `funding.requirement.raised` | `final` | A write pauses because an address that must pay gas cannot cover the cost. The platform opens one requirement for that address on that chain and sends this event once, even when more writes pause on the same requirement. | Fund `subjectAddress` with at least `requiredWei` by `expiresAt`. Keep the requirement open in your records until `funding.requirement.resolved` or `funding.requirement.expired` arrives. |
| `funding.requirement.resolved` | `final` | The platform sees that the address holds at least the required amount and resumes the writes that waited on the requirement. | Close the requirement that you opened for the earlier `funding.requirement.raised` event. The waiting writes continue without further action. |

## Identity [#identity]

Each System, an organisation's on-chain DALP deployment, has an identity registry that links account addresses to identity contracts, which hold the claims about each account. These events report changes to registry entries and to claims on registered identities. The platform sends a `final` identity event after chain finality and never retracts it.

| Event | State | Sent when | What to do |
| --- | --- | --- | --- |
| `identity.claim-issued.final` | `final` | A claim is added to a registered identity, or changed. The platform sends one event for each System whose identity registry holds the identity. | `change` is `added` for a new claim and `changed` for an update to one. Use `claimId` to identify the claim. The event has no claim data. |
| `identity.claim-revoked.final` | `final` | The identity removes a claim, or its issuer revokes it. The platform sends one event for each System whose identity registry holds the identity. | `change` is `removed` when the identity removed the claim and `revoked` when the issuer revoked it. Use `claimId` to find the claim in your records. |
| `identity.registration.provisional` | `provisional` | The platform reads an account address being registered in a System's identity registry, as active or pending, in a block that has not reached chain finality. It sends nothing when a pending registration is accepted later. | Record the registration as unconfirmed, and read `status` to tell an active registration from a pending one. `identity.status.final` confirms it after chain finality. |
| `identity.registration.retracted` | `retracted` | A chain reorganisation removes the block of a registration after the platform recorded a successful delivery of `identity.registration.provisional` to your endpoint. | Remove the registration you recorded for the event named in `supersedes`. |
| `identity.status.final` | `final` | A registration in a System's identity registry is added, accepted after it was pending, moved to a replacement identity contract, removed, or recovered to a new wallet after the account's wallet is lost. | `change` is `registered`, `accepted`, `identity-replaced`, `removed` or `recovered`, and `status` is the resulting `pending`, `active` or `removed`. After a recovery, `accountAddress` is the new wallet and `previousAccountAddress` is the lost one. |

## Operations [#operations]

An operations case records a problem that the platform cannot resolve automatically, for example a reconciliation break between a bank statement and token supply, or a bank credit that the bank rail parked. An operator acknowledges the case and resolves it, or the platform resolves it when the problem clears. A case that is not resolved by `expiresAt` is expired, and no event reports that. Two kinds belong to the custodian watch: `custodian-privileged-action`, for a privileged action by a wallet outside the custodian's organisation on a token it custodies, and `custodian-upgrade-notice`, for an upgrade scheduled for a factory whose tokens it custodies. [Custodian watch](https://docs.settlemint.com/docs/concepts/custody-and-signing/custodian-watch) describes both. Match the events of one case by `caseId`. Each event belongs to the chain in `chainId`. If `chainId` is `null`, the case names no chain and the event belongs to the organisation's default chain. A thin delivery omits `participantId`, `accountRef`, `detail` and `resolvedBy`.

| Event | State | Sent when | What to do |
| --- | --- | --- | --- |
| `operations.case.acknowledged` | `final beta` | An operator acknowledges an open case. The platform sends the event once for each case. | Mark the case as being worked on. Read `acknowledgedAt` for the time of the acknowledgement. |
| `operations.case.opened` | `final beta` | The platform opens a case. The platform sends the event once for each case. A new problem of the same kind for the same subject adopts the existing case, open or resolved, and sends no event. | Route the case to your operators by `kind` and `severity`. Keep the case open in your records until `operations.case.resolved` arrives or `expiresAt` passes. |
| `operations.case.resolved` | `final beta` | An operator resolves the case, or the platform resolves it when the problem clears. The platform sends the event once for each case. | Close the case in your records. `resolvedBy` identifies the operator, or the platform service that resolved the case. |

## Reporting [#reporting]

Reporting events tell you what the platform recorded in its reporting store. `reporting.confirmation-created.final` confirms a token movement for one wallet, and the platform sends it only to endpoints of an organisation with a member who holds the wallet or signs for it, once the block reaches chain finality. The other reporting events go to every endpoint of the organisation.

| Event | State | Sent when | What to do |
| --- | --- | --- | --- |
| `reporting.confirmation-created.final` | `final` | A mint, burn or transfer moves tokens in a wallet. The platform confirms each wallet affected: a transfer between two wallets confirms both, and a transfer to the same wallet confirms it once. | Fetch the confirmation by `confirmationId` from the reporting confirmations endpoint of the Platform API, which returns not found for a wallet that is not the caller's. A `thin` payload omits `confirmationId`, so this needs a `fat` payload. |
| `reporting.filing.deadline-warning` | `final beta` | A regulatory filing enters its configured deadline warning window without a submission. The platform emits one event for the filing period. | Read the filing period through the reporting endpoint of the Platform API and begin the required submission work. |
| `reporting.filing.sla-breached` | `final beta` | A regulatory filing misses its acknowledgement SLA or calendar deadline. The platform emits one event for the filing period and event kind. | Read the filing period through the reporting endpoint of the Platform API and handle the overdue filing. |
| `reporting.mirror-movement.final` | `final beta` | A settled movement on a mirror token: a venue fill, the bust of a settled trade, a mint, a burn or a corporate-action movement. Sent once per movement when the day's settlement feed is first recorded, after the day closes in the token's cut-off timezone. The parties are OnchainID addresses, never personal data. | Book the movement at the custodian or registrar. `movementId` is stable, so a repeated delivery is the same movement. A `thin` payload omits `fromIdentity` and `toIdentity`, so this needs a `fat` payload. |
| `reporting.statement-ready.final` | `final beta` | The platform records a client statement for one wallet and period, as a scheduled statement, a contract note or an on-demand statement. Sent once, the first time the statement is recorded. A contract note the platform amends in place is not re-announced. | Read the statement through the reporting statements endpoint of the Platform API, then download each format the event's `formats` lists with the statement's download endpoint. A `thin` payload omits `statementId`, so this needs a `fat` payload. |

## Token [#token]

The platform reads transfer and fee events from chain logs. It sends a coupon claim or maturity redemption event for each claim or redemption log once the log's block reaches chain finality, and it records corporate action and document events itself, with no chain log behind them. A corporate action is a scheduled change to a token and its holders' positions, such as a dividend, a coupon or a stock split. A mint or burn also produces the transfer events, with the all-zero address as sender or recipient.

The `token.transfer.provisional`, `token.transfer.retracted`, `asset.issuance.*` and `asset.burn.final` events, and version 2 of `token.transfer.final`, carry `occurredAt`, the time of the block that holds the movement, so a ledger can post the movement on the right date from the event alone. A token that keeps a register books each movement as a numbered line with a register reference, the identifier the registrar files it under. When a movement is booked as one of those lines, the event also carries `registerLine` with `lineId`, `registerReference` and, for a line that corrects an earlier one, `correctsLineId`. A movement that the platform cannot pair with exactly one booked line carries no `registerLine`. A mint or burn of a [mirror token](https://docs.settlemint.com/docs/concepts/records-and-evidence/mirror-tokens) carries `externalReference`, the custodian or registrar transaction id sent with the mint or burn. Events stored before these fields existed have none of them.

| Event | State | Sent when | What to do |
| --- | --- | --- | --- |
| `token.corporate-action.announced` | `final beta` | A corporate action is cleared for execution: an approver signs it off, or the action needs no approval. | Read the action's record through the corporate actions endpoint of the Platform API. The event names the action, the token and the action type only. |
| `token.corporate-action.completed` | `final beta` | A corporate action finishes executing and reaches the completed state. | Read the final record through the corporate actions endpoint of the Platform API. A completed action cannot be aborted, so no retraction follows. |
| `token.corporate-action.paid` | `final beta` | A cash dividend, a distribution or a coordinated distribution that pays in cash reaches the completed state. The platform sends it with `token.corporate-action.completed`. | Use it to separate cash payouts from other completed actions. `totalAmount` is what holders are entitled to, in base units of `denominationAddress`. A claim-based payout moves that cash later, as holders claim. Other action types, and payouts made in kind rather than in cash, send only `token.corporate-action.completed`. |
| `token.corporate-action.retracted` | `final beta` | A corporate action that was approved, or needs no approval, is aborted before it completes. An action that was denied, expired or still awaiting approval sends nothing. | Match on `corporateActionId` to cancel what you expected from `token.corporate-action.announced`. This event has no `supersedes` and can arrive without an earlier announcement. |
| `token.coupon-claim.final` | `final beta` | A bond holder claims coupon cash from a fixed treasury yield feature or a legacy fixed yield schedule, and the claim's block reaches chain finality. | Book the cash paid to the holder. `amount` is in base units of `denominationAddress` and can be less than the sum of the periods from `fromPeriod` to `toPeriod`. `claimId` is `<blockNumber>:<logIndex>`. Converting yield into tokens sends no event, and claims that reached finality before the platform started sending this event have none. A `thin` payload omits `holder`. |
| `token.document.published` | `final beta` | A document upload is confirmed with `holders` visibility, and each replacement version sends its own event. Other visibility levels send nothing. | Fetch the file through the documents endpoints of the Platform API, which apply the caller's visibility. The event names the document, its type, its title and its publish time only. |
| `token.fee-period-close.final` | `final beta` | A token's fee accounting feature closes a fee period for a recipient. A close with a zero amount sends nothing. | Use it to end an accrual period: `token.fee.final` events with `basis` `accrued` since the previous close belong to this period. |
| `token.fee.final` | `final beta` | A token charges a fee: a fee feature collects or accrues it, or a fund collects its management fee. A fee of zero sends nothing. | A management fee or an assets-under-management fee mints the fee to the recipient, so `asset.issuance.final` and `token.transfer.final` also report it. Post the fee once, and read `basis` for `collected` or `accrued`. |
| `token.maturity-redemption.final` | `final beta` | A holder redeems matured bond tokens for cash from a maturity redemption feature or a legacy bond, and the redemption's block reaches chain finality. | Book the cash paid to the holder. `amount` is in base units of `denominationAddress` and `tokenAmount` is the redeemed tokens in the token's base units. A custodian that redeems several holders in one transaction sends one event for each holder. `redemptionId` is `<blockNumber>:<logIndex>`. Redemptions that reached finality before the platform started sending this event have none. A `thin` payload omits `holder`. |
| `token.transfer.final` | `final` | The platform indexes a transfer, mint or burn of a token. | Treat the movement as confirmed: a chain reorganisation never retracts version 2, and a chain reorganisation that removes the block before finality cancels the event unsent. A transfer that moves one leg of a venue trade also carries `venueTrade`, with `tradeId`, `marketId`, `venueAddress` and `leg`, which is `base`, `quote` or `fee`. The field is absent on every other transfer, and `tradeId` is `null` for a fill recorded before venues emitted trade ids. The platform sends this event in version 2 only. Version 1 went out when the block was included. |
| `token.transfer.provisional` | `provisional` | The platform indexes a block that includes a transfer, mint or burn of a token, before the block reaches chain finality. | `token.transfer.final` confirms the movement. If a chain reorganisation removes the block, version 2 of `token.transfer.retracted` replaces this event. |
| `token.transfer.retracted` | `retracted` | A chain reorganisation removes the block of a transfer, mint or burn after the platform recorded a successful delivery of the event it supersedes to your endpoint. | Reverse the record for the event named in `supersedes`, and branch on the envelope `version`. Version 2 replaces a `token.transfer.provisional` event, and version 1 replaces a version 1 `token.transfer.final` event. The platform sends `token.transfer.final` in version 2 only. |

## Transaction request [#transaction-request]

A transaction request is one on-chain write that the platform accepts and tracks. These events report the request's progress, not the finality of a token movement. Each event reaches the organisation and chain of the request. Match events by `transactionId`, and use the asset and token events to record movements.

| Event | State | Sent when | What to do |
| --- | --- | --- | --- |
| `transaction.request.broadcast` | `pending` | The request enters a broadcast state with a transaction hash. | Store the hash and mark the request as awaiting an outcome. Do not book a token movement from this event. |
| `transaction.request.cancelled` | `final` | The request reaches `CANCELLED`. | Mark the request as cancelled. Read the transaction request record if you need the reason. |
| `transaction.request.confirmed` | `final` | The request reaches `COMPLETED`. | Mark the request as complete. Match the token or asset events before recording the resulting movement. |
| `transaction.request.dead-lettered` | `final` | The request reaches `DEAD_LETTER`. | Read the transaction request and its `mayStillLand`. While it is `true`, do not resend the call: hold the request open and wait for `transaction.request.confirmed`, `transaction.request.failed` or `transaction.request.cancelled` with the same `transactionId`. When it is `false`, the call did not land and the request does not settle by itself: ask an operator to close it, or send the call again with a new idempotency key. |
| `transaction.request.failed` | `final` | The request reaches `FAILED`. | Mark the request as failed and read the transaction request record for details. An operator can retry it, so another outcome can follow. |

The `final` state of `transaction.request.confirmed` and the other outcome events means the request has its outcome. It does not mean the block is final on the chain. `transaction.request.confirmed` goes out once the platform's indexer has processed the block that holds the transaction, for direct wallet writes and for account abstraction writes alike. A chain reorganisation after that point can still remove the transaction, so wait for the token or asset events before you treat a movement as final. A `transaction.request.dead-lettered` event is the one exception while its transaction request shows `mayStillLand: true`: the event is `final` for the queue, but a later outcome event with the same `transactionId` can still follow.

The platform records the event together with the state change. Setting a request to the state it already holds sends nothing. Leaving the broadcast states and entering them again with a hash sends another broadcast event. Replacing a hash while confirming sends nothing. A request that fails, is retried by an operator, and fails again sends two failed events with different `source_id` values.

One request can send `transaction.request.failed` and then `transaction.request.cancelled`, when it is cancelled after it failed. A dead-lettered request can send another outcome later, as the transaction request table describes. Treat the latest outcome as the current one, and read the record before you retry or refund on a `failed` event.

A thin delivery omits `fromAddress`, `errorMessage`, and `revertReason`. The platform limits the two error fields to 1,024 characters. Read the full record with `GET /api/v2/transaction-requests/{transactionId}`.

The default subscriptions skip all five events. Use `transaction.request.*`, `transaction.*`, exact names, or `*`, as the [subscriptions reference](https://docs.settlemint.com/docs/api-reference/webhooks/subscriptions#events-the-default-subscriptions-do-not-deliver) describes.

## Test event [#test-event]

`webhook.test.final` is the default test event. The platform sends a test event only when someone requests one for an endpoint, from the Console or with `POST /api/v2/webhooks/{webhookId}/test-events`. It reaches that endpoint whatever its subscriptions, with `lifecycle_state` `final`, `is_test` set to `true` and the payload `{ "test": true }`. Use it to check your signature verification, and never act on it as a business event. The [setup guide](https://docs.settlemint.com/docs/api-reference/guides/webhooks#send-a-test-event) states its limits.

## Reserved names [#reserved-names]

These event names are registered, but no action in the platform sends them.

| Event | Status |
| --- | --- |
| `compliance.freeze.recalled` | Reserved. No action sends this event. An exact subscription is accepted. |
| `settlement.transfer.retracted` | Reserved. No action sends this event. An exact subscription is rejected. |
| `token.transfer.pending` | Reserved. No action sends this event. An exact subscription is rejected. |

## Related [#related]

- [Market and settlement events](https://docs.settlemint.com/docs/api-reference/webhooks/market-events): the events of token sales, trading venues and XvP settlements.
- [Subscriptions](https://docs.settlemint.com/docs/api-reference/webhooks/subscriptions): the patterns that select events, and the events the default subscriptions skip.
- [Lifecycle states](https://docs.settlemint.com/docs/api-reference/webhooks/lifecycle): what each state means, with worked sequences.
- [Consuming webhooks](https://docs.settlemint.com/docs/api-reference/webhooks/consuming): identifiers, deduplication, ordering, retries and retractions.


# Overview

Source: https://docs.settlemint.com/docs/api-reference/webhooks
How a DALP webhook reaches your endpoint, what your receiver checks on each request, and which page documents each part of the contract.

The platform tells your systems what happened through webhooks, which are HTTP POST requests that it sends to an endpoint you register, each one signed with that endpoint's secret. Each request carries one event, such as `token.transfer.final`, which confirms a token transfer. The platform selects a new event for your endpoint when one of the endpoint's subscription patterns matches the event name. When a chain reorganisation replaces recent blocks, an automatic correction can also follow a provisional event your endpoint already received.

Use webhooks when a system must react to changes, such as an accounting ledger or a monitoring pipeline. Use Platform API reads when you need current state or must reconcile an uncertain notification. Registering an endpoint and receiving notifications change no asset ownership and start no transfers.

Your receiver must expect the same event more than once. The platform retries a failed attempt, and a reply that takes longer than the attempt timeout counts as a failure, even when your system already processed the request. Each repeat carries the same `webhook-id`. An event also reports a lifecycle state, such as `provisional` or `final`, which says how far the reported fact has progressed, and a later event can retract an earlier one. Your receiver verifies each signature, processes each event id once and acts on the lifecycle state. A retraction withdraws an earlier reported fact: reverse only effects your system applied, using the earlier event id or the payload identifiers. After 30 failed attempts in a row the platform switches the endpoint off, and while it is off the platform records no events for it. Repair the receiver before recovering deliveries. Resend adds one more attempt to a delivery, and Replay sends a stored event again as a new event. Both recover only events the platform recorded, so read what happened while the endpoint was off from the Platform API. The [failure runbook](https://docs.settlemint.com/docs/deployment/runbooks/webhook-deliveries-failing) covers that recovery. Attempt outcomes remain in the endpoint's delivery history.

[Figure] Every attempt and every Resend of an event carry one id, and your endpoint processes that id once. One event on its way to one endpoint, in three bands. Subscriptions: the event name, such as token.transfer.final from the event catalogue, is compared with your endpoint's subscription patterns. The pattern *.final matches it, so the platform queues the event for your endpoint with its own evt_id. When no pattern matches, the platform queues no initial event. Delivery: attempt 1 ends in a retryable failure, attempt 2 follows after a backoff delay and gets a 2xx reply, and a Resend adds another attempt. All three carry the same webhook-id, equal to evt_id. A Replay is a new event, with a new evt_id and is_replay set to true. Your endpoint: verify the signature on every request with your endpoint's signing secret. Deduplicate on evt_id, the focal step: process each id once and reply 2xx to a repeat. Then act on lifecycle_state, the fact's state in the event envelope. Labels: Subscriptions; token.transfer.final; a name from the catalogue; Your patterns; *.final matches the name; Queued for you; with its own evt_id; No match: no new event; Delivery; Attempt 1; retryable failure; backoff; Attempt 2; 2xx: delivered; Resend; another attempt; Replay; a new event, new evt_id; is_replay: true; Same webhook-id, equal to evt_id; Your endpoint; Verify the signature; on every request, with your endpoint's signing secret; Deduplicate on evt_id; process each id once, reply 2xx to a repeat; Act on lifecycle_state; Apply its reported state.

Every attempt and every Resend of an event carry the same `webhook-id`, and a Replay sends a new `evt_id`.

One event reaches one endpoint in three stages:

1. **Subscriptions.** For an initial event, the platform compares its name with your endpoint's subscription patterns. A match queues the event for your endpoint with its own event id, `evt_id`. A chain reorganisation can later send a correction for a delivered provisional event without matching the correction against your subscriptions. When no pattern matches, the platform queues no initial event. [Subscriptions](https://docs.settlemint.com/docs/api-reference/webhooks/subscriptions) lists the patterns and the events that the default subscriptions skip.
2. **Delivery.** Each attempt is a signed POST request, and every attempt for the event carries the same `webhook-id` header, equal to `evt_id`. A retryable failure gets another attempt after a backoff delay. A Resend, which you request for one delivery, adds another attempt with the same id. A Replay, which you request for one event or a block range, sends each event again as a new event with a new `evt_id` and sets `is_replay` to `true`. [Consuming webhooks](https://docs.settlemint.com/docs/api-reference/webhooks/consuming) states which failures the platform retries and how Resend and Replay work.
3. **Your endpoint.** Verify the signature on every request with your endpoint's signing secret. Then deduplicate on `evt_id`: process each id once, and reply with a 2xx status to a repeat so the platform records it as delivered. Then act on the fact's `lifecycle_state`, not on the event-name suffix. The [setup guide](https://docs.settlemint.com/docs/api-reference/guides/webhooks) shows the signature check, and [Lifecycle states](https://docs.settlemint.com/docs/api-reference/webhooks/lifecycle) says what each state means.

## Where to find what [#where-to-find-what]


  - [Setup guide](https://docs.settlemint.com/docs/api-reference/guides/webhooks): Register an endpoint, verify signatures, send a test event and rotate the secret.
  - [Event catalogue](https://docs.settlemint.com/docs/api-reference/webhooks/events): Events of every domain except markets and settlement, with state, timing and action.
  - [Market and settlement events](https://docs.settlemint.com/docs/api-reference/webhooks/market-events): Events of token sales, trading venues and XvP settlements, with state and timing.
  - [Subscriptions](https://docs.settlemint.com/docs/api-reference/webhooks/subscriptions): The pattern grammar, the default subscriptions and the live events they skip.
  - [Lifecycle states](https://docs.settlemint.com/docs/api-reference/webhooks/lifecycle): What each event state means and the sequences an endpoint receives.
  - [Consuming webhooks](https://docs.settlemint.com/docs/api-reference/webhooks/consuming): Deduplication, ordering, retries, Resend and Replay, and retraction handling.


## Related [#related]

- [Webhook Delivery](https://docs.settlemint.com/docs/concepts/events-out/webhook-delivery): the concept page on signed delivery, retries and the circuit breaker that pauses a failing endpoint.
- [Platform Event](https://docs.settlemint.com/docs/concepts/events-out/platform-event): the concept page on how the platform names and records an event, with a figure of the lifecycle states.
- [Webhook deliveries failing](https://docs.settlemint.com/docs/deployment/runbooks/webhook-deliveries-failing): the runbook for an endpoint that stopped receiving events.
- [Webhook endpoints in the Console](https://docs.settlemint.com/docs/console/organisation-settings/webhooks): create an endpoint, read its deliveries, and resend or replay events without the API.
- [Machine-readable event definitions](https://docs.settlemint.com/.well-known/dalp-events.json): an AsyncAPI document, a standard format for describing event interfaces, with the envelope and payload schema of each event.


# Lifecycle states

Source: https://docs.settlemint.com/docs/api-reference/webhooks/lifecycle
The lifecycle states that DALP webhook events send, the sequences an endpoint receives, and the states the platform reserves.

Every DALP webhook event reports a fact and the lifecycle state of that fact: how far the fact has progressed and whether a later event can replace it. The [event catalogue](https://docs.settlemint.com/docs/api-reference/webhooks/events) lists events and triggers. The [consuming page](https://docs.settlemint.com/docs/api-reference/webhooks/consuming) covers deduplication, ordering and retries.

## The states live events carry [#the-states-live-events-carry]

An event the platform sends has one of four lifecycle states: `pending`, `provisional`, `final` or `retracted`. The state is the envelope field `lifecycle_state`. Read the field, because the name does not always end in the state. `funding.requirement.raised` has state `final`, and `trading-venue.price-alert.triggered` has state `provisional`. Two retractions, `token.corporate-action.retracted` and `trading-venue.trade.retracted`, also have state `final`.

Subscription patterns such as `*.final` match the name suffix, not the field. The [subscriptions page](https://docs.settlemint.com/docs/api-reference/webhooks/subscriptions) covers them.

A chain reorganisation replaces recent blocks with a competing set of blocks. The finality depth is the number of blocks that must follow a block before the platform treats it as final. On a network whose node reports finality through the `finalized` block tag, the platform uses a recommended depth for a known chain, such as 65 blocks on Ethereum mainnet, and 64 blocks for any other. On a network without one, the depth is the number of confirmations set in the network's configuration, which can be 0.

| State | What it means | What your system does |
| --- | --- | --- |
| `pending` | A transaction request entered a broadcast state with a transaction hash. The request has no outcome. | Track the request by `transactionId` and wait for its outcome. This event does not confirm a token movement. |
| `provisional` | The platform reports a fact that can still change. A chain reorganisation can still remove the block that holds a fact read from a chain log. A trading-venue order status or price alert reports activity without confirming trade settlement. | Record the fact as unconfirmed and keep the record reversible. A later event follows only for some facts, as the worked sequences show. |
| `final` | For a chain log, the source block has reached chain finality. For a change recorded inside the platform, such as opening a funding requirement, the platform has committed the change. | Apply the reported fact once. A later `trading-venue.trade-settled.retracted` can reverse `trading-venue.trade-settled.final`, so `final` does not exclude a later business reversal. |
| `retracted` | An earlier reported fact no longer stands. A chain reorganisation or a trade bust can trigger this state. | Match `supersedes` when present. If it is absent or unknown, match by the payload identifiers and reverse only effects you applied. |

Read `type` for the event name and `version` for its version. Retractions caused by a chain reorganisation include `supersedes`, the earlier event's `evt_id`. For platform-recorded events with state `retracted`, this field is optional. It names the earlier event when the platform queued it for your endpoint, even if delivery never succeeded.

`token.corporate-action.retracted` has state `final` and no envelope `supersedes`. Match it by `corporateActionId`. `trading-venue.trade.retracted` also has state `final`. It reports a bust, the reversal of a trade whose delivery was still pending. That delivery has no `trading-venue.trade.final` event. Match it by `venueTradeId`.

A transaction request outcome has state `final`, including a failure or cancellation. This state reports the request's outcome, not the chain finality of a token movement. The [transaction request events](https://docs.settlemint.com/docs/api-reference/webhooks/events#transaction-request) describe those outcomes.

The state `recalled` is reserved: the platform sends no new event with it. A Replay can resend a `recalled` event that DALP 3.1 stored.

`bank-rail.credit.recalled` carries `lifecycle_state: "final"`. It reports that completed bank recalls cover the whole credit. Its name describes the bank outcome, and the envelope state describes the committed observation. See the [bank rail catalogue](https://docs.settlemint.com/docs/api-reference/webhooks/events#bank-rail).

## Worked sequences [#worked-sequences]

Each table lists the events for one case, with what your system does at each step. The tables assume your endpoint subscribes to the named events and deduplicates each one by `evt_id`.

### A transfer that finalises [#a-transfer-that-finalises]

When the platform indexes a token transfer, it creates a provisional event and a final event. It queues the provisional event for delivery at once and holds the final event until the finality depth passes the block of the transfer.

| Step | Event | State | What your system does |
| --- | --- | --- | --- |
| 1 | `token.transfer.provisional` | `provisional` | Record the transfer as unconfirmed. A chain reorganisation can still remove its block. |
| 2 | `token.transfer.final`, version 2 | `final` | Confirm the record. Match it to the provisional event by `chainId`, `transactionHash` and `logIndex` in the payload. |

### A transfer that a chain reorganisation removes [#a-transfer-that-a-chain-reorganisation-removes]

A chain reorganisation retracts a provisional event only when the platform recorded a successful delivery of that event to your endpoint. The platform cancels the held final event for the removed block, so no `final` event follows.

| Step | Event | State | What your system does |
| --- | --- | --- | --- |
| 1 | `token.transfer.provisional` | `provisional` | Record the transfer as unconfirmed. |
| 2 | `token.transfer.retracted`, version 2 | `retracted` | Find the record whose `evt_id` is in `supersedes` and reverse it. |

This rule applies to chain observations generally: without a recorded successful delivery, the platform cancels the provisional event and sends no retraction. Your handler can have applied an event even when its HTTP acknowledgement was lost. Keep those effects provisional: absence of a retraction does not confirm that the observation stayed on the canonical chain. Reconcile an uncertain observation against the current canonical transaction receipt and its logs before confirming your record. Reverse only provisional effects whose corresponding observation is no longer present.

`token.transfer.retracted` has two versions. Version 2 replaces a provisional transfer. Version 1 replaces a version 1 `token.transfer.final` event. The platform sends `token.transfer.final` in version 2 only.

### An issuance [#an-issuance]

An issuance mints new token units for a recipient. The platform also sends the token transfer events for the same movement. The issuance payload gives the `source_id` of the matching `token.transfer.final` event in `transferSourceId`, so you can book the movement once. Step 2a and step 2b are alternatives.

| Step | Event | State | What your system does |
| --- | --- | --- | --- |
| 1 | `asset.issuance.provisional` | `provisional` | Record the issuance as unconfirmed. |
| 2a | `asset.issuance.final` | `final` | Confirm the issuance. The platform sends this event after the finality depth passes the block. |
| 2b | `asset.issuance.retracted` | `retracted` | Reverse the issuance whose `evt_id` is in `supersedes`. No `asset.issuance.final` event follows for the removed block. |

### A role grant [#a-role-grant]

The platform sends a role grant only as a provisional event. It sends no `final` event, and no later event confirms the grant.

| Step | Event | State | What your system does |
| --- | --- | --- | --- |
| 1 | `access-control.role-granted.provisional`, version 2 | `provisional` | Record the grant as unconfirmed. Unless a retraction follows, this event is the only notice of the grant. |
| 2, only after a chain reorganisation | `access-control.role-granted.retracted`, version 2 | `retracted` | Reverse the grant whose `evt_id` is in `supersedes`. |

Role revocations follow the same pattern: `access-control.role-revoked.provisional` pairs with `access-control.role-revoked.retracted`.

The platform sends the retraction only when it recorded a successful delivery of the provisional event. If your acknowledgement was lost, a chain reorganisation can cancel the event and send no retraction. Reconcile an uncertain role against the current canonical transaction receipt and its logs. [Retractions](https://docs.settlemint.com/docs/api-reference/webhooks/consuming#retractions) states the rule.

Identity registration has a separate final confirmation. `identity.registration.provisional` reports the registration before chain finality. `identity.status.final` follows with `change` set to `registered` after finality, unless a chain reorganisation removes the observation first. If a chain reorganisation removes the registration after a recorded successful provisional delivery, `identity.registration.retracted` names that provisional event in `supersedes`. Finality confirms the reported registration status. It does not change a pending registration into an active registration.

### A funding requirement [#a-funding-requirement]

A funding requirement records funding needed by a paused write. Its events have state `final` although their names end in `raised`, `resolved` and `expired`. Each name reports one status change, and the platform sends it as `final` when it records that change. Step 2a and step 2b are alternatives.

| Step | Event | State | What your system does |
| --- | --- | --- | --- |
| 1 | `funding.requirement.raised` | `final` | Track the active requirement by `requirementId` and arrange funding. The platform sends one `raised` event for each requirement. |
| 2a | `funding.requirement.resolved` | `final` | Close the funding task for this requirement. The observed balance reached the required amount. |
| 2b | `funding.requirement.expired` | `final` | Close the funding task for this requirement. Expiration can follow the deadline or cancellation of the last waiting write. |

A requirement ends in `resolved` or `expired`, never both, because the platform changes only a requirement that is still active. No retraction event exists for a funding requirement.

### A settled trade that a bust reverses [#a-settled-trade-that-a-bust-reverses]

A bust is an approved reversal of a settled trade. The platform sends step 1 when the settlement transaction confirms, without waiting for chain finality. Step 2 follows only after a bust, once the reversal is complete on chain.

| Step | Event | State | What your system does |
| --- | --- | --- | --- |
| 1 | `trading-venue.trade-settled.final`, and one `trading-venue.trade-fee.final` for each charged side | `final` | Book the trade as settled and book each fee. |
| 2 | `trading-venue.trade-settled.retracted`, and one `trading-venue.trade-fee.retracted` for each fee charged | `retracted` | Reverse the trade and each fee. `supersedes` names the earlier event when the platform queued it for your endpoint. Otherwise match the trade by `tradeId` and the fee by `feeId`. |

## Delivery failures and event state [#delivery-failures-and-event-state]

A delivery attempt is an HTTP request for an event. A failed attempt does not make the event `retracted`, and retrying it keeps the same `evt_id` and lifecycle state. Verify the signature before processing the event, as the [setup guide](https://docs.settlemint.com/docs/api-reference/guides/webhooks#verify-the-signature) describes.

Return a 2xx status after processing, or for an event id you already processed. Which responses the platform retries, the attempt timeout and the three-day retry window are delivery limits, not a change to the fact's lifecycle state. The [consuming reference](https://docs.settlemint.com/docs/api-reference/webhooks/consuming#retries) defines them, with the receipt rules.

## Reserved states [#reserved-states]

The platform reserves one value of `lifecycle_state`. No new event has that value. Your endpoint receives it only when a Replay resends a `recalled` event that DALP 3.1 stored. Acknowledge such an event and change nothing.

- `recalled`: reserved for an event that withdraws an earlier delivery on purpose, as opposed to a chain reorganisation.

The [event catalogue](https://docs.settlemint.com/docs/api-reference/webhooks/events#reserved-names) lists the reserved event names. `token.transfer.pending` is still a reserved name even though the live `transaction.request.broadcast` event uses state `pending`.

## Related [#related]

- [Event catalogue](https://docs.settlemint.com/docs/api-reference/webhooks/events): the events of every domain except token sales, trading venues and XvP settlements, when the platform sends each one and what to do with it.
- [Market and settlement events](https://docs.settlemint.com/docs/api-reference/webhooks/market-events): the events of token sales, trading venues and XvP settlements, when the platform sends each one and what to do with it.
- [Subscriptions](https://docs.settlemint.com/docs/api-reference/webhooks/subscriptions): the patterns that select events, and the events the default subscriptions skip.
- [Consuming webhooks](https://docs.settlemint.com/docs/api-reference/webhooks/consuming): identifiers, deduplication, ordering, retries and retraction handling.
- [Platform event](https://docs.settlemint.com/docs/concepts/events-out/platform-event): the concept page, with the figure of the lifecycle states.


# Market and settlement events

Source: https://docs.settlemint.com/docs/api-reference/webhooks/market-events
Webhook events for token sales, trading venues and XvP settlements, with each event's lifecycle state, trigger and the action your endpoint takes.

Three products send the events on this page: token sales, which sell a token to investors, trading venues, which match orders and settle trades on chain, and XvP settlements, which exchange assets between parties. For each event, the tables give its lifecycle state, when the platform sends it and what your endpoint does with it. The [event catalogue](https://docs.settlemint.com/docs/api-reference/webhooks/events) lists the events of every other domain and the reserved names. Payload fields, schemas and examples live in the [machine-readable event definitions](https://docs.settlemint.com/.well-known/dalp-events.json) and in the `Webhook` types of `@settlemint/dalp-sdk`.

In a State cell, `beta` is an event-contract maturity label. It is not a value of the envelope's `lifecycle_state` field. New endpoints use `thin` payloads, which omit personal data fields such as `accountAddress`. If your receiver needs an address field, configure `fat` payloads and acknowledge the required fields before the platform records those events: a replay resends the stored payload and cannot restore a field a thin event left out. [Before using payload fields](https://docs.settlemint.com/docs/api-reference/webhooks/events#before-using-payload-fields) describes the change.

## Primary market [#primary-market]

Primary market events report the life of a token sale, and the platform sends each one after the block that holds its chain log reaches chain finality. Every event names the sale in `saleAddress`. An amount is an integer in base units, the smallest unit of its token or currency, so apply the asset's decimals before you show it.

| Event | State | Sent when | What to do |
| --- | --- | --- | --- |
| `primary-market.delivery.final` | `final` | An investor withdraws purchased tokens from a token sale. The sale holds tokens back for a soft cap, the minimum it must sell, or for a vesting schedule, which releases tokens over time. | Mark the investor's tokens as delivered by the amount in the event. If the investor lost a wallet and recovered the identity, the tokens go to the replacement wallet, so match on the investor in the event. |
| `primary-market.proceeds-withdrawn.final` | `final` | A funds manager withdraws a token sale's proceeds in one payment currency to a recipient. A withdrawal of zero sends no event. | Record the amount against the currency and the recipient in the event. A sale that accepts several currencies sends one event for each currency withdrawn. |
| `primary-market.refund.final` | `final` | A token sale pays an investor back in one payment currency. This happens when the sale fails its soft cap and the investor claims a refund, or when the sale pays back a purchase whose tokens cannot be delivered. | Read `reason`: `sale-failed` refunds a contribution to a failed sale, and `undeliverable-purchase` refunds the payment for tokens that could not be delivered. Reduce the investor's recorded contribution in that currency by the amount in the event. |
| `primary-market.sale-activated.final` | `final` | A sale administrator opens a token sale for subscriptions, in its presale round if one is configured and in its public round otherwise. Resuming a paused sale sends no event. | Open subscriptions in your own systems. `phase` says which round the sale started in: `presale`, which admits whitelisted investors only, or `public-sale`. |
| `primary-market.sale-closed.final` | `final` | A sale administrator ends a token sale, before or after its end time or before it opened, so it takes no more subscriptions. A sale that reaches its end time without being ended sends no closed event. | Stop offering subscriptions in your systems. Expect the outcome in `primary-market.sale-finalized.final`, and do not require an earlier `primary-market.sale-activated.final`. |
| `primary-market.sale-extended.final` | `final` | A sale administrator moves the end time of an active or paused token sale to a later time. | Replace the end time you stored for the sale with `saleEndTime` from the event. |
| `primary-market.sale-finalized.final` | `final` | A token sale that is closed or past its end time is finalised. `outcome` is `succeeded` when the sale met its soft cap or has none, and `failed` otherwise. | After `succeeded`, investors can withdraw held tokens and the sale's proceeds can be withdrawn. After `failed`, investors can claim refunds. |
| `primary-market.subscription.final` | `final` | An investor pays into a token sale with one payment currency to purchase tokens. | Record the purchase with the token and payment amounts in the event. Tokens arrive later with `primary-market.delivery.final` only when the sale holds them for a soft cap or vesting, because a sale with neither delivers at purchase. |

## Trading venue [#trading-venue]

A [trading venue](https://docs.settlemint.com/docs/concepts/issuing-and-markets/trading-venue) matches orders off chain, settles each trade on chain, and delivers the assets when the instrument's holding period, the delay between settlement and delivery, ends. A bust is an approved reversal of a trade. A `provisional` event reports matched activity that has not settled, and the chain events `trading-venue.trade.final` and `trading-venue.trade.retracted` have the state `final` because the platform sends them after chain finality. `trading-venue.trade-settled.final` and `trading-venue.trade-fee.final` go out when the settlement transaction confirms, without waiting for chain finality, and only a bust retracts them.

| Event | State | Sent when | What to do |
| --- | --- | --- | --- |
| `trading-venue.announcement.published` | `final beta` | A venue operator publishes an announcement, for the whole venue or for one instrument. A scheduled announcement sends this event when it goes live at its display-from time, within about 15 seconds, not when it is scheduled. An issuer notice, which a holder of the token's Governance or Supply management role submits through the API, sends this event once a venue operator approves it and the notice goes live. | Use the title, category and severity in the event to alert your users. The event has no body: read it from the announcements endpoint of the Platform API, which applies the caller's audience. |
| `trading-venue.announcement.updated` | `final beta` | A venue operator edits a published announcement's title, body, severity or display end. Saving an edit that changes nothing sends no event. | Refresh the title, category and severity you show, and read the new body from the announcements endpoint of the Platform API. |
| `trading-venue.announcement.withdrawn` | `final beta` | A venue operator withdraws a published announcement. Withdrawing a scheduled announcement before its display-from time sends no event. One withdrawn after that time sends the published event first. | Stop showing the announcement. The announcements endpoint of the Platform API no longer returns it to callers other than operators. |
| `trading-venue.cancellation-batch.completed` | `final beta` | An operator action cancels open orders in one batch: an instrument is delisted or suspended, a participant's orders are cancelled or the participant is blocked, a wallet is removed from a private instrument, or an approved mass cancel runs. A batch that cancelled no order sends nothing. An action that fails partway records its batch but sends no event. | Tell the affected participants and keep the batch id. Read or download the cancelled orders from the cancellation batches endpoint of the Platform API. |
| `trading-venue.market-status.changed` | `final beta` | An operator changes an instrument's lifecycle status. The payload carries the new status and the operator's required reason. | Update the instrument status and retain the reason with the transition. |
| `trading-venue.order-status.provisional` | `provisional beta` | The venue matching engine changes an order: the order is placed or replaced, filled, or changes status in another way. The platform sends one event for each order the change touches. | Update your copy of the order and keep the event with the highest `sequence` for each order. A `filled` status is not a settled trade: wait for `trading-venue.trade-settled.final`. |
| `trading-venue.price-alert.triggered` | `provisional beta` | The price of a matched trade crosses a user's price alert on an instrument. An alert with direction `above` fires at or over its threshold, an alert with direction `below` fires at or under it, and each alert fires once. | Notify the user who set the alert. The price comes from a matched trade that has not settled, so match `tradeId` against `trading-venue.trade-settled.final` before you treat the price as settled. |
| `trading-venue.settlement-fill.aged` | `final beta` | A parked settlement fill stays parked past the age alert threshold, one hour by default. The platform sends one event for each parked interval, with the fill's current age and the threshold in seconds. | Ask a venue operator to open the fill in the Held fills tab and retry it or bust the trade. |
| `trading-venue.settlement-fill.parked` | `final beta` | The venue parks a settlement fill because it could not settle it. The payload carries the refusal reason and the number of settlement attempts started so far. | Read the reason. Retry the fill from the Held fills tab once the cause is fixed, or bust the trade. |
| `trading-venue.trade-fee.final` | `final beta` | The venue charges one side of a settled trade a fee, and the platform records it with the settlement. The platform sends one event for each charged side, together with `trading-venue.trade-settled.final`. | Book the fee against the payer in the event. `amount` is the fee without VAT and `vatAmount` is the VAT on it, zero where none applies. Both are in the base units of the instrument's quote token, the token that prices its trades. `orderRecipientAddress` is the order's asset destination, not the account that receives the fee. |
| `trading-venue.trade-fee.retracted` | `retracted beta` | A bust reverses a settled trade that charged fees. The platform sends one event for each fee the trade charged, together with `trading-venue.trade-settled.retracted`. | Reverse the fee you booked from `trading-venue.trade-fee.final`. `supersedes` is optional and names that event when the platform queued it for your endpoint, so match the fee by `feeId` if it is absent or you never received that event. |
| `trading-venue.trade-leg.parked` | `final beta` | A delivered trade had one leg its receiver could not take. The venue booked that leg to the receiver's free balance in the venue escrow instead of undoing the trade. The platform sends one event for each parked leg, after the `trading-venue.trade.final` event of the same delivery. `leg` is `base`, `quote` or `fee`, and `amount` is in base units of `tokenAddress`. | Keep the trade as delivered and record that the leg waits in the receiver's escrow balance. The receiver withdraws it through the escrow, which runs the token's compliance again, so an unverified receiver cannot take it out until it is verified. Match the trade by `venueTradeId`. |
| `trading-venue.trade-settled.final` | `final beta` | A matched trade settles on chain and the platform records it. The platform sends one event for each trade after the settlement transaction is confirmed and its logs show the fill. | Book the trade as settled. `quoteAmount` is the cash leg, in base units of `quoteTokenAddress`. `delivery` is `delivered` when the assets already moved and `pending-delivery` while the instrument's holding period still applies. |
| `trading-venue.trade-settled.retracted` | `retracted beta` | A bust reverses a settled trade, and the reversal is complete on chain. The platform sends nothing while a reversal transfer is queued, has reverted, or has not completed. | Reverse the settlement you booked from `trading-venue.trade-settled.final`. `supersedes` is optional and names that event when the platform queued it for your endpoint, so match the trade by `tradeId` if it is absent or you never received that event. |
| `trading-venue.trade.final` | `final beta` | The venue contract delivers a trade on chain: its holding period ends and the assets move. A leg the receiver cannot take is booked to the receiver's escrow balance instead, and the trade still counts as delivered. | Treat the trade as delivered. An instrument with no holding period delivers inside the settlement transaction and sends no `trading-venue.trade.final`, so read `delivery` on `trading-venue.trade-settled.final` for those instruments. |
| `trading-venue.trade.retracted` | `final beta` | The venue contract undoes a trade because of a bust while the delivery of the trade is still pending. An undo for any other reason, including an outside cause that blocks delivery, sends nothing. | Mark the trade as undone. Its delivery was still pending, so the platform never sent `trading-venue.trade.final` for it, and the event has no `supersedes`: match the trade by `venueTradeId`. |

The `status` of a `trading-venue.order-status.provisional` event is the engine status the order holds after the change: `pending_reservation`, `armed`, `working`, `partially_filled` or `suspended` while the order can still execute, and `filled`, `cancelled`, `expired`, `rejected` or `pruned` once it cannot. `closeReason` carries the engine's reason for a closed order.

To reconcile these events with the venue's [FIX drop copy](https://docs.settlemint.com/docs/concepts/issuing-and-markets/venue-controls#what-each-drop-copy-report-carries), match them on the identifiers both feeds carry. The `sequence` of a `trading-venue.order-status.provisional` event is the log sequence in the `ExecID`, tag 17, of the drop-copy reports for the same entry. That `ExecID` has the form `<marketId>:<sequence>:<n>`. The event's `occurredAt` equals the reports' `TransactTime`, tag 60. For `trading-venue.trade-settled.final`, `tradeId` equals the `TrdMatchID`, tag 880, of the two fill reports, and `executedAt` equals their `TransactTime`.

## XvP settlement [#xvp-settlement]

XvP stands for exchange-versus-payment. An [XvP settlement](https://docs.settlemint.com/docs/concepts/settlement/xvp-settlement) is a contract that exchanges assets between parties in transfers called legs. Each sending participant approves it and locks its assets in the contract, which is called escrow. A settlement with a leg on another chain also has a hashlock, a hash that blocks execution until its secret is revealed. Every event includes `settlementAddress`. The platform sends it once the block reaches chain finality, and only to endpoints on the System that owns the settlement's factory. A System is an organisation's on-chain DALP deployment.

| Event | State | Sent when | What to do |
| --- | --- | --- | --- |
| `xvp.approval-revoked.final` | `final` | A settlement participant withdraws its approval while the settlement is open. The contract returns any escrow that participant locked in the same transaction, so refund events can come from it. | Store the new `approvedCount` and `requiredCount`, and mark `accountAddress` as not approved. Take the escrow change from `xvp.assets-refunded.final` or `xvp.refund-deferred.final`, because this event has no amount. |
| `xvp.assets-locked.final` | `final` | A settlement participant locks an asset in the settlement's escrow while approving it. The platform sends one event for each asset that the approval adds escrow for. | Add `amount` to the escrow you track for `accountAddress` and `assetAddress`. `amount` is the extra escrow this approval adds to what the participant already locked. |
| `xvp.assets-refunded.final` | `final` | Escrow that a participant locked leaves the settlement for that participant. This follows a revoked approval, a cancellation, a withdrawal after the settlement expires, or a `claimRefund` call. | Subtract `amount` from the escrow you track for `accountAddress` and `assetAddress`. After a `claimRefund` call the participant can send the tokens to another address, and the event does not identify that address. |
| `xvp.delivery-claimed.final` | `final` | A recipient calls `claimSettled` to pull a delivery that `xvp.delivery-deferred.final` parked in the settlement. The asset leaves the settlement at this point. | Mark the parked delivery for `accountAddress` and `assetAddress` as delivered. The recipient can choose another receiving address, and the event does not identify it. |
| `xvp.delivery-deferred.final` | `final` | A settlement executes but the transfer to a recipient fails, for example because the token blocks that recipient, so the contract parks the amount in the settlement. Only a settlement with a leg on another chain parks a delivery this way, and only after its secret is revealed. | Do not book the asset as delivered to `accountAddress`. It stays in the settlement until the recipient calls `claimSettled`, which produces `xvp.delivery-claimed.final`. |
| `xvp.refund-deferred.final` | `final` | The contract cannot transfer a participant's escrow back, for example because the token blocks that participant, so it parks the amount in the settlement. The revoked approval, cancellation or withdrawal after expiry that triggered the refund still completes. | Keep the amount in escrow for `accountAddress` and `assetAddress`. It leaves only when the participant calls `claimRefund`, which produces `xvp.assets-refunded.final`. |
| `xvp.settlement-approved.final` | `final` | A settlement participant approves the settlement. The event includes the approval count after the change. | Compare `approvedCount` with `requiredCount`: when they are equal, every approval is in. A settlement with `autoExecute` set then executes in the same transaction, unless it has a leg on another chain whose secret is not revealed. |
| `xvp.settlement-cancelled.final` | `final` | A settlement is cancelled before it executes. A fully approved settlement with a leg on another chain cancels only after every participant that sends an asset on this chain votes to cancel, and the votes alone send no event. | Mark the settlement as cancelled. `cancellerAddress` identifies the caller that completed the cancellation, and `xvp.assets-refunded.final` or `xvp.refund-deferred.final` events from the same transaction return the escrow. |
| `xvp.settlement-created.final` | `final` | A settlement factory creates a settlement and fixes its legs and its cutoff, the time after which the settlement expires. The event includes the hashlock and never the secret that opens it. | Store the settlement by `settlementAddress` and its legs by `legIndex`. `xvp.settlement-executed.final` uses the same leg indexes. |
| `xvp.settlement-executed.final` | `final` | A settlement executes: the contract uses the paying parties' escrow and transfers the assets to the receiving parties. This happens when a caller runs `execute`, or with the last approval when `autoExecute` is set. | Mark the settlement as executed and match `flows` to your stored legs by `legIndex`. A recipient the contract could not pay appears in `xvp.delivery-deferred.final` from the same transaction, and stays parked until `xvp.delivery-claimed.final`. |
| `xvp.settlement-expired.final` | `final` | A caller withdraws the escrow of a settlement that passed its cutoff without executing. Reaching the cutoff alone sends nothing. | Mark the settlement as expired. `callerAddress` identifies the account that withdrew the escrow, and `xvp.assets-refunded.final` or `xvp.refund-deferred.final` events from the same transaction return it. |

## Related [#related]

- [Event catalogue](https://docs.settlemint.com/docs/api-reference/webhooks/events): the events of every other domain, and the reserved names.
- [Subscriptions](https://docs.settlemint.com/docs/api-reference/webhooks/subscriptions): the patterns that select events, and the events the default subscriptions skip.
- [Lifecycle states](https://docs.settlemint.com/docs/api-reference/webhooks/lifecycle): what each state means, with worked sequences.
- [Consuming webhooks](https://docs.settlemint.com/docs/api-reference/webhooks/consuming): identifiers, deduplication, ordering, retries and retractions.


# Subscriptions

Source: https://docs.settlemint.com/docs/api-reference/webhooks/subscriptions
Lists the subscription pattern grammar, its validation rules, the default subscriptions, and the live events the defaults skip.

A [webhook endpoint](https://docs.settlemint.com/docs/api-reference/guides/webhooks) is the HTTPS address that receives DALP events. It receives an event when one of its subscription patterns matches the event name. A pattern is an exact name, `*`, a name prefix ending in `.*`, or a state pattern such as `*.final`.

## Pattern grammar [#pattern-grammar]

A pattern has one of four forms. For a new event, the platform matches it against the event name only. An event name has three parts separated by dots, for example `token.transfer.final`. Many names end in a lifecycle state. Some end in another word, such as `funding.requirement.raised`.

| Form | Pattern | Delivers |
| --- | --- | --- |
| Catch-all | `*` | Every event. |
| State pattern | `*.final` | Every event whose name ends in `.final`. |
| Name prefix | `token.transfer.*` | Every event whose name starts with `token.transfer.`. |
| Exact name | `token.transfer.final` | That event. |

### Syntax rules [#syntax-rules]

- A segment contains lowercase letters, digits, and hyphens. A hyphen sits between two letters or digits.
- Dots separate segments, and no segment is empty.
- `*` is a complete segment. It stands alone, comes first in a state pattern, or comes last in a name prefix.
- A name prefix has one or more segments before `.*`.
- An exact name has exactly three segments.

The patterns `token.*.final` and `Token.transfer.*` break these rules. The platform answers a request that contains such a pattern with status 400 and the error `REQUEST_INVALID`, id `DALP-14261`.

### Validation [#validation]

A pattern with valid syntax must also pass the registry rules. The platform applies them on `POST /api/v2/webhooks`, and on `PATCH /api/v2/webhooks/{webhookId}` when the body supplies `subscriptions`. A pattern or list that fails answers status 400 with the error `WEBHOOK_SUBSCRIPTION_INVALID`, id `DALP-0534`. The error is not retryable. Change the list and send the request again. The [Platform API error reference](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference) lists both errors.

The state in a state pattern must be one of `pending`, `provisional`, `final`, `retracted`, or `recalled`. A name prefix or an exact name must match a registered event. The retired custody ledger events are no longer registered (the SDK changelog names each removed event). An endpoint that already holds one keeps working, but saving a list that still names one is rejected with `WEBHOOK_SUBSCRIPTION_INVALID` until the name is dropped. The pattern `*.recalled` is accepted. It delivers only a `recalled` event that DALP 3.1 stored and a Replay resends. The reserved name `compliance.freeze.recalled` is also accepted as an exact subscription, although no action sends it. The other reserved names, `token.transfer.pending` and `settlement.transfer.retracted`, are rejected as exact names.

| Pattern | Result | Reason |
| --- | --- | --- |
| `*` | Accepted | The catch-all is always valid. |
| `*.final` | Accepted | `final` is a lifecycle state. |
| `*.pending` | Accepted | `pending` is a lifecycle state. No live event name ends in `.pending`, so the pattern delivers nothing. |
| `*.confirmed` | Rejected | `confirmed` is not a lifecycle state. |
| `ledger.entry.*` | Rejected | No registered event name starts with `ledger.entry.`. |
| `token.transfer.retracted` | Rejected | A retraction of a `.provisional` or `.final` event cannot be named exactly. Use `token.transfer.*` or `*`. |

### Retraction subscriptions [#retraction-subscriptions]

A retraction is an event whose name ends in `.retracted`. It withdraws an earlier event, and the retraction supersedes that event. The platform rejects a list when one of its patterns matches a retraction and no pattern in the list matches the event that the retraction supersedes. The rule applies when the name of the superseded event ends in `.pending`, `.provisional`, or `.final`.

For a chain reorganisation correction, the platform checks whether it recorded a successful delivery of the removed chain observation. The endpoint's subscription patterns do not decide whether the platform generates that automatic correction. Receiver-side processing alone is not a recorded delivery. Your receiver must handle these corrections. The [retraction rules](https://docs.settlemint.com/docs/api-reference/webhooks/consuming#retractions) cover lost acknowledgements.

| List | Result | Reason |
| --- | --- | --- |
| `*.provisional`, `*.final`, `*.retracted` | Accepted | Every retraction has its source event in the list. |
| `*.retracted` | Rejected | The list contains no source events. |
| `*.final`, `*.retracted` | Rejected | Retractions of `.provisional` events, such as the retraction of `token.transfer.provisional`, have no source. |
| `*.provisional`, `*.retracted` | Rejected | Retractions of `.final` events, such as `trading-venue.trade-fee.retracted`, have no source. |
| `token.transfer.*` | Accepted | The prefix delivers `token.transfer.provisional`, `token.transfer.final`, and `token.transfer.retracted`. |
| `token.corporate-action.retracted` | Accepted | The event it supersedes, `token.corporate-action.announced`, has no lifecycle state at the end of its name. |

### Worked examples [#worked-examples]

| Pattern | Delivers |
| --- | --- |
| `*` | Every event. |
| `*.final` | Every event whose name ends in `.final`, such as `token.transfer.final` and `asset.burn.final`. It skips `token.transfer.provisional`. |
| `token.transfer.*` | `token.transfer.provisional`, `token.transfer.final`, and `token.transfer.retracted`. |
| `funding.*` | `funding.requirement.raised`, `funding.requirement.resolved`, and `funding.requirement.expired`. |
| `identity.registration.provisional` | Selects that initial event. A chain reorganisation can also send `identity.registration.retracted` after a successful provisional delivery, without a matching retraction pattern. |

Bank rail endpoints select `bank-rail.credit.*` and `bank-rail.cash-out.*` explicitly. The defaults skip these milestone names, including `bank-rail.credit.recalled`, whose envelope state is `final`. A `*.recalled` pattern matches that event's name too, but matching a suffix never changes its envelope state.

## Default subscriptions [#default-subscriptions]

A new endpoint receives events that match three state patterns: `*.provisional`, `*.final`, and `*.retracted`. The platform applies them when the create request omits `subscriptions`. The Console create form starts with the same three patterns selected.

State patterns match the last part of the event name. They never read the `lifecycle_state` field of the envelope. The defaults therefore skip an event whose name ends in a word other than a state, even when its envelope shows `provisional` or `final`. `funding.requirement.raised` shows `final` and ends in `raised`. `trading-venue.price-alert.triggered` shows `provisional` and ends in `triggered`. No default pattern matches either name.

An explicit empty list, `[]`, selects no new events. It does not request the defaults. Repeated or overlapping patterns select an endpoint once, rather than creating a copy for each matching pattern. Automatic chain reorganisation corrections for provisional events delivered earlier can still arrive.

An existing endpoint keeps its stored list. The defaults apply only at creation. An update that supplies `subscriptions` replaces the stored list, so adding one pattern means sending the full list. An update that omits `subscriptions` leaves the list unchanged.

## Events the default subscriptions do not deliver [#events-the-default-subscriptions-do-not-deliver]

A new endpoint does not receive these events, because the last part of each name matches no default pattern. The name prefix in the second column delivers the event, and it also delivers the other live events that start with it. The exact event name works as well.

| Event | Subscribe with |
| --- | --- |
| `access-control.role-grant.expired` | `access-control.role-grant.*` |
| `access-control.role-grant.expiring` | `access-control.role-grant.*` |
| `bank-rail.cash-out.instructed` | `bank-rail.cash-out.*` |
| `bank-rail.cash-out.paid` | `bank-rail.cash-out.*` |
| `bank-rail.cash-out.released` | `bank-rail.cash-out.*` |
| `bank-rail.cash-out.requested` | `bank-rail.cash-out.*` |
| `bank-rail.cash-out.returned` | `bank-rail.cash-out.*` |
| `bank-rail.credit.admitted` | `bank-rail.credit.*` |
| `bank-rail.credit.allocated` | `bank-rail.credit.*` |
| `bank-rail.credit.cancelled` | `bank-rail.credit.*` |
| `bank-rail.credit.minted` | `bank-rail.credit.*` |
| `bank-rail.credit.parked` | `bank-rail.credit.*` |
| `bank-rail.credit.recalled` | `bank-rail.credit.*` |
| `bank-rail.credit.returned-to-payer` | `bank-rail.credit.*` |
| `custody.gateway-deposit.settled` | `custody.gateway-deposit.*` |
| `custody.gateway-withdrawal.settled` | `custody.gateway-withdrawal.*` |
| `funding.requirement.expired` | `funding.requirement.*` |
| `funding.requirement.raised` | `funding.requirement.*` |
| `funding.requirement.resolved` | `funding.requirement.*` |
| `operations.case.acknowledged` | `operations.case.*` |
| `operations.case.opened` | `operations.case.*` |
| `operations.case.resolved` | `operations.case.*` |
| `reporting.filing.deadline-warning` | `reporting.filing.*` |
| `reporting.filing.sla-breached` | `reporting.filing.*` |
| `token.corporate-action.announced` | `token.corporate-action.*` |
| `token.corporate-action.completed` | `token.corporate-action.*` |
| `token.corporate-action.paid` | `token.corporate-action.*` |
| `token.document.published` | `token.document.*` |
| `trading-venue.announcement.published` | `trading-venue.announcement.*` |
| `trading-venue.announcement.updated` | `trading-venue.announcement.*` |
| `trading-venue.announcement.withdrawn` | `trading-venue.announcement.*` |
| `trading-venue.cancellation-batch.completed` | `trading-venue.cancellation-batch.*` |
| `trading-venue.market-status.changed` | `trading-venue.market-status.*` |
| `trading-venue.price-alert.triggered` | `trading-venue.price-alert.*` |
| `trading-venue.settlement-fill.aged` | `trading-venue.settlement-fill.*` |
| `trading-venue.settlement-fill.parked` | `trading-venue.settlement-fill.*` |
| `trading-venue.trade-leg.parked` | `trading-venue.trade-leg.*` |
| `transaction.request.broadcast` | `transaction.request.*` |
| `transaction.request.cancelled` | `transaction.request.*` |
| `transaction.request.confirmed` | `transaction.request.*` |
| `transaction.request.dead-lettered` | `transaction.request.*` |
| `transaction.request.failed` | `transaction.request.*` |

## Choose patterns for your integration [#choose-patterns-for-your-integration]

Each row maps a need to a list that the platform accepts.

| You need | Subscribe with | Behaviour |
| --- | --- | --- |
| Every event | `*` | Delivers every live event, including the events that the defaults skip. |
| The defaults and one skipped family | `*.provisional`, `*.final`, `*.retracted`, `funding.requirement.*` | An update replaces the stored list, so the request must contain all four patterns. |
| Final events only | `*.final` | Delivers no retraction, including `trading-venue.trade-fee.retracted`, the retraction of a final event. It skips every event whose name does not end in `.final`, such as `identity.registration.provisional`. |
| Events and their corrections | `*.provisional`, `*.final`, `*.retracted` | These are the defaults. A list with `*.retracted` and without the matching source patterns is rejected. |
| One event family | `token.transfer.*` | Delivers the provisional, final, and retracted events of the family. It passes the retraction rule on its own. |
| One event | `identity.registration.provisional` | Selects that initial event. Automatic chain reorganisation corrections for a previously delivered provisional event can also arrive. |

The Console create and edit forms offer `*.pending`, `*.provisional`, `*.final`, `*.retracted`, and `transaction.request.*` as checkboxes. The transaction-request option starts unchecked. Their "Event names" field takes any other name prefix or exact name. It lists the published names grouped by their first segment, such as `token`, and offers a prefix such as `token.transfer.*` for each family of more than one event. The form refuses a name that matches no published event before it saves.

## Related [#related]

- [Event catalogue](https://docs.settlemint.com/docs/api-reference/webhooks/events): the events of every domain except token sales, trading venues and XvP settlements, when the platform sends each one and what to do with it.
- [Market and settlement events](https://docs.settlemint.com/docs/api-reference/webhooks/market-events): the events of token sales, trading venues and XvP settlements, when the platform sends each one and what to do with it.
- [Lifecycle states](https://docs.settlemint.com/docs/api-reference/webhooks/lifecycle): what each state means and which sequences an endpoint sees.
- [Consuming webhooks](https://docs.settlemint.com/docs/api-reference/webhooks/consuming): identifiers, deduplication, retries, and retractions on the receiving side.
- [Receive DALP webhooks](https://docs.settlemint.com/docs/api-reference/guides/webhooks): register an endpoint, verify the signature, and rotate the secret.
- [Webhook endpoints in the Console](https://docs.settlemint.com/docs/console/organisation-settings/webhooks): create an endpoint and choose its subscriptions.


# DALP privacy policy and personal data protection

Source: https://docs.settlemint.com/docs/business/legal/privacy-policy
How the SettleMint Digital Asset Lifecycle Platform collects, uses, stores, and protects personal data.

Effective date: 5 March 2026

Last updated: 20 August 2026

SettleMint NV ("SettleMint"), incorporated in Belgium (company number 0661.674.810, registered at Philipssite 5 bus 1, 3001 Leuven), publishes this Privacy Policy. It covers personal data processed in connection with the SettleMint Digital Asset Lifecycle Platform ("DALP" or the "Platform") and related websites and services, including your rights and the special rules that apply to public blockchain records.

SettleMint processes account, usage, technical, compliance and transaction-related data to operate DALP, support customers, secure the Platform and meet its legal obligations. Personal data written to public blockchain networks cannot be deleted or modified by SettleMint. Keep personal data and confidential terms off-chain unless your own legal and operational process allows it.

This Privacy Policy applies globally. Where specific regulations grant you additional rights, those are detailed in the [jurisdiction-specific sections](#11-jurisdiction-specific-provisions).

## Privacy at a glance [#privacy-at-a-glance]

This policy covers three privacy surfaces. Each follows its own rules.

| Privacy surface | What it covers | What this means |
| --- | --- | --- |
| Platform records | Account, usage, technical, communication, and compliance records that SettleMint or its subprocessors process to provide DALP and support customers | These records follow the access, retention, transfer, and deletion controls in this policy. |
| Customer-controlled records | End-user identity, verification, holder, and transaction records that a customer processes through DALP as its own controller | The customer decides the lawful basis and instructions for that processing. SettleMint acts as processor where the Data Processing Agreement applies. |
| Public-chain records | Wallet addresses, transaction hashes, smart contract records, and other data that can become visible on public EVM networks | SettleMint cannot remove these records after submission to the network. |

## 1. Data controller [#1-data-controller]

SettleMint NV is the data controller responsible for processing your personal data as described in this Privacy Policy. For questions or requests, contact the Data Protection Officer:

Data Protection Officer
SettleMint NV
Philipssite 5 bus 1
3001 Leuven, Belgium
Email: [privacy@settlemint.com](mailto:privacy@settlemint.com)

## 2. Personal data SettleMint collects [#2-personal-data-settlemint-collects]

The categories cover the personal data SettleMint collects. Which categories apply depends on how you interact with the Platform.

### 2.1 Account and identity data [#21-account-and-identity-data]

Creating an Account or being added as an Authorised User triggers collection of the following data:

- Full name
- Email address
- Organisation name and role
- Phone number (optional)
- Account credentials (passwords are stored in hashed form only)
- Multi-factor authentication identifiers

### 2.2 Compliance and verification data [#22-compliance-and-verification-data]

Identity verification workflows may process the following data about you or your end users:

- Government-issued identification documents (passport, national ID, driver's licence)
- Proof of address documentation
- Corporate registration and beneficial ownership information
- KYC/KYB verification status and results
- Sanctions screening results

Compliance and verification data is processed by you (the Platform customer) as the data controller for your end users. SettleMint acts as a data processor for this data. SettleMint's processing is governed by the Data Processing Agreement between you and SettleMint.

### 2.3 Platform usage data [#23-platform-usage-data]

Platform usage generates the following data, which SettleMint collects automatically:

- Pages visited and features used
- Operations performed (for example, asset creation and transaction submissions)
- Timestamps and session duration
- Error logs and performance data
- API usage and request metadata

### 2.4 Technical data [#24-technical-data]

SettleMint automatically collects this technical information.

- IP address
- Browser type and version
- Operating system
- Device identifiers
- Referring URL
- Language preferences
- Time zone setting

### 2.5 Transaction and blockchain data [#25-transaction-and-blockchain-data]

Creating or managing Digital Assets through the Platform causes SettleMint to process the following data:

- Transaction metadata (timestamps, asset types, amounts)
- Wallet addresses associated with your Account
- Smart contract deployment records
- On-chain transaction hashes

Data written to a public blockchain is immutable and publicly accessible. SettleMint cannot delete or modify on-chain data. Keep personal data, private document identifiers, and confidential terms out of public-chain metadata, calldata, and transaction inputs. All off-chain records remain governed by the retention and deletion controls described in this policy. For more information on public-chain privacy limits, see [A public EVM network makes activity discoverable](https://docs.settlemint.com/docs/deployment/security-compliance-posture#a-public-evm-network-makes-activity-discoverable).

Before launching a public-chain asset workflow, decide where each record belongs. Use this table as a guide.

| Keep off-chain | Use on-chain only when required for execution or enforcement |
| --- | --- |
| Identity documents, KYC/KYB files, sanctions reports, beneficial-ownership evidence, investor questionnaires, review notes, and private customer references | Wallet addresses, smart contract addresses, transaction hashes, role changes, token events, registry relationships, claim topics, and compliance parameters that the contracts need |
| Private reserve files, custody records, commercial terms, document identifiers, and internal approval notes | Neutral metadata, public references, or transaction inputs that your legal and operational review has approved for public-chain visibility |

For asset operations, review names, symbols, metadata fields, document references, calldata, event fields, and transaction inputs before submission. Once the transaction reaches the selected EVM network, SettleMint cannot erase or redact the public-chain record.

### 2.6 Audit and compliance data [#26-audit-and-compliance-data]

SettleMint maintains audit logs of compliance workflows, verification decisions, access events, and regulatory reports generated through the Platform. These records support security, legal compliance, and accountability obligations.

### 2.7 Communication data [#27-communication-data]

When you contact SettleMint for support or other purposes, SettleMint collects this data and uses it to respond to your enquiry and to maintain service records.

- Email correspondence content
- Support ticket details
- Chat transcripts
- Phone call records (where applicable)

### 2.8 Cookies and tracking technologies [#28-cookies-and-tracking-technologies]

SettleMint uses cookies and similar technologies to operate and improve the Platform. You can manage cookie preferences through the consent banner or your browser settings. For details, see [Section 9](#9-cookies-and-tracking-technologies).

## 3. How SettleMint uses your personal data [#3-how-settlemint-uses-your-personal-data]

SettleMint processes your personal data for these purposes and legal bases:

| Purpose | Legal Basis (GDPR) | Categories of Data |
| --- | --- | --- |
| Providing and operating the Platform | Performance of contract (Art. 6(1)(b)) | Account, Usage, Technical, Transaction |
| Account creation and management | Performance of contract (Art. 6(1)(b)) | Account and Identity |
| Processing compliance and verification workflows | Performance of contract (Art. 6(1)(b)) and legal obligation (Art. 6(1)(c)) | Compliance and Verification |
| Customer support and communication | Performance of contract (Art. 6(1)(b)) and legitimate interest (Art. 6(1)(f)) | Account, Communication |
| Platform security and fraud prevention | Legitimate interest (Art. 6(1)(f)) | Account, Usage, Technical |
| Analytics and Platform improvement | Legitimate interest (Art. 6(1)(f)) | Usage, Technical |
| Compliance with legal obligations | Legal obligation (Art. 6(1)(c)) | All categories as required |
| Billing and invoicing | Performance of contract (Art. 6(1)(b)) | Account |
| Marketing communications (with consent) | Consent (Art. 6(1)(a)) | Account (name, email) |

Where SettleMint relies on legitimate interest as a legal basis, it has conducted a balancing test confirming that its interests do not override your fundamental rights and freedoms. You may request details of these assessments by contacting the Data Protection Officer.

## 4. Data sharing [#4-data-sharing]

SettleMint does not sell personal data. It shares personal data only in these circumstances.

### 4.1 Service providers [#41-service-providers]

SettleMint engages third-party service providers who process personal data on SettleMint's behalf. These processors are contractually bound to process data only as instructed and to apply appropriate security measures.

Current processor categories include the following.

- Cloud infrastructure providers (hosting and storage)
- Identity verification and KYC/KYB providers
- Analytics and monitoring providers
- Customer support tools
- Email and communication services
- Payment processors

### 4.2 Professional advisors [#42-professional-advisors]

SettleMint may share personal data with professional advisors where necessary for business management. These recipients are bound by professional confidentiality obligations.

### 4.3 Legal requirements [#43-legal-requirements]

SettleMint may disclose personal data where required by law, regulation, legal process, or governmental request. Disclosure may also occur where necessary to protect SettleMint's rights, your safety, or the safety of others.

### 4.4 Business transfers [#44-business-transfers]

In connection with a merger, acquisition, reorganisation, or sale of assets, personal data may be transferred to the acquiring entity. The acquiring entity receives the data subject to the same privacy protections described in this policy.

### 4.5 With your consent [#45-with-your-consent]

SettleMint may share personal data with third parties where you have given explicit consent. SettleMint does not sell personal data to any third party.

## 5. International data transfers [#5-international-data-transfers]

SettleMint operates globally, and your personal data may be transferred to and processed in countries outside your country of residence, including countries outside the European Economic Area (EEA).

Where SettleMint transfers personal data outside the EEA, appropriate safeguards are in place.

- Adequacy decisions: transfers to countries the European Commission recognises as providing an adequate level of data protection
- Standard Contractual Clauses (SCCs): SettleMint uses the European Commission's standard contractual clauses (June 2021 version) for transfers to countries without an adequacy decision
- Supplementary measures: where necessary, SettleMint implements additional technical and organisational safeguards based on transfer impact assessments

You may request a copy of the applicable transfer safeguards by contacting the Data Protection Officer.

## 6. Data retention [#6-data-retention]

SettleMint retains personal data only as long as necessary to fulfil the purposes for which it was collected, or as required by law. This table sets out the applicable retention periods.

| Data Category | Retention Period | Basis |
| --- | --- | --- |
| Account and Identity Data | Duration of your subscription + 12 months | Contract performance, and legitimate interest for account recovery |
| Compliance and Verification Data | As required by applicable anti-money laundering law (typically 5 to 10 years after the end of the business relationship) | Legal obligation |
| Platform Usage Data | 24 months from collection | Legitimate interest (analytics and improvement) |
| Technical Data | 12 months from collection | Legitimate interest (security and troubleshooting) |
| Transaction and Blockchain Data | Duration of your subscription + 7 years | Legal obligation (financial records retention) |
| Communication Data | 36 months from last interaction | Legitimate interest (customer support continuity) |
| Marketing consent records | Duration of consent + 3 years | Legal obligation (proof of consent) |

On-chain transaction history is immutable and SettleMint cannot delete it. SettleMint deletes or anonymises off-chain personal data at the end of the applicable retention period, unless a legal obligation requires continued retention.

## 7. Data security [#7-data-security]

SettleMint implements appropriate technical and organisational measures to protect personal data against unauthorised access, alteration, disclosure, or destruction. Controls include:

- Encryption of data in transit (TLS 1.2+) and at rest (AES-256)
- Multi-factor authentication for Account access
- Role-based access controls with least-privilege principles
- Regular security assessments and penetration testing
- Intrusion detection and monitoring systems
- Employee security training and confidentiality obligations
- Incident response procedures with documented breach notification protocols

No method of electronic storage or transmission is 100% secure. SettleMint applies these measures but cannot guarantee absolute security.

## 8. Your rights [#8-your-rights]

### 8.1 Rights under GDPR (EEA, UK, and Switzerland) [#81-rights-under-gdpr-eea-uk-and-switzerland]

If you are in the EEA, the UK, or Switzerland, the following rights apply under applicable data protection law:

- Right of access: request a copy of the personal data SettleMint holds about you
- Right to rectification: request correction of inaccurate or incomplete personal data
- Right to erasure: request deletion of personal data where no compelling reason for continued processing exists. This right covers off-chain records only. Immutable public-chain transaction history cannot be removed.
- Right to restriction: request restriction of processing in certain circumstances
- Right to data portability: receive your personal data in a structured, machine-readable format
- Right to object: object to processing based on legitimate interest, including profiling
- Right to withdraw consent: where processing is based on consent, withdraw your consent at any time without affecting the lawfulness of prior processing
- Right to lodge a complaint: file a complaint with your local data protection supervisory authority

SettleMint will respond to your request within thirty (30) days. SettleMint may extend this period by sixty (60) days for complex requests, with prior notification.

### 8.2 Rights under CCPA / CPRA (California residents) [#82-rights-under-ccpa--cpra-california-residents]

California residents have additional rights under the California Consumer Privacy Act and the California Privacy Rights Act. See [Section 11.2](#112-california-ccpa--cpra) for details.

### 8.3 Exercising your rights [#83-exercising-your-rights]

To exercise any of your rights, contact the Data Protection Officer at [privacy@settlemint.com](mailto:privacy@settlemint.com). SettleMint may request identity verification before processing your request. SettleMint will not discriminate against you for exercising any of your privacy rights.

## 9. Cookies and tracking technologies [#9-cookies-and-tracking-technologies]

### 9.1 What SettleMint uses [#91-what-settlemint-uses]

SettleMint uses four categories of cookies and tracking technologies. Strictly necessary cookies are required for the Platform to function and cannot be disabled. They cover authentication, session management, and security. Functional cookies enable enhanced functionality and personalisation, such as language preferences and user interface settings. Analytics cookies help SettleMint understand how the Platform is used, covering page views, feature usage, and error reporting. SettleMint uses these to improve Platform performance and the user experience. Marketing cookies deliver relevant communications and measure the effectiveness of campaigns. SettleMint sets these only with your explicit consent.

### 9.2 Cookie management [#92-cookie-management]

On the SettleMint documentation site, a consent banner lets you accept or reject non-essential cookies. The Console and the Investor portal show no consent banner. The Investor portal loads no analytics, and the Console loads them only when the operator of the instance turns analytics on. The Console then sends the signed-in user's email address and user ID to SettleMint's HubSpot account, and the organisation's ID and name to SettleMint's Google Analytics property. You can manage cookies through your browser settings. Disabling certain cookies may affect Platform functionality.

### 9.3 Do Not Track [#93-do-not-track]

The Platform does not respond to "Do Not Track" browser signals because no uniform standard for honouring them exists. To limit tracking, use the consent banner on the documentation site or adjust your browser settings.

## 10. Children's privacy [#10-childrens-privacy]

The Platform is not directed at individuals under the age of 18. SettleMint does not knowingly collect personal data from children, and no features are intended for use by minors. If SettleMint becomes aware that a child's data was collected without appropriate consent, it will delete those records promptly.

## 11. Jurisdiction-specific provisions [#11-jurisdiction-specific-provisions]

### 11.1 European Economic Area, United Kingdom, and Switzerland [#111-european-economic-area-united-kingdom-and-switzerland]

If you are in the EEA, UK, or Switzerland, GDPR and equivalent national laws grant you the rights and protections described throughout this policy. The following additional provisions also apply.

- Data Protection Officer: you may contact the DPO at [privacy@settlemint.com](mailto:privacy@settlemint.com)

- Supervisory authority: you have the right to lodge a complaint with the Belgian Data Protection Authority (Gegevensbeschermingsautoriteit) at [www.gegevensbeschermingsautoriteit.be](https://www.gegevensbeschermingsautoriteit.be), or your local supervisory authority
- Legal bases: all processing activities have a documented legal basis as described in [Section 3](#3-how-settlemint-uses-your-personal-data)
- Automated decision-making: SettleMint does not make decisions based solely on automated processing, including profiling, that produce legal effects or similarly significantly affect you, unless required for contract performance or with your explicit consent

### 11.2 California (CCPA / CPRA) [#112-california-ccpa--cpra]

If you are a California resident, the following additional provisions apply under the California Consumer Privacy Act (as amended by the California Privacy Rights Act). In the preceding twelve (12) months, SettleMint has collected the categories of personal information described in [Section 2](#2-personal-data-settlemint-collects), which correspond to the following CCPA categories: identifiers, commercial information, internet or electronic network activity, geolocation data, and professional or employment-related information.

California residents hold the following rights:

- Right to know: request disclosure of the categories and specific pieces of personal information SettleMint has collected, the sources of collection, the business purposes, and the categories of third parties with whom SettleMint shares it
- Right to delete: request deletion of your personal information, subject to certain exceptions
- Right to correct: request correction of inaccurate personal information
- Right to opt-out of sale/sharing: SettleMint does not sell your personal information and does not share it for cross-context behavioural advertising
- Right to limit use of sensitive personal information: request that SettleMint limit its use of sensitive personal information to purposes necessary to provide the Services
- Right to non-discrimination: SettleMint will not discriminate against you for exercising your CCPA rights

Submitting requests: contact SettleMint at [privacy@settlemint.com](mailto:privacy@settlemint.com) to exercise your California rights. SettleMint verifies your identity before processing your request. SettleMint responds within forty-five (45) calendar days. This period may extend by an additional forty-five (45) days with notice.

Authorised agents: you may designate an authorised agent to submit requests on your behalf. The agent must provide written authorisation signed by you.

### 11.3 Brazil (LGPD) [#113-brazil-lgpd]

If you are located in Brazil, you have rights under the Lei Geral de Proteção de Dados (LGPD), including the right to access, correct, anonymise, block, or delete personal data. To exercise these rights, contact [privacy@settlemint.com](mailto:privacy@settlemint.com).

### 11.4 Other jurisdictions [#114-other-jurisdictions]

If you are located in a jurisdiction with data protection laws granting you additional rights not covered in this policy, SettleMint will comply with those requirements. Contact the Data Protection Officer for jurisdiction-specific information.

## 12. Data processing on your behalf [#12-data-processing-on-your-behalf]

### 12.1 Customer as controller [#121-customer-as-controller]

When you use the Platform to process personal data of your end users, for example through KYC/KYB verification workflows or asset holder management, you act as the data controller. SettleMint acts as the data processor.

### 12.2 Data processing agreement [#122-data-processing-agreement]

SettleMint's processing of your end users' personal data is governed by a Data Processing Agreement that complies with Article 28 of the GDPR. The agreement addresses the following:

- The scope and purpose of processing
- The types of personal data processed
- The obligations and rights of both parties
- Sub-processor management and notification
- Data breach notification procedures
- Audit rights
- Data deletion and return upon termination

### 12.3 Sub-processors [#123-sub-processors]

SettleMint uses sub-processors to assist in providing the Services. A list of current sub-processors is available on request from [privacy@settlemint.com](mailto:privacy@settlemint.com). SettleMint notifies you of changes to sub-processors. You may object to a new sub-processor under the Data Processing Agreement.

## 13. Changes to this policy [#13-changes-to-this-policy]

SettleMint may update this Privacy Policy to reflect changes in practices, the Platform, or applicable law. SettleMint will communicate material changes at least thirty (30) days in advance via email or through the Platform. The "Last updated" date at the top of this policy indicates when the latest revision was made.

Your continued use of the Platform after the effective date of an updated Privacy Policy constitutes acceptance of the changes. If you do not agree with the changes, discontinue use of the Platform.

## 14. Contact [#14-contact]

Contact the Data Protection Officer to ask about this Privacy Policy, exercise your rights, or complain about the handling of your personal data:

Data Protection Officer
SettleMint NV
Philipssite 5 bus 1
3001 Leuven, Belgium
Email: [privacy@settlemint.com](mailto:privacy@settlemint.com)

For general enquiries about the Platform:
Email: [support@settlemint.com](mailto:support@settlemint.com)

SettleMint aims to resolve all complaints internally. If you are not satisfied with the response, you have the right to lodge a complaint with the relevant data protection supervisory authority.


# Advanced accounts

Source: https://docs.settlemint.com/docs/changelog/dalp-3-0/advanced-accounts
Operators act through ERC-4337 smart wallets while a system paymaster pays the gas for each operation the platform authorises.

**Your operators issue, transfer and administer assets without keeping a native-token balance on every key.** On a conventional account each signer must hold the network's gas token, so every new operator and every network adds a balance to fund, and an empty one stops that person's work. DALP 3.0 adds smart wallets and a system paymaster that pays the gas for each operation the platform authorises.

Spotlight: A system paymaster pays the gas for each smart-wallet operation the platform signs off

- Standards: ERC-4337, ERC-7579 wallets
- Operator gas: Paid by the paymaster
- Sponsorship: Signed per wallet and call
- Reserve: Runway alarms in the Console

The paymaster holds a deposit of the network's native token with the EntryPoint, the shared ERC-4337 contract. Your institution funds the sponsorship reserve behind it from the Console, instead of funding every operator's key.

## Before and after [#before-and-after]

**Before 3.0:** each operator signed from a key that had to hold the network's native token. Every new operator and every network meant another balance to fund, watch and reconcile, and a key that ran dry blocked that operator's work until someone topped it up.

**With 3.0:** an operator's action runs through a smart wallet. DALP signs a sponsorship authorisation for that wallet and call, the system paymaster checks it and pays the gas from its deposit, and the Console raises an alarm when the reserve's runway runs short.

[Figure] How a sponsored smart-wallet operation reaches the network. An operator takes an action without holding a gas token. DALP signs a sponsorship authorisation bound to the wallet, the call data, a gas ceiling and a deadline. The DALP bundler submits the operation to the EntryPoint. The system paymaster checks the authorisation and pays the gas from its EntryPoint deposit, and the operator's ERC-7579 smart wallet runs the action. Without a registered paymaster, or when a custody policy blocks the authorisation, the wallet pays its own gas. Labels: Takes an action; Operator; No gas token on the key; Signs sponsorship; DALP; Wallet, call data, deadline; Submits the operation; DALP bundler; To the EntryPoint; Checks, then pays; System paymaster; From its EntryPoint deposit; Runs the action; Smart wallet; ERC-7579 account; No sponsorship; When none is signed,; the wallet pays its own gas.

A paymaster pays the gas for an operation the platform authorises, bound to one wallet and one call, and the operator's smart wallet runs the action.

## Fund one deposit instead of every operator's key [#fund-one-deposit-instead-of-every-operators-key]

A System manager opens "Advanced accounts" in Settings and chooses **Enable gas sponsorship**, which deploys the organisation's paymaster. "Fund sponsorship reserve" shows the address that tops up the reserve the paymaster spends.

Later an Asset manager mints a bond from their smart wallet. DALP signs a sponsorship authorisation that covers that wallet, a hash of that call, a gas ceiling and a deadline five minutes out. The bundler built into DALP submits the operation, the paymaster checks the authorisation and pays the gas, and the mint executes from the operator's wallet.

The **Sponsorship reserve** tile shows the balance and its days of runway, and its status turns to "Sponsorship runway low" or "Sponsorship runway critical" at the alarm thresholds set under "Configure gas reserves". The Console now keeps the gas payer and the paymaster deposit on its "Transaction funding" page, under "Infrastructure".

![Transaction funding page with the Gas card, the shared gas wallets with a Top up button each, and the Wallet type card](https://docs.settlemint.com/docs/screenshots/console-organisation-transaction-funding.light.en.webp)

[Screenshot] Your treasury sees who pays gas on a network and tops up the shared wallets that pay it.

Your treasury funds and watches one balance per network instead of one per operator, and a new operator starts work without a funding request. The **Submission reserve**, which pays to put operations on-chain, has its own balance and low-balance status on the same screen. Sponsorship needs a paymaster registered for the system and a signed authorisation, and when either is missing, or a custody policy blocks signing the authorisation, the operation runs unsponsored and the wallet pays its own gas. Any other signing error fails the operation.

## Tie each sponsored operation to one wallet and one call [#tie-each-sponsored-operation-to-one-wallet-and-one-call]

The paymaster pays only for an operation that carries an authorisation from the platform's sponsorship signer. Before the EntryPoint spends any gas, the paymaster checks the sending wallet, the hash of the call data, the gas ceiling, the signer and the deadline. An authorisation issued for one mint cannot pay for a different call or another wallet, and it expires at its deadline. A System manager can **Rotate signing key**, and the current key stops working as soon as the new one takes effect.

A leaked authorisation pays only for that wallet making that same call, within its ceiling and until its deadline, and the wallet's own signature is still needed for each operation. The paymaster checks the authorisation and not the business purpose, so any operation DALP signs for within the ceiling is covered, and who can act in DALP decides what gets sponsored.

## Give operators wallets your institution can govern [#give-operators-wallets-your-institution-can-govern]

Each smart wallet follows ERC-7579, the modular account standard, so validation rules attach as modules without replacing the wallet. Weighted multisig validation gives each key a weight and sets a threshold, and the wallet refuses an operation until the signatures reach it. Each wallet starts with a single-owner validator, and any installed validator can approve an operation. Once that single-owner validator is removed, a treasury wallet can require two of three officers before it moves funds, and no single key can skip that rule.

Every wallet is a lightweight proxy that reads its code from the platform directory, so one upgrade applies to all of them without a migration per operator. An upgrade by the directory administrator reaches every wallet at once, so that role needs the same control as any other key that can change every account.

## Upgrading [#upgrading]

Nothing to do for accounts you already run: existing externally owned accounts and their permissions keep working. A System manager decides when to choose **Enable Advanced accounts**, which routes new transactions through managed smart accounts, and funds the submission and sponsorship reserves on each network before turning on gas sponsorship.

## Why it matters [#why-it-matters]

- **Banks:** operators work without holding a network's native token, and your treasury funds one reserve per network instead of a key per person.
- **Regulators:** A sponsored operation carries an authorisation bound to one wallet and one call, and a multisig rule sits in the wallet on-chain.

## Next steps [#next-steps]

- [Understand smart wallets →](https://docs.settlemint.com/docs/concepts/custody-and-signing/smart-wallet)
- [Understand gas sponsorship →](https://docs.settlemint.com/docs/concepts/custody-and-signing/gas-sponsorship)


# Asset templates

Source: https://docs.settlemint.com/docs/changelog/dalp-3-0/asset-templates
Issue each new bond, fund or deposit token from a template your team has reviewed, so issuers set only the terms of the issue.

**Your next bond, fund or deposit token starts from a design your team has already reviewed.** Without a standard, each launch depends on someone remembering which features, defaults and data fields the instrument needs, and two teams can issue the same product two different ways. DALP 3.0 adds a library of instrument templates that holds those decisions, so the issuer fills in only the terms of this issue.

Spotlight: A template holds an instrument's features, defaults and data fields, so every launch repeats a reviewed design

- Library templates: Twenty-four, read-only
- Asset classes: Six
- Your templates: Duplicate, adjust, publish
- Issuer edits: Only configurable fields

The DALP Library covers Fixed Income, Equity, Funds, Cash, Real Assets and Structured. Your organisation's published templates sit beside it in Asset Designer, the guided flow where your team configures and issues an instrument.

## Before and after [#before-and-after]

**Before 3.0:** every instrument started from an empty configuration. Which token features a bond needs, which defaults are safe and which fields a reviewer expects lived with a few experienced people. A second team issuing the same kind of note could launch it with different features, and the difference showed only when a servicer or an auditor compared the records.

**With 3.0:** A System manager duplicates the closest library template, sets your institution's defaults and decides which values an issuer may change at launch. Once published, the template is where every issue of that instrument starts, and the issuer sees only the decisions that are still theirs.

[Figure] From a library template to an issued bond. A System manager duplicates the read-only Sovereign Bond template from the DALP Library into a draft copy, sets its defaults, token features and data fields, and publishes it as the house standard. In Asset Designer the issuer sets only the fields left configurable, and the bond deploys with the template's features installed on-chain. Locked defaults stay as designed, and the ISIN and dates are fixed once the issuer sets them. Labels: Sovereign Bond; DALP Library; Read-only system template; Your draft copy; Duplicate template; Defaults, features, fields; Your house standard; Publish template; Listed in Asset Designer; Issuer sets the terms; Asset Designer; Configurable fields only; Bond deployed; On-chain; Template features installed; Stays as designed; Locked defaults; ISIN, dates fixed at issue.

A System manager duplicates a library template and publishes it as the house standard, and the issuer then sets only the fields left configurable.

## Start from the closest of twenty-four library templates [#start-from-the-closest-of-twenty-four-library-templates]

Every issue in Asset Designer starts at "Choose instrument template", and the DALP Library already holds twenty-four templates across six asset classes. The Console now labels this first step **Instrument**.

![Issue asset screen on its first step, Choose an instrument, with a searchable list of instrument templates and their class and features](https://docs.settlemint.com/docs/screenshots/console-issue-new-asset.light.en.webp)

[Screenshot] Your asset team starts every new issue by picking the closest template.

| Asset class | Library templates |
| --- | --- |
| Fixed Income | Sovereign Bond, Corporate Bond, Treasury Bill, Green Bond, Commercial Paper, Convertible Note, Syndicated Loan |
| Equity | Common Equity, Preferred Equity, Employee Equity Award |
| Funds | ETF, Mutual Fund, Money Market Fund, Private Equity Fund |
| Cash | Certificate of Deposit, Tokenized Bank Deposit, Fiat-Backed Stablecoin |
| Real Assets | Commercial Real Estate, Precious Metals, Carbon Credit, Tokenized Art |
| Structured | Principal-Protected Note, Autocallable Note, Asset-Backed Token |

The Sovereign Bond template requires four token features: maturity redemption, a fixed treasury yield, historical balances and permit. It asks for the data a reviewer needs, such as the ISIN, the sovereign issuer, the issuer jurisdiction and the maturity date, and the template marks those fields immutable, so they are set once at issue. An Asset manager picks Sovereign Bond in Asset Designer and enters the terms of this issue: the maturity date, the face value, the denomination asset, the yield rate and the treasury that pays it. The bond deploys with the template's features installed on-chain, and its record carries the same fields as every other sovereign bond the institution has issued.

The review of what a sovereign bond needs happens once, on the template, and each issue repeats it. Your servicing and compliance teams check one design per product line, and a new team member issues a bond without rebuilding that knowledge from memory. A template sets the starting configuration and does not review the legal terms of an issue.

## Turn your own setup into the house standard [#turn-your-own-setup-into-the-house-standard]

Library templates are read-only, so your changes always live on your own copy. A System manager opens "Instrument templates", picks Corporate Bond and chooses **Duplicate template**. The copy is a draft that belongs to your organisation. They switch on the token features the product line uses and set each feature's defaults. For each setting they decide whether it is "Configurable in the asset designer". A management fee can keep its recipient fixed while the issuer enters the fee rate at launch. When the draft is right, "Publish template" lists it in Asset Designer next to the library.

The issuer who launches from that template sees only the settings marked configurable, and everything else arrives as the template set it. The product decision stays with the team that owns the product, and the issuer cannot quietly change a default that a reviewer signed off. Publishing locks the template's instrument type, so a template for a different instrument starts as a new copy.

## Catch a missing prerequisite before the instrument exists [#catch-a-missing-prerequisite-before-the-instrument-exists]

Each token feature in a template lists what it **Requires** and what it is "Incompatible with", and Asset Designer checks those rules before anything is deployed. Suppose an Asset manager picks Sovereign Bond in an organisation that has no denomination asset yet, the token that sets the payment unit for coupons and redemption. Asset Designer keeps the template unavailable and says that the bond needs a denomination asset, so the issuer creates or registers one first. If a template's fixed-yield terms are incomplete, Asset Designer refuses to create the asset until the yield rate, payment interval and start date are set.

A broken configuration stops at the form, before any contract exists. These checks cover the features and fields the template declares, and the commercial terms of the issue stay with your team.

## Upgrading [#upgrading]

Nothing to do. Instruments issued before 3.0 keep the features they launched with, and the DALP Library appears in Asset Designer after the upgrade. The upgrade sets the system asset classes to Fixed Income, Equity, Funds, Cash, Real Assets and Structured. Organisation templates filed under the former flexible-income class move to Funds when they describe a fund and to Equity otherwise. Hiding a template from Asset Designer leaves existing tokens unaffected.

## Why it matters [#why-it-matters]

- **Banks:** each product line gets one reviewed design, and every issue of that product repeats it.
- **Exchanges, CSDs and market infrastructures:** instruments of the same type arrive with the same features and the same reference data fields, such as the ISIN and the issuer jurisdiction.

## Next steps [#next-steps]

- [Set up instrument templates →](https://docs.settlemint.com/docs/console/asset-design/instrument-templates)
- [Understand instrument templates →](https://docs.settlemint.com/docs/concepts/modeling-assets/instrument-templates)


# SDK, CLI & MCP

Source: https://docs.settlemint.com/docs/changelog/dalp-3-0/cli-api
Script token, identity, compliance and operations work from a terminal or an AI agent, under the signed-in account's permissions.

**Your team scripts the platform work it repeats, and an AI agent can do the same under the permissions of the person who signed it in.** Issuing a token, registering an identity or checking a holder list through the Console takes clicks that a nightly job or an agent cannot make. DALP 3.0 ships a CLI with commands for that work, an MCP server that offers the commands to agents, and a TypeScript SDK, all calling the Platform API.

Spotlight: The CLI, its MCP tools and the SDK call the Platform API, which checks every call the same way

- Sign-in: Browser device flow, key stored locally
- Output: JSON, YAML, Markdown or JSON lines
- Agents: MCP server, skill files
- SDK errors: DalpSdkError with id and category

The Model Context Protocol (MCP) is an open standard that lets an AI agent discover and call tools. Through it, an agent calls the same CLI commands a person types, and the Platform API applies the same permission checks to both.

## Before and after [#before-and-after]

**Before 3.0:** automating platform work meant writing your own client for each API call, and an AI agent had no ready set of DALP tools to discover. Work the Console handled, such as creating a token or registering an identity, stayed manual unless a developer built and maintained a wrapper for it.

**With 3.0:** `dalp` commands cover tokens, token sales, identities and identity recovery, KYC, compliance templates and providers, fixed yield schedules, settlements, webhooks, platform status and system administration. `dalp mcp add` offers those commands to an AI agent as tools. The Platform API applies the same role check, API key scope check and input validation to each call, and a refused call returns the same structured error to a person, a script and an agent.

[Figure] Terminal, script and agent calls all pass the same Platform API checks. An operator's command, a script and an agent's MCP tool call all reach the Platform API, which applies the same role, scope and validation checks and returns either a result or a structured error envelope. Labels: Operator; Terminal; Types a command; Script; Pipeline; --format json; MCP tools; Agent; Registered as tools; Same checks; Platform API; Role, scope, validation; Result; Allowed; JSON, YAML or Markdown; Error envelope; Refused; id, category, retryable.

A command, a script and an agent's MCP tool call all reach the Platform API, which applies the same checks and returns a result or a structured error.

## Script the work your team repeats [#script-the-work-your-team-repeats]

The CLI runs Platform API operations from a terminal or a pipeline. `dalp login` opens an OAuth 2.0 device flow in the browser, so no password is typed into the terminal, and stores an API key in the macOS Keychain, or on other systems in a file only the user can read. Every command takes `--format json`, and also YAML, Markdown or JSON lines.

![Create API key sheet asking for a name, a scope and an expiration, over the list of API keys](https://docs.settlemint.com/docs/screenshots/console-my-account-api-keys-create.light.en.webp)

[Screenshot] Your team creates an API key for a script or pipeline, read-only or with write access.

A Developer at an issuing bank creates a seven-year bond with `dalp tokens create --type bond`, reads it back with `dalp tokens read`, and checks the empty holder list with `dalp tokens holders`. The same three commands then run in the bank's nightly job against a test system, and the job reads the JSON output to confirm each step. When the identity team onboards an investor, `dalp identities create` and `dalp identities register` record the on-chain identity and its country, and `dalp identities registration-status` confirms it landed.

Repeated operational work runs the same way each time and leaves the same platform records as the Console does. We wrote each command by hand for its task, so a new Platform API operation reaches the CLI only when a release adds a command for it.

## Let an agent work under your permissions [#let-an-agent-work-under-your-permissions]

`dalp mcp add` registers the CLI as an MCP server with a supported agent such as Claude Code, Codex, Cursor or OpenClaw, and `dalp --mcp` runs the server directly. `dalp skills add` installs skill files that describe the commands, and `dalp --llms` and `dalp --schema` print the same descriptions as Markdown or JSON Schema.

A Compliance officer asks an agent in the editor to list the compliance templates and the trusted issuers configured for the bank's system. The agent finds the tools, calls them through the officer's signed-in session, and returns the lists. When the agent tries a role grant the officer does not hold, the Platform API refuses the call with a permission error, and the agent reports it instead of retrying.

An agent gets a governed set of tools without a separate integration, and every call it makes is checked against a real account. The agent sees every command whatever the account's roles, and it acts with the full permissions of the signed-in account. The key that `dalp login` creates can write, and a signing request made with an API key does not ask for the PIN or one-time code a Console user enters.

## Branch on errors instead of reading messages [#branch-on-errors-instead-of-reading-messages]

A Platform API failure returns a structured envelope with a stable `DALP-` id, a category, a retryable flag, a `why` and a `fix`, and a `retryAfterSeconds` value when the platform asks the caller to wait. The TypeScript SDK raises it as a `DalpSdkError` with the same fields, and the CLI prints the same fields in its JSON output.

A Developer's job submits a transfer to an investor whose on-chain identity lacks the required KYC claim. The call fails with "Recipient not verified", marked not retryable, and its `fix` says the recipient must complete identity verification first. The job stops and hands the case to the identity team instead of retrying until it times out, and no units move.

Calling code decides between retrying, fixing input and escalating from fields, and [the error guide](https://docs.settlemint.com/docs/api-reference/guides/errors) lists the categories and the retry rules for each. The message, `why` and `fix` are written for people, so code should branch on the `DALP-` id and the retryable flag.

## Upgrading [#upgrading]

Nothing to do. The CLI and the SDK are new client packages for the 3.0 Platform API, and existing API integrations keep working. Install the CLI with your package manager, run `dalp login` against your instance, and keep the CLI version in step with the platform release so its commands match the API.

## Why it matters [#why-it-matters]

- **Banks:** repeated issuance and onboarding work runs as a script your team can review, under the same role checks as the Console, without the Console's wallet-code prompt on signing.
- **Exchanges, CSDs and market infrastructures:** settlement and token operations can be driven from your own jobs, and each refusal comes back as a field your code can act on.
- **Partners:** your product can call DALP through a typed SDK or offer its operations to an AI agent without building a wrapper.

## Next steps [#next-steps]

- [Install the CLI →](https://docs.settlemint.com/docs/api-reference/cli/install)
- [Use the CLI with AI agents →](https://docs.settlemint.com/docs/api-reference/cli/ai-agents)
- [Understand role grants →](https://docs.settlemint.com/docs/concepts/compliance-and-identity/role-grant)


# Compliance templates

Source: https://docs.settlemint.com/docs/changelog/dalp-3-0/compliance-templates
Your compliance team publishes a policy template once, and each new token copies it on-chain and checks it on every ordinary transfer.

**Your compliance team writes the policy once, and every new instrument that uses it starts with the same checks on its token.** When the policy lives in a document and the controls are rebuilt by hand for each asset, a country added to the policy can be missed on one token and nobody sees it until a transfer clears that should not have. DALP 3.0 turns the policy into a template the asset team picks in Asset Designer.

Spotlight: A policy template becomes each new token's own on-chain compliance, checked on every ordinary transfer

- Built-in templates: Nine regulatory regimes
- Applied: Copied to each new token
- Global controls: Apply to every bound token
- Rejections: Typed reasons

A template bundles identity checks, a country allow list, investor or raise limits and transfer approvals. The token runs those rules itself, so a transfer that fails one does not settle.

## Before and after [#before-and-after]

**Before 3.0:** the compliance team kept the policy in a document, and the asset team rebuilt the controls for each new token. A country added to the policy could be missed on one asset, a cap updated in one place and not another, and the only way to find out was to compare each token's settings against the document.

**With 3.0:** A Compliance manager builds the policy as a template in "Policy templates" and publishes it. The asset team picks it in Asset Designer, the token deploys with its own copy of the rules, and global controls set once at platform level apply to every token as well.

[Figure] From a draft policy template to the check on each ordinary transfer. A Compliance manager drafts a policy template with identity, country and limit rules and publishes it. In Asset Designer the Asset manager picks it, and the new token receives its own copy of the modules at creation. Each ordinary transfer is checked on-chain against the token's rules and then against the global controls that apply to every bound token. A Custodian's forced transfer or wallet recovery, the compliance bypass list and a fee-recipient exemption skip the check, and the token's Governance role can install or remove modules later. Labels: Draft policy template; Compliance manager; Identity, countries, limits; Published policy; Publish template; Publishing cannot be undone; Policy chosen; Asset Designer; The Asset manager picks it; Its own module copy; New token; Copied at creation; Checked on-chain; Ordinary transfer; Token rules, then global; System-wide rules; Global controls; Apply to every bound token; Skips the check; Custodian forced transfer or recovery, compliance bypass list, fee-recipient exemption; The token's Governance role can install or remove modules after creation.

A published policy template gives each new token its own copy of the rules, and each ordinary transfer is checked against them and the global controls.

## Let the asset team apply a policy the compliance team owns [#let-the-asset-team-apply-a-policy-the-compliance-team-owns]

The compliance team owns the policy, and the asset team applies it without making compliance decisions. A Compliance officer opens "Policy templates", picks the DALP Library template MAS Singapore - Capital Markets and chooses **Duplicate template**. The copy holds four controls: identity verification, a Singapore-only country allow list, a limit of 50 investors and a 180-day holding period. The officer adds the claim topics the programme requires and chooses "Publish template", which the Console asks the officer to confirm because it cannot be undone. An Asset manager creating a new fund reaches "Select compliance template", picks that policy, and the fund deploys with those four modules installed on its token. A transfer to an investor whose verified identity sits outside Singapore fails the allow list and does not settle.

![Policy templates table listing DALP Library templates with their jurisdictions and Published status](https://docs.settlemint.com/docs/screenshots/console-policy-templates.light.en.webp)

[Screenshot] Compliance officers browse the published policy templates and the jurisdiction each covers.

Only an administrator or a Compliance manager can create or publish a policy template, while an Asset manager can read and apply one. Two tokens created from the same published version start with identical rules. Each token keeps the copy it received at creation, so publishing a changed template does not change tokens already issued, and the token's Governance role can install or remove modules later.

## Start from nine regulatory templates [#start-from-nine-regulatory-templates]

The DALP Library ships nine current templates. Each includes identity verification, which requires a registered identity until your team adds the claim topics the programme needs.

| Template | What it sets |
| --- | --- |
| MiCA EU Standard | The 27 EU countries, a capital raise limit of 8,000,000 in the base currency per rolling 365 days |
| Reg D 506(b) - Private Placement | United States only, at most 2,000 investors |
| Reg D 506(c) - Accredited Only | United States only, transfer approvals valid for one day, accreditation once you add its claim topic |
| Reg CF - Crowdfunding | United States only, a capital raise limit of 5,000,000 in the base currency per rolling 365 days |
| UK FCA - Securities | United Kingdom only, at most 150 investors |
| MAS Singapore - Capital Markets | Singapore only, at most 50 investors, a 180-day holding period |
| Japan FSA - Crypto Assets | Japan only, transfer approvals valid for seven days |
| Australia ASIC + AUSTRAC - Digital Assets | Australia only, transfer approvals valid for seven days |
| UAE VARA + ADGM/DIFC - Virtual Assets | United Arab Emirates only, transfer approvals valid for seven days |

The library templates name no approval authority, so on a template with transfer approvals nobody can approve a transfer until your team names one. Library templates are read-only, so your team duplicates one and sets the trusted issuers, claim topics, approval authorities and limits its programme needs. Your counsel starts from a configuration that already reflects the regime instead of an empty form. The Reg D 506(b) template caps total holders and does not count non-accredited purchasers separately. A template configures platform controls, and choosing one does not make an offering compliant with the regime it is named after.

## Set a rule once for every token on the platform [#set-a-rule-once-for-every-token-on-the-platform]

Some rules apply across every instrument. **Global controls** in Settings apply compliance controls at platform level, and every token bound to the platform checks them after its own rules. A Compliance manager who must keep one country out of the whole book sets that rule once there, instead of editing each token's policy. Each module can also be scoped to the cases it governs, by country code, by identity claim topic or both.

A global control reaches tokens issued before it was set as well as new ones, which a per-token copy cannot do. Global controls apply to every bound token, so a rule meant for one programme belongs in that programme's template.

## Read the exact reason a transfer was refused [#read-the-exact-reason-a-transfer-was-refused]

When a mint or transfer fails compliance, the platform returns one of three typed reasons: the identity is not registered, the identity is not verified, or a named module blocked the operation. It says whether the sender or the recipient failed, and an unverified identity comes back with the claim topics that are missing, revoked or expired. An operator sees that the recipient lacks a current KYC claim and asks the verification issuer for it. Integrations read the same reasons, and each template with its modules, jurisdictions and draft or published status, through the Platform API and the CLI.

The reason tells your team what failed, and fixing it, such as issuing the missing claim, stays with the verification issuer.

## Name every path that skips the check [#name-every-path-that-skips-the-check]

Every module runs on-chain for each ordinary mint and transfer, and the paths around it are few and named. A Custodian's forced transfer or wallet recovery moves tokens without the transfer rules, by design. A transfer to an address on the compliance bypass list skips every module. The Compliance manager role maintains the list, and DALP's factories add the platform's own contracts to it when they deploy them. An approval authority can exempt a fee recipient from transfer approval, and the token's Governance role can remove a module. When a holder loses a wallet, a Custodian moves the balance to the new wallet, or, once an Identity manager has recorded the recovery, the new wallet claims it itself, and no module is consulted in either case.

A regulator who asks how a token could move outside its rules can be shown these paths, each tied to a role your institution grants. Who holds the Custodian, Identity manager, Governance and Compliance manager roles is therefore part of the policy.

## Upgrading [#upgrading]

Nothing to do. Tokens deployed before 3.0 keep their compliance modules unchanged. Choosing a template stays optional, because Asset Designer also accepts a manual configuration or no compliance at all, and it warns that the asset deploys without compliance controls. Templates built on the earlier module generation for older asset types carry the **Legacy** badge.

## Why it matters [#why-it-matters]

- **Banks:** the compliance team owns the policy, the asset team applies it, and each token that uses it enforces it on every ordinary transfer.
- **Exchanges, CSDs and market infrastructures:** A token arrives with its rules on-chain, and the active controls are readable through the API.
- **Regulators:** the rules a token enforces sit on the token, and every path around them is a named role.

## Next steps [#next-steps]

- [Apply policy templates →](https://docs.settlemint.com/docs/console/compliance/policy-templates)
- [Understand compliance policy →](https://docs.settlemint.com/docs/concepts/compliance-and-identity/compliance-policy)


# Custody & signing

Source: https://docs.settlemint.com/docs/changelog/dalp-3-0/custody
Sign every DALP transaction in your own custody provider's vault, while the platform builds, tracks and resumes it through approval to confirmation.

**Your custody provider keeps the keys and its approval policy, and DALP runs everything around the signature.** A bank's custody team does not move keys into a new platform, and its operations team still needs every transaction built, broadcast and tracked to the end. DALP 3.0 sends each signing request to the provider you configure and follows the transaction to confirmation.

Spotlight: Your provider's vault signs under its own policy, and DALP builds, routes and tracks the transaction

- Signing options: Five, including local signing
- External keys: Stay in the provider's vault
- Pending approvals: Held, then resumed
- Pre-sign screening: DFNS, off by default

DFNS, Fireblocks, Ripple Custody and Luna HSM sign inside their own systems. Local signing, where the platform manages the key, is the fifth option for deployments that accept it.

## Before and after [#before-and-after]

**Before 3.0:** custody teams keep keys in an HSM, an MPC wallet or a custodian's platform, under approval rules they have already signed off. A platform that wants its own keys creates a second key estate, a second approval process and a reconciliation between the two.

**With 3.0:** DALP prepares each transaction and sends the signing request to the provider you choose. The provider applies its quorum and sign-off rules inside its own vault. DALP waits for the decision, broadcasts the signed transaction or lets the provider broadcast it, and follows it to confirmation.

[Figure] DALP builds and tracks the transaction, and your custody provider signs it. DALP builds the signing request and applies its own authorisation and idempotency checks. The custody provider applies its approval rules and signs inside its vault. DALP or the provider broadcasts, and whichever broadcasts sets the nonce. DALP tracks the transaction to on-chain confirmation, and an approval resumes the send. With local signing, the platform manages the key and signs itself. Labels: Builds the request; DALP; Authorisation, idempotency; Signs in the vault; Custody provider; After its approval rules; DALP or the provider; Broadcast; Broadcaster sets the nonce; Confirms on-chain; DALP; Approvals resume the send; Local signing; The platform manages the key and signs itself,; with no external vault or provider policy.

DALP builds each transaction and sends the signing request to your custody provider, which signs in its vault, then follows the transaction to confirmation.

## Sign in the vault your custody team already runs [#sign-in-the-vault-your-custody-team-already-runs]

An Asset manager mints a bond in the Console, and the organisation signs through Fireblocks. DALP builds the mint, attaches a note naming the action and sends the request to the organisation's Fireblocks vault. The vault's Transaction Authorisation Policy requires two approvers, so the transaction waits in PENDING_APPROVAL while they review it in Fireblocks. When they approve, Fireblocks sends a signed webhook, DALP verifies it and the transaction continues, and DALP also polls in case the webhook does not arrive. The bond's supply changes once the mint confirms on-chain, and the transaction's recorded states show each step it passed.

![Add provider sheet listing the custody providers an organisation can connect, over the Custody page](https://docs.settlemint.com/docs/screenshots/console-organisation-custody-add-provider.light.en.webp)

[Screenshot] Your institution connects the custody provider that holds its keys.

The key and the approval policy stay where your custody team already reviews them, and DALP never holds an external provider's key. The provider enforces only the policies configured in it, and anyone who can act in DALP can still send it requests, so review platform roles alongside the vault's rules.

## Choose the provider that fits each deployment [#choose-the-provider-that-fits-each-deployment]

Every provider plugs into the same transaction path, so assets and workflows behave the same whichever one signs.

| Provider | Where the key lives | Who broadcasts |
| --- | --- | --- |
| DFNS | DFNS MPC wallet, under DFNS policies | DFNS, or DALP in a sign-only setup |
| Fireblocks | Fireblocks MPC vault, under its Transaction Authorisation Policy | Fireblocks |
| Ripple Custody | Ripple Custody, under its approval workflows | DALP, or Ripple Custody in provider-native mode |
| Luna HSM | A Luna hardware partition, reached over PKCS#11 | DALP |
| Local signing | The platform, which manages the key itself | DALP |

The table covers direct transactions. With smart wallets, every provider signs the operation and DALP's bundler submits it. Whoever broadcasts assigns the nonce: DALP when it broadcasts, the provider when it does. On an instance SettleMint operates, local signing keeps the key in a platform key store that SettleMint runs. A Luna partition can require an M-of-N quorum to activate before it signs. Ripple Custody needs an API credential set up in advance by your administrator. Changing provider does not move existing keys, so a wallet created under one provider stays with it.

## Show approvers what they are signing [#show-approvers-what-they-are-signing]

An approver who sees only a 32-byte hash cannot tell a mint from a transfer. DALP attaches a short description of each request: a note of up to 255 characters in Fireblocks and an external id of up to 50 characters in DFNS. The reviewer reads which action they are approving inside their own console. The signature still covers the transaction hash, so the label helps the reviewer and does not bind the payload.

## Screen a transfer before the key signs [#screen-a-transfer-before-the-key-signs]

For DFNS, the operator can turn on pre-sign screening for the deployment, with Chainalysis or Global Ledger. DALP then sets up a screening policy for each organisation it onboards, covering that organisation's tagged wallets. DFNS screens each signing request from those wallets and blocks the signature when the rule triggers. A transfer to an address the screening provider flags is refused at signing and never reaches the network. DALP also reads the native-gas balance of a managed custody wallet through the Platform API and the CLI, and DFNS can route gas through a fee-sponsor wallet.

Screening at the key stops a flagged payment before it exists on-chain, where it could not be recalled. It runs only on DFNS once the operator turns it on, it covers organisations onboarded after that and their tagged wallets, and what counts as a hit is the screening provider's call.

## Upgrading [#upgrading]

Nothing to do for the signing you already run: wallets and keys stay with the provider that holds them. DFNS screening is off by default. The operator turns it on in the deployment configuration, and it applies to organisations onboarded after that and to their tagged wallets.

## Why it matters [#why-it-matters]

- **Banks:** your custodian or HSM keeps the keys and the approval policy, and DALP runs the asset side around it.
- **Regulators:** with an external provider, key control and approval stay in that provider's system, separate from the platform that builds the transaction. Local signing keeps the key in the platform.
- **Partners:** A custody provider plugs into the same transaction path as every other, so DALP becomes the asset leg next to the custody you already run.

## Next steps [#next-steps]

- [Connect a custody provider →](https://docs.settlemint.com/docs/console/organisation-settings/custody)
- [Understand custody approval →](https://docs.settlemint.com/docs/concepts/custody-and-signing/custody-approval)


# Data feeds

Source: https://docs.settlemint.com/docs/changelog/dalp-3-0/data-feeds
Give each token its own price feed, signed by an issuer your registry trusts and refused on read once it is older than your staleness limit.

**Each token reads a price that a trusted issuer signed, and a read through the price resolver refuses one older than your staleness limit.** Fund share classes and bond tranches carry different values, and a shared price claim with no timestamp cannot tell this morning's figure from last month's. DALP 3.0 gives each token its own data feed, accepts only signed updates into it and refuses an old value when it is read.

Spotlight: A feed accepts only signed updates from trusted issuers, and the price resolver refuses a stale value

- Signing: EIP-712, checked on submit
- Who can submit: Issuers trusted for the topic
- Staleness limit: One per system, 24 hours by default
- Read interface: Chainlink-compatible

The feed contract checks the issuer, the signature, the nonce and the observation time before it stores a value. The price resolver checks the value's age each time an asset or an integration reads it.

## Before and after [#before-and-after]

**Before 3.0:** A token's price came from a base-price claim, one figure with no timestamp. A fund with two share classes that priced differently needed two instruments, and nothing on the chain showed who had set a value or when.

**With 3.0:** each token can carry its own feed. Every update names its issuer and its observation time, the feed rejects an update that fails its checks, and a value older than the system's staleness limit reverts when it is read.

[Figure] How a signed value reaches the asset that reads it. A trusted issuer signs a value, the feed contract checks the update before it stores the round, and the price resolver refuses a stale value on read, while a token with no feed falls back to its base-price claim. Labels: Issuer signs; EIP-712; Value, topic, time, nonce; Feed checks it; On submit; Trusted issuer, signature; Stored round; Per token; Latest, bounded or full; Price resolver; On read; Refuses a stale value; Asset or integration; Consumer; Acts on a fresh price; Base-price claim; No feed; Fallback, no age check.

A trusted issuer signs an update, the feed contract checks it before storing the round, and the price resolver refuses a stale value on read.

## Price each share class and tranche on its own [#price-each-share-class-and-tranche-on-its-own]

A feed is scoped to one token, so class A and class B of a fund, or two tranches of a bond, carry their own values in one instrument family. A Feeds manager opens "Data feeds" under "Organisation settings", selects **Create feed**, chooses "Asset-scoped" for the class A token and "Issuer-signed" as the source type, and picks a history mode: "Latest only", "Bounded" or "Full". After the daily valuation, the Feeds manager selects "Publish update" and enters the value. For a price, the organisation's identity is the trusted issuer, so the platform signs the update with the organisation's signer and submits it. The class B token gets its own feed and its own value, and an update to one never touches the other.

![Data feeds page listing each price feed with its latest value, freshness and source](https://docs.settlemint.com/docs/screenshots/console-organisation-data-feeds.light.en.webp)

[Screenshot] Your pricing team sees each price feed, how fresh it is and who signed it.

Share classes and tranches price separately without separate instruments, and each value on the chain carries who signed it and when it was observed. Each feed is created on its own, in the Console or through the Platform API.

## Accept a value only from an issuer your registry trusts [#accept-a-value-only-from-an-issuer-your-registry-trusts]

The feed contract runs its checks when an update is submitted and stores the value only when all of them pass. The topic and data format must match the feed. The issuer must be listed in the trusted-issuers registry for that topic and token, and the signature must come from a key that holds signing rights on the issuer's on-chain identity, from a plain wallet or a smart wallet. Each issuer's nonce must be the next in sequence. The optional deadline must not have passed. The observation time must be set, no earlier than the last accepted one and no further ahead than the feed's **Drift allowance**. The EIP-712 domain binds every signature to one feed contract, and so to one token.

A collateral agent whose identity is registered as a trusted issuer for a valuation topic publishes the collateral value of a loan token, and the platform signs the update with that user's own wallet. A colleague who is not listed for the topic sees "You must be a trusted issuer for this topic to publish updates." and nothing is stored. Someone who replays yesterday's signed update fails on the nonce.

An auditor reconstructs who signed which value over which token, and when, from the chain alone. The feed proves who signed a value and says nothing about whether the value is right, and every issuer the registry lists for the topic can submit.

## Refuse a stale price on every read through the resolver [#refuse-a-stale-price-on-every-read-through-the-resolver]

The price resolver applies one maximum age to every feed in the system, 24 hours by default. A wallet holding the Feeds manager role can change it with a direct call to the price resolver contract, to any non-zero value. When the valuation desk misses a day, the next read of that token's price through the resolver reverts instead of returning yesterday's figure, and the token's "Data feeds" tab shows the feed as **Stale**. Contracts that read prices through the resolver stop on the old value until a fresh one is published.

A missed update surfaces as a refusal instead of a wrong valuation. The limit is one value for the whole system, so a fast-moving exchange rate and a monthly valuation share it.

## Move legacy prices to feeds at your own pace [#move-legacy-prices-to-feeds-at-your-own-pace]

A token that priced from a base-price claim before 3.0 keeps that price after the upgrade, because the price resolver falls back to the claim when a token has no feed, and that fallback is on by default. A Feeds manager creates a feed for the bond and publishes the first value, and from then on the resolver reads the feed. Once every asset has a feed, a wallet holding the Feeds manager role can turn the fallback off with a direct call to the price resolver contract, and a token without a feed then refuses to price instead of reading a static claim.

The upgrade does not stop any asset from pricing on the day it lands. Until the fallback is off, a claim-priced token reads a static value with no age check.

## Read feeds with tools that already speak Chainlink [#read-feeds-with-tools-that-already-speak-chainlink]

Every feed implements the Chainlink-compatible aggregator interface, with `decimals`, `description`, `version`, `getRoundData` and `latestRoundData`, and a "Latest only" feed answers `latestRoundData` alone. So a contract or dashboard that reads that interface reads a DALP feed unchanged. A Feeds manager can also register an existing Chainlink-compatible feed with the **Chainlink (external)** source type, for example for a market rate, and "Create stable adapter" gives a feed a fixed address that keeps resolving through the feeds directory after the feed is replaced. Exchange rates refresh on one interval the operator sets for the deployment.

A direct read of a feed returns its latest value whatever its age, so apply your own age check or read through the resolver. An external feed skips the signature checks, so its values carry only the trust of the feed you register.

## Upgrading [#upgrading]

Price inputs move to per-token feeds. An asset that priced from a base-price claim keeps reading that claim after the upgrade, because claim fallback is on by default, but that price is static and gets no freshness check. The Platform API reads prices from feeds only, so such an asset shows no feed price there until it has one. Create a feed for each token that carries a price or a collateral value, publish its first value, then turn the fallback off with a call to the price resolver contract from a wallet that holds the Feeds manager role. [Data feeds](https://docs.settlemint.com/docs/console/organisation-settings/data-feeds) covers creating and publishing feeds.

## Why it matters [#why-it-matters]

- **Banks:** each valuation read from a feed names the issuer that signed it and the time it was observed.
- **Exchanges, CSDs and market infrastructures:** each share class or tranche prices from its own feed, readable through the Chainlink-compatible interface.
- **Regulators:** who signed each feed price, and when, is on the chain, and the price resolver refuses a value past the staleness limit.
- **Partners:** A valuation or market-data provider registered as a trusted issuer for a topic signs and submits its own updates.

## Next steps [#next-steps]

- [Create data feeds →](https://docs.settlemint.com/docs/console/organisation-settings/data-feeds)
- [Understand market data →](https://docs.settlemint.com/docs/concepts/records-and-evidence/market-data)


# Documentation

Source: https://docs.settlemint.com/docs/changelog/dalp-3-0/documentation
DALP 3.0 generates its API and error references from the platform, so a code your integration receives has its cause and fix in the docs.

**When your integration receives an error code, your developers find its cause and fix in the docs under the same DALP code and message the API returned.** A reference that someone updates by hand drifts from the product, and a developer then debugs against a page that no longer matches. DALP 3.0 generates its API and error references from the platform and gives each part of the platform one name across the docs.

Spotlight: The references come from the platform's own contract and error registry

- API reference: Served at /api/v2
- Platform API errors: 599 codes with fix and retryability
- Contract errors: Each revert with its cause
- Names: One per platform system

The interactive API reference and its OpenAPI specification come from the contract the platform runs on. Each error page lists the message, cause, fix and retryability the platform returns for that code.

## Before and after [#before-and-after]

**Before 3.0:** an integrator who received an error code searched pages written by hand, and a page could describe an older message or miss a code. Different pages used different names for the same part of the platform.

**With 3.0:** the API reference and the error references are generated from the platform, so a `DALP-` code in a response has an entry with the same message. The docs use one name for each of the platform's systems throughout.

[Figure] Where the DALP 3.0 API and error references come from. The API contract the platform serves produces the API reference, and the error registry produces the error references, so both match what an integration receives. Labels: API contract; Source; Served by the platform; API reference; Generated; /api/v2 and spec.json; Matches the API; Your integration; Codes, messages, shapes; Error registry; Source; Platform and contracts; Error references; Generated; Message, why, fix, retry.

The platform's API contract produces the API reference, and its error registry produces the error references, so both match what an integration receives.

## Find the fix for an error in the words the API used [#find-the-fix-for-an-error-in-the-words-the-api-used]

The interactive API reference at `/api/v2` and the OpenAPI specification at `/api/v2/spec.json` are generated from the API contract the platform serves, and the error references are generated from its error registry. The Platform API error reference lists 599 codes with their HTTP status, retryability and remediation. The contract error reference lists each on-chain revert with its message, why it happened, the suggested fix and whether a retry can succeed. A Developer whose transfer fails with DALP-4266, "Recipient not verified", finds the entry, reads that the recipient's identity lacks a required claim from a trusted issuer, and hands the case to the identity team instead of retrying. The message, why and fix are written for people, so code should branch on the `DALP-` code and the retryable flag.

![API keys page with links to the API reference and the OpenAPI document above a table of keys](https://docs.settlemint.com/docs/screenshots/console-my-account-api-keys.light.en.webp)

[Screenshot] An integrator reaches the API reference and the OpenAPI document from the API keys page.

## Read one name for each system across the docs [#read-one-name-for-each-system-across-the-docs]

The 3.0 docs gave each of the platform's systems one name, such as Asset Registry and Compliance & Identity, and used it on every page. A developer who meets a system in an error entry finds it under the same name in [the platform overview](https://docs.settlemint.com/docs/platform).

## Upgrading [#upgrading]

Nothing to do. Error codes you already handle keep their meaning, and the generated references follow the platform's contract and error registry.

## Why it matters [#why-it-matters]

- **Banks:** your developers resolve an integration error from a page that matches the response.
- **Partners:** your team builds against a reference generated from the same contract the platform serves.

## Next steps [#next-steps]

- [Browse the error code reference →](https://docs.settlemint.com/docs/api-reference/errors/error-code-reference)
- [Handle API errors →](https://docs.settlemint.com/docs/api-reference/errors/error-handling)
- [Understand the platform's systems →](https://docs.settlemint.com/docs/platform)


# Durable transactions

Source: https://docs.settlemint.com/docs/changelog/dalp-3-0/durable-transactions
Every DALP transaction moves through recorded states, so a crash, a timeout or a pending approval resumes from where it stopped.

**When a send stalls, your operations team knows where it stopped, and the platform picks it up from there.** A blockchain write passes through several steps, and when one fails without a record a team has two bad options: send again and risk moving value twice, or wait and leave a transfer in an unknown state. DALP 3.0 records every step of every transaction, so recovery starts from the last one that finished.

Spotlight: Each transaction is a recorded state machine, so recovery resumes from the last step that finished

- States: Eleven, each one recorded
- Nonce: Held while DALP broadcasts
- Reverts: Returned as named errors
- Retries spent: Parked for an operator

The engine writes each state before it moves on. A restart picks up at the recorded state, and a send that runs out of retries waits in DEAD_LETTER until an operator returns it to the queue.

## Before and after [#before-and-after]

**Before 3.0:** A write that timed out left the caller guessing whether it had reached the chain. A long token deployment could outlast the gateway timeout and return an error without the outcome. A revert came back as a hex string that someone had to decode against the contract before anyone knew which rule had refused the transfer.

**With 3.0:** every transaction carries a recorded state from RECEIVED to COMPLETED. A caller can take a status handle instead of holding the connection open, a revert returns the rule that fired, and stalled workflows show in "Platform status" before anyone goes looking.

[Figure] The recorded states a DALP transaction moves through. A transaction is recorded as RECEIVED and then QUEUED. In PREPARING, DALP holds the nonce when it broadcasts. SIGNING is skipped when the provider sends the transaction itself. BROADCASTING sends it, by DALP or the provider. CONFIRMING checks the receipt, and a receipt with a different hash fails the send as replaced. COMPLETED is terminal and releases the nonce. A send that has spent its retries waits in DEAD_LETTER until an operator returns it to QUEUED. A custody approval holds the send in PENDING_APPROVAL until the provider decides, and it fails if no decision arrives in time. Labels: QUEUED; Recorded; After RECEIVED; PREPARING; Nonce held; When DALP broadcasts; SIGNING; Key operation; Skipped if provider sends; BROADCASTING; Sent; By DALP or the provider; CONFIRMING; Receipt checked; Mismatch fails as replaced; COMPLETED; Terminal; Nonce released; DEAD_LETTER; Retries spent; Waits for an operator; PENDING_APPROVAL; Custody approval; Fails if no decision arrives in time.

Each transaction moves through recorded states to a terminal one, holds its nonce while DALP broadcasts and parks in DEAD_LETTER when retries run out.

## Pick up a send where it stopped [#pick-up-a-send-where-it-stopped]

Each transaction moves through eleven named states: RECEIVED, QUEUED, PREPARING, PENDING_APPROVAL, SIGNING, BROADCASTING and CONFIRMING, then one of COMPLETED, FAILED, CANCELLED or DEAD_LETTER. The engine records each state before it moves to the next. SIGNING is the key operation, and the engine skips it when the custody provider sends the transaction itself. A custody approval holds the send in PENDING_APPROVAL, before or after signing depending on the provider. An Asset manager mints through a DFNS wallet whose policy needs a sign-off, so the send waits in PENDING_APPROVAL. A rolling upgrade restarts the workflow service while it waits. On restart, the engine reads the recorded state and keeps waiting for the same approval instead of preparing a new transaction. When the approver signs off, the send moves to CONFIRMING and then COMPLETED, and the bond's supply changes once.

![Transactions page under Platform status listing each operation with its time, status and chain](https://docs.settlemint.com/docs/screenshots/console-organisation-platform-status-transactions.light.en.webp)

[Screenshot] An operator follows each transaction the platform sent and sees where it stands.

A DFNS or Ripple Custody approval fails after about 24 hours without a decision and a Fireblocks approval after about an hour, so an abandoned approval does not hold the account.

## Retry a send on the same nonce [#retry-a-send-on-the-same-nonce]

Each Ethereum account numbers its transactions with a nonce, and losing the link between an instruction and its nonce can cause a duplicate send or a gap. When DALP broadcasts, the engine allocates the nonce in PREPARING and holds it until the send reaches a terminal state. A retry of a live send reuses the same nonce, and sends from one account are queued so each nonce is allocated in order. When a receipt arrives, the engine checks that its hash matches the transaction it sent. A receipt from a different transaction at the same nonce fails the send as replaced, instead of letting it act on the other transaction's logs. A nonce error is recorded as NONCE_CONFLICT or NONCE_TOO_LOW on the failed send.

If the receipt does not appear within the polling limit, the engine marks the send as timed out, and reconciliation requeues it or moves it to DEAD_LETTER.

A retry cannot pay a counterparty twice for one instruction while DALP holds its nonce. When the custody provider broadcasts, the provider assigns the nonce, and DALP tracks the outcome instead.

## Read why a transfer reverted [#read-why-a-transfer-reverted]

When a send reverts on-chain, the engine decodes the reason against the error definitions of every DALP contract and returns the error by name with its parameters. An integration that tries to transfer from a frozen address, or to a holder whose identity claim has expired, receives the named error and the value that caused it. The operator sees which rule fired and can act on it, and each refused transfer leaves a structured record of when it was attempted and why it failed.

A revert from a contract outside DALP's error definitions comes back as its raw data.

## Wait for a long write without holding the connection open [#wait-for-a-long-write-without-holding-the-connection-open]

Some writes take longer than an HTTP connection stays open, such as a token deployment or a multi-step settlement. A Developer deploys a token and asks for an immediate answer, and receives a pending handle at once. The status read reports the deployment's recorded state, including after a reconnect, until it reaches COMPLETED. [Mutations and settlement](https://docs.settlemint.com/docs/api-reference/sdk/mutations) describes how a request chooses between the handle and a bounded wait.

A closed stream or a timed-out request says nothing about the outcome, so keep the handle until the status is terminal.

## Hand an operator the runs that need a decision [#hand-an-operator-the-runs-that-need-a-decision]

The engine watches every active workflow against two thresholds: how long it has waited, and how long since its state last changed. A run that is still making progress does not trigger, even after hours. When both thresholds cross, the workflows panel in **Platform status** reports that workflows are stalling. The Platform API and the CLI list every paused run, preview a resume as a dry run, and resume one run or a set of them. A send that has spent its retries waits in DEAD_LETTER, and an operator who has fixed the cause returns it to QUEUED through the same surface.

Your team hears about a stall from the platform before a counterparty notices it, and acts without access to the infrastructure. A step that did not finish runs again on resume, so any external call you add to a workflow must tolerate a repeat.

## Upgrading [#upgrading]

Nothing to do. Existing integrations keep working, and the `Prefer` headers are optional. Before a platform upgrade, drain waiting workflows as [Upgrades and migrations](https://docs.settlemint.com/docs/deployment/upgrades-migrations#drain-waiting-workflows-before-you-upgrade) describes. Each workflow worker drains its running work, for up to 30 minutes, before it stops, and a disruption budget keeps at least one worker ready during node maintenance.

## Why it matters [#why-it-matters]

- **Banks:** every transfer shows the recorded step it reached, including waiting for an approval or an operator.
- **Exchanges, CSDs and market infrastructures:** A settlement-critical send completes, fails with a named reason, or waits for an operator, and a retry while DALP holds the nonce does not send it twice.
- **Regulators:** A refused transfer carries the named rule that refused it, and an unrecognised contract error returns its raw data.

## Next steps [#next-steps]

- [Track async writes and settlement →](https://docs.settlemint.com/docs/api-reference/guides/idempotency-async-settlement)
- [Understand the transaction lifecycle →](https://docs.settlemint.com/docs/concepts/settlement/transaction-lifecycle)


# Gas optimisation

Source: https://docs.settlemint.com/docs/changelog/dalp-3-0/gas-optimization
DALP 3.0 removes repeated storage reads from the checks every transfer runs, with up to 40% less gas on the identity registry's registration check.

**The identity and compliance checks every regulated transfer runs cost less gas in 3.0, and the rules they enforce stay the same.** A transfer on a regulated token reads identity, compliance rules and supply limits from storage, and every read is paid for on every transfer as the book grows. DALP 3.0 removes repeated reads from those paths.

Spotlight: The checks a transfer runs read storage fewer times, and the rules they enforce stay the same

- Registration check: Up to 40% less gas
- List rules: Same cost at any list length
- Rolling limits: Running total, no history scan
- Proxies: Addresses fixed in code

The savings sit in the contract versions 3.0 ships: the identity registry, the per-token compliance modules, the issuance-volume and capital-raise limits, and the proxies 3.0 deploys. A system gets them once it runs those versions.

## Before and after [#before-and-after]

**Before 3.0:** A list rule scanned its entries one by one on each transfer, so the cost of a check grew as the programme added countries or investors. A rolling issuance limit summed the mint history for its window on each mint, and identity checks and proxies read the same storage more than once per call.

**With 3.0:** list rules look an entry up directly, rolling limits keep a running total, and identity checks and proxies read each value once.

[Figure] Where a mint or transfer reads less storage in 3.0. A mint or transfer passes the token proxy, the identity check, the list rules and the rolling limits, and each of these reads storage fewer times in 3.0 while the same rules decide the outcome. Labels: Mint or transfer; Holder; One call to the token; Fewer reads per call; Token proxy; Addresses fixed in code; Identity check; Identity registry; Registration: up to 40% less; One lookup; List rules; Same cost at any length; Running total; Rolling limits; No mint history replay; Same rules apply; Outcome; Same outcome as before.

A mint or transfer passes the proxy, the identity check, the list rules and the rolling limits, and each reads storage fewer times in 3.0.

## Check identity for less gas on every transfer [#check-identity-for-less-gas-on-every-transfer]

Every transfer asks the identity registry whether the recipient holds a registered, verified identity. The identity registry 3.0 ships answers that question without calling itself and resolves a lost-wallet check once instead of twice, and the per-token verification resolves the stored identity once. In our benchmark, run against the same registry before and after the upgrade with identical state, the registration check costs up to 40% less gas and returns the same answer. The claim-topic check that the identity verification rule runs on a regulated transfer costs about 8% less.

![Transfer tokens form for Capped Tech Shares with a recipient, an amount and a note on hidden ineligible participants](https://docs.settlemint.com/docs/screenshots/console-transfer-form.light.en.webp)

[Screenshot] The transfer form hides recipients the token's rules would refuse.

A book that settles many transfers a day pays less for the same identity check on each of them. The saving applies once your system runs the 3.0 identity registry, which an existing system receives through **System updates**.

## Keep list checks at the same cost as the list grows [#keep-list-checks-at-the-same-cost-as-the-list-grows]

Six compliance modules check list membership: the country allow and block lists, the identity allow and block lists, the address block list and transfer approval. In their per-token 3.0 versions, each keeps its entries in a set and looks an entry up directly. A Compliance officer who widens a bond's country allow list from five countries to fifty sees no change in what each transfer's check costs.

Per-transfer cost stays steady as a programme adds investors and countries. Adding or removing an entry costs more gas than before, and a module shared across tokens still scans its list.

## Enforce a rolling limit without replaying the mint history [#enforce-a-rolling-limit-without-replaying-the-mint-history]

The issuance-volume and capital-raise limit modules cap what a token can issue or raise over a rolling window. In 3.0 each keeps a running total for its window, updated on every mint and trimmed as old entries leave the window. When an Issuer runs a raise capped over a rolling 365 days, each new subscription checks the running total instead of summing a year of mints, and a mint pays a small fixed extra write to keep the total current.

The check costs the same on day 300 of a raise as on day one. The token supply limit module still reads its window day by day, so its check grows with the window length.

## Pay less overhead on every proxied call [#pay-less-overhead-on-every-proxied-call]

Every call to a token, a token feature or an identity passes through a proxy before it reaches the logic. The proxies 3.0 deploys hold the factory and registry addresses they need in their code instead of reading them from storage, and identity calls resolve their implementation in fewer steps.

The saving lands on every call, from mints and transfers to coupon claims. A proxy deployed before 3.0 keeps its earlier code, so this saving applies to proxies created from 3.0 onwards.

## Upgrading [#upgrading]

Nothing changes in what the rules decide. The savings come with the 3.0 contract versions, and [System updates](https://docs.settlemint.com/docs/console/organisation-settings/system-updates) shows the versions your system runs and applies the new ones. Review the new versions under your own change process before you apply them, because a gas change is a code change.

## Why it matters [#why-it-matters]

- **Banks:** A high-volume book pays less gas for the same identity and compliance checks once its system runs the 3.0 contracts.
- **Exchanges, CSDs and market infrastructures:** list checks cost the same at any length, so per-transfer cost stays steady as a programme grows.

## Next steps [#next-steps]

- [Review your system's contract versions →](https://docs.settlemint.com/docs/console/organisation-settings/system-updates)
- [Understand compliance modules →](https://docs.settlemint.com/docs/concepts/compliance-and-identity/compliance-modules)
- [Understand the contract set →](https://docs.settlemint.com/docs/platform/evm-contract-set)


# Identity & KYC

Source: https://docs.settlemint.com/docs/changelog/dalp-3-0/identity
Provider verdicts and reviewer approvals become on-chain claims the token checks at transfer, while documents and KYC history stay off chain.

**Your compliance team decides who is verified, and a token whose rules require a verified identity refuses an ordinary transfer to anyone who is not.** KYC verdicts usually sit in a provider's portal, get exported into a compliance database and reach the asset through a manual gate. DALP 3.0 turns each verdict into an on-chain claim the token reads at transfer, and keeps the documents and the review history off chain.

Spotlight: A trusted issuer's claim on the participant's on-chain identity is what the token checks

- Standards: ERC-734, ERC-735, ERC-3643
- Checked: On every ordinary transfer
- Documents: Off chain, encrypted on v2 upload
- KYC history: Every version kept

A compliance provider or a verification issuer attests a verdict as a claim on the participant's identity contract. The token's compliance rules read that claim and the registry of trusted issuers, so no document reaches the token. A custodian's forced transfer, a wallet recovery and an address on the compliance bypass list skip these checks.

## Before and after [#before-and-after]

**Before 3.0:** verdicts lived in each provider's portal. Someone exported them into a compliance database, the asset waited on an off-chain gate, and a lost wallet was recovered through a separate process with no link to the identity record.

**With 3.0:** A provider's verdict or a reviewer's approval becomes a claim on the participant's on-chain identity. The token reads the claim at transfer, each KYC submission keeps every version, and a lost wallet is recovered from the participant's record.

[Figure] How a verdict becomes the claim a token checks at transfer. A provider or reviewer reaches a verdict, a trusted issuer signs a claim onto the participant's on-chain identity, the transfer check reads that claim, and the KYC record and documents stay off chain. Labels: Provider or reviewer; Verdict; KYC, KYB, AML or approval; Trusted issuer signs; Claim issued; One claim per topic; Participant identity; On chain; Holds the topic claims; Transfer check; ERC-3643; Reads claim and issuer; Settles or reverts; Outcome; Forced transfer skips it; KYC record; Off chain; Versions and documents.

A verdict becomes a claim signed onto the participant's on-chain identity, the transfer check reads it, and the KYC record and documents stay off chain.

## Approve a participant once and let every token read the result [#approve-a-participant-once-and-let-every-token-read-the-result]

An Investor fills in KYC from their profile and selects **Submit for Review**. A Compliance officer opens the participant in "Participants", reads the submission as "KYC Version 1" with its "Timeline", and approves it, or requests changes with review notes. A Verification issuer then issues the verification, which is a claim signed onto the participant's on-chain identity for the topic it covers, such as KYC. When the investor later receives units of a bond whose rules require that topic, the transfer check finds the claim and the trusted issuer behind it, and the units settle. A transfer to a participant without the claim reverts with the reason, and the units stay with the sender.

![Participant page on the Verifications tab with the identity registration and a table of verifications](https://docs.settlemint.com/docs/screenshots/console-participant-verifications.light.en.webp)

[Screenshot] Your team sees which verifications a participant holds and that each one is active.

One verification serves every token that requires its topic, and the claim names the issuer that signed it. A verdict changes what a token allows only once the claim is issued or revoked on the chain. A custodian's forced transfer skips the check by design, and so does a transfer to an address a Compliance manager, or one of DALP's own factories, has put on the compliance bypass list.

## Bring verdicts in from the providers you already use [#bring-verdicts-in-from-the-providers-you-already-use]

Under **Compliance providers**, your team adds a provider, gives it its own issuer and registers that issuer as trusted for the topics it covers. 3.0 connects identity verification from Sumsub, Jumio, Onfido, Persona, Trulioo and Veriff, business verification from Middesk, Onfido and Persona, AML screening from Sumsub AML and ComplyAdvantage, and wallet monitoring from Sumsub KYT and Elliptic. When Onfido approves an applicant, the platform issues the claim from Onfido's issuer. When ComplyAdvantage raises an alert on a participant it monitors, the alert arrives by webhook against that participant's record, and an alert at or over the severity threshold your team set for that topic revokes the claim automatically, so the next transfer to them is refused.

Verdicts reach the token without an export and a reload, and the provider that reached each one is named on its claim. AML monitoring runs on the provider's schedule and reaches the token only through the claim, and each provider needs its own credentials.

## Show an auditor what was on file at the time [#show-an-auditor-what-was-on-file-at-the-time]

Each KYC submission is a numbered version. When an auditor asks about an investor who bought in March, the Compliance officer opens the participant's "KYC Data", then **Version History**, and reads which version was current then, when it was submitted and reviewed, the outcome and who reviewed it. A later change of address is a new version, and the version the March transfer relied on stays as it was. Documents uploaded through the Console or the v2 API are encrypted by the platform before storage, and none of them reach the chain.

The version history shows what was on file on any date. Documents uploaded through the v1 API are stored unencrypted, so upload through the Console or the v2 API.

## Recover a participant who lost their wallet [#recover-a-participant-who-lost-their-wallet]

When an investor loses the device that holds their wallet, an Identity manager opens the user's "Security" settings and selects **Recover Identity**. The wizard runs "Validation", an "Impact summary" of what the recovery does, "Execute recovery" and a "Summary". The platform creates a new wallet and a new on-chain identity, marks the lost wallet in the identity registry and links it to the replacement, revokes the user's sessions and resets their second factor. The wizard then recovers each token's balance to the new wallet through a custodian recovery, which needs the Custodian role on that token and skips the transfer rules, and the recovery is recorded.

The investor's holdings return to them without a burn and a re-issue, and the trail shows who recovered what. Claims do not move to the new identity, so each trusted issuer re-issues them before the participant is verified again.

## Take back an organisation identity someone deployed first [#take-back-an-organisation-identity-someone-deployed-first]

Someone can take over an organisation's on-chain identity by deploying a contract at its expected address before the organisation does, and the organisation would then act through an identity it does not control. A System manager who finds this before the system's initial setup completes calls the 3.0 recovery on the system contract. It deploys a replacement bound to the value that fixes the organisation's identity address and re-links the organisation to it in one transaction, so the organisation acts through the identity it controls. Reads show the corrected identity once the platform has read the re-link from the chain.

The recovery is a direct contract call with no Console screen, and it works only before the system's initial setup completes.

## Upgrading [#upgrading]

Nothing to do for existing participants. Identity claims stay on their identities, and tokens keep checking them. Documents uploaded through the v1 API stay unencrypted, so move document uploads to the Console or the v2 API.

## Why it matters [#why-it-matters]

- **Banks:** KYC stays with the providers and reviewers you choose, and the token enforces the outcome without holding a document.
- **Exchanges, CSDs and market infrastructures:** one verified identity is accepted by every token that requires its topics.
- **Regulators:** each claim names the trusted issuer that signed it, and every KYC version shows who reviewed it and when.

## Next steps [#next-steps]

- [Verify a participant →](https://docs.settlemint.com/docs/console/participants/verify-a-participant)
- [Configure trusted issuers →](https://docs.settlemint.com/docs/console/compliance/trusted-issuers)
- [Understand on-chain identity →](https://docs.settlemint.com/docs/concepts/compliance-and-identity/onchain-identity)


# DALP 3.0

Source: https://docs.settlemint.com/docs/changelog/dalp-3-0
Issue from reviewed instrument and compliance templates, sign in your own custody and resume every transaction from its last recorded step.

**Design each instrument from a reviewed template, enforce its compliance policy on every ordinary transfer, and keep signing in the custody you already run.**

A regulated institution spends most of an instrument's life servicing it after issue. DALP 3.0 starts each new instrument from templates your teams have reviewed and puts issuer-signed prices on the token. It keeps signing in the custody you already run and records every transaction step, so a stalled write resumes instead of going missing.

[Video] https://youtu.be/7SsW2AZUnMc. DALP 3.0 release overview. A walkthrough of DALP 3.0: design your own digital asset with compliance enforced on-chain, plus advanced accounts, custody, signed webhooks, platform monitoring, and a CLI with an MCP server for AI agents.. PT1M34S

Read [Breaking changes and migration](#breaking-changes-and-migration) before upgrading.

## Configure instruments and compliance [#configure-instruments-and-compliance]

The centre of 3.0 is asset design.

- [Start every new instrument from a reviewed template](https://docs.settlemint.com/docs/changelog/dalp-3-0/asset-templates). Twenty-four library templates across six asset classes give the issuer a reviewed design and leave only the terms of the issue to fill in.
- [Write a compliance policy once and reuse it](https://docs.settlemint.com/docs/changelog/dalp-3-0/compliance-templates). Your compliance team publishes identity, country, limit and approval rules as a template, and each new token that uses it copies the rules and checks them on every ordinary transfer through ERC-3643. ERC-3643 is the open Ethereum standard that requires a verified on-chain identity before a transfer settles.
- [Enforce verified KYC at transfer, keep documents off chain](https://docs.settlemint.com/docs/changelog/dalp-3-0/identity). The asset checks a verified on-chain claim, and the documents behind it stay off-chain.
- [Run fees, coupons, redemption and conversion on the token](https://docs.settlemint.com/docs/changelog/dalp-3-0/token-features). Fee, yield, redemption and conversion features attach to the live token and record what they do for each holder.
- [Price each token from a feed a trusted issuer signs](https://docs.settlemint.com/docs/changelog/dalp-3-0/data-feeds). Issuer-signed prices and values reach the chain, one feed per token.

## A platform built to run it [#a-platform-built-to-run-it]

3.0 also changes how the platform signs, records and tracks transactions.

- [Let operators act without funding their own gas](https://docs.settlemint.com/docs/changelog/dalp-3-0/advanced-accounts). Operators work through smart wallets, and a paymaster pays the gas for each operation the platform authorises.
- [Keep signing inside your own custody](https://docs.settlemint.com/docs/changelog/dalp-3-0/custody). DFNS, Fireblocks, Ripple Custody or Luna HSM keep the keys and their approval policy, local signing remains the fifth option, and DALP builds and tracks every transaction to confirmation.
- [Resume a stalled transaction from its last recorded step](https://docs.settlemint.com/docs/changelog/dalp-3-0/durable-transactions). Every write carries a recorded state, so a pending approval or a network timeout resumes from where it stopped.
- [Read your on-chain history as business records](https://docs.settlemint.com/docs/changelog/dalp-3-0/ledger-index). Ledger Data decodes each block into holdings, transfers, fees and redemptions, and rolls back and replays recent blocks when a chain reorganisation replaces them.
- [Pay less gas on identity, compliance and proxy checks](https://docs.settlemint.com/docs/changelog/dalp-3-0/gas-optimization). The 3.0 contract versions read storage fewer times and enforce the same rules, and an existing system gets them through System updates.

## Operate it from one place [#operate-it-from-one-place]

The release also makes the platform observable and reachable.

- [See platform health in one verdict](https://docs.settlemint.com/docs/changelog/dalp-3-0/monitoring). Platform status brings health into the Console in terms an operator can act on.
- [Receive signed events instead of polling the API](https://docs.settlemint.com/docs/changelog/dalp-3-0/webhooks). DALP posts signed identity registration and role events to your systems and records every delivery attempt.
- [Automate DALP operations from the CLI, SDK and MCP](https://docs.settlemint.com/docs/changelog/dalp-3-0/cli-api). The SDK, the CLI and its MCP server give scripts and AI agents the CLI's operations with typed errors. MCP, the Model Context Protocol, is an open standard that lets an agent discover and call those operations.
- [Filter, page and track settlement through the v2 API](https://docs.settlemint.com/docs/changelog/dalp-3-0/v2-api). Integrators get filtering, sorting, idempotency keys and control over whether a write waits for its result, while the v1 API keeps its request and response shapes.
- [Upgrade your on-chain components in one confirmed run](https://docs.settlemint.com/docs/changelog/dalp-3-0/self-managed-upgrade). The Console's System updates page lists every component that is behind before one run moves them all.
- [Answer a security review with enforced controls](https://docs.settlemint.com/docs/changelog/dalp-3-0/security). Authentication, key scopes, role checks, wallet codes and deployment controls are each enforced and documented.
- [Look up API and error references generated from the platform](https://docs.settlemint.com/docs/changelog/dalp-3-0/documentation). An error code your integration receives leads to its cause and fix under the same code and message, and each part of the platform has one name across the docs.

## Breaking changes and migration [#breaking-changes-and-migration]

- Run System updates after the platform moves. Open System updates and run **Upgrade all** so your on-chain components and the features on your tokens pick up the 3.0 behaviour. [Upgrade your on-chain components in one confirmed run](https://docs.settlemint.com/docs/changelog/dalp-3-0/self-managed-upgrade) covers the run.
- **Role checks apply to endpoints that had none.** A key or account that relied on an operation with no check at the API layer receives FORBIDDEN after the upgrade, so review grants before you upgrade.
- **Price inputs move to per-token feeds.** An asset that priced from a base-price claim keeps reading that claim after the upgrade, because claim fallback is on by default. That price stays static and gets no freshness check, and the Platform API reads prices from feeds only, so such an asset shows no feed price there until it has a feed. Create a feed for each token to receive signed, freshness-checked prices. A wallet holding the Feeds manager role can then turn the fallback off with a direct call to the price resolver contract. [Price each token from a feed a trusted issuer signs](https://docs.settlemint.com/docs/changelog/dalp-3-0/data-feeds) covers the feeds.
- **Platform status reads each panel from its own route.** The panels live under `/api/v2/platform-status/`: `data-freshness`, `transactions`, `platform-api`, `workflows` and `stat-cards`, with `history` as a separate read. The combined `/api/v2/platform-status/snapshot` read is deprecated and returns `Deprecation` and `Sunset` headers, so move clients to the per-panel routes.
- **Ledger Data builds its records on first start.** After the upgrade, Ledger Data builds its records from each network's history, so the first start takes longer on a long history.
- **The v1 API keeps its shapes in 3.0.** v1 routes keep their request and response shapes, and new capabilities land on v2.

## Smaller updates [#smaller-updates]

- Hide or unhide asset classes and instrument templates in Asset Designer, including per organisation, so each team sees what it issues.
- Search currencies by country and currency name.
- Resize the sidebar by dragging, with snap-to-collapse and a toggle shortcut.
- Real estate tokens can burn supply in their new contract version, and tokens already issued gain burn once they are upgraded to it.
- An XvP settlement swaps an asset for payment once every party approves. A settlement with a leg on another network also waits for its hashlock secret, which must be revealed before the cutoff date, and that leg settles as its own transaction on the other network, so the two legs are not one transaction.


# Ledger Data

Source: https://docs.settlemint.com/docs/changelog/dalp-3-0/ledger-index
Holdings, transfers, fees, yield and redemptions decoded from each block into records your team queries, with chain reorganisations rolled back.

**Your team answers audit, servicing and register questions from records the platform already holds.** A ledger network stores raw event logs, and turning them into holdings, fees and redemptions usually means a separate indexing service, contract mappings to maintain and a reconciliation step each time it drifts. DALP 3.0 builds that record into the platform as Ledger Data.

Spotlight: Ledger Data decodes each block as it arrives and stores the result as business records

- Decoding: As each block arrives
- Separate indexing stack: None to build or reconcile
- Chain reorganisations: Rolled back and replayed
- Past balances: From when Historical balances is on

Ledger Data follows every network your system runs on at the chain head, finds the DALP contracts it needs to follow, and writes typed records for holdings, transfers, fees, yield, redemptions and conversions. The Console and the Platform API read from those records.

## Before and after [#before-and-after]

**Before 3.0:** A team that needed balances at quarter end, a transfer history per holder or a fee total for a period ran its own indexing service beside the platform. Each contract change meant a new mapping, and after a backfill or a chain reorganisation someone had to check that the index still matched the chain and the books.

**With 3.0:** Ledger Data runs inside the platform. It decodes events as blocks arrive, rolls back and replays the blocks a chain reorganisation replaces, and serves the result to the Console and the Platform API.

[Figure] How Ledger Data turns each new block into stored records. Ledger Data compares each new block's hashes with the ones it stored, rolls back and replays a block the network replaced, decodes the events into typed records stored with each block's hash, and serves those records to the Console and the Platform API. Labels: Ledger network; Source; Blocks at the chain head; Decode the events; Ledger Data; Into typed records; Records and hashes; Stored together; Each block's hash is kept; Compare hashes; Every new block; Against the network; Roll back, replay; Replaced block; Back to the fork point; Console and API; Your team; Read the stored records.

Ledger Data decodes each block into typed records, replays blocks the network replaces and serves the result to the Console and the Platform API.

## Answer a register question from the record [#answer-a-register-question-from-the-record]

A token with the Historical balances feature records a balance checkpoint for every account on every transfer, and Ledger Data keeps those checkpoints by block. A Reporting officer preparing the quarter-end register for a bond opens the token's **Historical Balances** card, picks an "As of" date and opens the holders list as it stood then. An integration asks the Platform API for one holder's balance at a block number and receives the balance with the "Resolved block" and its "Block timestamp". Nothing moves: the read touches no asset and no cash, and the answer comes from checkpoints written when each transfer happened.

![Holders tab of an asset with a bar of each holder's share of the supply and a table of balances](https://docs.settlemint.com/docs/screenshots/console-holder-register.light.en.webp)

[Screenshot] Your reporting team sees who holds the supply and in what share.

The register at a record date comes from the platform instead of a replay of the chain or a spreadsheet from a separate index, so the figure your team reports is the one the token recorded. Past balances exist only for a token with the Historical balances feature, from the block where it was enabled, and the Console otherwise shows "Historical balances tracking is not enabled for this token."

## Keep servicing records without rebuilding them [#keep-servicing-records-without-rebuilding-them]

Ledger Data stores what each token feature did as its own records: fee collections, fee exemptions and AUM fee accruals, coupon periods and each holder's claims, maturity redemptions per holder, and conversions with the shares they issued. When an Issuer pays a coupon on a bond and later redeems it, each holder's claimed periods and each holder's redemption are lookups in those records, and the servicing team does not recalculate them from raw events at the end of the period.

A servicer, an auditor and an investor asking about the same payment read the same record. Ledger Data follows the contracts your DALP system deploys, so an asset issued outside DALP has no records here.

## Correct the record when the network replaces a block [#correct-the-record-when-the-network-replaces-a-block]

On a network where recent blocks can be replaced, a transfer can land in a block that later disappears. Ledger Data stores the hash of every block it processed inside the network's reorganisation window. When a new block's hashes disagree with the stored ones, it walks back to the fork point, the newest block both still agree on, reverses every change after it in exact reverse order and replays the canonical blocks forward. A holder whose incoming transfer the network dropped sees the balance return to what the network now holds, in the Console and through the Platform API.

A report does not carry a transfer the network no longer has. Each network has its own reorganisation window, which the operator can set, and a chain reorganisation deeper than that window is not fully corrected.

## Keep serving reads from the old records while an upgrade rebuilds [#keep-serving-reads-from-the-old-records-while-an-upgrade-rebuilds]

When a release changes how events are recorded, Ledger Data rebuilds a new copy of its records in the background and swaps it in when the copy is complete, so the copy in service keeps answering while the new one catches up. An operator who upgrades a deployment does not schedule a read outage for the rebuild.

Reads keep coming from the copy in service while a rebuild runs. An organisation onboarding that opts in waits with a retryable response until the rebuild catches up.

## Upgrading [#upgrading]

Ledger Data builds its records from each network's history after the upgrade, so the first start takes longer on a long history. Before go-live, review each network's reorganisation window as [Network configuration](https://docs.settlemint.com/docs/deployment/networks) describes. A token gains past balances from the block where its Historical balances feature is enabled. [Index rebuild after an upgrade](https://docs.settlemint.com/docs/deployment/runbooks/index-rebuild-after-upgrade) covers what to expect while a rebuild runs.

## Why it matters [#why-it-matters]

- **Banks:** register, fee and redemption questions are answered from records the platform holds, without a second indexing system to run and reconcile.
- **Exchanges, CSDs and market infrastructures:** holder balances at a record date come from checkpoints written on every transfer, with replaced blocks rolled back.
- **Regulators:** past holdings are read from recorded checkpoints tied to a block number and its timestamp, corrected for replaced blocks within each network's reorganisation window.

## Next steps [#next-steps]

- [Configure your networks →](https://docs.settlemint.com/docs/deployment/networks)
- [Plan for a rebuild after an upgrade →](https://docs.settlemint.com/docs/deployment/runbooks/index-rebuild-after-upgrade)
- [Understand Ledger Data →](https://docs.settlemint.com/docs/concepts/records-and-evidence/ledger-data)


# Monitoring

Source: https://docs.settlemint.com/docs/changelog/dalp-3-0/monitoring
Platform status gives operators one verdict from API, transaction, workflow and data-freshness signals, and shows the signal behind it.

**Your operations team sees in the Console whether the platform is healthy, and which signal says so.** Before an operator releases a redemption batch or opens a subscription window, they need to know the platform can carry it. DALP 3.0 puts that answer on one Platform status page, so nobody has to read infrastructure graphs first.

Spotlight: Four panels each judge one signal, and the worst panel sets the overall verdict

- Panels: Four, each with its own verdict
- Verdicts: Operational, Degraded, Outage, No data
- Block stall: Degraded at 130 s, outage at 190 s
- History: Worst state per day, 30 days

Data freshness, Transactions, Platform API and Workflows each read one signal and give a verdict. The page header shows the worst of the four, and a history strip shows the worst state of each completed day.

## Before and after [#before-and-after]

**Before 3.0:** whether the platform could carry a settlement run was a question for whoever had access to the infrastructure dashboards. An operator had to find the right graph for each network, read raw RPC and request metrics, and decide alone whether a slow chain or an error spike should stop the work.

With 3.0, **Platform status** under "Organisation settings" shows one overall verdict and four panels in operational terms, such as "Transactions are slow or partially failing." Each panel names the signal that set its verdict, and integrations read the same verdicts through the Platform API.

[Figure] Four Platform status panels roll up into one overall verdict. Data freshness, Transactions, Platform API and Workflows each set their own verdict from one signal, and the overall verdict is the worst of the four. Labels: Data freshness; Ledger Data; Chains in sync; Transactions; Network RPC; Block age, latency; Platform API; Requests per day; 5xx and 4xx rates; Workflows; Runs per day; Stalls per 1,000; Overall verdict; Platform status header; The worst panel verdict wins.

Four panels each judge one signal, and the worst of the four sets the overall verdict in the page header.

## Decide whether to release the batch from one page [#decide-whether-to-release-the-batch-from-one-page]

An operator who holds the system administrator or system manager role opens **Platform status** and reads the header first: "All systems operational", "Degraded service", "Service disruption" or "No data yet". Below it, each panel shows its verdict, its figures and one line on what the verdict means for operations. Five metric cards add the day's figures, including "Success rate (24h)" and "Completion time", the time within which 95% of successful workflows finished.

![Platform status page reading All systems operational with a panel each for data freshness, transactions, the Platform API, workflows and webhooks](https://docs.settlemint.com/docs/screenshots/console-organisation-platform-status.light.en.webp)

[Screenshot] An operator reads one verdict on platform health, with a panel for each service behind it.

An operator with the system manager role is about to release a coupon payment run for a bond. The header reads "Degraded service". The Transactions panel says "Transactions are slow or partially failing", while Platform API and Workflows are operational. The operator holds the run, so no payment instruction is sent onto a network that is not producing blocks on time, and releases it once the panel returns to operational. When the day closes, the history strip records it as degraded, so the reason for the delay is visible later.

The person who decides whether to proceed reads the reason for the verdict in the same place as the decision. A panel that fails to load shows an error and a **Retry** button. The verdict covers these four signals only, so a custody provider or a bank system outside DALP does not appear in it.

## Tell a stalled network from a quiet one [#tell-a-stalled-network-from-a-quiet-one]

For each network, the Transactions panel reads RPC health. A network whose newest block is 130 seconds old turns degraded, and one whose newest block is 190 seconds old is an outage. An RPC response slower than 1,500 milliseconds turns degraded, a response slower than 5,000 milliseconds is an outage, and so is a failed RPC call. A network set to produce blocks only on demand skips the block-age check, because an idle chain of that kind is not a stalled one. The Data freshness panel shows how many chains Ledger Data, the platform's record of on-chain history, has in sync and how many sync errors it recorded in the last 24 hours. While Ledger Data is rebuilding, the Data freshness panel stays Operational, so check the sync count before releasing a run after an upgrade.

A bank runs DALP on a private network that produces a block every few seconds, and block production stops. The panel turns degraded after the 130-second line and reaches outage after 190 seconds, while Platform API stays operational, so the operator knows the network is the problem. The [runbook for stalled ledger data](https://docs.settlemint.com/docs/deployment/runbooks/ledger-indexing-stalled) separates a stalled chain from one that is still catching up.

A slow or stopped chain shows as a named state before transfers queue up behind it. A status changes only after three matching samples taken ten seconds apart, so a stall shows about 20 to 30 seconds after it crosses a line.

## Keep a quiet day from raising a false alarm [#keep-a-quiet-day-from-raising-a-false-alarm]

The Platform API panel judges the last 24 hours of requests. With 500 or more requests that day, a 5xx rate of 5% or more is an outage, and a 5xx rate of 1% or a 4xx rate of 50% is degraded. Below 500 requests, 50 or more 5xx responses make an outage, so one failed call on a quiet day does not turn the panel red. A day with no requests shows no data instead of a guess. Refused sign-ins and permission errors do not count as 4xx errors, so unauthenticated probes do not degrade the verdict. The Workflows panel judges stalled runs against throughput: 20 stalls per 1,000 completions is degraded, and 50 is an outage.

A Developer's integration starts sending malformed requests overnight. By morning, half of the day's 2,000 requests return 4xx, and the Platform API panel reads degraded while the other panels stay operational. The operator sees that the platform is serving correctly and that one client needs fixing.

A verdict that follows volume keeps on-call staff from chasing a single error, and it still flags a quiet day that fails in earnest. Below 500 requests a day, the API panel shows operational or outage and never degraded.

## Feed the same verdicts to your own tooling [#feed-the-same-verdicts-to-your-own-tooling]

Each panel has its own read under `/api/v2/platform-status/`: `data-freshness`, `transactions`, `platform-api`, `workflows` and `stat-cards`. A separate `history` read returns the worst state per service for each day, 30 days by default. The CLI exposes the same reads through `dalp platform-status`. A Developer adds the transactions read to the bank's own operations dashboard, so the verdict the Console shows is the one the bank's tooling records.

Your operations centre and the Console report the same verdict from the same thresholds. Platform status sends no notifications, so paging still runs through your monitoring backend, fed by the platform's telemetry export that [deployment observability](https://docs.settlemint.com/docs/deployment/observability) describes.

## Upgrading [#upgrading]

Nothing to do. Platform status is new in 3.0 and reads from data the platform already collects. Only holders of the system administrator or system manager role can read it, so grant one of those roles to the people who need the page. An integration that reads `/api/v2/platform-status/snapshot` keeps working, but that read is deprecated and returns `Deprecation` and `Sunset` headers, so move it to the per-panel reads.

## Why it matters [#why-it-matters]

- **Banks:** your operations team decides whether to run a payment or redemption from a verdict it can read, inside the platform it already uses.
- **Exchanges, CSDs and market infrastructures:** A network whose newest block is 130 seconds old shows as Degraded, and at 190 seconds as an outage, so an operator can hold a batch.
- **Partners:** the same verdicts reach your monitoring tools through the Platform API and the CLI.

## Next steps [#next-steps]

- [Monitor platform status in the Console →](https://docs.settlemint.com/docs/console/organisation-settings/platform-status)
- [Export platform telemetry →](https://docs.settlemint.com/docs/deployment/observability)
- [Understand platform health →](https://docs.settlemint.com/docs/concepts/operating/platform-health)


# Security & deployment

Source: https://docs.settlemint.com/docs/changelog/dalp-3-0/security
DALP 3.0 enforces how callers sign in, which role may act and when a key may sign, and documents how the platform deploys.

**Your security team can trace each call, each asset action and each signature to a control the platform enforces.** A bank's review of a platform that moves regulated assets asks for evidence, and a written policy that the code does not enforce fails it. DALP 3.0 refuses a call that lacks the right credential or role, and a signed-in user's signing request needs a wallet code.

Spotlight: Each endpoint declares the authentication and role it needs, and a signed-in user's signing request needs a wallet code

- API keys: Read or read-write scope
- Role mismatch: Refused before the handler runs
- Before signing: PIN, secret code or one-time code
- Images: One setting points them at your mirror

Platform administration and on-chain asset roles are separate grants. One person can hold both, so a review checks each person's effective permissions.

## Before and after [#before-and-after]

**Before 3.0:** A security review had to infer from configuration which operations were guarded, and some API operations had no check at the API layer. Reviewers asked how a script's key differed from a person's session, and the answer depended on how a deployment was set up.

**With 3.0:** each endpoint declares the authentication and role it needs, and the platform checks them before the operation runs. API keys carry a scope, signing requests from a signed-in user need a wallet code, and the deployment pages describe the network, image and secret controls for your cluster.

[Figure] The checks a DALP request passes before a transaction is signed. A request is resolved to a session or an API key, checked for key scope and for the on-chain role it needs, and a signing request from a signed-in user must also carry a wallet PIN, secret code or one-time code, which API-key sessions skip. Labels: Session or key; Caller; Cookie or scoped API key; Read or write; Scope; Read-only key: no writes; Role check; Role; FORBIDDEN on a mismatch; Wallet check; Signing request; PIN, secret code or OTP; Transaction; Result; Sent for signing; Recent sign-in; Account actions; Within five minutes; API-key sessions skip the wallet check; Limit; A read-write key carries signing authority.

A request resolves to a session or an API key, then passes the key scope and role checks, and a signing request from a signed-in user also needs a wallet code.

## Show a reviewer how each call is authenticated [#show-a-reviewer-how-each-call-is-authenticated]

The platform resolves each request to a signed-in session or to an API key before any handler runs. An API key carries a read or a read-write scope, and a read-only key that attempts a write is refused with "This API key is read-only and cannot perform write operations". API keys are refused on the internal endpoint the Console uses, so a key works only through the REST API.

![Account Security page with the Approve transactions section: a Transaction PIN, a Transaction code and recovery codes](https://docs.settlemint.com/docs/screenshots/console-my-account-security.light.en.webp)

[Screenshot] Each person chooses how to confirm their own transactions.

A Reporting officer's export job runs on a read-only key. A change to the job adds a call that would update a record, and the platform refuses it at the first request, so nothing changes. The officer's team fixes the job before it reaches production.

A reviewer can see which credentials may write by reading their scope instead of tracing every job. A read-write key acts with the full permissions of the account that created it, so give automated jobs their own accounts and the narrowest roles they need.

## Keep asset authority with the people granted it [#keep-asset-authority-with-the-people-granted-it]

On-chain roles are granted per system and per asset, and the platform checks the role an endpoint declares before the operation runs. A mismatch returns a structured FORBIDDEN response that names the refusal. Platform administration covers users, organisations, integrations and system settings, and it carries no on-chain asset role.

A Compliance officer who holds the compliance manager role tries to mint units of a bond from a script. The platform refuses the call because minting needs the supply management role on that token, so the supply does not change. A colleague who holds the supply management role on that bond performs the mint instead.

Your institution can show which named role allowed each action on an asset. The system manager role can upgrade the contracts behind every instrument, so grant it under the same controls as an asset role.

## Ask for a wallet code before a key signs [#ask-for-a-wallet-code-before-a-key-signs]

Each request that signs a transaction for a signed-in user must carry a valid wallet secret: a PIN, one of the user's secret recovery codes, or a one-time code from an authenticator. When your deployment connects multi-factor checks from its identity provider, wallet verification can use them instead. A wrong code returns FORBIDDEN. Five failed attempts lock that code type for 15 minutes on the API instance that counted them, and the count resets when that instance restarts, so a gateway rate limit stays part of the control. Account security actions, such as revoking sessions, need a sign-in within the last five minutes.

An Asset manager approves a coupon payment in the Console, and the Console asks for the manager's PIN before the transaction is signed. A colleague who finds the manager's unlocked laptop cannot sign without that PIN.

A stolen session cannot sign a transaction in the Console without the wallet code, but it can create a read-write API key, and API-key calls skip the wallet check, so review API key creation alongside sessions.

## Deploy behind your own network controls [#deploy-behind-your-own-network-controls]

The deployment charts carry these controls:

- NetworkPolicy templates for ingress and egress on the Console and the RPC gateway, off by default for clusters that do not enforce NetworkPolicy.
- One ingress policy on the workflow service, on by default, that lets only its cleanup job reach its health port.
- One registry setting that points every first-party image at your internal mirror, so an air-gapped install needs no edit per chart.
- Source address ranges that limit who the RPC gateway's load balancer accepts traffic from.
- An OpenShift profile that runs each container as non-root, without privilege escalation and with all Linux capabilities dropped.

A bank's platform team installs DALP in a cluster with no internet route. They mirror the images, point the registry setting at the mirror, turn on the network policies their cluster enforces, and limit the RPC gateway to the bank's own address ranges. The images come from the mirror, and the reviewer reads each control from the rendered manifests.

Your infrastructure team keeps the controls it already runs, and the review reads them from configuration it owns. Network policies for the Console and the RPC gateway stay off until your team turns them on, so a production review should confirm they are enabled.

## Upgrading [#upgrading]

Review existing grants before you upgrade. Endpoints that had no check at the API layer now refuse callers without the declared role, so a key or account that relied on an unguarded call may receive FORBIDDEN after the upgrade. Existing sessions, API keys and role assignments carry forward. [Values and secrets](https://docs.settlemint.com/docs/deployment/install/values-secrets) and [hosting and access](https://docs.settlemint.com/docs/deployment/hosting-and-access) name the registry, network and secret settings.

## Why it matters [#why-it-matters]

- **Banks:** each control this page describes is enforced in the platform and traceable to a role, a key scope or a cluster setting your team owns.
- **Regulators:** each action on an asset needs a named role, a signed-in user's signing request needs a wallet code, and a read-write API key signs without one, so key creation is a reviewed control.
- **Partners:** an integration's key carries an explicit scope, so a read-only connection cannot change state.

## Next steps [#next-steps]

- [Review the security and compliance posture →](https://docs.settlemint.com/docs/deployment/security-compliance-posture)
- [Assign platform and on-chain roles →](https://docs.settlemint.com/docs/console/organisation-settings/admins-and-roles)
- [Understand role grants →](https://docs.settlemint.com/docs/concepts/compliance-and-identity/role-grant)


# Self-managed upgrades

Source: https://docs.settlemint.com/docs/changelog/dalp-3-0/self-managed-upgrade
System updates compares your on-chain components with the latest release and upgrades them in one confirmed run, at the same addresses.

**Your system manager decides when your system's factories, features and compliance modules move to a new release, and every token keeps its address.** A tokenised book sits on many contracts, and bringing each one up to date by hand is slow and can stop half done. DALP 3.0 shows every component that is behind on one Console page and upgrades them in one run that your system manager confirms.

Spotlight: System updates moves each component to the release the directory names, while its address stays the same

- Latest versions: Recorded in the on-chain directory
- Run by: System manager or system admin
- Statuses: Up to date, New version, New, Unknown
- Addresses: Kept, code behind them changes

The page compares the factories, features and compliance modules your system runs with the latest implementations in the directory. One confirmed run applies the changes, and each proxy keeps its address while the code behind it moves.

## Before and after [#before-and-after]

**Before 3.0:** moving a deployment to a new release meant upgrading components one by one. Nobody had a single list of which contracts were behind, and a partial upgrade left some tokens on old behaviour without anyone noticing.

With 3.0, **System updates** lists every component with its status, shows how many tokens each change affects, and upgrades them all with "Upgrade all". Addresses, balances and holder records stay where they are.

[Figure] How System updates brings on-chain components to the latest release. System updates compares each component with the on-chain directory, a system manager confirms, and the upgrade run moves each proxy to new code at the same address, keeping completed steps if a later one fails. Labels: On-chain directory; Latest releases; Written by its administrator role; Compare; System updates; Up to date, New version,; New or Unknown; Review, confirm; System manager; Types CONFIRM to start; Run the steps; Upgrade system; Migrations run to the end; Administrator-only steps wait; Same addresses; Result; New code, same proxy; Balances and history kept; Permit feature; Outside the run; Deployed directly, not; upgraded in place; Completed steps stay; If a step fails; Retry upgrade skips the steps already applied.

System updates compares each component with the on-chain directory, and one confirmed run moves each proxy to new code at the same address.

## See which components are behind before you change anything [#see-which-components-are-behind-before-you-change-anything]

The on-chain directory records the latest implementation of each platform component, and holders of its directory administrator role write to it. **System updates** lists each factory, feature and compliance module in your system with its status: "Up to date", "New version", "New" or "Unknown". "Details" shows the implementation your organisation runs next to the one the DALP release provides, for both the factory and the deployed instance, and states how many tokens the change affects. A summary line counts the components that need an upgrade.

![System updates page with the count of components that need an upgrade and a table of components with their state](https://docs.settlemint.com/docs/screenshots/console-organisation-system-updates.light.en.webp)

[Screenshot] Your administrator sees which components are behind and upgrades them in one run.

A Platform administrator who holds the system manager role opens **System updates** after the platform itself has moved to 3.0. The page shows the bond factory as "New version" and counts the bonds it affects. Before anything changes on-chain, the administrator knows which contracts move and which instruments sit behind them, and can share that list with the asset owners.

Your team reviews an upgrade from a list that comes from the chain, so the review starts from what is deployed. A component the page cannot compare shows as "Unknown", and someone has to check it by hand.

## Upgrade the whole system in one confirmed run [#upgrade-the-whole-system-in-one-confirmed-run]

**Upgrade all** starts one run for every component that is behind. The confirmation step warns which contracts need a data migration that cannot be interrupted once it starts, and notes that completed migration steps cannot be rolled back. The system manager types CONFIRM, and the page follows the run step by step.

The system manager starts the run, and a token migration fails halfway because the network drops a transaction. The page reports "Upgrade failed" and states that the steps already applied remain in effect. The manager presses **Retry upgrade**, the completed steps are skipped, and the run finishes the rest. Every bond keeps its address, so the investors' wallets, the explorer links and the integrations that hold those addresses work as before.

Some updates need a system administrator, and the page says so with a note that some pending updates need a system administrator, until one runs them. Smart wallets and on-chain identities read their code from the on-chain directory. A change by the directory administrator, the party that deployed the directory, reaches every wallet and identity without this run.

## Decide which components join the run [#decide-which-components-join-the-run]

Experimental components stay out of the run by default. **Include experimental components** is a switch on the page, off unless someone turns it on, and the page says when experimental components are available. The run also installs or updates the supporting components the platform needs, which the page does not list one by one.

An operator who wants to evaluate an experimental component on a test system turns the switch on there and leaves it off on the production system. Production then moves only to released components.

The permit feature is deployed directly rather than behind a proxy, so the run does not upgrade it in place.

## Upgrading [#upgrading]

After the platform moves to 3.0, open "System updates" and run **Upgrade all** so your on-chain components and the features attached to your tokens pick up the 3.0 contract behaviour. The run needs the system manager or system administrator role, and some steps need a system administrator. Plan it like any change to live contracts: data migrations cannot be interrupted or rolled back, and a failed run keeps the steps it completed. On an instance SettleMint operates, the operator of your deployment decides with you when the run happens. [Upgrades and migrations](https://docs.settlemint.com/docs/deployment/upgrades-migrations) covers the platform upgrade that comes first.

## Why it matters [#why-it-matters]

- **Banks:** your institution decides, with the operator of your deployment, when your system's factories, features and compliance modules change, and a named role confirms each run.
- **Exchanges, CSDs and market infrastructures:** token addresses stay fixed through an upgrade, so settlement instructions and integrations that hold them keep working.
- **Regulators:** the list of what changed comes from the chain, and the run states which steps were applied.

## Next steps [#next-steps]

- [Open System updates in the Console →](https://docs.settlemint.com/docs/console/organisation-settings/system-updates)
- [Plan a platform upgrade →](https://docs.settlemint.com/docs/deployment/upgrades-migrations)
- [Understand system versions →](https://docs.settlemint.com/docs/platform/system-version)


# Token features

Source: https://docs.settlemint.com/docs/changelog/dalp-3-0/token-features
Charge fees, pay coupons, redeem at maturity and convert on the token itself, with terms checked before a feature attaches and a record per holder.

**Your servicing team runs fees, coupons, redemption and conversion on the token, and every payment leaves a record per holder.** A token that only moves balances leaves fees, coupons and redemptions to spreadsheets and payment files that someone reconciles each period. DALP 3.0 gives those jobs to token features with their own rules and their own records.

Spotlight: Each feature checks its terms when it attaches and records what it does for each holder

- Fees: Four types, each with a frozen-rate option
- Coupon claims: Up to 104 periods per claim
- Redemption: At face value after maturity
- Conversion discount: 0 to 9,999 basis points

A token feature is behaviour you attach to an asset. The platform refuses terms that would fail on the chain or clash with another feature, and Ledger Data records each fee collection, coupon claim, redemption and conversion.

## Before and after [#before-and-after]

**Before 3.0:** A fee was charged without a collection record anyone could query, coupons were calculated off chain and paid by payment file, redemption was a burn followed by a separate payment, and conversion terms went unchecked until a holder tried to convert.

**With 3.0:** fees record each collection, and transaction fee accounting records each exempt address. Holders claim coupons from a treasury the contract checks, redeem at face value after maturity and convert on terms the platform checked when the feature attached.

[Figure] How token features service a bond from issue to redemption. The platform checks feature terms when they attach, transfers pay fees, holders claim coupons from a funded treasury, the bond matures and holders redeem at face value, and Ledger Data records each step per holder. Labels: Terms checked; Attach; Clashes refused up front; Transfers pay fees; Fees; Each collection recorded; Holders claim coupons; Yield; From a funded treasury; Bond matures; Maturity; On its date, or early; Holders redeem; Redemption; Paid at face value; Per-holder records; Ledger Data; Fees, claims, redemptions.

A feature attaches with its terms checked, the token charges fees and pays coupons from a funded treasury, and holders redeem at face value after maturity.

## Charge a fee and show who paid it [#charge-a-fee-and-show-who-paid-it]

A token can carry four fee features. A transaction fee takes a percentage of each mint, burn and transfer and pays it to the fee recipient in the same transaction. Transaction fee accounting records the same percentage without moving value, so finance settles it later. An AUM fee accrues an annual rate pro rata on the token's time-weighted supply and is collected by minting new units to the recipient, which dilutes every holder in proportion. An external transaction fee charges a flat amount per mint, burn and transfer in a second token. Each fee rejects a zero-address recipient, an AUM fee rejects a rate over 10,000 basis points, and transaction fee accounting keeps exemptions per address. The Console now calls the AUM fee the management fee.

![Fund page with its Actions menu open, listing the management fee actions among the token actions](https://docs.settlemint.com/docs/screenshots/console-fee-actions-menu.light.en.webp)

[Screenshot] An issuer sets, freezes and collects a fund's fee from the token's own actions.

The Issuer of a fund holds the token's governance role, sets the AUM fee recipient to the manager's wallet and selects **Freeze AUM fee rate**. Each collection mints units to the manager, and Ledger Data records each accrual and collection, so the question "which collections were made, at what rate and to whom" has one answer.

A frozen rate cannot change on that feature. Governance can still replace or remove a frozen fee feature, and a system upgrade changes the code behind it.

## Pay coupons that holders claim from a checked treasury [#pay-coupons-that-holders-claim-from-a-checked-treasury]

Fixed treasury yield carries a bond's coupon terms. The governance role sets the rate, the interval, the start and end dates, the denomination asset and the treasury, and the rate, interval and dates stay fixed for the life of the feature. At the end of each period every holder is owed a coupon on the balance held at that moment. Asset Designer refuses a yield start date on or after the maturity date.

An Investor who has held the bond for three years opens **Claim yield**. One claim settles up to 104 periods, and the Console repeats the claim until the holder is caught up, up to 20 rounds, verifying the wallet for each round. The denomination asset moves from the treasury to the holder's wallet, and each settled period is recorded for that holder with its amount, block and transaction.

A holder with a long backlog is paid in full across several claims instead of hitting the block gas limit. A claim fails while the treasury lacks the balance or has not approved the feature to spend it, and nothing is paid until the Issuer funds it.

## Redeem at maturity against a treasury the platform checks [#redeem-at-maturity-against-a-treasury-the-platform-checks]

When the maturity date arrives, the holder of the governance role selects **Mature bond**, which needs enough denomination asset in place. A holder then selects "Redeem at maturity" and enters the "Amount to redeem". Before the redemption goes out, the Console checks the treasury and stops the holder when a wallet treasury has not approved the spend or holds none of the denomination asset. The contract burns the units and pays the holder's own wallet face value for the units burned, rounded down, and the redemption is recorded for that holder. A transaction fee on burns reduces the units that are paid out.

The redemption register is a lookup per holder, and a shortfall stops the redemption with the holder's units unburned. A holder of the emergency role can **Trigger early maturity** with no check that the treasury can pay everyone, and if the treasury is then short, holders who redeem first are paid first.

## Convert a holding on terms the platform checked [#convert-a-holding-on-terms-the-platform-checked]

A convertible instrument pairs two features. The conversion feature on the convertible token holds the terms, and a conversion minter on the target token issues new shares only for conversions it trusts. When the feature attaches or is replaced, the platform checks that the discount is between 0 and 9,999 basis points, so the effective price never reaches zero, and that a window does not start after it ends. Partial conversion is off by default, and a minimum conversion amount, zero by default, stops dust conversions. On a token that marks converted balances instead of burning them, a partial conversion is refused while a yield feature is attached.

A noteholder selects **Convert** while the window is open. When the terms include interest, the platform settles the holder's interest backlog in up to 10 rounds first, then converts, and the target token mints the new shares. If interest is still settling after those rounds, the platform answers 409 with DALP-9080, which is retryable. The holder submits the conversion again and each attempt settles a further batch. Once the window closes, no conversion is possible until governance sets a new window.

The terms a holder converts on are the terms that were checked. A custodian can **Force Convert** a holder's units while the window is open, without the holder asking.

## Refuse a feature that would clash or fail [#refuse-a-feature-that-would-clash-or-fail]

Before the platform queues any transaction, it blocks an attach that would fail on the chain and refuses an attach or a replace that would put two features in conflict. An Asset manager who adds transaction fee accounting to a token that already charges a transaction fee is refused before anything reaches the chain. A maturity redemption whose denomination asset is the token itself is refused when it attaches.

These checks run when a feature attaches or is replaced, so a feature attached before 3.0 is not checked again.

## Upgrading [#upgrading]

A fee, yield, redemption or conversion feature reads its code from its feature factory on every call. A feature attached before 3.0 therefore runs the 3.0 behaviour once a system manager applies the 3.0 feature factories in [System updates](https://docs.settlemint.com/docs/console/organisation-settings/system-updates), with no re-attach. The permit feature, which lets a holder approve a spend with a signature, is deployed directly. A permit feature attached under DALP 2.1 keeps its earlier form, which accepts only a key signature, so a holder whose account is a smart wallet cannot sign a permit for that token.

## Why it matters [#why-it-matters]

- **Banks:** coupons and redemptions pay from a treasury the platform checks first, with a record for each holder.
- **Exchanges, CSDs and market infrastructures:** fees, coupons, maturity and conversion run on the live token, and each one is recorded per holder.
- **Regulators:** each fee collection, coupon claim and redemption can be traced to a holder, a block and a transaction.

## Next steps [#next-steps]

- [Manage fees →](https://docs.settlemint.com/docs/console/asset-management/manage/fee-administration)
- [Run yield and maturity →](https://docs.settlemint.com/docs/console/asset-management/manage/yield-maturity)
- [Understand token features →](https://docs.settlemint.com/docs/concepts/modeling-assets/token-features)


# v2 API

Source: https://docs.settlemint.com/docs/changelog/dalp-3-0/v2-api
The v2 API at /api/v2 lets integrations filter, sort and page lists, track a write through settlement and retry it safely where its route allows.

**Your integration asks the platform for exactly the records it needs and knows what happened to every write it sends.** A core banking system that pulls whole lists, or resends a payment instruction after a dropped connection, risks slow reconciliation and duplicate movements. DALP 3.0 adds a typed v2 API with filters, sorting, paging and a choice between waiting for settlement and tracking it.

Spotlight: One query style for every list, and one settlement contract for every write

- Base path: /api/v2
- Page size: 50 by default, 200 at most
- Settlement wait: 5 to 99 seconds, or poll
- v1: Shapes unchanged in 3.0

List endpoints share the JSON:API query style for filters, sorting and paging. A write returns its settled result or a status URL, depending on how long the caller asks the platform to wait.

## Before and after [#before-and-after]

**Before 3.0:** the v1 API returned whole sets with no structured filtering, so an integration fetched more than it needed and filtered on its own side. A write that timed out left the caller unsure whether it had reached the chain, and a blind resend could submit the instruction twice.

**With 3.0:** the v2 API filters and sorts on the server, pages with links, and lets each write either wait for settlement or return a status URL at once. On routes whose contract documents replay, a retry with the same idempotency key returns the original result instead of a second instruction.

[Figure] How a v2 mutation settles when the caller asks the platform to wait. A mutation is queued and returns 200 OK with the settled result if it settles within the wait budget, or 202 Accepted with a status URL to poll if the budget runs out, and a retry with the same idempotency key on a replay-safe route returns the original result. Labels: POST mutation; Integration; Idempotency-Key, Prefer; Queued; Platform; Runs in the background; 200 OK; Settled within N; Settled result inline; 202 Accepted; Budget elapsed; Status URL to poll; Poll status; Integration; Until a terminal state; Retry, same key; Uncertain reply; On replay-safe routes.

A mutation returns 200 with the settled result within its wait or 202 with a status URL, and a retry with the same idempotency key returns the original result.

## Ask for the records you need [#ask-for-the-records-you-need]

List endpoints take filters in JSON:API bracket notation, such as `filter[name]=Treasury`. An operator goes in a second bracket: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `iLike` and `notILike` for a case-insensitive match, `between`, `inArray`, `notInArray`, `isEmpty` and `isNotEmpty`. Sort with `sort=-createdAt`, or with `sortBy` and `sortDirection`, and use one of the two forms per request. Each resource accepts only the sort fields its contract lists, and the contract rejects any other.

![Activity page with a chart of events over time, filters for the event, the asset and the time range, and a table of events](https://docs.settlemint.com/docs/screenshots/console-activity-events.light.en.webp)

[Screenshot] The Activity page narrows a long event history to the time range, event or asset you need.

A Developer building the bank's register sync asks for the 50 most recent tokens whose name matches Treasury:

```http
GET /api/v2/tokens?filter[name]=Treasury&sort=-createdAt&page[limit]=50&page[offset]=0
```

The response carries the page and the links to the next one, so the sync walks the set without computing offsets. The register gets only the rows it needs, and a nightly reconciliation runs on a smaller data set. An `inArray` or `notInArray` filter uses the first 100 values and ignores the rest, so a longer exclusion list must be split across requests.

## Choose whether a write waits for settlement [#choose-whether-a-write-waits-for-settlement]

A blockchain write takes seconds to settle, and longer when the network is busy. A v2 transaction write is queued and returns `202 Accepted` with a status URL. Send `Prefer: wait=N` to have the platform hold the response for up to N seconds, clamped to between 5 and 99, and `Prefer: respond-async` for the status URL at once. The `Preference-Applied` response header echoes the directives the platform honoured.

A Developer's payment job issues a mint with `Prefer: wait=10`. On a quiet network the mint settles in four seconds, and the job receives `200 OK` with the settled result and books it straight away. On a busy afternoon the same call returns `202 Accepted` after ten seconds, and the job polls the status URL until the mint completes. In both cases the token supply changes once, because the platform queues the mint once whether or not the job waits. The 3.0 TypeScript SDK sends `Prefer: wait=99` on every mutation unless you set your own `Prefer` header.

A slow block no longer ties up a connection or loses a result, because the work runs whether or not the caller waits. A wait changes only how the result is delivered, so a `202` is not a failure and the job must keep the status URL until the operation finishes.

## Retry a write after an uncertain reply [#retry-a-write-after-an-uncertain-reply]

A lost reply is the case an idempotency key covers. Send an `Idempotency-Key` header with a mutation, and on a route whose contract documents replay, the platform runs the instruction once and returns the original result to a retry with the same key. Generate one key per instruction, store it with your own job id, and reuse it only to retry that same request.

A Developer's job sends a transfer and the connection drops before the reply. The job resends the same body with the same key, and the platform answers with the transfer it already accepted, so the holder receives the units once. [Idempotency and async settlement](https://docs.settlemint.com/docs/api-reference/guides/idempotency-async-settlement) gives the request contract and how long a key is kept.

A key protects only routes whose contract documents replay, so check the route before you rely on a retry.

## Choose how each transaction is sent [#choose-how-each-transaction-is-sent]

`X-Executor` selects how a transaction is sent, `eoa` from the account's own key address or `smart-wallet` from its smart wallet, and leaving it out uses the organisation's default. `X-Participant` names the participant the request acts as, in `pp_<uuid>` form. v2 errors from the platform carry the same envelope as the SDK and the CLI: a stable `DALP-` id, a category, a retryable flag, a message, a `why` and a `fix`.

A Developer's organisation sends transactions from smart wallets by default, with the gas sponsored. One maintenance script must send from the account's own key address, so it sets `X-Executor: eoa` on those calls, and the rest of the integration keeps the organisation's default. When a call is refused, the script reads the category and the retryable flag to decide whether to stop or try again.

An integration picks the sending path per call without a second credential. In 3.0, `X-Participant` must name the participant of the session itself, so one key acts as one participant.

## Upgrading [#upgrading]

Nothing to do. In 3.0 the v1 API at `/api/v1` keeps its request and response shapes, and its specification remains at `/api/v1/spec.json`. `/api` redirects to `/api/v2`, where the interactive reference and the OpenAPI specification are served. Build new integrations on v2, and check the v2 reference for each v1 operation you rely on before you move it. v2 becomes stable only from 3.2, which removes some v2 operations published before it, so read [3.2 compatibility](https://docs.settlemint.com/docs/changelog/dalp-3-2#compatibility) before you build on these shapes.

## Why it matters [#why-it-matters]

- **Banks:** your core systems pull only the records they reconcile, and a lost reply does not turn into a second payment instruction on replay-safe routes.
- **Exchanges, CSDs and market infrastructures:** each write either returns its settled result or a status URL you can track to a terminal state.
- **Partners:** your product reads DALP data in one query style and branches on each refusal by its fields.

## Next steps [#next-steps]

- [Track async writes and settlement →](https://docs.settlemint.com/docs/api-reference/guides/idempotency-async-settlement)
- [Page through collections →](https://docs.settlemint.com/docs/api-reference/guides/pagination)
- [Understand the transaction queue →](https://docs.settlemint.com/docs/concepts/settlement/transaction-queue)


# Webhooks

Source: https://docs.settlemint.com/docs/changelog/dalp-3-0/webhooks
Signed delivery of identity registration and role events, with retries for up to three days, a delivery history and replay by block range.

**Your systems hear about each identity registration and role change as it reaches a block, signed, without asking the API on a timer.** Polling means a scheduled job, empty responses and an interval that is either too slow for the back office or too heavy for the API. DALP 3.0 pushes signed events to the URLs you register and records every delivery attempt. Delivery is at least once, and after an outage you replay the deliveries that failed.

Spotlight: DALP signs each event, retries a failed delivery for up to three days and keeps every attempt on record

- Signing: HMAC-SHA256, Standard Webhooks
- Live event types: Identity, role granted, role revoked
- Retries: Backoff for up to three days
- After 30 failures: URL off until reactivated

3.0 sends three event types: identity registration, role granted and role revoked. Each arrives once a block includes it, and a chain reorganisation that drops the block sends a retraction, so your records follow the on-chain outcome.

## Before and after [#before-and-after]

**Before 3.0:** an integration polled the API, handled empty responses, tuned an interval and built its own retry and deduplication. A role revoked on chain reached the back office only at the next poll, and a chain reorganisation that dropped a change went unnoticed.

**With 3.0:** DALP posts each subscribed event to your URL, signed, retries a failed delivery on a growing backoff for up to three days, and shows every attempt in the endpoint's delivery history.

[Figure] How DALP delivers a webhook and what happens when your URL fails. An identity registration or role change on chain is signed and posted to your URL, a failed delivery is retried with backoff for up to three days, thirty failures in a row switch the URL off, and an operator reactivates it and replays the events recorded for it. Labels: On-chain event; Ledger Data; Identity and role changes; Signed; HMAC-SHA256; Id, timestamp and body; POST to your URL; Delivery; A 2xx marks it delivered; Retry with backoff; Retryable failure; For up to three days; URL switched off; After 30 failures; New events not queued; Reactivate, replay; Operator; Re-send recorded events.

DALP signs and posts each event, retries failures for up to three days, and switches a failing URL off until an operator reactivates it and replays.

## Receive identity and role changes as they happen [#receive-identity-and-role-changes-as-they-happen]

3.0 sends three live event types: an identity registration, a role granted and a role revoked. Each arrives once a block includes the change, and a chain reorganisation that drops the block sends a retraction of the same event.

![Create endpoint sheet over the Webhooks page with an endpoint URL, a display name and the lifecycle-state subscriptions](https://docs.settlemint.com/docs/screenshots/console-webhooks-create-endpoint.light.en.webp)

[Screenshot] A developer chooses which event states an endpoint receives.

A Developer who is an owner or administrator of the organisation selects **Create webhook endpoint**, enters an "Endpoint URL", which must start with https, and saves the signing secret the Console shows once. Under "Subscriptions" the Developer ticks `*.provisional`, the state these three events arrive in. When a Compliance officer registers an investor's identity, the back office receives the registration with the identity's address and the block it landed in, and opens the investor's account. When a member's role is revoked, the back office receives the role and the transaction that revoked it, looks up the member's wallet from that transaction and closes the member's access in its own systems. If a chain reorganisation drops either block, a retraction tells the back office to undo the step.

The event reference also lists transfer, issuance and freeze events, and 3.0 does not send them. Transfers, issuance, approvals and custody movements still need a read from the Platform API. A new endpoint subscribes to final, retracted and recalled events by default, and none of the three live events arrives in those states, so tick `*.provisional` when you create the endpoint.

## Prove an event came from DALP before acting on it [#prove-an-event-came-from-dalp-before-acting-on-it]

Each delivery follows the Standard Webhooks scheme. It carries a `webhook-id` header equal to the event's `evt_id`, a `webhook-timestamp` header and a `webhook-signature` header holding an HMAC-SHA256 signature over the id, the timestamp and the raw body. The TypeScript SDK checks all of it in one call and returns the typed event, or a failure code of `TIMESTAMP_SKEW`, `SECRET_MISMATCH` or `BODY_HASH_MISMATCH`. It refuses a timestamp more than five minutes away, and DALP signs a delayed retry again so it arrives inside that window.

```typescript
import { verifyWebhook } from "@settlemint/dalp-sdk";

export function handleDalpWebhook(rawBody: string, headers: Headers, secrets: string[]) {
  // During a secret rotation, pass the new and the previous secret.
  const result = verifyWebhook({ rawBody, headers, secret: secrets });
  if (!result.ok) {
    throw new Error(`Webhook verification failed: ${result.code}`);
  }
  // Delivery is at least once, so key processing on result.event.evt_id.
  return result.event;
}
```

When the Developer selects **Rotate secret**, the old and the new secret both stay valid for 24 hours, so receivers move to the new secret without missing an event. A forged or altered request fails verification and the handler refuses it. The signature proves DALP sent the event, and because delivery is at least once, the handler still keys its processing on `evt_id`.

## Re-send failed deliveries after an outage [#re-send-failed-deliveries-after-an-outage]

A 2xx response marks a delivery as delivered. A server error, a timeout, a 408 or a 429 is retried on a backoff that starts at about 30 seconds and grows with each attempt, for up to three days. Any other 4xx is not retried, because the same request would fail again. Each attempt appears in the delivery history with its status, failure class and HTTP status, and a single delivery can be retried by hand.

When the back office's receiver is down over a weekend, 30 failed deliveries in a row switch the URL off, and the "Circuit breaker" card shows "Disabled".

On Monday the Developer fixes the receiver, selects "Send test event", which still reaches a URL that is off, and confirms it verifies. The Developer then selects **Reactivate manually**, types the endpoint's name and replays the weekend's block range from the CLI or the Platform API, which re-sends the deliveries that failed before the URL switched off.

The delivery history shows which events failed and why, and a replay re-sends them with a fresh signature. Events that happen while a URL is off are not recorded for it, so a replay cannot bring them back, and the back office reads those changes from the Platform API.

## Choose how much personal data leaves DALP [#choose-how-much-personal-data-leaves-dalp]

A new endpoint receives thin payloads: DALP strips the account's wallet address, the sender's address and the country code from each event before it signs it. An integration that needs the full subject state uses **Switch to fat events**, which asks the Developer to confirm every field that leaves DALP and to type the organisation's name before "Acknowledge, switch to fat events".

Personal data leaves only after a named person at your organisation confirmed each field. The switch to fat payloads cannot be undone from the Console, so the receiving system falls under your data-protection controls from then on.

## Upgrading [#upgrading]

Nothing to do. Webhooks are an additional delivery channel, and integrations that poll the Platform API keep working as before.

## Why it matters [#why-it-matters]

- **Banks:** your core systems learn of each identity registration and role change from a signed message they verify before acting.
- **Exchanges, CSDs and market infrastructures:** A role grant or identity registration that a chain reorganisation drops reaches your systems as its own retraction event.
- **Partners:** an integration subscribes to the identity and role events it needs and replays the deliveries that failed during downtime.

## Next steps [#next-steps]

- [Receive DALP webhooks →](https://docs.settlemint.com/docs/api-reference/guides/webhooks)
- [Manage webhook endpoints →](https://docs.settlemint.com/docs/console/organisation-settings/webhooks)
- [Understand webhook delivery →](https://docs.settlemint.com/docs/concepts/events-out/webhook-delivery)


# Air-gapped deployment

Source: https://docs.settlemint.com/docs/changelog/dalp-3-1/air-gapped-deployment
A Job you enable inside your cluster deploys the DALP contracts with a key you hold, pulls images from your mirror and resumes where it stopped.

**An institution that runs DALP in a restricted or air-gapped cluster now deploys the DALP smart contracts from inside that cluster, with a key it holds.** A security review of such a cluster questions any deploy step that needs outbound internet or a key someone else keeps. 3.1 runs the contract deployment as a step inside the cluster you operate, from images in your own mirror, and on an instance SettleMint operates, SettleMint runs that step and holds the deployer key.

Spotlight: A Job you switch on inside your own cluster deploys the contracts, signing with a key you hold

- Default: Off until the operator enables it
- Deployer key: Kubernetes Secret you create
- Key check: Stops on the wrong address
- Re-runs: Resume from the last step

Before it sends a transaction, the Job checks that its key signs as the deployer address you recorded. It writes each completed step to a journal on a volume the upgrade keeps.

## Before and after [#before-and-after]

**Before 3.1:** DALP 3.0 shipped with no step in its deployment charts that deployed the DALP contracts from inside the cluster. A restricted cluster needed the contracts deployed from a machine with wider network access, and that exception was the part its security review questioned.

**With 3.1:** the operator turns the contract deployment Job on in the deployment's values. The Job runs inside the cluster from an image in the operator's own mirror, reads the deployer key at runtime, checks it, deploys the contracts through the network node the operator names and records every step in a journal. The platform's services trust object storage whose certificate comes from the operator's private certificate authority.

[Figure] The contract deployer runs inside the operator's cluster. The contract deployer Job runs inside the operator's cluster. It pulls its image from the operator's image mirror and reads the deployer key from a Kubernetes Secret the operator creates. It is off until the operator enables it, checks the key against the expected deployer address, has no role bindings and resumes from its journal. It records each step in a deploy journal on a kept volume and deploys the contracts through the operator's network node endpoint. Separately, the Platform API and the workflow engine mount the operator's CA certificate and trust object storage behind that private certificate authority. Labels: Images; KEY; Steps; Deploys; Trusts your CA; Image mirror; Your registry; Every image, including; the deployer; Deployer key; Your secrets; Kubernetes Secret; you create; Contract deployer; In your cluster; Off until you enable it; Checks the key against; the expected address; No role bindings; Resumes from journal; Deploy journal; Kept volume; Records each step; so a re-run resumes; Node endpoint; Your network; Receives the contract; transactions; API and workflows; Platform; Mount your CA; Object storage; Behind your CA; Uploads and exports.

A Job inside the operator's cluster deploys the contracts with the operator's key and resumes from its journal, while platform services trust the operator's CA.

## Deploy the contracts with a key that stays with you [#deploy-the-contracts-with-a-key-that-stays-with-you]

The Job reads the deployer key at runtime from a Kubernetes Secret the operator creates, or from the reference architecture's secrets manager where the operator wires it in. Without either, it fails closed and deploys nothing. An operator's key ceremony produces the deployer key and records its public address. The operator stores the key in a Kubernetes Secret, enters the address as the expected deployer in the values, names the network node endpoint and turns the Job on. At the next upgrade the Job starts, reads the key and checks the address the key signs as against the expected one. A mismatch stops the run before any transaction leaves the cluster, so a key that does not match the recorded address cannot deploy. The deployer key stays under the institution's own key ceremony and secret store, and the vendor does not need it to deploy. The Job checks the key against the address in the values, so that address has to come from the key ceremony's own record.

![Factories page listing each token and add-on factory with its kind, type and address](https://docs.settlemint.com/docs/screenshots/console-organisation-factories.light.en.webp)

[Screenshot] Your operator sees every token and add-on factory the deployed system offers.

## Show a security reviewer a short, fixed list of what the Job can reach [#show-a-security-reviewer-a-short-fixed-list-of-what-the-job-can-reach]

The Job's service account has no Kubernetes role bindings, and its account token is mounted only when an external secrets manager has to authenticate the pod. An optional egress policy limits the Job's network access to DNS and the endpoints the operator lists. A platform security reviewer reading the rendered chart sees an account that grants nothing, a journal volume and, with the egress policy on, a pod that reaches only the network node and the secrets manager. With the egress policy on and no endpoints listed, the Job reaches only DNS and cannot deploy, so the operator lists the node endpoint and the secrets manager.

## Resume an interrupted deployment without a second contract set [#resume-an-interrupted-deployment-without-a-second-contract-set]

The Job writes each completed step to a deployment journal on a volume that upgrades and uninstalls leave in place. A deployment stops halfway because the network node endpoint went down. The operator restores the endpoint and runs the upgrade again. The new Job reads the journal, skips the steps that already finished and continues from the last completed one, and a Job that finds a finished deployment in its journal changes nothing. The institution ends with one contract set at one set of addresses. Run one upgrade at a time while a deployment is in flight, and back up the journal volume, because a re-run without it deploys a new contract set at new addresses.

## Keep images and storage on your own network [#keep-images-and-storage-on-your-own-network]

One global registry setting points the images the charts reference, including the contract deployer, at the operator's own mirror. For object storage signed by a private certificate authority, the chart stores the operator's CA certificate as a Secret, or reuses one the operator already manages, and the OpenShift values show how the Platform API and the workflow engine mount it. A bank whose S3-compatible store inside its data centre uses a certificate from the bank's internal authority keeps uploads and exports on that store. When something needs diagnosis, an administrator exports a redacted [debug bundle](https://docs.settlemint.com/docs/deployment/observability#the-admin-debug-bundle) instead of granting shell access to the cluster. The CA trust is off until the operator supplies a certificate, the mirror has to hold every image the charts reference, and calls to a custody or KYC provider outside the network still leave it.

## Upgrading [#upgrading]

Nothing to do. The contract deployment Job and the private CA trust are off by default, and a deployment that enables neither runs as before. Both first shipped in the 3.0 patch releases, the CA trust in 3.0.6 and the Job in 3.0.9, and both are part of 3.1. Leave the Job off on a deployment whose contracts already exist: without a journal from an earlier run, the Job deploys a new contract set. [Install on OpenShift](https://docs.settlemint.com/docs/deployment/install/openshift) shows the values for both.

## Why it matters [#why-it-matters]

- **Banks:** the contracts deploy from inside a cluster with no outbound route, and the deployer key comes from your own key ceremony and secret store.
- **Exchanges, CSDs and market infrastructures:** the contracts deploy from inside your network, and the journal shows every step that ran.
- **Regulators:** the deployer key, the images and object storage stay on the network the institution runs, and the chart values show where each comes from.

## Next steps [#next-steps]

- [Install on OpenShift →](https://docs.settlemint.com/docs/deployment/install/openshift)
- [Hosting and access →](https://docs.settlemint.com/docs/deployment/hosting-and-access)
- [Understand a DALP instance →](https://docs.settlemint.com/docs/platform/dalp-instance)


# DALP 3.1

Source: https://docs.settlemint.com/docs/changelog/dalp-3-1
Each organisation signs through its own custodian, the contracts deploy from inside your cluster, and admins run long-term operations through the API.

**Each organisation can sign through the custodian it contracted, the contracts can deploy from inside a restricted cluster, and platform admins archive organisations and reset a stuck onboarding through the API.**

Part of running an instrument for years is running the platform under it: who holds the keys, where the contracts come from, and what happens to a dormant organisation or a user stuck halfway through onboarding. DALP 3.1, released on 12 August 2026, puts those decisions with your institution on the deployment you choose, your own cluster or an instance SettleMint operates. On an instance SettleMint operates, SettleMint runs the cluster and the contract deployment. 3.1 is for institutions that host several organisations on one deployment or run DALP inside a restricted network, and for the teams that support them. These notes cover everything shipped since 3.0, including the 3.0.1 to 3.0.11 patch releases. Before you upgrade, read [Compatibility](#compatibility). From 3.1.12 new Fireblocks vault accounts enrol in Fireblocks Gas Station, and from 3.1.19 the original asset families can be created only after the operator turns legacy asset creation on.

## Run it as your own [#run-it-as-your-own]

Ownership starts with who holds the keys and where the contracts run. [Give each organisation its own custody provider and credentials](https://docs.settlemint.com/docs/changelog/dalp-3-1/org-custody): a bank on a shared deployment can sign through the custodian chosen when its organisation was created, tests new credentials against the provider before they are used, and rotates them from the Console with every secret masked. [Deploy the contracts from inside your own cluster](https://docs.settlemint.com/docs/changelog/dalp-3-1/air-gapped-deployment): a Job the operator switches on deploys the DALP smart contracts from inside an air-gapped cluster, with a key the operator holds, images from the operator's own mirror and object storage behind a private certificate authority.

## Run it for the long term [#run-it-for-the-long-term]

A platform that hosts many organisations for years needs routine operations that leave a record. [Archive organisations and reset onboarding without database access](https://docs.settlemint.com/docs/changelog/dalp-3-1/platform-operations): platform admins archive and restore organisations and reset a stuck onboarding through permissioned calls, an invitation can carry the invitee's on-chain roles, and an organisation cannot approve one national ID for two people in the same country.

## Compatibility [#compatibility]

Integrations built on 3.0 keep their request and response shapes, and new capabilities arrive as additional v2 routes. Four behaviours change for an integration: v2 email filters match exactly, the API refuses blank text filters, the platform refuses a webhook receipt counter-signed the earlier way, and from 3.1.19 the original asset families can be created only once legacy asset creation is on. Before you upgrade, decide the following:

- **Custody records.** The upgrade gives every organisation a custody record taken from the deployment's custody settings and locks the provider of each organisation that already owns a wallet. Keep those settings pointed at the custodian that holds your existing keys while you upgrade. A deployment that still runs the legacy transaction signer database gives the migration access to it, and from 3.1.3 the migration also reads it to confirm which custodian holds the keys. [Upgrades and migrations](https://docs.settlemint.com/docs/deployment/upgrades-migrations) describes what runs.
- **Data sealed in the earlier format.** When the migration finds secrets or KYC documents still encrypted in the earlier format, it stops and asks for the password that sealed them. [Encryption at rest](https://docs.settlemint.com/docs/deployment/install/values-secrets#encryption-at-rest) gives the procedure.
- **Connection pooler.** The deployment charts now run a database connection pooler by default. A deployment whose PostgreSQL already sits behind its own pooler turns the chart's pooler off, as [How application pods reach Postgres](https://docs.settlemint.com/docs/deployment/install/values-secrets#how-application-pods-reach-postgres) describes.
- **Webhook receipts.** An endpoint that counter-signs delivery receipts signs the whole delivery identity, and the platform refuses a receipt signed the earlier way. [Counter-signed receipts](https://docs.settlemint.com/docs/api-reference/webhooks/consuming#counter-signed-receipts) gives the signing string.
- **Test networks.** A deployment on a test network that signs through DFNS or Fireblocks sets the default network and asset for new wallets, because they otherwise fall back to mainnet.
- **Fireblocks Gas Station, from 3.1.12.** New Fireblocks vault accounts enrol in Fireblocks Gas Station by default. A Fireblocks workspace without Gas Station turns that off before upgrading.
- **Original asset families, from 3.1.19.** New bonds, equities, funds, stablecoins, deposits, real estate and precious metals of the original catalogue can be created only after the operator turns legacy asset creation on. Tokens you already issued keep working, and nothing needs doing for them.
- **Duplicate national IDs.** Where two or more approved members of one organisation share a country and national ID, the upgrade keeps the earliest-approved profile and moves the others back to under review. A Compliance officer reviews those profiles after the upgrade, and from then on the platform refuses a second approval of the same ID.

[The 3.2 upgrade guide's section for 3.0 deployments](https://docs.settlemint.com/docs/deployment/upgrade-to-3-2#upgrading-from-30) lists these 3.1 steps for a deployment still on 3.0, and names the setting behind the custody, sealed-data, Gas Station, test-network and legacy asset decisions. The contract deployment Job and the trust for object storage behind a private certificate authority stay off until you enable them, as [Install on OpenShift](https://docs.settlemint.com/docs/deployment/install/openshift) shows.

## Smaller updates [#smaller-updates]

Records and data:

- Ledger Data reads DALP events from older contract versions as well as current ones.
- Ledger Data finds identities created by factories it was never told about and corrects its records to match the network.
- Token details and chart statistics load through leaner queries.

Console and display:

- The Console enforces its Content-Security-Policy, so the browser blocks scripts the policy does not allow.
- Currency amounts below a billion show in full, and the Console marks compact amounts as approximate.
- The Console shows the register-identity control based on the wallet itself, without first looking up an identity.
- A feature date that was never set shows Never or Unknown instead of a placeholder date.
- Kosovo is back in country selectors, total price keeps its decimals on asset details, and dynamic metadata fields show their unit.
- Asset participants are searchable by token symbol, and the topic picker for issuing a verification offers only the topics the issuer is trusted for.
- A table's search is kept in the link, so a shared link opens the same filtered view, and the saved organisation theme shows straight after signing in again.

API and platform behaviour:

- v2 email filters match exactly, and the API rejects blank text filters.
- A failed invitation returns an error that names the fix, and invitations expire after 7 days.
- API keys created before scopes existed keep read-write access instead of dropping to read-only.
- Error messages show their values instead of raw template placeholders, and a route path quoted in a message keeps its placeholders as written.
- Creating a user completes both of its stages or reports that the call can be retried.
- Revoking a token's administrator role through the API checks the token's live admins first and refuses to remove the last one.
- Price feeds use their own decimal precision when a price is submitted or backfilled.
- Recorded events keep each participant's original address, and creation times come from the block timestamp.
- The deployment charts allow API calls up to five minutes by default, so a long create flow is not cut off at the charts' own gateway.

Security hardening:

- A counter-signed webhook receipt covers the whole delivery, so it cannot be replayed onto another attempt.
- Webhook endpoints cannot point at reserved IPv6 address ranges.
- The deployment charts no longer ship predictable default object storage credentials.

Reliability hardening, shipped across the 3.0.x patches:

- Transactions: a transaction stuck behind a lost sequence number is reissued instead of waiting behind it, a stalled transaction queue recovers on its own, a transaction refused before broadcast is marked failed, and token creation resumes after a partial deployment.
- Ledger Data: a lost lock recovers instead of stopping the process, a long history backfill keeps going when a node endpoint is slow, and startup survives an unreachable node endpoint.
- Webhooks and background work: pausing deliveries no longer blocks an endpoint's queue, the platform cleans up abandoned background jobs, and a resubmitted reconciliation keeps its input.
- Database: a configurable statement timeout frees connections held by a hung query, and a dropped database connection no longer crashes the process that held it.

Operations visibility and documentation:

- Platform usage metrics come with a ready-made monitoring dashboard.
- The documentation covers global compliance controls and the token types each one applies to, and the platform overview gains a full architecture diagram.


# Organisation custody

Source: https://docs.settlemint.com/docs/changelog/dalp-3-1/org-custody
Each organisation on one deployment signs through its own custody provider, with credentials tested before use and rotated from the Console.

**Each organisation on a DALP deployment can now sign through its own custody provider, with its own credentials.** In 3.0 one custody provider served the whole deployment, so every institution on it shared one custody decision. 3.1 makes custody a setting of each organisation, so a bank on a shared deployment can sign through the custodian it contracted.

Spotlight: Each organisation holds its own custody record: provider, credentials and the workspace it signs from

- Providers: Five, chosen per organisation
- Credentials: Tested against the provider first
- Provider: Locked at the first wallet
- Secrets: Masked in every read

The platform tests new credentials against the live provider before it stores them. An organisation created from the Console starts on the deployment's provider with credentials the platform operator manages, until its owner adopts its own.

## Before and after [#before-and-after]

**Before 3.1:** one custody provider and one set of provider credentials served every organisation on a deployment. An institution that wanted its own DFNS or Fireblocks workspace needed the operator to change the deployment's configuration, and that change applied to everyone on it.

**With 3.1:** each organisation has a custody record of its own. It names the provider, keeps the organisation's credentials in the deployment's secrets store, and pins the workspace, vault and API origin the organisation signs through. The platform tests credentials against the provider before it stores them and locks the provider when the organisation's first wallet is created. The organisation's owner, or a Platform administrator working inside the organisation, rotates the credentials from the Console.

[Figure] The life of an organisation's custody record. An organisation picks its custody provider when it is created, and the platform tests the credentials before the organisation exists. The first wallet locks the provider, so from then on only rotation is possible. A rotation tests the new credentials before use and keeps the old set live briefly. At offboarding the stored credentials are destroyed and the record stays. Every read is masked, and the custody routes answer only for the caller's own organisation. Labels: Pick a provider; At creation; Credentials tested; before creation; Provider locked; First wallet; Rotation only; from here on; Rotate; Any time; Tested before use; old set kept briefly; Destroy; Offboarding; Every stored version; record kept; Every read; Masked: provider, who manages the credentials, lock time, last validation, fingerprint; Custody routes answer only for your own organisation.

An organisation picks its custody provider at creation, the first wallet locks it, and credentials are tested, rotated and read masked from then on.

## Choose the custodian when the organisation is created [#choose-the-custodian-when-the-organisation-is-created]

An organisation created through the Platform API names its own custody provider: the platform key store, DFNS, Fireblocks, Luna HSM or Ripple Custody. A bank joining a shared deployment creates its organisation with a custody block that carries its Fireblocks API key and secret key, its vault account ID and its default asset. The platform tests those credentials against Fireblocks before it creates the organisation, so a wrong key leaves no half-made organisation behind. The credentials go to the deployment's secrets store and never into the input of the deployment workflow that follows. The bank's risk team reviews one workspace that the bank contracted, and the deployment's other organisations keep custody records of their own.

![Custody page with the built-in platform store showing its health, default status and whether investors can choose it](https://docs.settlemint.com/docs/screenshots/console-organisation-custody.light.en.webp)

[Screenshot] The Custody page shows which provider is the default and whether investors can choose it.

A pinned API origin must use HTTPS and sit on the provider's allow list of hosts, so a typing mistake cannot send credentialed requests to an unknown server. DFNS records pin the DFNS organisation and default network, and Ripple Custody records carry their domain, ledger and key strategy.

An organisation created from the Console's onboarding starts on the deployment's default provider with credentials the platform operator manages, and its Organisation owner can later choose **Adopt your own credentials for this provider** on the Custody page. On an instance SettleMint operates, SettleMint runs the platform key store and manages those default credentials.

## Test credentials before anything depends on them [#test-credentials-before-anything-depends-on-them]

New credentials are checked against the live provider before the platform relies on them. An Organisation owner opens "Custody" under "Organisation settings", chooses "Rotate credentials", pastes the new Fireblocks API key ID and API secret key, and selects **Test credentials**. The Console reports that it is verifying with the provider, then shows "Credentials verified (wallet-create access)." with "Workspace verified." when the key belongs to the pinned workspace. When the owner submits the rotation, the platform tests the credentials again against the pinned workspace before it switches to them. It keeps the previous credentials readable for five minutes so signing already in flight can finish, and it refuses another rotation within a minute of the last one. A rotation can also repin the workspace or vault, but it never changes the provider. A credential that fails the provider's check is caught when it is entered, and a rotation does not cut off a transaction the custodian is already signing. The test shows that the credentials authenticate and can read or create wallets, and whether a signing request passes the provider's own policy stays the provider's decision.

## Read the custody state without exposing a secret [#read-the-custody-state-without-exposing-a-secret]

The Custody page and the matching API read return a masked view of the record. It shows the provider, whether the credentials are "Credentials managed by this organisation" or "Credentials managed by platform", when the provider was locked, the last validation, the credential version, the last rotation and a fingerprint of the credentials. For credentials the platform manages, it shows nothing derived from them. When an organisation offboards, its Organisation owner, or a Platform administrator working inside that organisation, destroys its credentials through the administrator custody API. Every stored credential version is deleted, and the custody record stays as a marker, so a later read shows "Credentials destroyed" and the organisation cannot sign until new credentials are rotated in. A departing institution's credentials do not stay behind in the secrets store, and the record of which provider served it remains. Both administrator custody routes answer only for the caller's own organisation, and destroying credentials cannot be undone.

## Create test-network wallets on the network you intend [#create-test-network-wallets-on-the-network-you-intend]

A deployment can now set the DFNS network and the Fireblocks asset on which new wallets are created, and each organisation can override both on its custody record. An organisation running a pilot on a Sepolia test network sets its DFNS "Default network" or its Fireblocks "Default asset ID", so its wallets are created on the test network rather than on Ethereum mainnet. Fireblocks vault account creation is also safe to repeat: a retried onboarding finds the vault account it already created by name instead of opening a second one. A wallet is bound to its network when it is created, so the setting decides where a pilot's wallets live. Left unset, both values still fall back to mainnet, so a deployment on a test network sets them.

## Upgrading [#upgrading]

Keep the deployment's custody settings pointed at the custodian that holds your existing keys while you upgrade. The upgrade then gives every existing organisation a custody record without further steps. At 3.1.0 the migration copies the provider from the deployment's signer configuration onto each organisation that has no record, with credentials the platform manages, and locks the provider of every organisation that already owns a wallet. From 3.1.3 the legacy transaction signer database, where a deployment still has one, answers first when it names a custodian, so give the migration access to it if you still run it. Existing organisations stay on the deployment's custodian until an owner adopts credentials of their own. The key migration skips wallets that a custody provider holds, because the platform has no key material for them. A deployment on a test network sets the DFNS default network and the Fireblocks default asset before new wallets are created. [Upgrades and migrations](https://docs.settlemint.com/docs/deployment/upgrades-migrations) describes the migration, and [the 3.2 upgrade guide's section for 3.0 deployments](https://docs.settlemint.com/docs/deployment/upgrade-to-3-2#upgrading-from-30) names the settings.

## Why it matters [#why-it-matters]

- **Banks:** your organisation's wallets can sign through the custodian your institution contracted on a shared deployment, and only your owner or a Platform administrator working in your organisation can rotate or destroy its credentials. On an instance SettleMint operates, a Platform administrator may be SettleMint staff.
- **Exchanges, CSDs and market infrastructures:** one deployment can host several member institutions, each with its own custody provider, credentials and rotation schedule.
- **Regulators:** the masked custody record shows an organisation's provider, when it was locked and when its credentials last passed a check.
- **Partners:** A custodian connects per organisation, so it serves its own client on a deployment without touching any other organisation's setup.

## Next steps [#next-steps]

- [Custody provider prerequisites →](https://docs.settlemint.com/docs/deployment/prerequisites#a-custody-provider-when-signing-leaves-the-platform)
- [Upgrades and migrations →](https://docs.settlemint.com/docs/deployment/upgrades-migrations)
- [Understand custody providers →](https://docs.settlemint.com/docs/concepts/custody-and-signing/custody-provider)


# Platform operations

Source: https://docs.settlemint.com/docs/changelog/dalp-3-1/platform-operations
Platform admins archive organisations and reset stuck onboardings through the API, invitations carry on-chain roles, and national IDs stay unique.

**Your platform admins archive and restore organisations and reset a stuck onboarding without touching the database, and an inviter can send new members their on-chain roles with the invitation.** A platform that hosts many organisations for years collects dormant organisations, users stuck halfway through onboarding and members who join without the roles they need. 3.1 gives each of those a defined operation, and refuses a second approved person with the same national ID in one organisation.

Spotlight: Routine platform administration runs as permissioned calls that leave a record

- Archive: Reversible, reason recorded
- Onboarding reset: Wallets archived, memberships kept
- Invitations: Roles signed by the inviter on acceptance
- National ID: One approved person per organisation

Every call to the platform administrator routes, refused calls included, writes a log entry with the caller, the route and the target. An archive also stamps who archived the organisation, when and why.

## Before and after [#before-and-after]

**Before 3.1:** winding down an organisation, clearing a user's broken onboarding or settling a duplicate identity record had no API operation, so it meant a manual change in the database with no standard record of who made it. A new member joined with no on-chain roles, and someone granted them in a second pass.

**With 3.1:** A Platform administrator archives, restores and resets through the Platform API, and each call is logged. An invitation can carry the on-chain roles the inviter picked, and the platform grants them from the inviter's wallet when the invitee accepts. The platform refuses a second approved profile with the same country and national ID inside one organisation.

[Figure] Three administration flows that keep their history. A Platform administrator archives an active organisation, which takes it out of daily use: it is hidden, cannot be selected and takes no new members. Restore brings it back. The archive records who, when and why, and the call is logged. For a stuck onboarding, the administrator signs in again within 15 minutes and resets it: the user's wallets are archived, sessions end and memberships stay, and the user onboards again while the archived wallets stay registered on chain. An inviter picks on-chain roles and verifies the invitation, the invitee accepts and finishes onboarding, and the platform grants the recorded roles from the inviter's wallet when it still can. Labels: Archive; Restore; Reset; Accept; Active; Platform administrator; Listed and selectable; Out of daily use; Archived; Hidden, not selectable; No new members; Who, when, why; Recorded; Call logged with the; caller and target; Stuck onboarding; Platform administrator; Signs in again; within 15 minutes; Wallets archived; Reset; Sessions ended,; memberships kept; Onboards again; User; Archived wallets stay; registered on chain; Invitation; Inviter; On-chain roles picked,; inviter verifies; Member joins; Invitee; Finishes onboarding; Roles granted; Platform; As the invitation; recorded them.

A Platform administrator archives organisations and resets onboarding, and an inviter sends on-chain roles that the platform grants on acceptance.

## Archive an organisation and keep its history [#archive-an-organisation-and-keep-its-history]

A Platform administrator takes an organisation out of daily use without deleting anything, and brings it back when needed. A pilot organisation has ended, so the Platform administrator calls `POST /api/v2/admin/organizations/{id}/archive` with the reason "Pilot ended". The organisation disappears from organisation listings, nobody can select it as their active organisation, and it accepts no new members. Its assets, wallets and records stay where they are, and the organisation record carries the archive time, the administrator who archived it and the reason. When the pilot restarts, `POST /api/v2/admin/organizations/{id}/restore` returns it to use.

![Organisations page for platform administrators listing each organisation with its status, members and assets](https://docs.settlemint.com/docs/screenshots/console-platform-admin-organisations.light.en.webp)

[Screenshot] A platform administrator sees each organisation's status and when it was archived.

Deleting an organisation would destroy its audit trail and leaving it active invites accidental use, so archive keeps the record intact and stops new sign-ins and new members. Restore clears the archive time, actor and reason from the organisation, so the earlier archive stays visible only in the administrator call log, which your log platform keeps for as long as it is set to. On an instance SettleMint operates, a Platform administrator may be SettleMint staff. Archive stops anyone from choosing the organisation or joining it, but sessions and API keys already working in it keep their access, so revoke them when an organisation must stop acting at once.

## Reset a stuck onboarding without losing the wallet history [#reset-a-stuck-onboarding-without-losing-the-wallet-history]

A Platform administrator clears a user's broken onboarding in one call, and the user starts again. A user's onboarding failed after their wallet was created, and they cannot continue. The Platform administrator signs in again, because the reset accepts only a sign-in from the last 15 minutes, and calls `POST /api/v2/admin/users/{id}/reset-onboarding` with the reason "Wallet lost, user re-onboarding". The platform moves the user's wallets to the archive, clears their custody wallet and active organisation, and ends every session they hold. Their organisation memberships stay, so they rejoin the same organisations when they onboard again. The call returns how many wallets it archived and their addresses. Support fixes a stuck user without a database change, and the wallets that existed before stay on record. The reset moves no assets: the archived wallets stay registered on chain, any tokens they hold stay at those addresses, and nothing those wallets already did on the network is undone.

## Invite people with their on-chain roles ready [#invite-people-with-their-on-chain-roles-ready]

An invitation can carry the system-level on-chain roles the new member needs on day one, the roles the smart contracts themselves enforce. An Organisation owner opens **Create or invite user** on the Users screen, enters the new compliance officer's email and picks roles under "On-chain permissions". A role the owner cannot grant shows "You do not have the authority to grant this role." On "Send invitation", the owner confirms with their own wallet verification, a PIN, a one-time code or MFA, and the invitation stores the roles. When the invitee accepts and finishes onboarding, the platform grants those roles, and resending the invitation keeps them. Only the role invitation stores on-chain roles, and it always asks for the inviter's wallet verification. An invitation expires after 7 days, and one without on-chain roles takes the ordinary path with no wallet verification. The grant is signed from the inviter's wallet when the invitee accepts. If the inviter no longer holds the authority then, or the custody policy needs an approval, onboarding completes without the roles and someone grants them by hand.

## Approve one person per national ID in an organisation [#approve-one-person-per-national-id-in-an-organisation]

A Compliance officer can rely on a country and national ID pointing to one approved person in the organisation. When a reviewer tries to approve a KYC profile whose country and national ID already belong to an approved member of the same organisation, the platform refuses the approval, and it refuses an invitation at acceptance when the invitee's approved ID already exists in that organisation. On the Users screen, the officer types a national ID into the search box, which matches names, emails, wallets and national IDs, and narrows the list with the **Residency** and "Country" filters, and eight other tables gain the same kind of filters. A lookup by national ID and country returns one approved person, so a duplicate cannot block it later. The rule applies to one country and national ID within one organisation, so two organisations can each hold a person with the same number.

## Upgrading [#upgrading]

The administrator routes, the invitation fields and the database objects arrive with the upgrade, and existing calls keep their shape. One behaviour changes: where two or more approved members of one organisation share a country and national ID, the upgrade keeps the earliest-approved profile and moves the others back to under review, so a Compliance officer re-reviews them, and from then on the platform refuses a second approval of the same ID. Plan a review of those profiles after the upgrade. [Upgrades and migrations](https://docs.settlemint.com/docs/deployment/upgrades-migrations) describes what the migration runs.

## Why it matters [#why-it-matters]

- **Banks:** day-to-day administration of a multi-organisation platform runs through permissioned calls that leave a record, with no direct database access.
- **Exchanges, CSDs and market infrastructures:** member organisations leave and return through archive and restore, and their history stays in place.
- **Regulators:** archived organisations keep their records, calls to the platform administrator routes are logged with the caller, and one country and national ID maps to one approved person within an organisation.

## Next steps [#next-steps]

- [Archive and restore organisations →](https://docs.settlemint.com/docs/console/platform-admin/organisations)
- [Create and manage users →](https://docs.settlemint.com/docs/console/participants/users)
- [Understand role grants →](https://docs.settlemint.com/docs/concepts/compliance-and-identity/role-grant)


# AI assistant and agents

Source: https://docs.settlemint.com/docs/changelog/dalp-3-2/ai-assistant
An assistant that drafts from the page and the documents you drop, watchers that prepare the next step, MCP access, and agents held to an on-chain mandate.

**Your team gets drafts filled from the page it is on and the documents it drops, and a member checks and signs each one unless an owner has let an agent act inside its on-chain mandate.** Term sheets, written policies and subscription forms stop being re-keyed into controls, and a coupon nobody funded is found days before its payment date. The assistant drafts in the controls your people already use, standing checks prepare the next step, and an agent makes only the calls its on-chain mandate lists, with transfer and approval amounts capped until the mandate expires. The mandate does not cap the size of a mint or burn.

Spotlight: Code reads every value, and a member signs unless an agent acts inside its mandate

- Drafts open in: The member's own control
- Watchers: Four, off until switched on
- Acting alone: Agents, inside an on-chain mandate
- Veto window: Four hours

Answers come from data the member can already read, and go to the model through the organisation's own OpenRouter key or the platform key. An agent's mandate lists the calls it may make and caps transfer and approval amounts until it expires, and it does not cap a mint or burn.

## Before and after [#before-and-after]

**Before 3.2:** someone reads a term sheet and types its coupon, dates and ISIN into the issuance form, then someone else checks it against the PDF. A compliance policy written in a memo is turned into token rules by hand, and a treasury shortfall surfaces when the payout fails.

**With 3.2:** A member asks from the page or drops the document, and the matching control opens with each value filled in and quoted from its page. Watchers post the next step to the Actions inbox of the people who own it. One watcher can be allowed to move funds on its own, and then only through an agent whose mandate the chain enforces.

[Figure] The assistant drafts and a member signs, and an agent acts only inside its on-chain mandate. A member asks about the page they are on or drops a PDF. The model picks the passage, code parses each value, and every value quotes its page. The member's own control opens filled in, and the member checks and signs. Questions and the records they cite go to the model through the organisation's own OpenRouter key, or the platform key where it has none. Separately, a watcher finds a problem and, at Suggest or Prepare, posts an item to the Actions inbox, with a draft where it can make one, which opens the same control. Only the payout watcher can be raised to Act with veto window or Act, by the owner after a track record, and it then runs as an agent principal inside its on-chain mandate, which the owner can revoke for one agent or halt for all. An MCP app that names an agent can also act inside that agent's mandate, which caps transfer and approval amounts but not a mint or burn. Labels: A question or a PDF; A member asks; About the page they are on; Model picks, code parses; Assistant drafts; Each value quotes its page; Opens filled in; Member's own control; The member checks and signs; What leaves DALP; Questions and cited records go to the; model through the OpenRouter key set; Finds a problem; Watcher; Payout, filing, expiry, bank credit; Item in the Actions inbox; Suggest or Prepare; With a draft where it can make one; Act with veto window, or Act; Payout watcher only; Owner raises it after a track record; Inside its on-chain mandate; Agent principal; Owner revokes one or halts all.

A member checks and signs each draft, while watchers post the next step to the Actions inbox and only the payout watcher can act inside an on-chain mandate.

## Ask about the page you are on and get a draft to sign [#ask-about-the-page-you-are-on-and-get-a-draft-to-sign]

A member asks from the command palette about the asset, participant, organisation, trading venue, audit trail or filings on screen. The answer cites the read behind each figure, and the Console shows the value from that read. A draft opens the matching control already filled in, for the member to check and sign. Organisation owners and administrators manage model access: the assistant runs on the organisation's own OpenRouter key, or on the platform key where the operator set one and the organisation has none, and six switches turn its capabilities on or off for the whole organisation.

![Assistant settings page with the model access, the data sent to the model and the capabilities](https://docs.settlemint.com/docs/screenshots/console-organisation-assistant-settings.light.en.webp)

[Screenshot] Your organisation decides what the assistant may see and which capabilities it offers.

An Asset manager on a bond's page asks what changed last month. The assistant reads the bond's period summary and answers with the transfer volume, the net supply change and the active holders, each compared with the month before, and names the largest movers by handle. The member asks for a mint to a named investor, and the mint control opens filled in, waiting for the member's wallet verification.

The assistant calls models only through OpenRouter, which picks the model provider and region, and each request asks for zero-data-retention endpoints only. In the question and the records the assistant reads, holder names, emails and wallet labels are replaced with handles. Document pages and memos go as written, names included, until an owner or administrator chooses **Mask**, which keeps them in DALP. DALP cannot check what a provider keeps.

## Turn documents into rules and drafts [#turn-documents-into-rules-and-drafts]

A token governor can write the asset's compliance policy in words on the Compliance tab and read it back as rules. A term sheet dropped on Issue asset fills the fields it states, and **Draft from a document** in the command palette reads a subscription agreement into the mint control, a bank statement into matches for parked bank credits, an identity document set into a verification, and a regulator or board letter into a new filing obligation. The assistant also drafts holder notices for a cash dividend or a distribution, and compares each term sheet on an asset's Documents tab with what the chain holds.

A Compliance officer who holds the Governance role on the bond selects **Write the policy** and enters "Only professional investors resident in Germany or Austria, with a 12-month lock-up." "Read the policy" lists each clause, the rule it became and the words its values came from. A check against the current holders then tests those rules against the 50 largest holders and names each holder who would fail and why.

**Open 3 rules** opens the first add-rule sheet with its values filled in, and each rule is saved with the usual wallet verification before the next one opens.

The model picks a passage or answers unsure, and code reads every value from it, so a date it cannot parse stays empty with the page to check. Policies are read in English and German, and the term sheet fill and document drafts run only while the organisation sends documents to the model.

## Let watchers prepare the next step [#let-watchers-prepare-the-next-step]

Four watchers run standing checks on DALP data: a dividend, distribution or coupon due within fourteen days that the treasury cannot cover, a filing due with nothing submitted, verifications that run out while an asset's rules still need them, and a bank credit nobody could match. Each stays off until an organisation owner or administrator switches it on. At Suggest, a watcher posts what it finds to the Actions inbox of the people who own that work. At Prepare, it adds a draft or options. The filing and verification watchers stop at Suggest, and the bank-credit watcher stops at Prepare.

The payout watcher finds a coupon due in nine days whose treasury holds too little. It posts an item to the Asset managers and organisation owners that prepares the coupon's **Fund schedule** control with the shortfall. An Asset manager opens the draft, checks the amount and signs, and the item closes when the treasury covers the payout.

**Stop all watchers** drops every watcher to Observe at once, where it runs and logs only.

## Let one watcher act, only inside an on-chain mandate [#let-one-watcher-act-only-inside-an-on-chain-mandate]

Only the payout watcher can go further than Prepare, and only when the owner raises it. Act with veto window schedules the action and runs it unless a member vetoes it within four hours. Act runs the action and reports it. A raise to Prepare or higher needs the owner's minimum track record over the last 90 days: enough resolved items, and enough of them taken unchanged. Either act level also needs an agent principal. That is a participant whose smart wallet can make only the calls its mandate lists, with per-transaction and per-period limits on the transfers and approvals it makes for each asset, until the date the mandate names.

An Organisation owner selects **Create agent**, reviews the starter mandate for the bond's payout asset and confirms with wallet verification, then raises the payout watcher to Act with veto window. The next shortfall the watcher finds becomes a transfer of the payout asset to the treasury, scheduled four hours after the item is posted.

Any member who can see the item can select **Veto transfer** before then. When nobody does, the agent sends the transfer and the item reads "Done by" with the agent's name and the transaction hash.

The chain enforces the limit, and the agent's key cannot change its own mandate: only the organisation's own account can replace or revoke it. "Revoke agent" stops one agent for good, and **Halt all agents** revokes every live mandate and cancels the transactions the agents have queued. A transfer cannot be undone once the agent has run it, and whether the mandate covers it is checked again when it runs.

## Connect Claude, ChatGPT or your own agents to DALP [#connect-claude-chatgpt-or-your-own-agents-to-dalp]

An organisation owner switches on the hosted Model Context Protocol (MCP) server, and members sign in from Claude, ChatGPT or another MCP app. The app reads what the member can read, and a change it prepares lands in the member's Actions inbox as a request from that app, where the member confirms it with wallet verification. Each call leaves an audit record that names the app, and an owner can revoke an app for every member. An app can also run a mint, burn, pause, unpause, block or unblock as one of the organisation's agents when it names the agent, with no member signature, and then only for the calls that agent's mandate lists. The mandate caps transfer and approval amounts, so it does not cap the size of a mint or burn.

A member connects ChatGPT and asks for a bond's holders, and the app shows the holders table as the member would see it. The member asks it to prepare a mint, the request appears in the Actions inbox, and the member opens the filled-in mint control and signs.

The DALP command-line tool also runs as an MCP server on the user's own machine, exposes every command and marks reads as read-only. What a connected app reads goes to that app's own provider, outside the assistant's Mask setting, and the command-line server runs writes under the signed-in user's API key without a prompt, so your own policy has someone review a command first.

## Upgrading [#upgrading]

The assistant is on for every organisation and answers once a key exists: the organisation's own, or the platform key the operator sets. Documents are sent to the model by default, so an owner or administrator who wants them kept in DALP chooses **Mask** in the assistant settings. Setting the platform key also turns on Ask AI, which answers questions on the documentation site, for anyone who can reach it, billed to that key, unless the operator keeps it off or gives it a separate key. Watchers stay off, the hosted MCP server stays off until an owner switches it on, and no agent exists until an owner creates one. [Decide on Ask AI](https://docs.settlemint.com/docs/deployment/upgrade-to-3-2#decide-on-ask-ai) describes the operator's choice.

## Why it matters [#why-it-matters]

- **Banks:** the assistant reads only what the member may read, drafts go through the same controls and signatures, and "Mask" keeps documents and memos out of what the assistant sends to its model provider.
- **Regulators:** each agent action names the agent and its transaction, and an agent's permitted calls and its transfer and approval limits sit in a mandate on chain that its own key cannot change. The mandate does not cap the size of a mint or burn.
- **Partners:** Claude, ChatGPT and your own agents connect through MCP and the command-line tool under the member's own access.

## Next steps [#next-steps]

- [Connect an AI app →](https://docs.settlemint.com/docs/api-reference/cli/hosted-mcp)
- [Set up the assistant →](https://docs.settlemint.com/docs/console/organisation-settings/assistant)
- [Understand agent mandates →](https://docs.settlemint.com/docs/concepts/custody-and-signing/agent-mandates)


# Cash and the bank rail

Source: https://docs.settlemint.com/docs/changelog/dalp-3-2/bank-rail
Mint a fiat token from each credit your bank confirms over its FIX session, pay redemptions only to approved accounts and reconcile the reserve.

**Your team can mint a fiat-backed token from each confirmed bank credit, pay redemptions only to approved accounts and show that the reserve covers the supply.** DALP logs on over TLS to your bank's own session of FIX, the Financial Information eXchange protocol, so a cash-token team runs the whole cycle, from client payment to reconciliation, on the bank account that holds the reserve.

Spotlight: Each credit the bank confirms mints at most once, and each redemption burns only when the bank reports it paid

- Bank side: Your bank's own FIX session, over TLS
- Each credit: Mints at most once, however often reported
- Payout accounts: Approved by someone other than the proposer
- Reconciliation: On every bank balance report

The rail logs on to your bank with each connection's own identifiers and password, reads credits, balance reports and payment outcomes from that session, and a Bank rail manager runs it from "Asset lifecycle" › **Bank rail** in the Console.

## Before and after [#before-and-after]

**Before 3.2:** A treasury team reads each credit off the bank statement and mints by hand. A payment keyed twice mints twice, a payment with a wrong reference waits in someone's inbox, and redemptions are matched to outgoing payments in a spreadsheet. When the auditor asks whether the reserve covers the supply, the answer is assembled after the fact.

**With 3.2:** the rail records each bank transaction once and mints it to the client's wallet, or holds it as suspense with an operations case when no client matches. A redemption is paid by an instruction the bank acts on once, and its tokens burn when the bank reports the payout settled. Every balance report is compared with the supply, and a difference that stays unexplained on two reports in a row opens a case.

A client can cash out only to a bank account approved by a bank rail manager other than the one who proposed it. The client requests the payout from "Withdraw" in the Investor portal, choosing a requested redemption line or, for a Supply delegate token, an amount whose exact allowance the client approves for the escrow. A retry keeps the same request identity. [Request a bank payout →](https://docs.settlemint.com/docs/concepts/operating/investor-portal-bank-transfers#how-to-cash-out) Each cash-out row shows where its tokens are held, including an escrow lock. A bank rail manager's integration follows each cash-out through its stream, which sends the cash-out each time the lock, the checker step or the burn moves it. [Follow a cash-out →](https://docs.settlemint.com/docs/api-reference/guides/bank-rail#follow-a-cash-out)

[Figure] How the bank rail keeps a cash token in step with its reserve account. Your bank reports a credit over its FIX session with DALP. The rail records each bank transaction once, matches it to a client by reference or virtual IBAN, screens the client's wallet and mints to it at most once. A credit that matches no client mints to the rail wallet as suspense until a manager allocates or returns it. A cash-out goes only to an account someone other than its proposer approved, its instruction goes out once on a business day, and the tokens burn when the bank reports the payout settled. Each balance report is reconciled against supply and suspense, and a difference on two reports in a row opens a case. Labels: Money in; Credit reported; Bank; Over your bank's; own FIX session; Recorded once; Once; A repeat changes; nothing; Match, screen; Checks; Reference or IBAN,; token compliance; Minted to wallet; Client; At most one mint per; bank transaction; Suspense tokens; No match; Allocate or return,; case stays open; Money out; Approved account; Cash-out; Approver is never; the proposer; Sent once; Instruction; On a business day,; before the cut-off; Burnt when paid; Bank report; Rejected: tokens; back to the holder; Reserve vs supply; Reconcile; Each balance report; against supply and; suspense. A case; opens after two; breaks in a row.

A credit mints once to the client it matches, a cash-out burns tokens when the bank reports it settled, and every balance report is reconciled.

## Connect to your bank's own FIX session [#connect-to-your-banks-own-fix-session]

The rail opens one FIX session to your bank for each active bank connection. A Bank rail manager adds the connection under "Asset lifecycle" › "Bank rail" with its CompIDs, the identifiers each side uses on the session, and the reserve account and currency, sets its logon password on the "Settings" tab and chooses **Activate connection**. DALP then dials the bank's FIX acceptor over TLS, checks the bank's certificate and logs on with that connection's identifiers and password. While the line is quiet it sends heartbeats, it logs out when the bank stays silent for 90 seconds, and after a drop it dials again with a wait that doubles up to a limit the operator sets. Both sides keep their message numbers across restarts, so after a drop each side asks the other to resend what it missed, and a payment instruction sent again is marked as a possible duplicate. Suspending a connection ends its session and stops the dialling. The operator sets the bank's FIX address for the whole deployment, so every connection on one deployment reaches the same bank acceptor.

![Payments tab of a bank connection listing each bank credit with its client, amount and status](https://docs.settlemint.com/docs/screenshots/console-bank-rail-payments.light.en.webp)

[Screenshot] Your team sees each bank credit minted to its client and allocates the one with no match.

## Mint each confirmed payment at most once, to the client who paid [#mint-each-confirmed-payment-at-most-once-to-the-client-who-paid]

A client's payment into the reserve account reaches their wallet as tokens without anyone keying it in. Each connection has a token link, the setting that ties one token to that bank connection, and a rail wallet, the wallet DALP keeps for the connection to sign every mint and burn. A Bank rail manager adds a corporate client on the connection's "Clients" tab, and DALP generates the payment reference the client quotes on its transfer. The rail can also match a credit by a virtual IBAN, an account number the bank assigns to one client. The client pays 24.99 USD into the reserve account and the bank confirms the credit over FIX. The rail screens the client's wallet against the token's compliance, mints 24.99 tokens to it, and the credit appears on the **Payments** tab with its mint transaction. If the bank sends the same confirmation again, the rail answers with the acknowledgement it stored and mints nothing. A credit the token cannot represent, or one whose mint fails or is refused approval, mints nothing and is listed with its reason. With the organisation's "Bank rail" approval rule off, every credit that matches a client mints without a second look.

## Hold an unmatched payment as suspense until a manager decides [#hold-an-unmatched-payment-as-suspense-until-a-manager-decides]

A payment whose reference matches no client still mints, but to the rail wallet, as suspense: tokens the rail holds for a payment it cannot place, each listed with its operations case. A manager chooses **Allocate** to move those tokens to the client who paid, or "Return to payer" with the bank's refund reference, which burns them once the bank has refunded the payer. When the organisation turns on the "Bank rail" approval rule, a second Bank rail manager approves each allocation and return. A credit over the token link's checker threshold, counted with the client's credits of the last 24 hours, then waits for approval before it mints. The approval rule starts off, so until an organisation owner or a platform administrator turns it on, one manager allocates or returns suspense alone. On an instance SettleMint operates, a platform administrator may be SettleMint staff.

## Pay redemptions only to accounts a second person approved [#pay-redemptions-only-to-accounts-a-second-person-approved]

A redemption pays out only to a bank account that someone other than its proposer approved. A client proposes a bank account in the Investor portal, or a manager adds one, and it becomes usable only when a Bank rail manager other than the person who proposed it approves it, whether or not the approval rule is on. A token runs in one of two supply modes. In booked movements the rail wallet holds the token's supply management role and books each redemption as a line on the token, and in supply delegate mode the rail wallet is the token's only supply delegate, allowed to mint and burn, and locks redeemed tokens in the rail's escrow. Each row on the "Cash-outs" tab names where the tokens are held. For a booked token a manager chooses **Record cash-out** and picks one of the client's active accounts, and for a token that mints through a supply delegate the client requests the cash-out from their own wallet. With the approval rule on, a cash-out over the threshold, alone or with the client's cash-outs of the last 24 hours, waits for a second manager.

The rail then sends one payment instruction over FIX to the bank, and when it reports the payment settled, the held tokens burn. A rejected payment, or a deadline the bank misses, gives the tokens back to the client. When mail is set up and the client has an email on file, it gets an email when the cash-out is paid, rejected or returned. If a holder cancels the redemption request after the instruction went out and the bank then pays, the cash-out stays unbooked and a critical case opens, because the rail cannot take the tokens back by itself.

## Send payments only on the connection's business days [#send-payments-only-on-the-connections-business-days]

Each connection has a time zone and can follow a holiday calendar and a payment cut-off, so the rail instructs nothing while the bank is closed on that calendar. A Bank rail manager sets them with **Edit payment schedule** on the connection's page. A cash-out approved after the cut-off, or on a closed day, waits until the next business day, and the "Cash-outs" tab shows the value date the client can expect. The client's own cash-out reads carry the same value date. The payout deadline and the settlement window count business time on the connection's calendar, so a long weekend on that calendar raises no overdue case. Without a calendar, every day is a business day, weekends included. A change to the calendar, time zone or cut-off applies only to cash-outs requested after it.

## Take back a payment the bank reverses, even after the client's custody gateway issued receipts [#take-back-a-payment-the-bank-reverses-even-after-the-clients-custody-gateway-issued-receipts]

When the bank reverses a credit, the rail records a recall, stops the credit from minting and opens a critical case. A Bank rail manager asks for the recall through the API and a second manager approves it. The rail then cancels a credit that has not minted, burns or books the tokens it holds, or waits for a token custodian to take the tokens back from the client. A credit already delivered into the client's custody gateway is recalled too: the receipt token's custodian moves the client's receipts into the rail wallet, the rail redeems them at the rail wallet's own custody gateway, and it burns the coins the gateway pays. What the client moved away and the gateway's fees are written down as a reserve adjustment, and the reconciliation shows the receipts waiting for their redemption. A recall of a delivered credit needs the rail wallet set up as a client of a custody gateway first, and the API refuses it with the step that is missing until then. The [recall guide](https://docs.settlemint.com/docs/api-reference/guides/bank-rail#recall-a-delivered-credit) lists each step and refusal.

## Recall a credit the bank reversed, and set credit limits, from the Console [#recall-a-credit-the-bank-reversed-and-set-credit-limits-from-the-console]

When the bank reverses a credit it confirmed, the credit's row on "Payments" shows **Open recall**. A Bank rail manager requests the recall's execution or abandons it, and a second manager approves. While tokens must come back, the sheet shows the target's balances and takes the claw's transaction hash and log index. Abandoning says first that the bank's debit stays a reserve difference until a manager records an adjustment. "Settings" shows the credit threshold and the mint cap in the token's units and lets a manager change them, with a raise waiting for a second manager. "Edit payment schedule" sets the daily report cut-off. A cash-out the bank returned shows each returned amount and links to the credit that re-credits it.

## Show that the reserve and the supply agree [#show-that-the-reserve-and-the-supply-agree]

The **Reconciliation** tab shows two lines: the bank balance against the token's supply, and the rail wallet against the credits it holds as suspense. Each line counts what is still in flight, such as credits waiting to mint and payouts the bank settled that wait to be booked, and shows what is left unexplained. A value the platform cannot read shows as "Not available", never as zero. When a balance report still breaks on the next report, the rail opens a critical operations case. It opens one on the first report when the rail wallet is no longer the token's only supply authority, the one account allowed to mint and burn it. A Bank rail manager records a bank fee or interest posting as a reserve adjustment through the API, with its reason and the bank's reference. With the "Bank rail" approval rule on, a second Bank rail manager approves it, because the manager who proposed it cannot, and from the next balance report on the adjustment explains the difference. The tab lists each open difference and who explained it. With the rule off, a reserve adjustment is approved the moment it is recorded.

Each closed connection date now keeps immutable daily versions of both lines and the evidence behind them: the bank balance report at or before the connection's cut-off and the indexed token facts the run read. A manager can reread a version or export it as CSV, and an earlier version keeps its original values and bytes. The worker retries unavailable days within the last three closed days and warns when a day leaves that window incomplete. The [daily reconciliation API](https://docs.settlemint.com/docs/api-reference/guides/bank-rail#daily-reconciliation) lists the cut-off, routes and refusal reasons.

## Stop a lost rail wallet before it signs again [#stop-a-lost-rail-wallet-before-it-signs-again]

A Bank rail manager can stop the rail wallet at once if its key is lost or leaks. **Contain rail wallet**, on the connection's "Settings" tab, takes the reason lost or compromised and suspends every token link on that network. From then on the rail signs nothing with that wallet: no credit mints with it and every cash-out step it would sign waits. A checklist on the same panel names each step to recovery: register the new wallet's identity, revoke the old wallet's authority on each token, empty the old escrow by forced transfer, grant the authority to the new wallet, set up the new escrow where a token uses one, and move the suspense, which includes the coins of credits still on their way to the client's custody gateway. Those credits are repinned to the new wallet at completion, so their delivery sends from it. The token's administrator, or its governor for a token that mints through a supply delegate, signs the revoke and the grant, and a token custodian empties the old escrow. A manager then chooses "Request completion", and another Bank rail manager approves it. Containment stops the rail signing, but a leaked key keeps its supply authority on each token until the token's administrator or governor revokes it, so revoke it first. A grant of supply authority that was already waiting for approval, a signature or gas when you contained the wallet cannot hand it back its power: the rail refuses completion while such a grant to the old wallet is still queued, and while the old wallet holds authority on any token linked to it, and it opens one security case that names the grant.

## Tell your back office about each bank payment as it happens [#tell-your-back-office-about-each-bank-payment-as-it-happens]

An integration subscribes to `bank-rail.credit.*` and `bank-rail.cash-out.*` instead of polling the rail. A credit reports when it is admitted and how it ends, and a cash-out reports its request, instruction, payment, return or release. The accounting team's ledger posts each client payment and payout from these events with the bank amount, the currency and the time of each step, while approval identities, suspense reasons, recovered amounts and write-down figures stay out of the payload. A payout the bank returns admits a new credit that names its cash-out and reports its own mint, so the ledger links the two without a manual match. The [bank rail event catalogue](https://docs.settlemint.com/docs/api-reference/webhooks/events#bank-rail) lists each trigger, and the [accounting feed](https://docs.settlemint.com/docs/api-reference/guides/accounting-feed#bank-rail-events) says which events to post. The default state subscriptions skip these event names, so an endpoint receives them only after you choose the family.

## Screen each bank payment with your AML provider and check who paid [#screen-each-bank-payment-with-your-aml-provider-and-check-who-paid]

Every confirmed credit that matched a client, and every cash-out before its payment instruction, goes to the AML provider the connection names, and nothing mints or pays until the answer allows it. Sumsub transaction monitoring is the first provider, and others plug in behind the same compliance port. A credit the provider rejects or holds parks with its reason, a cash-out it rejects or holds waits for a manager, and a second Bank rail manager releases either one, even while the **Bank rail** approval rule is off. A credit that came from an account the client has not had approved parks as well, unless the connection turns the payer check off. A compliance officer reads the verdicts through the API or downloads a date range as a CSV file from the connection's "Settings" tab. The provider, the level and the payer check are settings of each connection. A connection starts with the payer check on, so credits from an account the client has not had approved park until you approve the account or turn the check off.

## Upgrading [#upgrading]

The bank rail is new in 3.2 and stays off until the operator turns it on for the deployment, as the [bank rail API guide](https://docs.settlemint.com/docs/api-reference/guides/bank-rail#set-up-a-connection) describes. The operator then points the rail at the bank's FIX acceptor with its address and TLS settings, and the platform refuses to start the rail without that address, or with an unencrypted session to a host outside its own machine. Until then the rail runs a FIX simulator that ships with DALP for local testing, which accepts connections only from the same machine. The **Bank rail** approval rule starts off in every organisation, and an organisation owner or a platform administrator turns it on under "Approvals" in the General settings before the rail handles client money. A bank account always needs approval from a Bank rail manager other than the person who proposed it, whatever the rule says.

## Why it matters [#why-it-matters]

- **Banks:** a team can show that the token's supply follows the reserve account at its own bank payment by payment, and that no payout goes to an account its proposer approved alone.
- **Regulators:** every difference that survives two balance reports in a row is an open case, and with the approval rule on, every adjustment names the manager who proposed it and the one who approved it.
- **Bank integrators:** the [bank FIX session profile](https://docs.settlemint.com/docs/api-reference/guides/bank-rail#bank-fix-session) lists the logon, heartbeat, resend and message rules the rail expects from the bank's acceptor.

## Next steps [#next-steps]

- [Run the bank rail from the Console →](https://docs.settlemint.com/docs/console/asset-lifecycle/bank-rail)
- [Pay by bank transfer in the Investor portal →](https://docs.settlemint.com/docs/concepts/operating/investor-portal-bank-transfers)
- [Understand maker-checker approval →](https://docs.settlemint.com/docs/concepts/custody-and-signing/maker-checker)

Fiat screening exports include provider alerts. A deposit from an unverified payer stays parked until the payer account passes maker-checker approval. Cash-outs above the configured limit require a checker even when the Bank rail approval family is off.


# Compliance and reporting

Source: https://docs.settlemint.com/docs/changelog/dalp-3-2/compliance-and-reporting
Filings generated from the ledger and approved by a second person, anchored digests, a hash-chained audit trail, client statements and second approvers.

**Your team produces each filing from the ledger it already runs, and can show a regulator who prepared it, who approved it and, once anchoring is on, that the file is the one approved.** Deadlines arrive in several formats, and the question a supervisor asks afterwards is what was filed and who signed it off. Each filing is generated from an obligation you publish, approved by someone other than its maker, and kept with every step on the record.

Spotlight: Filings, statements and audit entries come from the ledger and name who acted

- Report families: 41, from holder register to venue pack
- Filing sign-off: A second person, never the maker. A waiver takes one.
- Audit trail: Hash chain, anchored daily once set up
- Filing to the regulator: Your team, recorded in DALP

The platform generates each filing, records its review, approval and the authority's answer, and keeps the files for the retention class the obligation sets. Your team files it through the authority's own channel.

## Before and after [#before-and-after]

**Before 3.2:** A compliance team rebuilds each filing from register exports and spreadsheets, collects sign-off by email, and answers a regulator's question about who changed what by stitching together service logs. Nothing ties the file a regulator received to the one that was approved.

**With 3.2:** you publish each duty as an obligation, and the platform builds the calendar and generates every filing from the ledger once its period is final. A second person approves the filing's digest, the digest can go on chain for anyone to check, and each state-changing request to the Platform API leaves an audit entry in a hash chain whose daily head can be anchored on chain.

[Figure] A filing is generated from the ledger, approved by a second person and can be checked against the chain. A published obligation version sets the cadence, deadline and file layout. When a period ends and the chain is final, the platform generates the filing from the ledger's report families. A maker submits it for review with its validation findings, and a second organisation owner or organisation administrator approves its digest. The organisation's team files it through its own channel and records the submission, then records the authority's receipt with its reference. When anchoring is on, the filing's digest is written to the chain, and anyone holding the file can check it. Every step leaves an audit trail entry in a hash chain whose daily head is anchored once anchoring is set up. Labels: Published version; Obligation; Cadence, deadline, layout; Generated from ledger; Period ends; Named report families; Submit for review; Maker; Validation findings shown; Approves the digest; Second person; Org owner,; not maker; Your team files it; Your channel; Submission recorded; Receipt recorded; Authority; Reference and time; Digest written on chain; When anchoring is on; Anyone holding the file can check it against the registry; Every step; In the audit trail, a hash; chain anchored once set up.

A published obligation drives a filing from generation through a second person's approval to the authority's receipt, with every step in the audit trail.

## Generate each filing from the ledger and prove who approved it [#generate-each-filing-from-the-ledger-and-prove-who-approved-it]

You publish the obligations your regulators set, and the filing calendar follows them. A published obligation version sets the cadence, the deadline, the holiday calendar and the file layout. Each organisation starts with the platform's obligation catalogue as unpublished drafts, including the ADGM information-rights disclosures and a quarterly distribution report. Filings draw on 46 report families, among them the holder register, custody positions, the client asset summary, the safeguarding extract, dormant accounts, settlement and fails, corporate action entitlements and payments, redemptions, the distribution waterfall, privileged actions, security incidents, wallet changes and the end-of-day venue pack generated at each market close. A filing comes out as CSV, XLSX, ZIP, JSON, XML or PDF, with an authority file in the layout the obligation defines.

![Filings page with counts of filings awaiting approval, overdue and with an unconfirmed anchor, above a table of filings](https://docs.settlemint.com/docs/screenshots/console-reporting-filings-list.light.en.webp)

[Screenshot] Your reporting team sees every filing, what awaits approval and what is overdue.

A quarter ends, and once the chain is final past it the platform generates the filing and checks it against the obligation's validation rules. The Reporting officer opens it on "Filings", reads the findings and selects **Submit for review**, which makes them the maker. An Organisation owner sees the filing waiting in the Actions inbox, opens the approval dialog, which shows the filing's manifest digest, and selects "Approve". The team uploads the file to the authority's portal, and a member selects "Record submission to authority" and later "Record acknowledgement" with the authority's reference and time. The person who approved the filing cannot record its receipt. Whatever the approval policy says, a filing is approved by an organisation owner or organisation administrator other than the person who submitted it, and a platform administrator who holds neither organisation role cannot approve it.

When a supervisor asks who approved last quarter's filing, the answer is on the filing: the maker, the approver, the digest they approved and the receipt. A blocking finding stops the approval until the data is corrected, and a correction goes through a new attempt that keeps the earlier one. An organisation owner or platform administrator can still waive a period alone with **Waive period** and a written rationale, which stays on the record, so a waived period has no second person. DALP generates and tracks filings but does not upload them to a regulator's portal, so a person files each one and records the submission. An obligation fulfilled by publication records the publication instead.

A filing can also be held. An organisation owner or platform administrator opens a filing and selects **Place legal hold** with the reason, and the filing and its files stay whatever the obligation's retention class says until the hold is released. A regulator's inquiry is the usual reason: the hold records who placed it and when, and it appears on the filing with a "Release legal hold" button beside it. Until 3.2 the Console showed a hold on a filing that nothing could place.

## Let a regulator or auditor check a filing against the chain [#let-a-regulator-or-auditor-check-a-filing-against-the-chain]

An organisation owner or platform administrator can anchor each fulfilled filing of an obligation, and any investor report, as a digest in an append-only registry on the organisation's on-chain system, on the network they select. The registry holds the digest, never the file. Whoever holds the document can later check that it is the exact one the issuer committed to, without sending it anywhere.

An Organisation owner turns on **Anchor filings on chain** for the quarterly obligation, with a label, a written reason and a confirmation that the entry is permanent and public. A label that names the organisation, a period or an id-like value asks the person to confirm that it becomes public and permanent before it is stored. When the next filing is acknowledged, the platform writes its digest, and the filing links to its "Anchor registry" entry. An auditor with a Console account who received the PDF opens "Check a document", names the issuer and picks the file. The browser hashes it, and the answer says the issuer anchored exactly those bytes. Holders get the same check on an asset's Documents tab in the Console and the Investor portal.

The registry only appends, so a later entry cannot change an earlier one, and the check needs no Reporting access, so a holder can verify a notice they received. A failed anchor raises a finding and never changes the filing, so a chain outage does not make an organisation miss a deadline. Anchoring stays off until an organisation owner or platform administrator turns it on for an obligation, and it needs a document anchor registry on the organisation's on-chain system.

## Prepare FSRA venue reports and send trade reports over FIX [#prepare-fsra-venue-reports-and-send-trade-reports-over-fix]

A trading venue in the Abu Dhabi Global Market answers to the Financial Services Regulatory Authority, the FSRA. The two obligations below serve a venue there, and a venue under another regulator publishes its own obligations and file layouts. Two catalogue obligations produce the FSMR s.149 transaction and order report files as daily CSVs, each filing ending with the authority's acknowledgement. The FSRA has published no rules on what these reports hold or when they are due, so the layout, modelled on MiFIR RTS 22 and RTS 24, the daily cadence and the deadline of 23:59 Asia/Dubai on the next ADGM business day are DALP's provisional reading, and the obligations carry no validation rules. For a regulator that takes trade reports over FIX, the Financial Information eXchange protocol, a published trade journal obligation can name a FIX session, and the platform keeps that session open from inside the deployment and sends the reports itself.

A trade matches on the venue, and on its next pass the platform queues a trade report under the obligation's frozen message layout. The regulator session sends queued reports oldest first, and a regulator acceptance with its reference marks the report acknowledged. A rejection keeps the regulator's reason, and an Organisation owner corrects the report, which is rendered again from the same obligation version and sent under the same report ID. While the session is down, the trade journal downloads as a file, and the owner files it by hand and records each outcome.

Every executed trade and every bust leaves a durable report with its body, its answer and its correction history, even when the regulator's line is down. Replace the seeded submitting-entity LEI and venue code with your own before you publish the FSRA obligations.

The platform also proves that the reports reached the regulator. A daily reconciliation compares each trade and bust of a closed trading day with the report the regulator acknowledged, keeps every result as a numbered version, and raises an operations case and an alert when a day has breaks. The platform records every message of the regulator session, administrative messages included, under a retention class you set, with legal holds and a date-range export. Filings shows the session's uptime, logon history, delays and alerts for the last 24 hours, and exports the same evidence as a report. A certification script runs the new report, bust, reject and resend, and reconnect cases against a local acceptor or the regulator's test environment, and records the run with the obligation version. The FSRA's specification, test endpoint and retention period are not part of the platform: you supply them as configuration when the FSRA publishes them, and a run against the local acceptor is not a certification.

## Show the person, the role and the change behind every request [#show-the-person-the-role-and-the-change-behind-every-request]

A chain signature names only the key that signed, and says nothing of the person who clicked, their role, or a request refused before it reached the chain. The audit trail records each state-changing request to the Platform API and each read of sensitive data, with the person, their organisation role at the time, how they signed in, the participant they acted for, the operation and the outcome. When an administrator acts as another user, the entry names both. Where the operation supplies them, changes record their before and after values with secrets redacted, and maker-checker decisions name the maker and the checker.

An Organisation owner changes the withdrawal fee schedule for one asset and gives the reason "Q4 tariff". The Reporting officer opens **Audit trail** under Reporting, filters on the action and opens the entry. It names the owner, the role "Owner", the sign-in method and the reason, and shows the old and new fee. The officer then selects "Export" for the quarter and gets a CSV of every matching entry, and that export writes its own entry naming who took it.

Each organisation's trail is a SHA-256 hash chain. Once anchoring is set up for the organisation on its default network, a daily sweep anchors each closed day's chain head on chain, and until then the sweep logs the gap and tries again. An integrity read through the Platform API reports the chain intact, or names the first row that differs. Entries are kept indefinitely by default, and a deployment can set 5, 7 or 10 years, after which a day is deleted only once it is anchored, held by no legal hold and archived in an end-of-day audit report. A change the platform cannot record is refused, and so is an export. Other sensitive reads are still served and the failure is logged, and sign-in and other account events go through even when their entry cannot be written.

## Send clients statements, contract notes and trade confirmations [#send-clients-statements-contract-notes-and-trade-confirmations]

An Organisation owner sets the statement policy on **Statements**: daily, weekly, monthly or quarterly, with the sections and formats clients get. A new organisation sends monthly statements with every section in CSV and PDF. Statements cover positions, the portfolio at close, movements, profit and loss, fees, custody deposits and withdrawals, and corporate actions, and the PDF carries the organisation's theme.

An investor trades on the venue during the day. After the session closes, the platform writes a contract note with each trade, its fee, VAT and net amount, and emails it with the files attached. A later bust replaces the note with an Amended edition. At month end the investor's statement arrives the same way, and Activity offers a CSV or XLSX confirmation for each final movement on their wallets. A partner system subscribed to the statement-ready webhook learns about each statement without polling.

A holder sees only their own wallets. A position without a price shows as unpriced and is left out of the statement's total, and the total says how many it left out.

## Keep approvals and conflicting roles in separate hands [#keep-approvals-and-conflicting-roles-in-separate-hands]

An organisation owner or platform administrator picks, in one place, which of ten families of change wait for a second approver: offerings, corporate actions, trading venues, reporting, bank rail, custody operations, withdrawals, prices, wallets and administration. A family can ask for up to ten distinct approvers. On an instance SettleMint operates, a platform administrator may be SettleMint staff. Turning a family off asks for that person's wallet verification, and while administration changes are protected, another owner approves the turn-off first. The same people name pairs of roles one wallet may not hold together, such as custodian and governance on the same token, and set each pair to block, or to warn, where a conflicting grant needs a reason the audit trail keeps. Time-bound token roles and organisation ownership end on their own at their expiry.

An Organisation owner opens "Approvals" under General and turns on **Corporate actions**, which then reads "Second person required". From then on, recording a corporate action waits for a second person, and a request raised while a family is off shows "No second approval (approval off)" in Actions, never "Approved". Once the owner has saved the role-pair rules, a grant of the Governance role to the wallet that holds Custodian on the same bond is refused with "Custodian cannot be held with Governance on the same contract" before anything reaches the chain.

A report lists every wallet that holds a segregated pair, including roles granted on chain outside the platform, so an auditor sees which controls the organisation runs. Every approval family starts off, and the role-pair rules stay off until an organisation owner or platform administrator saves them.

## Check a transfer against the asset's rules before anyone signs [#check-a-transfer-against-the-assets-rules-before-anyone-signs]

Transfer pre-check answers, before anyone signs, whether a transfer would clear the asset's compliance rules. When it would not, it names each blocker it can establish and who can resolve it: the party, an operator, or nobody without changing the transfer. An investor verification can carry a date after which it no longer holds, so a claim expires when the document behind it does.

An investor fills in a transfer in the Investor portal, and before signing the sheet says that the recipient lacks a verification the asset's rules require, a blocker an operator can resolve. Nothing reaches the chain, and nobody pays gas for a transfer that would revert. A holder could delete a claim from their own identity, so a rule that excludes holders by such a claim is refused for topics such as KYC, AML and sanctions screening, and needs an explicit acknowledgement for topics such as accreditation. Sanctions screening runs through block lists the issuer controls.

A clear result reserves nothing, and the real transfer can still fail. A wallet that a compliance manager, or one of DALP's own factories, puts on the compliance bypass list skips these transfer checks, so review that list alongside the rules. A custodian's forced transfer skips them by design.

## Hold a frozen address on chain, not only in the Console [#hold-a-frozen-address-on-chain-not-only-in-the-console]

A custodian freezes a wallet on a DALP asset while a review runs. The chain now refuses a forced transfer that would deliver units into that wallet, as it already refused a mint or a transfer to it, and refuses a supply manager's burn from it. To take the units, the custodian forced-transfers them out of the frozen wallet, which a freeze still allows, or lifts the freeze. A partial freeze keeps its earlier rule: a supply manager's burn or a forced transfer draws down the frozen units it needs.

A halt on an asset that is already halted now fails with [DALP-1109](https://docs.settlemint.com/docs/api-reference/errors), the code for a halted token, and a resume on an active asset fails with [DALP-9059](https://docs.settlemint.com/docs/api-reference/errors). The Console shows "is already halted" or "is already active" for either code. An asset on an earlier token implementation, including a legacy asset type, keeps the earlier behaviour.

## Upgrading [#upgrading]

The audit trail, the approval policy and the transfer pre-check are on after the upgrade. Every approval family starts off, so an organisation owner or platform administrator turns on the ones the organisation needs, and the role-pair rules stay off until one of them saves them. Audit entries are kept indefinitely unless the operator sets a retention period. Filings, anchoring, statements and trade reports run only once the operator, whoever runs your deployment, switches regulatory reporting on for the deployment, and trade reports also need the trading venue switched on. A regulator FIX session runs only to endpoints the operator allows for the deployment. Catalogue obligations arrive as drafts, so nothing is filed until you publish one. [Decide which capabilities your deployment runs](https://docs.settlemint.com/docs/deployment/upgrade-to-3-2#decide-which-application-layers-to-switch-on).

## Why it matters [#why-it-matters]

- **Banks:** an organisation owner other than the maker approves each filing's digest, and the authority's receipt stays on the filing.
- **Exchanges, CSDs and market infrastructures:** the end-of-day venue pack, the FSRA report files and FIX trade reports to a regulator come from the same trades the venue settled.
- **Regulators:** each filing names its maker and its approver, its digest can be checked on chain once anchoring is on, and the trail shows who acted in which role.
- **Partners:** A webhook announces each client statement, so a partner's app reports to its own clients without polling.

## Next steps [#next-steps]

- [Work filings in the Console →](https://docs.settlemint.com/docs/console/reporting/filings)
- [Read the audit trail →](https://docs.settlemint.com/docs/console/reporting/audit-trail)
- [Understand reporting obligations →](https://docs.settlemint.com/docs/concepts/records-and-evidence/reporting-obligation)


# Console and Investor portal

Source: https://docs.settlemint.com/docs/changelog/dalp-3-2/console-and-investor-portal
The Console opens on what waits for your team, and your clients onboard in an Investor portal in your brand, on your domain and in their language.

**Your team starts each day from one ranked list and one inbox, and your clients work in a portal that carries your brand and speaks their language.** Operators lose time visiting every area of the Console to find their next step, and an institution that wants its investors on a front end of its own has had to build one. 3.2 gives the Console a Dashboard and an Actions inbox, and adds the Investor portal: a separate app for your clients, in your theme, on your domain and in ten languages.

Spotlight: The Console opens on what waits for your team, and the Investor portal puts your brand in front of your clients

- Approvals: One Actions inbox
- Each write: Followed until it completes
- Investor portal: On your domain, in your theme
- Languages: Ten, Arabic right to left

Operators, issuers and compliance staff work in the Console. Investors sign in to the Investor portal, accept your terms, fill in the KYC profile you define and follow their holdings there.

## Before and after [#before-and-after]

**Before 3.2:** the Dashboard showed portfolio charts, and the work waiting on a person was spread across approval queues, settings pages and role screens, so a stuck wallet or a failed submission went unnoticed until someone asked. Investors had no front end of their own, so an institution either let them into the operator Console or built a portal itself. The Console read in four languages.

**With 3.2:** the Dashboard ranks what waits on each person, the Actions inbox gathers the new approvals with the actions it already listed, and the Submissions tray follows every write until it completes. Investors sign in to the Investor portal at your address, in your theme and their language, accept your trading terms and risk disclosure, and fill in a KYC profile whose sections you define. The Console and the portal read in ten languages.

[Figure] How a client's onboarding reaches the team that reviews it. A client signs in to the Investor portal on your domain, in your theme and their language. They choose a wallet from the custody options you offer, accept the trading terms and risk disclosure, and fill in a KYC profile whose sections your organisation defines. The profile waiting for review appears in the Console Dashboard's Needs attention list. Your team decides from the Actions inbox in a sheet that explains the action first, the Submissions tray follows each write until it completes, and lists and counts update as it lands. Every screen reads in ten languages, Arabic right to left, and one theme brands the Console, the portal, platform emails and report PDFs. Labels: KYC to review; Your clients, in the Investor portal; Sign in; Your domain; In your theme and; the client's language; Choose a wallet; Onboarding; From the custody; options you offer; Accept terms; Before acting; Trading terms and; risk disclosure; KYC profile; Profile; Sections your; organisation defines; Your team, in the Console; Needs attention; Dashboard; Ranked, most; urgent first; Decide in a sheet; Actions; Explained before; anything is written; Tray follows it; Submissions; Signing, confirming,; indexing, complete; Lists update; Settled; Tiles and counts; refresh as it lands; Every screen; Ten languages, Arabic right to left. One theme brands the Console, the portal,; platform emails and report PDFs.

A client onboards in your branded Investor portal, and your team decides from one Actions inbox while the Submissions tray follows each write.

## Start the day from what waits on you [#start-the-day-from-what-waits-on-you]

The **Dashboard** ranks everything that waits on the signed-in person, most urgent first, in one "Needs attention" list. Failed operations, approvals, pending launches, KYC profiles awaiting review, low-gas wallets and invitations each become a row, and the queues a person's roles own feed the same list. Operators also see key figures with a seven-day trend, the health of the platform parts they depend on, what changed since their last visit and the views they pinned. Holders see their portfolio, and until their identity is registered, the steps that remain. A Compliance officer signs in and reads "3 KYC profiles await review" at the top, with the link that opens them.

![Actions inbox with nine actions waiting, each with its due date and a button to act on it](https://docs.settlemint.com/docs/screenshots/console-actions-pending.light.en.webp)

[Screenshot] The Actions inbox puts everything that waits for you in one list.

Assets, offerings, trading venues and votes each have an **Insights** tab with key figures against the previous period, a "Needs attention" section, how the total breaks down, how it moved and where it sits by country. Each holding shows its unrealised gain or loss, total return and 24-hour change, and the portfolio shows its value over the last 7 days. A source the Dashboard cannot read shows as one unavailable row with "Try again", never as an empty list.

## Decide approvals from one inbox [#decide-approvals-from-one-inbox]

The approvals 3.2 adds, for privileged changes, withdrawals, held deposits, held prices and filings, sit in the **Actions** inbox next to the settlements, bond payments, custody approvals and KYC updates it already listed. An operator opens "Actions" and sees "Needs you", the rows they can act on, and "Waiting on others" below it, which names who each row waits on and why. Each action opens in a sheet that explains it before anything is written, and the count on the "Pending" tab, the sidebar badge and the top bar are the same number. Investors have their own "Actions" in the Investor portal. Email goes out only when mail is set up, and only for some kinds, such as held prices, custody allow list reviews, multisig, checker and corporate-action approvals.

A person who works for several subjects picks who they act for under "Working as". Switching never adds authority, because the on-chain roles still decide what the chosen participant may do. While someone works as another participant, "Portfolio", "Activity", search and role checks use that participant's wallets alone. An API call that names the participant in `X-Participant` reads the same wallets. Signing on a multisig is the one exception: a member keeps opening and approving a multisig through their own seat whoever they work as.

## Follow each write until it completes [#follow-each-write-until-it-completes]

The **Submissions** tray follows each write through its phases: "Preparing", "Awaiting approval", "Sign in wallet", "Submitting", "Confirming on-chain", "Indexing" and "Complete". An operator who submits a mint and moves to another page finds it in the tray at the same phase, in every open tab and after a page refresh. Lists, Dashboard tiles and the pending-action count update as the work lands, so nobody refreshes a table to see whether a mint went through. An operator who sees a mistake can undo a write that offers "Undo" while it is still on its way. Undo is offered until the write is submitted, and never while a custody provider holds the request. A request the platform stopped waiting for that can still go through now reads "May still go through" in the Console and Investor portal trays, says to check it before trying again, and shows the platform's reason, instead of "Confirming on-chain".

## Give your clients a portal in your own brand [#give-your-clients-a-portal-in-your-own-brand]

The Investor portal is a separate app for your investors, with its own sign-in, showing only the areas an investor can use. It sends every platform call to its own address, so it runs on your domain and its session belongs to that domain. It refuses to load inside a frame, so it cannot be embedded in a page of your online banking or another site. An Organisation owner sets the logo, fonts and colours on the Console's **Theme** page, and the same theme brands the Console, the portal and the browser tab titles. Platform emails use the theme's name, logo and colours, and report PDFs print the organisation's legal name, disclaimer and logo. The owner publishes trading terms and a risk disclosure under "Terms and risk disclosures" in the General settings, ticking "Require participants to accept this version again" for a change that every participant must accept.

An investor signs in at the bank's portal address, sees the bank's logo, accepts the new version and only then reaches Portfolio. The acceptance record holds the participant, the version, the time, the client address and the browser, and **Export acceptances** downloads it. On a deployment several organisations share, the sign-in page shows the global theme or the default look, because the portal learns the investor's organisation only at sign-in.

## Onboard clients through the KYC profile you define [#onboard-clients-through-the-kyc-profile-you-define]

An investor who holds no wallet in the organisation yet sets up in the portal in two steps, "Wallet type" and "Your wallet". They choose from the custody options your organisation offers investors, such as an embedded wallet, a browser wallet or a managed account, and an investor who brings their own key signs a message that proves it is theirs. The investor then fills in their KYC profile: name, country, national ID and the fields your profile sections add. An administrator builds those sections under "Organisation participants" › **Profile sections**, choosing each field's type, whether it is required and whether the investor or an identity manager fills it in. A bank adds a tax residency section that the investor completes and an internal risk tier that its identity managers fill in. Every save is a new version. The investor submits it, and an identity manager approves it field by field or uses "Request update", which opens an action for the investor. The person who submitted a version cannot approve it, and each version stays in the history. Once people have answered a field, its meaning is locked, so the history of what was collected stays readable.

## Work in the language your market uses [#work-in-the-language-your-market-uses]

The Console and the Investor portal read in ten languages: English, German, Arabic, Japanese, French, Dutch, Malay, Indonesian, Thai and Korean. An Organisation owner chooses which ones its people can pick under **Languages** in the General settings, and English stays on. An investor in Riyadh picks العربية, and the portal opens right to left, with addresses, symbols and amounts kept left to right inside the Arabic text. In the Console, a failure message the platform sends in English keeps its own left-to-right direction too, so its sentence ends where it should. The names of the compliance templates, asset classes and instrument templates DALP ships appear in the chosen language, invitation and approval emails follow it, and amount fields accept digits typed the local way. Names your organisation typed itself, such as its own template names, stay as they were typed.

## Upgrading [#upgrading]

The Console changes take effect on upgrade. Every organisation starts with all ten languages on, so an owner turns off the ones its people should not see. The Investor portal is its own app: the operator deploys it on a public address of its own, as [Deploy browser apps with user sessions](https://docs.settlemint.com/docs/deployment/install/browser-apps) describes. Investor sign-in is on for every organisation unless the operator switches it off for the deployment or the organisation opts out, one of the choices when you [decide which capabilities your deployment runs](https://docs.settlemint.com/docs/deployment/install/values-secrets#switch-application-layers-on-or-off). Once an owner publishes trading terms and a risk disclosure, every participant accepts them before trading or withdrawing, and accepts again when the owner requires it for a new version, in the portal and on the Console order ticket.

## Why it matters [#why-it-matters]

- **Banks:** investors deal with the bank on its own domain and under its own brand, and the KYC profile collects the facts the bank's policy asks for.
- **Exchanges, CSDs and market infrastructures:** participants accept the published trading terms and risk disclosure before they trade, and the acceptance record exports per version.
- **Regulators:** each acceptance names the participant, the version and the time, and each KYC version names who submitted it and who reviewed it.
- **Partners:** A partner without a client front end puts the portal in front of its clients in their institution's theme and language, on an address of its own.

## Next steps [#next-steps]

- [Use the Actions inbox →](https://docs.settlemint.com/docs/console/essentials/actions)
- [Brand the Console and the portal →](https://docs.settlemint.com/docs/console/organisation-settings/theme)
- [Understand the Investor portal →](https://docs.settlemint.com/docs/concepts/operating/investor-portal)


# Custody and wallets

Source: https://docs.settlemint.com/docs/changelog/dalp-3-2/custody
Embedded wallets, Utila, weighted multisig, a custody gateway per client and network, and custody books that close each day against the chain.

**Your clients deposit and withdraw through a gateway of their own, and your custody team closes each custody day against the chain.** A bank that takes client coins, such as a stablecoin, into custody needs one deposit point per client, withdrawals that wait for screening and approval, and a daily book it can sign. 3.2 adds that gateway and those books, with embedded wallets, Utila and weighted multisig beside the custody you already run.

Spotlight: Managed keys stay with your custodian or the platform key store, and each custody day closes against the chain

- Embedded wallets: Privy and Dynamic
- New managed provider: Utila
- Custody gateway: One per client on each network
- Custody day: Versioned report, checked on chain

Managed accounts sign through DFNS, Fireblocks, Luna HSM, Ripple Custody, Utila or the platform key store, which on an instance SettleMint operates runs in SettleMint's infrastructure. Self-custody holders sign in Privy, Dynamic or a browser wallet, and DALP holds no key for them.

## Before and after [#before-and-after]

**Before 3.2:** A custodian that holds client coins on chain runs deposits, payout addresses and withdrawal approvals in one system and its books in another. Each morning someone rebuilds the previous day's position from wallet exports and checks it against the chain by hand, and a client who wants to hold their own key needs a wallet the platform does not know.

**With 3.2:** each client gets a gateway on each network that screens deposits, mints custody receipts into the client's own wallet and pays withdrawals in order. The platform reconciles every closed day from the custody journal against the chain, keeps each run as a numbered version, and records the maker who signed it, and the checker when the organisation has turned on Custody operations approval.

[Figure] A client's coins move through the gateway, and each custody day closes against the chain. A client deposits a coin at its gateway, and a deposit from an unapproved source waits for screening. A cleared deposit mints custody receipts into the client's own wallet. To withdraw, the client returns receipts to an approved payout address and they move into escrow. Screening and, at the instant limit, a second approver review the request, and the gateway pays requests in order, each in full or not at all. Each closed day, the platform reconciles the custody books against the chain as a numbered version, which a maker signs and a checker approves when the Custody operations approval is on. Every step signs through the organisation's custody provider or key store. Labels: Coin to the gateway; Client deposit; Screened before it counts; Minted to the client; Custody receipts; In the client's own wallet; Receipts into escrow; Withdrawal; To an approved address; Screening, approval; Review; Second approver at limit; Coins to the payout; Pay in order; In full or not at all; Books against chain; Each closed day; Numbered version, CSV; Maker signs, checker approves; End-of-day sign-off; A second person, when Custody operations approval is on; Every step; Signs through your custody; provider or key store.

Client deposits and withdrawals run through the gateway and its escrow, and each closed day reconciles against the chain as a numbered version.

## A flag that freezes a client whose claim lapsed [#a-flag-that-freezes-a-client-whose-claim-lapsed]

When a compliance claim a gateway's client must hold is revoked or expires, the client is flagged: its open deposits and withdrawals freeze, its payout addresses are suspended, and no move that pays or credits the client runs until the flag clears. The provider issuing the claim again clears the flag on its own, and a screener clears reviewed flags from the gateway's client-flag panel.

## Sign with your custodian, an embedded wallet or both [#sign-with-your-custodian-an-embedded-wallet-or-both]

An organisation can offer managed and self-custody signing side by side. Utila joins DFNS, Fireblocks, Luna HSM, Ripple Custody and the platform key store as a managed provider. Investors can hold a self-custody wallet in the Investor portal through Privy or a browser wallet, and Console members can also use a Dynamic embedded wallet. Each managed provider declares how it signs on each network, and DALP refuses a custody setup on a network where the provider cannot sign. One participant can hold several custody accounts across providers, such as a treasury desk on the bank's vault and a board member on their own wallet, and picks the primary account for each network.

An Organisation owner adds a Privy configuration with the Privy application ID. An investor signs in to the Investor portal, Privy creates the wallet, and the wallet appears as a custody account on the investor's wallets tab. The investor signs each transfer in Privy, and when the organisation's paymaster pays gas for the investor's smart wallet, the investor needs no native coin.

A custody change always creates a new account and never moves an existing key. DALP holds no key for a self-custody wallet, so Privy or Dynamic secures it for the holder. Both run outside the deployment, as services the organisation sets up with its own application ID. The platform key store keeps keys inside the deployment, so on an instance SettleMint operates, SettleMint runs that store, and an institution whose keys must stay with it chooses a custody provider instead.

## Require a second signer or a named checker before a wallet moves [#require-a-second-signer-or-a-named-checker-before-a-wallet-moves]

A participant account can require several signers and give each seat a weight. The creator drafts the seats, invites the signers and deploys the wallet once, and the wallet then works as a co-signing queue. For a single-key wallet whose custodian has no approval step of its own, the platform adds the wallet checker: the wallet's owner names a second member of the organisation, and every transaction from that wallet waits until that person approves it.

A fund's treasurer creates its treasury wallet with a threshold of three, with the treasurer's seat at weight two and two analysts at weight one. The treasurer and one analyst can move funds, and two analysts together cannot. On a key wallet held in the platform key store, the wallet's owner names the head of operations as checker, with a wallet verification step. Each transfer from that wallet then waits in the checker's Actions inbox until the checker decides, and the audit trail names both people.

While a threshold or a checker stands, one person cannot move the wallet alone through DALP, whichever custody it uses. Naming, replacing or removing a checker needs the owner's wallet verification, so an API key cannot remove the control, and the audit trail records the change. The wallet's owner can remove a checker alone, and co-signatures and checker decisions expire on one deadline the deployment sets.

## Take client deposits and pay withdrawals through one gateway per network [#take-client-deposits-and-pay-withdrawals-through-one-gateway-per-network]

The custody gateway gives each client one deposit and withdrawal point on each network. Against each coin it receives, it mints custody receipts, ordinary DALP assets that stand for those coins, into the client's own wallet. A gateway manager approves the payout addresses each client may use. Two organisation service wallets run the daily steps. The screener acts on the verdicts of the screening providers the organisation links to the gateway: a clear from every provider clears the record, and an unclear answer opens a review for a person. A gateway set to screen by hand waits for a person who holds the screener role. The keeper reports plain transfers and pays waiting withdrawals.

A client opens the Investor portal's Deposit dialog, which shows its gateway address as a QR code, and sends a stablecoin to it. Deposits wait in quarantine by default until the screener clears them, and a cleared deposit mints custody receipts into the client's wallet. When the client asks to withdraw, it names an approved payout address, and the platform moves the client's receipts into the gateway's escrow at once. A request at or over the instant limit, a withdrawal amount the gateway managers set, also waits for a gateway manager's approval, which a second gateway manager confirms unless a gateway permission manager changes that count. Once it is cleared and approved, the keeper pays waiting requests in the order they became payable, each in full or not at all. When the funding at hand cannot cover them, the platform records an instruction to the custodian for the missing amount.

An operator sets the gateway up in the Console under "Asset lifecycle", "Custody gateway": [enable coins, create profiles and name the keeper and screener](https://docs.settlemint.com/docs/console/asset-lifecycle/custody-gateway-setup), [create a gateway for each client](https://docs.settlemint.com/docs/console/asset-lifecycle/custody-gateway-create) and [clear, freeze, refuse, return or recover the records that wait](https://docs.settlemint.com/docs/console/asset-lifecycle/custody-gateway-review). An integrator follows a deposit or a withdrawal through the [custody gateway API](https://docs.settlemint.com/docs/api-reference/guides/custody-gateway-api), and [Deposit and withdrawal stages](https://docs.settlemint.com/docs/api-reference/guides/custody-gateway-stages) lists every stage, who moves it and its time limit.

A Console user deposits and withdraws through the same dialogs on Portfolio, and proves withdrawal wallets on Personal > Withdrawal destinations. [Withdraw from your gateway →](https://docs.settlemint.com/docs/console/my-assets/portfolio#withdraw-from-your-gateway)

The trading venue and the custody gateway share one escrow design instead of each building its own vault. Free units leave only to their owner, and only the contract that controls the escrow can lock or pay them out, with two exceptions: a holder of the token's custodian role can force free and locked units out of an escrow, and a lost wallet's free units go to its recovered wallet. Every movement keeps the escrow's books equal to its free and locked units, so the books never exceed what it holds. XvP settlement keeps its own escrow.

Every 5 minutes the platform compares each receipt's supply with the coins held at the organisation's custody addresses, and a difference that persists for two hours opens a critical case.

## Close each custody day against the chain in a versioned report [#close-each-custody-day-against-the-chain-in-a-versioned-report]

Once a day passes the cutoff the deployment sets, the platform reconciles it. It rolls each wallet's book from opening to closing, checks the closing against the chain, and checks that every venue trade delivered the legs it promised. Each run is stored as a numbered version with the chain evidence it read, and a difference opens a break that carries its age until someone resolves it. For custodial withdrawals, an owner also sets a **Withdrawal fees** schedule per asset: a flat amount, basis points of the withdrawal, or the network cost passed through with a margin. The client sees the custody fee and the network fee as two separate amounts.

An Organisation owner opens "Daily reconciliation", picks the previous day and selects **Run reconciliation**. The report shows one venue trade whose cash leg never arrived and opens a break for it. The owner assigns the break and selects "Sign for checker approval" on the latest version. With Custody operations approval turned on, a second owner approves it from the Actions inbox. The version then reads "Locked and attested". A rerun the next morning adds version 2 and leaves the signed version and its evidence untouched, and the "Download CSV" file of each version stays the same.

An auditor can see what the platform reported for a given day and the chain history it read to get there. A balance the chain cannot answer stays unavailable with its reason and is never shown as zero. The second signature is asked only once an organisation owner or a platform administrator turns on **Custody operations** under Approvals, and on an instance SettleMint operates, a platform administrator may be SettleMint staff. A run needs the deployment's cutoff to be set.

## Decide who pays gas, and hold a write until it is funded [#decide-who-pays-gas-and-hold-a-write-until-it-is-funded]

An organisation picks plain wallets or smart accounts on each network. A plain wallet pays its own gas, or an organisation relayer submits its signed requests and pays for them. A smart account can use a paymaster backed by an organisation reserve. Funding requests follow the network's live fee quote instead of a fixed amount.

An Asset manager sends a transfer while the relayer is short of gas. The chain refuses it, and the platform pauses the transfer instead of failing it. It records one funding requirement that names the wallet and the amount, and the **Transaction funding** page shows where to send the top-up. Once the top-up lands, every write that waited on that requirement continues. The funding request shows the balance the wallet held when the chain refused, and an open funding dialog takes each new balance in place.

A write still waiting when the network's funding window closes, 30 minutes by default, fails with the gas required error.

On a network with a fee policy, the maximum fee of a Ripple Custody order now uses the fee cap with the tip at the policy's ceiling, so Ripple no longer holds a write on fees only because its own price is above the quoted fee.

## Upgrading [#upgrading]

Embedded wallets, multisig, the custody gateway and the custody books are available after the upgrade. Before it, the operator decides and prepares these:

- **Utila and Ripple Custody.** Both stay off for new provider configurations until the operator enables them, as [Utila setup](https://docs.settlemint.com/docs/deployment/utila-setup#what-the-platform-operator-switches-on) describes, and existing Ripple Custody configurations keep signing.
- **Ripple policies.** 3.2 names operations differently in the intents it files with Ripple, so [update your Ripple policies](https://docs.settlemint.com/docs/deployment/upgrade-to-3-2#update-ripple-policies) before the upgrade.
- **Fireblocks.** Requests sign as a typed message or a contract call, raw signing is refused unless the operator turns it back on, and new vaults carry a tag your policy rules match, as [Update Fireblocks settings](https://docs.settlemint.com/docs/deployment/upgrade-to-3-2#update-fireblocks-settings) describes.
- **Custody census.** The migration records which custodian holds each existing wallet and stops if it cannot prove one. [Prepare the custody census](https://docs.settlemint.com/docs/deployment/upgrade-to-3-2#prepare-the-custody-census) says what to set when the legacy signer database still exists.
- **Daily cutoff.** The daily reconciliation runs only once the operator sets the deployment's daily cutoff time and time zone, as [Run the daily custody reconciliation](https://docs.settlemint.com/docs/console/organisation-settings/custody-reconciliation#before-you-start) describes.
- **Custody operations approval.** It starts off in every organisation, and an organisation owner or a platform administrator turns it on under "Approvals" in the General settings.

## Why it matters [#why-it-matters]

- **Banks:** managed keys stay with the custodian you choose, or in the platform key store, which SettleMint runs on an instance it operates, and the custody day closes with a versioned report, which a second person signs once you turn on Custody operations approval.
- **Exchanges, CSDs and market infrastructures:** venue trades and the custody gateway settle through one escrow design, and the daily report checks every delivered leg.
- **Regulators:** client coins sit against receipts in each client's own wallet, and a reserve check raises a case when supply and holdings drift apart.
- **Partners:** each supported custody provider signs through the same path, so a gateway or a wallet works the same whichever provider signs.

## Next steps [#next-steps]

- [Run the daily custody reconciliation →](https://docs.settlemint.com/docs/console/organisation-settings/custody-reconciliation)
- [Understand the custody gateway →](https://docs.settlemint.com/docs/concepts/custody-and-signing/custody-gateway)
- [Understand custody providers →](https://docs.settlemint.com/docs/concepts/custody-and-signing/custody-provider)


# Developer platform

Source: https://docs.settlemint.com/docs/changelog/dalp-3-2/developer-platform
From 3.2 v2 breaks only on a new API version or after 90 days' notice, the SDK is generated from its routes, and webhooks arrive in order.

**From 3.2 your back office builds on a v2 API that breaks only on a new API version, or after a deprecation with at least 90 days' notice.** The promise covers the v2 API that 3.2 publishes, and reaching it removes 187 operations that 3.1 published, 42 of them with no v2 successor. The TypeScript SDK is generated from the same routes, and each webhook endpoint receives its events in order. The payloads of the event families 3.2 adds, apart from gas funding requirements, are beta and can still change inside v2. Once your organisation connects its own Xero app, DALP posts each final money event your rules map to that Xero ledger, once.

Spotlight: A v2 contract that holds from 3.2, and a client generated from its public routes

- v2 API: Stable from 3.2
- Deprecation notice: At least 90 days before a sunset
- Webhooks: In order, per endpoint
- From the 3.1 SDK: Code changes needed for 3.2

A breaking change ships on a new API version, next to the one you call, and an operation leaves v2 only after its sunset date. The SDK's types come from the same declaration as the routes they call.

## Before and after [#before-and-after]

**Before 3.2:** in 3.0 and 3.1, v2 could change between releases, so an upgrade could move a field or drop an operation that a back-office job relied on. Webhook events carried no sequence per endpoint, so a consumer that posts to a ledger had to put them in order itself.

**With 3.2:** v2 follows a written contract: no new required input, no narrowed input and no removed response field inside the version, and an operation leaves v2 only after a deprecation that gives at least 90 days' notice. A build check refuses a removed operation or parameter and a newly required input, and review catches a narrowed input or a removed response field. An operation that is going away says so on every response. The SDK and the CLI are generated from the public v2 routes, most reads can be revalidated with an ETag, and each webhook endpoint receives its events in sequence.

[Figure] How an integration calls the v2 API and receives its events. Your back office calls the v2 API through the TypeScript SDK, which is generated from the public v2 routes. From 3.2 a breaking change to v2 ships only on a new API version. Most reads carry an ETag and answer 304 when nothing changed. A write returns the settled resource, or a handle to follow when it has not settled within its wait. Every event takes the next number in each endpoint's sequence and is delivered signed and in order, a correction after its cause. An operation that is going away answers with the Deprecation and Link headers, and with Sunset once a sunset date is set, at least 90 days after the deprecation. Labels: Signed, retried; Your integration; Your system; Back office and; reporting systems; Generated client; SDK; From public routes,; one flat argument; v2 API; Stable from 3.2; Breaking changes; only on a new version; Cacheable reads; Reads; ETag, and 304 when; nothing changed; Settled or handle; Writes; A slow write; returns a handle; When an operation goes away; Deprecation and Link headers on every response, then Sunset; once a sunset date is set, at least 90 days after deprecation; Event recorded; Event; Named in the public; event catalogue; Next in sequence; Order; Per endpoint, a fix; after its cause; Signed delivery; Your endpoint; Retried. You drop; repeats by event id.

Your back office calls the v2 API through the generated SDK, reads revalidate with an ETag, and each webhook endpoint receives signed events in order.

## Build against a v2 contract that holds from 3.2 [#build-against-a-v2-contract-that-holds-from-32]

From 3.2, the [versioning policy](https://docs.settlemint.com/docs/api-reference/guides/versioning-and-deprecation) keeps breaking changes off v2: a breaking change ships only on a new API version, served next to the current one, and an operation leaves v2 only after its sunset date. A Developer at the bank finds out early when an operation is going away. Every response from it, error responses included, carries the `Deprecation` and `Link` headers, and the `Sunset` header once a sunset date is set. That date is at least 90 days after the deprecation, the `Link` header names each successor path, and the OpenAPI contract marks the operation deprecated, so the team plans the move on a known date. `/api/v1` takes no new operations, and 3.2 removes three v1 user and wallet operations and the single-wallet fields on v1 user reads, each with its successor in the [integration upgrade guide](https://docs.settlemint.com/docs/api-reference/guides/upgrade-to-3-2#removed-v1-operations). A release can still add operations, response fields and new errors inside v2, so a client handles errors by their class and the `retryable` flag and ignores fields it does not know.

![Webhooks page with the endpoint count, 24-hour deliveries and success rate, a chart and a table of endpoints](https://docs.settlemint.com/docs/screenshots/console-organisation-webhooks.light.en.webp)

[Screenshot] Your integration team sees each endpoint's deliveries and success rate.

## Call the API through a client generated from its routes [#call-the-api-through-a-client-generated-from-its-routes]

The SDK's route tree and types are generated from the platform's public v2 routes, so the compiler catches a call whose shape the platform would refuse. Every route sits under `dalp.api` and takes one flat object, as in `dalp.api.token.read({ assetId })`. A write resolves with the settled resource, or with a handle carrying `transactionId` and `statusUrl` when it has not settled within its wait, and every route has TanStack Query factories whose cache keys the SDK derives from the call. The `dalp` CLI is generated from the same routes and puts the verb first, as in `dalp get contacts`. A Developer upgrades the package, compiles, and gets a type error at each call, import and option that changed. Code written against the 3.1 SDK does not compile unchanged, and the [SDK migration guide](https://docs.settlemint.com/docs/api-reference/sdk/migration) lists each change. Venue setup, trade busts and venue report replay are in the v2 API reference but have no SDK operation, so a client calls them over HTTP.

## Read again only what changed [#read-again-only-what-changed]

With response caching on, as it is by default, most v2 reads return an ETag, as [response caching](https://docs.settlemint.com/docs/api-reference/guides/response-caching) describes, so a client asks whether a resource changed instead of downloading it again. A reporting job that polls positions every minute sends the stored tag in `If-None-Match` and gets `304` with no body while nothing changed. Cached responses are kept apart per caller, by organisation, user, roles and the participant the request acts as. After a write, that user's reads wait for the cache to catch up for a configurable window, 60 seconds by default, so the job never reads data from before its own write. Some reads, such as custody reconciliation and deposits, carry no tag, as [which reads carry a tag](https://docs.settlemint.com/docs/api-reference/guides/response-caching#which-reads-carry-a-tag) lists, so a client stores a body without one and reads it again in full.

## Receive events in the order they happened [#receive-events-in-the-order-they-happened]

Each webhook endpoint receives its events in the order the platform produced them. Every event takes the next number in the endpoint's own sequence and waits while an earlier event for that endpoint is still pending, and a retraction waits until the event it corrects has been delivered or settled. 3.2 adds event families for fees, corporate actions, venue order status, announcements and settlement fills, compliance verdicts, gas funding requirements, operations cases, role grants that are about to expire, custody gateway deposits and withdrawals, and bank rail credits and cash-outs. Every event name is in the public catalogue at `/.well-known/dalp-events.json`, and a subscription that names no published event is refused when the endpoint is registered. A Developer subscribes the bank's ticketing endpoint to `operations.case.*`, so each case an operator works in the Console opens and closes a ticket without polling. A ledger subscribed to `token.fee.final` posts fees in the order the platform recorded them. Delivery is at least once, so a consumer removes duplicates by the event's id. A pending event holds the later ones until it is delivered, fails for good or reaches the end of its three-day retry window, and an event that waits for chain finality holds nothing back, so it can arrive after events recorded later. Apart from gas funding requirements, the event families 3.2 adds are beta in the event reference, which means their payloads can still change inside v2.

## Post each money event to your Xero ledger once [#post-each-money-event-to-your-xero-ledger-once]

Your organisation's books stay in its own Xero ledger, and DALP posts the money movements to it. An organisation administrator connects the organisation's own Xero app while signed in to the Console, so the deployment holds no shared Xero credentials. DALP then posts each final money event the organisation's rule table maps, such as a trade settlement, a fee, a bank rail credit or cash-out or a paid dividend, as one Xero manual journal, and posts it once, across retries, crashes and configuration changes. The organisation's posting policy sends one journal per trade, the default, or one balanced journal for each day. A trade bust or another retraction posts as the reversal of its original journal, on the same Xero account codes the original used, even when the account mapping changed after the original posted. Every event leaves a posting record that says what happened to it, and an event that cannot post raises an "Accounting event blocked", "Accounting posting failed" or "Xero connection needs attention" case, which your team works with its other operations cases in the Console. DALP never chooses accounts. It posts nothing until the organisation stores its rule table, account mapping and posting policy and connects Xero, and the deployment must be able to reach Xero. In 3.2 DALP does not post mirror-token issuance and burn, or the coupon and maturity redemption cash paid on each claim. [Post DALP events to a ledger →](https://docs.settlemint.com/docs/api-reference/guides/accounting-feed)

Your organisation's owner reads every posting record on the Console's "Accounting" page under Organisation settings: what posted and to which Xero journal, what is still waiting, and why a record failed, in plain words next to Xero's own message. When Xero refuses a journal, the owner fixes the cause in Xero or in the configuration and selects "Retry posting". DALP checks Xero for a journal it already sent before it builds one again, so a retry never posts the same journal twice, and an event no rule covered is decided again with the newest configuration. An integration reads and retries the same records through the v2 API.

## The v1 API cannot bypass maker-checker [#the-v1-api-cannot-bypass-maker-checker]

When an organisation protects a group of changes with maker-checker, a v1 write whose v2 route that group would hold is refused with `403` before anything runs, and the refusal names the v2 route that can hold it for a second user. Four v1 writes gain a `403` they did not publish before: registering an external token, requesting a KYC profile update, creating a user and revoking a user's session. [v1 writes under maker-checker →](https://docs.settlemint.com/docs/api-reference/guides/upgrade-to-3-2#v1-writes-under-maker-checker)

## Upgrading [#upgrading]

The breaking changes land in 3.2 itself, before the v2 rule takes hold. Regenerate your client from the 3.2 OpenAPI document and compile: 187 v2 operations that 3.1 published are removed, 145 of them with a successor, some v2 requests gain required fields, and some response rows change shape. Existing routes also gain new refusals, which no compiler shows. Three v1 operations are removed, v1 user reads lose their single-wallet fields, and a v1 write is refused while maker-checker protects its v2 route. Error bodies drop the `defined` field on both versions, and CLI scripts move to the verb-first commands. A client that retries webhook registration with the same idempotency key gets the first endpoint back, without its signing secret, so store the secret from the first response. [Upgrade an integration to DALP 3.2](https://docs.settlemint.com/docs/api-reference/guides/upgrade-to-3-2) lists every change with its successor and how to detect it.

## Why it matters [#why-it-matters]

- **Banks:** core-banking and reporting integrations built on v2 hear about each deprecation on every response, with the successor named, long before anything goes away.
- **Exchanges, CSDs and market infrastructures:** post-trade and surveillance systems receive order, settlement and corporate-action events in sequence per endpoint.
- **Partners:** A partner generates its client from the same OpenAPI contract and receives webhook events signed and in order per endpoint.

## Next steps [#next-steps]

- [Read the versioning and deprecation policy →](https://docs.settlemint.com/docs/api-reference/guides/versioning-and-deprecation)
- [Upgrade an integration to DALP 3.2 →](https://docs.settlemint.com/docs/api-reference/guides/upgrade-to-3-2)
- [Understand webhook delivery →](https://docs.settlemint.com/docs/concepts/events-out/webhook-delivery)


# Income and corporate actions

Source: https://docs.settlemint.com/docs/changelog/dalp-3-2/income-and-corporate-actions
Split, buy back, pay income and run holder votes on the token investors already own, with a holder-by-holder review and an optional second approver.

**Split, consolidate, buy back, pay income and put resolutions to holders on the token they already hold.** A corporate action on a tokenised security has usually meant burning the old token, issuing a new one and reconciling two registers, with the cash paid from somewhere else. In DALP 3.2 the action runs against each holder's balance of the same token, from one record that keeps its terms, its review and the transactions that applied it.

Spotlight: One record holds the terms, the review, the approval and the transactions that applied them

- Action types: Thirteen, from cash dividend to spin-off
- Supply changes: Mint or burn on each holder's balance
- Second approver: Once your organisation turns it on
- Votes: Resolutions executed after a timelock

Your institution decides the event and its legal terms. DALP stores those terms on the action, shows every holder's change before anything moves, and links the record to the transactions that carried it out.

## Before and after [#before-and-after]

**Before 3.2:** A split or a capital decrease meant reissuing the token or adjusting balances one wallet at a time, then proving the new register matched the old one. Dividends were calculated in a spreadsheet and paid by a separate system, and a board resolution that changed the instrument waited for someone to carry it out by hand.

**With 3.2:** the Console records thirteen corporate action types: cash dividend, distribution, bond coupon, maturity redemption, conversion, bonus issue, rights issue, capital decrease, stock split, spin-off, partial redemption, buyback and coordinated distribution. A supply change mints or burns against each holder's balance of the existing token, so the register before and after the event is one holder history. Income pays out from a treasury you fund, a sensitive action can wait for a second approver, and a resolution that passes a holder vote is queued and, after a timelock, executed to apply its changes to the token.

[Figure] How a corporate action runs on the live token. An operator records the action and its terms. The review shows each holder's balance before and after and the snapshot the figures come from. Wallet verification records the action. When the organisation's approval rule for corporate actions is on, a second approver decides it first. The action then runs on the existing token: a supply change mints or burns against each holder's balance, and income pays out from a treasury the issuer funds. The record keeps the terms and links the transactions that applied them. Labels: Record action; Terms; Ratio, dates, cash; Every holder; Review; Before, after, snapshot; Wallet verification; Confirm; Records the action; Second; When rule is on; approver decides; Same token, one holder history; Runs on the live token; No burn and reissue for a split, bonus issue, capital decrease or buyback; Mint or burn per holder; Supply change; Cash buybacks pay as they burn; Paid from your treasury; Income; Holders claim what they are owed.

A corporate action runs on the existing token after review and any second approval, and its record links the transactions that applied it.

## Change supply without reissuing the token [#change-supply-without-reissuing-the-token]

A stock split, reverse split, bonus issue, capital decrease, partial redemption or buyback becomes a mint or burn against each holder's balance of the token itself. A supply change can let holders elect whether to take part before a deadline, and holders who do nothing get the default option. An issuer records a 2-for-1 split, and the review lists every holder under "Holder", "Before", "After" and "Change", with the holders receiving, the supply before and after and the snapshot the figures come from. **Split shares** then records it with the issuer's wallet verification and runs it, or "Send for approval" hands it to a second approver. When the allocations change after the review, the Console shows "Holdings changed since you opened this review. Check the new figures." and the platform refuses the stale confirmation. The register after the split is the same token's register, with no holder left on a retired token.

![Review step of a bonus issue on Capped Tech Shares with the supply before and after and each holder's balance](https://docs.settlemint.com/docs/screenshots/console-corporate-action-preview.light.en.webp)

[Screenshot] An issuer reviews what a bonus issue changes for each holder before confirming it.

From the moment a supply change is recorded until it completes or is aborted, the platform refuses another supply change and a plain mint or burn on that asset, whether or not the action needs an approver. Spin-offs and tradable rights issues mint onto a separate token, and a rights issue can instead add the entitled holders to the allow list of an existing sale. The platform enforces the one-at-a-time rule on its own routes, so a supply manager who calls the token contract directly can still mint or burn.

A holder who exercises every right in a tradable rights issue can apply for excess shares in the Investor portal and pays for them in the subscription asset when applying. At close, the lapsed rights are shared among the applicants pro-rata to what each applied for and rounded down to whole shares. The **Excess applications** table in the review shows each applicant with "Applied for", "Paid", "Allocated" and "Refund". Closing mints the allotted excess with the exercised shares and refunds the rest of each payment in the subscription asset. When the organisation turns on approval for corporate actions, the excess allotment waits for the same second approver as the rest of the close.

## Hold sensitive actions for a second approver [#hold-sensitive-actions-for-a-second-approver]

When your organisation turns on the **Corporate actions** row of its approval policy, recording a sensitive action waits for a second person. That covers a stock split, a rights issue, a capital decrease, a partial redemption, a buyback that pays cash, a dividend, coupon or distribution paid in tokens, the funding of a cash dividend, coupon or distribution, and a coordinated distribution across share classes. The approver is another organisation owner or a platform administrator, and cannot be the person who recorded the action or ran its last preview. On an instance SettleMint operates, a platform administrator can be SettleMint staff. A company secretary records a capital decrease, and a second organisation owner sees the same holder table and cash card before approving it. The rule is off by default, and while it is off, or while the organisation has no other owner who could approve, the Console warns that the action runs on the signature of whoever confirms it.

## Pay dividends and interest from a treasury you fund [#pay-dividends-and-interest-from-a-treasury-you-fund]

Two income types join the coupon. Dividend yield pays a declared amount per unit on a payment date you choose, and interest yield accrues on a deposit or fund at an annual rate, continuously or on an ACT/360 day count. Income does not arrive in holders' wallets on its own. Each holder claims what the register at the record date entitles them to, from a treasury you fund in an on-chain payout asset such as a stablecoin. Before a dividend is declared, the platform checks that the payout asset can reach the treasury and the 250 largest entitled holders, and refuses the declaration when one of them could not receive it. Holders beyond those 250 are not checked at declaration, and the check reports that it stopped there. An issuer paying a dividend in a stablecoin learns at declaration, before any money moves, that one holder's wallet cannot receive that stablecoin. An instrument with several share classes can pay them through a distribution waterfall, which takes one pool from the treasury and splits it across the classes by rank. A holder opens **Collect all** and collects every return one wallet is owed from one screen, and each claim is still its own transaction.

## Buy back units only against cash [#buy-back-units-only-against-cash]

A buyback or partial redemption that pays cash burns each holder's units and pays them in the same transaction, so no holder's units burn without that holder's payment. The confirmation is refused while the paying treasury holds less than the plan owes, and the review and approval screens show the cash paid per holder and where it is paid from. A fund buying back units at a set price sees the shortfall before the first unit burns. Burn and payment settle together in batches of up to ten holders, so a run that stops part way leaves the paid batches applied until a follow-up pays the rest.

## Let holders vote on resolutions that execute [#let-holders-vote-on-resolutions-that-execute]

A vote asks a token's holders to approve a resolution, choose between options or answer a poll, and a poll changes nothing on the token. A governance manager creates the vote with a record date, and each holder's weight is the voting power they have activated by that date, by delegating it to themselves or to someone else with "Activate voting power". A resolution can carry changes from a fixed list of token operations, such as the supply cap, the yield schedule, maturing the token or fee rates. Once it passes, the governance manager chooses **Queue for execution**, and "Execute" after the timelock delay applies those actions to the token. Fund holders who vote to raise the supply cap see the new cap land on the token once the governance manager executes the passed resolution, with the ballots and the outcome on record. A holder who has not activated voting power before the record date carries no weight, and a holder of the token's governance role can cancel a queued resolution during the delay.

## Pay a recovered wallet its coupons and interest [#pay-a-recovered-wallet-its-coupons-and-interest]

A wallet that identity recovery marked lost can no longer claim fixed-yield coupons or interest, and the Actions list no longer offers it the claim. The `recovered-wallet-claims` routes of the fixed treasury yield and interest yield features pay what the lost wallet is owed to its replacement wallet.

## Post each coupon claim and redemption to your ledger [#post-each-coupon-claim-and-redemption-to-your-ledger]

When a holder claims a coupon or redeems a bond at maturity, the platform sends `token.coupon-claim.final` or `token.maturity-redemption.final` once the block is final, with the cash amount, the payout asset and the holder. The accounting team posts each claim's cash when the holder receives it, instead of booking the coupon when it is recorded. The posting preset maps both events. An organisation that stores its configuration from the preset adds a `servicing.redemptions.<suffix>` account for each quote asset in its ledger currency, and writes its configuration again, as [Bond payout events](https://docs.settlemint.com/docs/api-reference/guides/accounting-feed#bond-payout-events) describes.

## Upgrading [#upgrading]

Corporate actions and dividends run only where the operator, whoever runs your deployment, keeps offerings on. That is the default in 3.2, and a deployment whose operator turns offerings off has no corporate actions or dividends either, as [Decide on the offerings surfaces](https://docs.settlemint.com/docs/deployment/upgrade-to-3-2#decide-on-the-offerings-surfaces) describes. Existing assets and their coupons keep working. Dividend yield, interest yield, distribution waterfalls and holder elections need token features that 3.2 adds, so an organisation runs System updates before it attaches them. Integrations should expect a mint or burn to be refused while a supply change on the asset is in progress, as [Mint and burn during a corporate action](https://docs.settlemint.com/docs/api-reference/guides/upgrade-to-3-2#mint-and-burn-during-a-corporate-action) describes. The approval rule for corporate actions starts off, so an organisation that wants a second approver turns it on in its approval policy.

## Why it matters [#why-it-matters]

- **Banks:** coupons, dividends and interest pay from a treasury your institution funds and controls, with a second approver when your policy asks for one.
- **Exchanges, CSDs and market infrastructures:** A split or consolidation keeps one token and one holder history, so listings, positions and the register carry on through the event.
- **Regulators:** each action keeps its terms, its review, who approved it and the transactions that applied it in one record.

## Next steps [#next-steps]

- [Understand corporate actions →](https://docs.settlemint.com/docs/concepts/issuing-and-markets/corporate-action)
- [Run a vote through the API →](https://docs.settlemint.com/docs/api-reference/guides/governance)
- [Understand denomination assets →](https://docs.settlemint.com/docs/concepts/modeling-assets/denomination-asset)


# DALP 3.2

Source: https://docs.settlemint.com/docs/changelog/dalp-3-2
DALP 3.2.0, dated 11 November 2026, runs an instrument for its whole life, from issuance to trading, on the deployment you choose.

**Minting a token is easy. Running the instrument is the work.**

Creating the token is one step. Running the instrument lasts its whole life: the first sale to eligible investors, coupons and dividends, splits and holder votes, a secondary market, cash that has to match the bank, and the filings a regulator expects on its own calendar. Where those steps run on spreadsheets and registers re-keyed between systems, a regulated institution reconciles by hand, pays for errors and refunds, and cannot show who acted on whose authority.

DALP 3.2 runs the instrument from issuance to trading on the deployment you choose: corporate actions on the live token, offerings that take money only from eligible investors, a compliant venue you operate, and an assistant that drafts while your team decides. Your institution keeps the legal terms, the cash and the decisions. An agent acts only inside an on-chain mandate your organisation owner sets, which lists the calls it may make, caps its transfer and approval amounts per transaction and per period, and expires. A mandate does not cap the size of a mint or burn. Managed keys stay with the custodian or key store you choose, and on an instance SettleMint operates, SettleMint runs the platform key store.

[Figure] The four stages of an instrument and the four pillars under them. An instrument moves through four stages: issuance, lifecycle management, primary offering and secondary trading. Under every stage run four shared pillars: integration and operations, control and security, deployment and operations, and the assistant. Each stage draws on the same identity checks, compliance rules, approval policy and audit trail, and an organisation turns each approval rule on for itself. Labels: 1. Issuance; Templates you publish; Register at a record date; 2. Lifecycle management; Corporate actions and votes; On the live token; 3. Primary offering; Only eligible investors; Fund dealing at NAV; 4. Secondary trading; A venue you operate; Token rules decide delivery; Under every stage; Integration and operations; Your systems get signed, ordered events as records settle; Control and security; Your keys, your approval rules, one audit trail; Deployment and operations; Your own cluster or an instance SettleMint operates; Assistant; Drafts while your team decides and signs.

Four stages carry an instrument from issuance to trading, and four shared pillars run under every stage on one audit trail.

Release date: 11 November 2026. In this release the Bloomberg and LSEG price requests follow each vendor's documentation and have not run against the live services. The release changes the SDK and both API versions, so operators and integrators start an upgrade from [Compatibility](#compatibility).

## Issuance [#issuance]

Your organisation decides which instrument templates its issuers may use, and for an asset issued with balance history it can answer who held a security on a record date, down to the owners behind a nominee.



### [Design and issue your own instrument types](https://docs.settlemint.com/docs/changelog/dalp-3-2/instruments-and-documents)

Issue from the templates your organisation published, two new sukuk among them, and read the holder register at a record date, reconciled against total supply and looked through to the owners behind a nominee.



## Lifecycle management [#lifecycle-management]

Your team can split, buy back, pay income and put resolutions to holders on the token investors already hold, with one holder history through every event.



### [Run corporate actions on the live token](https://docs.settlemint.com/docs/changelog/dalp-3-2/income-and-corporate-actions)

Review every holder's change before anything mints or burns, pay income from a treasury you fund, and execute a resolution holders passed on the token after a timelock.



## Primary offering [#primary-offering]

Your institution can place a new issue only with investors the token's own rules admit, and settle a fund's dealing days at its NAV.



### [Place new issues only with eligible investors](https://docs.settlemint.com/docs/changelog/dalp-3-2/primary-offerings)

A purchase the token's compliance rules refuse takes no money, and a raise that misses its minimum keeps every refund owed in the contract. Book-built offerings add a greenshoe and lock-ups by investor category.



## Secondary trading [#secondary-trading]

You can open a venue you operate, where a trade delivers only when each token's compliance rules allow it.



### [Open a compliant venue to trade and distribute your assets](https://docs.settlemint.com/docs/changelog/dalp-3-2/trading-venue)

Run order books, auctions and a trading calendar on a venue you operate, and send your surveillance provider a copy of every order and trade over FIX, the Financial Information eXchange protocol. DALP does not bring liquidity to a venue, and reversing a busted trade is a forced transfer, which skips the transfer rules by design.



## Integration and operations [#integration-and-operations]

Your back office and data vendors work from the records DALP keeps, your systems get signed, ordered events as records settle, and your clients work in a portal under your brand.



### [Build on one stable API and a generated SDK](https://docs.settlemint.com/docs/changelog/dalp-3-2/developer-platform)

Build on a v2 API whose breaking changes ship only on a new API version, with a TypeScript SDK generated from the platform's public routes and webhooks delivered in order to each endpoint. The payloads of the event families 3.2 adds, apart from gas funding requirements, are beta and can still change inside v2. Connect your own Xero app, and DALP posts each final money event your rules map as a manual journal, once, while your organisation's owner sees every posting in the Console and retries one that failed.

### [Move bank money and tokens together](https://docs.settlemint.com/docs/changelog/dalp-3-2/bank-rail)

Mint once for each credit your bank confirms over its own FIX session, pay redemptions only to bank accounts a second Bank rail manager approved, and see when the bank balance and the token supply disagree.

### [Publish checked provider prices to your tokens' price feeds](https://docs.settlemint.com/docs/changelog/dalp-3-2/market-data)

Provider prices reach your tokens' price feeds only after the platform checks them, and with the Prices approval rule on, a move past its tolerance waits for a second approver. The Bloomberg and LSEG requests follow each vendor's public documentation and have not run against the live services.

### [Give your team one inbox and clients a branded portal](https://docs.settlemint.com/docs/changelog/dalp-3-2/console-and-investor-portal)

Your team starts from a ranked Dashboard and one Actions inbox, and your clients get the Investor portal, a separate app in your theme, on your domain and in ten languages.



## Control and security [#control-and-security]

Your institution decides who holds the keys and which changes need a second person, and can show a regulator who acted, in which role and with what outcome.



### [Hold and sign with the custodian and controls you choose](https://docs.settlemint.com/docs/changelog/dalp-3-2/custody)

Give each client a custody gateway to deposit and withdraw through, close each custody day against the chain, and choose embedded wallets, Utila custody or multisig shared accounts alongside the custody you already run.

### [Generate the filings you owe and prove who approved them](https://docs.settlemint.com/docs/changelog/dalp-3-2/compliance-and-reporting)

Generate each filing from platform data on the schedule your published obligations set, with someone other than its maker approving it. Keep one audit trail of the person, their role and the outcome of each change made through the Platform API, send clients their statements, and put a second approver on the changes your policy names.



## Deployment and operations [#deployment-and-operations]

DALP runs in your own Kubernetes or OpenShift cluster, air-gapped where you need it, or on an instance SettleMint operates, and one organisation can work across several networks. On an instance SettleMint operates, a platform administrator may be SettleMint staff. Features that call an outside service, such as the assistant, Ask AI, embedded wallets and vendor price sources, need that access allowed.



### [Run several networks and recover stuck transactions](https://docs.settlemint.com/docs/changelog/dalp-3-2/networks-and-operations)

Run one organisation on several networks, manage from the Console the node endpoints behind Ledger Data, the platform's queryable copy of each network's chain data, and recover a stuck transaction or hold it for a person after recovery asks every configured endpoint about it.



## Assistant [#assistant]

Your team gets drafts prepared from the data each member can already read. Every write waits for a member's signature, or runs as an agent inside the on-chain mandate the organisation owner sets and can revoke, which caps transfer and approval amounts and does not cap a mint or burn.



### [Let the assistant draft while your team decides](https://docs.settlemint.com/docs/changelog/dalp-3-2/ai-assistant)

Ask the Console about the page you are on and get a filled-in draft to check and sign, while watchers an owner switches on post what needs attention to the Actions inbox. Once a provider key is set, questions and the records they cite go to an outside model provider, documents included unless an owner chooses Mask.



## Who it is for [#who-it-is-for]

- **Banks** that want tokenised deposits, bonds and funds serviced inside their own controls, with managed keys at the custodian they chose and a second approver on the actions their policy names.
- **Exchanges, CSDs and market infrastructures** that need corporate actions on the live token, book-built offerings with a greenshoe and category lock-ups, a venue they operate, FIX drop copy and a register that reconciles at a record date.
- **Regulators and the teams that answer them**, who get compliance enforced on each ordinary transfer of the token, with forced transfer and the compliance bypass list named as its exceptions, an audit trail of who acted in which role, and filings generated from platform data.
- **Partners** that bring core banking, custody or market data, and put DALP next to them as the asset leg through the [v2 API and its SDK](https://docs.settlemint.com/docs/changelog/dalp-3-2/developer-platform).
- **Existing customers**, who read [Compatibility](#compatibility) before they upgrade.

## Compatibility [#compatibility]

You can upgrade to 3.2 from 3.1 or directly from 3.0. Operators follow [Upgrade a deployment to DALP 3.2](https://docs.settlemint.com/docs/deployment/upgrade-to-3-2), and integrators follow [Upgrade an integration to DALP 3.2](https://docs.settlemint.com/docs/api-reference/guides/upgrade-to-3-2). Both guides hold every step. The operator is whoever runs the deployment: your platform team, or SettleMint on an instance it operates.

Before the upgrade, operators plan for these:

- **Which steps apply.** A deployment on 3.1.19 or later takes every step in the guide. One on an earlier 3.1 patch also decides on the original asset families and, before 3.1.12, on Fireblocks Gas Station, and one on 3.0 takes the 3.1 steps a direct upgrade skips, as [Which steps apply to you](https://docs.settlemint.com/docs/deployment/upgrade-to-3-2#which-steps-apply-to-you) lists.
- **In-flight work.** Workflows still running on 3.1 do not continue on 3.2, so let every transaction request, issuance run, corporate action run, invitation and identity recovery finish first, as [Finish in-flight work](https://docs.settlemint.com/docs/deployment/upgrade-to-3-2#finish-in-flight-work) describes.
- **A backup first.** A Helm rollback leaves the database migrated, so take a database backup before the upgrade, as [Take a recovery point](https://docs.settlemint.com/docs/deployment/upgrade-to-3-2#take-a-recovery-point) describes.
- **A maintenance window.** The upgrade replaces the Platform API's services in one step, so plan a maintenance window rather than a rolling upgrade, as [Run the Helm upgrade](https://docs.settlemint.com/docs/deployment/upgrade-to-3-2#run-the-helm-upgrade) describes. The Platform API answers again once the new pods are ready, and the guide gives the window no fixed length, so size it on a rehearsal.
- **Values the 3.2 chart ignores.** The 3.2 chart does not reject a 3.1 values key it no longer reads, and it deploys no RPC gateway, so each network takes its node endpoints directly. Move those values first, as [Move your values to the 3.2 chart](https://docs.settlemint.com/docs/deployment/upgrade-to-3-2#move-your-values-to-the-32-chart) lists.
- **Ripple custody.** DALP renames the operation names it sends on Ripple intents, so an organisation on Ripple custody updates its policies first, as [Update Ripple policies](https://docs.settlemint.com/docs/deployment/upgrade-to-3-2#update-ripple-policies) describes and the [Ripple policy reference](https://docs.settlemint.com/docs/deployment/ripple-policy#operation-names-that-changed-from-31-to-32) lists.
- **Fireblocks signing.** 3.2 refuses Raw signing by default and tags the vaults it creates, so check your Fireblocks policy first, as [Update Fireblocks settings](https://docs.settlemint.com/docs/deployment/upgrade-to-3-2#update-fireblocks-settings) describes.
- **The custody provider check.** With account abstraction on, the pods do not start unless the platform's custody provider can sign user operations on each enabled network, as [Check that the custody provider signs user operations](https://docs.settlemint.com/docs/deployment/upgrade-to-3-2#check-that-the-custody-provider-signs-user-operations) describes.
- **The custody census.** The migration records which custodian holds each existing wallet and stops on a wallet it cannot place, as [Prepare the custody census](https://docs.settlemint.com/docs/deployment/upgrade-to-3-2#prepare-the-custody-census) describes.
- **Which capabilities run.** After the upgrade every organisation can run offerings, where 3.1 shipped them off, and the same decision covers corporate actions and dividends, as [Decide on the offerings surfaces](https://docs.settlemint.com/docs/deployment/upgrade-to-3-2#decide-on-the-offerings-surfaces) describes. Secondary trading, regulatory reporting with the holder register exports, and the FIX drop copy to a surveillance provider run only once the operator switches them on, so [decide which capabilities your deployment runs](https://docs.settlemint.com/docs/deployment/upgrade-to-3-2#decide-which-application-layers-to-switch-on), with every default in [the deployment reference](https://docs.settlemint.com/docs/deployment/install/values-secrets#switch-application-layers-on-or-off).
- **The assistant and Ask AI.** No question leaves the deployment for a model provider until a provider key is set, and the platform key also turns on Ask AI on the documentation site for anyone who can reach it, so decide whether to share the key, give Ask AI its own key or keep Ask AI off, as [Decide on Ask AI](https://docs.settlemint.com/docs/deployment/upgrade-to-3-2#decide-on-ask-ai) and [Ask AI provider key](https://docs.settlemint.com/docs/deployment/install/values-secrets#ask-ai-provider-key) describe.
- **The original asset families.** 3.2 refuses new assets in the seven original families unless the operator allows them, as [Decide on legacy asset creation](https://docs.settlemint.com/docs/deployment/upgrade-to-3-2#decide-on-legacy-asset-creation) describes.
- **The index rebuild.** DALP rebuilds its data for each network after the upgrade, and reads keep answering from the existing data until it has caught up, as [Watch the index rebuild](https://docs.settlemint.com/docs/deployment/upgrade-to-3-2#watch-the-index-rebuild) describes.

Integrators plan for these:

- **The TypeScript SDK breaks.** Code written against the 3.1 SDK does not compile unchanged, as [The TypeScript SDK](https://docs.settlemint.com/docs/api-reference/guides/upgrade-to-3-2#the-typescript-sdk) and the [SDK migration guide](https://docs.settlemint.com/docs/api-reference/sdk/migration) describe.
- **187 v2 operations are removed.** 145 of them have a successor and 42 have none, and [Removed v2 operations](https://docs.settlemint.com/docs/api-reference/guides/upgrade-to-3-2#removed-v2-operations) lists each one.
- **Error bodies drop `defined`** on v1 and v2, so identify a failure by `data.id`, as [Error bodies drop `defined`](https://docs.settlemint.com/docs/api-reference/guides/upgrade-to-3-2#error-bodies-drop-defined) describes.
- **The CLI is verb-first**, so `dalp contacts list` becomes `dalp get contacts`, as [The CLI](https://docs.settlemint.com/docs/api-reference/guides/upgrade-to-3-2#the-cli) describes.
- **Some v2 requests require new fields** and some response rows changed shape, as [Required fields added to v2 requests](https://docs.settlemint.com/docs/api-reference/guides/upgrade-to-3-2#required-fields-added-to-v2-requests) lists.
- **Existing operations gain new refusals**, among them mint and burn during a corporate action and issuance from an unpublished template, as [New refusals on existing operations](https://docs.settlemint.com/docs/api-reference/guides/upgrade-to-3-2#new-refusals-on-existing-operations) lists.
- **The v1 API changes too.** 3.2 removes three v1 operations, v1 user reads drop their single-wallet fields, and a v1 write is refused where an organisation holds its v2 route under maker-checker, as [Removed v1 operations](https://docs.settlemint.com/docs/api-reference/guides/upgrade-to-3-2#removed-v1-operations) describes.
- **Venue event reads name only the caller's own side** of a trade a venue settled, unless the caller operates the venue, as [Trading venue reads](https://docs.settlemint.com/docs/api-reference/guides/upgrade-to-3-2#trading-venue-reads) describes.

The platform upgrade does not change the contracts an organisation runs on chain. Each organisation runs [System updates](https://docs.settlemint.com/docs/console/organisation-settings/system-updates) on each network when it wants the 3.2 contracts, and until it does, the token features and contracts that 3.2 adds are not on its system.


# Instruments and registers

Source: https://docs.settlemint.com/docs/changelog/dalp-3-2/instruments-and-documents
Issue from thirty-six templates, offer only the ones you publish, and answer who held a security on a record date, down to beneficial owners.

**Issue from the templates your organisation approved, and answer who held a security on a record date.** Your issuers see only the templates product control has published, from a library that grows by twelve, including two sukuk. The holder register comes from the token's own balance history, reconciled against total supply before anyone sends it.

Spotlight: The template fixes how an instrument behaves, and the token's balance history answers who held it

- Templates: Thirty-six, in seven asset classes
- New in 3.2: Twelve, including two sukuk
- Register exports: CSV, XLSX, PDF and a registrar file
- Look-through: Beneficial owners behind a nominee

An asset designer decides which templates issuers may use. Every holder list at a record block is checked against total supply before anyone can deliver it.

## Before and after [#before-and-after]

**Before 3.2:** each issuance was configured by hand, so two bonds from the same desk could carry different features and compliance settings. When the registrar, the transfer agent or the regulator asked who held a security on the record date, the operations team rebuilt the answer from exports and reconciled it by hand, and a custodian's omnibus wallet showed as one holder with no view of the investors behind it.

**With 3.2:** issuers choose only from the templates your organisation has published, so every instrument of one kind starts with the same behaviour. The holder register reads balances at a record block from the token's history, refuses to deliver a list that does not add up to total supply, exports it as a registrar file and looks through a nominee wallet to the owners its nominee declared.

[Figure] From a library template to the holder register at a record date. An organisation copies a template from the DALP Library into a draft, sets its token features and publishes it. Issuers issue only from published templates. The live token keeps its balance history, so the holder register can be read at a past record block and is checked against total supply. From that register the platform produces the shareholder list in CSV, XLSX and PDF, a registrar file to export and reconcile, and a register that looks through nominee wallets to their declared beneficial owners. Labels: 36 templates; DALP Library; Read-only, ready to copy; Draft template; Your organisation; Token features, fixed settings; Issuers can use it; Published; Offered in Issue asset; Holder register at a record block; Live token; Read from the token's balance history and checked against total supply; CSV, XLSX, PDF; Shareholder list; Delivered to the issuer; Export and reconcile; Registrar file; Wallet by wallet; Look-through register; Beneficial owners; Owners a nominee declared.

Published templates fix how an instrument behaves, and its balance history feeds the holder register, registrar file and beneficial-owner look-through.

## Issue sukuk, venture and digital asset instruments from the catalogue [#issue-sukuk-venture-and-digital-asset-instruments-from-the-catalogue]

The DALP Library grows to thirty-six templates in seven asset classes, and each one is a configuration of contracts the platform already runs. The twelve new templates start with the Ijara and Murabaha sukuk under a Shari'ah and AAOIFI compliance policy, a government security for sovereign, agency and sub-sovereign paper, and a spot commodity. A new Digital assets class holds a tokenised virtual asset and a custody receipt. Venture financing gets a SAFE, a warrant and the convertible equity they convert into. A controlling class share and an economic class share form a two-class equity that issuers pick as one structure, and a share-class mirror serves funds whose register a transfer agent or administrator keeps. An Islamic bank that wants to tokenise an Ijara sukuk starts from a template that already carries the sukuk structure and its compliance policy, instead of commissioning a custom contract. A template sets the instrument's behaviour on the token, and the legal documentation and the Shari'ah board's opinion stay with your institution.

![Instrument templates page listing DALP Library templates, each published with its version](https://docs.settlemint.com/docs/screenshots/console-instrument-templates.light.en.webp)

[Screenshot] Your asset team browses the library of published instrument templates.

## Offer issuers only the templates your organisation approved [#offer-issuers-only-the-templates-your-organisation-approved]

Issuers can choose only from the templates your organisation has published. Common Equity, Corporate Bond and Fiat-Backed Stablecoin are published from the start, and every other DALP Library template stays unpublished until you publish it. An asset designer who wants a house bond opens Corporate Bond in the DALP Library, chooses **Duplicate template**, picks the token features the house standard needs on the "Token features" tab, and marks which settings are fixed and which the issuer fills in at issuance. The draft cannot be published while a token feature is not configured, and once it is published, every bond the desk issues from it carries the same features and compliance policy. A DALP Library template cannot be edited, so a change to one starts with a copy of it, and where the operator allows the seven original asset families, the asset types DALP offered before templates, users can still create those without a template.

## Answer who held the security on a record date [#answer-who-held-the-security-on-a-record-date]

An operator can set the holders list to a past day, back to when the asset's balance history began, and read the holders as they stood at the end of it. The current view shows available, frozen and locked balances separately. **Export holder register** builds the shareholder list at a record block: each holder with their registered identity, country, units and share of supply, sorted by holding. Its summary shows whether the holders add up to total supply and says not to send the list when they do not, and "Deliver to issuer" stores CSV, XLSX and PDF editions for the issuer's owners and admins, who get an email with a link and never the holder data itself. A company secretary preparing a dividend reads the list at the record date and sends a file the platform has already reconciled against supply. The past view shows only the holder, the balance and the share. The shareholder list, the registrar file and the beneficial-owner register work only once your operator switches regulatory reporting on, and an asset without the Historical balances feature, or one that already had supply when the feature was attached, cannot produce a list at all.

## Reconcile with the registrar and see the owners behind a nominee [#reconcile-with-the-registrar-and-see-the-owners-behind-a-nominee]

**Registrar file…** downloads the register at the record block as one row per wallet, with its identity reference, country and quantity, and "Reconcile registrar file" takes the registrar's own CSV back and marks each wallet as matched, mismatched, missing on chain or missing in the register. A nominee, custodian or broker declares the beneficial owners behind one of its wallets with "Declare beneficial owners", in the Console or through the API, and the platform keeps the declaration only when its units add up to the wallet's balance at that block. "Register by beneficial owner" then reads the register looked through to those owners, with each read written to the audit trail, and the owners' names and ID numbers are encrypted in the platform database and never written on chain. A CSD can see the investors inside a custodian's omnibus wallet, and an issuer can tell each of them their share of a dividend, while the dividend itself is still paid to the nominee as one payment. Shareholder lists are also delivered on their own after a call auction settles, when the last trading day of a month closes and as a flagged correction after a bust, and those three follow trading on a DALP venue. The registrar file uses DALP's one built-in layout, so a registrar that needs another format needs that layout added.

## Give holders the documents that concern them [#give-holders-the-documents-that-concern-them]

Post a document once and every investor who holds the asset reads it from the asset page. Each document is "Public", **Holders only** or "Restricted", terms documents are always public, and only holders of the asset's governance role can add or change them. An issuer posts an annual report as Holders only, and every holder reads the same file, with its integrity check and its download, instead of receiving it by email. A holder sees the public documents and those marked Holders only, and never a restricted one. The Console and the Investor portal both preview PDF, Word, Excel, CSV and image files in the browser and offer every other file as a download.

## Upgrading [#upgrading]

Assets you have already issued keep working as before, and none of this changes their configuration. An asset gets the Historical balances feature from its template at issuance, so check an existing asset's Features tab before you rely on its holder register. Issuance from a template now needs that template to be published, so an organisation that issues from a DALP Library template other than the three published from the start publishes it first, as [Template publication](https://docs.settlemint.com/docs/api-reference/guides/upgrade-to-3-2#template-publication) describes for integrations. Templates whose features are new in 3.2, such as the share-class mirror and the custody receipt, need the organisation to run System updates first. Creating a token from a template whose feature has no factory on the system is refused before anything is signed, with HTTP 409 `TOKEN_CREATE_FEATURE_FACTORY_NOT_REGISTERED` (`DALP-207901`), and Issue asset marks the template as needing a feature factory. Creating an asset in one of the seven original asset families has been off since 3.1.19 and stays off, and an operator who still needs it decides that before the upgrade, as [Upgrade a deployment to DALP 3.2](https://docs.settlemint.com/docs/deployment/upgrade-to-3-2#decide-on-legacy-asset-creation) describes. Existing assets in those families keep minting, transferring and reporting. The holder register exports, the registrar file and the beneficial-owner register come with regulatory reporting, which stays off until your operator switches it on, as [Upgrade a deployment to DALP 3.2](https://docs.settlemint.com/docs/deployment/upgrade-to-3-2#decide-which-application-layers-to-switch-on) describes.

## Why it matters [#why-it-matters]

- **Banks:** every bond, deposit or fund your desks issue from the catalogue starts from a template product control approved, with the same features and compliance policy each time.
- **Exchanges, CSDs and market infrastructures:** the register at a record date reconciles against supply and against the registrar's file, and looks through custodian wallets to the owners behind them.
- **Regulators:** A shareholder list names the record block it was read at and states whether it adds up to total supply.
- **Partners:** on a mirrored share class, a transfer agent or administrator keeps the legal register and moves units on chain only through booked movements it records.

## Next steps [#next-steps]

- [Get a shareholder list →](https://docs.settlemint.com/docs/api-reference/guides/issuer-shareholder-list)
- [Read the holder register in the Console →](https://docs.settlemint.com/docs/console/asset-management/manage/holder-register)
- [Understand instrument templates →](https://docs.settlemint.com/docs/concepts/modeling-assets/instrument-templates)


# Prices and market data

Source: https://docs.settlemint.com/docs/changelog/dalp-3-2/market-data
Prices from SFTP files, FIX and data vendors reach token price feeds through ordered checks, with the evidence and the outcome kept for every price.

**Prices from your providers reach your tokens' price feeds through checks, and every published price keeps the record of the delivery it came from.** 3.2 adds price sources that collect SFTP files, FIX market data and two vendor APIs and publish only the prices that pass. The Bloomberg and LSEG requests follow each vendor's public documentation and have not run against the live services.

Spotlight: Each delivered price is checked in a fixed order, and its outcome is recorded whether it publishes or not

- Providers: SFTP files, FIX, two vendor APIs
- Evidence: Raw delivery kept with its hash
- Large moves: Held once you turn on the Prices rule
- Stale feeds: One operations case per episode

A price source brings prices in. It maps your provider's ISINs to your tokens' price feeds, and valuation, compliance and reporting read the price it publishes.

## Before and after [#before-and-after]

**Before 3.2:** A price reached a token's feed because someone keyed it in or a script pushed it. A wrong currency or a stale file went through unless a person caught it, a large move published without a second look, and the question "which delivery did this price come from" had no recorded answer.

**With 3.2:** the platform fetches each delivery, keeps the raw file or message with its hash, and runs every price through ordered gates. Each price either publishes or records why it did not. With the organisation's "Prices" approval rule on, a large move or a correction waits for a second approver, and a feed that stops updating opens an operations case that names the likely cause.

[Figure] How a delivered price reaches a token's price feed. A provider delivers a price over SFTP, FIX, Bloomberg Data License or LSEG DataScope Select. The platform keeps the raw delivery with its hash and records an observation. The observation passes ordered gates. A repeat or an older price is dropped, a wrong currency or a future-dated price is refused, and a small move is skipped, each outcome recorded. With the Prices approval rule on, a large move or a correction is held until a feeds manager or a holder of the token's Governance role approves it. A published price is signed by the organisation's operations signer. A stale feed opens one operations case that names the likely cause. Labels: Price delivered; Provider; SFTP, FIX, Bloomberg; or LSEG; Observation; Evidence; Raw delivery kept; with its hash; Checked; Gates, in order; Repeat, currency,; time, size of move; Published; Token feed; Signed by the; operations signer; Outcome recorded; Not published; Dropped, refused or; skipped, with why; Held for review; Prices rule on; A large move or; a correction; Approve or reject; Second approver; Feeds manager or; Governance role; Stale feed; One operations case names the likely cause and closes when a fresh price lands.; Freshness counts from the provider's observed time, never from the publish time.

The platform keeps each delivery with its hash, checks every price through ordered gates and publishes the ones that pass, recording the outcome either way.

## Bring prices in from the providers you already use [#bring-prices-in-from-the-providers-you-already-use]

A feeds manager connects a provider once, and its prices arrive without anyone typing them in. Under "Data feeds" › "Sources", **Add source** asks how the source delivers prices: "File" for an SFTP server with CSV or ISO 20022 `reda.001` files, "FIX" for a market data session, or "REST" for Bloomberg Data License or LSEG DataScope Select.

A fund administrator's feeds manager adds the custodian's SFTP server for its end-of-day CSV, stores the credential, which is never shown again, and runs **Test connection**, which shows the server's host key to compare with the one the custodian published. The manager trusts the key, chooses "Map instrument" for each ISIN and its token, and selects "Activate". A token that has no price feed gets one in the same step. From the next delivery on, the platform polls the server, reads each file once it stops changing and turns every row into an observation, the record of one price as delivered. The Bloomberg and LSEG sources were built and tested against each vendor's documented requests, and a run against a live account has to confirm them before you rely on them.

![Sources tab of Data feeds listing each price source with its protocol, instruments and last delivery](https://docs.settlemint.com/docs/screenshots/console-data-feeds-price-sources.light.en.webp)

[Screenshot] Your team sees each price source, how it delivers and when it last delivered.

## Know why each price published or did not [#know-why-each-price-published-or-did-not]

Every delivered price passes the same gates in the same order, and the first one that applies decides it. The platform drops a repeat or a price older than the feed's newest, refuses a wrong currency or a future-dated price, and skips a move below the publish threshold. When the source's heartbeat interval has passed since the last publish, a newer observation publishes even when it moved less. The outcome is recorded on the price, so the **Deliveries** tab shows for each delivery how many prices were accepted, rejected, dropped, held and published.

On a token's "Placement" tab, the **Price** card shows where the price came from under "Price from", who signed it under "Signed by", and "View evidence" opens the record the provider delivered. When an auditor asks where a fund's price came from, the answer sits on the price. A paused source, or one stopped by a credential or configuration failure, publishes nothing until a feeds manager restarts it.

## Hold a large move for a second approver once the rule is on [#hold-a-large-move-for-a-second-approver-once-the-rule-is-on]

When your organisation turns on the "Prices" approval rule, a price that moved more than the source's tolerance, or that corrects a price already published, waits on the source's **Held prices** tab and as a "Held price" row in the Actions inbox. A feeds manager or a holder of the token's Governance role opens it, compares the received price with the last published one against the tolerance, reads the evidence, and approves or rejects it with a PIN. Whoever set up or changed the source, mapped its instruments or asked for the delivery cannot decide it. If a newer price moved past the tolerance while the sheet was open, the approval is refused and the sheet shows the current state. Approval rules start off, and with this one off, such a price publishes and the platform records a waived approval instead of a review.

## Hear about a stale feed before a valuation uses it [#hear-about-a-stale-feed-before-a-valuation-uses-it]

The platform checks every mapped feed each minute and opens one operations case when a feed passes its staleness bound. The case names the likely cause, such as a paused source, a source failing on its credential, a price waiting for review or a delivery the gates rejected, so the operator knows where to look first. It closes by itself when a fresh price lands. Freshness counts from the time the provider observed the price, so a late approval or a price sent again does not make a feed look fresher than its data. Stale feeds have no webhook event of their own, so an outside system follows them through the operations case events.

## Upgrading [#upgrading]

Price sources are new in 3.2 and need no deployment switch. Feeds you maintain by hand keep working as before. Once a price source maps a feed, a manual value for it goes through the single publish and waits its turn behind the source, and a manual batch that includes that feed is refused. Before a source can connect, the operator allows the platform's outbound connections to your providers, and Bloomberg adds the address the platform calls from to its allow list, as [Prepare a price source](https://docs.settlemint.com/docs/deployment/price-source-prerequisites) describes. The "Prices" approval rule starts off in every organisation, and an organisation owner or a platform administrator turns it on under **Approvals** in the General settings. On an instance SettleMint operates, a platform administrator may be SettleMint staff.

## Why it matters [#why-it-matters]

- **Banks:** valuation, collateral and reporting read prices that came from your own providers through recorded checks.
- **Regulators:** each price a source publishes traces to the delivery it came from, its hash, the key that signed it and, for a held price, the person who approved it. A value entered by hand has no delivery behind it.
- **Partners:** A custodian or data vendor delivers by SFTP file, with the columns the source names, or over a FIX session, with the entry types the source maps, and DALP fetches it. A Bloomberg or LSEG source needs a run against a live account before anyone relies on it.

## Next steps [#next-steps]

- [Set up price sources in the Console →](https://docs.settlemint.com/docs/console/organisation-settings/price-sources)
- [Prepare a price source →](https://docs.settlemint.com/docs/deployment/price-source-prerequisites)
- [Understand market data →](https://docs.settlemint.com/docs/concepts/records-and-evidence/market-data)


# Networks and operations

Source: https://docs.settlemint.com/docs/changelog/dalp-3-2/networks-and-operations
Move indexing between node providers from the Console, run one organisation on several networks and recover stuck transactions with the evidence shown.

**Your operations team moves indexing, which reads each network's chain data into the platform, to another node provider from the Console, and recovery bumps or retries a stuck transaction, or holds it for a person while it may still land.** A lagging node must not feed stale balances to the people who act on them, and a stuck payment must not be chased across logs by hand. Each network's records stay apart, one organisation can run on several networks, and Platform status shows the evidence behind every verdict.

Spotlight: Each network is indexed and recovered on its own, and every verdict shows its evidence

- Indexing endpoints: A Console pool per network
- Lagging node: Left out of indexing
- Stalled network: Stops alone, others continue
- Platform API: Four roles that scale apart

A platform administrator edits the endpoints each network is indexed from without a restart. A network that cannot be indexed stops on its own, and recovery never files a transaction again on its own while it may still land.

## Before and after [#before-and-after]

**Before 3.2:** changing a node provider means a values change and a rollout. When one network's node falls behind, an operator finds out from a client who sees an old balance, and a transaction that stops moving is chased by hand across the node, the queue and the logs.

**With 3.2:** A platform administrator manages the node endpoints each network is indexed from in the Console, and Ledger Data, the platform's queryable copy of each network's chain data, leaves out an endpoint that falls behind. A network that stalls stops alone. Recovery checks every stuck transaction against every configured endpoint before it raises a fee, retries or holds the request for a person, and Platform status lists the requests, transactions and workflows behind each verdict.

[Figure] Each network is indexed, read and recovered on its own paths, and each fails and recovers on its own. A platform administrator manages the endpoints each network is indexed from in the Console: hosted providers or the institution's own node. Ledger Data indexing leaves out an endpoint that lags more than 50 blocks behind by default, and a network that stalls stops alone while the others keep indexing. Transactions and most Platform API reads use the endpoints set in the deployment values, and a stuck transaction gets a fee bump or a retry, or is held for a person, after recovery asks every configured endpoint about it. Platform status shows the requests, transactions and workflows behind each verdict, with Force retry and Force fail on a stuck request. Labels: Node endpoints for each network; Platform networks; Console pool for indexing, deployment values for the rest; Skips a lagging node; Ledger Data; Over 50 blocks behind; Deployment endpoints; Platform API reads; Ranked on health; Deployment endpoints; Transactions; Console edits do not apply; Only it stops; A network stalls; Others keep indexing; Recovered, or held; Stuck transaction; Fee bump, retry, then held; The evidence behind each verdict; Platform status; Requests, transactions and workflows, with Force retry and Force fail.

Node endpoints managed in the Console feed indexing for each network, recovery asks every configured endpoint about a stuck transaction, and Platform status shows the requests and transactions behind each verdict.

## Move indexing to another node provider without a redeploy [#move-indexing-to-another-node-provider-without-a-redeploy]

A platform administrator edits a network's node endpoints on **Platform networks** in the Console, and indexing picks up the change without a restart. On an instance SettleMint operates, a platform administrator may be SettleMint staff. An endpoint can be a hosted provider that authenticates with an API key header, or your own node behind basic authentication. Credentials are stored encrypted and never shown again. Each endpoint card shows its health, latency and error rate, and why an endpoint is left out of routing.

![Platform networks page listing each network with its chain ID and status and controls to edit it and its RPC endpoints](https://docs.settlemint.com/docs/screenshots/console-platform-admin-networks.light.en.webp)

[Screenshot] A platform administrator manages each network's node endpoints.

A node provider on one network starts to lag. Ledger Data indexing scores it below its cutoff, which by default leaves out an endpoint that trails the chain head by more than 50 blocks, and moves to the next usable endpoint, and the card marks the lagging one as excluded with the number of blocks it trails. The administrator adds a second provider to the pool from the same sheet, and the platform refuses it if it answers with another chain id or resolves to a private address the network does not allow. An endpoint that rate-limits is cooled down and the call moves to the next one at once.

Each pool change leaves an audit record. Transactions and most Platform API reads use the endpoints in the deployment values, which a Console edit does not change, and a network the deployment values do not declare with a subscription endpoint is not indexed.

## Run one organisation on several networks [#run-one-organisation-on-several-networks]

An organisation can hold one system per network. An organisation owner turns on multi-network support, picks an enabled network from the platform catalogue, and the platform deploys the organisation's system there and shows its progress. A platform administrator decides with **Offer network choice at onboarding** whether new organisations can start on a network other than the platform default.

An Organisation owner adds a second network for a new bond programme. The platform checks that the organisation can sign there, through the owner's custody account or a managed provider bound to that network, and refuses the add otherwise. Once the system is active, the Console's Network menu switches between the two.

The organisation keeps one set of members and settings across its networks. A request that names no network acts on the organisation's default network, and a request for a network the organisation cannot use is refused and never falls back to the default. An owner cannot turn multi-network support off while an added network is in use.

## Keep each network's records apart when one stalls [#keep-each-networks-records-apart-when-one-stalls]

Ledger Data follows each block near the chain tip by its hash, so a replacement block at the same height is detected and rolled back to the common ancestor before the new blocks are replayed. A network that cannot be indexed stops on its own and retries from its last indexed block, while every other network keeps indexing.

A node on one network keeps answering but stops sending new blocks. Ledger Data counts that as a transport failure and reconnects, and after 15 minutes without a committed block the network's card reads "Indexing stalled" with how long it has waited. The other networks' cards still read live. When the endpoint recovers, indexing continues from the last block it recorded. A platform administrator can also pause one network's indexing with **Pause indexing** and keep its data readable.

A replacement that reaches below the chain's final block or deeper than the configured repair depth is not repaired automatically, and that network waits for an operator.

## Recover a stuck transaction without filing it twice [#recover-a-stuck-transaction-without-filing-it-twice]

The platform checks every request that has not moved for five minutes. A passing fault, such as an unavailable node, puts it back on the queue within a retry budget. On a network with a public mempool, a signed transaction that misses inclusion gets a higher fee without a change to its call or its nonce. Before recovery calls a transaction dropped, it asks every configured endpoint for each hash the request recorded. Recovery never files a request again on its own while it may still land: when safe retries run out, it is held as a dead letter while the platform keeps watching for a late receipt. The bundler that submits smart-account transactions also fills a nonce its own wallet skipped, so one gap does not stop its later bundles.

An Asset manager mints during a fee spike, and the mint sits in the mempool. After three blocks, recovery raises each fee field by at least 12.5 percent and broadcasts the replacement at the same nonce. The replacement confirms, and the request completes as the original mint. Had the request ended as a dead letter that can no longer land, an Organisation owner could open it on Platform status and use **Force retry** or "Force fail" with a written reason.

Force retry and Force fail are refused while signed bytes for the request may still reach the chain, unless an API caller states that the custodian stopped a call the chain does not show, which DALP does not check. A workflow whose dependency stays down retries with backoff a bounded number of times and can still end failed.

## See the evidence behind each status verdict [#see-the-evidence-behind-each-status-verdict]

Each verdict on **Platform status** opens a detail screen that lists the requests, chain read samples, transactions, workflows and webhook endpoints behind it. FIX sessions, email, batch jobs and scheduled jobs have their own panels, and an owner or administrator can export a redacted debug bundle for support. The cluster's dashboards and alert rules ship with the deployment and cover Ledger Data falling behind the network, a wedged transaction lane, a funding pause that never resumes, and database and upgrade faults.

The Workflows panel on an Organisation owner's Platform status turns amber when 20 of every 1,000 completed workflows stall. The owner opens its Details and sees which workflows stalled, then opens Transactions, where a failed row shows the decoded contract error behind it.

Platform status shows only to an Organisation owner or a Platform administrator, and it reads only, except the recovery actions on a transaction.

## Size each kind of work for its own load [#size-each-kind-of-work-for-its-own-load]

The Platform API runs as four roles: serving requests in separate v1 and v2 fleets, indexing the network, durable work and scheduled work. The request and durable-work roles autoscale, indexing runs a fixed pair by default with its own pods for rebuilds, and the scheduler runs one pod. Durable work runs inside the platform, with no separate workflow engine cluster to operate.

A large corporate action run adds durable-work pods while the request fleets keep their own capacity, and a slow index rebuild never takes request pods with it. Each role sizes its own database pool, and the chart refuses a configuration whose connection pools do not fit the database's connection limit.

## Upgrading [#upgrading]

3.2 deploys no RPC gateway. Each network takes its node endpoints directly, a node on a private address needs that network to allow it, and every network needs a subscription endpoint for indexing. 3.2 also replaces the workflow engine, so let every operation in progress reach a final state before the upgrade, and plan a window in which nobody starts new ones. Sizing moves to the four Platform API roles, and the index rebuilds after the upgrade while reads keep using the current data. Multi-network support stays off for each organisation until an owner turns it on. [Upgrade a deployment to DALP 3.2](https://docs.settlemint.com/docs/deployment/upgrade-to-3-2) has each step, and [Networks](https://docs.settlemint.com/docs/deployment/networks) describes the network settings.

## Why it matters [#why-it-matters]

- **Banks:** A bank that runs its own nodes can index from them behind basic authentication, and moving indexing to another provider is a Console edit with an audit record.
- **Exchanges, CSDs and market infrastructures:** A stalled network stops alone. A stuck settlement transaction is recovered or held for a person, and recovery never files it again on its own while it may still land.
- **Partners:** one organisation runs on several networks behind the same API, and a request can name the network it acts on.

## Next steps [#next-steps]

- [Compare deployment topologies →](https://docs.settlemint.com/docs/deployment/topologies)
- [Understand platform health →](https://docs.settlemint.com/docs/concepts/operating/platform-health)
- [Understand ledger data →](https://docs.settlemint.com/docs/concepts/records-and-evidence/ledger-data)


# Offerings and fund dealing

Source: https://docs.settlemint.com/docs/changelog/dalp-3-2/primary-offerings
Run a first sale that refuses an ineligible buyer in the payment transaction, with a greenshoe and lock-ups, and settle fund dealing days at NAV.

**Place a new issue only with investors the token's own rules admit, and settle a fund's dealing days at its NAV.** A placement run from spreadsheets and email checks eligibility after the money arrives, and every mistake becomes a refund someone has to chase. In DALP 3.2 a purchase the token's rules refuse takes no money, and a raise that misses its minimum keeps every refund owed in the contract until it is paid back.

Spotlight: One sale contract takes the payment, checks the buyer, allocates and then delivers or refunds

- Eligibility: Token's own rules, in the payment transaction
- Book-building: Greenshoe and lock-ups by category
- Failed sale: Refunds held back from the issuer
- Fund dealing: Daily cut-off at 12:00 UTC, priced at NAV

Issuers run the raise from **Offerings** in the Console, investors subscribe from the Console or the Investor portal, and fund operators settle each dealing day. Eligible means what the token's compliance rules admit, and your institution still sets the legal offering terms, the investor disclosures and the price.

## Before and after [#before-and-after]

**Before 3.2:** eligibility was checked by hand against a list, payments arrived before anyone knew whether the buyer could hold the security, and a refused or failed placement meant refunds chased one investor at a time. Lock-ups lived in a side letter and the transfer agent's notes, and a fund's subscriptions and redemptions were priced and booked outside the register.

**With 3.2:** A purchase the token's compliance rules do not admit fails in the transaction that would take the payment, so no money changes hands. A book-built offering can fill an oversubscribed book with a greenshoe and lock each investor category on the token itself. A failed sale keeps every refund owed in the contract for its investor, and a fund's dealing day prices every open request at the fund's NAV.

[Figure] The life of a primary offering. The offering administrator sets the caps, the presale, any greenshoe and the lock-up per investor category. An optional presale admits only buyers on the allow list, at a discount. The public sale admits any buyer the token's rules admit who has accepted the sale's terms, when it has any. Every purchase checks the token's compliance rules, the per-buyer limits and the hard cap in the transaction that takes the payment. At finalisation a direct sale lets buyers claim their tokens, and a book-built offering delivers each allocation at settlement with its lock-up written into the token's lock-up rule. A sale that missed its minimum raise pays each investor back in the currency they paid. Labels: Set the terms; Caps, greenshoe,; lock-ups; Allow list only; Presale, optional; At a discount; Eligible buyers; Public sale; Any the rules admit; Finalise; Close; Outcome set; Rules, limits and hard cap; Every purchase; Checked in the payment transaction; Tokens delivered; Successful sale; Claimed, or settled with lock-ups; Refunds repaid; Minimum missed; In the currency they paid.

An offering runs from the administrator's terms through presale and public sale to delivery or refund, with every purchase checked in the payment transaction.

## Refuse an ineligible buyer before the money moves [#refuse-an-ineligible-buyer-before-the-money-moves]

An optional presale admits only buyers on the sale's allow list, at the discount, and the public sale that follows admits any buyer the token's compliance rules admit who has accepted the sale's terms, when it has any. The sale checks the token's compliance rules, the per-buyer limits and the remaining hard cap in the transaction that takes the payment. A refused purchase reverts, so the buyer pays nothing and there is no refund to chase. An investor in a country the offering does not admit opens it in the Investor portal and sees the Subscribe button turned off with a message that their country is not admitted, and an investor who lacks a verification the token requires sees **Complete verification** instead. An offering with recorded terms keeps its data room locked until the investor accepts them, and the acceptance is recorded on the sale contract. The portal also compares the payment, after any reduction to the remaining hard cap, with what the investor's wallet holds before Review: a purchase or application the wallet cannot pay stays on the amount step with both figures, and so does an application outside the offering's minimum, maximum or subscription step, so the investor never enters a PIN or signs the terms for it. The portal's early check cannot see rules that depend on balances or counts, such as an investor-count limit, so the check in the payment transaction is the one that decides, and a wallet that a compliance manager, or one of DALP's own factories, puts on the compliance bypass list skips the token's transfer checks.

![Offerings page listing each offering with its status, the amount sold and the amount raised](https://docs.settlemint.com/docs/screenshots/console-primary-offerings.light.en.webp)

[Screenshot] The offerings desk shows each sale's status, how much it has sold and how much it has raised.

## Fill an oversubscribed book with a greenshoe and lock-ups by category [#fill-an-oversubscribed-book-with-a-greenshoe-and-lock-ups-by-category]

A book-built offering takes applications, and a greenshoe grows the offering past the hard cap by up to the percentage set in its terms, either automatically when the allocation starts or when the offering administrator exercises it after the application window closes. In DALP the greenshoe is extra allocation capacity, and the platform runs no price stabilisation. The allocation run then divides the hard cap plus the greenshoe between the applicants pro rata to their demand, and its preview shows the base offering, the greenshoe and the total. The offering administrator reviews that preview before the run, and the run itself divides pro rata. The same offering can lock allocations by investor category, read from the claims on each investor's identity: for example 180 days for qualified institutional investors and 90 days for everyone else, or part of an allocation at three months and the rest at six. The sale contract records each lock in the token's lock-up rule in the same transaction that delivers the allocation, so the token itself refuses an early transfer and nobody depends on a side letter. The token's governance role can clear a lock, and a forced transfer skips the transfer rules by design, lock-ups included. Only a book-built offering on the 3.2 sale contract takes a greenshoe or category lock-ups.

## See which sale needs a decision before it hits its cap [#see-which-sale-needs-a-decision-before-it-hits-its-cap]

The **Offerings** list shows every sale in your organisation and flags the ones that need a decision: a sale at 90% of its hard cap, a presale past its end time, a sale waiting for finalisation and a sale in the 30 days after it failed. Each sale's overview shows what has sold against the hard cap, the soft cap when there is one, and the terms on record. An offering administrator who sees a sale near its cap decides whether to close it before the hard cap refuses the next buyer. The flags use fixed thresholds, and the decision to price, extend or close a sale stays with your team.

## Refund every investor when the minimum raise is missed [#refund-every-investor-when-the-minimum-raise-is-missed]

A minimum raise, the soft cap, is optional. When a sale has one, buyers receive their tokens only once it finalises as successful, and when it misses, each investor gets their money back in the currency they paid. In a direct sale each investor claims their refund, and in a book-built offering the settlement run returns every escrow. On the 3.2 sale contract a refund has no deadline, and the issuer can withdraw only what is left over the refunds still owed. An issuer whose bond placement falls short has nothing to unwind by hand. Payments a sale took before it moved to the 3.2 sale contract are held back only for 30 days after the sale fails.

## Settle a fund's dealing day at its NAV [#settle-a-funds-dealing-day-at-its-nav]

An open-ended fund takes requests on each dealing day, Monday to Friday, with a cut-off at 12:00 UTC. Before the cut-off an investor asks to subscribe a cash amount in the fund's stablecoin or chooses **Request redemption** for a number of units, and can cancel the request until then. A supply manager settles the day: subscriptions are priced at the latest NAV the class price feed published after the cut-off, and a day with no such NAV is refused rather than priced at zero.

For redemptions, **Settle dealing day** prices each open request at the NAV and drafts a buyback that burns the units and pays the investor, which waits for a second approver when your organisation turns on the approval rule for corporate actions. The fund's register and its cash move together from the same NAV, with no separate booking to reconcile. The dealing calendar is fixed, with no holidays and no other cut-off. Subscriptions settle through the API with no approval step.

## Mirror a share class whose register sits with an administrator [#mirror-a-share-class-whose-register-sits-with-an-administrator]

A fund whose legal register sits with a transfer agent or administrator can mirror each share class on chain. Units move only when the administrator books a movement with its register reference, and the token refuses every other transfer, mint or burn. An investor asks for a subscription, transfer or redemption, and the administrator books it against the register entry, which releases any hold and moves the units in one step. The token follows the register only while its booked-movements rule is installed, and its governance role can remove that rule, after which the token no longer follows the administrator's register.

## Refund a failed sale to a recovered wallet [#refund-a-failed-sale-to-a-recovered-wallet]

A failed sale refunds a lost wallet's contribution to the wallet that replaced it through identity recovery. The `recovered-wallet-refund-claims` route takes the lost wallet and pays the replacement wallet that the identity registry names.

## Upgrading [#upgrading]

After the upgrade every organisation can run offerings, where 3.1 shipped them off. The same operator decision covers corporate actions and dividends, so an operator who keeps offerings off on a deployment turns those off too, as [Decide on the offerings surfaces](https://docs.settlemint.com/docs/deployment/upgrade-to-3-2#decide-on-the-offerings-surfaces) describes. An organisation still installs the offering contracts on its system before its issuers see the offerings pages. Sales created on 3.1 keep their address and terms, and run the 3.2 sale contract once the organisation runs System updates. The greenshoe and category lock-ups need that contract and a book-built offering created on it, and the share-class mirror needs the booked movements factory that System updates installs.

## Why it matters [#why-it-matters]

- **Banks:** A placement for your clients refuses an ineligible buyer before the money moves, and a failed raise keeps every investor's refund in the contract until it is paid back.
- **Exchanges, CSDs and market infrastructures:** A book-built offering carries a greenshoe and category lock-ups that the token itself enforces after listing.
- **Regulators:** the sale contract records each purchase, acceptance and allocation, and the token holds each lock until it ends or its governance role clears it.
- **Partners:** A fund administrator keeps the legal register, and the on-chain class follows its booked movements.

## Next steps [#next-steps]

- [Understand primary offerings →](https://docs.settlemint.com/docs/concepts/issuing-and-markets/primary-offering)
- [Understand fund dealing →](https://docs.settlemint.com/docs/concepts/issuing-and-markets/fund-dealing)
- [Understand booked movements →](https://docs.settlemint.com/docs/concepts/records-and-evidence/booked-movements)


# Trading venue

Source: https://docs.settlemint.com/docs/changelog/dalp-3-2/trading-venue
Run permissioned trading venues with order books, auctions, calendars and halts, where every delivery passes the token's own compliance rules.

**Run your own permissioned market, where every trade still has to pass the token's compliance rules to deliver.** A tokenised security that trades on an outside platform leaves the issuer checking transfer restrictions after the fact and rebuilding the trade record from someone else's files. DALP 3.2 adds venues that you operate, with order books, auctions, a trading calendar and settlement through the venue's own escrow.

Spotlight: A venue is a market you operate, and the token decides every delivery

- Market structure: Order book and call auctions
- Settlement: Venue escrow, then the token's own rules
- Custodian role: Lent to the operations signer for one bust reversal, then revoked
- Venues: As many as your business needs

Each venue has its own members, admission rules, calendar, fee schedule and escrow. The Console calls each tradable pair on a venue, such as BOND/USDC, an instrument, with its own order book, price band and holding period. DALP does not bring liquidity to a venue, so you bring the members and the order flow.

## Before and after [#before-and-after]

**Before 3.2:** secondary trading in a tokenised security meant listing it on someone else's platform or matching buyers and sellers by hand. Eligibility was checked off the book, settlement and the register were reconciled afterwards, and the exchange's surveillance, tax and record-keeping duties were met from exports.

**With 3.2:** A venue admits members against the claims it requires, matches orders continuously or in auctions on the calendar you set, and settles each trade through its escrow and each token's normal transfer path. The venue sends its surveillance provider a copy of every order and trade over FIX, the Financial Information eXchange protocol, records VAT on every fee line and keeps its records for the period you set, apart from anything under a legal hold.

[Figure] One order on a venue, from admission to delivery. A member the venue admitted signs an order. A lock in the venue's escrow backs the resting order. The order matches in the continuous book or in a call auction. An optional holding period of up to 30 days keeps both legs reserved. Delivery then moves both legs through each token's normal transfer path, so the token's compliance rules decide whether it goes through. Each settled trade reaches your systems by webhook and your surveillance provider by FIX. An operator can bust an erroneous trade within 24 hours, and a forced transfer reverses a delivered trade in tokens your organisation issued, which skips the transfer rules by design. Labels: Admitted member; Admission; Required claims; Signed order; Order; Price, size, fee cap; Lock backs it; Escrow; Venue's own escrow; Book or auction; Match; On your calendar; Holding period; Optional; Up to 30 days; Each token's normal transfer path; Delivery; The token's compliance rules decide whether it delivers; Webhooks and FIX drop copy; Record; Forced transfer reverses it; Bust within 24 hours.

One order on a venue runs from admission through escrow and matching to delivery under the token's own compliance rules.

## Admit only the members each venue accepts [#admit-only-the-members-each-venue-accepts]

Admission decides who can trade, and a private instrument decides who can see it. You can run as many venues as you need, for example one for retail members and one for institutional desks, or one per jurisdiction. Each venue admits members against the identity claims it requires, and an admitted-only venue refuses orders from anyone it has not admitted. The instruments of an admitted-only venue, public ones included, stay out of market lists and cannot be opened by anyone the venue has not admitted, so make an instrument private only when named participants within the venue should see it. A restricted bond distribution then runs as a private instrument with a full trade record.

![Orders tab of a trading venue listing each order with its instrument, client, side, quantity and status](https://docs.settlemint.com/docs/screenshots/console-venue-orders.light.en.webp)

[Screenshot] Your venue team watches each order on the venue and its status.

When one wallet must leave one instrument, an organisation owner or a platform administrator opens "Barred wallets" on that instrument's settings, chooses **Bar wallet** and records the reason. The wallet's resting orders on that instrument are cancelled, the instrument disappears from that wallet's market lists and data, and a new order is refused with "Your access to this instrument is disabled", while its orders elsewhere stay. An organisation owner acting on a compliance officer's alert stops one wallet trading one instrument in one step, with the reason on record. On an instance SettleMint operates, a platform administrator may be SettleMint staff. A bar applies to a wallet and to one instrument, so keeping one person off it means barring every wallet that person holds, and stopping a wallet holding or receiving the token takes a freeze or the token's block list.

## Open, trade and close on a calendar you set [#open-trade-and-close-on-a-calendar-you-set]

An instrument trades continuously or on a trading calendar with session hours, holidays and half days. Auction-only instruments, and public instruments with a session, open with a call auction that clears at one price, at a random instant inside a published window. Each close sets an official closing price, and optional price bands keep orders and auction prices within a range of a reference price. A public continuous instrument can end the day with a closing auction, which collects orders and crosses them at one price that becomes the official close, and then a Trade at last session, where orders trade only at the last price. A venue operator who sees a disorderly market can halt or suspend one instrument and later resume it, and a halt also suspends its scheduled auctions while the same pair on another venue keeps trading. An operator can also switch on an automatic volatility interruption for one instrument, which stays off until it is set: when a trade would print further from the reference price than the threshold, continuous trading stops for a set time, then one single-price auction clears the book and trading resumes. The instrument header, the market data stream, the FIX drop copy and the audit log all show when it starts and ends. A private continuous instrument has no opening auction and no Trade at last session, and delisting is permanent.

## Sign a fee limit that covers every fill [#sign-a-fee-limit-that-covers-every-fill]

An order that fills in many small pieces pays a fixed fee on each piece. The venue prices the most an order can be charged across all its fills, using the instrument's fee schedule, the venue's on-chain order and settlement fees and any VAT it collects on chain, and requires the order to sign a fee limit that covers it. The Console and the Investor portal sign that limit and reserve the cash for it. An order whose worst case exceeds the venue's 10% maximum is refused with `fee-cap-above-venue-maximum`, so no order can park at settlement for lack of fee room.

## Let the token's rules decide every delivery [#let-the-tokens-rules-decide-every-delivery]

A resting order is backed by a lock in the venue's escrow, whether the asset is a DALP token or a plain ERC-20 stablecoin. When a trade delivers, both legs move through each token's normal transfer path, so the token's compliance rules decide whether the delivery goes through, and a holding period of up to 30 days can keep both legs reserved after a fill. A broker's client who lost an eligibility claim after placing an order cannot walk away from the trade: the token still refuses the payout to that client, so the venue books the refused leg to the client's free balance in the escrow and the trade counts as delivered. The client withdraws it once verified again, and cannot sell it on the venue before that. Only an outside cause undoes a trade at delivery: a paused token, a custodian-shrunk trade lock, a frozen sending side, or a receiver the issuer put on the compliance bypass list during the holding period. On an instrument with a holding period, a fill is refused when a buyer, seller or fee recipient is the zero address, the escrow or a bypass-listed address. An operator can bust an erroneous trade within 24 hours. When your organisation turns on the **Trading venues** row of its approval policy, a second venue operator decides the bust, and the operator who proposed it cannot decide it. Until then a proposed bust goes ahead without a second operator.

The venue contract holds no custodian role. Listing grants no custodian role. When the person approving a bust may grant it, DALP lends your organisation's operations signer the custodian role on each token of the trade that your organisation issued, and on chain that role can freeze and force-transfer any holder's balance. DALP uses it only to reverse a delivered trade after a bust, and revokes it from both tokens when the reversal ends, whether it completed or failed. A token listed before this change still carried the role its listing granted, and DALP takes that back too: the operations signer gives it back once the chain's role matches the grant the organisation's own queue recorded for that listing, and a role a token admin granted is never touched. It waits while a bust on one of the token's markets is approved, executing or failed, and sends a failed renounce again under a new request key, up to eight attempts. Reversing a delivered trade is a forced transfer, which skips the transfer rules by design. A delivered trade with a leg in a token you did not issue, such as a plain ERC-20 stablecoin, cannot be reversed, and a wallet on the compliance bypass list, which a compliance manager and DALP's own factories can add to, skips the transfer checks.

## Set limits and starting values once for the whole venue [#set-limits-and-starting-values-once-for-the-whole-venue]

A venue admin can limit the order types and time in force that every instrument on the venue accepts, listed instruments included, from the venue's **Listing rules** page. Orders already resting stay on the book. The same page holds starting values for the maker and taker fee, the fee account, the market-order protection band and the holding period. The listing wizard opens with them filled in, and a listed instrument keeps its own value. A limit that would leave a listed instrument with no order type or time in force is refused.

## Group the order book by a price step that fits the instrument [#group-the-order-book-by-a-price-step-that-fits-the-instrument]

The order book on the Console and the Investor portal trading screens has a "Price step" control. It offers the instrument's own price step and then 2, 5, 10, 50 and 100 of them, each named by the price it adds up to, so a trader can read a thin book at the level that suits it. On a book whose levels sit far apart, the options move up by powers of ten so that the coarsest one still merges neighbouring levels. Each bucket sits on a multiple of the step, with bids rounded down and asks rounded up, and shows the summed size of the levels inside it.

## Show each party only its own side [#show-each-party-only-its-own-side]

The venue's Orders table shows operators the trading member behind each order, and an operator assigns a broker to a participant from the participant's access page. A broker change applies to later orders only, so an earlier order, trade or held fill keeps the member it had at the time. In the Console and the API, traders and brokers never see who is on the other side of a trade, and their blotter shows only their own orders and fees. Operators publish and schedule announcements, traders set price alerts, and your systems get a signed webhook for each settled trade and each fee it charged, for venue orders and announcements, and for corporate actions announced, paid or completed, all marked beta in the event reference. Venues, instruments, orders, busts and reports are on the versioned API, where an instrument is called a market. Orders, market data and venue reads have matching TypeScript SDK operations, while venue setup, busts and report replay are called over HTTP from the API reference. The public trades read shows both sides' fee breakdown to anyone who can see the instrument, without naming either party, and the trade event on chain names both wallets.

## Charge VAT on venue fees and keep records as long as the law asks [#charge-vat-on-venue-fees-and-keep-records-as-long-as-the-law-asks]

The **VAT policy** of a new venue starts at 5% on fees, and each buyer and seller fee line records its VAT separately from the fee in trades, settlements, statements and fee reports. With "Collect VAT on chain" and a "VAT recipient" set, settlement pays both sides' VAT to that account in the same transaction as the trade and the fee, so tax owed never settles apart from the trade. A venue administrator can list participants that pay no VAT, and every change to the policy follows the venue's Trading venues approval row.

**Data retention** on the venue's listing rules sets how many years the venue keeps orders, order events and trades, from 1 to 100, and a monthly run copies expired, settled records to an append-only archive before it deletes them from the venue. "Legal holds" keep records of one venue, instrument, participant or time window out of that run, and with the organisation's "Reporting" approval row on, releasing a hold takes a request and a second person's approval. A venue with no retention period keeps everything, and its records leave only once an administrator previews and saves a period. The VAT model covers one standard rate and zero-rated participants, and with the Reporting approval row off, which is the default, one person's request releases a legal hold at once.

## Feed your surveillance provider over FIX [#feed-your-surveillance-provider-over-fix]

A venue can send a live FIX 5.0 SP2 drop copy to a surveillance provider: every accepted order, replacement, fill, cancel, expiry and bust becomes an execution report, and halts, resumes, session changes and official closes become market reports, in order. After a trading day ends, an operator can preview and replay that day's reports, and export the day's end-of-day surveillance files per asset class once every trade and approved bust has settled. One of the surveillance file types is an optional export, off by default, and needs the deployment's exchange settings. The drop copy session is set in the deployment's configuration and stays off until the team that runs your deployment enables it, and replay and file export run through the API, with no Console screen. The venue's FIX session only sends reports and takes no orders. Members place and cancel orders through the Console and the API, and each order carries the member wallet's signature.

## Stop orders that hold their balance [#stop-orders-that-hold-their-balance]

Traders can place stop orders beside limit and market orders. The venue reserves the balance when the stop is placed and holds it while the stop waits, so a stop never fails for lack of funds at the moment it fires. When the instrument trades at the trigger price, the stop joins the order book as a limit order at the price the trader set. A trader cancels an armed stop from the open orders to release the balance.

## Upgrading [#upgrading]

Venues are new in 3.2 and run only once the team that runs your deployment, your platform team or SettleMint on an instance it operates, switches secondary trading on, together with the FIX drop copy where your surveillance provider needs it, as [decide which capabilities your deployment runs](https://docs.settlemint.com/docs/deployment/upgrade-to-3-2#decide-which-application-layers-to-switch-on) and [the deployment reference](https://docs.settlemint.com/docs/deployment/install/values-secrets#switch-application-layers-on-or-off) describe. Integrations that read venue events should expect each read to name only the caller's own side of a trade, unless the caller operates the venue, and an instrument's session state can be `trade-at-last`, as [Trading venue reads](https://docs.settlemint.com/docs/api-reference/guides/upgrade-to-3-2#trading-venue-reads) describes. Approval rules start off, so an organisation that wants a second person on busts and venue changes turns on the Trading venues row of its approval policy.

## Why it matters [#why-it-matters]

- **Banks:** you can run a private distribution or a members-only market for your clients' securities, with every delivery checked by the token's own rules.
- **Exchanges, CSDs and market infrastructures:** order books, auctions, an official close, FIX drop copy, VAT on fees and record retention come on a venue you operate.
- **Regulators:** each trade delivers through the token's compliance rules, apart from a wallet on the compliance bypass list and a reversal after a bust, which is a forced transfer one operator can propose until the Trading venues approval row is on. Every bar and hold carries a reason, and the surveillance provider sees each event as the venue records it.

## Next steps [#next-steps]

- [Understand the venue →](https://docs.settlemint.com/docs/concepts/issuing-and-markets/trading-venue)
- [Follow one security from listing to the close →](https://docs.settlemint.com/docs/concepts/issuing-and-markets/venue-journey)
- [Understand venue controls and drop copy →](https://docs.settlemint.com/docs/concepts/issuing-and-markets/venue-controls)


# Overview

Source: https://docs.settlemint.com/docs/changelog
Every DALP release from 3.0 and its theme, how platform, API and system versions work, the API deprecation notice, and where to find breaking changes.

Each DALP release from 3.0 has an entry here, with what it adds to running the instrument and what an upgrade means for you. Patch releases have no entry of their own. The DALP 3.1 entry includes patches 3.0.1 to 3.0.11, and names the 3.1 patch releases that change a default.

## Releases [#releases]

### [DALP 3.2: Run the instrument from issuance to trading](https://docs.settlemint.com/docs/changelog/dalp-3-2)

Released: 2026-11-11

Minting a token is easy. Running the instrument is the work. DALP 3.2 runs the instrument from issuance to trading on the deployment you choose: corporate actions on the live token, offerings that take money only from eligible investors, a compliant venue you operate, a cash token that mints and redeems over your own bank's FIX session, and an assistant that drafts while your team decides. Your institution keeps the legal terms, the cash and the decisions. An agent acts only inside an on-chain mandate your organisation owner sets, which lists the calls it may make, caps its transfer and approval amounts per transaction and per period, and expires. A mandate does not cap the size of a mint or burn. Managed keys stay with the custodian or key store you choose, and on an instance SettleMint operates, SettleMint runs the platform key store. The release changes the SDK and both API versions and adds refusals to existing routes, so start an upgrade from its [compatibility section](https://docs.settlemint.com/docs/changelog/dalp-3-2#compatibility).

### [DALP 3.1: Run the platform as your own](https://docs.settlemint.com/docs/changelog/dalp-3-1)

Released: 2026-08-12

Your institution runs DALP as its own platform. Each organisation signs through its own custody provider, the contracts deploy from inside your own cluster, air-gapped where you need it, and administrators archive and restore organisations and reset a stuck onboarding without database access. Integrations built on 3.0 keep working apart from counter-signed webhook receipts. Later 3.1 patch releases change defaults such as legacy asset creation, so start an upgrade from its [compatibility section](https://docs.settlemint.com/docs/changelog/dalp-3-1#compatibility).

### [DALP 3.0: Design your own digital asset](https://docs.settlemint.com/docs/changelog/dalp-3-0)

Released: 2026-06-22

Your teams design each new instrument from templates they reviewed, write a compliance policy once and let each token that uses it enforce it on every ordinary transfer, and keep signing in the custody you already run. Prices move to per-token feeds and platform status to per-panel routes, and the entry's [breaking changes section](https://docs.settlemint.com/docs/changelog/dalp-3-0#breaking-changes-and-migration) names the migration path for each change.

## How versions work [#how-versions-work]

Four version numbers matter when you plan an upgrade. Each one moves on its own.

| Version | What it numbers | Where it is explained |
| --- | --- | --- |
| Platform release | The images and the Helm chart, as major.minor.patch, such as 3.1.4 | [Supply chain and support](https://docs.settlemint.com/docs/deployment/supply-chain-and-support#how-a-version-is-numbered) |
| API version | The Platform API contract, under `/api/v1` and `/api/v2` | [Versioning and deprecation](https://docs.settlemint.com/docs/api-reference/guides/versioning-and-deprecation) |
| System version | The smart contract versions an organisation runs on each network | [System version](https://docs.settlemint.com/docs/platform/system-version) |
| SDK and CLI | The client packages, which you match to the platform release you run | [SDK](https://docs.settlemint.com/docs/api-reference/sdk) |

A platform release belongs to a release line, the series of patches that share one minor version, such as 3.1. A patch keeps the minor version you run. At most two release lines take patches: the current line and the one before it. A line stops taking patches when the second newer minor version ships. [Which release lines take patches](https://docs.settlemint.com/docs/deployment/supply-chain-and-support#which-release-lines-take-patches) has the detail.

`/api/v1` takes no new operations. DALP 3.2 removes three v1 user and wallet operations and drops the single-wallet fields from v1 user reads, as the [3.2 compatibility section](https://docs.settlemint.com/docs/changelog/dalp-3-2#compatibility) lists. `/api/v2` is stable from the 3.2 release, and that release is where its promise starts: 3.2 itself removes 187 v2 operations that 3.1 published, and that section lists them too. From 3.2 on, the [versioning policy](https://docs.settlemint.com/docs/api-reference/guides/versioning-and-deprecation) holds for v2: a breaking change ships only on a new API version, next to the one you call, and an operation leaves only after a deprecation with at least 90 days' notice. A build check compares each release with the v2 contract already served for removed paths and methods, removed parameters, newly required inputs and removed response statuses, and a change to the values an input accepts or to the fields of a response is caught in review. A release can add operations, response fields and new errors, so handle errors by class and the `retryable` flag, as [Errors](https://docs.settlemint.com/docs/api-reference/guides/errors) describes.

An API version has no fixed end date. DALP serves it until it announces a deprecation, and then for at least 90 days. During that notice, a deprecated operation answers with the `Deprecation` and `Link` headers, and with the `Sunset` header once a sunset date is set. The OpenAPI contract marks the operation as deprecated.

The system version moves separately from the platform release. A platform upgrade does not change the contracts an organisation has deployed. A user with the System manager or Permission manager role opens System updates, which compares each component with the version the platform expects, and migrates the components marked Upgrade available or Not installed.

## Breaking changes and upgrades [#breaking-changes-and-upgrades]

Each release entry has a section an upgrade starts from: "Compatibility" in 3.1 and 3.2, and "Breaking changes and migration" in 3.0. That section lists the breaking changes, the new rejections on existing routes and the steps to take before you upgrade.

- [DALP 3.2 compatibility](https://docs.settlemint.com/docs/changelog/dalp-3-2#compatibility)
- [DALP 3.1 compatibility](https://docs.settlemint.com/docs/changelog/dalp-3-1#compatibility)
- [DALP 3.0 breaking changes and migration](https://docs.settlemint.com/docs/changelog/dalp-3-0#breaking-changes-and-migration)

For the upgrade itself, [Upgrades and migrations](https://docs.settlemint.com/docs/deployment/upgrades-migrations) covers how to drain waiting workflows, the database migration that runs before the new pods start, an index rebuild when a release needs one, and why a rollback does not reverse the database.


# Add-on approvals

Source: https://docs.settlemint.com/docs/concepts/compliance-and-identity/addon-approvals
An add-on can hold a consequential function until the required number of people approve that exact call, then run it once.

Add-on approvals make a checked add-on function wait until a set number of approvers approve one exact call, then run it once. They exist for actions on an add-on such as the custody gateway that are too consequential for one person: moving a payout address, releasing a frozen withdrawal, changing a fee account. A role check alone does not help here, because every holder of the role can act on their own. Add-on approvals add a second decision to the function itself, on chain, so a call whose rule needs approvals runs only after the required number of approvers approved that exact call. The count does not bind a holder of role management on the access manager, or a System manager, as [What the guarantee does not cover](#what-the-guarantee-does-not-cover) explains.

The mechanism belongs to the add-on's own access manager, the contract that holds the add-on's roles. A function the add-on marks as checked either runs at once for a role holder, or waits for a proposal to collect enough approvals. Approval is bound to the call data, so an approval given for one call cannot carry a different one.

## A checked call runs once, exactly as proposed [#a-checked-call-runs-once-exactly-as-proposed]

A role holder proposes a call: the target contract, the role the proposal is made under, and the full call data. The access manager stores the proposal and answers with its identifier. Approvers then approve that identifier, and a wallet holding the proposal's maker role sends the same call to the target. The access manager compares the call data it receives with the one it stored, then records the proposal as executed before the target's own code runs.

The proposal does not carry a value, so a payable function cannot be checked, and an add-on that offers a multicall cannot use the check on the functions it exposes through that path: a function reached through another function of the same contract has a different signature and is refused.

Proposals are keyed by the target, the call data and the maker role, and only one for that combination is open at a time.

A call that reverts leaves the proposal open. The whole transaction rolls back, including the record that the proposal ran, so the approvers' decisions survive a failed run and you can send the call again. A call that succeeds cannot run a second time on the same approvals.

## What an approval rule sets [#what-an-approval-rule-sets]

A rule is set per function, by its selector, the short identifier that names the function in the call data, and applies to every contract that calls the access manager. A rule on one contract overrides the function's rule for that contract, and clearing the override puts the function's rule back. A contract created later follows the function's rule, so a new custody gateway does not start unchecked.

Each rule carries three values:

| Value | Meaning | Bound |
| --- | --- | --- |
| Approver role | The role whose holders approve. Empty means the proposal's maker role. | Any role on the same access manager |
| Approvals needed | How many valid approvals the call needs before it runs. Zero runs the function directly. | 0 to 32 |
| Lifetime | How long the proposal stays open, in seconds. | Up to 31536000 seconds, 365 days |

A rule that needs approvals needs a lifetime. A function with no rule, or a rule of zero approvals, runs at once for a role holder.

Changing a rule's approver role makes every open proposal under it superseded, because the people who approved may no longer be the people the rule names. Changing the count or the lifetime leaves open proposals alone. A proposal created under a contract override ignores later changes to the function's own rule.

Setting a rule is itself an action the access manager checks. A local administrator or a holder of the system role the access manager is bound to may set it, and that action can require approvals too. In that case the API answers `422 Unprocessable Entity` with `platform.addonApprovals.APPROVAL_REQUIRED` and the call to propose: the access manager as the target, the default administrator role as the maker role, and the configuration call as the data.

The custody gateway is the add-on that ships these rules. On a newly created gateway access manager it sets one approval and a seven-day window on every checked function, so the first change to any of them needs one approval from someone other than the proposer.

## Who proposes and who approves [#who-proposes-and-who-approves]

The proposer holds the maker role the function names. An approver holds the rule's approver role at the moment their approval is counted, so an approval recorded before a role was revoked stops counting. The higher of the count the proposal was created with and the count in force now applies, so lowering a rule to a smaller count does not shorten an open proposal's requirement. A rule lowered to zero lets the function run at once for a holder of its role, and that call closes any open proposal for the same call data as executed.

The proposer cannot approve their own proposal. The access manager compares people, not wallets: it looks up each wallet's identity in the system's identity registry. It refuses an approval from any wallet registered to the proposer's identity, refuses a second approval from any wallet of an identity that already approved, and counts each identity once when the call runs. A wallet with no registered identity counts as a person of its own, so the check reaches only the wallets the identity registry links to a person. When a participant's wallets hold an identity, their smart wallet is registered under it too, so the two count as one person. The platform behind the API goes further, because it knows every wallet of a person and a person can act for several participants. The API refuses a person who proposed from any of their wallets, and refuses a second approval from any of their wallets, even when the approving wallet differs. A person who holds the maker role and the approver role on different wallets therefore sees the proposal as waiting for other approvers, not as waiting for them.

An approver cannot approve twice. An approval whose transaction failed does not count, because its record rolled back with the transaction.

The proposer or an approver can cancel a proposal while it is open.

## The bound system role [#the-bound-system-role]

Roles on an add-on's access manager are managed in two ways. Each role keeps its own administrator chain, as any role does, and the access manager can also be bound to one role on the system's access manager. A holder of that bound role grants and revokes every role on the add-on's access manager except the default administrator role.

The binding is set once, by the add-on's own factory, and never changed. The factory proves the system by the fact that it minted the manager: the system access manager it names must be the one its own factory serves. A manager deployed outside that factory cannot be bound at all.

Two limits hold for every caller. Nobody can change the administrator of the default administrator role, and no role can administer itself. Revoking the bound role on the system ends the permission on the next call, and roles it already granted stay until someone revokes them.

## The API for proposals and rules [#the-api-for-proposals-and-rules]

Proposals and rules live under `/api/v2/system/addon-access-managers/{accessManagerAddress}`.

| Call | Purpose |
| --- | --- |
| `POST …/proposals` | Propose a call from the target, the maker role and the call data. Answers the hash of the proposed call. |
| `POST …/proposals/{proposalId}/decisions` with `{"decision":"approve"}` | Approve the proposal. |
| `POST …/proposals/{proposalId}/transitions` with `{"transition":"cancel"}` | Cancel the proposal. |
| `POST …/proposals/{proposalId}/transitions` with `{"transition":"execute"}` | Send the approved call to its target from your wallet. |
| `POST …/action-configs` | Set one rule for up to 50 actions, each on one contract or, with no target, as the function's default. |
| `GET …/proposals` and `GET …/action-configs` | Read proposals and the rules in force. |

The proposal identifier is assigned on chain, so the create call answers the call hash instead. Read the proposal identifier by listing the proposals for that target.

Every write needs a wallet verification, the PIN, authenticator code, recovery code or passkey your wallet asks for. A write without one answers `400 Bad Request` with `platform.http.REQUEST_INVALID`. Send an `Idempotency-Key` with each write. The platform generates one when you omit it, and then you have nothing to retry with if the response is lost. A write that settles within the request's preference window answers `200 OK` with the transaction hash. A write still queued answers `202 Accepted` with a status URL to poll, and `Preference-Applied: respond-async`.

Before a proposal is queued, the API tries the call against the chain from your wallet. A call the access manager needs no approval for answers `422 Unprocessable Entity` with `platform.addonApprovals.APPROVAL_NOT_REQUIRED`, telling you to send it to the target directly. A refusal answers `422` with `platform.addonApprovals.PROPOSAL_REFUSED` and a `reason`:

| Reason | What happened |
| --- | --- |
| `proposer-cannot-approve` | A wallet of yours proposed it, or the signed-in user proposed it through the platform. |
| `already-approved` | A wallet of yours approved it, or the signed-in user approved it through the platform. |
| `checker-unauthorized` | The wallet does not hold the role the call needs. |
| `proposal-not-open` | The proposal was executed or cancelled. |
| `proposal-expired` | The lifetime ended before the next block. |
| `proposal-superseded` | The rule's approver role changed after the proposal was made. |
| `proposal-already-open` | A live proposal exists for the same target, call data and maker role. |
| `not-approved` | The call has fewer valid approvals than the rule requires. |
| `target-not-managed` | The target does not name this access manager as its checker. |
| `invalid-proposal-call` | The proposal targets the access manager with a call other than setting a rule, or carries no selector. |
| `not-maker` | An execute request came from a wallet without the proposal's maker role. |
| `refused` | The access manager refused the call for another reason. The error's `revert` names the contract error. |

Setting a rule from a wallet with no administrator authority on the access manager answers `403 Forbidden` with `platform.http.ACCESS_DENIED`, not with a refusal reason.

Reading, approving and cancelling a proposal reads the indexed record first. A proposal the caller cannot see answers `404 Not Found`. Approving a proposal whose expiry has already passed at the next block answers `422` with `proposal-expired`.

The platform holds one approval per person and proposal. Approving the same proposal twice from the same person answers `422` with `already-approved` while the first request is still in flight, and a request that never reached the queue stops holding that slot after two minutes. An administrator who impersonates a user counts as the administrator for this check, not as the user.

## Where approvers see the work [#where-approvers-see-the-work]

The Console and the Investor portal list a proposal in the actions inbox of the participant it concerns, under the row type "Add-on approval". The row names the call in words, for example "Release a frozen withdrawal", and reads from the wallet that proposed it to the contract it changes. Its status reads "Waiting for your approval", "Waiting for other approvers", or "Ready to run", with the approvals so far out of those needed. An approver of a call the Console cannot read sees "Can't be approved here". [Add-ons and add-on approvals](https://docs.settlemint.com/docs/console/asset-lifecycle/custody-gateway-approvals#review-and-approve) walks through the Console steps.

The Investor portal offers no decision. It tells an approver "Waiting for your approval in the Console" and points them at the Console, which is where an approval, a cancellation and an execution each need a wallet verification.

In the Console, "Review" opens the proposal. An approver approves, a wallet holding the maker role runs an approved change with "Run change", and the proposer or an approver cancels with "Cancel request". The sheet shows the contract, the call in words and its arguments with labels, the approvals so far, the approvals needed, and the expiry. A change to a rule shows the rule it writes: how many actions it covers, each action with its contract or "Every contract", the approvals required, the approval window, the approver, and whether it goes back to the default.

A call the platform cannot read, because it does not know the target's add-on type, reads "Unrecognized call". The sheet then shows the selector and the raw call data, and the Console offers no "Approve" button, because approving bytes you cannot read is what the check exists to prevent.

A person is never offered a decision on a proposal any of their wallets proposed or approved, nor on one they proposed or approved through the platform while acting for another participant.

## What the guarantee does not cover [#what-the-guarantee-does-not-cover]

An approval count binds the people who lack role-management authority over the access manager. A holder of the default administrator role, or of the bound system role, can grant themselves the approver role, or set the rule's count to zero, unless setting a rule is itself configured to need approvals. Configure that before you rely on a count. A System manager on the organisation's system can also replace the logic of every add-on access manager and every custody gateway with one call that no approval rule gates.

Nothing stops one person holding the maker role, the approver role and role management at once. The contracts do not prevent it, and only a grant made through the platform reaches the audit trail. Decide who holds each role before you turn a rule on.

On chain, the access manager tells people apart through the identity registry. A wallet that is not registered to its owner's identity counts as someone else, so a person who holds the approver role on such a wallet can still approve their own proposal from it outside the platform. The identity managers who register wallets are therefore part of the approval guarantee.

Expiry follows the chain's block time, not the wall clock, so a lifetime is a block-time interval and a stalled chain does not expire a proposal.

## Related concepts [#related-concepts]

- [Maker-checker](https://docs.settlemint.com/docs/concepts/custody-and-signing/maker-checker): Where the platform itself requires a second person, and how it differs from a role check or a signature threshold.
- [Role grant](https://docs.settlemint.com/docs/concepts/compliance-and-identity/role-grant): What it means for an address to hold a role, and how an add-on's access manager sits beside the system's.
- [Custody gateway](https://docs.settlemint.com/docs/concepts/custody-and-signing/custody-gateway): The add-on that ships these approval rules on its checked functions.
- [Actions](https://docs.settlemint.com/docs/console/essentials/actions): The queue where an approver meets a pending proposal, and what each row offers.


# Capacity topics

Source: https://docs.settlemint.com/docs/concepts/compliance-and-identity/capacity-topics
A capacity topic is a verification topic your compliance team registers to admit custodians. Learn who issues it and how far trust reaches.

A capacity topic is a verification topic your compliance team registers so that a token can admit a custodian, a firm that holds tokens for its clients and runs the payout and fee operations of those holdings. Such a firm is not an investor, so the investor claims in a token's holder rule, the rule that says which identities may hold the token, may not describe it. DALP defines no capacity topic. You register one on your own system, issue it to the custodian's identity and decide which tokens accept it.

Here a custodian is the client-holding firm, not the asset role named Custodian that can freeze holdings and force transfers. A custodian firm needs no capacity topic when your claim issuers issue it the ordinary institutional claims the holder rule already asks of an institutional holder. Use a capacity topic when they do not.

## Register the topic [#register-the-topic]

Open "Compliance", then "Verification topics", and add a verification topic as [Verification topics](https://docs.settlemint.com/docs/console/compliance/verification-topics) describes. The name is yours and cannot change once registered, because every issuer grant, rule and claim stores an identifier derived from it.

The examples on this page use `intermediary`, the name the Console's holder rule guidance uses for a capacity claim. Write your definition of the topic where your compliance team keeps its policies, for example "holds for clients and runs the payout and fee operations of those holdings, not own-book investment", so a later reviewer knows what the claim attests.

## Issue it to the custodian [#issue-it-to-the-custodian]

Issue the capacity claim once for each custodian identity on each network, from the participant's "Verifications" tab with "Add verification", as [Verify a participant](https://docs.settlemint.com/docs/console/participants/verify-a-participant) describes. Choose your capacity topic under "Verification topic".

Your organisation's issuer identity signs the claim, through an account with the "Verification issuer" role. DALP does not issue a capacity claim for you, with one exception: a wallet recovery issues the organisation's standing claims again on the new identity, signed by the organisation's operations signer. You withdraw it later with "Revoke verification", which keeps the record for audit and stops the claim counting. A revoked claim blocks the custodian's next transfer that depends on it and leaves settled transfers as they were.

## Write the holder rule [#write-the-holder-rule]

The holder rule is the token's expression over verification topics. A holder of the token's Governance role sets it with "Edit holder rule" on the token's "Compliance" tab, or through `PUT /api/v2/tokens/{assetId}/compliance-expression`, documented in the [Platform API reference](https://docs.settlemint.com/docs/api-reference/v2). When the token has an identity verification compliance module, the module's rule must pass as well.

Name the capacity topic as one more operand beside the investor claims:

```text
sanctionsScreening AND (knowYourCustomer OR intermediary)
```

Put every check that must apply to every holder outside the capacity branch. This form is wrong:

```text
(sanctionsScreening AND knowYourCustomer) OR intermediary
```

It passes any wallet whose identity carries the capacity claim without asking for sanctions screening. Read each `OR` in a rule as a second way in, and check what that branch skips. A wallet that holds the capacity claim from a trusted issuer passes its branch with no other check, so treat issuing the claim as an admission decision.

## Choose how far trust reaches [#choose-how-far-trust-reaches]

A claim counts only when its issuer is trusted for its topic. Grant that trust to the issuer identity that signs the capacity claim, for the capacity topic and for the other topics the custodian's wallets need, in one of two places:

| Where you grant it | Who it admits |
| --- | --- |
| A token's own trusted issuers | The custodian, for that token only. |
| The system's [Trusted issuers](https://docs.settlemint.com/docs/console/compliance/trusted-issuers) | The custodian, for every token in the system whose holder rule names the topic. |

A token admits the custodian only when both hold: it trusts the issuer for the topic, and its holder rule names the topic. A grant with no rule that names the topic admits nobody, and a rule that names the topic with no grant admits nobody. Global controls, the compliance modules that run on every ordinary transfer in the system, apply in addition to the token's own rule, and the holder rule cannot switch them off. A custodian forced transfer and a recipient on the compliance bypass list skip them, as [Compliance Policy](https://docs.settlemint.com/docs/concepts/compliance-and-identity/compliance-policy) describes.

## Give each further capacity its own topic [#give-each-further-capacity-its-own-topic]

A further holding capacity is a further topic with its own trust grant. Never widen an existing topic to cover it. A topic node in a rule carries only a topic id and a rule cannot test the data inside a claim, so a rule cannot tell two capacities apart inside one topic.

## Check the custodian is admitted [#check-the-custodian-is-admitted]

Before the custodian's first transfer, run the [transfer pre-check](https://docs.settlemint.com/docs/concepts/compliance-and-identity/transfer-path-compliance#read-a-transfers-verdict-before-signing) with the custodian's wallet as recipient. A missing capacity claim, or a claim from an issuer the token does not trust, appears as a blocker that lists the missing topic.

## Related concepts [#related-concepts]

- [On-Chain Identity](https://docs.settlemint.com/docs/concepts/compliance-and-identity/onchain-identity): What a claim records and how trusted issuers decide which claims count.
- [Compliance Policy](https://docs.settlemint.com/docs/concepts/compliance-and-identity/compliance-policy): The modules and global controls that run beside the holder rule on every transfer.
- [Transfer-Path Compliance](https://docs.settlemint.com/docs/concepts/compliance-and-identity/transfer-path-compliance): How a token enforces its rules inside the transfer.


# Compliance modules

Source: https://docs.settlemint.com/docs/concepts/compliance-and-identity/compliance-modules
Reference for what each compliance module permits or refuses, its parameters and units, and where you configure it.

Nineteen compliance modules enforce the platform's transfer and mint rules and track burns. This page gives one entry per module: what it refuses, the parameters and units that decide it, and how its refusal reads. For installation, [Global controls](https://docs.settlemint.com/docs/console/compliance/global-controls) covers the organisation-wide surface and [Policy templates](https://docs.settlemint.com/docs/console/compliance/policy-templates) covers the reusable token-scoped one, and the [Platform API](https://docs.settlemint.com/docs/api-reference/v2) manages the same modules programmatically.

A compliance module is one rule bound to a token. Ordinary transfers and mints evaluate active rules within scope. Burns notify stateful modules after the supply change rather than running the same recipient checks. A reverting hook still reverts the transaction. A recipient on the compliance bypass list skips the modules that judge a recipient on a second-generation engine and every module on a first-generation one. A custodian forced transfer and a wallet recovery skip every module, and the token's Governance role can turn off or replace its rules, so review who holds Custodian, Identity manager and Governance.

Rules reach a token four ways:

- A global control applies to every bound token of the organisation's system from "Global controls".
- A policy template's controls become a token's own rules when an asset is issued from that template.
- The compliance steps in Issue asset let the issuer fill in the values the policy leaves open.
- A holder of the token's Governance role adds, edits or turns off rules afterwards on the token's "Compliance" tab.

A token-level rule adds to any global control that already covers the same ground and cannot switch it off. See compliance policy for how the configuration surfaces and the underlying registry relate.

A second-generation module is installed as its own instance per token, refuses with a machine-readable reason code, and carries its configuration on one or more rules, each with a scope that decides which senders and receivers it checks. A DALP asset is a second-generation token and takes only second-generation modules: the Platform API refuses a first-generation module on one, when the asset is created and when a module is installed later, and names the module that replaces it, for example `collateral-v2` for `collateral`. Other asset types keep accepting first-generation modules. Errors and the API call the first generation V1 and the second V2. The entries below describe the current generation. A version note calls out where the older one behaves differently.

## Keep stateful rules counting [#keep-stateful-rules-counting]

Wallet count, Identity count, token supply limit, issuance volume limit, capital raise limit, time lock and transfer approval keep state in post-movement hooks. This holds in both generations. Transfer approval consumes approvals after a transfer.

Disabling one of these rules stops its state updates. Re-enabling it does not replay missed movements: counts, quotas, locks or remaining approvals may no longer reflect what happened while it was disabled.

New scopes default to `ACCOUNTING_ONLY` ("Track transfers outside this scope"). Movements outside the scope skip validation but still update the active rule's state. Clearing that option explicitly selects `SKIP_ALL`, which skips both validation and accounting outside the scope. The Console warns when you clear that option on a stateful rule. On a token or in global controls, "Turn off" on a rule asks only for wallet verification, which says the rule "stops checking transfers" but not that its state stops updating. Before you turn off a rule, check whether it is one of the stateful rules this section names. "Disable control…" on a first-generation token's control shows that state warning first.

To suspend a restriction while keeping state current, keep the rule active and use an `ACCOUNTING_ONLY` scope that excludes the movements you want to allow, or configure it to enforce nothing. For Wallet count and Identity count, set the maximum to 0 and remove every country cap. API clients should likewise keep stateful bindings active and set `executionMode` to `ACCOUNTING_ONLY` for out-of-scope accounting. Disabling a binding stops all its hooks.

[Figure] Where a token's compliance rules come from. Four sources feed a token's compliance evaluation. Global controls apply platform-wide and reach every bound token. At issuance, a policy template's controls become the token's rules, with Issue asset's compliance steps filling in the values the policy leaves open. The token's Compliance tab adds or edits rules after issuance. Together those three form the token rules. When a transfer, mint, or burn executes, every enabled rule checks the operation. If all rules pass, the operation executes. If one rule refuses, the operation fails and names the rule. Labels: Where a token's compliance rules come from; Global controls; Platform-wide,; every bound token.; Policy template; Sets rules; at issuance.; Compliance step; Issuer fills the; open values.; Compliance tab; Add or edit; after issuance.; Token rules; Every enabled rule checks the operation when it executes; A transfer, mint, or burn reads the rules live at that moment.; All rules pass; The operation executes.; One rule refuses; The operation fails and names the rule.

Active rules evaluate movements within their scope, and a failure reverts the transaction.

## Check a change before you confirm it [#check-a-change-before-you-confirm-it]

When you add or remove a rule on a token's Compliance tab, the Console asks the platform whether it would accept the change before it asks for your PIN. A refusal shows in the verification dialog with its reason and fix, for example that the token already has a rule of that type or that the rule type is not registered in the system. The confirm button stays disabled and the reason repeats as text, so you learn it before the PIN. The check stores nothing and signs nothing. The platform checks again when you confirm, because the token can change in between. If the check cannot answer, the dialog does not block you and the write returns its own refusal.

## Choose the module by what it keys on [#choose-the-module-by-what-it-keys-on]

The Console's category filter groups the catalogue by what each rule reads before it decides, and that is also how to choose one. Start from the fact your requirement keys on, then pick the module in that row.

| Console category | Modules | The rule keys on |
| --- | --- | --- |
| "Eligibility" | Identity verification, Identity allow list, Identity block list, Claim expiry | Who the receiver is: their registered identity and its claims |
| "Restrictions" | Country allow list, Country block list, Block addresses | Where a party is registered, or the raw wallet address |
| "Transfer controls" | Transfer approval, Own custody gateway | A named authority approving first, or the holder's own custody gateway |
| "Issuance & supply" | Supply cap, Token supply limit, Capital raise limit, Wallet count, Identity count, Issuance volume limit, Minimum holding | How much exists: supply, issuance, raised capital, holder count, position size |
| "Time-based rules" | Time lock, Lock-up | How long tokens have been held, or whether an unlock date has passed |
| "Settlement & collateral" | Collateral requirement | Proof of collateral behind the supply |

Within the eligibility row, the choice is population shape. [Identity verification](#identity-verification) admits anyone whose identity carries the right claims, so it fits an open population qualified by credential. The [identity allow list](#identity-allow-list) admits only a closed set you enumerate, which fits a private placement. The [identity block list](#identity-block-list) excludes named identities from an otherwise open population, and [claim expiry](#claim-expiry) keeps an admitted population's credentials current over time.

Within the supply row, the choice is what the limit counts. The [supply cap](#supply-cap) is a hard ceiling on units in existence. The [issuance volume limit](#issuance-volume-limit) is a quota on units issued per window, and the [capital raise limit](#capital-raise-limit) is a quota on fiat value raised per window. [Wallet count](#wallet-count) and [identity count](#identity-count) limit the number of holders rather than units, and [minimum holding](#minimum-holding) constrains each position's size rather than the total.

## Configure modules while issuing an asset [#configure-modules-while-issuing-an-asset]

When an asset is issued from an instrument template with a policy, each module the policy marks "Make configurable in Issue asset" gets its own step under "Compliance details" in [Issue asset](https://docs.settlemint.com/docs/console/asset-management/issue-new-asset). A control the policy requires without configuring it gets a step too. A module the policy fixes for issuers gets no step, and its policy values are installed as they are.

Each step carries the module's name and its parameters, described in each module's entry on this page, pre-filled with the policy's values. A module the policy applies more than once gets one step per instance, marked "Inherited from template (N rules)" and "Rule 1 of N". The "Applies to" line under the form shows each rule's scope, which comes from the policy and cannot be changed during issuance. Each step has its own address, so a reload returns to the same module.

The steps offer no way to add a module the policy does not bring. Only [Write the policy](#write-the-policy-in-words) can add a step, for a rule beyond the ones the policy brings. When the country rules contradict each other, the step and the summary show "Contradictory country rules". A capital raise limit needs the system's price resolver add-on: the platform fills in the resolver and the price topic when it creates the token, and refuses the creation when the system has none.

## Write the policy in words [#write-the-policy-in-words]

A compliance officer can write the asset's investor policy as text and let the platform compile it into rules from this catalogue. "Write the policy" sits at the top of the rules on a token's "Compliance" tab and at the top of each compliance step in Issue asset. It shows while the Console assistant and its drafts capability are on for the organisation.

You write the policy in English or German, at most 2,000 characters, for example "EU professional investors only, no US persons, minimum holding 1,000 units." "Read the policy" maps each part of the text to one module and reads every value, such as a country, a verification, an amount, a period or a date, from your own words. The assistant picks the module for each part and never writes a value. The read-back lists each clause, the rule it became and the words its values came from. A part no module expresses is listed with the reason: no module limits the share one holder may own, for example, and a lock-up date that has passed is not read. A policy in another language reads back that it cannot be read and asks for English or German.

On a token, "Check today's holders" runs the read-back rules against the 50 current holders with the largest balances and names the holders each country, verification or minimum holding rule would fail. A wallet with a valid escrow claim is exempt from the minimum holding, as it is on the installed rule. A holder count rule or a supply cap is compared with the current count or supply. A time lock or lock-up applies to future transfers only, so it fails no current holder. The check changes nothing, and it answers unavailable while the platform has not indexed the token yet.

Applying never installs a rule by itself. On a token, "Open N rules" opens the add-rule sheet for each rule in turn with its values filled in, and you confirm each one with wallet verification. Skip passes over one rule and Stop ends the run. In Issue asset, "Fill N rules into the design" writes the values into the compliance steps, and nothing deploys until you create the asset. The platform stores the policy text with the asset and links each rule to its words, and the "Compliance" tab shows them under "Policy" as the record of where each rule came from. A rule shows "Not added yet. Save the rule to apply it." under its words until an active rule with the same values is installed on the token. A rule of the same kind with other values does not count. The [Platform API](https://docs.settlemint.com/docs/api-reference/v2) offers the policy reading, the stored policy and the holder check as their own routes.

## Block addresses [#block-addresses]

Refuses an ordinary transfer or mint when a checked sender or receiver address is on the module's block list. Burns do not run this pre-check. It reads the raw wallet address, so it works before any identity is registered. Use it to refuse wallets your sanctions process names, or compromised wallets. You maintain the list, and DALP does not supply or update one. A [wallet restriction](https://docs.settlemint.com/docs/console/participants/restrict-a-wallet) freezes a wallet only on the tokens it holds when you run it, so add the address here to cover tokens the wallet acquires later.

| Parameter | Description |
| --- | --- |
| Blocked addresses | Wallet addresses the module refuses on either side of a transfer. |

## Capital raise limit [#capital-raise-limit]

Caps the gross fiat value raised through issuance in a fixed or rolling window, for example 5,000,000 in base currency per 365 days. Whether a cap satisfies a regulator's limit is for your legal team to decide. It converts each mint's token amount to fiat through the installed price resolver at mint time, and it fails closed if the price is missing, zero, negative, or stale. Burns do not release capacity, because the module measures gross capital raised, not net outstanding supply. For the same reason it cannot satisfy a requirement keyed to average outstanding value. Configuration is immutable once applied, so changing a parameter means removing the module and adding a new instance. It needs the price resolver add-on on the system. You set only the limit, and the platform fills in the resolver and the price topic. Without the add-on, asset creation fails and adding the rule is refused with `DALP-199482`. The "Rules" table reads the rule back in the units you set, for example "At most 5,000,000 in base currency raised per 365 days".

| Parameter | Description |
| --- | --- |
| Maximum raised (fiat) | Fiat amount, in whole base-currency units, that may be raised in each window. |
| Period length (days) | Tracking window in days, 1 to 730. |
| Rolling window | A continuous rolling window (sum over the last N days) instead of discrete fixed periods. |

## Claim expiry [#claim-expiry]

Refuses a mint or a transfer when the receiver's claim on any required topic has expired, or was never issued. A claim is a signed attestation on one identity fact, such as KYC status or accreditation, and a trusted issuer is the party the receiver's identity registry trusts to sign it. It checks every topic you select against the receiver's registered identity and accepts only a live claim from a trusted issuer. The sender side is never checked, so a holder whose claim lapsed can still exit the position. Stack it with [identity verification](#identity-verification): the verification expression decides who is eligible at all, and this module decides whether their credentials are still current. The Console warns when a required topic is only one alternative branch of the token's verification expression, because this rule then refuses receivers the expression would accept. This module exists in the second generation only.

| Parameter | Description |
| --- | --- |
| Topics that must stay current | Claim topics checked on every receiver. At least one, at most 16. |
| Grace period (days) | Days past the expiry date a claim is still accepted, to absorb a re-issuance backlog. 0 requires claims to be current. At most 3,650. |
| Require every claim to carry an expiry date | Claims issued before expiry dates were recorded carry none and count as valid by default. Turn this on to reject them, once every holder has a re-issued claim. |

## Collateral requirement [#collateral-requirement]

Refuses a mint unless the token's own on-chain identity carries a live collateral claim, from a trusted issuer, on the configured topic, for at least the required ratio of the resulting total supply. It reads the highest-value valid entry it finds. An expired one does not count.

| Parameter | Description |
| --- | --- |
| Proof topic ID | The claim topic that represents collateral proof. |
| Collateral ratio | Basis points: 10000 = 100%, 20000 = 200%. 0 disables the check. |
| Trusted issuers | Additional claim issuer addresses, added to the issuers the identity registry already trusts. An address you remove here, or every address when you disable or remove the module, stops counting as trusted unless the registry trusts it on its own. |

## Country allow list [#country-allow-list]

Resolves the receiver's registered identity and country, then refuses the operation unless that country is on the allow list. Use it when the permitted jurisdictions are enumerable, such as an offering registered in a fixed set of countries.

| Parameter | Description |
| --- | --- |
| Allowed countries | ISO 3166-1 numeric country codes. |

## Country block list [#country-block-list]

Resolves the receiver's registered identity and country, then refuses the operation if that country is on the block list. A receiver with no registered identity, or one whose country is not on file, is also refused. Only a receiver with a known country outside the block list passes. Use it for sanctions and embargo lists, where everywhere is permitted except the named jurisdictions.

| Parameter | Description |
| --- | --- |
| Blocked countries | ISO 3166-1 numeric country codes. |

## Identity allow list [#identity-allow-list]

Requires the receiver to hold a registered identity whose identity-contract address is on the allow list. That list holds identity-contract addresses, not wallet addresses.

A token holds one identity allow list, because a mint must pass every installed rule and a second list would not admit what the first refuses. On a token's Compliance tab, "Add rule" opens the list the token already has for editing and does not install another.

| Parameter | Description |
| --- | --- |
| Allowed identities | Identity-contract addresses. |

## Identity block list [#identity-block-list]

Refuses the operation only when the receiver holds a registered identity whose identity-contract address is on the block list. A receiver with no registered identity passes through, the opposite fail mode from the identity allow list.

| Parameter | Description |
| --- | --- |
| Blocked identities | Identity-contract addresses. |

Use this list for sanctions. You enumerate the identities, and the holder of a listed identity has no key to edit the list. A wallet recovery gives the holder a new identity, so add that identity to the list after any recovery of a listed holder. A rule that excludes holders of a sanctions claim does not give that protection, because [a holder can remove a claim from their own identity](#excluding-holders-of-a-claim).

## Identity verification [#identity-verification]

Refuses a mint or a transfer unless the receiver's registered identity satisfies the token's verification expression. The expression combines verification topics, such as KYC, AML, or accreditation, with AND, OR, and NOT operators, and can group conditions. A claim counts only when a trusted issuer attested it. This is the standard eligibility gate for a regulated instrument: instead of enumerating approved identities one by one, it admits anyone whose identity carries the right claims. Its single parameter is the verification expression itself, built in the Console's expression builder. While you design an asset or a compliance template, you can leave the expression empty, which means no claim is required. On a live token's module editor and in global controls, the Console does not save an empty expression, so an existing module rule cannot be cleared to admit everyone. The token's Holder rule editor does accept an empty rule, which leaves only the registration floor. When it refuses, the failure is a dedicated recipient-not-verified error, [DALP-4266](https://docs.settlemint.com/docs/api-reference/errors), which does not name the claims the receiver is missing.

### Excluding holders of a claim [#excluding-holders-of-a-claim]

A NOT branch in the expression excludes the holders of a claim topic, as in "verified and not sanctioned". A holder manages their own identity, so a holder who can delete that claim passes the rule meant to catch them. The platform therefore checks every save that puts a claim topic under NOT, in an identity verification rule on a token or in global controls, and in a token's compliance expression. The topic's "Use in exclusions" setting decides the result, and [Verification topics](https://docs.settlemint.com/docs/console/compliance/verification-topics#decide-who-a-rule-may-exclude-with-it) says how to set it.

- A topic set to "Not allowed" refuses the save, and the message names the topic.
- A topic set to "Allowed with acknowledgement" refuses the save until the request carries `holderRemovableNot` with `accepted` set to `true`, sent from a session that is not impersonated. A topic with no stored setting is graded the same way.
- A topic set to "Allowed" saves with no extra step.

The API answers a refused save with `422`. The Holder rule editor on a token's Compliance tab shows the reason and a checkbox that sends the acknowledgement with the next save. The identity verification module editor and global controls have no such control, so a save there that excludes a topic set to "Allowed with acknowledgement", or a topic with no stored setting, is refused until you narrow the rule. The expression builder marks a topic that needs the acknowledgement with a "Holder-removable" badge and a refused topic with "Cannot be used to exclude". A refused save of a token's compliance expression names three alternatives a holder cannot defeat: an identity block list, a country block list, or a positive claim for the group you admit. A holder who deletes a positive claim loses access instead of gaining it.

## Identity count [#identity-count]

Limits the number of distinct registered identities holding the token and refuses an operation that would add a new identity past a cap. Two wallets registered to one identity take one slot. A receiver without a registered identity is refused, because it has no identity to count.

| Parameter | Description |
| --- | --- |
| Counting policy | Current holders, the default, or lifetime. Chosen at installation, and it cannot be changed afterwards. |
| Maximum investors | Total cap on counted identities. 0 means no total cap. |
| Country limits | Optional cap per country, applied to the country of the wallet the identity first entered with. |

Lifetime counting counts only the identities that receive the token after the rule is added, so a cap set on a token that already has holders leaves those holders out of the count. The Console shows the current holder count and how to set the cap for a total limit, as it does for [wallet count](#wallet-count). Current-holder counting installs only on a token that has no holders yet.

Current-holder counting releases an identity once none of its wallets holds the token. Lifetime counting keeps an identity counted after it exits. Moving a whole position between two wallets of one identity keeps it counted under its original country, so the move cannot slip past a country cap.

A receiver on the compliance bypass list takes no slot, even when it carries an identity and a country. The bypass list holds platform contracts such as XvP settlements and token sales, so anyone who can create one of them cannot use it to fill the cap. A custodian forced transfer can exceed the cap and still counts a receiver that is not on the bypass list. A wallet counted before it joined the bypass list keeps its slot until it releases the usual way, so under lifetime counting it stays counted. The rule runs only on a second-generation engine, because it asks the engine which receivers are on the bypass list.

When a current-holder cap is full, a holder cannot move a whole position to an identity that holds none of the token yet, even though the count would not grow: the rule checks the transfer before the sender leaves. A wallet of the holder's own identity still receives it. Transfer to an existing holder, or burn first.

A current-holder rule can only be installed on a token that has no holders yet, because the rule counts from its first mint. On a token with holders, choose lifetime counting. Global controls cannot use current-holder counting, since a platform-wide rule cannot confirm that every token it governs starts empty.

Current-holder counts are only as complete as the transfers the rule sees. A rule that is disabled and re-enabled, or a scope that skips accounting for transfers it does not check, misses the movements in between. Scope current-holder rules to track the operations they skip.

## Issuance volume limit [#issuance-volume-limit]

Caps how many token units may be issued in a fixed or rolling window. Use it for dilution control, vesting schedules, tranche releases, or operational throttling. A burn releases capacity, attributed to the most recent issuance in the window first (LIFO). This module belongs to the first generation: a first-generation token or policy template takes it, and so do global controls, but a second-generation token refuses it.

| Parameter | Description |
| --- | --- |
| Maximum issuance per period | Token units that may be issued within one period. You can raise or tighten this later. |
| Period length (days) | Length of the issuance window in days: 1 to 36,500, or 1 to 730 for a rolling window. Locked once the module is enabled. |
| Rolling window | Rolling window slides day by day, and a fixed window resets capacity at the end of each period. Locked once the module is enabled. |

## Lock-up [#lock-up]

Blocks transfers until an unlock date, in two forms. The class lock covers the whole token: before its unlock date, the module refuses every transfer, whoever sends it. The holder lock covers one holder: it sets an amount and an unlock date, and before that date the module refuses a transfer that would leave the sending wallet with less than the locked amount. A holder with 1,000 tokens and 600 locked can move 400. A transfer of 401 is refused. Both locks lift at their date with no operator action. Forced transfers, wallet recovery and burns bypass both. This module exists in the second generation only.

The module never refuses a mint. It also never sees a burn, a redemption, a conversion that burns the principal, a custodian forced transfer, or a lost-wallet recovery, because the token does not consult compliance for them. An issuer who needs the lock to cover conversions keeps conversion disabled until the unlock date.

| Parameter | Description |
| --- | --- |
| Class unlock date (UTC) | When the class lock ends, as a date and time in UTC. Leave it empty for no class lock. You can extend, shorten, or lift it later. The API takes `unlockTime` in Unix seconds, with 0 for no class lock. |

A class lock also stops the contracts that move tokens for the issuer. An issuer treasury, or a token-sale, XvP settlement, or trading-venue contract that must deliver or refund during a class lock needs a sender scope exemption. On a token with a burn or redemption fee, the fee collector needs a receiver scope exemption.

### Holder locks [#holder-locks]

The token's governance role sets and clears holder locks from the token's holders list, with "Set lock-up" and "Clear lock-up" on a holder's row, or through the Platform API. "Set lock-up" shows while the token has an active lock-up rule, and "Clear lock-up" only for a holder with a stored lock. The unlock date must be later than the chain's latest block. A lock follows the holder's identity, not one wallet: every wallet of that identity keeps at least the locked amount. Moving tokens between wallets of the same identity is allowed, so consolidate first, then send the free part. Lost-wallet recovery registers the new wallet under a new identity, so the lock does not carry over. Set it again for the recovered wallet.

| Request | Body | Effect |
| --- | --- | --- |
| `PUT /api/v2/tokens/{assetId}/compliance-modules/{instanceAddress}/holder-locks` | Holder wallet, amount in base units, unlock time. | Sets or replaces the holder's lock. |
| `DELETE /api/v2/tokens/{assetId}/compliance-modules/{instanceAddress}/holder-locks` | Holder wallet. | Clears the holder's lock. |

Tranche locks, which release a holding in stages, are not offered.

## Minimum holding [#minimum-holding]

Keeps every non-zero position at or above a floor. It refuses a mint or a transfer that would leave the receiver holding less than the minimum, and refuses a transfer that would leave the sender with a residual balance below it. A full exit passes this module's position-floor check: a holder may go to zero, they may not sell down to a stub. Use it for board-lot rules, minimum subscription amounts, and cap-table hygiene. If the token charges transfer fees, exempt the fee collector's wallet, because the fee leg is far below any sensible minimum and would revert the whole transfer otherwise. Exempt only terminal, issuer-controlled wallets. A receiver on the system bypass list skips the receiver floor, while the sender's residual is still checked. This module exists in the second generation only.

| Parameter | Description |
| --- | --- |
| Minimum holding | Smallest position any holder may keep after an operation, in whole token units. |
| Exempt wallets | Wallets this rule ignores on both sides of a transfer. At most 20. |
| Exempt claims | A wallet whose identity holds one of these claims skips its own minimum, while the other side of the transfer is still checked. A new rule starts with "Escrow account" selected, so escrows can hold and pay out amounts below the minimum. At most 5. |

## Own custody gateway [#own-custody-gateway]

Keeps a custody receipt inside its holder's own custody gateway. A holder can send receipts only to their own gateway or that gateway's escrow. The gateway can book receipts into its escrow, return them to any wallet of the identity it serves, or burn them, and the escrow can pay them back to its gateway or to a wallet of that identity. A mint passes only to a wallet whose identity has a gateway at the configured factory. Every other movement is refused, and the rule also runs for a receiver on the system bypass list. Install it unscoped on custody receipts, not on general assets: a scoped rule skips the transfers outside its scope, and the [custody gateway](https://docs.settlemint.com/docs/concepts/custody-and-signing/custody-gateway) refuses to enable a coin whose receipt has no active rule bound to its factory. This module exists in the second generation only.

| Parameter | Description |
| --- | --- |
| Custody gateway factory | Address of the custody gateway factory whose gateways this receipt is bound to. The Console fills in the organisation's custody gateway add-on. |

## Supply cap [#supply-cap]

Refuses a mint that would push total token supply past the cap. It checks nothing else: this module does not reject transfers or burns, and the module keeps no history of its own, so a burn frees room under the cap immediately. Use it when the constraint is a hard ceiling on units in existence. Use the [issuance volume limit](#issuance-volume-limit) or the [capital raise limit](#capital-raise-limit) when the constraint is a quota per period.

| Parameter | Description |
| --- | --- |
| Maximum supply | The maximum total supply allowed, in whole token units. |

## Time lock [#time-lock]

Requires tokens to age for a minimum hold period before they can move. It tracks acquisitions in first-in-first-out order per holder, so the oldest tokens unlock first. Mints and burns always pass. A transfer needs enough unlocked balance. A new rule on a token starts with escrow payouts exempted: its scope exempts senders holding the escrow claim and keeps tracking their movements. Remove that exemption from the rule's scope if escrows must respect the hold period.

| Parameter | Description |
| --- | --- |
| Hold period (seconds) | Minimum holding period in seconds before tokens can be transferred: 1 second to 10 years. Locked once the module is enabled. |

For a token with a V2 time lock, holder balances show how much of each holder's available balance the lock still holds back. The token's holder list and the investor's holdings return `locked`, `transferable` (what can move now) and `nextUnlockAt` (when more of the balance unlocks), and the Console shows them as Locked and Next unlock. A balance the holder received before the module was installed never unlocks, so it counts as locked.

V1 and V2 differ here. V1 stored its configuration per hook call and let certain identities carry an exemption from the hold period, based on their claims. V2 stores the hold period once in the module itself and drops the exemption field entirely. A token-specific exemption comes from the rule's own scope instead of the module's configuration.

## Token supply limit [#token-supply-limit]

Caps total token supply against a lifetime, fixed-period, or rolling-period limit. Only mints count against the limit. A burn reduces tracked supply, never below zero. This module exists in the first generation only. For a new deployment, three narrower modules cover the same ground with one fixed rule each. The [supply cap](#supply-cap) handles a hard ceiling, the [issuance volume limit](#issuance-volume-limit) a periodic token-unit quota, and the [capital raise limit](#capital-raise-limit) a periodic fiat quota.

| Parameter | Description |
| --- | --- |
| Maximum supply | The maximum supply allowed. In whole token units, unless "Use base price" is on, in which case this is a base-currency amount instead. |
| Period length (days) | Tracking period in days. 0 means a lifetime cap, and greater than 0 means a periodic cap. |
| Rolling window | Use a rolling window instead of fixed periods. Only applies when the period length is greater than 0. |
| Use base price | Convert token amounts to a base currency with price claims before comparing to the limit. |
| Global (issuer-wide) | Track supply across every token for the issuer, instead of per token. |

## Transfer approval [#transfer-approval]

Requires an approval from a designated authority before a transfer executes. Both the sender and the receiver need a registered identity. Mints and burns pass. An approval binds the sender identity and the receiver identity, and the approval mode decides how its amount is enforced. Only an identity named as an approval authority can approve or revoke, and an approval stops counting if its approver is later removed from the authorities.

| Parameter | Description |
| --- | --- |
| Approval authorities | Identity addresses allowed to grant approvals. At least one is required. |
| Approval expiry (seconds) | How long an approval stays valid: a whole number of seconds from 1 to 31,536,000 (365 days). |
| Approval mode | How an approved amount is enforced: an exact amount, up to once, or up to a total. Locked once the module is enabled. |

V1 and V2 differ here. The earlier generation has a one-time-use switch and lets certain identities carry an exemption from the approval requirement, based on their claims, and binds each approval to an exact amount. V2 replaces the one-time-use switch with the approval mode above. It also drops the claim-based exemption in favour of an exemption for a designated fee recipient, needed for fee-splitting transfers. If the token charges transfer fees, avoid exact amount: the fee leg's net amount never equals the approved value, so the transfer reverts. Use up to once or up to a total instead, and exempt the fee leg's destination address as the fee recipient. An approval authority sets that exemption with a direct call to the rule's contract. The Console and the Platform API do not offer it.

## Wallet count [#wallet-count]

Limits the number of distinct wallets holding the token and refuses an operation that would add a new wallet past a cap. Each wallet counts on its own, even when several belong to one identity. Use [identity count](#identity-count) to count identities. A wallet does not need a registered identity to be counted. A receiver on the compliance bypass list is never counted, as for [identity count](#identity-count).

| Parameter | Description |
| --- | --- |
| Counting policy | Current holders, the default, or lifetime. Chosen at installation, and it cannot be changed afterwards. |
| Maximum investors | Total cap on counted wallets. 0 means no total cap. |
| Country limits | Optional cap per country, applied to the wallet's registered country when it was first counted. |

Lifetime counting counts only the wallets that receive the token after the rule is added. The holders a token already has are not counted until they next receive it, so a cap of 3 on a token with 3 holders still admits 3 more wallets. To keep such a token at N holders or fewer, set the cap to N minus its current holders. The Console shows the current holder count and this advice before you confirm, and the rule reads "At most 3 new wallets" instead of "At most 3 wallets". Current-holder counting installs only on a token that has no holders yet, so on a token with holders the Console disables it and starts on lifetime.

Wallet count is the current generation of the rule earlier releases called investor count, and an existing investor count rule becomes a wallet count rule without losing its count. Such a rule keeps lifetime counting. It cannot add country limits, because the wallets it counted before the upgrade carry no country. The Console explains this when you try, and the maximum keeps applying. Installation and completeness follow the same rules as [identity count](#identity-count).

The first generation behaves differently. It tracks a global cap and per-country caps in the same configuration, filters which investors count with a claim expression, and drops an investor from the count once a balance reaches zero.

## When a module refuses [#when-a-module-refuses]

A module refusal reverts the operation. Detailed errors identify the module. A generic transfer or mint rejection may need simulation to locate the blocker.

A V2 module fails with a compliance error, [DALP-1120](https://docs.settlemint.com/docs/api-reference/errors), that carries the refusing module instance, its type, a machine-readable reason code, and a human-readable reason. A V1 module fails with a compliance error, [DALP-1009](https://docs.settlemint.com/docs/api-reference/errors), that carries the plain-text reason alone, so you read the text to find the rule. V1 does not separate the module's identity from its message the way V2 does. The [contract error reference](https://docs.settlemint.com/docs/api-reference/errors/error-code-reference) documents both error envelopes in full.

A plain transfer or mint can instead fail before any module's detail is available: [DALP-1096](https://docs.settlemint.com/docs/api-reference/errors) for a transfer, [DALP-1110](https://docs.settlemint.com/docs/api-reference/errors) for a mint. Both carry no reason code and name no module, whether the receiver lacks a verified identity or a compliance rule blocked the operation. Use the "Transfer pre-check" tab to find the specific rule before you retry.

Two modules refuse through their own dedicated errors rather than a reason code. Transfer approval fails with [DALP-4036](https://docs.settlemint.com/docs/api-reference/errors) when no approval exists, [DALP-4035](https://docs.settlemint.com/docs/api-reference/errors) when an existing approval's validity window has passed, and [DALP-4034](https://docs.settlemint.com/docs/api-reference/errors) when the approval was limited to a single use that has been spent. It fails with [DALP-4423](https://docs.settlemint.com/docs/api-reference/errors) for a transfer above the amount an approval has left, [DALP-4118](https://docs.settlemint.com/docs/api-reference/errors) when the sender or receiver has no registered identity, and [DALP-1093](https://docs.settlemint.com/docs/api-reference/errors) when the approval's approver is no longer an approval authority. Identity verification fails with a recipient-not-verified error, [DALP-4266](https://docs.settlemint.com/docs/api-reference/errors), which does not name the claims the receiver is missing.

Most reason codes map to exactly one module. The count modules share theirs.

| Module | Reason code |
| --- | --- |
| Block addresses | `COMPLIANCE_CHECK_REASON_ADDRESS_BLOCKED` |
| Claim expiry | `COMPLIANCE_CHECK_REASON_CLAIM_EXPIRED` |
| Claim expiry | `COMPLIANCE_CHECK_REASON_CLAIM_MISSING` |
| Country block list | `COMPLIANCE_CHECK_REASON_COUNTRY_BLOCKED` |
| Country allow list | `COMPLIANCE_CHECK_REASON_COUNTRY_NOT_ALLOWED` |
| Issuance volume limit | `COMPLIANCE_CHECK_REASON_EXCEEDS_QUOTA` |
| Capital raise limit | `COMPLIANCE_CHECK_REASON_EXCEEDS_RAISE_LIMIT` |
| Supply cap | `COMPLIANCE_CHECK_REASON_EXCEEDS_SUPPLY_CAP` |
| Wallet count | `COMPLIANCE_CHECK_REASON_EXCEEDS_COUNTRY_LIMIT` |
| Identity count | `COMPLIANCE_CHECK_REASON_EXCEEDS_COUNTRY_LIMIT` |
| Wallet count | `COMPLIANCE_CHECK_REASON_EXCEEDS_TOTAL_LIMIT` |
| Identity count | `COMPLIANCE_CHECK_REASON_EXCEEDS_TOTAL_LIMIT` |
| Identity block list | `COMPLIANCE_CHECK_REASON_IDENTITY_BLOCKED` |
| Identity allow list | `COMPLIANCE_CHECK_REASON_IDENTITY_NOT_ALLOWED` |
| Collateral requirement | `COMPLIANCE_CHECK_REASON_INSUFFICIENT_COLLATERAL` |
| Time lock | `COMPLIANCE_CHECK_REASON_INSUFFICIENT_UNLOCKED` |
| Lock-up | `COMPLIANCE_CHECK_REASON_LOCKED_UNTIL` |
| Minimum holding | `COMPLIANCE_CHECK_REASON_RECIPIENT_BELOW_MINIMUM_HOLDING` |
| Minimum holding | `COMPLIANCE_CHECK_REASON_SENDER_BELOW_MINIMUM_HOLDING` |
| Own custody gateway | `COMPLIANCE_CHECK_REASON_NOT_OWN_CUSTODY_GATEWAY` |

One reason code is shared by four modules, for a receiver with no registered identity.

| Module | Reason code |
| --- | --- |
| Country allow list, Country block list, Identity allow list, Identity count | `COMPLIANCE_CHECK_REASON_IDENTITY_UNKNOWN` |

Capital raise limit fails closed on a bad price too, with its own code per cause.

| Cause | Reason code |
| --- | --- |
| The rule holds no price resolver address | `COMPLIANCE_CHECK_REASON_NO_PRICE_RESOLVER` |
| The resolver returns a zero or negative price | `COMPLIANCE_CHECK_REASON_NO_VALID_PRICE` |
| The resolver's price is stale | `COMPLIANCE_CHECK_REASON_STALE_PRICE` |

A price feed the resolver cannot find fails with the price resolver's own error, which carries no reason code.

Token supply limit stays on the plain-text V1 error, because it has no reason code of its own. Time lock can also fail with two internal bookkeeping codes, when its stored batches cannot be updated safely or a legacy token's batches are unbound.

| Cause | Reason code |
| --- | --- |
| The module's stored batches could not be updated safely during removal. | `COMPLIANCE_CHECK_REASON_TOKEN_REMOVAL_FAILED` |
| A legacy token's time-lock batches are not bound to this compliance engine. | `COMPLIANCE_CHECK_REASON_UNSAFE_LEGACY_TOKEN` |

Treat both as a platform condition to escalate, not a rule refusing a party.

A refusal reflects the rule and the on-chain state current at the moment the operation ran, not a transient fault. Retrying the same operation unchanged fails again for the same reason. Retry only after the condition behind the reason code changes. A list refusal clears when the country or identity is registered on, or removed from, the relevant list. An expired-claim refusal clears when the claim is re-issued. A limit refusal clears when the configuration is edited, the tracking window rolls over, or the amount is adjusted to clear a position floor. A burn frees room only under a module that credits burns back to its capacity. The capital raise limit never does, so a burn cannot clear that particular refusal.

Before retrying, open the token's "Transfer pre-check" tab. It shows for users who can freeze addresses on the asset and for users who hold System manager, Identity manager, Verification issuer or Compliance manager. Enter a "Sender", a "Recipient" and an "Amount", then select "Run check". The tab runs the same compliance evaluation against that proposed transfer without submitting anything, and groups the blockers it finds by who can resolve them. The blocker detail follows the roles of the wallet that signs your actions. Use the check to confirm the condition has changed.

## Troubleshooting [#troubleshooting]

**A module you expect is not offered**

The Console filters the catalogue to modules compatible with the surface's module-set generation and hides modules
already enabled there. A second-generation module does not appear on a first-generation policy template, and a module
the token already carries is not offered twice.

**A configured field cannot be changed**

Some fields lock once the module is enabled: the issuance volume limit's period length and window mode, the time
lock's hold period, the transfer approval mode, and every parameter of the capital raise limit. The Console marks the
locked field. To use a different value, remove the module and install a new instance. The new instance starts with no
memory of what the old one had tracked.

**Adding the capital raise limit, or creating an asset with it, fails**

The module converts mint amounts to fiat through the price resolver addon. While the system lacks that addon, asset
creation fails and adding the rule to a token or as a global control is refused with `DALP-199482`. Install the addon
first, then try again.

**A refusal names a rule no token-level module explains**

Check the rows marked "Global" in the "Rules" table of the token's "Compliance" tab. Global controls apply to the
token automatically, refuse operations the same way its own rules do, and show "Set in Compliance › Global controls"
in the Setting column: change them in global controls, not from the token.

**A country sits on both the allow list and the block list**

No holder in that country can then satisfy both rules, so an ordinary transfer or mint to that receiver fails when
both rules apply. If every allowed country is also blocked, no country satisfies both rules. Check for overlap between
the country allow list and the country block list before deploying both on the same token.

## Frequently asked questions [#frequently-asked-questions]

### Does burning tokens free up capacity under a limit?

It depends on what the module counts. The supply cap reads live total supply, so a burn frees room immediately. Token supply limit reduces its tracked supply on a burn, and the issuance volume limit credits a burn against the most recent issuance in the window. The capital raise limit never credits burns, because it measures gross capital raised: once value has been raised in a window, redeeming tokens does not un-raise it.

### Can one control apply different limits to different holders?

Yes, on second-generation modules. A V2 control carries one or more rules, and each rule has its own configuration and its own scope: senders and receivers included or excluded by claim topics and by countries. A per-country investor cap, for example, is a separately scoped rule beside the global one. A scope can also track operations it does not check, so reporting still sees transfers the rule deliberately skips.

### What happens to existing holders when a stricter rule is enabled?

Nothing, until they transact. Applicable checks and hooks run during execution. Enabling a rule does not claw back balances or revisit completed operations. A holder who no longer qualifies keeps their position but is refused as a receiver the next time tokens move toward them. A scope edit works the same way: it decides which later movements the rule checks and does not revisit existing holders.

## Related concepts [#related-concepts]

- [Compliance Policy](https://docs.settlemint.com/docs/concepts/compliance-and-identity/compliance-policy): How policy templates and global controls bring these modules to a token.
- [Transfer-Path Compliance](https://docs.settlemint.com/docs/concepts/compliance-and-identity/transfer-path-compliance): How a token runs its modules inside the transfer, and how a simulation finds the blocker.
- [On-Chain Identity](https://docs.settlemint.com/docs/concepts/compliance-and-identity/onchain-identity): The claims and identities that the identity modules read.


# Compliance Policy

Source: https://docs.settlemint.com/docs/concepts/compliance-and-identity/compliance-policy
A Compliance Policy lets a compliance team write eligibility and holding rules once, while an organisation-wide floor reaches every bound token.



[Figure] One compliance policy, a copied token layer plus a live global layer. A published Policy Template is copied into a new token at creation and becomes that token's own controls, which the token can later edit through its own bindings. Global Controls stay live in the system Compliance Engine and reach every token bound to it. A token movement must pass both layers before balances change. Labels: One compliance policy, two layers; Policy Template; Reviewed, reusable controls; Versioned off-chain record; copied at creation; Token policy; Modules bound to this token; Edited per token afterwards; checked live; Global Controls; Live in the system Compliance Engine; Mandatory floor for every token bound to the shared engine; Both layers checked.

A Policy Template is copied into the token's own policy at creation, and every movement then checks that policy and the system's Global Controls live.

A Policy Template lets a compliance team approve eligibility, jurisdiction, holding, and approval rules once, then hand asset teams something ready to select at creation. A later edit to the template never rewrites a token already issued.

Global Controls let a Compliance manager set a rule once and reach every token bound to the organisation's system Compliance Engine on that network, without editing each token by hand. Each token factory binds the tokens it deploys, and a factory migration binds older tokens.

A movement must pass both layers before it settles. On a second-generation engine, a recipient on the compliance bypass list skips only the checks that judge whether it may hold the token. DALP manages that list. [Who manages the compliance bypass list](https://docs.settlemint.com/docs/concepts/compliance-and-identity/compliance-policy#who-manages-the-compliance-bypass-list-and-how-does-an-address-end-up-on-it) says who can still change it. One failing rule in either layer reverts the movement in full before balances change.

## Why an asset team starts from an approved template [#why-an-asset-team-starts-from-an-approved-template]

An asset programme rarely stops at one token. A compliance team that approves eligibility, jurisdiction, holding, and approval rules for a corporate bond does not want to rewrite the same rules for the next issuance under that programme. A Policy Template lets that team approve the rule set once and hand it to an asset team to select.

[Asset Lifecycle](https://docs.settlemint.com/docs/concepts/issuing-and-markets/asset-lifecycle) names where that choice attaches. An Instrument Template binds four design inputs together at deployment: the asset's business class, the facts it records, the features it carries, and the compliance choice that governs it. A Policy Template is what a compliance team hands to that fourth input. Once the asset is live, the same choice surfaces again in its own workspace as a compliance configuration tab, so a reviewer reads the rules the token enforces and compares them with the approved template.

Without a reviewed template, each new issuance starts blank. A compliance team writes the same kind of rule from scratch for every asset, or an asset team improvises its own version. A due-diligence reviewer then checks each token's policy on its own, instead of pointing to one approved shape reused across the programme. With a template, every token can start from something a compliance team already reviewed. The platform does not record which template an asset used, so a reviewer matches its bindings to the template.

## Why the platform still enforces its own floor [#why-the-platform-still-enforces-its-own-floor]

A platform owner needs a different guarantee: one rule that reaches every token regardless of which template it started from, so a token's own rules cannot switch off an organisation-wide requirement. Global Controls answer that. Every token factory binds the tokens it deploys to the system Compliance Engine, the shared engine of the organisation's system on that network. A Compliance manager installs a rule once in that engine, and it reaches every bound token, including tokens created later, whether or not the token's own template ever named the rule. Without Global Controls, a platform owner would edit each live token by hand whenever a new floor is required. That work grows with the number of tokens.

The two layers do not answer to the same clock. A Policy Template ties to one point in an asset's working life, the Design and Service stages [Asset Lifecycle](https://docs.settlemint.com/docs/concepts/issuing-and-markets/asset-lifecycle) already names. Global Controls sit outside any one stage: they check every mint and transfer a token makes, and receive every burn for their counts, for as long as the deployment runs. A Compliance Policy is the pair of them together: a reviewed template an asset team selects, plus an organisation-wide floor that the template and the token's own rules cannot switch off. Only a Compliance manager changes that floor. A holder of the token's Governance role can still replace the token's compliance contract with a direct contract call, so review who holds Governance.

## What each layer holds [#what-each-layer-holds]

A template is a starting configuration, not a promise that every existing token changes when the template changes. The platform copies the chosen modules, each one a configured rule with its own values and scope, into the new token's on-chain compliance engine. This gives each issued token a stable, inspectable policy. Global Controls hold no such copy: each token consults the system engine directly on every transfer, so a change to a Global Control reaches every bound token at once. Both layers are enforced inside the transfer path before settlement, and each has its own owner, scope and change path.

## How teams use the two policy layers [#how-teams-use-the-two-policy-layers]

Day to day, a Compliance Policy divides work between programme policy and platform policy. A compliance team drafts a Policy Template, chooses its module generation, first or second as [Compliance modules](https://docs.settlemint.com/docs/concepts/compliance-and-identity/compliance-modules) defines them, when the deployment allows first-generation templates, adds controls and scopes, then publishes it for asset teams. [Policy templates](https://docs.settlemint.com/docs/console/compliance/policy-templates) and [Global controls](https://docs.settlemint.com/docs/console/compliance/global-controls) show the Console steps. Choose the second generation unless the template needs a control that only exists in the first, such as the issuance volume limit or the token supply limit. A handful of newer controls, such as a capital-raise limit or a minimum-holding requirement, exist only in the second generation. The choice is permanent: a template cannot mix generations. A required control incompatible with the saved generation can never be configured on that template, so the only fixes are dropping the control from the required list, or requiring a compatible one instead. An instrument template links the published template, and an asset team issuing from it starts from those controls instead of reconstructing them.

The template can carry two kinds of content: required controls and configured modules. Required controls name the rule types the template must include before it can publish. A readiness check blocks publishing a template that is missing one. Configured modules carry the values and scope that are installed on the token. Drafts remain editable. Published templates are available for selection. Platform library templates are read-only, while an organisation can copy one and maintain its own version.

A Compliance manager manages Global Controls separately. A global module can restrict every token bound to the system Compliance Engine or use token scope to narrow where it applies. Installing or changing it affects the system Compliance Engine, not the Policy Template catalogue. Operators therefore review two views when they need the effective policy: the token's own module bindings and the inherited Global Controls.

Choose where to put a rule by who it must reach and who may change it.

| Put the rule in | When it is right | What it costs |
| --- | --- | --- |
| A Policy Template | The rule belongs to an asset programme and should shape future tokens. | Existing tokens keep their current policy. The edit only reaches new ones. |
| One token's own bindings | A single live token needs a rule its programme does not share. | The change stays on that token. Repeating it by hand brings back the drift templates exist to remove. |
| A Global Control | The rule must reach every token bound to the system engine. | An organisation-wide change by a Compliance manager. It reaches every bound token at once. |

When a transfer fails, the failed module blocks the movement before balances change, and the caller receives [DALP-1096](https://docs.settlemint.com/docs/api-reference/errors/error-code-reference#compliance--token-operations) for a transfer or [DALP-1110](https://docs.settlemint.com/docs/api-reference/errors/error-code-reference#compliance--token-operations) for a mint. Neither error names which layer rejected the movement. To find the failing rule, the operator reads both the token's own bindings and the inherited Global Controls, or runs the same transfer on the token's "Transfer pre-check" tab, which names the failing rule. The operator then fixes the underlying eligibility, scope, limit, or approval condition.

## Where reuse ends and inheritance begins [#where-reuse-ends-and-inheritance-begins]

A Compliance Policy composes two on-chain compliance engines. Each second-generation token has its own engine with address-keyed module bindings, and the organisation's system also has one shared Compliance Engine on each network. A first-generation token has no engine of its own: it calls the shared engine directly, which runs that token's modules and then the Global Controls. During a token movement, the token evaluates active, in-scope local modules and then delegates to the system engine, as shown in the two-engine flow.

[Figure] One movement is checked twice before it settles. A token movement first runs the token's own engine, which evaluates the active, in-scope modules bound to this token. That engine then delegates to the system Compliance Engine, which evaluates the inherited Global Controls. When both layers pass, balances change. When any check fails, the whole movement reverts and nothing settles. Labels: Token engine; This token's own modules; active and in scope; delegates; System engine; Inherited Global Controls; the shared floor; both pass; any failure; Balances; change; Reverts; nothing settles.

The token engine evaluates its own modules first, then delegates to the system engine for the Global Controls, and either layer can revert the movement.

Policy Templates live off-chain as versioned settings records. A template stores its module-set version, jurisdictions, module configurations, scopes, and required control types. Applying one expands that record and installs the resulting bindings on the token. The token keeps only those bindings, so a later template edit never reaches it.

Global Controls live on-chain in the system Compliance Engine. Module types must first be registered in the system's compliance module registry. Registration only makes a type available. A separate install creates a configured binding on the system engine. Each token factory binds the tokens it deploys to that engine, and a factory migration binds the older tokens that factory deployed, so every bound token inherits the engine's active controls.

Scope preserves the difference between universal and targeted rules. Both engines evaluate sender and receiver scope the same way: by identity claims or by country. Only the system engine takes a token dimension. A token's own engine refuses one, since it is already bound to a single token. On the system engine, scoping by token lets one installed control cover a selected group of tokens instead of all of them.

## One policy, two API surfaces [#one-policy-two-api-surfaces]

Policy Templates are settings resources: create, update, publish, list, read, and delete operations. Reading one template also lists the instrument templates that link it, and deleting the template clears that link on each of them. Token bindings and inherited Global Controls are separate read surfaces, because they describe separate on-chain engines rather than the template catalogue.

A template targets one module-set version. First- and second-generation module types cannot be mixed in one template, and the version cannot change after the template is saved. The API refuses a module or required control of the other generation. It also checks every value of a supply cap, a first-generation investor count or a token supply limit, and the approval expiry of a transfer approval. Other values, such as approval authorities, can stay open until issuance. A published, second-generation template can then be linked to an instrument template. When an asset is issued from it, its configuration is expanded into token module writes.

Global installation targets the system Compliance Engine, not the system's compliance module registry. Registering a module type is only a prerequisite. Install, reconfigure, enable, disable, scope, and uninstall operations address the configured binding on the system engine. Reads of inherited controls resolve those bindings for a selected token, including whether each control is active and in scope.

Integrations should read both layers when they present the effective policy. A token-module list alone omits the mandatory floor. A global-control list alone omits the asset-specific policy. Transfer prechecks and on-chain execution remain the final authority because scope and identity state can change.

## Control ownership and audit evidence [#control-ownership-and-audit-evidence]

A Compliance Policy splits control into two domains. Policy Templates hold the approved pattern for an asset programme. Global Controls hold the organisation-wide rules that a bound token's own rules cannot switch off. Both domains use the same registered module types, but approval of one does not authorise changes to the other.

The evidence for a token starts with its current local bindings, which show what the token enforces now, including active state and scope. The platform does not record which template or template version an asset was issued from, so match the bindings against the approved template rather than assuming they track it. The inherited-control read adds a third source: the system Compliance Engine bindings that also reach that token.

Two conclusions do not follow from this evidence. A published template proves what was approved for reuse. It does not prove that every existing token tracks later template edits. An inherited Global Control proves a live system-level rule reaches the token. It does not prove that the token has no additional local restrictions.

For an ordinary transfer or mint, every active, in-scope module must pass or the movement reverts before balances change. Three paths sit outside that guarantee. On a second-generation engine, a recipient on the compliance bypass list skips, in both layers, the checks that judge whether it may hold the token: country and identity lists, identity verification, claim expiry, holder counts and transfer approval. Sender-side and supply checks still run. A first-generation engine skips every module for a bypassed recipient. A forced transfer skips both layers' module checks, the pause and the sender's freeze, gated by the token's Custodian role. It still refuses a recipient whose address is frozen on the token and runs the recipient's identity check in the identity registry, as [Transfer-Path Compliance](https://docs.settlemint.com/docs/concepts/compliance-and-identity/transfer-path-compliance) describes. A wallet recovery skips the same checks and can deliver into a frozen replacement wallet, gated by the Identity manager who records the lost wallet and names its replacement. Reviewing a token's effective policy means checking the bypass list and who holds Custodian, Governance, Identity manager, System manager, Compliance manager and Escrow manager alongside the bindings. A token is inside the shared floor only once it is bound to the system engine, so an older token needs review until a factory migration binds it.

## Frequently asked questions [#frequently-asked-questions]

### How do policy and instrument templates differ?

They shape different layers of a new token. An [Instrument Template](https://docs.settlemint.com/docs/concepts/modeling-assets/instrument-templates) defines a product: the facts an instrument records, the behaviours it carries, and the compliance rules it follows. A Policy Template packages only compliance controls, with its own review, publication, and versioning path, so one reviewed rule set can serve products whose facts and features differ.

### Does a module that is out of scope for a movement still do anything?

An out-of-scope module can still update its accounting. Scope decides whether a module's validation runs for that movement, but a module can be configured to keep running its accounting regardless. A module set to skip everything when it is out of scope skips both the check and its own bookkeeping. A module set to only skip validation keeps updating its state on every movement, even when out of scope. That is why a module that tracks running balances, such as a holding limit, still reads accurately after a movement it did not validate.

### Do compliance checks cover minting and burning as well as transfers?

Minting runs the same two-layer check as a transfer, with the sender side empty, so an issuance that fails a rule reverts before any supply exists. Burning runs no eligibility check, and the token's Supply management role can burn from any holder's wallet. Both engines are notified after the burn, which keeps modules that track balances accurate, and a notification that reverts also reverts the burn. For a forced transfer or wallet recovery, the recipient still has to clear identity verification: a current [On-Chain Identity](https://docs.settlemint.com/docs/concepts/compliance-and-identity/onchain-identity) registry checks the recipient's claims, and an older registry falls back to confirming the recipient is registered at all.

### Who manages the compliance bypass list, and how does an address end up on it?

DALP manages it. The system Compliance Engine holds the list, not the token or its administrator, and nothing on the token can add an address to it. A token factory adds each token it deploys, and an add-on factory adds each add-on it deploys. That includes every escrow an Escrow manager creates, for whatever controller the creator names, so the Escrow manager role puts each new escrow on the list. No Console screen or Platform API route edits the list directly. A System manager can change the list by registering a custom token factory or add-on, or by pointing a registered one at new code, because every registered factory and add-on can add and remove addresses. A Compliance manager can change it with a direct call to the system Compliance Engine. The chain records every change to the list with the account that called the Compliance Engine: the factory for an address it adds or removes, the calling account for a direct call. [Control ownership and audit evidence](#control-ownership-and-audit-evidence) gives the effect of a bypass.

## Related concepts [#related-concepts]

- [Asset Lifecycle](https://docs.settlemint.com/docs/concepts/issuing-and-markets/asset-lifecycle): The whole working life of a regulated tokenised instrument. A Policy Template binds into its Design stage and surfaces again in the Service stage's compliance configuration tab.
- [Transfer-Path Compliance](https://docs.settlemint.com/docs/concepts/compliance-and-identity/transfer-path-compliance): The enforcement of a regulated token's rules inside the on-chain transfer itself, so a movement that fails any rule reverts and never settles.
- [On-Chain Identity](https://docs.settlemint.com/docs/concepts/compliance-and-identity/onchain-identity): The ledger record of one subject's verifications that a regulated token checks before a transfer, read here by the identity registry a forced transfer or recovery still has to clear.
- [Instrument Templates](https://docs.settlemint.com/docs/concepts/modeling-assets/instrument-templates): Reusable product shapes that bind instrument facts, required features, and a compliance choice.
- [Composable Token](https://docs.settlemint.com/docs/concepts/modeling-assets/composable-token): One regulated contract model configured per instrument with the features and compliance rules it needs, including its own per-token compliance engine.


# Delegated Authority

Source: https://docs.settlemint.com/docs/concepts/compliance-and-identity/delegated-authority
Delegated Authority lets a signed-in operator work inside another party's account. One check decides who may enter. The party's own roles decide the rest.



[Figure] One delegated operation carries two identities. A delegated operation carries two identities at once. The operator stays signed in as themselves and uses their own credential. The party is the organisation or account the operator is working for, and it supplies the roles, the data, and the account. Between them sits one entry check, which asks whether this operator may work in this party's context, answered from a role the party already granted, so no separate delegation list exists. Once the check passes, the instruction runs from the party's account, while the operator's own credential unlocks the submission. Two records survive: the platform trail names the operator, the role held, the route, and the outcome, and the ledger names the party's account as the sender of the transaction. Entering a context grants no role. Labels: One delegated operation; Operator; Signs in as themselves; Their own credential; Party; An organisation or an account; Its roles, its data, its account; Entry check; May this operator work in this party's context?; Answered from a role the party already granted; The instruction runs from the party's account; The operator's own credential unlocks the submission; Platform trail; The operator, the role held,; the route, the outcome; Ledger record; The party's account as the; sender of the transaction; Entering a context grants no role.

Entry is one decision, and what the operator may do inside is a second decision against the party's own roles.

Delegated Authority lets a signed-in operator work inside another party's context, which the Console calls Working as. A party is a participant other than the operator's own, an organisation or an account. Entering its context grants no role: the party's own roles decide what the operator may then do.

A delegated operation carries the operator's name in the platform trail. The ledger names the party's account as sender.

Organisation entry uses existing on-chain role grants. Account entry follows from a wallet the user already controls.

## One person, many entities [#one-person-many-entities]

Delegated Authority lets one named person operate for more than one legal entity without any of them sharing a login. An operations lead who administers three issuing entities works under their own account throughout, and every instruction they send for an entity stays attached to their name.

The usual alternative is a shared service account per entity, and it removes attribution. An auditor asking who moved a position gets an account name rather than a person, and one leaver means rotating a credential the whole desk knew. A regulator reviewing that movement needs a named individual on the platform side. The on-chain write still has to settle from the entity's own account.

Stepping into an entity's context changes what an operator can see and which account their instructions come from. It changes nothing about what that entity may do. The platform denies an instruction the entity's own roles forbid, whether or not an operator stands in its context. That separation lets an institution widen who may operate an entity without reopening what the entity may do.

Granting entry also grants authority. An operator who can enter the organisation's context sends instructions from the organisation's wallet, so they can do whatever that wallet's roles allow. Organisation identity manager, the role that lets an operator in and not the platform's Identity manager role, also lets them add or remove keys on the organisation's own on-chain identity and issue claims from it. Permission manager opens the same door and can also grant every other system role. Grant Organisation identity manager when the operator's job is entity administration and organisation-identity changes from them are acceptable. Reserve Permission manager for operators who need that broader scope too.

No separate delegation list exists to maintain. Entitlement comes from grants that already exist, chiefly a Permission manager or Organisation identity manager role the entity has already granted to the operator in its own system access manager on the ledger. Revoke that role and the ability to act for the entity goes with it once the platform has indexed the revoke.

## One control marks, enters, and leaves a context [#one-control-marks-enters-and-leaves-a-context]

Delegated Authority appears in the Console as Working as. While you work in another party's context, a violet "Working as" bar opens every page with that party's name and Return to yourself, and the account menu button at the top right turns violet and reads "Working as" followed by the party's name. On the participants pages, the Working now badge uses the same violet. The Working as submenu leaves out a multisig wallet you sign for. That wallet opens as its own account under Shared accounts, with an Approvals tab, and its page offers Work as this participant.

The [My participants](https://docs.settlemint.com/docs/console/my-account/acting-as-participants) guide walks the control end to end: opening it, reading a row's kind and role, choosing a party, and returning to yourself.

A party you cannot operate right now still appears, disabled, with the reason on its row: no smart wallet on the ledger network you have selected, or no wallet the organisation can drive. Creating a party provisions its wallet, so a row stalled partway through that setup shows the wallet missing, not a fault in the switcher. Finish that setup or wait for it to finish.

Switching clears work the browser was holding, including a pending deployment and an unfinished instrument draft, so switch before you start rather than during. The network you selected survives.

Switching to the same party again never unblocks an operation. When the platform declines one, changing context does not change the answer: look to the party's own role, or, for a multi-signature account, to its signer set and its threshold.

## Two decisions, two accounts [#two-decisions-two-accounts]

The first decision asks whether this operator may work inside this party's context. The second asks whether the account that executes holds the role the operation requires. Widening the first never widens the second.

The first decision reads authority that already exists rather than a delegation table. For an organisation, the operator's own account must hold Organisation identity manager or Permission manager in that organisation's system access manager. Organisation identity manager is not the platform's Identity manager role, which manages the shared identity registry. The platform reads the role from its record of the organisation's system access manager on the ledger network the request names, so a grant or a revoke counts once the platform has indexed it. Entitlement is therefore per network:

**Network A**

The organisation runs a system here, and the operator's account holds an entitling role in it. Entry into the organisation's context is allowed on this network.



**Network B**

The same organisation, a different network. Either it runs no system here, or the operator holds no role in the one it runs. Entry is blocked on this network, and the role held on network A means nothing here.

A party that is an account rather than an organisation works differently. The platform admits the user's own person account when this organisation can drive its wallet, and any account that a wallet under the user's control signs for, such as a multisig in which that wallet holds a signer seat. No separate grant exists: removing the seat removes the entitlement. The platform rejects every other kind of party.

The second decision belongs to the account that executes. The platform resolves the party's own account and sends the instruction from it, so the role checks that decide the operation run against that account on the ledger. The operator's own credential still unlocks the submission. Before the instruction queues, the platform asks the operator for the second factor enrolled on their own account, a code or a personal identification number, and checks it against their enrolment rather than the party's.

Refusals are uniform. A context the operator may not enter, a party inside an organisation they do not belong to, and a party that does not exist all get the same response: a read runs in the operator's default context, their saved Working as choice or else their own, and a write is refused.

## The context lives on one request header [#the-context-lives-on-one-request-header]

Delegated Authority reaches the Platform API as one request header. Send the party's participant identifier in `X-Participant` and the request runs in that party's context. Omitting the header uses the session's current participant. Whichever participant the platform admits, by header or by session, every read and role check scoped to the caller's wallets uses that participant's wallets only: holdings, events, asset search, transaction status and the transaction list with `ownership=caller`. The routes on one multisig wallet (its details, signers, controllers, gas status, approvals and signer changes) also count the caller's own signing keys, because a signer seat belongs to the person. So do the multisig approvals in the actions list of a request that works as that multisig wallet. The list of multisig wallets does not. A request that acts as no one else reads the caller's own participant. A read that names a party the platform refuses runs in the caller's default context and returns `X-Participant-Dropped`. Send an explicit participant identifier when a request must use a specific authorised context. Concurrent requests can name different participants.

[Figure] The context never outlives the request. One caller with one credential sends three requests. A request whose header names party A runs in A's context. A request whose header names party B runs in B's context, concurrently with the first. A request with no header uses the session participant. Labels: The context never outlives the request; One caller; one credential,; three requests; Header names party A; the request runs in A's context; Header names party B; the request runs in B's context, concurrently; No header; the request uses the session participant.

An explicit header selects the participant for one request, so concurrent requests can name different participants, and no header means the session participant.

Build the switcher from the assumable participants endpoint rather than from your own model of who may act for whom. The [API explorer](https://docs.settlemint.com/docs/api-reference/v2) documents its request and response shape under the Participants tag. That endpoint returns exactly the set the entry check would allow on the selected network, and its identifier for each party is the value to send in the header. Each entry also lists the party's kind, the qualifying role for an organisation, and an availability flag whose reason tells you why the caller cannot use that party yet.

A read that names a party the caller may not enter runs in the caller's own context and carries the `X-Participant-Dropped` response header, so check that header before you treat the data as the party's. A read whose answer is the same for every participant, such as the public configuration, is served from the cache without the entry check and never carries the header. A write that names one returns [DALP-0524](https://docs.settlemint.com/docs/api-reference/errors) with the same header. Both answers are the same whether the party is one the caller may not enter or one that does not exist. That is deliberate: the response must not disclose which participants exist in this tenant or any other. It is therefore not evidence about existence, and retrying it changes nothing. Re-read the assumable list instead: revoking a role on the ledger drops a party from that list with no other signal.

The check runs before the platform queues any ledger operation, so a denied context leaves no partial submission to reconcile. A request that passes the check can still fail later, when the party's own roles are checked against its account on the ledger. The fix there is a role grant on the party's own account, not the operator's, since the operator already cleared the entry check.

## Attribution needs both records [#attribution-needs-both-records]

A delegated operation leaves two records, and attribution needs both. The platform's own trail names the person who acted, the participant they acted as, their platform and organisation role at that moment, the route they called and how it ended. Read role history for the on-chain role that let them in. The ledger names the party's account as the sender of the transaction and does not name the person. Sign-in events are recorded separately, and a sign-in can succeed without its audit entry, as the Audit Trail, the append-only log of platform activity, describes.

Entitlement is itself evidence. For an organisation, the operator's own role in that organisation's system access manager is the record of who could work for it. That role sits with the organisation's other grants and follows the same grant and revocation path. Answering who could act for an entity last quarter therefore means reading role history, not a delegation log.

Delegation stops at decisions that must name one individual. A support session is a session a platform administrator opens as a named user, and the platform records which administrator opened it. Inside one, the administrator can do what that user can do, except four things:

- Stand in as the second signature on a two-person sign-off, because then both signatures trace to one person.
- Turn on a published attestation the institution cannot later withdraw.
- Record a compliance rule that admits any contract. That decision needs a written rationale from anyone who makes it, and the platform refuses a support session even with the rationale, because the record has to name the person who decided.
- Accept the risk of a rule that excludes the holders of a claim they can remove themselves.

Each refusal names its reason rather than a generic permission error.

## Frequently asked questions [#frequently-asked-questions]

### Can I keep a different party's context open in a second browser tab?

No. The Console stores the active context once for the whole browser session, so every tab shares one context, and a switch in one tab reaches the others on their next navigation. Work that must run in two contexts at the same time belongs on the Platform API, where each request names its own context in its `X-Participant` header and two concurrent calls can differ.

### Can I enter a multi-signature account's context?

Yes, when a wallet you control holds one of its signer seats. Its page under Shared accounts offers Work as this participant, and entering it never lowers its threshold: every operation it starts still waits for its signers' weight. You rarely need to enter it, though. The Working as submenu leaves multisig wallets out, and the wallet's Approvals tab lets each signer co-sign while acting as themselves.

### Does acting for a party give me more permission than I have as myself?

It can. The instruction executes from the party's account, so you can do whatever that account's roles allow, including roles you do not hold yourself. Your entitlement lets you enter, and the party's roles authorise the operation.

### What happens if my entitling role is revoked while I am working in a context?

Your next request no longer runs in that context. The entry check runs on every request rather than once when you switch, so the entitlement ends with the role as soon as the platform reads the revocation from the ledger. A read answers in your own context and carries the `X-Participant-Dropped` response header. The Console shows a toast and returns Working as to you. A write is refused with [DALP-0524](https://docs.settlemint.com/docs/api-reference/errors) and the same header. The Console holds it behind a dialog that offers to continue as yourself. Each refusal is recorded in the audit trail. The assumable list is cached in the browser for a few minutes, so it can keep showing the party briefly after the role is gone. The next request is the check that holds.

### Does switching context let me approve my own work?

No. A two-person sign-off compares the people behind the two signatures, not the contexts they worked in, so a maker who re-enters as another party is still the same person, and the second signature does not count.

### Can an integration using an API key act for a party?

Yes. Delegated Authority reads the session's user and participant identity, and an API-key session has both the same way a signed-in session does. A request authenticated with a key can therefore send `X-Participant` and run in a party's context, provided the key's underlying user holds the entitling role. The key decides who is calling. The context decides whose books the call works in.

## Related concepts [#related-concepts]

- [On-Chain Identity](https://docs.settlemint.com/docs/concepts/compliance-and-identity/onchain-identity): The ledger record of one subject, carrying the verifications issuers signed about it.
- [Smart Wallet](https://docs.settlemint.com/docs/concepts/custody-and-signing/smart-wallet): An account whose own rules govern signing authority.
- [Custody Approval](https://docs.settlemint.com/docs/concepts/custody-and-signing/custody-approval): The control between a prepared transaction and its signature.
- [Role Grant](https://docs.settlemint.com/docs/concepts/compliance-and-identity/role-grant): The on-chain permission, Organisation identity manager or Permission manager, that the entry check reads from the organisation's system access manager.
- [Participant](https://docs.settlemint.com/docs/concepts/compliance-and-identity/participant): The platform's one record of a compliance subject, a person, an organisation, or an account, that a context is entered as.
- [Maker-Checker](https://docs.settlemint.com/docs/concepts/custody-and-signing/maker-checker): The pattern where one party proposes a change and a different party must approve it.
- [Compliance Policy](https://docs.settlemint.com/docs/concepts/compliance-and-identity/compliance-policy): The eligibility and holding rules a token enforces regardless of which operator or party sends the instruction.
- [Transfer-Path Compliance](https://docs.settlemint.com/docs/concepts/compliance-and-identity/transfer-path-compliance): The on-chain check that a delegated instruction still has to clear before the transfer it triggers can settle.


# On-Chain Identity

Source: https://docs.settlemint.com/docs/concepts/compliance-and-identity/onchain-identity
An On-Chain Identity is a ledger contract for one subject. It holds the claims issuers sign, and the identity registry links the subject's wallets to it.



[Figure] Verification happens off the ledger, and the identity carries the result. Verification work happens off the ledger: a review or a provider check produces a verdict, and the documents and case file stay where they were made. An issuer that the registry trusts for the topic signs the result onto the subject's On-Chain Identity, one record per subject that outlives every asset reading it. The identity accumulates entries: a know-your-customer entry from a trusted issuer that counts, an anti-money-laundering entry from a trusted issuer that counts, and an accredited-investor entry that was revoked and no longer counts, though it stays visible. At transfer time the asset asks whether the recipient's identity carries the topics it requires, signed by an issuer its own registry trusts. If it does, the transfer proceeds. If it does not, the transfer reverts before any balance changes. Labels: Off the ledger; Review or provider check; documents and case file stay here; A verdict; passed, failed, or still open; an issuer trusted for the topic signs the result; On-chain identity; One record per subject. It outlives every asset that reads it.; know-your-customer; trusted issuer, counts; anti-money-laundering; trusted issuer, counts; accredited investor; revoked, no longer counts; At transfer time; Does the recipient's identity carry the topics this asset requires,; signed by an issuer this asset's registry trusts?; Yes: the transfer proceeds.; No: it reverts before any balance changes.

Verification happens off the ledger, and what reaches the identity is the result, which the asset reads at the moment of transfer.

Evidence stays with the verifier. The ledger records only the result: a topic, the issuer that signed it, and an expiry date when one is set.

One identity serves every asset of the organisation on a network, and each asset applies its own rule to the same record.

The identity check reads claims at transfer time, so untrusting an issuer or revoking a verification takes effect on the next check, with no cleanup transaction.

## Why on-chain identity exists [#why-on-chain-identity-exists]

A regulated token must know who holds it, and a wallet address says nothing about the person or company behind it. One investor can also hold several wallets. An On-Chain Identity is a contract on the ledger that stands for one subject: a person, an organisation, or a contract such as a token. Every wallet the subject uses points to that one contract, so the token checks the identity the address is linked to, not the address alone.

The identity holds verification results. When an issuer you appoint has checked a subject, it signs the result onto the identity, and every asset that accepts that issuer reads the same result. A wallet already cleared for one instrument does not repeat the same check for the next one, as long as the next asset's rule accepts the same topics and issuers.

A typical tokenisation programme screens investors in one system and records ownership in another, and the two can drift apart. [Asset Lifecycle](https://docs.settlemint.com/docs/concepts/issuing-and-markets/asset-lifecycle) names that gap as a reconciliation risk. An On-Chain Identity narrows it for eligibility: the issuer's result sits on the ledger the asset transfers on, and the asset reads it inside the transfer. Until the issuer records a change, the ledger keeps the old result.

The platform does not decide who counts as an accredited investor or whether a screening result is acceptable. Your compliance function and the issuers you appoint decide that. The platform puts their result where the asset reads it at the moment of transfer.

## What a claim is [#what-a-claim-is]

A claim is one signed statement on an identity, such as "this subject passed know-your-customer checks". The Console calls a claim a verification, and the API calls it a claim. Each claim carries three fields:

- A topic, the named kind of statement, such as know-your-customer, anti-money-laundering or accredited investor. The organisation keeps a catalogue of topics, which the platform seeds when it deploys the system. [Verification topics](https://docs.settlemint.com/docs/console/compliance/verification-topics) explains how to add more.
- An issuer, the identity that signed the claim. A claim counts only when the registry the asset consults trusts that issuer for that topic.
- A value. For the investor eligibility topics, the value is a fixed pass value with an optional expiry date. These topics are know-your-customer, anti-money-laundering, know-your-transaction, know-your-business, qualified institutional investor, professional investor, accredited investor, accredited investor verified, and Regulation S. Topics that describe an asset, such as base price or collateral, carry structured fields that pricing and minting read.

An identity holds at most one claim per issuer and topic. An issuer that signs the same topic again replaces its earlier claim, so a renewal is one write. Two different issuers can each hold a claim for the same topic on the same identity.

The platform refuses to issue a claim when the issuing identity is not trusted for that topic. A transfer checks trust again, so a claim from an issuer outside its mandate never counts. When a person issues an investor eligibility claim, the platform also refuses it until the subject's know-your-customer profile is approved, whether the claim lands on an EVM identity or on a Canton party. Approve the profile first, as [Verify a participant](https://docs.settlemint.com/docs/console/participants/verify-a-participant) describes. A compliance provider's verdict does not wait for that profile. The profile stays off the ledger, so no contract checks it. The identity contract checks the issuer's signature when it stores the claim, and the asset checks the trusted issuers registry at each transfer. In both cases the platform issues a claim only to an identity that the organisation's identity registry holds.

A revoke through the issuer identity leaves the claim on the identity with its revoked state visible. A revoke made without the issuer identity removes the claim. The next transfer to that wallet fails when the asset requires that topic and no other trusted issuer's claim covers it. A connected [compliance provider](https://docs.settlemint.com/docs/console/compliance/compliance-providers) can issue and revoke claims for you: an approved verdict issues the matching claim, a rejected verdict revokes it, and a monitoring alert revokes only when its severity reaches the threshold you set for that topic on the provider.

An expiry date alone does not change the identity registry's result. An asset that must refuse expired claims runs the [Claim expiry](https://docs.settlemint.com/docs/concepts/compliance-and-identity/compliance-modules#claim-expiry) compliance module, which rejects a mint or transfer to a recipient whose claim on a required topic has expired.

## The identity registry [#the-identity-registry]

The identity registry is the contract that links each wallet to an identity, together with the country that compliance rules read. Each organisation has its own identity registry on each network it uses, as part of its system, the set of platform contracts the organisation runs on that network. A token checks this registry before a wallet may hold or receive it.

A wallet's registration is in one of three states. The Identity tab of a [participant](https://docs.settlemint.com/docs/concepts/compliance-and-identity/participant), the platform's record of one person or organisation, shows them as Approved, Pending approval, and Not registered, and the detail page of a user shows Registered and Pending registration:

- Approved means the registry holds an active entry, and tokens can see the wallet.
- Pending approval means a request to register the wallet is waiting, and an Identity manager has not accepted it. The request comes from the wallet's holder, from creating the identity, or from installing the identity on another network. An Identity manager is the system role that registers, changes and recovers identities.
- Not registered means the registry holds no entry for the wallet.

A participant with no identity on the network shows "Requires an identity" on that tab.

Registering a wallet activates every wallet of the same owner that is not active yet in one transaction, including a pending wallet and the smart wallet paired with the signing key. Removing a registration takes the wallet out of the registry, and the identity contract stays on the ledger with its claims. Only an Identity manager removes an approved registration. A wallet's holder can withdraw only their own pending request, so a holder cannot drop out of the registry to get around a lock-up.

The registry also carries a lost-wallet marker. A wallet marked lost cannot receive tokens again, and a recovery never registers a lost wallet to the new identity.

The identity factory, the contract that creates identities, links each wallet or contract to one identity and refuses a second one for the same wallet or contract. A participant holds one identity per network. A recovery replaces that identity with a new one and links the two.

A participant also holds one registry entry per identity registry, whichever way its identity is created: through the identity endpoints, as a new participant or user, through an invitation, through the install on another network, or through a multisig wallet. Two creates for the same participant never run side by side in one registry. While one runs, or waits for funding or an approval, a second is refused with a conflict, and the first keeps its place until it ends. A second wallet joins the identity only by being registered on the identity that already exists. A recovery is the exception: it replaces the identity, so it takes no such place.

On a second network, the participant installs its identity there, and the install files a pending registration that an Identity manager accepts. [On-chain identity in the Console](https://docs.settlemint.com/docs/console/my-account/onchain-identity) shows the steps.

## Trusted issuers [#trusted-issuers]

The trusted issuers registry records which issuers count for which topics. An issuer is itself an identity on the ledger, so the registry names that identity rather than a signing key. The keys the issuer signs with live on its identity, and revocation lives with the issuer too, keyed to the signature. [Trusted issuers](https://docs.settlemint.com/docs/console/compliance/trusted-issuers) shows how a verification policy manager, the system role that manages trusted issuers and topics, adds and removes them.

A trusted issuers registry can inherit from a parent, and from its parent's parent, to a depth of three levels: the asset's own list, the organisation's list, and the network-wide list that every organisation on that network inherits. Inheritance adds rather than overrides: a registry trusts its own issuers plus the ones its parents trust. An organisation cannot remove one inherited issuer, and its verification policy manager can detach the organisation's list from its parent entirely. An issuer that one organisation trusts is not trusted by another organisation, even on the same network, and a valid signature from that issuer still fails there.

Each asset records the identity registry it consults when it is created, and a holder of its Governance role can replace it later with a direct contract call. The claims on an identity are shared, but the trust decision is not, so one asset may count a claim that the asset beside it ignores.

## Where identity and eligibility meet [#where-identity-and-eligibility-meet]

When an asset tests a recipient, the ledger combines four records that different roles administer: the identity registry that binds the wallet to an identity, the catalogue of topics, the claims on the identity, and the trusted issuers for each topic. A rejected transfer traces back to one of these four.

The asset's rule is an expression over topics, joined by and, or, and not, with at most 32 elements. The token's Governance role sets it with "Edit holder rule" on the token's "Compliance" tab, or through the compliance expression route of the Platform API. An asset with no expression still needs a registered wallet that is not marked lost. The check resolves its conditions in order, and the first one that fails ends it: the transfer reverts, and nothing moves.

[Figure] Four conditions, evaluated in order. The check resolves four conditions in order. The recipient wallet must resolve to an identity in this asset's registry and must not be marked lost. The topic the rule names must also be registered, because an unknown topic can never be satisfied. The identity must hold an entry for that topic, storing at most one entry per issuer and topic. That entry's issuer must, in turn, be trusted for the topic in the registry this asset consults, and the issuer's own contract must still call the entry valid. Only then is the recipient verified and the asset's remaining rules run. Any condition that fails leaves the sequence at that point: the rail beside the column carries every one of the four checks to the same outcome, and the transfer reverts with nothing moved. Labels: The wallet resolves to an identity; registered here, and not marked lost; The topic is registered; an unknown topic is never satisfied; The identity holds an entry for it; one entry per issuer and topic; Its issuer is trusted for that topic; and still calls the entry valid; Verified: the asset's other rules run next; Reverts; on any failure; nothing moves.

Four conditions are evaluated on the ledger in this order, and the first that fails ends the check and reverts the transfer.

For each required topic, the check collects the claims under that topic, compares their issuer with the trusted list for the topic, then asks the issuer's own identity whether the claim is still valid. A revoked claim stays visible on the identity while it fails that last question.

The token's core identity check evaluates the recipient. Compliance modules can add rules about the sender. A burn has no recipient, so the recipient identity check does not run. A forced transfer by a Custodian, the asset role that freezes, forces transfers and recovers tokens, skips the compliance modules, the pause and any freeze on the sending wallet, and refuses a receiving wallet whose address is frozen. On an asset whose identity registry holds the topic expression, a forced transfer still runs the identity check in full, expression included. On an asset that applies its topic rule through an identity verification compliance module, a forced transfer checks only that the recipient is registered and its wallet is not marked lost, because forced transfers skip compliance modules.

## When a holder loses a wallet [#when-a-holder-loses-a-wallet]

An Identity manager recovers a user who lost access to their wallet. The recovery replaces the user's wallet and identity on the ledger, and it cannot be undone. On the ledger one Identity manager acts alone and names the replacement wallet, and that wallet can then claim the lost wallet's balance of every token, so treat Identity manager as a role that can move holdings. A recovery made through the platform asks a second person by default, because the "Recovery" group of the Administration family in [Approvals](https://docs.settlemint.com/docs/console/organisation-settings/general#approvals) starts on. An owner can turn it off, and an organisation with no owner or administrator besides the person recovering runs the recovery without one.

The recovery:

- It gives the user a replacement wallet and a new identity, and marks the lost wallets as lost in the registry, so no token can be sent to them again.
- It leaves what the lost wallet is still owed claimable by the replacement wallet: a failed sale's refund, fixed-yield coupons and interest. The lost wallet cannot claim them itself, so each has a recovered-wallet claim route that pays the replacement wallet.
- It records in the registry which wallet replaced which, so an auditor can follow one subject across the change. It also links the new identity to the identity it replaced, so a limit kept per investor, such as a token sale's allocation cap, keeps applying to the replacement wallet.
- It issues again, signed by the organisation's operations signer, every standing claim that the organisation's own issuer identity signed on the lost identity. A claim from another issuer does not move. That issuer signs it again on the new identity, so plan that step into your runbook.
- It moves the user's balances to the replacement wallet one token at a time, through the Custodian's forced recovery call signed by the operator who runs the recovery. A token whose call fails stays on the lost wallet, and a Custodian of that asset recovers it.
- It rebinds the custody gateway of the lost identity, whether the identity is the gateway's current or a former client, to the replacement wallet and then the replacement smart wallet, so the client keeps its gateway. While the Custodian's forced recovery has not moved the receipts held for custody, the gateway refuses the rebind and the recovery stops with that reason. Execute it again after the token recovery finishes.
- It signs the user out of every session, removes their sign-in code and passkeys, and resets their wallet verification: the transaction PIN, the transaction code and the recovery codes. When mail delivery is configured, it emails the user that an administrator recovered their wallet.

A recovery made before the registry kept the link between identities has no link, so a token sale's allocation cap does not follow that recovery on the ledger. A System manager adds the missing link with a contract call on the registry's storage contract, using the wallets and identity from the recovery's own event. Add it before a sale sets caps.

[On-chain identity in the Console](https://docs.settlemint.com/docs/console/my-account/onchain-identity#recover-a-user-who-lost-their-wallet) gives the recovery steps and what each screen shows.

## The integration contract [#the-integration-contract]

To an integration, an On-Chain Identity is one address. The [identity endpoints](https://docs.settlemint.com/docs/api-reference/v2) read an identity by wallet or by identity address, search for one, list the organisation's identities, and return the acting account's own identity. They also create an identity, register a wallet, file a pending registration, change a registration's country, remove a registration, and preview, run and follow a recovery. Creating an identity for a wallet its holder keeps in a browser or embedded wallet needs that wallet's own signature: the first request answers with the identity factory payload to sign, and the repeated request carries the signature.

What a caller can read depends on its role. A System manager, an Identity manager or a verification issuer can read any identity in the organisation. Every other caller reads only the identities of wallets its acting participant holds, and a bank rail manager can also read the identity of the organisation's bank rail wallet. A read of the caller's own identity returns an explicit not-provisioned result when the acting account has no identity yet.

Issuing a claim is a ledger write, so it follows the platform's [asynchronous mutation contract](https://docs.settlemint.com/docs/api-reference/guides/idempotency-async-settlement). Wait for it to settle inside the window you ask for, or take the accepted response and follow its status link. Acceptance means the platform recorded your instruction, and the outcome is the request's own Settlement Verdict, the recorded end state the platform reports once the write resolves.

The API has three reads. Reading an identity returns its address, its registration state, and the claims on it, each marked with whether the consulted registry trusts its issuer. A registration-status read returns one value to branch on: no system, no identity, not registered, pending, or active. An eligibility read returns `allowed`, `needs-action` or `blocked`, with a reason for each failing rule from the platform's [error catalogue](https://docs.settlemint.com/docs/api-reference/errors/error-handling), so an integration can tell a holder what to fix.

An eligibility result is a diagnosis, not a reservation. It describes the moment it ran, and the asset repeats the real check inside the transfer. A clear read followed by a revocation still ends in a reverted transfer.

### Replacing the organisation identity before setup [#replacing-the-organisation-identity-before-setup]

Only the system factory can record an identity as the organisation's identity, and it does so in the transaction that creates the system. Anyone can still use the identity factory to create an identity for the system's address before the system exists. When that happens, a System manager, the system role that administers the organisation's contracts, can replace it with a contract call. This works only before the system's one-time setup runs, and the replacement identity always carries the contract identity claim that the factory issues.

## Controls and evidence [#controls-and-evidence]

For a control function, an On-Chain Identity is a preventive control with a readable history. It records that a check was made, by which issuer, for which topic, and when it stopped counting. The material behind the check stays in the systems that already hold it.

What reaches the ledger is a topic, the issuing identity, a signature and a value. The platform does not write identity documents, review notes or provider payloads to the ledger, so they stay under your existing retention rules. Claim values are public, so keep personal data out of them.

Write eligibility rules positively and withdraw eligibility by revoking a claim. A rule that reads "verified and not sanctioned" lets through a wallet that no one ever screened, because a missing sanctions claim reads as false and the negation turns it into true. Screening results still belong in the record as evidence, and the enforcing step is revoking the eligibility claim the rule requires. A rule that excludes the holders of a sanctions claim has a second flaw, because a holder can remove that claim from their own identity. To enforce a sanctions list directly, use an [identity block list](https://docs.settlemint.com/docs/concepts/compliance-and-identity/compliance-modules#identity-block-list), which the issuer maintains and the holder has no key to edit. A recovery gives the holder a new identity, so add that identity to the list after any recovery.

The evidence trail sits on the ledger. Issues, changes, removals and revocations each land as a timestamped event with their topic and issuing identity, so a holder's eligibility history can be rebuilt from the ledger alone. Registration, country, the lost-wallet marker and recovery links sit in the registry beside it.

## Frequently asked questions [#frequently-asked-questions]

### Does a holder's personal data end up on a blockchain?

Identity documents and review notes stay off the ledger. The ledger exposes addresses, topics, issuers, signatures and claim values. Those records can be linked with other information, so assess them under your privacy policy.

### What happens when a screening flags a holder?

Your reviewer revokes the eligibility claim the asset requires, or a connected compliance provider revokes it when its alert meets the severity threshold you set. From that moment, a transfer to the holder fails on any asset that requires that topic and has no other trusted claim to accept. Transfers that settled before the flag stay settled. The revocation leaves the holder's existing balance where it is, and the holder can still send tokens out, because the identity check reads the recipient. To stop outgoing transfers, freeze the wallet or the position through the asset's controls.

### What if someone steals an issuer's signing key?

Remove the stolen key from the issuer's identity. Each claim check recovers the signer from the signature and asks whether that signer's key still carries the claim-signing purpose on the issuer's identity, so every claim the stolen key signed fails from the next read. Issuing those claims again under the remaining key restores them. Removing the issuer from a registry reaches only that level: a registry that inherits the issuer from a parent still trusts it until the parent removes it too.

### Can a holder delete a claim from their own identity?

A holder who controls a key with that permission can remove a claim from their identity, and the removal is itself a recorded event. The removal costs them their own eligibility. A rule that demands a present, valid claim cannot be satisfied by deleting anything. A rule that excludes the holders of a claim can be satisfied that way. The platform checks every such rule when it is saved, and the claim topic's "Use in exclusions" setting decides whether the save goes through, needs the author to accept the risk, or is refused. [Excluding holders of a claim](https://docs.settlemint.com/docs/concepts/compliance-and-identity/compliance-modules#excluding-holders-of-a-claim) describes the check.

### Is this the same identity as the login account?

No. Sign-in, two-factor authentication and wallet verification govern who may operate the Console. An On-Chain Identity governs whether a subject may hold a regulated asset. A user with full Console access and no claims cannot receive a restricted token, and revoking someone's Console access leaves their claims as they were.

## Related concepts [#related-concepts]

- [Asset Lifecycle](https://docs.settlemint.com/docs/concepts/issuing-and-markets/asset-lifecycle): The stages a tokenised instrument moves through from design to retirement, including the reconciliation risk an On-Chain Identity closes.
- [Capacity topics](https://docs.settlemint.com/docs/concepts/compliance-and-identity/capacity-topics): How compliance admits a custodian that holds for clients, with a topic it registers and issues itself.
- [Participant](https://docs.settlemint.com/docs/concepts/compliance-and-identity/participant): The platform's one record of a person or organisation that an On-Chain Identity's claims are about. One participant holds one identity per network.
- [Transfer-Path Compliance](https://docs.settlemint.com/docs/concepts/compliance-and-identity/transfer-path-compliance): The enforcement of a regulated token's rules inside the transfer itself, of which the identity check is the first step.
- [Compliance Policy](https://docs.settlemint.com/docs/concepts/compliance-and-identity/compliance-policy): The compliance modules and global controls that run beside the identity check on every transfer.
- [Settlement Verdict](https://docs.settlemint.com/docs/concepts/settlement/settlement-verdict): The recorded end state of an operation submitted to the platform, and the signal that a claim was issued or revoked.
- [DALP Instance](https://docs.settlemint.com/docs/platform/dalp-instance): One self-contained copy of the platform, connected to the networks you approve.


# Bulk participant import

Source: https://docs.settlemint.com/docs/concepts/compliance-and-identity/participant-import
Import participant rows in a background batch keyed by an organisation-scoped external reference.

An Identity manager calls `POST /api/v2/participants/import-batches` with `{ rows, walletVerification }`: up to 500 rows and one wallet step-up for the whole batch. The call answers `202 Accepted` with a `batchId`, a `statusUrl` and a matching `Location` header. Read `GET /api/v2/participants/import-batches/{batchId}` until `state` is `completed`. Send `Prefer: wait=<seconds>` to wait for the batch inside the request. The wait is held between 5 and 99 seconds. When it finishes in time, or every row already fails its row rules, the call answers `200` with the completed batch instead.

A session caller first requests a step-up challenge from `POST /api/v2/step-up-challenges` with the `operation` `POST /api/v2/participants/import-batches`, a `target` and a `payloadDigest`. The `target` is `null` when the import sends none of the `X-Chain-Id`, `X-Network-Id`, `X-Executor` and `X-Custody-Account-Id` headers. When it sends any of them, the `target` is the JSON text of an array holding `null` and then those four header values in that order, with a missing header as `null`. The digest is the lowercase hex SHA-256 of the import body's canonical JSON, with object keys sorted, absent fields dropped and the top-level `walletVerification` left out. The import then carries the challenge id in the `X-Step-Up-Challenge` header. A challenge works for one request and expires after five minutes. An API key caller sends no challenge and no `walletVerification`. A missing wallet step-up or challenge answers `400` and a caller without the Identity manager role answers `403`, before any row runs. Reading a batch needs the Identity manager role too. When the organisation's [approval settings](https://docs.settlemint.com/docs/console/organisation-settings/general#approvals) require a second person for the "System administration" group of the Administration family, the import waits for approval and runs once it is approved. Send an `Idempotency-Key` header to make a retried call safe: the same key from the same caller with the same rows answers the batch it already started, and the same key with different rows answers `409`.

Each row carries `externalRef`, `name`, `email`, `providerConfigurationId`, `nationality`, `residence` and `kyc` (`firstName`, `lastName`, `dob`, `residencyStatus`, `nationalId`). `nationality` and `residence` are ISO 3166-1 alpha-2 codes. `residence` becomes the KYC profile country.

Each row that does not fail opens a pending registration request for the participant, or refreshes one still pending, with `nationality` as the proposed identity registry country. An Identity manager accepts the registration as usual and sees that country prefilled. The import never accepts a registration itself.

A row can carry an optional `classification`: `retail`, `institutional` or `proprietary`. A batch that uses it also needs the claim issuer role. A caller without that role answers `403` before any row runs. The organisation's identity issues the class as a claim on `participantClassRetail`, `participantClassInstitutional` or `participantClassProprietary`, and only when the participant holds no class yet. A venue reads the class through its own class topic mapping. A row naming a different class from one the participant already holds fails with `classification-change-refused` and writes no claim, because a class change needs the holder of the participant identity's key. The row's other fields are already saved when it fails. A classified row whose reference is still pending in another batch writes no claim and fails with `classification-not-issued`. Send it again once that batch has finished.

The import does not take extra wallets. Each participant gets its custody provider's wallet. Register further wallets through the registration routes after the import.

`externalRef` is unique within the organisation. Sending a reference again updates that participant's name and KYC data instead of creating a second one. The import never changes a login email: a re-sent reference with a different email fails with `email-change-refused`. A reference that appears twice in one batch fails both rows. A reference whose creation failed is created afresh on its next send.

The batch answers one row per input row, in input order, with `status` `pending`, `created`, `updated`, `unchanged` or `failed`. A failed row carries a `code` and the field `issues` that caused it. A `created` or `updated` row carries `dependency-unavailable` when a later step, such as the KYC submission, did not finish. Send it again to finish it.

| Code | Meaning |
| --- | --- |
| `row-invalid` | A field broke its rule. `issues` names the field. |
| `external-ref-duplicate` | The reference appears more than once in the batch. |
| `email-in-use` | The email belongs to an existing user. The import does not adopt existing members. |
| `email-change-refused` | The reference is already imported with another login email. Change it through the user. |
| `participant-create-refused` | The user, wallet or identity could not be created. |
| `kyc-fields-rejected` | The KYC profile refused a field, or a field the organisation's profile sections require is missing. `issues` names it. The participant is already created. |
| `kyc-transition-refused` | The KYC version could not be submitted for review. |
| `kyc-version-refused` | A new KYC version could not be started. |
| `kyc-draft-open` | An operator has a KYC draft open for this participant. Finish or discard it, then retry. |
| `classification-not-issued` | The class claim could not be written. `issues` says why. Send the row again to retry it, unless `issues` says the outcome is unknown. Check the participant's claims first. |
| `classification-change-refused` | The participant already holds another class. A change needs the holder of the participant identity's key. |
| `dependency-unavailable` | A platform dependency was down. Send the row again later. |

A failed row never stops the other rows. KYC data follows the normal provider and review flow: the import submits it for review as the importing operator and never approves it.


# Participant

Source: https://docs.settlemint.com/docs/concepts/compliance-and-identity/participant
A participant is the platform's one record of a compliance subject, so role grants, claims, audit rows and delegated actions point at the same subject.



[Figure] Every other record points back to one participant. Six kinds of platform record all point back to a single participant. A wallet, whether a key account or a smart account, points at it. An on-chain identity, one per network, points at it. A role grant points at it. A claim points at it. An audit row points at it. A delegated action points at it. The participant itself sits in the middle as the one record those six kinds of data resolve to, a person, an organisation, or an account, created once and looked up everywhere else. Labels: Wallet; key or smart account; On-chain identity; one per network; Role grant; on-chain permission held; Claim; a signed attestation; Audit row; actor and role; Delegated action; assumed context; Participant; One record; a person, an organisation,; or an account; kind fixed at creation.

A wallet, an identity, a role grant, a claim, an audit row, and a delegated action all resolve to one participant record.

A participant is the platform's one record of a compliance subject. Every role grant, claim, audit row and delegated action resolves to it, so one subject's history stays together across sessions and wallets.

The subject a participant represents is checked against a closed list at creation, covering people, organisations and platform-internal subjects such as claim issuers and assets. An unlisted kind is refused. An account-based participant signs in one of three ways: a single external key, a single-signer smart account or a weighted multisig.

Assuming a participant, called Working as in the Console, never edits the record or grants a role. It picks which subject a check evaluates and which wallet executes the request, so that wallet's roles decide what the request can do.

## One subject, one record [#one-subject-one-record]

The same compliance subject shows up in many places. A person logs in through several sessions, holds more than one wallet, and might act for an organisation on some days and for themselves on others. Without one record, the KYC history, the role grants and the audit trail would each need their own idea of who that subject is, and the three would drift apart. The participant is that record. Every kind of subject, human, organisational or account-shaped, uses the same record type, so other parts of the platform never ask what kind of subject they are looking at before they look it up.

A participant is not the login user. The user is how a person signs in. The participant is the subject records point at, and one user can hold several. Participant kinds are not limited to person and organisation either: a claim issuer, an asset and a platform add-on are participants in the same sense a person is, though no one assumes them as a context.

At review time, a reporting obligation, an Audit Trail row and a Role Grant trace to the same participant, so an institution answers who this is once and reuses the answer everywhere. A role grant resolves through the wallet that holds it, a claim through the identity it sits on, and an audit row through its participant field. The participant record itself never grants a permission.

The platform keeps one participant record, and every other part of the platform reads that record rather than keeping its own copy. [Asset Lifecycle](https://docs.settlemint.com/docs/concepts/issuing-and-markets/asset-lifecycle) is one reader: it runs coupons, freezes and fee collection for identity-verified participants whose ids come from here.

## A participant is created once [#a-participant-is-created-once]

How the platform creates a participant depends on its kind.

- **A person created by an Identity manager.** When an identity manager creates a user directly, the platform creates the login, the person participant, a managed wallet and an on-chain identity in one request.
- **A person who arrives through the Investor portal.** The portal's "Wallet setup" wizard opens when an invited investor signs in with no participant in the organisation, when the participant they act as has no wallet the organisation can act through, or when its wallet setup is unfinished. The wizard first resumes a participant that still waits for its key proof. Otherwise it asks them to pick another participant they own that the organisation can act through, or, when they have none, to create one on a wallet the organisation holds or one they prove they control.
- **An organisation.** The platform creates the participant when it creates and finalises the organisation's system during bootstrap.
- **A single-key account.** It comes from a wallet-creation flow and reaches its owner through the wallets that sign for it.
- **A weighted multisig.** It comes from finalising a multisig draft, which does not deploy while any invite is still pending.

[Onboard an investor](https://docs.settlemint.com/docs/api-reference/guides/onboard-an-investor#from-first-sign-in-to-a-verified-holder) follows a person from first sign-in to a verified holder: identity registration, KYC review and the claim a token checks.

Day to day, you step into a participant instead of editing it. The "Working as" submenu of the account menu at the top right shows which participants you may act as and lets you switch between them. The submenu offers only participants your own authority already covers. A request checks the same authority when it names a participant directly, so the submenu is a smaller set than the list of participant kinds. If a selected participant stops being actable, the Console falls back to your own participant. [Delegated Authority](https://docs.settlemint.com/docs/concepts/compliance-and-identity/delegated-authority) explains which participants you may enter.

## A thin parent, kind-specific children [#a-thin-parent-kind-specific-children]

The participant record stores an id and a kind and holds no kind-specific facts: no organisation reference, no KYC profile reference, no wallet data. Everything specific to a kind lives on a separate record, linked back to the parent so that a person record can never masquerade as an organisation record. A new kind therefore gets its own record and never widens the participant record.

A participant is not the same thing as an on-chain identity. A single participant can hold more than one identity contract, one per network, tracked separately from the participant record. On a multi-network deployment, ask for a participant's identity on a named network.

[Figure] Kind-specific facts live off the participant record, never on it. The participant record stores an id and a kind, checked against a closed list of compliance-subject kinds such as person, organisation, claim issuer, and asset. An unlisted kind is rejected. A person record's specific facts live in a separate person record, linked to a login user and created with the user or at first sign-in. An organisation record's specific facts live in a separate organisation record, linked one to one to an organisation and created at system bootstrap. Neither record stores an on-chain identity. Identity binding lives in a third record, one row per network per participant, so a single participant can hold more than one on-chain identity contract at once. Labels: id and kind; Participant; fixed at creation; Participant kinds; reference lookup; closed list, checked at creation; kind; Person record; linked to a login user; created with the user or at first sign-in; Organisation record; one to one with an organisation; created at system bootstrap; Identity binding; one row per network, per participant; the on-chain identity contract lives here, not on the participant record.

The participant record fixes an id and a kind, and kind-specific facts and on-chain identity binding live off it.

## Selecting a participant on a request [#selecting-a-participant-on-a-request]

A request names the participant it acts as with an `X-Participant` header, and the platform resolves that header against your own authority. The platform accepts a person participant in two cases. You own it and the active organisation can act through it, or a wallet under your control signs for it, such as a multisig in which that wallet holds a current signer seat. A multisig participant you own is accepted only through such a seat, never on ownership alone. Organisation entry checks that the wallet of your acting participant holds Organisation identity manager or Permission manager in the organisation's system on the request's network. Every other kind of participant is refused. Without the header, the platform uses your stored Working as choice, and otherwise your own participant. When the stored choice is no longer reachable, a read falls back to your own participant and the response marks the stored one as dropped, while a write is refused with DALP-0524.

A write that names a participant you cannot use is refused with [DALP-0524](https://docs.settlemint.com/docs/api-reference/errors), the same error for every reason. A read that names one runs as your default participant instead, and the response records that the named participant was dropped. A read is forbidden only when that default is refused too. A caller who could tell a wrong kind, a participant that is not theirs and a participant that does not exist apart could enumerate participants by probing the header.

Resolving a participant picks the subject and the wallet that executes. It never changes what that wallet may do on the network, which stays a separate check against the wallet's own Role Grants. Acting as an organisation therefore runs your request with the roles the organisation's wallet holds.

## A participant outlives its account and its kind never changes [#a-participant-outlives-its-account-and-its-kind-never-changes]

A participant cannot change kind or be deleted once created, so create one only for a subject you intend to keep on record.

The kind is fixed at creation. Every kind-specific record is bound to a participant of that kind, so a participant cannot be converted from one kind into another. Correcting a wrong kind means creating a new participant, and the history already attached to the old one stays there.

The platform offers no route that detaches an organisation participant from its organisation, and the organisation cannot be removed while that link stands. An organisation participant is permanent from the moment its system is bootstrapped.

Removing a person's login does not remove the participant behind it. The platform blocks the removal outright while any of four conditions holds:

- The person is the only owner of an organisation.
- Any participant they hold or act as still has an on-chain identity, on any network.
- A wallet of any of those participants still holds a token balance.
- The person approves transactions for a wallet as its named checker.

Each block names its own reason. Give the organisation another owner, move the tokens out and replace the person as checker, then remove the account. An account whose participant has an on-chain identity cannot be removed. Ban it instead: banning stops sign-in and keeps the record.

When the removal goes through, the account, its sign-in methods, its sessions and the person record that tied the participant to the login go. The participant record stays, and so do the KYC records, the participant names and the audit entries tied to it. Authorship on a registration the person requested also survives, with the requester cleared rather than the record deleted. Check your retention and erasure policy before you rely on that.

## What the participant record does not guarantee [#what-the-participant-record-does-not-guarantee]

The off-chain audit trail records two subjects for a request. The actor field names the signed-in user. The participant field names the participant the request resolved to act as, so a request sent while acting as another participant records that participant. A request that resolved no participant leaves the field empty, so read the actor field as well before you attribute a write. A delegated action also executes from the assumed participant's wallet on chain, so the chain records the same principal independently.

The Working as submenu is not the catalogue of participant kinds. Reading it as that list understates the record's reach, which matters when you reconcile a compliance subject that never appears in it.

## Frequently asked questions [#frequently-asked-questions]

### Is a participant the same as the user who logs in?

No. A person participant links to one login user, and a user can hold more than one person participant. The participant is the compliance-facing record that a role grant, a claim and an audit row point at. The login user is how you sign in. An organisation participant has no login user, since nobody logs in as an organisation directly.

### Can one participant hold more than one wallet?

Yes. A participant's wallets, key accounts and smart accounts alike, are resolved separately from the participant record, which is why the record stores no wallet data. A person can pair a key account with a smart account, or add several smart accounts over time, without changing the participant record. A request still names one wallet to act through, so holding more than one only means choosing which.

### Can more than one person act as the same participant at the same time?

Yes. Each request names its participant in its own `X-Participant` header, so authorised users can make concurrent requests for the same organisation or account, and each request still passes its own access and operation checks. Acting as a multisig never lowers its threshold: every operation it starts still waits for its signers' weight, and the Working as submenu leaves it out.

## Related concepts [#related-concepts]

- [Delegated Authority](https://docs.settlemint.com/docs/concepts/compliance-and-identity/delegated-authority): The model for entering a participant's context, which participant you may assume, and what the executing account may then do.
- [On-chain Identity](https://docs.settlemint.com/docs/concepts/compliance-and-identity/onchain-identity): The network-specific identity contract a participant's compliance claims attach to. One participant can hold several, one per network.
- [Role Grant](https://docs.settlemint.com/docs/concepts/compliance-and-identity/role-grant): The on-chain permission an executing account holds. A participant record decides who is acting, never what that acting account may do.
- [Compliance Policy](https://docs.settlemint.com/docs/concepts/compliance-and-identity/compliance-policy): The reviewed rule set and live global controls a transfer must clear, evaluated against the participant a wallet resolves to.
- [Transfer-Path Compliance](https://docs.settlemint.com/docs/concepts/compliance-and-identity/transfer-path-compliance): The checks a regulated token enforces inside the transfer itself, which depend on knowing which participant each side of the movement is.
- [Audit Trail](https://docs.settlemint.com/docs/concepts/records-and-evidence/audit-trail): The off-chain record naming who acted and under what role. Its participant field names the participant a request acted as.
- [Smart Wallet](https://docs.settlemint.com/docs/concepts/custody-and-signing/smart-wallet): One kind of wallet a participant's writes can execute through. The wallet is not the participant. The participant is what the wallet acts for.


# Role Grant

Source: https://docs.settlemint.com/docs/concepts/compliance-and-identity/role-grant
A role grant names which wallet may make a privileged call, and the access manager contract checks it on chain before the call runs.



[Figure] Role Grant: one check before every privileged call. A privileged call is checked against the access manager's role grants, not a screen. hasRole runs at call time. A present role lets the call proceed. A missing or revoked one reverts it. Labels: One check, every privileged call; Address attempting the privileged call; Caller; Access manager; Holds every role it checks; hasRole(ROLE, caller); Checked at call time; Result; Role is present; Call executes,; state changes normally; Role is missing or revoked; Reverts, no state change.

The access manager checks the caller's role grant on chain, not anything a screen shows, and a missing or revoked role makes the call revert with no change.

A role grant lives in an access manager: the organisation's system access manager, one token's own, or an add-on's own. That manager alone decides whether the caller holds the role, except for five system roles that only the platform checks. System manager and Auditor sit in the system access manager, Custodian and Supply management in a token's, and authority in one gives none in another. Offering roles are token roles on the token an offering sells.

A grant through the platform can name a person instead of one address, and the change then reaches every wallet the organisation can act on for that participant. A grant can carry an end. At that time the platform sends the revoke, and the role stays held until that transaction lands.

Before any chain write, the platform refuses a grant that pairs Auditor with another system role. Once the organisation enables its segregation rules, it also refuses a grant that breaks one of them, and a rule set to warn lets the grant through once it carries a written reason. A grant made directly on chain skips both checks. A Console screen and an on-chain role check are two different systems, so a button appearing does not mean the transaction behind it succeeds.

## Why a role grant matters [#why-a-role-grant-matters]

A role grant records on chain who can mint, freeze or change the rules, and the access manager enforces that record. For most roles a contract checks the grant. Five system roles unlock Platform API and Console actions only, and no contract function checks them. The five are Gas manager, Verification issuer, Asset designer, Bank rail manager and Auditor.

After issuance, each operation an issuer runs on an asset is a call that a role gates, such as minting, freezing a holding, pausing the token or changing its compliance modules. [Asset Lifecycle](https://docs.settlemint.com/docs/concepts/issuing-and-markets/asset-lifecycle) lists these operations, and each one checks a role grant.

The platform splits authority into named roles. An Asset manager can deploy and configure a token. A separate Funds manager withdraws what an offering collects, and the Offering admin runs the sale. One person can hold both, unless the organisation enables the segregation rule that keeps them apart. An Auditor reads permissions, identities, audit logs and system state, and has no power to change anything.

To find who can move client funds, read the access managers' own records, the same records the chain enforces. Look for Custodian and Supply management in each token's access manager, and for Identity manager and System manager in the system access manager: an Identity manager names the replacement wallet in a recovery, and a System manager replaces the logic every token runs.

## Who can do what, day to day [#who-can-do-what-day-to-day]

A role grant decides which team member can complete which task, whether the role is a system role like Asset manager or an asset role like Custodian. The Console shows each role under its label, and the Platform API names it by a field such as `tokenManager` for Asset manager or `admin` for Permission manager. [Roles and segregation of duties](https://docs.settlemint.com/docs/concepts/compliance-and-identity/roles-and-segregation-of-duties) lists every role.

System manager bootstraps the deployment and manages upgrades. Identity manager registers and recovers identities, and the separate Organisation identity manager manages the organisation's own identity. Asset manager deploys and configures tokens. Verification issuer attaches identity claims, though holding that role alone does not make an address a trusted source: trust is a separate decision made in the trusted issuers registry. Gas manager funds and configures the paymaster, the contract that pays network fees for sponsored transactions. Rotating the paymaster's signing key needs System manager. The Platform API and the Console check Gas manager, and no contract does. The paymaster's own withdrawal and stake operations are gated on chain by System manager, not Gas manager, because they move funds out of the paymaster.

A revoke takes effect when its transaction confirms. After it, the next call that the role would have covered fails, including a retry of a request already queued. The person is not signed out. For a role a contract checks, the block happens when the transaction reaches the access manager. For a role only the platform checks, it happens once the platform's record of the chain shows the revoke.

## Two access managers, not one [#two-access-managers-not-one]

Two kinds of access manager hold the platform's own role grants: one system access manager for the organisation's system roles, and one per token for that asset's own roles. Add-ons such as a trading venue keep a third kind, covered below. A single address can hold broad authority in one and none in the other, and the contracts do not mirror each other's grants.

The system access manager is a single upgradeable contract. It holds the 15 system roles that the Console and the Platform API grant to a person, among them Permission manager, System manager, Asset manager, Compliance manager, Identity manager, Verification issuer and Auditor. It also holds Organisation identity manager, which the system grants to the account that bootstraps it, and the module roles that platform contracts grant each other during bootstrap. The token access manager is the equivalent contract for one token's seven roles: Permission manager, Governance, Supply management, Custodian, Emergency, Offering admin and Funds manager. Each one sits behind its own proxy, which the token factory deploys with the token. The factory holds the administrator role and Governance only while it deploys the token, and renounces both as the last step of the deployment. When the organisation switches to smart wallets, the switch also grants the organisation's own wallet the system roles its signer held. That wallet belongs to the organisation's participant, not to a person, so the Console lists it under the organisation's name and does not count it as a person. Anyone who can work as the organisation, a holder of Organisation identity manager or Permission manager, then sends requests from that wallet with those roles.

Offering roles have no access manager of their own. Offering admin and Funds manager are token roles held on the access manager of the token the offering sells. So a grant from an offering's page covers every offering of that token, and a sale has no role record of its own.

Both managers build on the same access-control foundation. Granting and revoking a role is itself gated: a caller needs the target role's admin role. In the system access manager, that admin chain is walked back to `DEFAULT_ADMIN_ROLE`, the one role that can set every other role's admin. In a token's access manager, `DEFAULT_ADMIN_ROLE` is the admin of every role directly. The Console calls `DEFAULT_ADMIN_ROLE` Permission manager.

Add-on contracts can define their own narrower role sets, granted through an access manager owned by the add-on. In the Trading Venue add-on, each venue splits the operator who configures instruments from the submitter that settles trades, each function gated by its own role check. Nothing on chain stops a venue administrator granting both roles to one address. This pair is one of the platform's default segregation pairs, so the platform refuses that grant through its own routes once the organisation enables its segregation rules. The submitter role belongs to the organisation's operations signer, and the operator role to the person who configures the venue.

A caller also reaches the two managers in different ways.

**System access manager**

One upgradeable instance for the whole deployment. A caller reaches it directly. Its own `DEFAULT_ADMIN_ROLE` chain is the only one that can grant System manager, Auditor, Gas manager and the other system roles.



**Token access manager**

One instance per token, deployed behind its own proxy with the token, which resolves its logic through the system contract. The initial administrator named when the token is created holds `DEFAULT_ADMIN_ROLE` on it from the start.

Holding a role in one gives no authority in the other: an Asset manager still needs a role in a token's own access manager to act on that token directly.

## A grant reaches every wallet of a person [#a-grant-reaches-every-wallet-of-a-person]

The platform records each person as a participant, and a participant can hold more than one wallet: a signing wallet and, in an organisation that uses smart wallets, the smart wallet that executes their transactions. A role grant through the platform names the participant, and the platform sends the grant to every wallet it can act on for that person. A grant can still name one address instead, for a wallet that belongs to no participant or when only one wallet should change.

The access manager checks the wallet that makes the call, so a role the signing wallet holds does nothing for a transaction the smart wallet executes. The Console marks a person whose smart wallet lacks a role their signing wallet holds as "Out of sync", and a Permission manager copies the missing roles across.

## Time-bound grants [#time-bound-grants]

Use an end for temporary authority, such as a cover Custodian for a holiday or an Auditor for one review. The Platform API accepts an end at least one minute after the request, and the Console asks for two minutes. The platform records the end and, when it passes, a platform workflow revokes the role on chain. The contract itself does not end the role: the revoke is a transaction the platform sends. On an asset, a grant sent again with a later end, or without one, replaces the earlier end. For an asset role, the platform also sends a webhook event when the end is less than 24 hours away and another after the revoke.

On an asset, every role is administered by `DEFAULT_ADMIN_ROLE`, so the platform checks the chain when the end passes and signs the revoke with the first wallet it holds keys for that still holds `DEFAULT_ADMIN_ROLE`: the wallet that granted the role, then the signer of another time-bound grant on the same asset, then the organisation's operations signer. A granter that has since lost `DEFAULT_ADMIN_ROLE` therefore no longer blocks the revoke. When none of those wallets administers the asset, nobody the platform can sign for may revoke the role: the platform sends no transaction, raises an operator alert and checks again after a backoff, so the role stays held until one of them administers the asset again or someone revokes it by hand.

Before it signs a revoke, the platform checks its transaction queue for a grant of the same role to the same account that is still being written, from any signer. While one is, the platform sends no revoke and checks again every minute, and it withdraws a revoke it queued earlier that has not been submitted yet. A grant that lands replaces or closes the expiry. A grant that fails lets the revoke go ahead. A revoke that was already submitted cannot be withdrawn. A grant of the role that lands after the platform queued its revoke also withdraws that revoke if it has not been submitted yet, even when the grant changed nothing on chain because the account still held the role. A permanent grant ends the expiry, and a grant with a later end keeps only that later end.

Permission manager has one extra rule on a token. Through the platform, a holder whose own Permission manager role has an end cannot grant Permission manager, and the platform refuses a change that would leave the token with no Permission manager whose role has no end.

## Segregation of duties [#segregation-of-duties]

Every role grant route of the platform checks the grant against the roles the wallet already holds, before any chain write. The check compares wallets, not people, so one person can hold both roles of a pair on two wallets. One rule applies in every organisation: a wallet cannot hold Auditor together with any other system role the platform grants. Each organisation can also keep its own pairs of roles that one wallet may not hold together, such as Supply management and Custodian, or Offering admin and Funds manager. Each pair is set to refuse the grant, or to let it through with a written reason that the audit trail keeps. The platform ships seven default pairs and applies them only after the organisation saves and enables its rules.

The check guards the platform's routes, not the contract. A grant made directly on chain outside the platform is not checked, so the platform also lists every wallet that holds a pair the organisation's rules name, from its record of role holdings. That report does not cover the Auditor rule. The [Roles and segregation of duties reference](https://docs.settlemint.com/docs/concepts/compliance-and-identity/roles-and-segregation-of-duties) lists the roles, the default pairs and the modes, and [Roles and permissions](https://docs.settlemint.com/docs/console/organisation-settings/admins-and-roles) shows how a Permission manager reviews, grants and revokes roles in the Console.

## Role changes need a Console sign-in [#role-changes-need-a-console-sign-in]

System, asset, offering and venue role grants and revokes through the Platform API require a Console-issued session, in both API v1 and API v2. The same rule applies to custody gateway role grants and revokes, fixed-yield schedule withdrawals, and the asset routes that add or remove supply delegates, hold reservers and authorised converters or revoke a burner capability. The v1 routes answer the refusal as their existing `403` `DALP-9485`, because v1 declares no other answer. The message and fix text in that response say to sign in to the Console, not to request a token role. A session issued by the Investor portal, an anonymous session or a session with no recorded issuing app answers `403 Forbidden` with `WALLET_ROLE_ADMINISTRATION_NEEDS_CONSOLE_SIGN_IN` ([DALP-200384](https://docs.settlemint.com/docs/api-reference/errors)). No role change starts. Sign in to the Console and retry. Sessions issued before this check recorded their issuing app are refused the same way until the user signs in to the Console again. The check applies whether or not an identity provider is configured. This refusal says nothing about whether the wallet holds the role needed to make the change: that check still applies after sign-in. API keys remain accepted where the route permits them.

## Checking a role before you rely on it [#checking-a-role-before-you-rely-on-it]

`hasRole(role, account)` is a plain view call against whichever access manager holds the role, and every governed contract exposes `accessManager()` so a caller can find the right instance without guessing. Read `hasRole` on chain for the exact current answer, or read the platform's indexed access-control views, which resolve the same roles into named flags for a faster lookup that can lag the block a change landed in. Check one of the two before submitting a transaction that depends on the answer: a role-management call from a caller who lacks the target role's own admin role reverts with the access manager's [unauthorised-account error](https://docs.settlemint.com/docs/api-reference/errors/error-code-reference#system--infrastructure). Recover by reading `getRoleAdmin(role)` for the admin role that can grant it, following that chain back to `DEFAULT_ADMIN_ROLE` if needed, and asking a holder of that role to act.

Every role identifier but one is a hash of a name, defined once as a constant so integrations reference the constant rather than recompute the hash. The exception is `DEFAULT_ADMIN_ROLE` itself, the zero value OpenZeppelin's access-control base reserves. Two shapes of batch helper exist: one applies one role to a list of addresses, gated the same as a single grant or revoke, and the other applies a list of roles to one address. On the system access manager, that second shape is gated to `DEFAULT_ADMIN_ROLE` specifically, stronger than a single role's own admin check. A caller who can grant one role at a time can still be refused the multi-role helper. The token access manager's equivalent has no such extra gate. Confirm which manager and which helper you are calling before assuming one caller can use both the same way.

Renouncing a role, including through the multi-role helper, lets a holder remove their own permission, and an authorised administrator can grant it again. The last `DEFAULT_ADMIN_ROLE` holder is different: without one, no account can grant or revoke the roles that `DEFAULT_ADMIN_ROLE` controls. So an access manager that counts its `DEFAULT_ADMIN_ROLE` holders refuses any revoke or renounce that would leave none, with `LastAdminProtected`. A token's access manager counts from the moment the token is created. A token created before counting existed starts once one of its administrators seeds the count. Until then, a direct contract call can still remove its last holder, so confirm another holder exists before removing one. A system's access manager that has not counted its holders yet refuses any change to who holds `DEFAULT_ADMIN_ROLE` with `AdminCountNotInitialized`, until an account allowed to upgrade it, a holder of `DEFAULT_ADMIN_ROLE` or System manager, seeds the count. Separately administered roles keep their own configured administrators regardless.

A role check inside a sponsored call checks the real caller, not the trusted forwarder that relays it. The system access manager also exposes `hasAnyRole`, a set-membership read some of its own gated functions use internally. The token access manager has no equivalent, so a caller checking a per-asset role checks `hasRole` once per role instead.

## On-chain role, organisation role, delegated authority [#on-chain-role-organisation-role-delegated-authority]

An on-chain role, an organisation role and delegated authority are three different things. The access manager checks only the on-chain role before a privileged call runs.

An on-chain role lives in an access manager and is checked at the moment of the call. A missing or revoked role reverts the transaction, and a present role passes only this check, so other checks can still reject the call. The organisation role, Owner or Member, and the platform role, Administrator or Member, decide which organisation and platform actions a signed-in person can take, such as changing settings or inviting people, and grant no contract authority. An organisation owner who must sign a mint still needs Supply management on a wallet the organisation can act on for them. Most Console controls that lead to a contract call read the platform's indexed view of the on-chain roles, which follows new blocks rather than the chain head. So a screen can show a control to someone whose role was revoked a moment ago, and the underlying call still reverts.

Delegated authority is a separate model. Working as another participant sets
whose context an operator steps into, and grants that operator no role. The on-chain roles of the account that executes
the call decide what the operator can then do, as if the operator held those roles directly. A reviewer who asks who can
do a given task takes the answer from the access manager, not from which party someone was acting as.

## Frequently asked questions [#frequently-asked-questions]

### Does a role apply to every asset, or to one?

An asset role applies to one asset. Per-asset roles, like Custodian or Governance, are checked against a single token's own access manager, so holding Custodian on one security token grants no authority on a second token deployed later, even under the same organisation. A system role applies across the organisation's system. A role an add-on defines, such as a Trading Venue's operator and submitter roles, is checked in that venue's own access manager and grants no authority on another venue.

### What happens to work already underway when a role is revoked?

A revoke does not undo a transaction that passed the access manager's check before it. The platform's record of the chain lags the chain itself: the revocation first lands as a [provisional event](https://docs.settlemint.com/docs/concepts/events-out/platform-event#the-envelope-states-how-settled-a-fact-is), `access-control.role-revoked.provisional`, and can be followed by a retraction, `access-control.role-revoked.retracted`, if a chain reorganisation reverses the block it was read from. A grant follows the same two-stage lifecycle. Store the event ID, idempotency key, role, account, and access manager address so a retraction updates the same record instead of creating a duplicate.

### Who can upgrade the access manager contracts themselves?

The system access manager authorises its own upgrade: the call needs `DEFAULT_ADMIN_ROLE` or System manager, checked on that same contract, and the upgrade can install any implementation. The token access manager has no equivalent function of its own. Its proxy resolves its logic address from the system contract on every call, and only System manager can change that registered implementation. Every token access manager on the deployment upgrades when it changes, and no token's own Permission manager can move or block that change. A holder of System manager controls the permission logic of every token on the system, and also replaces, each in one call, the token logic of every token a factory deployed, every add-on access manager and every custody gateway. Keep System manager, like Permission manager, on as few accounts as possible.

### Who grants the very first role on a new deployment?

The access manager grants `DEFAULT_ADMIN_ROLE` to a fixed list of initial admin addresses at deployment, before any other role exists. From there, `DEFAULT_ADMIN_ROLE`, or a role it delegates admin authority to, grants every other role. The system access manager and each token access manager hold their own separate instance of that chain, and an admin on one contract has no authority on the other. The token factory is among the initial administrators of a token's access manager only for the deployment, and renounces the role before the token is handed over.

## Related concepts [#related-concepts]

- [Asset Lifecycle](https://docs.settlemint.com/docs/concepts/issuing-and-markets/asset-lifecycle): The whole working life of a regulated tokenised instrument, from issuance through servicing to redemption. Every stage after issuance runs as an operation that a role gates.
- [Participant](https://docs.settlemint.com/docs/concepts/compliance-and-identity/participant): The platform's one record of a compliance subject. A role grant, a claim, an audit row, and a delegated operation all point at the same participant record.
- [Delegated Authority](https://docs.settlemint.com/docs/concepts/compliance-and-identity/delegated-authority): The umbrella model for one identity operating inside another party's context. Entering a context grants no role of its own. The executing account's own role grants decide what may then be done there.
- [Audit Trail](https://docs.settlemint.com/docs/concepts/records-and-evidence/audit-trail): The off-chain record of who acted and under what role. It observes a role grant's effect on a request. It does not itself grant or check one.


# Roles & duties

Source: https://docs.settlemint.com/docs/concepts/compliance-and-identity/roles-and-segregation-of-duties
Every role a DALP deployment checks, what each one permits, and which pairs of roles or people the platform keeps apart.

The platform checks three separate sets of roles. Organisation and platform roles decide which organisation and platform actions a signed-in person can take. They are Owner or Member in the organisation, and Administrator on the platform. On-chain roles decide which address can make a privileged contract call, or for a few roles which Platform API and Console actions a holder can take. Trading venue roles decide who can configure and settle a venue. Holding a role in one set grants nothing in the other two. The custody gateway add-on keeps its own roles in its own access manager, granted by the Gateway permission manager role.

To change who holds an on-chain role, use [Roles and permissions](https://docs.settlemint.com/docs/console/organisation-settings/admins-and-roles).

[Figure] Three role sets, each checked in a different place. Organisation and platform roles (Owner, Member, Administrator) are checked by the Console and Platform API for a signed-in person. On-chain roles, 33 in total, are checked by the system access manager and each token's access manager when an address calls a contract. Trading venue roles (admin, operator, submitter) are checked by the venue's own access manager. The three sets share no record, so a grant in one set gives no authority in another. Labels: Owner, Member, Administrator; Organisation and platform roles; Checked for a signed-in person by the Console and Platform API; 33 roles in the system and token access managers; On-chain roles; Checked for an address when it calls a contract; Admin, operator, submitter; Trading venue roles; Checked by each venue's own access manager.

Each set is checked in a different place, so a grant in one set gives no authority in another.

## Organisation and platform roles [#organisation-and-platform-roles]

An organisation member holds one of two organisation roles, Owner or Member. The Administrator platform role is set on a person's account, not in one organisation, and the Console shows it as the "Platform role". The role decides which resource actions the platform allows the person to perform. A person who needs to sign a contract call also needs the matching on-chain role.

| Resource | Owner | Member | Platform administrator |
| --- | --- | --- | --- |
| Organisation | update | none | list every organisation, archive, restore |
| Members and invitations | add, change and remove members, create and cancel invitations | none | add members |
| Settings | read, list, upsert, remove | read, list | read, list, upsert, remove, set the global theme |
| System | read, list, create | read, list | read, list, create, operate |
| Exchange rates | read, list | read, list | read, list |
| Webhooks | manage | none | manage |
| Corporate actions | approve | none | approve |
| Users | list, get, update | none | create, list, get, update, set role, ban, impersonate, delete, set password, set email |
| Sessions | none | none | list, revoke, delete |

The platform switches organisation deletion off, so no role deletes an organisation. The members, invitations, users and sessions rows come from the authentication library that the platform uses for sign-in. The platform defines the other rows itself. A platform administrator can impersonate a user and sign in as them. A platform administrator who is also an Owner of the organisation has the Owner column as well. Renaming the organisation, changing a member's role, removing a member and sending an invitation need the Owner role in that organisation, even for a platform administrator. Removing a member also needs the Identity manager on-chain role.

Owner and platform administrator are the two roles that count as eligible approvers for a partial redemption and for reporting sign-off. See [Maker-checker](https://docs.settlemint.com/docs/concepts/custody-and-signing/maker-checker) for the rules.

## On-chain roles [#on-chain-roles]

The platform defines 33 on-chain roles. Ten are held by contracts and never by people.

The other 23 are human roles, and the Console groups them under Platform, Compliance, Assets, and Oversight. The system-wide table lists 17 of them, and the Console and the Platform API grant 15 of those. The system grants Organisation identity manager to the account that bootstraps it, and no platform route grants Add-on manager. The tables name each role by its Console label, with the API field name where the two differ. Two scopes apply. A system-wide role is checked in the organisation's system access manager. An asset role is checked in the access manager of one token, so holding it on one token gives no authority on another. The Permission manager role, `admin` in the API, exists in both managers. Once the organisation switches to smart wallets, the organisation's own wallet holds system roles too. The Console lists that wallet under the organisation's name and does not count it as a person, for example when it warns that only one person holds Permission manager.

Granting or revoking a role needs the target role's administrator. In the system access manager, Permission manager can grant and revoke every role. In a token's access manager, Permission manager administers all of that token's roles. The [Role Grant](https://docs.settlemint.com/docs/concepts/compliance-and-identity/role-grant) page explains the model.

The Console marks each human role with a risk level. Permission manager and System manager are critical. Gas manager, Gateway permission manager, Escrow manager, Compliance manager, Identity manager, Bank rail manager, Venue manager, Governance, Supply management, Custodian, Emergency and Funds manager are elevated. Identity manager is elevated because one holder can replace any user's wallet and move that user's tokens with [an identity recovery](https://docs.settlemint.com/docs/console/my-account/onchain-identity#recover-a-user-who-lost-their-wallet). The other roles carry no risk mark.

### System-wide roles [#system-wide-roles]

| Role | Group | What it permits |
| --- | --- | --- |
| Permission manager (`admin`) | Platform | Grants and revokes every role in the system access manager, including to itself. Can upgrade the system access manager to any implementation. Gives no authority in a token's access manager. |
| System manager | Platform | Bootstraps and upgrades the system, including the system access manager, the implementation that every token access manager runs, and the token logic of every token a factory deployed. Points any add-on factory at new code, which every add-on that factory created runs from its next call: add-on access managers, custody gateways, escrows, token sales, token distributions, XvP settlements, trading venues, yield schedules, token governance and token features. One holder does it with no second approval, and the factory checks only that the new code reports the add-on's interfaces through ERC-165. Registers token factories, add-ons, and compliance modules. Creates trading venues. Sets the paymaster signer, and withdraws and stakes paymaster funds. |
| Gas manager | Platform | Funds and configures the paymaster and its fee splitter, as an API and Console permission. Rotating the paymaster's signing key needs System manager. No contract function checks it. |
| Escrow manager | Platform | Creates escrows from the escrow factory, such as the escrow a bank rail token link needs. An escrow sits on the compliance bypass list and its creator picks who controls it. Cannot upgrade the factory: that stays with the System manager. |
| Gateway permission manager (`custodyGatewayPermissionManager`) | Platform | Grants and revokes the custody gateway add-on's roles: its gateway managers, keepers and screeners. The add-on's own access manager checks it on chain against the system access manager. |
| Add-on manager | Platform | Manages protocol add-ons and their factories. Only the first version of the settlement factory checked it on chain. |
| Compliance manager | Compliance | Registers and configures compliance modules. Manages global compliance settings. Also holds the on-chain permission to edit the bypass list, which the Console and the Platform API do not expose. |
| Verification policy manager (`claimPolicyManager`) | Compliance | Registers topic schemes and manages trusted issuers and the claim topics they may issue. |
| Verification issuer (`claimIssuer`) | Compliance | Creates and revokes identity claims through the Platform API. Holding the role does not make an issuer trusted: trust is set in the trusted issuers registry. No contract function checks it. |
| Identity manager | Compliance | Registers, updates, recovers, and deletes identities in the identity registry. Onboards users. A recovery marks a holder's wallet lost and names its replacement, which can then claim that wallet's whole balance of every token, so this role can move holdings. |
| Organisation identity manager | Compliance | Manages the organisation's own identity, including its claims and keys and its organisation-level verifications. |
| Asset manager (`tokenManager`) | Assets | Deploys and configures tokens, registers external tokens, and creates token sales and yield schedules. |
| Asset designer | Assets | Designs asset classes and instrument templates. Cannot mint tokens or upgrade contracts. An API and Console permission only. |
| Bank rail manager | Assets | Sets up and runs the organisation's bank rail, the bank connection that mints tokens when the bank credits the account. An API and Console permission only. No contract function checks it. |
| Venue manager | Assets | Creates trading venues. The account that creates a venue holds its default administrator role. The venue contract checks its own roles after that, covered below. |
| Feeds manager | Assets | Registers, replaces, and removes data feeds. Sets price resolver staleness limits. |
| Auditor | Oversight | Read-only access to permissions, identities, audit logs, and system state. No contract function checks it, and it cannot change anything. |

### Asset roles [#asset-roles]

Asset roles are checked in the access manager of one token. On the "People" tab, Governance counts in the Compliance group, Permission manager in Platform, and the other asset roles in Assets. The asset's own role editor groups them as Administration, Compliance, Operations and Other.

| Role | What it permits on one token |
| --- | --- |
| Governance | Renames the token, replaces its compliance and identity registry bindings with any contract, which can take the token out of the global controls, edits metadata, adds and removes compliance modules, and sets feature parameters such as fee rates. On a bond, sets the cap and marks maturity. |
| Supply management | Mints, and burns from any holder's wallet, singly or in batches. No compliance rule can block a burn. Withdraws the denomination asset from the token's yield schedule. |
| Custodian | Freezes an address or part of a balance, forces a transfer, and recovers tokens from a lost wallet. A forced transfer skips the compliance modules, still runs the recipient's identity check, and runs while the token is paused or the sending wallet is frozen. It refuses a frozen recipient. Claims yield on a holder's behalf. |
| Emergency | Pauses and unpauses the token and recovers ERC-20 tokens sent to it by mistake. A pause does not stop a custodian forced transfer or a recovery. Can end a bond early. |
| Offering admin | Activates, pauses, extends and ends a token sale, finalises it, and withdraws unsold tokens. Sets its terms hash, step, whitelist and allocations, and on a book-built sale its application mode, greenshoe and lock-ups. |
| Funds manager | Funds a token sale, finalises it, withdraws the payment currencies it collected, and refunds a purchase that cannot be delivered. |

### Contract roles [#contract-roles]

Contract roles belong to platform contracts and are granted during bootstrap or registration. Do not assign them to a person. They matter to an auditor because they show which contract may write to which registry.

| Role | Held by | What it permits |
| --- | --- | --- |
| System module | The system contract | Acts as an alternative caller on the compliance, topic scheme, and trusted issuers registries. Binds identity registries. |
| Identity registry module | The identity registry | Writes identities, countries, and wallet recovery links in identity storage. |
| Token factory registry module | The token factory registry | Administers the token factory module role. No function checks it directly. |
| Token factory module | Each registered token factory | Registers identities, binds tokens to compliance, and issues organisation claims when a factory deploys a token. |
| Add-on factory registry module | The add-on registry | Updates add-on factory implementations. Administers the add-on module role. |
| Add-on factory module | Each registered add-on | Creates access managers, registers feeds, and registers identities for add-on contracts. |
| Trusted issuers meta registry module | The trusted issuers meta registry | Manages the trusted issuers registry on the meta registry's behalf. |
| Compliance engine module | Each token's compliance engine | Deploys module instances from the compliance module registry. |
| Token compliance factory module | The token compliance factory | Creates each token's compliance engine and grants it the compliance engine module role. |
| Token identity registry factory module | The token identity registry factory | Deploys each token's identity registry. |

## Trading venue roles [#trading-venue-roles]

Each trading venue has its own access manager with three roles. The venue contract checks them, not the system access manager. The account that creates the venue holds the default administrator role, which administers the venue admin role. The venue admin role administers the operator and submitter roles.

| Role | Holder | What it permits |
| --- | --- | --- |
| Venue admin | A person | Admits and revokes member identities. Sets the admission policy and calendar commitment. Resumes a paused venue. Sweeps tokens the venue's escrow holds beyond what it owes. Manages the venue identity's claims. Can also pause. |
| Venue operator | A person | Creates, halts, resumes, and delists instruments. Sets holding periods, fee schedules, fee accounts, price bands, and the per-fill gas limit. Pauses the venue. Flags and clears flags on trades. Cancels orders. Cannot undo a trade, resume a paused venue, or grant a role. |
| Venue submitter | The organisation's operations signer | Settles batches and auctions, reserves and releases holdings, flags trades and clears flags, and undoes a trade after the second approver has approved it. Never grant it to a person. |

Provisioning a venue in the Console grants the submitter role to the organisation's operations signer. See [Venue operations](https://docs.settlemint.com/docs/console/asset-lifecycle/venues) for the workflow.

## What the platform enforces [#what-the-platform-enforces]

For each control in this table, the platform rejects a decision made by the same person who proposed it. [Maker-checker](https://docs.settlemint.com/docs/concepts/custody-and-signing/maker-checker) describes the full rules, including the cases where an organisation can waive a control.

| Control | The platform rejects | How it is enforced |
| --- | --- | --- |
| Trading venue approvals | The proposer approving their own trade bust, desk trading limit, fee schedule, order cancellation, mass order cancellation or venue configuration change | A database rule on the venue approval record requires the checker to differ from the proposer. |
| Wallet checker approval | The wallet's checker starting a transaction from the wallet they check | The approval flow refuses the transaction and a different person must start it. |
| Reporting sign-off and acknowledgement | The preparer signing off their own filing, or the approver entering the authority's acknowledgement | A database rule on the submission requires the checker to differ from the preparer. The platform also checks the signing user and refuses an impersonated session. |
| Partial redemption and in-kind payout | The person who recorded or previewed the action approving it | A database rule on the corporate action requires the checker to differ from the proposer and from the last previewer. An organisation can switch the control off. |
| Bank account approval | The proposer approving the bank account they proposed for a client | The platform refuses the approval and a different Bank rail manager must make it. The rule holds when the Bank rail approval is off. |
| Recall execution or abandon | The manager who asked to execute or abandon a recall approving or rejecting that request | The platform refuses the decision, and an impersonated session cannot decide it either. The rule holds when the Bank rail approval is off. |

An owner or a platform administrator can also require a second person for ten families of change in the organisation's [Approvals](https://docs.settlemint.com/docs/console/organisation-settings/general#approvals) settings. The Administration family covers privileged changes such as role management, compliance configuration, freezes, pauses, forced transfers and recovery. Every family is off by default, except the "Recovery" group of Administration, which starts on.

The platform always enforces one segregation rule for system roles through its routes: one address cannot hold `auditor` together with any of the other 14 system roles the platform grants. A grant made directly on chain is not checked, and the conflict report does not list it. A grant of either side to an address that holds the other is refused, and a request cannot grant both together. The refusal is `PLATFORM_ROLE_SEGREGATION_CONFLICT`, and `data.conflicts` names each pair with scope `platform` and mode `block`. The administrator role appears there as `DEFAULT_ADMIN_ROLE`. A request that revokes the conflicting role at the same time is evaluated after that revoke and goes ahead when no other conflict remains.

Each organisation can also keep its own segregation-of-duties rules, stored in the `ROLE_SEGREGATION` organisation setting. A rule names two on-chain roles, such as `GOVERNANCE_ROLE` and `CUSTODIAN_ROLE`, and a scope: `contract` when the two roles conflict only on the same token, token sale or venue, `platform` when they conflict anywhere in the organisation's system. Each rule also has a mode, which decides what happens to a grant that breaks it:

| Mode | A grant that breaks the rule |
| --- | --- |
| `warn` | Is refused until it carries a `reason`, with `data.reasonRequired` set to `true`. The grant then goes ahead and the audit trail keeps the reason with the broken rules. |
| `block` | Is refused. The answer is `PLATFORM_ROLE_SEGREGATION_CONFLICT` and `data.conflicts` names each broken pair and its mode. |

Both modes stop a grant that has no reason. `warn` lets it through once someone records why.

The setting's `enabled` switch turns the check on. While it is off, grants go ahead and the rules still feed the conflict report. An organisation owner or a platform administrator saves the setting with `POST /api/v2/settings`. In the Console, an owner sets the switch and the rules in the [Segregation of duties](https://docs.settlemint.com/docs/console/organisation-settings/general#segregation-of-duties) section of General.

The check runs on every role grant route, for system, token, token-sale and venue roles, before any chain write. It also covers the initial permissions of a new token and the roles an invitation grants. It counts the roles the address already holds anywhere in the system, after the same request's revokes, and the other roles named in the same grant. It compares addresses, not people, so one person can hold both roles of a pair on two wallets, or use the second by working as a party whose wallet holds it. An address that holds a system module role is a platform contract and is not checked. The frozen v1 grant routes and the token create routes cannot send a `reason`, so they refuse a grant that breaks a `warn` rule. While the setting is enabled, the platform refuses a grant it cannot check, because the system's access manager or the target access manager is not in its record of the chain yet.

In the Console, a refused role change names each conflicting pair and its scope, for example "Custodian cannot be held with Governance on the same contract." The Console's role sheets send no `reason`, so they also refuse a grant that breaks a `warn` rule. Send that grant through the Platform API with a `reason` instead.

No organisation pair is enforced until the organisation saves and enables the setting. Until then its rules are the default pairs marked in the next table, each set to `block`, as a starting list.

`GET /api/v2/system/role-conflicts` lists every address that holds a pair the organisation's rules name, for a Permission manager or Auditor. It reads the platform's record of role holdings, so it also shows roles granted directly on chain outside the platform. It does not apply the always-on Auditor rule, so an address that holds Auditor and another system role does not show there. Narrow it with `filter[mode]`, `filter[scope]` or a `filter[q]` search, and sort it by `account`, `mode` or `scope`.

A system role grant may carry an `expiresAt` at least one minute in the future. A settled response repeats the expiry, and a durable workflow revokes the granted roles after it.

## Role pairs to keep apart [#role-pairs-to-keep-apart]

The table lists pairs where one holder would remove an independent check.

| Pair | Why to separate them | Enforced by the platform |
| --- | --- | --- |
| Identity manager and Verification issuer | One holder can register an identity and attach the claim that qualifies it, with no second review. | A default organisation rule, once enabled |
| Verification policy manager and Verification issuer | One holder can decide which issuers and topics are trusted and then issue claims under that trust. | No |
| Compliance manager and Custodian | One holder can relax the compliance rules and then force a transfer or move frozen balances. | A default organisation rule, once enabled |
| Governance and Custodian | Governance replaces a token's compliance bindings and the custodian forces transfers, so one holder controls both the rule and its exception. | A default organisation rule, once enabled |
| Supply management and Custodian | One holder can mint tokens and move them to another address without the holder's consent. | A default organisation rule, once enabled |
| Offering admin and Funds manager | One holder can run a sale and withdraw the funds it collects. | A default organisation rule, once enabled |
| Auditor and any other system role | An Auditor is read-only, while every other system role changes protocol or operational state. One holder could change the state that they also review. | Yes, for system role grants through the platform |
| Permission manager and any operational role | Permission manager can grant itself every other role, so it undermines every other pair in this table. Hold it on as few accounts as possible. | No |
| Identity manager and any other role | A recovery lets one holder redirect any holder's balances to a wallet it names. Hold it on as few accounts as possible. The **Recovery** protection group under Administration in [Approvals](https://docs.settlemint.com/docs/console/organisation-settings/general#approvals) is on by default, so a second person approves each recovery made through the platform. | No |
| System manager and any operational role | System manager can replace the logic of the system access manager and of every token access manager. Hold it on as few accounts as possible. | No |
| Venue operator and Venue submitter | The operator configures instruments and the submitter settles trades. One holder configures and settles. The contract also permits a person to hold the submitter role, which the venue design reserves for the operations signer. | A default organisation rule, once enabled |
| Venue admin and Venue operator | One holder admits participants and also sets their instruments and fees. | A default organisation rule, once enabled |

"A default organisation rule, once enabled" means the platform refuses the pair only after the organisation saves and enables the `ROLE_SEGREGATION` setting. A role change made through the platform is recorded in the [Audit trail](https://docs.settlemint.com/docs/console/reporting/audit-trail) with the person who made it, their platform and organisation role at the time, and the roles before and after. Review the conflict report at each access review. Review the pairs no rule covers, such as Permission manager or System manager with another role, on the "People" tab of Roles and permissions.

## Frequently asked questions [#frequently-asked-questions]

### Does the platform warn when one account holds two conflicting roles?

It refuses a system role grant that would leave one address holding `auditor` and any other system role, in every organisation. For the organisation's own rules it refuses or asks for a reason according to each rule's mode once the `ROLE_SEGREGATION` setting is enabled. `GET /api/v2/system/role-conflicts` lists the addresses that already hold a pair the organisation's rules name, including roles granted on chain outside the platform.

### Which controls need a second person without any role setup?

The controls in the enforcement table. They compare the people involved, not their roles, so they apply even when one person holds every role. A wallet checker is the exception in one respect: it applies only to a wallet that has a checker configured.

### Is an on-chain role the same as a platform administrator?

No. The Administrator platform role is set on a person's account and checked by the Console and Platform API. The on-chain Permission manager role, `admin` in the API, is held by an address and checked by the contracts. A platform administrator or an organisation owner has no contract authority until an address the organisation can act on for them holds the matching on-chain role.

### How many roles does DALP have?

The role vocabulary has 33 on-chain roles, 23 of them human and ten held by contracts. Organisation and platform roles add three more, Owner, Member and Administrator, and trading venues add three more. The sets are separate.

## Related concepts [#related-concepts]

- [Role Grant](https://docs.settlemint.com/docs/concepts/compliance-and-identity/role-grant): How a role is granted, checked on chain and ended.
- [Maker-Checker](https://docs.settlemint.com/docs/concepts/custody-and-signing/maker-checker): The controls that need a second person whatever roles people hold.
- [Delegated Authority](https://docs.settlemint.com/docs/concepts/compliance-and-identity/delegated-authority): Why working as another participant adds no role of its own.
- [Add-on approvals](https://docs.settlemint.com/docs/concepts/compliance-and-identity/addon-approvals): A second approver on one exact add-on call.


# Transfer-Path Compliance

Source: https://docs.settlemint.com/docs/concepts/compliance-and-identity/transfer-path-compliance
Transfer-Path Compliance enforces a regulated token's rules inside the on-chain transfer, so an ordinary movement that fails a rule reverts before it settles.



[Figure] Both failures land in the same place: nothing moved. A transfer or mint request reaches the token. The token first checks whether the recipient passes the identity registry checks. If not, the transaction reverts. If that passes, the token evaluates every configured rule, and any single failure also reverts. Both failures end in the same state: no balances change. A generic rejection may require simulation to identify the blocker. Only when the identity check and every rule pass do balances update and rule state record the movement. Nothing partially settles: the movement happens whole, or it does not happen. Labels: Transfer or mint reaches the token; Recipient identity registered?; no; yes; Every configured rule passes?; one failure is enough to stop it; no; yes; Balances update; rule state records the movement; Reverted; no balances change,; the failing rule is named; Nothing partially settles: the; movement happens whole, or; it does not happen.

Ordinary transfers must pass identity and compliance checks, and a failed check reverts the transaction and its balance changes.

Ordinary transfers and mints run the asset's applicable checks before balances change, and a failing rule reverts the movement. Every token bound to the organisation's system compliance engine on its network inherits global controls alongside its own modules: a token factory binds each token it deploys, and a factory migration binds older tokens. Forced transfers, wallet recovery and bypassed recipients skip some checks, and the Governance and System manager roles can change the checks themselves. Controls and evidence lists each.

Eligibility depends on on-chain claims and configured rules. An off-chain decision affects transfers after the corresponding claim or policy update reaches the chain.

A read-only pre-check reports current blockers before signing. A clear result does not reserve eligibility or guarantee later execution.

## Why transfer-path compliance matters [#why-transfer-path-compliance-matters]

For an institution issuing regulated assets, transfer-path compliance means the rules you configure travel with the asset: who may hold it, in which jurisdiction, up to what cap, under what lock-up. The token enforces applicable rules inside ordinary transfers and mints, including calls made outside the Platform API.

Transfer-path compliance runs on every ordinary transfer and mint across the whole [asset lifecycle](https://docs.settlemint.com/docs/concepts/issuing-and-markets/asset-lifecycle). The same eligibility registry that decides who may receive the first minted unit checks every later transfer.

On-chain checks enforce the recorded policy. They do not establish that the policy is legally sufficient or that off-chain evidence is current.

Your existing compliance providers keep their role. An accredited know-your-customer (KYC) or anti-money-laundering (AML) provider becomes an on-chain issuer: its passed check grants a holder eligibility, and its sanctions hit revokes it. The platform enforces the rules you configure. The legal policy, the provider relationships, and the decision to change a rule stay with your organisation.

## Running compliance day to day [#running-compliance-day-to-day]

Choose the rules each asset enforces and keep holder eligibility current. A country allow list, investor-count cap, or minimum holding can each block a transfer for a different reason. The platform applies whatever configuration exists when value moves, so rule changes and identity updates take effect on the next transfer.

You configure rules per asset under its Governance role, either picking modules one at a time or applying a policy template, a named, versioned package of preconfigured modules you reuse across issuances. The Governance role can change or turn off those modules at any time after issuance. Reach for a template once you repeat the same rule set. A one-off asset with a bespoke mix costs less to hand-pick than to version. A Compliance manager installs a rule that must hold everywhere, such as a sanctions block list, once as a global control. Every bound token inherits it at once, and that token's compliance view marks it as inherited. A new global control governs future movements only, never balances that already settled.

Eligibility work is claims work: you review a participant's evidence off-chain, or a connected provider sends its verdict, and a trusted issuer records the result as a claim on the participant's on-chain identity. Revoking the claim withdraws eligibility the same way.

[Figure] Two feeds govern ordinary movements. The eligibility feed carries off-chain review to a trusted issuer, who issues or revokes a claim on the holder's identity. The rule feed carries the asset's policy, a template or hand-picked rules, into the rules configured on the asset. Both feeds converge at the next transfer or mint attempt: when in-scope rules pass the movement executes, and when a rule fails the movement is blocked and simulation can help identify the blocker. Labels: Two feeds, one movement; Eligibility feed; Off-chain review or provider verdict; KYC file, sanctions screen; Claim issued or revoked; trusted issuer attests it; Rule feed; Policy template or hand-picked rules; chosen for the asset; Rules configured on the asset; Next transfer or mint attempt; At every movement; in-scope rules pass; a rule fails; Movement executes; balances update and rule state records it; Movement blocked; the failing rule is named.

An ordinary movement passes only when both the rules configured on the asset and the claims on each holder's identity agree.

When a transfer keeps failing, the token's "Transfer pre-check" tab explains why: enter the sender, recipient and amount, and it runs that exact transfer against the live rules without signing anything. The result lists detected blockers and who can resolve them, such as a holder with a missing claim, a sender without enough transferable units, or an operator managing a freeze or a paused token. A frozen holder address counts as a blocker for transfers: the recipient-eligibility check reports it as not eligible with the reason `address-frozen`. A stale price requires a fresh feed update. The result describes current state. Execution can encounter later changes. Fix the blocker, re-check, then submit the real transfer.

## How it works and what it covers [#how-it-works-and-what-it-covers]

Transfer-path compliance runs as a check inside the token's own state-update path. Every ordinary way of moving the token ends in the same hook: a direct transfer, an allowance-based transfer or a batch item. Enforcement therefore does not depend on how the movement was submitted. The token standard extends ERC-3643, an open standard for permissioned security tokens.

An ordinary transfer first runs the recipient's identity check in the token's identity registry: registration, a wallet not marked lost and, where the registry holds one, its topic expression. The compliance engine then checks the recipient bypass list, the addresses, such as the platform's settlement and vault contracts, that skip the rules that judge a recipient. DALP manages the list: a token or add-on factory adds the contracts it deploys. On the second-generation compliance engines, a bypassed recipient skips, in both module layers, the rules that judge the recipient: country and identity lists, identity verification, claim expiry, holder counts and transfer approval. The address block list, time lock, lock-up, minimum holding, own custody gateway and supply rules still run. A first-generation engine skips every module for a bypassed recipient. Active modules evaluate the movement in scope, and the token engine then delegates to the global engine. A failing check reverts the transaction. A generic rejection may require simulation to identify the blocker.

[Figure] One engine reads two layers from one catalogue. The token's compliance engine evaluates on every movement on the transfer path. It reads the platform's module catalogue of registered control types, which feeds two layers: the rules installed on this token, and the global controls installed once at the platform level. Every rule passing lets the transfer proceed. The first failure reverts it. Labels: One engine, two layers; Token transfer path; ordinary transfers and mints; The token's compliance engine; reads the module catalogue, then both layers; Module catalogue; registered control types; Rules installed; on this token; Global controls; installed once, platform-wide; Every rule passes: it proceeds.; One failure reverts it.; At every movement.

One catalogue supplies both layers of controls, and a bypass-listed recipient skips only the modules that judge the recipient on a second-generation engine.

Modules are typed and instanced. A control type must exist in the platform catalogue before an engine can install it. Installing it deploys a fresh instance, so the same type can run more than once with different parameters. Each instance can limit its checks by sender, receiver, or country. Global rules can also select tokens by scope. The Compliance manager sets a global rule's scope. The token cannot change that selection.

After a successful movement, stateful rules update their records in the same transaction: holder counts, issuance windows, consumed approvals, lock batches. A failed update reverts the whole transfer, so rule state and balances stay in step while the rule is enabled. A small set of paths move value without evaluating those rules. Controls and evidence lists each one with what it still requires.

## The integration contract [#the-integration-contract]

The API surfaces transfer-path compliance as three parts: configuration, simulation, and a failure contract. You install, configure, scope, disable, or remove compliance modules on a token or at the system level, and group modules into compliance templates you apply at asset creation.

Before submitting a transfer, simulate it. The [transfer-simulate endpoint](https://docs.settlemint.com/docs/api-reference/v2) takes the sender, recipient, and amount and runs the same on-chain compliance check the transfer itself would run. It returns a verdict of will clear or will revert. On a revert it also returns a blocker list: the rule that fails, which party it applies to, the reason class, and who can remediate it. The endpoint signs and changes nothing, so call it as part of a pre-trade workflow.

[Figure] Simulate first, then submit. The integrator first asks to simulate a transfer with the sender, recipient, and amount. The token answers with a clear verdict or the rules that block it, and the verdict returns to the integrator. Once ready, the integrator submits the real transfer under the same rules. The token executes it or reverts it, and the result settles on chain either way. Labels: Simulate first, then submit; Simulate; Integrator asks to simulate; sender, recipient, amount; Clears, or lists the; rules that block it; Token answers; verdict returns to the integrator; once ready; Submit; Integrator submits the transfer; same rules, for real this time; Token executes; or reverts,; naming the failing rule; settles on chain, or reverts on chain.

Simulating before submission shows current blockers, but the real transfer checks state at execution and can still fail after a clear simulation.

[DALP-1096](https://docs.settlemint.com/docs/api-reference/errors) reports a rejected transfer and [DALP-1110](https://docs.settlemint.com/docs/api-reference/errors) a rejected mint. Neither code alone identifies the failing layer. Inspect the simulation result and current policy. [DALP-1111](https://docs.settlemint.com/docs/api-reference/errors) identifies a stale-price blocker that needs a fresh feed update. Recheck after remediation. If a write was already accepted, read its outcome before deciding whether to retry the existing request or start a new attempt.

The token contract enforces the rules, and the API only reports them. An ordinary movement submitted through any client or a direct on-chain call passes the same checks. The forced-transfer and recovery routes skip the module checks, as [Controls and evidence](#controls-and-evidence) lists.

### Read a transfer's verdict before signing [#read-a-transfers-verdict-before-signing]

Call `GET /api/v2/tokens/{assetId}/transfer-simulate?from={sender}&to={recipient}&amount={amount}`. Any signed-in caller or API key can call it, and `amount` is an integer string in the token's base units. The call submits nothing and costs no fee. It reads the token's pause state, any freeze on either address, the sender's transferable units, the recipient's identity and the compliance rules bound to the token. Transferable units are the sender's balance less its frozen and held units.

The response holds `data.verdict`, either `will-clear` or `will-revert`, and `data.blockers`. Each blocker carries `code`, `party` (`sender` or `recipient`), `reason`, `remediationClass` and `remediation`, plus `moduleTypeId` and `moduleInstance` when a compliance module refused the transfer, and `topics` when a missing claim is the cause. When a rule that requires claims refused the party, `ruleSource` names it, and `topics` lists the claim topics missing for that rule:

- `token-registry` is the rule stored in the token's identity registry.
- `identity-verification-module` is the rule in the token's identity verification module, first or second generation.
- `global-control` is the system's global identity verification control. Each rule that refuses gets its own blocker, so a party that fails two rules sees two blockers. A blocker that no module explains, such as a freeze, too few transferable units, a paused token or a restricted refusal, carries neither module field. A `remediation` of kind `none` carries a `reason` that says why. The `remediationClass` says who can resolve the blocker:

- `self-serve`: the party can resolve it, for example by obtaining a claim the token requires or by holding enough transferable units.
- `operator`: someone at the issuing institution must act, for example to unfreeze an address, remove an entry from a block list, register an identity, approve the transfer or unpause the token.
- `structural`: the transfer cannot clear in its current shape, for example when no compliance module explains the refusal.

The verdict comes from live chain calls. When the transfer would revert, the platform adds the rule detail from its index of on-chain state, and that detail never changes the verdict. Rule-level detail goes only to a caller whose signing wallet holds the System manager, Identity manager, Verification issuer or Compliance manager role, or whose signing wallet is a custodian of the token. Any other caller sees freezes, a short balance and a paused token by name, and a single blocker with the code `compliance-restricted` for anything else.

The platform evaluates the identity and compliance rules only on a token the caller's organisation issued. On any other token the check covers the pause state, freezes and the sender's transferable units. A `will-clear` there says nothing about the token's rules. The check does not cover an allowance or a token feature that refuses the transfer, so a pass can still revert for those reasons.

A token that is not indexed on the caller's network answers not found. When the platform cannot read the chain or its index in time, the route answers [DALP-12354](https://docs.settlemint.com/docs/api-reference/errors), a retryable 503 with the message "The transfer check is temporarily unavailable". That answer is not a verdict, so retry after a short wait.

## Controls and evidence [#controls-and-evidence]

Transfer-path compliance is preventive for the movements within its scope. A failed check reverts that transaction's balance changes. Governance must account for bypassed recipients, recovery paths, and policies that do not encode every legal requirement.

Enforcement reads on-chain state at execution time: a revoked claim or a new block-list entry binds at the next movement that needs it. The lag between an off-chain decision and the matching on-chain claim update is your operating responsibility. The platform enforces only what your process has already recorded.

You can read the evidence without reconstructing it. Each token shows its own modules plus the global controls that reach it, each marked "Global", and one platform-level page shows the global policy. Each identity carries its claim history, with issuers, and simulation can identify the current transfer blockers. Keep personal evidence off-chain. Claim fields and identifiers are public, so review their contents before issuance. A claim records an issuer's attestation, and withdrawing trust in that issuer stops its claims from counting at the next movement, without touching the claims themselves.

Four paths move value without the full rule check, and each is recorded on chain:

- **Custodian forced transfer.** Only the token's Custodian role can run it. It skips the compliance modules, the pause and the sender's freeze, refuses a recipient whose address is frozen, and still runs the recipient's identity check in the token's identity registry, topic expression included where the registry holds one. A topic rule applied through an identity verification compliance module does not run. The chain records it as a custodian operation.
- **Wallet recovery.** An Identity manager records a wallet as lost and names its replacement, acting alone on chain. The platform's own recovery then moves each balance with the custodian's forced recovery call, under the same identity check. The replacement wallet can also claim the lost wallet's balance itself, so review who holds Identity manager as closely as Custodian.
- **Bypassed recipients.** The platform's own settlement and vault contracts may receive assets without the rules that judge a recipient, while sender-side and supply rules still run on a second-generation engine. Ordinary transfers leaving them for a non-bypassed recipient pass the applicable checks. No Console screen or Platform API route edits the bypass list directly. A System manager can change the list by registering a custom token factory or add-on, or by pointing a registered one at new code, because every registered factory and add-on can add and remove addresses. A Compliance manager can change it with a direct call to the system compliance contract.
- **Burn.** A burn skips eligibility checks because no one receives anything. Supply tracking rules record it after the fact, and the Supply management role can burn from any holder's wallet.

Three roles can change the check itself. The Governance role can replace a token's compliance contract and identity registry with a direct contract call, and change or turn off its modules. The System manager can replace the token logic that every token from a factory runs. A Compliance manager installs, scopes and removes global controls. Reviewing a token's effective policy means checking the bypass list and who holds Custodian, Governance, Identity manager, Supply management, System manager, Compliance manager and Escrow manager, beside the bindings.

## Frequently asked questions [#frequently-asked-questions]

### What happens when a holder loses eligibility after acquiring tokens?

The held balance stays where it is. Enforcement applies to movements, not to holdings. Once an issuer revokes a claim, the holder cannot receive more of any asset that requires it, and sender-scoped rules bind their outgoing transfers too. Freezing or moving the balance itself is a governed custodian decision, not an automatic consequence.

### Can anyone get around the rules?

A custodian forced transfer and a wallet recovery skip module evaluation, the bypass list skips the rules that judge a recipient, and a burn skips eligibility. [Controls and evidence](#controls-and-evidence) lists the four paths and the roles that can change the rules themselves. A wallet cannot recover itself: recovery needs an Identity manager to record the wallet as lost and name its replacement, and that Identity manager can name a wallet they control. A direct on-chain transfer between two ordinary wallets runs the same checks as one submitted through the platform.

### Does a clear pre-check guarantee the transfer will succeed?

No. The verdict only holds for the instant the simulation runs against live state, not as a lock on that state. Between the read and the signature, an issuer can revoke a claim or a Compliance manager can add a global control, and neither one waits for you to sign. Re-run the simulation immediately before submitting, especially after any delay for review, approval or a wallet's own signing prompt, because eligibility can move in that gap. The check also does not cover an allowance or a token feature that refuses the transfer, so a clear result can revert for those reasons too.

### How is this different from checking compliance in the application before submitting?

An application-side check advises, while the token enforces. Because the rules run inside the token contract, they bind every submission path, including ones that never touch your application. Simulation inspects the applicable on-chain checks against current state. A later transfer can see different state or encounter another execution failure.

### How do decisions from our KYC provider reach the chain?

A decision reaches the chain in one of two ways. A connected provider sends its verdict, and the issuer identity the platform provisioned for that provider signs or revokes the matching claim. Or your own reviewers complete the review, and an issuer you trust records the claim manually. Either way, enforcement reads the claim, and the attestation counts only when the registry trusts the issuer for that claim topic.

### Who decides which rules an asset enforces?

Your organisation decides, split by role. Whoever holds the asset's Governance role picks and parameterises its modules, or applies a policy template, at issuance, and can change or turn them off at any time after. The Compliance manager, an organisation-wide role, is the only one who can install or scope a global control. The Verification policy manager decides which issuers count for each claim topic. The platform validates and enforces whatever that configuration says. It does not choose the policy or substitute for legal or regulatory judgment.

## Related concepts [#related-concepts]

- [Asset Lifecycle](https://docs.settlemint.com/docs/concepts/issuing-and-markets/asset-lifecycle): The whole working life of a regulated tokenised instrument, from issuance through servicing to redemption. Transfer-path compliance runs inside every transfer and mint across that whole life.
- [Participant](https://docs.settlemint.com/docs/concepts/compliance-and-identity/participant): The platform's stable record of a subject that a claim, a role grant and an audit row all point at. The identity check inside every transfer resolves to one of these.
- [On-Chain Identity](https://docs.settlemint.com/docs/concepts/compliance-and-identity/onchain-identity): The ledger record of one subject that the token resolves in the identity registry before any rule runs.
- [Compliance Policy](https://docs.settlemint.com/docs/concepts/compliance-and-identity/compliance-policy): The reviewed policy template and platform-wide global controls that the rules enforced on this page are configured from.
- [Role Grant](https://docs.settlemint.com/docs/concepts/compliance-and-identity/role-grant): The on-chain permission an access manager checks before a privileged call runs. The Governance, Compliance manager and Verification policy manager roles this page names are each one.
- [XvP Settlement](https://docs.settlemint.com/docs/concepts/settlement/xvp-settlement): An on-chain exchange in which every leg settles together in one transaction or none settles at all, so no party delivers without receiving what they are owed.


# Agent mandate

Source: https://docs.settlemint.com/docs/concepts/custody-and-signing/agent-mandate
An agent mandate confines a software agent's smart wallet on chain: the calls it may make, the amounts it may move and the date it stops.

An agent mandate is the on-chain record that confines a software agent's smart account: the calls it may make, the amounts it may move and the date it stops. The account is a [Smart Wallet](https://docs.settlemint.com/docs/concepts/custody-and-signing/smart-wallet) whose only validator is the mandate validator, which checks every user operation against the mandate before a single call in that operation runs. This page covers what that contract enforces. [Agents and mandates](https://docs.settlemint.com/docs/concepts/custody-and-signing/agent-mandates) covers how the organisation owner creates, changes and revokes agents.

Software that funds payouts on a schedule or administers assets acts through a key the platform holds for it. A limit enforced only in the agent's own software is a limit the agent's key can lift, so the mandate puts the limit in the account. A call outside the mandate makes validation revert, so the account never executes it. The platform's bundler simulates validation before it submits anything, so it refuses the operation without submitting it and returns the validation failure.

The organisation's operations account writes the mandate and administers it. Its signing address is a managed custody key the platform signs with on the organisation owner's verified request. The agent's key acts inside the mandate and cannot widen it, because the validator refuses every call the key makes to the account itself or to the validator.

## What a mandate holds [#what-a-mandate-holds]

An installation names three things: the agent's signing key, the address that administers the mandate, and the mandate itself. The mandate carries the limits.

| Part | What it bounds |
| --- | --- |
| `expiresAt` | The unix timestamp the mandate stops at. Zero never expires at the contract, and the platform requires a future time. |
| `periodSeconds` | The length of the spend window, counted from the block that wrote the mandate. The chain refuses zero, and the platform requires 60 or more seconds. |
| `nativeLimitPerTransaction` | The most native coin one user operation may carry. It defaults to zero, so a mandate that says nothing about native value allows none. |
| `nativeLimitPerPeriod` | The most native coin one window may carry. It defaults to zero as well. |
| `targets` | Each contract the agent may call, and per contract the function selectors it may use there. |
| `assets` | Each ERC-20 the mandate meters, with a ceiling for one user operation and a ceiling for one window. |

An installation with a zero signing key, a zero owner, a zero asset, a zero-length period, a repeated target or asset, or a mandate over the module's caps is refused, so a mandate the module could not enforce is never stored. The module meters at most 32 targets, 16 selectors per target and 16 assets, which bounds the gas a validation spends reading a mandate.

## Who grants it [#who-grants-it]

Two roles act on a mandate account. The account's owner is the agent's signing key, which authorises the account once, at creation. The mandate owner is the operations account's signing address, which administers the mandate for as long as the mandate lives. The platform creates the account and writes the mandate at the same moment.

- The agent's signing key, as the account's owner, signs an account creation authorisation. The signed digest binds the validator, the salt, a deadline and the installation data, so anyone may submit the authorisation before its deadline and nobody can change what it installs.
- The account factory refuses a validator that is not in its module registry. The deployment registers the mandate validator there, and a mandate account names it explicitly because the factory's default is the single-signer validator.
- The installation data carries the agent's signing key, the mandate owner and the mandate. The account installs the validator with that data.
- `setMandate`, `revoke` and `transferMandateOwner` accept the account's mandate owner only. Any other caller is refused with `MandateOwnerOnly`, the account itself included. The Console and the API call these functions for the organisation owner.

## What the agent may call [#what-the-agent-may-call]

A mandate account runs one call data shape, `execute(bytes32,bytes)` as a single call or a batch, and refuses the rest, which keeps the account's own administration out of the agent's reach.

- The call data that runs is `execute(bytes32 mode, bytes executionCalldata)` with the single or batch call type. Other call data is refused with `MandateCallDataRefused` before any spend is recorded. That includes `execute(address,uint256,bytes)`, which the account does not implement. So `installModule`, `uninstallModule` and the account's own setters never run from a user operation the agent signs.
- A call must name a target the mandate lists, with a selector that target's entry lists. Anything else is refused with `MandateTargetRefused`. A call carries at least a selector, so the agent cannot send plain native coin with empty call data.
- A call whose target is the account itself or the validator is refused with `MandateSelfCallRefused`, so the agent's key reaches neither the account's modules nor the mandate that confines it.
- A call type other than single or batch is refused with `MandateCallTypeRefused`. A delegate call falls under that refusal, so a user operation cannot make the account execute in another contract's storage.
- On a metered target only `transfer`, `transferFrom` and `approve` may be listed, because only those carry an amount the module can read. Any other selector on a metered target is refused at install with `MandateAssetSelectorRefused`.
- Listing one of those three on a target the mandate does not meter is refused at install with `MandateAssetUnmetered`. Any other selector on an unmetered target is allowed, and the tokens it moves are not counted, although native value is still metered. List only the calls the agent needs.

## What an amount may be [#what-an-amount-may-be]

An amount is counted against two ceilings: one per user operation and one per window.

- The module reads the amount from the call's own arguments, adds it to what the account spent in the window, and compares the operation's total with the per-operation ceiling. The calls in a batch share that ceiling, so splitting a payment across calls does not raise it. Exceeding the ceiling reverts with `MandateAssetPerTransactionExceeded` or `MandateNativePerTransactionExceeded`.
- The same total is compared with the window's ceiling, which reverts with `MandateAssetPerPeriodExceeded` or `MandateNativePerPeriodExceeded`.
- Native value is metered against its own pair of ceilings. A call that carries value on a mandate with zero native ceilings is refused.
- `approve` counts its full amount when it is called, whether or not the spender later uses it. Gas is not metered.
- Windows are fixed slices of `periodSeconds` counted from the block that wrote the mandate, and each window starts at zero. An agent can therefore spend a full period ceiling at the end of one window and again at the start of the next. Writing a new mandate opens a new count at once, so the previous mandate's counters never limit the new one.
- A refused operation records no spend. Spend is recorded during validation, so an operation that passes validation and then reverts during execution still counts against both ceilings.

## How one user operation is checked [#how-one-user-operation-is-checked]

The validator checks the mandate before it looks at the calls. It answers a refusal in one of two ways:

- A signature that does not recover to the mandate's signing key returns the ERC-4337 validation failure, `SIG_VALIDATION_FAILED`, as the standard requires, and the EntryPoint drops the operation.
- Every other refusal reverts validation with a named error, so the account never executes. The bundler sees the failure when it simulates the operation and does not submit it.

Two further rules apply:

- The account signs no ERC-1271 message: its `isValidSignatureWithSender` answers `0xffffffff` for every request. A signature check carries no target, selector or amount, so accepting one would move assets without passing the ceilings.
- The mandate is read for the account that submits the user operation, so a validation is always checked against the account that would execute.

## How it ends [#how-it-ends]

A mandate ends on its date or by a revocation, and administrative changes stop with it.

- **Date.** After `expiresAt` has passed, a user operation reverts with `MandateExpired`. A record of zero means the mandate never expires, which only a mandate written to the contract outside the platform can hold. Until a revocation, the mandate owner can set a new expiry with `setMandate`, which also writes the rest of the mandate again and starts a new count. The signing key is fixed at installation and `setMandate` does not change it.
- **Revocation.** The mandate owner calls `revoke`, and it takes effect in the block that mines it: the next user operation reverts with `MandateRevoked` before any call in it runs. A second revoke returns without changing the recorded timestamp.
- **Revocation is final.** After a revoke, `setMandate` and `transferMandateOwner` are refused with `MandateRevoked`, so a revoked mandate cannot be replaced or handed on. The revocation stays visible for the life of the account, and a new mandate goes on a new account.
- **No uninstall.** The account refuses to remove its last validator, and installing another validator needs a call the mandate refuses, so a mandate account keeps its validator. The mandate ends only by its date or by revocation.
- **Transfer of administration.** The current mandate owner moves administration to another address with `transferMandateOwner`. The zero address is refused with `MandateZeroAddress`.

## Reading a mandate [#reading-a-mandate]

Five views answer what an account's mandate allows, what it has spent and whether it is still live. They need no key and no particular caller. The agent's page in the Console and `GET /api/v2/agents/{agentId}` show the same facts.

| View | Answer |
| --- | --- |
| `mandateOf(account)` | The signing key, the mandate owner, the expiry, the revocation timestamp, the period length and both native ceilings. |
| `allowedTargets(account)` | Each target with the selectors its entry lists. |
| `meteredAssets(account)` | Each metered asset with its per-operation and per-window ceilings. |
| `spentThisPeriod(account, asset)` | What the account has spent of one asset in the current window. Pass the zero address for native value. It answers zero when the account records no period. |
| `isRevoked(account)` | Whether the mandate is revoked. |

## How it fits the platform [#how-it-fits-the-platform]

- The mandate validator is an ERC-7579 validator module, so the account factory accepts it like any other registered validator.
- The validator reports that no single key may manage the account directly. The agent's key therefore cannot reach the account's sensitive setters, even though the platform holds that key.
- The account's code comes from the platform directory, so the directory administrator's implementation upgrade is the one change that reaches a mandate account without passing through its validator.
- The account is the sender on chain, so roles, compliance checks and the audit trail name the account's address, not the agent's key.
- The hosted MCP server runs a tool call whose `execution` is `mandate` as the agent named in `agentId`, from the agent's account and inside its mandate, so every refusal on this page applies. When `agentId` names no agent of the organisation, the server refuses the call, executes nothing and prepares no draft. See [Drafts, inbox and mandates](https://docs.settlemint.com/docs/api-reference/cli/hosted-mcp).

## Related pages [#related-pages]

Read [Agents and mandates](https://docs.settlemint.com/docs/concepts/custody-and-signing/agent-mandates) for how an organisation owner creates agents, edits their mandates and uses the kill switches, [Smart Wallet](https://docs.settlemint.com/docs/concepts/custody-and-signing/smart-wallet) for the account a mandate is installed on, [User operations](https://docs.settlemint.com/docs/concepts/custody-and-signing/user-operations) for how a signed operation reaches the chain, and [Drafts, inbox and mandates](https://docs.settlemint.com/docs/api-reference/cli/hosted-mcp) for the app path that asks for a mandate.


# Agents and mandates

Source: https://docs.settlemint.com/docs/concepts/custody-and-signing/agent-mandates
An agent acts as its own participant under a mandate the chain enforces: allowed calls, spending ceilings, an expiry, and two kill switches the owner controls.

An agent is software that acts for an organisation on its own, without a person approving each step. A limit in the agent's own code, or in the scope of an API key, can be lifted by whoever holds that key. DALP puts the limit on chain, in a mandate: the list of calls the agent may make, how much of each asset it may move, and the date the grant ends. The organisation owner grants, changes and withdraws the mandate, and the agent's key cannot.

This page covers how the owner runs agents. [Agent mandate](https://docs.settlemint.com/docs/concepts/custody-and-signing/agent-mandate) covers what the mandate contract checks and the errors it reverts with.

## What an agent is [#what-an-agent-is]

An agent is a participant of kind `agent`, owned by one organisation. It has three parts:

- **A signer.** A managed custody key that the platform holds and signs the agent's user operations with. It is also the account's owner. The signature is a plain 65-byte ECDSA signature over the user operation hash.
- **An account.** A [Smart Wallet](https://docs.settlemint.com/docs/concepts/custody-and-signing/smart-wallet) created through the account factory, the contract that builds every account, with the mandate validator as its only validator. The mandate validator is the module that checks each user operation against the mandate.
- **A mandate owner.** The signing address of the organisation's operations account, a managed custody key the platform signs with when the organisation owner changes or revokes the mandate. Only this address can change or revoke the mandate.

The agent's id is its participant id, so the agent's activity is the participant activity that every [participant](https://docs.settlemint.com/docs/concepts/compliance-and-identity/participant) has. Everything the agent does is sent from its own account and signed by its own key. The platform never uses a person's key or API key to act for an agent.

Only the organisation owner can call the agent routes, reads included. A request from anyone else is refused with `DALP-199555`.

The DALP CLI and the local MCP server are a different path. They act as the person who signed in, with that person's role, as [using the CLI with AI agents](https://docs.settlemint.com/docs/api-reference/cli/ai-agents) describes. An agent that acts on its own does not use them.

## What a mandate holds [#what-a-mandate-holds]

A mandate is one record on the agent's account.

| Part | What it limits |
| --- | --- |
| Expiry | A unix timestamp after which every user operation is refused. It must lie in the future when the mandate is written. |
| Period | The length of the window, from 60 to 4,294,967,295 seconds, that the per-period ceilings count over. |
| Allowed targets | Up to 32 contracts, each with up to 16 function selectors the agent may call there. |
| Asset ceilings | Up to 16 ERC-20 assets, each with a ceiling per transaction and a ceiling per period. |
| Native ceilings | A ceiling per transaction and a ceiling per period for native value. A zero ceiling refuses every call that carries value. |

The period is a fixed number of seconds counted from the block that wrote the mandate. Each period starts a fresh count, and replacing a mandate starts a new count at once.

## What the chain refuses [#what-the-chain-refuses]

The mandate validator checks every user operation before the account executes it. A refusal reverts validation, so nothing runs. The platform's bundler finds this when it simulates the operation and does not submit it, so the refusal is recorded on the platform, not on chain. A signature that does not recover to the agent's key returns the standard ERC-4337 validation failure instead.

- **Calls the mandate does not list.** A call to a contract that is not on the list, or with a selector that contract's entry does not list, is refused.
- **Other account functions.** The only call data accepted is the account's `execute(bytes32,bytes)` entry point, as a single call or a batch. A delegate call is refused.
- **Calls to the account or the validator.** The agent's key cannot install or remove modules, change the account's settings, or change its own mandate.
- **Amounts over a ceiling.** The amount is read from the call itself. A metered asset can only be called with `transfer`, `transferFrom` or `approve`, and the per-transaction ceiling covers the whole user operation, so a batch cannot spend more than one call may. A user operation the validator refuses does not use up any of the period ceiling. Spend is recorded during validation, so one that passes validation and then reverts during execution still counts against both ceilings.
- **An expired or revoked mandate.** The user operation is refused before any call in it runs.

The platform runs the same check before it sends anything, and the chain enforces the mandate again, so a fault in the platform's check cannot let a call through. The ceilings count only the assets the mandate meters, so list only the calls the agent needs and meter every token it can move. The contract-level revert names are on [Agent mandate](https://docs.settlemint.com/docs/concepts/custody-and-signing/agent-mandate).

## Create an agent [#create-an-agent]

The owner creates an agent from Agents, under Organisation participants in the Console, or with `POST /api/v2/agents`. The request carries a name of 1 to 120 characters, the mandate and the owner's wallet verification, the confirmation the owner gives with their own wallet before a sensitive change.

The platform creates the agent's custody key, then its account through the account factory, with the mandate validator installed and the operations account's signing address as the mandate owner. The agent reads `provisioning` until that is done, then `active`. A set-up that cannot finish reads `failed`.

Creation is refused with `DALP-199554` when the mandate breaks one of the rules below, because the chain could not enforce it as written. The error's `data.rule` names the rule, and `data.target`, `data.asset` or `data.selector` names the entry that breaks it. Creation is also refused while the organisation kill switch is on, with `DALP-199552`.

| `data.rule` | What the mandate does | Entry named |
| --- | --- | --- |
| `expiry-not-future` | Its expiry is now or in the past. | None |
| `contract-repeated` | It lists the same contract twice. | `target` |
| `asset-repeated` | It gives the same asset two ceilings. | `asset` |
| `function-repeated` | It lists the same function twice on one contract. | `target`, `selector` |
| `asset-limit-missing` | It allows `transfer`, `transferFrom` or `approve` on a contract that has no ceiling. | `target`, `selector` |
| `asset-function-not-allowed` | It allows a function other than those three on an asset that has a ceiling. | `asset`, `selector` |

The Console checks the same rules while the owner edits the mandate. It names the offending entry by its short address and its function name or selector, and blocks submission until the entry is fixed. It also requires at least one contract and checks that addresses, selectors and ceilings are well formed. On a contract with an asset ceiling, the sheet offers only "Approve spending of an asset" and "Transfer an asset". If the server still refuses, for instance because the expiry passes while the sheet is open, the toast shows the same sentence built from `data.rule`.

### The starter mandate [#the-starter-mandate]

The Console fills the Create agent sheet from a starter mandate, which `GET /api/v2/agents/mandate-proposal` returns. The starter mandate allows:

- `transfer` of the asset each coupon or dividend payout on the organisation's own assets is paid in. The proposal names each asset with the payout feature it serves, `fixed-treasury-yield` for coupons or `dividend-yield` for dividends. A mandate cannot restrict recipients, so the ceilings are the only limit on where that asset goes. Assets beyond the mandate's 32 contracts or 16 metered assets are left out of the proposal.
- A per-day ceiling for each payout asset of the smaller of 1,000 whole units and 10% of the largest last payout in that asset. When no payout has run, the ceiling is 1,000 whole units. The native ceilings are zero.
- An expiry 30 days after the mandate is written.

The starter mandate is a draft. The owner reviews it, and can trim or extend the targets, selectors, per-asset ceilings and expiry before confirming with wallet verification. Reading the proposal creates nothing.

## Read an agent and its limits [#read-an-agent-and-its-limits]

Agents lists the organisation's agents with their name, status, account, creation time and revocation time. `GET /api/v2/agents` returns the same list.

An agent's page, and `GET /api/v2/agents/{agentId}`, shows the identity, account, signer and mandate owner. It also shows the mandate as the chain holds it: expiry, period, allowed targets and selectors, and ceilings. For each asset it shows what the agent has spent this period against the per-period ceiling. An entry without an asset is native value. The mandate is absent until it is on chain.

An agent has one of four statuses:

| Status | Meaning |
| --- | --- |
| `provisioning` | The key and account are being set up. |
| `active` | The mandate is on chain and the agent can act within it. |
| `revoked` | The mandate was revoked. The agent record shows when, and by which kill switch. |
| `failed` | The set-up did not finish. |

## Change a mandate [#change-a-mandate]

The owner replaces an active agent's whole mandate with Edit mandate in the Console, or with `PUT /api/v2/agents/{agentId}/mandate`. The request carries the new mandate and the owner's wallet verification. The replacement drops the previous allowed calls, asset rules and counters, and starts a new period count.

A replacement that breaks one of the mandate rules is refused with `DALP-199554`, the same way creation is. An agent that is not active is refused with `DALP-199553`, and any change while the organisation kill switch is on is refused with `DALP-199552`.

## Revoke one agent [#revoke-one-agent]

Revoke agent is the per-agent kill switch. The owner confirms in the Console, gives a reason of 1 to 500 characters and completes wallet verification. The API call is `POST /api/v2/agents/{agentId}/revocation`.

The platform marks the agent `revoked` at once and refuses its next action. It then submits the on-chain revocation, and once that transaction is mined the chain refuses every user operation before any call in it runs. The platform also tries to cancel the actions the agent queued in the last seven days. An action that already reached the network can still land, so read the agent's activity after a revoke. The agent reads `revoked`, with the revocation time and `agent-kill-switch` as the switch used. Other agents are not touched.

Revoking is final. A revoked mandate cannot be replaced or granted again on the same account, so the account keeps the evidence that the organisation withdrew the grant. To grant a new mandate, the owner creates a new agent. Any later mandate change on a revoked agent is refused with `DALP-199553`.

## Halt all agents [#halt-all-agents]

Halt all agents is the organisation kill switch. The owner gives a reason of 1 to 500 characters and completes wallet verification. `PUT /api/v2/agents/kill-switch` switches it on or off, and `GET /api/v2/agents/kill-switch` reads its state, the time of the last change and the reason.

Switching it on revokes every agent that is not already revoked, and a scheduled agent action that fires is refused with `organisation-halted`. Those agents read `revoked` with `organisation-kill-switch` as the switch used. While it is on, no agent can be created, changed or act, and creation is refused with `DALP-199552`.

Switching it off allows new agents. Agents that were already revoked stay revoked.

## How agent actions are checked and attributed [#how-agent-actions-are-checked-and-attributed]

Every feature that acts for an agent sends its calls through one execution step. A request names the agent, the calls, the origin and an idempotency key. The origin records the feature, a reference, whether the action was scheduled and, when a person asked, who.

The step has two forms. A check evaluates the request against the agent's state, the organisation kill switch and the mandate read from chain, and submits nothing. A run does the same check, writes an audit record attributed to the agent, and sends the calls as one user operation from the agent's account. A scheduled action runs the same way when it fires, so a revoked agent or a halted organisation refuses it. Scheduled payout funding and a [hosted MCP](https://docs.settlemint.com/docs/api-reference/cli/hosted-mcp) tool call with `execution` set to `mandate` both go through this step.

A refusal is `DALP-199551` with a reason. It is not retryable. Where the reason concerns a target, selector, asset, amount or limit, the refusal carries it.

| Reason | What stopped the action |
| --- | --- |
| `agent-not-active` | The agent is still being set up or its set-up failed. |
| `agent-revoked` | The agent's mandate was revoked. |
| `organisation-halted` | The organisation kill switch is on. |
| `mandate-missing` | No mandate is on chain for the agent. |
| `mandate-expired` | The mandate's expiry has passed. |
| `target-not-allowed` | The contract or selector is not on the mandate. |
| `self-call-refused` | The call targets the agent's account or the validator. |
| `asset-per-transaction-exceeded` | The amount is over the asset's per-transaction ceiling. |
| `asset-per-period-exceeded` | The amount is over what is left of the asset's period ceiling. |
| `native-per-transaction-exceeded` | The native value is over the per-transaction ceiling. |
| `native-per-period-exceeded` | The native value is over what is left of the period ceiling. |
| `amount-undecodable` | The amount cannot be read from the call data. |
| `chain-refused` | The chain refused a user operation the platform check allowed. |

A refusal means the mandate or a kill switch stopped the action by design, and the fix is a different action or a change by the owner.

## Errors [#errors]

| Code | When |
| --- | --- |
| `DALP-199551` | The mandate, the agent's state or a kill switch does not allow the action. The reason names which. |
| `DALP-199552` | The organisation kill switch is on. Ask the owner to switch it off. |
| `DALP-199553` | The agent is not active. Wait for set-up to finish, or create a new agent after a revoke. |
| `DALP-199554` | The mandate cannot be enforced as written. `data.rule` names the rule it breaks, and the entry that breaks it is named too. |
| `DALP-199555` | The caller is not the organisation owner. |

## Related pages [#related-pages]

Read [Agent mandate](https://docs.settlemint.com/docs/concepts/custody-and-signing/agent-mandate) for the contract checks and revert names, [Smart Wallet](https://docs.settlemint.com/docs/concepts/custody-and-signing/smart-wallet) for the account an agent runs on, [User operations](https://docs.settlemint.com/docs/concepts/custody-and-signing/user-operations) for how its signed instructions reach the chain, and [Participant](https://docs.settlemint.com/docs/concepts/compliance-and-identity/participant) for the record that carries the agent's id and activity.


# Legacy deposits

Source: https://docs.settlemint.com/docs/concepts/custody-and-signing/custodial-deposits
How retired custody-wallet deposit addresses, watches, journals and positions relate to current gateways, receipt holdings and records.

The custody-wallet watch and journal model described by older deposit integrations has been retired. Current deposits use a client’s custody gateway: coins enter the gateway and custody receipts represent them. This reference explains what changed for addresses, token acceptance, records, notifications and positions.

[Figure] From retired custody books to current gateway evidence. The old watch and journal workflows are retired. Current gateway records and receipt holdings provide current evidence. Cases and registrar reconciliation remain separate. Labels: Retired: custody watch and journal; Current: gateway records and receipts; Separate: Cases and registrar reconciliation.

[Figure] From retired custody books to current gateway evidence. The old watch and journal workflows are retired. Current gateway records and receipt holdings provide current evidence. Cases and registrar reconciliation remain separate. Labels: Retired: custody watch and journal; Current: gateway records and receipts; Separate: Cases and registrar reconciliation.

The custody watch and journal are retired. Current gateways use records and custody receipts. Cases and registrar reconciliation are separate operator controls.

## Where the deposit address comes from [#where-the-deposit-address-comes-from]

Older integrations selected a custody-account address and started a deposit watch. That model is retired. Current deposits go to the acting client’s gateway address on the selected network. A provider account address is not a gateway deposit address. Read [Wallet deposits and withdrawals](https://docs.settlemint.com/docs/console/my-assets/wallet-transfers) before sending coins.

## Why the address appears only after its watch exists [#why-the-address-appears-only-after-its-watch-exists]

The deposit-watch prerequisite and its start route are retired. Current deposit instructions depend on the client’s gateway being available in indexed records. Starting an old watch does not make an address valid for gateway deposits, and the former pre-watch credit rule no longer applies.

## Which tokens are accepted [#which-tokens-are-accepted]

The former watch and external-token acceptance settings are retired. Current acceptance comes from the gateway’s enabled coin and receipt configuration. A direct deposit of an unsupported coin fails. A plain transfer of an unsupported coin is handled through the gateway’s unsupported-transfer records and their permitted decisions. Check the [gateway’s supported coins](https://docs.settlemint.com/docs/concepts/custody-and-signing/custody-gateway) before transferring.

## How a transfer is credited exactly once [#how-a-transfer-is-credited-exactly-once]

The durable watch and journal-credit mechanism is retired. Current gateway processing uses its deposit records and available coins to protect receipt minting from repeated processing. Use the gateway record and its history to follow the result. The old journal identifier and notification-once contract do not describe that result.

### Wait for the indexed block [#wait-for-the-indexed-block]

The former indexed-watch step is retired. Current reads show indexed gateway deposit records and their stage history. Wait for the actual record to appear rather than assuming the old watch cursor, polling interval or journal compensation rule still applies.

### Confirm the wallet still belongs to the investor [#confirm-the-wallet-still-belongs-to-the-investor]

The former watch’s custody-reset credit rule is retired. Current gateways belong to a client identity on a network and follow the current wallet-recovery model. Use the gateway of the client you are acting as. Reset-bound withdrawal-destination proofs remain a separate control. They do not establish a deposit watch.

### Screen the transfer [#screen-the-transfer]

The former universal spendable-or-held screening rule is retired. Current gateway screening checks the transfer’s source and permits only the decisions available at its stage. Custody acceptance is a separate step. The provider alone does not determine that every incoming deposit must wait for an operator.

### Credit the spendable or the held balance [#credit-the-spendable-or-the-held-balance]

The former spendable and held journal credits are retired. A current deposit mints custody receipts. Quarantine, mint refusal and awaiting custody describe different stages, with different permitted actions. Receipts held while custody acceptance is pending become usable through that acceptance flow. These stages are not renamed journal balances.

### Reversal after a chain reorganisation or a return [#reversal-after-a-chain-reorganisation-or-a-return]

The former journal compensation and webhook-revision promises are retired. A gateway return is handled through its actual deposit record and permitted transitions. A chain reorganisation does not, by itself, promise an automatic receipt rollback, journal compensation or replacement retraction notification.

### Funds that leave a deposit wallet [#funds-that-leave-a-deposit-wallet]

The old operator-movement attribution rule is retired. An unexplained debit must be investigated using actual transactions, gateway records and escrow or reserve evidence. There is no replacement movement book that guarantees an investor’s former journal position remains unchanged.

## Deposit lifecycle webhook events [#deposit-lifecycle-webhook-events]

The former custody deposit lifecycle events are retired. Their old payload and revision rules are not current subscription instructions. Read current gateway records and history for deposit stages, and consult the [webhook catalogue](https://docs.settlemint.com/docs/api-reference/webhooks) for events that remain available. There is no automatic one-to-one replacement for each retired event.

## Positions: spendable and held [#positions-spendable-and-held]

The custody-journal spendable and held position reads are retired. Current receipt holdings and gateway records answer holdings and stage questions. They do not reproduce the old position schema, pagination or attribution of funds to custodial locations.

## Operator movements [#operator-movements]

The old operator-movements read and its custody movement event are retired. Current transaction and gateway record evidence can help an investigation, but it is not a replacement report of custodial sweeps or reallocations.

## The custody journal is the source [#the-custody-journal-is-the-source]

The custody-operations journal and its daily reconciliation are retired. Current custody evidence consists of receipts, gateway records and escrow or reserve readings. The [registrar break register and reserve check](https://docs.settlemint.com/docs/concepts/records-and-evidence/reconciliation) remain separate controls. Retained platform ledger data does not recreate the former custody journal.


# Custodian watch

Source: https://docs.settlemint.com/docs/concepts/custody-and-signing/custodian-watch
How a custodian learns of privileged actions on tokens it holds, and why a factory upgrade of those tokens waits for the custodian's notice.

A custodian holds tokens that another organisation issued and administers. The issuer's wallets can freeze, force-transfer, mint, burn, pause, recover and change the roles on those tokens, and the issuer can upgrade the token factory that deployed them. The custodian watch tells a custodian when that happens, and holds a factory upgrade back until the custodian has had notice.

## What the watch covers [#what-the-watch-covers]

An organisation subscribes to the watch. The watch then covers each token the organisation custodies: a token that one of its watched custody addresses held at the start of the watch window or received during it. The window is the one the custody watch list already keeps for each address.

The watch looks at these actions, each on chain:

| Action | What it does |
| --- | --- |
| Forced transfer | Moves tokens out of a holder's wallet |
| Recovery | Moves a lost wallet's balance to its replacement |
| Freeze and unfreeze | Locks or releases an address or part of a balance |
| Mint and burn | Changes the supply |
| Pause and unpause | Halts or resumes transfers of the token |
| Role grant and revoke | Changes who may use the actions above |
| Implementation upgrade | Replaces the code the token runs, recorded once by the factory |

An action counts only when its on-chain sender is outside the custodian's organisation. The organisation's own wallets are the wallets of its participants, the controller of a participant's smart wallet, and its custody watch addresses. A freeze that the custodian signs itself raises nothing.

## What a custodian receives [#what-a-custodian-receives]

Each action raises one operations case for the custodian, of the kind **Privileged action on a custodied token**. The case names the action, the token, the sender outside the organisation, the affected wallet and amount where the action has them, and the transaction. A forced transfer, a recovery, a burn and an implementation upgrade open as critical. The other actions open as warnings.

The case reaches the custodian in two places. The organisation's webhook endpoints receive `operations.case.opened`, as [the event catalogue](https://docs.settlemint.com/docs/api-reference/webhooks/events#operations) describes, and the case appears in the **Cases** tab of Custody under Business operations. The platform raises a case once for each log entry on chain, so a retry never repeats it.

The watch starts at the head of the chain when an organisation subscribes. It reports what happens from that point and does not report earlier history. The platform checks for new actions every 15 seconds. If a check fails, the next one picks up from the same place.

## Notice before an upgrade [#notice-before-an-upgrade]

An upgrade of a token factory changes every token the factory deployed. When custodians hold tokens of a factory, the system upgrade refuses to touch that factory until an upgrade was scheduled for it and its notice has ended.

- **Subscribe with a notice period.** Each custodian sets the business days of notice it asks for, from 0 to 60. The default is 5. The days count Monday to Friday in UTC and keep the time of day. Public holidays are not modelled.
- **Schedule the upgrade.** The system's organisation records the factory to upgrade. Every subscribed custodian holding tokens of that factory receives a case of the kind "Upgrade scheduled for custodied tokens" at once. The upgrade may first run when the longest notice among those custodians ends.
- **Run the upgrade.** System updates upgrades the factory only after that time. Before it, the run stops and states when the upgrade may run. When no custodian holds tokens of the factory, the upgrade needs no schedule.
- **Cancel.** The organisation can cancel an upgrade that has not run. The record stays as cancelled and the custodians' cases are resolved.

A custodian that raises its notice period after an upgrade was scheduled can lengthen the wait: the run checks the notice again when it starts.

### Emergency upgrades [#emergency-upgrades]

An emergency upgrade bypasses the notice. It needs a reason, it may run at once, and it still notifies every custodian at once, with a critical case. Use it for an upgrade that cannot wait, such as a fix for an exposed key.

## Who can do what [#who-can-do-what]

The organisation owner or a platform administrator subscribes, changes the notice period, unsubscribes, schedules an upgrade and cancels one. Each of these writes is a system administration change, so an organisation whose approval policy holds that class sends it for a second person's approval first. Reading the subscription or the list of scheduled upgrades needs a reporting role on the system.

The routes are in the Platform API under `reporting.custodianWatch`: `PUT /api/v2/reporting/custodian-watch` to subscribe, `POST /api/v2/reporting/custodian-watch/scheduled-upgrades` to schedule an upgrade, and the matching reads and deletes. The [API reference](https://docs.settlemint.com/docs/api-reference) lists each with its schema.


# Custody Approval

Source: https://docs.settlemint.com/docs/concepts/custody-and-signing/custody-approval
Custody Approval requires a decision from your own approvers before a key signs, enforced by the key holder and by the platform's wallet checker.



[Figure] The approval sits between the payload and the signature. A maker submits an instruction, and the platform prepares one exact payload: the sender, the destination, the call and its amount, and the sequence number that orders it. The asset's compliance rules are simulated before anything is signed. Custody approval comes next: the checkers named in the key holder's policy decide whether this payload may be signed. Only then does the key holder release a signature, and that signature covers this payload and nothing else, before the transaction is broadcast. Labels: The prepared payload; sender and destination; the call and its amount; the sequence number; Prepared once, before any; key is asked to sign.; Maker submits an instruction; prepares the payload; Compliance rules simulated; Custody approval; the named checkers authorise this payload; Key holder releases one signature; Transaction broadcast; The approval and the signature both; cover this payload, and nothing else.

The approval decides on one prepared payload, and the signature that follows covers that payload and nothing else.

One approval covers one prepared payload. Where the platform broadcasts, it compares the signed bytes with the prepared request on six fields and stops the transaction on any difference. Where the provider broadcasts, the provider's own policy is the only check.

With a custody provider, a hardware module or a wallet contract, the key holder enforces the decision and does not sign what the policy has not cleared. The platform enforces the wallet checker, and the platform key store has no external policy.

A waiting transaction is a visible state that ends approved, declined, expired or cancelled.

## Why a signature needs a decision first [#why-a-signature-needs-a-decision-first]

Custody Approval lets you require a decision from your own named approvers before a key signs a payload. That decision belongs to people your organisation chose, under a policy your organisation set. The decision comes from the approval policy held by the custody provider, the hardware module or the wallet contract, plus the platform's own wallet checker. The Approvals settings in General are [maker-checker](https://docs.settlemint.com/docs/concepts/custody-and-signing/maker-checker), a separate control.

Banks already run this maker-checker discipline, the rule that the person who prepares a payment cannot be the one who authorises it, over payment instructions. Custody Approval moves the same discipline onto the step where a private key turns an instruction into an irreversible on-chain transfer. A conventional payment can sometimes be reversed after it leaves the bank. A signed on-chain transfer cannot: once it is broadcast, nothing undoes it.

The platform sits on the requesting side. It resolves the sender, builds the call, and asks the key holder to sign. The approval policy lives with the party that holds the key: a custody provider, a hardware security module in your own data centre, or the wallet contract itself on chain. With an external custody provider or a hardware security module, the platform never holds the key material and cannot obtain a signature that the policy has not cleared. With the platform key store, the platform holds the key and signs itself, so no external policy applies.

The record shows who prepared the instruction, who cleared it and when.

## What an approval authorises and what it does not [#what-an-approval-authorises-and-what-it-does-not]

An approval policy requires a decision beyond the instruction itself. A request subject to that policy waits for the configured approvers before signing can proceed. Role permissions still govern who may submit the request.

The approval is bounded in two ways. It authorises one prepared payload and grants no ongoing permission to move assets. It is also not a settlement guarantee: the signed transaction still has to reach the chain and still has to satisfy the asset's own transfer restrictions, a separate control described under Transfer-Path Compliance.

## Working a pending approval [#working-a-pending-approval]

A transaction that meets an approval rule stops in a pending-approval state and moves nowhere until someone decides. It appears in [Actions](https://docs.settlemint.com/docs/console/essentials/actions) for the participant whose wallet sent it, the investor or organisation account, with the operation it is waiting to perform. The platform records the pending state. A multi-signature approval can already contain signatures while it waits for the remaining weight.

Where the decision is taken depends on the wallet. On a platform multi-signature wallet, the approval is a record you work inside the platform. It shows the weight required, the weight collected and every signature so far, and each signer co-signs from the pending item. Each signer holds a weight, a share of signing authority counted toward the wallet's threshold. On a wallet held at a custody provider or inside a hardware security module, the platform shows the transaction as waiting, with the approvals the provider has counted against the number it needs when the provider reports them, and the decision belongs to the provider's own console, approval app, or hardware quorum ceremony.

The platform adds one approval of its own, the wallet checker. The owner of a key wallet that the platform signs for names one other member of the organisation as the wallet's checker. Every transaction from that wallet then waits in the checker's Actions list until the checker approves or rejects it there. A transaction the checker starts from that wallet fails at once, because the checker cannot approve their own transaction. A rejection fails the transaction, and a checker who does not decide within the approval window lets it expire. A wallet checker is optional on every wallet. The wallet's owner names, replaces or removes the checker alone, and removing the checker cancels every transaction waiting for that checker. Treat the checker as a control the owner can switch off, and pair it with a provider policy where the owner must not be able to remove it. If the checker leaves the organisation, the wallet refuses every transaction until its owner removes the checker or names a new one, and an account that is still a wallet's checker cannot be deleted.

Your approvers do not read raw transaction bytes. Where the provider supports it, the approval screen names the operation and its arguments, decoded from the same prepared call the approver is authorising. It therefore cannot describe something the payload does not do, and an undecodable call falls back to the contract and the function selector.

Do not resubmit the instruction while it waits. The platform is holding that wallet's next sequence number for the payload under review, so a second submission could queue a second movement of assets instead of hurrying the first. Follow the original operation's status or let the platform's own recovery resume it. Repeat an API request only when its route documents replay safety.

A pending approval ends in one of four ways:

- **Approved**: the key holder releases the signature.
- **Declined**: the platform records a failure with a rejected-signature reason.
- **Expired**: nobody decides in time, and the platform records a failure with an expired-approval reason.
- **Cancelled**: the platform withdraws the request at the provider first, and the transaction moves to cancelled only after the provider confirms the withdrawal.

When the provider cannot withdraw requests, does not confirm the withdrawal, or the request has already ended, the cancel is refused with `409` `TRANSACTION_CANCEL_CUSTODY_PARKED`, code DALP-14035, and the approval stays pending until an approver decides in the provider's own console or the deadline passes. A decline or a lapse is a final outcome. Nothing reopens a declined, expired, or cancelled approval, so prepare and submit a fresh instruction if the movement is still needed.

Cancelling a transaction that was already broadcast works differently. The platform signs a zero-value replacement at the same sequence number. A cancel cannot wait for an approver. When a policy holds that replacement for approval, the platform withdraws the held request, and the cancel answers with the same `TRANSACTION_CANCEL_CUSTODY_PARKED` refusal. Such a cancel succeeds only when the provider's policy lets the replacement sign without approval. Each new attempt files its own request. When the provider cannot withdraw requests, the approver rejects the held replacement in the provider's approval console.

[Figure] How a pending approval ends. A prepared transaction that meets no approval rule goes straight to signing. One that meets a policy enters pending approval instead. An approved transaction is signed and broadcast, confirmed, and completed. The other three exits never reach broadcast: declined by an approver or an expired approval window ends as failed, and a withdrawal before any decision ends as cancelled. Labels: Prepared; meets no approval; rule: signs directly; the policy demands a decision; Pending approval; awaiting the named checkers; approved; Signed and broadcast; Confirming; Completed; Never broadcast; Failed; declined by an approver,; or the window expired; Cancelled; withdrawn before a decision.

A prepared transaction either signs directly or waits for a decision, and approved work continues to broadcast while a decline, lapse or withdrawal ends it.

Allow for the wait in your design. Another write from the same wallet cannot take that wallet's sequence number while an approval is pending, so it waits behind the held transaction. A slow approver therefore delays that wallet's other work. Route routine high-volume work and approval-bearing work through different wallets when both have to keep moving.

## What this approval covers [#what-this-approval-covers]

Custody Approval is a gate on signature release, and the platform sits on the requesting side of it. The platform resolves the sender, builds the call, reserves the sequence number, simulates the asset's compliance rules, and then asks the key holder to sign. An external custody policy decides provider-side approvals. A weighted wallet enforces its own signature threshold. Platform-managed signing has no external approval policy, as [Does the platform hold the keys?](#does-the-platform-hold-the-keys) explains.

Two approval planes exist, and neither substitutes for the other. The custody-provider plane gates one external signature: the provider's policy engine or the hardware module's quorum holds the key operation until a rule, an approver, or a quorum of key custodians clears it. On the multi-signature wallet plane the approval is the signature, because several signers each contribute weight to one operation. The threshold is enforced by the wallet contract itself, for operations validated by the weighted validator. It validates the collected weight when the operation reaches the chain and rejects an operation whose weight falls short, so the platform holding submission is a convenience and the wallet contract is the control. Check the wallet's other installed validators, as [Maker-checker](https://docs.settlemint.com/docs/concepts/custody-and-signing/maker-checker) explains. The contract counts weight per key, not per person. In `managed` mode the platform signs for each custodied signer the caller controls, so check that no one person controls signers whose weights reach the threshold.

A provider hold does not clear through the wallet's approval calls, and a wallet threshold does not stand in for provider policy. Use that split to place a new rule. One that is naturally a threshold over the platform's own signers belongs on the wallet plane, where the contract enforces it on chain. One that needs a named individual, an external amount or destination check, or a hardware quorum belongs on the provider plane, where its policy engine or the module enforces it.

The split, plane by plane:

| What differs | Custody provider or hardware module | Multi-signature wallet |
| --- | --- | --- |
| What is approved | Release of one signature over the prepared payload. | Each signer's own signature over the operation. |
| Who enforces | The provider's policy engine or the module's quorum. | The wallet contract's validation rules, on chain. |
| Where the decision is taken | The provider console, approval app, or hardware ceremony. | The platform, as a co-signing step in the work queue. |
| Rule shape | Amount limits, destination rules, named approvers, a quorum of key custodians. | Per-signer weights against a threshold. |
| Where the evidence lives | The provider's or module's own audit log. | The approval record and the chain. |
| Key material | Never leaves the provider or the module. | Each signer holds their own key. |

An approval binds to one payload, and the platform checks that binding instead of trusting it. Where the provider signs but the platform broadcasts, the platform parses the returned signed bytes and compares them against the prepared request. A difference in any one of six fields stops the transaction before broadcast, and the platform releases that wallet's reserved sequence number the same way it would for a declined or expired approval. An approval is permission to sign one specific payload, and the platform broadcasts only bytes that match it. Where the provider broadcasts the transaction itself, the platform compares nothing before it goes out.

The six fields that must match:

- Sequence number
- Destination address
- Call data
- Chain identifier
- Native value
- The recovered signer address

The platform trusts no unsigned provider notification. An inbound message about an approval counts only when it verifies. Fireblocks and Utila messages verify against the provider's published key, and DFNS and Ripple Custody messages against an HMAC-SHA256 secret the operator configures. The platform checks that before it reads the message. Ripple Custody messages without a signature count only when a non-production deployment explicitly allows them. A verified message ends the wait at once. Without one, the platform keeps polling the provider until the approvers decide or the deadline passes.

The sequence-number reservation makes the payload binding hold over human time. The prepared payload fixes a specific next sequence number for the sending wallet, and an approval can take hours. The platform keeps that slot reserved throughout, so a concurrent write waits instead of consuming the number and invalidating the approved payload. A decline, a lapse, or a cancellation releases the reservation.

## The integration contract [#the-integration-contract]

In the v2 API, Custody Approval appears in two shapes that match the two control planes. A provider-side hold is a state that a write can enter. A multi-signature approval is an object that you create, read, and sign until its policy reaches a decision.

A write that meets a provider policy does not fail. It stays in flight and reports a pending-approval state whose reason names a pending custody approval. Treat that as a wait, and let recovery resume the work when the provider clears it. The queue deduplicates a matching submission under the same key, but the API route may do work before queue admission. A rule that blocks outright is different: it fails the transaction outright, and no approver decision reopens it. Fix what the rule objects to, such as the amount or the destination, and submit a new instruction. Retrying the same one fails again against the same rule.

A multi-signature approval is a record of its own on the wallet. You create one at `POST /api/v2/custody/wallets/{walletId}/approvals` with the prepared user operation the wallet is to execute, including its operation hash. The wallet must hold a positive multisig threshold. A wallet without one refuses creation with `409` `MULTISIG_APPROVAL_CONFLICT`. The platform recomputes the operation hash from the wallet, the network and the prepared operation, and refuses a preview addressed to another wallet or network, or one whose hash does not match, with the same `409`. It stores that preview, which fixes the sequence number, the gas limits, the fees and the call data, opens the approval with no weight collected, and mails the wallet's other signers. Every signature is taken over the hash of that stored preview, so no signer is asked to sign terms that drifted.

An approval opened through this route is not tied to a queued transaction, so it does not execute on its own. A write that a multisig wallet starts through the platform opens its approval together with a queued transaction. The signature that brings the collected weight to the threshold resumes that transaction. `POST /api/v2/custody/approvals/{approvalId}/submissions` resumes it explicitly once the threshold is met, for a transaction that did not resume. Submitting an approval below the threshold, past its deadline or without a queued transaction is refused with `409` `MULTISIG_APPROVAL_CONFLICT`.

A co-signer signs at `POST /api/v2/custody/approvals/{approvalId}/signatures` in one of two modes. In `external` mode the signer sends its address, its signature and the operation hash, and the platform verifies the signature against the stored preview. In `managed` mode the signer names its address and the platform signs with that signer's custodied key. Either way the signer must be an active signer on the wallet that the caller controls, and its weight is added once. A second signature from the same signer, a signature over another hash, an approval that is no longer collecting, and an approval whose window has closed are each refused with `409` `MULTISIG_APPROVAL_CONFLICT`. A signer whose key sits under a wallet checker policy cannot sign in `external` mode. In `managed` mode the platform asks the checker first and signs once the checker approves.

Reading the record at `GET /api/v2/custody/approvals/{approvalId}` gives you the required weight, the weight collected, the stored preview, the deadline, the signers still waiting on a checker, and every collected signature with its signer and the weight it added.

[Figure] Collecting co-signatures on a multi-signature approval. Three participants appear: the maker, the platform, and the signers. The maker creates an approval, and the platform returns it as pending, carrying the weight required and the weight collected so far. Each signer then signs the approval, and the platform returns the new collected weight. That loop repeats until the collected weight meets the threshold, or ends first without ever submitting: the deadline passes, or the transaction behind the approval is cancelled. Once the threshold is met, the platform submits the operation, and the maker reads the status: submitted first, then landed or rejected. Labels: Maker; Platform; Signer; create an approval; pending: weight required,; weight collected; Until the threshold is met; sign the approval; the new collected weight; threshold met: submit; submitted, then landed or rejected; ends first, without; ever submitting; Never submitted; Expired; before the threshold was met; Rejected; its transaction was cancelled.

Create the approval, collect co-signatures until the weight meets the threshold, then read the terminal status.

Read the approval's `status` instead of inferring one. It reads `pending` while more weight is needed and `threshold-reached` once the collected weight meets the threshold. It reads `submitted` when the operation goes out and `landed` when the operation executes. An approval that runs past its deadline reads `expired`. An approval whose submission or execution fails, or whose transaction is cancelled before it goes out, reads `rejected`. `submitted` does not mean executed: the operation is still on its way, and its own outcome is recorded as a [Settlement Verdict](https://docs.settlemint.com/docs/concepts/settlement/settlement-verdict). A sign call against an approval that no longer collects signatures fails instead of reopening it, so a stale client cannot revive an approval that has expired or been rejected.

A signer whose key carries a checker policy does not co-sign alone. The platform holds that signer's co-signature until the named checker approves it within the approval's own deadline, and the other signers see which signer is waiting for a checker.

## Controls and evidence [#controls-and-evidence]

For a control function, Custody Approval is a preventive control at the point of signature release: an unapproved payload is never signed, so there is no unauthorised transaction to detect or reverse. With an external provider, a hardware module or a wallet contract, the party holding the key enforces the decision before signing, so the platform is not the single point of trust for this control.

Keep it separate from transfer compliance, because the two answer different questions and both must pass. Transfer compliance decides whether an address, a claim, or a movement is permitted under the asset's own rules, and it is enforced on chain when the transfer executes. Custody Approval decides whether the key may sign the prepared transaction at all. An approval creates no eligibility claim and overrides no transfer restriction: an approved transfer that fails the asset's rules still reverts on chain.

Evidence is split by design, and an audit needs both pieces. The platform holds the request record: what was requested, by whom, when it entered pending approval, how long it waited, the terminal outcome with its reason, and the resulting on-chain transaction. The custody provider or hardware module holds the other piece: which approvers the policy named, who decided, and when. On the multi-signature wallet plane both pieces sit on the platform and on the chain, because the approval record names each signer, their weight, and their signing time, and the wallet contract enforced the threshold in public.

An external provider's policy lives at the provider, so no platform role can widen it, and on the provider and hardware paths the key operation waits for the key holder's answer. Three things sit inside the platform:

- the wallet checker, which the wallet's owner can remove
- the platform key store, where the platform signs itself
- a Smart Wallet's code, which follows the implementation the platform directory names, and which the directory administrator can replace for every account.

What happens when no rule matches is therefore decided by the provider's default, not by the platform. Configure a catch-all deny or manual-review rule, so nothing is left to that default. For a Fireblocks workspace, [Fireblocks policy for DALP vaults](https://docs.settlemint.com/docs/deployment/fireblocks-policy) lists the rules each vault needs in each signing mode. For a Ripple Custody domain, [Ripple policy for DALP intents](https://docs.settlemint.com/docs/deployment/ripple-policy) lists the properties that a policy can match and the operation names it must use.

## Frequently asked questions [#frequently-asked-questions]

### Which happens first, the compliance check or the approval?

The compliance check. The platform simulates the asset's transfer rules against the prepared transaction before it asks anyone to approve, so an operation the asset would reject never reaches your approvers. Those rules then run again for real when the transaction executes on chain, which is what catches an eligibility change that landed while the approval was pending.

### Who are the approvers?

The approvers are whoever your own policy names. On a custody provider, the approvers are the people and rules configured in that provider's own policy engine: named individuals, amount thresholds, destination restrictions, or a required quorum. On a hardware security module, they are the key custodians who must jointly activate the partition. On a platform multi-signature wallet, they are the signers on that wallet, each carrying a weight you set. On a key wallet with a wallet checker, the approver is the one member of your organisation that the wallet's owner named. The platform appoints approvers in none of these models.

### Can both approval planes run at once?

Yes. Clearing one plane never clears the other, because each is a separate authority: the wallet contract enforces its threshold on chain regardless of what the provider decided, and the provider's policy engine runs regardless of the wallet's collected signer weight. A movement that needs both keeps waiting until each has cleared on its own timeline, so the slower plane sets the pace for the whole request.

### Does the platform hold the keys?

Only if you choose that model. With a custody provider or a hardware security module, the key material never leaves the provider or the module. The platform holds provider configuration and workflow state. The platform key store keeps keys in the deployment's own secret store, for development and for deployments that accept platform-managed key material. That path has no external custody policy engine. Select it only when platform-managed key storage meets your deployment's signing requirements.

### Can a platform administrator bypass the approval?

Not at an external custody provider or a hardware module, because the key operation waits for their policy. A weighted Smart Wallet checks its installed validators on chain while its code is unchanged, and the platform directory administrator can replace that code for every account. On the platform key store there is no external policy, so platform approvals and the wallet checker are the only gates, and a wallet's owner can remove its checker alone. Check which validators are installed on each wallet and who can change them.

### How long can an approval stay open?

A request that waits at a custody provider or in a hardware security module has one deadline. The platform sets it once, when the request starts to wait, and records it with the request together with the limit that set it. The earliest of these limits applies:

- The approval window: 24 hours by default, set by `CUSTODY_APPROVAL_DEADLINE_MS`. A deployment can make it shorter. The platform does not start with a value above 24 hours.
- The gas sponsorship ticket, for a [Smart Wallet](https://docs.settlemint.com/docs/concepts/custody-and-signing/smart-wallet) operation whose gas is sponsored: the approval must finish 60 seconds before the ticket expires. The ticket lasts 300 seconds by default, so an approver has about four minutes. To give approvers more time, raise `PAYMASTER_TICKET_DEADLINE_SECONDS`, up to 3600 seconds.
- The signature's own deadline, for typed data that expires by itself.
- The quorum window of a hardware security module that collects its approvals as a quorum.
- The custody provider's own expiry of the request, where the provider reports one: the expiry the platform sets on a Ripple Custody intent, the expiry of a DFNS approval, and the expiry Fireblocks sets on a transaction that waits for approval.

A restart does not move the deadline, because the platform reads the recorded deadline and not the current configuration. When the deadline passes with no decision, the platform withdraws the request at the custody provider and records the approval as expired. A hardware security module keeps no request of its own, so nothing stays open there. Some providers cannot withdraw a request. For those, the transaction stays pending, the platform says the request is still open at the provider with the provider's reference, and it keeps reading the provider for up to `CUSTODY_OPEN_PAST_DEADLINE_MS` after the deadline (seven days by default, at most 30). A decision at the provider ends the transaction. If none comes, the transaction then fails and names the open request. An operator can reject the request in the provider's own console.

When the provider ends the request at its own expiry first, the platform records the approval as expired.

A platform multi-signature approval and a wallet checker decision expire on the same approval window, counted from when the approval opens. A co-signature that waits for a signer's checker expires with the multi-signature approval it belongs to. Whichever plane is waiting, the wait is durable, so a restart on either side does not lose a pending approval or the signatures already collected toward it.

## Related concepts [#related-concepts]

- [Maker-Checker](https://docs.settlemint.com/docs/concepts/custody-and-signing/maker-checker): The pattern where one party proposes a change and a different party approves it before anything takes effect. [Issuing an asset with an external custody provider](https://docs.settlemint.com/docs/concepts/custody-and-signing/maker-checker#issuing-an-asset-with-an-external-custody-provider) shows where the platform approval and the provider's policy each sit in one issuance.
- [Asset Lifecycle](https://docs.settlemint.com/docs/concepts/issuing-and-markets/asset-lifecycle): The working life of a regulated tokenised instrument. Custody Approval gates a signature at any stage where a key signs.
- [Custody Provider](https://docs.settlemint.com/docs/concepts/custody-and-signing/custody-provider): The external signing service whose policy engine gates one signature on the custody-provider plane.
- [Smart Wallet](https://docs.settlemint.com/docs/concepts/custody-and-signing/smart-wallet): The account whose own contract enforces the collected signing weight on the multi-signature wallet plane.
- [Settlement Verdict](https://docs.settlemint.com/docs/concepts/settlement/settlement-verdict): The recorded end state of an on-chain operation submitted to the platform (completed, failed, dead letter, or cancelled), and the only signal from which success may be reported.
- [Transfer-Path Compliance](https://docs.settlemint.com/docs/concepts/compliance-and-identity/transfer-path-compliance): The enforcement of a regulated token's rules inside the on-chain transfer itself, so a movement that fails any rule reverts and never settles.


# Legacy transfers

Source: https://docs.settlemint.com/docs/concepts/custody-and-signing/custody-deposits-and-withdrawals
What changed from custody-wallet deposits and withdrawals to gateways, and which destination proofs, fee rules and approvals remain.

The former custody-wallet deposit and withdrawal operations have been retired. Current wallet deposits and withdrawals use a client’s custody gateway and its custody receipts. Destination control proofs remain available, but proving an address does not make it an approved gateway payout address.

[Figure] From retired custody books to current gateway evidence. The old watch and journal workflows are retired. Current gateway records and receipt holdings provide current evidence. Cases and registrar reconciliation remain separate. Labels: Retired: custody watch and journal; Current: gateway records and receipts; Separate: Cases and registrar reconciliation.

[Figure] From retired custody books to current gateway evidence. The old watch and journal workflows are retired. Current gateway records and receipt holdings provide current evidence. Cases and registrar reconciliation remain separate. Labels: Retired: custody watch and journal; Current: gateway records and receipts; Separate: Cases and registrar reconciliation.

The custody watch and journal are retired. Current gateways use records and custody receipts. Cases and registrar reconciliation are separate operator controls.

## A deposit and a withdrawal are separate records [#a-deposit-and-a-withdrawal-are-separate-records]

The former custody-wallet deposit and withdrawal records are retired. Current gateway deposits and withdrawal requests have stable identifiers and stage histories. Use the identifiers returned by the current records API. The old deposit identifier formula and spendable or held postings no longer describe gateway evidence. [Custodial deposits and positions](https://docs.settlemint.com/docs/concepts/custody-and-signing/custodial-deposits) maps the retired addresses, watches, journals and positions to their current gateway equivalents.

## How a deposit becomes spendable [#how-a-deposit-becomes-spendable]

The old journal deposit state table is retired. Current deposits mint custody receipts, with stage-specific screening and acceptance. Receipts awaiting custody acceptance may remain held until that flow completes. Read the current record rather than applying a provider-wide rule to every deposit.

## An operator decides a held deposit [#an-operator-decides-a-held-deposit]

The old held-deposit review and transition routes are retired. An operator now reads the gateway deposit and uses only the decisions allowed by its stage and signer roles. Where the add-on requires checker approval, that approval remains necessary. There is no generic release, return or refusal action that applies to every hold.

## A destination is proved, then cleared [#a-destination-is-proved-then-cleared]

Address-control proofs and operator review remain available even though the legacy withdrawal workflow is retired. Propose a destination, sign its issued message, submit the proof, and wait for the required operator review. The operator can clear or refuse it. The participant can revoke it. A cleared destination proves and reviews address control, but is not automatically an approved gateway payout address. See [Withdrawal destination review](https://docs.settlemint.com/docs/console/organisation-settings/custody-reconciliation) and [Wallet deposits and withdrawals](https://docs.settlemint.com/docs/console/my-assets/wallet-transfers).

## A clearance belongs to one custody reset [#a-clearance-belongs-to-one-custody-reset]

The retained destination proof binds the organisation, participant, network, address, custody reset epoch and expiry. A proof that no longer matches that binding is refused. This protects the current proof list. It does not restart a retired deposit watch or authorise a new gateway payout address.

## Requesting a withdrawal holds the amount and the fees [#requesting-a-withdrawal-holds-the-amount-and-the-fees]

The old journal withdrawal request, limits and retry-key contract are retired. A current gateway request locks custody receipts under its current terms. Review the gateway’s amount and fee quote before submitting. The former held-balance errors and journal policy limits are not gateway request rules.

## A withdrawal waits out its cancel window [#a-withdrawal-waits-out-its-cancel-window]

The former journal cancellation window and transition route are retired. Current cancellation depends on the gateway request’s stage and configured cancellation setting. The current return flow releases the receipts when permitted. Do not assume every request waits before payment or can always be cancelled.

## A payout settles only on the exact transfer [#a-payout-settles-only-on-the-exact-transfer]

The former durable payout lifecycle is retired. In the current gateway, claiming a withdrawal pays coins and burns receipts atomically. Follow the actual request stage and gateway record history to distinguish a pending request, a claimable payment and a settled withdrawal.

## A payout the platform cannot prove is parked [#a-payout-the-platform-cannot-prove-is-parked]

The old parked-payout resolver is retired. Current gateway requests use their own stages, evidence and role-gated claim or return decisions. An uncertain old payout does not map automatically to a gateway stage, and there is no replacement generic consume-or-release action.

## What a withdrawal costs and how the fees are booked [#what-a-withdrawal-costs-and-how-the-fees-are-booked]

The former journal fee schedule and postings are retired. Gateway withdrawal fees use the gateway’s current terms: a fee can be deducted or recorded as owed. Client and service gas obligations are separate. Review the current quote. Neither fees nor network charges are universally zero.

### How the fees are quoted [#how-the-fees-are-quoted]

The old fee-quote endpoint and fixed gas estimate are retired. The current gateway quote uses its actual terms and network recharge ceiling. If the interface cannot price a fee, resolve that condition before submitting. A gateway quote is not a renamed legacy journal quote.

### How the fees are charged [#how-the-fees-are-charged]

The former journal hold for custody fees is retired. Current requests lock receipts and apply the gateway’s fee mode. A deducted fee reduces the value paid, while an accounting-only fee is recorded as owed. Consult the current network quote rather than relying on the old claim that the investor’s custody balance never pays gas.

### How the fees are booked [#how-the-fees-are-booked]

The old fee-account posting table is retired. Current gateway fee-accrued or fee-owed records and reconciliation provide evidence for gateway fees. They are not aliases for the old journal outcomes or fee-account balances.

## Who sees what [#who-sees-what]

The old route and role inventory is retired. Current gateway reads are client or organisation scoped, and transitions require the appropriate role and stage. Withdrawal proofs retain their participant and operator checks. Generic organisation Cases remain available to owners and platform administrators even when custody operations are off.

## Related pages [#related-pages]

The legacy workflows on this page are migration references. Use [Custody gateway](https://docs.settlemint.com/docs/concepts/custody-and-signing/custody-gateway) for the current deposit and withdrawal model, [Wallet deposits and withdrawals](https://docs.settlemint.com/docs/console/my-assets/wallet-transfers) for client actions, [Custody settings](https://docs.settlemint.com/docs/console/organisation-settings/custody) for Providers and Cases, and [Custody reconciliation](https://docs.settlemint.com/docs/console/organisation-settings/custody-reconciliation) for break and destination review. [Custody Provider](https://docs.settlemint.com/docs/concepts/custody-and-signing/custody-provider) explains signing responsibilities. [Maker-checker](https://docs.settlemint.com/docs/concepts/custody-and-signing/maker-checker) explains required approvals.


# Custody Gateway

Source: https://docs.settlemint.com/docs/concepts/custody-and-signing/custody-gateway
A custody gateway is a client's own deposit and withdrawal point on one network, where coins held in custody are exchanged for custody receipts and back.



[Figure] A client's gateway swaps coins for custody receipts and back. A client card on the left sends coins along an accent edge to the focal custody gateway card in the middle, which holds an escrow for anything that waits. The gateway sends custody receipts back to the client along a quiet edge and forwards the coins to a custody destination card on the right. Labels: Client; sends coins in; holds custody receipts; asks for coins back; coins in; receipts; out; Custody gateway; One per client; mints receipts for coins in; burns receipts for coins out; Escrow; holds what waits; forwards; Custody destination; where forwarded coins sit; optional: without one, the; escrow keeps the coins.

A custody gateway swaps coins for custody receipts on deposit and back on withdrawal, and its escrow holds whatever waits for a decision.

Each client has one gateway per network, and its address is the client's deposit address. The gateway mints custody receipts only against coins it has received and pays coins out only in the same step that burns the receipts.

Every deposit and every withdrawal is its own record with its own stage, and the stage is the status the client sees.

A gateway runs on the organisation's custody gateway add-on, so settings, roles and approvals are shared across all gateways of the organisation.

## What a gateway does [#what-a-gateway-does]

A custody gateway gives one client a single place on one network to hand coins to custody and to get them back. The client deposits coins and receives [custody receipts](https://docs.settlemint.com/docs/concepts/custody-and-signing/custody-receipt), ordinary DALP assets that stand for those coins. The client later returns receipts and receives the coins. The gateway runs both legs in one transaction, so a client who deposits or withdraws through it never loses a receipt without getting the coins. Three roles on the receipt act outside the gateway. The custodian role can force-transfer receipts to any wallet with a verified identity in the receipt's identity registry. The supply management role can mint receipts with no coins behind them, and can burn a client's receipts without paying out coins. The governance role can remove the compliance rule that keeps receipts in the loop.

One gateway holds several coins. An organisation enables the custody gateway add-on once, a single deployment of the gateway contracts for its system. Each client identity, the client's on-chain identity record, then gets its own gateway from the add-on. The gateway's address is fixed before the gateway exists.

Every gateway runs the implementation the add-on factory points to. A holder of the system manager role, or the add-on registry, can point the factory at a new implementation, which changes the code of every gateway of the organisation at once. No client and no gateway manager approves that change.

## How a deposit moves [#how-a-deposit-moves]

A deposit starts when coins reach the gateway, either because the client calls the gateway or because the client sends a plain transfer that the keeper then reports. The keeper and the screener are service wallets of the organisation, and the gateway managers are people, as [Who acts at each step](#who-acts-at-each-step) sets out. The gateway counts a plain transfer only once and only if the coins are still unclaimed by any other record. The keeper names the sender, and the gateway checks the coins itself.

[Figure] A deposit passes four steps and can rest in three places before it ends. A top row shows the steps receive, source check, mint receipt and forward, joined by accent edges. Three resting stages sit below: quarantined, which waits for the screener, mint refused, which waits for the gateway managers, and awaiting custody, which waits for the custodian. A bottom band lists the three end states: settled, returned to the sender and recovered to the recovery address. Labels: Steps; Receive; coins counted once; Source check; optional screening; Mint receipt; less any deposit fee; Forward; to the custody side; Resting stages; Quarantined; waits for the screener; Mint refused; waits for the managers; Awaiting custody; waits for custody; Ends; Settled, Returned to the sender, Recovered to the recovery address.

A deposit that passes every check settles at once, and one that needs a decision rests in one of three stages until it settles, returns or is recovered.

A deposit has a stage from the first moment: there is no separate received stage. The gateway runs the steps in one transaction for as long as each can decide on chain, and stops at the first one that needs an answer from outside.

The screening mode decides which deposits wait.

- **Always quarantine**, the default: every deposit rests in quarantine and mints nothing until the screener acts.
- **Credit approved sources**: a direct deposit from an approved source settles at once. A plain transfer is recorded before anyone has confirmed its sender, so it rests in quarantine like a deposit from any other source.
- **Off**: every deposit settles at once while the gateway is not paused.

A paused gateway refuses direct deposits but still records reported transfers, each in quarantine whatever the mode, and none of them can be cleared until the gateway is unpaused. A client can leave a gateway that stays paused past the coin's time limit, as [How a withdrawal moves](#how-a-withdrawal-moves) explains.

The client can pull a quarantined deposit back to its confirmed sender after a stored wait. The screener can clear or refuse it. A frozen quarantined deposit keeps its stage and cannot be cleared, refused or pulled back until the freeze ends. The gateway managers can still return or recover it.

A deposit rests as mint refused when its receipts cannot be minted, for example because the custody receipt's compliance rules reject the receiving wallet. A direct deposit that reaches the mint in that case fails and leaves no record, since the client is present to see the failure. With always-quarantine screening the deposit waits in quarantine first, and a refused mint at the screener's clear moves it to mint refused. While the receiving wallet is frozen, the clear itself fails and the deposit stays in quarantine. A reported transfer that reaches the mint never reverts. When the mint is refused, the deposit rests as mint refused, even when the receiving wallet is frozen, and waits for the gateway managers to fix the cause or send the coins back.

Awaiting custody exists because some custodians screen incoming coins themselves and can decline them after they arrive. When the gateway is set to wait for custody, which needs the custody receipt to carry the hold feature, the same transaction that mints also places a hold on the minted receipts in the client's wallet. The hold releases when the keeper confirms the custodian accepted the coins. If the custodian sends them back instead, the gateway managers return the deposit, which burns the held receipts and pays the coins back to the confirmed sender. The setting suits destinations such as a Fireblocks vault.

A deposit ends in one of three ways. It settles, or it is returned to its confirmed sender with a record of who returned it, or the gateway managers recover it to an address they name in the recovery call, with the approvals the add-on checker requires for recovery. Recovery applies to a frozen quarantined deposit or a mint-refused deposit whether or not its sender is confirmed, and to coins a custodian sent back for a deposit whose sender was never confirmed.

## How a withdrawal moves [#how-a-withdrawal-moves]

A withdrawal starts when the client returns custody receipts to the gateway and names the approved payout address that receives the coins. The receipts move into the escrow and stay locked for that request until it is paid or the receipts go back.

[Figure] A withdrawal locks receipts, passes review where required, waits for funds, then pays in order. A top row shows the stages requested, in review, awaiting funds, claimable and settled, joined by accent edges. Below requested sits awaiting payout address, where a request waits when the client has named no approved payout address. A bottom band lists the two ways receipts go back to the client: receipt returned, and return pending while the client wallet is frozen. Labels: Stages; Requested; receipts locked; in escrow; In review; only if screening; or a limit applies; Awaiting funds; paid in the order; they arrived; Claimable; coins set aside; for this request; Settled; burned; and paid; Awaiting payout; waits for an approved address; Receipts go back; Receipt returned, or Return pending while the client wallet is frozen.

A withdrawal moves from request to payout through review and funding, and a request that stops short returns its receipts to the client.

A request the client makes directly fails at once if the payout address is not approved, the amount is below the minimum, or the client's total for the day would pass the daily maximum. Receipts sent by plain transfer cannot fail that way: with no approved default payout address the request waits as awaiting payout, and the receipts stay locked until the client names an address. When the coin sets a time limit for naming a payout address and the client names none within it, the receipts go back. A request that passes takes the fee, gas ceiling and time limits in force at that moment, and keeps them for its whole life.

Review applies when screening or the travel rule covers the coin, or when the request reaches the instant limit. The screener clears screening. A request at or above the instant limit also needs the gateway managers' approval. With no instant limit set, the limit reads zero, so every request needs that approval. A gateway manager gives it with the withdrawal's `approve` transition, or **Approve** on the request in the Console. The call is checked: when the add-on's checker asks for approvals, the first attempt answers with the call to propose through the [add-on approval](https://docs.settlemint.com/docs/concepts/compliance-and-identity/addon-approvals) routes, and sending the transition again once the proposal is approved runs it. A frozen request, or one whose client has a revoked or expired compliance claim, cannot be approved until that clears. Each requirement clears on its own, so a request that needs both stays in review until the screener and the managers have both acted. Approval never pays: once nothing is outstanding the request moves to awaiting funds.

The keeper pays waiting requests of a coin in the order they started waiting for funds. A request is paid in full or not at all, and the queue stops at the first request that funding cannot cover.

Only confirmed funding pays. Funding that a listed funding source sends by calling the gateway counts at once, and a plain transfer from a funding source counts after the screener confirms who sent it.

A claimable request has coins set aside for it, and its receipts wait for the coins to be collected. With auto-claim on, which is the default, the step that makes the request claimable also tries to burn the receipts and pay the payout address. If the payment fails, for example because the payout address was suspended after the request opened, the request stays claimable with its receipts unburned and the queue moves on.

With auto-claim off, the request becomes claimable and the client claims it. A claim pays the stored payout address, less the fee and any gas recharge when the gateway deducts fees. In accounting-only mode the full amount is paid and the fee is recorded as owed.

The keeper quotes the gas recharge from the price of the chain's native coin, which the deployment sets for each network and coin and which expires after an hour by default ([Custody gateway keeper gas price](https://docs.settlemint.com/docs/deployment/install/values-secrets#custody-gateway-keeper-gas-price)). With no price, or a stale one, the request carries no gas recharge and the organisation pays the keeper's gas. The quote never passes the gas ceiling stored on the gateway.

A client can cancel while a request is in review or waiting for a payout address, or after it has waited for funds longer than the cancel time limit. The limit is the one the gateway held when the request was made, so a later settings change does not move it. With no cancel time limit set, a request waiting for funds cannot be cancelled. A claimable request can be cancelled once the screener or a gateway manager has suspended its payout address, or a gateway manager has removed it: the cancel releases the coins reserved for the request and returns the receipts. While the payout address stays approved, the request cannot be cancelled and is paid by a claim. A frozen request leaves the queue while younger requests go ahead, and rejoins at the back when its freeze ends. Receipts returning to a frozen client wallet wait as return pending until the wallet is unfrozen.

A client can also leave a gateway, for a deposit or a withdrawal, once it has stayed paused for the time limit set for the coin, counted from the earlier of the gateway's own pause and the add-on-wide pause. A quarantined deposit goes back to its confirmed sender. A request that is waiting for a payout address, in review or waiting for funds gets its receipts back, and a claimable request is paid to its stored payout address, or gets its receipts back when that address is no longer approved. A frozen deposit or request cannot exit.

### A corporate action re-bases a queued request [#a-corporate-action-re-bases-a-queued-request]

A stock split, bonus issue or other action that changes every holder's units by a ratio also changes the receipts a request holds. The gateway does not change every queued request when the action runs. It re-bases a request the next time anything touches it: a review decision, funding, a claim, a cancel or the keeper's queue. The request then holds the shares a direct holder of those receipts would hold after the action, rounded the way the action rounds. The keeper's queue and the totals in review and waiting for funds move with it.

Between the action's record date and the moment its step lands, the gateway's escrow is frozen for the receipt token. In that window a client cannot open a new request or claim one, and an ordinary return is refused. The refusal names the token and the action. A return caused by the action itself, for a request it rounds to zero, still goes through. A request that was already queued stays queued, and it re-bases the first time it is touched after the step lands.

A claimable request that a corporate action changes goes back to waiting for funds on the new amount. Its set-aside coins are released, a freeze on it stays in place, and its cancel time limit counts again from the moment it went back to wait. A request the action rounds to zero ends as returned, with the reason "Returned by a corporate action". It holds no receipts after the action, so nothing is paid out and nothing goes back to the client. The pending and claimable amounts a client reads for a request already show it on the new basis, before anything touches it: a claimable request the action changed reads as waiting again, and one rounded to zero reads 0.

## What waits in the escrow [#what-waits-in-the-escrow]

Each gateway has its own [escrow](https://docs.settlemint.com/docs/concepts/custody-and-signing/escrow), an on-chain contract that holds tokens under one controller, created in the same step as the gateway. The escrow holds the coins of deposits that wait in quarantine or rest as mint refused, the gateway's confirmed funding, the coins reserved for claimable requests, and the custody receipts locked for open withdrawal requests. A deposit that settles at once and is forwarded to a separate destination never enters the escrow. On a gateway without a separate destination, the coins of a settled deposit move into the escrow as funding for withdrawals.

The gateway's records and the escrow's records agree while the coin moves only by transfers. The gateway manager attests to that when enabling the coin. What the escrow owes the gateway equals the sum of seven kinds of coin: quarantined, held, provisional, funding, reserved, unallocated and returning. Provisional coins are funding reports still waiting for the screener to confirm the sender. The gateway's own address holds the coins of unsupported transfers and of arrivals the keeper has not reported. A forced transfer, burn or negative rebase applied to the escrow's balance of the coin breaks the equality, as [Escrow](https://docs.settlemint.com/docs/concepts/custody-and-signing/escrow#sweep-and-what-the-escrow-cannot-prevent) explains. Coins that match no deposit, withdrawal or funding sit in an unallocated balance. Only the gateway managers can recover that balance, to an address they name, and recovery never touches funding or anything a record is waiting on.

## The optional treasury [#the-optional-treasury]

A treasury lets a coin pay withdrawals at once instead of waiting for funding. The add-on can link one treasury to a coin. The treasury is the organisation's own wallet or vault. The add-on stores its address and never holds coins.

Only a gateway without its own destination for forwarded coins draws from the treasury, and only below its instant limit. Each client still has its own gateway and escrow, so a draw never mixes clients' coins. A draw goes from the treasury straight into that gateway's escrow, set aside for one request. A treasury that cannot pay leaves the request waiting for funding. A gateway manager turns the treasury off alone, because turning it off only removes a way to pay, while linking a treasury needs approval.

## Who acts at each step [#who-acts-at-each-step]

Four roles act across both flows: the client, the keeper, the screener and the gateway managers. Gateway managers are people, and the keeper and the screener are service wallets of the organisation. A gateway permission manager, a system role the organisation admin grants on the permissions screen, does not act on deposits or withdrawals. It grants the manager, keeper and screener roles once for the whole add-on and sets how many approvals each checked action needs.

| Role | What it does | What it cannot do |
| --- | --- | --- |
| Client | Deposits, requests a withdrawal, cancels, pulls back a quarantined deposit, leaves a gateway paused too long, sets a payout address on its own gateway. | Act on any other client's gateway. |
| Keeper | Reports plain transfers, runs the payout queue, retries a refused mint, confirms the custodian accepted coins. | Clear screening or decide who the sender is. |
| Screener | Confirms a sender, clears or refuses a quarantined deposit, clears withdrawal screening, freezes a record. | Approve a request above the instant limit. |
| Gateway managers | Create gateways, enable coins, manage profiles and the treasury, pause, approve above the limit, return or recover coins to an address they name. | Pay a withdrawal without funding behind it. |

A frozen record blocks the steps that move that record forward, and no other record. Reports of facts still go through: the keeper can report a custodian's return of coins for a frozen deposit that is awaiting custody, and the report records the amount without ending the freeze. The screener or a gateway manager freezes it, and the freeze ends at its expiry unless renewed. Once the gateway managers mark a frozen record as reported, the freeze no longer expires and the record leaves only by a return or a recovery.

A gateway manager can set a gateway's own screener key, with the add-on checker's approval. That key then answers screening for that gateway in place of every screener role holder.

## Profiles and settings [#profiles-and-settings]

Settings resolve at read time from three layers: the gateway's own value, else the value on the profile it points to, else the add-on default for the coin. A profile is a named record on the add-on holding values per coin, such as time limits, fees, auto-claim and who answers screening. An administrator assigns a profile to a gateway, and changing the assignment is one change instead of many.

A request in progress keeps the terms stored with it, so a later change reaches new requests only. Lists, the destination for forwarded coins, pause and approval counts are read live. Removing a profile that a gateway uses is declined.

## Approvals through the add-on checker [#approvals-through-the-add-on-checker]

The add-on checker is the approval mechanism for the gateway's sensitive actions, run by the add-on's own access manager contract. A gateway manager proposes an action, a set number of other gateway managers approve it, and the proposer then makes the call with the same parameters. The access manager counts the approvals on chain, so a change that needs approval takes effect only once that number of other gateway managers have approved it. Pending approvals appear in [Actions](https://docs.settlemint.com/docs/console/essentials/actions).

The number of approvals is set per action. Actions that only tighten, such as a pause, a freeze or a stricter setting, apply at once. Actions that loosen or move value, such as linking a treasury, moving a gateway to another profile or returning a deposit, need one other approver by default. Enabling a coin, creating or removing a profile, and creating a gateway without a profile need only the gateway manager role and no approval, whatever the counts say. A gateway permission manager can change that count for every gateway or for one gateway, alone and at once, because the count change needs no approval of its own. A count of zero lets one gateway manager act alone, so treat the count as part of the control.

The add-on checker is separate from the Approvals settings in General. One wallet counts as one approval, so several people behind one approval need a [multisig](https://docs.settlemint.com/docs/concepts/custody-and-signing/multisig) smart wallet as the role holder.

## Running the add-on through its API [#running-the-add-on-through-its-api]

[Deposit and withdrawal stages](https://docs.settlemint.com/docs/api-reference/guides/custody-gateway-stages) lists every stage a record can be in, who moves it and the time limit behind it, and the [custody gateway API how-to](https://docs.settlemint.com/docs/api-reference/guides/custody-gateway-api) walks a deposit and a withdrawal through the routes.

An organisation owner or platform administrator reads and changes the add-on at `/api/v2/addons/custody-gateways`. The reads answer from indexed chain data, so a read made just after a write can lag. They answer 404 while the organisation's system has no custody gateway add-on on the network.

The gateway routes belong to the "Self-custody" [licensed module](https://docs.settlemint.com/docs/deployment/install/values-secrets#switch-application-layers-on-or-off), which the `features.custodyOps` setting switches on for the deployment and which is on by default. A deployment that sets it to false serves none of these routes. An organisation that switched the module off for itself keeps its reads, and every write route answers `403 Forbidden` with `platform.module.DISABLED` ([DALP-20531](https://docs.settlemint.com/docs/api-reference/errors)).

- `GET …/factory` answers the add-on's factory, fee account, pause switch and access manager, and `GET …/tokens`, `…/profiles` and `…/gateways` list the coins with the receipt each mints, the profiles and the gateways. `GET …/gateways/{gatewayAddress}` answers one gateway with its client identity, country, profile, pause state, client wallet and payout address.
- `POST …/tokens` enables a coin with its custody receipt. The call must carry the coin's `freeze-expiry` and `paused-exit-after` in the same `defaults` list, because they are the only settings a coin needs to be enabled. A list that omits one, repeats a name, or gives a value the setting cannot hold answers 422, an already enabled coin answers 409, and nothing is queued. Enablement refuses a receipt whose decimals differ from the coin, a receipt without the own-custody-gateway rule bound to this factory, and a freeze expiry or paused-too-long limit that is missing or zero. The gateway manager attests that the coin's balances change only by transfers. The treasury is set after enablement.
- `POST …/profiles` creates a profile from a name and the claim topic a client must hold, and `POST …/profiles/{profileId}/transitions` with `{"transition":"remove"}` removes one. A profile that gateways use answers 409.
- `POST …/gateways` creates the gateway of a client identity under a profile. A client identity that already has a gateway answers 409.
- `PATCH …/tokens/{tokenAddress}/settings`, `…/profiles/{profileId}/settings` and `…/gateways/{gatewayAddress}/settings` change settings at one level, up to 20 in one request, and a `null` clears that level's own value so the level below applies. Switching wait for custody on, or changing where coins go while it applies, needs coins-go-to to resolve to a wallet of one of the organisation's Fireblocks custody providers, at the changed level and every level below it.
- `PATCH …/gateways/{gatewayAddress}` moves a gateway to another profile, and `PATCH …/gateways/{gatewayAddress}/client-wallet` binds its client wallet. The signing administrator must be a gateway manager, and a wallet that is not the client's answers 422.
- `POST …/gateways/{gatewayAddress}/approved-sources` and `…/approved-payouts` add an approved source or payout address, and their `…/{address}/transitions` remove one or suspend and reinstate a payout address. `POST …/gateways/{gatewayAddress}/tokens/{tokenAddress}/funding-sources` adds a wallet whose transfers of the coin fund withdrawals, and its `…/{sourceAddress}/transitions` removes it.

The administrator's own wallet signs each write. Each write asks for a wallet step-up and an `Idempotency-Key`. It answers 200 once the transaction settles inside the request's preference window, and 202 with the transaction to poll otherwise. Before anything is queued, the platform tries each call against the chain from the administrator's wallet. A call the add-on's checker wants approved answers 422 with the exact calls to propose and their hashes, and the same request is queued once the checkers have approved it. A call the add-on refuses answers 422 with the name of its revert, and a coin whose custody receipt cannot hold deposits answers 422 when wait for custody is switched on.

A gateway binds no client wallet when it is created, because a client identity can hold several wallets. Until a manager binds one, that client's own routes answer 404, and each mint reads the bound wallet and checks again that it belongs to the client identity.

## Roles and the two service wallets [#roles-and-the-two-service-wallets]

The add-on keeps its own access manager, so one grant covers every gateway of the add-on. A gateway permission manager grants and revokes the manager, keeper and screener roles at `GET /api/v2/addons/custody-gateways/role-members` and `POST /api/v2/addons/custody-gateways/role-members` and at `POST …/role-members/{role}/{account}/transitions` with `{"transition":"revoke"}`. The organisation owner, a platform administrator and a member whose wallet holds the gateway permission manager role on the system may call these routes, and anyone else answers 403. The chain still decides: a wallet without that system role answers 422 and nothing is queued.

An add-on with no access manager answers `GET …/role-members` with an empty page. On such an add-on the first grant queues two calls in one write: `ensureAccessManager()` on the factory, then `grantRole` on the access manager that call creates. A revocation before then answers `404` `GATEWAY_ADDON_NOT_DEPLOYED`. Revoking the keeper or screener role from a wallet that the platform still signs with answers `409` `GATEWAY_SIGNER_IN_USE`, so rotate the signer first.

In the Console the same roles are on Organisation settings › Roles and permissions › Add-on roles, where a permission manager grants or revokes a holder with one PIN, and for everyone else those controls are off and say why.

A grant does not activate a signer. The keeper and screener wallets are set up at `/api/v2/addons/custody-gateways/signers`, which lists every wallet of both roles with its state, its last observed native balance and whether that balance is below the role's threshold.

Both role-member writes require a Console-issued session as well as wallet verification. A Portal-issued session, an anonymous session or one with no recorded issuing app answers `403 Forbidden` with `WALLET_ROLE_ADMINISTRATION_NEEDS_CONSOLE_SIGN_IN` ([DALP-200384](https://docs.settlemint.com/docs/api-reference/errors)) and starts no write. Sign in to the Console and retry. These routes do not accept API keys. The gateway permission manager check and the on-chain role check still apply.

- `POST …/signers` sets up a role's wallet from one of the organisation's custody provider configurations and tops it up with gas unless `funding` is `skip`. Sending it again before the grant answers the same wallet.
- `POST …/signers/{role}/transitions` with `{"transition":"rotate"}` mints the role's next wallet. The current wallet keeps signing until the new one is granted.
- `PATCH …/signers/{role}` sets or clears the low-balance threshold of every live wallet of the role.

A scheduled pass every minute switches each granted wallet to active and retires the one it replaces, so a new wallet signs nothing until a gateway permission manager grants it the role on chain.

## Reading a gateway's records [#reading-a-gateways-records]

A deposit and a withdrawal are each one record with a stable identifier and one history row for every stage it entered, in the order the chain logged them. A deposit that settles inside its recording call has one history row. The record keeps what an auditor needs: for a deposit the receipts minted, the fee, the address the coins were forwarded to, the held amount and the custodian's answer, and for a withdrawal the reserved and paid coins, the payout address, the fee, the return reason and any failed auto-pay.

`GET …/gateways/mine` answers the gateway that serves the signed-in client wallet. `GET …/gateways/{gatewayAddress}/deposits`, `…/withdrawals` and `…/unsupported` list the records, filterable by text, and the deposits list also takes `filter[source]` as `txHash:logIndex`. `GET …/deposits/{depositId}` and `…/withdrawals/{requestId}` answer one record with its stage history, and each withdrawal carries `needsScreening` and `needsApproval`, the review steps it still owes. An operator, the gateway's client wallet and a wallet holding the screener role may read a gateway, and anyone else gets 404.

The client's own writes are `POST …/deposits` and `POST …/withdrawals`. When the wallet's allowance of the coin or the receipt is short, the approval is queued first in the same request.

A record moves by one transition at a time.

| Route | Transitions |
| --- | --- |
| `POST …/deposits/{depositId}/transitions` | confirm-sender, clear, refuse, flag, unfreeze, renew-freeze, report, return, retry, custody-returned, recover, pull-back, exit |
| `POST …/withdrawals/{requestId}/transitions` | clear, approve, reject, flag, unfreeze, renew-freeze, report, return, unfulfil, cancel, collect, exit, set-payout |
| `POST …/unsupported/{recordKey}/transitions` | confirm-sender, ignore, return, enable, recover |
| `POST …/{gatewayAddress}/transitions` | pause, unpause, close |

A transition the record's stage does not allow answers 409 with the stage and the transition, and nothing is queued. The cancel of a claimable request whose payout address is still approved answers the same 409. A transition that needs the screener or keeper role answers 403 when the wallet does not hold it. One that needs the add-on's checker approval answers 422 with the calls to propose, and one the contract refuses answers 422 with the name of its revert. Confirming that the custodian accepted a deposit is the keeper's alone and has no transition of its own.

An organisation owner or platform administrator also reads what the client never sees: the gateway's review queue with each item's off-chain notes, nearest deadline first, the notes an operator appends to a deposit, the screening answers of each linked provider with its reference, verdict and score, and every setting the add-on knows for a coin with its effective value and the level it comes from.

The Console shows the same records on the gateway's Deposits, Withdrawals and Unsupported tabs, newest first with search and stage filters, and each row opens to its facts and stage history with the decisions its stage allows. The Investor portal lists them on the Transfers tab of Portfolio, with open records under In progress and the rest under History, newest first in client wording.

## Closing a gateway, and following a client to a new wallet [#closing-a-gateway-and-following-a-client-to-a-new-wallet]

Closing needs the approvals the add-on checker requires for it, and is refused while any deposit or request has not ended, any receipt the gateway minted is unburned, or the gateway's escrow still owes it coins. Recover the unallocated coins first. A closed gateway refuses deposits, withdrawal requests and funding reports, and closing cannot be undone. A close that is blocked stays disabled in the Console and names what blocks it.

After closure is indexed, the Console shows Closed in the gateway list and detail header, even if the gateway was paused when it closed. The Overview tab shows the closure date and time, and removes the Pause, Unpause, Close and client freeze controls. You can still read the gateway's records and history. Gateway list and detail API responses include `closedAt`, which is null until closure is indexed and then contains the closing block's timestamp.

When the identity registry recovers a client's lost wallet to a new wallet under a new identity, the gateway follows the client there. Anyone can rebind the gateway, naming the new wallet: the gateway follows the registry's recovery links back from that wallet, at most eight hops, to its current client identity, and a wallet with no such link is refused. A holder of the identity manager role records that recovery link alone, so that role decides which wallet takes over the client's gateway, escrow and open requests. The rebind keeps the gateway's address, escrow, records and settings, moves the add-on's one-gateway-per-identity map to the new identity and makes the new wallet the client wallet. A new identity that already has a gateway of its own is refused, and rebinding to a wallet of the current client changes nothing. The new wallet cancels and claims the requests the lost wallet opened, and the lost wallet can no longer act. The Console's identity recovery makes this rebind for you: after it moves the user's token balances, it rebinds the gateway of the lost identity, current or former client, to the replacement wallet and to the replacement smart wallet, and moves the holds of every lost wallet of the client or a former client, also when the identity did not change. If the issuer's forced token recovery has not moved the receipts held for custody, the gateway refuses the rebind and the recovery stops with that reason. Execute the recovery again once the token recovery finishes.

A gateway manager can also freeze every wallet of a client on every custody receipt the add-on enabled, from the detail of an open gateway. Before it signs, the dialog names the wallets, the receipts and the open records the freeze reaches. It records a reason for each wallet and receipt. Frozen wallets cannot move receipts until a gateway manager unfreezes them.

## When a client's claim is revoked or expires [#when-a-clients-claim-is-revoked-or-expires]

When a compliance claim the gateway's client must hold is revoked or expires, the client is flagged. The flag freezes what the client could move: the revocation fan-out freezes the client's open deposits and withdrawals and suspends its payout addresses. No withdrawal can be requested, and the transitions that pay or credit the client wait until the flag clears. Those transitions are clearing or retrying a deposit, and clearing, collecting or exiting a withdrawal with its coins. A write that would move value while the flag stands is refused with `GATEWAY_CLIENT_FLAGGED` ([DALP-13995](https://docs.settlemint.com/docs/api-reference/errors)).

`GET …/gateways/{gatewayAddress}/client-flag` answers whether the flag stands, the open flags first with what raised each of them, and what the flags and payout-address hits did on the gateway. The provider issuing the claim again, or renewing it, clears the flag on its own. A screener clears reviewed flags with `POST …/gateways/{gatewayAddress}/client-flag/transitions` and `{"transition":"clear","triggerIds":[…]}`, naming the open flags they reviewed. A flag raised after the screener looked stays open and the response shows it. Once no flag stands, the fan-out unfreezes what it froze. A payout address the flag suspended stays suspended until it is reinstated.

The gateway's Console panel names the open flag and links each frozen record, with when each freeze ends and renewal where the freeze lapsed.

## Whitelisted addresses against the approved lists [#whitelisted-addresses-against-the-approved-lists]

`GET …/gateways/{gatewayAddress}/whitelist-entries` lists the client's whitelist entries that matter to the gateway: proved and active addresses, and revoked ones that are still an approved source. Each row carries when the address was proved, whether it is an approved source or payout address, and the proposal still to raise: add a source for an active entry that is missing from the sources, remove a source for a revoked entry that remains in them, and add a payout address for a proved or active entry that is missing from the payout addresses. The list reads the participant that owns the gateway in your organisation. A gateway whose client has none lists nothing.

The gateway overview shows the same list as the Whitelist panel. Each button raises the proposal through the existing approved-source and approved-payout routes and asks for your wallet verification. Nothing is raised unattended, and the direct routes are unchanged.

## Frequently asked questions [#frequently-asked-questions]

### Does a client need the keeper to leave a gateway?

No. Cancelling a withdrawal, pulling back a quarantined deposit and leaving a gateway that has stayed paused for the time limit set for the coin are calls the client's own wallet sends. None of them depends on the keeper, so a client can leave when the keeper is not running.

### Can a deposit mint receipts for a coin the gateway does not accept?

No. A direct deposit of a coin the add-on does not accept fails. A plain transfer of such a coin is recorded as unsupported and waits for the gateway managers, who return it, enable the coin and turn it into a deposit, recover it or mark it ignored.

### Why does a deposit rest in awaiting custody instead of settling?

Some custodians accept incoming coins only after their own screening. The gateway mints the receipts and holds them in the client's wallet in the same transaction, so the client sees the deposit, and the hold releases only when the custodian accepts the coins.

## Related concepts [#related-concepts]

- [Custody Receipt](https://docs.settlemint.com/docs/concepts/custody-and-signing/custody-receipt): The asset a client holds for coins in a gateway, and the rules for where it can move.
- [Custody deposits and withdrawals](https://docs.settlemint.com/docs/concepts/custody-and-signing/custody-deposits-and-withdrawals): How the platform credits a deposit to a custody wallet and pays a withdrawal straight out of it, with no custody receipt.
- [Custody Provider](https://docs.settlemint.com/docs/concepts/custody-and-signing/custody-provider): Who signs for the keeper and screener wallets, a decision separate from where deposited coins are kept.
- [Maker-checker](https://docs.settlemint.com/docs/concepts/custody-and-signing/maker-checker): The approval a proposed change needs before it takes effect, which the add-on checker applies on chain.
- [Operator Wallet](https://docs.settlemint.com/docs/concepts/custody-and-signing/operator-wallet): A wallet that pays gas for platform-initiated operations.


# Custody Provider

Source: https://docs.settlemint.com/docs/concepts/custody-and-signing/custody-provider
A Custody Provider decides who signs for an organisation's accounts, a managed custodian or the holder's own wallet, without changing accounts or approvals.



[Figure] An organisation's provider configuration resolves who signs for it. An Organisation vessel holds a focal Provider configuration card: a stored, probed record whose provider and credential source are fixed for the life of the record, with credentials that change by rotation. An accent edge labelled resolves the signer runs to a managed custody provider card, a service that holds the keys and signs on request, naming DFNS, Fireblocks, Luna HSM, Ripple, Utila, and the platform key store. A second edge labelled or the holder signs runs to a self-custody provider card, where Privy, Dynamic, and browser wallets let the holder sign with a key that stays theirs. A separate quiet card marked different job notes that custody approval approves a payload, not the signer. Labels: Organisation; Provider configuration; Stored and probed; provider and credential source; fixed for the life of the record; credentials change by rotation; resolves the signer; or the holder signs; Managed custody provider; holds the keys and signs on request; DFNS, Fireblocks, Luna HSM,; Ripple, Utila, platform key store; Self-custody provider; the holder signs. Keys stay theirs; Privy, Dynamic, browser wallets; Custody approval; Different job; approves a payload, not the signer.

A provider configuration resolves who signs, a managed provider or the holder's own wallet, and custody approval separately authorises the payload.

A configuration's provider and credential source are fixed at creation. Credentials change through probed rotation, and every new or rotated credential must pass a live probe against the provider before the platform commits it. A different provider is a new configuration.

New accounts require a healthy configuration that is enabled for account creation. An unhealthy configuration still signs some requests, and only a quarantined configuration signs nothing.

A custody provider signs. Custody approval decides whether a payload may be signed at all.

## Why the custody provider matters [#why-the-custody-provider-matters]

A custody provider lets an organisation decide who holds the key that signs for its accounts. That key sits with a managed custodian that signs under its own policy, or with the account holder's own wallet, where the holder signs and the platform never touches the key. That choice sits underneath every privileged operation an account performs across an asset's [lifecycle](https://docs.settlemint.com/docs/concepts/issuing-and-markets/asset-lifecycle): a subscription, a corporate action, a trade delivery. Each one confirms through signer verification at the moment of signing, whatever the bound provider requires. The provider decides who can sign for the account's address, and the position stays with that address on chain.

Every account is created against one provider configuration, a stored record naming the provider, the networks it serves, and whose credentials it uses. That record decides who controls the keys behind every transaction the organisation submits.

Providers come in two kinds. A managed provider holds keys and signs when the platform asks. The managed family covers IBM Digital Asset Haven, DFNS, Fireblocks, Luna HSM, Ripple custody, Utila, and the platform key store, which keeps keys in the platform's own secret store. A self-custody provider hands signing to the account holder instead. Privy, Dynamic, and browser wallets connect a wallet the holder controls, and the platform never holds that key. These integrations sign on EVM-compatible networks.

A deployment decides which of these providers it offers at all. Every kind has a switch, `custody.providers.<kind>.enabled`, and Ripple custody and Utila are the two that ship off. While a provider is off:

- The Console form does not offer it, and no organisation can store a new configuration for it.
- It is never offered for new accounts.
- The deployment refuses to boot if it names that provider as its own signer.

Configurations stored before the switch moved keep signing, still appear in the Console's provider list, and their credentials can still be rotated.

Every provider kind the deployment offers is available when adding a configuration. A configuration keeps the name of the provider it was added as, so the Console and the Investor portal show IBM Digital Asset Haven for a configuration added as IBM Digital Asset Haven and for every account it holds. An organisation can run several configurations side by side, and each account keeps the configuration it was created with. A configuration's provider and credential source cannot change afterwards, so custody moves only when an administrator adds a new configuration and points new accounts at it.

## Managed keys or the holder's own wallet [#managed-keys-or-the-holders-own-wallet]

Choose managed custody for accounts the organisation operates. Provider policy decides which signing requests can proceed automatically and which need approval. With an external provider, keys stay with that provider. With the platform key store, keys sit in the deployment's own secret store, so whoever operates the deployment holds them.

Choose a self-custody provider for holders who keep their own keys. The holder's wallet signs every request the platform sends to it, so the platform cannot sign a transfer in the holder's name. Two controls still act without the holder's signature. A holder of the custodian role on an asset can force a transfer or recover tokens from a lost wallet, and on a single-owner Smart Wallet the platform guardian can name a replacement owner key, which takes effect 72 hours later unless the holder cancels it. The account is proven by an interactive signature from the holder's wallet, and later signing requests require the holder's interaction. The cost is recoverability. The platform cannot restore a lost key for a plain wallet, and identity verification does not restore key control there, so a holder should add another active signer before access is lost.

One participant, the platform's single record for a person or an organisation, can use both kinds of custody. A participant has at most one on-chain identity on each network. It can own several wallets and bind each wallet to that identity on a network. On one network a managed key and a wallet the holder controls can therefore belong to the same participant and the same identity.

The Console marks an owned wallet with no binding as "Held, not bound". On the participant's page, "Add wallet" either creates a managed key or connects a wallet the participant already controls. When the key behind the participant's identity is in self custody, the participant has to sign the identity installation on each new network itself. The "Install identity on this chain" action then stops and shows "The participant's key is in self custody, so the participant must sign on this chain itself."

Managed configurations carry one further choice: whose credentials reach the custodian. Platform credentials belong to the deployment operator, the team that runs the platform installation. The Console offers them for the platform key store only, so a configuration added there for any other managed provider uses organisation credentials. The organisation supplies and rotates those itself, against a custodian account it can audit independently. That puts the rotation duty where the audit obligation already sits.

## Managing custody day to day [#managing-custody-day-to-day]

An organisation owner or a platform administrator manages provider configurations from the Console's [Custody](https://docs.settlemint.com/docs/console/organisation-settings/custody) screen, under organisation settings. Each configuration shows as a card naming its provider, execution health, and whether it accepts new accounts, along with its latest audit event. The same screen adds a configuration, which the platform records only once a live probe against the provider succeeds. It also controls account creation separately from execution: disabling new accounts stops only new signups, and existing accounts keep signing through it. For a managed configuration, the same screen rotates its credentials. Quarantining or recovering execution requires a written reason that lands in the audit trail.

An owner can extend a managed configuration's EVM network coverage from its card. The platform checks the required signing lanes, keeps all existing networks, and leaves adding the network to the organisation as a separate action.

## Which network a DFNS wallet is created on [#which-network-a-dfns-wallet-is-created-on]

A DFNS wallet lives on one DFNS network, and the platform picks it when it creates the wallet. It takes the first of three values that exists: the network the request names, the DFNS network that matches the request's chain ID, then the default network. The default network is the configuration's "Default network" field when it is set, then `DFNS_DEFAULT_NETWORK`, then `Ethereum`. The chain ID match covers 16 networks: Ethereum, Polygon, Arbitrum One, Optimism, Base, BSC, Avalanche C and Celo, each with its testnet. A network outside that list gets the default network, and on it DFNS signs wallet transactions as sign-only.

## How the platform names provider wallets [#how-the-platform-names-provider-wallets]

A provider console lists wallets by name, so the platform names each wallet it creates at a managed provider `DALP <role> <organization name> <chain ID> <reference>`. The role says what the wallet does, such as `participant` for an investor's wallet, `bundler` or `organization-identity`. The reference is eight hexadecimal characters derived from the wallet's account in the platform, so two wallets of one organisation on one network almost never share a name. A name never carries a person's name or user identifier.

The organisation name is written in plain ASCII characters. Accents are dropped, so `Northwind Café` reads `Northwind Cafe`, and every other character outside plain ASCII, such as an Arabic letter or an emoji, becomes `?`. A name holds at most 100 characters, and a Ripple Custody alias at most 75, so the platform shortens a long organisation name to fit. The role, the chain ID and the reference always stay whole.

"Reconcile wallet roles" renames each wallet on DFNS, Fireblocks and Ripple Custody that still carries a name the platform chose. The new name follows the wallet's current role and the organisation's current name, and keeps the wallet's reference.

On Ripple Custody it also rewrites the account description and the `dalpKind` property for the role. Each rename there is an account intent described as `Rename account <old alias> to <new alias>`, or as `Update the description of account <alias>` when only the description changes. The intent carries the organisation and the `dalpKind` of the wallet's role, the same properties as the account's creation, so your Ripple policies approve it the same way. A name that a person gave the wallet stays, unless it follows a pattern the platform or the provider uses for its own names, such as `Wallet 3`.

## How each provider signs and withdraws a request [#how-each-provider-signs-and-withdraws-a-request]

Each provider declares how it signs on each network, and whether the platform can withdraw a request that the provider still holds. A wallet transaction comes from an ordinary key-held wallet, and a user operation comes from a [Smart Wallet](https://docs.settlemint.com/docs/concepts/custody-and-signing/smart-wallet). "Provider files them" means the provider submits the signed request to the network itself. "Sign-only" means the provider returns a signature and the platform submits the request. [Custody approval](https://docs.settlemint.com/docs/concepts/custody-and-signing/custody-approval#how-long-can-an-approval-stay-open) describes how long a request can wait for a decision before the platform withdraws it.

| Provider | Wallet transactions | User operations | Withdraws a held request |
| --- | --- | --- | --- |
| DFNS | Provider files them on the 16 mapped networks, sign-only elsewhere | Sign-only, as typed data | Yes, it denies the held approval |
| Fireblocks | Provider files them on every network the workspace lists | Provider files them | Yes, it cancels the held transaction |
| Ripple | Provider files them on every network | Provider files them | No |
| Utila | Provider files them on every network bound to a Utila network | Provider files them | Yes, it asks Utila to cancel the request |
| Luna HSM | Sign-only, as a digest | Sign-only, as a digest | Not needed, the module keeps no request |
| Platform key store | Sign-only, as a digest | Sign-only, as a digest | Not needed, it holds no approval requests |

A Fireblocks workspace that lists no blockchain with a network's chain ID, or whose native asset Fireblocks has retired, has no lane there, and the platform refuses to add that network to the configuration. When a provider cannot withdraw, the platform records that the request is still open at the provider, with the provider's reference, so an operator can reject it in the provider's own console.

DFNS, Fireblocks, Ripple Custody and Utila hold a request for an approver and show text that DALP writes from the request, and all of them read one text. Fireblocks and Utila show it as the note on the request. Ripple Custody shows it as the intent description, which holds at most 250 characters and opens with a 60-character summary of the action when the text is longer. DFNS has no note, so it shows a label of at most 39 characters inside the 50-character external id of the request. The label keeps the operation, the amount, the token symbol and the counterparty. A text longer than 24 characters, such as a long token name, shows only its start, with no mark. When the label is still too long, it leaves out whole parts or cuts one, and it marks that cut with `~`.

## How rotation replaces a credential [#how-rotation-replaces-a-credential]

A custody credential is not edited in place. Rotation stages a replacement and runs it through a probe gate before anything signing is touched.

[Figure] A rotation must pass a live provider probe before it replaces the active credential. A candidate credential at version n plus one enters a rotation gate. The gate advances the credential version by exactly one and probes the candidate against the live provider within a 30 second bound. Only a candidate that passes reaches the active credential slot and signs from then on. A failed probe discards the candidate and version n keeps signing. Labels: Candidate credential; version n + 1, staged; Rotation gate; one version step; live probe, 30s bound; probe fails:; candidate discarded,; version n keeps signing; Active credential; version n + 1 signs.

A candidate credential becomes active only after a live probe succeeds, and a failed probe leaves the current credential signing.

Each rotation advances the credential version by exactly one. When two rotations of the same configuration run at once, both probe their candidate, the first to commit becomes version n + 1, and the second is refused with a conflict because a newer version is already recorded. Read the configuration before you retry. The probe is bounded at 30 seconds, so a provider that stops answering fails the rotation instead of hanging it.

Each rotation writes the new credential to a new slot in the platform's secret store. The commit updates the credential version, the slot and the rotation timestamp together. Signing reads the credential from the new slot from that moment, with no restart involved. The platform keeps the previous slot and tries to remove older ones after a one-hour grace period. A slot it fails to remove stays until a later attempt removes it. A rotation on a quarantined configuration passes through the same gate and can succeed, but it does not restore execution. Recovery is its own step with its own evidence.

## Health states decide what a configuration may do [#health-states-decide-what-a-configuration-may-do]

A custody provider configuration is always in one of three health states: healthy, unhealthy, or quarantined. A healthy configuration appears in the account-creation catalogue when new accounts are enabled. Unhealthy and quarantined configurations never appear there, so new accounts cannot select them. A quarantined configuration also signs nothing: every request bound to it fails and is never sent to another provider.

[Figure] Three health states decide whether a custody provider configuration may sign. Three states sit in a row. Healthy, the focal state, signs and opens accounts. A probe that fails moves it to Unhealthy, and a probe that passes moves it back, with no administrator involved. Quarantined is entered when an administrator quarantines a healthy or unhealthy configuration with a recorded reason, and leaving it requires recovery: a fresh passing probe plus a recorded reason. Labels: Healthy; signs and opens accounts; Unhealthy; last probe failed; Quarantined; stopped by an admin; a probe fails; quarantine, with a reason; a probe passes; recover: a fresh passing probe and a recorded reason; or quarantine directly, with a reason.

Probes move a configuration between healthy and unhealthy, administrators quarantine and recover it, and only a healthy configuration opens accounts.

| State | Set by | Offered for new accounts | Signs |
| --- | --- | --- | --- |
| Healthy | A passing probe | Yes, when enabled for account creation | Yes |
| Unhealthy | A failed probe | No | Some requests: a transaction request from a custody account and the submission signer's calls refuse it |
| Quarantined | An administrator only | No | No |

A failed probe marks the configuration unhealthy, which takes it out of account creation, and a later passing probe restores it, with no administrator involved in either direction. The fix runs on the provider's own side: the probe reaches the live provider, so there is nothing to reset in the platform beyond running **Test connection** again once the fault clears there.

Unhealthy does not stop every signature. A transaction request from a custody account refuses an unhealthy configuration, and so do the on-chain calls the platform signs with the organisation's own submission signer. Other signatures still go through an unhealthy configuration, such as a managed co-signature on a multisig wallet proposal or a typed-data signature. To stop every signature through a configuration, quarantine it. Only an administrator can enter or leave quarantine.

An administrator quarantines a configuration with a written reason, and the state sticks: passing probes are recorded but change nothing, and a successful credential rotation does not clear it either. Recovery is deliberate too: it refuses to run unless a probe has passed since the quarantine began, and it records its own reason, so the audit trail shows who stopped execution, why, who restored it, and on what evidence.

## The integration contract [#the-integration-contract]

On the API, custody is a catalogue of provider configurations scoped to the caller's organisation. The [`GET /api/v2/custody/provider-configurations`](https://docs.settlemint.com/docs/api-reference/v2) route serves the account-creation listing. [`GET /api/v2/custody/investor-provider`](https://docs.settlemint.com/docs/api-reference/v2) returns the options the organisation offers its investors. Every other operation runs under the [admin provider configuration endpoints](https://docs.settlemint.com/docs/api-reference/v2), restricted to an organisation owner or a platform administrator: list, create, probe, update, quarantine and recover, rotate, reconcile wallet roles, record a legacy provider wallet on its provisioning claim, and delete. An update turns new accounts on or off, offers the configuration to investors, makes it the investor default, or adds a network.

Two read surfaces exist for two audiences. The account-creation listing returns only healthy configurations enabled for new accounts, with credential provenance and execution diagnostics excluded, because a caller opening an account needs capabilities and nothing more. The administrator listing adds provenance, health, and the latest audit event, and still returns no secret material. No custody API route or Console screen returns a stored credential.

The account-creation listing also filters configurations by network. Send `chainId` to name the network. With no parameter, the listing uses the request's chain. An invitee reading with `invitationId` instead defaults to the inviting organisation's chain when available, falling back to the request's chain. Select the network before offering a configuration: participant creation refuses a configuration that does not serve the requested chain.

Several refusals on these routes share one code, and the error message names the case.

| Code | When the platform answers it | What to do |
| --- | --- | --- |
| `503` `CUSTODY_PROVIDER_UNAVAILABLE`, DALP-14218 | The provider did not pass its authenticated probe. On a create or a rotation nothing was saved. On a probe the configuration is marked unhealthy. | Retry. If the probe keeps failing, check the provider's status. |
| `409` `CUSTODY_PROVIDER_CONFIG_CONFLICT`, DALP-12272 | A delete hit a configuration that something still references. A recovery found no passing probe since the quarantine began. Another rotation of the same configuration committed a newer credential version first. A rotation targeted a configuration that holds no managed credential, or tried to change its credential source. A merge rotation sent no credential fields and the stored credential could not be read. An offer to investors or a default designation targeted a configuration that is not healthy and enabled for new accounts. | Read the configuration, clear what blocks the change, then send the request again. |
| `422` `CUSTODY_PROVIDER_CONFIG_INVALID`, DALP-12271 | The deployment has not enabled the provider or the ledger. The provider lacks a signing capability that one of the networks requires. A credential failed the provider's field checks. A configuration marked exclusive to the organisation does not use the organisation's own credentials. | Correct the request. Sending it unchanged gets the same answer. |
| `404` `CUSTODY_PROVIDER_CONFIG_NOT_FOUND`, DALP-18113 | The organisation holds no configuration with that id. | Check the id and the active organisation. |

A quarantine or a recovery without a reason fails request validation, because the reason is required and cannot be empty. The [error catalogue](https://docs.settlemint.com/docs/api-reference/errors) lists every code.

## Utila webhooks [#utila-webhooks]

A Utila approval that waits for an approver is also woken by Utila itself. In the Utila Console, open Vault Settings, then Webhooks, and register `https://<platform API host>/api/webhooks/utila` for transaction state changes. The platform checks the `x-utila-signature` header against the public key Utila publishes. That key is the default, so a stock install needs no setting. To use another key, set `UTILA_WEBHOOK_PUBLIC_KEY` to the PEM block or its base64 body. A blank value makes the platform answer every Utila delivery with 503 until a key is set.

A delivery only prompts a check: the platform reads the transaction from Utila again and decides from that answer, so a replayed or stale delivery cannot approve anything. A delivery with a bad signature is refused with 401. An event the platform has already handled is dropped.

## Controls and evidence [#controls-and-evidence]

For a control function, a custody credential is a secret the platform holds but never shows. Credentials live in the platform's secret store, keyed to one configuration and one credential version, and no Console screen or API response returns them. The platform reads them server-side only, to sign and to probe.

Evidence accumulates on the configuration itself. Every rotation stamps a rotation time and a strictly increasing credential version, so an auditor can reconstruct when each credential took over without an external change log. Every quarantine and every recovery writes an audit event naming what was done, who did it, the written reason, and when. A recovery event also records the passing probe that justified it.

The platform enforces a configuration's fixed provider and credential source on the record, before anything reaches a provider. For a key-held wallet, the configuration's history records which provider configuration signed for an account and when, and the custodian's own log records what it signed. For a Smart Wallet, the on-chain owner or signer set, with its change history, records which key the account accepted.

## Frequently asked questions [#frequently-asked-questions]

### Can an administrator quarantine a configuration while a rotation is running?

Yes. Quarantine and rotation are separate writes, and a rotation probes its candidate before it writes anything, so a quarantine can complete while a rotation is still probing. Both changes remain in force: if the rotation goes on to succeed, the new credential becomes active, but the configuration is already quarantined and stays stopped, like any other rotation on a quarantined configuration.

### Does the health state mean anything for a self-custody provider?

Not in the same way. A live probe only exists for managed providers. A self-custody configuration has no server-side credential to test, so its probe passes automatically and it stays Healthy by default. Quarantine still applies the same way: an administrator can quarantine a self-custody configuration with a recorded reason, which removes it from the account-creation catalogue exactly as it would a managed configuration.

### Can a self-custody provider's credentials be rotated the same way?

No. A self-custody provider has no platform-held credential to rotate, since the holder's own wallet signs and the platform never stores a key for it. A rotation request against a self-custody configuration is refused with `409` [CUSTODY_PROVIDER_CONFIG_CONFLICT](https://docs.settlemint.com/docs/api-reference/errors), code DALP-12272, because only a managed configuration stores a credential the platform can replace.

## Related concepts [#related-concepts]

- [Asset Lifecycle](https://docs.settlemint.com/docs/concepts/issuing-and-markets/asset-lifecycle): The stages an issued instrument moves through. Every privileged operation in every stage confirms through signer verification at the moment of signing, which is where a custody provider does its work.
- [Custody Approval](https://docs.settlemint.com/docs/concepts/custody-and-signing/custody-approval): The maker-checker gate that authorises a specific payload before it is sent to the custody provider for signing, a separate concern from which provider holds the keys.
- [Smart Wallet](https://docs.settlemint.com/docs/concepts/custody-and-signing/smart-wallet): The on-chain account a custody provider can sign for. Omitting a multisig configuration leaves a single owner key, which only makes sense when that key already sits behind a custody provider's own controls.
- [Multisig](https://docs.settlemint.com/docs/concepts/custody-and-signing/multisig): The other approval plane under custody approval, a weighted Smart Wallet whose own signers replace a single key that a custody provider or hardware module would otherwise gate.
- [Maker-checker](https://docs.settlemint.com/docs/concepts/custody-and-signing/maker-checker): The platform-enforced approval a proposed change needs before it takes effect, a different question from whether a custody provider's own policy lets a key sign. Its issuance figure shows both approvals in order.
- [Operator Wallet](https://docs.settlemint.com/docs/concepts/custody-and-signing/operator-wallet): A wallet that pays gas for platform-initiated operations such as account-abstraction bundling, separate from any custody provider that signs for an organisation's own accounts.


# Custody Receipt

Source: https://docs.settlemint.com/docs/concepts/custody-and-signing/custody-receipt
A custody receipt is an ordinary DALP asset that stands for coins held in custody, minted against coins a gateway received and burned on payout.



[Figure] With the own-gateway rule, a custody receipt moves only between a client and that client's own gateway. A client wallet on the left and the client's own gateway on the right are joined by two accent edges: the receipt goes from the wallet to the gateway when the client withdraws, and from the gateway to the wallet when a deposit mints it or a withdrawal returns it. A burn edge leaves the gateway. A quiet card below shows that a transfer to another holder is blocked by the own-gateway compliance rule. Labels: Client wallet; holds the custody receipt; a DALP asset like any other; withdrawal request; mint or return; Custody gateway; The client's own; mints against coins received; burns when coins are paid; Outside the loop; a transfer to another holder is; blocked by the own-gateway rule.

With the own-gateway compliance rule, a custody receipt moves only between a client and that client's own gateway, which burns it when it pays coins out.

A custody receipt is the token a client holds while its coins sit in custody. It is an ordinary DALP asset with the same decimals as the coin, and one receipt asset exists for each coin the organisation enables.

Gateways mint it only against coins they have received. The receipt's supply management role can also mint, so the organisation leaves that role unassigned.

A compliance rule on the receipt keeps it in a closed loop between a client and that client's own gateway, and the add-on refuses to enable a coin whose receipt lacks that rule.

## What a custody receipt is [#what-a-custody-receipt-is]

A custody receipt is the asset a client holds while its coins sit in custody. It is an ordinary DALP asset, so the same compliance, identity, freeze and forced transfer controls apply to it as to any other, and it shows in the client's wallet like any other holding. The custody receipt for a coin has the same number of decimals as the coin, so one receipt unit stands for one coin unit before any fee owed.

The custody gateway add-on is the organisation's one-time deployment of the gateway contracts. It enables a coin by binding it to its custody receipt. After that, the [custody gateway](https://docs.settlemint.com/docs/concepts/custody-and-signing/custody-gateway) mints and burns receipts of that coin. A client who wants coins back returns receipts to the gateway instead of selling them on.

## How the receipt is backed [#how-the-receipt-is-backed]

The gateway backs each receipt by doing its steps in a fixed order. On a deposit, the gateway checks that the coins are present and not already counted, and only then mints receipts to the client's wallet, less the deposit fee when the gateway deducts it. On a withdrawal, the gateway burns the receipts in the same transaction that pays the coins. Through the gateway, the client never loses a receipt without getting the coins, and the gateway mints no receipt for coins it did not receive. Two roles on the receipt act outside that guarantee: a forced transfer by the custodian role, and a mint or burn by the supply management role.

The receipt has a supply delegate feature, a list of the accounts allowed to mint and burn it. The list holds the add-on's factory, the contract that creates the gateways. The factory confirms that a caller is one of its own gateways. The receipt therefore needs one entry, and every gateway of the organisation can mint and burn in its name. A gateway of another organisation cannot.

The receipt still has the ordinary supply management role, and an account that holds it can mint and burn without the gateway. Keep that role unassigned on a custody receipt, because a receipt minted that way has no coins behind it.

The add-on refuses to enable a coin whose receipt carries a transaction fee, fee accounting or assets-under-management fee feature. Fees on deposits and withdrawals live in the gateway, where they are set per coin and stored with each request. In the default mode the gateway deducts a deposit fee before it mints and a withdrawal fee before it pays. In accounting-only mode it mints and pays the full amount and records the fee as owed, so the amounts on this page exclude any fee owed.

When a custodian must accept a forwarded deposit before the receipts are usable, the gateway places a hold on the minted receipts in the client's wallet. The receipt is then visible but cannot be spent until the custodian accepts the coins or the deposit is returned.

## Where the receipt may move [#where-the-receipt-may-move]

A receipt can move in three ways. A client returns it to its own gateway to request a withdrawal, and the receipt waits locked in the gateway's escrow. The gateway sends it to the client, when a deposit mints it or when a request ends and the receipts return. The gateway burns it when it pays coins out.

A compliance rule that limits transfers to the client's own gateway keeps a receipt in a closed loop between a client and that gateway. The add-on refuses to enable a coin whose receipt lacks the rule, and it checks only at enablement. A holder of the receipt's governance role can still remove the rule later, or point the receipt at another compliance contract, and the add-on does not check again. Without it, the receipt's other compliance rules decide who may receive it, and a client may be able to send it to another eligible wallet. Those rules also keep applying to transfers into the gateway.

With the rule in place, a client cannot pass a receipt to another person or park it at another client's gateway, because the receipt would stop standing for coins that the client's own gateway holds. A forced transfer by the receipt's custodian role skips this rule and can move receipts to any wallet with a verified identity in the receipt's identity registry.

The same rule applies to minting. The gateway mints only to a wallet of its own client, and a deposit whose receiving wallet is not a wallet of that client rests as mint refused until the gateway managers decide.

A frozen client wallet cannot receive a mint, as on any other asset. [Custody gateway](https://docs.settlemint.com/docs/concepts/custody-and-signing/custody-gateway#how-a-deposit-moves) defines each deposit stage. Where the deposit goes depends on the screening mode and the path. With the default always-quarantine mode, the deposit rests in quarantine and clearing it fails while the wallet is frozen. A reported transfer that reaches the mint rests as mint refused. A direct deposit with screening off fails and leaves no record. Receipts returning from a cancelled request wait as return pending until the wallet is unfrozen.

## What counts as backing [#what-counts-as-backing]

Each receipt is backed through its own gateway's records, and the gateway never counts quarantined coins, unsupported transfers or unallocated coins as backing for a payout. The optional collateral compliance rule on the custody receipt can add a further check on supply.

## Frequently asked questions [#frequently-asked-questions]

### Does holding a custody receipt cost a fee?

No. The add-on refuses to enable a coin whose receipt carries a fee feature, so holding or moving it charges nothing unless such a feature is added later. Deposit and withdrawal fees are set in the gateway and apply when coins enter or leave.

### Does the receipt have a different number of decimals than the coin?

No. The add-on checks that the receipt and the coin have the same decimals when it enables the coin, so the receipt amount equals the coin amount without conversion.

### Who can mint a custody receipt?

A gateway created by the organisation's custody gateway add-on, and any account the organisation grants the supply management role. Leave that role unassigned so that gateways are the only minters, as [How the receipt is backed](#how-the-receipt-is-backed) explains.

## Related concepts [#related-concepts]

- [Custody Gateway](https://docs.settlemint.com/docs/concepts/custody-and-signing/custody-gateway): The deposit and withdrawal point that mints and burns custody receipts and pays coins out.
- [Custody Provider](https://docs.settlemint.com/docs/concepts/custody-and-signing/custody-provider): Who signs for the organisation's service wallets, separate from the receipt that clients hold.
- [Maker-checker](https://docs.settlemint.com/docs/concepts/custody-and-signing/maker-checker): The approval a change needs before it takes effect.


# Escrow add-on

Source: https://docs.settlemint.com/docs/concepts/custody-and-signing/escrow
An on-chain contract that holds tokens for their owners. One controller locks and pays units, and a token custodian can still force-transfer them.

An escrow is an on-chain contract that holds tokens for their owners while something is pending, such as an order waiting to fill, a cash-out waiting for the bank, or a custody gateway withdrawal waiting to be paid. Each escrow has one controller, such as a trading venue, a custody gateway or a bank rail wallet, which locks the owners' units and pays them out. Without an escrow, each feature would keep its own pooled balance with its own accounting, and the escrow gives every controller the same lock, payout and compliance rules. Every DALP system, the set of contracts an organisation deploys on a network, gets an escrow factory, and a controller asks that factory for an escrow it controls. A holder of the token's custodian role can still move an owner's units out of an escrow with a forced transfer, even while the owner is frozen.

A withdrawal from a managed custody wallet uses no escrow, and its hold is a gateway withdrawal record, as [Custody deposits and withdrawals](https://docs.settlemint.com/docs/concepts/custody-and-signing/custody-deposits-and-withdrawals) explains.

## What holds tokens in an escrow [#what-holds-tokens-in-an-escrow]

Three features ask the factory for an escrow. Each escrow is labelled when it is created, and the label is how an operator tells escrows apart.

| Feature | Escrows | What waits in the escrow |
| --- | --- | --- |
| Trading venue | One per venue, created with the venue and labelled with its name | The units each open order commits, until the order fills, is cancelled or expires. Each fill's legs, until delivery. |
| Custody gateway | One per client gateway, created with the gateway | Deposited tokens held back for screening, the gateway's own funding that pays withdrawals, and the custody receipts a client returns to withdraw |
| Bank rail wallet | One per network for the rail wallet of a delegate-mode token link, labelled "Bank rail" | The tokens of each cash-out, locked until the bank pays or the cash-out is released |

An XvP settlement does not use an escrow. Each sender's leg sits in the settlement contract itself until the settlement executes, is cancelled or expires. [XvP settlement](https://docs.settlemint.com/docs/concepts/settlement/xvp-settlement) explains that flow.

When a controller deposits for an owner, the escrow pulls the tokens from an approval the owner gave the escrow itself. A trader approves the venue's escrow once, and a bank rail client approves the rail wallet's escrow before a cash-out, so the escrow never takes more than the owner approved.

## Who controls an escrow [#who-controls-an-escrow]

An escrow has exactly one controller, fixed when it is created, and no roles of its own. Only the controller locks, unlocks, relocks and pays. Others can still move units without it: a token custodian through a [forced transfer](#forced-transfer), a [lost-wallet recovery](#recovering-a-lost-wallet) that moves unlocked units to the replacement wallet, the token's supply management role by burning at the escrow's address, a feature attached by the token's governance role together with Supply management and Custodian or the admin role, and a system manager or the add-on registry replacing the escrow's code. A controller that needs a second arrangement asks the factory for a second escrow.

Two kinds of caller can create an escrow: an add-on factory registered in the system, or a wallet that holds the system's escrow manager role. The bank rail is not an add-on, so it creates an escrow for its rail wallet through the escrow manager route. A controller of the zero address is refused.

Each escrow gets its own on-chain identity, registered with a country the creator names, and is placed on the system's compliance bypass list so that owners can deposit into it. On a token with the current compliance contract, a transfer into a bypass-listed address skips the rules that judge the recipient's eligibility, such as country and identity lists and identity verification. The address block list still checks the escrow's address.

Every escrow runs the implementation the factory points to. A holder of the system manager role, or the add-on registry, can move that pointer, which changes the code of every escrow of the system at once. The factory asks for no second approval, and it checks only that the new code reports two interfaces through ERC-165: the escrow interface and the interface of a contract with its own on-chain identity.

## What the escrow books [#what-the-escrow-books]

Per token and per owner, the escrow keeps an unlocked balance and any number of locks. The unlocked balance is what the owner may withdraw, which the API returns as `free` and the Console shows as `Free`.

- A deposit books an amount to the owner's unlocked balance. The owner deposits directly, or the controller deposits on the owner's behalf, pulling from the owner's approval. The escrow must receive exactly the amount it books, so a fee-on-transfer or rebasing token reverts.
- A withdrawal pays the caller's unlocked balance to the caller. It is refused while the token reports the caller frozen.
- A lock holds units until a date, after which the owner may take them back. A lock can also carry no owner exit, for units the owner already agreed to hand over, such as a matched trade.

Every unit an owner deposits is booked, so what the escrow owes in a token stays at or below its balance of that token. The exception is a token that moves tokens out itself, which [Sweep, and what the escrow cannot prevent](#sweep-and-what-the-escrow-cannot-prevent) explains. The contract's `owed` view reports what the escrow owes its owners in a token, and its `lockOf` view reports one lock, with an unopened identifier reading as all zeros.

The controller picks each lock's identifier. An identifier can be used once and stays used after the lock empties, so every lock and every event stays unambiguous. A new lock's end date must lie in the future unless the lock carries no owner exit.

## How a controller moves units [#how-a-controller-moves-units]

Only the controller posts moves, and a call applies its list of moves all or nothing. There are four kinds.

| Move | What it does |
| --- | --- |
| Lock | Takes units from the owner's unlocked balance into a new lock. |
| Unlock | Returns all or part of a lock to the owner's unlocked balance. |
| Relock | Moves all or part of a lock into a new lock of the same owner and token. |
| Pay | Pays from a lock to any eligible wallet, or from the unlocked balance to the owner only. |
| Book | Moves units from a lock into another owner's unlocked balance in the same escrow, with no token transfer. |

An Unlock, Relock, Pay or Book can take the whole remainder of a lock. A Book makes no call to the token, so it runs no compliance check. It still refuses a frozen lock owner, and a recipient that is the zero address, the escrow itself or on the bypass list. The trading venue uses it to park a delivery leg whose receiver the token refused: the units wait in the receiver's unlocked balance, and the receiver's withdraw runs the token's compliance again. A Relock that would move nothing reverts, so relocking a lock that a payout already emptied fails. A Pay from the unlocked balance that names anyone other than the owner reverts. A controller moves an owner's unlocked units to anyone else only by locking them first and paying the lock.

A Pay is the token's own transfer from the escrow, so the token's compliance runs on it and the owner's freeze check applies. One more rule covers recipients on the compliance bypass list:

- A Pay to a bypass-listed recipient is refused. A token's compliance can skip recipient-side checks for a bypassed account, so without this rule a controller could pay an owner's lock into a second escrow it controls.
- The controller itself is the exception. A custody gateway pays a client's locked custody receipts to itself to burn them when the client collects a withdrawal.

Anyone may reclaim an expired lock. Reclaim books the whole remaining lock back to its owner's unlocked balance and calls no token, so a token's rules cannot block it. A lock with no owner exit can never be reclaimed.

[Figure] How an owner's units move through an escrow. An owner wallet deposits into the owner's unlocked balance and withdraws from it. The controller locks units from the unlocked balance into a lock, which carries a reclaim date or no owner exit. A lock returns to free through an unlock by the controller or a reclaim by anyone after the date. A relock moves a lock into a new lock of the same owner and token. A Pay, the highlighted path, sends a lock to an eligible recipient through the token's compliance. Labels: deposit; withdraw; Lock; Unlock, reclaim; Relock; Pay; Owner wallet; approves the escrow; once; Unlocked balance; withdraw at any time; leaves only to its owner; Lock; Controller only; held until a date,; or with no owner exit; New lock; same owner and token; new date; Eligible recipient; the token's compliance; runs on the payout.

Deposits and withdrawals move the unlocked balance, the controller locks from it, and a lock leaves by unlock, reclaim, relock or a Pay under token compliance.

## The escrow claim and token compliance [#the-escrow-claim-and-token-compliance]

Some compliance rules check how long the sender has held the units. Every payout comes from the escrow, so those rules would block payouts until the escrow itself had held the units long enough.

The factory issues a `dalpEscrow` claim to each escrow's identity, and the Console shows the claim's topic as "Escrow account". By default the platform binds a time-lock rule to that claim as a sender exemption. A sender that carries the claim skips the rule's check, so a payout from the escrow passes. The rule runs in accounting-only mode for that sender: it still records the transfer but does not refuse it. The owner's deposit runs the token's sender-side rules, such as the time lock and the address block list, with the owner as sender. The recipient-side rules, such as country and identity lists, identity verification and transfer approval, skip the escrow because it is on the bypass list. On a token that uses the first version of the system compliance contract, a deposit into the escrow skips every rule. Units paid back to their owner restart the owner's holding clock. [Composable token](https://docs.settlemint.com/docs/concepts/modeling-assets/composable-token) describes the compliance modules.

A minimum-holding rule is configured differently: it lists `dalpEscrow` among its exempt claims by default. The escrow's own pool may then sit below the minimum, while the owner on a deposit and the recipient on a payout still have to clear it. The issuer can change or remove either setting in the token's compliance settings.

The factory issues the claim when the system has registered the `dalpEscrow` topic and trusts the factory's identity to issue it. Until a system has both, a new escrow gets no claim, these exemptions do not apply to its payouts, and anyone may add the claim later through the factory.

## A corporate action re-bases the escrow [#a-corporate-action-re-bases-the-escrow]

A stock split, bonus issue or other [corporate action](https://docs.settlemint.com/docs/console/asset-management/manage/corporate-actions) that changes every holder's units by a ratio changes what an escrow holds for its owners. The platform counts each owner's free balance and each open lock as if the owner held them directly, and the action mints to or burns from the escrow the sum of those amounts. The escrow keeps a per-token log of the action's steps. Each free balance and each lock moves to the new basis the next time it is read or used, with the action's own rounding, so a round-up-to-one never leaves the escrow owing more than it holds.

To keep the records equal to the units while that happens, the action freezes the escrow for the token. From the action's record date until its step lands, the escrow refuses deposits, withdrawals, reclaims, new locks, relocks, payouts from a lock, sweeps, forced transfers and recoveries of that token. The refusal names the token and the action. An unlock of a whole lock is still accepted, because a venue cancels an order that way: the lock is released to its owner, and its units move to the owner's free balance once the action's step has landed. An unlock of part of a lock is refused. An account with the token's supply management role installs the freeze before the record date, and writing the step lifts it in the same call. A trading venue or custody gateway that rides the escrow is frozen with it, apart from the venue's own order cancels and the gateway's returns caused by the action.

## Sweep, and what the escrow cannot prevent [#sweep-and-what-the-escrow-cannot-prevent]

Tokens can reach the escrow address by a plain transfer that books them to no owner. A sweep pays out exactly the part of the token balance that exceeds what the escrow owes, and only the controller may send it. When the balance is at or below the debt, the sweep reverts with nothing to sweep.

The token can force-transfer from the escrow's address, burn from it, or apply a negative rebase, a supply adjustment that lowers every balance. The escrow cannot prevent any of these. Such a move can leave it owing more than it holds. `owed` reports the debt so monitoring can compare it with the balance.

## Forced transfer [#forced-transfer]

A holder of the token's custodian role, the role that may freeze an address and force a transfer, can move an owner's units out of the escrow, even while the owner is frozen. The transfer draws the owner's unlocked balance first, then each lock the caller names, in the order given. Its event names each lock and the amount drawn from it. A lock of another owner or token is refused, and so is an amount larger than the unlocked balance plus the listed locks. Through the Platform API, a lock that is no longer open is refused as well.

For a DALP token the caller must hold the token's custodian role. For a plain ERC-20 only the controller may do it. Either way the recipient must still be one the token accepts.

Through the Platform API, a token custodian sends `POST /api/v2/addons/escrows/{escrowAddress}/forced-transfers` with the token, the owner, the recipient, the amount and up to 32 lock identifiers. The request needs wallet verification, and it takes an `Idempotency-Key` header for safe retries. The route decides whether units that a bank rail cash-out still depends on may move, and where they go. The escrow contract checks none of that, so a custodian who calls the escrow directly can move those units to any recipient the token accepts. [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 route's rules. [Escrows in the Console](https://docs.settlemint.com/docs/console/asset-lifecycle/escrows) shows how to find the owner, token and lock identifiers.

The Platform API refuses a forced transfer from an escrow sent through the token's own route, `POST /api/v2/tokens/{assetId}/forced-transfers`, both at its preflight and at the write, with `422 TOKEN_FORCED_TRANSFER_FROM_ESCROW` and a message that names the escrow, because it would leave the escrow's balances and locks wrong. Send it through this route instead. The token contract does not refuse it.

## Recovering a lost wallet [#recovering-a-lost-wallet]

Anyone may move a lost wallet's unlocked balance to the wallet its identity registry names. The registry must mark the old wallet lost and name its replacement, and the token must not report the old wallet frozen. Locks stay with the lost wallet until they are unlocked or reclaimed, so recovery moves unlocked units only. A holder of the identity manager role marks the wallet lost and names its replacement, so that role decides where the units go.

## Reading escrows [#reading-escrows]

A platform administrator or the organisation's owner can list escrows and open one to see its balances, locks and history. Every other caller gets not found.

- `GET /api/v2/addons/escrows` lists every escrow the system's escrow factory created, with the kind of add-on that controls it, the controller, how many tokens it holds, what it holds per token and its open locks. The add-on kind is `trading-venue` or `other`, and `other` covers every controller that is not a trading venue, such as a custody gateway or a bank rail wallet. The list takes a page window, `filter[addonKind]`, and a `sort` over label, controller, token count, open lock count or creation time, with a leading minus for descending. `meta.facets` counts every escrow in scope per add-on kind, whatever the filter.
- `GET /api/v2/addons/escrows/{escrowAddress}` reads one escrow with its evidence: the label it was given, its controller, its factory, its identity and country, and its creation time.
- `GET /api/v2/addons/escrows/{escrowAddress}/balances` lists each owner's unlocked and locked units per token.
- `GET /api/v2/addons/escrows/{escrowAddress}/locks` lists each lock with its owner, token, amount, reclaim time, status and open time, and takes `filter[status]`.
- `GET /api/v2/addons/escrows/{escrowAddress}/events` lists the escrow's history, newest first.

The balances, locks and events reads each take a page window and their own `sort`. An escrow outside the caller's system, or one whose escrow factory is archived, answers as not found.

A lock status is `open` while units remain. Once a lock empties, the status names the move that emptied it: `unlocked`, `relocked`, `paid`, `booked`, `reclaimed` or `forced`.

The Console shows the same escrows under Asset lifecycle › Escrows, described in [Escrows](https://docs.settlemint.com/docs/console/asset-lifecycle/escrows).

## Related pages [#related-pages]

- [Composable token](https://docs.settlemint.com/docs/concepts/modeling-assets/composable-token): the compliance modules that decide whether a deposit or a payout passes.
- [Custody gateway](https://docs.settlemint.com/docs/concepts/custody-and-signing/custody-gateway): an add-on that asks the factory for one escrow per client gateway.
- [Custody receipt](https://docs.settlemint.com/docs/concepts/custody-and-signing/custody-receipt): the token a client returns to its gateway, locked in the gateway's escrow, when it withdraws.
- [Trading venue](https://docs.settlemint.com/docs/concepts/issuing-and-markets/trading-venue): an add-on that holds an order's committed units in its escrow until a fill, a cancel or expiry.
- [XvP settlement](https://docs.settlemint.com/docs/concepts/settlement/xvp-settlement): settlement that holds each side's leg in its own contract until the exchange.
- [Bank rail API](https://docs.settlemint.com/docs/api-reference/guides/bank-rail): the cash-out flow that locks a client's tokens in the rail wallet's escrow.
- [Custody deposits and withdrawals](https://docs.settlemint.com/docs/concepts/custody-and-signing/custody-deposits-and-withdrawals): the direct custody route, which holds in the gateway withdrawal record and uses no escrow.


# External signing

Source: https://docs.settlemint.com/docs/concepts/custody-and-signing/external-signing
Sign an EVM write with a key the platform never holds. A transaction preparation binds the write, records your submission and links it to one request.

External signing lets the holder of a custody account sign a write on an EVM network with a key the platform never holds, and still have the platform record that write in its [transaction lifecycle](https://docs.settlemint.com/docs/concepts/settlement/transaction-lifecycle). It works through a transaction preparation, a record that binds one write, its signer and its network for ten minutes. A retry of the same prepare or finalise call records one write, and a new preparation is a new write.

The preparation covers custody accounts linked through Privy, Dynamic or a browser wallet, the three providers that leave signing to the holder. The key sits with the holder's wallet or wallet provider. The alternative is the regular API route, where the platform asks a managed custody provider to sign for the account.

## Keeping keys in your own HSM or custody system [#keeping-keys-in-your-own-hsm-or-custody-system]

Choose one of two setups.

- **Connect it as a managed custody provider.** The platform connects to IBM Digital Asset Haven, DFNS, Fireblocks, Luna HSM, Ripple custody and Utila as managed providers, and its own platform key store is managed too. The key stays in the HSM or the provider's system, the provider's policy or quorum decides whether to sign, and the platform asks for each signature. This is managed signing, and the preparation routes on this page refuse these accounts. The [custody provider](https://docs.settlemint.com/docs/concepts/custody-and-signing/custody-provider) page describes the providers, and the [custody approval](https://docs.settlemint.com/docs/concepts/custody-and-signing/custody-approval) page describes how their policy holds a signature.
- **Hold the key as a self-custody account and sign through preparations.** The account's EVM address is linked to a self-custody provider configuration. You sign each prepared write yourself, and the platform checks the result against the preparation. An HSM the platform has no managed connector for can take this route when a wallet that speaks EIP-1193 fronts its EVM key and is linked as a browser wallet. That wallet signs the challenge that links the address, then signs each prepared write.

On the second route the platform never receives the signed transaction bytes. For a plain transaction, your wallet or service sends the transaction to the network and then reports the sender, the nonce, which is the sending address's sequence number, and the transaction hash. The platform checks what you report against the frozen write and follows the nonce on the network. It does not check which device produced the signature, so the evidence that a key sits in an HSM comes from your own key management.

Linking the address starts with `POST /api/v2/users/me/custody-account-control-preparations`, which returns a challenge for one enabled self-custody provider configuration and one EVM address. [Choose investor custody](https://docs.settlemint.com/docs/api-reference/guides/choose-investor-custody) walks through the linking calls.

## Signing setups the preparation accepts [#signing-setups-the-preparation-accepts]

The preparation records its signing method in `signingMethod`. Two values are possible on these routes, and the user-operation method has two ways to reach the network.

| Setup | `signingMethod` | Executor, the address that sends the write | Who signs | Who sends it to the network | Request state at finalise |
| --- | --- | --- | --- | --- | --- |
| Browser wallet transaction | `eip-1193-transaction` | The custody account's own address | The holder's wallet | The holder's wallet | `BROADCASTING` |
| Owner-signed user operation | `eip-4337-user-operation` | The participant's smart wallet | The holder, as the smart wallet's owner | The platform | `QUEUED`, then execution starts |
| Provider-submitted user operation | `eip-4337-user-operation` | The participant's smart wallet | The holder | The holder's wallet provider | `BROADCASTING` |

A [smart wallet](https://docs.settlemint.com/docs/concepts/custody-and-signing/smart-wallet) is a contract account that acts through user operations, signed instructions an EntryPoint contract validates and executes. [User operations](https://docs.settlemint.com/docs/concepts/custody-and-signing/user-operations) covers the bundler that sends them.

The platform picks the method when you prepare. You ask for `executionMode` `prefer-aa`, which uses the smart wallet, through account abstraction, when it can, or `direct`. With `prefer-aa` the preparation is an owner-signed user operation, and the smart wallet is the executor, when two conditions hold: the provider supports account abstraction, and the participant has a smart wallet on that network whose owner is the custody account's address. In every other case, and with `direct`, the preparation is a browser wallet transaction from the custody account's own address. The user-operation path needs a smart wallet with a single owner key. A smart wallet that uses weighted signers is refused with a binding conflict.

The preparation routes refuse managed signing. A custody account whose provider holds the key gets `DALP-14032` on the prepare call, and a finalise call that carries a managed authorisation gets `DALP-14033`. For that account, send the write through its regular API route.

## Who can prepare and sign [#who-can-prepare-and-sign]

The three preparation routes accept a signed-in session or an API key, and they require no organisation role. The custody account decides eligibility. It must be active, belong to the participant the request acts as, and hold an eligible organisation context on an enabled EVM network. Its provider configuration must serve that network, and its executor wallet must not be archived. A request that fails any of these gets `DALP-14032`.

A preparation belongs to the user and organisation that created it. Any other user or organisation that reads or advances it gets `DALP-14031`, the same answer as for a preparation that does not exist.

## What a preparation binds [#what-a-preparation-binds]

The prepare call fixes these facts and stores a digest over them: the calling user, the participant, the organisation, the custody account, its provider configuration, the network, the executor and the source address, the operation's kind and its digest, the summary, the signing method and the expiry. Each later claim, attachment and finalise call is checked against the stored facts it touches.

Send an `Idempotency-Key` header on the prepare call. The key belongs to the calling user. A repeat with the same key and the same binding returns the stored preparation. The same key with a different binding is refused with `DALP-14033`. Without the header, each call creates a new preparation.

The preparation expires ten minutes after it is created. A preparation that nobody has claimed cannot be claimed or finalised after that time.

## Steps from prepare to transaction request [#steps-from-prepare-to-transaction-request]

**Step 1 of 6**

### Prepare the write [#prepare-the-write]

Call `POST /api/v2/transaction-preparations` with `custodyAccountId`, `executionMode`, a `summary` and the `operation`: its `kind`, `contractAddress`, `callData` and an optional `value`. The response is the preparation in state `prepared`. It names the `signingMethod`, the `executor`, the `expiresAt` time and, for a user operation, `preparedUserOperation` with the `userOperationHash` and the `previewData` of the operation.

For a user operation the platform builds a preview before you sign. When the organisation's gas payer on that network is Paymaster-paid, the preview carries the paymaster's sponsorship, so the smart wallet pays no gas. Otherwise a smart wallet that cannot cover the gas and the native currency the operation sends gets `DALP-14034`, with `smartWalletAddress`, `heldWei` and the missing `shortfallWei`. A smart wallet can hold one open owner-signed operation per network. A second one is refused with `DALP-14033` until the first finishes or expires.

**Step 2 of 6**

### Read the preparation [#read-the-preparation]

`GET /api/v2/transaction-preparations/{preparationId}` returns the bound write and its progress: the signing method, the expiry, the submission claim, the attached handle or artifact and, once finalised, `transactionRequestId`.

**Step 3 of 6**

### Claim the submission before anything is sent [#claim-the-submission-before-anything-is-sent]

Call `POST /api/v2/transaction-preparations/{preparationId}/transitions` with `action` set to `claim`. A claim reserves one submission attempt. Repeating a claim with the same `claimKey` succeeds, so choose a key you can regenerate.

- **Browser wallet transaction.** The claim has `submissionKind` `eip-1193`, a `claimKey`, and the `sender`, `chainId`, `nonce`, `to`, `value` and `data` you are about to send. They must match the prepared sender, network, destination, value and call data. The claim reserves that sender, network and nonce against every other preparation. The body also requires a `startBlock`, but the platform ignores its value and records the network's current block as the start of its search for the transaction.
- **Provider-submitted user operation.** The claim has `submissionKind` `provider-handle` and a `claimKey`. It applies only to a user-operation preparation, and the key cannot belong to another preparation under the same provider configuration.
- **Owner-signed user operation sent by the platform.** Make no claim. Go to finalise.

**Step 4 of 6**

### Sign the write, and send it from your wallet [#sign-the-write-and-send-it-from-your-wallet]

For a browser wallet transaction, the wallet signs and sends the claimed transaction. Once it is sent, the nonce is used and the claim can no longer be abandoned.

For a user operation, sign the `userOperationHash` the preparation returned. The platform recovers the signer from that hash with no prefix added. A personal-message signature adds a prefix, so it does not recover to the account. A typed-data signature works when its hash equals `userOperationHash`.

On the provider path, record the provider's handle with `action` `attach` and an `attachment` of `claimKey` and `providerHandle`. The handle must name the active claim. A repeat of the same handle succeeds, and a different handle is refused with `DALP-14240`.

**Step 5 of 6**

### Finalise [#finalise]

Finalising cannot be undone: a consumed preparation stays linked to its transaction request. It links the preparation to a request and does not prove the chain executed the call, so follow the request to a terminal status.

Call the transitions route with `action` `finalize` and an `artifact` whose `kind` matches the prepared signing method. The artifact also carries a `_tag`: `Eip1193TransactionAuthorization` for a browser wallet transaction and `Eip4337UserOperationAuthorization` for a user operation.

- **Browser wallet transaction.** The artifact carries `sender`, `chainId`, `nonce` and `transactionHash`, which is `null` when the wallet returned no hash. It must match the persisted claim.
- **Owner-signed user operation.** The artifact carries `userOperationHash` and `signature`. The platform checks that the hash is the prepared one, recomputes it from the operation's own fields, requires a canonical signature and verifies that it recovers to the custody account's address. The request enters the queue and the platform starts execution.
- **Provider-submitted user operation.** The same artifact, finalised against the claim that holds the handle. The platform checks the hash against the prepared one. It does not recompute the hash or verify the signature on this path, because the provider submitted the operation. The EntryPoint verifies the signature when it executes the operation, so a bad signature fails on chain.

The response is the preparation in state `consumed`, with `transactionRequestId`. A repeat with the same artifact returns the same request, and a different artifact is refused with `DALP-14033`.

**Step 6 of 6**

### Follow the transaction request [#follow-the-transaction-request]

Read `GET /api/v2/transaction-requests/{transactionId}`, or its `/stream`, until `status` is `COMPLETED`, `FAILED`, `DEAD_LETTER` or `CANCELLED`. Keep reading a `DEAD_LETTER` request, one the platform stopped retrying, while its `mayStillLand` is `true`, because its call can still land. A write that your wallet already sent enters as `BROADCASTING`, and confirmation tracking follows a request that carries a transaction hash. An owner-signed user operation enters as `QUEUED` and runs the platform's execution from there.

To release a provider claim that has no handle, call the transitions route with `action` `abandon`. The preparation returns to `prepared`. Claim again with a new key, because the preparation refuses every key it has abandoned. A browser wallet claim cannot be abandoned, because its nonce may already have reached the network. A claim that holds a provider handle cannot be abandoned either.

## Preparation states [#preparation-states]

[Figure] A preparation moves through four states and ends consumed or expired. Four states: prepared, submission-claimed, consumed and expired. A claim moves prepared to submission-claimed, and an abandon moves a provider claim back to prepared. Finalise moves submission-claimed to consumed. Finalising an owner-signed user operation moves prepared straight to consumed, and the platform submits it. Ten minutes passing moves an unclaimed preparation to expired. For an expired browser wallet claim, reconciliation moves it to consumed when the wallet's nonce moved past the claim, and to expired when the nonce is still open. Labels: Claim; Abandon; Finalise; Nonce moved; Finalise, platform submits; Ten minutes pass; Nonce still open; prepared; bound for ten minutes; submission-claimed; one attempt reserved; consumed; linked to one request; expired; prepare again; a call you make; time passing or platform reconciliation.

Your calls move a preparation through `prepared`, `submission-claimed` and `consumed`, and time or reconciliation moves it to `expired` or `consumed`.

A preparation has four states, and the read returns the current one in `state`.

- `prepared`: the write is bound and nothing is claimed. A claim moves it to `submission-claimed`. Finalising an owner-signed user operation moves it straight to `consumed`, and the platform submits the operation.
- `submission-claimed`: one submission attempt is reserved. Finalise moves it to `consumed`. An abandon moves a provider claim without a handle back to `prepared`.
- `consumed`: the preparation is permanently linked to its transaction request.
- `expired`: the write can no longer be claimed or finalised, and no transaction request exists for it. Prepare the write again.

An unclaimed preparation expires ten minutes after it is created. A claim or finalise call after that time is refused with `DALP-12012`. The platform records the `expired` state when it refuses a claim or a finalise. Until then, the read can still show `prepared` with an `expiresAt` time in the past.

A claimed provider submission does not expire on its own. Finalise it, or abandon it while it has no handle.

## When a browser wallet claim outlives its preparation [#when-a-browser-wallet-claim-outlives-its-preparation]

A browser wallet claim whose ten minutes have passed is checked by the platform's background reconciliation, which reads the sender's nonce on the network.

- When the pending nonce equals the reserved nonce and the confirmed nonce has not passed it, nothing was sent. The preparation expires and the claim key is retired.
- When the pending nonce has moved past the reservation but the confirmed nonce has not, the wallet sent something that the network has not mined. The platform consumes the preparation and records a `BROADCASTING` request with the claimed sender, network, nonce and start block, and no transaction hash. It starts no new execution.
- When the confirmed nonce has moved past the reservation, the platform looks for the transaction that used the nonce in a finalised block. When that transaction has the claimed destination, value and call data, the platform consumes the preparation and records a `BROADCASTING` request with that transaction hash, so confirmation tracking follows it. When it finds no such transaction, or the transaction carries another call, it leaves the preparation as it is.
- A nonce slot that is blocked, or that the network does not answer for, leaves the preparation as it is.

A request recorded without a transaction hash shows only that the wallet sent some transaction at that nonce. It does not prove that the intended call succeeded, and confirmation tracking skips a request without a transaction hash. Check the network for the wallet's transaction at that nonce before you send anything again.

## Writes that need more than one step [#writes-that-need-more-than-one-step]

Some Console and Investor portal flows need several writes in order, such as an approval followed by a purchase. The public prepare route prepares one operation. A platform flow prepares the sequence itself. For a smart wallet it prepares one user operation that carries the extra calls, with the final write last. For a plain wallet it prepares one linked preparation per step, and the read names the earlier step a preparation waits on.

A linked step can be claimed only after the earlier step's transaction request is `COMPLETED`. Until then, its claim is refused as pending, even when the earlier step is only claimed. When the earlier request failed, was cancelled, or was dead-lettered with `mayStillLand` reading `false`, the claim is refused as failed and the whole sequence must be prepared again. While a dead-lettered earlier request may still land, the claim stays refused as pending. A step whose own time ran out, or whose earlier step expired, is refused as expired.

## Refusals and what the caller does [#refusals-and-what-the-caller-does]

When the preview of an owner-signed write reverts, the call answers `422` with the contract's own error, such as `DALP-1009` for a compliance refusal, or `DALP-0447` with `revertData` when the catalogue does not know the revert. No preparation is stored. A token write that a browser smart wallet signs answers the same way, with the contract's error instead of a generic queue refusal. A preview that the platform refuses without revert bytes stays a binding conflict, `DALP-14033`.

| Kind | Code | HTTP | What the platform observed | What the caller does |
| --- | --- | --- | --- | --- |
| Expired | `DALP-12012` | 410 | The ten minutes ran out before an unclaimed preparation was claimed or finalised, or an earlier step of its sequence expired. | Prepare the write again. Nothing was recorded as a transaction request. |
| Claim conflict | `DALP-14240` | 409 | The preparation already holds a different claim, the claim key was abandoned, the sender and nonce belong to another preparation, the claimed transaction is not the prepared one, the artifact has no matching claim, or the provider handle differs. | Read the preparation. Resume the claim you hold, or wait until the other preparation that holds the nonce is sent or expires. |
| Binding conflict | `DALP-14033` | 409 | The call does not match how the preparation is bound: another signing method or executor, a managed authorisation, a signature that does not recover to the account, a reused idempotency key with another binding, a smart wallet with weighted signers, or a second open owner-signed operation on the same smart wallet. | Send the claim, attachment or artifact that matches `signingMethod` and `executor`. Use a new idempotency key for a different write. |
| Preimage mismatch | `DALP-14241` | 409 | The user operation hash in the artifact is not the prepared one. | Sign the `userOperationHash` the preparation returned. |
| Pending | `DALP-14429` | 409, retryable | An earlier step of the sequence has no completed transaction request. | Wait for the earlier step to complete, then claim again. |
| Failed | `DALP-14430` | 409 | An earlier step of the sequence failed, was cancelled, or was dead-lettered and cannot land. | Prepare the sequence again. This step can never be claimed. |
| Not found | `DALP-14031` | 404 | No preparation with this id belongs to the calling user and organisation. | Use the id the prepare call returned to you. |
| Ineligible account | `DALP-14032` | 422 | The custody account is managed, inactive, held by another participant, not eligible on this network, or its executor wallet is archived. | Prepare with a self-custody account you hold on that network. |
| Smart wallet gas | `DALP-14034` | 422 | The smart wallet cannot cover the operation's gas and the native currency it sends, and the paymaster does not pay for it. `data` names `smartWalletAddress`, `heldWei` and `shortfallWei`. | Send at least `shortfallWei` to the smart wallet, then prepare again. |

The [Platform API error reference](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference#domain-rule-errors) lists each code with its full text.

## In the Console and the Investor portal [#in-the-console-and-the-investor-portal]

The Console's token transfer sheet and the Investor portal use the browser wallet path for a custody account linked to a browser wallet. Both need writable browser storage and the browser's lock API. They store each submission attempt, so a reload resumes a matching recorded attempt and does not send it again. When a submission stops, the Console names the reason with messages such as these:

- "The transaction expired before the wallet sent it, so the platform can no longer record it. Start the transaction again."
- "Another session holds the wallet submission for this transaction. Finish it there."
- "Another transaction from this wallet holds its next nonce until it is sent or expires. Finish that transaction, or start this one again in ten minutes."
- "The wallet may have sent the transaction, but the platform could not record it. Check the wallet's activity before sending anything again."

## Terms that sound similar [#terms-that-sound-similar]

Three other pages use a similar term for something different.

- The [custody approval](https://docs.settlemint.com/docs/concepts/custody-and-signing/custody-approval) page describes an external custody provider or HSM whose policy decides whether to release a signature the platform asked for. That is managed signing, which these routes refuse.
- [Multisig](https://docs.settlemint.com/docs/concepts/custody-and-signing/multisig) describes an external seat: a signer address on a weighted smart wallet with no platform identity behind it. A weighted smart wallet cannot use the owner-signed path on this page.
- [Single sign-on](https://docs.settlemint.com/docs/deployment/sso) describes external sign-in to the Console through an OpenID Connect identity provider. It decides who signs in, and it signs no transaction.

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

- After you prepare a write and finalise it, reading the preparation shows `state` as `consumed` and `transactionRequestId` set. Keep the `preparationId` to read it back.
- The transaction request reaches a terminal `status`.
- For a browser wallet transaction, the request's `transactionHash` matches the hash the wallet returned.

## Related pages [#related-pages]

Read [custody provider](https://docs.settlemint.com/docs/concepts/custody-and-signing/custody-provider) for the managed and self-custody providers, [smart wallet](https://docs.settlemint.com/docs/concepts/custody-and-signing/smart-wallet) for the account an owner-signed operation spends from, [Embed a Privy wallet](https://docs.settlemint.com/docs/api-reference/guides/embed-a-privy-wallet) for a worked user-operation example, and [Transaction lifecycle](https://docs.settlemint.com/docs/concepts/settlement/transaction-lifecycle) for the path a request follows once it is recorded.


# How gas is paid and funded

Source: https://docs.settlemint.com/docs/concepts/custody-and-signing/gas-funding
What happens to a write when the paying wallet runs out of gas, how the gas payer models differ, and the Platform API routes behind Transaction funding.

The platform sends the organisation's transactions from paying wallets, and the organisation or the user keeps those wallets funded with the network's fee, called gas. When a wallet runs short on a network that charges gas, the platform pauses the write and records a funding requirement that names the wallet and the amount. It resumes the write if the wallet is funded within the funding window. The Console shows a funding requirement as a funding request. The Console side of this, where an operator reads who pays, tops up a wallet and changes the gas payer, is [Transaction funding](https://docs.settlemint.com/docs/console/organisation-settings/transaction-funding).

## When a wallet runs out of gas [#when-a-wallet-runs-out-of-gas]

The platform pauses a write for funding only after the network refuses it because the paying wallet cannot cover its gas. A forecast of the gas need sizes the amount but never starts a pause. The one exception is when the platform sets up or repairs an organisation's bundler wallet: it checks the balance and raises a requirement without a refused write. The refused wallet can be a user's signing wallet, a smart wallet, the relayer wallet, the bundler wallet, or the paymaster deposit.

The platform then records a funding requirement for that wallet on that network. It holds the minimum amount the wallet needs, a larger recommended amount that also covers fee changes and the next operations, and the balance the platform saw. Only one requirement is active per organisation, network and wallet, so a second write that runs short on the same wallet joins it. While a write waits, its transaction request keeps its state and its status names the requirement. A smart-wallet operation that the bundler finds short when it builds a bundle waits the same way and joins the next bundle once its smart wallet or the paymaster deposit is funded. [User operations](https://docs.settlemint.com/docs/concepts/custody-and-signing/user-operations) covers how to read an operation's status.

[Figure] How a write paused for gas ends. The network refuses a sent write for gas, so the platform pauses it under an active funding requirement. A top-up resolves the requirement and the write resumes. If the funding window closes first, the requirement expires and the write fails with DALP-9087. One top-up releases every write waiting on the same wallet. Labels: Write sent; queued transaction; Network refuses; not enough gas; Paused; requirement active; Resumes; top-up observed,; requirement resolved; Fails, DALP-9087; window closed,; requirement expired; One top-up releases every write waiting on the same wallet.

A paused write ends in one of two ways: a top-up resolves its requirement, or the funding window closes.

A requirement has one of three statuses:

| Status | Meaning | Waiting writes |
| --- | --- | --- |
| `active` | The wallet is short. A notice shows at the top of Transaction funding. | Wait. |
| `resolved` | The platform observed enough funds on the wallet. | Resume, all of them, on one top-up. |
| `expired` | The funding window closed first. | Fail with the gas required error, `DALP-9087`. |

The funding window is a gas setting of each network, 30 minutes unless a platform administrator sets another value from 60 seconds to 7 days. [Gas settings](https://docs.settlemint.com/docs/deployment/gas-settings) covers it and the settle delay: when a wallet shows enough funds but the node still refuses the write, the platform waits that delay, 2 minutes by default, and sends again up to five times.

Some writes do not pause:

- On a network that charges no gas, a write never pauses for funds.
- A caller can decline the pause and get a fast failure instead, as [Fund through the API](#fund-through-the-api) shows.
- A smart-wallet write that needs more than one signer to approve fails on a shortfall instead of pausing.

The person who must fund a wallet hears about it by email. A user's own wallet emails each person who holds it, and a wallet with no person holder emails the organisation's owners. The email names the network, the wallet address and the minimum balance the wallet needs. A request for the relayer wallet, the bundler wallet or the paymaster deposit sends no email: those show as notices on [Transaction funding](https://docs.settlemint.com/docs/console/organisation-settings/transaction-funding) and on the home dashboard.

A user can cancel a write paused on their own EOA wallet while it waits. [Transaction lifecycle](https://docs.settlemint.com/docs/concepts/settlement/transaction-lifecycle) covers cancellation in other states.

## Choose a gas payer [#choose-a-gas-payer]

Two settings decide who pays gas when a user of the organisation signs a transaction. They change which wallet pays the fee and what you keep funded, and the fee itself stays the same. [Gas sponsorship](https://docs.settlemint.com/docs/concepts/custody-and-signing/gas-sponsorship) explains how each choice reaches the network.

- **Wallet type**, one choice for the whole organisation, between EOA wallets and [smart wallets](https://docs.settlemint.com/docs/concepts/custody-and-signing/smart-wallet) with approvals and recovery. The move from EOA wallets to smart wallets is permanent, and is made in the "Wallet type" row of [Transaction funding](https://docs.settlemint.com/docs/console/organisation-settings/transaction-funding#change-the-wallet-type).
- **Gas payer**, one choice per network. With EOA wallets, each user pays under "Self-pay" or the organisation's relayer pays under "Relayer-paid". With smart wallets, each smart wallet pays under "Self-pay" or the organisation's paymaster pays under "Paymaster-paid".

The organisation picks its wallet type and a preferred gas payer during [onboarding](https://docs.settlemint.com/docs/getting-started/onboarding). The first network takes that payer. When the deployment sets up a network's paymaster without a ready sponsorship signing key, sponsorship stays off there until an operator turns it on. Each network added later starts on Self-pay, and after a move to smart wallets every network starts on Self-pay. You change the gas payer one network at a time with [Change gas payer](https://docs.settlemint.com/docs/console/organisation-settings/transaction-funding#change-the-gas-payer).

| Wallet type and gas payer | Who pays gas | What you keep funded | Can you leave it |
| --- | --- | --- | --- |
| EOA wallets, Self-pay | Each user's own wallet | Each signer's wallet that runs short | Yes, per network |
| EOA wallets, Relayer-paid | The relayer wallet on that network | The relayer wallet | Yes, per network |
| Smart wallets, Self-pay | Each smart wallet, which repays the bundler | The bundler wallet and each smart wallet | Per network, not back to EOA |
| Smart wallets, Paymaster-paid | The paymaster deposit, which repays it | The bundler wallet and the paymaster deposit | Per network, not back to EOA |

[Figure] How a write reaches the network for each gas payer. EOA wallets with Self-pay: the EOA wallet signs, submits and pays. Relayer-paid: the EOA wallet signs, and the relayer wallet submits and pays through the forwarder contract. Smart wallets: the smart wallet signs, and the bundler submits through the EntryPoint and fronts the gas. Under Self-pay the smart wallet pays the bundler back, under Paymaster-paid the paymaster deposit does. Labels: EOA, Self-pay; EOA wallet signs, submits and pays, then target contract; EOA, Relayer-paid; EOA wallet signs, relayer wallet submits and pays,; forwarder contract, then target contract; Smart, Self-pay; Smart wallet signs, bundler fronts the gas, EntryPoint,; target contract, then the smart wallet pays the bundler back; Smart, Paymaster-paid; Smart wallet signs, bundler fronts the gas, EntryPoint,; target contract, then the paymaster deposit pays it back.

On a network that charges no gas, the same route runs and no fee is paid.

**Self-pay** suits users who already hold the network's currency, and networks that charge no gas, where the other payers only add a step. With EOA wallets, nothing on the organisation's side needs funding, but a signer who runs short waits until someone funds that signer.

**Relayer-paid** suits users who keep EOA wallets and should never hold gas. The organisation funds one wallet per network instead of one per user. The user's wallet signs a request, called a meta transaction. The relayer wallet sends it to the platform's forwarder contract and pays the fee, and the target contract records the user as the sender. The relayer cannot alter a signed request, because the forwarder rejects one whose signature does not match. It can delay sending it.

**Paymaster-paid** suits smart-wallet users who should never hold gas. The bundler wallet submits each operation and fronts the gas, and the paymaster's deposit at the EntryPoint contract pays it back in the same transaction. Both must stay funded. Choosing Paymaster-paid turns sponsorship on for that network, and choosing Self-pay turns it off. The paymaster contract stays deployed while sponsorship is off, and turning it off does not refund the deposit.

### What Relayer-paid does not cover [#what-relayer-paid-does-not-cover]

The relayer pays only for transactions it can relay:

- The forwarder accepts signatures from EOA wallets only, so a transaction from a smart-wallet sender fails at once.
- When the target contract does not accept the forwarder, the user's own wallet pays for that transaction, as with Self-pay.
- The relayer does not fund native currency that a call sends with it, so such a transaction fails at once.
- When the user's custody provider cannot sign the request, the transaction fails with an error that names the provider.

The platform sends one relayed transaction per user wallet per network at a time, because the forwarder runs each user's requests in a fixed order. The next one from the same wallet waits, for at most one hour, until the previous one completes. Transactions from different users do not wait for each other.

A relayed transaction can be cancelled until it is confirmed: the relayer then sends an empty transaction in its place.

### Changing who pays [#changing-who-pays]

A switch changes how new transactions on that network are paid. A transaction the platform already prepared for the relayer still goes through the relayer. Users keep the same wallet addresses, so a switch moves no assets and changes no user's permissions. It changes the address that sends new transactions. The transactions that deploy the organisation are paid by the deploying wallet, whatever you choose.

Switching a network to Relayer-paid creates a relayer wallet on that network. Until the relayer holds enough, user transactions on that network wait for funding. Switching back to Self-pay stops the relayer paying, and the relayer keeps its balance. It shows as "Idle" in the **Wallets** table, where a Permission manager can [withdraw](https://docs.settlemint.com/docs/console/organisation-settings/transaction-funding#withdraw-from-an-idle-wallet) it. Switching that network back to Relayer-paid later reuses the same relayer wallet and its balance.

## Fund through the API [#fund-through-the-api]

The Platform API reads and changes the same funding state. A system route acts on the organisation's default network unless the request sends `X-Chain-Id` with another chain ID. Amounts are decimal strings in wei, the currency's smallest unit.

| Task | Route |
| --- | --- |
| List funding requirements | `GET /api/v2/organizations/funding-requirements` |
| Read whether a write waits for funds | `GET /api/v2/transaction-requests/{transactionId}` |
| Follow a write as it pauses and resumes | `GET /api/v2/transaction-requests/{transactionId}/stream` |
| Read the bundler wallet's balance | `GET /api/v2/system/bundler/balance` |
| Read a paymaster deposit | `GET /api/v2/system/paymasters/{address}/balance` |
| Deposit into the paymaster from your account | `POST /api/v2/system/paymasters/{address}/deposits` |
| Read how much a payer wallet can withdraw | `GET /api/v2/system/payers/{address}/withdrawable` |
| Withdraw from a payer wallet or paymaster deposit | `POST /api/v2/system/payers/{address}/withdrawals` |
| Change the gas payer with EOA wallets | `PUT /api/v2/organizations/networks/gas-payer` |
| Turn sponsorship on or off with smart wallets | `PUT /api/v2/system/paymasters/config` |

The request and response fields of each route are in the [v2 API reference](https://docs.settlemint.com/docs/api-reference/v2), under Transaction funding, Transactions and Organisation deployment.

**Funding requirements.** The list returns only `active` requirements, newest first, unless you send `filter[status]=resolved` or `filter[status]=expired`. It also filters by `chainId`, `subjectAddress`, `subjectKind`, `expiresAt`, `lastRefusalAt` and `createdAt`. `subjectKind` is `eoa`, `smart-account` or `paymaster-deposit`. Each row carries the minimum as `requiredWei`, the recommended amount as `advisoryTotalWei`, the balance seen as `observedWei`, and `status`, `expiresAt` and `resolvedAt`. When the refusing check measured the balance, the requirement opens with that balance, and each later read that sees it change replaces it. The Permission manager, Gas manager and System manager roles see every row in full. Other callers see the address and amounts only for their own wallets and the organisation's wallets.

**A paused write.** A write is paused while its status read carries `activeRequirement`. The request keeps its state, for example `SIGNING`. `activeRequirement` holds the requirement `id`, the refused wallet's `address` and `role`, `subjectOwner`, which is `caller`, `organisation` or `platform`, `chainId` and `nativeCurrency`. A caller whose wallet signed the request, or who is an organisation owner or a platform administrator, also gets `shortfall` and `recommendedTotal`. `activeRequirementUnavailable: true` means the requirement could not be read, so read the status again. To see when the window closes, list requirements filtered by `subjectAddress` and read `expiresAt`. The status stream sends an event when a write starts or stops waiting on a requirement, and closes 180 seconds after it opens while the write is in flight, so reopen it to keep following. When the funding window closes, the request fails with the gas required error, `DALP-9087`.

**Decline the pause.** Send `Prefer: dalp-no-funding-pause`, alone or with a wait, as in `Prefer: wait=30, dalp-no-funding-pause`. A write the network then refuses for gas fails at once with `DALP-9087` and raises no requirement. Without a wait, the route answers HTTP 202 and the transaction request records the failure with the shortfall and the wallet address. A route that lists `DALP-14062` among its errors in the API reference can answer HTTP 400 with it, `TRANSACTION_QUEUE_FUNDING_REQUIRED`, instead, with `data.transactionId` naming the transaction request when the queue recorded one. The header can decline a pause but cannot force one.

**Top up.** No route moves funds into a wallet from outside the platform. Send the network's currency to the requirement's `subjectAddress` from your own wallet or service. The paymaster deposit is the exception: `POST /api/v2/system/paymasters/{address}/deposits` takes `amount` in wei, needs the Permission manager, Gas manager or System manager role and wallet verification, and pays from the account the request runs as.

**Withdraw.** Read the limit first. The Permission manager, Gas manager, System manager and Auditor roles can read it, and `destination` prices the reserve for that address.

- `balance` is the wallet's balance at the latest block, so a top-up shows on the first read after it confirms. For the paymaster, it is the EntryPoint deposit the indexer last observed.
- `reserve` is what the withdrawal itself costs, including a replacement at a raised fee. The platform prices it for a one-wei transfer and for sending the whole `withdrawable` amount to `destination`, and keeps the higher of the two.
- `inFlightReserve` is what the wallet's own writes on the network hold: the worst-case cost of its signed writes that have not settled and, for the bundler wallet, the bundles in flight.
- `withdrawable` is `balance` minus `reserve` and `inFlightReserve`, or 0 when those two take the whole balance.

The withdrawal applies the same rule when it is sent. It accepts the `withdrawable` amount the read showed unless the latest balance, the fee or the wallet's own writes changed since. For the paymaster, it also refuses that amount when the EntryPoint deposit on the network is lower than the indexed one the read showed. A `DALP-14027` refusal carries the figures it used: `balanceWei`, `reserveWei`, `inFlightReserveWei` and `withdrawableWei`.

The platform counts only the writes it sent itself. The network can also hold a spend from the wallet that the platform did not send, for example from the wallet's key used outside the platform. When that spend leaves less than the withdrawal, the withdrawal answers `DALP-12104` and sends nothing. Retry once the spend confirms. When it leaves the amount but uses part of `reserve`, the withdrawal is sent and the network can refuse it. The transaction request then fails and no funds move.

The withdrawal takes `destination`, `amount` in wei or `all`, and wallet verification, and only the Permission manager role can send it. A paymaster withdrawal also needs the System manager role on the signing account. It answers HTTP 200 with the amount moved once the transfer settles, or HTTP 202 with the transaction request to follow.

| Code | The route refuses |
| --- | --- |
| `DALP-14025` | A wallet that is not one of the organisation's payer wallets on the network. |
| `DALP-14027` | An amount over the current limit. |
| `DALP-14028` | A destination that cannot receive the transfer. |
| `DALP-12104` | A withdrawal while the network holds a spend the platform did not send. Retry it. |

**Change who pays.** With EOA wallets, send `chainId`, `gasPayer` as `self` or `relayer`, and an optional `reason`. An organisation owner or a platform administrator can call it or make the same change in the Console. A smart-wallet organisation is refused with `gas-payer-unavailable`. With smart wallets, send `enabled: true` for Paymaster-paid or `false` for Self-pay to the paymaster configuration route on the network. The Permission manager, Gas manager or System manager role can call it.

## Related pages [#related-pages]

Read [Gas sponsorship](https://docs.settlemint.com/docs/concepts/custody-and-signing/gas-sponsorship) for how a sponsored operation reaches the network, [Operator wallet](https://docs.settlemint.com/docs/concepts/custody-and-signing/operator-wallet) for how the platform watches the balances of the wallets it sends from, and [Transaction funding](https://docs.settlemint.com/docs/console/organisation-settings/transaction-funding) for the Console screen.


# Gas sponsorship

Source: https://docs.settlemint.com/docs/concepts/custody-and-signing/gas-sponsorship
Who pays the network fee for each write, how a sponsored smart wallet operation reaches the network, and what happens when a paying wallet runs dry.

Every write to an EVM network costs a fee in the network's native currency, called gas. Gas sponsorship means the organisation pays that fee for its users from wallets it keeps funded, so an investor or operator can act without holding the native currency while those wallets hold enough. The alternative is Self-pay, where each user funds their own wallet. This page covers the two settings that decide who pays, how a bundler and a paymaster carry a sponsored smart wallet operation to the network, and what happens when a paying wallet runs dry.

[Figure] How a smart wallet operation reaches the network, and who pays for it. A write from the Console or the API becomes a user operation that the user's smart wallet signs. The platform's bundler for that organisation and network collects it. When the network's gas payer is Paymaster-paid, the bundler adds a sponsorship ticket signed with the organisation's custodial key. The bundler sends a bundle to the EntryPoint contract on the network and its bundler wallet pays the gas up front. The EntryPoint checks the ticket and the smart wallet's signature, runs the call, and repays the bundler wallet from the paymaster deposit for a sponsored operation, or from the smart wallet's own balance otherwise. When the organisation has a refund splitter on the network, the repayment goes to the splitter, which shares it between the bundler wallet and the paymaster deposit while its sponsorship flag is on. Labels: bundle; bills if sponsored; gas refund; Console or API; Your write; The user's smart wallet; signs a user operation; Bundler; Org and network; Collects operations,; fronts the gas; Sponsorship ticket; Paymaster-paid; Signed with the; organisation's key; EVM network; EntryPoint; On chain; Checks, then runs it; Pays the gas; Paymaster deposit; for a valid ticket; Runs the call; Smart wallet; after a signature check; pays if not sponsored; Shares the refund; Refund splitter; Bundler wallet and; paymaster deposit.

The bundler fronts the gas for a user operation, and the EntryPoint repays it from the paymaster deposit or, without a valid ticket, from the wallet.

Two settings decide who pays gas. The wallet type is one choice for the whole organisation: EOA wallets or smart wallets. The gas payer is one choice per network: Self-pay, Relayer-paid with EOA wallets, or Paymaster-paid with smart wallets.

With Relayer-paid or Paymaster-paid, users need no native currency for the writes the organisation pays for. The organisation keeps the paying wallets funded instead.

A paying wallet that runs dry pauses the work it pays for. A top-up releases the work, and work still waiting when the funding window closes fails with the gas required error, [DALP-9087](https://docs.settlemint.com/docs/api-reference/errors).

## Two settings decide who pays [#two-settings-decide-who-pays]

An EOA wallet, or externally owned account, is a plain wallet controlled by one key. A [Smart Wallet](https://docs.settlemint.com/docs/concepts/custody-and-signing/smart-wallet) is a contract account with its own signing rules. The wallet type sets which kind every user of the organisation holds, on every network. When the platform offers smart wallets, onboarding proposes smart wallets with Paymaster-paid, so the organisation pays gas from the start. Otherwise onboarding proposes EOA wallets with Self-pay. The move to smart wallets is one-way: once the organisation is on smart wallets, the platform does not accept a move back.

The gas payer is set per network, so one organisation can sponsor gas on a public network and let users pay on another. The wallet type limits which payers a network can use.

| Wallet type | Gas payer | Who pays the fee | Wallets the organisation keeps funded |
| --- | --- | --- | --- |
| EOA wallets | Self-pay | Each user's wallet pays for its own writes. | None. Each user funds their own wallet. |
| EOA wallets | Relayer-paid | Users sign meta transactions, signed requests that another wallet sends, and the organisation's relayer wallet sends them and pays. | Relayer wallet |
| Smart wallets | Self-pay | Each smart wallet repays the bundler from its own balance. | Bundler wallet, plus each user funds their smart wallet |
| Smart wallets | Paymaster-paid | The organisation's paymaster repays the bundler from its deposit for every sponsored operation. | Bundler wallet and paymaster deposit |

On a network that charges no gas, none of these wallets needs a balance, and the Console recommends Self-pay there. On the Console's [Transaction funding](https://docs.settlemint.com/docs/console/organisation-settings/transaction-funding) page you read and change the gas payer for each network, and [Change the wallet type](https://docs.settlemint.com/docs/console/organisation-settings/transaction-funding#change-the-wallet-type) covers the move to smart wallets. Moving to smart wallets does not turn sponsorship on: check the gas payer on each network afterwards and choose Paymaster-paid where the organisation sponsors gas.

## How a sponsored operation reaches the network [#how-a-sponsored-operation-reaches-the-network]

A smart wallet does not send its own transactions. It acts through a user operation, a signed instruction defined by the ERC-4337 standard for account abstraction. An EntryPoint contract on the network validates the instruction and runs it. A bundler collects user operations and submits them to the EntryPoint in one transaction. [User operations](https://docs.settlemint.com/docs/concepts/custody-and-signing/user-operations) covers the API for sending, replacing and reading them.

The platform runs one bundler for each organisation and network, so the organisation does not run a bundler of its own. Each bundler signs with its own bundler wallet, which pays the gas for the bundle up front. The EntryPoint repays the bundler wallet in the same transaction, from one of two sources:

- **Paymaster-paid.** A paymaster is a contract that agrees to pay for an operation. The organisation's paymaster pays only for an operation that carries a sponsorship ticket. The platform signs the ticket with the organisation's custodial signing key. The ticket names the sender, a hash of the call, the organisation, a deadline and the most gas it covers. The paymaster refuses the operation when the sender or the call differ from the ticket, or when the cost exceeds the ticket's maximum. The EntryPoint refuses it once the deadline has passed. For an operation the paymaster accepts, the EntryPoint takes the repayment from the paymaster's deposit at the EntryPoint. For an operation the platform prepares, it signs the ticket only after the operation's gas estimate and funding checks pass, so an operation that fails estimation or is short of funds when it is first prepared leaves no signature request at the custody provider.
- **Self-pay.** With no ticket, the EntryPoint takes the repayment from the smart wallet's own balance.

A signed user operation that a client sends to the bundler API is checked against the payer's funds first, and one that the paymaster deposit or the smart wallet cannot cover is refused at submission. A write that the platform builds for a user pauses for funding instead, as [When a paying wallet runs out of funds](#when-a-paying-wallet-runs-out-of-funds) explains.

A refund splitter is a contract that divides each gas refund. When the organisation has one on the network, every bundle names the splitter as the receiver of the repayment instead of the bundler wallet, under Self-pay as well as Paymaster-paid. While the splitter's own sponsorship flag is on, it sends the bundler wallet a share set in basis points, one hundredth of a percent each, and deposits the rest into the paymaster deposit. While the flag is off, it sends the whole refund to the bundler wallet. A System manager sets the flag and the share on the splitter, apart from the network's gas payer.

The sponsorship key sits with the organisation's custody provider like any other custodial key, but its wallet must stay free of approval rules. When the provider's policy holds a sponsorship signature for approval, the platform refuses the operation at once and records the hold, so keep the paymaster wallet out of every approval policy at the custody provider, whichever provider it is. [Fireblocks policy](https://docs.settlemint.com/docs/deployment/fireblocks-policy) shows the Fireblocks version. A custody approval on the user's own signature is different: the operation waits for it, but only until 60 seconds before its ticket expires. The deployment sets the ticket lifetime, between 1 second and 1 hour, and the default is 5 minutes. With the default ticket, a person who approves a sponsored operation in the custody provider's app has about four minutes.

## Control the cost of sponsorship [#control-the-cost-of-sponsorship]

Sponsorship moves the fee to an organisation wallet, and the fee itself stays the same. Four controls limit what the organisation spends:

- **The per-ticket ceiling.** Each ticket covers at most a maximum gas cost. The deployment sets the ceiling per network in the network's native currency, and the platform refuses a ticket above it. A ticket deadline is at most one hour away.
- **The gas payer per network.** Switch a network to Self-pay to stop sponsoring there. The other networks keep their own payer.
- **The refund split.** A larger share for the paymaster deposit returns more of each refund to the sponsorship reserve.
- **Gas tank alarms.** Warning and critical alarms, set in days of runway left, tell you when a reserve needs a top-up.

The Permission manager, Gas manager and System manager roles see Transaction funding. With smart wallets, these roles change the gas payer and the gas tank alarms. The refund split is stored on the splitter contract, which accepts a change only from an account that holds the System manager role. With EOA wallets, an organisation owner or a platform administrator changes the gas payer, in the Console or through the API. Each of these changes is an administration change, so it waits for a second person when the organisation's [Approvals](https://docs.settlemint.com/docs/console/organisation-settings/general#approvals) settings protect it.

## When a paying wallet runs out of funds [#when-a-paying-wallet-runs-out-of-funds]

When a wallet cannot cover a write that the platform builds and sends for a user, the platform pauses the work, records one funding requirement that names the wallet and the amount to send, and waits. Nothing reaches the network while the work is paused. The requirement can name a user's own wallet, the relayer wallet, the bundler wallet or the paymaster deposit. One top-up that covers the requirement releases every write waiting on it, and nobody has to submit the work again.

The deployment sets a funding window for each network. Work still waiting when the window closes fails with the gas required error, [DALP-9087](https://docs.settlemint.com/docs/api-reference/errors). Its error data names the wallet, the network, the smallest amount to add and a recommended target balance. When a person's own wallet runs short, the platform emails that person the amount to send. A shortfall on a shared gas wallet, such as the relayer wallet, the bundler wallet or the paymaster deposit, sends no such email, so watch the Transaction funding page and the gas tank alarms for those.

A user operation a client signs and sends is refused at submission instead, and a smart-wallet write that needs several signers fails. An integration that prefers to fail fast sends `Prefer: dalp-no-funding-pause` with the write. The platform then fails a write it cannot fund at once with DALP-9087 instead of pausing it. A write that the transaction queue refuses before sending, because the paying account cannot cover it, returns [DALP-14062](https://docs.settlemint.com/docs/api-reference/errors), and nothing reaches the network. Fund the account and send the request again.

[How gas is paid and funded](https://docs.settlemint.com/docs/concepts/custody-and-signing/gas-funding#when-a-wallet-runs-out-of-gas) covers the funding requirement, and [Operator wallet](https://docs.settlemint.com/docs/concepts/custody-and-signing/operator-wallet#what-happens-when-a-wallet-empties) covers the funding webhook events. [Transaction funding](https://docs.settlemint.com/docs/console/organisation-settings/transaction-funding#fund-an-open-request) covers the top-up.

## Frequently asked questions [#frequently-asked-questions]

### Do investors need the network's native currency in their wallets?

Not for the writes the organisation pays for, when the network's gas payer is Relayer-paid or Paymaster-paid. A few writes fall outside Relayer-paid, such as a call that sends native currency, and [What Relayer-paid does not cover](https://docs.settlemint.com/docs/concepts/custody-and-signing/gas-funding#what-relayer-paid-does-not-cover) lists them. With Self-pay, each wallet pays its own gas and needs a balance in the native currency, unless the network charges no gas.

### Can the sponsor change what an operation does?

No. The user's smart wallet signs the operation, and the ticket binds the paymaster to that exact sender and call. A change to the call makes the ticket invalid. The paymaster can refuse to pay, but it cannot change the operation. The platform decides whether to issue a ticket, so a user with no native balance depends on the organisation's sponsorship being funded and on.

## Related concepts [#related-concepts]

- [Smart Wallet](https://docs.settlemint.com/docs/concepts/custody-and-signing/smart-wallet): The contract account that signs user operations under its own signing rules.
- [User operations](https://docs.settlemint.com/docs/concepts/custody-and-signing/user-operations): How to send, replace and read a user operation through the platform's bundler.
- [Operator wallet](https://docs.settlemint.com/docs/concepts/custody-and-signing/operator-wallet): The wallets the platform runs to pay gas, and what happens when one empties.
- [Custody Approval](https://docs.settlemint.com/docs/concepts/custody-and-signing/custody-approval): How a custody provider's policy holds a user's signature for approval.


# Maker-checker

Source: https://docs.settlemint.com/docs/concepts/custody-and-signing/maker-checker
Maker-checker, once turned on, keeps one mistaken instruction or compromised account from moving money, filing a report or approving a corporate action alone.



[Figure] Approval checks and role assignments provide different controls. Platform approval requires a different user on reporting sign-off, acknowledgement entry, desk limits, trade busts, and partial redemptions. A weighted Smart Wallet checks its signature threshold, subject to its installed validators. An ordinary role assignment grants permission but does not require a second approval. Labels: A different user decides; Platform approval; Sign-off, acknowledgement,; desk limits, trade busts, and partial redemptions.; The account checks signatures; Weighted smart wallet; A configured threshold governs calls.; Check every installed validator.; A role grants permission; Role assignment; Separate roles restrict who may act.; They do not add a second approval.

A platform approval and a weighted wallet enforce a decision or signature requirement, while a role assignment grants permission without a second approval.

Every switch under Approvals starts off. Once an owner or platform administrator turns the matching switch on, a single account cannot alone sign off a report, change a desk limit, bust a trade, run an irreversible corporate action such as a stock split, a partial redemption, a cash dividend or a payout in new tokens, or make a change in a protected family such as creating an asset. While a switch is on, the platform does not accept the proposer's own decision.

Some checks need no switch. Filing sign-off and acknowledgement entry always refuse the person who prepared or approved the submission, and two bank rail controls always refuse the proposer. An identity recovery asks a second owner or administrator by default: the Recovery group of Administration starts on, and an owner turns it off to run a recovery alone. The Administration rule does not hold a mint of an existing asset. On a token linked to a bank rail, the Bank rail row holds a mint over the credit limit.

An EVM custody call checks one role and needs no second decision. A weighted Smart Wallet can hold that role and add a signature threshold on top of it. Verify a maker-checker claim by checking who can sign.

## What maker-checker requires [#what-maker-checker-requires]

Maker-checker is the control in which one person, the maker, raises a change and a different person, the checker, decides it before it takes effect. The platform applies it to specific reporting, trading, corporate action, bank rail and administration changes. For on-chain custody calls, check the signing account's approval controls as well as its role assignment. [Custody Approval](https://docs.settlemint.com/docs/concepts/custody-and-signing/custody-approval) is the neighbouring control on the key signature itself.

## Why a change needs two people [#why-a-change-needs-two-people]

Left alone, a single mistaken instruction or a single compromised account could file a regulatory report, raise a trading desk's risk limit, or retire holder balances in a corporate action, with no one else ever seeing the decision. Maker-checker puts a different person in that path before the change can act.

Reporting sign-off shows the reason most clearly. An organisation configures an obligation for maker-checker so it can show a regulator that someone other than the filer reviewed the numbers before the platform published them, as well as that a filing went out. That is also why sign-off fails closed at publish: a missing second signer is found at publication, before the filing deadline.

A review that lives outside the system it governs can be skipped without anyone noticing. Maker-checker avoids that gap by checking, inside the platform's own write path, whether the decision came from someone other than the proposer. The check applies to writes through the platform. A holder of an on-chain role who calls the contract directly is outside it, as [An EVM role does not require two approvals](#an-evm-role-does-not-require-two-approvals) explains.

## Where the platform itself refuses the proposer [#where-the-platform-itself-refuses-the-proposer]

These surfaces keep this check inside the platform's own write path: signing off a reporting obligation's filing, entering the authority's acknowledgement of one, approving a trading desk's limits, busting a trade, and approving a corporate action that cannot be reversed once it runs. Those corporate actions are a stock split, a bonus issue, a rights issue, a spin-off, a capital decrease, a partial redemption, a coordinated distribution, a dividend or distribution paid in cash, a payout in new tokens and a buyback. Each blocks a decision made by the same person who proposed it, and each keeps a record of who proposed and who decided. For desk limits and trade busts this holds on a venue whose Trading venues switch is on. A venue with the switch off applies them at once, and the approvals ledger records that the approval policy waived the second person.

Two bank rail controls also refuse the proposer, and no Approvals switch turns them off. A client's bank account is active only after a bank rail manager other than the one who proposed it approves it, and the platform refuses the proposer's own approval. Executing or abandoning a recall, the reversal of a credit that the bank took back, starts with a request and waits until a different bank rail manager approves or rejects it. The requester cannot decide it and an impersonated session cannot either. Turning the Bank rail row under Approvals off changes neither rule. That row governs the other bank rail changes, such as a cash-out over the checker threshold, and starts off like every approval. The [roles page](https://docs.settlemint.com/docs/concepts/compliance-and-identity/roles-and-segregation-of-duties#what-the-platform-enforces) lists both controls beside the others.

The second signature on a filing must come from a different signed-in person. The platform declines an approval by the person who prepared the filing, because the two signatures would be one person's. It also does not accept one from an operator acting on another user's behalf, because an impersonated session cannot be the second signature. And the approval binds to the exact version the checker reviewed: a filing that changed after the review does not get approved, because applying it would approve bytes nobody read.

Acknowledgement entry follows the same rule under its own name. Recording the authority's acknowledgement discharges the filing period's duty and stops its overdue clock, and the platform does not record it when the entering user is the same person who approved the underlying submission. Entering and approving are two different acts, and each needs its own second person.

Desk trading limits and trade busts run through one shared approval record. On a venue whose Trading venues switch is on, a proposal waits until a different user approves or rejects it. The Console offers the proposer no Approve or Reject on their own proposal. On a venue with the switch off, the proposal is recorded already approved: a desk limit is enforced at once and a bust of an undelivered trade starts its undo at once. A bust of a delivered trade, whose reversal force-transfers the holders' tokens, always waits for a different user. Only an approved desk limit takes effect, and the latest decision wins. An approved proposal is settled: a second approve or reject of it is refused as already decided.

A limit names one wallet, one instrument and that instrument's quote token, and it caps the desk's open exposure across orders. The platform adds the incoming order to the wallet's open exposure on the instrument and rejects the order before it reaches the book when that total exceeds the limit. An order well under the limit on its own can still be rejected once the desk's existing exposure pushes the total over. A desk limit approved before limits had an instrument scope has no quote units, so the wallet cannot trade until an operator approves a scoped replacement.

The same Trading venues switch also governs the other venue controls. A venue configuration change, a fee schedule change, a venue VAT policy change, an operator order cancel and a mass cancel of open orders each wait for a different holder of the role the change needs. With the switch off they apply at once, and the approvals ledger records the waiver. The switch protects itself: switching it off, or letting an emergency halt skip it, is a venue configuration change too, so a second venue admin has to approve it, and a venue with a single admin has to add a second one first. Switching it on applies at once. [Venue controls](https://docs.settlemint.com/docs/concepts/issuing-and-markets/venue-controls#who-can-change-a-running-venue-and-who-must-agree) lists each control with its role.

After the maker sends a partial redemption for approval, it waits until an organisation owner or a platform administrator decides it. The corporate action, the issuer event that retires holder balances on a published plan, cannot run before that decision. In the Console the maker enters the PIN once on Review to send it, the sheet reads "Waiting for approval", and the checker approves with their own PIN. The maker then reopens the run and enters the PIN once more to run the approved plan.

The checker must not be the person who recorded the redemption or ran its last preview. The checker can decide from a signed-in session or with their own API key, but not from an impersonated session. The approval binds to the plan the checker read. A plan that changes afterwards loses its approval, and a decision not made within 72 hours of the last preview ends the record.

Every owner of the organisation and every platform administrator who is a member of it receives an email, except the maker. An owner or a platform administrator can decide it from Actions, where it shows as an "Approval request". The person who prepared it receives an email when it is approved or rejected.

Unlike reporting sign-off, this gate does not fail closed. The Corporate actions row under Approvals starts off, so an organisation turns the gate on there, and an organisation with no owner other than the maker opens the redemption without it. The record names whether the Corporate actions row was off or the organisation had no owner other than the maker. A dividend, bond coupon or distribution paid in new units of the token waits for the same decision under the same rules, because the platform has no step that takes minted units back. So do the other corporate actions this section lists. [Approve or reject a partial redemption](https://docs.settlemint.com/docs/api-reference/guides/corporate-actions#approve-or-reject-a-partial-redemption) covers the calls.

Where sign-off is required, it also fails closed at publish time. An obligation that demands two signatures in an organisation where one person can sign creates a deadlock, one discovered only on the filing deadline. The platform therefore does not publish it until at least two distinct people hold the owner role, because owners are the only eligible approvers it counts. The requirement follows the Reporting switch under Approvals, which starts off. An obligation can carry its own exception to that switch. The publish-time check for two eligible approvers therefore applies per obligation: with the switch off for an obligation, the platform publishes it whatever the number of approvers. Whatever the switch says, the filing sign-off refuses the person who prepared the filing.

## Who decides a request from the Approvals inbox [#who-decides-a-request-from-the-approvals-inbox]

Each kind of request that waits in the Approvals inbox names who may decide it, and approving and rejecting follow the same rule. A held administrative change, a reconciliation break resolution, a dividend entitlement push and a token sale are decided by a member who holds one of the request's approver roles, and only by such a member. No role decides by default: when the approval policy names other roles, an owner or a platform administrator who holds none of them is refused with `approver-role-not-permitted`, the message names the roles that may decide, and the request keeps waiting. A platform administrator who also holds an organisation role decides with either role. A wallet checker approval is decided only by the wallet's named checker. A decision from anyone else is refused with `not-named-approver`. The maker never decides their own request.

A member who may not decide a request cannot read it through `GET /api/v2/checker-approvals/{approvalId}` either, unless they made it: the route answers 404. A request that is decided in its own workflow, such as a held price, a bank-rail operation or a corporate action, is refused on `POST /api/v2/checker-approvals/{approvalId}/decision` with `wrong-kind` and HTTP 409, and stays where it was raised.

## Impersonated sessions cannot decide [#impersonated-sessions-cannot-decide]

A platform administrator can [impersonate](https://docs.settlemint.com/docs/console/platform-admin/users) a member. An impersonated session can still propose, but it cannot approve or reject. This stops one administrator from proposing as themselves and then approving as a second operator. On trading venue items and on the requests in the Approvals inbox, a proposal made while impersonating records the administrator, so the administrator cannot approve it later in their own session either. KYC works the same way: a KYC version submitted while impersonating, and a profile field or organisation detail edited while impersonating, keep the administrator next to the member. The administrator cannot then review that version or those fields in their own session. With the demo switch below on, this KYC check lets the administrator review them.

An impersonated session also cannot give out a sign-in for the member: it cannot approve a device sign-in such as `dalp login`, add a passkey, or connect an MCP client. Each of these would let the administrator sign in later as the member without the impersonation mark. The refusals answer with HTTP 403 and the codes `IMPERSONATED_DEVICE_APPROVAL`, `IMPERSONATED_PASSKEY_REGISTRATION` and `IMPERSONATED_OAUTH_GRANT`. The demo switch below does not lift them.

The refusal covers every decision on an item that waits for a second person: desk limits, trade busts, operator order cancels, mass cancels, venue configuration and fee schedule changes, venue announcements, add-on access proposals, account closure requests, client bank accounts, Canton wallet submissions, custody approvals and lifecycle approvals, KYC and profile reviews, participant registrations, transfer approvals, and the requests in the Approvals inbox. The Platform API answers such a request with `DALP-200386` (`IMPERSONATED_APPROVAL_DECISION_REFUSED`) and HTTP 403, and nothing changes. The frozen v1 KYC approve and reject routes answer with their usual 403 session-policy refusal. In the Console, Approve and Reject on the trading venue screens are disabled during an impersonation and read "Sign in as yourself to decide". Other screens show the refusal after the click.

A demo deployment can switch this off with the Helm value `global.dalpApp.config.auth.allowImpersonatedDecisions: true` (`ALLOW_IMPERSONATED_DECISIONS=true` outside the chart). It is `false` by default and in every shipped values file. Keep it off on any deployment that holds real assets or real people. Three acts refuse an impersonated session even with the switch on: the filing sign-off and its publish, a legal-hold release, and a change that loosens the approval policy.

## Issuing an asset with an external custody provider [#issuing-an-asset-with-an-external-custody-provider]

Approvals are an organisation setting, and every approval starts off except the Recovery group of Administration, which starts on. Until an owner or a platform administrator turns a family on in the [Approvals](https://docs.settlemint.com/docs/console/organisation-settings/general#approvals) section of the General settings, a change in that family goes ahead on the maker's request alone, and Actions shows it as "No second approval (approval off)". [Identity recovery](https://docs.settlemint.com/docs/console/my-account/onchain-identity#recover-a-user-who-lost-their-wallet) is the exception, and it also runs alone where the organisation holds no owner or administrator besides the person recovering: the platform cannot ask a person who does not exist.

Creating an asset is an administration change in the Token administration protection group. Turning on the Administration family protects every protection group, Token administration included, unless an exception turns that group off. An exception can also protect Token administration on its own while the family stays off. Either way, creating an asset then waits for a checker. An organisation that sets its protection groups as a list through the approval policy API holds asset creation only when that list includes Token administration.

[Figure] Issuing an asset under maker-checker with an external custody provider. User A creates an asset and confirms with wallet verification. With the organisation's approval rule for administration changes turned on, DALP holds the request as an approval request for up to 24 hours instead of running it. User B, an owner of the organisation or a platform administrator who is not user A, approves it in Actions. DALP then runs the request as user A, after it checks that user A still holds the permission, and queues the transaction. The custody provider that holds user A's key applies its own policy, which can wait for its own approvers, then signs. The provider broadcasts the transaction itself, or DALP broadcasts it, depending on the provider's mode. The network records the asset contract in a block, and the DALP indexer reads that block, so the asset appears in the Console. Labels: User A; Maker; User B; Checker; DALP; Platform; Custody provider; Its own policy; Network; EVM; 1; Creates asset; Confirms with wallet; verification; 2; Holds request; Approval request,; open for 24 hours; 3; Approves it; Owner or platform; admin, never user A; 4; Runs it as A; Checks A's role and; queues the write; 5; Checks policy; Can wait for its; own approvers; 6; Signs; Broadcasts itself,; or DALP broadcasts; 7; Adds contract; The asset contract; exists on chain; 8; Confirms it; Indexer reads it,; the asset appears.

User A's asset request waits for user B's approval, then DALP runs it as user A, the custody provider signs, and the asset appears in the Console.

The steps in order:

1. **User A creates the asset.** The request needs user A's wallet verification. Instead of running it, DALP records an "Approval request" and answers the API call with `202` and a status address under `/api/v2/checker-approvals/`. Nothing is signed and nothing reaches the network.
2. **DALP holds the request.** The approval request stays open for 24 hours, or for the expiry an owner set on administration changes through the approval policy API. A request that nobody decides in that time expires, and a rejected request ends. Either way nothing ran, and user A submits the change again to retry. A second request for the exact same change, while the first one waits, is refused with `409`.
3. **User B approves it.** The checker must be an owner of the organisation or a platform administrator. The platform does not accept a decision from user A, or from a session in which a platform administrator acts as another user. A member who is not an owner cannot decide unless an owner named the Member role as approvers of administration changes through the approval policy API. Once approver roles are named, only those roles decide: an owner or a platform administrator who holds none of them is refused, and the refusal names the roles that may decide. When the "Approvals required" setting in the [Approvals](https://docs.settlemint.com/docs/console/organisation-settings/general#approvals) section of General settings is above 1, that many different people must approve. An organisation with no second owner needs a platform administrator to decide, or the request lapses. A platform administrator is an operator of the deployment, not a member of the organisation, and the record names who decided.
4. **DALP runs the request as user A.** The platform runs the original request with user A as the requester, so the record shows who made the change and who approved it. If user A lost the permission to create assets while the request waited, the platform refuses to run it. Otherwise the Transaction Lifecycle Engine, the part of DALP that queues, sends and tracks every on-chain write, queues the transaction. DALP runs an approved request once: a second approval or a repeated decision does not run it again. Reading the request at its status address shows how the run went in `executionState`: `pending` before it starts, `running`, `completed`, `failed` when it stopped before the change was applied, or `reconciliation-required` when it ran in part and an operator must confirm the outcome.
5. **The custody provider checks its own policy.** The signing request goes to the custody provider that holds user A's key. Its policy decides whether the signature needs its own approvers, and the transaction waits for that decision within the approval deadline the deployment sets, at most 24 hours. On a network where a paymaster pays the gas, the wait also ends 60 seconds before the gas sponsorship ticket expires, which leaves about four minutes by default. [Gas sponsorship](https://docs.settlemint.com/docs/concepts/custody-and-signing/gas-sponsorship#how-a-sponsored-operation-reaches-the-network) explains the ticket. [Custody Approval](https://docs.settlemint.com/docs/concepts/custody-and-signing/custody-approval) explains where each provider takes that decision.
6. **The custody provider signs.** Depending on the provider's mode, the provider broadcasts the signed transaction, or it returns the signature and DALP broadcasts it.
7. **The network records the asset contract.** The transaction lands in a block.
8. **DALP confirms it.** DALP's indexer reads the block, and the asset appears in the Console.

While the request waits, DALP keeps it as user A sent it, so it can run it unchanged in step 4. A value the approval details show as `[REDACTED]`, such as a bank connection's logon password or a custody provider's credentials, is stored encrypted with the platform key and opened only to run the approved request. If that value no longer opens, the platform refuses to run the request.

The two approvals answer different questions. The platform approval in step 3 proves that a second person in the organisation agreed to the change. The custody provider's policy in step 5 proves that the key holder's own rules allowed the signature. Neither one replaces the other, and an organisation that wants both turns on the Administration rule in DALP and configures the policy at its custody provider.

While administration changes are protected, user A cannot switch the rule off alone either: turning an approval off waits for another owner or a platform administrator, so an organisation with a single owner needs a platform administrator for it. Until someone decides it, user A can withdraw that held turn-off from the Approvals row on General, and the decider sees each setting as it stands then next to the value the change would set.

Minting units of an existing asset is not held by the Administration rule. A mint goes ahead on the maker's request, subject to the custody provider's policy and, for a weighted Smart Wallet, its signature threshold. For a token on a bank rail, the Bank rail family holds a mint above the credit limit and a raise of the mint limit. [Roles and segregation of duties](https://docs.settlemint.com/docs/concepts/compliance-and-identity/roles-and-segregation-of-duties) covers how to keep the roles that mint apart from the roles that approve.

The v1 API cannot hold a request, because no v1 client can read the `202` answer. A v1 write whose v2 route a protected group would hold is therefore refused instead, before anything runs. Creating an asset through `POST /api/v1/token/create` while Token administration is protected, for example, answers `403` with the code `FORBIDDEN` and the id that route already returns for a refused caller (`DALP-9485` on token routes, `DALP-12252` on platform routes, `DALP-0003` on identity, compliance and user routes). The message names the protection group, and `data.fix` names the v2 route to send the change to, here `POST /api/v2/tokens`. Four v1 writes had no `403` before and now answer `DALP-12252` the same way: registering an external token, requesting a KYC profile update, creating a user and revoking a user's session. A v1 write whose v2 route is never held, such as a mint, runs as before.

## An EVM role does not require two approvals [#an-evm-role-does-not-require-two-approvals]

The EVM Contract Set, the deployed contracts that gate privileged calls on role permission, checks the custodian role, the token role that may freeze an address or force a transfer, before either call. Any address with that role can authorise the call alone. Granting the same role to two addresses lets either address act alone, so they do not co-sign.

Separating roles can restrict which person starts each kind of operation. It does not add an approval step to a function that checks one role. For a custody call that needs two signatures, a weighted Smart Wallet, the on-chain account that signs only when its collected signatures meet its threshold, can hold the role. Its signer weights and threshold decide which combinations can authorise a call.

Check the wallet's full validator configuration. A single-signer validator installed beside the weighted validator can let its owner authorise a call directly. A threshold also counts signatures, not independent people: confirm who controls each signing key.

**Role permission**

The asset contract asks whether the calling address holds the required role. Multiple role holders can each act independently.



**Signature threshold**

The wallet asks whether the collected signatures meet its configured threshold. Its other installed validators must not provide a path that bypasses the intended approval policy.

## Verify the approval requirement and its scope [#verify-the-approval-requirement-and-its-scope]

For a platform approval, inspect the proposal, the decision, and the identities that made each. On reporting obligations, confirm that sign-off is enabled. An obligation published without that requirement does not need a second person on its filings. On a partial redemption, read the record's approval policy and waiver: a waived record ran without a second approver.

For an EVM custody call, identify the role that authorises the call and every address that holds it. Then check how each address signs. Counting role holders alone cannot establish maker-checker.

| Control | What to verify | What can weaken it |
| --- | --- | --- |
| Platform approval | The proposer and deciding user differ. Required sign-off is enabled. | Publishing a reporting obligation without sign-off, or a waived partial redemption. |
| Weighted Smart Wallet | Signer ownership, weights, threshold, and every installed validator. | One person controlling enough keys, or another validator allowing direct access. |
| Role assignment | Every address permitted to call the function. | Treating several independent role holders as joint approvers. |

Revoking a role changes who can make the next call. It does not reverse a settled transfer. Preserve the approval record, wallet configuration, role history, and transaction reference needed to assess an earlier operation. Current role membership alone cannot prove which controls applied at that time.

## Frequently asked questions [#frequently-asked-questions]

### Does a maker-checker requirement mean two people must click a button?

No. The second act can be a recorded decision by another signed-in user or a signature required by the signing account. An ordinary EVM role check alone does not provide that second act.

### Does the impersonation rule also cover publishing?

Yes. Publishing an obligation configured for it is what discharges the filing duty, so the platform applies the same rule to that act as to an impersonated approval. A publish attempt from an operator acting on another user's session is blocked, and so is a publish attempt on a submission that was never signed off in the first place. Both cases protect the same fact: a published filing traces back to a signed-in person's own decision. With sign-off off for an obligation, the filing still refuses the person who prepared it.

### What happens when the filing changes after the checker reviewed it?

The pending approval is voided and does not carry over to the new content. A sign-off binds to one exact version of the filing, so any edit or regeneration after the checker's review invalidates what they approved, and the filing needs a fresh sign-off before it can publish. The same rule stops a second approver from acting on a submission someone else already approved.

### Does approving a trade bust mean the trade is reversed?

Before delivery, yes. After delivery, approval starts the reversal, and it completes only once the tokens' compliance rules allow the transfers. A bust can be proposed within 24 hours of the trade once neither of its orders is still open. Before delivery, approval undoes the trade on the venue by unlocking both legs. After delivery, approval reverses it with custodian forced transfers under the organisation's operations signer, the platform-managed account that signs the platform's writes for the organisation. Listing a market on a venue grants the token's custodian role to that operations signer when the signer listing it may grant that role, and the role can force-transfer and freeze any holder's units of the token, beyond the units in a trade. On a venue whose **Trading venues** row under "Approvals" is on, a different operator must approve the bust. With the row off, the bust is recorded already approved and runs at once.

Before delivery, approval submits one on-chain call that releases both locked legs. After delivery, it sends the forced transfers. Read the trade's outcome to confirm completion. If the call completed before the platform recorded the result, the Console's "Resume" control completes the remaining record updates. See [Trade busts](https://docs.settlemint.com/docs/console/asset-lifecycle/venues/trade-busts) for the workflow and its limits.

### How is maker-checker different from custody approval?

They are neighbouring controls that answer different questions. Maker-checker requires a different party's decision before a change takes effect. Custody approval gates the signing of one prepared transaction, and its approvers come from the wallet's own policy: a custody provider's rules, a hardware module's quorum, or a multi-signature wallet's signers.

## Related concepts [#related-concepts]

- [Asset Lifecycle](https://docs.settlemint.com/docs/concepts/issuing-and-markets/asset-lifecycle): The whole working life of a regulated tokenised instrument. Maker-checker is a control the platform applies during the Service stage and at one corporate-action step, not a lifecycle stage itself.
- [Smart Wallet](https://docs.settlemint.com/docs/concepts/custody-and-signing/smart-wallet): The on-chain account that signs only when its collected signatures meet a configured threshold, the mechanism a weighted wallet uses to enforce a signature requirement that an ordinary role check does not.
- [Custody Approval](https://docs.settlemint.com/docs/concepts/custody-and-signing/custody-approval): The neighbouring control on a custody instruction, where the approvers come from the wallet's own policy instead of a platform-enforced maker-checker split.
- [EVM Contract Set](https://docs.settlemint.com/docs/platform/evm-contract-set): The contracts that check role permission for privileged calls.
- [Role Grant](https://docs.settlemint.com/docs/concepts/compliance-and-identity/role-grant): What it means for an address to hold a role, and why holding two roles at once can remove a policy-enforced split.
- [Delegated Authority](https://docs.settlemint.com/docs/concepts/compliance-and-identity/delegated-authority): How a maker or a checker can act through a delegated write rather than their own address.
- [Multisig](https://docs.settlemint.com/docs/concepts/custody-and-signing/multisig): How to provision a weighted Smart Wallet with a signer list and threshold.


# Multisig

Source: https://docs.settlemint.com/docs/concepts/custody-and-signing/multisig
Multisig lets a tenant put a wallet under several signers, weighted so authority follows who must agree, before any of them can act alone.



[Figure] Nothing exists on chain until the creator finalises. A creator drafts a name, a threshold, and one row per signer. Each signer joins by accepting an invite, or the invite lapses after seven days unused, or the creator revokes it. The creator finalises once every invite has been accepted, revoked or lapsed: finalise does not run while any invite is still pending, and a lapsed invite leaves its seat empty. Finalising locks the draft and deploys the wallet with the resolved signer set. The deployed wallet then enforces its own threshold on every future instruction. Labels: Name and threshold; Draft; one row per signer; Each signer joins; Invite; or is revoked; Locks and deploys; Finalise; once nothing is pending; Deployed once; Wallet; enforces its threshold; DRAFT and INVITE are platform-only. WALLET is the only stage on chain.

A creator drafts a signer list, each invited signer joins or is revoked, and one finalise step deploys the wallet.

A tenant assembles a multisig's signer list before anything commits: the draft stays invisible outside the platform, and nothing exists on chain until the creator finalises it.

Each invite is single-use, expires after seven days, and stays revocable until then. Finalise does not run while an invite is pending. A lapsed invite stops counting as pending and leaves its seat empty, so the creator can finalise once every invite has been accepted, revoked or lapsed.

Each seat holds its own weight, so control can follow who must agree in practice. The threshold totals weight, and a seat whose weight reaches it can act alone. Once deployed, weight and threshold become the Smart Wallet's own concern, one of two approval planes under Custody Approval, alongside a custody provider or hardware module gating a single signer's own key.

## Why a wallet needs more than one signer [#why-a-wallet-needs-more-than-one-signer]

A wallet with a single key has a single point of failure: lose that key, or have it taken, and control over everything it holds goes with it. Multisig spreads that control across several signers and weights each seat so authority follows who must agree.

A generic N-of-M scheme fixes the single-key problem by adding signers, but it treats every signer as equal, and that rarely matches how authority works inside a financial institution. A treasurer's sign-off usually needs to count for more than a junior desk's, and a counterparty may hold a seat that can never clear the threshold alone. Multisig's weighted seats let the wallet's own threshold mirror that chain of authority. The wallet contract then enforces that no instruction executes until the weight behind it reaches the threshold. Give no single seat a weight that reaches the threshold if no one person may act alone.

## Why provisioning happens before any wallet exists [#why-provisioning-happens-before-any-wallet-exists]

The whole staffing process runs on the platform first, as a draft, until the creator finalises it. That draft-first path is a control of its own, separate from whatever the deployed wallet later enforces.

Who accepted a seat, with which key, and which seats were offered and then withdrawn before finalising are facts a compliance review needs, and none of them are visible from the chain alone. A revoked invite stays on the draft with the weight it offered and, when the creator emailed it, the address it went to, evidence a plain on-chain signer list would never show.

Provisioning through the platform, instead of deploying a wallet directly and registering it afterwards, also turns the finished wallet into a participant the platform already recognises. The same account-abstraction infrastructure that sponsors the deployment, the identity and compliance surfaces other participants already have, and the co-signing workflow in Custody Approval are all in place once finalise runs.

## What multisig covers [#what-multisig-covers]

Multisig names a specific pairing: the weighted Smart Wallet, the deployed account that enforces weight and threshold once it exists, plus the draft, invite, and finalise process that staffs it. This page covers getting from an empty signer list to a working wallet. Smart Wallet covers what that wallet does once it exists. Multisig belongs to the Self-custody module. Where the deployment or the organisation has that module off, wallets keep one signer and a threshold of one.

A draft is not a wallet. No signer holds any standing on chain, no address exists, and nothing about it can be enforced until finalise deploys the account with the resolved signer set. See Smart Wallet for the weight and threshold mechanics. See Custody Approval, the co-sign workflow that governs signing once the wallet exists, for how this approval plane compares with a custody provider or hardware module gating a single key.

## Configure signers before deployment [#configure-signers-before-deployment]

A creator decides who holds a seat and at what weight, and nothing commits until each invite is accepted, revoked or lapsed and the creator finalises. Give the seats whose sign-off is not optional enough weight that the wallet cannot act without them, and set the threshold below the full total only where being outvoted by the rest is an acceptable outcome.

A creator can build a signer list gradually: invite one colleague this week and a counterparty the next, and watch who joins before finalising.

Finalising is one-way, and it does not run while any invite is still pending. Finalise deploys the wallet only after every invite is accepted, revoked or lapsed. The platform sends no reminder, so a draft with an unanswered invite stays unfinalised until the signer joins, the creator revokes the invite, or seven days pass. A lapsed invite shows as **Expired** on the draft and adds no weight, so check that the seated signers still reach the threshold before finalising.

## Running a draft to completion [#running-a-draft-to-completion]

A creator drafts a multisig with a name, a threshold, and one row per intended signer, then invites each one with a link. Each invite ties to one seat and the weight the creator set for it. The creator shares it directly or sends it by email, so nothing goes out until the creator hands it over. Naming no threshold gets the strictest one: every seat's weight added together, so the wallet needs all of them.

An invited signer opens the link, signs in, and accepts by choosing one of their own key wallets, a wallet controlled by a single key, which commits its address to that seat. The seat then shows as joined.

[Figure] Three ways an invite can end. An invite starts as invited, valid for seven days. It becomes joined if the signer accepts, lapsed if seven days pass unused, or revoked if the creator cancels it. Joined, lapsed and revoked are terminal. A lapsed invite can no longer be accepted, and finalise leaves its seat empty. Labels: Signer holds a link; Invited; valid seven days; signer accepts; seven days pass; creator revokes; Joined; signer accepted; Lapsed; seven days unused; Revoked; creator cancelled it.

An invite that never joins either lapses or is revoked by the creator.

Joined, lapsed and revoked are final. A lapsed invite can no longer be accepted, and finalise deploys the wallet without its seat.

A creator waiting on a slow signer chases the invite directly, or revokes it and checks that the remaining signers can still meet the threshold. Once nothing is pending, finalising locks the draft and deploys the wallet with the signers who joined, plus any seat added directly. Signing afterwards runs through the co-sign flow Custody Approval covers: create the approval, collect signatures until the weight clears the threshold, then read the terminal status. In the Console each signer finds the wallet under Shared accounts in the sidebar, and its Approvals tab lists the approvals waiting for their signature.

## Three kinds of seat, and what finalise locks in [#three-kinds-of-seat-and-what-finalise-locks-in]

A signer row resolves one of three ways. An own seat is the creator's own eligible key. A joined seat is an invited signer who accepted. An external seat is a bare address the creator added directly, with no platform identity behind it. That last kind trades away the off-chain evidence an invite leaves behind: a joined seat records which platform participant accepted and with which key, and a revoked invite keeps the weight it offered and any email it went to, while an external seat keeps only its address and weight. The FAQ below covers when that trade is worth making.

Provisioning checks run before any account creation request is built. An own or invited seat must be a key wallet, so neither can be another multisig. The platform does not check an external seat's address, so it does not stop that address from being one. Two seats cannot resolve to the same address, and a threshold no combination of seats could reach is rejected outright.

Finalise locks the draft first, then re-derives the signer list from that locked snapshot, so a late edit or a second finalise attempt cannot race the first. Deployment then switches the new wallet to the weighted signer set. A failed finalise ends one of three ways:

| What failed | What happens to the draft |
| --- | --- |
| A check before deployment, such as a signer whose key stopped resolving or a threshold the seats cannot reach | It reopens, so the creator fixes it and finalises again. |
| The chain rejects the switch to the weighted signer set, and a retry cannot change the answer | The platform removes the participant it created, and the draft reopens. |
| A failure after the switch commits, or a switch whose outcome is unknown | It stays locked for reconciliation, so a retry cannot deploy a second wallet. |

Finalise runs in the background. The call waits only as long as the caller asked, and otherwise answers `202` with a finalise request, which the caller reads until it reports the participant and the Smart Wallet. The draft reads as finalising until the run finishes.

The platform's draft snapshot and the wallet's on-chain signer set agree because finalise builds the wallet from the draft. A review checking provisioning evidence compares the draft snapshot against the deployed wallet's signer configuration directly.

## What runs off chain, and the one call that does not [#what-runs-off-chain-and-the-one-call-that-does-not]

A multisig draft runs entirely on the platform until finalise. Creating a draft, adding or inviting signers, and accepting an invite all happen against the platform's own records, and only finalise reaches the chain.

Creating a draft seeds an own seat for the creator at weight one. Each invite stores only a hash of a random token, never the token itself.

Finalise carries an [idempotent write](https://docs.settlemint.com/docs/api-reference/guides/idempotency-async-settlement) key derived from the draft and its current member set version, so a duplicate call against an unchanged draft deploys nothing new.

## Frequently asked questions [#frequently-asked-questions]

**What happens if a seated signer's key stops being eligible before finalise?**

Finalise checks every seat against the platform record behind it, as well as the address captured when the seat was added. If a seated signer's platform wallet was revoked or removed after joining the draft, finalise does not proceed, even when the signers who remain still meet the threshold by weight. The draft reopens, so remove or replace that seat and finalise again.

**When is an external seat the wrong choice?**

When a review later needs to show who was proposed as a signer and then reconsidered. An invited seat leaves that trail behind: a joined seat records which participant accepted, and a revoked invite keeps the weight it offered and any email it went to, so a review can see a seat that was offered and withdrawn. An external seat records an address without the platform identity and acceptance history of an invited signer. Reach for one only when the signer never holds a platform identity at all, and only once losing that off-chain trail is an acceptable trade.

**Is DALP's multisig the same as a generic N-of-M wallet?**

No. A generic N-of-M scheme only counts how many signers took part. DALP's multisig sums each signer's configured weight instead, so a two-signer wallet where one signer holds enough weight alone can execute without the other, while a three-signer wallet with equal weights might need every one of them. Where other material calls this an N-of-M multisig, it means the same weighted mechanism. See Smart Wallet for the full weight and threshold mechanics.

## Related concepts [#related-concepts]

- [Smart Wallet](https://docs.settlemint.com/docs/concepts/custody-and-signing/smart-wallet): The deployed account and validator a multisig draft produces once it finalises, and where weight and threshold live afterwards.
- [Custody Approval](https://docs.settlemint.com/docs/concepts/custody-and-signing/custody-approval): The co-sign workflow that governs signing on a multisig wallet once it exists, separate from how the wallet was staffed.
- [Custody Provider](https://docs.settlemint.com/docs/concepts/custody-and-signing/custody-provider): The other approval plane under Custody Approval, an external signing service or hardware module gating one signer's own key instead of a wallet's weighted threshold.
- [Maker-checker](https://docs.settlemint.com/docs/concepts/custody-and-signing/maker-checker): The general propose-then-approve pattern a weighted multisig implements for wallet control, where enough weighted signers must approve an operation before it executes.
- [Participant](https://docs.settlemint.com/docs/concepts/compliance-and-identity/participant): The platform record a finalised multisig draft becomes, with its complete signer list fixed at deployment.
- [Idempotent Write](https://docs.settlemint.com/docs/api-reference/guides/idempotency-async-settlement): The retry safety pattern finalise relies on so a duplicate call against an unchanged draft never deploys a second wallet.


# Operator Wallet

Source: https://docs.settlemint.com/docs/concepts/custody-and-signing/operator-wallet
An operator wallet is a wallet the platform sends from and pays your users' network fees with, and the platform watches its balance.



[Figure] Two provisioning paths, one tracked wallet kind, two watchers on different clocks. An operator wallet reaches the platform's tracking by one of two paths: a plain externally owned wallet an operator has listed for monitoring, or the organisation's own bundler and relayer wallets, which pay gas for that organisation's account-abstraction operations and meta transactions. Both are registered under the same operator-wallet classification, because neither emits an on-chain event the platform's indexing would otherwise notice. One native-balance collector reads each wallet's balance on its chain. Two surfaces watch that balance against a 0.1-native cutoff: the payer status in Console's Transaction funding section marks a low balance the moment the number crosses it, and a monitoring alert fires only after the balance has stayed below the cutoff continuously for fifteen minutes. Labels: Provisioning, tracking, alerting; Listed for monitoring; Config-registered; named in deployment configuration; Sponsors user operations; Per-org bundler; the organisation's own bundler wallet; One tracked wallet kind; Operator wallet; read by the native-balance collector; Balance below 0.1 native?; one cutoff, applied twice; now; after 15m; Console: flags it low now; Payer status follows the balance,; with no delay applied; Alert: fires after 15 minutes; Only once continuously below the cutoff,; naming the wallet and chain.

Two provisioning paths feed one tracked wallet kind, flagged low in the Console at once and by the paging alert after fifteen minutes below the cutoff.

An operator wallet is a wallet the platform sends from and pays network fees with for your users: the organisation's bundler wallet, its relayer wallet, or a wallet the deployment lists for monitoring. The organisation funds its bundler and relayer wallets, and the deployment operator funds the wallets its configuration lists.

Work pauses for funds by default and resumes when the wallet is funded inside the funding window. Other terminal conditions, such as an expired sponsorship, can still end an operation for reasons unrelated to gas.

Nothing tops a wallet listed for monitoring up for you, and no target balance or runway is published for it. Sizing the top-up is your decision. The low-balance cutoff is fixed at 0.1 of the chain's native currency and is the same for the alert and the Console.

## Why the platform needs its own wallets [#why-the-platform-needs-its-own-wallets]

When your users submit account-abstraction operations or meta transactions, something has to send them and pay the network's gas token to land them on chain. The platform does that from wallets it holds for the organisation: the bundler wallet sends user operations and pays their gas up front, and the relayer wallet sends meta transactions. Under Paymaster-paid the paymaster deposit repays the bundler, so users hold no native gas. Under Self-pay each smart wallet repays it. No participant owns or controls these wallets. The alternative, each user holding native currency, is the Self-pay choice that [Gas sponsorship](https://docs.settlemint.com/docs/concepts/custody-and-signing/gas-sponsorship) compares.

A participant cannot fix an empty operator wallet, so the organisation or the deployment operator owns that problem. The queue stalls long before anything fails, so the platform watches these balances continuously instead of waiting for a failed transaction.

## Watching the balance, and what a low reading means [#watching-the-balance-and-what-a-low-reading-means]

Balance monitoring covers the wallets listed in deployment configuration and each organisation's bundler and relayer wallets. A wallet is tracked once, whichever way it was registered, and the platform refreshes each recorded balance on its own, so nobody triggers an update by hand.

Two surfaces watch that recorded balance against one low-balance cutoff of 0.1 of the chain's native token: the payer status on the Console's Transaction funding page, and a monitoring alert. The platform publishes the cutoff for each network alongside the balances, and the alert compares each wallet against that published figure, so both surfaces use the same cutoff. They can still list different wallets: the Console judges the paymaster on its deposit, and the alert also watches wallets the deployment lists for monitoring. The cutoff has no deployment setting. A deployment that still sets `dalp.observability.nativeBalance.lowThreshold` fails to install the monitoring chart until the setting is removed.

The Console's Transaction funding page lists the organisation's shared gas wallets on the network the sidebar has active, such as its relayer wallet and its bundler wallet, with the job each one does. It shows the balance the platform last recorded and a status the platform judges, and it tells apart a balance nobody has read yet from a balance that is zero. It does not list wallets that deployment configuration names, and it has no control that registers a wallet for tracking. Its top-up sheet gives the address and a suggested amount for a transfer you send from another wallet. [Shared gas wallets](https://docs.settlemint.com/docs/console/organisation-settings/transaction-funding#shared-gas-wallets) covers how to read the list.

The two surfaces do not update on the same rhythm. The Console payer status marks a wallet as low the moment its recorded balance crosses the cutoff. The alert only fires once the balance has stayed below the cutoff continuously for fifteen minutes, so a brief dip that a top-up transaction is already correcting does not page anyone. A wallet can therefore show as low in the Console for several minutes before the alert confirms it and fires.

The cutoff is 0.1 whole units of the chain's own native currency, on every network. The platform divides each balance by that chain's decimals before publishing it, so the one figure means the same native amount everywhere, with no common fiat value across networks.

## What happens when a wallet empties [#what-happens-when-a-wallet-empties]

When an operator wallet empties, the platform pauses the work it pays for, records a funding requirement against the organisation, and waits. A paused write has not been broadcast, so it has no partial effect on chain. A queued account-abstraction operation is held as `BLOCKED` until the payer is funded. [How gas is paid and funded](https://docs.settlemint.com/docs/concepts/custody-and-signing/gas-funding#when-a-wallet-runs-out-of-gas) covers the requirement and the writes that fail instead of pausing.

The funding requirement is the signal to look for. It names the wallet, the shortfall and a recommended amount to send, and it moves from active to resolved on its own once the money arrives. A paused transaction request keeps its state, and its status read names the open requirement in `activeRequirement`.

An integration with no Console open can subscribe to `funding.requirement.raised`, `funding.requirement.resolved` and `funding.requirement.expired` to learn the same thing. The [funding event catalogue](https://docs.settlemint.com/docs/api-reference/webhooks/events#funding) explains each event. These events need an explicit subscription, because the [default subscriptions skip them](https://docs.settlemint.com/docs/api-reference/webhooks/subscriptions#events-the-default-subscriptions-do-not-deliver).

[Figure] A gas shortfall is a wait, not a failure, until the window runs out. When an operator wallet's balance cannot cover the next transaction, the work that depends on it pauses instead of failing. Nothing is broadcast to the chain and nothing queued is discarded, and a funding requirement is raised against the organisation naming the wallet and the shortfall. The platform then re-checks the requirement when it sees the wallet's balance change, without anyone triggering the check. If the wallet is funded within the window, the paused work resumes on its own and nothing has to be resubmitted. If the window elapses first, the work fails terminally and reports the gas required error, DALP-9087. Labels: What happens when the wallet runs dry; The balance cannot cover the next transaction; the work that depends on this wallet is affected first; Nothing is broadcast and nothing is discarded; The work pauses; queued work stays queued, and a funding requirement is raised; The requirement is re-checked when the balance changes; nobody has to trigger the check; funded; not in time; Funded in time; The work resumes on its own.; Nothing is resubmitted.; Window elapses; The work fails terminally; and reports DALP-9087.

The queue holds while you fund, and the clock decides only whether the work you were waiting on is still there at the end.

The wait is bounded. Each funding requirement has a window set per network. Once it elapses, the paused work stops waiting and fails with the gas required error, [DALP-9087](https://docs.settlemint.com/docs/api-reference/errors), naming the address and the shortfall. Act on a low reading before the alert confirms it.

One related failure looks similar and behaves differently. An account-abstraction operation the platform has already agreed to sponsor has its own expiry, and funding a wallet does not extend it. When a sponsorship expires while the operation waits in the bundler, before anything is submitted, the platform prepares the operation again with a fresh sponsorship and signs it again. It does this up to three times. An operation the caller signed itself is not prepared again and fails at once. After the third renewal lapses, or when the sponsorship expired before signing finished, the operation fails. The message a participant sees then says the sponsorship expired before it reached the chain, that nothing was submitted and nothing was charged, and that they can start again. If a multi-party approval was collected for it, that approval has to be collected again too.

## Deciding what to do about a low reading [#deciding-what-to-do-about-a-low-reading]

A low reading calls for a top-up. Waiting instead of funding only makes sense when a transfer already sent clears the dip before the funding window closes. The cutoff itself is not adjustable: the alert and the Console payer status read the same 0.1 mark, so neither can be moved without the other. [Transaction funding](https://docs.settlemint.com/docs/console/organisation-settings/transaction-funding#choosing-how-to-respond) walks through choosing between the two and the steps for each.

There is no configured target balance for a wallet listed for monitoring, and nothing measures how fast it spends, so there is nothing to project into a runway for it. What the platform gives you instead is per-shortfall guidance: when a funding requirement is raised, it recommends an amount that covers the measured cost with headroom on top. Size a routine top-up for that kind of wallet from your own history of those recommendations.

The organisation's bundler wallet is different. The platform already tracks its seven-day gas burn and combines it with the paymaster deposit and the refund splitter's own balance to record a runway in days for that chain, a spending-rate picture a monitored wallet has no equivalent of. That recorded runway spans the whole refund loop, not the bundler wallet's balance alone. The low-balance cutoff does not watch it, so treat it as a second signal that pages no one. [Transaction funding](https://docs.settlemint.com/docs/console/organisation-settings/transaction-funding#size-a-top-up) uses that spending rate to suggest a top-up amount.

Nothing tops these wallets up automatically, with one narrow exception. The [refund splitter](https://docs.settlemint.com/docs/concepts/custody-and-signing/gas-sponsorship#how-a-sponsored-operation-reaches-the-network) routes a configured share of each gas refund to the organisation's bundler wallet. It only moves value the organisation already holds, and it never reaches a wallet listed for monitoring.

The gas required error, [DALP-9087](https://docs.settlemint.com/docs/api-reference/errors), names the wallet that was refused, in its `data.address`. When that is the participant's own wallet, the participant funds it. When it is a shared gas wallet, such as the relayer wallet, the bundler wallet or the paymaster deposit, the organisation does.

## Frequently asked questions [#frequently-asked-questions]

### Does the fifteen-minute confirmation reset if the balance briefly recovers?

Yes. The alert fires only when the balance has stayed below the cutoff continuously, so a single reading at or above it restarts the fifteen-minute window. The Console has no window to reset: its payer status follows the recorded balance. A wallet hovering around the cutoff can flicker in the Console for a long time without paging anyone, so a quiet pager is no proof that the balance is healthy.

### Why does a wallet at zero not page on a development chain?

The alert excludes chains that report their gas as free. On a chain where transactions cost nothing, zero is the expected resting balance of every wallet, so paging on it would be noise. The exclusion applies at any balance, not only at zero. The Console agrees on such a chain: its Transaction funding page marks the network as needing no funding and never marks its wallets low.

### Two workflows stall on the same wallet. Do I get two funding requirements?

No, one. Only one funding requirement can be active per organisation, per wallet, per network, so a second piece of work short on the same wallet attaches to the existing requirement instead of raising its own. The workflows share the requirement, but each checks the funds it needs before continuing. Concurrent spending can require another top-up.

### What does the recommended amount on a funding requirement cover?

Two numbers travel with a requirement. The amount that releases the pause is what the refused work itself needed, measured at the refusal with a buffer for fee drift. When the platform has a forecast for the remaining work, the recommended total is larger and sized so one transfer can cover the whole run. When it does not, the recommendation is the same amount as the shortfall. Sending only the smaller amount is valid and releases the pause, but the wallet can run short again a few steps later and raise a new request.

## Related concepts [#related-concepts]

- [Smart Wallet](https://docs.settlemint.com/docs/concepts/custody-and-signing/smart-wallet): The account whose account-abstraction user operations a per-organisation bundler wallet bundles and pays gas to land on chain.
- [Gas sponsorship](https://docs.settlemint.com/docs/concepts/custody-and-signing/gas-sponsorship): The two settings that decide which wallet pays gas, and how the bundler wallet and paymaster deposit pay for a smart wallet operation.
- [Transaction Queue](https://docs.settlemint.com/docs/concepts/settlement/transaction-queue): Where a paused account-abstraction operation sits, holding its place rather than failing, while its operator wallet waits to be funded.
- [Audit trail](https://docs.settlemint.com/docs/concepts/records-and-evidence/audit-trail): The record of who changed a wallet's monitoring configuration.


# Smart Wallet

Source: https://docs.settlemint.com/docs/concepts/custody-and-signing/smart-wallet
A Smart Wallet lets a tenant require several signers to agree before an instruction moves assets, with the rule enforced on chain, not by one private key.



[Figure] Where a smart wallet keeps its rule. Three signers hold different weights: a treasury lead with weight 2, and two managers with weight 1 each, four in total. Their signatures go into the account, which is a contract. Inside the account sits the rule it enforces: a threshold of 3 out of the 4 available weight. The account would refuse an instruction below that threshold, so the platform never submits one: an under-weight instruction waits off chain as a pending approval instead, and only a submission that already meets the threshold reaches the account. Once the threshold is met, the account executes the instruction as the sender. On the chain the account is the party that acted, so roles, compliance checks and the audit trail all name the account address rather than any signer's key. Labels: Signers and their weights; Treasury lead; weight 2; Finance manager; weight 1; Risk manager; weight 1; The smart wallet, a contract account; Threshold: 3 of the 4 available weight; The account itself adds up the weight that signed.; Below the threshold, it waits off chain instead of reaching the account.; threshold met; The account executes the instruction; It sends the call. No signer's key is the sender.; one instruction, one sender; On the chain, the account is the party; Roles, compliance checks and audit name its address.

Weights sit with the signers, and the threshold rule sits inside the account.

A weighted Smart Wallet needs several signers to agree before it acts. Each signer holds a weight, and their combined weight must clear the account's own threshold whenever the weighted validator is the account's only authorisation path.

The weighted validator checks that threshold on chain, inside the account itself, not in a process beside it. Review every installed validator, since another one can authorise a different signing path. Fees stay separate from authority: the organisation's paymaster can pay the network fee for an instruction the account has already approved, so no signer has to hold funds for fees.

Reconfiguring the account is itself an instruction. With only the weighted validator installed, changing the signer set or the threshold has to clear the current threshold first, the same as any other call. The account's code is shared: the directory administrator can replace it for every account at once.

## Why an account needs a rule of its own [#why-an-account-needs-a-rule-of-its-own]

A weighted Smart Wallet stops any signer whose weight is below the threshold from moving the account's assets alone. A tenant sets how many signers must agree and how much each one's approval counts for, and the account itself checks that agreement before anything executes. The rule for who may act, and how much weight they need, sits in the same account that holds the assets.

An ordinary account on a chain is a private key: whoever holds it can move everything the account holds, at any hour, with no second party in the room. Institutions answer that risk with maker-checker: a maker proposes and a checker authorises. That discipline usually lives in the process around the key, outside the account. A Smart Wallet moves the requirement inside the account: signers hold weights, and an instruction executes only when the weight behind it reaches the threshold.

The account contract holds the signer set and does the arithmetic itself, so no platform process can approve an instruction the signers did not. Adding a signer or lowering the threshold is an instruction that must clear the current threshold first, so the existing signers must agree to any widening. The account's code is the one part that sits outside the signers' control, as [How it works and what it covers](#how-it-works-and-what-it-covers) explains.

The account also separates the fee from the authority. The organisation's paymaster, funded from the organisation's deposit at the EntryPoint, can pay the network fee for an instruction the account has already authorised, so no signer's key has to hold the chain's native token. The paymaster gains no say over what executes. [Gas sponsorship](https://docs.settlemint.com/docs/concepts/custody-and-signing/gas-sponsorship) explains who pays on each network and how the organisation funds it.

Every operation across an asset's [Asset Lifecycle](https://docs.settlemint.com/docs/concepts/issuing-and-markets/asset-lifecycle), from issuance through servicing to redemption, reaches the chain as a transaction some account sent. A Smart Wallet is one way that account decides what counts as authorised, at every stage.

| What differs | A key account | A Smart Wallet |
| --- | --- | --- |
| Who moves the assets | Whoever holds the key | Any set of signers whose weights reach the threshold |
| Where the rule is enforced | In the process around the key | In the account, on chain, before it executes |
| How the rule changes | By changing the process | By an instruction that clears the current threshold |
| Who pays the network fee | The key, from its own native balance | The account, or a paymaster that covered that instruction |
| Who the chain records as the actor | The key | The account |

## Why the check runs in the account [#why-the-check-runs-in-the-account]

The alternative to a rule the account enforces is a rule enforced by whatever produces the account's signature. A managed custody provider or an internal approval process can require the same number of sign-offs before it releases a signature. That check runs off chain, in a system separate from the account, so the account has no way to confirm that every signature it later accepts passed through it. Whoever still holds a key the account accepts can produce a valid signature outside that process entirely.

A Smart Wallet closes that gap by moving the check onto the account itself. The threshold lives on the validator module the account installs, so the account counts the signing weight behind every instruction itself, before it executes anything, whichever key or provider produced each signature. Compliance rules, role grants, and the audit trail already name the account's address, and the threshold check runs at that same address, so there is no second system for those records to reconcile against.

## Running a Smart Wallet day to day [#running-a-smart-wallet-day-to-day]

Once a Smart Wallet is live, an operations team keeps its signer set current as people join and leave, and keeps the gas reserves funded. Without funded reserves, instructions never reach the chain.

You create the account with its signers and the threshold, either directly through the API, where every signer starts at weight 1, or by staffing it through Multisig's draft, invite, and finalise flow, where each seat carries its own weight. A configuration that could never execute anything is refused at creation: a repeated signer address, or a threshold higher than the sum of the weights.

The threshold trades control against convenience. A higher threshold needs more signers to agree before anything moves, including a change to the signer set itself, so it limits what one compromised signer can do, while requiring more signing weight to remain available. A lower threshold keeps things moving with fewer people, at the cost of concentrating effective control in whichever few signers reliably show up. A seat whose weight alone reaches the threshold can act alone. Give the signers whose sign-off is mandatory enough weight that nothing passes without them, and check which signer losses would stop the account reaching the threshold. A mandatory signer must also be available for any repair of the signer set.

Changing the set afterwards follows one rule: a change is an instruction like any other, so the account approves it at the threshold in force. Removing a signer therefore needs the remaining signers to agree, and a removal that would leave their weights short of the threshold is refused when you request it.

An instruction that arrives without enough weight waits as a pending approval. The account would refuse it, so the platform does not submit it. The other signers see the approval on the wallet's Approvals tab, under Shared accounts in the Console sidebar, and co-sign it before an expiry the platform sets from the deployment's approval deadline. Custody Approval, the pending-decision record that tracks each instruction until co-signers resolve it, covers that queue. On the API an approval reads `pending` while it collects weight and `threshold-reached` once the weight is met. It then reads `submitted` and ends as `landed`, `rejected` or `expired`.

[Smart wallets](https://docs.settlemint.com/docs/console/organisation-settings/transaction-funding#change-the-wallet-type), the Console's wallet type for this execution route, need two gas reserves, and each holds back different work when it runs short.

The submission reserve is the organisation's own bundler wallet. It pays to get any instruction on the chain and is always required: when it empties, instructions stall for every participant. Watch it with the [bundler balance read](https://docs.settlemint.com/docs/api-reference/v2), which reports that reserve's live native balance so a gas manager can fund it before it stalls anything.

The sponsorship reserve is the organisation's paymaster deposit, the funds the organisation keeps at the EntryPoint to pay for sponsored operations. It matters only on a network whose gas payer is Paymaster-paid. When it runs short, sponsored instructions wait for a top-up, and they fail with the gas required error if the network's funding window, the time a paused write waits for funds, closes first. A sponsored instruction does not fall back to paying from the account's own balance. Runway is the signal for this reserve: the platform adds the paymaster, bundler and refund splitter balances and divides the total by the bundler's average daily gas cost over the last seven days, and the Console shows the result in days. [How gas is paid and funded](https://docs.settlemint.com/docs/concepts/custody-and-signing/gas-funding) covers both reserves.

[Figure] How the account checks an instruction before it executes. A signer proposes an instruction, and co-signers sign it until the collected weight reaches the threshold. The account then checks the collected weight before anything else: short of the threshold, the instruction goes no further, though the platform holds it back long before this ever matters. Once that clears, a separate step decides who pays: a sponsor may cover the fee for this exact instruction, or with no sponsor the account pays it from its own balance, or the instruction fails if it holds none. Only once a payer is settled does the account execute the instruction as the sender. Labels: A signer proposes an instruction; Co-signers sign until the collected weight reaches the threshold; The account validates the weight against its threshold.; Check one: the collected weight; The account backstops it: a shortfall here is refused outright.; threshold met; A sponsor may cover the fee for this exact instruction.; Check two: who pays the fee; With no sponsor, the account pays itself, or fails without funds.; a payer is settled; The account executes, as the sender.

An instruction clears the account's own weight check first, then the fee question decides who pays, and can still block execution if no payer is available.

## How it works and what it covers [#how-it-works-and-what-it-covers]

A Smart Wallet is a contract account under ERC-4337, the account-abstraction standard. Instructions reach it as signed intents, UserOperation objects that hold a signature, rather than raw transactions. A shared entry-point contract validates each intent and then calls the account to execute it, and the platform's bundler, the off-chain service that batches many participants' intents into one on-chain submission, submits those batches to that entry point. The [smart wallet user operations guide](https://docs.settlemint.com/docs/api-reference/guides/user-operations) lists the REST and JSON-RPC routes that send and track those intents.

The account is modular, following ERC-7579, the modular-account standard. Validation is not compiled into the account: it is a module the account installs. A single-signer account installs a plain signature validator. A weighted account installs a validator that stores each signer's weight and the threshold and compares the collected weight against it. An account can hold up to sixteen validators at once, and cannot be left with none.

Each account is a light proxy that reads its code from the platform directory, the on-chain registry of DALP implementations, on every call. The accounts share that code and none of their state. The directory administrator upgrades every account at once by pointing the directory at a new implementation. No account's signers can choose or refuse that upgrade, and no account can upgrade itself.

An account created with an on-chain identity also gets a recovery module with the platform guardian as its only guardian, at a 72-hour delay. The platform guardian is an address the deployment names when it sets up the account factory. On a single-owner account the guardian can name a replacement owner key, and the replacement takes effect 72 hours later unless the current owner cancels it first. A weighted validator records no single owner, so guardian recovery cannot change a weighted account's signers. The set-guardians and cancel-recovery changes clear the threshold like any other.

The weighted validator answers "may this actor manage this account directly" with no, always, for every actor. Adding a signer, removing one, or moving the threshold therefore has to arrive as an instruction the account validates like any other, which means through the threshold. That restriction holds only when another installed validator does not authorise direct management.

Whether a participant's writes leave from their own key or from their Smart Wallet is an organisation-level setting, not a per-request choice. Flipping it changes which address the chain sees as the actor, so on-chain state written for a participant, such as identity registrations and role grants, follows the address that wrote it. A participant created as key-only, or as account-only, keeps its own route either way. The setting governs the rest.

## The integration contract [#the-integration-contract]

On the API, a Smart Wallet is one object with its address, its installed validators, its signers and their weights, and its threshold. You create the account once, read it from the indexed record, and change its signer set and threshold through separate queued writes.

Creation through the API takes the participant, the network, the signer addresses and the threshold. Every signer joins at weight 1, so the threshold must lie between 1 and the number of signers. The request is rejected before anything starts when an address repeats or is not a valid EVM address, when the threshold cannot be reached, or when the participant holds no active custody account on that network. A participant with no Smart Wallet address recorded on that network, which is the case in an organisation that does not route writes through Smart Wallets, is refused with `404` before anything starts. On a deployment with the Self-custody module switched off, more than one signer or a threshold higher than 1 is refused with `403` `MULTISIG_NOT_ENABLED`. When only the organisation has switched the module off, the same request is refused with `403` `platform.module.DISABLED`, which names the module in `data.module`. The participant's custody account on that network carries at most one Smart Wallet, and a create completes the one already recorded there: it links that wallet to the custody account and changes no signer. A signer set or threshold the recorded wallet does not already hold is refused with `409` `CUSTODY_LIFECYCLE_CONFLICT` before anything starts. Change signers through signer management instead. The platform records the signer set and threshold of the first create call it accepts for that participant and network. A later call that repeats them, in any order or letter case, returns the same request, and a call that names a different signer set or threshold is refused with `409` `CUSTODY_LIFECYCLE_CONFLICT`, whether the first wallet is still being created or already exists. A signer set with different weights comes from the Multisig draft flow, where each seat carries its own weight.

Creation is a queued write, not a synchronous one. The response carries a request identifier and the status `accepted`, which tells you the platform took the request, not that the account exists. Follow the request at `GET /api/v2/custody/wallet-create-requests/{requestId}`. While the account is being created, it answers `202` with `state: "running"` and a `statusUrl`, which is also sent as `Location`. Once the account exists, it answers `200` with the Smart Wallet, as the wallet read does. A creation that ended without an account answers `409` `CUSTODY_LIFECYCLE_CONFLICT`. Only the participant that made the request can read it, and only a caller who holds the account or a weighted seat on it gets the `200`.

Reads split into two kinds, and the difference decides what you may conclude. The account, its signers and its approvals come from the indexed record and never query the chain, so a change you queued a moment ago is absent there until it is indexed. The gas-status read combines the account's indexed native balance with the network's live gas price, and answers `empty` for a zero balance, `low` for a balance below the cost of 500,000 gas at the current maximum fee, or `funded`. It returns no amount and says nothing about sponsorship. Only a caller who holds the account or a weighted seat on it can read it.

A signer added after creation joins at weight 1, and a signer removed and then re-added returns at weight 1. A separate set-signer-weight change gives it another weight, and like every change to the account it has to clear the current threshold. The account's mutation route takes add-signer, remove-signer, set-threshold, set-signer-weight, install-module, uninstall-module, set-guardians and cancel-recovery changes. The [API reference](https://docs.settlemint.com/docs/api-reference/v2) lists the exact routes.

## Controls and evidence [#controls-and-evidence]

A Smart Wallet is a preventive control at the point of execution. The account validates the collected signer weight before it does anything, so an instruction below the threshold is refused before it executes. The enforcement point is the account contract itself, on chain.

The signer set, the weights and the threshold are on-chain state, and the check runs where the assets are. No signer and no other account can widen the control, provided the weighted validator is the only validator installed. The directory administrator's implementation upgrade is the one change that does not pass through the threshold. The account grants direct access to any actor that any one of its installed validators authorises, so a single-signer validator left in place beside the weighted one would hand its own recorded owner that same direct path. With only the weighted validator installed, it refuses direct management outright, so a change to the signer set, to the threshold, or to which validators are installed, has to clear the threshold in force first. The same fence covers identity claims made on the account, which must arrive through the account rather than from one signer acting alone.

Attribution is the second control the account provides. The party on chain is the account, whichever signer's key produced a signature, so transfer restrictions, role checks and the audit trail all name one address you already govern.

Evidence has two halves. On chain: the signer set, the weights, the threshold, and each amendment to them, with the transaction that made it. On the platform: each pending approval with the weight it required, the weight it collected, and every collected signature with its signer, its weight and its time.

A Smart Wallet is not transfer compliance. The threshold check runs first, during validation. The asset's own rules run later, inside the transfer, and the asset contract enforces them, so a fully approved instruction can still be rejected there. Transfer-Path Compliance is that separate control.

## Frequently asked questions [#frequently-asked-questions]

### How is this different from a multi-signature vault?

No separate vault contract holds assets on behalf of an account. The account itself is the multi-signature arrangement: assets sit in it directly, and the threshold applies to everything it does, not only to withdrawals from a special-purpose contract. That also means there is no second address to reconcile and no bridge step between the account you configure and the account that holds the assets. See Multisig for how a weighted account like this one gets staffed, through a draft, invites, and one finalise step.

### What happens if a signer loses their key?

The remaining signers remove that signer and add a replacement, which is an instruction like any other, so it needs their combined weight to reach the threshold. If the lost signer's weight was necessary to reach the threshold, the remaining signers cannot pass any instruction at all, including the one that would repair the signer set. Guardian recovery cannot help a weighted account either, because it replaces the owner of a single-owner validator and a weighted validator has none. Plan for this when you set the weights: give the account enough signers that no single lost key blocks the threshold.

### Can the fee sponsor change or block what I do?

The sponsor cannot change it. A sponsorship ticket, the authorisation the paymaster checks, names the account and a hash of the exact call it covers, together with a deadline and a fee ceiling. Changing one argument puts the instruction outside the authorisation, and a fee above the ceiling falls outside it too. On a Paymaster-paid network, an instruction the paymaster cannot sponsor fails as blocked by policy, and the account does not pay the fee for it instead. The platform decides whether to issue a ticket, so a signer whose account holds no native balance depends on the organisation's sponsorship being funded and on. An instruction that waits on an unfunded sponsorship reserve resumes once the reserve is topped up within the network's funding window.

### Can an organisation switch back from smart wallets to key wallets?

[Smart wallets](https://docs.settlemint.com/docs/console/organisation-settings/transaction-funding#change-the-wallet-type) is the Console's wallet type for routing an organisation's on-chain work through Smart Wallets and the sponsored-fee path instead of through participants' own keys. The setting is organisation-wide and one-way: once it is on, the platform does not accept turning it off. On-chain state written for a participant, such as identity registrations and role grants, follows the address that wrote it, so switching back would strand what was already written from the account.

### Can a weighted account also keep the single-signer validator installed?

Yes, but doing so reopens the direct-management path the weighted validator closes: the account authorises any actor that any one of its validators authorises, as covered under [Controls and evidence](#controls-and-evidence). Remove the single-signer validator once the weighted one is in place, or never install one, if the threshold should be the only way in.

## Related concepts [#related-concepts]

- [Asset Lifecycle](https://docs.settlemint.com/docs/concepts/issuing-and-markets/asset-lifecycle): The working life of a regulated tokenised instrument. A Smart Wallet is the account that authorises the transactions at every stage, from issuance to redemption.
- [Multisig](https://docs.settlemint.com/docs/concepts/custody-and-signing/multisig): The draft, invite, and finalise process that provisions a weighted Smart Wallet like the one this page describes.
- [Custody Provider](https://docs.settlemint.com/docs/concepts/custody-and-signing/custody-provider): The signing service that holds a controller's key and produces its signature. A Smart Wallet's threshold counts signing weight regardless of which provider signs for any one controller.
- [Custody Approval](https://docs.settlemint.com/docs/concepts/custody-and-signing/custody-approval): The control between a prepared transaction and its signature: before any key signs, the approvers named in the wallet's policy must authorise that exact payload.
- [Maker-checker](https://docs.settlemint.com/docs/concepts/custody-and-signing/maker-checker): The general pattern of one party proposing a change and a different party approving it. A Smart Wallet enforces that split inside the account's own on-chain threshold check, ahead of execution.
- [Gas sponsorship](https://docs.settlemint.com/docs/concepts/custody-and-signing/gas-sponsorship): Who pays the network fee for each write, how the paymaster sponsors a Smart Wallet's user operation, and what happens when a paying wallet runs out of funds.
- [Operator Wallet](https://docs.settlemint.com/docs/concepts/custody-and-signing/operator-wallet): The organisation's bundler wallet that pays gas for the account-abstraction operations a Smart Wallet submits, funded separately from any sponsorship a Smart Wallet's own instruction receives.
- [Settlement Verdict](https://docs.settlemint.com/docs/concepts/settlement/settlement-verdict): The recorded end state of an on-chain operation submitted to the platform, either completed, failed, dead letter, or cancelled, and the only signal from which success may be reported.
- [Transfer-Path Compliance](https://docs.settlemint.com/docs/concepts/compliance-and-identity/transfer-path-compliance): The enforcement of a regulated token's rules inside the on-chain transfer itself, so a movement that fails any rule reverts and never settles.


# User operations

Source: https://docs.settlemint.com/docs/concepts/custody-and-signing/user-operations
Submit a signed smart-wallet user operation, replace a pending one, estimate gas, read its status and receipt, and see how it settles.

The platform runs an ERC-4337 bundler for each organisation and network, so you send signed user operations to its API instead of running your own bundler, funded [operator wallet](https://docs.settlemint.com/docs/concepts/custody-and-signing/operator-wallet), queue, nonce manager and settlement process. A user operation is the signed instruction a [Smart Wallet](https://docs.settlemint.com/docs/concepts/custody-and-signing/smart-wallet) submits, and an EntryPoint contract validates and executes it.

Each organisation and network has one bundler, its own stored operations, and two interfaces: the Platform API for a typed request and an ERC-4337 JSON-RPC endpoint for a client that already speaks the standard. An ordinary platform write to a deployed single-owner smart wallet takes the same path without starting a transaction workflow.

## Send a user operation [#send-a-user-operation]

`POST /api/v2/bundler/{chainId}/send` takes the canonical EntryPoint and a signed user operation. The platform checks that the EntryPoint is the one this network supports and that the sender belongs to the calling organisation, simulates validation, and stores the operation before answering with its hash. The call does not wait for bundling: a returned hash means the operation is stored, not that it executes. The bundler picks the stored operation up from there.

These checks run before the operation is stored:

- **The payer's funds.** For a [sponsored](https://docs.settlemint.com/docs/concepts/custody-and-signing/gas-sponsorship) operation the platform reads the paymaster's EntryPoint deposit. Otherwise it reads the sender's balance plus its deposit. When the operation's prefund, added to the prefund of the payer's other live operations, exceeds those funds, the submission is refused with `AA31` when the paymaster's deposit is too low, or `AA21` when the sender cannot pay its prefund, the gas the EntryPoint reserves before it runs the operation. A network that charges no gas skips the check, and so does a submission whose funds cannot be read.
- **The priority fee.** A priority fee below the deployment's configured minimum is refused. A network whose fee quote is zero for both fee components is exempt.
- **The maximum fee.** The signed `maxFeePerGas` must reach 1.5 times the base fee of the network's latest block plus the operation's own priority fee, and the base fee counts as zero on a network whose blocks carry none. That is the headroom the bundler signs its bundle with, so the operation still repays the bundle's price if the base fee rises by up to half before the bundle lands. A lower value is refused with a message that names the floor.
- **The pre-verification gas.** The signed `preVerificationGas` must reach the gas the bundler pays to carry the operation, which is the value the estimate returns. A lower value is refused with a message that names the price.
- **The size.** On a network whose blocks carry a calldata floor, an operation larger than the deployment's limit is refused. The default limit is 8,192 packed and ABI-encoded bytes, the ERC-7562 limit.
- **The sender's standing.** When a bundle reverts on chain because an operation became invalid after the platform admitted it, for example because its sender spent the nonce or the funds elsewhere, that sender is refused on the organisation's bundler for a while, 24 hours by default. Only the sender of the operation the revert names is refused, never the other senders in the bundle. A revert on the platform's own paymaster, or on the platform's own operation, refuses no one. The sender's other waiting operations fail instead of being bundled.
- **The pending limit.** An organisation may have a limited number of operations sent through these routes waiting on one network at once, 256 by default. A replacement does not count as a new operation, and neither do the platform's own operations.

A sender refusal and the pending limit answer `429` with code `exec.aa.ADMISSION_THROTTLED`, or JSON-RPC error `-32504`. Both are retryable platform errors: a sender refusal carries `retryAfterSeconds`, and a pending-limit refusal clears as the organisation's operations are bundled. The three limits are deployment settings.

An operation that signs zero for both fee fields on a network whose fee quote is zero for both fee components is exempt from the maximum-fee and pre-verification gas checks, and from the size limit, while the latest block carries no base fee. When that block charges a base fee, `send` refuses it, because no bundle can carry it.

The base fee and the network's fork can change between `send` and the bundle, so the bundler runs the maximum-fee and pre-verification gas checks again on each signed operation, against the block it builds the bundle on.

- An operation whose maximum fee is below that block's floor stays `PENDING` and is checked again at every new block, so it joins a bundle once the base fee falls far enough. Later operations in its lane, the sequence of operations from one sender and one nonce key, wait behind it. A replacement with higher fees sends it sooner.
- It fails if it is still below the floor an hour after the platform last stored it. That hour counts from when it was sent, replaced, released from `BLOCKED` or returned by a dropped bundle.
- An operation whose pre-verification gas is below that block's price can never be carried, such as one stored before a fork raised the calldata floor, so it fails. So does an operation whose maximum fee is below its own priority fee, and one that signs zero for both fee fields on a network that charges a base fee.

Each of these failures carries the error `PRE_FLIGHT_REJECTED`, and the caller sends a new operation with higher fees. An operation that signs zero for both fee fields on a network whose blocks carry no base fee files its bundle at zero fees and skips the pre-verification gas check.

The answer is the operation hash. Submitting the same hash again returns that hash instead of storing a second operation. While the bundler has not accepted the stored, prepared operation, the repeat hands it to the bundler again, which covers a hand-off that was lost. The status and receipt reads below are scoped to the organisation and the network, so a hash outside the organisation's stored operations answers null.

## Replace a pending operation [#replace-a-pending-operation]

`POST /api/v2/bundler/{chainId}/send` with a second signed operation from the same sender at the same nonce replaces the pending one, which is how you reprice an operation whose fees are too low.

- The original must still be a signed operation the integrator submitted, waiting for a bundle. An operation already written into a bundle cannot be replaced, and neither can one the platform prepared itself.
- The replacement's maximum fee and priority fee must each reach the original's value multiplied by 1.1, rounded down to a whole wei.
- A replacement swaps the stored operation and its hash in one step and wakes the bundler, so the original hash then reads as unknown.
- A refusal names its reason: the original is in a bundle, the fee rise is too low, or the operation cannot be replaced.
- The original's prefund does not count against the payer's funds for its replacement.

## Estimate gas [#estimate-gas]

`POST /api/v2/bundler/{chainId}/estimate` returns pre-verification gas, verification gas and a call gas limit, plus the paymaster's verification and post-operation limits for a sponsored operation. It requires a sender the organisation owns.

On a chain that runs the Osaka fork, one transaction carries at most 2^24 gas, and the platform takes the lower of that and the block gas limit. It simulates the call at the limit it is about to return and returns a limit the call finishes within, keeping a 1.05x margin over the measured gas. On a chain that runs the Amsterdam fork, it returns the measured gas with no margin. A call that does not fit the room one transaction leaves is refused with a message that names the measured need and the room. The bundler packs bundles against the same ceiling, so a bundle is not filed with more gas than that ceiling allows.

A chain from the Prague fork on prices a transaction's calldata at no less than a floor. EIP-7623 sets it at 10 gas for a zero byte and 40 for any other byte, and on the Amsterdam fork EIP-7976 raises it to 64 gas for every byte. The floor applies to the whole transaction, so the bundler files each bundle with at least the floor of the calldata it sends. A bundle whose operations cost less than their calldata is filed with the floor instead.

Pre-verification gas is 21,000 plus the larger of two prices:

- The standard price is 85,800 of per-operation overhead plus the operation's encoded bytes at 4 gas for a zero byte and 16 for any other byte, plus 10 gas a 32-byte word.
- The floor price is the same bytes at the chain's floor, plus the 132 bytes of the `handleOps` call that carries them at the floor's non-zero rate.

A small operation stays at its standard price, because its overhead outweighs the floor. A calldata-heavy operation on a floored chain pays its floor, so the bundler is repaid what the chain charges it. The signature, the paymaster data and the fixed-width nonce, gas limit and fee fields count at the non-zero rate whatever bytes they hold. An estimate therefore still holds once the operation is signed with its real nonce and fees.

## Read the status [#read-the-status]

`GET /api/v2/bundler/{chainId}/user-operations/{userOperationHash}` reads the stored operation: its sender, nonce, call data, creation and update times, transaction hash and block number when recorded, its error when one was recorded, and one status.

| Status | What the operation is doing |
| --- | --- |
| `PENDING` | Accepted, reserved against its lane, or being prepared. Nothing has left the platform yet. |
| `BLOCKED` | Waiting on an approval, on payer funds, on bundler funds or on a sponsorship renewal. |
| `BUNDLED` | Written into a bundle that the platform has sent. |
| `MINED` | The bundle landed. The receipt says whether the operation itself succeeded or reverted, and `error` carries the revert data. |
| `FAILED` | It does not execute. The error names the reason. |

The read finds an operation by its hash, so it never answers for a prebuilt operation nobody signed. A `MINED` operation whose call reverted settles as failed. The platform does not re-sign it with a larger gas limit, so the caller sends a new operation.

## Read the receipt [#read-the-receipt]

`GET /api/v2/bundler/{chainId}/user-operations/{userOperationHash}/receipt` answers only after the stored operation is confirmed or reverted on chain, and it answers null before that, and for a missing operation. The block hash comes from the stored settlement. For an operation settled before the platform recorded block hashes, the platform reads it from the network's transaction receipt, and the answer is null while the network returns none. The receipt carries the user operation hash, sender, nonce, a success flag, the transaction hash, the block hash and the block number, plus the failure reason when the operation reverted.

## Use the ERC-4337 endpoint [#use-the-erc-4337-endpoint]

`POST /bundler/{chainId}` speaks ERC-4337 JSON-RPC. It supports `eth_chainId`, `eth_sendUserOperation`, `eth_estimateUserOperationGas`, `eth_getUserOperationByHash`, `eth_getUserOperationReceipt`, `eth_supportedEntryPoints`, `pm_getPaymasterData` and `pm_getPaymasterStubData`. The two paymaster methods apply the sponsorship rules, and their network argument must match the network in the route.

The route needs an API key with an active organisation and write scope. The network must be available to that organisation. Its default network qualifies when it is an enabled EVM network. Another network also needs multi-network access and an active deployment on that network. A batch holds 1 to 100 requests, and a batch that holds only notifications answers HTTP 204 with no body.

## Write directly from a deployed single-owner wallet [#write-directly-from-a-deployed-single-owner-wallet]

An ordinary platform write that goes to a smart wallet with one managed owner key skips the transaction workflow. The write takes the bundler path when no approval policy gates the wallet, the plan clears with that one owner and holds no weighted signers, the account already has code on chain, the organisation does not use gasless forwarding, and the write is not the one that deploys the account.

The platform stores the request and its user operation row in one commit, and hands the row to the bundler only after that commit. The request reaches `COMPLETED` once the bundler has confirmed the operation, and a caller that asked to wait receives that settled outcome within its wait budget. A caller that did not ask to wait gets the request identifier at once. A write that does not qualify, such as a gated, multisig, owner-signed or first write, runs the transaction workflow and reaches the bundler from there. A repeat of a qualifying write with the same idempotency key starts nothing new.

## What happens to an operation no bundle executed [#what-happens-to-an-operation-no-bundle-executed]

A mined bundle can hold an operation the EntryPoint did not execute. The platform reads the operation's nonce at the EntryPoint and searches the EntryPoint's event log for it, and settles on that evidence, so the wallet's lane does not wait.

- One event settles the operation with its real outcome: confirmed, or failed with the data it reverted with.
- A nonce still unused and no event means the EntryPoint did not execute the operation. The platform returns it for a later bundle, at most three times. The next bundle that still carries no event for it fails it with a reason that says the EntryPoint never executed it.
- A nonce that is used with no event means another operation took it, so this one can never execute. It fails with a reason that says the nonce was consumed for another operation.
- A bundle that was never broadcast is abandoned and its operations return for a new bundle. A bundle whose transaction reverted is replayed at the block before it mined: the replay names the failing operation, and the rest return.
- Several events for one operation, a nonce that moved without an event, or a failed chain read hold the bundle with a visible reason and settle nothing.

Inside a mined bundle, elapsed time alone never settles an operation. A sponsorship that expired on a sponsored operation is renewed instead of failing the operation, and a used nonce alone is not evidence until the event log is read.

## What happens to a nonce the bundler skipped [#what-happens-to-a-nonce-the-bundler-skipped]

The bundler wallet sends every bundle at its own transaction nonce, and the chain mines those nonces in order. A nonce that is never sent therefore holds back every bundle above it. A withdrawal from the bundler wallet that was granted a nonce and then rejected leaves exactly that hole.

The platform counts the wallet's nonces from the number the chain has mined, and uses the node's pending count only to find the highest nonce in use. Some nodes count a run of queued transactions above a hole as if the hole were filled, so the pending count alone would hide it.

- A nonce nothing holds goes to the next bundle or withdrawal. When bundles wait above it, the platform fills it with a transfer of zero value from the wallet to itself, after three blocks with no operation ready.
- A nonce that a withdrawal still holds is never filled and never handed to another write.
- A gap-filling transfer stays owned until the chain mines past its nonce. If no configured node knows it six blocks later, the platform releases it and fills the nonce again.
- A bundle the platform cannot read back after a restart is judged by its own transaction hashes. If no configured node knows any of them and the wallet has not reached the nonce, the platform holds the bundle as dropped and raises an alert. It never frees or resends a dropped bundle, so bundling for that organisation and network waits until an operator decides what happens to it.

## What happens to a reservation nobody signed [#what-happens-to-a-reservation-nobody-signed]

A caller that prebuilds an operation reserves the wallet's lane for a lifetime it asks for, and the platform stamps the row with the moment that lifetime lapses. A sweep then closes the rows that were never signed, never bundled and never hashed:

- A prebuilt operation past its lifetime expires with the reason `reservation-expired`, and the caller prepares a new one. It was never signed, so it has no hash and the status read does not find it.
- A reserved operation the platform owns that lapses without a signature fails with the same reason.
- A prebuilt row that was never reserved and has sat for an hour also expires.
- A row whose signature is already stored, or is being committed, is never expired.

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

- After you submit a signed operation and keep its hash, the status reads `MINED` or `FAILED`.
- The receipt carries the block number that a reconciliation uses as evidence.
- A `MINED` status with a receipt whose success flag is false is a call that reverted.

## Related pages [#related-pages]

Read [Smart Wallet](https://docs.settlemint.com/docs/concepts/custody-and-signing/smart-wallet) for the threshold that authorises an operation before it is signed, [Operator Wallet](https://docs.settlemint.com/docs/concepts/custody-and-signing/operator-wallet) for the account that pays the bundle, and [Transaction lifecycle](https://docs.settlemint.com/docs/concepts/settlement/transaction-lifecycle) for the workflow an ordinary platform write runs when it does not take this path.


# Platform Event

Source: https://docs.settlemint.com/docs/concepts/events-out/platform-event
A Platform Event tells an integration what happened through a named, versioned message, so it need not interpret raw chain logs.



[Figure] One chain fact becomes one row for each subscriber. An indexed chain fact enters at the top, identified by chain, block number and log index. It passes through the catalogue, the focal element: a fixed set of named events, one payload shape for each name and version, with machine-readable definitions generated from the registry. From the catalogue the fact fans out into one row for each subscribed endpoint. Every row carries its own identifier, unique across the whole platform. Its sequence number is scoped to the endpoint, so two endpoints can both hold sequence one for the same fact. Rows commit in the same transaction as the indexed fact, ordered by chain position and then each endpoint's own sequence. At the bottom, a later chain reorganisation never edits a row already sent: a retracted event arrives instead, naming the identifier it replaces. Labels: One occurrence, every subscriber; One indexed chain fact; A contract log the indexer wrote, identified by chain, block number and log index; The catalogue; Each event name and version fixes its payload shape; Generated definitions are checked against this one list; Endpoint A; Its own event identifier; Its own sequence number; Endpoint B; Its own event identifier; Its own sequence number; One row for each subscriber, committed with the indexed fact; Ordered by chain position, then the endpoint's own sequence; A chain reorganisation never edits what was already sent; A retracted event arrives instead, naming the identifier it replaces.

The catalogue decides what an event is called and what it contains, and everything downstream copies that decision.

An integration reads what happened, and how settled that fact is, without polling the chain or running its own indexer: one registry binds each event name and version to exactly one payload shape.

Every event names its lifecycle state. Read it with the event type: final can mean chain finality or a committed platform outcome. A final transaction-request event does not itself confirm a token movement.

Delivery retries can produce duplicates. Deduplicate on the event identifier and reconcile missing or retracted events.

## Why an integration needs a catalogue, not raw logs [#why-an-integration-needs-a-catalogue-not-raw-logs]

A platform event is how an integration learns what happened on the platform: what occurred, when, and how settled that fact is. A chain log answers the first two on its own. It says nothing about the third, because the block behind it can still be reorganised.

The alternative to the platform's event vocabulary is an integration that reads raw logs itself. It decides, on its own, how deep a block must sit before a fact counts as final, and what to do when a block it already trusted gets replaced. Made once, by the platform, that decision is the same for every subscriber, and the envelope states it. Made independently by every integration, it is a second reading of the same chain, on that integration's own schedule and its own judgment of depth.

Each handoff between separate systems is a reconciliation. A platform event pins the handoff to one record: what the integration was told, checked against what the platform's own indexed record says happened. The platform keeps that delivery record for 30 days after it settles, so retain what your reconciliation needs.

That list is not tied to one stage of an instrument's life the way a coupon payment belongs to servicing. Issuance, servicing and an eventual retirement each produce their own facts, and each one reaches an integration through this same catalogue, tagged with one of five lifecycle states.

## Why this catalogue lives on the platform, not in a tenant's own indexer [#why-this-catalogue-lives-on-the-platform-not-in-a-tenants-own-indexer]

The alternative to a platform-run catalogue is a tenant indexer running beside the platform: watching the same chain, choosing its own reorganisation depth, and turning raw logs into its own vocabulary. That second indexer answers the same question the platform already answers, from a read of the chain that only the tenant sees.

This catalogue holds no second reading, because the same indexer that decides a chain fact for the platform's own record is the one that derives the outbox row a subscriber later receives. The event and the indexed fact it describes come from that one decision, not from two.

## A vocabulary that cannot move under you [#a-vocabulary-that-cannot-move-under-you]

A platform event is one entry in a vocabulary defined by a single registry. Each entry binds an event name and version to one payload shape. The build rejects a second registration of the same name and version.

That guarantee targets the two quiet ways an integration built on notifications usually breaks. A field changes shape and the consumer keeps parsing the old one. Or a name starts covering a slightly different occurrence and nobody tells the consumers. Both fail silently, and a reconciliation turns them up weeks later.

The platform generates the [machine-readable event manifest](https://docs.settlemint.com/.well-known/dalp-events.json), event types for the [TypeScript SDK](https://docs.settlemint.com/docs/api-reference/sdk), and sample payloads from that registry. The [event catalogue](https://docs.settlemint.com/docs/api-reference/webhooks/events) is written by hand and checked against the registry. It explains when each event is sent and what a receiver does with it. Payload schemas and examples stay in the machine-readable definitions. Registration alone does not prove the platform sends an event. The catalogue separates live events from reserved names.

An integration selects the published payload contract by event name and version. Read both fields before interpreting the payload.

## The envelope states how settled a fact is [#the-envelope-states-how-settled-a-fact-is]

Every platform event has a `lifecycle_state`: pending, provisional, final, retracted, or recalled. Recalled is reserved. No live event uses it. Many names end in a state, such as `token.transfer.final`, but others end in a word such as `raised` or `published`. Read the envelope's state and event type together. The [lifecycle reference](https://docs.settlemint.com/docs/api-reference/webhooks/lifecycle) describes the live sequences and reserved states.

[Figure] Lifecycle vocabulary includes one reserved state. The vocabulary has five states. Recalled is reserved. The platform does not send it. A pending event reports a transaction request that was broadcast and is not confirmed. A provisional chain event reports an observation that a reorganisation may remove. A final chain event follows the configured finality depth. Retractions withdraw earlier facts after a reorganisation or a business reversal. A state change is a separate event, not an edit to a delivery already sent. Labels: The envelope names the state; pending; Request broadcast; Awaiting its outcome; provisional; Accepted by the chain; A reorganisation may still undo it; final; Past the configured depth; A reorganisation cannot reach it; retracted; Follows a chain reorganisation; Supersedes the event it replaces; recalled; A deliberate operator withdrawal; Reserved, not sent.

A state change is a new event and so is a correction, and nothing edits a delivery already sent.

For chain observations, provisional means included but still within the network's configured confirmation depth, and final means the source block has passed that depth. A platform administrator sets that depth for each network. The platform emits provisional at inclusion and final after the depth is reached. A chain reorganisation within the depth can retract a delivered provisional event. A reorganisation deeper than the configured depth is outside what a final event promises.

A fact does not change state in place. The same movement reported first as provisional and later as final reaches you as separate events with separate identifiers. Watch for the later event rather than for a field changing on the earlier one.

A retraction reports that an earlier fact no longer stands. It can follow a chain reorganisation or a business reversal, such as a trade bust. The platform leaves the earlier delivery intact. The [consumer contract](https://docs.settlemint.com/docs/api-reference/webhooks/consuming#retractions) defines how to match the correction, including when its `supersedes` field is absent or names an event you never received.

Pending reports a transaction request that the platform broadcast and that is not confirmed. A request outcome uses `final`, including a failure or cancellation. This is the request's outcome, not a token movement's chain finality. Recalled is a reserved state, and no live event uses it.

## From one log to one row per subscriber [#from-one-log-to-one-row-per-subscriber]

For an event derived from a chain log, the platform records one pending delivery for every endpoint whose subscription matches the event name, in the same database transaction as the indexed fact. No queue sits in memory between the two, so the event and the indexed state it describes commit together or not at all.

Transaction-request events describe a different source: a state change recorded inside the platform. The platform records the event together with that state change, rather than deriving it from an indexed chain log.

The fan-out is per subscriber, not per fact. Ten subscribed endpoints mean ten rows from one log, each signed on its own and each with its own identifier, so one endpoint's delivery history says nothing about another's.

Every subject area the indexer writes, token movements and identity and role changes alike, handles a failure to write those rows the same way. A failure to record the deliveries blocks the indexed write, so the whole unit retries together. When the retry succeeds, the indexed change and its notification land in that same commit, so a caller never sees one without the other. No gap can open between the indexed fact and its recorded delivery, and [Webhook Delivery](https://docs.settlemint.com/docs/concepts/events-out/webhook-delivery) moves that delivery to your endpoint. The cost is that a delivery-recording problem delays the indexed record too.

Each endpoint has its own delivery sequence. A later eligible event waits while an earlier event remains pending, including during retry backoff. A linked correction waits until its cause was delivered or can no longer be delivered. Events waiting for chain finality do not block later events. A Replay can deliver an older observation after a newer one, so keep the newest state you hold. The [ordering contract](https://docs.settlemint.com/docs/api-reference/webhooks/consuming#ordering) states the limits.

## Writing a consumer that stays correct [#writing-a-consumer-that-stays-correct]

A correct consumer subscribes only to the states it handles, deduplicates on the event identifier, and applies a superseding event by looking up the identifier that event names instead of assuming order.

An endpoint subscribes with patterns. A pattern matches a name prefix, as in `token.transfer.*`, a name suffix, as in `*.final`, or one exact name. The defaults match names ending in `.provisional`, `.final`, and `.retracted`, not the envelope's lifecycle state. The [subscriptions reference](https://docs.settlemint.com/docs/api-reference/webhooks/subscriptions#events-the-default-subscriptions-do-not-deliver) lists live events these defaults skip. A `*.pending` pattern delivers nothing, because no live event name ends in `.pending`. A subscription change replays no earlier events. Replay is a separate request.

The `webhook-id` header carries the event identifier. Store each identifier and check it before you act. Delivery, the signed HTTPS POST that carries one event to one subscribed endpoint, uses bounded retries: a retry after a lost acknowledgement can repeat a delivery your endpoint already processed. Nothing on the platform side deduplicates for you.

Treat an event as an append-only record rather than as an update. When a later event supersedes an earlier one, it includes a `supersedes` field naming the identifier it replaces, and the platform never rewrites the original delivery. That field holds one identifier, never a list, so a superseding event always points at exactly one predecessor. A consumer that applies a retraction by looking up the superseded identifier and reversing its effect stays correct through a reorganisation. A consumer that overwrites in place cannot tell the difference between a correction and a fresh occurrence.

The platform publishes machine-readable definitions as a subscription manifest, the [DALP events manifest](https://docs.settlemint.com/.well-known/dalp-events.json), with a version marker that identifies the inventory it describes. Pin that marker if you generate code from the manifest, so an inventory change is a decision you make rather than one that arrives during a deploy.

## Frequently asked questions [#frequently-asked-questions]

### Does subscribing to an event name guarantee the platform sends it?

No. The published manifest lists only the event names the platform sends, and schemas for names it does not send stay available for historical decoding. The live names include the access-control role events, asset creation, burn, issuance and pause events, compliance freeze and unfreeze events, identity registration events, the transfer events `token.transfer.provisional`, `token.transfer.final` version 2, and `token.transfer.retracted` versions 1 and 2, the identity claim events, the provider verdict event, the trading venue order status event, token sale events, identity status, custody events, and the eleven XvP settlement events under `xvp.*.final`. Compliance recall, settlement retraction, and pre-inclusion pending names have no active producer.

### Can a retracted or recalled event itself be retracted later?

No. A retraction caused by a chain reorganisation supersedes a provisional observation, or a stored version 1 `token.transfer.final` event, a legacy event the platform sent at inclusion. A retracted or recalled event is not itself retracted by a later chain reorganisation.

### Do two endpoints see the same identifier for the same occurrence?

No. An identifier names one endpoint's delivery record, not the occurrence itself, which is why deduplication works per endpoint rather than across endpoints.

## Related concepts [#related-concepts]

- [Asset Lifecycle](https://docs.settlemint.com/docs/concepts/issuing-and-markets/asset-lifecycle): The whole working life of a regulated tokenised instrument, from issuance through servicing to redemption. Each stage produces its own platform events, all through this one catalogue.
- [Webhook Delivery](https://docs.settlemint.com/docs/concepts/events-out/webhook-delivery): The transport that moves an event to your endpoint: the signed request, the retry schedule and the replay rules. The event is the fact, and delivery carries it to your endpoint.
- [Error Contract](https://docs.settlemint.com/docs/api-reference/guides/errors): The stable identifier and taxonomy on a failure, which lets a caller decide whether to retry, fix the request or escalate. It answers for a request that failed. An event reports something that happened.
- [Command Surface](https://docs.settlemint.com/docs/api-reference/cli/commands): The generated tree of platform commands. Like the event manifest and SDK types, it is generated from its defining contract. The hand-written event catalogue explains the events and is checked against their registry.


# Webhook Delivery

Source: https://docs.settlemint.com/docs/concepts/events-out/webhook-delivery
Webhook Delivery signs each event, retries failures for three days and records every attempt, so your receiver needs no retry logic of its own.



[Figure] The platform records each attempt, and the receiver deduplicates. The platform records the event first, and the delivery machinery works from that row rather than from memory. It then signs an envelope, whose headers follow the Standard Webhooks scheme, giving the message an identifier, a signature and a timestamp, with the platform adding its own delivery identifier and endpoint identifier beside them. The platform leases the row for the attempt, and the POST and its database record are separate effects. A crash frees the lease, and the next scan reclaims the row: a send whose outcome was never recorded can repeat. Each attempt has twenty seconds to finish, and one of three outcomes follows. A 2xx reply means the consumer accepted the message and the delivery ends there. A retryable failure goes back on an exponential curve that starts near thirty seconds and doubles, with the platform multiplying each delay by a random factor between 0.7 and 1.3. A terminal failure stops at once because repeating it cannot help, meaning a 4xx reply other than 408 or 429, a counter-signed receipt with a valid signature but a body hash that does not match, or an address the platform's destination policy refuses. Only the retry branch keeps going until it hits the three-day cutoff: retrying stops three days after the platform recorded the event, and the platform writes that abandonment as a warning log and a failed span rather than dropping the event silently. Labels: One event, repeated attempts; The platform records the event first; Delivery works from that row, never from memory; Signed envelope; webhook-id, webhook-signature, webhook-timestamp; plus the delivery and endpoint identifiers; Leased attempt; Recovery reuses recorded delivery outcomes; A crash before recording can repeat the send; Delivered; A 2xx reply. The; consumer accepted it.; Retry; Backs off from ~30s,; doubling and jittered.; Terminal; A 4xx (not 408/429),; or a failed receipt.; Retrying stops three days after the platform records the event; The platform logs that abandonment rather than losing it quietly.

Recorded attempts support recovery, but a response loss or crash before recording can still cause a duplicate, so deduplicate by webhook-id.

A brief outage at your receiver does not cost it the notification. A retryable failure is retried with jittered backoff, starting near thirty seconds, for up to three days from the moment the platform recorded the event. A `Retry-After` header on a failed reply raises the next wait to at least that long, within the time left.

A 4xx other than 408 or 429 is terminal, and so is a counter-signed receipt with a valid signature but a body hash that does not match. An address the platform refuses is terminal too, and nothing is sent. Correct the endpoint URL, then choose "Resend" on the failed event in the Console.

Recovery reuses recorded attempts, so a crash rarely resends what already worked. A POST your receiver got before the platform recorded it can still arrive twice, which is why `webhook-id` is the field to deduplicate on.

## What the platform does and what your receiver does [#what-the-platform-does-and-what-your-receiver-does]

The platform sends each event to your endpoint as a signed HTTPS POST, retries the failures worth retrying for three days, and records every attempt. Your receiver verifies the signature, deduplicates on `webhook-id`, answers 2xx once it holds the message, and handles the event's finality state.

The three days run from the moment the platform recorded the event, not from the first attempt. An event that waited before its first attempt has less than three days of retrying left. Attempt and delivery times are the platform server's clock, not the time of the block that produced the event, so they can read later than the newest block on an idle network.

The signature lets your receiver establish two things without trusting the network: that the platform sent the message, and that nothing altered it in transit. It does not tell you the fact is final. Check the event's finality state and your reconciliation requirements before acting on it.

## Why a notice needs its own delivery system [#why-a-notice-needs-its-own-delivery-system]

A [Platform Event](https://docs.settlemint.com/docs/concepts/events-out/platform-event) is a fact the platform has already recorded. A recorded event tells nobody outside the platform anything until somebody looks. Without a delivery system, a receiver polls the platform's read APIs and diffs the answer, or relies on a bare callback URL with no retry, backoff or record of what was sent. Both put the retry logic, the endpoint health tracking and the record of delivery on the receiver.

Webhook Delivery keeps that work on the platform side. It owns the retry schedule, the per-endpoint circuit breaker and the attempt records an operator reads back when a receiver later disputes whether it was told.

The contract is at least once, never exactly once. A crash or a lost response can still cause a resend, so the platform hands over a message identifier your receiver checks before it acts. Delivery owns getting the notice there. Deduplicating it is the one piece of the work only your receiver can do.

## Receiving, verifying and answering [#receiving-verifying-and-answering]

Each delivery reaches your receiver as one POST request with a JSON body. Three of its headers follow Standard Webhooks, an open scheme with verification libraries in most languages: `webhook-id` identifies the message, `webhook-signature` holds the signature or signatures, and `webhook-timestamp` gives the signing time in whole seconds. The platform adds `webhook-delivery-id` for the individual attempt and `webhook-endpoint-id` for the endpoint it addressed.

Verify with a Standard Webhooks library rather than by hand, using the endpoint's signing secret, and let the library reject a timestamp outside its tolerance. The library accepts a five-minute spread between that timestamp and your clock, so keep the receiver's clock synchronised. The platform re-signs an envelope before an attempt once its timestamp has reached four minutes old, so a message that waited in backoff does not arrive already expired. While a signing secret rotates, `webhook-signature` holds one signature per secret, separated by a space, and verifying against any one of them is enough.

A duplicate reaches you in two situations. The first is a retry of a delivery whose outcome the platform never confirmed. The second is a receiver that did the work but did not reply inside the twenty-second attempt window, so the platform retries a request you already fulfilled. A retry repeats the same `webhook-id`, while `webhook-delivery-id` changes on every attempt. Record the identifiers you have handled and return success for one you recognise. Store the handled identifier and the resulting business change atomically, or use an equivalent idempotent design.

A replayed event is the exception. Replay gives each event a new `webhook-id` and marks it as a replay, so deduplicate a replay on the identifiers inside its payload.

| Your reply | What happens next | Send it when |
| --- | --- | --- |
| Any 2xx | Delivery ends and is marked delivered. An endpoint that requires receipts also needs the receipt in time. | You received the message and are done with it. |
| A 4xx other than 408 or 429 | Stops at once. Nothing retries. | You never accept this exact message. |
| 408 or 429 | Retries. | Rate-limiting or not ready. The platform treats it as a retryable client failure. |
| A 5xx | Retries. | Something broke on your side. |
| No reply inside twenty seconds | Counted as a failure and retried. | Never on purpose. Acknowledge first, do the work after. |

When an attempt fails, the platform records what kind of failure it hit:

| Failure kind | What it means | Retried |
| --- | --- | --- |
| DNS failure | The endpoint's host did not resolve. | Yes |
| TLS failure | The security handshake broke. | Yes |
| Connection timeout | The connection never opened. | Yes |
| Read timeout | The connection opened but no reply arrived. | Yes |
| Invalid response | The reply carried no recognisable HTTP status, or was a redirect. | Yes |
| A 5xx, 408 or 429 reply | The receiver failed or asked the platform to wait. | Yes |
| Rejected by the receiver | Any other 4xx. | No |
| Receipt body hash mismatch | A counter-signed receipt verified but names a different body. | No |
| Refused address, recorded as `TARGET_REFUSED` | The platform's destination policy refused the address. Nothing was sent. | No |

Sending the identical request again would reproduce the identical refusal, so the platform does not retry a terminal failure. The failure kind tells an operator whose problem it is, and whether the platform is still trying, before anyone opens a log.

An endpoint can require counter-signed receipts. A 2xx reply only shows that the platform reached you and you answered. A counter-signed receipt goes further: your receiver signs the delivery identifiers and a hash of the exact body with the endpoint's signing secret. The `dalp.whr.v1` scheme ties the receipt to that delivery and payload. The [receipt contract](https://docs.settlemint.com/docs/api-reference/webhooks/consuming#counter-signed-receipts) defines the signing string, request fields and deadline. A missing receipt causes a retry. A receipt whose signature does not verify is refused without changing the delivery.

## Registering an endpoint [#registering-an-endpoint]

An organisation Owner or a Platform administrator registers and manages endpoints on the Console's [Webhooks](https://docs.settlemint.com/docs/console/organisation-settings/webhooks) page, which also shows each endpoint's breaker state and every event's attempts. The signing secret appears once, when the endpoint is created or its secret is rolled. Rolling keeps the previous secret valid for 24 hours, and the platform signs each delivery with both secrets during that overlap.

### Thin and fat payloads [#thin-and-fat-payloads]

A thin payload leaves out personal data, and every endpoint starts thin. A fat payload includes the personally identifying fields that the endpoint's subscriptions expose. The platform computes that list of fields from the subscriptions and refuses the switch to fat until the endpoint owner acknowledges every field on it. An endpoint cannot be created fat: register it thin, then move it to fat once the fields it would expose are known.

### Address checks [#address-checks]

Registering or updating an endpoint checks the address first. The URL must use HTTPS and resolve only to a public address, so a private, loopback or link-local target is refused before it is saved. Register the address your receiver is reachable at from the public internet.

At send time the platform resolves the endpoint's host, validates the address it got back and connects to that address directly, so no second name lookup can redirect the request after the check passed. Where a deployment allows specific internal addresses, those addresses lose this protection. The original host name still travels in the Host header and the security handshake, so virtual hosting and certificate checks behave normally.

The platform follows no redirects. A redirect reply is recorded as an invalid response and retried. Register the address the redirect points to. The platform reads at most eight kilobytes of a reply and stores that on the attempt record.

## Recovery reuses recorded attempts [#recovery-reuses-recorded-attempts]

Sending a webhook and recording its outcome are separate effects. A process can stop after your receiver got the POST but before the attempt record is written, and recovery may repeat that send.

On recovery, the platform uses the endpoint, event and attempt number to look for an existing delivery record. When the record exists, recovery reuses its outcome. When it does not, recovery sends the request. This reduces repeated sends but does not deliver exactly once.

Once retrying stops, an Owner or Platform administrator can still send the event again. "Resend" on a failed event adds one attempt to the same event with the same `webhook-id`, and only the latest attempt of an event can be resent. "Replay events" sends events the platform already recorded for the endpoint, by block range or one at a time, each with a new `webhook-id`. The platform refuses a replay while the endpoint is switched off or its circuit breaker is open.

## The circuit breaker that watches endpoint health [#the-circuit-breaker-that-watches-endpoint-health]

Webhook Delivery gives every registered endpoint its own circuit breaker, with three states: closed, open and half-open. It keeps one failing endpoint from consuming delivery capacity meant for every other receiver, and it lets recovery happen without an operator noticing and re-enabling the endpoint.

Thirty consecutive failed deliveries open the breaker, which pauses live sends to that endpoint. The platform then probes the endpoint at most once a minute. Two successful probes in a row move the breaker to half-open, and live deliveries resume. One further successful delivery closes the breaker and resets the failure count to zero, while one failed live delivery sends it back to open. The platform records each state change as it happens.

[Figure] Recovery is automatic, and a failed delivery can send it back to open. An endpoint's circuit breaker holds one of three states: closed, open, or half-open. Closed delivers normally and resets the failure count on every success. Thirty consecutive failed deliveries move it to open, which pauses live sends to that endpoint. While open, the platform runs its own background probe on a fixed schedule the endpoint owner does not control, and two of those probes succeeding in a row moves the breaker to half-open. Live deliveries resume at half-open: one further successful delivery closes the breaker and resets the failure count to zero, while a single failed live delivery sends it back to open. A manually triggered test event is excluded from every step of this cycle, so probing an endpoint by hand can never open, advance, or close its breaker. Labels: Recovery is automatic; closed; Delivering normally; Failure count at zero; 30 failures in a row; open; Live sends paused; Background probes only; half-open; Live deliveries resume; 2 probes succeed; 1 more live success; A failed delivery reopens it; A manually triggered test event never advances this cycle.

The platform probes an open circuit breaker, and successful probes admit live traffic through half-open before normal delivery resumes.

Test events stay out of that accounting. An operator can send a test event to a disabled or recovering endpoint. It moves neither the breaker nor the failure count, and it neither replaces nor speeds up the automatic probes.

## Evidence that the notice went out [#evidence-that-the-notice-went-out]

Webhook Delivery records every attempt it makes toward your receiver, not only the one that finally succeeds. Every attempt leaves a row with the attempt number, the status your receiver returned, its response headers and the first part of its body. A failed attempt's row also records the failure kind and the trace identifier that ties it to the wider operation. The platform keeps these records for 30 days after a delivery settles, so export what your dispute and audit policy needs before then.

Delivery also adds an entry to the event's chain of hop hashes, with a hash of the exact payload sent and the endpoint it was signed for. That records which content went out to which endpoint, which matters when a receiver disputes what it received.

The delivery signature and the counter-signed receipt both use a secret that the platform and your receiver share. Each side can check the other, but neither signature proves to a third party which side produced it.

When retrying stops, the platform writes a warning in its logs and marks the operation failed in its traces. Both name the attempt number, the failure kind and the event's age, so an operations team finds abandoned events there.

The platform versions its signing secrets. A successful delivery updates the last-used time of each secret version that signed it, and the endpoint's `secret.lastUsedAt` reports the most recent of those times.

## Frequently asked questions [#frequently-asked-questions]

### Can a private-network deployment point a webhook at an internal address?

Not from the endpoint form. The public-address check applies to every organisation the same way. A private-network installation can allow specific internal destinations at the deployment level. The deployment operator makes that decision for the whole installation, and an organisation cannot make it by editing its own endpoint URL. If a legitimate internal address keeps being refused, ask the operator about that allowance.

### What happens to deliveries already in flight when I change an endpoint's URL?

Nothing in flight retargets silently. If the endpoint still has pending deliveries, a plain URL change is refused. You either wait for those deliveries to finish, or resend the update with an explicit acknowledgement that pending attempts retry against the new address. A completed attempt keeps its original destination. Each attempt reads the endpoint's current URL at send time, so a delivery still retrying when you switch lands on the new address from its next attempt onward.

## Related concepts [#related-concepts]

- [Platform Event](https://docs.settlemint.com/docs/concepts/events-out/platform-event): The published vocabulary of things that happen and what a receiver may rely on. The event is the fact, and delivery carries it to your endpoint.
- [Transaction Lifecycle](https://docs.settlemint.com/docs/concepts/settlement/transaction-lifecycle): The states an instruction passes through inside the platform. A webhook is how an outside system hears about those state changes, and is not one of them.
- [Audit Trail](https://docs.settlemint.com/docs/concepts/records-and-evidence/audit-trail): The wider record that attempt rows, hop hashes and trace identifiers belong to.


# Overview

Source: https://docs.settlemint.com/docs/concepts
Find the DALP concept page that defines each part of the digital asset lifecycle: settlement, compliance, custody, records, and operations.

DALP is SettleMint's Digital Asset Lifecycle Platform for issuing, governing, settling, and servicing regulated tokenised assets. The concept library has ten groups, in the order an institution meets them: the platform, modelling assets, issuing and markets, settlement, Compliance & Identity, custody and signing, records and evidence, events out, operating, and API and integration.

Each concept page defines its subject and explains its controls and limits. Some cards link to platform and API reference pages, which hold the detail for those subjects.

[Figure] Ten stations, in the order an institution meets them. The concept library is arranged as one path with ten stations, read left to right along each row, wrapping to the next row after every three stations. The first station, and the recommended entry point, is the platform: what you deploy, and how it is divided. The second is modelling assets: what an instrument is, from template to token. The third is issuing and markets: how assets reach investors, and where they trade. The fourth is settlement: how value moves, and what makes it final. The fifth is Compliance &amp; Identity: who may hold it, and what gates a transfer. The sixth is custody and signing: who holds the keys, and who approves signing. The seventh is records and evidence: what is recorded, and what an auditor reads. The eighth is events out: what the platform reports to your systems. The ninth is operating: how you run the Console and the portal, and read the platform's health. The tenth is API and integration: the contract every request follows. The order is the order an institution meets these questions, not a required reading sequence. Every page stands on its own. Labels: Start here; The platform; What you deploy,; and how it is divided; Modelling assets; What an instrument is,; from template to token; Issuing &amp; markets; How assets reach investors,; and where they trade; Settlement; How value moves,; and what makes it final; Compliance &amp; Identity; Who may hold it, and; what gates a transfer; Custody &amp; signing; Who holds the keys, and; who approves signing; Records &amp; evidence; What is recorded, and; what an auditor reads; Events out; What the platform reports; to your systems; Operating; How you run it,; and read its health; API &amp; integration; The contract every; request follows.

Read [Where to start](#where-to-start) next for the fastest way in, based on why you are here.

## Where to start [#where-to-start]

Four entry points cover most arrivals. If none of them fits, start with the platform, as the figure does.

To work out what DALP is and where it runs, start at [DALP Instance](https://docs.settlemint.com/docs/platform/dalp-instance), then read [Platform Architecture](https://docs.settlemint.com/docs/platform) for how the platform divides responsibility across named systems.

For issuing or servicing an instrument, [Asset Lifecycle](https://docs.settlemint.com/docs/concepts/issuing-and-markets/asset-lifecycle) covers the whole arc, and [Instrument Templates](https://docs.settlemint.com/docs/concepts/modeling-assets/instrument-templates) explains how one product shape is defined once and reused.

For compliance, audit, or day-to-day operating, [Compliance Policy](https://docs.settlemint.com/docs/concepts/compliance-and-identity/compliance-policy) covers what gates a transfer, [Audit Trail](https://docs.settlemint.com/docs/concepts/records-and-evidence/audit-trail) covers the off-chain record of who did what, and [Platform Health](https://docs.settlemint.com/docs/concepts/operating/platform-health) covers how you read the platform's own condition.

Integration work starts in the API reference. [API Key](https://docs.settlemint.com/docs/api-reference/guides/authentication-api-keys) covers how a request authenticates, and [Idempotent Write](https://docs.settlemint.com/docs/api-reference/guides/idempotency-async-settlement) covers the one rule that keeps a retried instruction from settling twice.

## The platform [#the-platform]

What you deploy, and how it is divided.



- [DALP Instance](https://docs.settlemint.com/docs/platform/dalp-instance): One self-contained copy of the platform, on infrastructure you choose.

- [Platform Architecture](https://docs.settlemint.com/docs/platform): How DALP divides the platform into systems with clear responsibility.

- [EVM Contract Set](https://docs.settlemint.com/docs/platform/evm-contract-set): The identity, compliance, custody and settlement contracts deployed around one token.

- [System Version](https://docs.settlemint.com/docs/platform/system-version): How far an organisation's on-chain components trail the current module set.



## Modelling assets [#modelling-assets]

What an instrument is, from template to token.



- [Composable Token](https://docs.settlemint.com/docs/concepts/modeling-assets/composable-token): One regulated contract configured from a template with the features an instrument needs.

- [Instrument Templates](https://docs.settlemint.com/docs/concepts/modeling-assets/instrument-templates): One financial product shape: its facts, behaviours and compliance rules.

- [Asset Class](https://docs.settlemint.com/docs/concepts/modeling-assets/asset-class): An economic category that groups reusable product definitions.

- [Denomination Asset](https://docs.settlemint.com/docs/concepts/modeling-assets/denomination-asset): The one asset in which a paying token feature makes its payout per unit.

- [Stablecoin](https://docs.settlemint.com/docs/concepts/modeling-assets/stablecoin): A Composable Token with a declared reference price against one currency.



## Issuing & markets [#issuing--markets]

How assets reach investors, and where they trade.



- [Asset Lifecycle](https://docs.settlemint.com/docs/concepts/issuing-and-markets/asset-lifecycle): The working life of a tokenised instrument, from issuance through servicing to redemption.

- [Primary Offering](https://docs.settlemint.com/docs/concepts/issuing-and-markets/primary-offering): The first sale of new assets, delivered on success and refunded if a minimum is missed.

- [Corporate Action](https://docs.settlemint.com/docs/concepts/issuing-and-markets/corporate-action): A lifecycle event that turns announced terms into payouts, supply changes or entitlements.

- [Token Distribution](https://docs.settlemint.com/docs/concepts/issuing-and-markets/token-distribution): A Merkle-proof distribution of allocations that are pushed, claimed or vested.

- [Trading Venue](https://docs.settlemint.com/docs/concepts/issuing-and-markets/trading-venue): A permissioned exchange with its own instruments, order books and escrow.



## Settlement [#settlement]

How value moves, and what makes it final.



- [Transaction Lifecycle](https://docs.settlemint.com/docs/concepts/settlement/transaction-lifecycle): An instruction's path through preparation, signing, submission and recorded outcome.

- [Transaction Queue](https://docs.settlemint.com/docs/concepts/settlement/transaction-queue): How the platform queues, retries and deduplicates a write until it settles on chain.

- [Settlement Verdict](https://docs.settlemint.com/docs/concepts/settlement/settlement-verdict): The recorded outcome of an on-chain operation, and the only signal that it succeeded.

- [XvP Settlement](https://docs.settlemint.com/docs/concepts/settlement/xvp-settlement): Delivery versus payment and payment versus payment, with escrowed, netted local flows.

- [Workflow Engine](https://docs.settlemint.com/docs/concepts/settlement/workflow-engine): How multi-step operations record results and waits, and how replay reuses them.



## Compliance & Identity [#compliance--identity]

Who may hold it, and what gates a transfer.



- [Participant](https://docs.settlemint.com/docs/concepts/compliance-and-identity/participant): The one record of a compliance subject that roles, claims and audit rows point at.

- [On-Chain Identity](https://docs.settlemint.com/docs/concepts/compliance-and-identity/onchain-identity): The ledger record of one subject, with the verifications issuers signed about it.

- [Compliance Policy](https://docs.settlemint.com/docs/concepts/compliance-and-identity/compliance-policy): Policy templates and global controls that both approve a transfer before value moves.

- [Transfer-Path Compliance](https://docs.settlemint.com/docs/concepts/compliance-and-identity/transfer-path-compliance): How a token's rules run inside transfers and mints, and what bypasses them.

- [Role Grant](https://docs.settlemint.com/docs/concepts/compliance-and-identity/role-grant): The on-chain permission recorded for one address and checked before a privileged call.

- [Delegated Authority](https://docs.settlemint.com/docs/concepts/compliance-and-identity/delegated-authority): How an operator enters another party's context, then acts under that party's own roles.



## Custody & signing [#custody--signing]

Who holds the keys, and who approves signing.



- [Smart Wallet](https://docs.settlemint.com/docs/concepts/custody-and-signing/smart-wallet): An account that is code on the chain and enforces its own signing rule.

- [Agent mandate](https://docs.settlemint.com/docs/concepts/custody-and-signing/agent-mandate): The calls, amounts and dates that confine a software agent's smart wallet.

- [Multisig](https://docs.settlemint.com/docs/concepts/custody-and-signing/multisig): How a multi-signer Smart Wallet is drafted, invited and deployed with its joined signers.

- [Custody Provider](https://docs.settlemint.com/docs/concepts/custody-and-signing/custody-provider): The signing service an organisation enables, resolved by stored configuration.

- [Custody Approval](https://docs.settlemint.com/docs/concepts/custody-and-signing/custody-approval): The decision required before signing when a wallet's policy names approvers.

- [Maker-Checker](https://docs.settlemint.com/docs/concepts/custody-and-signing/maker-checker): One party proposes a change and a different party approves it before it takes effect.

- [Operator Wallet](https://docs.settlemint.com/docs/concepts/custody-and-signing/operator-wallet): The wallet that signs platform operations and whose gas balance operators fund.



## Records & evidence [#records--evidence]

What is recorded, and what an auditor reads.



- [Ledger Data](https://docs.settlemint.com/docs/concepts/records-and-evidence/ledger-data): The queryable record of the networks the platform follows, which serves its reads.

- [Market Data](https://docs.settlemint.com/docs/concepts/records-and-evidence/market-data): The governed on-chain source for prices, valuations and exchange rates.

- [Audit Trail](https://docs.settlemint.com/docs/concepts/records-and-evidence/audit-trail): The off-chain record of who acted, under what role and what happened.

- [Reconciliation](https://docs.settlemint.com/docs/concepts/records-and-evidence/reconciliation): The recurring comparison of your register with the on-chain ledger.

- [Reporting Obligation](https://docs.settlemint.com/docs/concepts/records-and-evidence/reporting-obligation): A regulatory reporting duty, frozen as a version that generates your filing periods.



## Events out [#events-out]

What the platform reports to your systems.



- [Platform Event](https://docs.settlemint.com/docs/concepts/events-out/platform-event): One entry in the generated catalogue of occurrences the platform reports.

- [Webhook Delivery](https://docs.settlemint.com/docs/concepts/events-out/webhook-delivery): Signed event notifications, recorded attempts and retries for up to three days.



## Operating [#operating]

How you run the Console and the Investor portal day to day, and read the platform's health.



- [Platform Health](https://docs.settlemint.com/docs/concepts/operating/platform-health): One operator verdict on API errors, chain connectivity, workflows and data freshness.

- [Console navigation](https://docs.settlemint.com/docs/concepts/operating/console-navigation): The frame lists only the areas you can open and keeps the sidebar on a refused address.

- [Tables](https://docs.settlemint.com/docs/concepts/operating/table-views): Save a list as a named view, act on several rows and move through rows by keyboard.

- [Form drafts](https://docs.settlemint.com/docs/concepts/operating/form-drafts): A long form keeps what you typed for seven days and never stores a PIN or code.

- [Address fields](https://docs.settlemint.com/docs/concepts/operating/address-fields): Search by name, paste an address or list, and catch a malformed address before saving.

- [What the assistant sends](https://docs.settlemint.com/docs/concepts/operating/assistant-data): The assistant sends masked questions to one pinned model, and a setting governs documents.

- [Investor portal](https://docs.settlemint.com/docs/concepts/operating/investor-portal): The separate web app where investors hold, buy and trade, under your branding.

- [Bank transfers](https://docs.settlemint.com/docs/concepts/operating/investor-portal-bank-transfers): Pay the organisation by bank transfer, then follow the deposit and any cash-out.

- [Wallet deposits and withdrawals](https://docs.settlemint.com/docs/concepts/operating/investor-portal-wallet-transfers): Deposit from a wallet, withdraw to an approved address and prove a self-custody wallet.



## API & integration [#api--integration]

The contract every request follows.



- [API Key](https://docs.settlemint.com/docs/api-reference/guides/authentication-api-keys): A long-lived `X-Api-Key` secret that authenticates Platform API requests.

- [CLI Session](https://docs.settlemint.com/docs/api-reference/cli/install): The identity a device-code login turns into a stored API key for later commands.

- [Command Tree](https://docs.settlemint.com/docs/api-reference/cli/commands): The generated `dalp` commands that translate each API operation into predictable words.

- [Error Envelope](https://docs.settlemint.com/docs/api-reference/guides/errors): The stable identifier and machine-readable class that every failure carries.

- [Page Window](https://docs.settlemint.com/docs/api-reference/guides/pagination): The paging contract of list endpoints, from offset and size to cursor and next link.

- [Idempotent Write](https://docs.settlemint.com/docs/api-reference/guides/idempotency-async-settlement): An `Idempotency-Key` identifies one intended operation so replays keep its choices.

- [Object Storage](https://docs.settlemint.com/docs/api-reference/guides/files): How the key of a file in one bucket decides whether it is public or private.




# Asset Lifecycle

Source: https://docs.settlemint.com/docs/concepts/issuing-and-markets/asset-lifecycle
Asset Lifecycle is the whole working life of a regulated tokenised instrument, from issuance through servicing to redemption, governed on one platform.



[Figure] One instrument, one trail, from design through servicing to an optional retirement. An instrument is designed first: its business class, the template it starts from, the facts to capture, the runtime behaviour to attach, and its transfer rules. One deployment then issues it, creating the token together with its own identity, roles, rule set, and behaviour list. It arrives ready to launch: reviewable, with no units issued and none moving, until an operator launches it. It is then serviced for as long as it lives, with supply issued and moved, holdings frozen and unfrozen, coupons and dividends paid, positions converted, fees charged, and trades settled. An instrument that carries the maturity feature ends retired: it matures, holders redeem at face value, and their positions burn. An instrument without that feature keeps servicing indefinitely instead. Every one of those steps writes to the same indexed record on the same asset, which is what makes the whole life auditable from one place. Labels: Design; class, template, facts, behaviour, transfer rules; Issue; one deployment: token, identity, roles, rules; Ready to launch; reviewable: no units issued, none moving; Service; issue and move supply, freeze holdings, pay; coupons and dividends, convert, settle trades; Retire; mature, holders redeem at face value, burn (if attached); One trail.

Design, issue, launch, service, retire: every stage writes to the same indexed record, which is what makes the whole life auditable from one place.

One instrument, one record: the same asset carries its rules, its holders, and its history from the first unit issued to the last redeemed.

Every stage after issuance is a role-gated operation on that asset. The contract checks the role and the asset's rules, and the platform adds its own checks, such as signer verification and approvals, on the operations sent through it.

Coupons and maturity redemption are features attached to the token. A holder of the token's governance role, together with Supply management and Custodian or with the admin role, can attach, detach or replace a feature after issuance, and each change is its own recorded governance operation. Maturing a fixed-income instrument closes issuance and fixes the redemption budget to the supply outstanding at that moment, for as long as the maturity feature stays attached.

## Issuance and servicing share an asset record [#issuance-and-servicing-share-an-asset-record]

Asset Lifecycle is the whole working life of a regulated tokenised instrument, from design and issuance through day-to-day servicing to final redemption. On DALP one asset record carries the instrument's rules, its holders and its history through all of it. Issuance is the short part, and the cost and risk sit in the years of servicing that follow.

The cost comes from the number of seams between systems. A typical programme runs issuance in one system, identity screening in a second, custody in a third, trading in a fourth, and settlement and reporting in a fifth. Every seam is a reconciliation, and a reconciliation is where an instrument's ledger state and its legal record drift apart.

The platform records issuance and servicing operations against the same instrument. The eligibility registry that decides who may receive the first minted unit also judges a transfer in year three and a redemption payment at maturity, unless a governance-role holder replaces it, which is a recorded governance operation. The roles that govern who may issue supply also govern who may freeze a holding. The record an auditor pulls in year five is the record the issuance team wrote in year one. The second bond of a given design reuses the first one's template, so it needs no new contract.

The platform owns the mechanics: creating the instrument, enforcing its rules, executing its operations, recording what happened. You keep the legal wrapper, the economic terms, the cash rails outside the platform, the accounting treatment, and the regulatory sign-off. The life is bounded at both ends: an asset is created ready to launch, and no operation reverses maturity.

## Running an issued asset day to day [#running-an-issued-asset-day-to-day]

The Console shows each issued asset as one workspace with what the instrument is, who holds it, what it has done, and which servicing steps you may take now. Everything you can do to the asset starts there.

The workspace is built from that asset's own configuration, so it shows only what that asset supports. Tabs appear when they apply: the [holder register](https://docs.settlemint.com/docs/console/asset-management/manage/holder-register) with its frozen amounts, the workflow history, the compliance configuration, the [documents and holder notices](https://docs.settlemint.com/docs/console/asset-management/manage/documents), price feeds when the deployment installs them, role assignments, and the cash asset a bond-style instrument pays in. The workspace hides a step the asset does not support. It also hides a step that none of your wallets holds the role for, except "Refresh mark", which stays greyed out. A step whose role sits on another of your wallets is greyed out and names that wallet. A step blocked by the asset's state, such as a halt, is greyed out and its tooltip names the check that blocks it, so you learn before you submit instead of after a transaction reverts. Amount fields on the mint, burn, transfer, forced transfer, partial freeze and redeem steps show the fiat equivalent at the asset's price, or say that the asset has no price.

## The layers an instrument is built from [#the-layers-an-instrument-is-built-from]

An Asset Lifecycle rests on three layers that meet at creation. The business class is what an operator browses, the instrument template is what an issuer starts from, and the issued asset is what exists on chain afterwards. A new product shape needs a new template.

The template is where the shape is fixed. It binds the business class, the schema of instrument facts to capture, the runtime behaviour the asset must carry, and the compliance choice that governs it. The issued asset inherits all of that at deployment.

[Figure] How an instrument is composed and deployed. Four design inputs converge on one instrument template. The business class is the grouping an operator browses, the instrument facts name what to capture, the required features are the runtime behaviour to attach in order, and the compliance rules decide what may proceed. The template binds them into one reusable shape. One deployment then produces the issued asset: the token contract, its own on-chain identity, its own role manager, its own rule engine, its own eligibility registries, and its ordered feature list, all scoped to that asset alone. Labels: Design inputs; Fixed at design time; Business class; what operators browse; Instrument facts; what to capture; Required features; behaviour, in order; Compliance rules; what may proceed; Instrument template; one reusable shape; Issued asset; One deployment; Token contract; On-chain identity; Role manager; Rule engine; Eligibility registries; Ordered feature list; all scoped to this; asset alone.

Four design inputs bind into one template, and one deployment produces the token with its own identity, roles, rule engine and registries.

Deployment creates more than a token. The factory deploys the token contract, its own on-chain identity, its own role manager, its own rule engine, and eligibility registries scoped to that token alone. Two instruments in the same organisation therefore carry independent role assignments and independent rule state. Revoking a role on one changes nothing on the other.

A token extension and a token feature are different things. A token extension is a capability the contract itself exposes and the platform discovers from the deployed code: pausable, burnable, capped, custodian control, and so on. A token feature is runtime behaviour built by a feature factory and attached at creation or later by governance: maturity redemption, treasury yield, voting power, fee collection, conversion. Features sit in an ordered list, and the order is policy, because feature hooks run on the token's own operations. Minting and burning pass through them, so do transfers and redemptions, and so does every later update or attachment.

A transaction-fee feature, for one, rewrites a burn into a fee transfer plus a smaller net burn, so the amount a holder asked to destroy and the amount destroyed are different numbers. The fee feature's position relative to maturity redemption or a yield feature makes no difference. Neither of those rewrites the amount, so each reads the balance change the fee feature left behind. A redemption's burn gets fee-diverted regardless of list position, which is why the amount a holder is recorded as redeeming and the amount paid out can differ. Order only changes the outcome between two rewriting features, where the first to run sees the original amount and the second sees whatever the first left behind.

Three kinds of configuration answer three questions. Metadata records instrument facts, such as the issuer or the maturity date. Features change what the token does, such as paying a coupon. Compliance rules decide whether an operation may proceed at all. The platform refuses a feature set whose parts cannot work together, at creation and on every later change it sends. The contract does not run that test itself.

Reads do not scrape the chain. On-chain events become typed platform records, which is why an operator screen, an integration, and an audit export give the same answer about the same instrument.

## The integration contract [#the-integration-contract]

On the platform's application programming interface (API), an Asset Lifecycle is one address and its subresources. The token address that creation returns is the resource root for everything the instrument ever does: supply changes, transfers, rule changes, feature operations, corporate-action runs, and every read.

Read before you mutate. A feature route applies only when the token reports that feature attached, so the attached-feature list gates the call. Detaching a feature later is its own governance operation. The detached row stays in the history with the block it left at, and you must never read it as live configuration. Event history is not current state either: one operation can emit several events, so read state before you act and events to reconstruct what happened.

[Figure] The servicing call sequence. The integrator first reads the asset from the platform: its state, its roles, its attached features, and its balances, and the platform returns the current configuration and holdings. The integrator then submits the servicing call under one idempotency key. The platform executes the operation against the asset contract, which settles it or reverts with the check that failed. The integrator polls that status until the platform reports a terminal outcome, and re-reads the asset before reporting the step complete. Labels: One servicing call; Integrator; Platform; Asset contract; 1. Read state, features, balances; configuration and holdings; 2. Submit, one idempotency key; 3. Execute the operation; settles, or reverts with the check; 4. Recorded outcome, terminal status; 5. Re-read before reporting complete.

Read the asset, submit under one idempotency key, and re-read before reporting the step complete, because acceptance is not completion.

Enforcement happens in two places, and the split decides how you handle errors. The route pre-checks the caller's role, signer verification, the asset's lifecycle state, the request shape, and the indexed balance, and rejects with a stable error code before anything is queued. The contract enforces the rest during execution: supply caps, holder eligibility, collateral cover, and the transfer rules. A request that clears every pre-check can still revert on chain. Read the operation's recorded outcome, its Settlement Verdict, to learn whether it settled or reverted. Acceptance is not completion. Resubmitting under the same idempotency key after a revert does not retry the instruction: the platform refuses it, because the key already names a failed operation. Fix what caused the revert, then send the same business instruction under a new key. The platform answers a submission with an identifier and a status address for that operation, and the status's terminal state is the answer.

Send one idempotency key per business instruction. A mint or a burn sent again under the same key with the same request returns the operation already queued or settled instead of writing twice, and the same key with a different request is refused. If the outcome is uncertain, inspect the original operation and the resulting asset or supply before sending another request. A changed wallet selection or payload is a different instruction and needs a new key.

Two limits catch integrators out. Batch ceilings differ per operation: mint and burn accept up to 100 items per request, while standard and forced transfers accept up to 10,000. And amounts are integers in the token's own precision, set at creation and not always eighteen decimal places, so store each instrument's precision beside its address.

## Controls across the whole life, and the evidence they leave [#controls-across-the-whole-life-and-the-evidence-they-leave]

Every act on an instrument, from its creation to its last redemption, needs a role and leaves a record. The controls apply per operation and per asset, and the evidence is one indexed trail on the instrument.

Two independent gates sit in front of every privileged operation. The first is the asset role: minting needs supply management, changing policy needs governance, a freeze or a forced transfer needs the custodian role, and launching or applying an emergency halt needs the emergency role. The second is signer verification at the moment of signing: you confirm the operation through your wallet's configured method, a personal identification number, a one-time code, or whatever your custody provider requires. The contract checks only the role. Signer verification is the platform's check on operations sent through it, so a holder of the role's key who calls the contract directly passes the first gate alone.

Asset roles are scoped to one asset, so an asset role on one instrument confers none over another. A holder of the system manager role is the exception: it can point a token factory at new contract code, which changes the code of every token from that factory at once, without any asset role holder's approval.

An asset is created ready to launch, paused. Its configuration is readable, and no ordinary mint or transfer runs until an emergency-role operator launches it. A real estate token is the exception at creation: its full number of fractions is minted to the named recipient in the creation transaction. The gap before launch is a review window by design, and it runs on no clock: the instrument stays ready to launch until someone with the emergency role launches it. After launch, the same role can apply an emergency halt and later resume token operations. Those controls are reversible, while maturing is not.

A recovery returns a lost wallet's holding to its replacement wallet. Recoveries and forced transfers bypass ordinary compliance checks and the sending wallet's freeze, and they run while the asset is halted. The receiving wallet must still pass the applicable identity check, and a forced transfer refuses a receiving wallet whose address is frozen. Each one emits its own on-chain event carrying the acting sender, the source, the destination, and the amount, so every exception is on the record. The holders of an asset's custodian role include the organisation's operations signer once a trading venue listing has granted it that role, so read the asset's role assignments to list them. Ordinary transfers stay under [Transfer-Path Compliance](https://docs.settlemint.com/docs/concepts/compliance-and-identity/transfer-path-compliance), where the rules are checked inside the transfer and a failure reverts it.

Evidence spans the whole life in one place. Creation, role grants and revocations, identity claims, supply changes, transfers, feature operations, corporate-action runs, and redemptions are indexed against the same asset with their transaction references. An auditor can reconstruct the on-chain operations from those records and reconcile them with external evidence.

Metadata entries and a collateral claim recorded against the asset are inputs the contract checks. They prove nothing outside it. A collateral claim states an amount and an expiry that the minting check evaluates against the configured ratio. The bank statement, the custodian report, and the legal title behind it stay in your own evidence file.

## Frequently asked questions [#frequently-asked-questions]

### Which instrument types can the platform issue?

The platform issues any instrument that its templates, features and compliance modules support, so start from the template that fits. Behaviour is attached at configuration time instead of compiled per product. The platform ships 36 templates across seven business classes: fixed income, equity, funds, cash, real assets, digital assets, and structured products. Fixed-income templates include corporate and sovereign bonds, government securities, treasury bills, commercial paper, syndicated loans, and sukuk ijara and murabaha. Equity templates include SAFEs, warrants, convertible target equity, controlling and economic class shares, and a share-class mirror for a class whose register a fund administrator keeps. Fund templates include funds, money market funds, and ETFs. Other templates cover custody receipts, autocallable and principal-protected notes, carbon credits, spot commodities, tokenised virtual assets, and tokenised art. A named product such as a covered bond is a template. [Instrument Templates](https://docs.settlemint.com/docs/concepts/modeling-assets/instrument-templates) lists them all.

### What happens to an instrument that never matures, such as an equity?

It has no end-of-life step. Maturity and redemption are a feature attached at creation, and an instrument without that feature keeps operating indefinitely, with no scheduled close. Supply can still fall through burns, and a capital decrease or a buyback runs as an announced batch burn against per-holder allocations fixed in the action's plan, but no one-way state ever closes issuance.

### Can we change an instrument's rules after it is live?

Yes. Compliance rules change one binding at a time after issuance, and each is a role-gated governance operation on that asset with its own record. The same applies to the instrument's metadata, its eligibility registry, and its ordered feature list. On chain, the governance role can also replace the token's whole compliance contract or its identity registry in one call, and together with Supply management and Custodian, or with the admin role, its full feature list. Treat that role as the instrument's rule-making authority. Some things are deliberately locked instead: template fields marked immutable when the template was published, and the maturity date on most fixed-income templates. A locked field is a design decision recorded at publication, so if a product needs different behaviour the answer is a new template instead of an edit to the live one.

### Who holds the assets through all of this?

The holders do, in their own wallets. A wallet must carry a verified identity in the instrument's eligibility registry before it can receive any units. Where its signing key lives changes who can sign. The key can sit in your hardware security module, with a qualified custody provider, or in an encrypted store the platform manages, and with the key in that store the platform signs the holder's transactions. A holder of the asset's custodian role can still move a holding without the holder's signature, and while an order works on a [Trading Venue](https://docs.settlemint.com/docs/concepts/issuing-and-markets/trading-venue) its units sit in the venue's escrow.

### How does a dividend or a split run?

The industry name for these is "corporate actions", and each is a named lifecycle event on a security: a cash dividend, a bond coupon, a stock split, a rights issue, a spin-off, or a decrease of capital. The platform translates the legal event into its economic effect and runs it with the same primitives everything else uses. A record-date snapshot fixes who held what. Batch mints, batch burns, or a yield declaration then apply the terms. No second engine sits behind them, and one record stores the announced terms, the snapshot, the batch progress, and the transaction references.

## Related concepts [#related-concepts]

- [Primary Offering](https://docs.settlemint.com/docs/concepts/issuing-and-markets/primary-offering): The contract-governed first sale of newly issued units to investors, the issuance step this page's whole life begins from.
- [Transfer-Path Compliance](https://docs.settlemint.com/docs/concepts/compliance-and-identity/transfer-path-compliance): The enforcement of a regulated token's rules inside the on-chain transfer itself, so a movement that fails any rule reverts and never settles.
- [XvP Settlement](https://docs.settlemint.com/docs/concepts/settlement/xvp-settlement): An on-chain exchange between two or more parties in which every leg settles together in one transaction or none settles at all.
- [Settlement Verdict](https://docs.settlemint.com/docs/concepts/settlement/settlement-verdict): The recorded end state of an on-chain operation submitted to the platform, and the only signal from which success may be reported.
- [Trading Venue](https://docs.settlemint.com/docs/concepts/issuing-and-markets/trading-venue): The permissioned exchange a deployment runs for its own identity-verified participants, where each order locks its units in the venue's escrow until the trade delivers or the order closes.
- [DALP Instance](https://docs.settlemint.com/docs/platform/dalp-instance): One self-contained copy of the platform, deployed on infrastructure you choose and connected to ledger networks you approve.
- [Instrument Templates](https://docs.settlemint.com/docs/concepts/modeling-assets/instrument-templates): The reusable definition of one product shape, binding its business class, the instrument facts it records, the on-chain behaviours it carries, and its compliance rules.
- [Corporate Action](https://docs.settlemint.com/docs/concepts/issuing-and-markets/corporate-action): A named lifecycle event on a tokenised security, such as a dividend, coupon, split, or rights issue, run through the primitives the instrument already carries.


# Corporate Action

Source: https://docs.settlemint.com/docs/concepts/issuing-and-markets/corporate-action
A Corporate Action records an issuer's event on a token, such as a dividend or a split, and applies it on chain as a claimable payout or a mint or burn.



[Figure] One action record routes legal terms to the instrument capability that executes them. An authorised operator records the announced terms and the entitlement basis in one corporate action record. That record routes the event to the instrument capability that owns the economic effect: scheduled yield, a dividend claim, maturity redemption, or a supply operation such as mint, burn, transfer, or sale. Each route applies its own contract rules when an authorised operator or holder invokes it. The record coordinates those operations. It does not execute every event automatically or create a second settlement engine. It retains the terms, entitlement basis, progress, and transaction references for the recorded outcome. Labels: Approved inputs; Announced terms; event, dates, economics; and authorised operator; Entitlement basis; schedule, balance, or; record-date snapshot; Corporate action record; Durable coordinator; holds terms and entitlement; tracks batch progress; links transaction references; Owning capability; Scheduled yield; accrual and holder claim; Dividend claim; snapshot entitlement; Maturity redemption; burn principal, pay face value; Supply operation; mint, burn, transfer, or sale; Recorded outcome; contract verdict and progress remain tied to the action.

One record holds the announced terms and the entitlement basis, then routes the event to the instrument capability that owns the money without executing it.

A Corporate Action records an issuer's announced event on the token and hands it to the feature that applies it. A holder claims a coupon or a dividend, or redeems at maturity, from their own wallet. A supply change mints or burns units on each holder's balance. The holder file and the ledger update come from the same record. The institution still keeps the board resolution, the notice and the funding evidence.

The catalogue has thirteen types that work in four ways. A cash dividend and a distribution declare a payout on chain. A bond coupon, a maturity redemption and a conversion name a programme the token already carries. A bonus issue, a rights issue, a capital decrease, a stock split, a spin-off, a partial redemption and a buyback change supply through stored per-holder allocations. A coordinated distribution pays every share class of an instrument from one pool.

The action record links the announced terms and entitlement basis to the resulting on-chain transactions, so a reviewer can trace one to the other.

## Why corporate actions need one record [#why-corporate-actions-need-one-record]

After issuance come years of servicing: paying what was promised, tracking who holds a claim to it, and proving both to a regulator later. [Asset Lifecycle](https://docs.settlemint.com/docs/concepts/issuing-and-markets/asset-lifecycle) places that servicing in its own stage, and a Corporate Action covers most of it. A maturity trigger runs in the optional Retire stage, where an instrument that carries the maturity feature matures, holders redeem at face value, and their positions burn.

A paper process splits a corporate action across separate systems. An issuer's legal notice names who is owed what, a registrar's holder file names who holds the instrument, a payments desk moves the funds, and a ledger records that it happened. Every handoff between them is a reconciliation where the ledger state and the legal record can drift apart. A Corporate Action closes that gap for one kind of event. It connects the announced economics straight to the holders entitled to receive them, so there is no separate holder file or payment instruction to keep in step with the chain.

## Why the instrument's own record runs it [#why-the-instruments-own-record-runs-it]

The alternative is a corporate-actions process that sits beside the instrument. It keeps its own copy of who holds what, its own funding source and its own record of who was paid. That copy is where the two systems can disagree: the side system computes an entitlement from stale data, and the instrument's own compliance rules would have refused the transfer.

A Corporate Action record keeps no copy of the holder register of its own. A dividend's snapshot is built from the holders' record-date balances and committed on chain as one root, so the entitlement basis is fixed and published. The record coordinates: it does not hold the money, and it does not decide eligibility on its own. Payout features draw from a configured treasury, the wallet or contract that holds the payout asset, and never hold the payout asset themselves. Each route invokes the feature that already owns that economic effect on the instrument itself, whether that effect is a dividend claim, a treasury-yield coupon, a maturity redemption, or a supply operation such as mint, burn, transfer, or token sale. Because the payout runs through the instrument's own contract, the same eligibility registry and transfer rule that govern every other movement of that instrument govern this one too. The identity check a holder already passed to receive the token is the same check that gates their payout.

The platform executes terms that an authorised issuer or agent supplies. It does not decide whether a dividend should be declared, whether an instrument should mature early, or whether the legal notice behind either is valid. Those decisions stay in the issuer's own governance and legal process, outside the platform.

## What a Corporate Action does [#what-a-corporate-action-does]

For most types an operator can read the plan first, which stores nothing. A bond coupon, a maturity redemption, a conversion, and a cash dividend or distribution have no plan until they are recorded. Recording stores the terms: for a cash dividend or a distribution paid in cash it also declares the payout on chain, and for a maturity redemption it matures the bond. Nothing is paid, minted or burned until the reviewed allocation is applied, or until a holder claims or redeems. A plan is the list of mints, burns or payouts per holder that a type would apply. Preview or quote reads it, record stores the terms, and confirm or commit runs it.

The economic result depends on the event. [Fixed interest](https://docs.settlemint.com/docs/concepts/modeling-assets/token-features/income#fixed-treasury-yield) accrues from a configured schedule, and a holder claims it. A cash [dividend](https://docs.settlemint.com/docs/concepts/modeling-assets/token-features/income#dividend-yield) fixes entitlement from a record-date snapshot and later becomes claimable. Maturity closes ordinary issuance, fixes the supply basis for principal redemption, and lets holders burn positions for the Denomination Asset, the single asset in which the instrument's face value and payouts are stated, at face value. A stock split, a bonus issue, a rights issue, a capital decrease, a spin-off, a partial redemption and a buyback each resolve to a chunked mint or burn against stored per-holder allocations. A rights issue can instead add the entitled holders to the whitelist of an existing token sale.

The [corporate actions API guide](https://docs.settlemint.com/docs/api-reference/guides/corporate-actions) covers the create, preview, confirm, and abort sequence, and the quote and commit calls that read the plan and run it under one wallet verification. The [Console](https://docs.settlemint.com/docs/console/asset-management/manage/corporate-actions) uses the quote and commit for a supply change or a payment in new tokens: the operator reads the plan for every holder first, and one PIN then records the action and runs it. A cash dividend, a distribution paid in cash, and a coordinated distribution keep the record, preview, and confirm steps. One invariant holds across every type: an operator must never treat the announcement step as payment.

## A dividend's snapshot is irreversible [#a-dividends-snapshot-is-irreversible]

For a dividend, the operator declares the ex-date, record date, payment date and claim deadline, the per-share amount, and whether the dividend is regular or special. Each date falls on or after the one before it, and the claim deadline lies in the future. [DALP-9206](https://docs.settlemint.com/docs/api-reference/errors) enforces that order. The dates may coincide, and every date except the claim deadline may lie in the past. A special dividend is a one-off payment. The kind is recorded with the dividend and does not change these checks. A past record date must fall on or after the moment the token's historical balances were enabled, which is what [DALP-9294](https://docs.settlemint.com/docs/api-reference/errors) enforces. The operator then records the holder snapshot, waits until the payment date, and holders submit claims with proof of entitlement. The snapshot is a Merkle root that the platform builds off chain from the holders' record-date balances and a governance-role holder records. The contract does not check the root against balances, so keep the holder list behind each root as evidence.

The snapshot is the step to get right, because a dividend accepts exactly one. It cannot be recorded before the record date has passed, which answers [DALP-9212](https://docs.settlemint.com/docs/api-reference/errors), and a second attempt on the same dividend answers [DALP-9213](https://docs.settlemint.com/docs/api-reference/errors). No operation replaces a recorded snapshot, and cancelling the dividend stops being possible the moment one lands, which answers [DALP-9214](https://docs.settlemint.com/docs/api-reference/errors). An entitlement basis captured against the wrong holder set cannot be corrected in place. What is left is to let the claim deadline pass, reclaim the unclaimed funding, and declare a fresh dividend against a new record date.

[Figure] A dividend runs one way, and cancel ends at the snapshot. A dividend moves through four stages in one direction. Declaration fixes the record, payment, and claim-deadline dates. Once the record date has passed, the operator records exactly one holder snapshot, and cancelling the dividend is refused from that moment on. From the payment date, each snapshot entry can be claimed once. After the claim deadline passes, an explicit reclaim call releases the reserved funding for unclaimed entries and closes the dividend. A snapshot taken against the wrong holder set cannot be replaced: the dividend runs out its claim deadline and a fresh one is declared. Labels: Cancel ends at the snapshot; Declared; record, payment,; and deadline fixed; Snapshot recorded; record date passed,; exactly one allowed; Claims open; from payment date,; one claim per entry; Funding reclaimed; an explicit call, after; the deadline, closes it; cancel possible until the snapshot lands.

A dividend can be cancelled until its snapshot is recorded, and recording the snapshot closes that path.

A payable dividend's claim deadline can be pushed out once, for as long as no reclaim has closed the dividend, to give holders who have not claimed a further window. A second extension on the same dividend is refused. A governance-role holder extends the deadline, cancels before the snapshot and reclaims after the deadline. An emergency-role holder can pause all claims on the dividend feature.

## Maturity cannot be undone [#maturity-cannot-be-undone]

Note (Maturity cannot be undone): Triggering maturity is one-way. No operation returns a matured instrument to its pre-maturity state, and once matured, transfers stop except for forced transfers and burns. Maturity also freezes the treasury binding: the feature can no longer be repointed to a different treasury address. The configured treasury can still receive funds. An operator who opened redemptions early during a shortfall recovers by sending the denomination asset directly to the treasury address already configured. The next redemption pays against the new balance. The block on transfers and mints is enforced by the maturity feature itself, so an account that can set the feature list and detaches that feature lifts it. Restrict the governance role on a matured instrument.

Two paths reach the matured state of the [maturity redemption](https://docs.settlemint.com/docs/concepts/modeling-assets/token-features/income#maturity-redemption) feature. The ordinary path is available to the governance role once the scheduled date is reached. It does not mature an instrument whose treasury does not hold face value times the supply outstanding, so redemptions cannot open underfunded on that path. The early path is available to the emergency role, only strictly before the scheduled date, and it skips that solvency check on purpose so an operator can open redemptions during a shortfall. Using it means holders who redeem first are paid in full and later holders may find nothing left. The ordinary path checks solvency once, at the moment of maturity. A treasury drained after maturity does not undo maturity, and later redemptions fail with [DALP-12373](https://docs.settlemint.com/docs/api-reference/errors).

Maturity fixes the aggregate redemption basis: the supply outstanding at that moment becomes the basis for principal redemption. Each holder then redeems separately, and a redemption pays only for the amount burned. That matters when another feature on the instrument rewrites part of a burn as a fee: the holder is then paid for the net burned amount.

A redemption fails before a holder pays gas for a transaction that would revert, and the failures trace back to the treasury's funding and configuration instead of the holder's own position. A holder is not told about the treasury unless the organisation shares redemption funding with holders: a redemption the treasury cannot fund, or one that reverts on chain, answers [DALP-12373](https://docs.settlemint.com/docs/api-reference/errors), which says only that the redemption cannot be completed and carries no treasury address, allowance, or amount. A holder who sees it contacts the issuer. When the organisation shares redemption funding, or the caller manages the token or is its treasury, a redemption the treasury's balance cannot pay answers [DALP-14506](https://docs.settlemint.com/docs/api-reference/errors) and one a wallet treasury has not approved enough for answers [DALP-9481](https://docs.settlemint.com/docs/api-reference/errors), each naming the treasury and the amounts.

The funding diagnosis belongs to the issuer. Read the maturity feature's treasury state and bond status before holders redeem, and approve the full payout the outstanding supply needs instead of the difference, because the standard token approval overwrites the earlier one. An approval sent from any wallet other than the configured treasury answers [DALP-9480](https://docs.settlemint.com/docs/api-reference/errors). The platform's own approve-allowance control signs with the acting wallet, so it works only when that wallet is the configured treasury. For any other treasury contract, the approval has to come from that contract's own admin or governance flow. Before maturity, the treasury can instead be set to a wallet the platform signs for.

A redemption attempted before the instrument has matured answers [DALP-9478](https://docs.settlemint.com/docs/api-reference/errors), and a preflight that runs before the indexed feature state has landed answers [DALP-9477](https://docs.settlemint.com/docs/api-reference/errors) or [DALP-9479](https://docs.settlemint.com/docs/api-reference/errors), both worth retrying instead of treating as a configuration fault. [Yield and maturity](https://docs.settlemint.com/docs/console/asset-management/manage/yield-maturity) covers funding and triggering a maturity feature step by step.

## Choosing a treasury type [#choosing-a-treasury-type]

The treasury type is a choice made when the feature is configured, and it changes what an operator does before every payout. An externally owned wallet suits a low-frequency payout that a human signs by hand. A vault suits recurring payouts, or an institution that cannot keep a signing key hot.

| Treasury type | What it needs before a payout | What it costs to run |
| --- | --- | --- |
| An externally owned wallet. | A standing approval to the feature for at least the payout amount, signed by that wallet. | The wallet authorises the allowance. An allowance that runs out stops redemptions with [DALP-9481](https://docs.settlemint.com/docs/api-reference/errors). |
| A vault or other contract. | The funds present, with the contract implementing its own payout logic. | No per-payout approval from a person, and the contract's own controls decide who moves the balance. The platform approves on its behalf only when the contract is the acting smart wallet. |

## Coordinator and capability stay separate [#coordinator-and-capability-stay-separate]

A Corporate Action coordinates, and the instrument's feature executes. Maturity shows that split most clearly. The record schedules the trigger and tracks its outcome. The maturity redemption feature is what matures the instrument.

[Figure] Two ways into maturity, and no way out of it. Two paths reach the matured state. Ordinary maturity is available to the governance role on or after the scheduled date, and only when the treasury holds face value times the supply outstanding. Early maturity is available to the emergency role, only strictly before the scheduled date, and it skips that solvency check so redemptions can open during a shortfall. Both lead to the same matured state, where transfers stop except for forced transfers and burns, and the treasury binding is frozen for repointing, though it can still be funded directly. From there each holder redeems separately, burning their own position for face value on the amount burned. No transition leads out of the matured state. Labels: Two ways in, no way out; Ordinary maturity; governance role, on or; after the date, funded; Early maturity; emergency role, before; the date, funding unchecked; Matured; Terminal state; transfers stop except; forced transfers and burns; Holders redeem; each burn pays face; value per unit burned; no transition leads out of the matured state.

Two entrances, one terminal state, and a solvency check that only one of the entrances applies.

This separation keeps one source of enforcement: whichever feature owns an event's economic effect is what enforces it, never the record that scheduled the call.

Payout-bearing features share one treasury rule: a feature pulls an approved denomination asset from an externally owned treasury, or delegates payout to a vault that implements its own payout logic. In neither case does the feature custody the denomination asset, which is why an identity-controlled payout asset stays compliant: the feature never needs an identity merely to hold funds.

## Paying several share classes from one pool [#paying-several-share-classes-from-one-pool]

An instrument with several share classes pays every class from one pool of cash through a distribution waterfall. The waterfall is a vault with a ledger for each class. It holds one balance and tracks how much of that balance each class may draw. A coordinated distribution is the corporate action that funds it: one pool, one record date, and each class paid in rank order.

Two separate cash dividends on two classes would draw on the same money with no shared rule for who comes first. The waterfall puts that rule in one place. Money enters once, when the coordinated distribution funds the pool, and the waterfall splits it into one leg for each class. Money leaves when a holder claims. Each class's dividend feature uses the waterfall as its treasury and draws down only its own class's leg. A class never receives a lump sum. Its leg always reaches holders as per-share dividends, for income and for capital return alike.

[Figure] One pool enters the waterfall and leaves as one leg for each class. The executing wallet funds one pool into the distribution waterfall, which holds a single cash balance. The waterfall splits the pool into one leg for each share class, in rank order, and keeps a counter for each leg. Each class's dividend feature uses the waterfall as its treasury. When a holder claims, the dividend feature pays out of that class's leg only, and the cash leaves the waterfall for the holder. Cash stays in the waterfall until a holder claims. Labels: One pool, one leg for each class; Funder; Executing wallet; holds the pool.; fund; Distribution waterfall; One cash balance; Controlling leg; Its own counter; Economic leg; Its own counter; payout; payout; Dividend yield; Controlling class; Dividend yield; Economic class; Holders; claim; Holders; claim; Cash stays in the waterfall until a holder claims.

The waterfall holds one balance and one counter for each class, a class draws only its own leg, and cash leaves only when a holder claims.

Two modes decide the legs. In ordinary mode, the whole pool goes to the classes with the lowest ordinary rank, split by the capital each class paid in. In priority mode, a determination that a trusted issuer signed names an event, such as a wind-down that the sponsor caused. Each class then recovers the capital it paid in, tier by tier, before the rest follows the ordinary ranks. The two orderings are independent, so a class can rank first for income and second for capital. The [distribution waterfall entry](https://docs.settlemint.com/docs/concepts/modeling-assets/token-features/income#distribution-waterfall) lists the terms and works through the numbers.

A coordinated distribution guards the split from preview to payment. Preview declares each class's dividend and takes its holder snapshot. The operator then reviews the split, and when the organisation's Corporate actions approval is on, an organisation owner or platform administrator other than the operator approves it. Confirm computes the split again and reverts before any money moves if it differs from the previewed one, so the platform never pays a split that differs from the preview. Confirm then funds the pool and records each class's snapshot in rank order. Three controls apply: a class can draw only its own leg, a second approver reviews the plan when the organisation has turned that approval on, and only one coordinated distribution can be open on an instrument at a time. Abort is refused while the funding transaction may still land or a class is still being recorded. After the pool is funded, abort keeps the classes already open for claims and cancels the rest.

## The integration contract [#the-integration-contract]

A Corporate Action integration treats creation, confirmation, holder execution, and reconciliation as distinct states, so it never confuses an announced event with a completed payout or supply change. The action identifier is the durable business key. Transaction references show how its current progress reached the ledger, and integrations read both.

Read the instrument's attached features before presenting an operation. A dividend route requires the dividend feature, scheduled interest requires fixed treasury yield, and principal redemption requires maturity redemption. Validate dates and positive amounts before you send the request, but expect the contract to recheck authorisation, timing, entitlement, available treasury funds, and claim status during execution. One corporate action in progress is allowed per token. A second create attempt while the first is not completed or aborted is refused, and the platform refuses its own mint and burn routes on that token until then. The token contract does not know about the record, so a direct mint or burn by a supply manager still runs.

Use one [idempotency key](https://docs.settlemint.com/docs/api-reference/guides/idempotency-async-settlement) per business instruction. If a response is lost, inspect the recorded operation and corporate-action state before sending another request. Reuse the key for an API retry only when that route documents replay safety. After submission, follow the recorded operation to its Settlement Verdict, the recorded end state of an on-chain operation and the only signal from which success may be reported, and re-read the corporate-action record before reporting completion. For holder claims, preserve the action or dividend identifier and the holder's proof data. Request acceptance and an unresolved transaction hash are intermediate states, never the answer.

## Controls and evidence [#controls-and-evidence]

The record creates an evidence chain from approved terms to holder-level execution: it identifies the event, dates, economics, entitlement basis, executing transactions, and the progress of any multi-transaction batch. A reviewer can separate what the issuer announced, what the platform executed, and which holder entitlements remain open.

Role checks restrict who may declare or confirm an action. Holder eligibility is fixed from the relevant source: scheduled yield follows on-chain balance history and the configured schedule, while a dividend uses the snapshot root a governance-role holder recorded. Dividend claims also recheck the claimant's on-chain identity at claim time. A failed check reverts the operation instead of producing an off-ledger exception. A holder of the token's custodian role can also claim a dividend for a holder, or redeem a holder's matured units, and the payout still goes to the holder.

A cash dividend, a cash distribution, a bonus issue, a rights issue, a spin-off, a capital decrease, a stock split, a partial redemption, a coordinated distribution, a payout in new tokens or a buyback can carry a [maker-checker](https://docs.settlemint.com/docs/concepts/custody-and-signing/maker-checker) gate: an organisation owner or platform administrator other than the maker approves or rejects the computed plan before confirm can run. While the organisation's Corporate actions approval is off, or while it has no other owner who could approve, the action runs without that approval. The gate governs the platform's submission and does not bind a direct contract call.

The record proves what the platform received and executed. It does not prove that the issuer's board resolution, notice process, tax treatment, or off-chain funding source was legally sufficient. Those source documents stay in the institution's evidence file, linked through the institution's own control process.

## Frequently asked questions [#frequently-asked-questions]

### Does a bond mature on its own when the scheduled date arrives?

No. Reaching the date changes nothing by itself. It only opens the ordinary maturity path to the governance role, and that trigger is still refused while the treasury holds less than face value times the supply outstanding. Until an authorised operator triggers maturity, the instrument keeps transferring and servicing normally, so a bond can sit past its scheduled date without maturing.

### Can an operator recover a corporate action that opened redemptions during a shortfall?

No. Recovery does not undo the trigger: no operation returns a matured instrument to its pre-maturity state once early maturity has opened redemptions. What an operator can do is send the denomination asset directly to the treasury address already configured for the feature, and the next redemption pays out of that refreshed balance. The operator closes the shortfall by topping up the treasury.

### Can an entitled holder claim twice?

No, and each feature refuses it on its own rule. A dividend entry is all or nothing: the recorded snapshot gives a holder one entitlement, the feature marks that entry claimed when it pays, and a second claim against the same entry is refused. Scheduled yield keeps a per-holder mark of the last period paid and pays only the periods after it, so a repeat claim inside the same period has nothing to pay. Redemption pays for the amount burned in that call. A holder can redeem remaining units later but cannot redeem units already burned.

### Can a holder redeem a matured position in parts?

Yes. A redemption pays for each burn separately. A holder chooses an amount each time, the feature burns it and pays face value on what was burned, and the same holder can return for the rest later. The one shared ceiling is the total paid across all holders, capped at face value times the supply recorded at the moment of maturity.

### Does a junior class earn income from a shared pool?

Only when its ordinary rank equals the senior class's rank. In ordinary mode the lowest rank takes the whole pool, so a class at a higher rank receives nothing from ordinary distributions, and no error reports it. Equal ranks share income by the capital each class paid in. A junior class recovers its paid-in capital through priority mode, when a trusted issuer's determination names an event that the terms rank differently. The [distribution waterfall entry](https://docs.settlemint.com/docs/concepts/modeling-assets/token-features/income#distribution-waterfall) shows the arithmetic.

## Related concepts [#related-concepts]

- [Asset Lifecycle](https://docs.settlemint.com/docs/concepts/issuing-and-markets/asset-lifecycle): The working life of a regulated tokenised instrument from issuance through servicing to final redemption, whose Service and Retire stages a corporate action fills.
- [Primary Offering](https://docs.settlemint.com/docs/concepts/issuing-and-markets/primary-offering): The contract-governed first sale that closes before an instrument's servicing life, and its corporate actions, begin.
- [Fund dealing](https://docs.settlemint.com/docs/concepts/issuing-and-markets/fund-dealing): The dealing-day subscriptions and redemptions of an open fund, which run beside its corporate actions.
- [Trading Venue](https://docs.settlemint.com/docs/concepts/issuing-and-markets/trading-venue): The venue that settles trades in the same Service stage a corporate action services, on the same instrument and the same compliance path.
- [Token Distribution](https://docs.settlemint.com/docs/concepts/issuing-and-markets/token-distribution): A separate Merkle-proof claim mechanism for putting an allocation into many wallets at once, the same claim pattern a dividend's holder snapshot reuses for payout instead of allocation.
- [Denomination Asset](https://docs.settlemint.com/docs/concepts/modeling-assets/denomination-asset): The asset in which one payout feature's face value and payments are stated.
- [Settlement Verdict](https://docs.settlemint.com/docs/concepts/settlement/settlement-verdict): The recorded end state of an on-chain operation and the only signal from which success may be reported.
- [Maker-Checker](https://docs.settlemint.com/docs/concepts/custody-and-signing/maker-checker): The approve-or-reject pattern that a cash dividend, cash distribution, partial redemption, stock split, bonus issue, rights issue, spin-off, capital decrease, coordinated distribution, payout in new tokens, or buyback can require before it runs, once the organisation turns on the Corporate actions switch under Approvals.


# Fund dealing

Source: https://docs.settlemint.com/docs/concepts/issuing-and-markets/fund-dealing
Fund dealing groups requests by UTC dealing day, closes each day at 12:00 UTC, and settles subscriptions and redemptions at one published net asset value.

An open-ended fund takes in and pays out money continuously, but it cannot price each request separately. Fund dealing gives every request a dealing day, closes the day at a fixed cut-off, and lets the fund operator settle the day's requests together at one net asset value (NAV) per unit. A dealing day is a weekday counted in UTC. The cut-off is 12:00 UTC on that day.

Dealing applies to a fund token that can settle a cash buyback and whose units are not on register lines. Register lines are the holder register that the [Booked movements](https://docs.settlemint.com/docs/console/asset-management/manage/booked-movements) feature keeps, and [Token features](https://docs.settlemint.com/docs/concepts/modeling-assets/token-features) lists the features a token carries. The platform refuses a request on any other token, including a bond.

The platform keeps two books for each fund token. The subscription book holds investors' requests to put in a cash amount. The redemption book holds holders' requests to give back a number of units. The books live in the platform and move no units. Requests, cancellations and rejections are platform records with no chain event, and only the settlement transactions reach the chain. The Console page [Fund subscriptions and redemptions](https://docs.settlemint.com/docs/console/asset-management/manage/fund-dealing) covers the screens. This page covers the model behind them.

Fund dealing belongs to the Primary market licensed module, together with offerings ([Switch application layers on or off](https://docs.settlemint.com/docs/deployment/install/values-secrets#switch-application-layers-on-or-off)). An organisation that opts out of it keeps its requests readable, and the platform refuses new requests, cancellations, term changes and settlements until the module is back on. A buyback that a settlement drafted before the opt-out stays a corporate action, and its approval and confirmation still run.

## The dealing calendar [#the-dealing-calendar]

Every request, in both books, takes its dealing day from the instant the platform records it, so the same instant always gives the same day and a client cannot choose its own. The calendar reads no holiday list, so a bank holiday on a weekday is still a dealing day.

| When the platform records the request | Dealing day it belongs to |
| --- | --- |
| Monday to Friday, before 12:00:00 UTC | That same day |
| Monday to Thursday, at or after 12:00:00 UTC | The next day |
| Friday, at or after 12:00:00 UTC | The following Monday |
| Saturday or Sunday | The following Monday |

The cut-off of a request is 12:00 UTC of its own dealing day. A holder or investor can cancel an open request until that instant. The cut-off follows from the request's dealing day alone, and the platform compares it with its own clock, never with a time the client sends. A cancel at 12:00:00.000 UTC or later is refused.

## Subscriptions record a cash amount [#subscriptions-record-a-cash-amount]

A subscription request names a wallet of the investor and a cash amount in the fund's subscription [stablecoin](https://docs.settlemint.com/docs/concepts/modeling-assets/stablecoin). It records the amount, not a number of units. The Console and the Investor portal take the amount in the same field as a transfer, which shows its value in the stablecoin's price currency when the stablecoin has a price. Before anyone can subscribe, a supply manager, a holder of the token's supply management role, sets the subscription terms: the stablecoin, the treasury that receives the cash and an optional minimum amount. A fund with no terms refuses every subscription request. A supply manager can change the terms at any time, the receiving treasury included, and the change needs no second approval.

The platform checks the request when the investor lodges it. The amount must be more than zero and at least the minimum. The wallet must belong to the investor. The platform also checks that the token's identity and compliance rules would let the wallet receive units. It refuses the request when they would not, or when it cannot complete the check.

A subscription request does not move or lock cash when the investor lodges it. The cash stays in the investor's wallet until the settlement pulls it, on the allowance the investor gave the receiving treasury. That allowance is not tied to any request on chain, so the treasury wallet can draw on it up to its limit. An investor who approves only what their open requests need limits that exposure. The request stays open until the investor cancels it before its cut-off or the operator settles its dealing day.

A supply manager settles a subscription day through the API, signing with the wallet that is the receiving treasury of the terms. A call from any other wallet is refused with [DALP-14081](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference#domain-rule-errors). Subscription settlement takes no second approval. The platform reads the fund's NAV for that day from the price feed and prices each open request of that day or an earlier one. In one transaction per batch of up to ten investors, it pulls each investor's stablecoin to the receiving treasury and mints the units. A priced request is settling until its transaction is on the chain, then settled.

A request the settlement leaves out is rejected with its reason:

- The investor's cash, after their earlier requests in the same settlement, no longer covers the request.
- The investor's allowance to the receiving treasury, after their earlier requests in the same settlement, does not cover the request.
- The investor cannot receive the fund token.
- The cash buys less than the smallest unit of the fund token at that NAV.
- The request was lodged in another stablecoin than the terms now name.

When a batch's transaction is refused or reverts on the first call, that batch's requests and every later batch's requests return to open and the call fails. Batches that landed before it stay settled. On a repeat call with the same key, a refused batch returns only its own requests to open, and the other batches are still sent. A batch that does not land in time stays settling until the operator repeats the call with the same key. The next settlement takes the reopened requests.

## Redemptions settle at the NAV of the dealing day [#redemptions-settle-at-the-nav-of-the-dealing-day]

A redemption request names a holder wallet and a number of units. The platform checks it against the units the wallet has available, less the wallet's other open and settling requests on the token and less any frozen units. An amount up to that figure is accepted and an amount over it is refused. A request does not lock units on chain, because a lock would need a transaction for every request, and the wallet can still move them. The platform checks the units again when the operator settles, and rejects the request if they are gone.

A redemption request has five statuses.

[Figure] The five statuses of a redemption request. A request starts open. The holder can cancel it before the cut-off, which makes it cancelled. A settlement can reject it, which makes it rejected. A settlement can take it, which makes it settling. A settling request becomes settled once its payment is on the chain, and returns to open if the buyback that would pay it completes without paying it or is aborted before its confirmation starts a transaction. Labels: Open; until cancelled or settled; Cancelled; holder, before cut-off; Settling; a buyback is drafted; open again if unpaid; Rejected; the settlement refuses it; Settled; payment on chain.

A request starts open and ends cancelled, rejected or settled, and a settling request returns to open when its buyback does not pay it.

Cancelled, settled and rejected are final statuses, and a rejected request is not retried, so the holder lodges a new one.

### How the operator settles a day [#how-the-operator-settles-a-day]

After the cut-off, a supply manager settles a redemption day. The call names the dealing day, a stablecoin and the paying treasury. The platform then works in this order.

1. It takes every open request of that dealing day or an earlier one. A day missed earlier is therefore settled with the next one.
2. It reads the NAV: the latest value the fund's price feed published, by block time, from the dealing day's cut-off up to the next dealing day's cut-off, and never later than the moment of settlement. The NAV belongs to the day being settled, so a request from an earlier day is priced at that NAV too. Once a request of the day has been paid, every later settlement of that day uses the same NAV. See [Market data](https://docs.settlemint.com/docs/concepts/records-and-evidence/market-data) for how a fund takes its price from a feed.
3. It turns the NAV into a price per unit in the smallest unit of the stablecoin, rounded down. The NAV and the stablecoin's own reference price must name the same currency.
4. It covers each holder's requests in creation order against the units the holder has available. A request the units do not cover is rejected as `insufficient-units`. A holder whose cash rounds to zero has its requests rejected as `zero-cash`. A holder the stablecoin would refuse to pay from the treasury has its requests rejected as `cash-not-receivable`. The cash of a holder is its units times the price per unit, rounded down, so the remainder stays in the paying treasury.
5. It drafts one buyback corporate action with a cash leg. The buyback names each paid holder once, with its units, and carries the one price per unit. The covered requests become settling, each with its cash.

The platform stores the settlement, the rejected requests, the settling requests and the corporate action in one transaction. If the open requests changed while it prepared the plan, it stores nothing and refuses the call with [DALP-14103](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference#domain-rule-errors), which a caller can retry. If every request is rejected, the settlement is stored without a corporate action.

The settlement does not move money. The buyback is a corporate action. The Corporate actions row under Approvals in the [General](https://docs.settlemint.com/docs/console/organisation-settings/general#approvals) organisation settings starts off. Once an owner or a platform administrator turns it on, the buyback needs [maker-checker](https://docs.settlemint.com/docs/concepts/custody-and-signing/maker-checker) approval: an organisation owner or platform administrator other than the supply manager who settled the day approves it. While it is off, or while the organisation has no other owner who could approve, the buyback runs without a second signature. The approval holds back the platform's own submission. The token checks only the supply management role, so it does not bind a supply manager who calls the token directly. A supply manager then confirms the buyback, which burns the units and pays the cash. The Console page [Corporate actions](https://docs.settlemint.com/docs/console/asset-management/manage/corporate-actions) covers that review.

Only one corporate action can run at a time on a token, so a settlement is refused with [DALP-12067](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference#domain-rule-errors) while an earlier buyback is still unfinished.

### The requests follow the buyback [#the-requests-follow-the-buyback]

The platform reads the buyback again whenever someone settles, lists or creates a redemption request on the token. A holder whose payment is on the chain has its settling requests marked settled, with the transaction hash and the time the platform recorded the payment. When the buyback completes, or is aborted before its confirmation starts a transaction, a holder's unpaid requests return to open with their original dealing day and cut-off. The next settlement takes them again. If the buyback was aborted after its confirmation started a transaction, the platform does not reopen the unpaid requests. They stay "Settling" and their units stay counted against the holder's available units. A read that fails is logged and does not block the call.

## Frequently asked questions [#frequently-asked-questions]

### Does the platform calculate the NAV?

No. A trusted issuer of the fund's price feed topic publishes it, and the settlement reads the value published for the dealing day. The platform does not keep that publisher apart from the supply manager who settles, so separate the two in your own controls if they require it. A request is never priced before its cut-off, and a dealing day with no NAV published between its cut-off and the next cut-off cannot be settled. A redemption settlement is refused with [DALP-14099](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference#domain-rule-errors) and a subscription settlement with [DALP-14081](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference#domain-rule-errors) and the reason `nav-unavailable`, until someone publishes one.

### Can a supply manager cancel an investor's request?

No. A cancellation works only for the wallets of the holder or investor who made the request. A request that belongs to another wallet, belongs to another token or does not exist answers as not found, for a supply manager too.

### What if the same request is sent twice?

A redemption request call is idempotent per holder and idempotency key. A repeat with the same token and amount returns the stored request as it stands now, even when it was cancelled in the meantime, and never reopens it. A repeat with another token or amount is refused.

A subscription request call is idempotent per token and key. A repeat with the same investor and amount returns the stored request while the token, the terms, the wallet and the amount still pass their checks, and a repeat with another investor or amount is refused.

### When does an investor use fund dealing instead of a Primary Offering?

A [Primary Offering](https://docs.settlemint.com/docs/concepts/issuing-and-markets/primary-offering) is a one-time first sale of a token on fixed terms. Fund dealing serves an open-ended fund after that, taking subscriptions and redemptions every dealing day at that day's NAV.

### How does a bank transfer payout relate to this?

It does not. A fund redemption pays in a stablecoin through a buyback. The redemption requests of the bank rail are a separate flow with their own roles, and [Bank rail](https://docs.settlemint.com/docs/console/asset-lifecycle/bank-rail) covers them.

## Related concepts [#related-concepts]

- [Corporate Action](https://docs.settlemint.com/docs/concepts/issuing-and-markets/corporate-action): The buyback lifecycle that pays a settled redemption day.
- [Primary Offering](https://docs.settlemint.com/docs/concepts/issuing-and-markets/primary-offering): The first sale of a token at a fixed price.
- [Market data](https://docs.settlemint.com/docs/concepts/records-and-evidence/market-data): The feed that publishes the NAV.
- [Maker-Checker](https://docs.settlemint.com/docs/concepts/custody-and-signing/maker-checker): The second approval a buyback can require.


# Primary Offering

Source: https://docs.settlemint.com/docs/concepts/issuing-and-markets/primary-offering
A Primary Offering lets an issuer sell newly issued units once and resolve payment, allocation, and delivery or refunds as one on-chain outcome.



[Figure] Primary Offering lifecycle. You can follow issuer inventory and investor funding into allocation. Finalisation sends proceeds to the issuer and tokens to investors after success, or returns payments when an optional minimum is missed. Labels: One controlled offering; Issuer commits; tokens, price and terms; Investors subscribe; eligible funding only; offer; Allocate under the cap; record each funded subscription; finalise; SUCCESS; No minimum set, or met; FAILURE; Minimum set, but missed.

The sale binds inventory and funding to one outcome: delivery after success, or refunds when an optional minimum is missed.

A minimum raise is optional. Setting one moves delivery to finalisation, and nothing finalises until someone calls it.

Activation locks the offering's commercial terms: prices, the hard cap, per-buyer limits, unlock schedules, presale terms and the terms hash. A sale administrator can still extend the end time, edit the presale whitelist, set per-investor allocations and pause the sale. The sale's contract code is not fixed: a holder of the system manager role can point the token-sale factory at new code, which changes every live sale of the system at once. The factory asks for no second approval and checks only that the new code reports the token sale and on-chain identity interfaces through ERC-165.

A failed offering lets each investor claim a refund in the currency they paid. The issuer cannot withdraw a refund still unclaimed, except a contribution made before the sale's contract carried the refund reserve, which is protected for thirty days only.

## What a primary offering is [#what-a-primary-offering-is]

A Primary Offering lets an issuer sell newly issued units once and get one on-chain outcome instead of several separate ones. A single contract takes each subscriber's payment, decides that buyer's allocation against the terms the issuer configured, and resolves the whole sale into delivered tokens or a refund.

[Asset Lifecycle](https://docs.settlemint.com/docs/concepts/issuing-and-markets/asset-lifecycle) places the cost of a tokenised instrument in the gaps between the systems around it, each a reconciliation the issuer has to run and defend. In a first sale, demand, payment, allocation, and delivery or refund usually live in separate systems: a subscription book, a payment rail, and a token-transfer step. Each handoff between them is a seam. A Primary Offering closes those gaps by making one contract responsible for all four steps. No separate records of promise, payment and receipt exist to reconcile afterwards.

The tokens enter investor hands for the first time, directly from issuer-controlled inventory, before any secondary trading. A hard cap limits the total amount available and per-buyer limits prevent one subscription from exceeding its permitted allocation. An optional minimum raise, the soft cap, adds a success condition. If the offering does not reach it, finalisation fails the offering and investors can reclaim their contributions. An offering runs in one of two modes. A first-come sale allocates each purchase at once. A book-built offering takes applications, closes the sale and then divides the units in an allocation run, with an optional greenshoe and lock-ups per investor category.

The platform runs the distribution mechanics: eligibility checks, accepted payment currencies, allocation records, token release, proceeds withdrawal, and refunds. The issuer remains responsible for the legal offering terms, investor disclosures, pricing decisions, and any obligations outside the platform.

## What you fix before the sale opens [#what-you-fix-before-the-sale-opens]

Before a Primary Offering can accept purchases, a sale administrator activates it. When the organisation's approval policy has the offerings family on, activation waits for an organisation owner other than the requester, and so do creating, ending and resuming the sale. Activation locks most of what you configured for the life of the sale. Before it, the offering is a draft you can rewrite. After it, the only route to a different term is to end this offering and run another.

| Term | Changeable after activation | What choosing wrong costs |
| --- | --- | --- |
| Minimum raise (soft cap) | No | It decides whether buyers hold tokens on the day they pay or wait for finalisation. A wrong value changes what every investor holds on the day they pay. |
| Vesting start, duration and cliff | No | Vesting cannot be added to a live sale, and it cannot be removed from one. |
| Presale window, price factor and per-address cap | No | The presale phase can be closed early, but its terms cannot be edited. |
| Terms document hash | No | The hash is set once during setup, from the uploaded terms documents. It cannot be replaced, so every subscription points to one version of the terms. |
| Payment currencies and their price ratios | No | You cannot add a currency for a buyer who asks after the sale opens. |
| Per-buyer minimum and maximum | No | The per-buyer maximum defaults to the hard cap, so leaving it unset means no per-buyer limit at all. |
| Subscription step | No | Every buyer's running total must land on a whole multiple of the step. A step that does not divide the per-buyer minimum is refused. |
| Hard cap, sale token and start time | No | These are set when the offering is created. |
| Sale end time | Extend only | The end time can only move later, and never past the vesting start. A sale administrator can still end the sale early at any moment, which closes the window at once. |
| Presale whitelist membership | Yes | Edits stop having any effect once the presale window closes, whether or not anyone closed it on purpose. |
| Per-investor allocation | Yes | A lower allocation stops further purchases by that investor, whichever wallet it buys with. It never takes back tokens the investor already bought. |
| Sale pause | Yes | A sale administrator pauses and resumes the sale. This is separate from the token's own pause, which the token's emergency role holds. |

Activation also requires the sale to already hold the full hard cap of the sale token. An offering cannot open on inventory you intend to mint later. One exception is a [book-built offering](#book-built-offerings-greenshoe-and-lock-ups) whose settlement mints the shares: it holds none of the offering, needs no funding, and activates once the sale holds the supply management role on the token. Such a sale is put in application mode before anyone funds it: once it holds any of the offering, the platform refuses the switch, because its settlement would issue those shares a second time.

That role lets its holder mint and burn the token. The sale's code uses it only to mint allocations at settlement, a system manager who repoints the token-sale factory can change that code, and the role stays with the sale until a token administrator revokes it.

[Figure] A minimum raise decides when the buyer holds the tokens. A purchase is accepted once it passes eligibility, the per-buyer limits and the hard cap, and the payment is taken at that moment either way. What happens next depends on one configured value. When no minimum raise is set, the tokens transfer to the buyer during the purchase itself, unless a vesting schedule holds them back, and finalisation always succeeds. When a minimum raise is set, nothing transfers during the purchase: every buyer waits until someone finalises the offering, success delivers the tokens, and a shortfall opens refunds instead. Nothing finalises on its own, so until someone calls it both the tokens and the proceeds wait. Labels: When the buyer holds the tokens; Purchase accepted, payment taken; checked against eligibility, limits and the hard cap; Is a minimum raise set?; no; yes; No minimum raise; Tokens transfer at purchase,; unless vesting holds them back.; Finalisation always succeeds.; Minimum raise set; Nothing transfers at purchase.; Every buyer waits for finalisation.; A shortfall opens refunds instead.; Nothing finalises on its own. Until someone calls it, the tokens and the proceeds both wait.

One configured value decides whether a buyer walks away holding tokens or holding a claim.

## Running the offering [#running-the-offering]

A Primary Offering has two stages: setup, then active. Setup is where you configure the sale token, inventory cap, dates, prices, accepted payment currencies, buyer limits, and the optional presale, minimum raise, subscription step, terms documents, and vesting. In the Console, create the sale first, upload its terms documents on the sale's "Marketing" tab, then use **Set terms**. Activation ends setup, and from then on purchases execute against that fixed configuration.

One offering can run two phases in sequence: an optional presale that admits only whitelisted buyers at a discounted price factor, then the public phase that admits any buyer who passes the token's eligibility rules. The phase does not turn over on a timer of its own. It turns over the next time anyone transacts with the sale after the presale window has passed, and a sale administrator can also open the public phase deliberately. Either way, once that window is behind you the whitelist no longer decides who may buy.

Each purchase takes payment in an accepted currency and records the buyer's token allocation. The sale rejects a purchase instead of partly filling it, and it names the reason:

- outside the time window, or not on the presale whitelist while the presale is running: wait for the applicable phase or request approval for the buyer's address.
- terms not acknowledged when the offering requires them: acknowledge the current terms hash and resubmit.
- a payment currency the offering does not accept, or an amount too small to buy a whole token unit: switch to an accepted currency, or raise the amount.
- a result below the buyer's stated minimum output, reported as [DALP-4300](https://docs.settlemint.com/docs/api-reference/errors): raise the payment or lower the minimum output and resubmit.
- a buyer the token's compliance rules do not admit, reported as [DALP-4045](https://docs.settlemint.com/docs/api-reference/errors): get the missing identity claim issued before retrying.
- a per-buyer, presale, or issuer-set per-investor allocation cap already reached, reported as [DALP-4227](https://docs.settlemint.com/docs/api-reference/errors), or the hard cap, reported as [DALP-4114](https://docs.settlemint.com/docs/api-reference/errors): reduce the amount to what the remaining capacity allows.
- a running total that would not be a whole multiple of the subscription step, which the platform API refuses before it sends the purchase, reported as [DALP-0686](https://docs.settlemint.com/docs/api-reference/errors): change the amount so the buyer's total lands on the step.

The per-buyer minimum binds only a buyer's first purchase. The subscription step has no such exception. It applies to the running total after every purchase, so a top-up must also keep the total on the step.

### Subscription step and per-investor allocations [#subscription-step-and-per-investor-allocations]

A subscription step makes every holding a whole multiple of a fixed lot, for example 1,000 units for an instrument that is only issued in that denomination. Without it, the per-buyer limits allow any amount between the minimum and the maximum. The step is a setup term: a sale administrator sets it during setup, in the creation wizard or with the sale's own setting, and it is fixed at activation. A step of zero switches the rule off.

A per-investor allocation reduces what one investor may take after the issuer has built its book, for example when demand from one institution exceeds what the issuer wants to place with it. The allocation belongs to the investor's identity instead of one wallet. Every wallet registered to that identity shares the allocation and the amount already bought, and a wallet that replaced a lost wallet through identity recovery keeps the lost wallet's allocation. A sale counts purchases per identity only from the point it adopted identity-keyed allocations, so earlier purchases do not count toward the allocation. The allocation applies on top of the per-buyer maximum and the hard cap, and the smallest limit wins.

Unlike the other limits, an allocation can change after activation. A sale administrator sets or clears it at any time, with no second approval, in the Console "Allocation caps" section of the offering or through the [token sale endpoints](https://docs.settlemint.com/docs/api-reference/v2). An allocation below the per-buyer minimum is refused, because the investor could then never make a first purchase. An allocation of zero removes the investor's cap.

## Finalisation, and what waits on it [#finalisation-and-what-waits-on-it]

After the window ends, someone has to finalise the offering. Nothing finalises an offering automatically and no deadline applies.

The sale contract accepts the call from anyone. Through the platform, a sale administrator or funds manager sends it, and the Console offers Finalize offering to either role. When the Offerings row under Approvals in the organisation settings is on, finalisation is a [maker-checker](https://docs.settlemint.com/docs/concepts/custody-and-signing/maker-checker) step: the platform sends it only after an organisation owner other than the requester approves. An organisation whose only owner is the requester cannot finalise through the platform while the row is on, because the request is refused when it is made. The approval governs the platform's call only, so it cannot stop a wallet outside the platform from finalising. Finalisation needs the window closed first, either because the end time has passed or because a sale administrator ended the sale early. It then records one outcome: success when no minimum raise was configured or when the raise was met, failure otherwise.

An offering that was never activated cannot finalise: the call is refused with [DALP-4279](https://docs.settlemint.com/docs/api-reference/errors). Its inventory is not lost. A sale administrator ends the sale from setup, then withdraws the unsold tokens, which in that case are all of them. Both steps go through the Platform API, because the Console offers End only while the sale is running or paused, and the withdrawal only once the sale is finalised.

Until that call lands, the issuer cannot withdraw proceeds, whether or not a minimum raise is configured. On an offering with a minimum raise, buyers cannot withdraw their tokens either. The Console flags the state as awaiting finalisation once the window has passed and finalisation has not run.

After a successful finalisation the funds manager can withdraw proceeds to an address the funds manager names in the call, and buyers can take their tokens, subject to any vesting schedule. Unsold inventory comes back through its own withdrawal, which the sale administrator calls. The contract allows it after finalisation, or earlier when a sale administrator ended the sale with an explicit end. When the end time passes with no explicit end, the offering still needs finalisation first, and the Console offers the withdrawal only after finalisation. After a success, tokens that buyers bought and have not withdrawn stay in the sale. After a failure, every token counts as unsold.

Through the Platform API, withdrawing proceeds or unsold inventory and starting an undeliverable-purchase refund require a Console-issued session. A Portal-issued session, an anonymous session or a session with no recorded issuing app answers `403 Forbidden` with `WALLET_ROLE_ADMINISTRATION_NEEDS_CONSOLE_SIGN_IN` ([DALP-200384](https://docs.settlemint.com/docs/api-reference/errors)), before any withdrawal or refund starts. Sign in to the Console and retry. API keys keep the route's existing access policy. Investor purchases, token claims and refunds of their own purchases do not require a Console session.

An investor with several ended offerings to settle can settle them in one call, `POST /api/v2/addons/token-sales/investment-settlements`, naming up to 20 sales. It asks for the wallet verification once. For each sale it then withdraws the tokens a successful sale owes now, or claims a refund for each currency a failed sale still holds. Each claim or refund is its own transaction, and one that fails does not stop the others. The answer lists one result per claim or refund. A sale that owes the acting wallet nothing comes back skipped, so an investor with several custody accounts settles each account in its own call. A browser wallet cannot settle several sales in one call. It signs each claim or refund through the sale's own routes.

## When the raise falls short [#when-the-raise-falls-short]

When an offering fails, the sale refunds what investors paid. With a minimum raise configured, no tokens have left the sale.

Each investor claims their own refund, in the exact currency they paid, and once per currency they used. An investor who funded in two currencies makes two claims. The accepted currency list is fixed at activation. Refunds use each buyer's recorded contributions.

For thirty days after the offering fails, the issuer cannot withdraw anything: the attempt is refused while the refund grace period is running ([DALP-4270](https://docs.settlemint.com/docs/api-reference/errors)). After that grace period ends, the issuer may withdraw only the balance beyond the refunds that investors have not claimed. A refund claim has no deadline, so an unclaimed refund stays in the offering until its investor claims it. One exception: a contribution taken before the offering's contract was upgraded to this reserve is protected only by the grace period. Tell investors that a refund is a claim they must make.

## How funding becomes an allocation [#how-funding-becomes-an-allocation]

Each Primary Offering is an isolated contract bound to one sale token. It holds issuer inventory and buyer payments until the lifecycle opens the correct withdrawal path. Its configuration, phase, balances, and settlement outcome stay separate from every other sale, even when the same issuer runs several offerings.

At purchase time, the contract converts the payment amount through that currency's configured price ratio and the sale token's precision. It checks the active phase, time window, buyer identity and token compliance, terms acceptance when configured, buyer limits, remaining hard-cap capacity, and the buyer's minimum token output. Only then does it increase the buyer's purchase record and contribution record.

Allocation and delivery can occur at different times, and two independent settings separate them. A minimum raise defers delivery until successful finalisation so a failed raise can refund cleanly. Vesting records the allocation at purchase and releases only the portion the schedule allows. Vesting accrues from the vesting start instead of from the end of the cliff, so at the moment the cliff ends, everything that accrued during it becomes claimable at once.

The outcome is terminal: no path returns a succeeded or failed offering to a live phase.

## Book-built offerings: greenshoe and lock-ups [#book-built-offerings-greenshoe-and-lock-ups]

A sale in application mode is a book-built offering. Investors do not buy tokens at once. Each investor applies with a payment that the sale holds in escrow, the sale closes, and an allocation run divides the offering between the applicants pro rata when demand exceeds it. The settlement then mints each allocation to its investor, pays the issuer's recipient for the shares allocated and refunds the rest. Two optional terms, set while the sale is in setup, shape that outcome: a greenshoe and a lock-up per investor category.

### The allocation run, its approval and the reclaim [#the-allocation-run-its-approval-and-the-reclaim]

After the sale ends, the sale admin requests one allocation run and names the recipient of the payment. The run allocates as sale admin and settles as funds manager, so the signing wallet needs both roles. The preview lists every applicant with demand, allocation and refund, plus the unissued leftover from rounding down and the total kept per currency, and fixes them with the book hash. A request that names an older hash is refused. Once settling starts the recipient is bound, and a run that names another recipient is refused.

When the offerings family of the organisation's approval policy is on, the run waits for a second approver, an organisation owner other than the requester. The approval binds the platform's request only: a wallet that holds the two roles the run signs with can allocate and settle on chain directly, without it. The request is open for seven days, and on approval the run recomputes from the chain and stops if the book moved since the request. A request in an organisation whose only owner is the requester is refused when it is made. When the family is off, the run starts on the request.

If the allocated book does not reach the soft cap, finalisation fails the offering. Nothing is allocated and every applicant is refunded in full. Investors never claim after a run, because the tokens and the refund arrive together in the settlement.

If the sale admin does not start the run within 30 days after the sale ended, each application reads Reclaim due. No run can start after that, and every applicant takes the whole escrow back in every currency they paid in, with one wallet verification. A reclaim ends a running or paused sale, so it cannot be extended afterwards.

### The greenshoe [#the-greenshoe]

A greenshoe lets the offering grow above its hard cap at the offer price when demand allows. The sale admin sets its maximum as basis points of the hard cap and chooses who decides how much of it is used. The sale stores that maximum and adds at most the hard cap times it, rounded down to whole tokens. On a token with a supply cap, it adds no more than the room the cap leaves above the current supply and the hard cap. The most a sale can store is 65,535 basis points. Zero removes it.

| Exercise | Who decides | When the amount is fixed |
| --- | --- | --- |
| `automatic` | The platform | When the allocation starts: the demand above the hard cap, up to the capacity. |
| `discretionary` | The sale admin, once, through the greenshoe exercise endpoint | After the application window closes and before the allocation starts. |

A discretionary exercise is a whole number of tokens, at most the capacity, the demand above the hard cap and, on a capped token, the room left under the supply cap. Without an exercise the offering stays at the hard cap. The exercised amount is part of the book that the approver of the allocation run reviews, so an exercise changes the book hash and a run requested before it must be requested again.

The over-allotted shares are new shares. The settlement mints them like the rest of the allocation, so the sale needs the supply management role on the token, and the issuer is paid for them in the same run. The allocation divides the hard cap plus the exercised greenshoe, with the same pro rata rule and rounding as a plain oversubscribed offering, so tokens sold can exceed the hard cap by the exercised amount. A first-come sale takes no greenshoe: it has no point at which demand above the offering is known, so it sets a larger hard cap instead. A sale reads its greenshoe and its application book through the application-mode endpoint, where `offeringExact` is the hard cap plus the greenshoe and `greenshoeExact` is the part the greenshoe adds.

Both terms need a sale whose contract carries them: the greenshoe needs the fifth sale implementation, and the lock-up schedule, even a single step, needs the sixth. A sale runs the sale implementation its system's token-sale factory points at, so while that factory points at an earlier implementation, its sales have no greenshoe and no lock-up to set: the write is refused with [DALP-200382](https://docs.settlemint.com/docs/api-reference/errors) and no transaction is sent. A holder of the system manager role, or the add-on registry, points the factory at an implementation, and the factory checks only that the new code reports two interfaces through ERC-165: the token sale interface and the interface of a contract with its own on-chain identity. Because each sale reads its implementation from the factory on every call, that change applies to every sale of the system at once, live sales included, and neither a sale administrator nor a second system manager approves it.

### Lock-ups per investor category [#lock-ups-per-investor-category]

A lock-up keeps an allocation from moving, in steps, after delivery. The sale admin sets up to eight categories, each a claim topic on the investor's identity such as `qualifiedInstitutionalInvestor` with an unlock schedule, and a default schedule for investors in no category. For each applicant the settlement checks the categories in the order given. The first category whose claim topic the investor's wallet is verified for sets the schedule, so list the strictest schedule first.

A schedule has up to four unlock steps. Each step is a share of the allocation in basis points and a wait from the first delivery of the settlement in seconds. The shares of one schedule add up to 10,000, each step unlocks after the one before it, and a wait is at most 1,826 days. A step whose wait is zero and whose share is the whole allocation locks nothing, and so does a schedule with no steps. One step that releases the whole allocation is a plain lock-up duration.

| Category schedule | Meaning |
| --- | --- |
| One step, 180 days, 10,000 bps | Everything unlocks 180 days after the first delivery. |
| Two steps: 90 days at 4,000 bps, 180 days at 6,000 bps | 40% unlocks at 90 days, the remaining 60% at 180 days. |
| No steps | The category's investors keep no lock. |

The lock is written in the token's lock-up compliance rule, in the same transaction that mints the allocation, so no ordinary transfer can move the shares unlocked. A forced transfer by the token's custodian role skips compliance rules, the lock-up rule included. A one-step schedule writes the rule's single holder lock. A multi-step schedule writes one tranche per step that is still locked when the allocation is delivered. Every schedule runs from the first delivery of the settlement, so all investors of one category unlock each step at the same moment. Until a step unlocks, the rule refuses any transfer that would leave the sending wallet with less than the share still locked, so the unlocked share can move. The shares still pay dividends and carry votes.

An investor who already holds an active single lock keeps it: the amounts add up and the later unlock time applies. Vesting tranches are added beside a single lock without moving its unlock time. A step whose unlock would already have passed writes no tranche.

A sale with lock-ups needs two things on its token before it activates: an active lock-up rule, and the governance role for the sale's address, which the rule requires to write a holder lock. The governance role lets its holder change the token's compliance, identity registry and features. The sale's code uses it only to write holder locks on its own token's lock-up rule, and a system manager who repoints the token-sale factory can change that code. A schedule with more than one step also needs a rule that stores unlock steps. Without the rule the activation is refused with [DALP-4526](https://docs.settlemint.com/docs/api-reference/errors), without the role with [DALP-4527](https://docs.settlemint.com/docs/api-reference/errors), and a multi-step schedule on a rule that stores one lock with [DALP-4529](https://docs.settlemint.com/docs/api-reference/errors). A schedule whose shares do not add up to 10,000, or whose steps do not unlock in order, is refused with [DALP-4528](https://docs.settlemint.com/docs/api-reference/errors). A settlement batch also stops when the rule is removed or turned off after activation. It stops with [DALP-4530](https://docs.settlemint.com/docs/api-reference/errors) when the delivery would pass the eight unlock steps one holder identity stores on a token. No allocation is delivered unlocked.

Read each applicant's result in the `lockup` field of the application: the locked amount across every step, the unlock time of the last step, the claim topic of the category, which is null for the default schedule, and `tranches`, one entry per step with its amount and unlock time.

## The cap table: who bought in [#the-cap-table-who-bought-in]

Every offering has a view of its investors for its sale administrators and funds managers, the cap table. It lists each buyer's activity in that sale, one row per payment currency the buyer used, with nothing brought in from before or after that sale. A secondary market trade never earns a row, because a transfer is not a purchase. The platform's general holder view, which tracks every wallet holding the token, answers that broader question instead.

If you know "cap table" as the record of who owns a company or an instrument across its whole history, DALP's feature under that name answers a narrower one. It is built only from this one sale's purchase records, so a buyer's stake in a different sale of the same token, or a transfer received afterward, never shows up here.

### What a row represents [#what-a-row-represents]

Each row aggregates one buyer's purchases in a single payment currency. It lists the buyer's wallet, its resolved name when the registry has one, KYC status, country, how many purchases the buyer made in that currency, the total committed, and the total allocation. A buyer who paid in two currencies gets two rows, one per currency, sorted by total allocation and tie-broken on the currency address so the two sit next to each other instead of merging. When a sale holds tokens for a buyer, the row also says whether the token refuses to deliver them to the buyer's wallet (`undeliverable`) and whether they can go to the wallet that replaced a lost one through identity recovery (`recoveredWalletDeliverable`). The Console shows both as a delivery state and offers the matching action to the funds manager, such as refunding an undeliverable purchase.

`investorCount` counts distinct buyers, so it can run smaller than the number of rows. A row's `purchaseCount` counts only that buyer's purchases in that one currency, not their purchases across the whole sale.

### The cap table is rebuilt on every request [#the-cap-table-is-rebuilt-on-every-request]

Each request rebuilds a cap table. The platform aggregates the sale's recorded purchases by buyer and currency, looks up each buyer's identity for KYC status, name, and country, and returns the combined rows.

Because of that, the same request can answer differently between two reads. A buyer's KYC status can move from pending to registered, and a purchase that settles after your first read appears on the second. If you need a point-in-time record, such as for an audit, export the cap table at that moment.

### KYC badges [#kyc-badges]

Each row's badge reads one of three values.

| Badge | What it means |
| --- | --- |
| Registered | An identity record was found with an active status. |
| Pending | The record exists but has not cleared. |
| Unknown | The registry holds no record at all for that wallet, which means the registry has never seen the wallet. |

### Who can read a cap table [#who-can-read-a-cap-table]

[Figure] Two surfaces reach the cap table, and only one is checked. Four roles share one access manager. All four can open the cap table tab in the Console, but opening the tab checks nothing on its own. The API checks again on every request and returns data to only two of the four roles, sale admin or funds manager. A visible Console tab is never proof that the same request will succeed against the API. Labels: Who reaches the cap table; Administrator; Token manager; Offering admin; Funds manager; One access manager, four granted roles; the same manager checks every request; Which surface is the caller using?; console; api; Console tab; All four roles can open it.; Opening it checks nothing else.; It is not proof of API access.; API request; Every caller is checked again.; Only sale admin or funds manager; pass. The other two are denied.; A visible Console tab is never proof the API request behind it will succeed.

Four roles can open the cap table tab, and only the sale admin and funds manager roles can read the table.

Every field in a cap table row is investor data, and the platform checks access at the API, before any of it leaves the server, not only at the Console's tab. The server resolves the caller's own wallets against the sale token's access manager and checks for exactly two roles there: sale admin or funds manager. A caller with neither role gets no data and receives [DALP-0006](https://docs.settlemint.com/docs/api-reference/errors), an authorisation error with HTTP status 403 that says the acting wallet lacks a role the action requires.

Administrator and token manager open the Console tab but are not among the two roles the server accepts, so a caller who reaches the tab through one of those two alone is still denied at the API. A visible tab is never proof that the request behind it will succeed.

### Integrating with the endpoint [#integrating-with-the-endpoint]

For integrations, the [cap table endpoint](https://docs.settlemint.com/docs/api-reference/v2) returns one row per buyer-currency pair instead of one row per buyer, alongside the sale's own totals. The endpoint reference lists the exact fields and types. The token address in that response can come back empty for a token the tenant has yet to index. Each amount in a row, such as the payment committed or the tokens allocated, comes as a pair: a display decimal string and a raw exact integer string. Sum the exact values in your own calculations, never the decimal strings, to avoid rounding.

## The integration contract [#the-integration-contract]

A Primary Offering API follows the business lifecycle. You create and configure the sale before activation, submit purchases while it is active, then end and finalise it to resolve the offering's outcome. Token delivery can occur at purchase when no minimum raise or vesting condition defers it. The indexed sale record gives integrations the effective phase, totals, currencies, limits, and each investor's position.

A submitted operation is a request. [Asset Lifecycle](https://docs.settlemint.com/docs/concepts/issuing-and-markets/asset-lifecycle) documents the idempotency contract every servicing call on the platform shares: one key per business instruction, and the terminal Settlement Verdict as the signal to trust. For a purchase, also check that the amount appears in the buyer's purchased amount and per-currency contribution record before another system reports the subscription as settled.

Amounts use integer token units. Payment conversion depends on the configured currency ratio and on the decimal precision of both the payment currency and the sale token. A purchase also carries a minimum token amount. Because the token amount comes out of that currency ratio and precision conversion, the minimum protects the caller from accepting a lower allocation than expected. Preserve the payment currency beside each contribution because refunds and proceeds withdrawals use the recorded currency instead of one aggregate cash balance.

The creation request carries the sale's commercial terms: payment currencies and prices, the hard cap, purchase limits, the minimum raise, vesting, and the presale discount and per-address cap. No later operation changes them. After creation, a sale administrator can still set the terms hash, the subscription step and, for a book-built offering, the book-building mode, the greenshoe and the lock-ups. The contract accepts each of these only while the offering is still in setup. Check the offering's phase before you send one. The per-investor allocation, the presale whitelist, and an end-time extension stay available after activation.

### Sale events [#sale-events]

Each step of a sale reaches your systems as a webhook event, sent once the block that holds it is final. The lifecycle events are sale activated, sale extended, sale closed, and sale finalised, which reports the success or failure outcome. Money and token movements arrive as subscription, delivery, refund, and proceeds withdrawn events. A book-built offering sends none of its application, greenshoe, lock-up, allocation or reclaim steps as a webhook, so read them through the applications and allocation-run reads. The [primary market event catalogue](https://docs.settlemint.com/docs/api-reference/webhooks/market-events#primary-market) explains when each event is sent and what your receiver does with it.

Do not wait for a closed event to learn that a sale is over. A sale that reaches its end time without an explicit end sends none, and its outcome arrives with the finalised event. Pausing, resuming, and an early move to the public phase send no lifecycle event.

## Controls and evidence [#controls-and-evidence]

When you review a Primary Offering, start with the controls enforced when each subscription executes. The buyer must have a registered identity and must satisfy the sale token's configured compliance rules. A presale phase adds a whitelist gate that limits who may buy, and that gate stops applying when the presale window closes. Separately, minimum, maximum, presale, and total caps limit how much any buyer can be allocated.

The issuer binds the terms documents to the offering. The issuer uploads them as `terms` documents on the sale. Through the platform, the terms hash is derived from the uploaded files and a caller cannot send one of its own. The contract itself accepts any hash from a sale administrator during setup, so check that the recorded hash matches the published documents. The issuer then records that hash on the sale contract once during setup. The contract refuses a second hash and refuses acknowledgement until a hash exists. The platform also refuses a purchase while uploaded terms documents have no recorded hash. Each buyer must acknowledge the hash on chain before purchase, and a purchase without that acknowledgement reverts. Acknowledgement is stored against the buyer's address, and the hash it points to never changes. Retain the acknowledgement event's hash when you check consent. For the call sequence, read [Sale terms and acknowledgement](https://docs.settlemint.com/docs/api-reference/guides/sale-terms-and-acknowledgement).

The sale contract records its configuration, phase transitions, purchases, buyer allocations, contributions by payment currency, outcome, token withdrawals, proceeds withdrawals, and refunds. That record proves what the on-chain mechanism accepted and paid. It does not prove that disclosures were adequate or that an investor met obligations outside the configured identity and token rules.

Offerings belong to the Primary market licensed module, which the deployment switches on with `features.tokenSale` in the [Helm values](https://docs.settlemint.com/docs/deployment/install/values-secrets). An organisation can opt out of it in Organisation settings. Its offerings then stay readable in the Console and the Investor portal, both apps hide their write controls under a read-only banner, and every write route refuses with `403` and `platform.module.DISABLED` ([DALP-20531](https://docs.settlemint.com/docs/api-reference/errors)), investors' own purchases, token withdrawals and refund claims included. Switch the module back on to resume. The switch closes the platform's routes only. The sale contracts still accept calls sent to them directly, so pause or end a sale on chain to stop it.

## Frequently asked questions [#frequently-asked-questions]

### What does pausing a sale stop?

Pausing blocks two things: new purchases, and token withdrawals for buyers who already qualify to receive them. It does not touch refund claims, proceeds withdrawal, or extending the sale end time, all of which keep working while paused. A sale administrator pauses and resumes the sale, and a pause has no time limit. Unpausing restores whichever phase the sale was in before the pause, and finalising an offering lifts a pause automatically, so nobody stays locked out once the sale ends.

### Is there a limit to how many payment currencies a sale can accept?

Yes, ten at once. The contract rejects an eleventh currency on chain. The creation request sets the currencies and the platform offers no route to change them afterwards. The contract counts accepted currencies, so removing one during setup would free its slot, and only a direct contract call does that.

### What happens to excess or unsuccessful demand?

A purchase that would exceed the remaining hard cap, a per-buyer limit, or the presale cap is refused instead of partly filled. The caps themselves never produce a smaller-than-requested allocation, though the ratio and precision conversion still can, which is what the buyer's minimum output guards against. Unsuccessful demand is different: if the offering later misses its configured minimum raise, every already-accepted contribution becomes refundable, one claim per currency the buyer used, and the issuer cannot withdraw it while it stays unclaimed.

### Nobody finalised our offering and the window closed weeks ago. Is it lost?

No. Finalisation has no deadline, and anyone, not only the issuer or an administrator, can trigger it. An offering that sits unfinalised for weeks is waiting. The outcome it records depends only on whether the raise cleared its minimum when the window closed. Proceeds and refunds become available the moment finalisation runs. Token delivery under vesting keeps accruing from the vesting start throughout the delay, so a late finalisation does not shrink the buyer's claimable amount.

### Can the vesting start date fall before the sale ends?

No. The vesting start must be at or after the sale end time. Set a vesting start earlier than that and the call reverts instead of clamping to a valid date.

### Can an offering sell more than its hard cap?

Yes, in application mode with a greenshoe. The sale admin sets how much of the hard cap the greenshoe may add. The sale adds at most that share, in whole tokens, and only as far as demand exceeds the hard cap. The allocation then divides the hard cap plus the exercised amount. A first-come sale cannot exceed its hard cap.

### Can different investors of one offering have different lock-ups?

Yes, on a book-built offering. One category can release 40% at three months and 60% at six, while another releases everything at six. [Lock-ups per investor category](#lock-ups-per-investor-category) shows how a schedule is chosen and what it needs.

## Related concepts [#related-concepts]

- [Asset Lifecycle](https://docs.settlemint.com/docs/concepts/issuing-and-markets/asset-lifecycle): The whole working life of a regulated tokenised instrument, from issuance through servicing to final redemption.
- [Corporate Action](https://docs.settlemint.com/docs/concepts/issuing-and-markets/corporate-action): A named lifecycle event on an already-issued security, such as a dividend or a coupon, run against existing holders instead of investors in a sale.
- [Token Distribution](https://docs.settlemint.com/docs/concepts/issuing-and-markets/token-distribution): The platform's other route for putting a token in a holder's hands, distributed under a Merkle root instead of sold to investors.
- [Fund dealing](https://docs.settlemint.com/docs/concepts/issuing-and-markets/fund-dealing): The subscriptions and redemptions an open fund takes after launch, settled each dealing day at one published net asset value.
- [Trading Venue](https://docs.settlemint.com/docs/concepts/issuing-and-markets/trading-venue): The permissioned secondary market where eligible participants trade token pairs after primary distribution.
- [Settlement Verdict](https://docs.settlemint.com/docs/concepts/settlement/settlement-verdict): The recorded end state of an on-chain operation submitted to the platform, and the only signal from which success may be reported.


# Token Distribution

Source: https://docs.settlemint.com/docs/concepts/issuing-and-markets/token-distribution
Token Distribution, the airdrop of the API and contracts, commits an allocation list under one Merkle root and pays it out by push, claim or vesting.



[Figure] One shared base, three distinct claim contracts. Every token distribution verifies eligibility against the same fixed Merkle root and shares one timelocked withdrawal, which never takes tokens that claims can still reach. Below that shared base, three separate contract families diverge. A push distribution has the sender distribute tokens directly, with no claim step, and calling claim always reverts. A time-bound distribution lets each recipient claim their full allocation once, self-service, inside a fixed start and end window. A vesting distribution has the recipient initialise their allocation before a deadline, then claim repeatedly as the strategy pinned at that initialisation unlocks more. Labels: Shared base, every family; Merkle-root eligibility; one fixed root checks every claim,; distribution, and initialisation; Timelocked withdrawal; never takes tokens that; claims can still reach; Push; The sender distributes; and recipients do nothing.; distribute is owner-only.; There is no claim step,; and claim always reverts; Time-bound; Each recipient claims; once, self-service.; claim works only inside; the fixed start and end; window, full amount; Vesting; Initialise once, then; claim as more unlocks.; initialise before the; deadline. Claims follow; the pinned strategy.

Every token distribution shares one Merkle-root eligibility check and one timelocked withdrawal path, which never takes tokens that claims can still reach.

Token Distribution commits an allocation list of any size under one Merkle root, so publishing the list costs the same for ten recipients or ten thousand. Delivery costs gas: the sender pays for each push batch of up to 100 recipients, and each recipient pays for their own claim unless a relayer submits it. Every claim checks against that root instead of a stored per-address list.

In all three families, an owner withdrawal never takes tokens that claims can still reach. It runs seven days after scheduling at the earliest, and never before a time-bound distribution's claim window has ended or a vesting distribution's initialisation deadline has passed. A vesting distribution keeps the unclaimed part of every initialised allocation for its recipient. A push withdrawal takes the whole balance, including the tokens of indexes the owner has not distributed.

A push distribution moves tokens the moment the sender distributes them, with no claim step for the recipient. A time-bound distribution flips that: each recipient claims their own full allocation once, self-service, only inside a fixed start and end window. A vesting distribution initialises first, then pays claim after claim as the strategy pinned at that initialisation unlocks more.

## Why put an allocation in many hands without running a sale [#why-put-an-allocation-in-many-hands-without-running-a-sale]

After a token is issued, an issuer often needs to put units into many wallets at once. That covers rewarding the holders who already stayed, seeding a launch's early community, or paying out the allocations a subscription round already promised. Doing that as a sequence of individual transfers means paying gas for every one, keeping a private list of who has been paid, and reconciling that list against what the chain moved.

Token distribution replaces that running record of who has been paid with one published Merkle root: a single committed value that fixes the whole recipient set and every allocation when the contract deploys. Publishing it costs the same whether the list names ten recipients or ten thousand, because the contract never stores the list itself, only the root a caller's proof is checked against. Each distribution transfer runs as an ordinary movement through that same instrument's transfer path, the one issuance and every other servicing operation already write to. The operator still keeps the recipient list, because the tree and every recipient's proof are built from it by the operator's own integration. That list is the input to the root. A private, off-platform record of who has been paid is the second ledger that can drift from the one the chain settled.

## Why a distribution uses the token's own compliance path [#why-a-distribution-uses-the-tokens-own-compliance-path]

The transfer a distribution pays out runs through the underlying token's own transfer-compliance modules, the same modules that check every other transfer on that token. [Controls and evidence](#controls-and-evidence) describes them. A payout system built beside the platform would need its own view of who may hold the token, a second copy of the eligibility rules the token's compliance modules already enforce. If the two views differ, a distribution could pay a wallet the token's own rules would refuse.

Nothing here needs a separate custodian or a second wallet holding funds in transit. In every family the distribution contract holds the tokens, funded in advance, and pays out from its own balance. That balance remains subject to the token's custodian role, which can force-transfer it out of the distribution contract.

## What Token Distribution is, and how the three families differ [#what-token-distribution-is-and-how-the-three-families-differ]

Markets call a token distribution an airdrop, and the platform's contract families and API identifiers keep that word. A distribution is created, funded, paid out and claimed with direct contract calls. The platform installs the distribution factories and shows the distributions in the Console and the Platform API. What differs from one family to the next is who pays gas, and when the reward reaches a recipient's wallet.

A push distribution puts every transfer on the sender. The issuer calls `distribute` or `batchDistribute`, and tokens land in each wallet unasked. Reach for it when a reward must land on a fixed date, and the issuer is willing to cover every transfer's gas.

A time-bound distribution makes each recipient pay and act. Each recipient calls `claim` themselves, once, inside a start and end window the issuer sets. The recipient pays the gas, the network fee for the transaction, unless a relayer submits the call through the trusted forwarder that the distribution implementation names for every distribution of its type. A recipient list of any size costs the issuer the same amount to publish, because eligibility rests on a Merkle proof instead of a stored per-address list. Reach for it when recipients can cover their own gas and should self-serve inside a window you set. The issuer then does not push every transfer out one by one.

A vesting distribution spreads the reward's economic effect out over time, discouraging an immediate sell-off. A recipient first initialises their allocation, which starts a vesting clock but moves no tokens, then claims repeatedly as more of the allocation unlocks under a pluggable strategy, such as a linear schedule with a cliff. No separate lock-up contract is needed for any single recipient. The distribution itself carries the schedule.

Every family shares one recovery path: the owner schedules a withdrawal, then waits at least seven days. On a time-bound or vesting distribution, the wait also lasts until the claim window has ended or the initialisation deadline has passed. The owner cannot shorten that wait. The withdrawal then sends only the tokens no claim can still reach, and the token's transfer rules still apply to it. The withdrawal rule binds the owner only. The token's custodian role can force-transfer the distribution's balance at once, and the system manager role can replace the code of every distribution of a factory, the withdrawal rule included.

## Running a distribution day to day [#running-a-distribution-day-to-day]

Token distribution's three families divide the day-to-day operating work differently. Push distribution is owner-driven: only the contract owner can call `distribute` or `batchDistribute`, and that owner can be an automation's wallet. The owner is a single address the deployer names when the distribution is created. It needs no role on the token, and it can transfer or renounce ownership at any time. The owner alone distributes, sets the cap and schedules withdrawals. On a vesting distribution, the owner also changes the vesting strategy for later initialisations. Tokens reach each recipient without the recipient acting. Time-bound and vesting distributions are self-service, so the operator's job narrows to choices at deployment, then monitoring. A time-bound distribution needs a claim window. A vesting distribution needs an initialisation deadline and a vesting strategy.

Each recipient on a self-service distribution calls `claim` or `batchClaim` themselves. The operator never moves a token on their behalf.

A push distribution enforces two limits on chain. It cannot double-pay the same Merkle index, and it cannot exceed a distribution cap when one is set. A cap of zero means uncapped on chain, and the Platform API reports no cap as `distributionCap: null`. Both checks run inside `distribute` itself, so a batch that would violate either one fails before any tokens move. The owner can raise or lower the cap later. The change takes effect at once, with no timelock, and each distribution is checked against the running total at that moment.

A vesting distribution has an operator-visible step that push and time-bound skip: initialisation. A recipient's index moves through three states worth tracking separately: uninitialised, initialised and vesting, and fully claimed. An uninitialised index cannot be claimed at all, no matter how much time has passed, and initialisation itself stops working once the distribution's own initialisation deadline passes. Track which recipients have initialised separately from which have claimed, since initialising moves no tokens and is not itself a transfer. Only the recipient can initialise, because the leaf is verified against the caller's own address, so a recipient who misses the deadline cannot be initialised by the operator.

[Figure] A vesting claim's three-state lifecycle. Before initialisation, an index is outside the vesting clock and a claim reverts. Initialising proves the Merkle allocation, pins the vesting strategy active at that moment, and starts the clock, without moving any tokens. Once initialised, claiming is repeatable: each call moves only the newly unlocked amount. When the cumulative claimed amount reaches the total allocation, the index is fully claimed and nothing more unlocks for it. Labels: Awaiting initialisation; claim reverts. This index is not in the vesting clock yet; initializeVesting proves the Merkle allocation, pins the strategy; active at that moment, and starts the clock. No tokens move; Initialised, vesting; claim pays whatever the pinned strategy says has unlocked so far; repeatable: each claim moves only the newly unlocked amount; the cumulative claimed amount; reaches the total allocation; Fully claimed; the tracker marks the index claimed. Nothing more unlocks.

A vesting index moves through one initialisation, any number of claims, then a fully claimed state, while push and time-bound skip initialisation.

Withdrawing the tokens no claim can still reach is the one lifecycle step every family shares, and it is deliberately two steps. The owner calls `scheduleWithdrawal`, and the contract records the withdrawal's eligible time: seven days after scheduling, or the moment claims close when that comes later. A time-bound distribution's claims close when its claim window ends. A vesting distribution's claims close to new allocations when its initialisation deadline passes. Recipients of allocations initialised by then keep claiming, from tokens the withdrawal leaves in place. A push distribution has no claims, so only the seven days apply.

The owner cannot bring the eligible time forward, and `executeWithdrawal` refuses before it with [DALP-4353](https://docs.settlemint.com/docs/api-reference/errors/error-code-reference/dalp-4300-4399). The owner can cancel the schedule at any point before execution, and scheduling again sets a new eligible time by the same rule, with the seven days counted from the new schedule. Only one withdrawal can be pending at a time, and no direct, one-call withdrawal exists: the older `withdrawTokens` call always refuses.

[Figure] A withdrawal takes a schedule, a wait until claims close, then execution. The owner schedules a withdrawal, and the contract records an eligible time that anyone can read on chain. The wait lasts at least seven days and until claims close, and the owner cannot shorten it. Execution then moves the tokens no claim can still reach to the address the owner names. The owner can cancel at any time before execution, and a new schedule starts the wait over. Labels: Scheduled; the contract records; an eligible time that; anyone can read; Waiting period; at least seven days,; and until claims; close; Executed; tokens no claim can; reach move to the; address the owner names; the owner cannot shorten the wait, and can cancel before execution. A new schedule starts the wait over.

Recovery waits at least seven days and until claims close, then takes only what no claim can still reach.

A cancelled schedule starts over instead of resuming.

| Family | Eligible time | What the withdrawal sends |
| --- | --- | --- |
| Push | Seven days after scheduling, because recipients cannot claim | The whole balance of the distributed token, including the tokens of every index the owner has not distributed |
| Time-bound | Seven days after scheduling, or one second after the end time when that is later, because a claim at the end time still succeeds | The whole balance, because no claim can follow the window |
| Vesting | Seven days after scheduling, or one second after the initialisation deadline when that is later, because an initialisation at the deadline still succeeds | On a distribution created with withdrawal reserves, the balance less the unclaimed part of every initialised allocation. On a fully funded distribution, that is the allocations nobody initialised in time, plus any tokens sent beyond the allocations |

_When a withdrawal becomes eligible, and what it sends, in each family_.

A vesting withdrawal leaves the unclaimed part of every initialised allocation in the contract: its total less what its recipient has claimed so far. Those recipients keep claiming after the withdrawal as their allocations vest. An initialised allocation that its recipient never claims stays in the contract, because no withdrawal can take it. Only a forced transfer by the token's custodian role moves it out.

A vesting distribution created before withdrawal reserves were introduced keeps its whole balance reserved after its factory moves to the new implementation. Recipients can still claim, but owner recovery sends zero, even after all claims finish: the contract cannot reconstruct the older allocations from its records.

When nothing is spare, because every token in the contract still backs an open claim, `executeWithdrawal` sends nothing, still clears the schedule, and emits `TokensWithdrawn` with an amount of zero. The event's amount is always what the withdrawal sent.

`withdrawalSchedule()` returns whether a withdrawal is pending and its eligible time, and the `WithdrawalScheduled` event carries the scheduling time and the eligible time. The Platform API reports the eligible time as `withdrawalEligibleAt`, and the Console's airdrop detail screen shows it as "Recovery available".

Watch a push distribution's cap and per-index state for failed batches as well as completed ones: one invalid item, including a recipient the token's compliance rules refuse, reverts the whole batch. A time-bound distribution needs its window watched, since a claim outside the start and end time fails outright and does not queue. The window is set when the distribution deploys and has no setter, so extending one means deploying a new distribution. A vesting distribution needs its initialisation deadline tracked separately from its claims, since a recipient who never initialises in time never enters the vesting clock at all.

## One base contract, three claim implementations [#one-base-contract-three-claim-implementations]

One abstract base contract underlies all three token distribution families and owns exactly two things: Merkle-root eligibility and the timelocked withdrawal. Each family defines two values for that withdrawal: when its claims close, and how much its recipients can still claim. One withdrawal rule then serves all three. The root has no setter, so a changed eligibility list needs a new distribution contract. Each distribution runs the code its factory points to on every call, so a system manager who repoints the factory changes that code for every distribution of that type at once.

Everything about claiming diverges below that shared base. Each family plugs in its own claim-tracking behaviour, and the tracker type is what distinguishes a push claim from a vesting claim at the storage level. A push distribution tracks claims with a bitmap, one bit per index, claimed or not, with no concept of a partial amount. Time-bound and vesting distributions both track a cumulative claimed amount per index instead. Time-bound spends that capacity on one full claim. Vesting is the family that exercises it, claiming progressively.

| Behaviour | Push | Time-bound | Vesting |
| --- | --- | --- | --- |
| Choose it when | A reward must land on a fixed date and the issuer covers every transfer's gas | Recipients can cover their own gas and should self-serve inside a window you set | The reward should unlock gradually instead of landing all at once |
| Who moves tokens | The owner, calling distribute or batchDistribute | Each recipient, calling claim or batchClaim | Each recipient, calling claim or batchClaim |
| Claim step | None. Claim and batchClaim always revert | One claim per index, full allocation | Initialise once per index, then claim repeatedly |
| Timing gate | None beyond the owner's own schedule | Only inside the start and end time | Initialise before the deadline, then claim once the cliff passes |
| Claim tracking | Bitmap: claimed or not, no partial amount | Amount-based, used for one full claim | Amount-based, used for progressive claims |
| Unlock pace | Set by the owner's own distribution schedule | Full amount unlocks at the single claim | Set by the strategy pinned at initialisation |

_The three distribution contract families, compared where they diverge_.

A vesting distribution pins its strategy at initialisation. Calling `initializeVesting` for an index pins the strategy current at that moment into the index's own record, before any tokens move. Every later claim for that index recomputes against the pinned strategy, never the contract's current one. An owner can repoint future initialisations at a new strategy, but no index already initialised ever notices the change. A linear vesting strategy fixes its cliff and total duration as constructor arguments at deployment, both immutable afterward. The allocation vests linearly across the full duration, measured from the recipient's own initialisation, but nothing is claimable until the cliff elapses. The first claim after that pays out everything vested so far.

Every distribution, in any family, is deployed as its own contract with a predictable address, so its identity is known before deployment. Deploying one needs the `TOKEN_FACTORY_MODULE_ROLE` at the system level, or the `GOVERNANCE_ROLE` on that specific token, a role grant the access manager checks before the deployment call runs. It is not open to arbitrary callers. The deployment also creates an on-chain identity for the distribution and registers it in the system identity registry under the country the deployer names, so the distribution can receive and hold a token whose compliance rules accept only registered holders.

## The integration contract [#the-integration-contract]

On chain, the three token distribution families expose different verb sets, and calling the wrong one for a distribution's family reverts. Push exposes `distribute` and `batchDistribute`, gated to the owner, and its `claim` and `batchClaim` always revert with a dedicated error ([DALP-3018](https://docs.settlemint.com/docs/api-reference/errors/error-code-reference#airdrop--distribution)).

Time-bound and vesting both expose `claim` and `batchClaim` to any caller. Vesting requires `initializeVesting` or `batchInitializeVesting` too, as a mandatory first call per index, before that index's claim succeeds.

A claim, a distribution, and an initialisation all check against the same fixed Merkle root. Each leaf is the index, the account and the total amount, ABI-encoded and hashed with keccak256, and that hash is ABI-encoded and hashed again: `keccak256(abi.encode(keccak256(abi.encode(index, account, totalAmount))))`. The proof must match that encoding precisely, with no fallback path. Building the correct proof for a given entry is your integration's responsibility, including getting each recipient their proof.

Build the tree with one leaf per index. Every family records claims, and a vesting distribution its initialisations, per index, so two leaves under one index share one record: one recipient's claims count against the other's, and a vesting withdrawal can then take tokens that index can still claim, or revert every time it runs.

Every claim and initialisation verifies the leaf against the caller's own address and pays that address, so integrations submit claims from the recipient's wallet instead of a service account. And batch calls cap at 100 entries in every family. A larger batch reverts before any entry processes.

A batch call's effect on token movement also differs by family. A push `batchDistribute` sends a separate transfer to each named recipient. A `batchClaim` on time-bound or vesting collapses several of the caller's own indexes into one transfer.

The Platform API does not create, fund, pay or claim an EVM distribution: those are direct contract calls. When the platform's contracts are deployed on a network, the network's directory registers the push, vesting and time-bound factory implementations. A system manager therefore installs a factory through `POST /api/v2/system/addon-factories` without naming an implementation. An implementation that the caller supplies takes precedence. A factory's `create` call also takes the country under which the new distribution's on-chain identity is registered, so the distribution can hold a token whose compliance checks identities. Once a factory is installed, the Platform API serves the distributions the platform has recorded from the chain:

- `GET /api/v2/addons/airdrops` lists the distributions of the active system's airdrop factories. Each item carries its contract address as `id`, its `typeId` (`push-airdrop`, `time-bound-airdrop` or `vesting-airdrop`), `name`, `token`, `merkleRoot`, `distributionCap`, `amountTransferred`, the withdrawal schedule (`withdrawalScheduled`, `withdrawalEligibleAt`), `vestingStrategy`, `vestingInitializationDeadlineAt` and `createdAt`. The list filters by search text, `typeId` and `filter[token]`. A system with no airdrop factory answers not found instead of an empty page.
- `GET /api/v2/addons/airdrops/{airdropAddress}` reads one distribution with the same fields plus `recipientCount`.
- `GET /api/v2/addons/airdrops/{airdropAddress}/recipients` lists every account the distribution has sent tokens to, with the amount and the last transfer time, most recent first. An account that was allocated tokens and has received none is not listed.

The vesting fields are empty for push and time-bound entries. When the platform has no indexed metadata for the token, `token` is null and the decimal amounts are null, while the exact amounts are still returned. An address that no airdrop factory of the active system deployed answers not found. The Platform API's distribution write routes do not serve EVM distributions and refuse one with `OPERATION_FAMILY_UNSUPPORTED` (HTTP 422).

In the Console, the "Placement" tab of an asset shows an "Airdrops" section when at least one distribution pays out that asset. It sums "Allocated", "Distributed" and "Remaining" across the asset's campaigns, and shows "Allocated" and "Remaining" only when every campaign has a cap. The figures are left out when the platform has no metadata for the token or when the asset has more than 200 campaigns. The table lists each campaign with "Distributed", "Recovery" and "Created". "View details" opens a sheet with the campaign's figures, its recipient count and a paged list of recipients with "Amount received" and "Last transfer".

Each installed distribution type also has its own entry under "Asset lifecycle" in the sidebar, "Push airdrop", "Vesting airdrop" or "Time-bound airdrop", which lists that factory's distributions and opens each one. When two factories of one type are installed, each entry shows its factory's name instead. A type that is not installed stays in the sidebar with the hint "… is not deployed. A system manager deploys it in Factories.", or "… is not deployed. Open Factories to deploy it." for a system manager. The Console has no control that creates or runs a distribution.

Map each refusal to its own message for the caller. An index that has not initialised fails vesting's claim with [DALP-3025](https://docs.settlemint.com/docs/api-reference/errors/error-code-reference#airdrop--distribution), and a claim outside the active window fails time-bound's claim with [DALP-3001](https://docs.settlemint.com/docs/api-reference/errors/error-code-reference#airdrop--distribution) or [DALP-3002](https://docs.settlemint.com/docs/api-reference/errors/error-code-reference#airdrop--distribution), depending on which side of the window it falls. Neither of those is the condition a bad Merkle proof produces ([DALP-3032](https://docs.settlemint.com/docs/api-reference/errors/error-code-reference#airdrop--distribution)), nor the one an already-claimed index produces ([DALP-3030](https://docs.settlemint.com/docs/api-reference/errors/error-code-reference#airdrop--distribution)). Treat all four as separate cases in your own error handling.

## Controls and evidence [#controls-and-evidence]

Who is on the recipient list, and for how much, is decided off chain by whoever builds the Merkle tree. The contract enforces only that a claim, a distribution, or an initialisation matches the committed root.

An audit of a distribution asks who built the Merkle tree, from what source list, and under what approval. The contract allows anything the tree contains, subject to the token's compliance rules.

The transfer runs through the underlying token's own transfer-compliance modules, the same modules that check every other transfer on that token by evaluating each configured rule before balances change and reverting if any rule fails.

Evidence is on chain and per distribution, across all three families. Creation, every transfer, whether a push distribution or a self-service claim, every vesting initialisation, and every withdrawal-schedule step each emits its own event. An auditor can tie each payment to its distribution, recipient and path from the events: a push send, a time-bound claim, or a vesting initialisation followed later by one or more claims. A batch claim emits one transfer for several indexes, so read the claim events for the split per index. A withdrawal's `TokensWithdrawn` event carries the amount it sent, which is zero when nothing was spare. The chain records execution. Keep the recipient list and its approval evidence separately to explain how the Merkle root was chosen.

A push distribution and a self-service claim carry different accountability even though both move the same tokens. A push distribution is a step the operator, or an authorised automation, took on the recipient's behalf. A claim is a step the recipient took themselves.

## Frequently asked questions [#frequently-asked-questions]

### What happens when a push distribution misses a recipient?

The owner can still distribute to that index later, because a push distribution has no claim window and no deadline of its own. The recipient cannot self-serve in the meantime: a claim on a push contract always reverts. The index stays payable until the owner distributes it or a withdrawal empties the contract. A push withdrawal sends the whole balance seven days after scheduling and keeps nothing back for indexes the owner has not distributed. A distribution that would exceed the cap fails until the owner raises the cap.

### What happens if I never initialise my vesting allocation?

Nothing unlocks, ever. The vesting clock starts only when initialisation runs for your index, and the contract refuses that call once the distribution's initialisation deadline passes, so a late attempt reverts. Your allocation then counts as spare balance, which the owner's withdrawal can send out of the contract once the deadline has passed. Initialise before the deadline even when you plan to claim much later: an initialised allocation stays in the contract for you, whenever the owner withdraws.

### Does my vesting schedule run from deployment or from my own initialisation?

From your own initialisation. The contract records the timestamp of your initialisation, and the strategy measures the cliff and vesting duration from that moment, so two recipients who initialise a week apart also finish a week apart. Waiting to initialise does not bank vested time. It delays the entire schedule, and the initialisation deadline caps how long you can wait.

### Can I claim while the cliff is still running?

No. The call reverts instead of paying zero. Under a linear strategy, nothing is claimable until the cliff duration has passed since your initialisation, and the contract rejects a claim whose computed claimable amount is zero. Once the cliff passes, the first claim pays everything vested since initialisation in one transfer, and later claims pay only what unlocked since the previous one.

### Can someone else claim my allocation for me?

The recipient must still authorise the claim, but a relayer can submit it and pay the gas through the platform's meta-transaction support, and the recipient still receives the tokens. When recipients cannot transact at all, even through a relayer, a push distribution is the family built for that.

### Can the owner withdraw tokens while claims are still open?

No, not the tokens an open claim can still reach. The owner can schedule a withdrawal at any time, but it runs seven days after scheduling at the earliest, and never before a time-bound distribution's claim window has ended or a vesting distribution's initialisation deadline has passed. `executeWithdrawal` refuses before then with [DALP-4353](https://docs.settlemint.com/docs/api-reference/errors/error-code-reference/dalp-4300-4399). What the withdrawal then sends depends on the family.

A time-bound withdrawal runs only after the end time, when no claim can follow, so it sends the whole balance. A vesting withdrawal runs only after the initialisation deadline and leaves the unclaimed part of every initialised allocation in the contract, so a recipient who initialised in time keeps claiming as the allocation vests. A push distribution has no claims to protect: its withdrawal sends the whole balance seven days after scheduling, so distribute every index first.

The rule binds the owner only. The token's custodian role can still force-transfer the distribution's balance at once, and the system manager role can replace the code of every distribution of a factory.

## Related concepts [#related-concepts]

- [Asset Lifecycle](https://docs.settlemint.com/docs/concepts/issuing-and-markets/asset-lifecycle): The whole working life of a regulated tokenised instrument. A distribution transfer runs through the same instrument's transfer path that every other servicing operation already writes to.
- [Primary Offering](https://docs.settlemint.com/docs/concepts/issuing-and-markets/primary-offering): The platform's other route for putting a token in a holder's hands, sold to investors instead of distributed under a Merkle root.


# Trading Venue

Source: https://docs.settlemint.com/docs/concepts/issuing-and-markets/trading-venue
A Trading Venue lets a tenant run its own exchange for a tokenised asset. An approved bust lends the operations signer a custodian role for the reversal alone.



[Figure] One order, from signature to delivery. A trader's wallet signs an order. The venue checks the signature, deposits only the shortfall, the part of the commitment the trader's free balance in the venue's escrow does not cover, from the trader's wallet into that escrow, and locks the order's amount. The same path serves a DALP token and a plain ERC-20. The trader's only approval is an ERC-20 approval to the escrow. Only once the commitment confirms on chain does the order rest on the book, where the engine matches on price and then on time. With a positive holding period, a fill is reported and priced while both legs stay locked. Delivery transfers value to the counterparties. The instrument's holding period ends, and both legs and the fee are paid out of the locks through each token's own compliance path. Until that moment an approved bust undoes the trade by unlocking the legs back to free balance, and a delivery a token refuses undoes itself the same way. Labels: Trader signs an order with their own key; The venue deposits the shortfall and locks the order's amount; Venue escrow: free, then locked; The wallet pays in only what free balance lacks, against one approval to the escrow.; Nothing is pulled when free balance already covers the order.; The order rests, and the engine matches on price, then time; The fill is reported and priced, and both legs stay locked; Delivery: counterparties receive the legs; The holding period ends, and the locks pay out both legs and the; fee through each token's own compliance path.; Until then, an undo unlocks the legs back to free balance. Nothing is forced back.

  

One order's whole path: it commits before it rests, can match without being delivered, and passes each token's own compliance path before anything is final.

A venue is a tenant's own exchange: its own members, its own calendar, its own fee schedule, under one on-chain identity, and a tenant runs as many as it needs. An instrument is one trading line inside a venue, so the same pair listed on two venues is two instruments with two prices.

Listing gives the venue contract no custodian power. Both legs settle through the venue's own escrow, where a trader's units are free or locked to an order, for a DALP token and a plain ERC-20 alike. The organisation's operations signer, the platform account that submits settlements, holds no custodian role on a listed token. An approved bust lends it the role on the base and the quote token for the reversal and takes it back when the reversal ends. On chain that role lets the account freeze, force-transfer and recover any holder's units of the token, and the platform uses it only to reverse a delivered trade.

A fill is not delivery. With a positive holding period, both legs stay locked in the escrow until delivery. An instrument with a holding period of zero delivers inside the fill's own transaction, with no window at all.

## Why trading needs a venue [#why-trading-needs-a-venue]

Issuance is a single event. A primary offering sells newly created units once, and the register then closes to that offer. What a holder does with the position afterward is a separate question the sale itself never answers.

An institutional buyer prices that gap in before they ever subscribe. An instrument nobody can exit is worth less to hold than one that trades, and that discount lands on the offering itself, not just on the holder stuck with it later. A venue is what turns a single sale into an instrument with an ongoing secondary market.

That places trading downstream of issuance, inside the same asset's working life rather than beside it. [Asset Lifecycle](https://docs.settlemint.com/docs/concepts/issuing-and-markets/asset-lifecycle) names the stage directly: after an instrument is issued and launched, it is serviced for as long as it lives, and settling trades sits in that same Service stage next to paying coupons, freezing holdings, and collecting fees. [Primary Offering](https://docs.settlemint.com/docs/concepts/issuing-and-markets/primary-offering) is the contract-governed first sale that life begins from. A venue is what happens to the same asset afterward, for as long as anyone wants to trade it. [Venue journey](https://docs.settlemint.com/docs/concepts/issuing-and-markets/venue-journey) follows one security from listing to the session close, step by step.

## Why the venue runs on the platform [#why-the-venue-runs-on-the-platform]

The alternative to a venue built into the platform is a venue built beside it. That second system lists the same tokens under its own view of who may hold them. It needs its own way to hold units mid-trade too, because a trade in progress has to sit somewhere between the seller and the buyer, and each of those is a seam. A seam is where the exchange's own rules and the issuer's rules can quietly disagree: a trade the venue allows and the token's own compliance would have refused.

The venue holds traders' units in one escrow it controls, and the escrow pays out only through each token's own transfer, so the token's rules still judge every delivery. On a token with the current compliance contract, the seller's deposit into the escrow runs the token's sender-side rules. The delivery out of the escrow runs its rules for the buyer as recipient. A recipient the rules refuse does not undo the trade: its leg waits in its free escrow balance until it passes the rules again. A delivered trade is a normal token transfer, so it lands in that asset's own record the same way every other movement does, next to the coupons, freezes, and fee collection [Asset Lifecycle](https://docs.settlemint.com/docs/concepts/issuing-and-markets/asset-lifecycle) already indexes there.

Compliance risk stays with the token, because every delivery runs through the token's own rules. A reversal of a delivered trade uses custodian forced transfers, which skip those rules on chain, so the platform checks the rules against the reversal transfers before it accepts the bust. A platform administrator or the organisation owner sets each instrument's maker and taker fees and its fee account on chain, signing with a wallet that holds the venue operator role.

## What a venue is, and what an instrument is inside it [#what-a-venue-is-and-what-an-instrument-is-inside-it]

A venue is a tenant's own exchange, run on its own terms. It admits whoever it decides to admit, keeps its own calendar and fee schedule, carries its own on-chain identity, and records its admission policy on chain, which the platform checks at order intake. A private instrument narrows it further to the participants it names, and the token's own compliance still decides every delivery. A tenant runs as many venues as it needs, one for retail members and one for institutional desks, or one per jurisdiction.

The trading venue is the "Secondary market" [licensed module](https://docs.settlemint.com/docs/deployment/install/values-secrets#switch-application-layers-on-or-off), and a deployment ships with it off. While `features.tradingVenue` is off for the deployment, the venue routes answer as not found and the Console shows no venue screens. While it is off for one organisation, that organisation keeps read access to its venues and instruments, and every write is refused with HTTP 403 `platform.module.DISABLED`, error [DALP-20531](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference), with `data.module` set to `tradingVenue`. The FIX drop copy also needs the surveillance module.

An instrument is one trading line on one venue: a base token, a quote token, and the book, price band, fee schedule, and holding period that make them tradable there. The same pair listed on two venues is two instruments, with two order books and two prices, and halting one leaves the other trading. At most one instrument per token on each system is that token's reference instrument, and only its official close reaches the token's price feed. An instrument's close is computed by a defined methodology set at the instrument: the last trade price, or a volume-weighted average over a configured window before the close. A session with no settled trade closes at its auction price and then the previous close, or straight at the previous close, as the instrument's "No-trade fallback" decides.

[Figure] One tenant, several venues, several instruments, one reference instrument per token. One tenant runs Venue A and Venue B. Venue A lists BOND/USDC and BOND/EURC. Venue B lists its own BOND/USDC instrument. BOND/USDC on Venue A is flagged as BOND's reference instrument, and a separate connection shows only its official close reaching BOND's price feed. The other two instruments keep their own closes and are not connected to the feed. Labels: One tenant; Venue A; identity, admission, calendar; Venue B; identity, admission, calendar; BOND / USDC; Reference; on Venue A; BOND / EURC; on Venue A, own close; BOND / USDC; on Venue B, own close; official close only; BOND price feed.

A venue contains instruments, and only a token's reference instrument sends its official close to the token's price feed.

## Listing: what a venue gets and what stays with the issuer [#listing-what-a-venue-gets-and-what-stays-with-the-issuer]

Listing grants the venue contract no custodian role over a token. The venue asks its escrow to lock, unlock, relock and pay out the units owners committed. A venue admin can also have the escrow sweep out a surplus, meaning units that reached the escrow without being owed to any owner. No path in the venue contract reaches a forced transfer, an address freeze, or a recovery on a listed token. The venue and its escrow follow their factory's implementation, so a holder of the system manager role, or the add-on registry, can repoint the factory and change the code of every live venue and escrow at once. The escrow itself keeps two emergency exits. For a DALP token, any holder of that token's custodian role, the organisation's operations signer included, can move an owner's free and locked escrow units to another wallet through the escrow. The escrow pays with an ordinary token transfer, so the recipient must pass the token's rules. For a plain ERC-20, only the venue contract may force a transfer, and the venue contract has no code that does. A recovery moves a lost wallet's free escrow balance only to the wallet the identity registry names as its replacement.

Listing gives no platform account a custodian role either. A bust lends one. A delivered trade's bust always waits for a second operator, so the venue never waives it. When that bust is approved or resumed, the platform grants the organisation's operations signer the custodian role on the access manager of both the base and the quote token, signed by the listing signer, and waits for both grants to settle on chain. It then sends the forced transfers that reverse the trade, and revokes the role from both tokens when the reversal ends, whether it completed, failed or stalled. A proposal that waits for its second operator grants nothing, so a proposal that is rejected or expires never leaves a role behind. The platform lends only a role the operations signer does not already hold, so a role a token admin granted on the token's Permissions page stays. When the grant cannot be made, for example on a plain ERC-20 with no access manager or when the listing signer cannot grant roles on the token, the bust is refused and names the step to fix: a token admin grants the custodian role to the operations signer on the token's Permissions page. A reversal that stalls partway can lose the role while a transfer is still in flight, and resuming the bust lends it again. When a revoke cannot be sent or does not settle, the platform logs the token so a token admin can revoke the role on the token's Permissions page. Tokens listed before busts lent the role still carried the role their listing granted, because nothing revoked it. The platform takes those back too: it finds each one by matching the role the chain shows to the grant transaction the organisation's own queue recorded for that listing, and the operations signer gives the role back with no admin role needed. A role a token admin granted sits in a different transaction and is never touched. The platform leaves a token alone while a bust on one of its markets is approved, executing or failed and waiting to resume, so a cleanup never takes the role away from a reversal that is under way. A renounce that fails is sent again on a later pass under a new request key, up to eight attempts, and after the last the platform logs an error so a token admin can revoke the role on the token's Permissions page. Only a role held by the organisation's current operations signer is given back. When the holder is a former operations signer, or the organisation has no managed operations signer, the role stays, and the platform logs the token and counts it so a token admin can revoke it on the token's Permissions page.

Every token is handled the same way, because the venue has one escrow and the escrow has one set of rules. The escrow is an instance of the [escrow add-on](https://docs.settlemint.com/docs/concepts/custody-and-signing/escrow), a custody contract that the venue controls for many owners, and it keeps a free balance and locked balances per owner and token. When a trader places an order, the venue checks the signature, pulls from the trader's wallet only the shortfall, the part of the commitment the trader's free balance lacks, and locks the order's amount. The trader's only approval is an ERC-20 approval to the venue's escrow, for a DALP token and a plain ERC-20 alike, and an order that free balance already covers needs none. A commit the approval does not cover is refused on chain and the order never rests. The escrow has its own on-chain identity with a `dalpEscrow` claim and sits on the compliance bypass list. A deposit into it therefore runs the token's sender-side rules, such as the address block list and time lock, and skips the rules that judge the recipient. On a token that uses the first version of the token compliance contract, a deposit into the escrow skips every rule, sender-side ones included. A payout from it runs the recipient's rules in full. A token with holding rules exempts the escrow's claim from those holding rules.

A platform administrator or the organisation owner can list a token. The listing is accepted only when three things hold: the listing signer has the venue operator role, the organisation has an operations signer on the chain, and that signer has the venue submitter role. A failed check refuses the listing with the step and account to fix. The listed instrument then stays pending until its go-live preconditions complete: a registered feed writer, an eligible fee account, a trading schedule, a trading model, a valuation price, a floor price where the instrument needs one, and listing rules the instrument meets. A listing the venue contract itself reverts is refused with the venue's error name, so the caller sees which venue rule the listing broke. Listing needs no hold feature and no reserver authorisation from an issuer.

[Figure] The one paved path a reservation can take, and the paths that do not exist. A trader's wallet signs an order to the off-chain matching engine, and nothing moves yet. A matched fill goes to the on-chain venue contract, still moving nothing. The contract locks, unlocks, and pays out through the venue's escrow, which holds each trader's free and locked balances. Every transfer the escrow makes runs the listed token contract's own checks before the leg and fee reach the counterparty wallet. A separate, blocked path leads from the venue contract toward a forced transfer, an address freeze, or a recovery, and it terminates before reaching the token: that path does not exist in the deployed contract. Labels: Trader wallet; Matching engine; Off-chain; signs an order, nothing moves; On-chain; Venue contract; matched fill, nothing moves; locks, unlocks, pays out; Venue escrow; free and locked balances per owner; listed token's checks run here; forced transfer / freeze / recovery: blocked, never reaches the token.

The venue contract moves units only through its escrow, and the path toward a forced transfer, a freeze or a recovery ends before it reaches the token.

### What the venue limits for every instrument, and what it only suggests [#what-the-venue-limits-for-every-instrument-and-what-it-only-suggests]

A venue can limit the order types and the time in force that every instrument on it accepts. The limit is a ceiling, and it applies to instruments already listed as well as to new ones: an instrument accepts what it sets for itself and the venue also allows. Orders already resting stay on the book. Raising a limit again restores the option for instruments that still list it. A limit that would leave a listed instrument with no order type, or no time in force, is refused when the venue admin saves it, so a venue never strands an instrument that traders can no longer use.

The venue can also hold starting values for the maker and taker fee, the fee account, the market-order protection band and the holding period. These are not limits. The listing wizard copies them once, when an operator opens it, and the operator can change each one. Once the instrument is listed it keeps its own value, and a later change to the venue's starting value does not reach it. A venue admin sets both on the Listing rules page, and a venue that requires a second approver holds the change for one. [Venue operations](https://docs.settlemint.com/docs/console/asset-lifecycle/venues/listing-rules) covers the page.

## Trading: how a resting order becomes a fill [#trading-how-a-resting-order-becomes-a-fill]

Every order is an EIP-712-signed intent, a typed structured message signed for the maker's wallet: by the custody provider after the investor's wallet verification for a custodial wallet, or by the investor's own wallet. The venue contract checks that signature, so it cannot place or change an order the maker's wallet did not sign. An order carries a type and a time in force, independently of each other.

| Order type | What it does |
| --- | --- |
| Limit | Rests at a stated price until it fills, expires, or is cancelled |
| Market | Matches immediately at the best available price |

| Time in force | What it does |
| --- | --- |
| Good-til-cancelled (GTC) | Stays resting until filled or cancelled. An auction that leaves it unfilled carries it to the book on an instrument set to carry, which is the default for every instrument |
| Good-til-date (GTD) | Carries its own signed expiry. The matching engine keeps its own clock: every new order and every expiry pass advance it past due dates, so the order expires within seconds of its date even when no new order arrives. The pass runs every second while it finds orders to expire and every five seconds otherwise |
| Day (DAY) | Rests until filled, cancelled or the session closes. When the instrument's session closes, the matching engine expires it and refunds its commitment, so an early close or a holiday moves the expiry with it |
| Immediate-or-cancel (IOC) | Fills what it can at once and cancels the rest |
| Fill-or-kill (FOK) | Fills its whole quantity at once or is cancelled without trading. It is accepted only in the continuous session, because an auction cannot fill it immediately |

A stop order is a limit order with a trigger price. The venue reserves the order's full amount when the trader places it, the same amount a limit order at that price reserves, and holds it while the stop is armed. The stop does not rest on the book. It is armed until the instrument prints a trade at or through the trigger price: a sell stop fires when a trade prints at or below the trigger, a buy stop when a trade prints at or above it. Any trade print counts, an auction uncross included. A fired stop joins the book as a limit order at its limit price, with the reservation it already holds, and is reported as a new order. A trader cancels an armed stop like any resting order, and the cancel releases the reservation in full. A stop also closes when it expires. A stop stays armed while an instrument is halted and activates once the instrument is live again. A suspension or a delisting cancels it with the rest of the book. Intake refuses a stop whose trigger is already on the wrong side of the last trade (a sell stop at or above it, a buy stop at or below it), a stop with a market order type, and a stop set to immediate-or-cancel or fill-or-kill: a stop is good-til-cancelled, good-til-date or day. The trigger price is not part of the maker's signed digest, so the order signature binds the amount, price and expiry, and the venue enforces the trigger server-side. A private instrument, one open only to the participants it names, takes limit orders only: good-til-cancelled, plus good-til-date and day orders on an instrument with a continuous book. A public instrument can allow every order type and time in force above. An instrument with no trading calendar refuses day orders, because no session close would expire them.

A resting order can be amended in two ways, and the way decides its place in the queue. Lowering its quantity at the same price is done in place: the order keeps its id, its signature and its position, and the lock behind the removed quantity returns to the trader's free escrow balance. A new price or a larger quantity needs a newly signed order, because the maker never signed those terms. The venue cancels the original, which unlocks its remainder back to free balance, and then places the replacement from that free balance plus any shortfall deposited from the trader's wallet. When a fill of the original has no recorded settlement yet, as right after a partial fill, the cancel still stops new fills at once, and the request waits up to the reservation timeout for the venue to record that settlement before the remainder unlocks. The original closes as replaced, and the new order takes its own id, joins the back of the queue at its price, and may trade at once if its price crosses. If the replacement fails after the cancel, the venue answers HTTP 409 with `ORDER_AMENDMENT_INCOMPLETE`, error [DALP-12375](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference): the original is cancelled and the replacement was not placed. A settlement the venue does not record within that wait answers this 409, and the remainder stays locked until the venue records the settlement and unlocks it to free balance. When the escrow or the book refuses the replacement itself, the remainder is already free. A repeat of the same amendment, once the remainder is free, places that replacement without cancelling the original a second time: an API caller sends the same signed replacement again, and a replacement the venue signs with the trader's custody wallet, as the Console and the Investor portal send it, is the same replacement when its terms are the same, because those apps derive its salt from the original order and the requested price and quantity. A replacement with other terms, sent as an amendment of the cancelled original, answers `TRADING_VENUE_ORDER_NOT_FOUND`. On this 409 the Console and the Investor portal say the original is cancelled, show whether its remainder is still locked or already back in free balance, and tell the trader to place a new order once the remainder is released. Both kinds of amend are recorded in the order log, so a drop copy can report them as replacements.

An accepted order does not join the book directly. The venue first commits it in its escrow: it checks the trader's signature, deposits only the shortfall from the trader's wallet, and locks the order's amount. The order rests and appears in the book only once that commitment confirms on chain. A commitment that reverts or times out, including one the trader's escrow approval does not cover, rejects the order before it joins the book, and rejected is terminal: the trader signs a new order, because the original is never retried. Once resting, the book shows each price level, streamed to readers as a full snapshot followed by diffs. Each instrument sets which attributes of a level its participants see: the price always, and the resting quantity and order count when the instrument allows them. A hidden attribute is sent as null, and the venue operator sees every attribute. The engine matches strictly by price and then by the order's time of arrival.

A cancel, an expiry, or a prune unlocks the order's remainder back to the trader's free escrow balance, and nothing leaves the escrow. Free balance belongs to the trader, who withdraws it to their wallet from the Balances panel in the Console or the Investor portal, or through the venue balances API. The panel shows free and locked escrow balances per leg, and a withdrawal is refused when it asks for more than the free balance. A settlement that fails undoes its fill and frees both trade locks into free escrow the same way, and the Console desk rereads the escrow balances as soon as the fill reads Undone, so "Reserved for orders" clears with it.

A buy limit order locks enough of the quote token to pay its limit price plus a fee at the maximum fee rate the trader signed into the order, which the venue caps at its own maximum. The order ticket in the Console and the Investor portal signs the higher of the instrument's maker and taker fees, with VAT included when the venue collects VAT on chain. A fill below the limit price spends less than that. The unspent quote amount stays locked while the order stays open, and the venue unlocks it back to free escrow balance when the order closes: when it fills completely, or when it is cancelled, expires or is rejected. Until that unlock is on chain, the trader's Balances panel keeps showing the unspent amount as locked. The settlement stands either way.

An instrument can also run an auction, at the open or at the end of a collection window. During an auction the book collects limit orders without matching them, and the auction then matches the collected orders once, at a single clearing price. Every auction on an instrument prices by the instrument's "Pre-open price rule" setting, which has two options. Under the default, "Tie average", the platform tests each price level that lies between the best sell price and the best buy price and keeps the level at which the largest quantity trades. When several levels trade that largest quantity, it keeps those that leave the smallest quantity unmatched. When more than one level is still tied, the clearing price is the mean of every tied level, not the midpoint between the lowest and the highest. The reference price and the last trade price play no part in a tie. When no buy price reaches a sell price, the auction does not trade.

The setting's other option, "Previous close reference", anchors the auction on the instrument's previous official close. An instrument with no close yet uses the instrument's reference price, set at listing, instead. The option tests each order price on the book between the best sell price and the best buy price, and ranks the levels by the quantity that trades and then by the smallest gap between the buy and the sell quantity at that level. One best level is the clearing price. When several levels tie, the auction clears at the tied level nearest the anchor, and at the anchor itself when two tied levels sit equally near it. Without either a previous close or a reference price, the auction does not trade and the collected orders carry to the book. This option never averages prices, so the "Auction price rounding" setting plays no part. When no level trades and an anchor exists, the "Auction remainder" setting decides what happens to the collected orders, and that anchor is recorded as the auction price.

A public continuous instrument can end its continuous session with a closing auction. The calendar sets when it starts, between the open and the close, and before Trade at last when the day has one. From that time the book collects limit orders without matching them. One uncross at the end of the auction, at the Trade at last time or else at the close, matches them at a single price under the instrument's "Pre-open price rule", and the "Auction remainder" setting decides what happens to the orders left unmatched. A band-refused or tie-blocked uncross does not hold the session open. The auction's price is the instrument's official close. An auction-only or private instrument has no closing auction. Day orders expire at the close.

A public continuous instrument can end its day with a Trade-At-Last session. The calendar sets when it starts, between the open and the close. From that time until the close, an order trades only at the last price: the last trade, else the previous official close, else the reference price. The instrument accepts limit orders at exactly that price, matches them against resting orders ignoring the price band, and refuses market, immediate-or-cancel and fill-or-kill orders and any other price. An unfilled good-till-cancelled or good-till-date remainder rests at the last price. The official close uses the trades up to the start of the session, so trades at the last price do not move it. An auction-only or private instrument has no Trade-At-Last session.

A price step, also called the tick size, is the smallest price change the instrument allows. Under the Tie average option, when the mean of the tied levels falls between two price steps, the instrument's "Auction price rounding" setting decides the clearing price. "Nearest step, half up" and "Nearest step, half down" round the mean to a price step. "Block between price steps" is the default and leaves the tie unresolved, so the auction does not trade. When this happens at the scheduled open, the instrument keeps collecting orders. When it happens at the end of a collection window, the instrument session closes. The instrument's "Auction remainder" setting decides what happens to the orders an auction leaves unmatched, including every collected order when the session closes this way: "Carry to the book" keeps them resting, and "Cancel remainders" cancels them.

The auction fills orders in the same priority as continuous trading. Buy orders fill from the highest price down and sell orders from the lowest price up, and at one price the earlier order fills first. Every fill trades at the clearing price.

An instrument whose session has a preopen, a period before the open in which the book collects orders without matching them, runs its opening auction at a moment no one knows in advance. The platform draws that moment at random inside a window that starts at the scheduled open time, so no order can aim at it, and it never publishes the drawn moment. The window length is a deployment setting. The trading calendar read returns it in milliseconds as `uncrossWindowMs`, and during the preopen the Console shows "Opens within N seconds after" the scheduled time, with the window length in seconds as N. A continuous instrument with no preopen has no opening auction and opens at the scheduled time.

A preopen order goes first only at the opening auction, which prices the collected orders together. Whatever the auction leaves unfilled then rests like every other order, by price first and arrival time second. A later order at a better price fills ahead of a leftover preopen order, and a later order at the same price fills behind it. This holds for a buy and a sell, and for as long as the order rests.

A venue price band limits both accepted limit prices and trade prices. The venue default starts Off. Each instrument inherits that default, turns the band off, or overrides it with its own static or dynamic policy.

| Policy | Range |
| --- | --- |
| Static | A fixed minimum and maximum price in the quote token |
| Dynamic | An initial percentage above and below the previous official close, with an expansion step and a maximum percentage |

Both bounds are inclusive. A dynamic band widens only the side a trade reaches, by one expansion step, up to the cap. The reference remains the previous official close until the next session close resets the band. Without an anchor, a dynamic band blocks trading and chooses no reference price.

The venue rejects an out-of-range limit order as above or below the band. Continuous fills and auction clearing prices must also stay inside it. A market order is signed at its separate protection-band edge, but its fills still stop at the effective price band. Saving a tighter policy cancels excluded resting orders and unlocks their locked balances.

An instrument can also carry a volatility interruption, a circuit breaker that is off until an operator sets it. The rule has a threshold in basis points, a duration in seconds, and a reference price: the last trade or the previous official close. A fill that would print further from the reference than the threshold does not print. Fills inside the threshold stand, and continuous trading stops at the first resting order beyond it. For the duration, the instrument collects orders without matching them. Then one single-price auction clears the book, and continuous trading resumes. The auction price is not bound by the market-order protection band, but the static band, the price band and the floor still apply, and an auction that cannot clear is retried on the next scheduler pass. A session change away from continuous trading ends the interruption. The instrument stream carries the interruption and its end time with the band, the drop copy sends it as a market report, and each start and end is recorded in the audit log.

An instrument can instead suspend the orders a band excludes. The band setting `outOfBandCarryOver` is `close` by default, which keeps the behaviour above. Set to `suspend`, it moves each resting order outside the band, including a good-till-cancelled or good-till-date order carried over from an earlier day, to the status `suspended`. The order records the reason, `above-price-band` or `below-price-band`, in its close reason field. A suspended order leaves the book and no trade can match it, but it keeps its reservation and its place in the time queue.

Every band change runs a reinstatement pass: a new session band, a widening after a trade, a saved policy, or a policy switched off. A suspended order that the band covers again returns to the book in its original time priority, and it trades at once if it now crosses resting orders. A suspended good-till-date order still expires on schedule, and its reservation is released. A participant can cancel a suspended order. New and replacement orders outside the band are still rejected. Drop copy reports a suspension as an execution report with order status Suspended and the reason in its text, and a reinstatement as the order being New again.

Issuer floors and anchor-based widths stored before this band policy keep applying. Turning the price band off does not remove those limits or per-order size limits. The separate market-order protection band also remains in force.

The maximum order size and the minimum and maximum order value can differ by participant class. A venue sets general limits, which apply to every class, at venue level and for each instrument. Either level can add limits for the retail, institutional or proprietary class. [Claim topics](https://docs.settlemint.com/docs/console/compliance/verification-topics) are the identity evidence types a venue can require for admission, and the venue maps them to those classes. When the sender's identity holds mapped topics for more than one class, the order takes the most protective class: retail before institutional, and institutional before proprietary. When it holds none, the order takes the "Client classification" the instrument lists for that participant wallet, when there is one. The venue checks every limit that applies and keeps the strictest, which is the smallest maximum and the largest minimum. A class limit can therefore tighten the general limits but never loosen them. An order with no class is checked only against the general limits. The Console shows and edits an instrument's general limits. It has no field for the venue-level general limits, the class limits or the topic mapping, so you set those through the Platform API.

An instrument itself moves through one lifecycle: pending until every listing precondition completes, then live. An operator can halt or suspend a live instrument and resume it back to live, and a halted instrument can also be suspended. A delisting is permanent, and an operator can delist an instrument from any other state, a pending one included. The figure shows the main path and leaves out suspension and the delisting of a pending instrument.

A halt also suspends the instrument's scheduled auctions. An opening auction or a collection-window clearing that falls due while the instrument is halted does not run. The first session step after the operator resumes the instrument runs it. When a session ends while the instrument is still halted, it closes without its opening auction. A continuous session with no preopen also holds its open while the instrument is halted or suspended. The open applies on resume, and any crossing orders uncross.

An instrument can also carry a resume cut-off in whole minutes, and the venue's listing rules hold a default for instruments that set none. From that many minutes before the session close until the close, the platform refuses to resume a halted or suspended instrument with HTTP 409 `MARKET_RESUME_INSIDE_CUTOFF`, error [DALP-174401](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference), which carries the close time and the cut-off. After the close a resume is allowed, a cut-off of 0 blocks nothing, and an empty cut-off leaves resume unrestricted.

[Figure] An instrument's own status, from creation to an optional permanent delisting. An instrument is created pending. It goes live once every listing precondition completes. From live, an operator can halt it, and from halted the operator can resume it back to live. Those two states cycle under operator control. From either live or halted, an operator can delist the instrument, and delisting is permanent: there is no path back from it. Labels: Pending; Live; operator; halts; operator; resumes; Halted; operator delists, permanent; Delisted.

An instrument's status: pending until every precondition completes, then live, with operator halt and resume and permanent delisting from either state.

## Settlement: a fill is not delivery [#settlement-a-fill-is-not-delivery]

A matched trade is reported, priced, and published straight away, and on an instrument with a positive holding period both legs stay locked in the escrow, untouched, for a window after that. The token's own compliance check is the venue's final authority on whether a transfer is legal, and that check only runs at the moment of delivery: the holding period is what waits for it. Atomic settlement at the moment of the trade is available too: setting an instrument's holding period to zero delivers inside the fill's own transaction, with no window before delivery. A bust on such a trade reverses a delivered trade with custodian forced transfers.

Before delivery, an undo is not a reversal. Nothing has moved yet, so unlocking both legs has nothing to move back and no fee to refund. It is closer to the trade never finishing than to the trade being cancelled. The venue undoes a pending trade with the same event and bookkeeping whatever the cause. The causes are an approved bust, an outside cause at delivery, and the settlement submitter's automatic undo. An outside cause is one the trader did not choose. The venue lists four: a paused token on either leg, a trade lock that a custodian shrank below what the legs need, a frozen sending side (the account that owns the lock, or the escrow itself), and a receiver added to the compliance bypass list during the holding period. The API reports an undo for an outside cause as `refused`. It is not a bust, which always starts with an operator's proposal. An undo for an outside cause is the one case that looks like a real correction, since the trade was already reported: the price is corrected, the trade drops from clean history, and both sides are told why. An undo unlocks each leg back to its owner's free escrow balance, and the owner withdraws it to their wallet.

Any other refusal at delivery does not undo the trade. A receiver can make the token refuse a transfer to itself, for example by removing its own identity claim during the holding period, and undoing the trade for that would hand the receiver a free option to walk away from a price that moved against it. Instead the venue pays every leg that can be paid and books each refused leg to its receiver's free balance in the escrow. That booked leg is a parked leg. The trade counts as delivered, and the venue emits a `DeliveryLegParked` event for each parked leg next to the delivery event. Each leg is judged on its own: the base leg, the quote leg and each fee leg can park separately, and both sides of a trade can park. The parked units sit in the receiver's free balance, and the receiver withdraws them like any other free balance. The withdraw runs the token's compliance and freeze checks again, so a receiver that is still unverified or frozen cannot take them out. It cannot sell them on the venue either: placing an order that would lock units from the free balance is refused with `MakerCannotReceiveToken` while the token's identity registry does not verify the maker, or while the token's compliance would refuse the escrow paying that maker.

On a venue whose **Trading venues** row under "Approvals" is on, a bust needs two venue operators. One proposes it within 24 hours of the trade, and a different operator approves or rejects it. With the row off, a bust of an undelivered trade is recorded already approved and the undo starts at once, with no second person. A bust of a delivered trade reverses it with forced transfers of the holders' tokens, so it needs a second operator whether the row is on or off. When the trade is still pending, the proposal flags it on chain at once. Delivery skips a flagged trade for up to seven days past its due time, so the clock cannot settle a trade while the decision is open. Delivery itself needs no role: once a trade is due and no review holds it, any account can call it on the venue contract. A rejection clears the flag, and the trade delivers once it is due. An approval runs the undo at once. If delivery remains pending after the flag's review window closes, the settlement service can still complete the approved undo. On chain, only a holder of the venue submitter role can undo a trade, and the platform holds that role in the organisation's operations signer. The platform submits the undo only after the bust's approval. The second approval is a platform check, and the venue admin grants and revokes the submitter role. Before queueing the undo, the platform refuses a bust the venue would reject: a delivery that is past its due time without a review flag, or an organisation operations signer that lacks the venue submitter role. The refusal applies when the bust is proposed and again when it is approved or resumed. The Console and the Platform API set and clear the flag only through a bust proposal and its decision. A holder of the venue operator or venue submitter role can also flag or clear a pending trade directly on the venue contract, with no proposal and no second approval, which holds that trade back from delivery for up to seven days past its due time. Setting and clearing the flag is best effort, and a failure never cancels the proposal or the decision. When the flag cannot be set, only the holding period keeps the trade from delivering. When the flag cannot be cleared after a rejection, the platform logs the gap, and the trade stays held until an operator clears the flag or the seven-day review window ends.

A trade that already delivered is outside the venue contract. A bust on a delivered trade is still possible inside the same 24 hours, from the Console or the Platform API, and the platform first checks that the token's compliance rules allow the reversal transfers. An approved bust then sends custodian forced transfers under the operations signer: the base units go back to the seller, and the quote units the seller received, both fees, and any VAT paid on chain go back to the buyer. The Console lists delivered and pending trades alike for a bust proposal.

A forced-transfer reversal is queued as one chain of transfers signed by the operations signer, each under its own fixed idempotency key. The queue confirms each transfer on chain before it queues the next, and the approval waits for the whole chain for as long as its request allows, keeping back enough time to record the outcome. When the queue does not confirm the chain in that time, the outcome is unknown, because the transfers may already be queued and still land. The bust then goes back to approved. "Resume" reads the bust's own queued transfers first. It records the bust as executed when all of them have been sent, and it re-sends under the same keys when they have not, so no transfer goes out twice. Only a reversal the queue refuses outright fails the bust.

[Figure] One event, two triggers, three consequences. Two independent triggers, a bust a second operator approved before delivery or an outside cause blocking delivery at the due time, both fire the identical DeliveryUndone event with identical bookkeeping. That one event has three consequences: both legs return to their owners, the price is corrected and dropped from clean history, and both traders are told why. Labels: Operators approve a bust,; before delivery; An outside cause blocks it,; at the due time; DeliveryUndone; Both legs return to; their owners; Price corrected, dropped; from clean history; Both traders; told why.

One event, two triggers: an operator's bust and an outside cause at delivery both fire the identical undo, with identical bookkeeping.

## Market data: what an instrument publishes [#market-data-what-an-instrument-publishes]

An instrument keeps its own price record from its trades: an official close for each session, a ticker, candles and live streams. The ticker and the candles leave out an undone trade, because a bust takes the trade out of the prices as well as out of the books. Every instrument opens and closes on a trading calendar that its venue and the instrument set together, and every venue event that concerns a participant lands in their notification list. [Venue market data](https://docs.settlemint.com/docs/concepts/issuing-and-markets/venue-market-data) explains the close, the ticker and candles, the streams, watchlists and price alerts, [the trading calendar](https://docs.settlemint.com/docs/concepts/issuing-and-markets/venue-market-data#the-trading-calendar) and [how a participant hears about an order](https://docs.settlemint.com/docs/concepts/issuing-and-markets/venue-market-data#how-a-participant-hears-about-an-order).

### Announcements [#announcements]

A venue operator publishes an announcement to the whole venue or to one instrument, and an issuer can publish one about its own security, which waits for a venue operator's approval. [Announcements](https://docs.settlemint.com/docs/concepts/issuing-and-markets/venue-market-data#announcements) covers scheduling, attachments, issuer announcements, history and publication windows.

## Controls and evidence [#controls-and-evidence]

Admission is checked when an order arrives. Revoking a participant's admission does not cancel the orders they already have resting. Cancel those from the **Orders** screen. At intake the maker must be a participant the venue admits and, on a private instrument, a participant of that instrument. Removing a wallet from a private instrument cancels its open orders on that instrument and leaves one cancellation batch. An [instrument denial](https://docs.settlemint.com/docs/concepts/issuing-and-markets/venue-market-denials) is narrower than losing admission: it bars one wallet from one instrument, records the reason and who recorded it, and leaves the venue's other instruments open to that wallet.

An access profile sets what one participant may do on one instrument: place orders, see the instrument in watchlists, see order book depth, and trade the instrument groups the profile lists. Every instrument always has a default access profile that matches its privacy: "Full access" on a public instrument, "Watchlist only" on a private one. No instrument is without one, so a participant who has no profile of their own always follows the instrument's default. A venue operator can override each setting for one participant, and a setting the override leaves out follows the profile. `PUT /api/v2/addons/trading-venues/{venueAddress}/markets/{marketId}/participants/{walletAddress}/access` replaces the profile and the overrides in one call. It needs a reason of up to 500 characters and a wallet verification, and only a platform administrator or the organisation owner can call it. A venue operator or venue admin can read the same route, which returns the profiles the instrument offers, the participant's overrides and the effective access. The effective access still honours instrument membership and any denial, so a barred wallet has no access whatever its overrides say. The instrument's participant list (`GET /api/v2/addons/trading-venues/{venueAddress}/markets/{marketId}/participants`) returns that effective access for each wallet in `access`, and the Console Participants table shows it in an Access column: the actions the wallet can take, or Denied for a barred wallet. A new order from a participant whose instrument group list holds neither the instrument's group nor `all` is refused with `instrument-group-not-permitted`.

A participant without depth access sees only the best bid and ask by default, or no book when the instrument's depth-denied mode is `none`, and no indicative quote either way. Venue operators see 50 price levels. On a public instrument, an entitled participant sees the instrument's `entitledDepthLevels` and other participants see `participantDepthLevels`, each from 1 to 50. A participant on a private instrument sees only the best bid and ask. The depth read and every stream snapshot carry `depthAccess` as `allowed`, `top-of-book` or `none`, so a client knows what the book shows. `GET /api/v2/addons/trading-venues/{venueAddress}/participants/{walletAddress}/access` gives a venue operator or venue admin one wallet's whole access to the venue: its admission, block, required verifications, freezes on the listed securities, private-instrument memberships, effective access on every instrument and approved desk limits. A wallet that is not a participant of the venue answers 404 `TRADING_VENUE_PARTICIPANT_NOT_FOUND`.

Evidence is identity-linked, sequenced, and venue-scoped: the trail carries signed orders, book events, session transitions, fills, deliveries, and undos with their reason, each naming the venue it belongs to. The platform rebuilds a book's state by replaying that trail, and it rebuilds the drop-copy reports and the daily surveillance files from the same trail. The trail is the platform's own record. Order commits, fills, deliveries and undos are also on chain, and the [retention policy](https://docs.settlemint.com/docs/concepts/issuing-and-markets/venue-retention) moves expired records to the venue archive.

Every order also has a trading member: the broker a venue operator assigned to the participant that owns the wallet, or the participant itself when it has no broker. The platform works the member out as of the moment of the order, so assigning or clearing a broker changes the member of later orders only. An earlier order keeps the member it had. Only venue operators receive the member. `PATCH /api/v2/addons/trading-venues/{venueAddress}/participants/{walletAddress}/access` assigns it. A trader or a broker never sees a member, another participant's name or the counterparty's order on the platform. The venue contract's trade events name both wallets on chain, so a reader of the chain can still link a trade to the buyer's and the seller's wallets.

A running venue changes only through the venue role each change needs, and a second holder of that role approves while the venue's Trading venues switch under Approvals is on. When the deployment enables the FIX drop copy, the venue also sends a surveillance provider each order and trade event as it records it, and the platform rebuilds a completed trading day's reports and the daily surveillance files from the same trail. [Venue controls](https://docs.settlemint.com/docs/concepts/issuing-and-markets/venue-controls) covers [who can change a running venue and who must agree](https://docs.settlemint.com/docs/concepts/issuing-and-markets/venue-controls#who-can-change-a-running-venue-and-who-must-agree), the drop copy session and its reports, the order-lifecycle file mapping, the replay and the daily surveillance files.

## The integration contract [#the-integration-contract]

For an integrator, the Trading Venue is a versioned API route group under `/api/v2/addons/trading-venues`. Chain-writing calls such as venue and instrument administration writes can answer `202` with a status URL to poll. Placing an order answers `200` with the order's id and hash once its escrow commitment confirms and the order is on the book. When the commitment has not confirmed inside the request, or the caller asked for an asynchronous answer, the call answers `202` with a `Location` header. Poll `GET /api/v2/addons/trading-venues/{venueAddress}/order-placements/{orderId}` until its status reads `placed` or `failed`. An order amendment answers the same way.

An order's own status and a trade's delivery status are two separate tracks, and reading one for the other is the mistake that costs an integrator a real position. The figure below omits one open state: `suspended`, which an instrument that suspends orders outside its price band uses between working and a close or a return to the book. It counts as open, so the order still holds its reservation.

[Figure] An order's own status: its open states, closing into one of five terminal states. An order is open while it is pending reservation, working, partially filled, or suspended outside a price band. The figure leaves out the suspended state. Armed is the state of a stop order that has reserved its balance and waits for its trigger price to trade. From any of those it closes into one of five terminal states: filled, cancelled, and expired close for the reasons their names say. Rejected means an order check of the book refused it, such as a price band, the lot size or the minimum notional. Pruned is part of the status set, and no platform path sets it. Labels: Open; pending_reservation; armed; working; partially_filled; filled; cancelled; expired; rejected; an order check refused it; pruned; in the status set, never set.

An order's own status: its open states, closing into one of five terminal states.



[Figure] A trade's delivery status: pending, then delivered or undone. A trade's delivery status starts pending. It becomes delivered once the due delivery runs, even when a refused leg waits in its receiver's escrow balance, or it becomes undone, either from an operator's bust or an outside cause blocking delivery. Both are terminal. Labels: pending; due delivery runs; bust, or an outside cause blocks it; delivered; undone.

A trade's delivery status, tracked separately from the order's own status: pending until the due delivery runs, then delivered or undone.

In the API, a trade's `status` is `pending-delivery`, `delivered` or `undone`, and an undone trade carries an `undoReason` of `bust`, `refused` or `reserver-removed`. `refused` means an outside cause blocked delivery. Any other refusal parks the refused leg, and the trade is `delivered`. `reserver-removed` marks the settlement submitter's automatic undo of a pending trade, which needs no bust proposal. An order also carries a `settlementStatus` that rolls up its trades: `none`, `pending-settlement`, `partially-settled`, `completed` or `settlement-failed`.

The full contract, every status, every field, every error, is [in the API reference](https://docs.settlemint.com/docs/api-reference/v2).

[Figure] Placing an order through to a final, reported trade state. The integrator places a signed order. The platform API commits the order in the venue's escrow and answers with the order's id and hash once the commitment confirms and the order is working on the book, or with 202 and an order placement to poll when the commitment has not confirmed inside the request. After a match, the platform submits a fill batch to the venue contract, which reports fill events with a delivery due date. The integrator's status becomes filled with delivery pending. When the due delivery runs, the venue contract moves both legs and the fee and reports back delivered, or undone with a reason. The integrator's final status reflects that outcome. Labels: Integrator; Platform API; Venue contract; place signed order on a venue's instrument; commit through the venue's escrow; commitment confirmed; order id and hash, working; submit fill batch after a match; fill events, delivery due after the; holding period; status: filled, delivery pending; due delivery moves; both legs and the fee; delivered, or undone with its reason; final trade state.

Place a signed order, treat it as working only after its commitment confirms, and treat units as received only after the trade reports delivered.

## Frequently asked questions [#frequently-asked-questions]

### What is the difference between a venue and an instrument?

A venue is a tenant's own exchange: its own on-chain identity, access manager, admission policy, calendar, and escrow, and a tenant runs as many as it needs. An instrument is one trading line on one venue. The same pair listed on two venues is two instruments, with separate order books, reservations, trade histories, and prices, and halting one leaves the other trading.

### What does an issuer give up by listing a token on a venue?

Custodian power over the token, held by the organisation's operations signer and not by the venue. A bust lends that account the custodian role on the token for the reversal alone, when the listing signer can grant roles there, and takes it back when the reversal ends. The venue contract itself holds no custodian role, and listing needs no hold feature and no reserver authorisation from the issuer. Traders approve the venue's escrow, and the escrow moves only the units an order committed. The escrow's identity carries a `dalpEscrow` claim and sits on the compliance bypass list, and a token with holding rules exempts that claim. The platform lends the operations signer's custodian role only to reverse a delivered trade after an approved bust.

### Who holds the assets while an order is working?

In the venue's escrow, for a DALP token and a plain ERC-20 alike. Units a trader deposits sit there as free balance until an order locks them. A locked amount leaves the escrow at delivery, and an unlock returns it to the trader's free balance. Free balance leaves to its owner when they withdraw it, or when the submitter pays it to its owner, and an owner can reclaim a lock after the order's signed expiry. A trader can cancel their own order on the venue contract and withdraw without the platform. A holder of the venue operator or venue submitter role can also cancel any trader's order on chain, and can bulk-cancel a trader's orders by raising their cancel epoch by one. A single call raises the epoch by one at most, so no one can push it so high that the trader can no longer bulk-cancel. Two things follow. A venue upgrade does not repair a trader whose epoch an operator or submitter had already pushed to the maximum: the epoch never falls, because lowering it would bring cancelled orders back to life. That trader can still cancel orders one at a time. And two bulk cancels sent against the same epoch race: the second reverts, so a client reads the trader's epoch from the venue right before it sends. The other exits are a venue admin's sweep of units no owner is owed, a forced transfer by a holder of the token's custodian role, and a recovery, which any account can trigger, of a lost wallet's free balance to the wallet the identity registry names as its replacement.

### Can the operator reverse a trade?

Only through a bust, proposed within 24 hours of the trade once neither of its orders is still open. With the "Trading venues" row under "Approvals" on, a different operator must approve the bust before it runs. With it off, the bust runs when it is proposed. Before delivery, the approved bust releases the trade. Both legs are still locked, so the settlement service undoes the trade on the venue by unlocking them to their owners' free balances. No fee has moved, and nothing is forced back from anyone. The proposal holds the trade on the venue until the decision, so delivery cannot overtake it. If the delivery remains pending after the review window closes, the settlement service still submits the approved release. Once the trade is delivered, the venue offers no undo. An approved bust then reverses the trade with custodian forced transfers under the operations signer, from the Console or the Platform API. The Console's "Trade busts" tab offers **Propose bust…** for delivered and pending trades alike.

### Is an undo the same as a refund?

No. A refund returns something that was paid. Before delivery, nothing has been paid: both legs are still locked in the escrow, so an undo unlocks them back to their owners' free balances and moves nothing. A bust of a delivered trade is different: forced transfers move both legs, both fees and any VAT paid on chain back, which reverses the delivery itself.

### Who sets trading fees and who receives them?

Each instrument carries its own maker and taker fees, in basis points of the quote leg, and its own fee account, all set when the instrument is listed. Zero is a valid rate. A platform administrator or organisation owner changes them later through instrument configuration, signing with a wallet that holds the venue operator role on that venue. The fee moves at delivery, in the same transaction as the legs, to the fee account the instrument holds at that moment, or to the recipients of the settlement's fee route. The contract caps the fee at the order's signed maximum and checks that the route adds up.

### Does the venue provide liquidity or market makers?

No. The venue matches and settles orders, and it never supplies capital or acts as a counterparty. Convening liquidity stays a decision for the operator.

## Related concepts [#related-concepts]

- [Asset Lifecycle](https://docs.settlemint.com/docs/concepts/issuing-and-markets/asset-lifecycle): The whole working life of a regulated tokenised instrument, from issuance through servicing to redemption. Settling trades is one of the operations this venue performs inside that same life.
- [Primary Offering](https://docs.settlemint.com/docs/concepts/issuing-and-markets/primary-offering): The contract-governed first sale of newly issued units to investors, the issuance step this venue's whole life continues from.
- [XvP Settlement](https://docs.settlemint.com/docs/concepts/settlement/xvp-settlement): An on-chain exchange between two or more parties in which every leg settles together in one transaction or none does. It is the platform's bilateral settlement primitive, without an order book.
- [Settlement Verdict](https://docs.settlemint.com/docs/concepts/settlement/settlement-verdict): The recorded end state of an on-chain operation submitted to the platform, and the only signal from which the success of the operation may be reported.
- [Market Data](https://docs.settlemint.com/docs/concepts/records-and-evidence/market-data): The governed on-chain source for prices, valuations, and exchange rates. A token's reference instrument writes its official close to that token's price feed, when the token has one.


# Venue controls and evidence

Source: https://docs.settlemint.com/docs/concepts/issuing-and-markets/venue-controls
How a Trading Venue checks admission, which roles change a running instrument and who must agree, and the FIX drop copy and surveillance files it produces.

A [Trading Venue](https://docs.settlemint.com/docs/concepts/issuing-and-markets/trading-venue) is a tenant's own exchange for tokenised assets. It checks a participant's admission on every new order and ties each change to a running instrument to a venue role. When the deployment enables its FIX drop copy, it also sends a surveillance provider each order and trade event as the venue records it. The Trading Venue page explains how an order becomes a delivered trade.

Admission is checked when an order arrives. Revoking a participant's admission does not cancel the orders they already have resting. Cancel those from the **Orders** screen. At intake the maker must be a participant the venue admits and, on a private instrument, a participant of that instrument. Removing a wallet from a private instrument cancels its open orders on that instrument and leaves one cancellation batch. An [instrument denial](https://docs.settlemint.com/docs/concepts/issuing-and-markets/venue-market-denials) is narrower than losing admission: it bars one wallet from one instrument, records the reason and who recorded it, and leaves the venue's other instruments open to that wallet.

Evidence is identity-linked, sequenced, and venue-scoped: the trail carries signed orders, book events, session transitions, fills, deliveries, and undos with their reason, each naming the venue it belongs to. The platform rebuilds a book's state by replaying that trail, and it rebuilds the drop-copy reports and the daily surveillance files from the same trail. The trail is the platform's own record. Order commits, fills, deliveries and undos are also on chain, and the [retention policy](https://docs.settlemint.com/docs/concepts/issuing-and-markets/venue-retention) moves expired records to the venue archive.

Every order also has a trading member: the broker a venue operator assigned to the participant that owns the wallet, or the participant itself when it has no broker. The platform works the member out as of the moment of the order, so assigning or clearing a broker changes the member of later orders only. An earlier order keeps the member it had. Only venue operators receive the member (`PATCH /api/v2/addons/trading-venues/{venueAddress}/participants/{walletAddress}/access` assigns it). A trader or a broker never sees a member, another participant's name or the counterparty's order on the platform. The venue contract's trade events name both wallets on chain, so a reader of the chain can still link a trade to the buyer's and the seller's wallets.

## Who can change a running venue, and who must agree [#who-can-change-a-running-venue-and-who-must-agree]

An operator changes a running instrument through a fixed set of controls, each tied to a venue role. Whether a control waits for a second person follows one organisation setting, the **Trading venues** row under "Approvals" on the "General" page of "Organisation settings", and an exception there can turn it on or off for one venue. With the row on, a different holder of the required role must approve, and the platform refuses a decision from the person who proposed. With the row off, the change applies at once and "Actions" logs it as "No second approval (approval off)".

| Control | What it changes | Role | With the Trading venues row on |
| --- | --- | --- | --- |
| Desk limit | Caps the open order value one trader wallet may carry on one instrument. Intake refuses an order that would pass the latest approved limit | Venue operator | A second operator approves. An undecided proposal lapses after a configurable window, 24 hours by default |
| Trade bust | Undoes a trade within 24 hours of it, before or after delivery | Venue operator | A second operator approves. An undecided proposal lapses like a desk limit |
| Order cancel and mass cancel | Cancels one open order, or every open order that matches a filter. A mass cancel leaves one cancellation batch per instrument | Venue operator | A second operator approves |
| Venue configuration | The venue calendar and its closed days, the venue price band, admission, listing rules (including order-rule limits and starting values), the [VAT](https://docs.settlemint.com/docs/concepts/issuing-and-markets/venue-vat) and [retention](https://docs.settlemint.com/docs/concepts/issuing-and-markets/venue-retention) policies, and resuming the venue | Venue admin | A second venue admin approves within 24 hours. A pending change blocks a second proposal for the same setting, and an approval whose recorded before-state no longer matches the live configuration is refused |
| Venue approval requirement | Switches the venue's second-person requirement off, or lets an emergency halt skip it | Venue admin | A second venue admin approves, even when the venue has no other admin yet: add one first. Switching the requirement on, or tightening the emergency halt, applies at once. With the row off there is nothing to approve, so the change applies at once |
| Instrument configuration | Instrument listings, instrument calendars, collection windows, price bands, instrument fields and limits such as the holding period, fees, fee tiers, instrument transitions, scheduled and dated changes, participant removal, and pausing the venue | A platform administrator or the organisation owner, signing with a venue operator wallet | A venue operator other than the proposer approves, on the same terms as venue configuration |
| Emergency halt | Halts one instrument at once, through the Platform API | Venue operator | Runs at once when a venue admin allowed emergency halts for the venue and the halt request asks for one. It records the halt as executed, with no checker, and a resume is its own request. Resume and delist never take this path |
| Instrument groups | Defines the groups, such as equities or fixed income, that the venue sorts its instruments into | Venue admin | Applies at once |

The second approval binds the Console and the Platform API. A holder of the venue operator role can also cancel any order directly on the venue contract, or flag and clear a pending trade there, with no second approval, and that cancel does not name its caller on chain. A venue administrator grants and revokes the venue operator and venue submitter roles through the Platform API.

The same venue keeps read-only records an auditor can check against these controls. The Orders screen lists every order submitted to the venue. Each operator action that cancels orders in bulk leaves a cancellation batch with the operator, the reason and the orders it closed. The settlement instructions show which token moved from whom to whom for each trade. **Held settlement fills** lists the fills settlement could not complete, each with its reason. The venue read, `GET /api/v2/addons/trading-venues/{venueAddress}`, adds a summary: the orders resting now and the instruments they rest in, the trades of the last 24 hours and of the 24 hours before, the settlement batches that fully delivered in each of those windows, and the batches still awaiting delivery. An undone trade counts in none of them. [Venue operations](https://docs.settlemint.com/docs/console/asset-lifecycle/venues), [Orders](https://docs.settlemint.com/docs/console/asset-lifecycle/venues/orders), [Mass cancellations](https://docs.settlemint.com/docs/console/asset-lifecycle/venues/mass-cancellations), [Instrument](https://docs.settlemint.com/docs/console/asset-lifecycle/venues/instrument) and [Trading calendar](https://docs.settlemint.com/docs/console/asset-lifecycle/venues/trading-calendar) cover each control and record in the Console.

## How the drop copy session runs [#how-the-drop-copy-session-runs]

The drop copy is one Financial Information eXchange (FIX) session from one venue to one surveillance provider, and the provider sees each order and trade event as the venue records it. It runs FIX 5.0 SP2 over the FIXT.1.1 session layer. The session belongs to the deployment's configuration, not to a Console setting. It stays off until it is enabled with the venue's network and address, the port, the SenderCompID and TargetCompID, the time reporting starts from and the venue's market identifier code. A session that dials out also needs the provider's host name. The Console has no drop copy screen. An operator reaches the session's output through the venue reports API: the replay preview and request, and the daily file list and download.

The session either dials the provider or waits for the provider to dial in. Dialling out is the default and uses TLS unless the configuration turns it off. Waiting for the provider needs three settings, and the configuration is refused without any of them: the provider's host on the session's allow list, plain TCP over a private link, and no sequence reset at logon. For an incoming session, the deployment must also make the listening port reachable from the provider, and it does not do that by default.

One process holds the session at a time. When the provider's sequence numbers skip, the session asks for a resend. A SequenceReset whose NewSeqNo is missing or lower than the number the session expects ends the session. The expected number never moves backwards. An incoming message body longer than 65,536 bytes is refused. Once each UTC day the session also sends start-of-day position reports, built from indexed balances at midnight UTC. While the balances, accounts or instrument mappings for the day are incomplete, the session sends no positions and tries again through that UTC day. It never reports a missing balance as zero.

An undone trade reaches the provider as a Trade Cancel ExecutionReport (`150=H`) on each leg. Its Text (58) carries the undo reason, such as `bust` for an approved bust or `refused` for a delivery an outside cause blocked. The leg of the side that failed delivery adds `;failed-side`, and a report timed by the trade's execution time, because no undo time was recorded, adds `;undo-time-unrecorded`.

## What each drop copy report carries [#what-each-drop-copy-report-carries]

The drop copy sends one FIX ExecutionReport for each order and trade event, and one for each new, validly signed order that intake refused. It also sends instrument events in the same sequence: SecurityStatus (`35=f`) carries halts, resumes, suspensions, band changes, configuration changes and official close, while TradingSessionStatus (`35=h`) carries session transitions. These messages carry the symbol and the status or session fields a surveillance system uses to attribute and time the event, and they support the same resend path as order reports.

The field table below describes order and trade ExecutionReports (`35=8`). Instrument messages (`35=f` and `35=h`) use the status, session and configuration fields described above.

Instrument status reports use `326=2` for halted, `326=3` for resumed and `326=4` for suspended or delisted. Band reports use `326=6` with `332` and `333` when bounded, while session reports use `340=4/2/5/3` for pre-open, open, closing auction and closed. An auction collection reports as open (`340=2`), and a Trade-At-Last session reports as open (`340=2`) with `625=5` for post-trading on that report only.

A volatility interruption reaches the provider as a sequenced SecurityStatus message (`35=f`). When it starts, the report carries `326=2`, the trigger price in LastPx (31) and a Text (58) of `volatility-interruption:started:resumes-at=<time>:reference=<price>`. When it ends, the report carries `326=3` and the Text `volatility-interruption:ended`.

| FIX field | Carried on | Value |
| --- | --- | --- |
| PartyID (448), PartyIDSource (447), PartyRole (452) | Fills and trade cancels | The account mnemonic of the other side of the trade, sent as a custom-coded party with role 37 (contra trader). The venue knows participants by wallet, so the mnemonic from the drop copy account map stands in for a trader id, and a wallet the map does not name is sent as its address. |
| ManualOrderIndicator (1028) | Every order/trade report (`35=8`) | `N`. Every order is signed by the maker's wallet. The venue has no path for an operator to place an order for a client. |
| OrdType (40) | Every order report (`35=8`) | `1` market, `2` limit, `4` (stop-limit) for an order placed as a stop. An armed stop sends no report. The New report arrives when the stop fires and joins the book, and carries StopPx. |
| StopPx (99) | Reports for a stop order | The trigger price, in the same decimal form as Price. |
| Capacity (528) | Reports for an account with a profile | `P` for a principal account, `G` when proprietary is set, `A` for agency, `W` for sponsored. Sponsored takes precedence when both sponsored and proprietary are configured. An account without a profile carries no Capacity. |
| ExecInst (18) | Reports for a fill-or-kill order | `G` (all or none). Other orders carry no ExecInst. |
| OrigTime (42) | Every order/trade report (`35=8`) | The order acceptance time in UTC, kept across its reports. A refusal report carries the refusal time instead, because the order was never accepted. |

The first restart after an upgrade that changes these fields rebuilds the drop copy's saved order state from the venue log.

## Order-lifecycle file mapping [#order-lifecycle-file-mapping]

The order-lifecycle (OLC) file is a comma-separated file with a fixed 68-column schema. The platform builds the file from the drop-copy reports, and a venue operator lists and downloads the files for a finished trading day from the venue reports API. The file opens with a header row and holds one row per order or trade report. Market status and session messages are left out. Every value keeps printable ASCII characters only, and a time is epoch seconds with three decimals. The mapping below records the source used for each column. `empty` means that the drop-copy report does not carry a value for that field.

| OLC column | Source | Mapping note |
| --- | --- | --- |
| `TM` | report transaction time | Epoch seconds. |
| `ORIG_TIME` | FIX tag 42 | OrigTime, the order acceptance time, parsed to epoch seconds. |
| `SENDING_TIME` | empty | The report does not carry the session sending time. |
| `TRANSACT_TIME` | report transaction time | Epoch seconds for every event type. |
| `SIDE` | FIX tag 54 |  |
| `QTY` | FIX tags 32, 151, 38, and 14 | Fill size for F/G/H, remaining quantity from tag 151 for 5/E, exact order quantity minus cumulative fills for 4/8/9/C/I, and otherwise order quantity. |
| `PRICE` | FIX tag 31, 99, or 44 | Last price for F/G/H, limit price for 4/I, and `0` for a market order. A stop-limit order uses the limit price, then the stop price. Any other order uses the stop price when present, then the limit price. |
| `SYMBOL` | FIX tag 55 |  |
| `SECURITY_ID` | FIX tag 48 |  |
| `CLIENT_OID` | FIX tag 11 |  |
| `EXEC_ID` | FIX tag 17 |  |
| `VENUE_OID` | FIX tag 37 |  |
| `SECONDARY_CLIENT_OID` | empty | No secondary client order ID in the report. |
| `SECONDARY_EXEC_ID` | empty | No secondary execution ID in the report. |
| `COUNTERPARTY_ID` | FIX tag 448 | Contra-party ID from the party block. Empty on a report that has no party block. |
| `ACCOUNT` | FIX tag 1 |  |
| `ROOT_SYMBOL` | empty | No root symbol is present in the report. |
| `TRADEID` | FIX tag 880 |  |
| `TRD_MATCH_ID` | FIX tag 880 | Same trade ID. No distinct match ID is present. |
| `SELF_MATCH_PREVENTION_ID` | empty |  |
| `CURRENCY` | FIX tag 15 |  |
| `SENDER_COMP_ID` | drop-copy settings SenderCompID | Empty when the settings name no SenderCompID. |
| `SENDER_SUB_ID` | empty | The drop-copy settings carry no sender SubID. |
| `TARGET_COMP_ID` | drop-copy settings TargetCompID | Empty when the settings name no TargetCompID. |
| `TARGET_SUB_ID` | empty | The drop-copy settings carry no target SubID. |
| `DELIVER_TO_COMP_ID` | empty | The drop-copy settings carry no deliver-to CompID. |
| `DELIVER_TO_SUB_ID` | empty | The drop-copy settings carry no deliver-to SubID. |
| `EXEC_BROKER` | empty |  |
| `TEXT_NOTE` | FIX tag 58 | Commas are removed, and so is any leading space, `=`, `+`, `-` or `@`. |
| `CLEARING_ACCOUNT` | empty |  |
| `CLEARING_FIRM` | empty |  |
| `ISIN` | FIX tag 48 when tag 22 is `4` | Empty for other security ID sources. |
| `EXEC_INST` | FIX tag 18 |  |
| `TIME_IN_FORCE` | FIX tag 59 |  |
| `EXPIRE_TIME` | FIX tag 126 | Parsed to epoch seconds. |
| `LAST_MKT` | FIX tag 30 |  |
| `EX_DESTINATION` | empty | No distinct execution destination is present. |
| `SECURITY_EXCHANGE` | FIX tag 30 | Same instrument identifier as `LAST_MKT`. |
| `ORD_TYPE` | FIX tag 40 |  |
| `CAPACITY` | FIX tag 528 |  |
| `ORIG_CLIENT_OID` | FIX tag 41 |  |
| `RELATED_ID` | Earliest known order ID in the file | Keeps the same root across replacement reports. When earlier reports are outside the file, retains the earliest available tag 41, and otherwise tag 11. |
| `ON_BEHALF_OF_COMP_ID` | empty | The drop-copy settings carry no on-behalf-of CompID. |
| `ON_BEHALF_OF_SUB_ID` | empty | The drop-copy settings carry no on-behalf-of SubID. |
| `CUM_QTY` | FIX tag 14 |  |
| `LEAVES_QTY` | FIX tag 151 |  |
| `CFI_CODE` | empty |  |
| `MATURITY_DATE` | FIX tag 541 | The drop-copy reports do not carry this tag, so the column is empty. |
| `PUT_OR_CALL` | FIX tag 201 | The drop-copy reports do not carry this tag, so the column is empty. |
| `STRIKE_PRICE` | FIX tag 202 | The drop-copy reports do not carry this tag, so the column is empty. |
| `OPEN_CLOSE` | FIX tag 77 | The drop-copy reports do not carry this tag, so the column is empty. |
| `TRADE_CLIENT_ID` | empty | No distinct trade-client ID is present. |
| `VENUE` | FIX tag 30 |  |
| `ORD_STATUS` | FIX tag 39 |  |
| `LOCATEREQD` | empty |  |
| `CLIENT_TAGS` | empty | No client tags are present in the report. |
| `DISPLAY_QTY` | empty |  |
| `OPERATOR_ID` | empty | The drop-copy report carries no operator identity. |
| `SPREAD_ID` | empty |  |
| `MSG_CLASS` | FIX tag 150 and tag 39 | `FILL` for `F` with tag 39 `2`, `PARTIAL_FILL` for other `F`, `SUSPENDED` for `9` with tag 39 `9`. Other combinations map to a fixed class, or empty. |
| `IS_OPERATIONAL` | constant | `1`. |
| `SOD` | constant | `0`. The file carries no start-of-day snapshot rows. |
| `LEG_FILL` | constant | `0`. No leg fills are present. |
| `STOP` | FIX tag 99 and tag 40 | `1` when StopPx is present or order type is stop-market or stop-limit, otherwise `0`. |
| `SPREAD` | constant | `0`. No spread orders are present. |
| `TAG_1028` | FIX tag 1028 |  |
| `GEO_LOCATION` | empty |  |
| `AGGRESSOR` | FIX tag 1057 | `Y` becomes `1`, `N` becomes `0`. Other values are empty. |

The drop-copy reports carry no spread, leg, trader or operator identity, so `SPREAD_ID` and `OPERATOR_ID` stay empty, `LEG_FILL` and `SPREAD` are `0`, and `RELATED_ID` carries the replacement ancestry.

The report body supplies the event fields. The body holds no session identifiers, so `SENDER_COMP_ID` and `TARGET_COMP_ID` come from the SenderCompID and TargetCompID in the venue's drop-copy settings, and the other session columns stay empty.

## Replaying a completed trading day [#replaying-a-completed-trading-day]

A provider can lose messages after acknowledging them, and the venue answers with the day it already recorded rather than new trading. A replay sends one trading day over the same FIX session: stored bodies go back as they were first sent, and only the reports the provider refused are built again.

An operator previews the day before asking for it. `GET /api/v2/addons/trading-venues/{venueAddress}/reports/{tradingDay}/replay` reads the day and changes nothing:

```json
{
  "data": {
    "tradingDay": "2026-06-12",
    "ended": true,
    "regenerated": 0,
    "stored": 1284,
    "differing": [],
    "issues": [],
    "request": null
  },
  "links": {
    "self": "/api/v2/addons/trading-venues/0x7f3c2b5e8a1d4c6f9b0e2a5d8c1f4b7e0a3d6c9f/reports/2026-06-12/replay"
  }
}
```

`stored` counts the reports the first send kept for the day, and `regenerated` counts the ones this preview built again from the venue log, plus the stored instrument reports that have no rebuild. `issues` lists what the venue log could not be mapped into. `differing` lists the exec ids whose rebuilt body differs from the body the provider received, which is how a divergence between the log and the provider's copy shows before a resend goes out. `ended` is false while the UTC day is still running, and the preview answers in that case too, so an operator sees the day take shape.

`POST .../replay-requests` records the request and answers with the queued entry:

```json
{
  "data": {
    "id": "0b7c1f5e-2f2a-4c39-9a51-1d3f2c8e4b60",
    "requestedAt": "2026-06-13T08:12:44.000Z",
    "enqueuedAt": null,
    "reportCount": null
  },
  "links": {
    "self": "/api/v2/addons/trading-venues/0x7f3c2b5e8a1d4c6f9b0e2a5d8c1f4b7e0a3d6c9f/reports/2026-06-12/replay"
  }
}
```

`enqueuedAt` and `reportCount` stay null until the session that holds the drop-copy lease has built and queued the day, and that session fills both in the same write. The two null fields are the state an operator watches: a request still waiting while the session runs means the day cannot be built, and the platform logs the exec ids it could not rebuild and the mapping issues it met. A day that cannot be built sends nothing, because a partial day leaves the provider further from the venue log than it was.

A replay sends each report of the day with its own exec id and PossResend (97) set to `Y`. A report the provider accepted keeps the body it first carried, and a report the provider refused when it was first sent is built again from the venue log. An instrument report whose transition was polled from the venue instead of derived from the engine log has no rebuild, so its stored copy is sent. Each resent message takes a new sequence number from the session, and the provider reads it by its exec id.

A venue the drop-copy settings do not name and a session that is not enabled answer both calls with 409 and DALP-14389, and so does a request for a day that has not ended. Both calls need the venue operator or venue admin role, and the request also needs a wallet verification.

## Exporting the daily surveillance files [#exporting-the-daily-surveillance-files]

The FIX session is the venue's real-time drop copy. A daily file is the other way to hand a provider the venue's activity, in one of two formats, and the OLC file mapped above is one of them. Both are rebuilt from the venue log with the same mapping that builds the drop-copy reports, so a file and the FIX feed describe a day with the same fields.

VALCSV is an optional drop-copy transport for a provider that takes a finished day as a file instead of, or next to, the FIX session. For each asset class it carries an order lifecycle file with one row for each order and trade report of the day: accepted orders, replacements, fills, cancels, expiries, intake refusals and Trade Cancels, with the instrument halts, session changes and other instrument reports left out. Its 22 columns hold the side, symbol, account mnemonic, quantity, price, venue and client order ids, leaves quantity, time in force, market identifier code, transaction time, execution type, order status and type, the report's Text, and a JSON column with the trade id, aggressor flag, execution reference, security id and currency. Next to those files it carries one accounts file that lists each account profile with its capacity, ISO approval, market maker and proprietary flags, supervisor, aggregation unit and label. OLC carries one order lifecycle file per asset class with its 68 columns.

`GET .../reports/{tradingDay}/files?format=valcsv` answers with the day's file names and byte sizes, or the reasons that stop them:

```json
{
  "data": {
    "tradingDay": "2026-06-12",
    "format": "valcsv",
    "reports": 1284,
    "issues": [],
    "files": [
      { "name": "valcsv_NORTHWIND_EQ_20260612.csv", "bytes": 481203 },
      { "name": "valcsv_accounts_NORTHWIND_20260612.csv", "bytes": 412 }
    ]
  },
  "links": {
    "self": "/api/v2/addons/trading-venues/0x7f3c2b5e8a1d4c6f9b0e2a5d8c1f4b7e0a3d6c9f/reports/2026-06-12/files"
  }
}
```

A file is named `<format>_<exchange OMS name>_<asset class>_<YYYYMMDD>.csv`, and the accounts file is `valcsv_accounts_<exchange OMS name>_<YYYYMMDD>.csv`. The exchange OMS name and the asset class of each instrument come from the venue's drop-copy settings.

`files` stays empty while `issues` is not, and an issue names what blocks the day: the UTC day has not ended, a trade of the day is still pending delivery, an approved bust of the day has not executed, a venue instrument has no asset class mapped, a report cannot be built from the venue log, or, for VALCSV, an account in the reports has no profile.

`GET .../reports/{tradingDay}/files/{fileName}` returns one file as `text/csv` with an attachment disposition and records the download in the request audit trail. A name the day does not produce answers 404 with DALP-14390.

These files need no live FIX session. A venue turns VALCSV on in the deployment's drop-copy settings, not in the Console: the venue's chain and address (`TRADING_VENUE_DROP_COPY_CHAIN_ID`, `TRADING_VENUE_DROP_COPY_VENUE_ADDRESS`), an exchange OMS name (`TRADING_VENUE_DROP_COPY_EXCHANGE_OMS_ISV`), an asset class on every instrument in `TRADING_VENUE_DROP_COPY_INSTRUMENTS`, and, in `TRADING_VENUE_DROP_COPY_ACCOUNT_PROFILES`, a profile for every account mnemonic the day's reports name. `TRADING_VENUE_DROP_COPY_ENABLED` can stay `false`. The platform does not push the files: a venue operator or venue admin lists and downloads a finished day through the routes above, or a platform operator writes it to a directory with the scheduler's operations command `drop-copy valcsv --date YYYY-MM-DD --out DIR`, and the venue delivers the files to its provider. VALCSV is off by default. A venue that reports to its provider over the FIX session alone leaves the exchange OMS name unset, and every file request for it then answers 409 with DALP-14389.


# Venue journey

Source: https://docs.settlemint.com/docs/concepts/issuing-and-markets/venue-journey
Follow one security from listing on the trading venue through the identity check, funding, trading, settlement, positions, reports, and the session close.

This page follows one security through its whole life on a trading venue, in the order a real participant meets it: an operator lists an instrument, an investor passes identity checks, funds a wallet, places an order, and the platform matches it and settles it. It ends with the positions, statements, and shareholder lists that record the result. Step 1 can happen before, during, or after steps 2 to 4, but steps 2 to 4 run in order, and steps 5 to 7 run on every order. Each step names the screen where a person does the work and the Platform API route behind it. Use it to see how the other pages fit together. It does not replace them, and each step links to the page that holds the detail.

A trading venue is the contract and the services around it that run one or more instruments. An instrument is one trading line: a base token that is bought and sold, and a quote token that pays for it. [Venue operations](https://docs.settlemint.com/docs/console/asset-lifecycle/venues) covers the operator side, and [Trading](https://docs.settlemint.com/docs/console/my-assets/trading) covers the order ticket in detail. The [Trading Venue](https://docs.settlemint.com/docs/concepts/issuing-and-markets/trading-venue) concept explains why the design looks the way it does.

[Figure] The venue journey in eight steps, from listing to positions and reports. Step 1: an operator lists the instrument. Step 2: the investor completes identity checks on the Profile page. Step 3: the eligibility claim reaches the chain after an approved provider verdict or from a trusted issuer. Step 4: the investor funds a wallet with the quote token. Step 5: the investor signs and places an order in the Investor portal. Step 6: the venue matches orders by price, then by time. Step 7: fills settle on chain in batches, and each fill moves both legs together or fails as a whole. Step 8: positions, statements, and shareholder lists record the result. Labels: Venue journey; 1 Listing; operator lists it; 2 KYC; identity checks; 3 Claim; eligibility on chain; 4 Funding; quote token deposit; 5 Order; signed in the Portal; 6 Match; price, then time; 7 Settlement; both legs or neither; 8 Records; positions and reports.

Steps 1 to 4 prepare the instrument and the investor, steps 5 to 7 run on every order, and step 8 reads what the first seven wrote.

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

- The token that the venue lists already exists.
- A platform administrator or the organisation owner lists the instrument, signing with a wallet that holds the venue operator role on the venue.
- The organisation's operations signer holds the venue submitter role.
- The investor has a custodial wallet, whose keys the platform's custody provider holds and signs with after the investor verifies the wallet, or a self-custody wallet, whose keys the investor holds. The platform holds no key for a self-custody wallet, so the investor's wallet signs each order itself, as [Orders from a self-custody wallet](#orders-from-a-self-custody-wallet) describes.

Every order commits its units in the venue's escrow, for a DALP token and a plain ERC-20 alike: the venue deposits whatever the trader's free escrow balance lacks from the trader's wallet and locks the order's amount, so the units cannot be spent twice. Every trade has two legs, the base token and the quote token, and both settle through that escrow.

## Step 1: an operator lists the instrument [#step-1-an-operator-lists-the-instrument]

An operator lists the instrument in the Console under "Venues", with "List instrument" in the header of the venue page. The wizard sets the base and quote token, the tick size (the smallest price step) and lot size (the smallest quantity step), the maker and taker fees in basis points, the market-order protection band (a limit on how far a market order may walk the book), and the trading calendar. The platform checks the listing before it accepts it, and the instrument stays pending until its listing ceremony completes. That checklist covers the feed writer, the fee account, a trading schedule or collection window, the trading model, the prices, and the venue's listing rules. [Venue operations](https://docs.settlemint.com/docs/console/asset-lifecycle/venues) describes every field and the ceremony checklist, and [Venue market settings](https://docs.settlemint.com/docs/console/asset-lifecycle/venues/instrument#most-listing-choices-get-a-later-edit-some-do-not) says which choices can be edited later.

![List a new instrument wizard at the Pair step](https://docs.settlemint.com/docs/screenshots/console-venue-journey-list-market.light.en.webp)

[Screenshot] The "List a new instrument" wizard at its "Pair" step, with the base and quote token fields.

The venue's "Listing rules" page sets a default price band, initially Off: a static minimum and maximum quote price, or a dynamic percentage range. Each instrument can inherit it, turn it off, or override it. A dynamic band starts around the previous official close, expands only the side reached by a trade up to its cap, and resets at the next session close. [Venue operations](https://docs.settlemint.com/docs/console/asset-lifecycle/venues) covers these controls and their effect on resting orders.

The same page can hold starting values for the fees, the fee account, the protection band and the holding period. The wizard opens with them filled in, and the operator can change each one. The values are copied when the wizard opens, so the listed instrument keeps its own after that. The page can also limit the order types and the time in force that every instrument on the venue accepts. The limit reaches instruments already listed, and a listing that asks for an option outside it is refused.

Listing does not require a primary offering. No listing check asks about one, so a token that was issued directly and never sold through an offering can be listed.

The Platform API keeps the earlier name for an instrument: its routes use `/markets` and the instrument's id is `marketId`.

| What happens | Route |
| --- | --- |
| The wizard checks the venue roles, the operations signer, and that the pair is free | `GET /api/v2/addons/trading-venues/:venueAddress/listing-preflight` |
| The operator creates the instrument | `POST /api/v2/addons/trading-venues/:venueAddress/markets` |
| The operator halts, resumes, or delists it | `POST /api/v2/addons/trading-venues/:venueAddress/markets/:marketId/transitions` |

## Step 2: the investor passes identity checks [#step-2-the-investor-passes-identity-checks]

The investor completes know your customer (KYC) identity verification on the "Profile" page of the Investor portal, which opens from the account menu. Onboarding sets up the investor's wallet and does not include identity verification. On the "Information" card, the investor enters personal details, such as name, country of residence, national ID, date of birth and residency status, and selects "Save". Under "Identity documents", the investor selects "Create new draft" when no draft is open, uploads the documents, and selects "Submit for review". The saved details show "Waiting for review" until an operator reviews them in the Console, and then show "Approved" or "Changes requested". An approval updates the status of the details and does not issue the eligibility claim. The claim comes from the provider's verdict, as [Step 3](#step-3-the-eligibility-claim-reaches-the-chain) describes, or from a trusted issuer in the Console, as [Verify a participant](https://docs.settlemint.com/docs/console/participants/verify-a-participant) describes.

When the organisation has a verification provider and the investor's identity has no eligibility claim for KYC, the page also shows the provider's check. For that check the platform asks the provider for a short-lived SDK token, and the investor sends documents to the provider directly. After the investor finishes, the page checks for the claim every 10 seconds for up to 15 minutes and shows "Identity verified" once it arrives. The sequence an operator or an integrator runs, from creating the user to registering the identity, is in [Onboard an investor](https://docs.settlemint.com/docs/api-reference/guides/onboard-an-investor). Adding the provider is a one-time Console task in [Compliance providers](https://docs.settlemint.com/docs/console/compliance/compliance-providers).

![The Investor portal Profile page with the Information card, Identity details and Identity documents](https://docs.settlemint.com/docs/screenshots/portal-venue-journey-identity-checks.light.en.webp)

[Screenshot] The "Information" card of the Profile page, with the "Approved" state, the identity fields and the "Identity documents" section.

The card shows the first name, last name, country of residence and national ID fields, then "Identity details" with date of birth and residency status, each field with its own status, and the "Save" button. The national ID is masked in this image.

| What happens | Route |
| --- | --- |
| An identity manager creates the user and the custodial wallet | `POST /api/v2/users` |
| The identity manager registers the identity under a country | `POST /api/v2/system/identity-registrations` |
| The investor's app requests the provider SDK token | `POST /api/v2/compliance/subjects/sdk-access-token` |
| "Save" stores the personal details | `PATCH /api/v2/users/:userId/profile` |
| "Create new draft" opens a document draft | `POST /api/v2/kyc-profiles/:userId/versions` |
| "Submit for review" submits the draft | `POST /api/v2/kyc-profile-versions/:versionId/submissions` |

## Step 3: the eligibility claim reaches the chain [#step-3-the-eligibility-claim-reaches-the-chain]

The eligibility claim is the on-chain statement that an identity passed a check, such as KYC. An approved provider verdict issues the claim, a rejected verdict revokes it, and a monitoring alert at or above the topic's threshold can revoke it later. The investor does nothing in this step. The platform acts on the provider's signed verdict, or a trusted issuer issues the claim in the Console.

The claim matters twice. The venue's admission policy can require named claim topics, such as a KYC topic, before a wallet sees or trades an instrument, and each token's own rules judge every delivery. A missing, expired, or revoked claim rejects a new order with `identity-not-verified`. A wallet on the security's block list or frozen on the base token is rejected with `suspended-wallet`. Orders that already rest on the book stay there, because revoking a claim does not cancel them. A fill delivers only when each recipient still passes the receiving token's checks, so a buyer who lost the claim fails at delivery while a seller who lost it still delivers units already committed to the escrow. Cancel the participant's resting orders when a claim is revoked. An unregistered wallet is rejected with `unregistered-wallet`, a wallet outside the venue's admission policy with `wallet-not-admitted`, and an order whose recipient may not receive one of the instrument's tokens with `ineligible-wallet`. A sell of units that the base token's Time lock still holds is rejected with `units-time-locked`. The response gives the seconds until the next units unlock.

An operator reads the registration state with `GET /api/v2/system/identity-registration-statuses`.

## Step 4: the investor funds the wallet [#step-4-the-investor-funds-the-wallet]

An order needs the quote token for a buy and the base token for a sell. The investor opens "Wealth", then "Portfolio" in the Investor portal and selects "Deposit". The button appears only on an instance that has custody operations or the bank rail enabled, and the dialog offers "From a wallet" only with custody operations. A bank rail adds "By bank transfer". "From a wallet" shows the investor's [custody gateway](https://docs.settlemint.com/docs/concepts/custody-and-signing/custody-gateway) address as a QR code, as text, and with a copy button, and lists the accepted coins. Send only an accepted coin to that address, because anything else cannot be credited automatically. The gateway mints [custody receipts](https://docs.settlemint.com/docs/concepts/custody-and-signing/custody-receipt) for the coins it receives. While the gateway is paused, the dialog reads "This gateway is paused. Do not send a deposit until it resumes." An investor whose organisation has not created a gateway yet sees "No gateway yet".

![Deposit dialog with the gateway address, its QR code and the accepted coins](https://docs.settlemint.com/docs/screenshots/portal-venue-journey-fund-wallet.light.en.webp)

[Screenshot] The Deposit dialog shows "Your gateway address" as a QR code and as text with a copy control, an "Accepted coins" line, and a "Receipt balances" card underneath.

| What happens | Route |
| --- | --- |
| The dialog reads the investor's gateway | `GET /api/v2/addons/custody-gateways/gateways/mine` |
| The dialog lists the accepted coins | `GET /api/v2/addons/custody-gateways/gateways/:gatewayAddress/tokens` |

Before the first order the ticket may ask for a trading authorisation. The investor approves the venue's escrow, as an ERC-20 approval, for the amount the ticket shows, for a DALP token and a plain ERC-20 alike. An order that free escrow balance already covers needs no approval. [Trading](https://docs.settlemint.com/docs/console/my-assets/trading#before-you-start) lists the exact amounts.

## Step 5: the investor places an order [#step-5-the-investor-places-an-order]

The investor opens "Wealth", then "Trading" in the Investor portal, selects the instrument, and fills the order ticket. When the instrument has a price band, the ticket shows its bounds on the "Price band" line. A price outside the band disables "Place buy order" or "Place sell order", and the ticket names the band beside the button, so the order never reaches the venue. The ticket also disables Place and names the pause beside the button while the venue is paused, and it follows a pause or resume without a reload. Both price bounds are inclusive. Selecting "Place buy order" or "Place sell order" opens a review card that shows the amount "Reserved for this order". "Confirm buy order" or "Confirm sell order" asks the investor to verify the wallet, and the platform signs the order through the investor's custodial wallet. The ticket answers "Your order is accepted." once the venue has taken the order.

![The Investor portal trading screen for EUROC / AEDT with the order book and the Buy order ticket](https://docs.settlemint.com/docs/screenshots/portal-venue-journey-place-order.light.en.webp)

[Screenshot] The EUROC / AEDT header with "Session open · Live" and the session figures, the chart, the order book and recent trades, and the order ticket on "Buy" with the limit price, quantity, "Reserved for this order" and "Place buy order", above the balances.

Above the order book, "Price step" groups the resting levels into price buckets. Its first option is the instrument's own price step, one tick, which shows every resting price. The next options are 2, 5, 10, 50 and 100 ticks, each named by the price it adds up to. A bucket sits on a multiple of its step, so bids round down and asks round up, and its size is the sum of the levels inside it. Selecting a bucket fills the ticket's price. The Console trading screen groups its order book the same way.

The ticket and the review card show the exact amount "Reserved for this order". In the review card, prices, order value, fees, VAT and totals in the quote token share one decimal precision, long enough to retain every amount, with the price step as the minimum. Trailing zeros align the figures without changing what is reserved or charged. Base quantities keep the lot size's precision. Both the Console and Investor portal follow this rule.

Once the venue has taken the order, the ticket empties the quantity and puts "New order" where "Place buy order" or "Place sell order" was. Selecting "New order", or changing any field, clears the accepted note and starts the next order.

The venue accepts the signed order first. It then deposits any shortfall from the investor's wallet into its escrow and locks the order's amount, so the free balance drops and the locked balance rises. The order shows "Reserving balance" until the commitment confirms on chain, and it joins the book after that.

| What happens | Route |
| --- | --- |
| The platform signs the order with the investor's custodial wallet, and the venue takes it | `POST /api/v2/addons/trading-venues/:venueAddress/orders` |
| The caller polls a placement the API accepted asynchronously | `GET /api/v2/addons/trading-venues/:venueAddress/order-placements/:orderId` |
| The investor cancels an open order | `DELETE /api/v2/addons/trading-venues/:venueAddress/orders/:orderId` |

The venue checks the order before it reaches the book and rejects it with a named reason. The reasons include `venue-paused` (a venue admin must resume the whole venue), `market-halted`, `market-suspended` and `market-not-live` (the instrument is not trading), `authorization-insufficient` (the allowance is too low), `above-price-band` and `below-price-band` (the limit price is outside the range), and `desk-limit-exceeded` (the order is over the trading limit an operator set for the wallet), and `invalid-order` (a stop whose trigger price is already on the wrong side of the last trade). An instrument past its trading cut-off accepts no new order and the venue rejects it with `maturity-cutoff-reached`. The venue cancels the instrument's resting orders and releases their holds. For a bond, the cut-off is an instrument setting, the number of days before the bond's maturity date at which trading stops. The default of 0 days stops trading at maturity. For a rights token, the cut-off is the trading end of its rights issue. A dynamic band without a previous-close anchor blocks trading with `no-band-anchor`. [Trading](https://docs.settlemint.com/docs/console/my-assets/trading#troubleshooting) explains the fix for each.

### Orders from a self-custody wallet [#orders-from-a-self-custody-wallet]

A wallet whose keys the investor holds (a Privy embedded wallet, MetaMask, or a smart wallet one of them controls) follows the same steps, with one difference: the platform has no key to sign the order, so the investor's wallet signs it. In the Investor portal the review card reads "Sign in wallet". The investor signs, then selects "Place buy order" or "Place sell order" to submit the signed order. Investors whose keys the platform holds see no change.

An integration that builds its own front end on the SDK does this in three calls:

1. Request the order signature (`POST /api/v2/addons/trading-venues/:venueAddress/order-signatures`) with the order fields and no wallet signature. For a self-custody maker the venue answers `409` with `dapi.runtime.EXTERNAL_MESSAGE_AUTHORIZATION_REQUIRED`. The response carries the custody account and `signingPayload.typedData`, the order as EIP-712 typed data with `EIP712Domain` declared, ready for `eth_signTypedData_v4`.
2. Have the investor's wallet sign that exact payload. Do not change any field, because the venue checks the signature against the same order.
3. Send the first request again with the signature in `externalMessageAuthorization.signature`. The venue checks that the signature is a standard 65-byte signature from the account's signing key and that the smart wallet accepts it, then returns the signed order. Place it with `POST /api/v2/addons/trading-venues/:venueAddress/orders` as for any signed order.

A wrong signature, or a wallet signature sent for a maker whose keys the platform holds, fails with `400` and `dapi.runtime.EXTERNAL_MESSAGE_AUTHORIZATION_INVALID`. Send the request again without a signature to read the payload, then sign it.

## Step 6: the venue matches orders [#step-6-the-venue-matches-orders]

The venue keeps one order book per instrument and matches by price, then by arrival time. An instrument runs in one of two modes. A continuous instrument matches an incoming order against the resting book at once. An auction-only instrument collects orders during a window and clears them together at a single price, the price that matches the most volume. What the auction leaves unfilled follows the instrument's remainder rule. An instrument set to "Carry to the book" keeps good-till orders resting, with their holds, for the next auction. An instrument set to "Cancel remainders" cancels them. The listing wizard starts with "Carry to the book", and the choice is fixed once the instrument is listed. The status badge in the trading screen header says which phase the instrument is in, for example "Pre-open", "Opening auction", "Closing auction", "Session open · Live", "Trade at last", or "Session closed". A public continuous instrument can end its day with a "Closing auction", which collects orders and crosses them at one price, and then in "Trade at last", where orders trade only at the last price until the close.

Continuous fills and auction clearing prices stay inside the effective price band. A market order keeps its separate signed protection limit, and its fills must satisfy both limits. Saving a tighter policy cancels excluded resting orders and restores their reserved balances.

Every participant who can see the instrument sees its trades, candles and ticker, and the book to the depth their access allows. During pre-open and collection, the instrument's indicative price and quantity follow its publication setting. The screens do not show who is on either side. The venue contract's trade events name the buyer's and the seller's wallets on chain, so anyone who reads the chain can link a trade to both wallets.

| What the screen shows | Route |
| --- | --- |
| The order book | `GET /api/v2/addons/trading-venues/:venueAddress/markets/:marketId/book` |
| The trades tape | `GET /api/v2/addons/trading-venues/:venueAddress/markets/:marketId/trades` |
| Candles and the 24-hour ticker | `GET .../markets/:marketId/candles` and `GET .../markets/:marketId/ticker` |
| Live updates | `GET .../markets/:marketId/stream` |

## Step 7: the fill settles [#step-7-the-fill-settles]

A match is not a delivery by itself. The venue stages each fill and submits fills to the chain in batches. Within a batch, every fill moves both legs together. On an instrument with no holding period, the base units go to the buyer's recipient and the quote units, less the fee, to the seller's recipient in the filling transaction. With a holding period, the fill relocks both legs in the escrow until delivery. A fill that cannot complete leaves both legs where they were. The platform tries a passing failure again, and a fill that still cannot settle waits as a held fill until an operator retries or busts it, as [Held fills](https://docs.settlemint.com/docs/console/asset-lifecycle/venues/held-fills) describes. It does not stop the other fills in the batch. No party pays without receiving.

Each leg still passes its token's own transfer rules, so a match can fail at this point if a holder lost eligibility after the order was placed. An instrument can also set a holding period. During it the trade is recorded and priced, and its delivery is pending. An operator can undo a pending delivery through a trade bust, with a second operator's approval while the organisation requires one, as [Trade busts](https://docs.settlemint.com/docs/console/asset-lifecycle/venues/trade-busts) describes. An instrument with no holding period delivers inside the filling transaction.

The "Your trades" tab on the trading screen lists each fill with its price, quantity, fee, and status: "Pending delivery", "Delivered", or "Undone". Charged fees share the longest exact decimal precision among the listed fees, with the price step as the minimum, so even a fee of one smallest token unit stays visible. A fill shows its fee as "Not charged yet" until its settlement transaction lands, and shows the charged fee from then on, even while it awaits delivery. "Order history" shows each order's final state and, for an order that closed unfilled, the reason.

When a pending delivery is undone, both legs unlock into their owners' free escrow balances, and each owner withdraws them to the wallet from the Balances panel. The platform does not offer the undone lot again and does not return it to the book, and the orders' filled figures leave it out. The owner of a limit order with an undone lot can choose Place again on that order. It opens the new-order ticket with the same side, limit price and the undone quantity, and the original expiry if it is still in the future. You review and sign it as a new order, which gets new time priority. The side that failed has no Place again. The order on the side that failed shows "Settlement failed" with the undo reason. Every other order on the trade keeps its own status and close reason and adds a note that a trade on it was undone. An open order stays open for the rest of its quantity. The same rules apply in the Investor portal.

| What the screen shows | Route |
| --- | --- |
| Fills and their delivery status | `GET /api/v2/addons/trading-venues/:venueAddress/blotter` |
| The investor's orders | `GET /api/v2/addons/trading-venues/:venueAddress/orders` |
| The investor's reservations | `GET /api/v2/addons/trading-venues/:venueAddress/reservations` |
| The investor's escrow balances | `GET /api/v2/addons/trading-venues/:venueAddress/balances` |

The fills, orders and refused orders reads answer one page at a time, newest first: 50 rows when the request sends no `limit`, and at most 200. Send each page's `meta.nextCursor` back as `cursor` to read the next one, until it is `null`. Only the first page carries `meta.total`. The blotter takes a `status` filter, so a client that wants only the fills awaiting delivery asks for `status=pending-delivery` instead of reading every fill.

The orders read answers the caller's own orders, whatever `status` it filters by, even when the caller also operates the venue. A venue operator reads every participant's orders through `GET /api/v2/addons/trading-venues/:venueAddress/orders/operator`, or by sending an operator filter such as `participant` or `side`.

A reservation reads `committing: true` while its order's escrow commitment is still on its way: the venue holds the commitment, but the escrow balances and the token allowance do not show its pull yet. Add those amounts to a new order's before you compare it with the free escrow balance and the allowance to the venue's escrow. The Console and the Investor portal tickets do this before they offer "Authorize" or place an order.

A reservation reads `refundExhausted: true` once the venue spent every retry on refunding it. The escrow still holds those units, and they come back only after an operator reconciles the refund. An `active` reservation of an order that no longer works, with `refundExhausted: false`, is a refund the venue is still sending: an immediate-or-cancel order that fills in part keeps its remainder locked until that refund lands, a few seconds after the fill settles. The Console and the Investor portal desks show "Reserved for orders" as loading during that time, on the leg of the refund's token in the market the order was placed in, and show the units as reserved again only when the refund is spent. A refund in another market or another token does not hold this market's figures back.

## Step 8: positions, statements, and shareholder lists [#step-8-positions-statements-and-shareholder-lists]

The investor reads positions in the Investor portal under "Wealth", then "Portfolio". The "Holdings" tab lists balances read from indexed chain state, so a position updates once the block that settled the trade is indexed. Its "Value" column shows each holding in the organisation's base currency. The "Returns" tab shows the income those holdings earn: dividends, coupons, and interest. It also lists "Realized disposals": each burn or transfer out of the investor's wallets, with its realised profit or loss.

![The Holdings tab of the Investor portal Portfolio with each holding's balance and value](https://docs.settlemint.com/docs/screenshots/portal-venue-journey-positions.light.en.webp)

[Screenshot] The "Holdings" tab with the portfolio value chart, and below it a table with one row per token showing "Symbol", "Balance", "Value", "Unrealized P&L" and a "Transfer" action.

| What it shows | Route |
| --- | --- |
| Holdings and their base-currency value | `GET /api/v2/user-asset-balances` |
| Income returns | `GET /api/v2/portfolio/returns` |
| Realised disposals | `GET /api/v2/user-realized-pnl` |
| The caller's statements | `GET /api/v2/reporting/statements`, then `GET /api/v2/reporting/statements/:statementId/download` |
| One security's holders at a record block | `GET /api/v2/reporting/shareholder-lists/:tokenAddress`, then `GET .../download` |
| Scheduled and delivered lists | `GET /api/v2/reporting/shareholder-lists/:tokenAddress/deliveries` and `POST /api/v2/reporting/shareholder-lists/:tokenAddress/deliveries` |

The "Statements" tab on "Portfolio" shows one row for each wallet and period, with the columns "Period", "Wallet", "Status", and "Download". A statement lists the opening and closing balances and the movements of one wallet over a period. The organisation's statement policy sets how often the platform produces statements, and each one appears once its period has closed. Before the first period closes, the tab reads "No statements yet". "Status" reads "Incomplete" when, for any security, the opening balance plus the movements does not equal the closing balance, and "Reconciled" otherwise. Do not use an incomplete statement as a record of the wallet's balances. Each row offers "Download CSV", "Download Excel workbook", or "Download PDF" for each format the platform produced. See [Investor statements](https://docs.settlemint.com/docs/api-reference/guides/investor-statements).

A shareholder list is the register of holders of one security at one record block, a chosen chain block that fixes the balances, which an issuer uses after an auction cycle or at month end. On the "Holders" tab of the security in the Console, the "Export" menu offers "Holder register…", "Registrar file…", "Beneficial owners…", and "Issuer deliveries…" only for a security created with the Historical balances feature. Only organisation owners, platform administrators, and accounts with the system admin, auditor, compliance manager, or system manager role see them. Every other account sees only "This table as CSV". "Holder register…" opens the "Export holder register" sheet, which has a "Register" tab, a "Registrar file" tab, a "Beneficial owners" tab, and a "Deliveries" tab. The list is also available through the API. See [Issuer shareholder list](https://docs.settlemint.com/docs/api-reference/guides/issuer-shareholder-list).

The "Register" tab has "Deliver to issuer", which schedules a delivery. Only organisation owners and platform administrators see it. It is unavailable when the units held do not add up to total supply, or when no list exists at that record block. The "Deliveries" tab lists each delivery with its trigger: "After auction", "Requested", "Month end", or "Correction". "Requested" is a list an operator asked for with "Deliver to issuer". The API calls that trigger `scheduled`. A "Correction" supersedes an earlier delivery and states why. For a security that trades by auction, the platform also produces the list itself and stores it for the issuing organisation.

The platform emails the issuer's owners a notice when it delivers a list, or when it cannot produce one and marks the delivery "Refused". A delivery for a security created without the Historical balances feature is marked "Refused". The platform sends the email only when it has email delivery configured.

## The session close [#the-session-close]

An instrument follows its trading calendar. At the close the session ends, the venue accepts no new orders except "Day" limit orders for the next session, and the instrument computes its official close price from the session's settled trades. The instrument's close methodology sets the price: the last trade, or a volume-weighted average price over a configured window. A session with no eligible trade follows the instrument's "No-trade fallback": by default the auction price, then the previous close, or the previous close directly. Only a token's reference instrument publishes its official close to the token's price feed. An operator changes the methodology under "Edit official close" on the instrument detail.

A closed session leaves resting orders in place, except "Day" orders, which the venue expires at the close. An order placed as "Good till cancelled" rests through the close and is on the book at the next open. For a continuously traded security, the platform schedules a "Month end" delivery once the last trading day of the month has closed. To deliver a list for another record block, use "Deliver to issuer" as [Step 8](#step-8-positions-statements-and-shareholder-lists) describes.

## Many instruments, one quote token each [#many-instruments-one-quote-token-each]

Each instrument has exactly one quote token. A venue lists many instruments, and different instruments on the same venue can use different quote tokens. For example, one venue can list EUROC priced in AEDT and SGDT priced in EUROC.

Three rules follow from this design:

- A trade settles in the instrument's quote token. Both legs move on chain in the base token and that quote token. The platform does not convert currencies at order time, so a buyer needs a balance of the quote token and a seller receives it.
- The fee is charged in the quote token, at the instrument's maker and taker rate.
- Valuation is a separate step. The platform converts each holding into the organisation's base currency through the exchange rates the organisation tracks, and the "Value" column on the "Holdings" tab shows the result. [Exchange rates](https://docs.settlemint.com/docs/console/organisation-settings/exchange-rates) shows which currencies are tracked and the latest rate for each.

When no rate path exists, or a token has no price, the "Value" column shows a dash. It does not estimate a value. A position in a stablecoin quoted in a currency the organisation does not track therefore trades normally and appears in the holdings, but it has no value in the base currency until the organisation adds a rate for it.

## How fast the screens update [#how-fast-the-screens-update]

Market data arrives live over the instrument stream. The platform has no push channel to an individual user, so the other screens read fresh data when the browser window regains focus and at these moments:

| Screen | When it refreshes |
| --- | --- |
| Order book, trades, ticker, and candles | Live: the instrument stream carries the book and the trades, and each trade print refreshes the ticker and candles |
| Open orders and your trades | On each trade print, after the investor places or cancels an order, and after the platform indexes a block that changes the venue, checked every 15 seconds |
| Reservations | After the investor places or cancels an order, when an order or fill on the trading screen changes state, and after the platform indexes a block that changes the venue, checked every 15 seconds |
| Holdings | After the investor places or cancels an order, and when an order or fill on the trading screen changes state |
| Portfolio figures | After the investor places or cancels an order |

A position changes after the platform indexes the block that settled the trade, so it can lag the fill. "Your trades" is the first place a fill shows. The platform does not push positions to the user.

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

- After a full pass, "Your trades" lists the fill as "Delivered" with the fee in the quote token, or as "Pending delivery" while a holding period runs, with the charged fee once the settlement transaction has landed and "Not charged yet" before that.
- "Order history" shows the order as "Filled".
- For a buy, "Holdings" shows the higher base balance and the lower quote balance once the settlement block is indexed. A sell shows the reverse.
- The operator sees the same fill in the "Instrument activity" tile of the instrument detail under "Venues".

## Frequently asked questions [#frequently-asked-questions]

### Can an investor trade a token that was never sold in a primary offering?

Yes. No check requires an earlier offering, and listing needs no token feature. The instrument stays pending until its listing ceremony completes, as [Step 1](#step-1-an-operator-lists-the-instrument) describes.

### Does a trade in one quote token change a balance in another currency?

No. A trade moves only the instrument's base token and its quote token. The organisation's base currency matters only when the Portfolio values the holdings.

### Why does a position lag a fill?

Positions come from indexed chain state. The fill shows in "Your trades" first, and the holding changes after the platform indexes the settlement block.


# Venue market data

Source: https://docs.settlemint.com/docs/concepts/issuing-and-markets/venue-market-data
A Trading Venue instrument's official close, ticker, candles, streams, announcements and price alerts, plus its trading calendar and participant notifications.

An instrument is one trading line on a [Trading Venue](https://docs.settlemint.com/docs/concepts/issuing-and-markets/trading-venue), a base token against a quote token, on a tenant's own venue. The API paths and the `marketId` field keep the older name, market. Each instrument publishes its own prices and trades on a calendar its venue and the instrument set together, and the platform tells participants what happened to their orders. The Trading Venue page explains what a venue and a market are and how an order becomes a delivered trade.

## Market data: what an instrument publishes [#market-data-what-an-instrument-publishes]

An instrument keeps its own price record from its trades: an official close for each session, a ticker, candles and live streams. The ticker and the candles leave out an undone trade: a bust takes the trade out of the prices as well as out of the books. The [Platform API reference](https://docs.settlemint.com/docs/api-reference/v2) carries every route and field this section names. [Market Data](https://docs.settlemint.com/docs/concepts/records-and-evidence/market-data) is the separate feed system that holds a token's price, and the reference instrument's close is the one value a venue writes to it.

### The official close and the token's price feed [#the-official-close-and-the-tokens-price-feed]

An instrument's official close is its last trade of the session, or the volume-weighted average price over a set window before the close, rounded down to the price step. On a day with a closing auction, the close is the auction's price when it cleared one. When it cleared nothing, the close counts only the trades up to the start of the auction. On a day with a Trade-At-Last session, the close counts only the trades up to the start of that session and the window ends there, so trades at the last price after it do not move the close. When no trade falls in that window but the session traded earlier, the platform takes the same length of window ending at the session's last trade. A session with no trade falls back to the auction price and then the previous official close, or straight to the previous close, and an instrument with no previous close uses its reference price. An instrument set to close on the volume-weighted price cannot be listed or changed without its window, and the window cannot be longer than the instrument's shortest scheduled session. [Venue market settings](https://docs.settlemint.com/docs/console/asset-lifecycle/venues/instrument#most-listing-choices-get-a-later-edit-some-do-not) covers the setting and the fallback in full.

Of the instruments that trade a token, one can be flagged as its reference instrument, and the platform writes that instrument's close to the token's price feed. A token has at most one reference instrument on each system. Listing an instrument without a choice makes it the reference instrument only when no other instrument holds the role. Asking for the role is refused with "Another instrument already publishes this base token's price on this system" when another instrument holds it, and it is refused for a base token pegged to a currency or with an unknown asset class. Moving the role onto an instrument through an instrument update takes it from the instrument that held it. It skips the write in seven cases. Each skip is logged with its reason, and the instrument's own close stands either way.

| The platform skips the feed write when | Why |
| --- | --- |
| The base token has no active price feed on the system | There is no feed to write to |
| The base or the quote token has no resolved price | The close cannot be converted without it |
| The base token's asset class is pegged to a currency, or is unknown | A pegged token takes its price from exchange-rate feeds, and an unclassified one has no rule that prices it from a market |
| The quote token's own price was observed after the close | The conversion would mix a later price into an earlier close |
| No exchange rate known at the close converts the quote currency into the base token's currency | Only exchange rates observed at or before the close count |
| The converted close rounds to zero at the feed's precision | The feed would record a price of zero |
| The organisation has no operations signer bound to the system | Nothing can sign the feed update |

A close can move after the session ends. A trade that settles late, a bust, or a change to the previous close makes the platform recompute the last five closed sessions of the instrument, and it republishes only the latest close.

### Ticker, candles and live streams [#ticker-candles-and-live-streams]

The ticker gives the latest trade price, the best bid and offer, and the last 24 hours' open, high, low, volume and trade count. It adds the current session's open, high, low, volume and value, with the change from the previous official close. Its 52-week range comes from the daily candles of the last 365 days. Candles come in 1-minute, 5-minute, 15-minute, 1-hour, 4-hour, 1-day and 1-week intervals. By default the platform stores the first six. A deployment can narrow that list but always keeps 1-day candles, and a 1-week candle folds the 1-day candles of its week. A request that names none of `to`, `limit` and `indicators` returns the whole series, at most the newest 1500 buckets. A request that names any of them returns a window of 1 to 500 bars, 500 by default, that ends at the bar holding `to` (now by default), so its last bar is the forming one. A bucket with no trade repeats the previous close with zero volume. A 1-day candle starts at local midnight in the instrument's calendar time zone, or at UTC midnight when the calendar sets no time zone, a 1-week candle starts at Monday midnight in the same zone, and shorter candles start at UTC-aligned times. On the trading desk header, "Open price" is the opening auction price of the current session, or the first trade of the session when the auction set no price, while the first candle on the chart opens at the first trade, so the two can differ.

On the Console and Investor portal charts, the Open, High, Low and Close summary wraps to keep the labels readable in a narrow panel. Working-order labels stay at their order prices in a separate column beside the axis, clear of the candles and the last-price tag. The axis labels the candles at the market's tick precision in equal-width figures, so a price under 4 reads 3.9990 and the separators line up in one column.

The `indicators` parameter takes a comma-separated list of `sma`, `ema`, `vwap`, `bb`, `rsi` and `macd`. The platform computes them over the bars with a trade in the returned window and answers one array per indicator, aligned to the candles. An entry is null while an indicator is still warming up and on every bar without a trade, so a quiet stretch does not pull an average toward the repeated close or narrow the Bollinger bands. The simple and exponential moving averages and the Bollinger bands use the last 20 bars with a trade, the bands sit two standard deviations from the middle, and the RSI uses 14. The MACD uses 12, 26 and 9 unless `macdFast`, `macdSlow` and `macdSignal` set periods from 2 to 200.

Three live streams push changes so that a screen does not poll. Each path below starts with `/api/v2/addons/trading-venues/{venueAddress}`.

| Stream | Who may open it | What it sends |
| --- | --- | --- |
| Instrument stream, `GET .../markets/{marketId}/stream` | Anyone who can see the instrument | A snapshot of the book, then book changes, trades, indicative auction prices, the price band in force with any volatility interruption and when it ends, and each announcement the viewer may read. When settlement undoes a trade the stream already announced, a `trade-undone` frame names the undone trade sequences and carries the ticker figures without them. A heartbeat follows 30 seconds of silence, and the stream ends when the viewer loses access to the instrument |
| Participant order stream, `GET .../order-stream` | A participant, for their own wallets | The caller's open orders, then every change to their orders and trades and each new notification |
| Operator order stream, `GET .../orders/stream` | A venue operator | Every order of the venue, or of one instrument |

Each book change after the snapshot carries the instrument identifier and two positions in that instrument's own event log, `fromSequence` and `toSequence`, which bound the change. Each instrument numbers its own log, so the same pair listed on two venues streams two independent sequences.

The two order streams resume from an event cursor. The platform keeps seven days of order changes for resuming, and a cursor older than that opens a fresh snapshot instead. One caller holds at most eight order streams on one venue in each instance of the Platform API, and the next one is refused with HTTP 429 and `ORDER_STREAM_LIMIT_REACHED` before anything is read. Close a stream you no longer read, then open the new one. A reserved slot whose stream never starts frees after 30 seconds.

### Grouping the order book by a price step [#grouping-the-order-book-by-a-price-step]

The Console and the Investor portal group the order book by a price step in ticks. The options are 1, 2, 5, 10, 50 and 100 ticks of the instrument's own price step, each named by the price it adds up to. When the levels of a book sit 100 ticks or more apart, the same options move up by powers of ten and the one-tick option stays first, so the coarsest step always spans more than one gap between levels. A bucket's price is a multiple of the step, rounded down for bids and up for asks, and its size is the sum of its levels. On a compact desk, where the six options do not fit on one row, the control folds into a single select that lists the same options. A bucket hides its size when any level inside it is hidden.

### Announcements [#announcements]

A venue operator publishes an announcement to the whole venue or to one instrument, in the category "Notice", "Broadcast", "Trading window" or "Corporate action", with the severity "Information", "Warning" or "Critical". An optional display window limits when participants see it. A display-from time in the future schedules the announcement, and the platform publishes it within 15 seconds of that time. An edit keeps the replaced text, the editor, the time and the reason as a numbered revision. An announcement carries up to five PDF attachments, each up to 10 MiB, or a lower limit the deployment sets, and only someone who can see the announcement can download them. A withdrawal cannot be undone.

After its display window ends, an announcement stays readable as history. A participant's plain list answers only what is on display, and `filter[history]=true` lists the notices that have gone on display, including those whose display ended. A participant never receives a withdrawn announcement, a scheduled one or one pending approval. A venue operator's plain list keeps every notice, and `filter[history]` narrows it to the same published notices. The Investor portal shows this history on the **Announcements** page under "Wealth", a table of the venues the investor can see that they filter by category, market and date and in which each row reads "On display" or "Display ended".

An issuer can also publish an announcement about its own security, in the category "Issuer", when the caller holds the token's governance or supply management role. It is sent with the category `issuer` and the security's address, and it names no instrument. The announcement waits as pending approval, invisible to participants, until a venue operator of the submitting venue approves it through the Platform API. It then reaches every visible instrument whose base token is that security, on any venue of the same organisation and network. A venue admin can set daily publication windows for these announcements through the listing rules API. In `warn` mode, which a venue that never set the windows uses, an announcement outside them is accepted with a warning. In `block` mode it is refused with HTTP 422 and `OUTSIDE_PUBLICATION_WINDOW`, error [DALP-14744](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference).

### Watchlists and price alerts [#watchlists-and-price-alerts]

A watchlist belongs to one user in one organisation. Each entry is a token, and it can pin one instrument of that token. A price alert names an instrument and either an absolute price or a percentage move from the instrument's previous official close. It fires once, when a trade prints at or beyond its target, and sends a webhook and a notification. A percentage alert works out its target again from the close in force at each trade, so its level moves with each new session.

## The trading calendar [#the-trading-calendar]

Every instrument opens and closes on a calendar, and the same calendar decides which dates count as trading days for a good-til-date order. A venue calendar holds a time zone, a weekly template of preopen, open and close times, and dated exceptions such as half days. It can extend a shared holiday calendar, and it adds its own closed days. An instrument can replace the venue's weekly template with its own and add its own dated exceptions. A holiday closure always wins: an instrument's own entry for the same date gives way to it, and a closure the venue owns wins over one inherited from a shared calendar. On any other date, an instrument's own dated entry replaces the venue's entry for that date.

The platform generates sessions 90 days ahead. It judges a calendar save on the day each instrument trades, which is the venue and instrument layers combined, not on the layer being saved alone. A day or exception can also carry an optional closing auction time, after the open and before Trade at last or the close, which the calendar occurrence reports as `closingAuctionAt` and an auction-only or private instrument refuses. A day or exception can also carry an optional Trade-At-Last time, after the open and before the close, that starts a post-session in which a public continuous instrument trades only at the last price (see [Trading Venue](https://docs.settlemint.com/docs/concepts/issuing-and-markets/trading-venue)). The calendar occurrence reports it as `tradeAtLastAt`, and an auction-only or private instrument refuses a calendar that sets it. A save that would leave a combined day in the next 90 days with a preopen after its open, an open at or after its close, a closing auction time outside the open and the Trade-At-Last time or close, or a Trade-At-Last time outside the open and the close is refused. The refusal names up to five affected instruments, each with its first broken date, and counts the rest.

Two reads answer calendar questions, so a client never combines the layers itself. Both paths start with `/api/v2/addons/trading-venues/{venueAddress}`. `GET .../markets/{marketId}/calendar/trading-days` answers, for each date in a range of at most 366 dates, whether the instrument trades and when its session opens and closes. `GET .../markets/{marketId}/calendar/effective-closures` lists every closed date in a range with its name and its `source`: `venue`, `shared-calendar` or `instrument`. A shortened day is not a closure, and neither is a weekday the weekly template never opens. Both reads combine the layers the same way the platform does when it generates sessions, and neither offers a date the schedule skips.

An auction-only instrument has no daily hours. It collects orders over collection windows and clears once, at each window's end. The platform refuses a window that does not start before it ends, does not end in the future, spans more than 90 days, clears on a closed calendar day, overlaps another window, or clears on the same local date as another window. The Console saves a weekly pattern as separate windows for the next 12 weeks, and the platform keeps the pattern and generates windows from it 90 days ahead. [Instrument](https://docs.settlemint.com/docs/console/asset-lifecycle/venues/instrument#a-calendar-override-adds-one-exception-for-today-and-still-needs-saving) covers the operator overrides and a day without a preopen, and [Trading calendar](https://docs.settlemint.com/docs/console/asset-lifecycle/venues/trading-calendar) covers the calendar editor.

## How a participant hears about an order [#how-a-participant-hears-about-an-order]

Every venue event that concerns a participant lands in their notification list on the platform, and the same event can also reach them by email. The kinds are an order that filled or partly filled, any other change to an order (expired, cancelled by the venue, rejected, refused at entry), a price alert the participant set that fired, an announcement, and a corporate action.

Email is a choice per kind, made twice. A venue operator sets the organisation default on the "Participant alerts" tab of Venues, and a participant changes their own settings on "Notifications" in the Investor portal. A setting a participant never changed follows the organisation default and the portal marks that row "Your organisation's default". With no organisation default the setting is off, so the organisation decides whether alerts leave the platform at all, and each participant decides which ones reach them. An alert email goes to the participant's email address and names the instrument, side, filled and remaining quantity, average fill price and time. It uses the organisation's theme and time zone, and the participant's own language when the organisation has that language enabled. The platform sends no text message or mobile push alerts.

Delivery runs beside trading rather than inside it. A separate process reads the notification list after the event is committed and sends what the settings allow, so a slow or failing mail server never holds an order, a fill or a settlement. One event reaches a participant once even when it concerns several of their wallets, and an alert that is more than an hour old when delivery first sees it is not sent.

An email also links to the participant's notification settings in the Investor portal, where they turn these emails off after signing in. A mail server refusal is tried again later rather than dropped: the wait doubles from 30 seconds to at most an hour, and delivery gives up after eight attempts. A participant with no email address is not retried, because a later attempt cannot succeed.

The participant's settings are readable and writable through `GET /api/v2/addons/trading-venues/notification-preferences` and `PATCH /api/v2/addons/trading-venues/notification-preferences`, and an organisation default through `GET /api/v2/addons/trading-venues/notification-defaults` and `PATCH /api/v2/addons/trading-venues/notification-defaults`. Any venue operator of the organisation may read them. Only an organisation owner or platform admin may change them, and the change needs the same wallet verification as other venue writes. A change names only the settings it changes, and a null value drops a participant's own choice so the organisation default applies again. The [Platform API reference](https://docs.settlemint.com/docs/api-reference/v2) carries the request and response shapes.

Without an Investor portal URL, the platform sends no alert email, even when an organisation default enables it, because the recipient has no alert settings page to stop these emails. The delivery is not retried, and the alert stays in the participant's notification list on the Console.

The notification list keeps each notification for 90 days, whatever the email settings say. `GET /api/v2/addons/trading-venues/notifications` returns the caller's notifications newest first, and `unread=true` keeps only the unread ones, which makes its total the unread count. A transition marks one notification read, or every unread one at once. An order the participant cancelled themselves raises no notification, and neither does a cancel the maker may have sent on chain. An announcement notification follows its announcement: a withdrawal deletes it, and an edit updates its title and severity.


# Instrument denials

Source: https://docs.settlemint.com/docs/concepts/issuing-and-markets/venue-market-denials
A per-instrument deny list bars one wallet from one public instrument and records the reason and the user who barred it. The wallet keeps trading the rest.

An instrument is one tradable line on a venue. An instrument deny list bars one wallet from one instrument and leaves every other instrument of the venue open to it. It exists because the coarser tools a venue holds cannot express that case: they stop a wallet everywhere, or they decide who sees a private instrument, and neither records why one participant lost one instrument.

## Where a denial fits [#where-a-denial-fits]

A venue block stops the wallet on every instrument the venue lists, which is a venue-wide consequence for a problem on one trading line. A private instrument decides access through its participant list, and a public instrument has no such list. An access-profile override narrows trading, watchlist or depth inside an instrument the wallet can already see. It cannot hide a public instrument from that wallet, and it carries no reason and no actor.

A denial is its own record: one instrument, one wallet, the reason, the user who recorded it and the time. The denial is a platform record, not an on-chain one. The platform's order intake and market data enforce it, and the wallet's admission on the venue contract does not change. There is at most one per instrument and wallet, so barring a wallet that is already barred replaces the reason and the actor instead of adding a second entry. Lifting a bar deletes the record, and lifting a wallet that is not barred succeeds without a change.

## Bar a wallet [#bar-a-wallet]

The API calls an instrument a market, so the deny list lives under the market's path. `POST /api/v2/addons/trading-venues/{venueAddress}/markets/{marketId}/denials` records the bar. The body names the wallet, the reason, which holds 1 to 500 characters after trimming, and the wallet verification:

```json
{
  "walletAddress": "0x2a9f4c7b1d8e3056af72b4c9d0e1f6a3b8c5d2e7",
  "reason": "Repeated wash trades against its own resting orders in this instrument",
  "walletVerification": { "verificationType": "PINCODE", "secretVerificationCode": "482913" }
}
```

The answer is `200` with the recorded denial. The identifiers in this example are shortened:

```json
{
  "data": {
    "marketId": "…",
    "walletAddress": "0x2a9f4c7b1d8e3056af72b4c9d0e1f6a3b8c5d2e7",
    "reason": "Repeated wash trades against its own resting orders in this instrument",
    "actor": "…",
    "createdAt": "2026-06-12T09:41:07.000Z"
  },
  "links": {
    "self": "/api/v2/addons/trading-venues/0x7f3c2b5e8a1d4c6f9b0e2a5d8c1f4b7e0a3d6c9f/markets/…/denials/0x2a9f4c7b1d8e3056af72b4c9d0e1f6a3b8c5d2e7"
  }
}
```

`actor` is the user behind the session, which on an impersonated session is the person acting and not the user they act as. The stored wallet address is lowercase.

Only a platform administrator or the organisation owner can bar or lift a wallet. A bar and a lift apply at once, with no second approval, whatever the **Trading venues** row under "Approvals" says. Any other caller gets `404` `TRADING_VENUE_MARKET_NOT_FOUND` instead of a refusal, so the answer does not reveal whether the instrument exists. A bar without the wallet verification in its body, or a lift without it in its header, is refused with `400` `WALLET_VERIFICATION_REQUIRED` and changes nothing.

`DELETE .../denials/{walletAddress}` lifts one bar, with the same roles. A lift has no body, so its wallet verification travels in the `X-Wallet-Verification` header as a JSON object, for example `{"verificationType":"PINCODE","secretVerificationCode":"482913"}`. `GET .../denials` lists the bars of one instrument with `offset`, `limit` and `sort`. Without `sort` the list is newest first. `sort` takes `createdAt` or `walletAddress`, ascending, or descending with a leading `-`. A holder of the venue operator role can read the list without being a platform administrator or the organisation owner, and cannot change it. In the Console that operator still sees **Bar wallet**, and a bar they submit is refused as not found.

## What the bar changes [#what-the-bar-changes]

Barring a wallet takes its resting orders on that instrument off the book and releases their reservations. The cancellation runs as a participant cancel-all limited to that one instrument, so it shows among the venue's cancellation batches with the operator's reason. Orders the wallet has on other instruments stay where they are. Lifting a bar restores nothing: cancelled orders stay cancelled.

The instrument then behaves for that wallet as if it were not listed. It disappears from instrument lists, from the instrument read and from market data such as the ticker, the order book and the stream, and the wallet's access on the instrument reports the denial with no trading, no watchlist and no depth. A new order is refused at intake with the rejection reason `market-access-denied` and the message "Your access to this instrument is disabled". Order intake reads the instrument without the per-wallet gates and refuses a barred wallet with its own reason, so the trader learns why the order failed instead of reading an unknown instrument.

Visibility is decided per wallet. A caller that holds several wallets still sees the instrument through any wallet that is not barred, so keeping a person off an instrument means barring every wallet that person holds, including the signing address behind a smart wallet. A caller who operates the venue, or a platform administrator or organisation owner, still sees the instrument through that role.

## Where an operator bars a wallet [#where-an-operator-bars-a-wallet]

In the Console, the **Barred wallets** tile on a public instrument's settings takes a "Wallet address" and a "Reason for the bar". "Bar wallet" asks for your wallet verification. Each barred wallet is listed with its reason and a "Lift bar" button, whose verification asks whether to let the wallet, named by its address, "see and trade this instrument again". The tile is not offered on a private instrument, where the participant list decides who trades, and it is hidden from a caller who cannot read the list.

The list belongs to one instrument, so the same wallet can be barred on one instrument while it keeps trading on the next. [Venue operations](https://docs.settlemint.com/docs/console/asset-lifecycle/venues) covers the rest of a venue's controls, and [Trading Venue](https://docs.settlemint.com/docs/concepts/issuing-and-markets/trading-venue) covers how an instrument, its orders and its trades work.


# Venue retention

Source: https://docs.settlemint.com/docs/concepts/issuing-and-markets/venue-retention
Set how many years a venue keeps its trades and orders, preview the monthly run, read the append-only archive, and hold records back with a legal hold.

A venue collects every order, order event and trade it ever handled. Retention sets how many years those records stay at the venue, and a monthly run then moves the expired ones into an append-only archive, which keeps them with no end date, before deleting them from the venue. A legal hold keeps any part of that history out of the run until it is released.

## The period and the preview [#the-period-and-the-preview]

Each venue carries one retention period: a whole number of years from 1 to 100, or none. A venue starts with none, which keeps every record forever and archives nothing. `GET /api/v2/addons/trading-venues/{venueAddress}/retention-policy` answers the stored period:

```json
{
  "data": {
    "venueAddress": "0x7f3c2b5e8a1d4c6f9b0e2a5d8c1f4b7e0a3d6c9f",
    "retentionYears": 7
  },
  "links": {
    "self": "/api/v2/addons/trading-venues/0x7f3c2b5e8a1d4c6f9b0e2a5d8c1f4b7e0a3d6c9f/retention-policy"
  }
}
```

A member of the organisation can read the period. Changing it is `PUT` to the same route with `retentionYears` and `walletVerification`, and needs the venue admin role and a wallet verification. On a venue whose **Trading venues** row under "Approvals" on the "General" page of "Organisation settings" is on, the write answers with a venue configuration approval whose `commandType` is `venue-retention-policy`. A second venue admin decides it, the period changes when it is applied, and the database refuses a decision from the admin who proposed it. With the row off, the period changes at once and the write answers with the applied policy.

A period deletes records, so the Console asks for a preview before it saves one. `GET .../retention-policy/preview?retentionYears=7` answers what the next run would archive and delete if that period were in force:

```json
{
  "data": {
    "venueAddress": "0x7f3c2b5e8a1d4c6f9b0e2a5d8c1f4b7e0a3d6c9f",
    "retentionYears": 7,
    "orders": 18422,
    "orderEvents": 96031,
    "trades": 12760
  },
  "links": {
    "self": "/api/v2/addons/trading-venues/0x7f3c2b5e8a1d4c6f9b0e2a5d8c1f4b7e0a3d6c9f/retention-policy/preview"
  }
}
```

The counts apply the same eligibility the run uses, so they leave out records a legal hold covers and orders that a trade, a delivery, a staged fill or an active reservation still needs. The preview reads and changes nothing, and it needs the venue admin role.

In the Console, **Data retention** on the venue's Listing rules page holds "Retention period (years)", an empty field that reads "Keep forever", a "Preview" that prints the counts, and "Save retention period". While a changed numeric period has not been previewed, the save stays disabled and the panel warns that older records are copied to the archive and then deleted from the venue. A save on a maker-checker venue reads "Your change is held for approval. The retention period stays as it is until another venue admin approves it." and shows the current and proposed period.

## What the monthly run removes [#what-the-monthly-run-removes]

The run starts at 03:15 UTC on the first of each month and takes each venue on its own. A venue that fails is logged and retried at the next occurrence, and the other venues still run. The cutoff is the period subtracted from the run's date.

A trade leaves when it is delivered or undone, it executed before the cutoff and last changed before it, and no delivery of it is still unresolved. Its fee lines and its resolved delivery travel with it into the archived record.

An order leaves when it is closed, it was created and last changed before the cutoff, and no trade, delivery, staged fill or active reservation still refers to it. Its released reservation goes into its archived record, and its order events leave with it. An event that belongs to no order, such as a session transition, stays.

A record is deleted only when the archive holds it with the same payload. A record the archive already holds with a different payload stays at the venue, and the run counts it as a mismatch.

Each archived record names every participant it concerns: the maker and the recipient of an order and of its events, and the makers and recipients of both orders of a trade. A later hold or a search can therefore find a record by wallet.

## What the archive holds [#what-the-archive-holds]

The archive keeps one append-only record set per record kind, keyed by organisation, venue and the source id, and each row carries the venue, the instrument, the participants, when the record happened, the payload and the time it was archived. The payload is the source row as JSON with every top-level number written as a string, so no numeric value loses precision. The platform refuses to update, delete or truncate an archived record. The archive lives in the operator's PostgreSQL database, so the database owner's own controls protect it beyond that.

A batch works on one instrument at a time, trades before orders. It takes the venue's retention lock, reads the holds in force, locks up to 500 expired rows in key order while skipping rows another transaction already holds, archives them, and deletes exactly the rows the archive now holds with that payload, checking eligibility again under the lock. Placing a hold takes the same lock, so a hold recorded before a batch starts is honoured by that batch.

## Read and export the archive [#read-and-export-the-archive]

`GET /api/v2/reporting/venues/{venueAddress}/archived-records` pages one venue's records oldest first. It takes `from` and `to` on the record's own time, `kind` as `order`, `order-event` or `trade`, a `limit` and a `cursor`, and answers the page with `meta.nextCursor` for the next one. A cursor the archive did not return is refused with a bad request.

`GET .../archived-records/export` streams the same filter as a CSV file, one row per record with the payload as a JSON string, and records the export in the request audit trail.

A reader is an organisation owner, a platform administrator, or a caller whose acting wallet holds a reporting role on the organisation's system. The caller must also have a wallet with the venue operator or venue admin role on that venue. A caller who does not operate the venue on the selected network gets venue not found, and so does a venue address that the network does not hold.

## Legal holds [#legal-holds]

A legal hold keeps matching records out of every later run. `POST /api/v2/reporting/venues/{venueAddress}/legal-holds` takes a `marketId`, a `participantAddress`, a `fromAt`, a `toAt` and a required `reason`, and a hold with none of those bounds covers the whole venue. An instrument the venue does not list is refused, and a participant or time bound is recorded as sent, so a mistyped wallet produces a hold that matches nothing and protects nothing. The window is half open: a record at `fromAt` is held, a record that starts at `toAt` is not, and a window must start before it ends. A trade is placed in the window by its execution time. An order counts from its creation to its last change, so an order alive at any point in the window is held, and its events stay with it.

A participant hold covers the orders and order events where that wallet is the maker or the recipient, and the trades where either order is its own or pays it.

Only an organisation owner or a platform administrator can place or release a hold, acting on a wallet that operates or administers the venue. `GET .../legal-holds` lists the venue's holds with the scope, the reason, and who placed, asked to release and released each one.

Releasing a hold follows the organisation's approval policy: the **Reporting** row under "Approvals" on the "General" page of "Organisation settings". That row is off unless an organisation turns it on.

- With the row on, a release takes two people. `POST .../legal-holds/{holdId}/release-requests` records the requester and the reason, and a second request while one waits is refused with 409. `POST .../legal-holds/{holdId}/release-decisions` takes `approve` or `reject`. The requester cannot approve their own request, which answers 403.
- With the row off, the request releases the hold at once. The answer carries `releasedAt`, and `releasedBy` reads `approval-policy-waiver`, so the stored hold shows the policy as the releaser. An approval of a request that was already waiting releases the hold whoever gives it.

On either setting, a rejection clears the request and the hold stays active. A decision on a hold with no waiting request answers 409, a hold that is already released refuses another request with 409, and a hold id the venue does not hold answers 404. A session acting as another user is refused on both release routes with 403, because one person could otherwise be the requester and the approver. It is refused the same way when it places a hold, because a hold carries the acting user's own signature and the hold would name the impersonated user as its placer. A platform administrator places and releases holds from their own session.

The Console path for both is the **Legal holds** tab of the venue. [Legal holds](https://docs.settlemint.com/docs/console/asset-lifecycle/venues/legal-holds) covers that sheet, its labels and its states, and [Trading Venue](https://docs.settlemint.com/docs/concepts/issuing-and-markets/trading-venue) covers the orders, events and trades the archive holds.


# Venue VAT

Source: https://docs.settlemint.com/docs/concepts/issuing-and-markets/venue-vat
A venue sets a VAT rate, settlement calculates it on each fee line, and the tax moves to a configured recipient in the same settlement as the trade.

A venue can charge VAT on the fees it takes, and that tax has to be visible on the trade and reach the account that owes it to the authority. The venue holds one VAT policy, settlement calculates the tax on each fee line it charges, and on a venue that collects it on chain the tax moves to a configured recipient account inside the same settlement as the trade and the fee.

## The policy [#the-policy]

`GET /api/v2/addons/trading-venues/{venueAddress}/vat-policy` answers the policy in force:

```json
{
  "data": {
    "venueAddress": "0x7f3c2b5e8a1d4c6f9b0e2a5d8c1f4b7e0a3d6c9f",
    "vatRateBps": 500,
    "vatApplicable": true,
    "vatOnChain": true,
    "vatRecipient": "0x5c8e1a4b7d2f9036ec51a8b4d7f0e2c9a6b3d8f1",
    "zeroRatedParticipants": [
      {
        "walletAddress": "0x91b3f7c2d5e8a1046bc9f2a7d4e1c8b5a0f3d6e9",
        "reason": "Fee falls outside the scope of VAT for this participant's registration",
        "actor": "…",
        "createdAt": "2026-05-02T11:07:31.000Z"
      }
    ]
  },
  "links": {
    "self": "/api/v2/addons/trading-venues/0x7f3c2b5e8a1d4c6f9b0e2a5d8c1f4b7e0a3d6c9f/vat-policy"
  }
}
```

The rate is a whole number of basis points from 0 to 10000. The applicability switch decides whether the venue charges VAT at all, and the on-chain switch decides whether the tax is paid on chain or only recorded. A new venue starts at 500 basis points and applicable, with collection off. A venue that existed before this policy was introduced starts at 0 basis points with VAT off, so its settlements do not change until an admin turns it on.

`PUT` to the same route changes the policy. `vatRateBps`, `vatApplicable` and `walletVerification` are required. `vatOnChain`, `vatRecipient`, `zeroRatedParticipants` and `reason` are optional, and a field the request leaves out keeps its stored value. A `zeroRatedParticipants` list replaces the stored list. It needs the venue admin role and a wallet verification. Every VAT policy change, whichever field it touches, follows the **Trading venues** row under "Approvals" on the "General" page of "Organisation settings". With the row on, the change becomes a venue configuration approval whose `commandType` is `venue-vat-policy`: a second venue admin applies it, the admin who proposed it cannot decide it, and a venue with a single admin cannot change its VAT policy until a second admin holds the role. With the row off, the change applies at once and the response carries the applied policy. The change log keeps the policy before and after.

A reason is required when the on-chain switch, the recipient or the zero-rated list changes, and the request audit trail records it. A change that could never apply is refused with 422 DALP-20523: collection on chain with no recipient, collection on chain while VAT is not applicable, and a change that needs a reason and carries none. When a change switches collection on chain on, or names a new recipient while it is on, the recipient is checked as well: the venue or its escrow account is refused with the same code, and so is a recipient that one of the venue's quote tokens would refuse. That check runs the token's own transfer rules with the escrow as the payer, so the recipient has to be able to receive every quote token the venue settles in. With the row on, the same checks run when the change is proposed and again when it is applied.

In the Console, "VAT policy" on the venue's Listing rules page holds these fields:

- **VAT rate (basis points)**
- **Charge VAT on fees**
- **Collect VAT on chain**
- **VAT recipient**
- **Participants that pay 0% VAT**
- **Reason**

The line under the rate converts the rate you enter, such as "2,100 basis points is a VAT rate of 21%.", and while the field holds no valid rate it gives the scale: "Enter the rate in basis points: 100 basis points is 1%."

You save them with **Save the VAT policy**. A change that waits for a second admin reads "Sent for approval. Another venue admin must approve it." and one that applies at once reads "The VAT policy is saved."

## How the VAT is calculated [#how-the-vat-is-calculated]

Each buyer fee line and each seller fee line carries its own VAT: the line amount multiplied by the rate in basis points, rounded up to the next base unit of the quote token. A fee line whose type does not carry VAT records zero, an inapplicable policy records zero on every line, and a zero rate records zero.

A wallet on the zero-rated list pays its fee and no VAT on its side of a trade, whether it buys or sells, and the counterparty still pays its own share. Every change to the list carries a reason, stored with the wallet and the acting user.

The fee and the VAT stay separate values. A settled fill records the buyer fee, the seller fee, the buyer VAT, the seller VAT and the recipient the tax went to, and every fee line records its amount and its VAT. The recorded fee is the fee the chain charged minus its VAT, so a sum over fees never counts the tax twice. The trade fee event carries `amount` and `vatAmount`, and a statement line carries the fee and its VAT as its own fields.

## Paying it on chain [#paying-it-on-chain]

The venue contract needs no VAT field. A settlement's fee route is a list of recipient and amount entries that must add up to the two sides' fee totals, and the escrow pays one transfer per entry in the same post as the trade. The VAT rides as one more entry, for the two sides' VAT together, paid to the VAT recipient. The platform builds the fee route from the pinned VAT policy, and the venue contract checks only that the entries add up to the fee totals and stay within each order's signed maximum fee.

The settlement instructions show the tax as its own `vat` leg from the buyer to the VAT recipient, and the seller's cash leg is the quote amount minus the seller's fee and the seller's VAT, so each side bears its own share and the chain transfer reconciles with the calculated VAT. The VAT rides the settlement that delivers the trade, so an instrument with a holding period pays it when the trade delivers.

Before a batch settles fills that owe VAT, it checks the recipient again with the quote token's transfer rules, from the escrow as the payer. A recipient the token now refuses holds those fills instead of sending them into a revert, the platform logs an error that names the venue, the recipient and the quote token, and the rest of the batch settles.

A settlement that carries no fee schedule cannot route VAT. A fill that is charged a fee there and owes VAT on it is parked with the reason for an operator to retry, while the other fills of the batch settle. A fill charged no fee, because the instrument charges none or a discount waives it, settles with no fee and no VAT leg.

## A held fill keeps the rule it was staged with [#a-held-fill-keeps-the-rule-it-was-staged-with]

The policy is pinned on the fill when it is matched: the rate, the applicability, whether collection is on chain, the recipient and whether each side is zero-rated. A change therefore applies to fills matched after it, and a fill staged before the switch settles under the rule it was staged with. A recovery replay reads the same pinned rule, so trades of one settlement transaction never carry different VAT.

A held fill keeps the recipient it was staged with, and a retry pays that recipient. Clearing that recipient's compliance block or busting the fill releases it. Naming a new VAT recipient does not.

## The signed fee limit [#the-signed-fee-limit]

The fee cap a client signs has to hold every fee the order can be charged across all of its fills. The venue prices that worst case with one function, shared by order intake and every client's order ticket: the order split into the most fills it can have, one per lot, each fill priced at the highest tier it can reach, with the fixed and minimum fees of the instrument's fee schedule charged on every fill and the percentage fee on the whole order. On a venue that collects VAT on chain, the VAT on those fees is added, rounded up per fill. The cap is the smallest whole number of basis points that covers that total.

An instrument with no fee schedule is priced on its own rate instead: the higher of its maker and taker fee on the whole order, plus the venue's on-chain fixed fees, the order fee once and the settlement fee on every fill. The contract charges those fixed fees only when no fee schedule applies, and the indexer reads them from the venue's `FixedFeesUpdated` event.

The single-instrument read carries `feeSchedule`, the tiers of the instrument's current fee schedule, and `vatOnChain`, and every instrument read carries `orderFee` and `settlementFee`, the venue's fixed fees in quote token units, so a client can compute the same cap. The order ticket signs it and reserves the principal plus the fees at that cap. An order whose signed cap is lower is refused at intake with `max-fee-below-schedule` and the message "The order's maximum fee of X basis points is below the Y this instrument's fee schedule, fixed fees and VAT can charge across the order's most fills".

An order whose worst case exceeds the venue's maximum of 1000 basis points, 10% of its value, cannot be covered by any cap the venue accepts. It is refused at intake with `fee-cap-above-venue-maximum` and the message "The fees this order can be charged across its most fills come to X basis points of its value, beyond the venue's maximum of 1000, so no fee limit the venue accepts covers it". A larger order, or a schedule with lower fixed fees, brings the worst case back under the maximum.

Switching collection on, or raising the rate while collection is on, is refused with 409 DALP-20524 while open orders on the venue were signed under a fee limit that cannot hold the fee plus VAT. The count and the policy write run in one transaction that holds the venue's VAT lock, the write rereads the policy under that lock, and order entry takes the same lock while it writes an accepted order. An order entered at the same moment is therefore either counted or refused, and a change prepared against an older reading of the policy is still checked against the policy it replaces.

On the investor side, the ticket shows **Estimated VAT** beside the fee, and the review step shows the same VAT, at the digits of the instrument's price step and rounded down. When the VAT has more digits it shows "≈" before it, and pointing at it or moving focus to it shows the exact amount. The buy's reservation line reads "Order amount plus maximum fee, VAT included" on a venue that collects VAT on chain, "Order amount plus maximum fee, VAT not reserved" where the VAT is only recorded, and plain "Order amount plus maximum fee" where VAT does not apply.

## Reversing a trade [#reversing-a-trade]

The buyer paid the whole `vat` leg, so a bust that reverses a delivered trade force-transfers that leg, both sides' VAT, from the VAT recipient back to the buyer, under the operations signer's custodian role on the quote token, in the same batch as the fee refund. A quote token on which the operations signer holds no custodian role cannot have that leg reversed. The seller returns the cash it received, which is the quote amount minus its fee and its VAT. A trade whose VAT was only recorded has no VAT leg to reverse. [Trading Venue](https://docs.settlemint.com/docs/concepts/issuing-and-markets/trading-venue) covers the bust workflow itself.


# Asset Class

Source: https://docs.settlemint.com/docs/concepts/modeling-assets/asset-class
An asset class groups instrument templates by economic category for catalogue navigation and exposure reporting.



[Figure] One asset class groups several instrument templates. An asset class is a named economic category. It groups several instrument templates, and each template separately defines its product facts, its features and its own compliance choice. Issued instruments hold no class of their own: they read the class through their template at query time, so a class rename or delete reaches assets issued long ago. Labels: Economic category; Asset Class; One stable grouping, such as Fixed income or Digital assets; Template A; product facts and features; its own compliance choice; Template B; product facts and features; its own compliance choice; Template C; product facts and features; its own compliance choice; Issued instruments; read their class through their template at query time, holding no copy of it,; so a class rename or delete reaches assets issued long ago.

The class groups templates by economic category, and each template specifies a product and its compliance configuration.

An asset class is a named economic category, such as Fixed income or Funds, that groups instrument templates for the catalogue and for exposure reports. It sets no token behaviour and no compliance rule.

Nine classes ship with the platform. You can add your own and hide any class you do not use.

Delete is not blocked while templates still use a class. Hide instead, or move the templates first.

## The class names exposure, the template configures the product [#the-class-names-exposure-the-template-configures-the-product]

An asset class answers one question about an instrument: what kind of economic exposure it represents. The instrument template beneath it answers a different one: how one product is configured. The platform keeps the two apart, so changing one product's configuration leaves the class it reports under untouched. Changing the class itself, by a rename or by reclassifying a template, relabels every instrument beneath it at once.

That separation is what keeps a growing catalogue legible. Debt product templates can sit in a fixed-income class while carrying different dates, cash-flow features and compliance frameworks. A new product joins an existing class instead of forcing a new category, and exposure reports keep comparing like with like as the catalogue grows.

The class label follows issued assets into portfolio breakdowns and catalogue navigation. A report can move from a class-level view to the templates and instruments beneath it without losing the common grouping, which is what makes exposure comparable across products that share nothing else.

## Shipped classes and custom classes [#shipped-classes-and-custom-classes]

Nine asset classes ship with the platform and are visible to every organisation: Fixed income, Cash, Real assets, Equity, Funds, Structured, Digital assets, Derivatives, and Yield instruments. They cover the economic categories the shipped instrument templates are built around.

Add a custom class when the shipped categories do not meet your reporting needs. A class has a name and a slug, the lower-case key the platform derives from the name. Review the name and scope before assigning templates, because the class label appears in portfolio views for their issued instruments. The platform refuses a name whose slug matches a shipped class. It also refuses a name with a letter or digit from another script, because that name forms no slug. A custom class therefore never shares a slug with a shipped one.

If your organisation created a custom class before the platform shipped a class with the same slug, the upgrade resolves the clash. When every template in your class uses a base asset type the shipped class allows, the shipped class adopts its templates and template structures, and your class is removed, so its identifier no longer resolves. Otherwise the class keeps its name, identifier, templates and issued instruments, and moves to a new slug: the old slug, a hyphen, and the first eight letters and digits of its identifier in lowercase. Filters, links and reports keyed on the old slug stop matching that class after the upgrade.

A Permission manager, System manager, or Asset designer adds, edits, hides, or deletes a class. An Asset manager can read the catalogue through the API but not change it. Other roles cannot read it, and the Console screen opens only for the three managing roles. The [Asset classes screen](https://docs.settlemint.com/docs/console/asset-design/asset-classes) covers the full workflow: where the screen lives and which badge marks a System row against a Custom one. It also covers why Hide sits next to every row while Edit and Delete appear only on the rows you created.

## Hide first, delete last [#hide-first-delete-last]

Hide, Rename and Delete differ in how far they reach through templates and issued instruments, and in whether you can take them back. Hide touches nothing and reverses in one click. Delete reaches everything beneath the class.

| What you do | What it reaches | Reversible |
| --- | --- | --- |
| Hide | Removes the class from the pickers your people choose from, for your organisation only. Templates keep their class and issued instruments keep reporting it. Another organisation still sees a system class you hid. | Yes. Turn on Show hidden and choose Make visible. |
| Rename | Custom classes only, gated the same as Edit. Changes the displayed name everywhere at once, including on instruments issued months ago, because the name is read live instead of copied onto the asset. The slug is rebuilt from the new name, and the class's templates move to it in the same save. Anything outside the platform that grouped on the old slug stops matching. | Renaming back restores the name and slug, and the templates follow it again. Copies taken in between, such as an exported report, keep whatever was live when they were written. |
| Delete | Custom classes only. The platform does not block a delete while templates still reference the class. Those templates lose the class: a holding lookup for their instruments finds no class, while portfolio and asset stats breakdowns keep bucketing them under the stale slug the template stored. | No. The confirmation says so, and it does not mention the templates. |

Hide takes a class out of circulation without touching a single template or issued instrument. It is scoped to your organisation and reverses in one click. It also works on the nine shipped classes, which Delete does not.

[Figure] Deleting a class in use leaves templates and issued instruments without one. Deleting a custom asset class removes the class row, and nothing checks first whether instrument templates still point at it. Each template that pointed at the deleted class keeps the grouping slug it stored but no longer points at a class that exists. Instruments already issued read their class through the template rather than holding a copy, so a holding lookup for an affected instrument finds no class from that point on, while portfolio and asset stats breakdowns keep reporting the template's stale stored slug instead. Hiding the class instead leaves every link intact and can be undone. Labels: What a delete leaves behind; The class row, deleted; custom classes only, and nothing checks whether it is still in use; link cleared; Keeps the grouping slug it stored; Instrument template; and no longer points at a class that exists; Instruments already issued; read their class through the template rather than holding a copy,; so holdings show no class. Stats keep the stale label; Hiding the class instead leaves every link intact, and you can undo it.

Hide reverses in a click, but Delete does not once templates already point at the class.

If you do need a class gone instead of hidden, move first: point every template that uses it at another class, then delete. The delete confirmation does not list the templates that still use the class, and neither does the Asset classes screen. The instrument template list in the Console filters by class, and that filter matches each template's stored copy of the class slug, which a rename of the class keeps current. Filter by the class before you delete to find every template you still need to move.

## Where the classification is recorded [#where-the-classification-is-recorded]

An asset class is an off-chain catalogue record: an identifier, a name, a description, a slug, an owner and a system flag. An instrument template stores the class identifier plus a copy of the slug, taken when the template was created or last reclassified and refreshed whenever the class is renamed. A later class rename or deletion does not update an exported report, and a deletion leaves the template's stored slug as it was.

The classification is single-valued and it lives on the template: one template belongs to one asset class, and an issued asset takes its class from the template it was created from instead of storing its own. The identifier preserves the relationship. The slug supports filtering, navigation and reporting. That is what makes a rename reach backwards through the catalogue and a delete reach with it.

[Figure] One shared set of system classes, with per-organisation hiding and private custom classes. The nine system classes are one shared set owned by no organisation. Hiding one writes a record on your organisation's side that points at the shared row. The shared definition never changes. A custom class belongs to your organisation alone and never takes the slug of a shipped one. Another organisation still sees every system class, including any you hid, and never sees your custom classes or your hide records. Labels: One shared set, per-organisation choices; Shared system classes; nine rows owned by no organisation. Hiding never edits them; Fixed income; Digital assets; and seven more shipped classes; points at the shared row; Your organisation; Hide record: Fixed income; written on your side only; Custom class: Private credit; invisible outside your organisation; Another organisation; Still sees every system class,; including any you hid; never sees your custom classes; or your hide records.

Hiding writes a record for your organisation only, so the shared definition and what everyone else sees never change.

Visibility is organisation-scoped, and hiding is recorded separately from the class itself. System definitions have no organisation owner and are visible by default. Hiding one writes a record against your organisation instead of changing the shared definition, which is why your choice never reaches another organisation. Custom definitions carry the organisation's identifier, and the API resolves only classes that are shared or owned by the requesting organisation.

Compliance sits in a separate record. A template can reference one Compliance Template, which defines the checks and modules applied when an asset is created, so a regulatory regime never replaces the economic class. Reporting can aggregate instruments by class while compliance evidence follows the actual rules selected for the template and issued asset.

## What the API exposes [#what-the-api-exposes]

Integrations manage asset classes through the [platform-settings endpoints in the version 2 API](https://docs.settlemint.com/docs/api-reference/v2), which list, read, create, update and delete definitions. List responses support pagination, sorting, search, facets and a visibility filter. Reads return the shared system classes plus the classes the calling organisation owns, and nothing owned by anyone else.

Two rules keep an integration working across a rename.

Key on the identifier, never on the slug. The slug is the grouping key current navigation and reporting paths use, and it is rebuilt from the name whenever the Console saves a class, so it moves when a name moves. The identifier does not.

Treat a slug as unique within what your organisation can read. A shipped class's slug belongs to that class alone, and your organisation's own classes are unique within your organisation. The platform refuses a create or rename whose slug matches a shipped class or another class your organisation owns. It answers HTTP 409 with [DALP-0463](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference), a caller error that is not retryable. Choose a different name. The refused request changes nothing: the class that holds the slug keeps its name and description. Two names that differ only in case or spacing, such as "Trade Finance" and "trade finance", derive the same slug, so the second create is refused. Another organisation may hold a custom class with the same slug as one of yours, and your reads never return it.

Create and update requests carry the class name, description and slug. If a create request omits the slug, the platform derives one from the name in kebab-case. The service rejects an instrument template whose class identifier is neither a shared system class nor a class owned by the caller's organisation.

Read the instrument template's compliance-template link and configuration to assess compliance. The class slug describes economic classification.

## What a class does not enforce [#what-a-class-does-not-enforce]

An asset class supports compliance work by making populations easier to define and review, but it does not enforce investor or transfer rules. The class answers which economic group an instrument belongs to. The linked Compliance Template answers which controls apply when an asset is created.

This separation lets compliance teams compare instruments by economic exposure without assuming that all products in a class share one regulatory treatment. Two templates in the same class can select different compliance frameworks. One compliance framework can be used across economic classes when its rules fit.

For audit and reporting, use the class as a grouping dimension and the actual template and issued-asset configuration as control evidence. A report can show exposure by class, then identify the compliance framework attached to each product. The class label alone cannot prove that a transfer check ran, what it blocked or what evidence it left.

One consequence follows from the class being read live instead of copied. A portfolio breakdown you exported last quarter can disagree with the same breakdown run today because someone renamed a class in between, with no change to a single instrument. Where a report has to be reproducible, store the class identifier alongside the label you printed.

## Frequently asked questions [#frequently-asked-questions]

### Can I change the class an instrument belongs to after it is issued?

Not one instrument at a time. Classification lives on the template, so reclassifying the template moves every instrument issued from it in the same moment, and there is no per-instrument override. A holding's class resolves through its template alone. The template also stores a fresh copy of the class slug when it is reclassified, so its stored grouping key follows the move.

### If I delete a class and recreate it with the same name, do the links come back?

No. A new class receives a new identifier even when its name and slug match the deleted one, so the platform treats the two as unrelated. Re-point each affected template at the new class to restore the grouping. Instruments issued from those templates then report it again through the template.

### Why does an externally registered token show no asset class?

It never came from an instrument template, and the platform finds a token's class only through its template. A token issued outside the template flow therefore has no class.

### Is the asset class recorded on chain?

No. The platform stores the class off chain and resolves it live whenever a report runs. Adding, renaming, hiding or deleting a class needs no transaction and touches no contract. The asset classification claim that the platform adds to some tokens' identity at creation is a different record: it holds the instrument's own type, class and category, such as an equity class, and never the asset class. On-chain enforcement, who may hold an asset and what may transfer, comes from the compliance configuration, never from the class.

## Related concepts [#related-concepts]

- [Instrument Templates](https://docs.settlemint.com/docs/concepts/modeling-assets/instrument-templates): Reusable product definitions grouped by an economic category.
- [Composable Token](https://docs.settlemint.com/docs/concepts/modeling-assets/composable-token): The configurable on-chain asset created from an instrument template.
- [Compliance Policy](https://docs.settlemint.com/docs/concepts/compliance-and-identity/compliance-policy): The enforceable rule set that decides whether a regulated transfer may proceed.
- [Stablecoin](https://docs.settlemint.com/docs/concepts/modeling-assets/stablecoin): An instrument of the Cash class.
- [Denomination Asset](https://docs.settlemint.com/docs/concepts/modeling-assets/denomination-asset): The token a payout feature pays in, chosen after the template's class is set.


# Composable Token

Source: https://docs.settlemint.com/docs/concepts/modeling-assets/composable-token
A composable token lets an issuer bring a new regulated instrument to market by configuring facts, features, and rules instead of writing new contract code.



[Figure] One contract model composed for many instrument shapes. An Instrument Template supplies three inputs: the instrument facts to record, the Token Features whose behaviour runs in execution order, and the compliance rules that decide who may hold the asset and what may proceed. These inputs configure one focal Composable Token contract carrying identity, roles, and per-token compliance. The same contract model then represents a bond, fund, sukuk, loan, structured note, commodity, or another shape the issuer defines. Labels: Instrument template; Instrument facts; terms to record; Token Features; behaviour, in execution order; Compliance rules; who may hold it; Composable Token; One contract model; identity, roles,; per-token compliance; Instruments; Bond; Fund; Sukuk; Loan; Structured note; Commodity; or another shape; the issuer defines.

A template selects the facts, ordered features, and rules for one contract model, which gives product coverage through composition.

A composable token is the one ERC-20-compatible asset contract the platform deploys for every instrument, with identity, role and compliance controls built in and an ordered list of token features that carry its behaviour. An issuer brings a new instrument to market by configuring it, with no new contract code, as long as the platform's features, fact fields and compliance modules cover the design.

Feature order is policy: it decides which feature sees which amount.

A feature attaches at creation or on a live asset. The generic feature lifecycle API replaces its configuration by rotating the instance.

## Why a new instrument does not need new contract code [#why-a-new-instrument-does-not-need-new-contract-code]

An issuer that wants a new instrument type on a platform built from one contract per asset type waits on a new contract, because coverage only grows when one ships. A Composable Token removes that wait. Every instrument the platform issues, a bond, a fund, a sukuk, a structured note, or a shape an issuer defines, comes from the same regulated contract model, configured instead of rebuilt. The second bond of a given design reuses the first one's template instead of commissioning another contract.

One regulated contract model is deployed for every instrument, and each issued token carries its own configuration of instrument facts, token features, and compliance rules. A token feature is a module that adds one behaviour, such as a fee or a coupon. Available features, metadata fields, and compliance modules bound the instrument designs a deployment can issue.

The Instrument Template is the off-chain product definition. It names the required features and the compliance choice, and so records the product shape. The features hold the behaviour, for example transfer fees, coupon and yield schedules, voting power, conversion windows, historical balance snapshots, and the other regulated behaviours the platform registers. Underneath every entry sits the same regulated token core, the base balance and transfer logic every instrument shares. The platform deploys one instance of this contract model for each instrument on an EVM-compatible network.

A bond, fund, sukuk, loan, structured note, or commodity still names a financial instrument, and the platform still records which one an asset is. Two instruments of different types differ in their configuration, and the contract model behind them is the same.

Responsibilities divide the same way. Composition provides the digital mechanics and policy hooks, and the template records the product shape the platform uses. Legal terms, regulatory classification, and suitability remain issuer responsibilities, detailed in the controls and evidence section.

## How composition works [#how-composition-works]

A Composable Token is one shared regulated asset contract initialised with the regulated token core, identity and role controls, metadata, pause and custody behaviour, and a per-token compliance contract. The asset factory, the deployed contract that creates every token, creates configured [Token Features](https://docs.settlemint.com/docs/concepts/modeling-assets/token-features) and installs their addresses as one ordered set during deployment. The instrument facts come from the template the issuer chose, so the deployment starts from an approved product shape instead of a blank contract.

The list is written as one complete ordered set. The factory creates all requested feature instances first, then sets that list in the same transaction. If a feature factory is missing or creation fails, the transaction reverts instead of leaving an asset with a partial feature set.

An operation runs through that list in three phases. In the first, every feature is asked whether the operation may proceed, and each is asked about the operation exactly as the caller requested it. Only the second phase is a pipeline.

Second, the features that rewrite run in list order, and this is where a result is handed on. Each rewriter receives the original operation and the legs the previous rewriter produced. A leg is one balance movement the operation settles into. The rewriter may split, resize, or add to the legs. Each resulting leg is then executed through the token's full pipeline, which asks the first-phase question again for that leg.

Third, every feature is notified once. The notification reports both the original operation and the legs that executed. These three calls, the question, the rewrite, and the notification, are the hooks a feature receives. The whole run is atomic: the legs settle and every feature sees them, or the operation reverts and nothing changes.

[Figure] Three phases, and only the middle one is a pipeline. One transfer enters the token's ordered feature list, which holds up to 32 entries. In the first phase every feature is asked whether the operation may proceed, about the operation exactly as requested, so a refusal reverts the whole operation from any position. In the second phase the features that rewrite run in list order as a pipeline: each rewriter receives the legs the previous one produced, plus the original operation, and each resulting leg executes through the token's full pipeline. In the last phase every feature is notified once with the original operation and the legs that executed. The run is atomic: the executed legs and their notifications land together, or nothing changes. Labels: Position decides in one phase only; Transfer requested; one operation enters an ordered list of up to 32 features; each one is asked about the operation exactly as requested; 1. Every feature is asked; a refusal reverts the whole operation, from any position in the list; 2. Rewriters run in list order; First rewriter; Next rewriter; The legs that execute; each receives the legs the one before produced, plus the original operation; told the original operation and the legs that executed; 3. Every feature notified once; Atomic: legs settled, or nothing changed.

Only the rewriting phase hands a result on, while the question before it and the notification after it reach every feature with the same inputs.

So position is a behavioural choice among the rewriting features and only among them. Put a fee rewriter ahead of another rewriter and the second one works from the legs the first produced, which changes the amounts that settle. The recommended order puts [hold](https://docs.settlemint.com/docs/concepts/modeling-assets/token-features/balances-and-holds) first, then transfer restrictions such as [maturity](https://docs.settlemint.com/docs/concepts/modeling-assets/token-features/income#maturity-redemption) blocks and [conversion](https://docs.settlemint.com/docs/concepts/modeling-assets/token-features/conversion#conversion) locks first, fee collection next, external fee hooks that account for fees in another token after that, and analytics last. A restriction cannot be outranked by moving a fee feature above it, because a refusal reverts the whole operation, not one stage of it. An analytics feature such as a historical-balance or voting-power snapshot cannot record an amount no holder received. It is told the executed legs wherever it sits in the list, so its position does not change that notification.

An instrument template defines the composition off chain, before anything is deployed. A template binds an asset class, instrument-fact schema, base asset type, required feature identifiers, and a compliance template. The Platform API checks feature dependencies and incompatible pairs before it publishes or uses that template. The asset factory then resolves each feature type to its registered factory and creates the on-chain instances. The factory itself checks neither dependencies nor conflicts.

System addons sit at a different level of the same deployment. They are shared components registered once per deployment, such as the settlement and feature factories, and their registry controls which implementations a deployment can use. An addon is shared deployment infrastructure, and a token feature is per-instrument behaviour. An addon can supply the factory that creates a feature, and each resulting token feature belongs to one token.

## Issuing from the template catalogue [#issuing-from-the-template-catalogue]

Issuing a composable token starts with an instrument template: the reusable product shape that collects the instrument facts, required token features, and compliance choice the creation flow needs. The operator supplies the values this issue needs for the facts the template defines, and deploys the configured asset.

The catalogue is a set of reusable starting shapes. System templates cover common products, while organisation templates capture the product designs your own firm has approved. A platform-supplied template stays a shared baseline: it cannot be edited or deleted, and an attempt answers [DALP-14365](https://docs.settlemint.com/docs/api-reference/errors). What you can change is whether your organisation offers it: unpublish it to remove it from your issuance flow, or hide it to keep it out of the template picker whatever its published state. Copy it into an organisation template when you need it to differ.

Two checks run before a template can be published. A required feature whose dependency is absent answers [DALP-14094](https://docs.settlemint.com/docs/api-reference/errors), for example dividend yield without historical balances, because the feature cannot read the balances it pays on. Add the missing dependency to the template's required features and publish again. A pair of features that cannot run on one token, such as transaction fee with transaction fee accounting, or register lines with a feature that moves units, answers the same [DALP-14094](https://docs.settlemint.com/docs/api-reference/errors). Keep one of the pair. Its `data.reason` names each feature involved. Both checks run again at creation, where the same conflicting-feature pair answers [DALP-0605](https://docs.settlemint.com/docs/api-reference/errors) instead, so a template edited around a check does not reach a deployed asset.

Editing a template never changes tokens already issued from it. A template configures a deployment. Once an asset exists, its ordered feature list and its own compliance contract live on chain, and editing the template writes nothing there and starts no transaction. The link survives the edit, so those assets stay listed and filtered under the template's current name, slug, and asset class. Changing what a live asset does means changing that asset, by attaching or rotating features on it.

## Servicing a live asset [#servicing-a-live-asset]

Servicing a live composable token means driving its feature lifecycle, because the features are where its behaviour lives. An account with the token's governance role attaches, detaches and rotates features. It also needs Supply management and Custodian, or the admin role, because a feature acts with those powers. Attached features are on-chain capability contracts with their own state, and the [token feature endpoints in the API reference](https://docs.settlemint.com/docs/api-reference/v2) drive all three lifecycle moves. Attach adds a feature, detach removes it, and rotation replaces it with a new instance carrying new configuration. The generic feature lifecycle API changes configuration through rotation, and the replaced instance stays on chain. Feature-specific operations can update settings that the feature permits, such as a treasury address before maturity.

Attach and rotation append an instance to the ordered list. Detach removes an instance. A newly attached feature joins the end, and there is no position parameter on the request. A rotated feature's replacement instance also joins the end instead of inheriting the old position, so rotating a rewriter that ran ahead of another rewriter changes execution order as well as configuration. The Platform API never repositions an existing entry, so when position matters, attach or rotate the features in the sequence you want them to settle in. On chain, an account with those roles can replace the whole ordered list in one `setFeatures` call, which can reorder, remove or add entries.

Rotation is also the reason a detach is rarely the right tool for a configuration change. A rotate retires the current instance and installs its replacement in the same write, so the hooks keep flowing and no window opens. Reach for a detach only when the behaviour itself must stop.

While a feature is off the list it receives no hooks, so any state it derives from balances stops tracking them, and the missed window is never backfilled. After a reattach, totals the feature can recompute from live on-chain state are right again at once. Per-holder derived values catch up only when that holder's balance next moves. A voting-power feature detached across a mint re-seeds its total supply on reattach and reads a holder's own units live, but a delegate's vote count catches up only when the delegating holder next moves, and votes weighted as of a block inside the window read the wrong totals permanently. Plan the window across a quiet period for the affected feature instead of treating a detach as a toggle. Detaching a restricting feature, such as maturity redemption or hold, also removes its restriction from the next operation on.

Neither the Console nor the Platform API detaches or rotates conversion or the distribution waterfall after issuance. The Platform API also refuses to detach or rotate dividend yield while declared dividends are unclaimed. The token itself does not protect these features: an account with the roles that set the feature list can remove either of the first two on chain with `setFeatures`.

[Figure] Two ways to change a feature, and only one opens a window. Two independent paths from Attached. A rotate deploys a new instance carrying the new configuration. It joins the end of the ordered list, the old instance stays readable on chain, and no window opens because hooks keep flowing throughout. A detach opens a window in which no hooks arrive and derived state freezes, and that gap is never backfilled. On reattach, totals recomputed from live balances are correct at once, while per-holder derived values catch up only when that holder's balance next moves. Servicing history is read against the instance that was attached at the time. Labels: One feature on one token, over time; Rotate: no window opens; Attached; hooks arrive,; derived state; stays current; rotate; Rotated; A new instance, carrying the new configuration,; joins the end of the list.; The old instance stays readable on chain.; No window opens: hooks keep flowing.; Detach: opens a window; Attached; hooks arrive,; derived state; stays current; detach; Detached window; no hooks, derived; state freezes, never; backfilled; reattach; Reattached; totals recompute at; once, holder values; catch up on next move; history reads against the instance attached at the time.

Rotating a feature keeps hooks flowing, while detaching opens a window in which no hooks arrive and derived state freezes.

Four configuration facts decide what a composable token does, and they differ in what it takes to change them.

| What you configure | What it decides | What changing it takes |
| --- | --- | --- |
| The instrument template. | Which facts the asset records, which features it must hold, and which compliance template it links. | Supplied at creation. A creation request without one is declined. |
| The order of the feature list. | The legs a transfer settles into, because the rewriting features hand their result to the next rewriter in the list. | Set as one complete ordered set at creation. Through the Platform API, attach and rotation append an instance and detach removes one. On chain, the roles that set the feature list can replace the whole list in one call. |
| How many features the token holds. | Up to 32 entries on one token. | A hard ceiling. A list longer than 32 is rejected, not truncated. |
| One feature's own configuration, such as a coupon schedule or a fee rate. | That feature's behaviour, and its position, because the replacement joins the end of the list. | Rotation, which deploys a replacement instance and retires the current one. |

## When an off-chain register decides every movement [#when-an-off-chain-register-decides-every-movement]

A feature can also refuse every movement the token would otherwise make. The Booked movements feature, which the Features tab lists as "Register lines", does this for a share class whose legal register a transfer agent or fund administrator keeps off chain. Each change to a holding becomes a movement on the token. An investor requests it or the administrator enters it, and an administrator with the token's Supply management role, which allows minting and burning, books it with the reference of its register entry, which moves the units in the same transaction. The token refuses every other mint, burn, transfer, forced transfer and wallet recovery, and it refuses any other feature that would move units. These refusals last while Booked movements is attached. An account with the roles that set the feature list can detach it, and from then on the token accepts ordinary mints, burns and transfers again. Features that never move the token, such as dividend yield, keep working on the booked balances.

The Share-Class Mirror instrument template issues such a token with Historical balances, Hold and Booked movements attached and no compliance policy, because the register decides who may hold the class. Every recipient still needs a verified identity. Each share class is its own token, so a fund with several classes has one mirror token per class, and every register entry is booked on the token of its class. Hold reserves the units of an open request, which is why Booked movements needs it attached. Features that move units outside a movement, such as Management fee, Conversion, Conversion minter, Supply delegate and Maturity redemption, cannot sit beside it. [Booked movements](https://docs.settlemint.com/docs/console/asset-management/manage/booked-movements) covers the Console workflow, the refusals and the API routes.

## The integration contract [#the-integration-contract]

Developers integrate with composable tokens through the generic asset and feature surfaces instead of a switch over fixed contract names. Creation input specifies the asset metadata, the concrete instrument type name, initial metadata entries, and an ordered list of feature type and configuration pairs. The name enters the deterministic deployment address, and the list fixes the execution order of the transfer pipeline.

The instrument type name identifies the template-backed shape, even though the implementation is the generic asset contract. Treat it as instrument metadata and deployment identity, never as proof that a dedicated bond or equity implementation exists. Integration code branches on the features it finds attached.

Feature identifiers are registry keys. The asset factory derives the matching feature-factory key, resolves it from the system addon registry, creates the feature, and installs the returned address. Integrations should read attached feature state through the generic discovery surface, then use the interface of the feature type they find. Integration code varies by feature type, not by template.

Listing a token's features through the API returns them sorted alphabetically by name, so that order carries no meaning. When order matters, read the ordered list from the chain through the token's `getFeatures()` function, because that is the list the transfer pipeline runs.

Do not assume that a feature type appears only once over an asset's life. Detach and reattach operations can leave several historical instances. For a current operation, select the attached instance that most recently became active. For audit or history, retain the detached records.

Feature lifecycle writes are asynchronous, so a caller reads or waits for the settled result instead of treating the initial response as completion. Attaching a feature the token already holds is refused with the reason `already-attached`. Rotate the existing instance instead of retrying the attach. The exact status codes, headers, and response shapes for these calls are in the [token feature endpoints in the API reference](https://docs.settlemint.com/docs/api-reference/v2). After settlement, list the token's features to read the deployed address instead of deriving it.

Creation has its own rejections worth designing for. A request without an instrument template answers [DALP-0316](https://docs.settlemint.com/docs/api-reference/errors), because there is no template-free creation path. A token type with no registered factory in the active system answers [DALP-0314](https://docs.settlemint.com/docs/api-reference/errors). Choose a type the deployment registers. A denomination asset that does not expose readable ERC-20 `symbol()` and `decimals()` answers [DALP-9073](https://docs.settlemint.com/docs/api-reference/errors), because maturity and coupon features read that metadata on chain after the asset deploys.

## Controls and evidence [#controls-and-evidence]

Each composable token has its own compliance contract, so one instrument's policy does not become an implicit rule for every asset in a deployment. Before balances change, that contract checks the token's installed rules and the system-wide rules for the sender, receiver, amount and token, and a failed check reverts the transfer. A custodian forced transfer and a wallet recovery skip those rules. The check that the recipient has a verified identity still runs, and attached features still see the operation with a forced flag, so a feature such as Booked movements can still refuse it. The token's governance role can install, turn off, reconfigure or remove its rules, and it can point the token at a different compliance contract.

The instrument template links the product shape to a selectable compliance template. The platform rejects a draft compliance template, an unsupported module-set version, or an incompatible module set before the link becomes deployable. This moves a class of configuration failures ahead of asset creation.

Supply, governance, custody and emergency operations stay gated by the asset's access manager, the contract that holds its role assignments. An attached feature acts with the token's authority: it can move units between any two accounts, mint, burn and set an allowance, and each move still runs the token's identity and compliance checks. The token accepts any contract that names it as a feature, so setting the feature list needs the governance role together with Supply management and Custodian, or with the admin role. Whoever chooses which contracts hold that authority must already hold those powers or be able to grant them to itself.

Every composable token runs the implementation its asset factory names. A system manager can replace that implementation, which changes the code of every composable token in the system at once, and the factory emits `TokenImplementationUpdated` with the old and new address.

The evidence follows the same split as the architecture. An auditor reads three sources.

| Evidence source | What it holds | Where it lives |
| --- | --- | --- |
| The chain. | Every transaction and event from the token and its attached features. | On the network. The platform indexes it for queries. |
| The instrument template. | The approved starting configuration: instrument facts, required features, and compliance choice. | On the platform. |
| The issuer's own records. | Legal approval and classification. | Off the platform, unless an implementation explicitly stores them. |

## Frequently asked questions [#frequently-asked-questions]

### Can a standard ERC-20 wallet hold a Composable Token?

Yes. The asset contract implements the ERC-20 interface, so wallets, explorers, and existing token tooling read balances and submit transfers without any DALP-specific software. The difference is what happens after submission: every transfer runs the identity, compliance, and feature checks this page describes, so a transfer a plain ERC-20 contract would settle can revert here. The wallet must satisfy the asset's recipient identity requirements to receive tokens.

### Does the 32-entry ceiling count detached features?

No. The ceiling measures the list installed on the token at one moment, because the contract stores the ordered set in a fixed array of 32 slots. A detach frees the entry it held, and a rotation swaps one entry for its replacement, so historical instances cost no capacity. What grows over an asset's life is the population of on-chain instances, one more with every rotation, while at most one instance of each type is attached.

### Do transfer fees apply to a forced transfer or a recovery?

No. A custodian forced transfer and a wallet recovery pass a forced flag into every hook in the pipeline, and the fee features exempt themselves when it is set. The fee rewriter returns the legs unchanged, so the administrative move delivers the exact amount ordered instead of a fee-split remainder. A burn by the Supply management role is an ordinary burn, so a transaction fee with a burn rate takes its fee from it. The flag reaches every feature in all three phases, wherever it sits in the list, so each feature decides its own forced-operation behaviour.

### Does rotating or detaching a feature put balances at risk?

The lifecycle write itself moves no units, because balances live in the token contract's own storage, and a feature holds only the state it derives from the hooks it receives. What the write changes is which rules apply. Detaching maturity redemption, Booked movements or hold removes the restriction that feature enforced, from the next operation on, and attaching a feature gives it the token's authority to move units. A badly timed detach also costs derived state, the totals and per-holder values the feature stops tracking during the window.

## Related concepts [#related-concepts]

- [Instrument Templates](https://docs.settlemint.com/docs/concepts/modeling-assets/instrument-templates): Reusable product shapes that bind instrument facts, required features, and a compliance choice.
- [Asset Lifecycle](https://docs.settlemint.com/docs/concepts/issuing-and-markets/asset-lifecycle): The working life a Composable Token enters once issued, from servicing through an optional retirement, on the same indexed record its creation started.
- [Asset Class](https://docs.settlemint.com/docs/concepts/modeling-assets/asset-class): The economic category, such as a bond or a fund, that groups the reusable product definitions a composable token can be configured from.
- [Denomination Asset](https://docs.settlemint.com/docs/concepts/modeling-assets/denomination-asset): The asset a payout-bearing Token Feature pays out in, resolved independently by each feature installed on a Composable Token.
- [Stablecoin](https://docs.settlemint.com/docs/concepts/modeling-assets/stablecoin): A cash-class instrument issued the same way, through an Instrument Template that configures a Composable Token.
- [EVM Contract Set](https://docs.settlemint.com/docs/platform/evm-contract-set): The identity, compliance, custody, and settlement contracts DALP deploys on EVM chains around one composable security token.


# Denomination Asset

Source: https://docs.settlemint.com/docs/concepts/modeling-assets/denomination-asset
A Denomination Asset lets a payout-bearing Token Feature, such as Maturity Redemption or a yield schedule, pay holders in a real asset it never custodies.



[Figure] What is burned and what is paid are two different assets. A holder redeems 100 bond-style tokens. Two separate things happen from that one instruction. Redemption burns the surrendered tokens outright, destroying them, and no denomination asset moves for that half of the transaction. Separately, the treasury, which holds the denomination asset, often a stablecoin balance, pays out face value times 100, the amount owed for what was burned, to the holder. The holder receives the denomination asset, never the tokens they surrendered, and the feature itself never custodies the denomination asset at any point. Labels: Holder redeems 100 bond-style tokens; destroys the tokens; owes the payout; 100 bond-style tokens are burned; Surrendered; destroyed outright, not paid out; no denomination asset moves here; Treasury; holds the denomination asset; often a stablecoin balance; face value times 100; Denomination asset; Received by the holder; paid from the treasury, not by the feature.

Redemption burns the bond-style token, and separately the treasury pays the denomination asset at face value, so the two assets never trade places.

A payout-bearing Token Feature never pays a holder from its own balance. Every payout draws from a separately configured treasury, and nothing locks that treasury's balance or allowance, so holders rely on the treasury's owner to keep it funded.

What redemption burns and what it pays are different assets: the surrendered token is destroyed, the denomination asset is delivered.

Maturity freezes the treasury binding of that feature instance. The address can still be funded but cannot be repointed.

## Why a payout needs an asset the feature never touches [#why-a-payout-needs-an-asset-the-feature-never-touches]

A denomination asset is the token that a payout-bearing [token feature](https://docs.settlemint.com/docs/concepts/modeling-assets/token-features), such as maturity redemption or a yield schedule, pays holders in. It is always a different token from the one being held, and the feature draws it from a treasury the issuer funds.

A bond-style instrument, one that matures and is redeemed at a face value, has its own token, and that token is what a holder trades and holds. It is not money, and [Asset Lifecycle](https://docs.settlemint.com/docs/concepts/issuing-and-markets/asset-lifecycle) names what happens to it at the end of its life: the instrument matures, holders redeem, and their positions burn. Redemption destroys the very token being redeemed, so that token cannot also be what pays the holder. A yield feature meets the same problem earlier in the instrument's life: a coupon or a dividend is value paid on top of a holding, not more of the holding itself. Something has to represent that value in a form redemption or a yield payment never touches. The denomination asset is that something: a currency-like token a payout-bearing Token Feature pays out per unit redeemed or per unit of yield earned.

The feature pays through a treasury and holds no balance of its own. The issuer funds one named treasury for each feature, and every payout is an ordinary transfer from that treasury to the holder. Any rule on the denomination asset applies to that transfer as it would to any other.

## Choosing the denomination asset at configuration [#choosing-the-denomination-asset-at-configuration]

An issuer picks the denomination asset once, at instrument configuration, before the bond-style token exists. The Console's "Denomination asset" field rejects an address with no contract deployed at it on the selected network, so a stablecoin or other external token has to exist first. Reusing an established stablecoin means the bond-style token depends on that stablecoin's own issuer and decimals, neither of which it controls. Issuing a purpose-built denomination asset instead avoids that dependency, at the cost of operating its own supply and compliance gating from day one. Reuse an established stablecoin when the instrument can live with a token it does not control. Issue a purpose-built one when the instrument's own compliance rules or liquidity needs cannot bend to somebody else's token. After the feature exists, only its treasury can change, and only until maturity.

## One resolution per feature, one of two payout paths [#one-resolution-per-feature-one-of-two-payout-paths]

Each payout-bearing Token Feature resolves its own denomination asset. A Token Feature is a unit of behaviour a Composable Token installs, such as Maturity Redemption or a yield schedule. The denomination asset is a property of each feature. The token's Holdings list shows it only when the token also holds a balance of it, flagged as the Redemption or Yield row. A token with two payout-bearing features installed can have two different denomination assets active at once, each with its own treasury to fund.

The feature never custodies the denomination asset it pays out. It always draws from a separately configured treasury, through one of two Treasury Payout Modes: an approval-based pull, or a delegated payout call into a vault contract that implements its own logic and interface. The platform probes automatically for which mode applies, by checking whether the treasury supports that vault interface, and nothing about the feature's own code changes between the two paths. That probe runs when the treasury is configured and again at the maturity call, and the resolved mode is cached in between instead of recomputed on every payout. A treasury that gained or lost vault support since configuration is therefore picked up at maturity.

**Approval pull**

The treasury is an externally owned wallet with a standing approval to the feature, or a contract that grants that approval itself. Either way the feature pulls the payout with that allowance. An externally owned treasury approves through the platform's own control. That control signs with the acting wallet, so a smart-wallet treasury the platform operates can use it too. Any other contract treasury calls approve itself instead, through whatever admin or governance flow it exposes.



**Vault call**

The treasury is a contract that implements the `ITreasuryPayer` interface, and the feature calls its `payout(token, to, amount)` function instead of pulling funds itself. Choose it when the payout needs logic a plain balance and allowance cannot express: a multi-signature release, its own internal accounting, or a rate limit on how fast it pays out. That logic is a contract you write and keep correct.

A Maturity Redemption feature rejects a denomination asset that equals its own token when the feature is configured. It also rejects a zero denomination address. Paying out the same token the feature is burning would break the redemption invariant: a redeemer's balance would grow at the face-value rate while total supply shrinks from the same burn.

## Fund the treasury before maturity, or redemptions stay closed [#fund-the-treasury-before-maturity-or-redemptions-stay-closed]

The treasury needs enough of the denomination asset funded before maturity. The platform blocks the normal maturity call if the treasury balance falls short of the whole supply at face value: the token's supply counted in whole tokens, times the face value.

Funding the balance is not enough on the approval-pull path, where the treasury lets the feature pull funds up to an allowance. The maturity gate checks only the treasury's balance of the denomination asset, never its allowance to the feature, so a treasury that holds the full amount but never approved the feature passes that gate cleanly. Every redemption then reverts with [DALP-9481](https://docs.settlemint.com/docs/api-reference/errors), because payout pulls funds through that same allowance, and a standard token approval overwrites rather than adds to what is already granted, so a top-up must state the new total allowance. Approve at least the amount needed to redeem the whole supply. Only the treasury's own wallet can approve, and the [treasury allowance endpoint](https://docs.settlemint.com/docs/api-reference/v2) sets the allowance before or after maturity, which makes it the fix for an externally owned or platform-operated treasury once redemptions start failing this way.

An emergency early maturity skips the solvency check, so redemptions open on a treasury that may already be short. Either path pays out only on tokens destroyed, and not on the amount a holder requested.

## Read the denomination asset on the feature, not the token [#read-the-denomination-asset-on-the-feature-not-the-token]

An integrator reads the denomination asset per feature, not per token. The [feature configuration endpoint](https://docs.settlemint.com/docs/api-reference/v2) returns each attached feature's own `denominationAsset`, alongside its `faceValue` and `treasury`, since there is no token-level or Holdings-level accessor for any of them. Preview a Maturity Redemption payout before submitting one with the feature contract's `calculatePayout()`, which returns the redeemed token amount times the face value, divided by ten to the power of the token's decimals.

A live redemption's actual payout can come in lower than the preview. A co-installed fee feature can divert part of the requested burn, so only the net amount destroyed earns denomination. Read the emitted `Redeemed` event's payout amount as the actual figure, instead of a value recomputed from the request.

The feature contract also caps total payouts at face value times the supply at maturity. Each payout is for the net amount burned, so the cap acts as a backstop. When a payout would pass the cap, the feature pays only what is left of the budget and still burns the tokens redeemed.

## Custody stays with the treasury [#custody-stays-with-the-treasury]

For a compliance review, the feature that pays out the denomination asset never holds it. Every payout-bearing feature draws from a separately configured treasury, so the funds move only from the treasury to the holder. The holder starts that movement, or, for a delegated redemption, an account with the token's Custodian role does.

Which of the two maturity paths opened redemptions is itself a compliance-relevant fact, because the two paths give a reviewer different assurances to weigh:

**Normal maturity**

Callable by the token's governance role, which administers its features, from the maturity date onward, once the treasury has passed the solvency check that gates a normal maturity call.



**Emergency early maturity**

Callable by the token's emergency role, which can also pause the token, before the maturity date. It skips that check by design, so redemptions can open on a treasury already short. Redemptions are served first-come, first-served against the treasury balance, and one the balance cannot cover reverts with the holder's tokens unburned.

The normal-path solvency check runs once, at the maturity call: the treasury is an external address, and nothing stops it from being drained after maturity passes. Every redemption, on both paths, checks the treasury's live balance for its own payout and blocks that payout when the balance falls short. A later shortfall reverts the whole redemption, so the holder's tokens are not burned and nothing is paid from a balance that is no longer there. Until every holder has redeemed, keep the treasury funded for the supply still outstanding and keep its allowance in place: only the amount above that is surplus.

The payout is a transfer of the denomination asset, so that asset's own rules apply to it. Before calling mature, confirm that the treasury and every holder's wallet are accepted by any allow list on the denomination asset. A payout the asset rejects reverts the redemption with the holder's tokens unburned, and the matured token cannot be sold on instead. After maturity, funding the treasury and, on the approval path, setting its allowance still work. The platform cannot override another token's rules, so a reused stablecoin's own issuer has to admit a rejected wallet.

Review redemptions opened through the emergency path as a possible shortfall event.

## Frequently asked questions [#frequently-asked-questions]

### Does the denomination asset have to be a stablecoin?

No. Any deployed ERC-20 can serve, and dividend yield and interest yield also refuse a registered fee-on-transfer or rebasing token. Token creation enforces metadata: the platform does not create a token whose denomination asset does not expose a readable ERC-20 symbol and decimals. The check lands before anything deploys, so a wrong address fails the creation call instead of the first payout. Stablecoins are the usual choice because holders expect a currency-like payout.

### Can the treasury address change after it is configured?

Before maturity, yes. The governance role can repoint the treasury to a new address, and every repointing re-detects which payout path applies. Because the platform caches that detection between checks, repointing the same address again is also how you force a fresh probe after a treasury contract changes what it supports. Maturity removes that option: it freezes the treasury binding, so a vault that later loses its payout interface, or a plain treasury that turns into one, is stuck on whatever mode was last resolved, with no later way to repoint it. The token's governance role can still replace the matured feature with a new instance that has its own treasury. Confirm the treasury still supports the mode you expect before calling mature, because that call is the last chance to fix it.

### Can a holder still transfer a bond-style token after maturity?

No. Maturity freezes the token itself: regular transfers are blocked, and so are new mints, so the supply that redemption prices against stays fixed. Four moves remain. A holder can redeem, an account with the Custodian role can redeem on a holder's behalf, a custodian can still execute forced transfers, and a co-installed feature can still move tokens it triggers itself. The block lasts while [maturity redemption](https://docs.settlemint.com/docs/concepts/modeling-assets/token-features/income#maturity-redemption) stays attached. If the governance role detaches the feature, transfers and mints work again.

### What happens to denomination asset left in the treasury after redemptions?

It stays where it is. The maturity feature moves treasury funds only when a redemption pays out, and only for the exact amount that redemption owes, so nothing sweeps the account when redemptions wind down. A treasury funded above face value times supply keeps the surplus under its owner's control. The platform also caps the total paid across all redeemers at face value times the supply at maturity, so overfunding never inflates what holders collectively receive.

### What unit is the face value stated in?

Face value is an amount of the denomination asset, stated in that asset's smallest unit, per whole token, so the gross payout for one whole redeemed token is the face value. A zero face value is refused at construction, so a deployed feature always has a real payout rate.

## Related concepts [#related-concepts]

- [Asset Lifecycle](https://docs.settlemint.com/docs/concepts/issuing-and-markets/asset-lifecycle): The working life a denomination asset pays into.
- [Corporate Action](https://docs.settlemint.com/docs/concepts/issuing-and-markets/corporate-action): Maturity, the event that opens redemptions and settles a denomination asset payout, is one instance of a corporate action.
- [Instrument Templates](https://docs.settlemint.com/docs/concepts/modeling-assets/instrument-templates): The configuration flow where an issuer picks the denomination asset before the bond-style token exists.
- [Composable Token](https://docs.settlemint.com/docs/concepts/modeling-assets/composable-token): The Token Feature model that lets each payout-bearing feature resolve its own denomination asset independently.
- [Asset Class](https://docs.settlemint.com/docs/concepts/modeling-assets/asset-class): The economic grouping an instrument template belongs to, decided before any denomination asset is chosen.
- [Stablecoin](https://docs.settlemint.com/docs/concepts/modeling-assets/stablecoin): The usual choice of denomination asset, though any deployed ERC-20 with readable metadata can serve.


# Instrument Templates

Source: https://docs.settlemint.com/docs/concepts/modeling-assets/instrument-templates
An instrument template lets an issuer configure a new instrument from an approved shape, instead of re-deciding what it records, does, and permits each time.



[Figure] What the issuer fills in, and what the template already locked in for them. One instrument template binds four things: an asset class, an instrument-fact schema, a behaviour list and a compliance template. The asset class is the shelf an operator browses to find the template, such as fixed income or funds. The fact schema names what the record must carry, such as an ISIN or a maturity date, and marks which entries lock permanently at issue. The behaviour list names what the instrument can do on the ledger: mature and redeem, distribute yield, account for fees, convert. The compliance rules decide who may hold it and to whom it may transfer. Every setting in the definition sits on one of two sides. The template fixes part of it, and the issuer never sees those settings. The template leaves the rest open, and the issuer fills them in when creating the instrument. Both sides feed the one deployment that puts the instrument on the ledger. The instrument that results carries exactly the behaviours and locked facts its template required, and records which template it came from. A later edit to that template never reaches it. Labels: One instrument template; Business class; the shelf an operator browses to find it; Instrument facts; what the record must carry, and which entries lock at issue; On-chain behaviours; maturity, yield, fees, conversion, approvals; Compliance rules; who may hold it, and how it may move; The template fixes; the issuer never sees these; and cannot override them; The template leaves open; the issuer fills these in; at the moment of issue; Deployment; The issued instrument; carries exactly the behaviours and locked facts its template required; and records which template it came from. A later edit never reaches it.

One definition splits into what the template fixes and what the issuer fills in, and both feed the one deployment that puts the instrument on the ledger.

An issuer completes only the settings a template leaves open. The template has already fixed every other setting for the whole family.

The Platform API applies the template on every create, so an instrument created through the platform starts with exactly the behaviours its template required.

Later template edits do not rewrite an issued instrument's on-chain configuration. Catalogue names and classification can still change through the template link.

## Why instrument templates matter [#why-instrument-templates-matter]

An instrument template lets a team approve a product shape once, then issue every bond, fund share, or note built to that shape by filling in only the fields it leaves open. A template is the reusable definition behind a product shape. It lets the platform support a whole catalogue of instruments without a new smart contract for each one.

That changes what a new product costs. A new shape needs configuration, not new code, whenever the platform's existing behaviours, fact fields, and compliance modules already cover what it requires. Thirty-six shapes ship with the platform already, listed in the platform's template catalogue. They sit in seven of the nine asset classes the platform ships, the economic categories a template belongs to: fixed income, equity, funds, cash, real assets, digital assets and structured products. The other two classes, derivatives and yield instruments, ship with no template of their own and accept equity-based templates. An issuer who needs a variant copies the closest one and adjusts it.

The second effect is consistency inside a family. Where a desk re-decides the shape at each issuance, two of its bonds can differ in what they record and what they permit, and a reviewer has to read both. A template makes the whole family answer one definition.

A template sets which pricing fields an instrument carries, and the issuer sets what those fields say. A template creates nothing by itself: an issuer selects it, and the instrument exists only once someone issues from it.

## Why a template works through one shared contract [#why-a-template-works-through-one-shared-contract]

The alternative to a template is a new contract for every product line, each with its own review and its own chance to drift from what the last one promised. That path multiplies two things a control function has to track: the code under review, and the number of places the same rule can end up applied differently.

A template is a definition, not a contract. Every instrument the platform issues runs on the same [Composable Token](https://docs.settlemint.com/docs/concepts/modeling-assets/composable-token), the one configurable asset contract behind every product. A template is what configures it: which facts it records, which behaviours it runs, and which compliance rules govern its transfers. A behaviour is what the Console and the API call a [token feature](https://docs.settlemint.com/docs/concepts/modeling-assets/token-features). [Asset Lifecycle](https://docs.settlemint.com/docs/concepts/issuing-and-markets/asset-lifecycle) names this the design stage, the step before anything is issued where the class, template, facts, behaviour, and transfer rules are all decided together. A template is what makes that decision repeatable across a whole family instead of a one-off review for every instrument in it.

## Working with templates day to day [#working-with-templates-day-to-day]

Day to day, an instrument template is an entry in a list your organisation curates. Each template is a draft, published, or unpublished in your organisation, and the issuance flow offers the published ones. A Permission manager, System manager, or Asset designer in your organisation creates, edits, publishes and deletes templates. Three templates that ship with the platform start published in every organisation: Common Equity, Corporate Bond, and Fiat-Backed Stablecoin. Every other shipped template starts unpublished until your organisation publishes it. You can publish and unpublish the shipped templates, but you cannot change them. Anything you want to change starts as a copy, and that copy stays a draft until you publish it.

The draft is where the work happens. You pick the asset class, choose the behaviours the product needs, add the facts the instrument must record, and decide setting by setting what stays fixed and what the issuer fills in. You can fix the fee recipient while leaving the fee rate open. The platform refuses to publish a template while a behaviour you selected is still incompletely configured, and it names the setting it is waiting on, so a half-built shape never reaches the issuance flow.

The rule that decides which side a setting belongs on is what letting it vary would cost the family. Fix a setting when every instrument in the family must answer it the same way. That is what makes the family stand for one approved shape. Leave a setting open when the value differs per issuance, where a near-duplicate template for every variant would cost more than trusting the issuer to fill it in. The fee recipient is worth fixing because the desk's revenue always resolves to the same account whichever instrument earns it. The fee rate is worth leaving open because each deal negotiates its own number. The template only guarantees that a rate exists.

**The template decides four things outright.**

The asset class decides where an operator finds the template. The base asset type is the instrument family the template deploys, such as bond, equity, fund or deposit, and it fixes which pricing fields the instrument carries. The required behaviour list is what the instrument gets exactly as published, because publishing checks for a missing dependency and for a conflicting pair before it lets the list stand. The instrument-fact schema marks each field required, which blocks creation until the issuer fills it, and separately marks it immutable, which locks the value the moment the instrument deploys.

**Three things stay for the issuer to complete at creation.**

Every fact value the template requires, with an immutable one locking on the ledger the moment the instrument deploys. Whichever behaviour settings the template left open arrive as inputs in the creation flow, while the settings the template fixed travel with every instrument unchanged. Compliance sits between the two: the template supplies a starting rule set, the issuer completes it at the compliance step, and what results becomes the instrument's opening transfer controls.

Publishing puts the template into the issuance flow, and a published template never returns to draft. Unpublishing takes it out of the issuance flow for your organisation without making it a draft, so publishing it again needs no second readiness check. A template that a published instrument structure uses cannot be unpublished until the structure is. Creating an instrument then means selecting the template and completing what it left open, and the flow stops at any required fact still empty.

[Figure] A template's one-way path from catalogue to published. A template starts in the platform catalogue, which is shared with every organisation: you publish it for your organisation to issue from it, and you never edit it. Unpublishing takes it out of your picker only. Other organisations keep it. Copying it creates your organisation's own draft, where everything is editable and the platform refuses to publish while a selected behaviour is still incomplete. Publishing runs one way: a published template enters the issuance flow and never returns to draft. Its name, base asset type, facts, behaviours and rules stay editable, only the slug set at creation never changes, and deletion reaches only a template with no instruments behind it. Labels: One template's lifecycle; Platform catalogue; shared with every organisation; publish it to issue from it, never edit it; Unpublish; out of your picker only; other organisations keep it; copy; Your draft; everything is editable; publish refused while a behaviour is still incomplete; publish, runs one way; a published template never returns to draft; Published; offered in the issuance flow; name, facts, behaviours and rules stay editable; the slug, set at creation, never changes; Delete; reaches only a template with; no instruments behind it.

A template moves from copy to draft to published in one direction, and a published template never returns to draft.

Three controls decide what your operators see. Unpublishing, hiding a template and hiding an asset class remove nothing. Unpublishing is what you do to a template your organisation does not offer, shipped or your own: it drops out of your picker and stays available to every other organisation, because the shipped catalogue is common to all organisations and each one keeps its own published state. Your own templates were never visible to another organisation in the first place. Hiding a template also keeps it out of the picker, whatever its published state. Hiding a whole asset class takes its templates out of the step where an operator picks a class, and instruments already created from anything you hide keep working. Deletion reaches only a template with no instruments behind it, because the link each instrument keeps to its template holds the definition in place. A delete against a template with issued instruments is refused with [DALP-181131](https://docs.settlemint.com/docs/api-reference/errors), and a delete against a template that belongs to an instrument structure is refused with [DALP-14383](https://docs.settlemint.com/docs/api-reference/errors).

You can still edit your own published template: its name, its base asset type, the facts it collects, the behaviours it attaches, the compliance rules it points at. One thing never changes after creation: the slug, the identifier the platform derives from the first name. Once instruments have been issued from the template, the storage and mutability of its fact fields lock as well.

## How a template is put together [#how-a-template-is-put-together]

An instrument template sits between the asset class an operator browses and the instrument that ends up on the ledger. A template is a stored definition. It binds the asset class, the base asset type, an instrument-fact schema, a required behaviour list, and an optional compliance template, and that binding is what makes selecting a template enough to issue. The fact schema names each field and its type, from plain text and dates through to the identifiers a securities record needs, such as ISIN, LEI, CUSIP and FIGI. It also marks each field: an identifier or an issue date locks permanently at issue, while a servicing detail such as an auditor or an appraiser stays editable under permission. The behaviour list draws on the platform's own set of on-chain capabilities: maturity redemption, yield distribution, fee accounting, conversion, signed approvals. The [token features catalogue](https://docs.settlemint.com/docs/concepts/modeling-assets/token-features) lists each feature, its parameters, and who operates it. The compliance template is a reusable rule set the issuance flow starts from.

Scope has two levels. Platform templates carry no owner and every organisation sees them, while an organisation's own templates stay visible only to it. A structure of two templates issues one multi-class instrument, such as the Dual-Class Share Structure that the [distribution waterfall](https://docs.settlemint.com/docs/concepts/modeling-assets/token-features/income#distribution-waterfall) pays: a controlling class, sponsor-held and carrying control, paired with an economic class, investor-held and carrying the cash flows and the secondary trading. The pairing says which templates belong together and nothing about compliance. Each class keeps its own rules, because the investor class needs eligibility and transfer-approval checks the sponsor class has no use for.

At issuance the platform reads the definition once and then steps out of the way. The instrument keeps a record naming the template it came from, which is how a portfolio groups by product shape. That record is provenance. The ledger holds the behaviours and the locked facts from the moment of creation, and editing the template afterwards does not reach them.

## The integration contract [#the-integration-contract]

On the API, an instrument template is a settings resource you list, read, create, update, publish and unpublish through the [template endpoints in the API reference](https://docs.settlemint.com/docs/api-reference/v2). Every call that creates a composable asset must name one, and a create that names no template is rejected outright ([DALP-0316](https://docs.settlemint.com/docs/api-reference/errors)). Whatever your client did with the template, the server reads it again and applies it.

Three rules follow. First, the new instrument gets exactly the template's required behaviour list. A template cannot be saved or published while a required behaviour's own dependency is missing or two of its behaviours conflict ([DALP-14094](https://docs.settlemint.com/docs/api-reference/errors)), so the list a create reads is already complete before deployment starts. Configuration you send for a behaviour outside that list is dropped, and the create still succeeds without it. A create call therefore cannot add a capability the published shape does not carry, though the token's governance role can attach one afterwards through the feature endpoints. The conflict check reads every key you send, including the ones about to be dropped. If you send configuration for a behaviour that conflicts with a required one, the create is refused for that pair ([DALP-0605](https://docs.settlemint.com/docs/api-reference/errors)) and the configuration is not dropped silently. Read the created instrument back to confirm which behaviours attached.

Second, the template overwrites a fixed setting with its own value, and supplies that value when your request omitted it. This stops an SDK call from issuing an unapproved variant. A setting the template leaves open but marks required must reach the server, or the create fails ([DALP-9175](https://docs.settlemint.com/docs/api-reference/errors)).

Third, the deployment stamps on-chain facts the template marks immutable as immutable on the token, and the token then refuses a later edit. For an immutable fact stored off chain, the Platform API refuses the edit.

Reading an instrument back returns the template it came from, by identifier and by name, so an integration groups holdings by product shape without keeping its own mapping. A template read resolves the platform catalogue plus your own organisation's templates, and never another organisation's. The identifier is unique across the platform. The name is unique inside the organisation that owns it, and creating a template with a name already in use inside that organisation is refused ([DALP-0463](https://docs.settlemint.com/docs/api-reference/errors)).

A template read also tells you whether the template is still a draft and, in `isPublished`, whether the calling organisation has it published. The issuance flow offers published templates only. The platform enforces the same rule on the API: a create or an issuance run that names an unpublished template is rejected with a non-retryable conflict ([DALP-14019](https://docs.settlemint.com/docs/api-reference/errors) for a create, [DALP-14020](https://docs.settlemint.com/docs/api-reference/errors) for an issuance run). Publish the template through the publish endpoint first.

## Controls and evidence [#controls-and-evidence]

For a control function, an instrument template is the artifact under review. The template is where a product shape wins approval: what the instrument must record, what it may do on the ledger, and which transfer rules it starts from. Review the fixed template settings once, then review each issuance's open values and legal terms under the issuer's own process.

Three platform refusals keep the reviewed shape intact up to issuance. No user can edit or delete the catalogue that ships with the platform, only copy it, though a platform release can change it, so each adjustment your organisation makes stands as its own named template with its own author and timestamps, and the shipped definition stays available for comparison. A template stays a draft until someone publishes it, and the platform refuses to publish one whose behaviours are not fully configured ([DALP-14345](https://docs.settlemint.com/docs/api-reference/errors)), so what reaches the issuance flow is a finished definition. Once instruments exist, the platform also refuses to change where a fact field is stored or whether its value may change ([DALP-12114](https://docs.settlemint.com/docs/api-reference/errors)), so the facts a live family records keep their rules. After issuance, review the token's role holders as well as the template. The governance role can change the instrument's features, compliance rules and identity claims, and a system manager can upgrade the code every Composable Token runs.

The evidence runs in both directions. From a template you reach every instrument an issuer created from it, because each instrument stores that link. You can delete a template with nothing behind it, but never one with live instruments, so the definition behind a live instrument stays retrievable. From an instrument you reach its template and see which recorded facts it declared immutable. The token refuses an edit to an immutable on-chain fact from any role, and the Platform API refuses an edit to an immutable off-chain fact.

Paired templates keep their compliance rules apart. Where two classes of one instrument arrive as a single declaration, each class keeps its own rule set. A controlling class and an economic class carry different restrictions, and copying one onto the other is the error the separation prevents.

## Frequently asked questions [#frequently-asked-questions]

### Is an instrument template a smart contract?

No. A template is a stored definition the platform reads at issuance. What deploys is one generic asset contract, which the platform configures from that definition, so a product shape supported by the existing capabilities needs configuration instead of a new token implementation. Review the configuration and legal terms before issuance. The template decides the configuration and never runs on the ledger itself.

### How does an instrument template differ from a compliance template?

The two work together. An instrument template describes the product: its asset class, the facts it records, and the on-chain behaviours it carries. A compliance template describes the rules a product follows: which controls apply, in which jurisdictions, and which of them an issuer may still adjust. An instrument template can point at one compliance template, so both arrive together when an issuer picks the product shape.

### What happens when a live family needs a shape change the template cannot make?

A shape change is either an edit a published template accepts or an edit it refuses. Adding a fact, adding or removing a behaviour, changing the base asset type, or pointing at a different compliance template are all edits a published template still accepts, and each reaches every instrument created from it after that point. Nothing already issued moves. Once instruments exist, two edits are refused: moving a fact field between on-chain and off-chain storage, and changing whether its value may change. When the family needs one of those, or when the old and new shapes should stay apart, publish a new template instead of editing the old one into it. The two versions then coexist, and an issuer picks the one that matches what they are creating. Every existing instrument keeps pointing at the template it deployed from, so the old and new shapes stay visible as separate definitions.

### What if the catalogue has no matching shape?

You can copy the closest template and adjust it, which keeps the parts that already fit and is the shorter route to a variant of a shape the catalogue carries. Or you can start from a blank template and configure it yourself, which suits a product unlike anything shipped. Both paths produce an ordinary organisation template that goes through the same draft and publish steps.

### Who can create and publish templates?

Only a Permission manager, System manager, or Asset designer in your organisation can create, edit, publish or delete a template. Issuing an instrument from a published template needs the Asset manager role, so the decision about a product's shape can sit with a different person from the decision to bring one to market.

## Related concepts [#related-concepts]

- [Asset Lifecycle](https://docs.settlemint.com/docs/concepts/issuing-and-markets/asset-lifecycle): The whole working life of a regulated tokenised instrument, from issuance through day-to-day servicing to final redemption, on one platform.
- [Composable Token](https://docs.settlemint.com/docs/concepts/modeling-assets/composable-token): The single configurable asset contract behind every new instrument, configured at creation from a template.
- [Asset Class](https://docs.settlemint.com/docs/concepts/modeling-assets/asset-class): The economic grouping an operator browses to reach the templates inside it.
- [Denomination Asset](https://docs.settlemint.com/docs/concepts/modeling-assets/denomination-asset): The asset a payout-bearing behaviour a template attaches, such as maturity redemption, pays holders through, without ever custodying it.
- [Stablecoin](https://docs.settlemint.com/docs/concepts/modeling-assets/stablecoin): An instrument of the Cash class, with a declared peg and an optional collateral check.
- [Transfer-Path Compliance](https://docs.settlemint.com/docs/concepts/compliance-and-identity/transfer-path-compliance): The enforcement of a regulated token's rules inside the on-chain transfer itself, so a movement that fails any rule reverts and never settles.


# Stablecoin

Source: https://docs.settlemint.com/docs/concepts/modeling-assets/stablecoin
A Stablecoin lets an issuer declare a currency peg and enforce a collateral check against a signed claim, on the same record as the rest of the token's life.



[Figure] Collateral enforcement compares a signed claim with the required amount at mint. An illustrative mint results in a supply of 1,000 units. At a collateral ratio of 150 percent, the required claim amount is 1,500 units. The collateral check requires a valid trusted-issuer claim that covers that amount. Other token rules still apply. The signed amount is an attestation. The check does not verify reserves in an external account. Labels: Example: collateral enabled; Post-mint supply; 1,000 units; Includes the new mint; Required collateral; 1,000 × 150% = 1,500; Round up to whole units; Check signed claim; At least 1,500 units; Valid and unexpired; Reserve evidence remains separate; A signed claim attests to an amount. It does not establish an external balance.; Other token rules still apply before the mint can complete.

At a 150 percent ratio, minting to a total supply of 1,000 units requires a valid claim for at least 1,500 units.

An issuer declares a stablecoin's reference currency and price as claims on the token's own identity, and the platform shows the peg next to every mint, transfer, and freeze the token logs. The classification itself does not guarantee redemption or independently verified reserves.

When collateral enforcement is enabled, every mint is checked against a valid, unexpired claim that covers the post-mint supply at the configured ratio, so a mint the attested collateral cannot cover fails before it completes. The ratio defaults to 100 percent, and a ratio of zero disables this check.

Reserve reports and attestations attach to the same asset record for independent review. Uploading them does not verify a reserve balance on chain.

## Why a peg belongs on the token's own record [#why-a-peg-belongs-on-the-tokens-own-record]

A stablecoin is an instrument of the cash [asset class](https://docs.settlemint.com/docs/concepts/modeling-assets/asset-class). An issuer selects that class at design time, and the platform deploys it through the same factory, identity contract, roles and rules as a bond or an equity share.

Off-platform, a stablecoin's peg and its reserve backing are usually published as separate documents the issuer controls. A whitepaper states the peg, and a periodic attestation states the reserve, with no structural link between what circulates on chain and what either document covers. On this platform, the declared reference currency and price are claims, signed attestations that an issuer adds to the token's identity contract, which the token names on chain. The token contract itself logs every transfer and freeze, and the platform shows both on one asset record. When collateral enforcement is turned on, the mint check reads a claim from that same identity, so a reviewer who already checked the peg claim finds the collateral claim beside it.

Running issuance, disclosure and enforcement in separate systems creates handoffs where a ledger state and an attested record can drift apart, as [Asset Lifecycle](https://docs.settlemint.com/docs/concepts/issuing-and-markets/asset-lifecycle) describes. The platform shows a stablecoin's peg claim, its collateral check and its uploaded reserve documents beside its transfer and freeze history on one asset record. The claims and the history are on chain, and the platform stores the documents. An integrator or an auditor reads one asset view for what the token claims and what has happened to it, instead of reconciling a chain state against a separately maintained attestation file. The token's governance role can add and remove the token's claims.

That record answers what the contract enforces. It does not answer whether the reserve behind the peg exists at the stated size. That question is verified through the issuer's own operating process and the documents reviewed under [Review reserve evidence separately](#review-reserve-evidence-separately).

## Configure the token and its disclosures [#configure-the-token-and-its-disclosures]

An issuer creates a stablecoin in the cash asset class, either directly through the creation API or through an Instrument Template, the reusable issuance blueprint that pre-fills required fields and disclosures. Both paths accept the same declared reference currency and declared price, and a collateral ratio that defaults to 10,000 basis points, which is 100 percent, when the request leaves it out. Send 0 to issue without the collateral check. A request can also carry a peg mechanism, one of fiat-backed, crypto-backed, algorithmic, or commodity-backed, and a free-text reserve description. Either one attaches as a claim on the token's own identity the moment it is supplied, and leaving both out attaches nothing. The template also configures a Composable Token, the token assembled from configurable permissions and controls, and can require further features and metadata.

The seeded Fiat-Backed Stablecoin template collects issuer and reserve-attestation metadata alongside the declared peg. Inspect the selected template's own fields before issuance: the platform validates what is submitted, and validation is not evidence that the disclosed reserves exist or hold the stated value.

| Setting | Meaning |
| --- | --- |
| Reference currency and price | The currency and declared price used to value the token. A declared peg price is not a market-price guarantee. |
| Collateral ratio | 0 to 20,000 basis points, which is 0 to 200 percent. The default is 10,000, which is 100 percent. Zero disables the check. |
| Peg mechanism and reserve description | Optional fields on the create request. Either one attaches as a claim on the token's identity when supplied, and neither one establishes reserve backing on its own. |
| Template metadata | The selected template defines the issuer and reserve disclosures collected at issuance. |

The Console displays the peg currency when price-currency data is available. It displays the peg mechanism and reserve description when the token's identity claim supplies them. Missing details stay absent. They are not evidence that a reserve is empty or verified.

Start with [issuing an asset](https://docs.settlemint.com/docs/console/asset-management/issue-new-asset) to select a template and inspect its required fields. Use the [API reference](https://docs.settlemint.com/docs/api-reference) for the creation contract.

## Collateral enforcement checks the attested amount [#collateral-enforcement-checks-the-attested-amount]

Collateral enforcement is a compliance rule on the token. It checks claims on the token's own On-Chain Identity, the registry of attestations attached to that token, and accepts a valid, unexpired claim from an issuer that the trusted issuers registry trusts for the collateral topic, or from an issuer that the rule's own configuration names. Governance sets that configuration, so check that the attesting issuer is independent of the token's issuer. The claim's amount must cover the supply after the proposed mint at the configured ratio.

The required amount is the post-mint supply multiplied by the ratio, rounded up to a whole base unit. For example, 1,000 base units at 150 percent require a claim for at least 1,500 base units. Keep supply and claim amounts in the same units. The check does not convert a reserve's market value into token units.

A signed claim can be valid while its underlying reserve report is wrong. The check inspects the attestation and the amount it states. Independent reserve verification is the issuer's responsibility and happens outside the check.

The collateral check runs at mint. It does not recheck collateral on transfer or burn, and a later claim expiry does not remove existing supply. Other token controls can still restrict those operations.

When collateral enforcement is absent or the ratio is zero, this check does not limit minting. A token's other configured permissions and compliance rules continue to apply. The token's governance role can turn off, remove or reconfigure the collateral rule, ratio included, so review who holds that role and the token's compliance history as well as the current ratio.

## Price freshness follows the feed configuration [#price-freshness-follows-the-feed-configuration]

Every token's price feed has its own staleness window: the maximum age a price observation may reach before a mint or another price-dependent check treats it as unusable. The platform can express a price feed window that never expires, alongside an ordinary maximum-age window measured in seconds. A declared peg price suits the non-expiring kind, since a fixed peg does not go stale the way a moving market feed does.

The feed system supports a non-expiring window, and the business class does not set one, so check the asset's own feed configuration. A non-expiring window treats the declared peg price as fixed. It does not show that a market price still matches it. [Market Data](https://docs.settlemint.com/docs/concepts/records-and-evidence/market-data) explains feed observations and their validation.

## Review reserve evidence separately [#review-reserve-evidence-separately]

The platform provides document categories for reserve audits, attestation reports, and reserve composition. It also supports legal opinions and regulatory filings. The category list describes the documents an issuer can attach. It is not a requirement that every stablecoin has supplied them.

Verify the reserve account, valuation method, report date, and redemption terms through the issuer's operating process. A document upload, declared peg, or successful mint does not establish that holders can redeem at the stated price.

## Frequently asked questions [#frequently-asked-questions]

### Why does a mint fail after a collateral claim expires?

With a nonzero collateral ratio, the mint check requires a valid claim that covers the resulting supply. Renew the attestation through a trusted issuer and confirm its amount before retrying. A larger mint can also fail when the claim remains valid but no longer covers the required amount.

### Does a collateral ratio of 150 percent establish 150 percent reserve backing?

It requires an attested amount of at least 150 percent of post-mint supply. Establishing the underlying reserve balance requires separate evidence.

### Does a stablecoin classification enable collateral checks?

Yes, by default. A stablecoin created without a ratio gets the 100 percent default, so its mints are checked. Send a ratio of 0 to turn the check off. Inspect the asset's compliance rules for the collateral rule and its ratio, because governance can change them after issuance.

## Related concepts [#related-concepts]

- [Asset Lifecycle](https://docs.settlemint.com/docs/concepts/issuing-and-markets/asset-lifecycle): The whole working life of a regulated tokenised instrument, from issuance through servicing to redemption. A stablecoin's mint-time collateral check runs inside that same Service stage.
- [Instrument Templates](https://docs.settlemint.com/docs/concepts/modeling-assets/instrument-templates): Select the features and metadata required for issuance, including the seeded Fiat-Backed Stablecoin template.
- [Composable Token](https://docs.settlemint.com/docs/concepts/modeling-assets/composable-token): Combine the token's permissions and runtime controls that a stablecoin, like any other issued asset, is assembled from.
- [Asset Class](https://docs.settlemint.com/docs/concepts/modeling-assets/asset-class): The catalogue grouping, cash, that a stablecoin belongs to alongside deposits and certificates of deposit.
- [Compliance Policy](https://docs.settlemint.com/docs/concepts/compliance-and-identity/compliance-policy): Define and review the rules applied to the asset, including the collateral check itself.
- [Denomination Asset](https://docs.settlemint.com/docs/concepts/modeling-assets/denomination-asset): Use a token as the payment or settlement asset for another instrument.


# Balances, holds and delegates

Source: https://docs.settlemint.com/docs/concepts/modeling-assets/token-features/balances-and-holds
Reference for the historical balances, voting power, hold and supply delegate token features: what each records or restricts and who operates it.

Four token features cover balances over time and who may move or create units. Historical balances records balances so any past time can be read, and voting power turns balances into vote weight. Hold reserves units in a holder's wallet without moving them, and supply delegate lets a registered wallet or add-on mint and burn. This page states what each feature does, its parameters, and who operates it after issuance, with a worked example.

A [token feature](https://docs.settlemint.com/docs/concepts/modeling-assets/token-features) is a module attached to one token. An account with the token's governance role attaches, detaches and configures it after issuance where the feature allows it, and each entry names any other role an action needs. The DALP Library is the catalogue of [instrument templates](https://docs.settlemint.com/docs/concepts/modeling-assets/instrument-templates) that ship with the platform, and each entry says which of them include the feature.

## Historical balances [#historical-balances]

Records every account's balance and the total supply after each mint, burn, or transfer, so any past time can be queried. The token calls the feature once for each operation with the legs that executed. The feature sums each account's net change and writes one checkpoint per touched account, plus one for total supply when it changed. Checkpoints are keyed by timestamp, and several writes in one block keep the last. `balanceOfAt` and `totalSupplyAt` return the latest checkpoint at or before the time you ask for, and a future time is rejected. Dividend yield, interest yield, and the distribution waterfall read it for record-date balances, and fixed treasury yield needs it too, as [Income features](https://docs.settlemint.com/docs/concepts/modeling-assets/token-features/income) describes. Choose it on any token that pays dividends or interest. The DALP Library includes it on 35 of its 36 system templates, all except Custody receipt. [Ledger Data](https://docs.settlemint.com/docs/concepts/records-and-evidence/ledger-data) explains why a point-in-time record matters.

The feature has no parameters and no role after issuance. It cannot be detached while fixed treasury yield, dividend yield, interest yield, or the distribution waterfall is attached. The Console's attach list does not offer it. It arrives through a template or through the Platform API's attach route.

The feature records the time it started. A token has 1,000 units on day 0, and the feature starts on day 10. The standard `totalSupplyAt` query for day 5 returns 0, because no checkpoint exists at or before day 5. The strict variant rejects the same query with `QueryBeforeEnabled`. A query for day 12 with no activity since returns 1,000.

While the feature is detached it records nothing, so a lookup for that period returns the last checkpoint written before the detach. Remove dependent features before detaching historical balances.

## Voting power [#voting-power]

Turns balances into voting units with their own checkpoints. A holder has one voting unit per token held. Units count as votes only for the address the holder delegates to, so a holder who has not delegated has no votes. The Console action "Activate voting power" delegates to the holder's own wallet. On every mint, burn, and transfer, the feature moves units between delegates and writes checkpoints, so `getPastVotes` and `getPastTotalSupply` answer for a past time. Delegation moves vote weight and leaves token balances unchanged. The token's governance addon reads the feature as its source of vote weight. The DALP Library includes it on eight templates: Commercial Real Estate, Common Equity, Convertible Target Equity, Economic Class Share, Employee Equity Award, Mutual Fund, Private Equity Fund, and Tokenised Art.

The feature has no parameters. After issuance, a holder delegates. A holder delegates through the delegation route, which needs an activated identity registration for the delegating wallet. The Platform API has no route that relays a delegation signed off platform. Governance attaches and detaches the feature, and the Governance wizard offers an inline attach when the token lacks it. A detach is blocked while the token's governor has pending, active, or queued proposals.

Alice holds 600 tokens and Bob holds 400. Alice has activated her voting power, and Bob has not. A vote with record date T reads 600 votes for Alice and 0 for Bob. The total supply at T is 1,000, so the delegated weight is 600 of 1,000. If Bob delegates after T, his weight counts only for votes with a later record date. See [Governance](https://docs.settlemint.com/docs/console/my-assets/votes) for the screens.

## Hold [#hold]

Lets a reserver, an account or add-on authorised to hold units, commit units in the holder's wallet without moving them. The units stay where they are, but the holder can no longer spend them: a transfer or burn above the available balance is rejected with `AmountExceedsAvailable`. The available balance is the balance, less the units the custodian froze, less the units held. A wallet the custodian froze in full has no available balance. Releasing a hold moves no units, and the feature records a release event. A reserver places a hold on any holder's units and can deliver the held units to a recipient, without the holder's signature. The delivery runs the token's full compliance path. Each reserver touches only its own reservations. A hold can have a lifetime in seconds or never expire, and an expired hold stops counting at once. Choose it when an add-on, such as the [custody gateway](https://docs.settlemint.com/docs/concepts/custody-and-signing/custody-gateway), must commit units inside the holder's own wallet. The DALP Library includes it on 34 templates, all except Controlling Class Share and Economic Class Share. It comes first in every one except Share-Class Mirror, which lists historical balances first.

The feature has no attach parameters. It starts with an empty reserver list. Governance authorises outside reservers, and a feature attached to the same token enrols itself, with no expiry, the first time it places a hold. Each enrolment takes one of the 32 slots, and a detached feature keeps its slot until governance removes it. Authorise a reserver only for a system you trust, such as the custody gateway.

After issuance, an account with the governance role authorises and removes reservers, at most 32 at a time. The Console lists the reservers and removes them, and adding a reserver is a Platform API action that accepts a lifetime. Removing a reserver makes all its reservations stop counting at once. Anyone can clear a reservation that no longer counts, because it expired, its reserver was removed, or the feature that placed it was detached, and the Features tab lists these inactive reservations with a "Clear" action. A forced custody update, such as a custodian forced transfer, passes the check by design, and mints never touch held units.

A holder has 1,000 units. The custodian froze 100, and a reserver holds 300. The available balance is 600, so a transfer of 700 reverts with `AmountExceedsAvailable`, and so does a new reservation of 700. A custodian forced transfer of 700 succeeds and can leave the holder below the held total, and the available balance then reads 0.

The feature belongs first in the token's list, so a fee or rewrite feature cannot consume units that the hold already committed. The DALP Library puts it first on every template except Share-Class Mirror, and a feature attached later goes to the end of the list. The Console attaches it from the "Attach a feature" list on the token's Features tab. It runs on EVM only.

## Supply delegate [#supply-delegate]

Lets a registered wallet or add-on mint and burn a token's units without holding the supply management role. The governance role decides who may mint, who may burn, and how many units a minter may have outstanding. A delegate is a wallet, or a contract that vouches for other callers, such as a system add-on factory that vouches for the add-ons it deployed. A vouching delegate does not mint or burn itself. Each caller it vouches for acts as the delegate. The platform rejects a vouching delegate that is not a contract answering which callers it vouches for. Each delegate may mint, burn, or both, and a delegate with neither is rejected. Choose it when a system, such as a custody gateway or the bank rail, must create and retire units in step with deposits and payments, and you do not want to hand that system the supply management role.

The feature has no attach parameters. It starts with no delegates, so it mints and burns nothing until governance adds one. A token holds at most 32 delegates. Adding a delegate that is already registered is rejected. To change its permissions, remove it and add it again.

A mint runs the token's full compliance path, so a receiver that the token's compliance rules reject is rejected. A burn takes units only from the caller's own balance, so a delegate cannot burn another holder's units, and units that a hold feature reserves stay out of reach. Each mint and burn has a 32-byte reference that the caller picks, or zero for none. A custody gateway passes its deposit or request identifier, and the bank rail passes a hash of its bank transaction identifier, so no bank data goes on the chain. The platform does not check that a reference is unique.

A minting delegate can have a cap. The cap bounds the delegate's outstanding units, which are its mints minus its own burns, never below zero. A burn frees room under the cap again, but only for units that leave the total supply: when a transaction fee feature turns part of a burn into a fee payment, that part frees nothing. A vouching delegate has one count shared by every caller it vouches for. With no cap, the delegate can mint any amount, and governance can register a minter without one, so set a cap for every delegate you add. A mint past the cap is rejected with an error that names the cap and the outstanding count. A delegate with a cap of 1,000,000 units that has minted 600,000 and burned 200,000 has 400,000 outstanding and may mint 600,000 more.

After issuance, an account with the governance role attaches and detaches the feature. The Console attaches it from the "Attach a feature" list on the token's Features tab, and its section there shows a short description. The Platform API adds and removes delegates, with the governance role and a wallet verification. Removing a delegate stops its next mint or burn at once, but its outstanding count stays, because the units it minted are still in circulation. The feature cannot sit beside the [booked movements](https://docs.settlemint.com/docs/console/asset-management/manage/booked-movements) feature, which keeps register lines and which this catalogue does not cover: a template or an attach that combines them is rejected. The DALP Library includes it on one template, Custody receipt, which pairs it with hold. It runs on EVM only. [Custody receipt](https://docs.settlemint.com/docs/concepts/custody-and-signing/custody-receipt) explains the gateway that uses it, and [Bank rail](https://docs.settlemint.com/docs/console/asset-lifecycle/bank-rail) covers the other.


# Conversion features

Source: https://docs.settlemint.com/docs/concepts/modeling-assets/token-features/conversion
Reference for the conversion and conversion minter token features that turn a loan or convertible token into newly minted target tokens.

Two token features work as a pair to convert one instrument into another. The conversion feature sits on a loan or convertible token and prices each conversion. The conversion minter sits on the target token and mints the result for the conversion features it lists. Set a pair up in this order: issue the target token with the conversion minter, issue the loan token with the conversion feature pointing at that target, then add the conversion feature's address to the minter's converters. A conversion fails when the target token has no conversion minter or the minter does not list the conversion feature.

A [token feature](https://docs.settlemint.com/docs/concepts/modeling-assets/token-features) is a module attached to one token. An account with the token's governance role attaches, detaches and configures it after issuance where the feature allows it, and each entry names any other role an action needs. The DALP Library is the catalogue of [instrument templates](https://docs.settlemint.com/docs/concepts/modeling-assets/instrument-templates) that ship with the platform, and each entry says which of them include the feature.

## Conversion [#conversion]

Turns a holder's balance of a loan or convertible token into newly minted target tokens at a price that a trigger sets. Governance publishes a trigger, the priced offer a holder converts against, such as a financing round. A trigger holds the round price per target token. The custodian can also force a conversion for a holder, without the holder's signature. The effective price is the round price less the discount, rounded down, and limited to the price cap when one is set. The converted principal, plus accrued interest when interest converts, divides by that price to give the target amount, rounded down to the target token's decimals. The loan side then reduces its exposure with the debt method, and the target token's conversion minter mints the result. The call is atomic: a failed mint reverts the principal reduction. Choose it for convertible notes, SAFEs, and warrants. The platform values the loan token one for one in the denomination asset, so a loan token worth less or more than one unit still converts at one. The DALP Library includes it on four templates: Carbon Credit, Convertible Note, SAFE, and Warrant.

[Figure] A conversion links a loan token to a target token. Governance publishes a trigger that holds a round price per target token. A holder converts loan tokens against that trigger. The conversion feature sits on the loan token. It prices the conversion, then retires the converted principal by the configured debt method: burn, lock in escrow, or mark as converted. It then calls the conversion minter on the target token, which accepts calls only from converters on its allow list. The minter mints the target tokens to the holder, once for each conversion identifier. Labels: Trigger; Published by governance:; a round price.; Holder; Converts loan tokens; against a trigger.; Conversion feature; On the loan token.; Prices and reduces debt.; Conversion minter; On the target token.; Converters on its allow list.; mints; Principal retired; Burned, locked, or; marked as converted.; Target tokens minted; To the holder, once for; each conversion id.

The conversion feature on the loan token and the conversion minter on the target token point at each other, and the minter mints only for listed converters.

All fourteen settings are fixed at issuance, except the window, which governance can change later. The Issue asset form shows the first six rows of the table, with the target token first, and an "Include accrued interest" switch for `includeInterestInConversion`. The other settings take their defaults, and you set them in the template's feature settings or through the Platform API.

| Parameter | Description |
| --- | --- |
| Target token address (`targetToken`) | The DALP asset that holders receive. It must have the conversion minter and cannot be the loan token. No asset class is required. |
| Conversion denomination asset (`denominationAsset`) | The [denomination asset](https://docs.settlemint.com/docs/concepts/modeling-assets/denomination-asset) that prices the conversion. Every trigger and any interest provider must use the same asset. |
| Conversion discount (BPS) (`discountBps`) | Discount on the trigger's round price, 0 to 9,999 basis points. The default is 0. A value of 2000 means 20%. |
| Conversion price cap (per share) (`capPricePerShareWad`) | The highest effective price for one target token, in the denomination asset, which the API takes as an 18-decimal fixed-point value. Leave it blank for no cap. It cannot change after issuance. To use a valuation cap, divide it by the fully diluted share count. |
| Conversion window start (`conversionWindowStart`) | When conversions open, as a date. Blank means open from now. |
| Conversion window end (`conversionWindowEnd`) | When conversions close. Blank means no deadline. It cannot be before the start. |
| Minimum conversion amount (`minConversionAmount`) | The smallest conversion, in loan token base units. The default is 0, which means no minimum. |
| Partial conversion allowed (`partialAllowed`) | Whether a holder can convert part of a balance. The default is false: the holder converts the whole balance. |
| Include interest in conversion (`includeInterestInConversion`) | Whether accrued interest converts with the principal. The default is false. When true, token creation also binds the conversion feature as the only consumer of the interest provider. That bind cannot be undone. |
| Interest provider (`interestProvider`) | The interest yield or fixed treasury yield feature that supplies the interest. 0 finds it automatically when exactly one is attached. |
| Close interest on conversion (`closeInterestOnConversion`) | Whether a full conversion stops the holder's interest accrual. The default is true. |
| Debt method (`debtMethod`) | How the loan side retires the principal: 0 Burn (the default), 1 Lock, or 2 MarkConverted. |
| Escrow address (`escrowAddress`) | The account that receives locked principal. Required when `debtMethod` is 1, and 0 otherwise. |
| Conversion minter (`conversionMinter`) | The conversion minter on the target token. 0, the default, finds it automatically. |

The debt method decides what happens to the loan tokens. Burn destroys the converted principal. Lock moves it to the escrow account, which then holds it. MarkConverted moves nothing: the holder keeps the loan tokens, but converted tokens can no longer be transferred or burned, and "convert all" converts only the unconverted balance. No Library template pins Lock or MarkConverted. MarkConverted also blocks attaching interest yield or fixed treasury yield later, and it rejects a partial conversion while a fixed treasury yield feature is attached.

After issuance, governance publishes and disables triggers and changes the conversion window. The window is a conversion setting, but the Platform API route that updates it is addressed with the feature name `conversion-minter`. Neither the Console nor the Platform API rotates or detaches the conversion feature, so through the platform no other term changes. On chain, the token's governance role can still replace the whole feature list, conversion included. A holder converts the holder's own balance and, when interest converts, the holder's accrued interest. A full conversion that would close accrual while convertible interest remains first needs that interest drained. The Platform API drains it in up to 10 rounds before it converts. A forced conversion skips that check. The custodian role can force a conversion. [Token conversion](https://docs.settlemint.com/docs/console/asset-management/manage/conversion) walks through publishing a round, holder and forced conversions, and what the holder sees.

A holder with 100,000 loan tokens, all with 18 decimals, converts against a trigger with a round price of 2.50. The discount is 20%, the cap is 1.80, accrued interest is 3,000, and interest converts. The discounted price is 2.00, so the cap lowers the effective price to 1.80. The value is 100,000 plus 3,000, which gives 103,000. The holder receives 103,000 divided by 1.80, which is 57,222.22 target tokens. Without the cap the holder would receive 51,500, and without interest 55,555.56.

A conversion that rounds to zero target tokens is rejected, so a decimal mismatch cannot burn principal for nothing. When rounding drops part of a target token, the conversion record keeps that fraction, and Conversion History shows it under the target tokens received. 100 notes with 18 decimals, converted at 0.72 into a target with 0 decimals, give 138 target tokens, and the row shows 0.888888888888888888 lost to rounding. Nothing pays the fraction out. The conversion feature has a second generation, the newer feature implementation that [Token features](https://docs.settlemint.com/docs/concepts/modeling-assets/token-features) describes. It retires the principal as a booked movement, a movement the token executes outside the fee and rewrite features, so a transaction fee or an external fee on the loan token takes no part of the principal. Both generations share one configuration. The figure on this page shows how the loan and target tokens pair, and the corporate action "conversion" in [Corporate actions](https://docs.settlemint.com/docs/console/asset-management/manage/corporate-actions) runs it for a bond.

Each conversion counts once in the totals, by its conversion identifier. For the feature, the platform keeps the number of conversions, the principal converted, the interest converted and the target tokens issued. For each trigger it keeps the number of conversions and the principal converted, and for each holder it keeps the principal converted. A repeated event for a recorded conversion does not change a total.

## Conversion minter [#conversion-minter]

Sits on the target token and mints there only for the conversion features on its allow list. A call from any other address is rejected. Each conversion has a unique identifier, and the minter marks it used before it mints, so a replay fails on the loan side and on the target side. It records the recipient, the amount, the loan token, the converter, and the trigger for each issuance. Choose it on any token that other instruments convert into. The DALP Library includes it on two templates: Carbon Credit and Convertible Target Equity. Neither lists a converter.

| Parameter | Description |
| --- | --- |
| Convertible classes (`authorizedConverters`) | The conversion features that may mint here. Zero to 100 rows, each a distinct conversion feature address. The list starts empty. |

After issuance, an account with the governance role and the Supply management or admin role adds converters, because an authorised converter mints on the target token. Governance alone removes them. The Console action "Add converter" takes the conversion feature's address on the loan token. A wallet or other contract that is not a conversion feature is rejected. The second generation mints as a booked movement, so a fee on the target token takes no part of the issued tokens. Detaching the minter while a conversion is live leaves every conversion on that pair reverting. [Corporate Action](https://docs.settlemint.com/docs/concepts/issuing-and-markets/corporate-action) covers the conversion as a corporate action.


# Fee features

Source: https://docs.settlemint.com/docs/concepts/modeling-assets/token-features/fees
Reference for the token features that charge or record fees: management fee, transaction fee, transaction fee accounting and external transaction fee.

Four token features charge or record fees, and they differ in who pays and what moves. The management fee mints new tokens to a recipient and dilutes holders. The transaction fee takes a percentage of each operation in the same token. Transaction fee accounting records that percentage and moves nothing. The external transaction fee pulls a fixed amount of a second token from the payer. The [side-by-side comparison on the Token features page](https://docs.settlemint.com/docs/concepts/modeling-assets/token-features) shows one transfer under each fee.

A [token feature](https://docs.settlemint.com/docs/concepts/modeling-assets/token-features) is a module attached to one token. An account with the token's governance role attaches, detaches and configures it after issuance where the feature allows it, and each entry names any other role an action needs. The DALP Library is the catalogue of [instrument templates](https://docs.settlemint.com/docs/concepts/modeling-assets/instrument-templates) that ship with the platform, and each entry says which of them include the feature.

## Management fee [#management-fee]

Accrues an annual management fee on the token's time-weighted average supply and mints it to the fee recipient when someone collects it. It never touches a transfer, a mint, or a burn. It dilutes holders instead: every holder's share of supply shrinks by the amount minted, and the recipient gains it. The accrued fee is the average supply since the last collection, multiplied by the yearly rate and the elapsed time, divided by 365 days, and rounded down. Choose it for a fund-style fee that must not change any holder's balance or any transfer. The DALP Library includes it on five templates: Mutual Fund, ETF, Money Market Fund, Private Equity Fund, and Commercial Real Estate.

| Parameter | Description |
| --- | --- |
| Management fee (BPS) | The yearly rate in basis points, 0 to 10,000. 100 basis points equal 1%. |
| Management fee recipient | The account that receives each collection. |

After issuance, an account with the governance role sets the rate, sets the recipient, and freezes both. Changing the rate first settles the fees accrued so far at the old rate, when the old rate and the accrued amount are both greater than zero. The second generation, the newer feature implementation that [Token features](https://docs.settlemint.com/docs/concepts/modeling-assets/token-features) describes, settles the same way when the recipient changes, paying the old recipient. Only an accrual that rounds down to zero carries over to the new recipient. On that generation, a recipient change fails while the token refuses the payment, for example while it is halted, or while the old recipient's address is frozen on the token or no longer eligible to hold it. In the first generation, changing the recipient settles nothing, so earlier accruals go to the new recipient at the next collection. A management fee moves to the second generation when a Permission manager or System manager runs [System updates](https://docs.settlemint.com/docs/console/organisation-settings/system-updates) on the asset's network, once the platform runs DALP 3.2. A freeze locks the rate and the recipient of this feature instance and cannot be undone. It does not bind the token: the governance role can replace or detach the frozen feature and attach a new one with other terms. Any account can collect, and the collection pays the accrued fee to the recipient in force at that moment. Collection continues after a freeze. The how-to [Fee administration](https://docs.settlemint.com/docs/console/asset-management/manage/fee-administration) covers the screens.

With a constant supply of 1,000,000 tokens and a 1% rate, a full year accrues 10,000 tokens. The supply becomes 1,010,000, and a holder of 100,000 tokens falls from 10% to 9.901% of supply. The next period starts from 1,010,000. When the supply changes during the period, the average decides the fee. A supply of 1,000,000 tokens for 180 days and 1,500,000 tokens for the next 185 days averages 1,253,424.66 tokens, so the fee is about 12,534.25 tokens. The closing supply would give 15,000. A fee that rounds down to zero does not reset the window, so the accrual keeps growing until it produces a whole base unit.

In the second generation, the fee mint is a booked movement, a movement the token executes outside the fee and rewrite features. A transaction fee on the same token does not split it, transaction fee accounting does not record it, and an external transaction fee is not charged on it. Compliance and identity checks still apply to the recipient.

## Transaction fee [#transaction-fee]

Takes a fee as a percentage of each mint, burn, or transfer and splits the operation into two legs, the balance movements it settles into: a net leg to the receiver and a fee leg to the recipient. The second generation rounds the fee up to the next base unit, so any non-zero amount at a non-zero rate pays at least one base unit. The first generation rounds it down. The amount the user asked to move is always the total. A transfer of V sends V less the fee to the receiver, and the fee from the sender to the recipient. A mint of V mints V less the fee to the target and the fee to the recipient. A burn of V sends the fee from the holder to the recipient and burns the rest. The fee is not dilutive: supply changes only by the mint or burn the user asked for. No fee applies to a zero-value operation, to an operation that involves the fee recipient, to a custodian forced update, to a zero rate, to a first-generation fee that rounds down to zero, or to a booked movement such as a management fee mint. With a rate of 10,000 basis points, the whole amount goes to the recipient. The DALP Library includes it on one template, Mutual Fund.

| Parameter | Description |
| --- | --- |
| Mint fee (BPS) | The fee on a mint in basis points, 0 to 10,000. The default is 0. |
| Burn fee (BPS) | The fee on a burn in basis points, 0 to 10,000. The default is 0. |
| Transfer fee (BPS) | The fee on a transfer in basis points, 0 to 10,000. The default is 0. |
| Fee recipient | The account that receives the fees. |

After issuance, an account with the governance role sets all three rates together, sets the recipient, and freezes the rates. A freeze locks the rates of this feature instance only and cannot be undone, and governance can still replace or detach the feature. Setting the recipient still works after a freeze, and the change applies to the next operation. The fee leg runs the full pipeline, so an ineligible recipient blocks the whole operation. [Fee administration](https://docs.settlemint.com/docs/console/asset-management/manage/fee-administration) covers the screens.

A transfer of 100 tokens with a 250 basis point fee gives the receiver 97.5 and the recipient 2.5, and the sender pays 100. A mint of 100 at 100 basis points gives the target 99 and the recipient 1, and supply rises by 100. A burn of 100 at 100 basis points costs the holder 100, pays the recipient 1, and lowers supply by 99. On a 6-decimal token, 33.333333 tokens is 33,333,333 base units. At 150 basis points the second generation takes 500,000 base units, so the net is 32,833,333. An amount of 99 base units at 100 basis points has a fee of 1 and a net of 98, so splitting a transfer into small pieces no longer avoids the fee. The first generation takes 0 on that amount and passes it through unsplit.

A maturity redemption of a second-generation bond is refused when the burn fee takes the whole amount, for example 1 unit on a 0-decimal token with a non-zero burn fee. A batch redemption reports that holder as a skip.

In the second generation, a forced or booked movement emits no fee event. The first generation emitted an event even though it took no fee. Transaction fee cannot sit beside transaction fee accounting.

## Transaction fee accounting [#transaction-fee-accounting]

Applies the same percentage math as the transaction fee, including rounding up in the second generation, and records the result without collecting anything. On each mint, burn, or transfer, it computes the fee on the gross amount, adds it to a running total, and emits a fee event. Balances, supply, and transfers are untouched, and the recipient receives nothing on chain. Use it for off-chain invoicing and reporting. The DALP Library includes it on two templates, ETF and Asset-Backed Token. It cannot sit beside the transaction fee, because the two would account for the same transfer.

| Parameter | Description |
| --- | --- |
| Accounting fee on mint (BPS) | The recorded fee on a mint, 0 to 10,000. The default is 0. |
| Accounting fee on burn (BPS) | The recorded fee on a burn, 0 to 10,000. The default is 0. |
| Accounting fee on transfer (BPS) | The recorded fee on a transfer, 0 to 10,000. The default is 0. |
| Accounting fee recipient | The account named in the records. |

After issuance, an account with the governance role sets the rates and the recipient, freezes both, sets a per-account fee exemption, and reconciles. Reconcile reads the running total, sets it to zero, and emits a record. It moves no tokens and distributes nothing, because the actual collection happens off chain. A second reconcile with a zero total is rejected with `NoFeesToReconcile` ([DALP-1070](https://docs.settlemint.com/docs/api-reference/errors)). Reconcile and the exemption work after a freeze. An exempt account is skipped when it is on either side of an operation. Only transaction fee accounting has a per-account exemption. The other three fee features do not. A redemption accrues once at the burn rate.

A transfer of 100 tokens at 250 basis points records a fee of 2.5, and the receiver still gets all 100. After a reconcile of 1, the total reads 0, and no balance changes. The second generation skips booked movements, so a management fee mint no longer inflates the total.

## External transaction fee [#external-transaction-fee]

Charges a fixed fee for each mint, burn, or transfer, pulled in a second token. The token amount moves in full, and the fee does not depend on the amount. The payer is the account that receives a mint, or the sender of a transfer or a burn. The feature pulls the fee from the payer to the fee recipient with an ERC-20 transfer, so the payer must hold the fee token and must have approved the feature contract to spend it. That approval is an allowance, the amount of a token that one account lets another account spend. A payer without balance or allowance makes the whole token operation revert. The fee recipient is not exempt: when the recipient pays, it pays itself and still needs the allowance. Custodian forced updates, zero-value operations, and a fee token of zero charge nothing. The DALP Library includes it on one template, Asset-Backed Token.

| Parameter | Description |
| --- | --- |
| Fee token address | The ERC-20 token that pays the fee. It cannot be the token itself or the feature contract. A zero address charges nothing, whatever the fee amounts. |
| External fee recipient | The account that receives the fees. |
| External mint fee | The fixed fee for a mint. |
| External burn fee | The fixed fee for a burn. |
| External transfer fee | The fixed fee for a transfer. |

The issuance form takes the three fee amounts in base units of the fee token. After issuance, the "Set external fee amounts" sheet takes decimal units and scales them by the fee token's decimals, so 2.5 in the form is 2.5 base units and 2.5 in the sheet is 2.5 tokens. A zero fee token means the feature collects nothing.

After issuance, an account with the governance role sets the amounts, the recipient, and the token, and freezes them. A freeze locks the amounts, the recipient, and the token of this feature instance, and cannot be undone. Governance can still replace or detach the feature. Collection continues after a freeze. Payers approve the feature, not the recipient. With a fee of 2,500,000 base units of a 6-decimal fee token, a 100-token transfer costs the sender 100 tokens plus 2.5 fee tokens, and a 200-token transfer costs the same 2.5. A mint of 100 tokens charges the account that receives the mint, even when the issuer submits it. A redemption is charged at the burn fee.

In the second generation, a booked movement such as a management fee mint is not charged. See [Fee administration](https://docs.settlemint.com/docs/console/asset-management/manage/fee-administration) for the neighbouring fee screens.


# Income features

Source: https://docs.settlemint.com/docs/concepts/modeling-assets/token-features/income
Reference for the token features that pay holders: dividend yield, interest yield, fixed treasury yield, maturity redemption and the distribution waterfall.

Four token features pay holders income or principal from a treasury, and a fifth, the distribution waterfall, splits one pool across share classes. Dividend yield pays an amount per share that the issuer declares, interest yield accrues a rate over time, fixed treasury yield pays a fixed coupon each period, and maturity redemption pays face value once after maturity. The distribution waterfall decides no per-holder amount: it splits one pool across share classes, and each class's dividend yield pays from its own part.

A [token feature](https://docs.settlemint.com/docs/concepts/modeling-assets/token-features) is a module attached to one token. An account with the token's governance role attaches, detaches and configures it after issuance where the feature allows it, and each entry names any other role an action needs. The DALP Library is the catalogue of [instrument templates](https://docs.settlemint.com/docs/concepts/modeling-assets/instrument-templates) that ship with the platform, and each entry says which of them include the feature.

## Dividend yield [#dividend-yield]

Pays a cash dividend that the issuer declares, with an amount per share. After the record date, governance records one holder snapshot. The platform reads each holder's balance on that date from [historical balances](https://docs.settlemint.com/docs/concepts/modeling-assets/token-features/balances-and-holds#historical-balances), works out each holder's amount, and fixes the full list of entitlements in a Merkle tree, a compact fingerprint that lets each holder prove their own entry. Holders then pull their claim: the feature pays it from the treasury and never holds the money itself. Declaring a dividend and recording the snapshot move no money. A claim reverts when the treasury is short. Choose it for equity-like instruments where the issuer decides each payout. The DALP Library includes it on nine templates: Controlling Class Share, Economic Class Share, Common Equity, ETF, Mutual Fund, Preferred Equity, Private Equity Fund, Commercial Real Estate, and Sukuk Ijara.

| Parameter | Description |
| --- | --- |
| Dividend denomination asset | The [denomination asset](https://docs.settlemint.com/docs/concepts/modeling-assets/denomination-asset) that pays dividends. It cannot be the token itself or a registered fee-on-transfer or rebasing token. |
| Dividend treasury | The account that pays holders, or the distribution waterfall for a share-class instrument. A wallet treasury must approve the feature to spend. A vault contract pays itself. |
| Default claim deadline (days) | How many days holders have to claim when a declaration names no deadline, counted from the payment date, or from the declaration if that is later. At least 1. The default is 90. |

All three settings are fixed at issuance. The feature has no setter for the treasury, so the only way to change one is to detach the feature and attach a new one, which is refused while declared dividends are still unclaimed.

For each dividend, the issuer enters the amount per share, the ex-date, the record date, the payment date, and optionally a claim deadline. The dates run in order, and the claim deadline must be in the future. A record date in the past is allowed when historical balances cover it. Without a claim deadline, the platform sets the later of the payment date and today, plus the default days. An identical declaration retried with the same idempotency key keeps the deadline derived for the first accepted write. A retry within the 24-hour idempotency window returns the first declaration and does not extend that window. While the first submission is still in flight, the retry joins it without a second eligibility check. If the first submission failed before signing, the retry runs the full eligibility check again and keeps the original deadline.

After issuance, an account with the governance role declares a dividend, records its snapshot once the record date has passed, and cancels a dividend before its snapshot exists. Anyone can fund the treasury, with a plain transfer or with `POST /api/v2/tokens/{assetId}/features/dividend-yield/dividends/{dividendId}/top-ups`. The Console shows Fund dividend only to the governance role. A holder with a verified identity claims, or an account with the custodian role claims on a holder's behalf, and either way the payout goes to the holder's wallet. An account with the emergency role pauses and resumes claims from the "Claims" row on the token's Features tab. The claim deadline is soft: a holder can still claim after it until governance reclaims the dividend. Once the deadline has passed, the Console marks the dividend Expired and offers the reclaim to the governance role as "Release unclaimed". The Platform API offers it as `POST /api/v2/tokens/{assetId}/features/dividend-yield/dividends/{dividendId}/reclaim`. A reclaim closes the dividend and releases the feature's liability, after which the row reads Released. It moves no tokens, because the treasury never lost them. Governance can also extend a payable dividend's claim deadline once, by an on-chain call that neither the Console nor the Platform API offers. [Corporate Action](https://docs.settlemint.com/docs/concepts/issuing-and-markets/corporate-action) explains why a snapshot cannot be replaced, and [Corporate actions](https://docs.settlemint.com/docs/console/asset-management/manage/corporate-actions) covers the screens.

For example, a token has 18 decimals, and the denomination asset has 6. The amount per share is 0.40, and a holder had 250 tokens on the record date, so the holder's entitlement is 100.00 units of the denomination asset. With 1,000,000 tokens in supply, the declaration estimates 400,000.00 of funding. The snapshot replaces that estimate with the exact sum of the rounded-down entitlements, so the requirement is the estimate or slightly less.

## Interest yield [#interest-yield]

Pays simple interest on holder balances, from a treasury. The interest does not compound. A global index grows with the rate and with elapsed time, and each holder's interest is the balance times the growth of the index since the holder's last settlement. The feature settles a holder at every balance change, so the holder who held the balance during the interval receives it, and a transfer moves the accrual with the balance. Each settlement rounds the interest down to the smallest unit of the denomination asset and carries the fraction to the holder's next settlement, so how often a holder is settled does not change what the holder earns. Holders pull with a claim that pays the whole accrued amount. The feature never holds the money, and it requires [historical balances](https://docs.settlemint.com/docs/concepts/modeling-assets/token-features/balances-and-holds#historical-balances). The DALP Library includes it on two templates, Money Market Fund and Syndicated Loan. A wallet that identity recovery marked lost cannot claim. The Platform API pays what it is owed to its replacement wallet through the token's `recovered-wallet-claims` route.

| Parameter | Description |
| --- | --- |
| Interest denomination asset | The token that pays interest. It cannot be the token itself or a registered fee-on-transfer or rebasing token. |
| Interest treasury | The account that pays holders. |
| Annual interest rate (BPS) | The yearly rate in basis points, 1 to 20,000. 100 basis points equal 1%. |
| Interest start date | When accrual starts. Zero means now. It must be now or in the past. |
| Accrual model | "Continuous" accrues each second over a 365-day year. "ACT/360 daily snapshot" credits each completed UTC day on a 360-day year, and the start date must then be an exact UTC midnight. |

After issuance, an account with the governance role updates the rate, from 1 to 20,000 on the Console sheet "Update interest rate". Interest accrued so far settles at the old rate first. The treasury, the denomination asset, the start date, and the accrual model are fixed. A holder claims, and anyone can fund the treasury with a wallet verification and no role on the token. Funding from an account other than the treasury transfers the denomination asset to the treasury. When the treasury itself signs, funding raises the treasury's allowance to the feature by the amount instead, because the treasury already holds the asset. An account with the emergency role pauses and resumes the feature from the "Accrual" row on the token's Features tab. A pause stops accrual, claims, and rate changes. Governance excludes an account from accrual and includes it again from the "Excluded from accrual" list on the same tab. A conversion that includes interest reads and closes accrual through this feature.

For example, a holder owns 1,000 tokens at a 5% yearly rate, in a 6-decimal denomination asset. Over 30 days with the continuous model, the interest is 4.109589. With ACT/360 over 30 completed days, it is 4.166666. Over 365 days, the continuous model pays exactly 50.000000 and ACT/360 pays 50.694444, because 365 days count against a 360-day year.

## Fixed treasury yield [#fixed-treasury-yield]

Pays a fixed coupon for each period, on the balance a holder owns at the end of that period, from a treasury. The schedule runs from a start date to an end date and is cut into periods of one interval each. For each completed period, the holder's coupon is the balance at the period end, multiplied by the basis per unit, multiplied by the rate, divided by 10,000. The holder who owns the tokens at the period end gets the whole coupon, whatever they held earlier in the period. Transfers carry no accrual. A period becomes claimable in the first second after its end time, not in the block at the end time itself. Holders pull with a claim that settles every completed period, at most 104 periods in one call. The feature has no pause. The DALP Library includes it on nine templates, among them Corporate Bond, Green Bond, Sovereign Bond, and Certificate of Deposit. A wallet that identity recovery marked lost cannot claim. The Platform API pays what it is owed to its replacement wallet through the token's `recovered-wallet-claims` route.

| Parameter | Description |
| --- | --- |
| Yield denomination asset | The token that pays the coupon. |
| Basis per unit | The face value of one whole token in the denomination asset. The issuance form takes a decimal. The "Set yield schedule" sheet and the Platform API take base units. |
| Yield treasury | The account that pays holders. A wallet treasury must approve the feature to spend. |
| Yield start date | When the schedule starts. It must be in the future at creation. |
| Yield end date | When the schedule ends. It must be after the start date. Issuance and an attach both refuse an end date after the maturity date of the token's maturity redemption. |
| Annual yield rate (BPS) | The yield per year in basis points, which DALP converts to the rate paid each period. 1 to 20,000, at issuance and when the feature is attached afterward. |
| Payment interval | Hourly, daily, weekly, monthly (30 days), quarterly (90 days), semi-annual (180 days), or yearly. |

The Console's issuance form and its "Set yield schedule" action for this feature take the rate per year. An asset on the standalone yield schedule takes its rate per period in that schedule's sheet. DALP converts it to the rate paid each period, the annual rate times the interval's share of a 365-day year, and the EVM contract keeps the fraction. A feature attached before DALP kept the fraction keeps paying whole basis points. 500 basis points a year paid every semi-annual (180-day) period pays 246.575 basis points each period, and paid daily it pays 1.37 basis points each day. Within those limits, the Console refuses a rate only when the schedule cannot pay it: the end date must be after the start date, and the interval and the rate must be positive. The Platform API converts the same way when the request sets `rateBasis` to `annual`. A request that leaves `rateBasis` out takes the basis its template states, and the DALP Library's fixed-income templates state `annual`. When neither the request nor the template states one, the API pays `rate` every period unchanged. The DALP Library's fixed-income templates pre-fill a semi-annual, quarterly, or yearly interval, and Corporate Bond pre-fills 500 basis points a year. Yearly means 365 days.

When the span is not a whole number of intervals, the last period is shorter, and the contract pays it the rate prorated to its length. A semi-annual schedule over 365 days has three periods, of 180, 180, and 5 days. At 500 basis points a year, each 180-day period pays 246.575 basis points and the 5-day period pays 5/180 of that, 6.85 basis points, so the year pays 500 in total. A per-period rate sent through the Platform API is prorated in the short period the same way. A feature attached before DALP prorated the short period keeps paying it the full rate. A claim that needs more than 104 periods takes several calls. A shared budget caps each period at the yield on the total supply at its end. A holder's coupon is capped by what the other holders' claims left, and an empty budget advances the holder's position with a zero payout. A claim with nothing to pay reverts with `NoYieldAvailable` ([DALP-4243](https://docs.settlemint.com/docs/api-reference/errors)).

After issuance, governance sets the treasury, which is the only setting that changes. Anyone can fund the treasury, and a holder claims. The treasury wallet itself approves the allowance. The Platform API refuses, before anything is queued, a top-up from a wallet that holds less of the denomination asset than the amount ([DALP-14501](https://docs.settlemint.com/docs/api-reference/errors)) and a top-up from the treasury's own wallet, whose transfer to itself cannot change what the treasury covers ([DALP-14502](https://docs.settlemint.com/docs/api-reference/errors)). That wallet approves the allowance instead. It also refuses a claim the treasury cannot pay: its balance, or for a wallet treasury its allowance to the feature, is below what the holder is owed ([DALP-14503](https://docs.settlemint.com/docs/api-reference/errors)). The refusal names the amount owed and the treasury, not the treasury's balance. When the organisation does not share redemption funding with holders and the caller does not manage the token, the refusal names neither. When more than 104 periods are owed, so one claim settles only part of them, or the index has not priced the owed periods yet, the API refuses the claim only if the treasury cannot pay any of it, and the refusal names no amount. The Console's "Set yield schedule" action attaches the feature to an asset that has none, with its first schedule. Changing the rate, the dates, or the interval needs a detach and a new attach, which starts a new schedule. A token that has the feature needs historical balances too. The contract requires it and attaching reverts without it ([DALP-1071](https://docs.settlemint.com/docs/api-reference/errors)). Select historical balances before fixed treasury yield in the template's Features step.

A holder owns 10 tokens at the end of a period. The basis per unit is 1,000.00 of a 6-decimal denomination asset, and the annual rate is 500 over a 360-day schedule of two semi-annual periods, so each period pays 246.575 basis points. The notional is 10,000.00 and the coupon is about 246.58 for each 180-day period, which scales to 5.00% over a 365-day year.

The second generation adds a write-once authorised consumer for the conversion integration and an account exclusion list of at most eight accounts. The consumer has no Console or API entry. Governance excludes and includes accounts from the "Excluded from accrual" list on the Features tab, which shows how many of the eight slots are used. An account included again keeps its slot. The Console shows no generation badge. See [Yield and maturity](https://docs.settlemint.com/docs/console/asset-management/manage/yield-maturity) for the screens.

## Maturity redemption [#maturity-redemption]

Redeems tokens at face value after maturity. Before maturity nothing changes for transfers. Governance matures the token at or after the maturity date, and the treasury must then hold face value times the supply, or the call is rejected. The emergency role can mature it earlier, strictly before the date, with no funding check, so redemptions can open on an underfunded treasury and run first come, first served. Neither path resets the matured state, and the post-maturity block lasts while the feature stays attached. After maturity, every mint reverts with `TransferBlockedAfterMaturity` ([DALP-1092](https://docs.settlemint.com/docs/api-reference/errors)), even a custodian-forced mint or a fee mint, and regular transfers revert the same way. Burns pass, and so do custodian forced transfers. Each holder then redeems, or an account with the custodian role redeems on a holder's behalf. Either way the feature burns that holder's tokens and pays face value on the amount burned to the holder's wallet. [Corporate Action](https://docs.settlemint.com/docs/concepts/issuing-and-markets/corporate-action) explains why maturity cannot be undone. The DALP Library includes it on 14 templates, among them Corporate Bond, Green Bond, Sovereign Bond, Commercial Paper, and Treasury Bill.

| Parameter | Description |
| --- | --- |
| Maturity date | When the token can mature. It must be in the future. |
| Denomination asset | The token that pays the redemption. It cannot be the token itself. |
| Face value | The payout for one whole token in the denomination asset. The issuance form takes a decimal and scales it by the asset's decimals. It must be greater than 0: the form refuses 0, and the Platform API answers 0 with `TOKEN_CREATE_FEATURE_CONFIG_INVALID` before anything is signed. |
| Redemption treasury | The account that pays redemptions. A wallet treasury must approve the feature to spend. |

After issuance, governance matures the token and sets the treasury, which can change only before maturity. The emergency role matures it early. Anyone can fund the treasury, and the treasury wallet itself approves the allowance. The Platform API refuses a top-up from a wallet that holds less of the denomination asset than the amount ([DALP-14504](https://docs.settlemint.com/docs/api-reference/errors)) and a top-up from the treasury's own wallet ([DALP-14505](https://docs.settlemint.com/docs/api-reference/errors)). Before anything is queued, it refuses a redemption that a wallet treasury's allowance cannot pay ([DALP-9481](https://docs.settlemint.com/docs/api-reference/errors)) or that the treasury's balance cannot pay ([DALP-14506](https://docs.settlemint.com/docs/api-reference/errors)). Each refusal names the treasury, the amount the redemption needs, and the treasury's allowance or balance. When the organisation does not share redemption funding with holders and the caller neither manages the token nor is its treasury, both answer as not available right now ([DALP-12373](https://docs.settlemint.com/docs/api-reference/errors)) without the treasury's figures. A holder with an available balance redeems, and an account with the custodian role can redeem on a holder's behalf, for up to 100 holders in one call. The maturity date, the denomination asset, and the face value are fixed. Redemption can be partial and repeated, and total payouts are capped at face value times the supply recorded at maturity. A transaction fee with a burn fee reduces the payout to the net burned amount. A token with this feature is valued from its face value times the price of its denomination asset and carries no price feed of its own: a template that requires the feature creates the token without one, and attaching the feature later removes the token's own feed after the attach is queued. See [Yield and maturity](https://docs.settlemint.com/docs/console/asset-management/manage/yield-maturity) for the screens.

For example, a holder redeems 2.5 tokens, with a face value of 1,000.00 per token in a 6-decimal asset, and receives 2,500.00. Before the token can mature, a supply of 1,000,000 tokens needs 1,000,000,000.00 in the treasury. When an early maturity opens an underfunded treasury, a redemption that needs more than the balance reverts with `InsufficientTreasuryBalance` and the burn rolls back.

## Distribution waterfall [#distribution-waterfall]

A share-class instrument pays several classes from one cash pool. The waterfall decides how much each class's leg gets, by rank, and each class's dividend yield pays holders from its own leg. Each class's dividend yield uses the waterfall as its treasury, so it can draw only its own leg. The waterfall attaches to the controlling class token. It holds the cash and keeps, for each distribution, what each class's leg still holds, and for each class how much capital it has had back. It does not own or move the share tokens, and it restricts no transfer. Money enters through `fund`, which splits the pool into legs and binds each class's dividend to its leg. Money leaves through two functions. A class's dividend yield calls `payoutFor`, with the dividend's number, when a holder claims. `release` returns what a closed leg still holds to the wallet that funded it. A class's leg is paid out as per-share dividends to its holders. The operator action that drives it is the coordinated distribution, and [Paying several share classes from one pool](https://docs.settlemint.com/docs/concepts/issuing-and-markets/corporate-action#paying-several-share-classes-from-one-pool) explains why the design works this way. The DALP Library includes the waterfall on one template, Controlling Class Share, which belongs to the Dual-Class Share Structure, the template pair that issues a controlling and an economic class. It runs on EVM only.

The Console shows each parameter under its name and a sentence on what to enter, for example "Contribution basis", the capital the class paid in. The structure editor on the instrument structures tab uses the same names when it links one class's field to another.

| Parameter | Description |
| --- | --- |
| `denominationAsset` | The token the pool is paid in. Every class's dividend yield must use the same asset. |
| `ownClass` | The class row that belongs to the token holding the waterfall. |
| `classTerms` | One row for each share class, 2 to 8 rows. |
| `classTerms` `role` | A unique name for the class, such as `controlling` or `economic`. |
| `classTerms` `token` | The class token. A class that does not exist yet is bound during issuance. Its dividend yield must use the waterfall as its treasury. |
| `classTerms` `contributionBasis` | The capital the class paid in. Enter a decimal in the payment asset, above zero. The platform scales it by that asset's decimals, not by 18. |
| `classTerms` `ordinaryRank` | 1 to 255. In ordinary mode, the lowest rank is paid first. |
| `priorities` | Zero to 64 rows. Each row ranks the classes for one kind of event. |
| `priorities` `determinationKind` | A text label for the event, such as `sponsor-event`. It must be unique and must match the claim's text exactly, including case. |
| `priorities` `ranks` | One tier for each class, 1 to 255. Tier 1 recovers capital first. Every class needs a tier in every row. |

In the Dual-Class Share Structure, the issuer enters the payment asset and, for each class, the contribution basis and the ordinary rank. Both ordinary ranks default to 1, so an ordinary distribution splits by contribution basis. The Library seeds one `sponsor-event` priority row that puts the economic class (Class B) at tier 1 and the controlling class (Class A) at tier 2, and the issuer cannot change its tiers. The class and row terms cannot change after the waterfall is deployed, because no function edits a class or a row. Two settings per class and priority row can change, each until the first distribution is funded under that row. An account with the governance role turns netting on or off with `setDistributionNetting`, and sets a wind-down premium with `setDistributionPremium`: an amount in the payment asset that the class is owed once under that row, on top of its capital. The premium is an on-chain call only. The Console and the Platform API do not offer it. The distribution waterfall card on the token page shows the netting setting of each class under each priority row and whether the row is locked, and a governance account changes it there or through the Platform API (`v2/token/setDistributionNetting`). A waterfall that was upgraded after distributions were funded can fold those distributions into its running totals with `syncAllocations`, from the same card or through `v2/token/syncAllocations`. Any account can run it, and it changes no split.

After issuance, an account with the governance role funds a distribution through a coordinated distribution, which also needs [maker-checker](https://docs.settlemint.com/docs/concepts/custody-and-signing/maker-checker) approval while the Corporate actions row under Approvals in the organisation settings is on. The issuance run binds each class to its token, and `fund` is rejected until every class is bound. A class left unbound can be bound afterward only by an on-chain `bindClass` call from the governance role. The Console and the Platform API do not offer it. The factory also registers the waterfall as a contract with an identity and adds it to the compliance bypass list, so a payment token that refuses unregistered recipients still accepts the pool. The bypass covers receiving only, and every payout to a holder is still checked.

The waterfall works in one of two modes, and the mode decides who gets the pool.

**Ordinary mode** applies when the operator names no determination kind, and also when the named kind has no valid claim. The whole pool goes to the classes with the lowest ordinary rank, split pro rata by contribution basis. A class at a higher rank gets nothing. Equal ranks share the income, and distinct ranks are winner-take-all.

**Priority mode** applies when the operator names a configured kind and the controlling token's identity holds a valid `issuerEventDetermination` claim of that kind from a trusted issuer. Tiers run in ascending order. Each tier is due the unreturned capital of its classes, which is the contribution basis less the capital the class has already had back, and then any premium set for the class under that row. With netting on for the row and the class, a class's unreturned capital is the contribution basis less every leg the class has been allocated, ordinary distributions included, and never below zero. A tier fills completely before the next one starts. A shortfall inside a tier splits pro rata by what each class is still owed in capital and premium, and each class's share pays its capital before its premium. Whatever is left after the last tier follows the ordinary rule.

A kind with no configured row, and a claim that is missing, revoked, from an issuer that is not trusted, or of another kind, all fall back to ordinary mode without an error. A trusted claim whose data cannot be decoded is rejected. Legs always add up to the pool. Shares round down, and the remainder goes to the last class of the group. `quote` previews the split without moving money. `fund` computes the split again and reverts with `SplitChanged` before it takes any money if the result differs from what the operator approved. A class's dividend yield can draw only the leg its dividend was bound to when the distribution was funded, so one distribution never spends another distribution's unclaimed money. The waterfall rejects a caller that is not that class's current dividend yield (`UnauthorizedClass`), a dividend that no funded distribution bound (`UnboundDividend`), a payout above the leg (`InsufficientAllocation`), a payout in another asset (`PayoutAssetMismatch`), and a plain `payout` call that names no dividend (`ReferenceRequired`).

An account with the governance role releases a leg back to the funding wallet once the leg is closed: it has no dividend, its dividend was cancelled, or its dividend is paid, including after governance reclaimed the unclaimed rest. A leg is released once, an empty leg is refused, and every release is refused while the waterfall holds less than it owes across all distributions. A leg whose dividend was never declared, or was cancelled, also gives back the capital it counted as returned. The Console offers Release in the Class money panel of a coordinated distribution's record, and the Platform API offers the same operation on the corporate action's leg.

In this example, the controlling class has a contribution basis of 9,000,000, ordinary rank 1, and tier 2 in the `sponsor-event` row. The economic class has a basis of 1,000,000, ordinary rank 1, and tier 1.

| Case | Pool | Controlling | Economic | How it works out |
| --- | --- | --- | --- | --- |
| Ordinary | 10,000,000 | 9,000,000 | 1,000,000 | Equal ranks, so the pool splits 9:1 by contribution basis. |
| Priority, shortfall | 8,000,000 | 7,000,000 | 1,000,000 | Economic recovers its 1,000,000 first. Controlling takes the remaining 7,000,000. |
| Priority, upside | 12,000,000 | 10,800,000 | 1,200,000 | Capital of 1,000,000 and 9,000,000 comes first. The residual 2,000,000 splits 9:1. |
| Second priority after the shortfall | 5,000,000 | 4,700,000 | 300,000 | A later pool: economic has its 1,000,000 back, and controlling is still due 2,000,000 of its 9,000,000. That 2,000,000 comes first, and the residual 3,000,000 splits 9:1. |

Netting changes what a class is due. Take two classes with a basis of 350,000,000 each and equal ordinary ranks. An ordinary distribution of 200,000,000 gives each class 100,000,000. A priority distribution of 500,000,000 then pays the economic class 250,000,000 and the controlling class 250,000,000 when netting is on for the economic class. With netting off, the economic class is still due its full 350,000,000, and the controlling class receives the remaining 150,000,000.

[Figure] Priority mode fills capital buckets in tier order, then splits the residual. A pool of 12,000,000 enters priority mode. Tier 1 is the economic class's capital of 1,000,000, and it fills first. Tier 2 is the controlling class's capital of 9,000,000, and it fills next. The residual of 2,000,000 follows the ordinary rule and splits 9 to 1 by contribution basis. The result is 10,800,000 for the controlling class and 1,200,000 for the economic class. With a pool of 8,000,000 the pool runs out inside tier 2, and the controlling class receives 7,000,000. Labels: Priority mode, pool of 12,000,000; Pool; 12,000,000; Tier 1; Economic capital; 1,000,000; Tier 2; Controlling capital; 9,000,000; Residual; 2,000,000; Ordinary rule, 9:1; Legs: controlling 10,800,000, economic 1,200,000; With a pool of 8,000,000 the pool runs out inside tier 2.

Each tier fills before the next one starts, and whatever is left after the last tier follows the ordinary rule.

Three points cause most mistakes with this feature.

Distinct ordinary ranks are winner-take-all. A junior class at a higher ordinary rank receives no ongoing income, and the platform raises no error for it. With three classes, A (basis 6,000,000, rank 2), B (basis 3,000,000, rank 1), and C (basis 1,000,000, rank 1), a pool of 10,000,000 gives A nothing, B 7,500,000, and C 2,500,000. Give classes equal ordinary ranks to share income, and use priority tiers to return junior capital.

The contribution basis does two jobs. It is the split ratio in ordinary mode and the principal balance in priority mode. Enter the cash the class paid in, never its net asset value.

The two orderings are independent. The ordinary rank orders income, and the ranks of a priority row order capital return. A class can share income equally and still come second for capital, as the controlling class does above. The platform checks that a determination claim comes from a trusted issuer. It does not check who that issuer is beyond that registration, so any issuer the trusted-issuer registry accepts for that claim can switch a distribution into priority mode.

The runbook is [Corporate actions](https://docs.settlemint.com/docs/console/asset-management/manage/corporate-actions), which covers creating, previewing, approving, and confirming a coordinated distribution.


# Token features

Source: https://docs.settlemint.com/docs/concepts/modeling-assets/token-features
How the sixteen documented token features reach a token, how to choose one, and why a feature operation is rejected, with one reference page per feature group.

Seventeen token features add behaviour to a token, such as paying a coupon, charging a fee, or converting a loan into equity, and this catalogue documents sixteen of them. A feature reaches a token through an instrument template or, after issuance, through a governance action. This page covers that route, how to choose a feature, and why an operation is rejected. Five reference pages hold one entry per feature, with its parameters, units and the roles that operate it. [Instrument templates](https://docs.settlemint.com/docs/console/asset-design/instrument-templates) covers the template workflow, and composable token explains why a token's behaviour is built from features. The [Platform API](https://docs.settlemint.com/docs/api-reference/v2) manages the same features programmatically.

An instrument template is a set of token features with their defaults, plus metadata fields and a compliance policy. You select a feature on the template's "Features" step, and issuing from that template installs it. After issuance, an account that holds the governance role attaches, detaches, rotates, or updates it. A token holds an ordered list of at most 32 features and runs them in list order: the template's order at issuance, and the end of the list for a feature attached later. The platform never sorts the list.

After issuance, the Console attaches twelve features from the "Attach a feature" list on a token's Features tab. Hold, voting power, permit, and supply delegate take no settings. Register lines, the feature behind [Booked movements](https://docs.settlemint.com/docs/console/asset-management/manage/booked-movements), is the one feature this catalogue does not document. It needs hold attached first and asks which moves an investor may request. Maturity redemption, dividend yield, interest yield, management fee, transaction fee, transaction fee accounting, and external transaction fee ask for their settings, which the sheet shows for review before the wallet step. The list leaves out a feature that is already attached, and interest yield on an asset type other than deposit or fund. Fixed treasury yield attaches from "Set yield schedule" on the token's yield page, and voting power also from the Governance wizard, which offers an inline attach when the token lacks it.

The menu on a feature's section on the same tab detaches every feature except conversion and the distribution waterfall, and replaces a feature that has settings. Conversion and the distribution waterfall reach a token through the platform only from a template at issuance, and neither the Console nor the Platform API attaches, detaches or rotates them. The Platform API attaches every other feature. On chain, the token's governance role can still replace the whole feature list, those two included. Each feature entry names the actions that exist after issuance and the role each one needs.

Every form that configures a feature, in the template's "Features" step, in structures, and at issuance, shows each parameter under its name and a sentence on what to enter, and opens the feature with its own summary line, the same sentence the feature's detail screen shows. The tables give the platform identifier wherever an API call takes it. The four fee features, fixed treasury yield, conversion, and the conversion minter have a second generation, a newer implementation of the feature contract, and their entries say how it differs. Each feature instance runs the implementation its feature factory points to, and the Console shows no generation badge.

[Figure] Where a token's features come from. An instrument template has three parts: the token features with their defaults, the metadata fields an issuer fills in, and the compliance policy a new token starts with. Issue asset turns the template into a token. The token holds an ordered list of at most 32 features, which it runs in list order. The platform never sorts the list. After issuance, an account with the governance role can attach, detach, rotate, or update a feature. A later template edit does not reach a token that was already issued. Labels: One instrument template, three parts; Token features; Chosen on the Features; step, with defaults.; Metadata fields; Product facts the; issuer fills in.; Compliance policy; The rules a new; token starts with.; Issue asset; The token's ordered feature list; At most 32 features. They run in list order, and the platform never sorts the list.; After issuance, the governance role changes the list; Attach, detach, rotate, or update a feature. A template edit never reaches an issued token.

A template fixes the starting feature list, and after issuance only governance actions change the token's own list.

## Feature reference pages [#feature-reference-pages]

Each page covers one group of features and states, for every feature in it, the parameters, the units, and the actions after issuance.

- [Income features](https://docs.settlemint.com/docs/concepts/modeling-assets/token-features/income): dividend yield, interest yield, fixed treasury yield, maturity redemption, and the distribution waterfall.
- [Fee features](https://docs.settlemint.com/docs/concepts/modeling-assets/token-features/fees): management fee, transaction fee, transaction fee accounting, and external transaction fee.
- [Conversion features](https://docs.settlemint.com/docs/concepts/modeling-assets/token-features/conversion): conversion and the conversion minter.
- [Permit](https://docs.settlemint.com/docs/concepts/modeling-assets/token-features/permit): the permit feature and the Platform API routes that sign and relay a permit.
- [Balance, voting, hold and supply features](https://docs.settlemint.com/docs/concepts/modeling-assets/token-features/balances-and-holds): historical balances, voting power, hold, and supply delegate.

## Choose the feature by what it does [#choose-the-feature-by-what-it-does]

Group the sixteen features by the job they do, then pick the one in that row that matches your requirement.

| You need to | Features | The feature decides |
| --- | --- | --- |
| Pay holders income or principal | [Dividend yield](https://docs.settlemint.com/docs/concepts/modeling-assets/token-features/income#dividend-yield), [Interest yield](https://docs.settlemint.com/docs/concepts/modeling-assets/token-features/income#interest-yield), [Fixed treasury yield](https://docs.settlemint.com/docs/concepts/modeling-assets/token-features/income#fixed-treasury-yield), [Maturity redemption](https://docs.settlemint.com/docs/concepts/modeling-assets/token-features/income#maturity-redemption), [Distribution waterfall](https://docs.settlemint.com/docs/concepts/modeling-assets/token-features/income#distribution-waterfall) | How much a holder receives, from which treasury, and when |
| Charge or account for fees | [Management fee](https://docs.settlemint.com/docs/concepts/modeling-assets/token-features/fees#management-fee), [Transaction fee](https://docs.settlemint.com/docs/concepts/modeling-assets/token-features/fees#transaction-fee), [Transaction fee accounting](https://docs.settlemint.com/docs/concepts/modeling-assets/token-features/fees#transaction-fee-accounting), [External transaction fee](https://docs.settlemint.com/docs/concepts/modeling-assets/token-features/fees#external-transaction-fee) | Who pays, in which asset, and whether value moves |
| Convert one instrument into another | [Conversion](https://docs.settlemint.com/docs/concepts/modeling-assets/token-features/conversion#conversion), [Conversion minter](https://docs.settlemint.com/docs/concepts/modeling-assets/token-features/conversion#conversion-minter) | The price, the window, and which token is minted |
| Keep records and enable voting | [Historical balances](https://docs.settlemint.com/docs/concepts/modeling-assets/token-features/balances-and-holds#historical-balances), [Voting power](https://docs.settlemint.com/docs/concepts/modeling-assets/token-features/balances-and-holds#voting-power) | Which balances can be read at a past time, and who holds vote weight |
| Approve or reserve units | [Permit](https://docs.settlemint.com/docs/concepts/modeling-assets/token-features/permit#permit), [Hold](https://docs.settlemint.com/docs/concepts/modeling-assets/token-features/balances-and-holds#hold) | Who can approve a spender by signature, and who can reserve units |
| Let a wallet or add-on mint and burn | [Supply delegate](https://docs.settlemint.com/docs/concepts/modeling-assets/token-features/balances-and-holds#supply-delegate) | Who may mint, who may burn, and up to what amount |

Within the income row, the choice is how the amount is decided. [Dividend yield](https://docs.settlemint.com/docs/concepts/modeling-assets/token-features/income#dividend-yield) pays an amount per share that the issuer declares each time, fixed from balances on a record date. [Interest yield](https://docs.settlemint.com/docs/concepts/modeling-assets/token-features/income#interest-yield) pays a rate that accrues on balances as time passes. [Fixed treasury yield](https://docs.settlemint.com/docs/concepts/modeling-assets/token-features/income#fixed-treasury-yield) pays a fixed coupon for each period, on the balance held at the end of that period. [Maturity redemption](https://docs.settlemint.com/docs/concepts/modeling-assets/token-features/income#maturity-redemption) pays face value once, after maturity, in exchange for the token. The [distribution waterfall](https://docs.settlemint.com/docs/concepts/modeling-assets/token-features/income#distribution-waterfall) decides no amount. It splits one pool across the share classes of an instrument, and each class's dividend yield then pays from its own part.

Within the fee row, the choice is who pays and what moves. One 100-token transfer shows the four behaviours side by side. The example uses a transaction fee of 2.5%, which is 250 basis points,, a flat external fee of 2.5 units of a second token, and a 1% yearly management fee that is collected separately.

| On one 100-token transfer | Net: [transaction fee](https://docs.settlemint.com/docs/concepts/modeling-assets/token-features/fees#transaction-fee) | Gross: [external transaction fee](https://docs.settlemint.com/docs/concepts/modeling-assets/token-features/fees#external-transaction-fee) | Inflationary: [Management fee](https://docs.settlemint.com/docs/concepts/modeling-assets/token-features/fees#management-fee) | Tracking: [transaction fee accounting](https://docs.settlemint.com/docs/concepts/modeling-assets/token-features/fees#transaction-fee-accounting) |
| --- | --- | --- | --- | --- |
| The receiver gets | 97.5 tokens | 100 tokens | 100 tokens | 100 tokens |
| The sender pays | 100 tokens | 100 tokens, plus 2.5 fee tokens | 100 tokens | 100 tokens |
| The fee is paid in | The same token, to the recipient | A second token, to the recipient | New tokens, minted to the recipient | Nothing moves |
| The fee depends on | A percentage of the amount | A fixed amount for each operation | Average supply and elapsed time | A percentage, recorded only |
| It dilutes holders | No | No | Yes | No |
| A holder must act | No | Hold fee tokens and approve the feature | No | No |

The next table shows what each feature needs before it works, what it cannot sit beside, and whether it needs a token before issuance. A feature that needs a token before issuance makes the template row show "Needs a denomination asset" or "Needs a target token" on Issue asset until the tenant has that token. The Features step enforces the dependencies and the conflicts as you toggle: "Select Historical Balances first." and "Conflicts with Transaction Fee Accounting." are the messages it shows.

| Feature | Needs | Cannot sit beside | Needs a token before issuance |
| --- | --- | --- | --- |
| [Conversion](https://docs.settlemint.com/docs/concepts/modeling-assets/token-features/conversion#conversion) | A conversion minter on the target token, and an interest provider if interest converts | [Booked movements](https://docs.settlemint.com/docs/console/asset-management/manage/booked-movements) | Yes: a denomination token and a target token |
| [Conversion minter](https://docs.settlemint.com/docs/concepts/modeling-assets/token-features/conversion#conversion-minter) | A conversion feature that is on its list of converters | [Booked movements](https://docs.settlemint.com/docs/console/asset-management/manage/booked-movements) | No |
| [Distribution waterfall](https://docs.settlemint.com/docs/concepts/modeling-assets/token-features/income#distribution-waterfall) | Dividend yield and historical balances | Nothing | Yes: a payment token |
| [Dividend yield](https://docs.settlemint.com/docs/concepts/modeling-assets/token-features/income#dividend-yield) | Historical balances | Nothing | Yes: a denomination token |
| [External transaction fee](https://docs.settlemint.com/docs/concepts/modeling-assets/token-features/fees#external-transaction-fee) | Nothing | Nothing | Yes: a fee token |
| [Fixed treasury yield](https://docs.settlemint.com/docs/concepts/modeling-assets/token-features/income#fixed-treasury-yield) | Historical balances | Nothing | Yes: a denomination token |
| [Historical balances](https://docs.settlemint.com/docs/concepts/modeling-assets/token-features/balances-and-holds#historical-balances) | Nothing | Nothing | No |
| [Hold](https://docs.settlemint.com/docs/concepts/modeling-assets/token-features/balances-and-holds#hold) | Nothing | Nothing | No |
| [Interest yield](https://docs.settlemint.com/docs/concepts/modeling-assets/token-features/income#interest-yield) | Historical balances | Nothing | Yes: a denomination token |
| [Management fee](https://docs.settlemint.com/docs/concepts/modeling-assets/token-features/fees#management-fee) | Nothing | [Booked movements](https://docs.settlemint.com/docs/console/asset-management/manage/booked-movements) | No |
| [Maturity redemption](https://docs.settlemint.com/docs/concepts/modeling-assets/token-features/income#maturity-redemption) | Nothing | [Booked movements](https://docs.settlemint.com/docs/console/asset-management/manage/booked-movements) | Yes: a denomination token |
| [Permit](https://docs.settlemint.com/docs/concepts/modeling-assets/token-features/permit#permit) | Nothing | Nothing | No |
| [Supply delegate](https://docs.settlemint.com/docs/concepts/modeling-assets/token-features/balances-and-holds#supply-delegate) | Nothing | [Booked movements](https://docs.settlemint.com/docs/console/asset-management/manage/booked-movements) | No |
| [Transaction fee](https://docs.settlemint.com/docs/concepts/modeling-assets/token-features/fees#transaction-fee) | Nothing | Transaction fee accounting | No |
| [Transaction fee accounting](https://docs.settlemint.com/docs/concepts/modeling-assets/token-features/fees#transaction-fee-accounting) | Nothing | Transaction fee | No |
| [Voting power](https://docs.settlemint.com/docs/concepts/modeling-assets/token-features/balances-and-holds#voting-power) | Nothing (token governance needs it) | Nothing | No |

## When an operation is rejected [#when-an-operation-is-rejected]

A rejection comes from one of three places: the template, the attach and detach API, or the token itself while it runs. A rejection reflects the rule and the state at that moment, so repeating the same call fails again until the condition changes.

The template's "Features" step blocks a feature that misses a dependency or conflicts with another one. Publishing checks both again, and issuing a token with the conflicting pair is rejected with [DALP-0605](https://docs.settlemint.com/docs/api-reference/errors).

An attach, detach, or rotate through the Platform API can be rejected for these reasons.

| Reason | What it means |
| --- | --- |
| `already-attached` | The token already has the feature. A conflicting feature that is already attached gives the same reason, with a message that names it, and the refusal's `conflictingFeatureName` field carries the id of the feature to detach. |
| `conversion-incompatible` | The token's conversion uses MarkConverted, and you tried to attach or rotate interest yield or fixed treasury yield. A balance-based yield would keep paying on converted supply. |
| `conversion-provider-unresolvable` | The change would leave the conversion feature without exactly one interest provider: both yield features are attached and none is chosen, the chosen one is wrong, or the denominations differ. |
| `dividends-outstanding` | A detach or rotate of dividend yield while declared dividends are still unclaimed. Let holders claim, or reclaim the dividends, first. |
| Detach blocked by dependents | Another attached feature depends on the feature. The message lists them. |
| Detach blocked by open proposals | The token's governor has pending, active, or queued proposals, and the feature is voting power. |
| `dependency-not-attached` | An attach of a feature whose dependency is missing. The refusal lists the missing features, for example historical balances for a yield feature, or hold for register lines. |
| `token-not-configurable` | The token was issued without a feature list, as tokens of the original asset families are, so nothing can be attached. |
| `start-date-in-future` | An interest yield start date after the chain's next block. Leave it out or set it at or before that time. |
| `payout-treasury-is-token` | A yield or maturity redemption treasury that is a token contract. |
| `fixed-yield-ends-after-maturity` | A fixed treasury yield that would end after the attached maturity date, or a maturity date before the attached fixed treasury yield ends. Applies to attach only. |
| `create-feature-would-revert` | A simulation of the factory call from the submitting wallet reverted. The refusal names the contract error when it is known. Nothing was queued. |
| `feature-not-found`, `stale-index` | The feature is not attached, or the index lists a feature the token no longer carries on chain. |
| `unchanged-address` | A rotate whose configuration equals the current one, so it would land on the address already in use. A feature without settings, such as permit, always gives this. |
| `not-replaceable` | A rotate of register lines. Change its requestable kinds through the settings route instead. |
| `name-mismatch` | The body names a different feature from the path. |
| `factory-not-found` | The system has no factory registered for the feature. |

At run time, a token or a feature reverts with an error that names the rule. These are the ones you meet most often.

| Feature | Error | When it happens |
| --- | --- | --- |
| Any feature with a governance action | `UnauthorizedCaller` ([DALP-4331](https://docs.settlemint.com/docs/api-reference/errors)) | The caller lacks the governance role. |
| Maturity redemption | `TransferBlockedAfterMaturity` (DALP-1092) | A transfer or a mint after maturity. |
| Maturity redemption | `InsufficientTreasuryBalance` (DALP-1043) | Maturing, or redeeming, when the treasury cannot cover the payout. |
| Hold | `AmountExceedsAvailable` | A transfer, burn, or reservation above the available balance. |
| Conversion | `CannotTransferConvertedTokens` | MarkConverted: a transfer or burn of units already converted. |
| Conversion | `ConversionMinterMissing`, `UnauthorizedConverter` | The target token has no minter, or its minter does not list the conversion feature. |
| Conversion | `ZeroTargetAmount` | The target amount rounds down to zero. |
| Distribution waterfall | `InsufficientAllocation` | A class's payout exceeds its leg. |
| Distribution waterfall | `UnauthorizedClass`, `PayoutAssetMismatch` | The caller is not the class's dividend yield, or the payout is in another asset. |
| Distribution waterfall | `UnboundDividend`, `ReferenceRequired` | The claimed dividend was not bound by a funded distribution, or the call names none. |
| Distribution waterfall | `WaterfallUnderfunded`, `AlreadyReleased` | A release while the waterfall holds less than it owes, or of a leg already released. |
| Distribution waterfall | `SplitChanged` | The split changed between the preview and the confirm. Nothing moved. |
| Distribution waterfall | `ClassNotBound` | A class has no token bound. |
| Distribution waterfall | `DistributionNettingLocked` | A netting change after a distribution was funded under that priority row. |
| Distribution waterfall | `UnknownPriorityRow` | A netting change or read for a determination kind that has no priority row. |
| Transaction fee, transaction fee accounting | `FeeRatesAreFrozen` (DALP-1020) | A rate change after a freeze. Accounting also locks the recipient. The net fee does not. |
| Management fee | `FeeRateIsFrozen` (DALP-1019) | A rate or recipient change after a freeze. |
| External transaction fee | `FeesAreFrozen` (DALP-1024) | An amount, recipient, or token change after a freeze. |
| External transaction fee | `ERC20InsufficientAllowance` (DALP-1102) | The payer has not approved the feature to spend the fee token. |
| Transaction fee accounting | `NoFeesToReconcile` (DALP-1070) | Reconcile with a zero total. |
| Fixed treasury yield | `NoYieldAvailable` (DALP-4243) | A claim when no completed period has anything to pay. |
| Historical balances | `QueryBeforeEnabled` | A strict lookup for a time before the feature started. |

## Troubleshooting [#troubleshooting]

**A feature card says Select X first or Conflicts with X**

The Features step shows "Select Historical Balances first." when a feature needs another one, and "Conflicts with
Transaction Fee Accounting." when two selected features cannot sit on one token. Enable the named feature first.
Turning a feature off also turns off every feature that depends on it, so the confirmation can remove more than the
card you clicked.

**A template shows Needs a denomination asset**

Seven features need a token that already exists in the tenant: external transaction fee, maturity redemption, fixed
treasury yield, dividend yield, interest yield, the distribution waterfall, and conversion. Any token satisfies the
check, and conversion also needs a target token that has the conversion minter. Open the template's detail panel and
issue the token it needs, or register an existing one, for example with "Issue a stablecoin" or "Register an existing
stablecoin", then return to Issue asset.

**A coupon pays more than expected**

The contract pays its stored rate once for each payment period. A schedule created through the Platform API with
`rateBasis` set to `per_period`, or with no basis from either the request or its template, stores the rate as given,
so 500 basis points with a daily interval pays 5% of face value every day. Also check the schedule length: with a
per-period rate, a span that is not a whole number of intervals ends with a shorter period that still pays a full
coupon. Fix the rate and the dates by detaching the feature and attaching a new schedule.

**A transfer fails after maturity**

After maturity every mint and every regular transfer reverts with `TransferBlockedAfterMaturity`. The matured state
cannot be reset, and the block lasts while maturity redemption stays attached. Burns pass, so holders redeem. A
custodian can still run a forced transfer, and an attached feature can still move units. Redeem the position, because
retrying the transfer fails again.

**A transfer fails on held units**

A venue has reserved some of the holder's units, so the transfer is above the available balance and reverts with
`AmountExceedsAvailable`. Units the custodian froze count the same way. Cancel the resting order on the venue to
release the hold, or transfer no more than the available balance.

**A waterfall class receives nothing**

Check four causes. Distinct ordinary ranks are winner-take-all, so a class at a higher rank gets nothing in ordinary
mode. The pool may not reach the class, and the preview then shows "Not reached". A class with a leg but no supply on
the record date, or a per-share rate that rounds to zero, gets no dividend, and its leg stays in the waterfall. Last,
`fund` reverts with `ClassNotBound` until every class has a token.

**An operation reverts on the fee token's allowance**

An external transaction fee pulls the fee from the payer with an ERC-20 transfer, so the payer needs fee-token balance
and an allowance for the feature contract. The payer is the account that receives a mint, or the sender of a transfer
or a burn. The fee recipient is not exempt, so it needs the allowance when it pays.

**A detached feature leaves a gap in its history**

Historical balances records nothing while it is detached. A lookup for that period returns the last checkpoint written
before the detach, so a dividend with a record date in the gap reads stale balances. The platform blocks the detach if
the token has fixed treasury yield, dividend yield, interest yield, or the distribution waterfall. Remove dependent
features before detaching historical balances.

## Frequently asked questions [#frequently-asked-questions]

### Can I add or remove a feature after issuance?

Yes for most features, with the governance role. Holders do not approve these changes: governance can attach a management fee that dilutes every holder, or a transaction fee on every transfer, to a token already in circulation. The Console attaches twelve features from the "Attach a feature" list on the Features tab: hold, voting power, permit, supply delegate, register lines, maturity redemption, dividend yield, interest yield, management fee, transaction fee, transaction fee accounting, and external transaction fee. It attaches fixed treasury yield from "Set yield schedule" on the yield page, which "View yield details" on the Features tab opens. The Platform API attaches those features, historical balances, and the conversion minter. Through the platform, conversion and the distribution waterfall reach a token only at issuance, and neither the Console nor the Platform API detaches them. A detach is blocked while another feature depends on the feature, while declared dividends are unclaimed, and, for voting power, while governance proposals are open. These settings change in place: fee rates and recipients, the fixed treasury yield and maturity redemption treasuries, the interest rate, and the conversion window. Any other setting needs a rotate, which replaces the feature with a new contract at the end of the list. The Console offers it as "Replace" in the section menu of a feature that has settings.

### Does the order of features matter?

Yes, and the platform does not enforce an order. Features run in list order, so a mis-ordered list can change compliance, fee, and rewrite behaviour. The list follows the template at issuance. A feature attached later goes to the end, and a rotated feature moves to the end. The recommended order puts hold first, then restrictions, fees, external fee hooks and analytics, and the DALP Library places hold first on every template except Share-Class Mirror. Read the order from the token's `getFeatures()` list, since the API lists features alphabetically.

### Is the fixed treasury yield rate annual?

In the Console's issuance form and its "Set yield schedule" action for this feature, yes. An asset on the standalone yield schedule takes its rate per period. You enter the rate per year and DALP converts it to the rate each period pays: 500 basis points a year on a semi-annual schedule pays 246.575 basis points every 180 days, and a shorter final period pays that prorated to its length. Through the Platform API, set `rateBasis` to `annual` for the same conversion. A request that leaves it out takes the basis its template states, which is `annual` for the DALP Library's fixed-income templates. With `per_period`, or with no basis stated anywhere, the API treats `rate` as the per-period rate, so 500 basis points on a daily schedule pays 5% of face value every day.

### Do unclaimed dividends expire?

No. The claim deadline does not stop a claim. A holder can claim after the deadline until governance reclaims the dividend. Reclaiming releases the feature's liability, closes the dividend and moves no tokens, and a holder can no longer claim it after that. In a waterfall, the unclaimed amount stays in that class's leg. Once governance has reclaimed the dividend, an account with the governance role can release the leg, which returns the amount to the wallet that funded the distribution.

### Does a template edit change issued tokens?

No. A template edit changes future issuance only. The token's own feature list lives on chain, and only governance actions on the token change it.


# Permit

Source: https://docs.settlemint.com/docs/concepts/modeling-assets/token-features/permit
Reference for the permit token feature and the Platform API routes that sign a permit, relay it, and read its signing domain and nonce.

The permit feature lets a token holder approve a spender with a signature instead of an approve transaction, and the Console and the Platform API sign, store and relay that signature.

A [token feature](https://docs.settlemint.com/docs/concepts/modeling-assets/token-features) is a module attached to one token. An account with the token's governance role attaches, detaches and configures it after issuance where the feature allows it, and each entry names any other role an action needs. The DALP Library is the catalogue of [instrument templates](https://docs.settlemint.com/docs/concepts/modeling-assets/instrument-templates) that ship with the platform, and each entry says which of them include the feature.

## Permit [#permit]

Lets a holder approve a spender with an off-chain signature instead of an approve transaction, following EIP-2612, the Ethereum standard for signed approvals. The signed message is a permit. It lets a spender, an address such as an exchange or a payment contract, move up to a set amount of the holder's tokens until a deadline. The amount the spender may move is its allowance, and the permit sets the allowance when someone submits it. Anyone can submit the signed permit. The feature checks the deadline, consumes the owner's nonce first, verifies the signature, and sets the allowance on the token. The nonce is a counter that the feature keeps for each owner. It starts at 0 and rises by one whenever one of the owner's permits is used, so a signature works once and only in order. The standard form accepts signatures from ordinary wallets. A second form checks signatures through EIP-1271, the standard that lets a contract wallet vouch for a signature, so a smart wallet can sign. The signature is bound to the token's name at deployment, and a second submission of the same signature fails because the nonce has moved. The feature restricts no token operation. Choose it when a spender should not need a separate approve transaction. The DALP Library includes it on 32 templates, all except Carbon Credit, Controlling Class Share, Custody receipt, and Share-Class Mirror.

The feature has no parameters. A holder signs a permit with "Create permit approval" or through the Platform API. The button sits on the permit page, which "View permit details" on the Permit card of the Features tab opens. The review step states "A Custodian relays this permit." On the chain anyone can submit a permit. On the platform an account with the custodian role relays it, from [Actions](https://docs.settlemint.com/docs/console/essentials/actions) or from the permit page, and the organisation pays the network fee, through its paymaster when it sponsors gas. Signing and relaying each ask for wallet verification. That is a second check, such as a PIN code or a one-time code, before the platform signs or submits on your behalf. A signed permit that nobody relays before its deadline expires, and the holder signs a new one. After issuance, governance attaches and detaches it. The Console attaches it from the "Attach a feature" list on the token's Features tab and detaches it behind a typed confirmation. It cannot be rotated. Attaching it again after a detach restores the same contract with its nonces unchanged, as the nonce section of the Permit API below describes. A permit with a passed deadline is rejected with `ERC2612ExpiredSignature`. It runs on EVM only. [Smart wallet](https://docs.settlemint.com/docs/concepts/custody-and-signing/smart-wallet) covers the signing side for a contract wallet.

### Permit API [#permit-api]

Two Platform API routes handle a permit. One signs it and stores it, and the other relays it so that the allowance changes on the chain. The [generated API reference](https://docs.settlemint.com/docs/api-reference/v2) lists the request bodies, the responses, and the error codes of both under "Sign and store a permit" and "Relay a signed permit".

| Route | Who calls it | What it does |
| --- | --- | --- |
| `POST /api/v2/tokens/{assetId}/features/permit/signatures` | The holder. The platform signs with the wallet that executes for the holder, after wallet verification, so the caller needs no token role | Signs a permit for the `spender`, `value`, and `deadline` in the body, stores it as `pending`, and returns it with its `id` and `nonce`. It sends no transaction |
| `POST /api/v2/tokens/{assetId}/features/permit/permits` | An account with the custodian role | Sets the allowance on the chain. The body names a stored permit by `signedPermitId`, or gives `owner`, `spender`, `value`, and `deadline` with either `v`, `r`, and `s` or one packed `signature` |
| `GET /api/v2/tokens/{assetId}/permit-info` | Any signed-in caller | Reads the feature address, the domain separator, the permit type hash, the token name, and, when you send `owner`, that owner's current nonce. It answers 200 with `data: null` when the token has no attached Permit feature |
| `GET /api/v2/tokens/{assetId}/features/permit/signatures` | Any signed-in caller | Lists stored permits with their `status` (`pending`, `relayed`, or `expired`) and `relayable` |
| `GET /api/v2/tokens/{assetId}/permit/replay-history` | Any signed-in caller | Lists the nonces that were already used on the chain |

Amounts such as `value` are whole numbers in the token's smallest unit, sent as strings or integers up to the largest `uint256`. A `deadline` is a Unix timestamp in seconds. Both write routes take a `walletVerification` object with a `secretVerificationCode` and a `verificationType` of `PINCODE`, `OTP`, `SECRET_CODES`, or `OIDC_MFA`. A permit reaches the chain in one of two ways. In the platform-signed path, the holder calls the sign route and a custodian then relays the stored permit by `signedPermitId`. In the externally signed path, your signer reads `permit-info`, signs the typed data itself, and a custodian relays the signature with `owner`, `spender`, `value`, `deadline`, and either `v`, `r`, `s` or `signature`. For a contract wallet, send the bytes that the wallet's EIP-1271 check accepts as `signature`. The relay route answers 202 with a `transactionId`, a `status`, and a `statusUrl` by default. Send `Prefer: wait=<seconds>` to wait for settlement and receive 200 with the token. The platform keeps `wait` between 5 and 99 seconds. [Idempotency and async settlement](https://docs.settlemint.com/docs/api-reference/guides/idempotency-async-settlement) covers the 202 handle and the `Prefer` header.

```bash
curl -X POST "https://your-instance.example.com/api/v2/tokens/0x7a1c0b9e5d3f4a8b2c6e1d9f0a3b5c7d9e1f2a4b/features/permit/signatures" \
  -H "X-Api-Key: sm_dalp_..." \
  -H "Content-Type: application/json" \
  -d '{
    "spender": "0x3f5ce5fbfe3e9af3971dd833d26ba9b5c936f0be",
    "value": "500000000000000000000",
    "deadline": 1793750400,
    "walletVerification": { "verificationType": "PINCODE", "secretVerificationCode": "123456" }
  }'
```

The response holds the stored permit. Its `id` is the value to relay.

```json
{
  "data": {
    "id": "0198a3c4-5b7e-7d2a-9c41-6f0e8b3d5a12",
    "tokenAddress": "0x7a1c0b9e5d3f4a8b2c6e1d9f0a3b5c7d9e1f2a4b",
    "owner": "0x9d4e2b6a8c0f1e3d5b7a9c2e4f6a8b0d1c3e5f7a",
    "spender": "0x3f5ce5fbfe3e9af3971dd833d26ba9b5c936f0be",
    "value": "500000000000000000000",
    "deadline": "1793750400",
    "nonce": "3",
    "signatureKind": "ecdsa",
    "status": "pending",
    "createdAt": "2026-10-28T13:05:11.000Z"
  },
  "links": { "self": "/api/v2/tokens/0x7a1c0b9e5d3f4a8b2c6e1d9f0a3b5c7d9e1f2a4b/features/permit/signatures" }
}
```

A custodian relays that permit and waits up to 30 seconds for the result.

```bash
curl -X POST "https://your-instance.example.com/api/v2/tokens/0x7a1c0b9e5d3f4a8b2c6e1d9f0a3b5c7d9e1f2a4b/features/permit/permits" \
  -H "X-Api-Key: sm_dalp_..." \
  -H "Prefer: wait=30" \
  -H "Content-Type: application/json" \
  -d '{
    "signedPermitId": "0198a3c4-5b7e-7d2a-9c41-6f0e8b3d5a12",
    "walletVerification": { "verificationType": "PINCODE", "secretVerificationCode": "123456" }
  }'
```

#### The signing domain [#the-signing-domain]

A permit signature follows EIP-712, the standard for signing structured data. The domain a signer must use has four fields, and the permit feature contract answers for them.

| Domain field | Value |
| --- | --- |
| `name` | The token's name when the permit feature was deployed |
| `version` | `1` |
| `chainId` | The chain the token runs on |
| `verifyingContract` | The permit feature contract, which `permit-info` returns as `featureAddress` |

The signed type is `Permit(address owner,address spender,uint256 value,uint256 nonce,uint256 deadline)`. `permit-info` returns the token's current indexed name as `tokenName`. If your hash does not match `domainSeparator`, the name at deployment differs, and `domainSeparator` is the value to trust. `permit-info` also returns the hash of the domain as `domainSeparator` and the hash of the type as `permitTypeHash`, so you can compare them with what your signer computes before you sign. The domain separator is indexed and `asOfBlockNumber` says which block it was read at. The nonce is read live. The sign route compares the domain that the feature declares with the indexed separator and stops with `TOKEN_PERMIT_FEATURE_UNAVAILABLE` when they differ, and with `TOKEN_PERMIT_READ_REFUSED` when the separator is not indexed yet.

#### Nonces [#nonces]

Use the nonce from `permit-info` when you build a signature yourself. The chain accepts a permit only when its nonce equals the owner's current nonce, and the use of the permit raises that nonce by one.

- **Signing through the platform.** The sign route starts at the owner's current nonce and skips every nonce that a pending stored permit uses. Two permits from one holder therefore get consecutive nonces. A permit whose nonce is above the current nonce stays `pending` with `relayable: false` until the permits before it are used. An expired permit does not advance the nonce: sign a new permit, which takes the released nonce, and relay it first.
- **A permit held for custody approval.** When a custody approval rule, which sends the signature request to a named approver before it is signed, holds the signature, the sign route answers 409 `TOKEN_PERMIT_SIGNING_PENDING` and keeps the nonce for that permit. Another permit from the same holder takes the next free nonce. After the approver approves, sign again with the same spender, value, and deadline to receive the signature over the held nonce. If a different permit claims the nonce in the meantime, the losing call answers 409 `TOKEN_PERMIT_NONCE_CONFLICT`, and you sign again.
- **Detaching and attaching Permit again.** Detaching Permit removes it from the token's list and leaves its contract in place. Attaching it again restores that same contract, at the same address, so the nonces keep their values and the signing domain does not change. While Permit is detached, the sign and relay routes refuse every request because the token has no attached Permit feature, and a stored permit cannot be relayed. After the new attach, a stored permit whose deadline has not passed and whose nonce equals the owner's current nonce relays again, and a signature that you built outside the platform stays valid on the same terms. A permit whose deadline passes while Permit is detached expires as usual.

#### Retries and idempotency [#retries-and-idempotency]

- **Sign.** The sign route does not deduplicate. Each successful call stores one more permit with the next free nonce, so a retry after a lost response creates a second permit. List the stored permits before you retry. A permit that waits for custody approval is the exception: the same spender, value, and deadline receive the same nonce.
- **Relay by `signedPermitId`.** The platform deduplicates by the stored permit and not by the `Idempotency-Key` header. While a relay of that permit is queued or running, a repeat call answers 202 with the `transactionId` of the first relay and sends no second transaction. After the relay settled, a repeat call answers 409 `TOKEN_PERMIT_ALREADY_RELAYED`, or 409 `TOKEN_PERMIT_NOT_RELAYABLE` when the platform has not recorded the result and the nonce has moved. Read the permit's status either way. When the first relay failed, the next call submits a new transaction.
- **Relay with a signature.** No stored permit exists, so the header does the work. Send the same `Idempotency-Key` on every retry, and the transaction queue attaches the retry to the first request. The queue matches the retry to the first request, and the route itself gives no replay guarantee. Without the header the platform generates a new key for each call, a retry sends a second transaction, and the chain rejects it because the nonce is already used.

#### Errors [#errors]

A request with a missing or wrong wallet verification, a caller without the custodian role on the relay route, and a token without an attached Permit feature use the platform's standard errors. Those need a change to the request or the caller before any retry, except a wallet verification attempt limit (429), which clears after the wait that the response states. The permit-specific errors are below. The [error reference](https://docs.settlemint.com/docs/api-reference/errors) lists every code with its fix.

| Code | Status | Retry | Route | Cause |
| --- | --- | --- | --- | --- |
| `TOKEN_PERMIT_DEADLINE_EXPIRED`, DALP-9495 | 422 | No | Sign | The deadline is not after the current chain time. Sign again with a later deadline |
| `TOKEN_PERMIT_WALLET_UNAVAILABLE`, DALP-9496 | 409 | No | Sign | No executor wallet, the organisation wallet that signs and submits on a user's behalf, is set for this organisation and chain. Configure one |
| `TOKEN_PERMIT_NOT_FOUND`, DALP-9497 | 404 | No | Relay | No stored permit matches this organisation, chain, token, and `signedPermitId` |
| `TOKEN_PERMIT_ALREADY_RELAYED`, DALP-9498 | 409 | No | Relay | The permit was already submitted. Read the permit and its transaction instead |
| `TOKEN_PERMIT_NOT_RELAYABLE`, DALP-9499 | 409 | No | Relay | The permit expired, its deadline passed, or its nonce is not the owner's current nonce, for example because the chain already used it. Read the permit, then sign a new one if needed |
| `TOKEN_PERMIT_NONCE_CONFLICT`, DALP-9500 | 409 | Yes | Sign | Another permit took the nonce while this one was stored. Sign again |
| `TOKEN_PERMIT_FEATURE_UNAVAILABLE`, DALP-9501 | 503 | Yes | Sign | The owner's nonce or the token name is not available, or the domain that the feature declares does not match the indexed one. Retry after indexing |
| `TOKEN_PERMIT_SIGNING_FAILED`, DALP-9502 | 503 | Yes | Sign | The custody signer did not complete the signature |
| `TOKEN_FEATURE_PERSISTENCE_FAILED`, DALP-9266 | 503 | Yes | Both | The platform could not read or save the token feature data that the request needs |
| `TOKEN_PERMIT_PERSISTENCE_FAILED`, DALP-9505 | 503 | Yes | Both | The platform could not read or save the stored permit. Retry without changing the request |
| `TOKEN_PERMIT_SIGNING_PENDING`, DALP-14037 | 409 | No | Sign | A custody approval holds the signature. The response includes the approval reference and its expiry, which is never later than the permit deadline |
| `TOKEN_PERMIT_CUSTODY_APPROVAL_CLOSED`, DALP-14038 | 409 | No | Sign | The custody provider rejected the signature, it failed, or the approval expired. Sign a new permit |
| `TOKEN_PERMIT_READ_REFUSED`, DALP-13001 | 422 | No | Both | A nonce or domain read failed for the reason in the response, for example a domain separator that is not indexed yet. Report it with the request ID if it persists |
| `CONTRACT_ERROR`, DALP-9026, DALP-9027, DALP-9069 | 422 | No | Relay | The chain rejected a permit sent with a signature: the deadline passed (9026), the recovered signer is not the owner (9027), or a contract wallet's signature failed verification (9069). Rebuild the signature with the current nonce and domain, or sign a new permit with a later deadline |


# Address fields

Source: https://docs.settlemint.com/docs/concepts/operating/address-fields
Address fields in the Console search by name, take a pasted 0x address or list, name the addresses they know, and flag a malformed address before you save.

Every Console field that asks for a wallet or contract address opens a list you can search by name, and also takes an address you paste or type. A field that asks for several addresses, such as an allow list, a block list, an offering's presale list, a venue's zero-rated VAT participants or the identities a venue admits, keeps the chosen addresses as a list under the same search.

## Search by name or paste an address [#search-by-name-or-paste-an-address]

Open the field and type part of a name, a token symbol or part of an address. The list shows your recent choices first, then the best matches among the participants, tokens and contacts you can see. A field that takes only tokens lists only recent tokens. Select one, or move with the arrow keys and press Enter.

When more addresses match than the list shows, it says so, such as "Showing 25 of 140. Keep typing to narrow the list.", and "Show more" lists more. In a field for a token in a large organisation the list may say only "Showing the first 25. Keep typing to narrow the list." because it did not count every eligible participant.

In a field for a token, a row also says "Holds" and the amount when that wallet already holds some of the token, and "Verification pending" when the wallet's [on-chain identity](https://docs.settlemint.com/docs/concepts/compliance-and-identity/onchain-identity) exists but is not registered yet. A user who may not read identities sees the holding only.

To use an address that is not in the list, paste the full `0x` address. You can paste into the closed field, which opens with the pasted text as the search. A known address shows the name your directory holds for it. An address that matches no participant, token or contact you can see shows "Not in your directory" in a field that accepts outside addresses, and "This address is not one of the choices for this field." in a field that only takes a known choice. A well-formed address can still be the wrong one, so check the name the field shows before you save.

A one-line filter in a table's toolbar, such as Client on a venue's Orders tab, shows only the warning icon, and the words when you point at it.

## Refused addresses and what to do [#refused-addresses-and-what-to-do]

The field flags a malformed address before you choose it:

| What you see | What it means |
| --- | --- |
| "The capitals in this address do not match its checksum, so it may be mistyped." | The mix of upper- and lower-case letters is wrong. Copy the address again from its source. |
| "An address has 40 characters after 0x." | A character is missing or extra. The message also gives the count it found. |
| A message that names the characters an address may use. | A character is not hexadecimal. |
| "Names ending in .eth are not supported here." | Paste the `0x` address instead of the name. |
| "The zero address belongs to nobody, so what goes there is lost." | The field refuses the zero address. Only a field built to accept it takes it. |
| "This is a token contract, not a wallet. Choose a wallet." | The field asks for a wallet and you chose the token's own contract. |
| "This is one of your own wallets." | The field refuses your own wallet, or shows this as a warning where you may still use it. |

## Add several addresses [#add-several-addresses]

A list field shows the addresses it holds above an "Add an address" control. Add one by searching and choosing it. To add many, paste them: text split by commas, semicolons, new lines or spaces adds every address in it at once, so a column copied from a spreadsheet works. The line under the field says how many it added, how many it skipped because they were already in the list, and how many need fixing.

Each address in the list shows its name when it is known, and its own problem next to it when there is one:

- "Not an address. An address is 0x followed by 40 characters." for text that is not an address.
- The messages from the table above.
- "This address is already in the list. Remove this copy." for a second copy. A button above the list, such as "Remove 2 duplicates", removes every copy in one step.

You cannot save the form while an address has a problem. Remove an address with its remove button, or the whole list with "Remove all". Every removal shows Undo on the line under the field.

A list of more than five addresses shows the first five and every address with a problem. "Show more" reveals the rest fifty at a time.

## Keyboard and screen readers [#keyboard-and-screen-readers]

An address field works from the keyboard. In an open list, the arrow keys move, `Enter` chooses and `Esc` closes. In a list field, `Tab` reaches each remove button in turn, and after a removal focus moves to the next address. A screen reader reads the number of addresses, the problems and each change the field makes.

[Table views](https://docs.settlemint.com/docs/concepts/operating/table-views) covers the tables these fields filter, and [Compliance Modules](https://docs.settlemint.com/docs/concepts/compliance-and-identity/compliance-modules#identity-allow-list) the allow and block lists they fill.


# What the assistant sends

Source: https://docs.settlemint.com/docs/concepts/operating/assistant-data
Which models receive an assistant question, who can keep it, what DALP masks before it leaves, and what the data setting adds.

The Console assistant answers questions about the page a member has open. DALP sends each question through OpenRouter, a service that routes requests to model providers, to one fixed model that DALP does not run: `~deepseek/deepseek-v4-flash-latest` sorts the question and writes the answer. The same model serves every organisation, whether it uses the free assistant on the platform's key or its own OpenRouter key.

Before a question leaves, DALP replaces the names, emails and wallet labels it finds with handles. Three kinds of text can still carry a name to the model: a name the member types that DALP does not detect, a name in pasted text under "Send documents" that matches no participant, and document text. Document text leaves as written by default on both keys, to a model provider and region that OpenRouter picks for each call. An organisation owner or a platform administrator can choose "Mask" to keep it in DALP. The organisation's OpenRouter key stays in DALP's secret store and goes only to OpenRouter, and the member's session and cookies never leave DALP. The setting is the **Data sent to the model** row on the [Assistant](https://docs.settlemint.com/docs/console/organisation-settings/assistant) page in "Organisation settings", which also holds the model key, the capabilities, the watchers and the MCP server. To ask the assistant a question, see [Search](https://docs.settlemint.com/docs/console/essentials/search#can-i-ask-the-assistant-a-question-from-search). When one request needs several controls, see [Assistant plans](https://docs.settlemint.com/docs/console/essentials/assistant-plans).

## Which models receive a question [#which-models-receive-a-question]

DALP pins the model. No setting lets an organisation choose another model, and the free assistant and the organisation's own key use the same one.

`~deepseek/deepseek-v4-flash-latest` does every job that needs a model:

- It makes every decision call, a model call that must choose from a fixed list of options. The first, made for every question, asks whether the question fits the open page and whether it asks for an answer or for a change. A change request then goes to it again to pick the control. DALP takes the option the model names and treats an answer outside the options as unsure.
- It writes every answer and every draft.
- It turns a compliance policy written in words into rules, on the Compliance tab and in the Asset designer. It sees only the clause, with each value replaced by a placeholder and each word outside a fixed word list replaced by an ellipsis.
- It reads document passages and approval text when the data setting is **Send documents**, to pick which passage fills a field or whether a text matches what an approval does.

The `~` and `-latest` mark a name that OpenRouter points at the latest DeepSeek V4 Flash release, so the answering model can change without a DALP release. When the organisation has stored its own key, the **Model access** row on the [Assistant](https://docs.settlemint.com/docs/console/organisation-settings/assistant) page shows this model under "Model".

A failed or doubtful call follows fixed rules:

- When the first decision call says the question does not fit the open page, DALP asks once more and ends the question as out of scope only when both answers agree.
- A decision call whose answer is not one of the options is asked once more, and is treated as unsure when the second answer is not one either.
- A decision call that does not answer within 8 seconds, or that fails, is not asked again. The question ends without an answer, as when the model provider cannot answer.
- A decision call refused as busy, by OpenRouter or by DALP's own limit on decision calls, is not retried, and the question ends as busy.
- When an answer would lose a sentence to DALP's check for typed figures and unbracketed names, the model is asked once, without any reads, to rewrite it.

The record of each question keeps the model that OpenRouter reported for the answer, so a reviewer can see which DeepSeek release answered. For a document, the record keeps the model of each decision call instead. The record does not name the model provider or the region that served the call.

## Who receives a question [#who-receives-a-question]

OpenRouter receives every call and passes it to a model provider that serves the pinned model. OpenRouter picks that provider for each call. DALP does not choose the provider and cannot pin it to a region, so the provider and the region can change from one question to the next.

The two kinds of key differ in whose OpenRouter account sends the question.

- **Free assistant.** The installation's OpenRouter key sends the question. The operator who runs the installation sets that key, and the calls run on the operator's OpenRouter account, not on the organisation's. The free assistant is the default when the installation has a key. It is shared, so it can be busy at peak times. When the installation has no such key, there is no free assistant.
- **The organisation's own key.** The organisation's OpenRouter key sends the question, so the calls run on the organisation's own OpenRouter account and its own quota.

Both keys send the same content: the masked question, what the assistant reads in masked form, and the document text unless the organisation chose **Mask**.

On both keys, each request sets OpenRouter's zero data retention filter, so OpenRouter routes it only to endpoints that declare that they keep no data. When no such endpoint is available, the assistant is unavailable and DALP does not fall back to an endpoint that may keep data. DALP sets the filter and cannot verify that an endpoint honours it.

## Who can keep a question [#who-can-keep-a-question]

- **OpenRouter and the model provider.** Zero retention is the provider's commitment to OpenRouter. DALP cannot check what the provider or OpenRouter keeps, so treat what the assistant sends as shared with both.
- **DALP, in the record of the question.** Each question leaves one record, which never holds the OpenRouter key. It holds:
  - the question as the member typed it, and the masked text sent to the model
  - the answer, with handles in place of names, and how the question ended
  - the model, the token usage and the time taken
  - the member's role at the time and the page the question was asked on
  - any rating, with the reason and note the member wrote
  - the reads the assistant made, with their inputs but never the data they returned
  - the data setting in force, whether the question included text from outside DALP, and the answer of each decision call
  - the handles of the conversation, with the records they stand for
- **DALP, in the audit trail.** Each question also writes an entry in the audit trail, and that entry keeps the request the Console sent, which includes the question as the member typed it.
- **Whoever exports the questions.** Readers of the "Assistant questions" tab can download the questions of a time window as a CSV file with "Export", including each question as typed. Each export is recorded on the audit trail with its row count and window. DALP's retention does not reach an exported file.

DALP deletes the record of a question once it is older than the retention period. The operator of the installation sets that period between 1 and 3,650 days, and it is 365 days unless the operator sets another value. A daily job deletes the old records, up to 50,000 in each run, so a large backlog clears over several days. Deleting a person's DALP account deletes the records of their questions at once. The audit trail entry, which holds the question as typed, is not deleted with the record. It follows the retention of the audit trail. With no value set, the audit trail keeps entries without a limit, and the operator can set 5, 7 or 10 years. Past that period, DALP deletes an entry only once its day is anchored on the chain and in a published or acknowledged end-of-day audit report, so an entry for a day that was never anchored and reported stays.

Three kinds of reader open the records on the **Assistant questions** tab of the [Audit trail](https://docs.settlemint.com/docs/console/reporting/audit-trail): members with access to the audit trail, organisation owners and platform administrators. The tab shows the fields of each record, with the refusal code, the reads in words, and the masked text only when it differs from the question. Each read of the tab is itself recorded on the audit trail.

## What the assistant reads [#what-the-assistant-reads]

The assistant answers only about what the open page is about, and it reads as the member who asked. Six kinds of page can be asked about. Apart from an asset, DALP checks the member's access to the page's subject before it calls a model:

| Page | Access check |
| --- | --- |
| An asset | Each read, as the member |
| A user's page, when the user has a participant | The member can read the participant's status |
| The operator dashboard, Actions, Activity, All assets, Portfolio, Users and Entities | The member holds a system role |
| A trading venue | The member can read the venue |
| The audit trail | The member has access to the audit trail |
| Filings, the filing calendar, obligations and the anchor registry | The member has access to regulatory reporting |

On an asset page the masked question goes to the model before any read of the asset's data, so it leaves DALP even when the member turns out to have no access to that data.

Each read goes through the same API route the Console calls, with the member's own session. A read the member may not make is refused, and the assistant says it cannot read that data. The Console assistant has no tool that writes. A question makes at most six rounds of reads with at most four reads in each round. A question about another asset, another participant or something the page does not cover gets one sentence saying what the page covers, and no model writes an answer for it.

## What DALP replaces before a question leaves [#what-dalp-replaces-before-a-question-leaves]

DALP looks up the names in the question through the asking member's own search and swaps each one for a handle, a label such as `holder 7` that stands for one record for the rest of the conversation, so a follow-up question can say `holder 7` again and mean the same holder. The question with real names stays in DALP, in the record of the question. The models get only the question with handles.

DALP looks up at most five names in a question, within two seconds. A name past that limit, a name the search does not find, and a search that fails are replaced with "someone", "an organisation" or "an address", never sent as written. Emails are replaced without a search.

Some names are not detected. A name written only in lower case, a single first name that is also an ordinary word, as in "Did Will sell?", and a name such as `vitalik.eth` reach the model as typed. Keep such names out of a question, or write them with a capital letter.

The assistant reads asset data to answer. It never passes that data to the model as it is stored. For each read, DALP keeps an allow list of fields and drops every other field. Names, emails and wallet labels become handles with a masked label, such as the country and the type of holder. Dates and amounts reach the model as references to a field of the read, not as values, and the Console puts the real values back after the answer returns.

## Pasted text [#pasted-text]

A question longer than 140 characters is masked as pasted text, however it reached the question field: a paste, a drop, dictation or autofill. A pasted text may be up to 4,000 characters.

DALP looks up at most 20 names in a pasted text, within three seconds. A name that matches a participant becomes a handle. Under **Mask**, every other name becomes a numbered placeholder such as `name:1`. Under "Send documents", names that match no participant stay as written. Under both values, emails, IBANs and phone numbers become `contact:1`, `iban:1` and `phone:1`, and an address that matches no participant becomes `address:1`.

When the search cannot answer, DALP does not send the text with names left in. The question ends with "I can't read pasted text right now." and no model call. The masked text goes first to the model, which sorts the request. When a pasted text asks for a change, the drafting model receives it marked as data from a third party. When it asks for an answer, the model receives the masked text as the question. Only the masked text leaves DALP. The record of the question and its audit trail entry keep the pasted text as the member gave it, with its names, emails and IBANs. A draft from a pasted text also records a count of what was masked.

## What a draft sends [#what-a-draft-sends]

A request to change the management fee, freeze part of a holder's balance or split an asset's shares goes through the same replacement. The model also receives the name of the control and the names of its fields. A holder the request names is replaced by a handle first, and a holder field takes only a handle: never a name, a description or an address.

A draft saves nothing. The Console opens the control with the values filled in, and the member reviews every field and confirms with the usual wallet verification. The draft itself carries no verification.

## What the data setting adds [#what-the-data-setting-adds]

The setting has two values. **Send documents** is the default when no choice has been stored, on the free assistant and on the organisation's own key alike. A stored choice applies on both keys.

- **Mask**: document text is not sent. The assistant is told that document text is withheld.
- **Send documents**: document text is sent as written, including any names inside it, with each item cut at 8,000 characters.

Document text means four things: a PDF a member drops on the Console, a term sheet the assistant reads on the Asset designer, the label of each election option on a corporate action, and the description the initiator typed on a multisig mint. The mint description check also sends the mint amount and the token symbol.

Under both values, names in the question and in what the assistant reads from records become handles. The one exception is a pasted text under **Send documents**, where names that match no participant stay as written.

**Send documents** cannot hide a name that appears inside a document, because DALP does not rewrite the document text. When you switch from "Mask" to "Send documents", the confirmation says so before it saves.

Under **Mask**, the assistant offers no PDF reading, on the Asset designer or anywhere else in the Console.

## Who can allow documents [#who-can-allow-documents]

Two conditions must hold before DALP stores an explicit **Send documents** choice, on the free assistant or on the organisation's own key:

- The person is an organisation owner or a platform administrator. A member cannot open the [Assistant](https://docs.settlemint.com/docs/console/organisation-settings/assistant) page, and the Platform API refuses the request with "Allowing documents to be sent needs an organisation owner or a platform administrator."
- The person confirms in the "Send documents to the model?" dialog with **Allow sending**. The request carries that confirmation, and the audit trail records that it was given.

An organisation owner or a platform administrator can set **Mask** again. Adding or removing the organisation's own key leaves the choice as it was: after a removal the free assistant goes on sending documents unless the organisation chose "Mask", and the confirmation for removing the key says so. An organisation that never made a choice keeps the default.

## How DALP treats text from outside [#how-dalp-treats-text-from-outside]

A document or an approval text written by someone else can say anything, including instructions to the assistant. DALP treats it as untrusted data. DALP admits document text and approval text into a prompt through a single step, and no other path puts it there. Pasted text takes its own path, described under [Pasted text](#pasted-text).

Under **Mask**, that step never reads the text and puts the sentence "Document text is not shared with the assistant." in its place. Under "Send documents", it marks the text as data from outside DALP, removes invisible and control characters, breaks any sequence that could imitate that mark or a reference to a record, and cuts each item at 8,000 characters. The assistant is told not to follow instructions found inside such text, and not to repeat a handle, a figure reference or a citation found in it. A question that included such text is marked on its record, and a draft from that question keeps only values that the member's own request contains.

The model can still follow such an instruction, so DALP limits what a manipulated answer can do. The Console assistant has no tool that writes, a person confirms every change it drafts, and every read runs as the asking member, so a manipulated answer cannot read more than that member could. It can still mislead or fill a draft wrongly, which is why the member reviews each field before confirming.

The hosted MCP server on the same [Assistant](https://docs.settlemint.com/docs/console/organisation-settings/assistant) page is a separate door. An outside AI client connected to it can prepare a write for a person to sign, or run a write under an [agent mandate](https://docs.settlemint.com/docs/concepts/custody-and-signing/agent-mandate) that the organisation set up, within that mandate's limits and with no person confirming the write.

## How an answer cites its figures [#how-an-answer-cites-its-figures]

The model never types a figure into an answer. It writes a reference to a field of one of its reads, and the Console shows the value from that read in the page's own number format. DALP removes every sentence that holds a digit outside such a reference or a known handle, and every sentence whose reference points at no value in a read. Standard names that contain digits, such as ERC-3643 or T+2, and list numbers are kept. A number written as a word, such as "three", is not checked. The check proves a figure came from a read, not that the sentence around it is right, so check a material figure on the page its source opens.

Under the answer, **Sources** lists up to eight records the answer relied on, such as a holder, an event, an action or a document. "Show on page" opens the page that shows the record and marks it. An answer can also carry a small table or a row of figures, built from the same reads. On the latest answer in a conversation, the line at the top opens a list of every read the assistant made. A read that the DALP CLI also offers shows the `dalp` command that repeats it, with a button to copy it. See [Using the DALP CLI with AI agents](https://docs.settlemint.com/docs/api-reference/cli/ai-agents#the-console-assistant-and-the-cli).

## Limits on questions [#limits-on-questions]

Each member and each organisation can ask a fixed number of questions in each window. The member's count is checked first, so a question refused for the member's limit does not use up the organisation's.

| Key | Each member | The organisation |
| --- | --- | --- |
| Free assistant | 20 every 10 minutes | 300 every hour |
| The organisation's own key | 100 every 10 minutes | 1,500 every hour |

A window resets on the clock. A refused question says when to try again. When a member has three questions or fewer left, the search dialog says how many and when the window starts over. A document the assistant reads counts as a question. A question that has not finished after 45 seconds ends with no partial answer, and so does a question the model provider cannot answer.

The **Usage** row on the [Assistant](https://docs.settlemint.com/docs/console/organisation-settings/assistant) page shows organisation owners and platform administrators the questions asked in the last 7 days, the questions refused because the assistant was busy, and the limits that apply to the organisation's key. The count includes typed filters and compliance policy readings. A term sheet check and an approval brief are not counted. When members rated answers, the row also counts the answers rated helpful and not helpful. When anyone asked a question in the last 7 days, "See these questions in the audit trail" opens them, for a reader who can open the audit trail.

## Draft from a document [#draft-from-a-document]

A member can drop a PDF anywhere in the Console, or pick **Draft from a document** in the search palette. DALP recognises what kind of document it is and opens the control it calls for, filled in:

- A subscription agreement opens the mint control on the asset it names, with the investor and the units.
- A bank statement opens the bank rail's **Payments** page with each unmatched credit the statement pays and the client it names.
- An identity document set opens the verification issuance on the named participant's **Verifications** tab.
- A regulator or board letter that sets a filing obligation opens **New obligation** with the name, cadence, deadline and LEI it states.
- A term sheet opens the Asset designer, which fills the asset once its type is chosen.

The model only picks which passage of the document answers a field, or says none or unsure. DALP reads every value from that passage with its own rules, so the model never writes a field value. An investor, participant or client is filled only from a name the member's own search finds, and an address, email or IBAN in the document is never used. Each filled field shows the page and the words it came from, and a field DALP could not settle stays empty with the pages to check.

Nothing is saved until the member submits the control, with the usual approvals and wallet verification. The control opens only for a member who may use it on that page.

The PDF is uploaded, read once and deleted, whatever the outcome. DALP does not keep it for a later read. The record of the question holds the kind of document, the field ids and what was found for each, never the document text. The passages the model reads go to `~deepseek/deepseek-v4-flash-latest`. Each document counts against the assistant's limits.

## The approval brief [#the-approval-brief]

A person who opens a corporate action waiting for a decision, or a multisig mint or transfer approval waiting for a co-signature, sees an **Assistant brief** at the top of the sheet. DALP builds it from the same records the person can open, read with their own session, so it shows nothing they could not already see. The summary and every figure come from DALP's own checks, and no model writes them.

A model sees text only for two checks. For a corporate action it reads the label of each election option, and for a multisig mint it reads the description the initiator typed, to judge whether the text says what the plan or call does. A model reads that text only when the data setting is **Send documents**, as [What the data setting adds](#what-the-data-setting-adds) describes. Under "Mask" those two checks do not run and the brief shows the other checks.

The brief is a reading aid. It never blocks an approval, and it does not approve or vouch for the action. "Approve", "Reject" and "Co-sign" work the same with or without it.

## Watchers send nothing to the model [#watchers-send-nothing-to-the-model]

A watcher reads DALP data on a schedule and posts what it finds to the Actions page of the members who own that work. It sends nothing to OpenRouter or to a model provider. The brief on each finding uses fixed wording filled with figures from DALP, so no model writes it. A watcher therefore runs without an OpenRouter key: it needs only the assistant switched on. Each watcher is off until an organisation owner or a platform administrator turns it on under **Watchers** on the [Assistant](https://docs.settlemint.com/docs/console/organisation-settings/assistant) page, and every run leaves an entry in the audit trail.


# Console navigation

Source: https://docs.settlemint.com/docs/concepts/operating/console-navigation
The sidebar lists only what you can open, collapses to icons, and keeps you in the frame when an address is missing, retired or not yours to open.

Every signed-in Console page sits in one frame with three parts: the sidebar, the top bar and the content area. One set of access rules decides what the sidebar lists and whether an address opens. A page that is missing, retired or not yours to open stays inside the frame, with the sidebar in place.

What the sidebar lists follows the roles of the participant you act as, the person, organisation or account record whose authority the Console uses, so switching participant can change the list. The account menu shows who you are signed in as, the organisation you work in and the participant you work as.

## The sidebar lists what you can open [#the-sidebar-lists-what-you-can-open]

One set of access rules decides both what the sidebar's sections show and whether a direct address opens, so an entry and its address give the same answer. The Platform API still checks every read against your session, so the sidebar is not the access control. An area your roles, organisation, network or deployed add-ons do not allow is left out of the list, and a section whose entries are all gone loses its own label too. Add-ons are optional features, such as airdrops, that your organisation deploys before anyone can use them.

- A full page load draws the sidebar's links once, in the page the server sends, so no link appears or disappears when the browser takes over. This includes links that depend on your roles on single assets, such as Offerings for the holder of a sale role.
- The entry for the page you are on is marked as the current page, and opening a page directly scrolls its entry into view. A page below an entry, such as a trading desk under Trading, marks that entry.
- The Actions entry carries a badge with the number of actions waiting for you, and the badge disappears at zero.
- **Shared accounts**, listed before Wealth, lists the multisig wallets you can act as, wallets that need a set number of their signers to approve a transaction. Each entry opens that wallet's page under My participants. The list comes from the participants you can act as, and the group is hidden when that list holds no multisig wallet.
- On the pages the account menu opens, such as Profile, Security, API keys and My participants, the account menu button itself is marked as the current page. A shared account's page also marks its entry under Shared accounts.
- When the platform cannot answer whether you may use a section's areas, that section shows a "Service temporarily down" row and a Try again row instead of hiding them. Try again asks the platform again.

Some entries stay listed before they have anything to show:

- Portfolio and Invest under Wealth are always listed. Trading, Settlements and Votes each appear once your organisation deploys the add-on behind them, and stay listed while empty.
- All five pages need your on-chain identity, the identity you register before you can hold or trade assets. Until it is registered, each of them opens with "Register your identity to hold and trade assets" and an Open identity steps button.
- After that, an empty Portfolio says "No holdings yet" with a Browse offerings link, and empty Trading, Settlements and Votes pages say "No instruments to trade", "No settlements yet" and "No votes yet".
- If your roles let you use the add-ons under Asset lifecycle, that section also lists each of the three airdrop types, Push airdrop, Vesting airdrop and Time-bound airdrop, that your organisation has not deployed. For a system manager each of these entries opens Factories, and hovering one reads "Push airdrop is not deployed. Open Factories to deploy it." For everyone else the entry does not open, and hovering it reads "Push airdrop is not deployed. A system manager deploys it in Factories."

## The top bar [#the-top-bar]

The sidebar opens with the logo, and the top bar opens with the sidebar toggle and Search. [Search](https://docs.settlemint.com/docs/console/essentials/search) finds a page or a record by name or address. The Submissions badge shows how many of your submissions need review and how many actions wait for you, and its icon turns to a spinner while a submission you just made is in progress. Hovering it lists each count, and selecting it opens the Submissions panel that [Activity](https://docs.settlemint.com/docs/console/essentials/activity) describes. When the assistant is on and the page offers Ask, an Ask panel button sits before the Submissions badge and opens the Ask panel.

The account menu button shows an avatar over two lines: the active organisation, then your own name, or "Working as" followed by the participant's name while you work as someone else. The avatar is yours, or the participant's while you work as someone else. While you work as someone else, the whole button also turns violet, and a violet "Working as" bar under the top bar names the participant and offers Return to yourself, so the bar shows on every page. When the top bar is narrower than 672px, the button drops the two lines and keeps only the avatar.

## The account menu [#the-account-menu]

The menu opens with your name and a You badge, with your email below them. When your name is the same as your email, only the badge and the email show. Below them come up to three submenus, and each appears only when it offers a choice.

- **Organisation** lists the organisations you belong to and switches between them. It appears when you belong to more than one, or when you may create one, in which case it ends with Create organisation.
- **Working as** switches the participant the Console acts for. It opens with a card for the participant you work as and a search field. Below them come Return to yourself while you work as someone else, your recent participants, the other participants you can work as, and View all participants. It leaves out multisig wallets, which open as their own accounts under Shared accounts in the sidebar. It appears when you can work as at least two participants, and always while you work as someone else. [My participants](https://docs.settlemint.com/docs/console/my-account/acting-as-participants) explains what changes when you switch.
- **Network** lists the organisation's active networks and marks the default one. When those networks span more than one ledger family, a Ledger choice narrows the list. Organisation owners and platform administrators also see whether the active network's indexed data is up to date. The submenu appears when [multi-network support](https://docs.settlemint.com/docs/console/organisation-settings/networks) is on for the organisation and the organisation has more than one active network. When no network serves the selected ledger, the Actions page shows a Pick network button, which opens the account menu on this submenu.

Below them, the menu opens Profile, My participants, On-chain identity, API keys and Security, switches the language and the theme, and offers Documentation, Keyboard shortcuts, Report an issue and Sign out. When your deployment has an Investor portal, the menu links to it too. Organisation owners and platform administrators also see Export debug information, which downloads a zip to forward to the support team. An organisation owner's zip leaves out the platform logs and traces, which carry every organisation's activity. [The admin debug bundle](https://docs.settlemint.com/docs/deployment/observability#the-admin-debug-bundle) lists what the zip holds.

## Collapse and resize the sidebar [#collapse-and-resize-the-sidebar]

The sidebar toggle collapses the sidebar to icons, and `Ctrl` + `B` or `⌘` + `B` does the same from anywhere outside a text field. From 768px wide you can also drag the sidebar's edge to set its width between 12rem and 24rem. Dragging it narrower than 10rem collapses it, and double-clicking the edge restores the default 16rem and expands it. Hovering the edge reads "Drag to resize, double-click to reset".

This browser keeps the expanded or collapsed state and the width in cookies for seven days, so a reload opens the sidebar the way you left it.

- A collapsed icon names its page in a tooltip on hover, and adds the key chord that opens the page where it has one.
- Each sidebar destination has its own icon, so two pages stay distinguishable when the sidebar is collapsed. The exceptions are the asset classes your organisation defines, which share one class icon, and the Shared accounts entries, which share another.
- An expanded entry wraps its name onto two lines at most. When the name is still cut short, hovering the entry shows it in full.
- The sidebar has flat, labelled sections and no groups that fold open, so no entry hides behind another, collapsed or expanded.

## On a small screen [#on-a-small-screen]

Below 768px wide the sidebar opens over the page as a drawer and the toggle closes it again. From 768px it stays beside the page.

From 768px to 1023px wide the sidebar collapses to icons on its own, so the page keeps its room. The toggle or `Ctrl` + `B` opens it while you need it, without changing the state this browser keeps. From 1024px the sidebar opens the way you left it. The Investor portal and this documentation site behave the same way.

- The top bar sizes its parts by its own width rather than the screen's, because the sidebar takes part of the screen. The account menu button takes at most 45% of the bar, and never more than 18rem, so a long participant name truncates instead of crowding the search.
- The content area takes its height from the visible part of the screen, so a phone's browser bar never covers the last row of a table or the page's action.
- On a screen shorter than 30rem, such as a phone on its side, the top bar shrinks to 3rem so the page title and its first row of content share the first screen.
- A sheet and a dialog are never taller than the screen. One with more to show scrolls inside itself.

## Page headers [#page-headers]

Console pages open with one shared header, in one order: the breadcrumb, the page title, a description, a line of facts about the record where the page has one, and the page's actions. The actions sit beside the title, and move below it when the header is too narrow to hold both. Sign-in, onboarding and full-screen flows keep their own title.

- A title can carry an information button that opens a short summary of its topic and a Read the docs link.
- Tabs sit directly under the header, and any notice for the page sits under the tabs. The tab bar stays at the top of the page while you scroll.
- A page with more than seven tabs shows seven and folds the rest into More, and a trading venue's page folds after six. The tab you are on is never folded away. While tabs that need an access check are still loading, More lists the tabs that are ready and one loading row.

## Links to the documentation [#links-to-the-documentation]

Console pages link to the documentation in four ways. Each link opens in a new browser tab, and each points to a page under `/docs` on the Console's own address.

- An information button beside a title or a term, labelled "Learn more about" and the topic, opens a one-sentence summary and a "Read the docs" link.
- A term inside a sentence is a link with a book icon.
- A message that blocks an action can carry a "How to fix this" link with a book icon.
- A guide link, in the page body, shows as text with a small arrow.

The account menu holds a "Documentation" item. In the Console it opens the Console section of the documentation. [Documentation served from the Console](https://docs.settlemint.com/docs/deployment/install/values-secrets#documentation-served-from-the-console) says how a deployment supplies the pages behind these links.

## Follow the breadcrumb [#follow-the-breadcrumb]

The breadcrumb at the top of a page walks back up its sections. It starts with a home icon that opens Dashboard, lists the sections between Dashboard and the page, and ends with the page itself.

- The trail stays on one line. The home icon never truncates, however long the trail. The entries after it shrink and truncate instead, and hovering a cut entry shows its full name.
- Every sidebar section in the trail, such as Wealth, Asset lifecycle or Organisation settings, links to the section's own address, and that address opens the first page of the section you may use.
- The current page and any entry whose address leads to no page are plain text without a link.
- A trail with fewer than two entries is hidden.
- When the trail has less than 576px of room, as on a phone, it shows only the entry just above the page, with its chevron turned to point back. That entry opens its page when it has one.
- On a settings page the trail is the sidebar section followed by the sidebar item, such as Organisation settings, then General.
- A token's trail reads Assets, the asset class, the token and the open tab. No entry names the instrument template.
- A record page adds the record after its list, such as Asset lifecycle, Venues, then the venue. A page with tabs adds the open tab, such as Wealth, Portfolio, then Returns. The page title names the open tab, the first tab keeps the section's name, and the tab's own heading is not repeated under the header.

## Read a table's filters [#read-a-tables-filters]

Where a table offers filter buttons, each column that holds a fixed set of values, a status or a day gets its own button: the column name and a down arrow, which opens that column's values. A table's create action is never one of these buttons. It sits at the top right of the page header. An applied filter shows its column name and the chosen values on the button itself, with its own clear control. A text, number or other date filter shows as a chip beside the buttons, with the same operator wording as the filter menu. A filter set from the address bar therefore reads the same as one you picked from the menu.

When the Console's AI assistant is on, a phrase typed into the search of a table that supports it can offer a filter. The offer row reads "Filter ·" followed by the conditions and "Press Enter". Pressing `Enter` writes the same filter state the menu writes, so the address, the filter buttons and the rows all agree, and a screen reader hears "Filter applied."

## When an address does not open [#when-an-address-does-not-open]

A missing page, a refused area and an unanswered access check each show a state inside the frame, with the sidebar intact and a way back.

| What you see | When it appears | What you can do |
| --- | --- | --- |
| "This page does not exist" | The address matches no page, or names a record the platform does not know. | Go back or Go home |
| "Not available" | The area exists, and your roles, organisation, network or add-ons do not allow it. | Go home |
| "Couldn't check access" | The platform could not answer whether you may open the area. | Try again or Go home |
| "XvP settlement isn't set up" | The address leads to an add-on page that no deployed add-on serves, and your organisation has no XvP settlement add-on. | Go home |

"This page does not exist" adds that the address may be mistyped or the page may have moved, and that the sidebar and top bar still work. Go back returns to the previous page, and Go home opens Dashboard. An unknown record shows the same state. Some record pages replace that sentence with their own and add a link back to their list: an external token address the platform has never seen says there is no external token at that address on the active network, and offers Back to external tokens.

"Not available" reads "This page isn't available for your account or organisation." The browser tab and the breadcrumb read "Not available" too, so the name of the refused page does not show, and the home crumb opens Dashboard. The check runs before the page reads any data, so nothing behind a refused area loads. The Platform API refuses the same reads on its own, whatever the Console shows. Try again on "Couldn't check access" asks the platform again.

A bare section address, such as the one for Compliance, opens the first page of that section you can use, in sidebar order. When you can use none of them it shows "This page does not exist". When the platform cannot answer for one of them before the Console reaches one you can use, it shows "Couldn't check access".

## Retired addresses [#retired-addresses]

An address an earlier release served opens the page that replaced it, for the retired addresses listed here, so a bookmark or a link in an old document still opens the current page. The query and the anchor carry over to the new page, and the old address is replaced in the browser history, so Back does not bounce between the two.

Retired addresses lead to Portfolio, Contacts, My participants, Transaction funding, Organisations under Platform admin, External tokens, Issue asset, and the pages under Organisation settings, Compliance and Asset design that replaced the old platform settings area. They also lead to organisation setup, the Insights pages, an asset class's list, the token and venue tabs that changed name, and the XvP settlement create flow.

A redirect is kept for a limited number of releases. Update saved bookmarks and links in your own documents to the new address.

## Moving between pages [#moving-between-pages]

A link to another Console page replaces the page you are on at once, so the previous page never stays under the new address. The content area draws the destination's own loading frame at the click when the browser already has that page's code. The browser has it when you opened the page before, pointed at its link, or the sidebar fetched it. Otherwise the content area stays empty until the code arrives.

When you open a page, the Console uses your sign-in session as it last read it and starts a fresh read in the background, at most once every five seconds. Once the Console has read your session, a navigation never waits for that read. The platform judges each read against your session and refuses a read made with a session that has ended.

## When your session ends [#when-your-session-ends]

If the background read has already seen your session end, the next page you open goes to the sign-in page. Otherwise the page opens. When the platform refuses a read because you are signed out, the Console asks the platform again for your session. If that answer reports you signed out, the Console clears the data it holds in this browser and opens the sign-in page. Once you sign in, the page you asked for opens.

A session read that times out, or that the platform answers as busy or failed, does not count as signed out. The Console keeps the session it last read and does not open the sign-in page. Every read still goes to the platform, which judges it against the session.

## A new page opens at the top [#a-new-page-opens-at-the-top]

A followed link opens the new page with its title and actions in view. Back and Forward return each page to the scroll position you left it at.

[Keyboard shortcuts](https://docs.settlemint.com/docs/console/essentials/keyboard-shortcuts) lists the keys that open a page, a page's main action and its table search.


# Form drafts

Source: https://docs.settlemint.com/docs/concepts/operating/form-drafts
A long Console form keeps what you typed in this browser for seven days, offers to resume it, and refuses to store a field named as a PIN or a code.

A long Console form saves what you type in your own browser while you type, and offers the entries back when you reopen it, so a reload, a closed tab or an idle sign-out does not throw the work away. Signing out yourself deletes it. The draft belongs to one user, one organisation and one form, it lives only in the browser that holds it, and it expires after seven days.

These forms keep drafts for every signed-in user, with nothing to switch on:

- **Chapter flows**, forms split into steps you move through in order: creating a vote, creating an XvP settlement, creating a token sale offering, listing an instrument, provisioning a trading venue, adding a compliance provider, and the corporate action composer for a buyback, burn, split, bonus issue, rights issue, spin-off or in-kind payment.
- **Sheets and panels:** the terms of a corporate action declaration, adding or editing a network, creating or editing a webhook, creating a data feed, adding a price source, creating or editing a reporting obligation, enabling a custody provider, and the custody approval policy and fee schedule panels.

A form that ends in a signed operation leaves that operation on [Actions](https://docs.settlemint.com/docs/console/essentials/actions) once it is signed. [Transaction lifecycle](https://docs.settlemint.com/docs/concepts/settlement/transaction-lifecycle) describes what happens after you sign. The asset designer, the policy designer and the instrument template designer keep their drafts on the server, apart from the browser draft this page describes.

The composer keeps one draft per menu and token. Continuing a stopped corporate action keeps a draft of its own, so it starts from the stopped run's terms and leaves the draft of a new action on that menu as it was.

## Read the draft state [#read-the-draft-state]

Once a chapter flow holds a draft, its page header shows "Draft saved" or "Draft restored" beside the network name, with a Discard draft button at the end of the header. A sheet shows the state on one line above its fields, with its own Discard draft button, and announces a change of state to a screen reader.

| Words | What they mean |
| --- | --- |
| "Draft saved" | Everything typed so far is stored in this browser. |
| "Draft restored" | The stored entries are back in the form. |
| "Not saved in this browser" | The browser refused storage, or the form holds a field that is never stored. Closing loses the entries. |

A form you have not changed stores nothing and shows no draft state. A form you change back to exactly how it opened deletes its draft.

Discarding cannot be undone. Discard draft asks "Discard this draft?" and states "Your entries will be removed from this browser. Nothing has been signed." Choose Discard draft to delete the entries, or Keep draft to go back to the form. In the corporate action composer, discarding starts the flow over on its first chapter. In the other chapter flows, discarding from the header also closes the flow.

## Resume a saved draft [#resume-a-saved-draft]

Reopening a form with a stored draft shows "Saved draft from 27 Oct 2026, 14:02 UTC", a second line "Kept in this browser until 3 Nov 2026. PINs and codes are never saved.", and two buttons, Resume draft and Discard. The saved time carries the UTC label in every language, and the expiry date is the UTC date whatever time zone the browser is in.

- A sheet asks before it fills. Resume draft fills the form, and Discard deletes the draft.
- A chapter flow restores on entry instead, because a chapter you have not reached sends you back to the first chapter, which would break a link to a later chapter. It shows "Resumed your draft from 27 Oct 2026, 14:02 UTC" with Discard. Discard there starts the flow over on its first chapter with empty fields, without a reload.
- Typing before you answer the offer does not overwrite the stored draft. Resume draft loads the stored entries. Discard deletes the stored draft and keeps what you typed since as the new draft.
- An idle or expired session keeps the draft on this computer for up to seven days. Sign in again and reopen the form to see the offer.
- A successful submit deletes the draft, and so does Discard. A chapter flow that has just submitted stays on the chapter that shows its outcome.
- Signing out yourself deletes every draft of the user who signed out, in every organisation, and leaves other users' drafts in the same browser alone.

## What a draft never holds [#what-a-draft-never-holds]

The Console decides from each field's name in the form, not from its label or from what you type: a field whose name reads as a credential or a code is never written. The words that block a field are PIN, OTP, TOTP, password, passphrase, passcode, secret, mnemonic, credential, passkey, WebAuthn, JWT, bearer and step-up. The word pairs are private key, API key, API token, app token, access token, refresh token, auth token, session token, CSRF token, ID token, one-time, verification code, recovery code, backup code and seed phrase. A form that holds any one of them is refused as a whole, so the state reads "Not saved in this browser" rather than keeping a partial draft. A secret typed into a field with another name, such as a token inside a webhook URL, is stored with the draft.

## When a draft expires [#when-a-draft-expires]

A draft expires seven days after it was last saved. An expired entry is deleted when the form reads it, and expired entries are cleared whenever a form with drafts first opens. An entry that no longer fits the form's fields is deleted when read, so a form that gained or lost a field starts clean instead of half filled.

## Where the draft lives [#where-the-draft-lives]

The draft sits unencrypted in the browser's local storage, under a key built from the user, the organisation and the form. The Console offers a draft only to the user and organisation it belongs to, but anyone with access to this browser profile can read the stored entries. The Console never sends the draft to the server, so it does not follow you to a second device or a second browser, and clearing site data removes it. On a shared computer, sign out yourself, which deletes your drafts, rather than leaving the session to expire.


# Bank transfers

Source: https://docs.settlemint.com/docs/concepts/operating/investor-portal-bank-transfers
Pay an organisation from your own bank account, request a payout back to that account, and follow both payments in your wallet's Transfers.

A bank transfer deposit credits your wallet from an account at your own bank. You pay the organisation's account at its bank, and DALP never holds the money. Once the bank reports the payment, the organisation's bank rail, its connection to that bank, matches the payment to you by a reference or a virtual IBAN. The organisation then approves the mint, by its approval policy or by a second person, and the tokens appear in your wallet. A cash-out runs the other way and appears in the same Transfers list. The [bank rail](https://docs.settlemint.com/docs/console/asset-lifecycle/bank-rail) page covers the operator side of the same connections.

Copy the details from the Deposit dialog. They belong to one bank connection and one token. A payment that carries the wrong reference, or arrives after its connection was paused, cannot be matched to you, so ask the organisation about it, quoting the amount and the date.

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

- You are signed in to the Investor portal and acting as the participant that holds the wallet you want to fund.
- The organisation made you a client on at least one of its bank connections.
- The bank rail is switched on for the organisation. When the client link or the bank rail is missing, the Deposit dialog offers no bank transfer method.

## Steps [#steps]

**Step 1 of 5**

### Choose a deposit method [#choose-a-deposit-method]

Open "Portfolio", then select "Deposit". The dialog lists the ways this organisation offers you. "From a wallet" is the custody route, described in [Wallet deposits and withdrawals](https://docs.settlemint.com/docs/concepts/operating/investor-portal-wallet-transfers), and "By bank transfer" opens the bank details. A dialog with one method opens that method directly.

The Deposit button appears when the organisation's custody deposits are on and licensed, or the bank rail is switched on. The "From a wallet" method needs custody operations to be on. The dialog waits while it reads which methods apply, and shows a retry when reading your bank details fails.

**Step 2 of 5**

### Find your token group [#find-your-token-group]

Each token you can receive is a group, headed by the token's symbol and a line that says you receive that token in your wallet. When the platform cannot name a token, the group is headed by the token's shortened address instead.

Under the group, each bank connection you are a client of is one card with the bank's name. A card on a paused connection or a paused token link carries a "Paused" badge and says "This bank connection is paused. Do not send a payment until it resumes."

**Step 3 of 5**

### Copy the account and the reference, or the virtual IBAN [#copy-the-account-and-the-reference-or-the-virtual-iban]

A reference connection shows two values: the organisation's reserve account at its bank, labelled with its currency, and the payment reference that goes in the payment. A virtual IBAN connection shows one value, the virtual IBAN the bank assigned to you. Every value has a copy control.

The reference is what matches the payment to you, so put it in the payment exactly as shown. On a virtual IBAN connection the IBAN itself matches the payment to you.

**Step 4 of 5**

### Make the payment from your bank [#make-the-payment-from-your-bank]

Send the amount in the currency of the account you copied, to that account or IBAN, with the reference when the connection uses one. The platform does not see the payment until the bank reports it, so an instruction your bank has not sent yet cannot appear in the portal.

**Step 5 of 5**

### Follow the payment in Portfolio transfers [#follow-the-payment-in-portfolio-transfers]

Open "Portfolio", then "Transfers". Each bank payment you made is one "Bank payment" row, merged with your custody transfers and withdrawals, newest first. The Type filter narrows the list to bank payments.

A payment that has arrived and is not in your wallet yet sits in the "In progress" section, separate from the history, however many newer transfers exist. It moves into the history once it is minted or returned.

## Read the outcome [#read-the-outcome]

A bank payment row shows the amount and currency, the date and time, the payment reference and the value date, and one of three outcomes.

| Outcome | What it means | What the row carries |
| --- | --- | --- |
| "Minted to your wallet" | The payment arrived and the tokens are in your wallet. | The mint transaction, with a copy control. |
| "Waiting" | The payment arrived and the tokens are not in your wallet yet. | No reason. |
| "Returned" | The bank returned the payment to you. | No mint transaction. |

"Waiting" is a normal state. The payment has reached the organisation and the mint has not completed, often because it waits for the organisation's approval, which lapses after seven days. The row gives no reason.

The page refreshes the list on its own while a payment is waiting, so you do not need to reload it.

When your bank later reverses the payment, the organisation can recall the tokens, with a second bank rail manager's approval, by a forced transfer from your wallet or a booked correction.

## Follow a cash-out [#follow-a-cash-out]

A cash-out turns tokens back into money paid to one of your own bank accounts.

Request the cash-out from "Withdraw" in the Investor portal, as [How to cash out](#how-to-cash-out) describes. A cash-out pays only into an active bank account. Propose a bank account from the account menu of the Investor portal or the Console: open "Bank accounts", select "Propose a bank account", then enter the account holder, the bank, and the IBAN or the account number and bank identifier. When you are a client for more than one token, also choose the token the account is for. The account shows "Proposed" until a second person at the organisation approves it, then "Active". The menu item shows only once the organisation has linked you as a bank client. Without a link, the Bank accounts address says the page is not available. A refused or revoked account keeps its row with that state, and the organisation's reason is not shown to you.

How a cash-out starts depends on the token link's supply mode:

- In **Booked movements** mode, your wallet requests a redemption on the token with "Request redemption" on the token's "Booked movements" card, or with `POST /api/v2/tokens/{assetId}/features/register-lines/lines`. The organisation then records the cash-out, or you record it through the API.
- In **Supply delegate** mode, you approve the rail's escrow for the amount with `POST /api/v2/tokens/{assetId}/approvals` on the token, naming the escrow as the spender, and then record the cash-out through the API.

The organisation tells you which mode your token uses and the escrow's address. The [bank rail](https://docs.settlemint.com/docs/console/asset-lifecycle/bank-rail) page describes both modes.

Through the API, record a cash-out at `POST /api/v2/users/me/bank-cash-outs` from a fresh signed-in session with an `Idempotency-Key` header. A call without the key, or with an API key instead of a session, is refused.

Each cash-out is one outgoing "Cash-out" row in "Transfers", with the amount in the currency of the bank connection and its state. The Type filter lists "Cash-out", and the search matches the amount, the currency, the state and the detail text. A cash-out that has not finished sits under "In progress". Once it is "Paid", "Released" or "Returned" it moves to "History".

In these state names, "your bank" means the organisation that pays you out, which approves the cash-out, not the bank that holds your own account. "The bank" means the organisation's bank, which sends the payment.

| State | What it means |
| --- | --- |
| "Setting aside your tokens" | Your tokens are being set aside for the payout. |
| "Waiting for a second approval at your bank" | The amount is above the single or 24-hour limit, so a second person at the organisation approves it. |
| "Approved" | The bank approved the cash-out and has not sent the payment yet. |
| "Sending to your bank" | The payment instruction is on its way to the bank. |
| "With your bank" | The bank has the payment instruction. |
| "Closing out" | The bank paid you and your tokens are being closed out. |
| "Paid" | The bank paid the amount into your account. |
| "Releasing" | The cash-out is stopped and your tokens are being freed. |
| "Released" | The cash-out did not go out and your tokens are free again. |
| "Needs your bank's attention" | The bank paid you, and closing out your tokens needs follow-up at your bank. |
| "Payment coming back" | The bank sent the payment back and the amount is being credited to you again. |
| "Returned" | The bank sent the payment back. The amount is credited back to you as tokens once it is approved. |

A released row names the reason, for example "Released: the payout deadline passed". A release can also follow a move of your tokens: "Released: the tokens were taken back before the payment went out" when you took them back from the escrow after its deadline, and "Released: your bank paused cash-outs; you can request again" when a token custodian returned them from an escrow the rail no longer controls, or the token link stopped being active.

The detail line shows the destination account with all but its last four characters hidden, the bank's reference once the bank gives one, the transaction hash, the payout deadline while the payment has not gone out, and the date it was paid.

The row is read-only. In **Booked movements** mode you stop a cash-out by withdrawing its redemption request before the payment goes out: select "Withdraw" on the request in the "Booked movements" card, then confirm "Withdraw request". The row then reads "Released: the request was withdrawn".

## Troubleshooting [#troubleshooting]

**The bank transfer method is missing**

The dialog lists "By bank transfer" only when the organisation has the bank rail switched on and has made you a client
on at least one of its bank connections. Ask the organisation to add you as a client on a connection, then open the
dialog again.

**Your bank details cannot be read**

The panel says your bank details could not be read and offers "Try again". Your links do not change on their own while
that message shows, so retry before you ask anyone for the details.

**A card says Paused**

Do not send a payment to a paused connection or a paused token link. Keep the details, because they are the ones you
use once the connection resumes.

**Your payment does not appear**

A bank transfer appears only after the bank reports it, and the row is matched by the reference or the virtual IBAN.
Check that the payment carried the exact value you copied, and that you paid the account shown on the card.

**A payment shows as Waiting for a long time**

A waiting payment has arrived and the mint has not completed. The row carries no reason, so ask the organisation to
check the payment against its bank reconciliation rather than sending a second payment.

## How to cash out [#how-to-cash-out]

Open "Portfolio", select "Withdraw", then "To my bank account". This method appears when the organisation has enabled the bank rail and linked you as a bank client. If it is your only withdrawal method, it opens directly. Choose the token when you have more than one, then choose your active payout bank account. Propose your own account through Account > Bank accounts. Another person at your bank approves it before it can receive a payout.

The Console Portfolio offers the same method under **Withdraw**. There the booked step lists only the redemption lines you already requested, and a missing payout account links to [Bank accounts](https://docs.settlemint.com/docs/console/my-account/bank-accounts) in the Console account menu, the same page as in the Investor portal. Your bank payments and cash-outs also show on the Console Portfolio [Transfers](https://docs.settlemint.com/docs/console/my-assets/portfolio#follow-your-transfers) tab, with the same rows as here.

The bank link determines which of these two paths you see:

1. **A redemption line:** choose a request to redeem tokens from the wallet linked to your bank. If you have not requested one, select "Request a redemption" and complete that request. Returning to the bank method selects the new line. A line that already has a cash-out shows its state and cannot be selected again.
2. **An amount:** enter the amount in the currency shown. Use the wallet linked to your bank. When its allowance is too small, select "Approve exact amount" and authorise that amount for the escrow, the account that holds tokens until the payment can proceed. An allowance that already covers the amount lets you proceed directly.

Select "Request cash-out". The dialog closes and the payment appears in Portfolio > Transfers. Payments still being processed sit under "In progress". A payment that exceeds the bank's approval limits waits for another person at the bank to approve it. A retry after a refused request or an unconfirmed response keeps the same request identity, including when you close and reopen Withdraw, so it cannot create a second payment for that attempt.

A paused bank link, an escrow that is not ready or a missing active payout account replaces the form with its current readiness message. Propose an account through Account > Bank accounts when none is active for the token. A failed read offers "Try again" and does not mean that your bank link has disappeared.

### After your bank replaces its wallet [#after-your-bank-replaces-its-wallet]

Cash-out can be temporarily unavailable while the bank replaces its wallet. Reopen the method or select "Try again" to read its current details. The replacement escrow needs its own allowance, so approve the exact amount again when prompted. The Portal reads the current bank link before approval and before requesting payment. Changed details stop the write so you can use the new details.

### When a request is refused [#when-a-request-is-refused]

Follow the sentence shown in the dialog. A line already paying into another account cannot be requested again for the account you chose. An open recall of a bank credit takes tokens from the linked wallet. Cash-out becomes available again once it closes. While your participant account is suspended, closed, terminated or restricted from withdrawals, every cash-out request is refused. An administrator can lift a suspension, closure or restriction. A termination is final. If the wallet's existing allowance covers the amount but its balance is too small, the bank's message remains visible and the Portal does not ask you to approve the same amount again.

## Read the same data from the API [#read-the-same-data-from-the-api]

The Deposit method only reads. `GET /api/v2/users/me/bank-links` returns the caller's own links: the bank's name, the currency, the reference or virtual IBAN, the reserve account, the token, and the link's state. `GET /api/v2/users/me/bank-deposits` returns the caller's bank payments, filtered by `filter[progress]` with `open` or `done` and by `filter[q]` for a search term, and pages through the cursor in `links.next`.

The Withdraw method sends `POST /api/v2/users/me/bank-cash-outs` with the connection, active payout account and either a redemption line or a currency amount. `GET /api/v2/users/me/bank-cash-outs` returns the caller's cash-outs in Transfers, newest first, filtered by `filter[progress]` with `open` or `done`, in offset pages. These routes are described in the [Platform API reference](https://docs.settlemint.com/docs/api-reference/v2).

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

- The "Bank payment" row shows your amount, your reference and the outcome you expect.
- A "Minted to your wallet" row, because only that row means the funds are in your wallet.
- A mint transaction on that row that names the transfer that paid it.

## Related pages [#related-pages]

Use [Portfolio](https://docs.settlemint.com/docs/console/my-assets/portfolio) for the holdings the minted tokens arrive in, and the [bank rail](https://docs.settlemint.com/docs/console/asset-lifecycle/bank-rail) page to understand what the organisation does with a payment before it reaches your wallet.


# Wallet deposits and withdrawals

Source: https://docs.settlemint.com/docs/concepts/operating/investor-portal-wallet-transfers
Deposit coins from your own wallet, withdraw them to an approved payout address, cancel or collect a withdrawal, and prove a self-custody wallet.

In the Investor portal you deposit by sending coins from a wallet you control to your gateway address, and you take coins out by withdrawing them to an approved payout address. Your gateway is your own deposit and withdrawal point on one network. A deposit credits your wallet with custody receipts for the coins you send. A withdrawal returns those receipts to the gateway, and the gateway pays the coins to your payout address. The [custody gateway](https://docs.settlemint.com/docs/concepts/custody-and-signing/custody-gateway) page explains what happens behind each stage.

The Withdrawal destinations page holds a separate list: the self-custody wallets you prove with a signature. Proving a wallet records that you control its address. A gateway withdrawal goes only to the payout addresses approved for your gateway. A wallet on Withdrawal destinations does not become a gateway payout address until a gateway manager adds it.

The Console offers a Console user the same steps. **Withdraw** on [Portfolio](https://docs.settlemint.com/docs/console/my-assets/portfolio#withdraw-from-your-gateway) opens this withdraw dialog, the Portfolio [Transfers](https://docs.settlemint.com/docs/console/my-assets/portfolio#follow-your-transfers) tab lists the same rows as the portal's "Transfers" tab, and [Withdrawal destinations](https://docs.settlemint.com/docs/console/personal/withdrawal-destinations) under Personal is this destinations page.

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

- You are signed in to the Investor portal and acting as the participant whose custody balance you want to use.
- Your organisation created your gateway.
- To withdraw, you hold custody receipts in your wallet.
- To withdraw, a gateway manager approved a payout address for your gateway.
- To withdraw, you set up a transaction PIN or transaction code under Security, because every withdrawal, cancel and collect asks you to confirm with one of them.
- To prove a self-custody wallet, you have a browser wallet that holds that wallet's key and is connected to the network you withdraw on.

When a control is missing, the cause is one of these:

| What you see | What it means |
| --- | --- |
| The Withdraw button, the "From a wallet" deposit method and the Withdrawal destinations page are all missing | Custody operations are off for your platform. |
| The Withdraw button is missing, while the Withdrawal destinations page and the "Transfers" tab remain | Your organisation switched its Self-custody module off. The Deposit button is missing too unless the organisation offers bank transfers. The "Transfers" tab shows a "Read only" notice, you can still read your records, and the platform refuses every write with `platform.module.DISABLED`. Ask your organisation to switch the module on. |

Several roles at the organisation that runs your account decide parts of this flow in the Console. A screener clears a deposit that waits in review. A gateway manager approves the payout addresses of your gateway and can send a deposit to a recovery address. A custody operator clears the self-custody wallets you prove.

## Deposit coins from your wallet [#deposit-coins-from-your-wallet]

**Step 1 of 4**

### Start a deposit [#start-a-deposit]

Open "Portfolio", then select "Deposit". When the organisation also offers bank transfers, the dialog shows two tabs, "From a wallet" and "By bank transfer". Select "From a wallet". With one method, the dialog opens it directly. [Bank transfers](https://docs.settlemint.com/docs/concepts/operating/investor-portal-bank-transfers) covers the other tab.

![Deposit dialog with the gateway address, its QR code and the accepted coins](https://docs.settlemint.com/docs/screenshots/portal-venue-journey-fund-wallet.light.en.webp)

[Screenshot] The Deposit dialog shows "Your gateway address" as a QR code and as text with a copy control, an "Accepted coins" line, and a "Receipt balances" card underneath.

**Step 2 of 4**

### Copy your gateway address [#copy-your-gateway-address]

The dialog shows your gateway address as a QR code and as text with a copy control, then the "Accepted coins" line that lists the coins this gateway takes. Send only those coins. The dialog says that anything else cannot be credited automatically.

The "Receipt balances" card under the address shows, for each asset, what is "Available" to withdraw and what is "Waiting for custody". When the dialog cannot read your gateway address, it shows that error with **Try again** and no card. When only the balances fail to load, the card says so and offers "Try again".

When the dialog shows "This gateway is paused. Do not send a deposit until it resumes.", wait until the notice is gone before you send. A deposit that arrives while the gateway is paused is recorded as "In review" and is not credited until the gateway resumes and the deposit is cleared. Once the gateway has been paused too long, the gateway contract lets you pull a deposit back to its sender, a call the portal does not offer. Your address does not change, so keep it.

**Step 3 of 4**

### Send the coins from your wallet [#send-the-coins-from-your-wallet]

Send the amount from your own wallet to the gateway address, on the gateway's network. The deposit appears on the "Transfers" tab once the gateway records it.

**Step 4 of 4**

### Follow the deposit [#follow-the-deposit]

Open "Portfolio", then "Transfers". Each deposit is one row with a plus sign before its amount, a line on its progress, its status and the date, merged with your withdrawals, bank payments and cash-outs, newest first. The "Type" filter narrows the list to deposits, and "Search transfers" searches it. A deposit that has not ended sits in the "In progress" section, before the "History" section.

![Transfers tab with In progress and History sections and the Type filter](https://docs.settlemint.com/docs/screenshots/portal-wallet-transfers-transfers.light.en.webp)

[Screenshot] The "Transfers" tab shows a search field, a "Type" filter set to "All types", an "In progress" section and a "History" section.

Each row shows the signed amount with a description line, the status and the date.

### What each deposit status means [#what-each-deposit-status-means]

| Status | What it means |
| --- | --- |
| "In review" | The deposit waits for screening of the sending wallet, by the organisation's screening provider or a person. Nothing is credited. |
| "On hold" | The deposit is frozen. It is reviewed again when the freeze ends. |
| "Not credited" | The receipts could not be minted to your wallet, for example because the wallet is no longer registered to your identity. Your gateway managers are handling it. |
| "Waiting for custody" | The receipts are credited and held until the custodian accepts the coins, or the coins are on hold at the custodian. |
| "Completed" | The deposit settled and the receipts are yours to use. |
| "Returned" | The coins went back to the sender. |
| "Recovered" | Your gateway managers sent the coins to a recovery address instead of back to the sender. |

## Withdraw coins to your payout address [#withdraw-coins-to-your-payout-address]

**Step 1 of 5**

### Start a withdrawal [#start-a-withdrawal]

Open "Portfolio", then select "Withdraw". The dialog shows the "Auto-collect" switch, the "New withdrawal" button and your withdrawals, newest first, with a "View all transfers" link when there are more.

![Withdraw dialog with the Auto-collect switch, the New withdrawal button and the withdrawal list](https://docs.settlemint.com/docs/screenshots/portal-wallet-transfers-withdraw.light.en.webp)

[Screenshot] The Withdraw dialog shows an "Auto-collect" switch with its help line, a "New withdrawal" button, and a list of withdrawals, each with its amount, status and date.

"Auto-collect" is on by default. With it on, the coins are paid to your payout address as soon as the gateway can pay the request from the coins it holds for payouts. With it off, a funded request waits as "Ready to collect" until you collect it. Changing the switch asks for your transaction PIN or transaction code.

The switch holds only your own choice: when a gateway manager has turned automatic payment off for a coin, requests for that coin wait as "Ready to collect" even with the switch on.

When the gateway is paused, "New withdrawal" cannot be selected, and pointing at it or moving focus to it shows "This gateway is paused, so new withdrawals are off until it resumes."

**Step 2 of 5**

### Choose the token, the destination and the amount [#choose-the-token-the-destination-and-the-amount]

Select "New withdrawal". In the "Withdraw" sheet, choose the custody receipt to return under "Token". Each option shows its symbol and the amount available.

"Destination" then lists the payout addresses approved for your gateway, with the default one first and marked "Default". This list holds only the payout addresses a gateway manager approved for your gateway. Proving a wallet on the Withdrawal destinations page does not add it here.

Enter the "Amount". The line under it shows how much is available, and how much is "waiting for custody" when some receipts are still held. Under the amount, the sheet prices the fee and shows "Fee", then what you receive, in the coin you are paid in.

**Step 3 of 5**

### Review the fee and what you receive [#review-the-fee-and-what-you-receive]

Select "Review". The review step shows the "Amount", the "Fee", what "You receive" and the "Destination". Your gateway's escrow is the contract that holds the receipts while the withdrawal runs. When its permission to take receipts from your wallet is below this amount, an "Approve" card with the amount and symbol comes first. The request approves exactly this amount for that escrow, then requests the withdrawal.

The fee is the gateway's withdrawal fee. "You receive" is the gateway's quote of what reaches your payout address after that fee. The gateway fixes the fee when it records your request.

**Step 4 of 5**

### Confirm with your transaction PIN or code [#confirm-with-your-transaction-pin-or-code]

Select "Withdraw", then enter your transaction PIN or transaction code. The receipts are held from your wallet until the withdrawal completes or is cancelled. The portal confirms the request with the amount and symbol, or says it is still processing and that you can follow it in "Actions". When a compliance claim of your gateway's client was revoked or expired, the client is flagged and the request is refused naming the flagged client. Nothing is held and no record is created.

**Step 5 of 5**

### Follow the withdrawal [#follow-the-withdrawal]

The withdrawal appears in the Withdraw dialog and as a "Withdrawal" row on the "Transfers" tab, with the payout address after "To" and the status.

### What each withdrawal status means [#what-each-withdrawal-status-means]

| Status | What it means | What you can do |
| --- | --- | --- |
| "Requested" | The gateway recorded the request. | Wait. It cannot be cancelled in this state. |
| "Waiting for payout address" | The request names no approved payout address. | Cancel, or name an approved payout address through the Platform API. The portal has no control for it. |
| "In review" | The request is being reviewed. | Cancel. |
| "Waiting for funds" | The request waits for the coins that pay it, in the order requests started waiting. | Cancel, once the gateway's cancel time limit has passed. |
| "Ready to collect" | Coins are set aside for this request. When the automatic payment failed, the row says to collect the coins yourself. | Collect, or Cancel when the payout address was suspended or removed. |
| "On hold" | The request is frozen and leaves the queue until the freeze ends. When the hold has an end date, the row shows it. | Wait. |
| "Completed" | The coins were paid to your payout address. | None. |
| "Returning receipts" | Your receipts are on their way back to your wallet. | Wait. |
| "Receipts returned" | Your receipts are back in your wallet, because you cancelled or the request was stopped, for example rejected in review. | None. |

## Cancel or collect a withdrawal [#cancel-or-collect-a-withdrawal]

**Step 1 of 2**

### Cancel a withdrawal [#cancel-a-withdrawal]

On a withdrawal row in the Withdraw dialog or on the "Transfers" tab, select "Cancel", then enter your transaction PIN or transaction code. The portal says "Withdrawal cancelled. The receipts are back in your wallet." and the row moves to "Receipts returned".

The "What you can do" column of [the withdrawal status table](#what-each-withdrawal-status-means) says which rows offer "Cancel", so you cannot always cancel. On a "Requested" row, and on an "On hold" row frozen from a status that offers "Cancel", the button shows but cannot be selected, and pointing at it or moving focus to it shows the reason. A "Ready to collect" row whose payout address was suspended or removed since you chose it offers "Cancel" in place of "Collect", because the coins can no longer be paid there. An "On hold" row frozen while ready to collect offers no action. When its payout address was suspended or removed, it shows a "Cancel" that cannot be selected instead. A "Returning receipts" row and a finished row offer no action. A request waiting for funds can be cancelled only after it has waited longer than the gateway's cancel time limit. When it is too early, the portal answers with the date from which you can cancel. The row keeps naming that date while you wait, and Cancel switches on by itself when the time arrives, with no reload. A gateway with no cancel time limit allows no cancelling of a request waiting for funds, and the portal says so.

**Step 2 of 2**

### Collect a withdrawal that is ready [#collect-a-withdrawal-that-is-ready]

On a "Ready to collect" row, select "Collect", then enter your transaction PIN or transaction code. The portal says "Collection requested. The coins are paid to your payout address." and the row moves to "Completed" once the payment lands. Collecting while your gateway's client is flagged is refused naming the flagged client, until the flag clears.

## Prove a self-custody wallet as a withdrawal destination [#prove-a-self-custody-wallet-as-a-withdrawal-destination]

A self-custody wallet is a wallet whose key you hold. Proving it shows that you control the address. A withdrawal goes only to a payout address a gateway manager approved for your gateway, so prove the wallet and ask your gateway manager to add it as a payout address.

**Step 1 of 4**

### Open the destinations page [#open-the-destinations-page]

In the sidebar, under "Personal", open "Withdrawal destinations". The page has two sections. "Self custody" lists the wallets you added, with the "Wallet", the "Network", the date "Added" and the "State". "Managed custody" lists the wallets your custodian holds for you, each with its provider and chain ID. A managed custody wallet takes no signature here, because the key stays with the custody provider. The section says "Your custody desk adds one of these as a withdrawal destination when you ask for it."

![Withdrawal destinations page with the Self custody table and the Managed custody list](https://docs.settlemint.com/docs/screenshots/portal-wallet-transfers-destinations.light.en.webp)

[Screenshot] The "Withdrawal destinations" page shows a "Self custody" section with an "Add a wallet" button and a table of wallets with their network, date added and state, then a "Managed custody" section listing the wallets your custodian holds.

**Step 2 of 4**

### Connect the wallet you want to add [#connect-the-wallet-you-want-to-add]

Select "Add a wallet". In the "Add a self-custody wallet" sheet, select "Connect wallet" and approve the connection in your browser wallet. The wallet you connect is the destination, on the network the wallet is connected to, so switch the wallet to the network you withdraw on first. The sheet shows the wallet's address, its name and the chain ID.

**Step 3 of 4**

### Sign the challenge [#sign-the-challenge]

Select "Add wallet", then approve the signature request in your browser wallet. Signing costs no gas and sends no transaction. The message names the organisation's identifier, the chain ID, the wallet address and an expiry, so you can check what you sign. The portal says "Wallet added", and the row shows "Awaiting clearance".

**Step 4 of 4**

### Wait for a custody operator to clear it [#wait-for-a-custody-operator-to-clear-it]

A custody operator reviews the wallet. When they clear it, the state becomes "Active". When they refuse it, the state becomes "Refused" and the row offers no action. The operator's reason shows under the state.

### Sign again or remove a wallet [#sign-again-or-remove-a-wallet]

A row in "Awaiting signature" has no accepted signature, for example because you closed the sheet before signing or the challenge expired. Select "Sign the challenge" on that row, connect the same wallet on the same network, and select "Sign the challenge" in the sheet. The platform issues a fresh challenge for the same entry, so the wallet keeps its row and you do not add it again.

After a custody operator clears a wallet, the gateway still needs it as an approved source for deposits and as an approved payout address for withdrawals. The operator raises both from the **Whitelist** panel on the gateway overview. Until they do, the wallet shows no deposit or withdrawal route.

Removing a wallet cannot be undone. A removed wallet takes no new withdrawal, and adding it again needs a new signature and a new clearance from a custody operator. To remove one, select "Remove" on its row, then select "Remove the wallet" to confirm, or "Keep the wallet" to stop. The row moves to "Removed". "Remove" is offered on wallets that are "Awaiting signature", "Awaiting clearance" or "Active".

## Troubleshooting [#troubleshooting]

**The dialog says No gateway yet**

No gateway serves the wallet you act with: the organisation has not created your gateway, or has not bound it to this
wallet. Ask them to do so before you deposit or withdraw.

**The Withdraw sheet says Nothing to withdraw**

Your wallet holds no custody receipts you can withdraw. Deposit coins first, and wait for the deposit to reach
"Completed".

**The Withdraw sheet says No approved destination**

You can withdraw only to a payout address approved for your gateway. Ask a gateway manager to approve one. A wallet
that is "Active" on Withdrawal destinations is a separate list and does not count until the gateway manager adds it.

**The fee could not be priced**

The sheet shows "The fee could not be priced. The request prices it again." and "Review" stays unavailable until a fee
shows. Change the amount to price it again. When the sheet says the fee covers the amount, enter a larger amount.

**The portal says The withdrawal was not requested**

The message carries the reason. The platform refuses a request to a payout address that was suspended or removed after
you chose it, and a request for more receipts than you hold free of custody holds. Choose another destination or a
smaller amount.

**The Withdraw sheet says Withdrawals are on hold**

The platform refused the request because your organisation has restricted your account from withdrawals. Ask your
organisation to lift the restriction, then request the withdrawal again.

**The browser wallet does not sign**

"No browser wallet found" means the page found no wallet extension: install or open one, then reload. "Another account
signed" means the wallet signed with a different account than the destination: connect the wallet you are proving.
"Another network is connected" means the wallet is on a different network from the destination: switch it and connect
again.

## Use the same routes from the API [#use-the-same-routes-from-the-api]

The Withdrawal destinations page uses the custody operations routes: `GET /api/v2/custody-ops/whitelist` lists your destinations, `POST /api/v2/custody-ops/whitelist` proposes one and returns the message to sign, `POST /api/v2/custody-ops/whitelist/{entryId}/proofs` sends the signature, and `POST /api/v2/custody-ops/whitelist/{entryId}/revocations` removes one. Every route is in the [Platform API reference](https://docs.settlemint.com/docs/api-reference/v2).

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

- A deposit row that reads "Completed", and the receipt balance in the Deposit dialog showing the amount as "Available".
- A withdrawal row that reads "Completed", with your payout address after "To".
- A self-custody wallet whose row on Withdrawal destinations reads "Active".

## Related pages [#related-pages]

Use [Portfolio](https://docs.settlemint.com/docs/console/my-assets/portfolio) for the holdings the receipts sit in, [Bank transfers](https://docs.settlemint.com/docs/concepts/operating/investor-portal-bank-transfers) to fund your wallet from a bank account, and [Custody gateway](https://docs.settlemint.com/docs/concepts/custody-and-signing/custody-gateway) for what happens to a deposit or a withdrawal at each stage.


# Investor portal

Source: https://docs.settlemint.com/docs/concepts/operating/investor-portal
What your investors see in the Investor portal, from sign-in to the dashboard, and how the portal runs on your own domain with your organisation's branding.

The Investor portal is the web app your investors use to hold, buy and trade the assets your organisation issues. It is a separate app from the operator Console, with its own sign-in, its own session and its own web address. It runs on your domain and shows your theme: your logo, sign-in page images, browser icons, fonts and colours. [Your branding](#your-branding) names the cases where a global theme or the default theme shows instead. This page is for the organisation that runs the portal. Investors read the [investor guide](#the-investor-guide).

The portal reads its data from the Platform API, the same API the Console and your own integrations call, and holds no sample data. An area with nothing in it shows an empty state that says so, such as "No open offerings" in Invest.

Your organisation keeps its controls over every holding an investor sees here. A holder of the token's Custodian role can freeze a balance or force a transfer, as [Transfer-Path Compliance](https://docs.settlemint.com/docs/concepts/compliance-and-identity/transfer-path-compliance) describes, and a bank rail recall can take back tokens minted against a payment the bank reversed, as [Bank transfers](https://docs.settlemint.com/docs/concepts/operating/investor-portal-bank-transfers) describes.

## What an investor goes through [#what-an-investor-goes-through]

On a first visit, an investor goes through up to six steps before the dashboard opens. On a later visit, sign-in and the second factor are all that remain, unless a new trading document version or an enforced two-factor rule adds a step again.

1. **Sign in.** Your organisation adds investors in the Console with "Create or invite user" on the [Users](https://docs.settlemint.com/docs/console/participants/users) page. The portal has no sign-up page. With an identity provider configured, the platform refuses sign-up from the portal. Without one, the Platform API accepts email sign-up through the portal's address, and such an account has no active organisation until a platform administrator makes one active. Its sign-in page tells investors that their identity manager gives them access. Identity manager is the Console role that registers identities and onboards users. An investor signs in with email and password or with a passkey. The portal offers no sign-in through your identity provider. "Forgot your password?" sends a link to set a new password. A visitor who opens an investor page without a session goes to sign-in and returns to the page they asked for afterwards.
2. **Second factor.** When the account has two-factor authentication, a dialog asks for a 6-digit code from an authenticator app, an email or a text message, depending on the methods the account has.
3. **Wallet setup.** The investor pages open only for a session with an active organisation and an investor participant that holds a wallet. A participant is the account the investor acts as in your organisation. An investor without one goes to the "Wallet setup" page.
   - When your organisation offers more than one wallet type, the investor picks one. An embedded wallet is created with the investor's sign-in and needs nothing installed. A browser wallet is the investor's own wallet, which they prove with one signature. With a managed account, your organisation creates and holds the wallet. The embedded wallet appears only when the deployment has its embedded wallet service configured.
   - The investor then creates the wallet, or connects their own and signs a message to prove it. An investor who already has a suitable participant on the platform picks it instead.
4. **Trading document acceptance.** When your organisation has published trading terms or a risk disclosure, the portal shows "Review the current trading documents". The investor ticks each current version and selects "Accept and continue". The portal records the acceptance and continues.
5. **Two-factor setup.** When the deployment requires two-factor authentication and the investor has not set it up, the portal sends every investor page to the Security page until the investor sets it up. When trading documents also wait for acceptance, the acceptance screen comes first.
6. **Dashboard.** The dashboard opens with the sidebar beside it.

Two account states stop the journey and offer no retry, because the investor cannot change them. A session with no active organisation shows "No active organisation". A platform administrator must make an organisation active on the account, and until then the investor can open Profile and Security or sign out. The onboarding screen "This organisation has not chosen an investor wallet yet" shows in two cases: your organisation has not designated an investor wallet provider, or it designated the embedded wallet and the deployment has no embedded wallet service configured.

You publish the trading documents in the Console, under [Trading terms and risk disclosures](https://docs.settlemint.com/docs/console/organisation-settings/general#publish-trading-terms-and-risk-disclosures). Publish both kinds together. Once one kind has a version in force, no investor passes the acceptance screen until the other kind is published too. A new major version always asks investors to accept again. A new version within the same major version asks again only when you tick "Require participants to accept this version again". The portal shows the acceptance screen again the next time it reads the investor's acceptance status.

The platform also checks acceptance on the trading venue and on withdrawals. While an acceptance is outstanding, it refuses to place, amend, sign or cancel an order, and it refuses to create a withdrawal. Other operations, such as a purchase in an offering through Invest, are held back by the portal's acceptance screen only.

## The dashboard and the areas [#the-dashboard-and-the-areas]

The dashboard has three shapes. Before the investor's on-chain identity is registered, it shows "Register your identity to hold and trade assets" with the steps that remain. The on-chain identity is the record that regulated assets check before a wallet can receive them. With a registered identity and no holdings, it shows "You hold no assets yet." with a "Browse offerings" button that opens Invest. With holdings, it shows "Key figures" and the portfolio. Each shape includes "Needs attention", which lists what waits for the investor.

![Investor portal dashboard with the sidebar, key figures and Needs attention](https://docs.settlemint.com/docs/screenshots/portal-dashboard-overview.light.en.webp)

[Screenshot] The sidebar on the left lists Dashboard, Actions and Activity, then Portfolio, Invest and the other areas under Wealth, then Contacts and Watchlists under Personal.

The dashboard shows key figures, a Needs attention panel and the portfolio.

The sidebar leaves out an area your organisation does not offer, rather than greying it out. Dashboard, Actions and Activity sit at the top without a group label.

| Area | What the investor does there | Sidebar group | When it appears |
| --- | --- | --- | --- |
| Dashboard | Sees what needs attention, the portfolio value and recent activity | Unlabelled | Always |
| Actions | Completes tasks that wait for them, such as casting a vote or accepting a transfer | Unlabelled | Always, with a count of pending actions |
| Activity | Looks back at what happened on the account | Unlabelled | Always |
| Portfolio | Sees holdings, their value and the income they pay, such as dividends and interest | Wealth | Always |
| Invest | Buys into an offering that your organisation has opened | Wealth | Always. It shows "No open offerings" when nothing is open to the investor |
| Trading | Buys from and sells to other investors after issuance | Wealth | When the deployment turns on the Secondary market module and your organisation has deployed the trading venue add-on |
| Announcements | Reads the notices a venue publishes, including those no longer on display, and filters them by category, market and date | Wealth | Under the same two conditions as Trading |
| Settlements | Swaps assets with another party, where neither side's transfer completes without the other | Wealth | When your organisation has deployed the XvP settlement add-on |
| Votes | Votes on proposals for the assets they hold | Wealth | When your organisation has deployed the token governance add-on |
| Contacts | Keeps the wallets of counterparties for reuse | Personal | Always |
| Watchlists | Follows assets | Personal | Always |
| Withdrawal destinations | Sees the wallets that withdrawals can go to | Personal | When the deployment turns on the Self-custody module |

The account menu holds Profile, My participants, On-chain identity, Security, Bank accounts when your organisation offers bank payouts, and Notifications, then the theme, the language, Documentation when the investor guide is configured, Keyboard shortcuts, Report an issue and Sign out. The language menu lists the languages your organisation enables in the Console, from the same ten, and shows only when more than one is enabled. Arabic is laid out right to left.

The portal's paths match the Console's paths, such as `/wealth/portfolio` and `/personal/contacts`. The breadcrumb starts with the sidebar group, and the group name is a link. Wealth opens Portfolio and Personal opens Contacts, the first area of each group, which every investor sees.

## When something is unavailable [#when-something-is-unavailable]

The portal tells the investor what went wrong and offers only the actions that can change it.

| What the investor sees | Cause | What the screen offers |
| --- | --- | --- |
| "Platform unreachable" | The session read failed with a server error or took longer than 10 seconds, or a read the portal needs to admit the investor failed | Retry |
| "The platform is unreachable" on sign-in | The sign-in request got no answer | The sign-in button reads Retry |
| "Page not found" | The address points to nothing the investor may see, for example a malformed id, an unknown add-on address or a record the investor may not see | Go back, Go home |
| "Not available" | A direct link to an area your organisation does not offer | Go to dashboard, Go back |
| "Couldn't check your access" | The portal could not read whether the area is available | Try again, Go to dashboard |
| "XvP settlement isn't set up" | A Settlements link while your organisation has not deployed the XvP settlement add-on | Go to dashboard, Go back |
| "Unable to load this section" | One section's read failed. The rest of the page keeps working. The platform's own title replaces this one when the error has one | Try again, unless the platform refused the read or marked it as not retryable |
| "Your session is about to expire" | The organisation's idle sign-out is 60 seconds away | Stay signed in |

A section read that fails for a temporary reason is retried up to two times with a growing delay, and then the section shows as unavailable.

The portal does not retry a read that the platform refused. It also does not send that read again for five minutes, even when the investor switches windows or returns to the page. A section error shows a reference ID that the investor can pass to your support team.

You set the idle sign-out period in the "Idle sign-out" row of the Security section on the Console's [General](https://docs.settlemint.com/docs/console/organisation-settings/general) page. An idle sign-out in one portal tab also signs the investor out in their other portal tabs.

## Your domain [#your-domain]

An investor's portal session belongs to the portal's domain, and the Console does not accept it. You cannot embed the portal inside a page of another site, because it refuses to load in a frame.

The Investor portal is its own workload in the Helm chart, switched on with `investorPortal.enabled`, and off by default. You give it a public URL in `global.dalpApp.env.INVESTOR_PORTAL_URL`. The chart passes that URL to the portal and lists it as a portal origin of the Platform API, so the platform accepts sign-ins from that host. The Console's account menu then shows an "Investor portal" item to every Console user, and the item opens the portal in a new tab. Without a valid `http` or `https` portal URL, the Console shows no item.

The investor's browser never calls the platform directly. It sends every platform call to the portal's own origin, and the portal server forwards `/api` and `/dalp` paths to the private platform address in `DAPI_INTERNAL_URL`. The session cookie therefore belongs to the portal's domain wherever the platform runs. The Console accepts only a session that its own sign-in issued.

The portal forwards a sign-up call like any other, so the identity provider rule in [What an investor goes through](#what-an-investor-goes-through) applies to it. When the Console signs in only through an identity provider, an account that administers the platform or an organisation cannot sign in to the portal. It signs in to the Console through the identity provider.

The forwarding route removes the forwarding headers the browser sent and passes on the client address only from the proxy in front of the portal. The deployment names that proxy in `TRUSTED_PROXY_PROFILE` as `envoy`, `nginx` or `openshift`, and any other value counts as none. A read that loses its connection is retried once, and a request with a body is not retried. When the platform does not answer, the call gets HTTP 502 with the code `UPSTREAM_UNAVAILABLE`. A method the platform does not serve, such as `TRACE` or `PROPFIND`, gets HTTP 405 with the code `METHOD_NOT_ALLOWED` and an `Allow` header that lists the methods it does serve. Event streams pass through as streams. [Deploy browser apps with user sessions](https://docs.settlemint.com/docs/deployment/install/browser-apps) has the Helm values and the OpenShift Route setup.

## Install the portal as an app [#install-the-portal-as-an-app]

An investor can install the portal from a browser that supports installing web apps, such as Chrome on Android, or Safari on iOS through Share, then Add to Home Screen. The portal then opens in its own window from an icon on the home screen or desktop. DALP builds no separate iOS or Android app, because the installed portal is the same portal: the investor signs in, enters the second factor and signs wallet requests on the same pages as in the browser.

The app takes its name, icon and colour from your theme. The name is the logo's alternative text, with "DALP Investor portal" when you set none. The icons are the theme's browser icons, and the colour behind the icon while the app opens is the light background colour. An organisation that sets no browser icons shows the default icons on the home screen, so upload them on the Console's [Theme](https://docs.settlemint.com/docs/console/organisation-settings/theme) page. Installing needs an https address, which your portal URL already is in production.

The device keeps only the portal's script, style and font files, so a repeat visit loads them without a download. It keeps no page, no platform answer and no account data. The portal does not work offline: with no connection, the investor sees the browser's own offline message, and no order or other request goes through until the connection returns. A sign-in, second factor or wallet signature is never served from the device, so an installed portal cannot show a stale signed-in page.

## Your branding [#your-branding]

The portal applies the theme your organisation sets on the Console's [Theme](https://docs.settlemint.com/docs/console/organisation-settings/theme) page and keeps no copy of its own. A theme change reaches an investor's open portal the next time the page loads.

- **Logo.** The sidebar shows the horizontal logo, and the icon when the sidebar is collapsed. The sign-in page uses the sign-in logo when you set one.
- **Sign-in page images.** The sign-in page shows the overlay and background images you set.
- **Browser icons.** The favicons, the home-screen icon and the icon of the [installed app](#install-the-portal-as-an-app) come from the theme.
- **Typography and colours.** The sans-serif and monospace faces and the light and dark colours style every page.
- **Titles.** The browser tab title, the home-screen app title and the installed app's name use the logo's alternative text. Without it, the tab reads "DALP Investor portal" and the home-screen title reads "SettleMint", so set the alternative text.

When a platform administrator turns on a global theme, every page shows the global theme instead of your organisation's theme, before and after sign-in. Without a global theme, signed-out screens such as sign-in show your theme only when the deployment has a single organisation. In a deployment with more than one organisation they show the default theme, and your theme appears after sign-in. When the theme read takes longer than 2 seconds or fails, the portal draws the default theme and reads the theme again on the next navigation.

## The investor guide [#the-investor-guide]

The investor guide is a separate documentation site for investors. It has six pages: "Investor guide", "Sign in and set up your account", "Deposit by bank transfer", "Bank payments in Transfers", "Bank accounts for payouts" and "Read your bank cash-outs". The Helm value `investorDocs.enabled`, off by default, deploys the guide beside the portal and routes `/docs` on the portal's host to it.

The portal links to the guide only when you set `INVESTOR_GUIDE_URL` in `investorPortal.env`. The value is a path on the portal's host, such as `/docs`, or an `http` or `https` address, and the portal ignores any other value. With a valid value, the account menu shows "Documentation". The information icon next to a term, on screens such as the portfolio, offerings with vesting or a refund window, the trading venue and settlements, then adds a "Read the docs" link below its one-line explanation.

Other information icons, such as those that explain a figure or a form field, carry no link. Without the value, the menu item and the links are hidden, and the explanations stay. Each link opens the guide in a new browser tab.

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

- The portal's public URL opens a sign-in page that shows your logo and sign-in images, and the browser tab shows your title. In a deployment with more than one organisation and no global theme, they appear only after sign-in.
- `/manifest.webmanifest` on the same address lists the name and icons that an installed app uses, and the portal installed from a phone browser shows its home-screen icon.
- Signed in as an investor, the sidebar lists only the areas your organisation offers.
- A direct link to another area shows "Not available".
- The Console's account menu shows "Investor portal" and opens this host.

## Related pages [#related-pages]

- [Delegated authority](https://docs.settlemint.com/docs/concepts/compliance-and-identity/delegated-authority): the acting-as model the portal shares with the Console.
- [Users](https://docs.settlemint.com/docs/console/participants/users): adding investors.
- [Portfolio](https://docs.settlemint.com/docs/console/my-assets/portfolio): the holder operations an investor starts from a holding.
- [Bank transfers](https://docs.settlemint.com/docs/concepts/operating/investor-portal-bank-transfers): deposits by bank transfer, which an investor starts from Deposit in Portfolio.


# Platform Health

Source: https://docs.settlemint.com/docs/concepts/operating/platform-health
Platform Health rolls API errors, chain connectivity, workflow completion and data freshness into one verdict for platform admins and Owners.



[Figure] Four independent panels roll up into one verdict, and the worst panel wins. Four quiet input cards sit in a row, each showing its own current verdict. Platform API reads operational, Transactions reads operational, Workflows reads operational, and Data freshness reads degraded. Arrows from each converge into one focal card labelled Rollup verdict, worst of four panels wins. Below the focal card, four small outcome chips read outage, degraded, operational, and no data. An accent arrow from the focal card points to the degraded chip, showing that the one degraded panel among three otherwise healthy ones is enough to make the overall verdict degraded. Labels: Platform status (Console, Owner or platform admin); Platform API; operational; Transactions; operational; Workflows; operational; Data freshness; degraded; Rollup verdict; worst of four panels wins; outage; degraded; operational; no_data.

The Platform status page rolls up four independent panels into one verdict, and the worst verdict among them wins, never an average.

Every panel resolves to one of four verdicts: `outage`, `degraded`, `operational` or `no_data`, which means there is no signal to judge.

Only a platform admin or the organisation's Owner can open the Platform status page. On a shared deployment, every Owner sees request totals and error rates summed across all organisations, never another organisation's requests.

A rollup takes the worst verdict among independent panels, and the best verdict within a redundant provider pool. One failed upstream does not fail the chain while any other in the pool still answers.

## One verdict for the whole platform [#one-verdict-for-the-whole-platform]

Platform Health is the condition the platform reports about itself, and the Console's Platform status page shows it as one verdict. A platform admin or an organisation's Owner reads there whether the platform is healthy now, without reconciling separate charts. A monitored signal that crosses its condition reads as `outage` or `degraded`. A chain that is reindexing after a restart or backfill reads as `operational`. Rebuilding state is the indexer working as designed, so a restart does not turn the page red.

Data freshness, Transactions and Platform API read the whole deployment, because the indexer, the chains and the API serve every organisation. Workflows counts only your organisation's background work, so two organisations on one deployment can see different headers.

## Reading the Platform status page [#reading-the-platform-status-page]

The page leads with four core panels, Data freshness, Transactions, Platform API and Workflows, which arrive together from one read. A slow source holds all four, and a failed Data freshness, Transactions or Platform API source fails all four. A failed workflow source leaves only Workflows at `no_data`. Webhooks, Email, FIX sessions, Batch jobs and Scheduled jobs load on their own, and raise the header only while degraded or in an outage.

The page also shows the same rollup over recent days, hour by hour, so a dip that already recovered stays visible. Each day is judged on the whole day's evidence, then each hour on its own evidence, capped at its day. An hour never reads worse than its day, so a short outage colours only the hours it lasted. The history covers full UTC days only. The day in progress is left out because not every telemetry source publishes a partial day at the same pace.

## Panel rollups and the two probes underneath [#panel-rollups-and-the-two-probes-underneath]

Panel rollups follow two rules, depending on what they aggregate. Independent panels roll up to the worst verdict among them, because one degraded panel is a real problem however healthy the others are. Redundant providers, such as the pool of upstream RPC endpoints behind one chain, roll up to the best verdict. A chain stays operational while any one of its upstreams answers, and the pool degrades only once every upstream in it does.

Two probes sit beneath the Console page, for the team that runs the deployment. Readiness asks whether the process can serve traffic. `/readyz` checks Postgres, the indexer's own readiness and whether the [Workflow Engine](https://docs.settlemint.com/docs/concepts/settlement/workflow-engine) is shutting down, and reports ready only when all three agree. It also answers 503 while the process starts or drains. A failed readiness check takes the process out of the load balancer and nothing more.

Liveness asks whether the process is still running at all. It is served on a port of its own. A thread beside the main event loop reads a heartbeat that loop stamps, and reports the process wedged once the stamp is more than thirty seconds old. Kubernetes restarts the pod on that answer, so a seized process is replaced without an operator. The restart does not fix the cause, so read the runbook if it repeats. That dedicated port is the Platform API pod's. The workflow runner and indexer pods answer liveness on the health port their main loop serves. A seized loop there stops answering, and Kubernetes restarts the pod after four failed probes ten seconds apart.

[Figure] Readiness watches the dependencies. Liveness watches the event loop. Two lanes contrast the two probes. On the left, readiness: three inputs, a Postgres probe, the indexer's own readiness evaluation, and a check for whether the Workflow Engine is shutting down, feed into a focal card labelled merged readiness service. That card produces the outcome 200 ready, or 503 with a specific reason that takes the process out of the load balancer. On the right, liveness, served on a port of its own: the main event loop stamps a heartbeat, and a thread running beside that loop reads the stamp. A stamp older than thirty seconds answers 503 wedged, which Kubernetes answers by restarting the pod. A fresher stamp answers 200. A failing dependency stops traffic reaching the process. Only the process's own loop seizing gets it restarted. Labels: /readyz: readiness; Postgres; probe; Indexer; readiness; check; Workflow; Engine; shutdown; Merged readiness service; 200 ready, or 503 with a reason; liveness: a port of its own; The event loop stamps a heartbeat,; a thread beside it reads the stamp; Silent past 30s: 503 wedged; Kubernetes restarts the pod.

Readiness checks Postgres, the indexer and the Workflow Engine and stops traffic on any failure, while only a stalled process loop restarts the pod.

## The readyz and healthz contract [#the-readyz-and-healthz-contract]

`/healthz` on the API port returns `{ status: "ok" }` as soon as the port accepts connections, before the application has finished building, and checks no dependency. The startup probe uses it. `/readyz` keeps answering 503 until the application has finished building. It then fans out concurrently to a Postgres probe, budgeted at eight seconds, and a host probe that reads the merged readiness of the indexer and the Workflow Engine, budgeted at one second. Any one failing returns 503 with the specific reason. [Platform API not ready](https://docs.settlemint.com/docs/deployment/runbooks/platform-api-not-ready) walks through finding which dependency tripped it.

## How the Platform API panel judges a day [#how-the-platform-api-panel-judges-a-day]

The Platform API panel judges each day from integer request counts, and the day's request volume decides which rule applies. A 5xx response is a server error and a 4xx response is a client error.

| Requests that day | Condition | Verdict |
| --- | --- | --- |
| 0 | no requests at all | `no_data` |
| Fewer than 500 | 50 or more 5xx responses | `outage` |
| Fewer than 500 | fewer than 50 5xx responses | `operational` |
| 500 or more | 5xx responses are 5% or more of the total | `outage` |
| 500 or more | 5xx responses are 1% or more, or 4xx responses are 50% or more | `degraded` |
| 500 or more | otherwise | `operational` |

In the history, this table judges the day. Each hour of that day is then judged by the same 5xx and 4xx shares over its own requests, without the volume split, and capped at the day's verdict. A quiet day judged `operational` shows no `degraded` or `outage` hour. On an outage day, only the hours whose own error share meets the outage condition read `outage`.

Unauthorised and forbidden responses are excluded from the 4xx count, because an authentication failure describes the caller, not the platform. A flood of failed sign-ins therefore does not move this panel. Read the [Audit Trail](https://docs.settlemint.com/docs/concepts/records-and-evidence/audit-trail) or your edge logs for it.

## What an organisation sees of other organisations' traffic [#what-an-organisation-sees-of-other-organisations-traffic]

The Platform API panel counts requests from every organisation on the deployment, and the Owner of any organisation can open it. An Owner therefore sees the deployment's total request volume and error shares, never another organisation's requests, callers or paths. The panel's detail view covers only your own organisation's requests, including its totals and charts, so the detail figures can be lower than the panel's.

## A status records a condition, not a fix [#a-status-records-a-condition-not-a-fix]

A `degraded` or `outage` entry means a monitored signal crossed its configured condition. Read the affected panel for the cause and impact. The page records that the condition existed and says nothing about whether anyone resolved it. A chain that stops making progress while its process keeps serving requests is not a wedged process, so nothing restarts it. The stalled chain shows on this page and in readiness, and an operator decides what to do.

## Frequently asked questions [#frequently-asked-questions]

### Who can see the Platform status page?

A platform admin or the organisation's Owner. A system role such as System manager does not open it.

## Related concepts [#related-concepts]

- [Workflow Engine](https://docs.settlemint.com/docs/concepts/settlement/workflow-engine): Its completion rate and shutdown state feed the Workflows panel and the readiness check.
- [Settlement Verdict](https://docs.settlemint.com/docs/concepts/settlement/settlement-verdict): The recorded outcome of one on-chain operation, the kind of outcome the Transactions panel counts in this page's rollup.
- [Platform API not ready](https://docs.settlemint.com/docs/deployment/runbooks/platform-api-not-ready): What to check when `/readyz` reports 503.
- [Ledger indexing stalled](https://docs.settlemint.com/docs/deployment/runbooks/ledger-indexing-stalled): What to check when the Data freshness panel reports a chain stuck.


# Tables

Source: https://docs.settlemint.com/docs/concepts/operating/table-views
Save a Console list as a named view, act on several rows at once, move through rows by keyboard, and come back to the list as you left it.

Console members can save a filtered list under a name and act on many rows at once. Four lists offer both: Holders, the blocklist, Users and Actions each keep named views of their filters, sort, search, page size and columns, and each offers a selection bar. The People tab of Roles and permissions offers a selection bar too, with Grant roles and Revoke roles. Every Console table remembers its column layout in your browser and the row you last focused. Saved views of an assistant answer are a different feature: they re-run the reads behind a question, and [Saved views](https://docs.settlemint.com/docs/console/personal/saved-views) covers them.

Any signed-in member who can open a list can save views of it, arrange its columns and select its rows. Whether an action on the selection runs depends on the role behind that action, such as the Custodian role for a freeze on Holders.

## Save the list you built [#save-the-list-you-built]

A saved view is a name for one list's filters, sort, search, page size and columns. The platform stores it for you, so it opens the same list from any browser you sign in to.

1. Set the filters, sort and search you want, and arrange the columns as you read them.
2. Open Saved views in the toolbar and choose Save current view….
3. In the Save this view dialog, type a Name of up to 60 characters. The dialog says the view "Saves the filters, sort and columns you see now."
4. Switch on Share with my organisation when colleagues need the same list. The hint reads "Everyone in your organisation can open this view. Only you can change it." Everyone in the organisation then sees the view's search text and filters, including any name or address typed into them.
5. Choose Save view. A notice reads "View “Frozen holders” saved", with your name in place of the example.

![Save this view dialog over the Users table, with an empty Name field, the Share with my organisation switch off and Save view](https://docs.settlemint.com/docs/screenshots/console-table-views-save-view.light.en.webp)

[Screenshot] The Save this view dialog opens over the Users table.

The Name field is empty, the Share with my organisation switch is off, and Save view stays unavailable until you type a name.

To open a view, open Saved views and pick it. The open view carries a tick, and a notice reads "View “Frozen holders” opened". Opening a view writes its filters into the page address and starts at the first page, so the address carries the state and a copied link opens the same list for someone else.

The menu lists your own views under "My views" and other members' views of the same table under "Shared with your organisation". A view shared with the organisation carries a "Shared" badge, in either list. Only the owner changes or deletes a view. Each of your own rows carries a Delete view button that names the view. Deleting takes effect at once, without a confirmation, and removes the view for everyone it was shared with. A notice reads "View “Frozen holders” deleted".

![Users table, signed in as Platform Admin, with the Saved views menu open, reading No saved views yet, and Save current view… highlighted](https://docs.settlemint.com/docs/screenshots/console-table-saved-views-menu.light.en.webp)

[Screenshot] Signed in as Platform Admin, the user opens the Saved views menu from the toolbar of the Users table.

Platform Admin has no saved view of this table and sees none shared with the organisation, so the menu reads "No saved views yet", with "Save current view…" highlighted below it.

| What you see | Why, and what to do |
| --- | --- |
| "You already have a view with this name." | Names are unique among your views of one table, ignoring case. Pick another name or delete the older view. |
| "You can keep up to 50 views for a table. Delete one to save another." | You keep at most 50 views of one table. Delete one you no longer use. |
| "Couldn't save the view." or "Couldn't delete the view." | The request failed for another reason. Try again. |
| "Couldn't load saved views." in the menu | The list of views did not load. The table itself keeps working. |
| "No saved views yet" | Nobody has saved a view of this table that you can see. |

## Arrange the columns [#arrange-the-columns]

The View button sits at the end of the toolbar. When columns are off, including those a table starts with hidden, it counts them: with two off it shows "View" and "2 hidden", and its accessible name reads "View 2 hidden". It counts only the columns you or the table turned off, so the count is the same at every width: a column that a narrow screen folds under the row name, or leaves out for lack of room, does not count. A column whose header stays on one line folds under the row name once that header no longer fits, so a long header is never cut off at the card edge.

Its menu ticks the columns that show and offers Arrange columns…, which opens a dialog that says "Choose the order the columns appear in. This browser remembers your layout." Each column has a move up and a move down control, and Reset columns brings back the table's default columns and order.

The layout belongs to you and that table in this browser. Another browser, or another person in the same browser, starts from the default. A column added to the table after you last arranged it appears at the end. Opening a saved view applies its columns as well as its filters, and that layout becomes this browser's layout for the table.

## Act on a selection [#act-on-a-selection]

Ticking a row opens a bar at the edge of the window.

| Control | What it does |
| --- | --- |
| "N selected" | The count of ticked rows, announced as it changes. |
| Select all N on this page | Ticks every row of the page on screen. |
| An action button | Runs that action for every ticked row. |
| Export N | Downloads the ticked rows as a CSV file. |
| Clear | Unticks every row and closes the bar. |

![Users list with one row ticked and the selection bar showing 1 selected, Export 1 and Clear](https://docs.settlemint.com/docs/screenshots/console-table-selection-bar.light.en.webp)

[Screenshot] One row is ticked on Users.

The selection bar reads "1 selected" and offers "Select all 20 on this page", "Export 1" and "Clear", with no other action.

An action that cannot run for the whole selection stays in the bar and states the reason. The platform checks your permission when the action runs, so an enabled button is not proof that the action succeeds. The actions differ by list:

| List | Actions for a selection | What stops them |
| --- | --- | --- |
| Holders | Freeze, Unfreeze | "You do not have the custodian role for this token." without that role. "Every selected holder needs a balance that is not frozen." for Freeze, and "Every selected holder needs a frozen balance." for Unfreeze. Both leave the bar while the list shows a [past date or block](#read-a-list-as-it-stood). One wallet confirmation covers every ticked holder. |
| Blocklist | Remove from blocklist | Hidden without the Custodian role on the token. With one row ticked, it opens the "Unblock address?" sheet, which asks you to confirm. With more, it says "Each removal needs its own wallet confirmation. Select one address." |
| Users | Export only | None. |
| Actions | Approve, Reject | "Only pending checker approvals can be decided together. Deselect the other actions." when the selection holds a row of any type other than a [Checker approval](https://docs.settlemint.com/docs/concepts/custody-and-signing/maker-checker), such as an administrative change, a withdrawal or a held deposit. The bar shows on the Pending tab only. |

Approve and Reject on Actions run as soon as you choose them, with no confirmation, and send a decision for every ticked Checker approval at the same time. A decision cannot be undone, so check every ticked row first. When some succeed and some fail, a notice reads, for example, "3 decided, 1 failed. The failed ones are still pending." When every decision fails, the notice reads "Failed to execute Approve" or "Failed to execute Reject" instead, with a reference ID when the platform returns one. The failed rows stay in Pending for you to decide one by one.

Each Actions tab keeps its own saved views, so a view saved on Completed does not appear on Pending.

The rules behind each action live on its own page: [Emergency halt and freeze](https://docs.settlemint.com/docs/console/asset-management/manage/pause-freeze) for a freeze, and [Actions](https://docs.settlemint.com/docs/console/essentials/actions) for checker approvals.

## Read a list as it stood [#read-a-list-as-it-stood]

Holders carries an As of control in its toolbar. The button reads "As of today" until you pick something. Choose a date, or type a block number, and the list shows the balances as they stood then, read from the chain data the platform has indexed into its own database, with Back to today to return. [Ledger data](https://docs.settlemint.com/docs/concepts/records-and-evidence/ledger-data) covers that index. A block number must be a whole number above 0, or the field says "Enter a whole block number above 0." A date is read at 23:59:59 UTC on that day.

On a phone the control opens a bottom sheet with the calendar and the block field in one view. On a wider screen it opens a popover under the top bar that scrolls inside the space below it.

## Move through rows by keyboard [#move-through-rows-by-keyboard]

| Keys | What happens |
| --- | --- |
| `↓` `↑` | Moves the focused row down or up. `j` and `k` do the same. |
| `Enter` | Opens the focused row's page or details. |
| `x` | Ticks or unticks the focused row, on a list that offers a selection. |
| `/` | Moves focus to the table's search field. |
| `Esc` | Clears the selection. With nothing selected, leaves the focused row. |

In the search field, `Esc` clears the search text, and a second `Esc` leaves the field. The focused row carries a ring. A screen reader hears "Row 3 of 40" as the ring moves, "Row selected" or "Row deselected" when you press `x`, and "Selection cleared" when `Esc` clears the selection.

The keys do nothing while a text field has focus, while a dialog, sheet or menu is open, and while you hold `⌘`, `Ctrl` or `Alt`. [Keyboard shortcuts](https://docs.settlemint.com/docs/console/essentials/keyboard-shortcuts) lists the keys that work on every page.

## Read new rows when you choose [#read-new-rows-when-you-choose]

Actions and a venue's orders keep streaming while you read, and a token's holders refresh when a write settles. None of them move rows under the pointer. Rows that arrive wait behind a pill that reads "2 new", with the accessible name "Show 2 new rows". Choosing it brings them in. A row already on screen updates in place and keeps its position, so a changed status or balance shows without the pill and without re-sorting the rows. Choosing the pill, or changing the sort, filter or page, puts the rows back in sort order.

## Read which filters apply [#read-which-filters-apply]

A filter applied from the page address, from a saved view or from the assistant's filter offer shows on the toolbar the same way as one you picked from the filter menu. [Navigation](https://docs.settlemint.com/docs/concepts/operating/console-navigation#read-a-tables-filters) explains the filter buttons and chips.

## Open the row a link names [#open-the-row-a-link-names]

A link that names one row of a table opens that row's details on the page that holds the table. A fill's trade reference on a venue order opens the venue's settlement instructions with the batch that holds the trade opened, and a link to a venue configuration approval opens that approval the same way.

The row opens once, when it first shows among the table's rows. A table that loads after the page opens, or a search that hid the row and is cleared, still opens it. You can close the row, and rows that arrive later do not reopen it. Opening the link again opens it again.

## Come back to the same place [#come-back-to-the-same-place]

Filters, sort, search and page live in the page address, so a bookmark or the Back button restores the list you left. The table also remembers the row you last focused for that history entry, so Back and Forward return the ring to that row. Column choices come back from the browser, and a saved view brings back both. A sheet opened from a row stays open with what you typed when the window crosses the width at which columns fold, for example when you rotate a tablet.


# Audit Trail

Source: https://docs.settlemint.com/docs/concepts/records-and-evidence/audit-trail
An audit trail lets you show a regulator or an auditor who did what, under which role, without relying on the requester's own account of the request.



[Figure] Audit trail: two records, two different proofs. On chain, a write is provable only as far as which smart account signed it. Off chain, the platform's audit trail binds that same request to the human actor, the role they held at the time, and the route they called, written as one record per covered request. The trail proves who acted under what role, on which route, with what outcome. It does not prove which party a delegated actor was standing in for. Labels: One record per covered request; Proves which smart; account signed; On chain; Binds the request to; actor, role, and route; Off-chain audit trail; Audit record; one entry per covered request; Proves; Actor, role at the time,; route, outcome, timing; Does not prove; Which party a delegated; actor was standing in for.

The trail binds a request to the actor and role that made it, not to the party a delegated actor stood in for.

Request middleware writes the trail from each route's declared audit disposition, so a route is covered from the moment it is written.

A covered mutation that cannot be recorded does not run. Authentication writes, which the authentication server records itself, are the exception: they fail open, so a trail outage cannot lock every operator out. Most sensitive reads that cannot be recorded are still served, with the failure logged as an error. Six routes declare that they require the entry and are refused instead.

Under a delegated authority the trail names the operator as the actor and the participant the request acted as.

## Why the chain cannot answer who acted [#why-the-chain-cannot-answer-who-acted]

A signature on a blockchain transaction proves which smart account sent it. It says nothing about which person sat behind that account, which role they held, or whether that step was theirs to take. A regulator asking who approved a compliance override, or an auditor confirming that only cleared staff opened a customer's file, is asking about a person and a permission, and a chain answers about a wallet.

A denied request, a rejected submission, a configuration edit and a sensitive read produce no transaction, so a chain-only investigation finds nothing.

The audit trail binds every covered state-changing or sensitive request to the human actor, their platform role and organisation role at that moment, and the outcome, whether or not the request ever reached the chain. It does not record which on-chain role grant authorised the act. The trail is read back through the same part of the platform that already produces what a regulator must be told, which is why it is one of the [reporting obligation](https://docs.settlemint.com/docs/concepts/records-and-evidence/reporting-obligation) export's own report kinds, covered later on this page.

## Why this trail covers the whole platform, not one asset's life [#why-this-trail-covers-the-whole-platform-not-one-assets-life]

[Asset Lifecycle](https://docs.settlemint.com/docs/concepts/issuing-and-markets/asset-lifecycle) indexes a different trail: every stage of one instrument's life, from design through issuance, servicing, and retirement, against that same asset's own indexed record, which is what makes that instrument's whole life auditable from one place. That trail answers whether an act on that instrument was authorised and left a record.

The audit trail answers a wider question. It covers every state-changing or sensitive request across the platform, regardless of whether an asset is even involved. Signing in, resetting a password, creating an API key, and enabling two-factor authentication all get an entry, described in the section below, alongside every transfer, coupon run, and trade that touches an asset. An entry names the actor and the role they held. It names an asset only when the request itself acted on one.

## What the trail covers, and what it leaves out [#what-the-trail-covers-and-what-it-leaves-out]

Application-level write restrictions do not make the database itself a write-once archive.

What is logged: every state-changing request, and every read whose occurrence itself matters, tied to the person who made it, the role they held at that moment, their tenant, and the outcome. Ordinary reads are not logged. Logging every read would make the trail itself a privacy problem.

What is immutable: the application never updates or deletes an audit row. A database owner still could, and the hash chain and its on-chain anchor would show it. A pending row never changes. The outcome is a second append-only row linked to the pending row. The database refuses a change to a recorded audit row. The only write it accepts on an existing row fills in the hash of a row recorded before hashing existed, and only when that hash matches the row. The trail shows the two rows as one entry that keeps the pending row's identifier and start time. For every row, an organisation's or the platform's, the database refuses a delete unless the row's day is anchored. It does not check the retention window, which only the retention job applies. Each row is linked to the previous row by a SHA-256 hash. The platform's integrity check can report the first broken row, and a reviewer who compares an export with the on-chain anchor can detect a change the database alone would not show.

What is exportable: three read shapes plus a reporting-obligation export, which [How you read the trail](#how-you-read-the-trail) covers.

What the retention is: the `global.dalpApp.config.monitoring.auditRetentionYears` Helm value takes 5, 7 or 10 years, or `indefinite`. The default is `indefinite`, which keeps every row. The window ends at the end of a UTC day. A UTC day past the window is deleted only as a whole, after its chain head has been anchored and after every row of that day is in a published or acknowledged end-of-day audit report. The report reads the trail once, so a row written after that read is in no report and keeps its day. Rows of a platform-wide operation, such as a platform administrator's user administration and impersonation, form one platform chain. The daily job anchors that chain like an organisation's, the platform integrity check reads it, the database refuses a delete of its rows until their day is anchored, and the retention job never removes them, because no end-of-day audit report holds a row without an organisation. The scheduled purge runs after the daily anchor attempt.

## Two writes bracket every request [#two-writes-bracket-every-request]

The audit trail writes an entry twice for every covered mutation: once before the handler runs, recording that the attempt happened, and once after, closing the entry with the outcome. A request that dies between the two writes has already left the first one, so no attempt vanishes without a trace. A sensitive read writes both rows after its handler has run.

Both writes join the hash chain of the request's organisation, or the platform chain when the operation is platform-wide. The first write records the request scope, the hash of the previous row, and its own hash before the handler runs. The second write is a new row that records the final outcome and links to the first. The platform's integrity check can therefore detect a changed row, a row removed from the middle of a chain, or a row removed from the end of an anchored day. It still treats an unfinished request as evidence that the attempt began. It cannot detect a removal from a day that has no anchor.

[Figure] The first write lands before the handler runs. The second appends the outcome. A covered mutation produces two rows. Before the handler runs, a row records the attempt as pending. Then the handler runs, and a second row records success or failure. If the handler never finishes, the first row stays pending, and that stuck row is itself evidence of the attempt. Labels: Two writes bracket the handler; Entry opens; as pending; Write 1, before; The request runs; Handler; Outcome appends as; the outcome; Write 2, after; Handler never finishes; The entry stays pending: indexed,; so it can be found and investigated.

The first row records the attempt before the handler runs and the second appends the outcome, so a crash between them leaves a pending row as evidence.

## How the trail proves that its rows were not changed [#how-the-trail-proves-that-its-rows-were-not-changed]

Each organisation's rows form a SHA-256 chain in write order, and the rows of platform-wide operations form one more chain. A row hash covers the canonical row fields and the previous row hash, so changing a field breaks that row and removing a row from the middle of the chain breaks the link of the next row. The database sets the previous hash and the hash of every new row, and refuses a row that arrives with either already set. Concurrent requests take turns when they choose the previous hash, which keeps one chain ordered even when several operators act at once.

At 00:05 UTC a daily job writes each organisation's chain head for a closed day into the organisation's document anchor registry on its default network, labelled `operator-audit`, and stores the transaction hash in a table that only accepts new rows. An organisation with no default network, or no active anchor signer, is retried on the next run, and its days stay unanchored until then. The database also refuses `TRUNCATE` on the audit table and on the anchor table, and refuses an anchor for a UTC day that has not closed or that is not the last row hash of the day it names. It does not check the stored transaction hash, so an anchor row shows what the database held for that day and is not proof that the head was published on chain. The job anchors an organisation's earliest closed day without an anchor first and stops that organisation at the first day it cannot anchor. It anchors at most 31 days per organisation in one run, so the first run after the feature ships catches up over several days. The retention job runs after this anchor attempt and does not remove an organisation's row from an unanchored day.

The daily job also anchors the platform chain. No organisation owns it, so the job submits its closed-day head through the organisation that anchored first and still has a default network and an active anchor signer. It tries the next organisation when that one cannot sign, and the platform days stay unanchored until one can. The anchor row of a platform day carries no organisation.

An authorised organisation reader can verify a date range of up to 31 days through `GET /api/v2/reporting/trail/integrity` in the [Platform API reference](https://docs.settlemint.com/docs/api-reference/v2). The check walks the range in batches. An intact response includes the range's head hash. If a row's previous hash or canonical content differs, the response identifies the first broken row and includes the expected and stored hashes so an investigator can compare the database with an exported record or the on-chain anchor. The check also compares the chain head at the end of each anchored day in the range, and the last anchored day before it, with every anchor stored for that day. It reports the reason `anchor` when a head differs from its anchor, when two anchors of one day disagree, and when an anchored day has no rows left. `brokenAnchorId` holds the identifier of the anchor involved in an `anchor` break. When a head differs from its anchor, `firstBrokenRowId` is the row at the head. When the break is found in the anchors alone, because two anchors disagree or a day has no rows, `firstBrokenRowId` is empty, and `actualHash` is empty for a day without rows. A day with no rows left is a break unless it is older than the configured retention window, because retention removes those days. Under the default `indefinite` retention, every anchored day with no rows is a break. The check cannot tell the removal of a whole day older than the window from retention. It reads only the database and never the on-chain copy, and it cannot detect a change made by a database owner who disables the triggers and then rewrites the chain and its anchors together. The transaction submitted for each day's head is the evidence for that case, and an investigator compares it with the chain.

A platform administrator verifies the platform chain the same way through `GET /api/v2/reporting/trail/operator/integrity`, which takes the same date range and returns the same answer. That read is itself recorded on the platform chain.

An entry still pending well after its request should have finished is the signal that the completion write failed, not that nothing happened. The trail returns such an entry with the outcome `pending` and no completion.

The two kinds of covered requests fail differently on purpose when the opening write itself cannot land:

**Mutation**

Refused outright, before the handler ever runs, so no partial state exists on either side. An unrecorded state change is the exact gap the trail exists to close, so the platform blocks the attempt rather than let it happen invisibly. The refusal costs no availability the mutation had anyway: the trail lives in the same store the mutation was about to write to. The caller gets the platform's standard [`INTERNAL_SERVER_ERROR`](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference#unclassified-errors). Its reference entry says to retry once and contact support if it persists.



**Sensitive read**

Served anyway for most reads. The read changes nothing, so refusing it would trade real availability for a weaker claim. The platform logs the audit-write failure for operators to investigate.

Six routes declare that their entry is required, because they hand out a bulk export or a regulated record. When the platform cannot open the entry, it withholds the response and answers with the same error as a refused mutation. They are the audit trail export, the daily transactions report, the shareholder list registrar file, the shareholder list beneficial owners read, the assistant turns export and the trading venue report file read.

Blocking an unrecorded mutation is the rule for every route the request middleware covers. Authentication is the one exception. Signing in with a password or a passkey, signing out, signing up, requesting or completing a password reset, and changing a password all write to the same trail. So do creating, updating or deleting an API key, enabling or disabling an authenticator-app sign-in code, verifying that code or a backup code, and the lock of an account after repeated wrong passwords. Membership writes also get an entry: leaving an organisation, removing a member, sending or cancelling an invitation, changing an organisation's name or settings, deleting an account, and an operator unlocking a locked account. So does a platform administrator's user administration: setting a role, banning and unbanning, creating, updating and removing an account, setting a password, starting and stopping impersonation, and revoking sessions. A password sign-in refused while the lock holds is recorded as a failed sign-in with the code `PASSWORD_LOCKED`. The recorded authentication writes go through the authentication server's own lifecycle hooks rather than the middleware, because the request middleware does not cover the authentication server's routes, and a sign-in runs before a session exists for it to attach to. A short trail outage must not lock every operator out, so these writes fail open: the attempt still succeeds, and a missed write is logged rather than blocking it. The request waits at most two seconds for its entry. A slower write completes after the response. Some authentication events write no entry, among them a sign-in through an identity provider and a sign-in code sent by email or text message.

## One record, written by declaration [#one-record-written-by-declaration]

One internal record holds every recorded entry: the actor, the role they held at that moment, their tenant, the target, the route, the outcome, and the timing. Request middleware writes it, not the code that handles the request, so coverage follows each route's declared audit disposition rather than anyone's diligence.

Every HTTP API route declares that disposition: mutation, sensitive read, or none. A route with no explicit declaration defaults from its access declaration, so a state-changing route is covered from the moment it is written rather than when someone remembers to instrument it. A coverage guard rejects a write route that opts out without a written exemption.

The entry records the request's target and its JSON body. It stores the route and the resolved path it acted on, plus the query string with credential and personal-data parameters such as passwords, PIN codes, one-time codes, and recovery codes redacted, bounded to 1,024 bytes. Redaction is by parameter name, so an ordinary filter value such as an email can still appear in the query string. Keep personal data out of query parameters.

The platform names the target when it reads the trail, not when it writes the entry. Each entry returned by the trail carries `targetName`: the token's name, the member's name, the venue's name, the symbol of the token a sale sells, or the name of the venue an add-on access proposal changes. The name is resolved for the caller reading the trail, so a target that caller may not read, one that no longer exists, and a banned member all answer `null`, and the Console then shows the target's kind label instead. The recorded target stays as it was written, so a rename changes what a later read shows, not what the entry holds.

The entry stores the JSON body as sent, as the request's arguments. Keys that hold credentials, secrets, PIN codes, tokens, keys, or personal data such as a date of birth or an IBAN are replaced by `[REDACTED]`, and a body over 64 KiB is cut to its hash and a bounded diff. Names and email addresses in a body stay readable, so keep personal data out of free-text fields. Routes that carry sealed personal data store a marker instead of the body. A request that fails keeps its arguments. A consolidated transition entry also carries the requested destination state as its reason. A failed transition records the state it was asked to reach, not one it reached. The entry also holds no database link to the organisation, user, or participant it names, the compliance subject recorded for that request, so it outlives all of them.

The entry's participant field names the participant the request resolved to act as. The platform fills it when it records the outcome, from the participant selection the route resolved, so a write made under a delegated authority, the arrangement where one party acts for another, names the party as well as the operator. A request that resolved no participant leaves the field empty. A participant requested with the `X-Participant` header also appears in the target as `participant=<id>`. The target is recorded before that selection is checked, so read the participant field, not the target, for whom the actor acted for. When a platform administrator impersonates a user, the entry also records the administrator who started that session, and the trail shows them as the operator acting as the user.

## How you read the trail [#how-you-read-the-trail]

The shape of your question decides which read to use. For self-service, [the Console's audit trail page](https://docs.settlemint.com/docs/console/reporting/audit-trail) shows an organisation's own operations. It opens on the last 30 days, and the reader can choose another window and page through all of it. It is gated no tighter than the API behind it: the organisation's owner, a platform administrator, or a holder of the Permission manager, Auditor, Compliance manager or System manager system role may open it. An Auditor who cannot approve anything can still see what happened.

Each entry's time is the platform server's clock at the moment it handled the request, not a block time. On a network whose clock runs ahead of real time, an entry can read earlier than the chain activity it caused. On an idle network, it can read later than the newest block. Chain-dated figures follow the rule in [Ledger data](https://docs.settlemint.com/docs/concepts/records-and-evidence/ledger-data#which-clock-dates-an-indexed-figure).

The API answers three other shapes of question, detailed in full in [the API reference](https://docs.settlemint.com/docs/api-reference/v2). It covers a time window over your own tenant's trail, one entry by its id, and every entry that touched a given resource across every actor and route. That third shape is usually where an investigation starts, because the question is "what happened to this thing", not "what did this person do". A fourth shape, gated to platform administrators, spans every tenant plus the entries that belong to no tenant at all.

The window reads return 200 entries per call at most, newest first. The response's total count is the number of entries the whole window holds, and each window read gives a cursor for the next page, so a caller can walk to the oldest entry. The resource read has no cursor, so it returns the newest 200 matches, and a total above 200 shows that more exist. The lookup of one entry by its id finds the entry wherever it sits in the window. For a window too large to walk page by page, the [CSV export](https://docs.settlemint.com/docs/console/reporting/audit-trail#export-the-trail-as-csv) returns every entry of a window in one streamed file. The trail is also one of the platform's own report kinds. A [reporting obligation](https://docs.settlemint.com/docs/concepts/records-and-evidence/reporting-obligation) can carry it in its report set, and that export reads the same table without the row limit.

Two safety details matter for an integrator. Reading the trail is itself a sensitive read and gets its own entry, so the trail records its own readers. And a lookup of another tenant's entry returns not found rather than forbidden, because a forbidden response would confirm the identifier exists, which is itself a disclosure across tenants. A not-found on your own tenant's entry can also mean the window missed it, so narrow the window before assuming the id is wrong.

## What you can show a regulator [#what-you-can-show-a-regulator]

From the Console you can show a regulator your organisation's operations: the actor, their platform and organisation role at that moment, the route and the outcome. Each entry also records the participant the request acted as. For the time before your deployment began writing the trail, you can show nothing.

That limit follows from the write path already described. The evidence for who a delegated actor was acting for lives elsewhere: the ledger names the party's account as the sender of the transaction, and the organisation's system access manager names who could act for it at the time. [Delegated Authority](https://docs.settlemint.com/docs/concepts/compliance-and-identity/delegated-authority) covers both.

Do not tell a regulator that a database owner cannot change the store: the hash chain and its on-chain anchor are the evidence that exposes a change. Do not promise a fixed retention period across deployments either: the window is configured, while anchoring and the end-of-day audit reports decide when an expired row may be removed.

The Console gives an authorised reader the trail without an engineer. The screen opens on the last 30 days, and its Export downloads every entry of the window and filters the reader picks. A control that needs the trail filed on a schedule should get it from a reporting obligation's export, not from a single API page.

## Frequently asked questions [#frequently-asked-questions]

### Does an audit entry show what a request changed?

Where the route records it, yes. A route that records a change stores the old and new values on the entry, and the Console shows them as Before and After. Configuration changes are: a wallet checker, a custody provider configuration, an obligation, the statements policy, platform settings, the theme, holiday calendars, templates and profile sections, and the network gas payer. A platform administrator's user administration records old and new values the same way: the role, the ban, a created, updated or removed account, and the count of a user's active sessions on a revoke. An update to an API key's settings by its holder does too. During an impersonation the entry also names the administrator. A password an administrator sets is recorded only as replaced, and an impersonation names the user it started on. These entries belong to no organisation, so an organisation's Audit trail page does not list them. The same holds for every write that reaches all organisations: the indexing scope, networks and RPC pools, base calendars, the platform assistant switch, the global theme, an organisation's archive and restore, and an administrator's onboarding resets. A platform administrator reads them through the platform-wide query. The entry holds the old and new value of each field that changed, and the reason the operator gave on the forms that ask for one. A change that leaves the stored value as it was records nothing, and credentials and API keys are never recorded. [One record, written by declaration](#one-record-written-by-declaration) describes how the entry stores the request body.

On-chain access control and smart wallet writes record that view when the platform accepts the request. This covers role changes on the system, tokens, custody gateways and trading venues, add-on proposals, and smart wallet signers, thresholds and modules. The before value is the indexed state read just before the write, with the indexed block it reflects. The after value is the state the request asks for. A queued write records the same view as one that settles inside the request.

Compliance, token control and trust registry writes record it too. This covers compliance module installs, removals, scopes, transitions and parameters on a token and on the system, the compliance expression, holder locks, the supply cap, pause and unpause, metadata, collateral, price, yield schedules, trusted issuers and their claim topics, claim topics and topic schemes. A creation records an empty before value, and a removal records the old value and no after value.

Token feature and price feed writes record it as well, in raw units. This covers attaching, rotating, detaching and updating a feature, feature transitions, fee rate freezes, fee exemptions, distribution netting, hold reservers, supply delegates, authorised converters, conversion triggers, accrual exclusions, register line settings, fixed yield schedules, and price feed registration, replacement, removal, adapters, issuer-signed feeds and staleness windows, and the custody gateway token, profile and gateway settings. An update records only the fields the request sets, and a list change records the whole list before and after. A price feed write runs as a workflow, so the platform links its transaction when the workflow ends, whether it succeeded or failed. A failed feed write keeps its values and its linked transaction, and reads as reverted. A feed request repeated under the same idempotency key records no change. Mapping instruments to a price source records the requested instruments and the operation id with no transaction link, because the outcome per instrument is read from the operation. Revoke routes and treasury allowance approvals record no change.

Token sale, refund splitter, paymaster, external token and factory writes record it too. For a token sale this covers setting the terms, extending the sale, changing its status, the presale whitelist, the purchase increment, investor allocations, application mode, the greenshoe and lock-ups. A status change to Public sale, Paused or Ended records that status. An activation or a finalisation records the requested transition instead, because the contract decides which status the sale lands in. An extension records the new end time, and a whitelist change records each named investor as listed or not. An investor whose listing does not change is left out. Application mode, the greenshoe and lock-ups have no indexed state, so their before value is read from the sale's contract and carries no indexed block. A lock-up change records the categories with their unlock steps and the default steps, before and after. A sale role set records the role holders before and after through the token it belongs to. The refund splitter records its warning and critical thresholds, or its refund share. A paymaster signer key rotation records the signer address before and after, and never key material. Registering an external token records its address and type, promoting it records its type, origin and whether it is dismissed, and dismissing it records the dismissed flag. Creating token or add-on factories records an empty before value and the factories the request creates, and a request for factories that already exist records nothing.

Custody gateway, bank rail and organisation network writes record it as well. For a custody gateway this covers its profile, client wallet, approved sources and payouts, funding sources, auto-claim, default payout and pause, unpause and close, and the creation of a coin, profile or gateway. For a bank rail it covers the escrow, the activation of a token link, and a link's mint cap and credit threshold with the approval request they open or close. Adding a network to an organisation records an empty before value and the requested network, or the earlier status of a failed or pending network that is retried, and it has no transaction link because it starts a workflow instead of queueing one transaction.

Holder locks are read from the platform's index of lock events. If the index holds no lock for the holder, the before value reads `none indexed` with the indexed block, and `indexRebuilding: true` is added while the index is rebuilding. `none indexed` does not mean the holder had no lock: the chain's `HolderLockSet` events settle that, and the entry keeps the wording it was written with. `POST /system/compliance-modules` records before and after but has no transaction link, because it starts a workflow instead of queueing one transaction.

An accepted request is not an applied change. The entry links the transactions the request queued and shows one outcome: queued while any is open, confirmed when all completed, reverted when any did not take effect. A role grant whose transaction reverts reads as reverted, not as a success.

### Are denied and failed requests recorded?

Yes. The opening write lands before the handler runs, so an attempt is recorded whether it later succeeds, fails, or is refused, and the closing write stores the HTTP status the caller received. A denial or a rejected submission never reaches the chain at all, which is exactly why the off-chain trail records it. A caller with no session is recorded too, with the actor marked as anonymous.

### How do you tie an audit entry to logs and the transaction it produced? [#how-do-i-tie-an-audit-entry-to-logs-and-the-transaction-it-produced]

Through the request identifier. Every entry stores the id of the request that produced it, and the same identifier appears in the platform's structured logs and traces for that call. For a write that reached the chain, it is also the join key back to the resulting transaction, so one identifier connects the trail entry, the logs, and the on-chain effect.

### What happens to an entry when the account it names is deleted?

Nothing happens to it. The entry holds no database link to the account it names, so deleting the account does not cascade into the entry, and the evidence outlives the account.

## Related concepts [#related-concepts]

- [Delegated Authority](https://docs.settlemint.com/docs/concepts/compliance-and-identity/delegated-authority): The model for acting for another party. The trail records the participant each request acted as.
- [Participant](https://docs.settlemint.com/docs/concepts/compliance-and-identity/participant): The compliance subject a delegated actor steps into.
- [Role Grant](https://docs.settlemint.com/docs/concepts/compliance-and-identity/role-grant): The on-chain permission an audit entry's role-at-time field records. The trail observes its effect on a request. It does not itself grant or check one.
- [Reconciliation](https://docs.settlemint.com/docs/concepts/records-and-evidence/reconciliation): A related record for a different question, one names who acted, the other confirms whether ledgers agree.
- [Reporting Obligation](https://docs.settlemint.com/docs/concepts/records-and-evidence/reporting-obligation): The versioned filing and export mechanism that can carry the trail in its own report set when a window is too large for the capped read API.


# Booked movements

Source: https://docs.settlemint.com/docs/concepts/records-and-evidence/booked-movements
A token with booked movements moves units only when an administrator books a movement under a register reference, and refuses any other mint, burn or transfer.

Booked movements is a token feature for an instrument whose legal register lives outside the platform, with a transfer agent or a fund administrator. While the feature is attached, the token keeps an on-chain record of every movement of its units, called a line, and refuses any mint, burn, transfer, forced transfer or wallet recovery that is not the booking of a line. The register stays the book of record. Units move on chain only when an administrator, a holder of the token's Supply management role, books a movement and gives its register reference. The platform records the reference but does not check it against your register or for repeats, so uniqueness is yours to enforce.

[Reconciliation](https://docs.settlemint.com/docs/concepts/records-and-evidence/reconciliation) explains how you compare your register with the platform's ledger for an ordinary token. On a token with booked movements, each movement also carries the register reference it was booked under, so the comparison matches entry to entry when each register entry has its own reference.

## What a line records [#what-a-line-records]

A line is one movement between two parties. Its kind follows from the parties. A line with no giving party is a subscription and mints units. A line with no receiving party is a redemption and burns units. Any other line is a transfer. The API writes the missing party as the zero address, `0x0000000000000000000000000000000000000000`.

| Field | What it holds |
| --- | --- |
| From and to | The party that gives units and the party that receives them. |
| Amount | The units the line moves. A line of zero units is refused. |
| State | `requested`, `booked` or `cancelled`. |
| Opened by and at | The wallet that opened the line and when. |
| Decided by and at | The wallet that booked or cancelled the line and when. Empty while it is requested. |
| Register reference | The reference your register files the movement under. Empty until the line is booked. |
| Corrects | The booked line this line corrects, if any. |

A booked or cancelled line never changes again. To fix a booked line, an administrator books a new line whose `corrects` value names it, so the history keeps both the mistake and the correction. A correction does not undo the earlier line by itself: the administrator chooses its parties and amount. To fix a subscription of 1,000 units booked to the wrong holder, book a redemption of 1,000 units from that holder that corrects it, then book the subscription to the right holder.

## How units move [#how-units-move]

Units move only when a line is booked, whether a holder requested it or an administrator booked it directly.

**A holder requests a line.** For a transfer or a redemption the holder must be the giving party, and the platform holds the requested units on the holder's balance through the token's hold feature until the line is booked or cancelled. For a subscription the holder must be the receiving party, nothing is held, and each recipient has at most one subscription request open at a time. The token refuses a request whose kind the token does not allow, a transfer or redemption request from a wallet the identity registry marks as lost, and a transfer or redemption request on a token with no hold feature.

**An administrator books a line directly.** A holder of the Supply management role on the token opens and books a line in one call, for a subscription, a transfer, a redemption or a correction of an earlier booked line. A correction must name a line that is booked.

Booking a requested line releases the held units first, then records the register reference and moves the units in the same transaction. Only a holder of the Supply management role books, and a booking without a register reference is refused. The move still passes the token's own checks: the receiving wallet must be registered in the identity registry, and any compliance modules the token carries still apply. When any check refuses it, the whole transaction reverts: the line stays requested and its units stay held.

A requested line can also end without moving units. The administrator cancels it as a refusal, or the holder who opened it cancels it as a withdrawal, and the line records who cancelled it. Anyone else is refused. Cancelling releases the held units. On chain, the opener or an administrator can still cancel after the feature is detached, so held units are not stranded. The Platform API acts only on an attached feature.

## What the token refuses [#what-the-token-refuses]

Every movement that is not a booking reverts with "This token only moves through a movement the administrator books." That covers a plain mint, burn and transfer, a forced transfer by the custodian, and a wallet recovery: each of those needs a line too. The refusal holds only while the feature is attached. A holder of the token's Governance role can detach it, and the token then moves units without a line among wallets registered in its identity registry until the feature is attached again.

The feature needs the hold feature on the same token, and it cannot sit beside the management fee, conversion, conversion minter, supply delegate or maturity redemption features, because each of those moves units outside a line. A template or an attach that combines them is refused.

A booking reaches the token as a booked movement, which tells the token's other features that the amount is already on a ledger. A second-generation fee feature does not split it, a second-generation fee ledger does not count it, and an external transaction fee is not charged on it. [Token features](https://docs.settlemint.com/docs/concepts/modeling-assets/token-features) describes both generations of each fee feature.

## Which moves holders may request [#which-moves-holders-may-request]

A token keeps a set of line kinds open to holder requests: subscription, transfer, redemption or any mix. When the issuance names none, holders may request all three. A holder of the Governance role changes the set. Lines already requested stay open when their kind is switched off, and an administrator can always book any kind directly.

The Share-Class Mirror template issues a token with the historical balances, hold and booked movements features attached and no compliance template, because the register decides who may hold the share class. With no compliance template, a detach leaves the identity registry as the only check on who receives units. The token starts paused. The issuance can ask for it to be unpaused on creation, and an unpaused token is ready for its first booking. Its holders may request all three kinds until governance narrows the set.

## Work with lines in the Console [#work-with-lines-in-the-console]

The [Booked movements workflow](https://docs.settlemint.com/docs/console/asset-management/manage/booked-movements) walks through the Console: booking or rejecting a requested movement, booking one directly, correcting a booked movement, and choosing what investors can request. In the Investor portal, a holder requests a movement, withdraws an open request, and sees their own movements and the amount still available to request.

## Read and write lines through the Platform API [#read-and-write-lines-through-the-platform-api]

Six routes under `/api/v2/tokens/{assetId}/features/register-lines` list and read lines, request a line, book a line, cancel a line and set the requestable kinds. The [Platform API reference](https://docs.settlemint.com/docs/api-reference/v2) carries their shapes. A line read returns the indexed record and does not read the chain:

```json
{
  "data": {
    "lineId": "7",
    "tokenAddress": "0x71C7656EC7ab88b098defB751B7401B5f6d8976F",
    "featureAddress": "0x3C44CdDdB6a900fa2b585dd299e03d12FA4293BC",
    "kind": "subscription",
    "state": "requested",
    "from": "0x0000000000000000000000000000000000000000",
    "to": "0x2546BcD3c84621e976D8185a91A922aE77ECEc30",
    "amount": "1000000000000000000",
    "registerReference": null,
    "corrects": null,
    "openedBy": "0x2546BcD3c84621e976D8185a91A922aE77ECEc30",
    "decidedBy": null,
    "openedAt": "2026-01-15T10:00:00.000Z",
    "openedTxHash": "0xabababababababababababababababababababababababababababababababab",
    "decidedAt": null,
    "decidedTxHash": null
  },
  "links": {
    "self": "/api/v2/tokens/0x71C7656EC7ab88b098defB751B7401B5f6d8976F/features/register-lines/lines/7"
  }
}
```

A caller with the Supply management or Governance role on the token lists and reads every line. Any other caller lists and reads only the lines where one of their wallets gives, receives or opened the line, and gets not-found for the rest.

The ordinary token writes keep working on such a token and become lines. A mint books a subscription, a burn books a redemption and a forced transfer books a transfer, each with the Supply management role. These calls take a `registerReference`, which is required on this token, and an optional `corrects` line. A call without a reference, or a call that names more than one movement, is refused with "A token with booked movements needs a register reference and one movement per call". A burn or forced transfer is also refused before anything is sent when the holder's unfrozen balance, less what holds reserve, cannot cover it. A transfer call from a holder opens a transfer request from the calling wallet to the recipient, which the administrator books or rejects as any other request. On a token without the feature, a call that includes `registerReference` or `corrects` is refused.

Each webhook event for a booked movement includes `registerLine` with `lineId`, `registerReference` and, for a correction, `correctsLineId`. When each register entry has its own reference, a reconciliation job can match the movement to its register entry from the event alone.

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

- After you book a line, reading it back through the line route shows `booked`.
- The line carries the register reference you gave and names the wallet that booked it in `decidedBy`.
- The holder's balance has moved by the line's amount.
- The webhook event for the movement carries the same register reference under `registerLine`.

## Related pages [#related-pages]

Read the [Booked movements workflow](https://docs.settlemint.com/docs/console/asset-management/manage/booked-movements) to book movements in the Console, [Reconciliation](https://docs.settlemint.com/docs/concepts/records-and-evidence/reconciliation) to compare your register with the platform's ledger, [Token features](https://docs.settlemint.com/docs/concepts/modeling-assets/token-features) for the features a token can carry, and [Audit trail](https://docs.settlemint.com/docs/concepts/records-and-evidence/audit-trail) to find who changed a token's register line settings.


# FSRA venue reports

Source: https://docs.settlemint.com/docs/concepts/records-and-evidence/fsra-venue-reports
Which venue report columns hold the MIR 3.6.7 post-trade details, and the provisional FSMR s.149 files an ADGM venue sends the FSRA.

A multilateral trading facility (MTF) in the Abu Dhabi Global Market (ADGM) answers to the Financial Services Regulatory Authority (FSRA) under two sets of rules. The Market Infrastructure Rules (MIR) 3.6.7 name the details of each trade that the venue makes public and gives to the regulator. Section 149 of the Financial Services and Markets Regulations (FSMR) obliges the venue to report its orders and transactions to the FSRA. The venue matched trades report has a column for every MIR 3.6.7 detail. Two draft [reporting obligations](https://docs.settlemint.com/docs/concepts/records-and-evidence/reporting-obligation) generate the s.149 files in a provisional layout, because the FSRA has published no specification for them. The platform generates the files. The MTF operator uploads each one to the FSRA, records the FSRA's acknowledgement on the filing, and stays responsible for meeting both rules.

Note (The s.149 layout is provisional): The FSRA publishes the s.149 duty but no rules on what a report holds or how it is filed: FSMR s.149(5) lets the FSRA make such rules, and none are in the current rulebooks. The s.149 layout below is provisional, modelled on MiFIR RTS 22 and RTS 24 until the FSRA specification is confirmed. RTS 22 is the European transaction reporting standard and RTS 24 the European standard for the order records a venue keeps. The field list, the cadence and the deadline are all settings on the obligation, so a confirmed specification that fits those settings replaces them with a new obligation version.

## Post-trade fields under MIR 3.6.7 [#post-trade-fields-under-mir-367]

The venue matched trades report holds one row for each trade matched on the reference day, including a trade later undone at delivery. MIR 3.6.7 names seven details, and MIR 3.6.2 adds three indications. Each one has a column in the report.

| Rule | Detail | Column | What the column holds |
| --- | --- | --- | --- |
| MIR 3.6.7(a) | Trading day | `tradingDay` | The date of the venue session the trade was executed in. A trade outside any session is dated in the instrument's time zone, then the venue's, then UTC. |
| MIR 3.6.7(b) | Trading time | `executedAt` | The execution time in UTC, to the millisecond. |
| MIR 3.6.7(c) | Instrument identification, provisional | `instrumentId` | The instrument's ISIN when its token metadata holds a valid one under the key `isin`. Otherwise the venue's own instrument ID. |
|  |  | `instrumentIdType` | `ISIN` or `VENUE`, naming which of the two `instrumentId` holds. |
| MIR 3.6.7(d) | Unit price | `unitPrice` | The price of one whole unit of the instrument in whole units of the quote asset, without fees, exact to 18 decimal places. It is empty while the platform does not know the decimals of either token. |
| MIR 3.6.7(e) | Price notation | `priceCurrency` | The currency the quote asset is priced in, as an ISO 4217 code. When the quote asset has no price currency, the column holds its symbol. |
| MIR 3.6.7(f) | Quantity | `unitQuantity` | The number of whole units traded. It is empty while the instrument's decimals are unknown. |
| MIR 3.6.7(g) | Venue identification | `venue` | The venue's identifier on the platform, or its contract address when the venue has no configuration record. |
| MIR 3.6.2(b) | Price set by factors other than the market | `nonMarketValuationFlag` | Always `false`. The venue matches orders only on its order book, so it has no portfolio trades and no volume-weighted average price trades. Review the flag if the venue adds a trading facility. |
| MIR 3.6.2(c) | Negotiated trade | `negotiatedTradeFlag` | Always `false`. The venue has no facility for negotiated trades. |
| MIR 3.6.2(d) | Amendment of a disclosed trade | `recordStatus` | `NEWT` for a trade, `CANC` for a trade undone at delivery, which cancels the record published for it. |

The columns `priceTick` and `quantity` hold the venue's own integer price step and base-unit quantity.

Note (The instrument identifier is provisional): MIR 3.6.7(c) asks for "a unique code to be decided by the Regulator". The FSRA has not named that code, so the ISIN, with the venue's own instrument ID as a fallback, is a provisional choice. `instrumentIdType` tells a reader which scheme each row uses.

The venue orders report carries the same instrument and price columns for each order: `instrumentId`, `instrumentIdType`, `unitPrice` (the limit price, empty for a market order), `priceCurrency`, `unitQuantity`, `filledUnitQuantity`, `remainingUnitQuantity` and `venue`.

## The FSMR s.149 order and transaction reports [#the-fsmr-s149-order-and-transaction-reports]

The platform catalogue holds two draft obligations under the regime "FSRA order and transaction reporting (FSMR s.149)". Each organisation receives its own draft copy of both, as it does for every catalogue entry. Review the copy, set the values that name your venue, and publish it from [Obligations](https://docs.settlemint.com/docs/console/reporting/obligations).

| Obligation | Report it reads | Authority file | Modelled on |
| --- | --- | --- | --- |
| FSRA s.149 transaction report (provisional) | Venue matched trades | `fsra-s149-transactions.csv` | MiFIR RTS 22 transaction reports |
| FSRA s.149 order report (provisional) | Venue orders | `fsra-s149-orders.csv` | MiFIR RTS 24 order records |

Both share one schedule and one completion rule:

- **Cadence.** Daily. The platform generates the filing once the reference day closes on the obligation's calendar, and lists rows only when a venue session closed that day.
- **Deadline.** The draft sets one business day on the ADGM calendar after the reference day, by 23:59 Asia/Dubai. This is a setting on the obligation, not an FSRA rule.
- **Ending.** The filing ends when a user records the FSRA's acknowledgement on it. A filing with no acknowledgement recorded within 24 hours of its recorded submission turns unacknowledged.
- **Empty days.** A day without a closed session still produces a filing, with no data rows. The obligation accepts it as a nil return.
- **File.** UTF-8 CSV with a header row, separated by commas, with no byte order mark and LF line endings.
- **Filer.** The "Reporting entity LEI" on the obligation, and the `SubmittingEntityId` column, hold the MTF operator's LEI.

Note (Fill in your identifiers): The catalogue leaves the "Reporting entity LEI" empty and puts placeholders in the authority file columns: `REPLACE-WITH-OPERATOR-LEI` in `SubmittingEntityId`, and `REPLACE-WITH-VENUE-MIC` in `Venue` and `TradingVenue`. A copy published unchanged files reports with those placeholders and no reporting entity LEI. Before you publish, enter the MTF operator's LEI in the "Reporting entity LEI" and in `SubmittingEntityId`, and your venue's MIC in `Venue` and `TradingVenue`.

### Transaction report columns [#transaction-report-columns]

One row per matched trade of the reference day.

| Column | Value |
| --- | --- |
| `ReportStatus` | `NEWT`, or `CANC` for a trade undone at delivery |
| `TransactionReferenceNumber` | The trade ID |
| `TradingVenueTransactionId` | The trade ID |
| `SubmittingEntityId` | The MTF operator's LEI, fixed text |
| `BuyerId` | The buyer's account on the venue |
| `BuyOrderId` | The buy order ID |
| `SellerId` | The seller's account on the venue |
| `SellOrderId` | The sell order ID |
| `TradingDateTime` | The execution time in UTC, such as `2026-04-01T11:00:00.000+00:00` |
| `TradingDay` | The trading day |
| `Quantity` | The number of whole units traded |
| `Price` | The unit price |
| `PriceCurrency` | The price currency, upper case |
| `Venue` | The venue's MIC, fixed text |
| `InstrumentId` | The ISIN, or the venue's instrument ID |
| `InstrumentIdType` | `ISIN` or `VENUE` |

### Order report columns [#order-report-columns]

One row per order placed on the reference day, with its state at the end of that day. The report does not list each event in an order's life, as an RTS 24 record would.

| Column | Value |
| --- | --- |
| `SubmittingEntityId` | The MTF operator's LEI, fixed text |
| `TradingVenue` | The venue's MIC, fixed text |
| `OrderId` | The order ID |
| `MemberId` | The account that placed the order |
| `InstrumentId` | The ISIN, or the venue's instrument ID |
| `InstrumentIdType` | `ISIN` or `VENUE` |
| `BuySellIndicator` | `BUY` or `SELL` |
| `OrderType` | `LIMIT` or `MARKET` |
| `ValidityPeriod` | `GTC`, `GTD`, `DAY`, `IOC` or `FOK` |
| `LimitPrice` | The limit price per whole unit, empty for a market order |
| `PriceCurrency` | The price currency, upper case |
| `InitialQuantity` | The number of whole units ordered |
| `FilledQuantity` | The number of whole units filled |
| `RemainingQuantity` | The number of whole units not filled |
| `OrderStatus` | The order's status at the end of the day, upper case |
| `EventReason` | Why the order closed, when it closed |
| `OrderSubmittedAt` | When the order was placed, in UTC |
| `LastEventAt` | When the order last changed, in UTC |

### What the provisional layout leaves out [#what-the-provisional-layout-leaves-out]

RTS 22 and RTS 24 ask for fields the venue does not hold, and the provisional layout leaves them out: the buyer's and seller's LEI or national identifier, the decision maker, the trading capacity, short-selling and waiver indicators, and the client identification codes. The buyer, seller and member columns hold the participant's account on the venue instead.

## Replace the provisional layout [#replace-the-provisional-layout]

When the FSRA confirms its specification, edit your copy of each obligation and publish the result as a new version. Filings already made keep the version they were made under.

1. Change the columns, the file name and the CSV settings under "Custom file layout" in the [obligation editor](https://docs.settlemint.com/docs/console/reporting/obligations#edit-the-draft), or send the whole layout through `PUT /api/v2/reporting/obligations/{obligationId}` in the [Platform API](https://docs.settlemint.com/docs/api-reference/v2).
2. Change the cadence and the deadline in the same draft.
3. Publish the draft.

## Rule references [#rule-references]

- MIR 3.6.1 and 3.6.2, post-trade transparency, and MIR 3.6.7, the post-trade information table. COBS 8.2.1 applies them to an MTF operator.
- FSMR s.149(1) and (2), the duty to report orders and transactions, and s.149(5), the FSRA's power to make rules on content and manner.
- MiFIR RTS 22 (Commission Delegated Regulation (EU) 2017/590) and RTS 24 (Commission Delegated Regulation (EU) 2017/580), the models for the provisional layout.

## Related concepts [#related-concepts]

- [Reporting Obligation](https://docs.settlemint.com/docs/concepts/records-and-evidence/reporting-obligation): how a published version freezes the layout, cadence and deadline of a filing.
- [Trade reports](https://docs.settlemint.com/docs/concepts/records-and-evidence/trade-reports): the per-trade reports a venue sends over a FIX session.


# Ledger Data

Source: https://docs.settlemint.com/docs/concepts/records-and-evidence/ledger-data
Ledger Data lets an integration answer a holder list, a transfer history, or a compliance check with one query, instead of decoding chain events itself.



[Figure] Reads answer from the record, up to a stated point. The ledger network is the authority for what happened. The platform reads each block once, in order, and decodes the events inside it into business records: holdings, transfers, fees, and compliance state. Those records and that block's progress point commit together in one step, or neither commits, so the progress point never runs ahead of the committed records. The committed progress point states how far the record can be trusted, and every platform read answers from at or below that point rather than from the live network. Labels: The network, the authority for what happened; block 41; block 42; block 43; still arriving; read once, in order; Decode each event into a business record; holdings, transfers, fees, compliance state; One commit, or neither; The decoded records; what the block contained; The progress point; how far the record is trusted; Every platform read answers from here; at or below the progress point, never from the live network.

Records and the progress point commit together, and every read answers at or below that point.

The record holds business data, not raw chain data: who holds what, every transfer, every fee, already decoded, so a holder list or a year of transfers costs one database query rather than a walk of the chain.

The index carries a progress point for each network, the last block it has fully recorded, and answers nothing past it. A batch's records and its progress point commit in one database transaction, so a read answers from committed batches only.

When a network replaces recent blocks, the index deletes the records above the fork and replays the canonical chain, so the same blocks produce the same figures under the same recording rules.

## Why an indexed record matters [#why-an-indexed-record-matters]

Ledger Data lets you answer a business question about a ledger network with one query, instead of decoding its blocks and events yourself. It keeps a record of every network the platform follows, current as blocks arrive, organised into holdings, transfers, and the other records a network node's raw events do not carry on their own.

You can ask who held a security on 31 March, every transfer for one holder across a tax year, or whether an address was on the investor register when a transfer settled. Answering these from raw chain events needs event decoding and historical reconstruction. Ledger Data does that work for the contract types the platform knows.

Every stage of an instrument's life, from a primary sale through a coupon payment to a delivered trade, reads this one record, so no stage keeps its own decoder that the others must trust. [Asset Lifecycle](https://docs.settlemint.com/docs/concepts/issuing-and-markets/asset-lifecycle) describes those stages.

Ledger Data also removes the risk of a wrong number returned with confidence. A balance that omits a transfer restored after a chain reorganisation, or a fee total that counts a corrected block twice, becomes a finding the moment someone compares it against the chain. Ledger Data corrects by deletion and replay rather than by editing a figure in place, so, once any rebuild has finished, the same query over the same blocks returns the same answer. A historical balance can therefore be re-queried and checked against the chain. The [historical balances](https://docs.settlemint.com/docs/concepts/modeling-assets/token-features/balances-and-holds#historical-balances) token feature is the on-chain counterpart: it checkpoints balances and total supply so that a record date can be answered on chain too.

## Watching the index day to day [#watching-the-index-day-to-day]

You watch Ledger Data. You do not operate it. It follows every network the deployment has enabled, and the number that matters is how far its progress point sits behind that network's newest block. Everything else on the monitoring surface explains why the gap is what it is.

The index normally follows the network head. It can also catch up, backfill a contract's earlier history, roll back a replaced block, or rebuild after a change to its records.

[Figure] The index is always in one of five conditions. Following the network head is the steady state, with the progress point at the newest block. Four excursions leave it, each for a stated reason, and each returns when its work completes: catching up enters after a restart or when the network ran ahead and returns when the progress point reaches the head. Backfilling enters when a new contract owes its history and returns when that earlier history is complete. Rolling back enters when the network replaced a block and returns when the rollback and replay complete. Rebuilding enters when a release changed event recording and returns when the rebuilt copy swaps in. Labels: Following the network head; The steady state; progress point at the network head; leaves for one of four reasons,; returns when that work completes; Catching up; enters: restarted or the network ran ahead; returns: progress point reaches the head; Backfilling; enters: a new contract owes its history; returns: its earlier history is complete; Rolling back; enters: the network replaced a block; returns: rollback and replay complete; Rebuilding; enters: a release changed event recording; returns: the rebuilt copy swaps in.

The index either follows the head or is out on one of four excursions, and each excursion returns to following when its work completes.

The monitoring surface reports block lag, block age, how far the network sits ahead of its own settled point, whether the first full pass over history has finished, how much contract backfill remains, and whether a rebuild is running. Lag and staleness each move the verdict through the same two severities, degraded then critical, and a verdict changes only after several consecutive samples agree, so one slow block never flaps the board. The [ledger indexing stalled runbook](https://docs.settlemint.com/docs/deployment/runbooks/ledger-indexing-stalled) states the exact thresholds and the checks that tell ordinary catch-up from a chain whose ingest has failed.

You also decide, for each system the platform has discovered, whether platform reads expose its data. The index keeps indexing every discovered system either way. Excluding a system hides its data, and the data of everything it deployed, from those reads and deletes nothing. Re-including it needs no backfill, because the data is already current. [Indexing scope](https://docs.settlemint.com/docs/console/platform-admin/indexing-scope) is where a platform administrator makes that choice, system by system, network by network.

A rebuild is the expensive case. A release that changes how the index records an event declares its own rebuild, and it reprocesses a network's full history under the new rules before a replacement copy takes over. The rebuild runs behind an already-serving deployment rather than gating it: existing reads keep answering from the current copy until the replacement has caught up, and only then do the two swap in a single step. Historical figures for the period a rebuild is still redoing read as provisional until it finishes, so check whether one is running before treating an old figure as final. The [upgrades and migrations guide](https://docs.settlemint.com/docs/deployment/upgrades-migrations) covers what a release requires and how to confirm a rebuild has finished, since a release reporting complete does not mean the rebuild has.

## How the record stays correct [#how-the-record-stays-correct]

Ledger Data is a derived cache: the platform rebuilds it from the ledger network's own blocks, and nothing in it flows back to the network. Indexed API reads use its progress and consistency rules. Operations that require a live network value use separate network reads.

Exactly one process holds the write lease for a network at a time, and each handover raises an ownership number that stamps every progress write. When a superseded owner finishes work late, the platform rejects its whole batch rather than letting it move progress after the handover.

The index reads a network in batches: a contiguous run of blocks from the next unread block up to the network head, capped at a configured width that halves after repeated fetch failures and doubles again after three clean commits. A batch's decoded records, its progress point, the block hashes it keeps for reorganisation checks, and the change events its blocks produce all commit in one database transaction, or none of them do. The index tracks progress on two axes: how far it has read blocks in an unbroken run, and how far back it has filled in the history of every contract it discovered along the way. Reads use the second, stricter axis, because the index can read a block while a contract it found inside that block still owes its earlier history. That is what keeps a half-filled contract out of your results: rather than serving partial history for it, the index holds the answer back until the gap is closed.

[Figure] Reads follow the stricter of two progress axes. The index tracks progress on two axes. One axis is how far it has read blocks in an unbroken run. The other is how far back it has filled in the history of every contract it discovered along the way, and a contract found in a recent block can still owe its earlier history, leaving a gap. Reads answer at or below the stricter of the two, so a half-filled contract never appears in a result. Labels: Blocks read in an unbroken run; Two axes of progress; blocks read; still arriving; Every discovered contract's history filled in; a contract found in a recent block still owes its earlier history; history filled in; owed history; Reads answer at or below here; The stricter axis wins.

Block reading can outrun contract backfill, leaving a gap, so reads answer from the stricter axis and a half-filled contract never appears in a result.

The index follows a network's newest block rather than waiting for that network to declare a block settled, so a record appears within processing time of its block. A network declares a block settled through its own finality signal where it publishes one, and otherwise after a number of confirmations the deployment configures for it. The cost of following the newest block is that a network can still replace a recent one, and the design answers that directly. The index keeps a hash for every block inside a retained window, configured per network. With no window configured, the window is the larger of the network's finality distance and 64 blocks: 65 blocks on Ethereum, 200 on Polygon, 240 on Arbitrum, and 64 on Base, Optimism and any other network. A deeper window also delays any webhook event that waits for finality. The configured window limits retained hashes, and the network's finality signal is a separate cutoff. Detection walks stored hashes and nothing else, so a rollback cannot reach past the oldest hash the index still keeps: the window is the bound on how far back a rollback can go, not a convention. Set it below the network's actual worst-case reorganisation depth and the index cannot repair a replacement past that point, so that network stops at its last indexed block, with the records of the replaced blocks still in place, until an operator recovers it. Set it deeper than the network's own finality distance and the extra depth is pruned once its blocks are finalised, so it costs storage and comparison work for a bound the network already retired. Review the configured depth against the network's finality model and your operational requirements. A configured depth is not proof of the maximum possible reorganisation.

Detection walks back from the last processed block, comparing stored hashes against the network's current ones. Height alone would miss the case that matters: a replacement block can sit at the same height as the one the index already processed, so nothing appears to have moved and only the hash reveals the change. On a detected fork the index deletes every record above the fork point, rewinds its progress point, and retracts the change events it already delivered, all in one transaction. It then replays the canonical blocks. When no stored hash matches anywhere in the window, the index does not roll back. It stops indexing that network, logs the failure, and leaves that network's records at the last indexed block while the other networks keep running. [Beyond the window](https://docs.settlemint.com/docs/deployment/networks#beyond-the-window) says how an operator recovers.

[Figure] A replaced block is rolled back in one transaction and replayed. A block arrives whose hash disagrees with the one the index stored at that height. A replacement can sit at the same height, so only the hash reveals it. The index walks back comparing stored hashes against the network's, newest first, to the fork point, the newest block both still agree on. In one database transaction, or nothing, it deletes every record above the fork, rewinds the progress point, and retracts the change events it had already delivered. It then replays the canonical blocks from the fork forward, and the same blocks produce the same records a first pass would have. Labels: A block arrives whose hash disagrees with the stored one; a replacement can sit at the same height, so only the hash reveals it; Walk back to the fork point; compare stored hashes, newest first. The fork is the newest block both still agree on; One transaction, or nothing; delete every record above the fork; rewind the progress point; retract delivered change events; Replay the canonical blocks from the fork forward; same blocks in, same records out: the query answers as it would on a first pass.

Detection compares hashes rather than heights, the rollback is one transaction, and the replay produces the same records a first pass would have.

Running totals are the one place the index waits. They are figures the index folds forward as it processes events instead of recomputing per query. It folds a total forward only to whichever comes first, its own progress point or the newest block the network has declared settled, so it never has to un-fold a total. Point-in-time reads carry no such delay, because the index recomputes them from records a rollback can remove.

## The integration contract [#the-integration-contract]

An integration reads chain state from Ledger Data, not from the network. The platform's application programming interface (API) answers holdings, transfer history, balances at a past block, and compliance state out of the index. A live call to the network is the exception, kept for infrastructure checks and for the few values the index does not hold.

|  | Indexed read | Live network read |
| --- | --- | --- |
| Answers | What happened, at any past block. | What holds true right now. |
| Cost | One database query. | One or more network calls. |
| Freshness | Current to the progress point. | Current to the newest block, replaceable. |
| Used for | Holdings, transfers, fees, yield, redemptions, compliance. | Infrastructure checks and values the index lacks. |

On-chain confirmation and indexed visibility are separate outcomes. A queued write that uses the indexer barrier waits until its block is available for indexed reads. If that wait expires, a [retryable error](https://docs.settlemint.com/docs/api-reference/guides/errors) identifies the transaction and states that it succeeded on-chain while indexed data is not ready. Check that transaction's outcome before resubmitting anything.

Read the operation's Settlement Verdict for its recorded end state: completed, failed or set aside. Then check the resource or the indexing progress your integration needs.

Coverage is explicit, and discovery and registration answer different questions. For the contract types the platform knows, discovery is automatic: the platform finds each new contract through its own on-chain registries and fills in that contract's history from its deployment block, and holds the contract's results back until that backfill completes. A contract of a type the platform does not know, an externally issued token for example, stays invisible until someone registers it, and a query against it returns an empty result rather than an error. A balance at a past block is a direct lookup rather than a replay. The index also records derived figures, such as what a position was worth on a given day, as it processes the event that causes them. A history request therefore costs what its date range holds, not everything the deployment has ever seen.

The platform can also push committed changes to your endpoints through Webhook Delivery, the transport that delivers each committed change to your endpoint. It writes those events in the same database transaction as the indexed rows they describe, so every event you receive described a movement the index held when it committed. When a reorganisation removes the source block, the platform sends a follow-up Platform Event, the typed record for a pushed change that your handler matches against, marked as a retraction. That event names the earlier event it supersedes, so your handler can match the two. Keep your ingestion idempotent and reconcile against the indexed record after a rollback. What you do about work you already did on the retracted event is your own business rule, not something the platform decides for you. [Post DALP events to a ledger](https://docs.settlemint.com/docs/api-reference/guides/accounting-feed) covers how the platform posts an organisation's money events to its Xero ledger, including the reversal it posts for a retracted event, and what a subscriber that feeds another ledger does.

## What it evidences, and what it does not [#what-it-evidences-and-what-it-does-not]

Ledger Data is the evidence layer. Enforcement happens on chain, inside the transfer itself, under [Transfer-Path Compliance](https://docs.settlemint.com/docs/concepts/compliance-and-identity/transfer-path-compliance). The index records what the chain did, in a form you can query, export, and defend.

It produces the register at any past block, so a quarter-end holder list is a lookup rather than a reconstruction. Per holder it produces every transfer with its counterparty. Per period it produces fees collected and exemptions applied, yield accrued and paid, and redemptions. Each event it stores names the transaction sender, the contract that emitted the event, and the addresses involved. It keeps each address twice, as the raw address and as the identity the platform resolved it to, so a query by participant returns their activity whether you filter by a wallet or by the party behind it.

Two properties make the record defensible: repeatability and provenance. The same query over the same blocks returns the same figure. A correction is a deletion and a replay that the network's own canonical chain drives, not an operator editing a number, and every figure holds a progress point stating which blocks it covers.

Ledger Data does not change what a network treats as final, and three limits belong in any control narrative. Coverage stops at the contract types the platform knows, so anything outside that set needs registering before it appears. The index observes ledger networks only, and holds nothing about a custody provider's own books, an external bridge, or an off-chain reserve. History exists for the period the platform has processed under the current recording rules, so a release that changes how the index records a derived figure leaves earlier periods incomplete until its rebuild finishes. Reads stay live while that rebuild runs, so those earlier periods answer incompletely rather than returning an error or nothing at all. During that window a chart calculated backwards from a current total still draws a line, so a populated chart is no evidence that the rebuild has run. Check the monitoring surface instead: it shows whether a rebuild is running, and an active rebuild shows at once.

## Frequently asked questions [#frequently-asked-questions]

### Is the index the source of truth?

No. The ledger network is the source of truth. The index is derived from it and can be rebuilt from its blocks. On-chain contracts enforce their rules during execution. API prechecks, reads, and reports can also depend on indexed state.

### What happens to a figure I already read if the chain reorganises?

The index corrects the figure at its source, and your next read returns the corrected value. It deletes the records above the fork point, rewinds its progress point, replays the canonical blocks, and retracts any change event it already delivered from a removed block. Reconcile your own systems against the indexed record after a rollback, not against what you captured before it. A reorganisation corrects the record of chain activity. It does not rewrite your operation's recorded verdict.

### How far behind the network is the index?

A record normally appears within seconds of its block. The index follows a network's newest block instead of waiting for that network to declare a block settled, so it does not wait for settlement. The trade is that the index can still correct a record inside the reorganisation window, which is what the rollback and replay path exists for. Running totals are the exception, and they fold forward only to the newest settled block.

### Which clock dates an indexed figure?

The chain's clock, as far as the index has read it. When a read decides a date-bound fact, it compares the chain's dates with the time of the newest block the index has committed. Such facts include whether an interest accrual period has closed, whether a hold, a lock-up, a time-locked batch or an identity claim has expired, how far a bond is towards maturity, and which yield or fixed-yield schedule period is running. A network whose clock runs ahead of real time, or one that has produced no block for a while, therefore gets the same answer the chain would give at that block.

Until the index has dated a block on a network, there is no chain time to compare with, and the answer depends on the figure. Interest, dividend and yield figures, fixed-yield schedule periods and identity-claim checks answer that they are temporarily unavailable rather than guessing. Holds, lock-ups and time-locked batches count as still in force, and a bond shows no progress towards maturity.

There is one exception. On a token's features, the periods of a fixed-yield feature close at the time the next block will carry. "Ready to claim" is worked out at that time, because a claim lands in the next block, so the next coupon and the claimable amount always agree.

Records the platform writes itself, such as audit trail entries and webhook attempts, carry the server's clock instead, because they record when the platform acted, not when the chain did. Chart windows such as "last 30 days" also follow the server's calendar.

### Do I need my own reconciliation between the index and the chain?

Reconcile the platform's records with your own books and retain transaction references for independent checks against the canonical ledger. The index handles supported event decoding and rollback, but it does not replace your reconciliation policy.

### Do reads fail when a network endpoint goes down?

No. Indexed reads answer from records the index has already committed, not from the live network, so they keep working through an endpoint outage. What stops is progress: the progress point holds still and block lag grows, which is exactly what turns the chain degraded and then critical on the monitoring surface above. Once the endpoint recovers, the index catches up and new records appear.

### Does the platform index every contract on the chain?

No. The index follows the contract types the platform already knows, within the on-chain estates operators chose to follow. That scope keeps unrelated activity out of your read models and keeps the cost of the index proportional to what you run.

## Related concepts [#related-concepts]

- [Asset Lifecycle](https://docs.settlemint.com/docs/concepts/issuing-and-markets/asset-lifecycle): The whole working life of a regulated tokenised instrument, from issuance through servicing to redemption. Every stage reads from the one record Ledger Data keeps.
- [Market Data](https://docs.settlemint.com/docs/concepts/records-and-evidence/market-data): The governed on-chain source for prices, valuations, and exchange rates, where each subject and topic resolves to one active, replaceable feed.
- [Audit Trail](https://docs.settlemint.com/docs/concepts/records-and-evidence/audit-trail): The off-chain record of who acted, under what role, and what happened for every state-changing request. Ledger Data records what the chain did, the audit trail records who asked the platform to do it.
- [Reconciliation](https://docs.settlemint.com/docs/concepts/records-and-evidence/reconciliation): Comparing your own register against the platform's ledger on your own cadence, so a difference that needs a person is caught rather than assumed away.
- [Reporting Obligation](https://docs.settlemint.com/docs/concepts/records-and-evidence/reporting-obligation): A versioned regulatory duty whose published version generates the filing periods it covers, drawing on Ledger Data's record as evidence for each one.
- [Settlement Verdict](https://docs.settlemint.com/docs/concepts/settlement/settlement-verdict): The recorded end state of an operation you submit to the platform, and the only signal you may read success from.
- [Transfer-Path Compliance](https://docs.settlemint.com/docs/concepts/compliance-and-identity/transfer-path-compliance): The enforcement of a regulated token's rules inside the on-chain transfer itself, so a movement that fails any rule reverts and never settles.
- [DALP Instance](https://docs.settlemint.com/docs/platform/dalp-instance): One self-contained copy of the platform, deployed on infrastructure you choose and connected to the ledger networks you approve.
- [Webhook Delivery](https://docs.settlemint.com/docs/concepts/events-out/webhook-delivery): The transport that delivers a pushed change event to your endpoint, including the retraction it sends when a reorganisation removes the source block.
- [Platform Event](https://docs.settlemint.com/docs/concepts/events-out/platform-event): The record type a pushed change event is, and the catalogue your handler matches against.
- [Error Contract](https://docs.settlemint.com/docs/api-reference/guides/errors): The stable identifier on a failure, including the retryable error the platform returns when a write outpaces the indexed read.


# Market Data

Source: https://docs.settlemint.com/docs/concepts/records-and-evidence/market-data
Market Data gives valuation, compliance, and reporting one governed price for an asset or currency pair, so they stop reconciling separate copies of the market.



[Figure] How Market Data turns sources into governed values. Trusted issuers and external aggregators are two independent kinds of source. Either publishes an observation. A governed directory selects one active feed for each subject and topic. That single feed then serves three parallel outputs at once: an indexed asset price, a valuation, and an exchange rate, not a sequence of separate steps. Labels: Governed market data; Trusted issuer; signed observation; External aggregator; compatible source; Subject + topic; One active slot; governed feed directory; Asset price; Valuation; FX rate.

The governed directory selects one active feed for each subject and topic from issuer and aggregator sources, and consumers read it as one series.

Valuation, compliance, and reporting all draw the same governed price, so none of them keeps a private copy of the market that could diverge from the others without anyone noticing.

A subject names what a value belongs to, and a topic names what it means, so the same two keys always resolve to the one feed active for them.

A read through the price resolver against a feed whose last observation has aged past its window is refused rather than served. The scalar-feed adapter and the feed contract return the aged value with its timestamp, so a consumer reading them checks the age itself.

## Why price needs a governed source [#why-price-needs-a-governed-source]

An institution running tokenised assets needs a price in more places than one moment suggests. A collateral desk marks a position to compute a margin call. A compliance check screens a transfer against a threshold. A fund report values holdings from a net asset value that a feed supplies. Each of these draws from Market Data, and each draws the same value for the same subject and topic at the same moment.

Without a governed source, each of those workflows would keep its own copy of the market, refreshed on its own schedule from whatever source it happened to integrate. Two copies drift the moment their update cadences differ, and a drifted copy is invisible until someone compares two numbers that should have matched and finds they did not. [Asset Lifecycle](https://docs.settlemint.com/docs/concepts/issuing-and-markets/asset-lifecycle) names the general shape of this problem. A programme that runs each stage of an instrument's life in its own system meets a reconciliation at every handoff between those systems, and a reconciliation is where two records that should agree are instead found apart. A private price copy is the same problem for a single number: two records that should agree, maintained apart. An auditor asking which price was official at a given moment gets an answer that depends on which system they asked.

Governance keeps a shared price defensible. The institution, not the platform, decides which issuers or external aggregators it trusts and how long a value may age before the platform treats it as stale. Market Data's job is to hold that decision on chain and serve one answer from it. A shared price then traces back to a source someone chose and can name.

## Why this governance runs on the platform, not beside it [#why-this-governance-runs-on-the-platform-not-beside-it]

The alternative to platform-governed pricing is a market-data terminal or a vendor feed, integrated once by whichever system needs it that quarter. That system picks its own idea of a stale quote, its own retry behaviour when the vendor goes down, and its own storage shape for the number it keeps. Nothing forces it to match the next system that integrates the same vendor differently. An institution running compliance, reporting, custody, and a trading venue behind one platform would then repeat that integration once per consumer, each with its own definition of current.

Market Data closes that gap by sitting inside the same platform as its consumers instead of beside it. Each token has at most one reference market on a [Trading Venue](https://docs.settlemint.com/docs/concepts/issuing-and-markets/trading-venue), and that market writes its official close to the token's price feed in Market Data when the token has one and its asset class takes its price from a reference market rather than from exchange-rate feeds. A compliance screen or a reporting run reads that same feed for the same subject and topic. The rule that decides when a value is too old to serve is derived once and applies wherever a consumer asks for it, so current means the same thing to every workflow that asks. An institution that wants a different one of its trusted sources to answer changes it in one governed place, and every consumer sees the change at the same moment instead of catching up on its own schedule.

## What a subject and topic name [#what-a-subject-and-topic-name]

Market Data organises every value it serves under two keys. A subject names what the value belongs to: the zero address for a global series, a token's own address for an asset-specific one. A topic names what the value means, pinned to a schema when its feed is created, so a price and a valuation for the same token are two different feeds even though they share a subject. Platform foreign-exchange feeds use a deterministic address derived from a currency's ISO 4217 numeric code as the subject, with the base and quote currencies recorded in the feed's own description.

Ask for a subject and a topic, and Market Data returns whichever feed the directory holds active for that pair. It never merges two sources into one answer and never asks the caller to choose between them: that choice was already made when the feed was registered.

## Running feeds day to day [#running-feeds-day-to-day]

Operators manage feeds as a set of named slots. For each subject and topic, they register a compatible feed, watch its latest observation, and remove or replace it when the source changes.

Each feed is pinned to one topic and one schema at creation: the schema is that topic's registered encoding signature, the shape a value must take. An update naming a different topic or schema is refused before anything else runs.

A trusted issuer can publish a signed scalar update stating the value, the observation time, an expiry that bounds how long it may be submitted, and the next issuer nonce. The feed then runs its checks in order, starting with that pinned topic and schema, and any one of them failing leaves the last accepted observation exactly where it was.

[Figure] What a signed update passes before it becomes the current observation. A signed scalar update arrives at the feed. The feed runs ten guards in order, grouped into four families. Pinning checks that the update names the feed's own topic and schema. Signer authority checks that the issuer is trusted for this subject and topic and that the signature comes from a key that issuer authorised. Replay and deadline checks that the nonce is the next one in that issuer's sequence and that any submission deadline has not passed. Value and time sanity checks that the value is positive where the feed requires it and states an observation time. It also checks that the observation is not older than the one already accepted and does not sit further ahead of chain time than the feed's drift allowance. Passing all ten makes the update the current observation. Failing any one of them, from any family, leaves the last accepted observation unchanged, so a refused update never degrades what consumers already read. Labels: Ten guards, in order; Signed update submitted; Pinned to this feed; 1. Topic matches the feed's own topic; 2. Schema matches the feed's own schema; Signer authority; 3. Issuer trusted for subject and topic; 4. Signature from a key the issuer authorised; Replay and deadline; 5. Nonce next in that issuer's sequence; 6. Deadline, where set, has not passed; Value and time sanity; 7. Value positive, where the feed requires it; 8. Observation time present; 9. Not older than the accepted observation; 10. Observation time inside the drift allowance; Any one of the ten; failing leaves the last; accepted observation; unchanged; Becomes the current observation.

Ten guards run in order, and the previous observation survives any one of them failing.

A feed built on an external aggregator can be registered in the same directory and selected the same way, since the directory still holds only one active feed for each subject and topic. A scalar-feed adapter, a contract with a fixed address that reads whichever feed is active, lets consumers keep one address while the feed is replaced. Replacement must preserve the feed kind, schema, and decimal precision. Operations can therefore change the source without changing every consumer address, while the registration and update events remain available for reconciliation.

## Taking prices from a provider instead of a person [#taking-prices-from-a-provider-instead-of-a-person]

An issuer of regulated bonds or funds usually gets its prices from a custodian, a vendor, or a counterparty. If a person copies each price into a feed, the feed shows who typed the number but not which provider quoted it, and a typo reaches valuations and compliance rules. A price source moves the provider into the governed path: the organisation registers the provider once, maps its ISINs, the 12-character securities identifiers, to token price feeds, and the platform publishes only the prices that pass its checks.

A delivered price becomes an observation that records the ISIN, price, currency, price type, and the provider's observed time. Ordered gates then decide its fate: a repeat is dropped, an observation older than the feed's latest is never moved forward to fit, a currency that differs from the feed's quote currency is rejected, and a price that moved less than the publish threshold is skipped. Every outcome is stored on the observation, so an auditor can see why a provider price never reached the feed as well as why one did.

A price that moved beyond the hold tolerance, or that corrects an earlier price from the same provider, is held for review when the organisation's `Prices` approval rule is on. Every approval rule starts off. With the `Prices` rule off, such a price publishes, and the platform records a waived approval for that observation in place of a review. With it on, a feeds manager or the governor of that token approves or rejects it with a wallet verification, and the people who configured the source or queued the delivery cannot. With the rule on, a second person sits between an unusual provider price and a feed that valuations read.

Freshness counts from the provider's observed time, not from the moment the platform published. A late approval therefore cannot make a feed look fresher than the provider's price is. When a mapped feed passes its staleness bound, the platform opens one operations case for that stale episode and names the likely cause, such as a paused source or a held price. The case closes when a fresh price lands.

The platform stores a source's settings and credential and applies the checks, review, and stale alert to any delivery it receives. The platform fetches the deliveries itself: it polls SFTP servers for CSV and `reda.001` files, keeps a FIX market data session open to a counterparty, and asks Bloomberg Data License and LSEG DataScope Select for the prices of the source's mapped ISINs at the times the source names. The Bloomberg and LSEG requests follow each vendor's public documentation and are untested against the live services. The routes are in [Read and submit price feeds](https://docs.settlemint.com/docs/api-reference/guides/feeds).

## Deciding how long a value stays current [#deciding-how-long-a-value-stays-current]

Market Data serves one active value for each subject and topic, and a value is only useful while it is recent. The platform enforces that rather than leaving it to each consumer. When a read finds the active feed's observation older than the window that applies, the on-chain price resolver refuses the read with [DALP-1111](https://docs.settlemint.com/docs/api-reference/errors) instead of returning the aged value. That refusal states the subject, the topic, the timestamp of the observation it rejected, and the window it measured against. That is how a consumer tells a stale feed from a subject and topic that has no feed registered at all: the second answers [DALP-1022](https://docs.settlemint.com/docs/api-reference/errors), and no fresh observation fixes it.

One window applies to a read, and it is decided in two layers: a deployment-wide default, and an optional override on a single feed that takes three forms.

| Layer | What it accepts, and where it applies |
| --- | --- |
| Global default. | A positive window in seconds or an explicit never-expires value. It applies wherever no per-feed override exists. Until someone sets a global window, the default is one day, and never-expires applies once a global setting to it has been recorded. |
| Per-feed override, a window in seconds. | One window for one subject and topic, sized for a feed whose publisher runs faster or slower than the house rule. |
| Per-feed override, never expires. | No age limit, for one feed that does not age. Every other feed keeps a window. |
| Per-feed override, inherit global. | Clears the override, returning one feed to the house rule. |

Read the effective window for a subject and topic when you need to know what applies. The answer names both the window and the layer that produced it, so an override someone set months ago stays visible rather than inferred.

## Choosing how much history a feed keeps [#choosing-how-much-history-a-feed-keeps]

Retention decides how many rounds the feed contract keeps in its own storage, separate from the indexed history the API serves. The platform's issuer-signed feed create flow always uses Latest only and rejects zero or negative observations, so it cannot create a feed for an interest rate or an exchange-rate movement that can cross zero. An externally deployed feed may have different value and retention rules. Registering it does not change those rules.

| Retention mode | What the contract keeps, and what that costs |
| --- | --- |
| Latest only. | The newest round. A historical round read against the contract answers [DALP-0131](https://docs.settlemint.com/docs/api-reference/errors). Indexed history is unaffected. |
| Bounded. | A fixed number of rounds. Rounds past that depth leave contract storage. |
| Full. | Every round, at the most on-chain storage. It is the only mode where any round stays readable from the contract itself. |

The platform's create flow does not offer Bounded or Full retention, although the underlying feed contract supports both. Use the indexed API when a consumer needs the history of accepted native observations.

Retention is fixed in each feed contract. A consumer that requires older rounds directly from a contract needs a separately deployed compatible feed with that retention mode. Replacing the directory entry can select that feed if its kind, schema, and decimal precision match. The replacement starts with its own history, while the previous feed's rounds remain readable at its address for as long as it is deployed. Indexed history follows the events both contracts emit.

## What the domain covers [#what-the-domain-covers]

Market Data separates three duties: the on-chain directory selects the active feed, each feed contract owns its own accepted observations, and the index follows their events to serve current and historical API views. An API response is an indexed view of on-chain state, not a fresh call to the source.

The directory permits one active entry per key. It verifies that the topic exists, that the feed schema matches the topic, and that a scalar feed exposes the `AggregatorV3` interface. Subject zero is global. Any other subject binds the feed to that address. A replacement keeps the same semantic and numeric contract, which protects consumers from a silent unit change.

The directory neither aggregates sources nor derives rates. An external aggregator computes its own answer upstream and publishes it through a compatible feed. Separately, the indexed foreign-exchange graph derives available cross-rates from confirmed currency-pair observations. It retains observation time and history, so a derived rate can still be tied to its underlying market-data series.

Three related values are outside Market Data. A token's own resolved price, and the price history that cascades onto that token's record, are outputs the token domain computes from this domain's feeds, not values Market Data stores as its own. A portfolio's or a system's value history is the same kind of downstream output, owned by the portfolio domain. A trading venue's official close is a number the venue decides from its own trading under the instrument's close methodology. The platform submits it on chain through this domain's submission path. The number stays the venue's, and this domain derives nothing from it.

## The integration contract [#the-integration-contract]

Developers address Market Data by subject and topic. Feed-management routes register, replace, remove, submit, resolve, and read observations. Exchange-rate routes expose the latest positive observation, configured pairs, supported currencies, and paginated history for an ISO 4217 base and quote pair.

A feed value is a scaled integer. Its decimals define the scale, while its observation timestamp states when the source observed the value. Read both. A successful submission means the signed update passed the feed's authority, replay, time, and value checks and was recorded on-chain. A mutation request that was only accepted by the platform does not prove that the feed changed. Use its transaction outcome and then the indexed feed state.

Consumers that need a stable contract address can use the scalar-feed adapter. It resolves the current feed from the directory on every call and forwards the `AggregatorV3` reads. If no scalar feed is registered for that subject and topic, it fails rather than returning a default. An adapter changes only how consumers read the feed. An issuer-signed feed behind an adapter still accepts signed updates from its trusted issuers, and the platform still treats it as issuer-signed. Indexed API reads can lag the chain briefly, so do not treat an immediate missing record after registration as proof that the on-chain slot does not exist.

Match each refusal by its error code. A subject and topic with nothing registered answers [DALP-1022](https://docs.settlemint.com/docs/api-reference/errors). An address that does not answer the `AggregatorV3` interface answers [DALP-9519](https://docs.settlemint.com/docs/api-reference/errors), which usually means the address is wrong. An observation timestamp further ahead of chain time than the feed's drift allowance answers [DALP-0639](https://docs.settlemint.com/docs/api-reference/errors). Check the observation timestamp and the signer host's clock before retrying. Price-topic submissions through the feed route require the Feeds manager role and use the organisation's submission signer. Token price operations also expose their own authorisation rules.

## Controls and evidence [#controls-and-evidence]

Market Data separates the authority to select a source from the authority to publish an observation. Feed managers govern directory entries. For issuer-signed feeds, only an issuer trusted for that subject and topic can submit, and the signature must come from a key authorised by that issuer.

A price that comes from a provider adds a review duty. The person who configures a price source cannot approve a price that source held, and the governor of a token can approve a held price only for that token. The raw message behind each source price is kept off chain with its hash, so a reviewer reads what the provider sent.

The feed prevents replay and stale overwrites before state changes. Within a feed, each issuer has its own strictly increasing nonce. An optional deadline bounds submission. Observation time must be present. An observation older than the current one cannot replace it. The platform's native issuer-signed feeds require positive values and allow no future drift from chain time. Other compatible feed contracts may enforce different value and time rules, fixed by their own contracts.

On-chain events record feed registration, replacement, removal, and accepted updates. An accepted signed round records the value, observation time, issuer, and signer. Those events are the durable record, while the configured history mode determines only how many rounds the contract itself keeps in its own storage. The indexed history provides the operational query surface. These records show what the platform accepted, and which trusted issuer and signing key submitted it. They do not prove that the off-chain market observation was economically correct, which remains part of source governance.

## Frequently asked questions [#frequently-asked-questions]

### Is a topic the same as a currency pair?

No. A topic defines the value's meaning and schema. Platform foreign-exchange feeds use the price topic and a deterministic currency address as the subject. The feed description records the base and quote currencies, such as EUR / USD.

### Does replacing a feed change the decimals or scale of values a consumer already read?

No. A replacement is accepted only if it keeps the same feed kind, schema, and decimal precision as the entry it replaces, so a value a consumer already stored keeps the same meaning and scale. What resets is the upstream source and its round history: the new feed contract starts with no rounds of its own, while the previous feed's rounds stay readable at its own address for as long as it remains deployed.

### Can more than one issuer publish to the same feed?

Yes. The trusted issuers registry can authorise several issuers for one subject and topic, and the feed accepts a signed update from any of them once its checks pass. Each issuer keeps its own strictly increasing nonce, so issuers never compete over sequence numbers, but the staleness check compares an incoming observation against whichever issuer's update is latest, not against that one issuer's own history. A newer submission from a second issuer can therefore supersede an older one from the first.

### What happens if a signed update's nonce falls out of sync?

A submission is refused unless its nonce is exactly one more than the last nonce that issuer had accepted, even when the value and observation time are otherwise valid. The first accepted nonce is 1. Read the issuer's current nonce, sign a new update with the next value, and submit it. Observation time may equal the latest accepted timestamp. An earlier timestamp is rejected.

### Does the platform calculate a fund's net asset value?

No. The platform computes no net asset value of its own. A fund share class takes its net asset value per unit from a governed data feed, which a trusted issuer or a configured provider publishes. The fund register, a report of a fund's classes and holders, multiplies each class's feed price by the units held and states the value in the feed's own currency. A class with no feed price has no value there. The "Client asset summary" report first converts the feed price into the organisation's base currency, and it leaves the value empty when the class has no feed price or no exchange rate links the two currencies. With the Primary market add-on, a fund redemption settles at a net asset value that the feed published between 12:00 on the dealing day named in the settlement call and 12:00 on the next dealing day, both in Coordinated Universal Time (UTC). A dealing day is a weekday, Monday to Friday, counted in UTC. Without a net asset value from that window, the platform rejects the settlement call with [DALP-14099](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference#domain-rule-errors), and the redemption requests stay open until a net asset value is published and settlement runs again. [Fund Dealing](https://docs.settlemint.com/docs/concepts/issuing-and-markets/fund-dealing) covers the dealing rules.

### Does a change to the global default window affect a feed that already has its own override?

No. A per-feed override in seconds stays fixed for that feed regardless of what the global default becomes, until someone changes or clears it. Only a feed with no override, or one explicitly set to inherit the global default, picks up a change to that default. Reading the effective window for a subject and topic always shows which layer produced the answer, so an old override never hides behind a number that changed without notice.

## Related concepts [#related-concepts]

- [Asset Lifecycle](https://docs.settlemint.com/docs/concepts/issuing-and-markets/asset-lifecycle): The working life of a tokenised instrument. A price feed appears as one of the workspace tabs a deployment can install, and the seam-count argument that motivates a governed price source is the same one this page names for pricing.
- [Ledger Data](https://docs.settlemint.com/docs/concepts/records-and-evidence/ledger-data): The platform's queryable record of the ledger networks it follows, built by decoding blocks and events into business records.
- [Trading Venue](https://docs.settlemint.com/docs/concepts/issuing-and-markets/trading-venue): The permissioned exchange. A token's reference market on it writes each session's official close to that token's price feed, when the token has one.
- [Reconciliation](https://docs.settlemint.com/docs/concepts/records-and-evidence/reconciliation): The recurring comparison between an off-chain register and the on-chain ledger. A feed's registration and update events stay available for that comparison after the source behind it changes.
- [Audit Trail](https://docs.settlemint.com/docs/concepts/records-and-evidence/audit-trail): The off-chain record of who acted and under what role. Registering, replacing, or removing a feed is one of the state-changing requests it covers.


# Mirror tokens

Source: https://docs.settlemint.com/docs/concepts/records-and-evidence/mirror-tokens
A standard token that stands for a holding kept off chain, minted and burned one to one with the custodian's or registrar's transaction id.

A mirror token is a standard DALP token that stands for a security held off chain at a custodian or registrar. The custodian mints and burns it one to one against that holding, the collateral rule caps its supply, and every mint and burn carries the custodian's or registrar's transaction id. Once minted, the token trades and settles like any other token.

## What makes a token a mirror token [#what-makes-a-token-a-mirror-token]

A token is a mirror token when its metadata has a `heldAt` entry that names where the legal holding sits. An optional `heldAtAccount` entry names the account there. Add both as metadata fields on the token's instrument template.

A mirror token also needs:

- the supply delegate token feature, with the custodian's wallet added as a delegate that can mint and burn
- the supply management role on that same wallet
- the collateral rule at a ratio of 100%

Without the supply delegate feature, or without the collateral rule at 100% for a mint, a mint or burn is refused with [DALP-200385](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference#client-request-errors) and the reason `setup-incomplete`.

## Minting and burning [#minting-and-burning]

Post the new attested holding as a collateral claim first, through `PATCH /api/v2/tokens/{assetId}/collateral`. A mint above the claim is refused by the collateral rule.

Send the mint or burn with the custodian's or registrar's transaction id in `registerReference`. DALP puts a keccak-256 hash of the id on chain, through the token's supply delegate feature, and keeps the text off chain.

| Refusal `reason` | What it means |
| --- | --- |
| `external-reference-required` | The mint or burn has no `registerReference`. |
| `single-movement-per-reference` | The call names more than one recipient or holder. |
| `burn-own-units-only` | The burn names another holder. The holder transfers to the custodian's wallet first. |
| `caller-not-delegate` | The wallet is not a supply delegate with that permission. |
| `setup-incomplete` | The supply delegate feature or the collateral rule is missing. |

API v1, batch runs, sale funding and agent mandates cannot carry a reference, so a mirror token refuses them.

In the Console, the Mint and Burn sheets on a mirror token show where the holding sits and require the external reference. The token page shows a Held at card.

## Reading the reference back [#reading-the-reference-back]

The reference appears on the movement it belongs to:

- [Webhooks](https://docs.settlemint.com/docs/api-reference/webhooks/events): `token.transfer.*`, `asset.issuance.*` and `asset.burn.final` carry `externalReference`.
- Activity: `GET /api/v2/tokens/{assetId}/events` and its export add an `externalReference` value to the supply delegate mint or burn, for a caller with a role on the token. Other callers see the movement without it.

Investors see the location as text: the holding page in the Portal shows "Held at", and the positions and portfolio tables of a PDF statement name it on a full-width line under the instrument.

## Corporate actions wait for reconciliation [#corporate-actions-wait-for-reconciliation]

A corporate action pays or allots the holders it counts on its record date. On a mirror token those holders must match the custodian's or registrar's record. A reconciliation break on the token, first seen on or before the record date, that is still open or under investigation, therefore holds the corporate action's snapshot: preview is refused with `reconciliation-break-open` and nothing is stored. A corporate action without a record date counts the day preview runs.

The snapshot goes ahead once every such break is resolved or written off. Either change goes through the break's own approval, so a second operator checks it when your organisation requires maker-checker. A break first seen after the record date does not hold the snapshot. A token that is not a mirror token is never held.

## Position statements [#position-statements]

The custodian's or registrar's position statement is the record a mirror token is compared with. Send it to DALP once per business date.

`PUT /api/v2/reporting/mirror-reconciliations/{tokenAddress}/configuration` names the statement's layout and the cut-off of the day. The layout is a named CSV profile: its delimiter (comma, semicolon or tab) and the headers of the columns naming the wallet, the quantity and, when the file has one, the ISIN. The cut-off is a local time with an IANA timezone. A token nobody configured reads the default profile `dalp-registrar-v1`, with the columns `holderWallet` and `quantity`, and has no cut-off. Only the organisation owner or a platform administrator can change the configuration.

`POST /api/v2/reporting/mirror-reconciliations/{tokenAddress}/statements` stores the statement of a date, in the CSV text your profile describes. Each changed text of a date becomes that date's next numbered version, and every version keeps the profile it was read with. Sending the text of the date's latest version again adds nothing and answers that version, so a retried upload is safe.

A file the profile cannot read stores nothing. The answer is `Rejected`, with the refusal and the line:

| Refusal | What it means |
| --- | --- |
| `empty-file` | The file has no header row. |
| `missing-column` | The file lacks a column the profile names. `column` says which. |
| `invalid-wallet` | A row's wallet is not a readable address. |
| `invalid-quantity` | A row's quantity is not a number the security's decimals can hold. |
| `duplicate-wallet` | A wallet appears on two rows. |
| `isin-mismatch` | A row names another ISIN than the one recorded on the token. |
| `malformed-quote` | A quote character sits inside an unquoted cell. |
| `unterminated-quote` | A quoted cell is never closed. |

`GET /api/v2/reporting/mirror-reconciliations/{tokenAddress}/statements` lists the stored versions, newest date and version first.

## Daily reconciliation [#daily-reconciliation]

Once a mirror token has a cut-off, DALP reconciles it every day. At the cut-off it reads the token's holders at the last final block, the latest statement version of that date, the supply and the trusted collateral claim, and compares them:

- each investor's quantity on chain with the quantity on the statement, line by line.
- the statement total with the supply and with the collateral claim.

If a daylight-saving change repeats the local cut-off time, DALP uses its second occurrence. If the change skips that time, DALP moves the cut-off forward by the clock change, so a 02:30 cut-off in Brussels becomes 03:30. The clock change does not skip the day's reconciliation.

The run of the date is `clear` when everything matches, `break` when anything does not, and `no-statement` when no statement of the date was stored by the cut-off. A `no-statement` run is never clear. It raises a case for your operations team.

Each investor line that does not match opens a break in the reconciliation break register, with its ageing, under the asset key `registrar:<token address>`. A statement total that differs from the supply opens a break on `supply:<token address>`, and one that differs from the collateral claim opens a break on `collateral-claim:<token address>`, under the same asset key. A later run where the line or the total matches clears its break. The first run of a date reads only the statement versions stored by the cut-off, so a statement that arrives late still leaves a `no-statement` run. A statement stored after the run, or a new version of it, gives the date a new numbered run.

`GET /api/v2/reporting/mirror-reconciliations/{tokenAddress}/runs` lists the runs with their outcome and number of breaks. `GET .../runs/{runDate}` returns the date's latest run with its totals and every line that does not match, and `GET .../runs/{runDate}/file` exports those lines as CSV. Both take `?version=` to read an earlier run of the date.

In the Console, the holder register's export sheet has a **Reconciliation** tab on a mirror token, with the runs, the lines of each run and a CSV export. A reporting obligation can include the `mirror-reconciliation` report, which lists each run in its period with every line that does not match.

## Settlement feed [#settlement-feed]

DALP sends the custodian or registrar every settled movement on a mirror token: each venue fill, the bust of a settled trade, each mint and burn, and each corporate-action movement. A movement's value date is the date of its settlement block in the token's cut-off timezone.

Each record carries the movement, the trade for a fill or a bust, the settlement transaction, the parties, the quantity, the unit price for a fill or a bust, and the value date. The parties are the wallets' OnchainID addresses. The feed never carries national ID numbers or other personal data.

Once a value date has closed in the token's timezone and its last block is final, DALP writes the day's file and sends one `reporting.mirror-movement.final` webhook per movement. The file lists the movements in settlement order, so the same movements always give the same bytes. A changed day becomes the date's next file version. A movement keeps the same `movementId`, so a repeated delivery of its webhook is the same movement.

`GET /api/v2/reporting/mirror-reconciliations/{tokenAddress}/settlement-feeds` lists the files. `GET .../settlement-feeds/{valueDate}/file` downloads one, with `?version=` for an earlier version. `POST .../settlement-feeds/{valueDate}/replays` rebuilds the day from the chain and says whether it equals the stored file. It stores nothing.


# Reconciliation

Source: https://docs.settlemint.com/docs/concepts/records-and-evidence/reconciliation
Reconciliation lets your register stay the book of record while you prove it agrees with the platform's ledger, and know exactly when a gap needs a person.



[Figure] Reconciliation: the off-chain register compared against the DALP ledger. Your off-chain register is the book of record. The DALP on-chain ledger is auxiliary evidence you compare it against on a cadence, daily batch or event-driven. A difference explained by timing lag or a chain reorganisation resolves itself once both sides catch up. A difference that survives that check escalates to a person. Labels: Two records, one authority; Off-chain register; Your system; Book of record; On-chain ledger; DALP; Auxiliary evidence; Compare on a cadence; batch daily, or event-driven; Timing lag or a chain reorganisation; Resolves once both sides; catch up; Unexplained after that check; Escalates to a person. Nothing; in the platform decides for you.

Your register stays the book of record, and a person handles any ledger difference that timing or a chain reorganisation does not explain.

Reconciliation lets your off-chain register stay the book of record for as long as you want it to, with the DALP ledger standing beside it as evidence you compare against on your own terms.

A difference is often timing, because the two records come from different processes on different schedules.

The platform's evidence supports either cadence, a daily batch pull or an event-driven comparison, from the same point-in-time, replayable record.

## Why reconciliation matters [#why-reconciliation-matters]

Reconciliation lets you keep your own register as the book of record. On a cadence you choose, you compare it with the platform's Ledger Data, the queryable record of what happened on the chain you follow. The platform supplies point-in-time queries and events. The comparison and the decision on each difference are yours. A gap caused by timing or a chain reorganisation closes on a later comparison once the ledger has caught up or corrected, and a gap that does not close needs a person. When the two disagree, your register prevails and the difference is investigated, not corrected automatically. Your register stays the book of record until you decide the ledger takes over.

This page covers two comparisons: your register against Ledger Data, and, when custody operations are on, custody receipt supply against the coins held, under [Custody reconciliation](#custody-reconciliation).

A difference between the two is often timing. Your register and the DALP ledger are produced by different processes on different schedules. Your register reflects instructions your operations team entered and confirmed on its own timing. The DALP ledger reflects the terminal verdict the platform reached for the on-chain write it executed. A transfer can be true in one record before the other has caught up, and reconciliation often reads that lag as a discrepancy when the two records agree.

## Why reconciliation compares against one ledger, not several [#why-reconciliation-compares-against-one-ledger-not-several]

[Asset Lifecycle](https://docs.settlemint.com/docs/concepts/issuing-and-markets/asset-lifecycle) names the cost this discipline answers. A programme that keeps issuance in one system, identity screening in a second, custody in a third, trading in a fourth, and settlement and reporting in a fifth needs a comparison at every handoff between them. That handoff is where an instrument's ledger state and its legal record can drift apart. The platform records issuance and servicing against one asset instead, so reconciliation here is a comparison between two parties, your register and one ledger, in place of the several comparisons a multi-system programme would run.

That is also why the platform never asks you to hand over book-of-record status to get the comparison. An institution that already runs its own operations of record, its own accounting treatment, and its own regulatory sign-off can prove the chain agrees with that record. It can do so on a cadence its own operations team sets, without retiring the system those functions are built around. The decision to let the ledger take over stays yours, made through your own legal, regulatory, accounting, and operational review, never a setting the platform switches for you.

## Running reconciliation day to day [#running-reconciliation-day-to-day]

You run reconciliation on a schedule you set. The platform does not run it for you. The DALP ledger answers a point-in-time query at any past block, so pulling the register as of a cutoff and comparing it to your own is a repeatable lookup rather than a live capture you have to time carefully. Either cadence works, and each costs something different. A batch pull, once a day or once a cycle, needs only that one point-in-time query and skips event handling entirely, but a difference can sit undetected for up to a full cycle. An event-driven comparison runs when a change event arrives. The consumer must handle provisional, final, and retracted events, and reconcile any gaps or duplicates. An operation running an end-of-day close is usually well served by the batch cadence. One carrying intraday exposure needs the event-driven path to catch a difference before the day closes.

Most differences trace to one of two causes. The first is timing. Every DALP ledger read answers as of its progress point, the furthest block its record can be trusted through, and how far that point trails the chain's newest block depends on the network's own finality settings. The Ledger Data index reports degradation when its lag or staleness passes the thresholds in the [ledger indexing stalled runbook](https://docs.settlemint.com/docs/deployment/runbooks/ledger-indexing-stalled). Your reconciliation policy sets its own acceptable discrepancy. Your register may post before or after the index's progress point. The second is a chain reorganisation, which the platform corrects on its own by deleting and replaying the affected records. Wait for that correction rather than reconciling against a figure captured mid-rollback.

A difference that survives both explanations does not get resolved automatically. Route it to a person who can pull the DALP ledger's own evidence, the transfer list and the progress point it covers, and compare it against your register's underlying instruction. That step stays manual on purpose: nothing in the platform decides which of two disagreeing records is correct.

## How the two records relate [#how-the-two-records-relate]

Two platform records feed reconciliation: the DALP ledger, a decoded, queryable projection of the chain you follow, and the Settlement Verdict, the platform's own terminal outcome for a write you submitted. They answer different questions. The ledger reads each block once and commits its records and progress point together. When the chain replaces recent blocks, it deletes the affected records and replays the canonical chain rather than leaving a stale figure in place. The verdict is recorded once, for the write itself, and never revoked.

Ordinarily those two agree: a verdict of completed means the platform's write reached the chain and the ledger has caught up to the block it landed in. One case breaks that pairing: a reorganisation orphans the exact transaction that a verdict already reported completed. The ledger deletes the orphaned records and replays, but nothing in the platform revisits the verdict. Treat the ledger's record as the authority for what the chain holds, and have your comparison flag any completed verdict whose transaction the ledger no longer holds.

Neither record extends past the chain the platform follows. The ledger proves what happened on that chain. It proves nothing about a custody provider's own books, an external bridge, or a reserve held off-chain. Any of those needs its own evidence, sourced separately, before your reconciliation process can rely on it.

A token can also require every movement of its units to carry a reference to the entry in your register that records it. With the Booked movements feature attached, the token moves units only when an administrator books a movement under a register reference, and it refuses every other mint, burn, transfer, forced transfer or wallet recovery. Each webhook event for a booked movement includes `registerLine`, with the ID of the booked line and its register reference, so a reconciliation job can match the movement to its register entry when each entry has its own reference. [Booked movements](https://docs.settlemint.com/docs/concepts/records-and-evidence/booked-movements) explains the lines and how a correction works, and the [Booked movements workflow](https://docs.settlemint.com/docs/console/asset-management/manage/booked-movements) shows how to book them in the Console.

## The integration contract [#the-integration-contract]

Two API surfaces give a reconciliation job what it needs, and neither requires you to poll the raw chain. Query the DALP ledger for the register as of a past block, for one holder's transfers across a period, or for period aggregates such as fees, exemptions, yield, and redemptions. A point-in-time or per-transfer answer includes the progress point it covers, so a comparison against your register states exactly which blocks it accounts for. A period aggregate is stricter: the ledger folds a running total forward only to the newest settled block, so compare an aggregate against that block instead of the progress point.

For the event-driven path, subscribe to Platform Event notices, the signed record the platform emits as a write changes state, delivered through Webhook Delivery, the HTTPS push that carries each notice to your endpoint. Each step in a write arrives as its own event with its own identifier. For example, a transfer can post as provisional before it posts final. A reorganisation that invalidates a delivered event produces a retraction naming the identifier it replaces. Your consumer reconciles by replacing the record for that identifier, not by guessing which of two events is current.

Read a write's own outcome from its Settlement Verdict, not from acceptance. Acceptance only means the platform durably queued the instruction. Idempotency has an edge your pipeline must handle. The queue attaches a matching submission to an existing transaction request when the key, sender, network, and wallet selection match inside the 24-hour window. That does not cover work the API route may perform before queue admission. Outside the window, or with a different wallet-selection fingerprint, a matching queue submission does not attach. It fails outright. Inspect the original operation's status and on-chain result before creating a new attempt. A new key identifies new work and can duplicate an operation that already succeeded. Build your comparison job to key off the progress point and the verdict, not off request timing, and a chain reorganisation becomes a correction your job absorbs rather than an alert it has to raise.

## Custody reconciliation [#custody-reconciliation]

When custody operations are on, the platform runs a reserve check for custody receipts and keeps a register of reconciliation breaks. The reserve check compares custody receipt supply with the coins held at custody addresses. The break register keeps the differences a registrar file reconciliation finds on record until a later clean run closes them or a resolution or write-off is applied after a second user approves it. The platform does not read the custody provider's own statements, so those stay a separate comparison outside the platform.

The reserve check covers custody receipts. A custody receipt is the token that represents coins held at the organisation's custody addresses. Every five minutes, the platform reads indexed state for each organisation and compares a receipt's total supply with the coins held at the organisation's custody addresses. The expected supply is the balance of the underlying coin at the custody addresses the organisation watches, minus the quarantined, held, unsupported and unallocated amounts the [custody gateway](https://docs.settlemint.com/docs/concepts/custody-and-signing/custody-gateway) reports, plus the coins in open gateway instructions, which are custody instructions still in progress. When the difference has not cleared for two hours, the platform raises a critical operations case. The case carries the label `Balance difference`, is listed by the operations cases route of the [Platform API](https://docs.settlemint.com/docs/api-reference/v2), and reaches a webhook subscriber as an `operations.case.opened` event. The same check raises a case with the same label when an address holds the supply management role on a receipt, an address other than the gateway factory is a supply delegate, the Hold feature is detached, the gateway factory is no longer the Hold reserver, a forced transfer passed a hold, a gateway implementation was updated, a gateway escrow locks fewer receipts than open requests are owed, or a keeper or screener wallet falls below its low-balance threshold. A case resolves itself when a later check of that network no longer finds its condition, except a gateway implementation update, which does not resolve itself.

A bank rail recall that a manager abandons leaves the holder's tokens in place, so the bank's debit stays an unexplained difference between the bank balance and the token supply until a manager records a reserve adjustment. The Abandon dialog in the Console states this before it submits, and a second manager has to approve the abandon.

A registrar file reconciliation compares a registrar's holder file with the chain. When an organisation Owner or platform administrator runs it, every holder line that does not match becomes a break in the organisation's register with the cause `External`, keyed by wallet and asset. A break has five statuses.

[Figure] The statuses of a reconciliation break. A break starts open and can move between open and investigating with a note. From either status, a second user's approval, or the change alone while the custody operations approval is off, closes it as resolved or written off, and a clean run closes it as resolved automatically. A closed break is never edited again. Labels: Open; Found by a run; Investigating; Owner at work; Closed, never edited again; Resolved; Approved, or approval off; Written off; Approved, or approval off; Resolved automatically; A clean run clears it.

A break moves between open and investigating on a note, needs a second user to resolve or write off while the custody operations approval is on, and closes on a clean run without one.

A break is open when a run finds it. An organisation Owner or platform administrator can mark it investigating and back to open, each time with a note. While the organisation's "Custody operations" approval is on, resolving it or writing it off asks a second user, an organisation Owner or platform administrator other than the requester, to approve. With that approval off, the default, the change applies at once. A later run that finds the same wallet and asset clean closes it as resolved automatically. A later run that still differs updates the same break and advances its age in weekdays without creating a duplicate.

A closed break is never edited again. A difference that returns after a resolution opens a new break linked to the closed one. A write-off covers the difference it was approved for. While the same amount keeps showing in every run since the write-off, no new break opens. A clean run in between ends that cover, and a difference that returns or changes then opens a new linked break. The approved write-off, its note and its maker and checker stay as recorded. A run changes a break only when the run's date is not earlier than the latest date the break already rests on, so rerunning an earlier date neither clears a break first seen later nor reopens one that a later run cleared.

To work the register, follow [Custody reconciliation in the Console](https://docs.settlemint.com/docs/console/organisation-settings/custody-reconciliation).

## What the evidence proves, and what it does not [#what-the-evidence-proves-and-what-it-does-not]

Reconciliation evidence has two layers. One records what happened on the chain that the platform follows, with repeatable queries and traceable sources. The other records who in your organisation acted on each exception. The DALP ledger supplies the first, deterministic under the same query and the same blocks. Every correction traces to the chain's own canonical history, never to an operator editing a figure, which is what makes it defensible evidence for what the chain did. It does not, on its own, establish who in your organisation investigated or cleared a specific reconciliation exception. That trail lives in your own operations record, not the platform's.

The platform's Audit Trail, the append-only log of which session performed each step, records the session that acted, which is normally the person who acted. When someone works under a Delegated Authority, the permission for one participant to act on another participant's behalf, the log names the operator's own session rather than the party they stood in for. Do not present the platform's log as independently proving who a delegated step was taken on behalf of.

State the evidence claim's limits to a reviewer: the ledger evidences the chain the platform follows, known contract types only, for the period processed under its current recording rules. It says nothing about a custody provider's own books, an external bridge, or an off-chain reserve. Those need separate evidence that you produce and defend yourself.

## Frequently asked questions [#frequently-asked-questions]

### Which system prevails when the two disagree?

Your off-chain register, for as long as it stays your book of record. The DALP ledger is auxiliary evidence: authoritative for what happened on the chain the platform follows, not for your legal or economic position. A disagreement means you investigate. Neither record overrides the other by default, because they answer different questions.

### What happens if your idempotency key already expired? [#what-happens-if-my-idempotency-key-already-expired]

A resubmission outside the 24-hour idempotency window does not attach to the original request. It fails instead of quietly retrying it. That failure is not itself a reconciliation difference, and resubmitting the same key again does not resolve it. Check the original operation's outcome first. Use a new key only for a new attempt you have confirmed is needed, then reconcile that attempt by its operation identifier and verdict.

### What would have to change for the chain to become our book of record?

A decision on your side, not a mode switch on the platform's. It means retiring the parallel off-chain register as the legal record and treating the DALP ledger, backed by Transfer-Path Compliance's on-chain enforcement and the ledger's own repeatable, provenance-backed evidence, as sufficient on its own. Make that decision through your legal, regulatory, accounting, and operational review. A period without discrepancies does not by itself establish that the ledger can serve as the legal register. Even once it does, the ledger's evidence still stops at the chain itself: it says nothing about a custody provider's own books, an external bridge, or an off-chain reserve, and those keep their own separate trail either way.

### How do you treat a provisional event? [#how-do-i-treat-a-provisional-event]

Not as a reconciled position. A transfer can arrive as a provisional event before the chain confirms it and again as a final event once it does, and a reorganisation within the finality depth can retract the provisional one. Hold a provisional event aside until its final event arrives or a retraction removes it, and reconcile only against the final or retracted state your consumer has replaced it with.

### What do you reconcile aggregates against? [#what-do-i-reconcile-aggregates-against]

The newest settled block, not the general progress point. A period aggregate, such as a fee, exemption, yield, or redemption total, is a running figure the ledger folds forward only as far as the chain's newest settled block. That cutoff is one step stricter than the progress point a per-transfer read can use. Pull your own register as of that settled block, not as of the ledger's progress point, or the comparison starts from two different cutoffs.

### Daily bank rail evidence [#daily-bank-rail-evidence]

A [daily bank rail version](https://docs.settlemint.com/docs/api-reference/guides/bank-rail#daily-reconciliation) preserves the bank balance against supply and the rail wallet against parked credits for one connection date. The bank report is the latest retained report at or before a pinned civil cutoff. The token facts are current indexed facts, read while the drained block stays unchanged, so the version does not claim chain state at that cutoff. The report time and indexed block are stored as evidence pins. Equal pins reuse the version, either older axis refuses the run, and newer evidence creates another immutable version. Unavailable values and case counts remain unavailable, with reasons, so a missing source cannot look like a zero difference. A manager can reread or export any stored version.

## Related concepts [#related-concepts]

- [Asset Lifecycle](https://docs.settlemint.com/docs/concepts/issuing-and-markets/asset-lifecycle): The whole working life of a regulated tokenised instrument on one platform record. The argument for why this comparison is two parties, not the several a multi-system programme would run.
- [Ledger Data](https://docs.settlemint.com/docs/concepts/records-and-evidence/ledger-data): The platform's queryable record of the ledger networks it follows, the source of the point-in-time and per-period evidence a reconciliation job compares.
- [Settlement Verdict](https://docs.settlemint.com/docs/concepts/settlement/settlement-verdict): The platform's own terminal outcome for a submitted write, recorded once, and never revoked. The record a reconciliation job reads instead of request acceptance.
- [Transaction Lifecycle](https://docs.settlemint.com/docs/concepts/settlement/transaction-lifecycle): The governed path a write travels from acceptance to its verdict, including the idempotency rule that keeps a retry from creating a phantom reconciliation difference.
- [Transfer-Path Compliance](https://docs.settlemint.com/docs/concepts/compliance-and-identity/transfer-path-compliance): The on-chain enforcement of a regulated token's rules at transfer time. What a native, chain-is-the-register arrangement leans on in place of a parallel off-chain control.
- [Audit Trail](https://docs.settlemint.com/docs/concepts/records-and-evidence/audit-trail): The append-only log of which session performed each step. Evidence for who investigated a reconciliation exception, distinct from the ledger evidence for what the chain did.


# Reporting Obligation

Source: https://docs.settlemint.com/docs/concepts/records-and-evidence/reporting-obligation
A reporting obligation lets your organisation prove to a regulator which rules governed a filing, and keeps that proof fixed even after the duty changes.



[Figure] One obligation, a frozen version, the periods it generates. A reporting obligation starts as an editable draft: name, regime, and cadence rules. Publishing freezes that draft as a numbered version, immutable from then on. The version alone generates filing periods, on an hourly schedule, once each period's calendar interval has closed. Q4 2025 closed and was filed under an earlier version. Q1 2026 is open, generated from the current version, version 3. Labels: Duty, version, filing period; Reporting obligation; Regulatory duty; Draft: editable anytime; Publishing freezes it as a version; Version 3; Frozen version; Immutable once written; Sets cadence, deadlines, format; Generates filing periods; Hourly, once a period closes; Q4 2025 (closed); Filed, evidence retained; Discharged as fulfilled; Q1 2026 (open); Generated from version 3; Deadline still pending.

An obligation is an editable draft until you publish it, and publishing freezes a numbered version that alone generates filing periods.

A reporting obligation records which rules governed a filing, so your organisation can show a regulator the configuration used long after the obligation has moved on. You configure the duty as an always-editable draft of what to report and by when.

Publishing freezes that draft into a numbered version. Editing the obligation afterward never touches a version already published.

The platform generates filing periods from a published version's cadence. Each period stays linked to the version that defined it.

## Why a filing needs a rule set that cannot move [#why-a-filing-needs-a-rule-set-that-cannot-move]

A regulator asking about a filing from two years ago wants to know which rule set governed it on the day you filed. If that answer lives in a duty's current settings, any edit made since changes it without anyone intending that.

Publishing freezes the draft under a version number, and no platform route updates or deletes a published version, so a filing from three versions ago still points at the exact deadline rule, scope, and data points that produced it. [What a version proves](#what-a-version-proves) states the limits of that guarantee.

A filing period reads the same indexed ledger records, held at the same block height and log position, that back the platform's transfers, holdings and prices. Its chain figures come from the platform's own indexed record of the chain, which an auditor can recompute from the chain's blocks, rather than from a separate reporting system's copy. [Asset Lifecycle](https://docs.settlemint.com/docs/concepts/issuing-and-markets/asset-lifecycle) describes why fewer handoffs mean fewer reconciliations.

## Why an obligation and its version are different things [#why-an-obligation-and-its-version-are-different-things]

Configure each reporting duty as a separate obligation with a name, cadence, and required fields. Publish a new version when the duty changes. That version determines the requirements for later filing periods.

An organisation can have several obligations, such as transaction reporting and holdings disclosure, each with its own cadence and fields. The obligation holds an editable draft. Editing alone creates no filing periods. The platform also keeps a catalogue of obligations for common regimes, which only the platform can edit. Each organisation receives its own draft copy of every catalogue obligation, and reviews, edits and publishes that copy like any obligation it owns.

Publish after you have checked the duty, cadence, and deadlines. Publishing freezes the draft into a numbered version and allows the platform to generate filing periods. A mistake remains in force until you publish a corrected version. An organisation owner or a platform administrator can create, edit, publish, or disable an obligation. A Reporting reader can read its configuration: an organisation owner, a platform administrator, or a member whose acting wallet holds the Permission manager, Auditor, Compliance manager or System manager role on the organisation's system.

An obligation can require [maker-checker](https://docs.settlemint.com/docs/concepts/custody-and-signing/maker-checker) sign-off on its filings. This setting defaults to enabled. Maker-checker makes a second approver sign off each filing. Publishing needs no second approval: it only checks that two eligible approvers exist. Choose the setting according to the review required for that reporting duty. A change takes effect in the next published version and does not alter earlier periods.

## How periods appear on the calendar [#how-periods-appear-on-the-calendar]

A filing period is one dated instance of a duty, such as Q1 2026 transaction reporting with its remittance deadline. The platform creates periods automatically. Once an hour, it checks published obligations for calendar intervals that have closed since the previous check and generates each period from the published version's cadence. If the obligation was disabled first, the platform waives the period instead. An obligation editor can also generate a filing for an ended date range. Its period is linked to the current published version but sits outside the cadence, so it never falls overdue and the schedule does not change.

A new period waits until the platform's chain data reaches the finality required for reporting, then opens. This wait reduces the risk of filing figures that a chain reorganisation could change. Disabling an obligation waives periods still waiting for finality. Open and overdue periods continue unchanged. The API cannot re-enable a disabled obligation. The platform generates the filing's files. Your organisation uploads them to the authority, then records the submission and the authority's receipt reference, or a publication reference, and that record makes the period fulfilled. An unfiled period becomes overdue when its deadline passes.

[Figure] A period waits for chain finality before it opens, and disabling only reaches a period still waiting. Every hour, the platform checks each published, enabled obligation for a calendar interval that has closed. A closed interval opens a new filing period, but that period first waits for the underlying chain to reach finality on the data it reports before it flips open for filing. Disabling the obligation while a period is still in that waiting stage marks it waived, and generation for that obligation stops for good: the API has no operation that re-enables it. A period that has already opened, or that already fell overdue, keeps running untouched, since disabling never reaches back to stop it. Labels: Filing period lifecycle; Interval closes; Hourly check; Waiting for; chain finality; Scheduled; Open for filing; Ready to file; too late to disable; Waived; Disabled early; Generation stops; Already open; or overdue; Runs untouched.

A period waits for chain finality before it opens, and disabling the obligation waives only a period still waiting, not an open or overdue one.

The Console's Obligations page shows each duty next to its current published version, and the Filing calendar shows the periods those versions generated, each row carrying a remittance deadline, an urgency badge, and coverage for each reporting family.

## How a report format shapes the files the authority receives [#how-a-report-format-shapes-the-files-the-authority-receives]

A report format is the part of a reporting obligation that sets how the authority wants its files laid out. It names each file and its columns, and says where each column reads its value: a data point, a field of a generated report, or fixed text. Without a format, a filing contains the standard reports its obligation selects. An obligation can select the security incidents report, which lists security alerts and operations cases of kind security. An operations case is the platform's record of an incident that an operator acknowledges and resolves. The platform raises a security alert and a security case for a burst of failed sign-ins, a burst of refused authorisations, a privileged role grant and a new API key, and the report lists them. It lists nothing the platform does not detect, so an empty security incidents report does not show that no incident took place.

Each column can also write its value the way the authority's template expects. A number can be scaled from token base units by the token's decimals, rounded to fixed decimal places, and written with the authority's decimal and thousands separators. At 18 decimals and two places, `1500000000000000000` is written `1,50` in a template that uses a decimal comma. A date takes a layout such as `DD/MM/YYYY` and a time zone, so an event at 21:30 UTC on 30 September is dated 1 October in Dubai. Text can be upper or lower case, and an EVM address can use its checksum case.

A CSV file can set its delimiter, its byte order mark, and its line ending. A spreadsheet whose list separator is a semicolon then opens the file without an import step.

The format is versioned with the rest of the obligation. Publishing checks each column against what it can know before any data exists: the data point or EVM report field the column names, and whether its format suits the data point's type. A field the report does not have, a number format over a text data point, or a CSV setting on a spreadsheet file stops the publish with a message that names the column. A report field holds text, so generation checks each value as it writes the file. A value the format cannot write stops the filing at the first such row, and the message names the file, the column, and the row. A second authority layout for the same report needs only a second format, never a platform release.

## Which reports a filing can carry [#which-reports-a-filing-can-carry]

Each filing generates the reports in its obligation's report set. The platform's report families are grouped here by the question each answers. The names are the ones the Console shows under "Report" in the obligation editor.

| What you are reporting on | Report families |
| --- | --- |
| Who holds the asset | Holder register, Mirror reconciliation, Custody positions, Client asset summary, Safeguarding extract, Dormant accounts, Frozen assets, Wallet register |
| Movement on chain | Transfer journal, Trade journal, Settlements and fails, Incoming transfers, Outgoing transfers, Daily transactions, Pending and failed transactions |
| Corporate actions and income | Corporate actions, Corporate action entitlements, Corporate action payments, Redemptions, Distribution waterfall |
| Backing and money | Reserve and asset backing, Fees and charges, Fee period closes, Gas wallets |
| Who is eligible and what was decided | Compliance decision log, Investor eligibility register, Withdrawal destination whitelist, Approvals |
| What your operators did | Operator action trail, Privileged action activity, Security incidents, Wallet changes, Service availability, Break ageing |
| Trading venue | Venue daily statistics, Venue orders, Venue matched trades, Venue audit log, Venue market watch, Venue holdings, Venue trading parameters, Venue new participants |

The Console offers every family the deployment serves, and its obligation editor sets one report for each draft. The Platform API takes several reports on one draft. Send them as the report set of `POST /api/v2/reporting/obligations` or `PUT /api/v2/reporting/obligations/{obligationId}`. Four custody operations reports are served only while custody operations are switched on, which they are by default. They are the wallet register, incoming transfers, outgoing transfers and the withdrawal destination whitelist.

The trade journal holds one row for each executed venue trade and each bust. It is also the source of the per-trade reports the platform sends to a regulator over FIX, described in [Trade reports](https://docs.settlemint.com/docs/concepts/records-and-evidence/trade-reports). For a venue in the Abu Dhabi Global Market, [FSRA venue reports](https://docs.settlemint.com/docs/concepts/records-and-evidence/fsra-venue-reports) lists the venue matched trades columns that carry the MIR 3.6.7 post-trade fields and the provisional FSMR s.149 order and transaction reports.

### Service availability [#service-availability]

This report measures how the custody and API services performed over the period. It needs a period with a start, so it cannot be generated for an open-ended window. Each row is one of five kinds, named in the `rowKind` column:

- `provider-availability`: one row per custody provider configuration, with its availability percentage over the period and the milliseconds it spent in any health state other than healthy.
- `health-window`: one row for each window a custody provider spent outside the healthy state, with its start, end and health.
- `api-route-group`: one row per API endpoint tag, or per route template where an endpoint has no tag, with the request count, the count of responses with a status of 400 or higher, the average latency and the latency that 95 per cent of requests stayed under.
- `delayed-operation`: one row for each delayed custody operation, of two sorts.
  - A custody withdrawal created before the period end whose cancellation window closed before the period end. The expected time is that window's end.
  - A deposit whose screening outage or screening freeze case passed its recorded expiry before it was resolved.
- `incident-window`: each operations case that overlaps the period, clipped to the period, with its kind, subject and recorded detail.

### Gas wallets [#gas-wallets]

For each network in the filing's scope, this report lists the wallets that pay for the organisation's transactions: the paymaster deposit, the bundler and the gas station. Each row carries the network, role, address, balance and threshold in wei, the time of that balance, the last top-up and its amount, and the time the newest funding alert for that wallet was raised. The status column reads `empty` at a zero balance, `low` below the threshold and `funded` otherwise. The bundler's threshold is its top-up level, sized from the network's live fee quote when the snapshot was taken. A snapshot recorded before that level was stored carries no bundler threshold. Balances come from the latest recorded balance snapshot at or before the filing's as-of time. A network where the organisation's system has no account abstraction ready produces no rows.

### Corporate action entitlements [#corporate-action-entitlements]

One row covers each holder allocation of each previewed corporate action whose record date falls in the period. An action whose preview recorded no record date counts in the period it was created in. Each row carries the action, token, event type and status, the record, ex and payment dates, the holder's participant and wallet, the eligible quantity, the payout asset and its decimals, and the gross entitlement the preview allocated.

The platform computes no tax withholding. Every row reports a tax rate and tax withheld of zero, a net entitlement equal to the gross, and the tax status "not computed", so an issuer that withholds off the platform states the net amounts in its own records.

## The data model behind the three terms [#the-data-model-behind-the-three-terms]

Three linked records represent the obligation, version, and filing period. The obligation holds the organisation's editable draft. It has no status field, and counts as published once it has a published version. A version stores the configuration at publication and remains immutable. A filing period points to that version and records its reference interval and calculated deadline.

Editing the draft leaves published versions unchanged. A period generated under version 2 keeps that link after version 5 is published. Publishing allocates the next version number, stores the configuration, and sets that version as current in one atomic step. Earlier versions and periods remain intact. The API cannot restore an older version as current. Publish a new version to change the configuration.

## The integration contract [#the-integration-contract]

The API lets you list, read, create, and update obligations, publish a version, or disable an obligation. Publishing validates the draft, checks that its calendars belong to your organisation or the platform, and, when maker-checker is enabled, requires at least two organisation owners before it commits. `DELETE /api/v2/reporting/obligations/{obligationId}` disables an obligation and removes nothing, and no call re-enables a disabled obligation: disabling waives eligible periods while preserving their records, and a duty you want back needs a fresh obligation. An organisation owner or a platform administrator can make changes, and a Reporting reader can list and read. Field-level constraints, request and response shapes, and per-endpoint error handling are in the [API reference](https://docs.settlemint.com/docs/api-reference/v2).

The obligation response identifies the current version number. The publish response returns the frozen configuration of the version it creates. `GET /api/v2/reporting/obligations/{obligationId}/versions` lists every published version of the obligation with its number, publication time, publisher and frozen configuration, so an integration can read a past version at any time. The version's deadline rule specifies the business calendars used to calculate the due date. Use the [filing-periods list](https://docs.settlemint.com/docs/api-reference/v2) to read the resulting periods and deadlines. It returns your organisation's periods ordered by remittance deadline unless you request another order. For each reporting family, it reports coverage as pending, covered, refused, or historically unconfirmed. Read these results instead of calculating periods and deadlines in your integration.

An obligation can carry validation rules. Each rule is one comparison, using `=`, `!=`, `<`, `<=`, `>` or `>=`, over the obligation's data points, the named values a filing reports. For example, `{class-a.units} + {class-b.units} = units` checks that the units of two share classes add up to the total. Each rule has a severity of `blocking`, `warning`, or `informational` and an effective date range. Publishing refuses a rule that does not parse, is longer than 2,000 characters, names an undeclared data point, or compares values of different types. Write a date as `"2026-09-30"` or as a date and time with an offset, such as `"2026-09-30T00:00:00Z"`. A date and time without an offset does not compare with a date. When a filing is generated, the platform checks each rule in force on the period's last day. A failed `blocking` or `warning` rule stays on the filing as a finding that names the rule, the data points, and their values. Approval is refused while a `blocking` finding stands. Correct the data and generate the filing again. Generating a filing again, like replacing it, opens a fresh attempt that the platform checks against the rules again, and resolves the findings of the attempt it replaces. Approval is also refused while a `warning` finding is open. An organisation owner other than the person who prepared the filing accepts open warnings with the `AcceptRuleWarnings` act, a written rationale, and the filing's row version. A failed `informational` rule never blocks approval.

## What a version proves [#what-a-version-proves]

A published version records the dated configuration that governed a filing period. Later publications can supersede it, but the platform does not update or delete the earlier version.

Maker-checker at publication checks approver availability. When the setting is enabled, the organisation must have at least two owners. One owner can still publish alone. The check does not prove that a second person reviewed the configuration. If an eligible person later leaves, the organisation may need another approver before the next sign-off.

A version proves which rule set governed a filing. It does not prove that the filing was correct or complete. The filing period carries the submission's separate review trail.

## How an anchor proves a filing was not altered [#how-an-anchor-proves-a-filing-was-not-altered]

A version records which rules governed a filing. An anchor lets a regulator or auditor confirm that a copy they hold is byte for byte the filing the organisation fulfilled. Anchoring covers filings. FIX trade reports sent to a regulator are not anchored, as [Trade reports](https://docs.settlemint.com/docs/concepts/records-and-evidence/trade-reports#what-is-anchored-and-what-is-not) explains. Anchoring is off until an organisation owner or a platform administrator turns it on for an obligation in [Obligations](https://docs.settlemint.com/docs/console/reporting/obligations).

### What is hashed [#what-is-hashed]

A filing is stored as an ordered list of files, called parts. The platform takes the SHA-256 of each part's bytes and its length in bytes, builds a short text manifest from them, and takes the SHA-256 of that text. The result is the manifest digest.

A reviewer can rebuild the manifest outside the platform:

1. Write the first line as `dalp.reporting.artifact-manifest.v1`.
2. For each part, in order and numbered from 0, write one line with the part number, the part's SHA-256 as 64 lowercase hex characters without a `0x` prefix, and its length in bytes as a decimal number. Separate the three fields with the unit separator character, U+001F.
3. Join the lines with a line feed, U+000A, and add no line feed after the last one.
4. Take the SHA-256 of the UTF-8 bytes of that text. It is the value the approver checks in the "Approve" dialog and the value the registry stores. Changing one byte of any part, adding or removing a part, or putting the parts in a different order produces a different manifest digest.

### Where it is written [#where-it-is-written]

When a filing of an anchored obligation is acknowledged or published, the platform writes the filing's manifest digest into the document anchor registry: an add-on contract on the organisation's own system, on the network chosen when anchoring was turned on. Each entry records the issuer identity, the subject identity, the digest, the document type, the label and the block it was written in.

The current registry implementation has no update and no delete function. The registry runs behind a proxy, and a new implementation decides what the registry reads back. A System manager on the organisation's system can point the registry's add-on type at a new implementation through the system's add-on registry, and that change is itself an on-chain transaction anyone can read. The registry refuses every write once its add-on registration is archived. Otherwise it accepts a write only from a sender with an active identity that holds a claim key on the issuer identity, and only when the trusted issuer registry trusts that issuer for the anchoring topic on the subject. The platform writes each filing at most once, and a repeat of a write that already landed returns the existing entry instead of adding a second one.

### How a copy is checked [#how-a-copy-is-checked]

A holder of a copy checks it with "Check a document", which appears on the Anchor registry screen and beside an asset's documents in the Console and the Investor portal. The holder names the issuer identity and chooses the files in the order they were delivered. The browser hashes each file and sends only the digests and lengths, so the document never leaves the holder's machine. The platform recomputes the manifest digest, finds the registry that the named issuer's own system runs, and looks for that issuer's entries under the digest up to the last block the indexer has read. The same check is `POST /api/v2/reporting/anchors/verify`, which needs a signed-in caller and no organisation or Reporting role, as the [Platform API reference](https://docs.settlemint.com/docs/api-reference/v2) describes.

The issuer is required because two organisations can anchor byte-identical files, and an entry that only names an issuer proves nothing when it sits in a registry the issuer does not run. A reviewer who does not use the platform can read the same entries from the registry contract's public read functions, by digest or by subject identity.

### What each answer means [#what-each-answer-means]

| Answer | Console title | What it means |
| --- | --- | --- |
| `anchored` | "Anchored by this issuer" | The named issuer committed to exactly these bytes in the registry its own system runs. The copy is the one it attested. |
| `not-found` | "No entry of this issuer's, so far" | No entry of the issuer's matches at or below the indexed block, which the answer names. The bytes differ from what was attested, the parts are in another order, a different issuer anchored them, the check named another network than the one the entry is on, or the entry was written after that block. |
| `not-indexed` | "Nothing has been read yet" | The indexer has read no block on this network. The answer says nothing about the document. |
| `registry-unresolved` | "This issuer's registry could not be named" | No system on this network answers for the issuer, more than one does, or the one that does runs no live registry. Nothing was read. Check the issuer address and the network. |

A `not-found` answer means that no matching entry was read up to the named block. An altered copy produces this answer because its manifest digest differs from the anchored one.

An anchor proves that a copy matches the bytes the platform held for the filing when it wrote the anchor. It does not prove that the authority received those bytes, because the platform does not deliver a filing and a user records its submission and the authority's receipt. It does not prove that the filing was correct, and it never changes whether the duty was met: a failed anchor leaves the filing fulfilled with a finding, as [Filings](https://docs.settlemint.com/docs/console/reporting/filings) describes.

## Frequently asked questions [#frequently-asked-questions]

### Do version numbers restart for each new reporting obligation, or share one counter?

Each obligation keeps its own count. Publishing your transaction-reporting obligation for the third time makes that publish its version 3, regardless of how many versions any other obligation your organisation holds has reached. Citing "version 3" to a regulator identifies a rule set only together with the obligation it belongs to, never by the number alone.

### Could the hourly check ever generate two filing periods for the same interval?

No. The version and calendar interval uniquely identify each period. A second attempt to create the same period leaves the first record unchanged. More frequent checks or a restart therefore do not create another period for that version and interval.

### Which calendar decides a period's deadline: my organisation's or the regulator's?

Both. The filer's calendar and the authority's calendar can disagree on which days count, so two organisations on the same cadence can land on different deadlines in different jurisdictions. The version's deadline rule names which calendar applies to which half of the calculation.

### Can the platform deliver every authority file as one upload?

No. Each authority file is a separate file in the filing, and the report format has no option that joins them. Authority portals usually take one template per filing type or module. The FSRA electronic prudential reporting system, for example, takes one Excel, CSV, or XBRL template per module, so a bundle would need to be split again before upload. Upload each file to the template slot the portal names.

## Related concepts [#related-concepts]

- [Asset Lifecycle](https://docs.settlemint.com/docs/concepts/issuing-and-markets/asset-lifecycle): The seam-count argument for keeping a regulated instrument's whole life on one platform, applied here to the reporting step specifically.
- [Ledger Data](https://docs.settlemint.com/docs/concepts/records-and-evidence/ledger-data): The queryable, decoded record of the chain a filing period's figures are read from, read at the block height the period names.
- [Market Data](https://docs.settlemint.com/docs/concepts/records-and-evidence/market-data): The governed price and valuation history a filing that reports value draws on, read from its append-only observations rather than a live cursor.
- [Reconciliation](https://docs.settlemint.com/docs/concepts/records-and-evidence/reconciliation): The recurring comparison between an off-chain register and the on-chain ledger, the check a filing period's own figures still need to pass before you rely on them.
- [Audit trail](https://docs.settlemint.com/docs/concepts/records-and-evidence/audit-trail): The record of who created, updated, or published an obligation, and when, the surface a regulator would ask for alongside a published version.
- [Maker-Checker](https://docs.settlemint.com/docs/concepts/custody-and-signing/maker-checker): The filing sign-off requirement and the separate check for eligible approvers when publishing an obligation.


# Trade reports

Source: https://docs.settlemint.com/docs/concepts/records-and-evidence/trade-reports
Report each executed trade and bust to a regulator as a FIX trade capture report over a FIX session, and record the regulator's answer on each report.

A trading venue that must report each executed trade and each bust to its regulator can have the platform do it. The platform renders one FIX trade capture report, message type `35=AE` by default, for each trade event in the trade journal of a published [reporting obligation](https://docs.settlemint.com/docs/concepts/records-and-evidence/reporting-obligation). FIX, the Financial Information eXchange protocol, is the message standard trading venues and regulators use. The platform queues each report and sends the queue over a FIX session that it opens to the regulator, then records the regulator's answer on the report. A session runs only to an endpoint the deployment allows. When no session can run, the reports stay queued and the organisation files the trade journal export through its own channel.

You configure the message layout and the session through the Platform API. The Console shows the queue and the session state.

The obligation version holds the message layout. The FIX tags for trade and bust reports are written into the obligation version, so a change to a regulator's tag set needs a new version and no platform release. A report keeps the version it was queued under.

Two groups act on trade reports. A Reporting reader reads the queue and the session state: an organisation owner, a platform administrator, or a member whose acting wallet holds the Permission manager, Auditor, Compliance manager or System manager role on the organisation's system. An organisation owner or a platform administrator also records an outcome by hand, corrects a rejected report, and drafts and publishes the obligation that carries the layout and the session.

## What the platform sends [#what-the-platform-sends]

A report is one message about one event. Its identity is the trade and the event kind, `trade` or `bust`, joined with a colon, so a trade that is later busted produces one report of each kind: `trade-1:trade` and `trade-1:bust`.

Each message follows the version's layout. The body starts with the message type in tag 35 and continues with each mapped tag in layout order. The platform then adds the FIX version string, called the BeginString, in tag 8, the body length in tag 9 and the checksum in tag 10. When the session sends the message it adds the sequence number, the sender and target identifiers, called CompIDs, and the sending time. A version that carries no layout uses this default:

| Tag | Value | Required |
| --- | --- | --- |
| 35 | `AE`, TradeCaptureReport | Yes |
| 17 | The report ID, such as `trade-1:trade` | Yes |
| 11 | The trade ID | Yes |
| 60 | The execution time | Yes |

The default BeginString is `FIXT.1.1`. A layout can name a separate message type for a bust. Without one, a bust report uses the trade message type and differs from the trade report in its report ID and its fields.

A layout reads from the fields each trade journal row carries:

| Group | Fields |
| --- | --- |
| Identity | `reportId`, `eventType`, `tradeId`, `marketId`, `venueAddress` |
| Instrument | `baseTokenAddress`, `quoteTokenAddress` |
| Orders | `buyOrderId`, `sellOrderId` |
| Parties | `buyerAccount`, `buyerClassification`, `buyerParticipant`, `buyerIdentityReference`, and the same four fields for the seller |
| Execution | `priceTick`, `quantity`, `executedAt`, `status`, `undoReason` |
| Fees | `buyerFee`, `sellerFee`, and `fees`, one `side:feeType:amount:vatAmount` entry per fee line |
| Change time | `updatedAt` |

A mapping whose value is empty is left out of the message unless the mapping is required. A required tag with an empty value, a value outside printable ASCII, or a value that breaks a validation rule stops the render, and the report is not queued.

## When a report is queued [#when-a-report-is-queued]

The platform checks for trade changes 15 seconds after its previous check ends. Each check covers every published obligation that is not disabled and whose report set includes the trade journal. It queues reports for such an obligation whether or not the obligation configures a regulator session. A change is a new trade, a bust, or a later update to a trade, for example its settlement. The platform reads the changes in the order the trades last changed and queues one report for each trade and each bust under the obligation's published version.

An obligation queues each trade and each bust once, across all its versions. A later update to a trade it already queued, other than its bust, adds no report. If that report has never been sent or corrected and still waits under the published version, the platform renders its body again from the changed trade. Every other report keeps its body, and only its source time moves.

A new version resumes after the last trade change any earlier version of the same obligation reached. Reports an earlier version queued keep the body that version rendered. The organisation's session sends the ones still waiting, and a regulator answer to any of them moves that report.

An obligation that has queued no report yet, for example one whose first version with the trade journal was just published, starts at the oldest trade change in the organisation's history. Once a session runs, it sends a report for every past trade and bust. Before you publish the trade journal on such an obligation, confirm that the regulator expects the full history.

Each obligation tracks the last trade change it queued separately, so two obligations with the trade journal each queue a report of every trade and bust. The organisation's one session sends every queued report. An answer moves only the report of the obligation that runs the session, and the other obligation's report stays `submitted`. When both obligations configure a session, no session starts.

Two obligations that carry the trade journal send every trade and bust to the regulator twice, under the same report ID. Keep the trade journal in one obligation per organisation.

A published layout can still fail to render one trade, for example when a required tag maps to a field that trade leaves empty. Queueing for that obligation then stops at that trade, so no later trade or bust is queued ahead of it. The session still sends the reports queued before it. The platform logs "Queueing transaction reports stopped for this obligation" with the obligation, its version and the reason, for example `FIX tag 571 is required`, and logs it again on every check until the trade renders. The log does not name the trade. The queue count, the oldest-report age and the `TransactionReportsQueuedTooLong` alert do not show the stop, because nothing new is queued. Other obligations and organisations keep queueing.

The platform writes that message to its logs only, and no screen or alert shows the stop. To restart queueing for that obligation, an organisation owner or a platform administrator changes the message layout in the obligation's draft through the Platform API so the logged reason no longer applies, for example by mapping the required tag to a field every trade carries, then publishes the draft on [Obligations](https://docs.settlemint.com/docs/console/reporting/obligations). The Console keeps the message layout but does not edit it. The new version resumes at that trade. Queueing also resumes without a new version when a later change to that trade gives it the missing value. The trade then counts as changed at that moment, so trades and busts that changed while queueing was stopped are queued before it.

A report keeps:

| Field | What it holds |
| --- | --- |
| Report ID | The trade and event identity. |
| Obligation version | The published version whose message layout rendered the body. |
| Message type and body | The FIX message type and the rendered body, as [When a report is queued](#when-a-report-is-queued) describes. |
| Source time | The moment the source row last changed. |
| State | `queued`, `submitted`, `acknowledged` or `rejected`. |
| Attempt | How many times the report has been corrected and queued again after a rejection. |
| Send and answer times | When the session sent it, when the regulator answered, and the reference the regulator gave. |
| Rejection reason | The text the regulator gave, or the one recorded by hand. |

## Configure the message layout for an obligation version [#configure-the-message-layout-for-an-obligation-version]

The message layout sits on the obligation version beside the report set and the delivery settings. It names the BeginString, defaulting to `FIXT.1.1`, the message type for a trade, an optional separate message type for a bust, the field mappings, the validation rules and, optionally, how the regulator answers.

Edit the layout and the session through the Platform API. The Console's obligation editor has no field for either: it opens a draft that carries the trade journal with "Trade journal" selected and keeps the layout and the session when you save. Create or replace the draft with `POST /api/v2/reporting/obligations` or `PUT /api/v2/reporting/obligations/{obligationId}`, then publish it with `POST /api/v2/reporting/obligations/{obligationId}/publish`. The [Platform API reference](https://docs.settlemint.com/docs/api-reference/v2) carries the request shapes.

A field mapping takes a tag number, a source field, an optional expression and a required flag. The source field is one of the trade journal fields in [What the platform sends](#what-the-platform-sends). An expression substitutes named source fields into a constant, as `${tradeId}-${eventType}` does. A tag can be mapped once. The session envelope tags 8, 9, 10, 34, 35, 49, 52 and 56 cannot be mapped, because the platform writes them.

A validation rule names a tag and one of three kinds: required, a pattern, or a comma-separated list of allowed values. Each carries the message a refusal shows. A rule must name a tag that a mapping carries, since a rule on any other tag could never be checked.

Publication refuses a version whose layout breaks any of these rules and names the message layout as the rule that failed. Publication also refuses a version that configures a regulator session while its report set leaves out the trade journal, because the session sends trade journal reports only.

## How the answer is read [#how-the-answer-is-read]

By default the platform reads a TradeCaptureReportAck, `35=AR`, and takes the report ID from tag 571, the status from tag 939, the regulator's reference from tag 818, and the reason from tags 751 and 58. Status `0` accepts the report and status `1` rejects it.

A version can carry its own answer layout instead: the answer's message type, the tag that echoes the report ID, the status values that accept and reject, the tag carrying the regulator's reference, and the tags that explain a rejection. An answer with no report ID, an acceptance with no reference, and a status that is neither an acceptance nor a rejection are unreadable, so each one lands on the exceptions list and changes no report. A rejection with no reason text is recorded as "Rejected without a stated reason".

## How a session sends the queue [#how-a-session-sends-the-queue]

The platform runs one FIX session for each organisation whose published trade journal version configures one, and the platform opens the connection to the regulator. The version names:

- the regulator's host and port, whether the connection uses TLS, and the server name to present, which defaults to the host
- the sender and target CompIDs
- the heartbeat interval, from 5 to 300 seconds, defaulting to 30
- whether Logon resets the sequence numbers, which defaults to no
- an optional credential slot
- an optional weekly schedule of UTC days and a daily window, where a window whose end is before its start runs past midnight
- how long the session's messages are kept, `messageRetentionClass`, which defaults to `indefinite`
- the time zone whose calendar day closes a trading day for the reconciliation, `tradingDayTimeZone`, which defaults to `UTC`
- an optional test environment, `testProfile`, with the same fields as the session, for certification

Without a schedule the session stays up. The version never holds a username or a password. A credential slot names two entries in the deployment's secret store, `reporting/regulator-fix/<organisation ID>/<slot>/username` and `reporting/regulator-fix/<organisation ID>/<slot>/password`, which the platform reads when the session connects.

Every 30 seconds a supervisor compares the published versions with the sessions it runs. Three checks run before the supervisor connects. A session that fails one is logged once and not started:

- The endpoint is on the allow list. The deployment lists the regulator endpoints it allows as `host:port` entries in `regulatorReporting.allowedEndpoints`, set through the `REGULATOR_REPORTING_ALLOWED_ENDPOINTS` environment variable. A session to any other endpoint is not started. With the list empty, no regulator session runs.
- The organisation runs one session. When more than one of its published trade journal versions configures one, none starts until one remains.
- The FIX session supports the layout's BeginString.

A session sends queued reports oldest first, up to 100 at a time. Each report takes the next sequence number from the session's stored counter and gets an entry in the sent log that keeps the exact bytes sent, and the report moves to `submitted` with its send time. A restart therefore continues the sequence without a gap. When the regulator asks for messages again, the session replays the bytes the regulator first received, marked as a possible duplicate with PossDupFlag and carrying the original sending time. A Logon with sequence reset, or a reset the regulator asks for, starts the sequence numbers again from 1 and puts every report the regulator has not confirmed back in the queue.

The sent log holds the bytes of each report. The session's message log, described in [Keep the session's messages](#keep-the-sessions-messages), holds every message of the session and is readable through the Platform API.

A dropped connection reconnects after one second, doubling the wait up to one minute. The session stops at the end of its schedule window, when its version's configuration changes, or when the version stops being published, and the next supervisor pass starts it again when it should run. Some faults hold the session instead of reconnecting it: the regulator logs on or answers with other CompIDs, sends a sequence number lower than expected, or logs out with a status that asks the initiator to stop. A held session stays down until its configuration changes, its schedule window closes and opens again, or the platform service restarts.

## When a report moves and when it does not [#when-a-report-moves-and-when-it-does-not]

An acceptance or rejection moves only the report it names, and only from `submitted`. A repeated acceptance with the same reference, or a repeated rejection with the same reason, leaves the report as it is. The regulator can also refuse a message at session level, with a FIX Reject or BusinessMessageReject, which moves the report sent under that sequence number.

The two kinds of answer are recorded in opposite orders. An answer to a report is applied to the report before the session records that it received it, so a crash between the two applies the same answer again and leaves the report as it is. A session-level rejection is recorded as received before it moves the report, so a crash between the two can leave the report `submitted`. Record the rejection by hand in that case.

An answer that cannot move a report is kept with its raw message on the organisation's exceptions list. The [Filings](https://docs.settlemint.com/docs/console/reporting/filings) screen shows each one with its reason:

| Code | Reason shown in the Console |
| --- | --- |
| `not-an-answer` | The regulator sent a message that is not an answer to a transaction report |
| `unreadable` | The answer lacks a field needed to read it |
| `unknown-report` | The answer names a report that was never queued |
| `does-not-apply` | The answer does not fit the report's current state |
| `rejected-without-report` | The regulator rejected a session message that carried no report |

## Correct a rejected report or record an outcome by hand [#correct-a-rejected-report-or-record-an-outcome-by-hand]

An organisation owner or a platform administrator records each change with `POST /api/v2/reporting/transaction-reports/{transactionReportId}/transitions`. The route returns the report after the change, and the request audit records the actor and the transition. The [Platform API reference](https://docs.settlemint.com/docs/api-reference/v2) carries the request shape.

| Transition | Allowed from | What it records |
| --- | --- | --- |
| `resubmit` | `rejected` | A corrected source row. The platform renders the body again and requeues it. |
| `submit` | `queued` | The report was filed outside the platform. The send time is the request time. |
| `acknowledge` | `submitted` | The regulator's reference, which cannot be blank. |
| `reject` | `submitted` | The regulator's reason, which cannot be blank. |

A rejected report is fixed by resubmitting a corrected source row that names the same trade and event kind. The platform renders the body again from the version the report was queued under, keeps the report ID, increments the attempt and puts the report back in the queue. The platform checks only that the row names the same trade and event kind. It does not compare the other fields with the trade journal, so the corrected report carries the values the caller sends.

The earlier rejection reason, send time and reference are cleared from the report, so the report holds no history of its corrections. The audit trail holds each transition, and the session's sent log keeps the bytes of each attempt sent.

A transition from any other state is refused with the state the report is in. The transition route identifies a report by its platform ID, which you read from the report list.

## Find a report [#find-a-report]

`GET /api/v2/reporting/transaction-reports` lists the organisation's reports, newest queued first. Each row carries the platform `id` that the transition route takes, the regulator-facing `reportId`, the `tradeId`, the state, the attempt, the rendered body and the rejection reason. Any Reporting reader can call it, the same audience as the queue status.

| Filter | Returns |
| --- | --- |
| `filter[state]` | Reports in one state: `queued`, `submitted`, `acknowledged` or `rejected`. |
| `filter[obligationVersionId]` | Reports queued under one obligation version. |
| `filter[q]` | Reports whose `reportId` or `tradeId` contains the text, ignoring letter case. |

`meta.total` counts the reports that match. The list returns up to 50 reports per page, or the number set in `page[limit]` up to 200. When more match, `meta.nextCursor` holds a cursor: send it as `page[cursor]` with the same filters to read the next page. A cursor issued for other filters or another organisation is refused. To correct a rejection, list with `filter[state]=rejected`, then send `resubmit` for the row's `id`.

## Fall back to the file [#fall-back-to-the-file]

The trade journal is also a report in an ordinary filing. A version whose report set includes it produces the journal as a file in the version's output format, through the same generation, review and approval steps as any other filing on [Filings](https://docs.settlemint.com/docs/console/reporting/filings). When no regulator session can run, an organisation owner or a platform administrator files that export through the organisation's own channel and records each outcome on the transition route: `submit` for a report filed outside the platform, then `acknowledge` with the regulator's reference or `reject` with the reason. The report then reads exactly as the session would have left it, and nothing on the report marks the outcome as recorded by hand. The audit trail holds the actor and the transition. The `acknowledge` and `reject` transitions also apply to a report the session sent, so check the trail before you rely on a report's answer as the regulator's own.

## Reconcile each trading day [#reconcile-each-trading-day]

Each day the platform compares what the venue executed with what the regulator acknowledged. A pass runs every 5 minutes for each organisation whose published trade journal version configures a session. It reconciles every trading day of the last 14 days that has closed, plus a grace hour, in the time zone the session names in `tradingDayTimeZone`, which defaults to `UTC`. A day that still has breaks is reconciled again on each pass.

Each trade and each bust of the day lands in one class:

| Class | Meaning |
| --- | --- |
| `acknowledged` | The regulator accepted the report. |
| `rejected` | The regulator rejected the report. |
| `submitted-not-acked` | The session sent the report and the regulator has not answered. |
| `queued` | The report waits in the queue to be sent. |
| `missing` | No report was ever queued for it. |

Every class but `acknowledged` is a break. The platform keeps the result as a numbered version of the day. It stores a new version only when the result differs from the day's latest, so the version number counts real changes, and a stored version is never edited. A day with breaks raises one critical operations case for that day, and the case closes on the pass that finds the day balanced. The same breaks move the `TransactionReportReconciliationBreaks` alert, which fires when a break stays open for 15 minutes.

A Reporting reader reads the versions with `GET /api/v2/reporting/regulator/reconciliations` and the lines of one version, filtered by class, with its `lines` route. A report of kind `regulator-reconciliation` exports the versions as a file. The [Platform API reference](https://docs.settlemint.com/docs/api-reference/v2) carries the request shapes.

## Keep the session's messages [#keep-the-sessions-messages]

The platform records every message of the session in both directions, administrative messages included, such as Logon, Heartbeat, Resend Request and Sequence Reset. Each entry keeps the raw frame, the sequence number, the sequence reset it belongs to, the message type, the possible-duplicate flag, the sending time and the time the platform recorded it. The Logon password and a new password in the frame are replaced before the frame is stored, so the stored frame's body length and checksum no longer match its content.

How long the messages stay is configuration. The session's `messageRetentionClass` is `five-years`, `seven-years`, `ten-years` or `indefinite`, and a session that sets none keeps every message. The platform carries no regulator's retention period, so set the class to the period your regulator requires. A sweep erases the messages older than their class, except those a legal hold covers.

A duty manager places a legal hold with `POST /api/v2/reporting/regulator/message-holds`, for a period or for every message when the period is left out, and releases it with a `PATCH` on the hold. A released hold stays on record. The next sweep after a release erases the messages past their class that no other hold covers.

A Reporting reader lists the messages of a period with `GET /api/v2/reporting/regulator/messages`, which answers the last 24 hours when no period is given, and lists the holds with `GET /api/v2/reporting/regulator/message-holds`. A report of kind `regulator-messages` exports the messages of a date range. Wide PDF reports group the columns into separate tables and repeat a row number so you can follow the same message across each group. CSV exports keep every column on one row.

## Show that the session is monitored [#show-that-the-session-is-monitored]

`GET /api/v2/reporting/regulator/monitoring-evidence` takes a period and answers with the proof an auditor asks for:

- each session's uptime in seconds and as a percentage of the period, and how many times it logged on and off
- the logon and logout history, with the reason recorded for each
- the messages the regulator sent and the platform sent, the session-level rejects, the resend requests and the sequence resets
- the reports in each state, the age of the oldest queued report, the longest wait, and how many reports waited longer than 15 minutes, counted until the report was sent or the period ended
- the alerts the reconciliation raised

The history includes every logon, logout, delay breach and reconciliation alert in the requested period. A report of kind `regulator-monitoring` exports the same evidence across as many pages as the period needs. The [Filings](https://docs.settlemint.com/docs/console/reporting/filings#watch-the-regulator-reporting-evidence) screen shows the last 24 hours.

## Certify the session [#certify-the-session]

The regulator's specification and test endpoint are not part of the platform. The session configuration carries an optional `testProfile` with the same fields as the session, and the obligation version carries the message layout, so both come from the regulator when it supplies them.

`bun run certify` in the reporting app package runs four cases: a new report, a bust report, a rejected report that is corrected and sent again, and a dropped connection followed by a resend. `--target local-acceptor` runs them against a FIX acceptor the script starts, which proves the platform's session logic and not the regulator's. `--target regulator-test` dials the `testProfile` of the session configuration named by `--config`, reading the test credentials from `FSRA_TEST_USERNAME` and `FSRA_TEST_PASSWORD`. It also needs `--reject-source`, a source row the test environment rejects. `--spec` names the message layout and defaults to the platform's default layout. The test sender and target CompIDs must each differ from the live session’s CompIDs. The script keeps the session sequence numbers across the four cases. The disconnect case restarts the client after four acknowledgements and requires a second accepted Logon, a replayed application message with PossDup, and acknowledgements for every report. Coordinate the test endpoint’s resend case before running it. Reconnecting alone does not pass. The script exits with a failure when a case fails.

`--record <apiBaseUrl>` sends the run to `POST /api/v2/reporting/regulator/certifications` with the API key in `DALP_API_KEY`. The caller needs the role that edits obligations. The record keeps the environment, the endpoint, each case and the overall outcome with the obligation version, so a version's certification stays with it. A Reporting reader lists the runs with `GET /api/v2/reporting/regulator/certifications`.

A run against `local-acceptor` is not a regulator certification. Certify against the regulator's test environment once it supplies one.

## What is anchored and what is not [#what-is-anchored-and-what-is-not]

FIX trade reports are not anchored on chain. The evidence of what was sent is the session's message log and its sent log, which keep the exact bytes of each message. A trade journal filing is anchored like any other filing when its obligation has chain anchoring turned on, as [How an anchor proves a filing was not altered](https://docs.settlemint.com/docs/concepts/records-and-evidence/reporting-obligation#how-an-anchor-proves-a-filing-was-not-altered) describes. Contract notes and trade confirmations are a record for the holder, covered in [Investor statements](https://docs.settlemint.com/docs/api-reference/guides/investor-statements).

## Watch the queue [#watch-the-queue]

The [Filings](https://docs.settlemint.com/docs/console/reporting/filings) screen shows a "Transaction reports to the regulator" panel to any Reporting reader once the organisation has a published version that configures a session, a session that has connected before, a queued report or an unmatched answer:

- "Regulator connection" reads "Connected" with "Logged on" and the UTC time, "Disconnected" with "Reports wait until the connection returns", or "Not set up". The platform keeps one session record for each pair of sender and target CompIDs the organisation has used, so an organisation whose CompIDs changed shows one cell for each pair, named by the target CompID.
- "Waiting to be sent" counts the queued reports, with "Oldest waiting" in minutes.
- "Unmatched regulator answers" lists the newest 50 exceptions with the time received, the report each named and the reason.

A session reads as connected while one platform instance runs it and the regulator has accepted its Logon. The same state is available from `GET /api/v2/reporting/transaction-reports/status`, which returns whether a published version configures a session, each session's state and Logon time, the queue count, the age of the oldest queued report, and the newest 50 exceptions. A report's age counts from when it was first queued, so a report queued again after a correction keeps its original age.

Across organisations, the platform publishes the queue size, the age of the oldest queued report, how many sessions are logged on, how many are held, and how many messages were sent, resent and rejected at session level. The metrics carry no organisation label. The alert `TransactionReportsQueuedTooLong` fires when the oldest queued report has waited past the deployment's window, which defaults to 15 minutes and is set with the observability chart value `dalp.observability.transactionReports.queuedWindowSeconds`. The alert `TransactionReportReconciliationBreaks` fires when a break of the recent trading days stays open for 15 minutes, using the `dalp.reporting.regulator_reconciliation_open_breaks` gauge, and its runbook entry is in the observability troubleshooting guide.

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

- `GET /api/v2/reporting/obligations/{obligationId}/versions` returns the published version with the message layout and the regulator session.
- On [Filings](https://docs.settlemint.com/docs/console/reporting/filings), "Regulator connection" reads "Connected".
- "Waiting to be sent" returns to zero after a trade.
- No new row appears under "Unmatched regulator answers".
- `GET /api/v2/reporting/transaction-reports/status` returns the same session state, queue count and exceptions.

## Related pages [#related-pages]

Read [Reporting obligation](https://docs.settlemint.com/docs/concepts/records-and-evidence/reporting-obligation) for how a version freezes its configuration, [Obligations](https://docs.settlemint.com/docs/console/reporting/obligations) for the duty that carries the trade journal, and [Audit trail](https://docs.settlemint.com/docs/concepts/records-and-evidence/audit-trail) to find who corrected or recorded a report.


# Settlement Verdict

Source: https://docs.settlemint.com/docs/concepts/settlement/settlement-verdict
A Settlement Verdict is the recorded end state of an accepted write: completed, failed, dead letter or cancelled. Report success only on completed.



[Figure] Acceptance is a receipt. Only the verdict is an outcome. A client submits an instruction. The platform accepts it and returns an identifier, which proves only that the instruction was durably recorded, not that it worked. The client then observes the request until it reaches one of four end states: completed, failed, dead letter, where the platform stopped before a final result, or cancelled. Those four states are the Settlement Verdict. Only completed reports success. Until one is reached, the correct report is that the operation is still processing. Labels: Client submits an instruction; Platform accepts and returns an id; a receipt that it was recorded, not an outcome; client observes until an end state; Settlement verdict; Only completed reports success.; completed; it worked; failed; it did not work; dead letter; stopped before a; final result; cancelled; stopped before it ran; No verdict yet? Report it as still processing; never success from acceptance, and never wait forever.

Acceptance returns a request identifier, and only a recorded outcome of completed reports success, while failed, dead letter and cancelled do not.

A Settlement Verdict is the platform's recorded outcome of any write it accepts, such as an issuance, a transfer or an XvP approval. Report success only when it reads completed. Every accepted instruction becomes a tracked transaction request that ends in one of four recorded states: completed, failed, dead letter, where the platform stopped before a final result, or cancelled.

An acceptance response proves only that the instruction was durably recorded, not that it worked. Success is read from the verdict alone, and a screen or integration that stops waiting shows the operation as processing and keeps its status link.

The verdict is an application outcome. It does not replace the network's finality rules or the transaction receipt.

## Why a recorded verdict matters [#why-a-recorded-verdict-matters]

A Settlement Verdict separates two events that transaction systems often blur: the platform acknowledging an instruction and the platform confirming its outcome. Acceptance means the instruction is safely recorded. The verdict states what became of it. Key client reporting, statements and downstream money movement off the verdict, and apply the network's finality rules before treating a completed write as settled.

The risk this removes is the false positive: telling a client an asset was issued or a payment settled when the operation later failed. Payment systems keep an acknowledgement distinct from a settlement confirmation, and the platform applies the same distinction to on-chain writes. Integrations should wait for the recorded outcome before reporting that an operation succeeded.

This signal is not particular to one kind of operation. A [custody approval](https://docs.settlemint.com/docs/concepts/custody-and-signing/custody-approval) clearing its wallet, an [XvP settlement](https://docs.settlemint.com/docs/concepts/settlement/xvp-settlement) moving every leg together, a smart wallet deployment, and a corporate action all resolve through the same four states, because each is an accepted write against the platform's transaction state machine. [Asset Lifecycle](https://docs.settlemint.com/docs/concepts/issuing-and-markets/asset-lifecycle)'s own integration contract tells the reader to read the verdict the same way, instead of treating acceptance as completion. The verdict is not one of that page's named stages. It applies across every stage that writes to chain.

Use the verdict to track the platform operation and the network's finality rules to assess chain settlement risk. A recorded application outcome does not guarantee same-day settlement or make a transaction immune to reorganisation.

## Following a request to its outcome [#following-a-request-to-its-outcome]

An operator watches each transaction request toward its verdict. Every accepted write appears as a tracked request with a live status, and the request has finished when the status reaches a terminal value.

While a request is in progress it moves through named working states: `RECEIVED`, `QUEUED`, `AWAITING_WORKFLOW`, `PREPARING`, `PENDING_APPROVAL`, `SIGNING`, `BROADCASTING` and `CONFIRMING`. Platform status shows them as Received, Queued, Waiting for its workflow, Preparing, Waiting for approval, Signing, Sending to the network and Confirming, and shows a dead letter as Stopped after retries. Pending approval is a [custody approval](https://docs.settlemint.com/docs/concepts/custody-and-signing/custody-approval) step where a designated approver authorises the operation. If that approval is declined or expires, the request ends as failed with a matching reason and does not reopen on its own, so submit a fresh instruction with a new idempotency key if the transfer is still needed. When the approval window closes while the custody provider still holds the request, the request ends as dead letter instead, with `mayStillLand` reading `true`, which means the call or the provider's filing can still reach the chain. Wait for it to settle before you submit again. A screen that cannot wait for the verdict shows the operation as still processing, and the request's status keeps following it in the [transaction queue](https://docs.settlemint.com/docs/concepts/settlement/transaction-queue). It never shows success early.

A failed verdict states its reason: a sub-status, an error message, and, when the platform recognises the failure, a decoded explanation with a suggested next step. A failed token create fails its request with the create write's sub-status when the create write itself failed with one. Every other failure that fails the request reads `WORKFLOW_FAILED`: a duplicate create, a later step of a token create, and a price update. A failure whose write may still land does not fail the request, which stays open until its write settles. The recovery sweep then closes the request of an ended token create by the same rule. In every case that fails the request, it keeps the revert bytes of the write that failed. Dead letter means the platform has stopped retrying. While `mayStillLand` reads `true`, a recovery sweep keeps checking the request and settles it once its outcome shows. Otherwise it waits for an operator. Cancelled records a deliberate stop by the requester. Before broadcast it takes effect immediately, unless a custody provider holds the request for approval and has not confirmed its withdrawal. After broadcast it succeeds only if a replacement transaction outruns the original on chain, using the network's replacement-transaction rules. If the original lands first, the request keeps the verdict its execution earned, so a cancel that lost the race is never recorded as cancelled.

Never resubmit an instruction because a wait timed out. Read the verdict first, because a write that later completes would run twice.

[Figure] In progress leads to one of four verdicts. Only a deliberate retry returns it to execution. An accepted request starts in progress. From in progress it ends completed, failed, cancelled, or dead letter. An operator can requeue a failed or dead-letter request back to in progress. A dead-letter request whose call may still land settles later to completed, failed, or cancelled. Nothing else moves a terminal state forward. Labels: accepted; starts; in progress; completed; failed; dead letter; cancelled; operator requeues; force-retry.

In progress leads to one of four verdicts, and only an operator requeue or a late settlement of a dead-letter request moves a terminal state forward.

## How the outcome becomes durable [#how-the-outcome-becomes-durable]

A Settlement Verdict is a terminal state in the platform's own transaction state machine. That state machine is the source of truth for what became of the requested operation. The chain and its finality rules stay the source of truth for whether a transaction is final. Every accepted write is recorded as a request that moves through eight working states and settles into one of four terminal outcomes.

The status read reports the stored request record. It does not query the chain. The receipt for a mined transaction is a separate lookup, used for chain inspection and reconciliation. The two answer different questions: the verdict says what became of the requested operation, the receipt says what one chain transaction did.

Completion is gated on read visibility. After a write confirms on chain, the request stays confirming, with its receipt, until the platform's own index has processed that block, so a caller that sees completed can read the result it produced. A caller waiting synchronously waits at most 99 seconds for the index. Past that bound the write answers with a retryable error that says the transaction settled but its indexed data is not readable yet.

|  | Settlement Verdict | Blockchain receipt |
| --- | --- | --- |
| Is | The platform's terminal state for the whole requested operation. | The chain's record of one mined transaction. |
| Answers | Did the operation complete, fail, or stop? | What did this one transaction do on chain? |
| Use | The outcome that gates workflow progress. | Chain inspection, reconciliation, explorer links. |
| Holds | Failure reason and the operation's result. | Knows nothing of approvals, retries, or the operation. |
| Cardinality | One per request, even across retries. | One per broadcast transaction. An operation may have several. |

_The verdict and the receipt answer different questions. The verdict is the operation's outcome, and the chain keeps its own finality rules_.

Completed and cancelled never change. A failed request can still be recorded as dead letter. An organisation owner or a platform administrator can requeue a failed or dead-letter request straight back into execution. The wallet that sent a failed request can cancel it while nothing was signed. Do not requeue a dead-letter request while `mayStillLand` reads `true`: the call can still land, and a requeue can run it twice. A dead-letter request can also still settle. A recovery sweep settles one whose call may still land to completed, failed, or cancelled once a receipt or the custody provider shows how it ended. The same roles can cancel or force-fail a dead-letter request. Force-fail refuses while the chain or the custody provider shows that the call can still land. Nothing else moves a terminal state. Retries and crash recovery attach to the existing request. The one exception is a write the platform rejected before signing: a retry under the same key starts a new request, and the failed one stays on record.

## The integration contract [#the-integration-contract]

A Settlement Verdict appears on the API as the terminal status of a transaction request. A write returns either a synchronous success carrying the result, or an accepted response carrying the request identifier and a status address. The integration is complete only when the observed status reaches one of the four terminal values.

By default a write returns HTTP 202 with a handle: the request id, its current state, and a status URL. The 202 proves the platform durably accepted the instruction. It says nothing about the outcome, so do not treat it as success. Send `Prefer: wait=N` to wait inline for 5 to 99 seconds. The wait also ends a few seconds before the request's own deadline. Completion within that window returns HTTP 200 with the resource and transaction hashes. Otherwise, the response returns the same HTTP 202 tracking handle. See [Idempotency and async settlement](https://docs.settlemint.com/docs/api-reference/guides/idempotency-async-settlement) for the full header contract, including the hybrid `Prefer: respond-async, wait=N` form.

Poll the status URL until the request is terminal, or open its status event stream. Keep following a dead-letter request while its `mayStillLand` reads `true`, because its call can still land. The stream sends the current state and later changes. It closes at a terminal state, except a dead letter that may still land, or after 180 seconds without a change. Fall back to polling when it closes without a verdict. [Webhooks](https://docs.settlemint.com/docs/api-reference/webhooks) report the platform events your endpoint subscribes to. They do not replace the transaction request's status. A filterable list endpoint in the [API reference](https://docs.settlemint.com/docs/api-reference/v2) supports ad hoc monitoring.

A failed verdict states an error message, a sub-status, and, when the failure maps to a known error, a structured code with decoded arguments and a suggested fix. Per the platform's [error contract](https://docs.settlemint.com/docs/api-reference/guides/errors), branch on the code, not the message text.

A not-found from the status route means the id is unknown or outside your credential's scope. Never conclude from it that the write did not happen. Verify the key, wallet and organisation instead.

The queue attaches a matching submission to the existing transaction request when the [idempotency key](https://docs.settlemint.com/docs/api-reference/guides/idempotency-async-settlement), sender, chain, and wallet selection match inside a 24-hour window. A route may perform other work before queue admission, so repeat an API request only when that route documents replay safety. A fresh key identifies a new instruction.

[Figure] The write either settles inline or hands back a status to poll. A client submits a write. The platform tries to settle it before responding. If it settles within the wait window, the response is 200 OK with the result and the transaction hashes. If it is still settling, the response is 202 Accepted with a request id and status URL, and the client polls that URL, reading the current state again and again, until it is terminal. Either way, the outcome is read from the verdict, never from the response that carried it. Labels: Client submits a write; tries to settle before it responds; 200 OK; settled inline; result and transaction hashes; 202 Accepted; still settling; request id and status URL; Poll the status URL; current state, again and again,; until it is terminal; Either way; the outcome is read from the verdict.

A write either settles inside the wait window or returns a status URL to poll, and the verdict supplies the outcome in both cases.

## Controls and evidence [#controls-and-evidence]

A Settlement Verdict serves compliance as the evidential record of what a submitted operation became. Each request keeps its acceptance time, terminal outcome, time of the last state change, failure detail and linked on-chain transaction hashes, so an auditor can answer what happened, when and why for any write after the fact. An operation that settles inside the synchronous wait leaves the same request record as one that reports back later.

The verdict records what happened. Enforcement lives in the asset's own on-chain rules, which bind a direct call to the contract as much as a platform write. A forced transfer by the asset's custodian skips them, and an address on the compliance bypass list skips the recipient-side checks. When those rules reject a write, the write reverts without moving any balance. The verdict then records a failed state with a structured reason: the party's identity is not registered for the asset, required identity claims are missing or revoked, or a specific rule module blocked the operation. The failing party and wallet are named when the platform can identify them, so the auditor sees which control fired. [Transfer-Path Compliance](https://docs.settlemint.com/docs/concepts/compliance-and-identity/transfer-path-compliance) explains how to resolve each.

An indexed resource read can lag the operation's status. A chain reorganisation can also change indexed activity after completion was recorded. Reconcile a mismatch using the request record and its transaction references.

The status surface also controls what it discloses: a lookup for a request owned by another organisation answers exactly like a lookup for a missing one, so the surface cannot be probed to reveal another organisation's activity.

## Frequently asked questions [#frequently-asked-questions]

### What happens when a broadcast transaction never gets a receipt?

After about two minutes without a receipt, the platform marks the request with the `TIMEOUT` sub-status, which is not a fifth end state: the request stays confirming and the platform keeps watching, so a later receipt still settles it. An automated reconciliation pass, distinct from your own books reconciliation, sweeps up requests that have not moved for five minutes and checks the chain again. A receipt found there completes or fails the request. Finding none, the platform spends the request's retry budget only when the chain shows nothing pending at the request's nonce: it requeues while attempts remain, and ends the request in dead letter once they run out. A dead letter keeps its hash and any custody provider filing. While either can still reach the chain, `mayStillLand` reads `true`, and the recovery sweep settles the request when its outcome shows.

### A completed operation does not appear in reads yet. Did it fail?

No. A completed verdict means the platform's own index has processed the block, but a resource read can still lag the status, or a chain reorganisation can change indexed activity. Poll the read side again, and never treat a stale read as evidence the write failed.

### How is an operation reported when nothing needed to change on chain?

As a completed verdict with no transaction hash. When the requested work was already done, for example when every item in a batch was already registered, the platform records completion without broadcasting anything. A retry of the same instruction then replays that recorded completion instead of executing again.

## Related concepts [#related-concepts]

- [XvP Settlement](https://docs.settlemint.com/docs/concepts/settlement/xvp-settlement): An on-chain exchange between two or more parties whose local legs settle together in one transaction, with a leg on another chain coordinated by a hashlock.
- [Custody Approval](https://docs.settlemint.com/docs/concepts/custody-and-signing/custody-approval): The policy step a transaction request can wait in before signing, where a designated approver or custody provider authorises the operation.
- [Transaction Lifecycle](https://docs.settlemint.com/docs/concepts/settlement/transaction-lifecycle): The one path every instruction takes, the checks, the durable record, and the execution that ends in one of this page's four verdicts.
- [Transaction Queue](https://docs.settlemint.com/docs/concepts/settlement/transaction-queue): The control that dedupes a retried instruction, sequences it against its sender's other writes, and hands accepted work to the execution this page's verdict reports on.
- [Workflow Engine](https://docs.settlemint.com/docs/concepts/settlement/workflow-engine): The durable orchestration that runs a multi-step business process and can wait on a single write's verdict before a step resumes.


# Transaction Lifecycle

Source: https://docs.settlemint.com/docs/concepts/settlement/transaction-lifecycle
The Transaction Lifecycle gives every platform write one auditable path to its outcome, and a same-key retry at the queue attaches to the same record.



[Figure] One governed path, so no write is lost or run twice. An instruction arrives from a person, an integration, or an agent. Before it is submitted, the console runs ordered checks that decide which keys sign and confirm the requester's credential. The platform then writes the instruction down once. That durable record carries it through five steps: accepted and written down, checked and prepared to send, held for approval when policy asks, signed, then sent to the network, and confirmed by the network. Alongside the record sits the requester's wait, which is a separate thing. If the requester is still waiting when the work finishes, the result comes back in the response. If the wait window ends first, a tracking identifier comes back instead and the record continues without them. Either way the path ends at one recorded outcome: completed, failed, dead letter, or cancelled. Labels: An instruction from a person, an integration, or an agent; Before it is submitted; Confirm which keys sign; Verify your credential; The console runs these in order. The platform validates what they produced.; One durable record; Written before anything moves.; Accepted and written down; Checked and prepared to send; Held for approval, when policy asks; Signed and sent to the network; Confirmed by the network; Your wait; Still waiting when; the work finishes; The result comes; back to you.; Your wait window; ends first; A tracking ID; comes back.; Record continues.; Either way, the path ends in the same place.; One recorded outcome; completed, failed, dead letter, or cancelled.

One record carries an instruction the whole way, whether you wait for the answer or leave early.

An instruction is any change the platform makes for you, such as an issuance or a transfer. Every accepted instruction gets one durable record that ends completed, failed, dead letter or cancelled. Completed and cancelled never change, and an administrator can requeue a failed or dead-letter request. A dead letter outcome means the platform stopped sending the call. While its hash or custody provider filing can still reach the chain, `mayStillLand` reads `true` and a recovery sweep keeps checking the request and settles it once its outcome shows. Otherwise it waits for an administrator. At the transaction queue, a matching submission attaches to that record when it repeats the same key, sender, network, and wallet selection within the idempotency window. An API route can do other work before reaching the queue.

You choose how long to wait for the answer. The work is identical either way. Ending your wait early returns a tracking identifier, not a failure.

Signing follows the wallet's own policy, so custody approval is required only when that policy calls for it. The token's own transfer rules run separately, during execution on the network.

## Why one governed path matters [#why-one-governed-path-matters]

The Transaction Lifecycle gives every write the platform accepts one auditable path to its outcome. A restart, or a retry that reaches the queue under the same idempotency key, resumes the record the platform already holds, and a resent call reuses the same signed bytes and nonce, so the chain accepts it once. A second submission under a new key is a new instruction.

The alternative is letting each part of the platform send its own writes to the network. That multiplies the paths an instruction could take to reach the same effect. A path that bypasses this queue is a path where a required check, a custody approval, or a compliance rule never had the chance to run. Every write the platform signs or submits, from every part of the platform, funnels through this same queue, so no platform route skips a platform control. A key holder who calls a contract directly bypasses the platform, and only the contract's own on-chain rules bind that call.

The platform records an instruction before execution runs. A restart or a release part-way through resumes the record it already has, and recovery is bounded, so a persistent infrastructure failure can still end the run as failed.

Report success only after the operation completes, and apply the network's own finality rules separately: application status does not guarantee same-day settlement, and it does not rule out a chain reorganisation.

For an auditor, the record names the requester and the acceptance time whichever platform route was used.

## Running the queue day to day [#running-the-queue-day-to-day]

The [transaction queue](https://docs.settlemint.com/docs/concepts/settlement/transaction-queue) is where an operator meets the Transaction Lifecycle. Every write the platform accepts becomes one tracked request whose named state shows where it is and whether anyone needs to act.

The order is fixed. A request is accepted and queued, then prepared, which is where the platform checks the call and reserves its place in the sending order. If the wallet's policy requires an approval, it waits there until a named approver decides.

A signer then produces the signature, the platform sends the transaction to the network, and a watcher follows it until the network confirms. Only then does the platform record the outcome.

A write the account holder signs outside the platform through [external signing](https://docs.settlemint.com/docs/concepts/custody-and-signing/external-signing) gets a request of its own and joins this order part way. A transaction the holder's wallet already sent starts at `BROADCASTING`, and a user operation its owner signed for the platform to submit starts in the queue.

Most steps run automatically. Custody approval, a funding requirement, or an exhausted recovery budget can require a person to act.

|  | Moves on its own | Waits for a person |
| --- | --- | --- |
| Where | Accepted, prepared, signed, sent, or awaiting confirmation. | Held for a custody approval, or held on an exhausted retry budget. |
| Moved by | The platform's own execution, including its retries. | An approver's decision, or an administrator requeuing the request. |
| If nobody acts | The platform continues execution or recovery. | A missed deadline fails the request, or sends it to dead letter while a custody provider filing stays open. An exhausted retry budget sends it to dead letter. A dead letter whose call may still land settles from the chain or the custody provider. The rest wait for an administrator. |

A wait that runs out is not a failure. When a screen or an integration stops waiting, the request carries on as before, and its status keeps reporting where it is. Never resubmit because a wait ended, because a write that later completes would run twice.

The Submissions tray in the Console and in the Investor portal keeps following the request after the screen stops waiting. **Clear done** removes the completed and cancelled rows from the tray, keeps the failed and in-progress ones, and leaves the requests themselves untouched. Each browser remembers the rows cleared for an organisation for 30 days, so a cleared row stays hidden when the tray reads its requests again.

A cancelled outcome exists only because someone asked for it. Stopping a request while it still waits on the queue, before signing, ends it as cancelled at once. Asking to stop one already broadcast succeeds only if a replacement transaction outruns the original on chain, so the request always keeps the outcome its execution earned. The managed key that signed the write signs that replacement: the sender's own custody wallet, or the organisation's relayer for a relayed write. When the platform holds no managed key for the write, such as a write signed in a browser wallet or sent by a smart account, the cancel is refused and nothing is signed. When a custody provider holds that replacement for approval, the platform withdraws it and refuses the cancel, as [custody approval](https://docs.settlemint.com/docs/concepts/custody-and-signing/custody-approval) explains.

An organisation owner or a platform administrator recovers a failed or dead-letter request by force-retrying it, which requeues the existing request rather than starting a second one. A dead letter whose `mayStillLand` reads `true` can run twice if retried. With no nonce reservation, the platform refuses that retry with `DALP-200383`. The operator can retry through the API with `custodianStopped: true` only when three things hold: no nonce reservation or recorded submitted nonce remains, the chain does not show the call, and the operator has confirmed that the original call was stopped. For a custody call the operator confirms this with the provider. DALP records this operator attestation. It does not verify the stop. This confirmation never overrides a call the chain shows or an unresolved nonce slot. Signed nonce reservations keep their existing settlement checks. The [API reference](https://docs.settlemint.com/docs/api-reference/v2) has the exact endpoint, its parameters, and its error responses.

## Where responsibility changes hands [#where-responsibility-changes-hands]

The path has four layers. Where an instruction sits tells you which layer owns it and what a failure there means.

The first layer is the console, the platform's own operator interface, for instructions that start there. An ordered set of checks there decides which keys sign and confirms the requester's credential before a request is sent. The Console applies that order itself. The platform validates every field it receives, from the console and from a direct integration alike, so neither route is the weaker one.

The second is acceptance. The platform settles who may make the request and which account executes it, then writes the instruction down once. The transaction queue deduplicates a matching submission, as [The integration contract](#the-integration-contract) states.

The third is execution. Preparation, approval, signing, sending, and confirmation all run against that one record, and the run is journaled, so a crash or a deployment resumes the same request. Each accepted instruction ends in one recorded outcome, however many attempts it took.

The fourth layer is read visibility. After the network confirms a write, the platform keeps the request at `CONFIRMING`, with its receipt, until its own [indexed record](https://docs.settlemint.com/docs/concepts/records-and-evidence/ledger-data) has processed that block, and only then records it as completed. A status read never waits for the index: it answers with the stored state, and while an index rebuild holds the request, the answer names the chain and the block the rebuild must pass. A write you are waiting on synchronously waits at most 99 seconds for the index. When the index has not caught up by then, the write answers with a retryable error that says the transaction settled on chain but its indexed data is not readable yet. Read the request status instead of sending the write again.

[Figure] The four layers that own an instruction. Four stacked layers, in order. In the console, ordered checks decide who signs and confirm the requester's credential. The platform receives the fields they produced and validates them. At acceptance, the platform settles authorisation and the executing account first, then writes the instruction down once. A repeat of the same instruction attaches to that record instead of starting a second one. In durable execution, the platform prepares, seeks approval, signs, sends, and confirms against that one record, and a restart resumes it rather than starting a new one. Before the platform reports the request completed, it waits for its own indexed record to reach the confirmed block. A synchronous write waits for that only within a bounded window, and answers with a retryable error if the index has not caught up by then. Labels: Ordered checks decide who signs and confirm your credential.; In the console; The platform receives the fields they produced, and validates them.; Acceptance; Authorisation and the executing account are settled first.; Then the instruction is written down, once.; Durable execution; Prepare, approve, sign, send to the network, confirm.; A restart resumes this record, never a new one.; Before completed is reported; The platform waits for its own indexed record to reach; the confirmed block. A synchronous wait is bounded.; If the index falls too far behind, that wait fails and asks you to retry.

Acceptance is the pivot: the layers before it prepare the instruction, and the layers after it run against a record the platform already holds.

## The integration contract [#the-integration-contract]

A write returns one of two things: the finished result, or a handle to work still in progress. Your integration is complete only when the request's status reaches a terminal value, never when the write call returns.

Asynchronous is the default. A write sent with no stated preference comes back as an accepted response carrying the request's identifier, its current state, and a status address to follow. Ask for a bounded wait instead when your caller can hold the connection open and would rather have one round trip than a poll loop, for example a checkout step waiting on a person. Default to async, and poll or stream the status, when the write can outlast a short wait or your caller cannot hold a connection open, for example a batch job. Either way, the response tells you which one it gave you, so your integration branches on that instead of guessing.

Follow the request's status until it reaches a terminal state: poll the status address on a plain interval, or open its status event stream when you would rather the platform push each change to you. Neither replaces the terminal check, and a stream that closes early is a closed connection, not a stopped request, so poll the status address. A dead letter whose `mayStillLand` reads `true` has not ended yet: keep following it, and do not send the write again. An endpoint subscribed to `transaction.request.*` receives the outcome without polling, as described in [Transaction lifecycle events](https://docs.settlemint.com/docs/api-reference/webhooks/events#transaction-request). The [idempotency and async settlement contract](https://docs.settlemint.com/docs/api-reference/guides/idempotency-async-settlement) has the exact wait windows, status codes, headers, and stream limits, and the [API reference](https://docs.settlemint.com/docs/api-reference/v2) has every field and error this page does not repeat.

At the transaction queue, a matching submission with the same idempotency key, sender, ledger network, and wallet selection inside a 24-hour window attaches to the existing transaction request. Reusing the key with a different wallet selection is rejected outright. An API route can do other work before it reaches the queue, so this rule does not prove the whole route is safe to replay. A key first used more than 24 hours earlier is refused as an idempotency conflict, even for an identical write. Reconcile the earlier request, then send the replacement under a new key.

## Controls and evidence [#controls-and-evidence]

Each write leaves one record that shows who asked, which controls ran and what the network did. The controls fire at fixed points on the path: custody approval before signing, and the asset's transfer rules during execution on the network.

Signing follows the selected wallet's policy. When that policy requires [custody approval](https://docs.settlemint.com/docs/concepts/custody-and-signing/custody-approval), its named approvers must authorise the payload before signing. The asset's own [transfer rules](https://docs.settlemint.com/docs/concepts/compliance-and-identity/transfer-path-compliance) run on the network at execution, and an ordinary transfer that fails one of them reverts. A forced transfer by the asset's custodian skips those rules, and an address on the compliance bypass list skips the recipient-side checks. Both controls apply however the request was authenticated.

A console session carries a further check ahead of both: the requester confirms that specific request with a personal verification code, and the platform verifies it before accepting the write, so a logged-in session alone does not move assets. Repairs are the exception: an organisation owner or a platform administrator can force-retry a failed or dead-letter write without a verification code, and the platform signs and sends it again. A request authenticated by an API credential does not carry that step. The credential itself is what authorises it. That route's equivalent control is how tightly the credential is scoped and how often it is rotated, not a per-request code.

The record is what an auditor reads afterwards. It carries the acceptance time, the requester and the operation kind, such as `token.mint`, with the call it asked for. It also carries each move from one state to the next with its time, the failure reason and its detailed sub-status when a request ends badly, and the network transactions the request produced.

Because every surface passes through the same acceptance step, the evidence is the same whether the instruction came from the console, from an integration, or from an agent. The status surface also limits what it discloses: a request outside the caller's scope answers not-found, exactly as a request that never existed would, so it cannot be probed to map another organisation's activity.

## Frequently asked questions [#frequently-asked-questions]

### What happens if I don't send my own idempotency key?

The platform generates one for you. A later request that also omits the header gets a different generated key. Send your own idempotency key when a route documents replay safety and your integration may need to retry it. On other routes, inspect the original operation and its effects before sending another request.

### What happens when the requested work was already done?

The request completes without sending anything to the network. When every item in an instruction was already in place, for example a batch whose members are all registered, the platform records the completion with no network transaction attached, and a matching retry reuses that same recorded completion.

The [idempotency and async settlement contract](https://docs.settlemint.com/docs/api-reference/guides/idempotency-async-settlement) covers the header names, formats, and edge cases these two questions do not.

## Related concepts [#related-concepts]

- [Transaction Queue](https://docs.settlemint.com/docs/concepts/settlement/transaction-queue): The operational surface of this same lifecycle, where an operator sees a request's state and acts on the ones waiting for a person.
- [Settlement Verdict](https://docs.settlemint.com/docs/concepts/settlement/settlement-verdict): The recorded outcome of an operation the platform accepted, one of four end states, and the only signal from which success may be reported.
- [Custody Approval](https://docs.settlemint.com/docs/concepts/custody-and-signing/custody-approval): The control between a prepared transaction and its signature: when the wallet's policy requires approval, its named approvers authorise the payload before signing.
- [Ledger Data](https://docs.settlemint.com/docs/concepts/records-and-evidence/ledger-data): The platform's queryable record of the ledger networks it follows, which the lifecycle waits on before it reports a request completed.
- [Transfer-Path Compliance](https://docs.settlemint.com/docs/concepts/compliance-and-identity/transfer-path-compliance): The asset's own rules, enforced inside the on-chain transfer itself, which is the last control the lifecycle passes and the one that reverts a non-compliant ordinary movement.
- [XvP Settlement](https://docs.settlemint.com/docs/concepts/settlement/xvp-settlement): An on-chain exchange between two or more parties whose local legs settle together in one transaction, with a leg on another chain coordinated by a hashlock.
- [Workflow Engine](https://docs.settlemint.com/docs/concepts/settlement/workflow-engine): The durable execution layer that resumes a multi-step operation, including this lifecycle's own execution, after a process restart.


# Transaction Queue

Source: https://docs.settlemint.com/docs/concepts/settlement/transaction-queue
The transaction queue lets an integrator retry a blockchain write under the same key, so the retry attaches to the first request instead of filing it twice.



[Figure] Acceptance is not settlement. A submitted write is accepted by the queue, which records intent and deduplicates any retry that reuses the same idempotency key before handing the accepted operation to durable execution. Durable execution broadcasts the transaction and retries it as needed. Only once that work finishes does a terminal settlement verdict report what happened. Acceptance happens quickly. Settlement can take longer, and the two are never the same event. Labels: Submit; a write request; Record intent,; deduplicate retries; Queue accepts; a matching key attaches here; Durable execution; broadcasts, retries; Settlement verdict; reports once; execution finishes; Acceptance happens fast. Settlement can take longer. They are never the same moment.

The queue's own job is acceptance and deduplication, and what settlement means once execution finishes belongs to the settlement verdict.

The queue deduplicates a transaction request that reaches it with the same idempotency key, sender, chain, and wallet selection within 24 hours. A route may do other work before it reaches the queue, so check that route's replay contract and the original request status before resubmitting. See [Idempotent Write](https://docs.settlemint.com/docs/api-reference/guides/idempotency-async-settlement) for the exact replay rules.

Acceptance answers immediately, and settlement is the answer that counts. The queue confirms a submitted write right away, and durable execution broadcasts, confirms, and reports the outcome once the chain settles it, so a fast acceptance is never read as proof the transaction happened.

A stalled or failed transaction is recoverable. Each signing address has its own nonce lane on each network, so one address's stuck write does not block another's. Relayed writes share the organisation relayer's lane, so a stuck relayed write holds up the relayed writes behind it. Automatic recovery resolves transient failures, and an operator can force a retry, a failure, a cancellation or a nonce correction when it cannot.

## Why every write needs a queue [#why-every-write-needs-a-queue]

Every operation the platform performs against a ledger ends the same way: a signed write broadcast to a blockchain. Issuing supply, freezing a holding, paying a coupon, and settling a trade are all, underneath, one more write to a chain that charges gas whether the write succeeds or fails. A caller that resubmits a write because a connection dropped or a request timed out can turn one intended mint, transfer, or freeze into two. A doubled transfer is a real balance change on chain, with a reconciliation gap behind it. The platform signs each write with the managed key it holds for the sender's wallet, or with the organisation's relayer for a relayed write, and a write the holder signs outside the platform is signed and paid for by the holder.

More than one caller can submit work for the same sender at once. An operator working in the Console, an integrating API client, and a workflow step reacting to an earlier event can all sign against the same wallet, on the same chain, in the same minute. Every write from one sender needs a nonce, the wallet's own increasing sequence number, and two writes that reuse the same nonce from the same sender cannot both land: the chain accepts one and rejects the other. Without one place that serialises that sequence per sender and chain, concurrent callers compete for the same slot instead of queuing behind it.

Every accepted instruction needs a durable record of what was asked, what was attempted, and what the chain answered, plus a path back when a transaction stalls instead of confirming.

## Why one queue for the whole platform [#why-one-queue-for-the-whole-platform]

The alternative is each part of the platform that writes to a chain, such as asset issuance, custody, trading settlement and workflow steps, building its own retry, nonce and recovery logic. Each copy would be its own chance to double-broadcast a write or collide two nonces.

The platform instead funnels every on-chain write it signs or submits through this one queue, and a write the holder's own wallet sends is recorded on the queue for confirmation tracking. An instrument's own servicing operations queue the same way a trading venue's settled trade does. [Asset Lifecycle](https://docs.settlemint.com/docs/concepts/issuing-and-markets/asset-lifecycle) has the full list. One deduplication rule and one ordering rule then apply the same way, whichever part of the platform asked for the write.

## Acceptance is not settlement [#acceptance-is-not-settlement]

A fast answer to a submitted write means the platform accepted it, not that the transaction happened. The queue records the intent, attaches a same-key retry to the existing request, and hands the accepted work to durable execution. What happened, confirmed, failed or something in between, is reported separately once execution finishes. Settlement Verdict explains what that terminal report means.

Once a write reaches the queue, a matching submission with the same key, sender, chain, and wallet selection within 24 hours resolves against the existing transaction request. While the work is in flight, the queue attaches to it. Once it has completed, the queue reads back its recorded result. Against a transaction that failed, dead-lettered, or was cancelled, the queue refuses the duplicate key rather than replaying it. For a dead-lettered call that may still land, the refusal says so: do not send the call again until it settles. The one exception is a failed or dead-lettered transaction that the platform rejected before signing, with no nonce, signed transaction, hash, receipt or custody provider filing recorded: the queue keeps the failed row, releases its key, and the unchanged write starts a new transaction request. The same key on a different write is refused as an idempotency conflict: HTTP 409 on most routes, and HTTP 400 with `TRANSACTION_QUEUE_IDEMPOTENCY_CONFLICT` on a token or token-feature write. A write that settles a one-time outcome, such as a maturity, a redemption of a holder's whole balance, a claim or a refund, holds that outcome until its transaction request finishes: a second request for it under another key is refused at once with `TRANSACTION_QUEUE_OUTCOME_IN_FLIGHT`, instead of being accepted and reverting on chain. An operator's force-retry of a failed request is refused the same way while a newer request for its outcome is running. This rule does not cover work an API route performs before queue admission. Check the original outcome and transaction references before starting a new attempt.

## What an operator sees, and one name not to confuse it with [#what-an-operator-sees-and-one-name-not-to-confuse-it-with]

An operator sees the whole queue on the Transactions table of Platform status, an organisation-wide view across every wallet, not only the caller's own. It shows each transaction's status, such as Stopped after retries, the label for a dead letter, `DEAD_LETTER`, with its sub-status on a second line. The Submissions tray follows the requests a user started. When automatic recovery cannot resolve a stuck or failed row, an operator can step in directly rather than wait on the schedule. The levers there are the ones that [What the operator API adds beyond acceptance](#what-the-operator-api-adds-beyond-acceptance) covers.

The Console's Actions page is a separate work list for people: settlement approvals, bond maturity and redemption, votes, KYC updates, and the custody or multisig approvals a queued transaction waits on. Approving one there lets the queued request continue. A runbook about the Actions page does not apply to the transaction queue.

## Ordering, delivery, and what happens when work stalls [#ordering-delivery-and-what-happens-when-work-stalls]

The platform orders execution per sender address and chain ID, through that sender's nonce lane, so a pending nonce for one sender does not hold up another sender's nonce sequence. Shared network or service capacity can still delay both.

Delivery to the chain is at least once, not exactly once: the same accepted row can be resubmitted more than once over its life. The platform checks the row's state and tracks the sender's nonce to coordinate retries and replacements, as [Nonce management](#nonce-management) describes. Those controls do not make an independently submitted request a safe retry. A transaction can stall with no confirmation, or it can fail in a way execution already knows does not change on retry. They end in different terminal states, by different routes and on different budgets. A stalled row is requeued repeatedly by a reconciliation sweep that runs on a five-minute cycle, and moves to Dead letter when its retries run out. A row that fails in a way retrying cannot change records Failed straight away. The recovery-path figure draws both paths, along with the one way an operator can run the row again.

[Figure] Transient and terminal failures take different recovery paths. A transaction anywhere in the queue's pipeline, any state before a terminal one, can fail two ways. One that fails deterministically before it ever broadcasts, an invalid request is one case, is classified immediately and recorded as failed without spending any retry budget. One that stalls with no confirmation past a state-specific threshold is picked up by a periodic reconciliation sweep. That sweep requeues it if retries remain, or moves it to dead letter once the retry limit is reached. Failed and dead letter are terminal states on the queue's own state machine. Neither row requeues itself: only an operator's forced retry requeues it. A dead letter whose call may still land can still close as completed, failed or cancelled once the platform finds its outcome. Labels: In the pipeline; any pre-terminal state; terminal rejection; stuck past threshold; Classified deterministic; for example, invalid input; retry is skipped; Reconciliation sweep; a periodic tick checks stuck rows; retries remain: requeue; retry skipped; retries exhausted; Terminal state; Failed or dead letter; an operator can force a retry; the row never requeues itself; Operator forces a retry; requeues the row as pending.

Failed follows a deterministic rejection and Dead letter follows exhausted retries, and only an operator's forced retry runs either again, as a fresh start.

## Nonce management [#nonce-management]

The transaction queue assigns every nonce itself, from one nonce lane per sender address and chain ID. Two network entries for the same chain ID share the lane. A lane has one owner at a time, and a write from an owner that another process has displaced is refused, so two processes never hand out the same nonce for the same sender.

### How a nonce is reserved and sent [#how-a-nonce-is-reserved-and-sent]

1. **Reserve.** The lane reserves the next free nonce for the transaction and checks it against the chain's own transaction count for the sender. A reservation holds a lease of 2 minutes.
2. **Seal.** The signed transaction is stored with its nonce before the platform broadcasts it. Every resend of a sealed version uses the same signed bytes, so it keeps its nonce and its transaction hash. A fee replacement, described in the next section, signs a new version for the same nonce.
3. **Broadcast.** The transaction engine sends the signed bytes. On a transient node failure it sends the same bytes again, up to 3 more times, after waits of 200, 400 and 800 milliseconds.
4. **Reclaim.** Once a minute, a sweep deletes reservations whose lease expired before the transaction was signed and sent, and the lane takes those nonces back.

The transaction engine's RPC client tries each endpoint once per send. When a send fails on one endpoint in a way that may have reached the node, and the client moves to another endpoint, it marks the outcome as uncertain, because the first endpoint may already have taken the transaction. [How the transaction engine picks an endpoint](https://docs.settlemint.com/docs/deployment/networks#how-the-transaction-engine-picks-an-endpoint) describes that client. The engine then decides from the chain what happened instead of trusting the refusal:

| The node answers | What the engine does |
| --- | --- |
| The transaction is already known | Keeps the transaction hash of the signed bytes and waits for its receipt. |
| The nonce is too low | Looks for a receipt of these signed bytes. With no receipt, it records the outcome as uncertain, because an earlier signature of the same call may have taken the nonce. |
| A refusal such as insufficient funds, a stale fee cap, intrinsic gas too low or an invalid configuration | Fails the attempt. It records the failure as definite only when no earlier send was uncertain and the chain does not show the transaction. |

When the node refuses a transaction before it is sealed because its fee cap is stale, the engine signs it again, up to 3 times.

### Stuck and dropped transactions [#stuck-and-dropped-transactions]

The engine watches every broadcast transaction for its receipt. When a transaction still has no receipt 3 blocks after the engine first saw it pending, or 3 blocks after its last replacement, the engine replaces it with the same nonce at a higher fee. It does this only for an EIP-1559 transaction with no missing lower nonce, on a network with a public mempool, with a fresh market fee quote and a chain head that is not stale. When the sender cannot pay for the replacement, the engine raises a funding request instead. Each replacement bids at least 12.5% more than the previous one, and the engine stops after 3 replacements, or when the next bid would exceed three times the original fee cap, the network's tip ceiling, the market tip envelope or the spending budget. The request settles on whichever version the chain includes.

A transaction that the watcher has polled for 120 seconds with no receipt stays Confirming and gets the sub-status `TIMEOUT`. Its message says which case applies: another transaction already used its nonce, the sender's pending transaction count is higher than its nonce, it is blocked behind a missing lower nonce, or nothing on the chain holds its nonce and the node most likely dropped it. A pending count higher than the nonce does not show that the transaction is still pending, because a Besu node also counts transactions queued behind a missing lower nonce. For that case the message says that the reconciliation sweep checks the transaction by its own hash and reports it as dropped when no node holds it.

The reconciliation sweep runs every 5 minutes. It checks the receipt of a transaction stuck for more than 5 minutes, then requeues it while retries remain, 3 by default, or moves it to dead letter. With no receipt, the sweep first compares the transaction's nonce with the sender's confirmed and pending transaction counts, because filing the call again while the original transaction can still be mined would run the call twice. It requeues the request only when the counts show that nothing is pending at that nonce. The rerun of a signed transaction sends the same stored signed bytes again, with the same nonce and hash, so the call cannot run twice.

When the sender's pending count is higher than the nonce, the sweep asks every configured endpoint of the network for the request's own recorded hashes: the request's transaction hash, the hash of its stored signed transaction and the hash of each recorded fee replacement or cancellation. When an endpoint knows one of them, the transaction is still pending and the sweep leaves the request alone. When every endpoint answers that it knows none of them, the sweep treats the transaction as dropped. It then holds the request on every run while the count stays higher than the nonce: it does not resend the transaction and never files the call again at a new nonce. If the count later falls back to the nonce, the slot reads as free and the sweep requeues the request, which sends the same signed bytes again. It logs `Reconciliation refused to requeue a request whose nonce slot is not free` with the code `exec.nonce.SLOT_REFUSED` and the `hold_reason` `dropped`, the metric `dalp.execution.reconciliation_refused_requeues_total` counts it under the reason `dropped`, and, once holds have continued on every run for about 15 to 20 minutes, the bundled observability stack raises the critical alert `TransactionRecoveryDroppedNonceSlots`. Every later transaction of that sender waits behind the dropped nonce until an operator acts. When several requests of one sender are held as dropped, act on them in nonce order, lowest first, because the chain includes a nonce only after every nonce below it. When an endpoint cannot answer the lookup and no endpoint knows a hash, the sweep holds the request as unresolved and leaves it for the next run. A run gives these lookups a 2-minute budget that only the lookups themselves spend, so an endpoint that never answers cannot hold up the rest of the run: once the budget is spent, the lookup still waiting and every later one count as unanswered, and the run logs `exec.nonce.SLOT_LOOKUP_BUDGET_SPENT`. A run that resumes after a long durable wait starts with a fresh budget. When such holds continue for an hour, for example because one configured endpoint keeps failing the lookup, the bundled observability stack raises the warning alert `TransactionRecoveryUnresolvedNonceSlots`.

The sweep also looks for a wedged lane. A lane is wedged when the sender's pending transaction count has stopped below the next nonce the lane handed out, no request holds the lowest unmined nonce, and that has lasted at least 10 minutes. Pooled transactions that sit beyond the gap do not count as work in progress, even though a node such as Besu reports them as pending. When the request that holds the missing nonce was never signed and sent, the sweep fails that request and fills the gap with a self-transfer that does nothing, so the chain can include the later nonces. A lane it cannot fill is logged as `Nonce lane wedged` with the code `exec.nonce.LANE_WEDGED`, and the metric `dalp.execution.nonce_lane_wedged_total` counts it. A refused fill logs `exec.nonce.LANE_FILL_REFUSED`. A fill that a custody policy holds for approval is refused too: the fill cannot wait for an approver, so DALP withdraws the held request. A fill that sits in the pool because the base fee rose above its fee cap is repriced on the next sweep: DALP signs the same self-transfer with a higher fee, records it as a repricing of that nonce and sends it, up to three times. A fill it cannot reprice logs `exec.nonce.POOLED_FILL_NOT_REPRICED` with the reason.

When a custody provider assigns the nonce itself, the lane does not hold it, and the engine cannot replace a stuck transaction on that lane. DALP cannot cancel such a transaction either. Cancel it at the custody provider.

### What an operator can do [#what-an-operator-can-do]

The holder of the sending wallet can cancel a transaction with `POST /api/v2/transaction-requests/{transactionId}/transitions` and the body `{"action":"cancel"}`. Cancelling a dead letter, and the `fail`, `retry` and `nonce` actions, need an organisation owner or a platform administrator. Before broadcast the request ends cancelled at once. After broadcast, the cancellation replaces its nonce with a zero-value self-transfer that bids at least twice the market fee, or 12.5% more than the last bid if that is higher. When the network sets a tip ceiling and a spending budget, the bid is cut to those limits and to three times the original fee cap. If even the market fee, or 12.5% above the last bid when that is higher, would break a limit, the cancellation is refused and nothing is signed. When a custody policy holds the replacement for an approver, DALP withdraws the held request and refuses the cancellation with code [DALP-14035](https://docs.settlemint.com/docs/api-reference/errors), as [Custody Approval](https://docs.settlemint.com/docs/concepts/custody-and-signing/custody-approval) explains. An operator can also force a lane's next nonce through the same route, with the body `{"action":"nonce","nonce":42,"reason":"Align the lane with the sender's on-chain count"}`. A forced nonce needs a reason, and the lane keeps the last 10 forced values with their reason and time. The [Platform API reference](https://docs.settlemint.com/docs/api-reference/v2) documents both operations.

A transaction that the sweep holds as dropped leaves the operator two ways out. The first is to rebroadcast the request's signed transaction with `eth_sendRawTransaction`. No Platform API returns it, so the deployment operator reads it from the platform's database. When the request has a recorded fee replacement, send the latest replacement, which bids the highest fee. When the request has a recorded cancellation, someone cancelled it: do not rebroadcast the call, cancel the request again, and escalate to engineering if that cancellation is refused. A write that a custody provider signed can have no stored signed transaction, so act on the custodian's record of the request instead. The sweep does not rebroadcast a transaction it holds as dropped. The confirmation watcher can: when the request has a recorded fee replacement, it sends the latest replacement again, and on a network with a public mempool it can replace the transaction at a higher fee. The rebroadcast keeps the original nonce and hash, so the call cannot run twice, but it can land after the caller stopped waiting. Before you rebroadcast, confirm that the caller has not already submitted the same action again under a new idempotency key. The second way out is to cancel the request, which fills the nonce with the cancellation's self-transfer. A node outside the network's configured endpoints, such as a validator, can still hold the dropped transaction, so check that node's pool before you cancel. Force-fail and force-retry, the `fail` and `retry` actions of the same route, refuse a dropped request that has signed or broadcast its transaction with an HTTP 409 conflict whose message names the ways out, including the rule never to rebroadcast a request that has a recorded cancellation.

## What each outcome leaves you [#what-each-outcome-leaves-you]

A transaction has four terminal states. Any other state, such as `QUEUED` or `CONFIRMING`, is still in progress, including after a synchronous wait ends, which only means the wait budget ran out. Execution continues. Completed means the chain settled the work with a recorded outcome. Failed means execution rejected the transaction outright or hit a failure that retrying cannot fix. Dead letter means recovery stopped without a final result, usually because the retries ran out or another call took the nonce. A call that was sent, and whose nonce no other call took, may still land, and so may a call filed with a custody provider. The request's `mayStillLand` field says which: `true` while the call can still land, `false` once it cannot. Cancelled records a stop the requester asked for, before execution finished.

| What you see | What is still possible |
| --- | --- |
| Still pending after your synchronous wait | Read back the status URL the response carried, until the transaction reaches a terminal state. The queue deduplicates a matching submission, but repeat the API request only when its route documents replay safety. |
| Completed | Nothing. The row stays closed, and the platform blocks a forced retry against it. |
| Failed | An operator can force a retry. You can submit a fresh attempt yourself under a new idempotency key. The row does not requeue itself. |
| Dead letter | If the call may still land, the refusal says so: do not send it again, because the platform keeps checking it and reports the outcome when it settles. Ask an operator to close it after a chain or provider check. When `mayStillLand` reads `false`, submit a fresh attempt under a new idempotency key. The row does not requeue itself. |
| Cancelled | The platform blocks a forced retry. A fresh attempt needs a new idempotency key. |

Between force-retry and a fresh attempt, the choice turns on what you have already confirmed. A forced retry keeps the row's identity, its idempotency key included, so it is the right lever when you want the same logical operation to continue under its original name. Only an operator can pull it. Before using a new key, read the original terminal state and inspect its transaction references if the chain outcome is uncertain. Do it earlier and the new key broadcasts independently, even if the original request already succeeded: exactly the hazard the FAQ on resubmitting under a new idempotency key walks through.

A forced retry is not a resume. It requeues the row from the start, clears the recorded error, and resets the retry count, so the row gets a full budget again rather than the remainder of a spent one. That is why it is an operator's decision rather than an automatic one: whatever exhausted the first budget is usually still true.

Nothing about any of this rewrites the row's past. The platform appends each forced transition to the row's own history, so the trail shows the state it came from and the reason the operator gave, and a reopened transaction stays visibly a reopened transaction.

## What the operator API adds beyond acceptance [#what-the-operator-api-adds-beyond-acceptance]

The queue admits one accepted instruction per sender, chain, and idempotency key. A second submission of the same write under the same triple is not an error: it signals that the work already exists, so the queue attaches it to that work rather than broadcasting again. A different write under the same triple, or a key first used more than 24 hours earlier, is refused as an idempotency conflict. The queue follows the exact replay rules in [Idempotent Write](https://docs.settlemint.com/docs/api-reference/guides/idempotency-async-settlement). Once accepted, asynchronous is the default: the call returns immediately with a handle rather than waiting on anything. A caller can opt into a bounded synchronous wait instead, clamped by whatever time the request has left. Past that budget, or by default, the response degrades to an async-accepted handle, the transaction's identifier and a status URL to read it back with, rather than failing the call. A synchronous caller that hits its budget receives a pending result, not a rejection. The exact wait budget and its limits are in [the API reference](https://docs.settlemint.com/docs/api-reference/v2).

The platform classifies deterministic validation or contract failures separately from temporary faults. A recognised gas, account prefund, or paymaster-deposit shortfall is excluded from terminal classification so the funding flow can pause and retry after a top-up. Recovering a stuck, failed, or dead-lettered row outside its automatic recovery is an operator-only step: a force-retry, a force-fail with a recorded reason, a cancel, or a force-nonce correction, each scoped to exactly the failure mode it exists to fix.

## What a stalled or failed transaction does not mean [#what-a-stalled-or-failed-transaction-does-not-mean]

A failed or dead-lettered transaction is not a lost transaction. Its row and its full history persist and stay visible in the operator-facing transaction table until someone acts on it. Reaching either state does not delete evidence of what the caller attempted. A queue timeout on a synchronous call is not a rejection either. The work continues under durable execution, and the platform hands the caller a handle to check later rather than a definitive failure. Reporting either of these as a hard failure overstates what the platform recorded.

The platform scopes a wallet-balance shortfall error to the caller's own resolved executor wallet, never a shared Operator Wallet funded by the platform itself and never another participant's address. That scoping is what keeps a routine gas-shortfall report from becoming an unintended disclosure of a different party's wallet identity.

## Frequently asked questions [#frequently-asked-questions]

### Does resubmitting under a new idempotency key ever create an unwanted duplicate?

Yes. The queue's protection covers a repeated key against the same sender and chain. The platform treats a new key as a new intent, not a retry, so it broadcasts on its own even if the original request already succeeded. If a caller mints a new key without first reading back the original transaction's status, the platform has no way to recognise the two as the same work, and both proceed.

### Does the same idempotency key protect a retry across two different chains?

No. The queue deduplicates on the sender, the chain, and the idempotency key together. The same key on a second network is a different triple, so it starts an independent accepted instruction there rather than attaching to the first network's work. A caller retrying one logical operation across more than one network needs a separate key for each, matching the way the platform already scopes ordering.

### Does forcing a retry give a failed transaction a new idempotency key?

No. A first force-retry applies only once a row has reached Failed or Dead letter. A still-stalled row keeps recovering on the automatic schedule instead. A Dead letter row whose `mayStillLand` reads `true` can run twice if retried. When it has no nonce reservation, force-retry reads the slot and refuses with `DALP-200383` unless no submitted nonce is recorded, the chain does not show the call, and the operator independently confirms that the original call was stopped, with the provider for custody calls, by sending `custodianStopped: true`. DALP records this operator attestation. It does not verify the stop. The confirmation never overrides a visible call or an unresolved nonce slot. A provider filing without a hash or a recorded nonce also needs this confirmation. Signed nonce reservations keep their settlement checks. The platform records the confirmation with the retry and refuses a request that changed during its check. A step of a role set is never retried this way, because it would land alone with no role check, undo or expiry. A new role set repeats the change. If the retry requeued the row but could not start execution, repeating force-retry on that unclaimed Queued row resumes its attempt or starts a new attempt if the earlier run ended. What it does is requeue the same row rather than create a new one, so the row keeps its original sender, chain, and idempotency key. Everything about its execution resets: state, retry count, recorded error, revert and contract or RPC error detail, nonce, signed transaction, hash, confirmation count, and receipt. A gas price in the operator's request replaces the stored one. See [Idempotent Write](https://docs.settlemint.com/docs/api-reference/guides/idempotency-async-settlement) for the wallet-selection fingerprint a requeued row still carries forward unchanged.

### Why can an operator reopen a failed transaction but not a completed one?

Completion means the chain accepted the work, so reopening a completed row would mean broadcasting a second transaction for something that already happened, which is exactly what the queue's replay rules exist to prevent. A failed or dead-lettered row can be requeued after its cause is resolved, except a dead letter whose `mayStillLand` reads `true`. Inspect the recorded transaction and chain receipt first when the actual outcome is uncertain.

## Related concepts [#related-concepts]

- [Asset Lifecycle](https://docs.settlemint.com/docs/concepts/issuing-and-markets/asset-lifecycle): The whole working life of a regulated tokenised instrument. Every servicing operation it describes, issuing supply, freezing a holding, paying a coupon, settling a trade, reaches the chain through this same queue.
- [Transaction Lifecycle](https://docs.settlemint.com/docs/concepts/settlement/transaction-lifecycle): The full state vocabulary a queued transaction moves through, from acceptance to a terminal state.
- [Settlement Verdict](https://docs.settlemint.com/docs/concepts/settlement/settlement-verdict): The terminal report the queue's accepted work resolves to once execution finishes.
- [XvP Settlement](https://docs.settlemint.com/docs/concepts/settlement/xvp-settlement): An on-chain exchange whose legs settle together or not at all. Each leg is still a write that queues and dedupes through this same spine.
- [Workflow Engine](https://docs.settlemint.com/docs/concepts/settlement/workflow-engine): The durable engine whose steps submit their on-chain writes through this queue for deduplication and sequencing, since replaying a workflow step does not by itself make an external write happen once.
- [Idempotent Write](https://docs.settlemint.com/docs/api-reference/guides/idempotency-async-settlement): The idempotency window, the wallet-selection fingerprint, and the exact replay rules behind that guarantee.
- [Operator Wallet](https://docs.settlemint.com/docs/concepts/custody-and-signing/operator-wallet): The platform-funded wallet a gas-shortfall error deliberately never names, as distinct from a caller's own executor wallet.


# Workflow Engine

Source: https://docs.settlemint.com/docs/concepts/settlement/workflow-engine
The Workflow Engine lets a multi-step operation survive a process restart by reusing every recorded step result instead of starting over.



[Figure] A workflow durably tracks each step through completion, waiting, and recovery. An illustrative workflow has four steps. Validation and preparation are complete. Approval is waiting on a decision. Submission has not started. Beside the steps, a journal explains that recorded activity results are reused during replay. Unfinished work can run again. Labels: Illustrative workflow; Validate request; Done; Prepare operation; Done; Approval pending; Step 3, waiting; Waiting for a decision.; Submit operation; Not started; The journal; Recorded activity results; are reused when the; workflow replays.; An unfinished activity; can run again after; a restart.

Validation and preparation are complete and approval waits on a decision, while a restart replays recorded results and can rerun unfinished work.

A multi-step operation, such as an asset deployment or a corporate action, recovers from a crash by reusing the result of every step it recorded. The engine stores each activity's result and reuses it on replay. An activity interrupted before its result was saved runs again, so an external effect needs its own duplicate protection.

The engine tracks a run as running, waiting, suspended, completed, or failed. A run enters waiting for an approval, a threshold, or a timer with a deadline the operation defines, and suspended when an infrastructure retry sequence is exhausted and awaits automatic recovery.

On-chain writes still use the Transaction Queue for deduplication and sequencing. Durable execution alone does not make external effects happen exactly once.

## Why a multi-step operation needs durable execution [#why-a-multi-step-operation-needs-durable-execution]

An operation such as deploying an asset, processing a corporate action, or approving a batch of identity claims is never one call. It chains several steps, each one a separate effect: a custody signature, an on-chain write, a compliance check, sometimes a wait for a threshold or an approval. If the process running that chain restarts before it finishes, nothing outside the platform can tell which of those effects already happened.

A naive retry fails in one of two ways. Restarting the whole operation can resubmit a step that already reached the chain, so an asset deploys twice or a claim is minted twice. Resuming from wherever the process happens to pick back up can skip a step that never ran, so a required step is silently missing from an operation the caller believes is complete. Both mistakes are invisible from outside. The caller sees a result and cannot tell whether each internal step ran once.

The Workflow Engine keeps the steps inside one multi-step operation from running twice or from silently not running at all after a restart.

## Why one recovery layer serves every operation, not one per domain [#why-one-recovery-layer-serves-every-operation-not-one-per-domain]

The alternative is for each kind of operation to carry its own recovery logic, with one retry scheme for an asset deployment, another for a corporate action and a third for a batch of identity claims. Each scheme would answer the same question, whether a given step already ran, in its own way, so recovery would depend on which team wrote the retry code.

The Workflow Engine is shared machinery instead. One execution record and one replay rule serve every domain that runs a multi-step operation, whether it deploys an asset, provisions a custody wallet, or processes a corporate action. An integrator reads the same kind of status and the same kind of recorded evidence whatever operation they started, because the recovery layer underneath does not change.

## What the engine records, and what replay does with it [#what-the-engine-records-and-what-replay-does-with-it]

The engine records each activity's result as it completes. A restarted process replays the workflow's code from the top, but a completed activity returns its stored result instead of running its work again. An activity interrupted before its result was saved executes again.

Replay only guarantees the workflow's own bookkeeping. It says nothing about the business outcome of an external effect, so external effects still need their own duplicate protection, including writes submitted through the Transaction Queue. A stored result does not prove every business outcome was successful. Read the operation's result and any failure details before reporting success.

## Running, waiting, and suspended are different states [#running-waiting-and-suspended-are-different-states]

A running workflow executes its next activity. Waiting means the operation needs a condition such as an approval, funds, or a timer. It can continue when that condition is satisfied. A deadline can end a wait, but the workflow decides what happens when the deadline expires.

Suspended means an infrastructure failure exhausted the activity's immediate retries. The platform schedules further recovery attempts with backoff, and persistent failure can end the run as failed. When an incident prevents progress, restore the unavailable dependency.

A Canton submission behaves the same way. When the participant is unreachable or answers with a retryable error, the submission suspends and the platform runs it again later instead of failing it. If every recovery attempt fails, a submission that never reached the ledger ends as failed with the code `canton.submission.REDRIVE_EXHAUSTED`. A submission the ledger may already have run is not failed. The platform holds it and, on each later attempt, first reads the ledger's completion for the command: a successful completion settles it, a rejection fails it with the ledger's reason, and no completion once the command's validity window has closed expires it. It never signs the command again or releases funds while the outcome is open. Operators see a held submission through the `CantonSubmissionInDoubt` alert and the `canton.submission.IN_DOUBT` log line, and resolve it by restoring the participant so its completion can be read.

Completed and failed are terminal workflow statuses. They describe the workflow's outcome. Waiting and suspended are non-terminal. Status projections can lag during a database outage, so a stale running status does not prove that an activity is still executing.

[Figure] A workflow moves between running and one of two terminal statuses, pausing on waiting or suspended along the way. Running executes the workflow's steps and leads to one of two terminal statuses, completed or failed. A step can pause the workflow into waiting, deferred on an approval, a threshold, or a timer, which resumes running once its condition is met. Separately, a run can land in suspended when its retry ladder runs out, and the platform's own resume pass automatically redrives it back to running. Both pauses return to running rather than ending the workflow. Labels: Workflow status flow; Running; executes the next activity; Waiting; paused on an approval,; threshold, or timer; resumes running when met; Suspended; infrastructure retries spent,; awaits automatic recovery; bounded recovery attempts; Completed; workflow returned a result; Failed; a step could not complete.

Running leads to completed or failed, and a step can pause it into waiting, or the platform can park it as suspended, with both pauses returning to running.

## When an operation pauses for funds [#when-an-operation-pauses-for-funds]

An operation configured to wait for gas funding pauses the affected step when the paying wallet has insufficient funds. The work recorded before that step remains available for replay. The funding request identifies the wallet or deposit to fund, the required amount, and the deadline.

The amount required to retry the refused operation controls when it can resume. The operator may also see an estimate for the remaining work. That estimate helps plan funding but does not raise the resume threshold.

Fund the destination shown in the request. An ordinary signing account or a self-funded smart account uses an address balance. A paymaster uses its deposit in the EntryPoint contract. Funding the paymaster address alone does not increase that deposit.

A balance observation and a transaction broadcast can use different network nodes. A deposit visible to one node may take time to reach another. The platform makes bounded broadcast retries after funding. A repeated rejection does not always mean another deposit is needed.

When the funding deadline expires, read the recorded error, fund the requested destination, and start a new attempt as the operation's API specifies. Operations that do not enable the funding pause fail with [`GAS_REQUIRED`](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference#dependency-errors), which identifies the funding shortfall.

## The engine and the API run separately [#the-engine-and-the-api-run-separately]

The API hands durable work to the Workflow Engine, which runs in a separate process. The engine uses database-backed execution records to recover after a restart, so recovery waits for that database when it is unavailable. Its availability and capacity can therefore differ from the API's: an accepted request can remain in progress while the engine recovers.

**Workflow Engine**

Coordinates activities and stores their results for replay. Its result describes the multi-step operation.



**Transaction Queue**

Deduplicates, sequences, and executes the on-chain writes submitted by activities. Each write has its own outcome.

## Follow the operation's status contract [#follow-the-operations-status-contract]

An asynchronous start returns an operation identifier or status link. Acceptance means the platform accepted the request for processing. It does not mean the operation finished. Use the status endpoint returned by that operation and interpret its documented states.

After a lost response, inspect the original operation before sending another request. Repeat the API request with the same [`Idempotency-Key`](https://docs.settlemint.com/docs/api-reference/guides/idempotency-async-settlement) only when its route documents replay safety. In the Workflow Engine, reusing the key does not create a fresh attempt after a terminal failure. Correct the failure's cause before starting a new business attempt with a new key.

A client polls until the operation reaches a documented terminal state. Read the resulting resource after success. A pending operation does not promise that a separate resource read contains its changes.

For operational monitoring, the Workflows panel on the Console's Platform status page shows workflow health, as [Platform Health](https://docs.settlemint.com/docs/concepts/operating/platform-health) describes. That view complements the status endpoint used by the integration. It does not replace the operation's result.

## Recovery records and audit evidence [#recovery-records-and-audit-evidence]

The execution journal records activity results needed for recovery. It has a retention policy and does not replace the platform's Audit Trail, the append-only record of who did what and when, or your compliance archive. Retain the operation identifier, transaction references, approvals, and other evidence your policy requires.

A workflow's recorded decision also does not prove that a token transfer passed compliance. The token's transfer checks decide whether its balances may change. Read the write's Settlement Verdict, the typed terminal outcome recorded for that on-chain write, to establish the on-chain outcome.

A failed workflow exposes error information through its operation's status contract. Read the error code and retry guidance before deciding whether to change the request, restore a dependency, or escalate.

## Frequently asked questions [#frequently-asked-questions]

### Can a workflow wait indefinitely?

Yes, if its wait has no deadline. Durable execution preserves the wait and imposes no universal time limit. Check the deadline the operation you are integrating documents for its wait, and design an approval or funding process around it.

### Does completed mean everything the operation requested succeeded?

Read the operation's result. A workflow can complete after recording a business rejection or a partial outcome that its own contract permits. The workflow status alone does not describe each external effect.

### Should I restart a suspended workflow manually?

The platform schedules recovery attempts for infrastructure suspension. Check dependency health and the operation's recorded details before starting another request. A second request with a new key can create separate work while the original run is still recoverable.

## Related concepts [#related-concepts]

- [Asset Lifecycle](https://docs.settlemint.com/docs/concepts/issuing-and-markets/asset-lifecycle): The whole working life of a regulated tokenised instrument, where the deployments, corporate actions, and other multi-step operations this engine recovers run.
- [Transaction Lifecycle](https://docs.settlemint.com/docs/concepts/settlement/transaction-lifecycle): The path one on-chain write follows once a workflow activity submits it through the Transaction Queue, from its pre-checks to one recorded outcome.
- [Transaction Queue](https://docs.settlemint.com/docs/concepts/settlement/transaction-queue): The separate control that dedupes, sequences, and gates the on-chain writes a workflow step submits.
- [XvP Settlement](https://docs.settlemint.com/docs/concepts/settlement/xvp-settlement): An on-chain exchange between two or more parties in which every leg settles together or none does, a sibling settlement primitive in this same category.
- [Settlement Verdict](https://docs.settlemint.com/docs/concepts/settlement/settlement-verdict): The typed terminal outcome a single on-chain write reaches, distinct from a workflow's own typed outcome.
- [Custody Approval](https://docs.settlemint.com/docs/concepts/custody-and-signing/custody-approval): One concrete source of the approval a workflow step can wait on before resuming.
- [Idempotent Write](https://docs.settlemint.com/docs/api-reference/guides/idempotency-async-settlement): The Idempotency-Key mechanism a workflow's start request carries, so a retried start under the same key attaches to the first workflow.


# XvP Settlement

Source: https://docs.settlemint.com/docs/concepts/settlement/xvp-settlement
XvP Settlement lets two or more parties exchange tokenised assets without either side delivering first: local legs settle atomically, external legs by hashlock.



[Figure] Two legs cross inside one transaction. The bank brings bond tokens and the investor brings cash tokens. Each approves and escrows its own leg into the settlement contract, which holds both. Inside the contract the two legs cross at a single execute step: that one step delivers the cash to the bank and the bond to the investor together. This local-only example cannot execute without both approvals or after the deadline. Senders can claim refunds. Token restrictions can defer delivery. Labels: Bank; brings the bond tokens; Investor; brings the cash tokens; approves and escrows; approves and escrows; Settlement contract · one transaction; Bond leg, escrowed; Cash leg, escrowed; execute; both legs, one step; Bank gets the cash; Investor gets the bond; Otherwise nothing moves; If either leg is never escrowed, or the deadline passes first,; execute never runs and every sender recovers its own leg.

This local-only settlement executes both net deliveries in one transaction, and a failed delivery reverts execution.

A local-only XvP settlement nets every position and delivers it inside one transaction, or the whole settlement reverts. Once a revealed hashlock secret commits a settlement with an external leg, a delivery the token refuses is parked for its recipient to claim, and every other delivery still completes.

Each sender approves, which locks their assets in the settlement contract. Execution then moves one net amount per participant per asset.

The cutoff date lets an uncommitted settlement refund. Revealing a valid secret commits it and closes that refund path. When a leg lives on another chain, a hashlock coordinates its release through a shared secret, and the parties verify the external lock, the deadlines, and execution on each system themselves.

## Why an exchange needs to settle without principal risk [#why-an-exchange-needs-to-settle-without-principal-risk]

Two parties agree to exchange tokenised assets, a bond for cash, or one currency token for another. Whoever delivers first is exposed until the other side pays, and the other side may never pay. For legs on this platform, XvP Settlement removes that exposure by making both deliveries depend on the same transaction. For a leg on another system, a hashlock coordinates release and the parties carry the remaining risk.

One primitive covers two exchange shapes market practice names separately. Delivery versus payment (DvP) moves a security against a cash token. Payment versus payment (PvP) moves one cash asset against another. XvP, X versus payment, is the umbrella term, where X stands for whichever asset is the variable leg.

Industry practice calls the exposure this removes principal risk: the loss a party takes by delivering its share of a trade before receiving the other side. Conventional markets manage it through central infrastructure and a settlement delay after the trade. For local-only execution, the contract applies every net delivery inside one transaction. Approval escrows a sender's net contribution until execution runs or an available refund path releases it. A settlement still needs planning for locked capital, for a token's own restrictions, and for the contract and network risk any on-chain operation involves.

When a leg lives on another chain or an external system, a hashlock coordinates release through a shared secret instead of one shared transaction. That does not place both systems inside one atomic operation. The parties verify the external lock, the deadlines, and finality on each side before anyone reveals the secret. The platform does not price the trade or prove that an external leg completed, and the settlement contract charges no settlement fee. Those stay with the parties' own commercial and reconciliation processes.

## Why this settlement runs on the platform, not beside it [#why-this-settlement-runs-on-the-platform-not-beside-it]

The alternative is settling beside the asset: a bilateral escrow agent, a correspondent-bank DvP link or a private clearing arrangement holds both legs until it decides to release them. That arrangement needs its own view of who may hold and receive the traded assets, kept separately from the token's own compliance rules, because it is a different system deciding on a movement it does not itself control. That gap is a seam: a delivery the escrow arrangement allows and the token's own compliance would have refused.

Until a revealed secret commits the settlement, every local flow of a token with compliance rules is re-checked against those rules at execution, the same check an ordinary transfer passes. A plain ERC-20 asset has no compliance contract and is not checked. Settling trades sits in the Service stage of the [Asset Lifecycle](https://docs.settlemint.com/docs/concepts/issuing-and-markets/asset-lifecycle), next to paying coupons, freezing holdings and collecting fees. A delivered settlement is a normal, compliance-checked transfer, so it lands in that asset's own record the same way every other servicing operation does.

Escrowed assets sit in the settlement contract, not in a platform or counterparty wallet, and the contract releases them only through execution or a refund path. Other controls still reach them. A holder of the System manager role can point every settlement of a factory at new contract logic, because each settlement reads its logic from the factory on every call. The asset's Custodian can force a transfer out of the settlement address or freeze it, and the asset's Emergency role can pause the token, which stops execution and refunds for that asset.

## Running a settlement day to day [#running-a-settlement-day-to-day]

An XvP settlement is one record that carries an exchange from proposal to its end. In the Console you work it from [Settlements](https://docs.settlemint.com/docs/console/my-assets/settlements). You create it, collect an approval from each sender, and watch it finish in exactly one of three states: executed, cancelled, or expired when the cutoff date passes.

You list every flow at creation: which asset moves, from whom, to whom, how much, and the cutoff date. Approval is collected sender by sender, so a settlement reads Pending while it collects approvals and can sit partially approved, and each approval is the step that locks that sender's assets into escrow. The platform first grants the settlement contract an ERC-20 allowance on each asset where the sender's current allowance falls short of the net amount it locks, then approves. A contract call that arrives with too little allowance answers [DALP-1105](https://docs.settlemint.com/docs/api-reference/errors/error-code-reference#compliance--token-operations), and raising the allowance and retrying clears it. Once every sender has approved, the settlement reads Ready, or Waiting for secret while a secret reveal is outstanding. After the reveal it reads Ready after reveal. Execution is its own step, which any account can trigger, and an optional auto-execute can fire it the moment it becomes ready.

A local participant is a party to a leg that settles on this platform. Three exits protect the parties if the exchange never completes.

- **Revoke.** Before execution, a sender can revoke their own approval, which returns that sender's escrowed assets. On a settlement with an external leg, revocation closes once every sender has approved.
- **Cancel.** Any local participant can cancel the whole settlement before execution. Once a settlement with an external leg is fully approved and waiting for its secret, cancellation instead needs a unanimous vote of the local participants.
- **Withdraw after the cutoff.** The cutoff date is a hard deadline: a settlement that has not executed by then can no longer execute. One withdrawal then refunds every participant exactly what they locked, and any account may send it. A second withdrawal against the same settlement is refused with [DALP-2007](https://docs.settlemint.com/docs/api-reference/errors/error-code-reference#settlement--xvp). The one exception is a settlement already committed by a revealed secret, which stays executable past the deadline, as [How it works and what it covers](#how-it-works-and-what-it-covers) explains.
  A token that refuses one participant's refund parks that refund in the settlement until the participant claims it to a receiver the token accepts, and the other refunds complete. Committed settlements remain outside the expiry refund path.

The cutoff date must sit strictly after the moment you create the settlement. The factory checks that at creation and answers [DALP-2011](https://docs.settlemint.com/docs/api-reference/errors/error-code-reference#settlement--xvp) when it does not. Set it too soon and it can pass before every sender approves, and there is no extension: you create a fresh settlement with a new deadline. Set it too far out and the first sender to approve leaves its assets in escrow for that whole window, whether or not anyone else acts. Size it to how long the parties need to approve.

[Figure] A settlement moves from pending through approval to a terminal state. A settlement starts pending while it collects approvals. Once every sender has approved it becomes Ready, or Waiting for secret if it still needs a secret reveal. A revealed secret then makes it Ready after reveal. From Ready or Ready after reveal, execute settles it, past the cutoff once the secret is revealed. Before execution a settlement can also end early: pending or ready, any local participant can cancel it, or the cutoff date passes and it expires. While it waits for the secret, cancelling instead needs a unanimous vote, and an unrevealed cutoff expires it. Labels: Pending; collecting approvals; Ready; ready to execute; Waiting for secret; every sender approved; Ready after reveal; open past the cutoff; all senders approved; local only; all senders approved; external leg; secret revealed; Executed; net settlement recorded; execute; execute,; past cutoff; Cancelled; Other exits, before execution; Pending or ready: a local; participant cancels.; Waiting for secret:; needs a unanimous vote.; Expired; Pending or ready: the; cutoff date passes.; Waiting for secret:; an unrevealed cutoff; expires it.

A settlement starts Pending, becomes Ready or Waiting for secret once every sender approves, and ends Executed, Cancelled or Expired.

## How it works and what it covers [#how-it-works-and-what-it-covers]

Each XvP settlement is its own dedicated escrow contract, and any user can create one from the system's XvP factory, except a participant whose account restricts securities transfers. Creation moves nothing on its own. Assets enter escrow only when each named sender approves and deposits its own leg, so naming a party in a settlement gives that settlement no claim on their assets until they act themselves. That contract is the settlement source of truth for the local flows, approvals, deadline and outcome.

Execution settles net positions rather than one transfer per flow. For each asset, the contract computes what each participant pays minus what they receive across all local flows. Net payers are debited from their escrow, net receivers get one delivery, and a participant whose flows cancel out moves nothing. Per asset, all net positions must sum to zero. If they do not, the settlement fails closed and answers [DALP-1068](https://docs.settlemint.com/docs/api-reference/errors/error-code-reference#compliance--token-operations). Escrow follows the same arithmetic: approval locks exactly the sender's net requirement per asset, so a participant whose flows offset locks nothing yet still must approve.

One check gates every payout. Before moving any funds, the contract verifies that each approved sender's escrowed amount exactly matches that requirement. A mismatch stops execution before anything moves: every escrow stays in the contract, and participants recover it through whichever exit still applies, revocation, cancellation, or withdrawal after the cutoff.

| Participant | Gross flows | Net settlement |
| --- | --- | --- |
| A | 100→B, 40←C | +60, debited 60 |
| B | 100→C, 100←A | 0, nothing moves |
| C | 40→A, 100←B | -60, delivered 60 |

_Gross flows, where → pays and ← receives, collapse into one net amount per participant: positive for a net payer whose escrow is debited, negative for a net receiver who is delivered that amount. The column must sum to zero per asset, or the settlement fails closed_.

Before hashlock commitment, a failed delivery reverts the whole execution transaction. A committed settlement can park a blocked delivery for a later claim while completing its other net deliveries. A leg on another chain or system is coordinated rather than executed: the contract stores a hashlock, and the local legs settle only after the matching secret is revealed before the deadline. The external system runs its own locking and release against the same hashlock. This platform never controls that leg.

Revealing the secret commits the settlement. From that moment cancel, refund, and expiry all close, and execution is allowed even after the deadline, so a revealed secret cannot leave the local leg stranded or refunded while the external leg is claimed against it. Execution after the deadline and parking of a blocked delivery or refund come with version 4 of the settlement logic. Each settlement runs whatever logic its factory points at, and a System manager can repoint a factory, which changes the rules for settlements already open. A factory still on an earlier version reverts the whole execution on a failed delivery and cannot execute after the deadline.

Any account can trigger execution. Completion still depends on successful transaction submission and the contract's execution checks. The parties set the deadlines across legs so that a leg that consumes the secret later stays open longer.

## The integration contract [#the-integration-contract]

On the API, an XvP settlement is one object with a small verb set: create, approve, execute, store, decrypt and reveal a secret, revoke approval, cancel or vote to cancel, withdraw after expiry, and claim a parked amount. You create it once with every flow it settles, collect an approval from each sender, and read its outcome from the settlement's own state. Only the wallet that created the settlement can store its secret. The platform seals the secret under that wallet's signature, so only that wallet can decrypt it again. On chain, anyone who presents the secret can reveal it once every sender has approved and before the cutoff date.

You create a settlement from a flows array, and an empty one answers [DALP-2012](https://docs.settlemint.com/docs/api-reference/errors/error-code-reference#settlement--xvp). Each local flow names the asset, sender, recipient and amount, and it executes on the platform. An external flow is a coordination reference to a leg elsewhere: it adds an external chain id and the external asset's decimals, and the platform records it but never executes it. A settlement that includes an external flow must be created with either a raw secret or a precomputed 32-byte hashlock, or creation answers [DALP-2010](https://docs.settlemint.com/docs/api-reference/errors/error-code-reference#settlement--xvp). Local-only settlements need neither.

Approval is per sender, and each approval escrows that sender's assets. Execution succeeds only when every sender has approved, and, for a settlement with external flows, only after the secret has been revealed.

Auto-execution at creation is optional and off by default: with it off, revealing the secret makes the settlement ready, but execution is a separate call you make. With it on, execution fires the moment the settlement becomes ready.

Read outcomes from the settlement's state, never from a request's acceptance. An accepted create or approve call means the platform durably took the request, and the request's own outcome is recorded as a Settlement Verdict. The exchange itself has settled only when the settlement reports its executed state. The other terminal states, cancelled and expired, are equally final.

[Figure] Creating a settlement through to its terminal state. The integrator creates a settlement, and the platform deploys it as its own contract. Each sender approves in turn, and each approval escrows that sender's leg. When a hashlock applies, the integrator reveals the secret before triggering execution. The integrator then calls execute, the platform submits execute to the settlement contract, and the contract reports back a terminal state, which the platform relays to the integrator. Labels: Integrator; Platform; Settlement; create settlement; deploy the settlement contract; approve, one call per sender; escrow that sender's leg; OPT; [hashlock applies]; reveal secret; execute; execute; terminal state; terminal state.

The platform submits each call to the settlement contract: create, approve per sender, reveal if a hashlock applies, execute, then read the terminal state.

## When a corporate action changes the escrowed token [#when-a-corporate-action-changes-the-escrowed-token]

A stock split, bonus issue or other [corporate action](https://docs.settlemint.com/docs/console/asset-management/manage/corporate-actions) that changes every holder's units by a ratio also changes what a settlement escrows. The platform sizes the settlement's units from its per-owner deposits, and the action mints to or burns from the settlement the sum.

From the action's record date until its step lands, the settlement refuses new deposits, revealing a secret, settling, and also cancelling, withdrawing and refunding when one of its flows is in that token. Participants cannot cancel, withdraw or refund until the step lands. Then the step cancels a settlement that is still open and refunds every deposit on the new basis. A settlement whose secret has been revealed is committed, so it settles its flows re-based by the action once the step has landed. A settlement cancelled before the freeze stays cancelled.

## Controls and evidence [#controls-and-evidence]

For a control function, an XvP settlement is an escrowed exchange whose enforcement point is execution, the moment assets change hands. Until a revealed secret commits the settlement, every flow of a regulated token is re-checked against that token's transfer restrictions at that point, not only at approval, and the on-chain settlement record is the audit evidence for the exchange.

The re-check closes the timing gap: a participant who passed eligibility checks at approval but lost them before settlement, for example through a sanctions hit or a revoked verification, cannot receive assets. For an uncommitted settlement, a failed check reverts execution and nothing moves. A committed settlement skips the re-check, because it can no longer refund. A delivery that the token itself refuses is parked for the recipient to claim later, and the other deliveries complete. The re-check runs on every local flow as you wrote it: the flow's sender, its recipient and its full amount, checked against the token's compliance rules before any net delivery moves. The settlement contract sits on the compliance bypass list, so a deposit into escrow skips the recipient-side checks. Execution restores them: before a settlement is committed, the contract checks every local flow from its sender to its recipient and refuses a recipient on the bypass list. After a revealed secret commits it, that per-flow check is skipped, and only the token's own check on the payout from the settlement contract applies.

Before a settlement is committed, enforcement is atomic: a flow that fails its check stops the whole settlement and no assets move. Parking applies in two places. In refunds, one blocked address must not freeze every other participant's money. During delivery after a secret reveal, unwinding is no longer possible. A freeze of the settlement contract's own address, or a pause of the token, still blocks every participant's delivery and refund for that asset until it is lifted. In both cases the blocked leg is parked for the affected participant to claim separately to a permitted address, while every other participant's settlement or refund proceeds. The participant claims it with "Claim parked amount" under the settlement's "Actions" menu, in the Console or the Investor portal, or through the Platform API with `POST /api/v2/addons/xvp-settlements/{settlementAddress}/parked-claims`. The claim names the receiving address, which defaults to the claiming wallet. A wallet with nothing parked is refused before anything is sent, with [DALP-3028](https://docs.settlemint.com/docs/api-reference/errors/error-code-reference#airdrop--distribution). A receiving address the token refuses moves nothing, and the participant can claim again to another address. An amount parked before the platform began recording parked amounts stays claimable only on chain, by calling `claimRefund` or `claimSettled` on the settlement contract directly.

Evidence is on-chain and per settlement. The settlement record shows the flows as written, plus every approval, the deadline, and the terminal outcome. Events timestamp approvals and revocations, the secret reveal, cancellations, execution, refunds, parked deliveries and their later claims. An auditor can reconstruct who committed what and when, and how the exchange ended, without relying on off-platform logs.

## Frequently asked questions [#frequently-asked-questions]

### Can a settlement be made up entirely of external flows?

No. Every settlement needs at least one flow whose sender is on this chain. A flow list made up entirely of external-chain legs fails at creation and answers [DALP-4242](https://docs.settlemint.com/docs/api-reference/errors/error-code-reference#system--infrastructure). The requirement exists because local flows are what give the settlement contract an on-chain participant to escrow assets and to trigger execution. An all-external settlement would have no one able to act on it. Use this settlement contract only when the exchange includes a real local asset flow.

### Who signs an approval, and who holds the escrowed assets?

Each approval is an on-chain transaction sent from your wallet's address. For a managed wallet, the platform signs it with the key it holds for that wallet once you confirm with your wallet verification: a PIN, a one-time code or the wallet's configured signing method. Escrowed assets are held by the settlement contract, not by the platform or by any counterparty, and the contract releases them only through execution or a refund. The overrides under [Why this settlement runs on the platform, not beside it](#why-this-settlement-runs-on-the-platform-not-beside-it) still reach them.

### Who pays the transaction costs?

The settlement contract charges no settlement fee. Transactions still consume gas. The selected signing and sponsorship configuration determines whether the participant, relayer, or sponsor funds it. A participant without sponsorship may need the chain's native token.

### Does the record show my trades as written, or only the net amounts?

Both, in different places, and each serves a different check. The settlement stores every flow exactly as you created it, asset, sender, recipient, and amount, so a trade ticket reconciles line by line against that record rather than against a derived figure. Execution then moves only the net amount per participant per asset, so what the chain transfers is the netted position, not the gross flow list. Build reconciliation against the stored flows, and treat the net movements as a separate, computed check, not the source you match trade tickets to.

### Which hash function produces the hashlock?

keccak256, the EVM's native hash function. The hashlock is the keccak256 hash of the secret, and the contract accepts a reveal only when the hash of the presented secret matches. An external system pairing a leg with this platform must lock against the same keccak256 hash. A system that supports only SHA-256 cannot reuse the same hashlock value. Any design using different hashes of one secret needs separate coordination review.

### Is this a clearing house?

No. There is no central counterparty taking the other side of the trade, and no intermediary pools assets across parties: each settlement is its own dedicated escrow contract, and the parties settle directly with each other through it. A settlement nets flows only within itself. It does not net exposures against any other settlement or any other pair of parties. The platform submits transactions, the token and settlement contracts enforce the compliance checks on chain, and the settlement contract holds escrowed assets.

## Related concepts [#related-concepts]

- [Asset Lifecycle](https://docs.settlemint.com/docs/concepts/issuing-and-markets/asset-lifecycle): The whole working life of a regulated tokenised instrument, from issuance through servicing to redemption. Settling trades is one of the operations this settlement performs inside that same life.
- [Transaction Lifecycle](https://docs.settlemint.com/docs/concepts/settlement/transaction-lifecycle): The one path every EVM instruction takes, the checks before sending, the durable record, and the execution to one recorded outcome. Every settlement call rides this path.
- [Transaction Queue](https://docs.settlemint.com/docs/concepts/settlement/transaction-queue): How the platform queues, retries, deduplicates, and reports a submitted write between acceptance and a settled on-chain fact.
- [Workflow Engine](https://docs.settlemint.com/docs/concepts/settlement/workflow-engine): The durable execution record behind a multi-step operation, which is why a settlement's own approve, reveal, and execute steps can recover after a process restart.
- [Settlement Verdict](https://docs.settlemint.com/docs/concepts/settlement/settlement-verdict): The recorded end state of an on-chain operation submitted to the platform (completed, failed, dead letter, or cancelled), and the only signal from which success may be reported.


# Asset classes

Source: https://docs.settlemint.com/docs/console/asset-design/asset-classes
Manage the business categories that organise instrument templates and decide where issued assets appear.

Asset classes are the business categories, such as Fixed income or Cash, that organise your product catalogue. The classes you keep visible decide what the rest of your organisation sees: the classification choices when someone designs an instrument template, the groups of the template catalogue, the entries under **Assets** in the sidebar, the "Value by asset class" chart on [Asset insights](https://docs.settlemint.com/docs/console/asset-management/insights) and on the "Insights" tab of [Portfolio](https://docs.settlemint.com/docs/console/my-assets/portfolio), and the "Allocation" block on the portfolio [Dashboard](https://docs.settlemint.com/docs/console/essentials/dashboard). A class never changes how an issued token behaves. Compliance and settlement read the token's own policy and features.

Open this screen to plan the catalogue before your organisation designs instrument templates, or when your product lineup outgrows the categories the platform ships with, for example when private credit needs its own grouping. Issuing an asset does not need it, and the template wizard's classification step can create a class without leaving the wizard, for the same roles that can write here.

A class is either a system class or a custom class, and the **Source** column badges each row "System" or "Custom". Nine system classes ship with the platform, with fixed names and descriptions, and most of them pin the base asset types their templates may use, as [System classes and the base types they allow](#system-classes-and-the-base-types-they-allow) lists. A custom class belongs to your organisation, accepts any base asset type, and can be renamed, hidden or deleted. Every create, rename, hide and delete of a class lands in the organisation's [audit trail](https://docs.settlemint.com/docs/console/reporting/audit-trail), with who made it and their platform and organisation role at the time.

![Asset classes table with Name, Source and Hidden columns and the Add asset class button](https://docs.settlemint.com/docs/screenshots/console-asset-classes.light.en.webp)

[Screenshot] The table lists each asset class with its name and slug, a System or Custom badge under Source, and whether it is hidden.

"Show hidden" and "View" sit above the table, and **Add asset class** appears above it for roles that can manage the catalogue.

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

- **The organisation.** Classes and their visibility are stored per organisation. Switch to the organisation whose catalogue you want to change first.
- **A role that manages asset design.** The sidebar shows "Asset classes" under "Asset design" only to accounts that hold the Permission manager, System manager or Asset designer role, and any other account that opens the screen by its link gets "Not available". The same roles add, edit, hide and delete a class.
- **A name with a Latin letter or digit.** The platform derives a class's slug, the URL-safe identifier, from them, so a name written only in another script is refused.
- **A second approver, when your organisation requires one.** When the "Platform settings" group is protected under [Approvals](https://docs.settlemint.com/docs/console/organisation-settings/general#approvals), each change on this screen waits on [Actions](https://docs.settlemint.com/docs/console/essentials/actions#decide-an-administrative-change) until another person approves it, and nothing changes until then.

## Steps [#steps]

### Open Asset classes [#open-asset-classes]

1. In the sidebar, open "Asset design", then **Asset classes**.
2. The table lists the visible classes sorted by name, with the slug under each name, and the "Source" and "Hidden" columns. "Slug" and "Description" are hidden by default, and **View** shows them. Search with "Search asset classes…", or filter by "Source" to list System or Custom classes only.
3. To see the hidden set, select **Show hidden**. The table then lists the hidden classes only.

### Add a class [#add-a-class]

Prefer an existing system class when your product fits one, because it carries platform-maintained naming and keeps templates on the base asset types that match it. Create a custom class when your taxonomy differs, or when the product needs a base type its system class would refuse.

1. Select **Add asset class**. A sheet opens.
2. Enter a **Name** and, optionally, a "Description". The Console derives a URL-safe slug from the name, and "Create" stays unavailable while the name yields no slug.
3. Enter a **Reason (optional)** to record why in the audit trail.
4. Select **Create**.

![Add asset class sheet with Name, Description and Reason fields](https://docs.settlemint.com/docs/screenshots/console-asset-classes-add-form.light.en.webp)

[Screenshot] The Add asset class sheet shows Name, Description and Reason (optional) fields, with Cancel and Create buttons.

Adding or renaming a class is refused when its slug belongs to a system class or to another class of your organisation. A name such as Equity or Yield instruments is refused with a duplicate-name message from the [error catalogue](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference), because a system class already holds its slug, and so is Trade Finance when trade finance exists. The existing class keeps its name and description. A name made only of punctuation cannot be saved, because it yields no slug. Accented Latin letters fold to plain ones, so Café gives cafe.

## Edit a custom class [#edit-a-custom-class]

1. In the row of a custom class, open the row menu behind the three-dot button at the end of the row. System classes have no **Edit** item.
2. Select **Edit**. The "Edit asset class" sheet opens with the same fields.
3. Change the "Name" or "Description", and select **Save**.

Renaming a class also regenerates its slug, and the class's template URLs move to the new slug.

## Hide or delete a class [#hide-or-delete-a-class]

Hide a class when the grouping might return, or when it is a system class, which can never be deleted. Hiding is per organisation, keeps every template's assignment, and one menu choice reverses it. Delete only a custom class you are retiring for good.

1. To hide a class, select **Hide** in its row menu. Select "Make visible" on a hidden class to bring it back.
2. Before you delete a custom class, assign each of its templates to another class. Filter the [Instrument templates](https://docs.settlemint.com/docs/console/asset-design/instrument-templates) catalogue by **Asset class** to list them. A deleted class leaves its templates without a class and out of asset issuance until someone edits each one.
3. Select **Delete** in the class's row menu. The "Delete asset class?" dialog warns that the action cannot be undone. Select "Delete asset class" to confirm.

## What hiding or deleting changes [#what-hiding-or-deleting-changes]

Hiding or deleting a class takes effect for everyone in your organisation at once. The class disappears from the classification choices in the template wizard, templates that belong to it drop out of the "Issue asset" template library, and its entry drops out of the "Assets" section of the sidebar, because both group templates by visible class. Issued assets, their holders and their balances do not change.

[Figure] What each class state changes in the pickers, the sidebar and issuance. One class in your catalogue can be visible, hidden, or deleted. A visible class is offered in template design and asset issuance, and it groups the sidebar, the template catalogue, and the dashboards. A hidden class leaves the pickers and the sidebar. Its templates keep the class, and Make visible restores everything. A deleted class is gone permanently, an option for custom classes only. Its templates stay but leave issuance until each one is reassigned. Labels: One class in your catalogue; system or custom; Visible; Offered in template; design and issuance.; Groups the sidebar, the; catalogue, and dashboards.; Hidden; Leaves pickers and the; sidebar. Templates keep; the class. Make visible; restores everything.; Deleted; Custom classes only,; and permanent.; Templates stay but; leave issuance.; Issued assets stay untouched in every case, and so do their holders and balances.

Hiding can be reversed and deleting cannot, and both change where templates and their assets are offered and grouped,
not an issued asset.

## System classes and the base types they allow [#system-classes-and-the-base-types-they-allow]

| System class | Base asset types its templates may use |
| --- | --- |
| Fixed income | Bond |
| Funds | Fund |
| Cash | Stablecoin or deposit |
| Structured | Bond or fund |
| Real assets | Real estate or precious metal |
| Equity, Derivatives and Yield instruments | Equity |
| Digital assets | Any |

Derivatives and Yield instruments build on the equity base type, and their behaviour comes from the token features a template adds.

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

- Clear the "Source" filter and **Show hidden** if either is active.
- Confirm the table shows the class under its expected name and slug, with the visibility you set.
- Open [Instrument templates](https://docs.settlemint.com/docs/console/asset-design/instrument-templates) and confirm its templates group under the intended class, or, for a new class, start a template in the wizard and confirm the class is offered in the classification step.

## Troubleshooting [#troubleshooting]

**There is no Add asset class button**

The screen shows "You are not authorized to manage asset classes." when its role check finds none of the managing
roles, for example after your role was removed while the page was open. Ask for the Permission manager, System manager
or Asset designer role in this organisation, or ask someone who holds one of those roles to make the change.

**Creating a class is refused as a duplicate**

The derived slug belongs to a system class or to another class of your organisation. Choose a name that reduces to a
different slug, or reuse the existing class.

**A class is missing from the table**

Select **Show hidden** to check the hidden set, and confirm you are in the right organisation, because each
organisation keeps its own custom classes and its own visibility choices.

**Templates vanished from Issue asset**

The template library only offers templates whose class is visible. Make the owning class visible again, or, if it was
deleted, edit each affected template and assign a replacement class.

## Frequently asked questions [#frequently-asked-questions]

### Do asset classes change how a token behaves?

No, not once the token exists. Everything on this screen is a design-time record: catalogue membership and visibility. The one place a class reaches further is template design, where eight system classes limit which base asset type their templates may use.

### Can a custom class use the same name as a system class?

No. The Console derives a slug from the name and refuses a name whose slug a system class holds, so a custom Equity or Yield instruments is refused, and the message names the slug and says it belongs to a system asset class. Choose a name that differs, such as Listed equity. When a platform release adds a system class whose slug one of your custom classes already used, the platform moves the custom class to a new slug and keeps its name, so you can still see a custom class named like a system class.

### Does hiding a class affect other organisations?

No. Visibility is stored per organisation, including for system classes. Hiding Structured in your organisation leaves every other organisation untouched: its pickers and sidebar still show Structured, and so does its template catalogue. Deleting reaches no other organisation either, because you can delete only classes your organisation created, and no other organisation ever saw them.

### Do I have to set up classes here before designing templates?

No. The wizard's inline class is the same kind of object you add here: it lands in this table, and you hide or delete it the same way as any other custom class. Use this screen to plan the whole taxonomy up front, tidy visibility or retire classes. The wizard's inline form does none of these.

### How do I merge two classes?

No single control merges classes. Edit each template in the class you are retiring and assign the surviving class in its classification step, then hide or delete the emptied class. Reassign first so the affected templates remain available for issuance.

### Can I control the order classes appear in?

No. The table, the template wizard's classification choices, and the sidebar all sort classes alphabetically by name, and there is no manual ordering. Renaming a custom class is the only way to move it, and a rename regenerates its slug, as [Edit a custom class](#edit-a-custom-class) describes.


# Asset design

Source: https://docs.settlemint.com/docs/console/asset-design
The Asset design group of the Console sidebar: the product shapes an issuer picks from.

The **Asset design** group defines a product before any token exists. An asset class groups instrument templates and can limit the base asset types they may use, and "Issue asset" copies a published template into each new token. [Token features](https://docs.settlemint.com/docs/concepts/modeling-assets/token-features) explains what a template's features do.

Work in that order: pick or create the class, build and publish the template under it, then issue from it.


  - [Asset classes](https://docs.settlemint.com/docs/console/asset-design/asset-classes): Manage the business categories that organise instrument templates and issued assets.
  - [Instrument templates](https://docs.settlemint.com/docs/console/asset-design/instrument-templates): Define the product shapes issuers pick at issuance and group them into multi-class sets.



# Instrument templates

Source: https://docs.settlemint.com/docs/console/asset-design/instrument-templates
Define the reusable product shapes issuers select during asset issuance, and group them into multi-class structures.

An instrument template packages one financial product shape for reuse: the asset class and base asset type, the [token features](https://docs.settlemint.com/docs/concepts/modeling-assets/token-features) and their default values, the metadata fields the issuance flow collects, and the compliance policy a new asset starts from. What you publish on this screen decides what an issuer sees, and must fill in, the next time they open [Issue asset](https://docs.settlemint.com/docs/console/asset-management/issue-new-asset).

Use this screen when a new product line needs a shape, such as a bond series, a share class or a deposit programme, or when an existing line's fields, features or policy must change for future issuance. You also use it to choose which templates your organisation offers for issuance. You do not need it to issue one asset. The DALP Library ships system templates for debt, equity, funds, deposits, stablecoins, real assets, structured products, digital assets and Islamic certificates, and most templates start as a copy of one of them. Three of them start published in every organisation: Common Equity, Corporate Bond and Fiat-Backed Stablecoin. Every other DALP Library template stays out of Issue asset until your organisation publishes it.

An issued instrument keeps its own copy of the configuration it was created with, so publishing a change, unpublishing or hiding a template alters the next issuance and never rewrites an existing asset. A template that has issued instruments cannot be deleted. Every create, edit, publish, unpublish and delete of a template or structure lands in the organisation's [audit trail](https://docs.settlemint.com/docs/console/reporting/audit-trail), with who made it and the values before and after.

![Instrument templates catalogue](https://docs.settlemint.com/docs/screenshots/console-instrument-templates.light.en.webp)

[Screenshot] The instrument templates catalogue is a table with one row per template.

Each row names the template, its asset class, its source, its draft, published, or unpublished state, its version, and its last update. A row expands to show the description and the required features.

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

- **The role.** You need the Permission manager, System manager or Asset designer role to create, edit, duplicate, publish, unpublish or delete templates and structures. The sidebar shows "Asset design" only to those roles, and any other account that opens an instrument templates page by its link gets "Not available".
- **The factory.** The Configurable Asset, the factory that deploys a template's assets, must be registered in your organisation's system before templates can be created or used. The wizard's Classification step warns "Deploy the Configurable Asset under Factories before creating templates." when it is not. A system manager registers it on [Factories](https://docs.settlemint.com/docs/console/organisation-settings/factories) as the token factory of type "DALP asset".
- **A published policy.** A compliance manager or permission manager must publish the policy you want to attach on [Policy templates](https://docs.settlemint.com/docs/console/compliance/policy-templates). As an asset designer you can read it there but not create or publish it.
- **An asset class.** Pick one from [Asset classes](https://docs.settlemint.com/docs/console/asset-design/asset-classes) or create it inside the wizard.
- **Published Library templates.** An organisation that issues from a DALP Library template other than the three that start published must publish it here first, or the platform refuses the next issuance.
- **A second approver, when your organisation requires one.** When the "Platform settings" group is protected under [Approvals](https://docs.settlemint.com/docs/console/organisation-settings/general#approvals), each change on this screen waits on [Actions](https://docs.settlemint.com/docs/console/essentials/actions#decide-an-administrative-change) until another person approves it, and nothing changes until then. With the group off, one holder of these roles can create, edit, publish and unpublish a template, including one with no compliance policy.
- **A name with a Latin letter or digit.** The platform derives the template's identifier from the name. A name written only in another script, such as Chinese, forms no identifier and is refused.

## Steps [#steps]

### Open Instrument templates [#open-instrument-templates]

Open **Asset design**, then "Instrument templates". The catalogue is a table with one row per template and the columns "Name", "Asset class", "Source", "Status", "Version" and "Updated". Narrow it with the search box or the "Asset class", "Source" and "Status" filters, sort it by a column heading, and page through it at the bottom. "Source" separates "DALP Library" system templates from your organisation's own, and "Status" separates "Draft", "Published" and "Unpublished" templates.

Select the arrow at the start of a row to expand it. The expanded row shows the template's description and its required features, plus its structure role, which class it fills in a multi-class structure, the published structures that use it under **Used by published structures**, and a "Hidden" badge when those apply. Selecting the row itself opens the template's detail page. To check what issuers see, filter "Status" to "Published" and expand each row to look for the "Hidden" badge.

When you hold a managing role, each row ends with a button. On a published template it reads **Unpublish**, and on an unpublished one "Publish", and it asks you to confirm the change. On a draft it reads "Open draft", because a draft publishes from its detail page after it passes readiness. On a template that a published structure uses, it reads "Used by structures" and opens the "Structures" tab.

### Choose a starting point [#choose-a-starting-point]

Select **Create template** and pick one of the three starting modes:

| Starting mode | What you get | Choose it when |
| --- | --- | --- |
| **Blank** | An empty draft with no inherited features. | No existing template fits the product. |
| **Clone one of yours** | A draft copy of one of your organisation's templates. | A close relative of the product already exists. |
| **Start from DALP library** | A draft copy of a system template. | A DALP Library shape matches the product. |

Every mode creates a new draft. Nothing you change in it touches the source. A clone is named after its source with "(Copy)" appended. Cloning the same source again picks the next free "(Copy 2)", "(Copy 3)", and so on, because template names must be unique in your organisation. **Duplicate template** on any template's detail page is a shortcut into this step with that template preselected. [What the DALP Library ships](#what-the-dalp-library-ships) lists the shapes that need a specific set of features and policy.

![Create an instrument template, Start step, with the Blank, Clone one of yours and Start from DALP library cards](https://docs.settlemint.com/docs/screenshots/console-instrument-template-create.light.en.webp)

[Screenshot] The Start step shows three starting-mode cards: "Blank", "Clone one of yours" and "Start from DALP library".

Choosing "Clone one of yours" or "Start from DALP library" opens a source gallery grouped by asset class, with a search box and an asset-class filter for narrowing a long catalogue.

### Name the template and classify it [#name-the-template-and-classify-it]

Work through **Basics** and "Classification". The name is yours to change later through the detail page's Basics section, using its "Edit" control, even after publishing. The identifier derived from it at creation is not, so name the product line rather than this quarter's offering. Accented Latin letters fold to plain ones in the identifier.

The asset class decides which base asset type the instrument uses, and the base type decides which instrument-specific details issuance collects later, such as maturity and coupon inputs for a debt shape. The **Instrument type** choice on "Classification" names the instrument in reports, for example "Sukuk" or "Government security". It starts at the type the base asset type implies and does not change how the token behaves.

### Select the token features and their values [#select-the-token-features-and-their-values]

Select the token features on **Features** and configure each one's defaults. The [token features catalogue](https://docs.settlemint.com/docs/concepts/modeling-assets/token-features) lists each feature, its parameters, and what it needs.

- Feature dependencies and conflicts are enforced as you toggle. A feature that needs another one reads **Select Historical balances first.** until you enable that one. A feature that conflicts with one you selected names the other one, such as Conflicts with Transaction fee accounting.
- Turning a feature off also turns off every feature that depends on it.
- Each feature value offers two choices. **Fixed value** takes the value you enter here, and Issue asset does not ask for it. "Issuer sets it at issuance" leaves the value open on "Instrument details", with an optional default that pre-fills the field and that the issuer can replace.
- A fixed treasury yield's **End date** follows its "Start date": once the start date has a value, the earliest end date you can pick is the next day, and while both are empty the end date's sample date is a day after the start date's. The template stores no date until you pick one.
- A date field in a feature's settings, opened from its card, refuses a typed day that does not exist, such as `2026-02-30`, and shows a message under it. **Save** in those settings stays unavailable until you correct or clear that date.
- Seven features need a token already registered in your organisation's system, as [Features that need a registered token](#features-that-need-a-registered-token) explains.

The **Instrument capital** choice on the same step declares what the instrument's units are: "Share capital" for ordinary, preferred and class shares, "Unit capital" for fund units and real-estate fractions, or neither for a SAFE, a warrant or a debt shape. It decides which [corporate actions](https://docs.settlemint.com/docs/console/asset-management/manage/corporate-actions) an asset can run, and each asset keeps the capital its template declared when it was issued.

### Add the metadata fields issuance must collect [#add-the-metadata-fields-issuance-must-collect]

On **Metadata**, select "Add field" for each product fact the issued instrument should record, such as an ISIN or a maturity date. A field carries a label, a key made from it, a "Type", a "Changes" choice and a "Storage" choice. "Fixed once set" means the value cannot change after it is saved, and "Managers only" lets anyone with the token's "Governance" role change it later. "Storage" reads "On-chain" or "Off-chain". After tokens are issued from a template, a field's "Storage" and "Changes" are locked.

**Type** has fifteen options. Prefer a specific one such as "ISIN", "LEI" or "Currency" over "Text", because a field with a specific type checks the issuer's entry as they enter it. Mark a field "Required" only when issuance should not proceed without it, because every required field becomes a gate each future issuance must pass.

A **Default value** pre-fills the entry. "Configurable in Issue asset" lets the issuer set the value on "Instrument details" instead of taking the default you set here. A date field also takes an optional "Lower bound" and "Upper bound", the earliest and the latest day the issuer can enter. "Default value", "Lower bound" and "Upper bound" refuse a typed day that does not exist, such as `2026-02-30`, and show a message under that field. "Add field", or "Save" when you edit a field, stays unavailable until you correct or clear that date.

### Attach a compliance policy [#attach-a-compliance-policy]

On **Compliance**, pick the published policy template that assets created from this template start from, or "No compliance template". A template with "No compliance template" still publishes, and its assets deploy without token-level modules, the per-asset compliance rules a policy installs. Issue asset warns "Asset will deploy without compliance controls." but does not block. Identity checks and inherited global controls, the organisation-wide rules set on [Global controls](https://docs.settlemint.com/docs/console/compliance/global-controls), still apply.

The Compliance step starts with a **Jurisdiction** field: pick the country where assets from this template are issued, and the policy list below filters to match. The platform stores your choice as the default value of the template's `jurisdiction` metadata field when that field is a country field, and otherwise of `issuerJurisdiction`. When the field it would write does not exist, the step adds it as a country field, which then appears on the "Metadata" step and is filled in for the issuer at issuance. A template with neither field gets `jurisdiction`. When both fields exist and neither is a country field, the "Jurisdiction" field is disabled. When that field limits its options to certain countries, the "Jurisdiction" field offers only those countries.

With a default of Germany, the list shows policy templates that name Germany, policy templates that name a group containing Germany such as the EU or the EEA, and global policy templates. The **Applies to Germany** chip turns the filter on and off: select it to list every policy template when the one you need lies outside the filter, and select it again to filter once more. The filter never changes the policy template you already selected, which stays selected and visible when it lies outside the filter. With no jurisdiction chosen, the list is unfiltered. Choose "No jurisdiction" to clear the choice.

Attaching a policy adds **Compliance details** steps to every future issuance from this template, one for each control the policy marks "Make configurable in Issue asset" and one for each control it requires without configuring it. The issuer fills in only those values. Deleting the linked policy on Policy templates later clears the link on this template. The template stays published, and later assets issued from it start without that policy's token-level controls until you link a replacement.

### Review and publish [#review-and-publish]

Resolve any gap the **Review** step lists, then publish or select "Save as draft". The readiness check blocks publishing when a required feature has no configuration yet or a stored feature configuration no longer matches its expected shape. Its fix is reopening the Features step. Unpublishing never returns a template to draft. To stop offering the template later, unpublish it, as [Publish or unpublish a template for your organisation](#publish-or-unpublish-a-template-for-your-organisation) describes.

## Publish or unpublish a template for your organisation [#publish-or-unpublish-a-template-for-your-organisation]

Two controls change whether your organisation offers a template, and both work on DALP Library templates and on your own.

- On the template's detail page, the **Visibility** card starts with the "Published" switch. Turn it on to offer the template in Issue asset, and off to stop offering it.
- In the catalogue table, the **Publish** or "Unpublish" button at the end of the row does the same without opening the template.

![A published template's detail page with the Visibility card and its Published, Hide from main sidebar and Hide from Issue asset switches](https://docs.settlemint.com/docs/screenshots/console-instrument-template-detail.light.en.webp)

[Screenshot] The template's detail page shows the "Details", "Metadata", "Token features" and "Compliance" tabs.

The "Visibility" card on that page holds three switches: "Published", "Hide from main sidebar" and "Hide from Issue asset".

Either control opens a small panel anchored at it, titled **Publish template?** or "Unpublish template?". The panel says that existing tokens and deployed contracts do not change, and that unpublishing does not make the template a draft. When you confirm, the change takes effect at once and applies to your organisation only. On a draft the switch is unavailable and the Console explains why: resolve the readiness gaps, then select the "Publish template" button in the detail page header. Only the first publish runs the readiness list. Every later save still refuses a missing dependency, a conflicting pair or an invalid feature configuration.

## Edit, hide or delete a template [#edit-hide-or-delete-a-template]

A published organisation template stays editable through its **Details**, "Metadata", "Token features" and "Compliance" tabs. Saved changes update future issuance. A DALP Library template is the exception: its detail page shows a "DALP Library" badge beside the title, with an information button that says the template is read-only, and it has no edit or delete control. "Duplicate template" in the Actions menu is the only way to adapt one into an editable copy your organisation owns.

Three more controls on the detail page take a template out of use:

- The other two **Visibility** switches, "Hide from main sidebar" and "Hide from Issue asset", hide the template without deleting anything. Hiding is reversible and applies to your organisation only. "Hide from Issue asset" removes the template from the choices for new issuance, whatever its published state, and leaves existing tokens unchanged. It also removes the template from the starting-point gallery in "Create template", which unpublishing does not. A DALP Library template cannot be hidden from the main sidebar, but it can be hidden from Issue asset. Publishing and hiding govern issuance from a template only: on a deployment whose operator turned on legacy asset creation, an integration can still create a classic asset type through `POST /api/v2/tokens` without a template, as [Issue asset](https://docs.settlemint.com/docs/console/asset-management/issue-new-asset#can-an-integration-create-an-asset-without-a-template) explains.
- **Delete** is permanent and offered only on templates your organisation created. The confirmation dialog warns that it removes the template together with its metadata fields and feature settings. "Delete" is disabled while the template is a class of a structure, and the platform refuses it while an issuance from the template is still running. A template that tokens were issued from cannot be deleted either. After you confirm, the Console shows "Tokens were issued from this template." with "Keep the template. To stop new issuance from it, unpublish it or hide it from Issue asset.", and the template stays.

## Declare templates as one structure [#declare-templates-as-one-structure]

An instrument structure declares two to eight templates as one multi-class instrument, such as a dual-class share. Each template fills one class of the structure, and each class keeps its own compliance stack.

Open the **Structures** tab of Instrument templates and select "Create structure". Enter a "Name", and optionally a "Description" and an "Asset class", which files the whole structure in the catalogue. Under "Classes", select "Add class" for each class, give it a "Class name" of at least two letters or digits, and choose its template. Each class needs its own name, and a structure has two to eight classes. A draft template cannot fill a class, so finish and publish the draft first.

A DALP Library structure is read-only: the Console says **System structures are read-only.** Select "Copy to edit" to make your own copy, named after the source with "(copy)" appended. Once instruments have been issued from a structure, its classes are locked: the Console says "Deployed instruments reference this structure" and asks you to create a new structure instead. Select "Delete structure" to remove a structure of your own. Its templates stay and only the pairing is removed, but the platform refuses the delete while deployed instruments were issued from the structure. A structure you create starts published, as [Publish an instrument structure for your organisation](#publish-an-instrument-structure-for-your-organisation) describes.

## Publish an instrument structure for your organisation [#publish-an-instrument-structure-for-your-organisation]

A structure has its own published state in your organisation, separate from the state of its templates. The DALP Library holds the **Dual-Class Share Structure** and the "Convertible Note Structure". Issue asset offers a structure only when three things are true: your organisation has the structure published, every template in it is published, and no template in it is hidden.

| Structure | Starts as | Why |
| --- | --- | --- |
| A DALP Library structure | **Unpublished** | It follows the DALP Library templates, which start unpublished. |
| A structure your organisation creates | **Published** | You built it from templates you chose, so it is offered once they are published. |

Open the **Structures** tab of Instrument templates to see every structure as a table. The "Status" column reads "Published" or "Unpublished", and a published structure with a hidden template also shows "Not offered". Expand a row to see each class with its role, its template, and the template's own state: "Published", "Unpublished", or "Hidden". Filter "Status" to find the structures your issuers cannot choose.

![Instrument structures table with DALP Library and organisation structures and their publish actions](https://docs.settlemint.com/docs/screenshots/console-instrument-structures.light.en.webp)

[Screenshot] The "Structures" tab is a table with one row per structure.

Each row names the structure with its source, "DALP Library" or "Organisation", and the number of instruments your organisation deployed from it (a DALP Library structure never counts another organisation's instruments), then its asset class, its "Published" or "Unpublished" status, and its last update. A row ends with a "Publish" or "Unpublish" button and a "View structure" link. Your organisation's own structures show "Edit structure" instead, plus "Delete structure" while nothing is deployed from them. A row expands to show each class.

To publish a structure, select **Publish** at the end of its row, or open the structure and turn on the "Published" switch at the top of the sheet. On a DALP Library structure that switch is the only control you can change. When some of the structure's templates are unpublished, a dialog lists them first, because publishing the structure also publishes them for your organisation. Confirm to publish all of them in one step, or cancel to change nothing.

To stop offering a structure, select **Unpublish** or turn the switch off. There is no confirmation, the change is reversible, and the structure's templates stay published. Unpublishing does not affect assets already issued from the structure, and an issuance run that the platform accepted before you unpublished still completes.

A template that a published structure uses cannot be unpublished. In the catalogue its row shows **Used by structures**, which opens the "Structures" tab, in place of "Unpublish". On its detail page the "Published" switch is disabled and names the structures that use it. Unpublish those structures first. Because a structure your organisation creates starts published, its templates are protected from the moment you save it.

When you replace a class of a published structure with an unpublished template, the structure becomes **Unpublished**. It stays unpublished when that template is published later for another reason, so the structure is offered again only when someone publishes it.

Both DALP Library structures start unpublished in every organisation, including one that published their templates.

## Draft, published and unpublished templates [#draft-published-and-unpublished-templates]

Each template has one of three statuses in your organisation. The status is yours alone: another organisation that reads the same DALP Library template sees the status it chose.

| Status | Offered in Issue asset | How a template gets there |
| --- | --- | --- |
| **Draft** | No | You create a template. It stays a draft until it passes readiness and you publish. |
| **Published** | Yes, unless you also hide it | You publish it, or it is one of the three DALP Library templates published at first. |
| **Unpublished** | No | You unpublish it, or it is any other DALP Library template you have not published. |

Your choice replaces that starting state for your organisation and stays until you change it again.

Publishing and unpublishing are reversible without limit. Unpublishing never returns a template to draft, so publishing it again needs no second readiness check. An asset issued from a template you later unpublish keeps its page, its asset class, its sidebar entry, and its operations.

[Figure] Publishing offers a template to issuers, and each issued instrument keeps its own copy of the configuration. A draft template is editable and invisible to issuers. Publishing it makes it selectable in Issue asset, where an issuer's selection carries the template's fields, features, and policy into a new instrument. The issued instrument keeps its own copy of that configuration. Later edits to the template reach only future issuance and never rewrite an instrument that already exists. Labels: Instrument templates screen; Draft template; Editable. Issuers never see it.; Publish; Published template; Offered in Issue asset.; Issuer selects it; Issue asset; Collects the template's fields.; Issued instrument; Keeps its own frozen copy.; Later template edits; Reach only future issuance.; Never an existing instrument.

A template change lands at the next issuance: every instrument already issued keeps its own configuration from issuance.

## Features that need a registered token [#features-that-need-a-registered-token]

Seven features need a token already registered in your organisation's system, the token that pays or prices the feature: external transaction fee, maturity redemption, fixed treasury yield, dividend yield, interest yield, the distribution waterfall and conversion. Conversion also needs a target token that carries the conversion minter. Any token the system already holds satisfies the check. It does not have to be a stablecoin, and the conversion target does not have to be an equity token. A template that fixes the value itself, instead of leaving it to the issuer, does not trigger the condition.

Enabling one of these without its token in place still lets the template save and publish. Issue asset then marks its row "Needs a denomination asset" or "Needs a target token", and the issuer cannot pick it until the token exists. For a denomination asset, its details offer "Issue a stablecoin" and "Register an external token". For a target token, they offer "Issue a conversion target token".

Two sets of features conflict: **Transaction fee** conflicts with "Transaction fee accounting", and "Booked movements" conflicts with "Management fee", "Conversion", "Conversion minter", "Maturity redemption" and "Supply delegate".

## What the DALP Library ships [#what-the-dalp-library-ships]

The DALP Library holds 36 system templates, spread over seven of the nine asset classes. Derivatives and Yield instruments have no template of their own. Beyond the plain bonds, shares, funds, and deposits, these templates cover shapes that need a specific set of features and policy:

- **Sukuk Ijara** and "Sukuk Murabaha" are lease-backed and cost-plus Islamic certificates in Fixed income. Both carry the "Shari'ah / AAOIFI - Islamic Finance" policy and maturity redemption. Ijara pays declared periodic rental distributions through Dividend yield, and Murabaha pays through Fixed treasury yield.
- **Tokenized Virtual Asset** is a custody-backed claim on a digital asset, in Digital assets. "Tokenized Spot Commodity" is a physically backed commodity token, in Real assets. Both use Historical balances and Permit.
- **Government Security** is coupon-bearing debt of a government, its agencies, or a sub-sovereign authority. It starts as a copy of "Sovereign Bond" with the issuer field labelled "Government issuer".
- **Controlling Class Share** and "Economic Class Share" are the two classes of the "Dual-Class Share Structure". The controlling class carries Historical balances, Distribution waterfall and Dividend yield. The economic class carries Historical balances, Dividend yield, Voting power and Permit. "Share-Class Mirror" is the on-chain record of a share class whose register a fund administrator keeps.
- **Custody Receipt** is the claim a client holds on coins that your custody gateway received for them. [Custody receipts](https://docs.settlemint.com/docs/concepts/custody-and-signing/custody-receipt) describes how it is backed.
- **SAFE** and "Warrant" convert into a separately deployed "Convertible Target Equity", which is the equity share they convert into. Both carry Historical balances, Conversion, and Permit. The target token must authorise the converter first, as [Authorise the converter on the target token](https://docs.settlemint.com/docs/console/asset-management/manage/conversion#authorise-the-converter-on-the-target-token) describes.

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

- Open the template's detail page and check that the badge beside its name reads **Published** rather than "Draft" or "Unpublished", and that the class, features, metadata fields, and policy match what you defined.
- Then start "Issue asset": the template appears under its asset class, selectable unless it still needs a prerequisite token, in which case its row shows "Needs a denomination asset" or "Needs a target token" instead.
- Once selectable, choosing it shows exactly the required fields and configurable values you published.

## Troubleshooting [#troubleshooting]

**The template cannot be published**

Publishing is blocked when you lack the Permission manager, System manager or Asset designer role, or when a draft's
readiness list shows a gap. A readiness gap is a required feature with no configuration yet, or a saved feature
configuration that no longer matches its expected shape. Open the **Token features** tab, or the "Features" step in
the wizard, configure the feature the gap names, and save. A template written through the API is also refused when a
feature misses a dependency or when it selects two conflicting features.

**The template is absent from asset issuance**

A template appears in **Issue asset** only when your organisation has it published, it is not hidden from Issue asset,
its asset class is visible, and the system has a "DALP asset" factory. Check the "Status" column in the catalogue and
the "Visibility" switches on the detail page. A DALP Library template other than Common Equity, Corporate Bond, and
Fiat-Backed Stablecoin stays unpublished until someone in your organisation publishes it. When none of these explains
it, ask a system manager to check [Factories](https://docs.settlemint.com/docs/console/organisation-settings/factories).

**A structure is listed but cannot be selected**

One of its templates needs a prerequisite token, and its row shows "Needs a denomination asset" or "Needs a target
token". Set up that token first, then reopen **Issue asset**.

**A structure is absent from asset issuance**

Issue asset lists a structure only when your organisation has published it and every template in it, and none of those
templates is hidden. An unpublished structure, such as either DALP Library structure in a new organisation, shows
**Unpublished** on the "Structures" tab. There, "Publish" offers the structure and publishes its unpublished templates
with it after you confirm. Ask an asset designer when your account cannot publish. A structure with a hidden template
shows "Not offered", and its expanded row marks the hidden template. Show that template again from its detail page,
then reopen "Issue asset".

**Unpublish is disabled on a template**

A published structure uses the template. The catalogue row shows **Used by structures** instead of "Unpublish", and
the disabled "Published" switch on the detail page names the structures. Unpublish them on the "Structures" tab, then
unpublish the template.

**Unpublish is refused on a draft or an unpublished template**

The platform answers the `409` error `ASSET_TYPE_TEMPLATE_NOT_UNPUBLISHABLE` (DALP-14018) when you unpublish a
template that is still a draft or is already unpublished. A draft was never published, and unpublishing never returns
a template to draft. Read `isDraft` and `isPublished` on the template first, then publish a ready draft instead.

**An API, SDK, or CLI issuance is rejected because a template is unpublished**

The platform rejects a token creation or an issuance run that names a template your organisation has not published,
with the `409` error `TOKEN_CREATE_TEMPLATE_UNPUBLISHED` or `TOKEN_ISSUANCE_RUN_TEMPLATE_UNPUBLISHED`. The frozen v1
token creation route rejects the same request with its existing `422` `INPUT_VALIDATION_FAILED` (DALP-0316). Retrying
does not help until the template is published. This affects every DALP Library template except Common Equity,
Corporate Bond and Fiat-Backed Stablecoin until you publish it. Publish the template on this screen or call the
publish endpoint, then send the request again.

**The template is listed but cannot be selected**

The template needs a prerequisite token, as [Features that need a registered
token](#features-that-need-a-registered-token) explains. Use the row's details in Issue asset to issue or register
that token. After issuance, [Token conversion](https://docs.settlemint.com/docs/console/asset-management/manage/conversion) covers running the
conversion itself.

**A template lost its class or policy**

Deleting the asset class or policy template it used clears that field on the template rather than deleting the
template. A template that lost its policy stays published, and Issue asset warns "Asset will deploy without compliance
controls." Open the template and set a replacement before the next issuance. Before you delete a policy template, its
**Used by** card lists the instrument templates that link it.

**The wizard rejects the template name**

Template names are unique within an organisation, so a name already in use is refused. Pick a distinct name.

## Frequently asked questions [#frequently-asked-questions]

### Who can see the templates my organisation creates?

No other organisation's members see your templates. The catalogue shows your own templates plus the shared DALP Library. The published state is equally organisation scoped, so unpublishing a DALP Library shape removes it from your issuers' choices without affecting anyone else.

## API routes [#api-routes]

The [instrument template endpoints](https://docs.settlemint.com/docs/api-reference/v2) list, create, read, update, publish, unpublish and delete a template, and the [CLI commands](https://docs.settlemint.com/docs/api-reference/cli/commands) mirror them.

- `PUT /api/v2/settings/asset-type-templates/{assetTypeTemplateId}/publication` with the body `{"published": true}` publishes a template, and the same request with `{"published": false}` unpublishes it. Publish accepts a DALP Library template and an unpublished template, as well as a ready draft. Each template in a list or read response reports `isPublished` for the calling organisation, and the list accepts `isPublished` as a filter and as a sort field.
- Publishing through the API also rejects a template whose feature misses a dependency or that selects both conflicting features. The Features step prevents both.
- Deleting a template that tokens were issued from answers HTTP 409 with [DALP-181131](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference).
- `PUT /api/v2/settings/asset-type-template-structures/{structureId}/publication` with the body `{"published": true}` publishes a structure together with its unpublished templates, and the same request with `{"published": false}` unpublishes it. Both answer `409` when the structure is already in that state. Each structure in a list or read response reports `isPublished` for the calling organisation, each of its members reports `isPublished` and `isHidden`, and the list accepts `isPublished` as a filter and as a sort field.
- Unpublishing a template that a published structure uses answers the `409` error `ASSET_TYPE_TEMPLATE_USED_BY_PUBLISHED_STRUCTURE`, and its `data.structures` lists the `id` and `name` of each structure that uses the template. An issuance run on an unpublished structure answers the non-retryable `409` error `TOKEN_ISSUANCE_RUN_STRUCTURE_UNPUBLISHED`.
- On a deployment whose operator turned on legacy asset creation, a token manager can still create a classic bond, equity, fund, stablecoin, deposit, real-estate or precious-metal token through the API without a template, as [Upgrade a deployment to DALP 3.2](https://docs.settlemint.com/docs/deployment/upgrade-to-3-2#decide-on-legacy-asset-creation) describes. That token takes the compliance modules the request supplies, not a template's policy, and skips the publication check. With the setting off, the default, the API refuses that request and every new token comes from a published template.


# Airdrops

Source: https://docs.settlemint.com/docs/console/asset-lifecycle/airdrops
Open an airdrop add-on from the Asset lifecycle sidebar, read its airdrops and each airdrop's distribution, and find where every other add-on type opens.

"Push airdrop", "Vesting airdrop" and "Time-bound airdrop" each have their own entry under **Asset lifecycle** in the Console sidebar. The entry opens a table of that add-on's airdrops, and each airdrop opens a read-only detail screen with its distribution, cap, recipients and recovery date. The [Token distribution concept](https://docs.settlemint.com/docs/concepts/issuing-and-markets/token-distribution) explains how the three airdrop types differ.

An add-on is a contract that your DALP system deploys from an add-on factory to work with its tokens: an airdrop, an offering, an XvP settlement, a vote, a trading venue, an escrow or a custody gateway. Every add-on opens at a Console address built from its factory address, and the same address opens the other add-on types, each on its own screen or as one overview card. [Add-on types and where each opens](#add-on-types-and-where-each-opens) lists them. A change that an add-on approval rule holds is decided on the custody gateway's [Approvals](https://docs.settlemint.com/docs/console/asset-lifecycle/custody-gateway-approvals) tab or in [Actions](https://docs.settlemint.com/docs/console/essentials/actions).

![The Push airdrop page with the Search airdrops field, Export and View, before any airdrop exists](https://docs.settlemint.com/docs/screenshots/console-addon-airdrops.light.en.webp)

[Screenshot] The "Push airdrop" page shows its table before any airdrop exists.

With no airdrop yet, the table reads "No data available yet", under a "Search airdrops…" field with "Export" and "View". Once airdrops exist, the columns are "Airdrop", "Distributed", "Recovery" and "Created".

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

- **A role that shows the entry.** The airdrop entries show to a System manager, an Asset manager, a Permission manager, an Owner, a Platform admin, and a holder of the Governance role on an asset. The "Custody gateway" entry shows to an Owner and a Platform admin.
- **A deployed add-on.** An airdrop type the system has no add-on for shows as a greyed entry. A System manager reads "Push airdrop is not deployed. Open Factories to deploy it." and the entry opens [Factories](https://docs.settlemint.com/docs/console/organisation-settings/factories). Anyone else reads "Push airdrop is not deployed. A system manager deploys it in Factories." [Factories](https://docs.settlemint.com/docs/console/organisation-settings/factories) lists every add-on factory with its type and address.

## Steps [#steps]

### Open the add-on [#open-the-add-on]

Open the add-on type's entry under **Asset lifecycle**. The page title is the type's name, and the breadcrumb reads "Asset lifecycle", then the type.

After the fixed entries, such as "Offerings" and "Venues", the sidebar shows one entry for each airdrop add-on the system has, then **Custody gateway**. When the system has two add-ons of one type, each entry carries the add-on's own name.

### Read the airdrops [#read-the-airdrops]

The table lists the add-on's airdrops:

- The **Airdrop** column carries the airdrop's name with the symbol of the token it distributes.
- **Distributed** shows the amount sent so far, out of the cap when the airdrop has one.
- **Recovery** reads "Scheduled" once the airdrop's owner has scheduled a withdrawal, and "None" otherwise.

The withdrawal can run from the "Recovery available" time on the detail screen, and it takes only the tokens no recipient can still claim. On a vesting airdrop, it leaves the unclaimed part of every allocation whose vesting has started, and those recipients keep claiming. On a push airdrop, whose recipients do not claim, it takes the whole balance.

Search with **Search airdrops…**. Each row's menu offers "View details" and "Copy address".

### Open an airdrop [#open-an-airdrop]

Select an airdrop row, or **View details** in its menu, to open the airdrop's detail screen. The header carries the airdrop's name and the date it was created, and reads "Scheduled" when a withdrawal is scheduled. A "Distribution" card lists the fields in [Airdrop details](#airdrop-details).

The Console has no control that creates an airdrop or schedules its recovery. A holder of the **Governance** role on the token creates an airdrop by calling its factory contract's `create` directly, and the airdrop's owner schedules a recovery on the airdrop contract.

## Read the other add-on types [#read-the-other-add-on-types]

The add-on address opens a different screen for each other type:

- An XvP settlement add-on shows the settlements table and **Create XvP settlement**. [XvP settlement](https://docs.settlemint.com/docs/console/my-assets/settlements) describes it, and its detail screen.
- An offering add-on shows the offerings table. An offering address takes you to the offering's operating screen when you operate the sale, and to its subscription view when you do not. [Offerings](https://docs.settlemint.com/docs/console/asset-lifecycle/primary-offerings) describes the operating screen.
- A votes add-on redirects to **Votes** under "Wealth".
- Any other add-on shows one **Add-on overview** card with the add-on's "Address", "Type" and "Category".

A vesting distribution created before withdrawal reserves were introduced keeps its whole balance reserved after its factory moves to the new implementation. Recipients can still claim, but owner recovery sends zero, even after all claims finish: the contract cannot reconstruct the older allocations from its records.

## Airdrop details [#airdrop-details]

The **Distribution** card on an airdrop's detail screen lists:

| Field | What it shows |
| --- | --- |
| Token | The token the airdrop distributes, or **Unknown token**. |
| Distributed | The amount sent so far. |
| Cap | The most the airdrop distributes, or **No cap**. The owner of a push airdrop can change it. |
| Recipients | How many wallets received tokens. |
| Recovery available | The earliest moment the scheduled withdrawal can run: seven days after scheduling or, when later, the end of a time-bound airdrop's claim window or a vesting airdrop's **Vesting must start by** deadline. It shows while a withdrawal is scheduled. |
| Vesting strategy | The vesting contract, on a vesting airdrop. |
| Vesting must start by | The deadline for a recipient to start vesting, on a vesting airdrop. |
| Merkle root | A fingerprint of the list of eligible wallets and amounts. The contract checks each claim, or each distribution the owner of a push airdrop sends, against it. |
| Address | The airdrop contract's address. |

## Add-on types and where each opens [#add-on-types-and-where-each-opens]

The Console groups add-on types by category. Each name in the table is the label the Console shows.

| Category | Add-on types | Where it opens |
| --- | --- | --- |
| Distribution | Push airdrop, Vesting airdrop, Time-bound airdrop | Its own entry under **Asset lifecycle** in the sidebar, with a list of its airdrops and a detail screen for each. |
| Distribution | Offerings | **Offerings** under **Asset lifecycle**. See [Offerings](https://docs.settlemint.com/docs/console/asset-lifecycle/primary-offerings). |
| Exchange | Settlements | **Settlements** under **Wealth**. See [XvP settlement](https://docs.settlemint.com/docs/console/my-assets/settlements). |
| Exchange | Trading venue | **Venues** under **Asset lifecycle**. See [Venue operations](https://docs.settlemint.com/docs/console/asset-lifecycle/venues). |
| Governance | Votes | **Votes** under **Wealth**. An add-on address of this type redirects there. See [Governance votes](https://docs.settlemint.com/docs/console/my-assets/votes). |
| Custody | Custody gateway | **Custody gateway** under **Asset lifecycle**. See [Approvals](https://docs.settlemint.com/docs/console/asset-lifecycle/custody-gateway-approvals). |
| Custody | Escrow | **Escrows** under **Asset lifecycle**. See [Escrows](https://docs.settlemint.com/docs/console/asset-lifecycle/escrows). |
| Custody | Sponsorship Paymaster | No sidebar entry. Its link opens an **Add-on overview** card. |
| Income | Yield | No sidebar entry. Its link opens an **Add-on overview** card. |
| Data | Price Resolver, Issuer-Signed Scalar Feed, Scalar Feed Adapter, Document Anchor Registry | No sidebar entry. Its link opens an **Add-on overview** card. |

The Console keeps the access manager and the governance timelock out of the sidebar. The access manager is an internal add-on that creates a dedicated access manager for an add-on such as a trading venue or the custody gateway. The factory list also holds token feature factories, such as Dividend yield or Permit, which add a feature you configure on the token, as [Token features](https://docs.settlemint.com/docs/concepts/modeling-assets/token-features) describes.

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

- For an airdrop add-on, the airdrop you looked for is in the table, and its detail screen shows the same **Distributed** amount as the table row.
- After the owner schedules a recovery, the row reads "Scheduled" under "Recovery" and the detail screen shows **Recovery available**.

## Troubleshooting [#troubleshooting]

**An add-on entry is missing from the sidebar**

The airdrop entries show only to a System manager, an Asset manager, a Permission manager, an Owner, a Platform admin
and a holder of the Governance role on an asset. The **Custody gateway** entry shows only to an Owner and a Platform
admin. An airdrop type that the system never deployed shows greyed with the line "Push airdrop is not deployed", so
ask a System manager to deploy it in [Factories](https://docs.settlemint.com/docs/console/organisation-settings/factories).

**An address shows This page does not exist**

The address names an add-on or an instance the Console has no screen for. Add-ons other than airdrops, XvP settlements
and offerings have no instance screen, so an instance address of one of them shows "This page does not exist". Use the
add-on's own entry instead, or the **Add-on overview** card at the add-on address.

**A claim is refused during a corporate action**

An airdrop that holds a token for claimants is frozen for that token from the record date of a [corporate
action](https://docs.settlemint.com/docs/console/asset-management/manage/corporate-actions) that changes every holder's units by a ratio, such as
a stock split, until the action's step lands. Claims in that window are refused with a message that names the token
and the action. Claim again once the action has finished. After it, each claim pays its committed amount scaled by
every action since the root was set. An airdrop counts as one holder, so a claim rounds down to the action's unit and
is never lifted to one share.

## API routes [#api-routes]

| Task | Route |
| --- | --- |
| List add-on factories | `GET /api/v2/system/addon-factories` |
| Read one add-on factory | `GET /api/v2/system/addon-factories/{factoryAddress}` |
| List airdrops | `GET /api/v2/addons/airdrops` |
| Read one airdrop | `GET /api/v2/addons/airdrops/{airdropAddress}` |

The request and response fields of each route are in [the v2 API reference](https://docs.settlemint.com/docs/api-reference/v2).


# Bank rail

Source: https://docs.settlemint.com/docs/console/asset-lifecycle/bank-rail
Connect the bank, link the reserve token, add the clients whose bank transfers mint to their wallets, and follow their cash-outs through the bank.

The bank rail credits a client's wallet when a matched, screened bank transfer reaches the organisation's reserve account, and pays a client's redemption out to their bank account. A transfer that matches no client, or whose wallet the token blocks, parks as suspense instead. A client's redemption request becomes a cash-out on these screens, and the bank's payment of it is the payout. Each row on **Bank rail** is one bank connection and the token that represents its reserve currency. Opening a row opens that token's page, where a bank rail manager follows payments, adds clients, records cash-outs, reads the reconciliation and changes the connection's settings.

An integration can follow the same payment milestones through [bank rail webhooks](https://docs.settlemint.com/docs/api-reference/webhooks/events#bank-rail). An organisation owner registers an endpoint with the credit or cash-out family subscription. Approval identities and park reasons remain on the authorised bank rail reads and screens. Events carry the payment status, amount and stored time.

With exactly one connection, **Bank rail** opens that token's page directly. With none, or with more than one, it opens the list below. Filter the list by "State" or search it, and select "Bank rail" in the breadcrumb on a token page to return to it. A row marked "Setup incomplete" is a draft connection or has no token yet.

![The Bank rail list with the Add token button and the Token, Bank, Reserve account, State and Created columns](https://docs.settlemint.com/docs/screenshots/console-bank-rail-tokens.light.en.webp)

[Screenshot] The "Bank rail" page shows one row per bank connection.

Each row shows the linked "Token", or "No token linked yet", the "Bank", the "Reserve account" with its currency, the "State" such as "Active", "Draft" or "Suspended" with "Setup incomplete" where it applies, and "Created". The **Add token** button sits on the title row.

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

- **The bank rail on this deployment.** The "Bank rail" entry appears under "Asset lifecycle" only on a deployment that serves the bank rail, and only to accounts that hold the "Bank rail manager" role. A permission manager grants the role on "Roles and permissions".
- **A second manager, where the approval settings ask for one.** [When a second manager decides](#when-a-second-manager-decides) lists the changes that wait for a different "Bank rail manager".
- **Rights on the token.** Activating the token link grants the rail wallet its authority over the token with your wallet. The right you need depends on the token's "Supply mode", which its features set. In "Booked movements" mode, the mode of a token with the [Booked movements](https://docs.settlemint.com/docs/console/asset-management/manage/booked-movements) feature, your account has to administer the token. In "Supply delegate" mode it has to govern the token. If you activate without that right, the refusal names the one you lack. Then someone who administers or governs the token gives the rail wallet that authority before you activate.
- **The rail wallet.** The rail has a wallet of its own. An identity manager has to register its on-chain identity, and it needs gas, the network's fee currency, before the token link activates.
- **Escrow manager.** A bank rail manager who creates the escrow for a token in "Supply delegate" mode also needs the "Escrow manager" role. The escrow sits on the compliance bypass list and its creator picks who controls it, so grant the role only to people you trust. [Pay out from an escrow](#pay-out-from-an-escrow) says which step needs it.
- **A live bank connection.** Until a connection is active or suspended and has a token link, its token page shows "Settings" alone. "Payments", "Clients", "Cash-outs" and "Reconciliation" appear once it is, and a draft connection does not count. [Add a connection](#add-a-connection) and [Activate or suspend a connection](#activate-or-suspend-a-connection) take you there.
- **What the bank gives you.** The bank name, the CompID DALP sends as, the CompID the bank sends as, the reserve account and its currency, and the logon password the FIX session uses. A CompID is the identifier each side uses on the FIX session, the message link to the bank.
- **A token.** The token that represents the reserve currency. It is a DALP token your organisation issued, and no other connection links it. It has Booked movements with the Hold feature and lets holders request a redemption, or it has the supply delegate feature. Its decimals cover the currency's minor units. It has no supply and no other supply delegate. In "Booked movements" mode no other account holds its supply management role, and in "Supply delegate" mode no account holds that role. A connection links one token.

## Steps [#steps]

Set up a bank in this order: add the connection, set the logon password, activate it, then link and activate the reserve token. The token page shows **Settings** alone until the connection is live and has a token link.

### Add a connection [#add-a-connection]

The CompIDs, the reserve account and the matching mode cannot change after you add the connection.

1. On "Bank rail", select **Add token**, or "Connect a bank" when no connection exists yet. A sheet opens.
2. Enter "Bank name", "Reserve account" and "Currency". In **Our CompID**, enter the CompID DALP sends as. In "Bank CompID", enter the CompID the bank sends as. The two CompIDs must differ and may use letters, digits, dots, hyphens and underscores.
3. Under **Credits match by**, choose "Payment reference DALP gives each client" or "Virtual IBAN the bank assigns to each client". With a payment reference, DALP gives each client a reference to put on their transfer. With a virtual IBAN, the bank assigns each client an account number and you enter it when you add the client.
4. Optionally change "Holiday calendar", "Time zone" and "Payment cut-off". [Set when the bank takes payments](#set-when-the-bank-takes-payments) explains them.
5. Select **Add connection**. The button stays unavailable until the form is complete, and the sheet says what is missing beside it. The Console opens the token's "Settings" tab.

The connection starts as a draft with a payout deadline of 7 business days and a settlement window of 1 business day, counted on the connection's holiday calendar. The deadline is how long a cash-out may wait for the bank to pay. The window is the time the bank needs to settle, so a payment instruction goes out only while the deadline leaves at least that much time. A credit that has not minted within the window also raises an operations case, a record of a problem that an organisation owner or platform administrator works, as [Operations cases](#operations-cases) explains. The token's **Settings** tab shows both. To change them or the bank name, use `PATCH /api/v2/bank-rail/connections/{connectionId}`, as the [bank rail API guide](https://docs.settlemint.com/docs/api-reference/guides/bank-rail) describes.

### Set the logon password [#set-the-logon-password]

Saving a new password replaces the old one and ends the live session within ten seconds, and the next logon uses the new password. Agree the new password with the bank before you save it.

1. Open the token and select **Settings**.
2. In the logon password card, enter the logon password agreed with the bank. It takes 8 to 256 printable characters.
3. Select **Save password**. It stays unavailable until the password has 8 to 256 printable characters.

DALP stores the password in the secret store and never shows it again. The card shows only whether a password is set.

### Activate or suspend a connection [#activate-or-suspend-a-connection]

1. Open the token. A draft connection cannot activate until it has a password. **Activate connection** is unavailable until then, and the reason popover links to the logon password card on "Settings".
2. Select **Activate connection** to let the bank log on. The state reads "Active". Until you link a token, the page shows only "Settings". Linking the token makes "Payments", "Clients", "Cash-outs" and "Reconciliation" available. When the linked token first becomes active, setup opens "Payments".

Select **Suspend** to end the live session. A suspended connection keeps its clients and history, records nothing new from the bank and sends no payment instruction until you activate it again.

### Link and activate the reserve token [#link-and-activate-the-reserve-token]

1. On the token's "Settings" tab, open "Token", search for the token by name, symbol or address, and pick it. The list holds only the tokens this connection can link now: tokens you issued with no supply, with decimals that cover the currency, that the rail wallet can mint, and that no other connection links. When no token qualifies, the list says what a token needs. Enter the **Checker threshold** in the currency's major units. It is the amount above which a cash-out needs a second manager. While the "Bank rail" approval row is on, a cash-out waits for a second manager when it brings the client's cash-outs of the last 24 hours, released ones left out, over the threshold.
2. Select **Link token**.
3. Check **Rail wallet identity** on the link. "Pending registration" means an identity manager has to register the rail wallet's on-chain identity first. "Activate token" stays unavailable, with the reason popover, until the identity is registered. "Registered" means the identity is registered, and activation still checks that the token's compliance lets the rail wallet hold the token. "Unavailable" means the identity could not be read, and activation checks it again.
4. Before you confirm anything, the link runs the same checks activation runs and shows the result under the buttons. When a check fails, **Activate token** is unavailable, and the line under it names the blocker and the accounts behind it, for example the accounts that hold the token's supply management role.
5. Select **Activate token** and confirm with your wallet. DALP checks that the rail wallet can hold the token before it submits anything.
6. Until the supply authority reaches the rail wallet, the link shows "Waiting for activation" and says it waits for the grant to confirm. "Activate token" stays unavailable meanwhile. Once the chain shows the rail wallet's authority, the link activates on its own and shows "Active".

The link's **Supply mode** comes from the token's features and does not change later. A token with Booked movements links as "Booked movements": activation grants the rail wallet the token's supply management role. A token with the supply delegate feature and no Booked movements links as "Supply delegate": activation adds the rail wallet as the token's only supply delegate, allowed to mint and burn up to the link's mint cap, or without limit when the link has none. In this mode, credits mint through the delegate, a parked credit is allocated by a plain transfer from the rail wallet, and a return to the payer burns the rail wallet's tokens. Cash-outs in this mode go through an escrow, as [Pay out from an escrow](#pay-out-from-an-escrow) describes.

Activation is refused, for example, when:

- the token already has supply
- in **Booked movements** mode, another account holds its supply management role, unless the link allows other supply managers (see below)
- in **Supply delegate** mode, any account holds its supply management role
- another account is a supply delegate of the token
- the token's compliance does not let the rail wallet hold it
- the rail wallet has no gas

The Console names the first blocker it finds before you confirm with your wallet. When other accounts hold the supply management role, ask a token admin to revoke it from them. When other accounts are supply delegates, ask a token governor to remove them as delegates. Then select **Activate token** again. A link that is still waiting can be removed with "Remove token" while it has no clients. "Remove token" is unavailable on a suspended link, and the reason says to activate the link again first. DALP also refuses the removal while a request to raise the link's credit threshold or mint cap is open, or while a request to allow other supply managers is open.

### Allow another system to book movements [#allow-another-system-to-book-movements]

On a "Booked movements" link, **Allow other supply managers** on the token link lets accounts other than the rail wallet that hold the token's supply management role book mint and burn movements, for example while the bank's own core system books on the same token. The rail wallet must still hold the role.

Turning it on first asks for your wallet confirmation. Closing that step changes nothing. It then opens a request that a different bank rail manager approves or rejects on the same panel. With the "Bank rail" approval row off, it applies at once and is recorded as not approved by a second person. Turning it off applies at once.

The panel lists the current other holders, read from the token. The rail never grants or revokes the role itself. Every grant or removal while the switch is on raises an operations case naming the account. Supply another account books with no bank payment behind it shows as a reserve break, and a redemption another account books before the bank pays is explained on the reconciliation until the bank pays. If the bank then does not pay, a critical case names the account that booked it.

## Read a token page [#read-a-token-page]

A token page opens with the token's name and symbol, the bank, its state, the reserve account and how credits match. Each tab has its own address, so you can link to it. A live or suspended connection with a token link opens on "Payments". A draft connection, or one with no token link, opens on "Settings", which is the only tab it shows, and a link to another tab lands there.

The page has five tabs:

- **Payments**
- **Clients**
- **Cash-outs**
- **Reconciliation**
- **Settings**, which holds the logon password, the reserve token, the "Rail wallet" card, the "AML screening" block, the payout deadline, the settlement window and the "Payment cut-off" with its calendar and time zone. The two CompIDs are in its collapsed "Technical" section, because you only need them when you configure the bank's side of the FIX session.

The title row carries **Edit payment schedule** and "Suspend", or "Activate connection" on a draft or suspended connection.

### Set the credit threshold and the mint cap [#set-the-credit-threshold-and-the-mint-cap]

On "Settings", the reserve token card shows the limits in the token's units. Lowering a value saves at once under wallet verification. Raising or clearing it opens a request that shows the old and the new value and when it expires.

- **Credit threshold** is the amount above which a minted credit waits for a second manager.
- **Mint cap** shows only in "Supply delegate" mode and limits what the rail wallet may mint. Under the field, the card shows how much the rail wallet has minted minus what it burned, as of the last indexed block. When that amount differs from the cap, the card suggests it as a new cap and a button fills the field with it. Set the cap higher to leave room for new credits.
- **Daily report cut-off** is a time and a time zone that "Edit payment schedule" also sets: a balance report sent after it belongs to the next day's reconciliation.

A different bank rail manager selects "Approve" or "Reject" on a pending request, and the other limit stays locked until the request is decided. The manager who opened the request sees a note instead of "Approve" and "Reject".

### Set when the bank takes payments [#set-when-the-bank-takes-payments]

The connection names a holiday calendar, a time zone and a payment cut-off. A new connection starts on the ADGM business days calendar with the UAE public holidays and the `Asia/Dubai` time zone, with no cut-off.

To change them, open the connection and select **Edit payment schedule**. A change applies to new cash-outs only.

- A day is a business day unless the calendar closes it or it is a Saturday or Sunday. With **No holiday calendar**, every day is a business day.
- A cash-out approved at or after the cut-off, or on a closed day, goes on the next business day. Its row shows the new value date and says it is queued for the next opening.
- The rail sends no new instruction while the bank is closed. A day closed after a cash-out was queued moves its value date to the next open day.
- The payout deadline and the settlement window count business time on this calendar.

### Screen payments with your AML provider [#screen-payments-with-your-aml-provider]

DALP sends every confirmed bank credit that matched a client, and every cash-out before its payment instruction goes out, to the AML provider the connection names. The **AML screening** block on "Settings" shows the provider ID, the level and whether the payer account is checked, with "Edit settings" and "Export results".

1. Select **Edit settings**. Enter the provider ID of the AML provider linked in your compliance settings, as a UUID, and the level name the provider uses for fiat transactions. Leave the level empty to use the provider's default, and leave the provider empty to turn provider screening off.
2. Choose whether to **Check the payer account of every credit**. It is on for every connection until you turn it off. A credit from an account the client has not had approved waits until a manager retries it and a second manager approves the mint. The check needs no provider.
3. Select **Save settings**. If another manager saved the settings after you opened the page, DALP refuses the change as stale. Open the page again and repeat it.

A credit the AML check rejects or holds, or whose payer account is not one of the client's approved accounts, shows **Parked** with that reason and the account it was paid from. Nothing is minted. Select "Retry", then another bank rail manager approves the mint, even while the "Bank rail" approval row is off. A cash-out the check rejects or holds shows "Waiting for approval" and sends no payment instruction until a manager other than the system approves it. Rejecting the approval releases the cash-out.

To hand the results to your compliance team, select **Export results**, choose a "From" and a "To" date and select "Download CSV". The file lists every screening created in that range, with the payer, the verdict, the score, the payer check and who released it. The dates cover whole days in UTC. Leave "From" empty to start at the first screening, or "To" empty to include every screening up to the download. "From" and "To" refuse a typed day that does not exist, such as `2026-02-30`, and show a message under that field. "Download CSV" stays unavailable until you correct or clear that date. It also stays unavailable while "To" comes before "From".

## Follow payments [#follow-payments]

Open the token and select **Payments**. The table lists every credit the bank reported, newest first, with the value date, the amount, the client it matched, or the payer's reference when none matched, its status, the "Bank transaction" and the mint transaction once it settles. A copy button beside the bank transaction and the mint transaction copies the whole value. Filter the list by status. The page refreshes every 10 seconds, and "Show more" loads older credits.

A credit that matched a client and passed screening shows "Minted". When the token link has a credit threshold and the "Bank rail" approval row is on, every credit that exceeds it shows "Waiting for mint approval" first, including a credit that matched no client. With the row off, the credit mints at once. DALP adds the client's credits of the last 24 hours to a matched credit before it compares. A bank rail manager selects **Approve** or "Reject". Once approved, the credit mints to the client, or parks with a reason. A rejected or expired request parks it with the reason "Another manager did not approve the mint". The [bank rail API guide](https://docs.settlemint.com/docs/api-reference/guides/bank-rail#approve-a-credit-before-it-mints) describes how to set the credit threshold through the API.

A credit is a bank transfer the rail has recorded. A credit that did not match, or whose wallet the token blocks, mints to the rail wallet, which holds the tokens there as suspense, and shows **Parked** with the reason. A credit for a client that takes delivery through a custody gateway also mints to the rail wallet, where the tokens wait on their way to the gateway, and shows "Minted". Each parked credit has an operations case, which [Operations cases](#operations-cases) explains. [Parked credits](#parked-credits) lists each reason and what to do. Once a manager allocates a parked credit, the row shows "Allocated", names the client that received it and no longer shows the park reason.

![A token page on the Payments tab, with the Value date, Client, Amount, Status and Bank transaction columns and an Allocate button on a parked credit](https://docs.settlemint.com/docs/screenshots/console-bank-rail-payments.light.en.webp)

[Screenshot] The table shows a "Parked" credit with no matching client and an "Allocate" button, and three "Minted" credits with their clients.

Above the table sit the token header with the bank, the state, the reserve account and how credits match, the "Edit payment schedule" and "Suspend" buttons, and the "Payments", "Clients", "Cash-outs", "Reconciliation" and "Settings" tabs.

### Recall a credit [#recall-a-credit]

When the bank reverses a credit it confirmed, the rail records a recall and the credit stops minting. "Payments" shows **Open recall** on that credit. It opens a sheet with the recall's state, the bank's reversal ID, the amount, the mode, the target wallet, what was recovered, the excess, the written-down amount and every recorded claw.

1. In "Received", select **Request execution**. A different bank rail manager selects "Approve" or "Reject", and the sheet names the action that waits. You cannot decide your own request.
2. In "Clawing", the tokens must leave the target wallet. For a custodian, the sheet links to the token's forced transfer and shows the target's free and escrow balances. In "Supply delegate" mode, enter the claw's transaction hash and log index, then select **Record claw**. The button stays off until both are valid. Select "Close claw" when the tokens are back.
3. The rail burns the recovered tokens and the recall ends **Recalled**.

To drop a recall, select **Abandon** and enter a reason. The dialog says the bank's debit stays a reserve difference until a manager records a [reserve adjustment](#explain-a-difference-with-a-reserve-adjustment), and a second manager must approve. An approved abandon lets the credit mint again. A refused step shows its own message, for example that the mint is still in flight or that a cash-out of the client is live.

### Allocate or return a parked credit [#allocate-or-return-a-parked-credit]

1. Select **Allocate** on a parked credit and, when it matched no client, pick the client to pay. When the credit matched a client whose link was removed from "Clients", the dialog says so. Pick another link of the same client. The list shows only that client's links, and a client with no link left has to be added again first. To send the money back instead, wait until the bank has refunded the payer, select "Return to payer" and enter the bank's refund reference.
2. Select **Request allocation** or "Request return". With the "Bank rail" approval row off, the Console says no second approval is needed and the rail moves or burns the parked tokens at once. With the row on, the credit shows "Waiting for approval".
3. A different bank rail manager selects **Approve** or "Reject" on the same row. You cannot decide your own request. Approving moves or burns the parked tokens, and rejecting leaves the credit parked.

While a request waits on a credit that holds parked tokens, **Allocate** and "Return to payer" stay on the row. A credit that minted nothing hides "Allocate" and "Return to payer" while a request waits. Asking again replaces the open request, which is also how any manager asks again after a request expires.

### Review matches from a bank statement [#review-matches-from-a-bank-statement]

The Console assistant can read a bank statement and propose which client each unmatched payment belongs to. Open [Search](https://docs.settlemint.com/docs/console/essentials/search), select **Draft from a document** and choose the statement as a PDF of at most 20 MB. DALP reads the file once and deletes it. It opens the token page of the connection with the most matching payments, where "Matches from your bank statement" lists each proposed match above the "Payments" table. When other connections also have payments on the statement, a line says how many, so you open each one and draft from the document again.

Select **Review** on a match to open the allocation for that payment with the proposed client filled in, then request the allocation as in [Allocate or return a parked credit](#allocate-or-return-a-parked-credit). Nothing moves until you request it. Select "Dismiss" to close the list. A statement on which no unmatched payment appears says "No unmatched bank rail payment appears on this statement."

## Add a client [#add-a-client]

A client is a participant wallet whose bank transfers mint to it. Adding one gives it a payment reference or a virtual IBAN to put on its transfers.

![The Clients tab with the Clients and Bank accounts sub-tabs and the Client, Deposit instructions, Wallet and Created columns](https://docs.settlemint.com/docs/screenshots/console-bank-rail-clients.light.en.webp)

[Screenshot] The clients table shows one row per client with the "Client", the "Deposit instructions" holding the reference or IBAN, the "Wallet" and "Created", and the "Add client" button.

1. Open the token and select **Clients**.
2. Select **Add client**, then choose a "Participant" and one of its wallets in "Wallet", in the sheet that opens.
3. On a virtual IBAN connection, enter the IBAN the bank assigned in **Virtual IBAN**. On a payment reference connection, DALP generates the reference and the table shows it under "Deposit instructions".
4. Select **Add client**.

The **Participant** list holds every person who is a member of the organisation, without any extra role. Tokens, companies and other entities are not listed, because they cannot be bank rail clients. A directory role does not change this.

**Add client** stays unavailable, with the reason popover, until the connection has a token link. DALP refuses a client when the token's compliance blocks the client's wallet for a reason the client cannot fix themselves.

No email carries the reference or IBAN. The client reads it, with the bank name and reserve account to pay, in the Investor portal under the **By bank transfer** deposit method, as [Bank transfers](https://docs.settlemint.com/docs/concepts/operating/investor-portal-bank-transfers) describes, or through `GET /api/v2/users/me/bank-links`. You can also give it to the client yourself.

No two clients of a connection share a payment reference or a virtual IBAN.

Removing a client asks for confirmation first. The wallet keeps its balance, but the deposit instructions stop working. **Remove** is unavailable while the client has a proposed or active bank account, so refuse or revoke those first.

## Review bank accounts [#review-bank-accounts]

A cash-out pays only to an active bank account of the client. A client proposes an account for their own link, or a bank rail manager adds one through the API. It receives nothing until a bank rail manager other than the proposer approves it, whoever proposed it. This rule holds whatever the approval settings say.

On the token's "Clients" tab, open **Bank accounts**. It lists every account of the connection with the client, the IBAN or account number, the holder and bank, and its status. It reads "Proposed", "Active", "Refused" or "Revoked". Filter the list by status. A refused or revoked account stays listed with the reason.

- On a "Proposed" account, select **Approve**. The account becomes "Active". You cannot approve an account you proposed. "Approve" is unavailable in that row's menu and says another manager has to approve, and you can still refuse it from the same menu.
- To turn a proposal down, open the row menu, select **Refuse**, enter a reason and confirm. The account stays listed as "Refused" and never receives a payout.
- To stop payouts to an "Active" account, open the row menu, select **Revoke**, enter a reason and confirm. A cash-out the bank has not been instructed to pay is released, and the row shows "The bank account was revoked".

## Pay out a redemption [#pay-out-a-redemption]

In "Booked movements" mode a manager records the cash-out, as this section describes. In "Supply delegate" mode the client records it, as [Pay out from an escrow](#pay-out-from-an-escrow) describes.

A client who wants their money back requests a redemption on the token from their own wallet, with **Request redemption** on the token's Booked movements card in the Investor portal, as [Booked movements](https://docs.settlemint.com/docs/console/asset-management/manage/booked-movements) describes, or `POST /api/v2/tokens/{assetId}/features/register-lines/lines`, which opens a redemption line. The request holds the tokens, so the client cannot spend them while the bank pays. The bank rail then pays the client's approved bank account and burns the tokens once the bank confirms the payment, so the reserve and the supply go down together. When the bank pays and the burn does not complete, the cash-out shows "Unbooked" until you work its operations case.

1. Open the token, select "Cash-outs" and select **Record cash-out**.
2. Pick the client, one of its open redemption requests and one of its active bank accounts. The panel shows the amount the bank pays.
3. Select **Record cash-out**. The rail adds the client's cash-outs of the last 24 hours, leaving out released ones, and compares the total with the token link's "Checker threshold". At or below it, the cash-out is approved at once. Over it, and only while the "Bank rail" approval row is on, the row shows "Waiting for approval" and a different bank rail manager selects "Approve" or "Reject". You cannot decide your own cash-out. An approved cash-out goes to the bank in its next opening, as [Set when the bank takes payments](#set-when-the-bank-takes-payments) describes.

DALP refuses a cash-out for a client whose participant account is suspended, closed, terminated or restricted from withdrawals, in either supply mode, and a checker cannot approve one for them. A checker can still reject it. A cash-out already approved when the restriction starts is released before the payment instruction goes out, or before its tokens lock in **Supply delegate** mode, and the row shows "Released" with the reason. An administrator can lift a suspension, closure or restriction on the participant's account status before the client cashes out again. A terminated account stays terminated, so that client cannot cash out.

The rail sends the payment instruction to the bank once, before the payout deadline less the settlement window. When the bank reports the payment settled, the rail burns the held tokens and the row shows "Paid" with the transaction. When the bank rejects the payment or does not settle it by the deadline, the rail cancels the request, the client gets the tokens back and the row shows **Released** with the reason. A client can also cancel their own request before the payment goes out.

Under the client's name, the row says where the tokens wait: the redemption line in "Booked movements" mode, or the escrow address with its lock ID, which you can copy, in "Supply delegate" mode. In "Supply delegate" mode, an organisation owner or platform administrator also finds **Open escrow** in the row menu. It opens the escrow on "Asset lifecycle", then "Escrows". Other managers see the address alone.

The bank can send a paid payout back, for example when the client's account was closed. The row then shows **Returned, re-crediting** and, once the rail has opened a credit for the returned money, "Returned, credit opened". That credit appears on "Payments" with the bank's return ID. A returned-payout credit always waits for another bank rail manager's mint approval, whatever the credit threshold and even while the "Bank rail" approval row is off. DALP cannot return it to the payer, because the bank already refunded them. Under the amount, the row notes each returned amount, and once the returned payment has arrived it links to that credit on "Payments".

![The Cash-outs tab with the Record cash-out button and the Client, Destination account, Amount, Status, Payout deadline and Created columns](https://docs.settlemint.com/docs/screenshots/console-bank-rail-cash-outs.light.en.webp)

[Screenshot] The cash-outs table shows one row per cash-out with the "Client", the "Destination account", the "Amount", the "Status", the "Payout deadline" and "Created", and the "Record cash-out" button.

### Pay out from an escrow [#pay-out-from-an-escrow]

A token without Booked movements has no redemption request to hold the tokens. In **Supply delegate** mode an escrow holds them instead: an escrow is a contract that keeps a holder's tokens locked until a set time. The rail wallet controls the escrow and releases or pays each lock. After a lock ends, the holder can take the tokens back. A token custodian can move tokens out with the escrow's forced transfer, locked or not, and the escrow sets no limit. The Platform API refuses a lock whose cash-out the bank may still pay, and returns an unpaid cash-out's lock only to its owner during a compromised rail wallet rotation. Without the lock, a client could spend the tokens after the bank had already paid them.

The rail wallet controls one escrow on each network, which every "Supply delegate" link on that network uses. A "Supply delegate" link shows an **Escrow** block on the "Settings" tab. A "Booked movements" link has no escrow and shows no block. The block has four states:

- No escrow yet: the block reads "No escrow holds tokens for this link yet" and offers **Create escrow**. Select it and confirm with your wallet. The manager's acting wallet signs the creation, and the rail wallet controls the new escrow.
- **Being created.** The page checks again every five seconds and shows the transaction.
- **Ready.** The block names the escrow. An organisation owner or platform administrator also sees "Open escrow", which opens the escrow under "Asset lifecycle", "Escrows". Other managers see the address alone.
- "More than one escrow matches this token link": the rail cannot tell which one to use, so the block lists the escrows. The rail refuses cash-outs until only one remains.

**Create escrow** needs the "Escrow manager" role on the wallet you act through. Without it, the button is unavailable and the reason popover says so, even for a bank rail manager who manages the system. Ask a permission manager to grant "Escrow manager" to that wallet on "Roles and permissions". "Create escrow" is also unavailable while the link is suspended and while the Console checks your roles. The API route is `POST /api/v2/bank-rail/connections/{connectionId}/token-links/{tokenLinkId}/escrow`, and it refuses with `data.reason` `escrow-manager-missing` for the same case. Any bank rail manager reads the escrow with `GET` on the same path. The rail refuses cash-outs while the rail wallet controls no escrow, or more than one.

A cash-out in this mode names an amount, not a request, and the client records it through the API for their own account, at `POST /api/v2/users/me/bank-cash-outs`. A bank rail manager cannot record one for them: on "Cash-outs", **Record cash-out** is unavailable, with "This token uses Supply delegate mode, so each client requests a cash-out from their own wallet." beside it. The manager follows each row on "Cash-outs" and decides the ones over the threshold. The cash-out itself runs in three steps:

1. The client approves the escrow, from their linked wallet, to take at least the amount.
2. The client records the cash-out with the amount and one of their active bank accounts. The request must carry an `Idempotency-Key` header. DALP refuses it without one, and a retry with the same key returns the same cash-out.
3. The rail moves the tokens into the escrow and locks them until the payout deadline. The same checker threshold and approval setting apply. After a checker approves, the rail locks the tokens again with a new deadline, so the bank gets the full payout time.

When the bank reports the payment settled, the rail takes the locked tokens and burns them, and the row shows **Paid**. When the bank rejects the payment or the deadline passes, the rail unlocks the tokens and the row shows "Released", and the client withdraws them from the escrow. When the client's approval does not cover the amount, the request is refused. When the approval drops before the rail moves the tokens, the cash-out is released with the reason "The escrow could not lock the holder's tokens", no payment goes out, and an operations case says what to do.

The request answers while the rail still locks the tokens. A bank rail manager's integration that waits for the lock, the checker step or the payment follows the cash-out's stream instead of reading it again and again, as the [bank rail API guide](https://docs.settlemint.com/docs/api-reference/guides/bank-rail#follow-a-cash-out) describes.

## Read the reconciliation [#read-the-reconciliation]

![The Reconciliation tab reading Clear, with the Bank balance, Token supply, Reserve unexplained and Suspense unexplained figures and the two line tables](https://docs.settlemint.com/docs/screenshots/console-bank-rail-reconciliation.light.en.webp)

[Screenshot] The "Reconciliation" tab shows the verdict "Clear" at the top, then four figures: the "Bank balance" with the newest report's time and business day, the "Token supply", "Reserve unexplained" and "Suspense unexplained".

Below the figures sit two tables, "Bank balance against supply" and "Rail wallet against parked credits", each with its lines, counts and amounts.

Open the token and select **Reconciliation**. Two lines are compared per connection:

- **Bank balance against supply.** The bank's newest balance report against the token's supply, taking credits in flight, payouts the bank settled before or after the report, payouts another supply manager booked before the bank paid, open recalls, recalls the rail completed after the report and approved reserve adjustments into account. A recall is a bank request to take a payment back after it was credited.
- **Rail wallet against parked credits.** The tokens the rail wallet holds against the credits parked as suspense, the tokens clawed back for a recall that the rail has not burnt yet, and the credits on their way to a client's custody gateway, which the table shows as "Minted, delivering to a custody gateway".

The page opens with the verdict and the date of the bank balance, then four figures: the bank balance, the token supply and the unexplained amount of each line. Each figure has an info button that explains how it is calculated. Findings follow when something needs attention: other accounts that hold the supply role or are supply delegates, a rail wallet that lost its supply authority, overdue credits and open recalls. A table under each line shows the amounts behind it, and **Rail wallets** lists each rail wallet with its role, supply authority and token balance.

The bank balance figure also names the business day the report belongs to: "Business day", then the date and the connection's time zone. A report that arrives on a day the bank is closed belongs to the last open day before it. While a credit is parked, a line under the **Rail wallet against parked credits** table reads "Oldest parked credit" with the number of business days the oldest one has waited. Both count business days on the connection's holiday calendar. Without a calendar, every day is a business day, weekends included.

Each unexplained figure reads "Adds up" or "Does not add up". The status is "Clear" when both lines are explained. It is **Break** when:

- either line has an unexplained difference
- in "Booked movements" mode, another account holds the token's supply management role, unless the link allows other supply managers and the rail wallet still holds it
- in "Supply delegate" mode, any account holds the token's supply management role
- another account is a supply delegate of the token
- the rail wallet lost its own supply authority
- after a rail wallet rotation, the old wallet still holds tokens and is not frozen on the token

**Unavailable** means the supply, a balance or the token's roles could not be read, or the indexer did not supply an unchanged drained block at or beyond finality, so nothing is judged. The rail retries that report once the facts are available. "No report" means the bank has sent no balance report for the reserve account yet, or the connection has no token link yet.

### Keep a daily version [#keep-a-daily-version]

The [daily reconciliation API](https://docs.settlemint.com/docs/api-reference/guides/bank-rail#daily-reconciliation) keeps both lines and their evidence pins as immutable versions per connection date. A manager can reread a version or export its CSV. The bank report is selected at or before the connection's cutoff, and the token facts are the indexed facts available when the run executes. The worker retries unavailable days within the last three closed days and raises one warning if a day leaves that window incomplete, including while the connection is suspended. That warning also covers an attempted date whose cutoff or store failure prevented any version from being stored.

### Explain a difference with a reserve adjustment [#explain-a-difference-with-a-reserve-adjustment]

A bank fee, interest or a refund to a payer moves the bank balance without a credit or a cash-out, so the reconciliation shows an unexplained difference. A bank rail manager records the posting as a reserve adjustment through the API. While the **Bank rail** approval row is on, a different manager approves or rejects it. With the row off, it is approved at once. An approved adjustment explains the difference from the next balance report on, and the operations case for the break clears when that report reconciles. The [bank rail API guide](https://docs.settlemint.com/docs/api-reference/guides/bank-rail#reserve-adjustments) lists the fields.

## Rotate the rail wallet [#rotate-the-rail-wallet]

The rail wallet is the key the rail uses to sign mints, burns and escrow moves. Rotation replaces the key when it is compromised or lost. It spans several people, because the rail wallet holds supply authority on each linked token, and the people who manage those tokens are often not the bank rail managers. The [rail wallet incident runbook](https://docs.settlemint.com/docs/console/asset-lifecycle/bank-rail/wallet-incident) defines both cases, gives the order of the steps and says who you need and what each person does.

Open the token and select **Settings**. The "Rail wallet" card shows the "Generation", "State" and "Address" of the wallet. The state is "Active", "Staged", "Contained" or "Retired".

### Contain the wallet [#contain-the-wallet]

1. Select **Contain rail wallet**.
2. Choose why the key is being replaced. Choose **Compromised** or "Lost". A note is optional.
3. Read "What happens" and select **Contain rail wallet**.

DALP signs nothing new with the key once it is contained, and completion waits until the contained wallet has no queued writes, no grant of supply authority still on its way to it, and no supply authority left on a linked token. Every token link is suspended and no credit is minted. A cash-out the bank has not been instructed to pay is released with "The token link is no longer active", so the client gets the tokens back. The rail prepares a replacement wallet, which signs nothing until you complete the rotation. On a rotation opened as "Lost", **Report compromised** turns it into a compromised rotation at once. It drops any open abandon request, the rail never signs with the old wallet again, and nothing reverses it. Whoever holds a compromised key can still sign with it until each token revokes its authority and the old escrow is emptied.

### Work the checklist [#work-the-checklist]

The **Rotation checklist** lists each step in order, with its status as text. It reads "Done", "Yours to do", "Waiting on" a named role, "Blocked by" an earlier step, "Not applicable" or "Failed". "Next" marks the first step you can act on or, when there is none, the step that holds the others up. A step names the role it needs, the token it applies to and, where the Console can read them, the people who hold that role.

Each step links to the screen where it is done through "Open the token's permissions", "Open the token's holders", "Go to the escrow" or "Open identities". "Go to the escrow" opens the token's "Settings" tab on the bank rail, where the **Escrow** block sits.

**Copy link** copies the step's address to send to the person. If you hold the token role yourself, "Revoke authority" or "Grant authority" appears on the step and asks for your wallet. The checklist updates once DALP sees the result on the chain.

The steps are:

1. **Contained**.
2. **New wallet identity registered**, by an identity manager. Fund the new wallet with gas before the grant.
3. Then, for each token:
   - **Authority revoked**, by a token admin or, for a supply delegate link, a token governor.
   - **Old escrow protected**, by a token custodian, who empties the old escrow with its forced transfer. It appears for a supply delegate link whose old escrow holds tokens, and for every supply delegate link on a compromised rotation.
   - **Authority granted**, by the same role that revoked it, once the new wallet's identity is registered. On a compromised rotation it stays blocked until no link leaves authority with the old wallet and no old escrow holds tokens.
   - **Escrow created**, for a supply delegate link, by an escrow manager.
   - **Suspense moved**, by a token custodian, with the amount and an "Open the token's holders" link, where the custodian makes the forced transfer. The amount covers the credits held in suspense and the coins of credits still on their way to the client's custody gateway. Those coins are repinned to the new wallet when the rotation completes, so their delivery sends from it. A credit that is mid-send from the contained wallet blocks completion until it lands or fails.
4. **Request completion**, by a bank rail manager.
5. **Approve completion**, by a second bank rail manager.

On a compromised rotation, every "Authority revoked" and "Old escrow protected" step moves up to follow **Contained**. Until DALP sees no authority left with the old wallet, the card says the old key still holds supply authority on a number of links.

### Request and decide completion [#request-and-decide-completion]

**Request completion** stays unavailable, with the reason popover, until every earlier step is done. [What blocks completion](https://docs.settlemint.com/docs/console/asset-lifecycle/bank-rail/wallet-incident#what-blocks-completion) lists the other refusals.

While the "Bank rail" approval row is on, a different bank rail manager selects **Approve** or "Reject" on the request. With the row off, the request is approved at once and the rotation completes on the next read. The dialog shows the "Old wallet" and "New wallet" addresses and how many token links move with their open credits. Reject needs a reason, and the requesting manager sees it and can select "Request again". You cannot decide your own request. On approval, the links, their open credits and the rail's signing key move to the new wallet in one step. Credits that parked while the wallet was contained mint from the new wallet without a manual retry. Requests to allocate or return a parked credit that were still waiting are cancelled, so ask again. Credits waiting for mint approval ask for it again.

A lost key can be abandoned with **Request abandon**, which a second manager approves while the "Bank rail" approval row is on. Abandoning is refused once a manager has submitted a revoke or grant for the rotation, or once any token link's supply authority has left the contained wallet. A compromised rotation cannot be abandoned.

### Read both wallets on the reconciliation page [#read-both-wallets-on-the-reconciliation-page]

During a rotation, **Rail wallets** on "Reconciliation" has one row per wallet with its address, its role as "Current rail wallet", "Next rail wallet", "Contained rail wallet" or "Previous rail wallet", its supply authority and its token balance. The old wallet's balance moves to the new one at the "Suspense moved" step. The retired wallet stays listed as history. A retired wallet that still holds tokens but is frozen on the token raises an operations case, not a "Break".

### Recover an unbooked delegate cash-out [#recover-an-unbooked-delegate-cash-out]

When the cause of an "Unbooked" cash-out on a supply delegate link is a compromised escrow, a token custodian first moves the locked tokens to the rail wallet with the escrow's forced transfer. Then select **Recover** on the cash-out row. "Unbooked" means the bank paid but the tokens were not burnt. The rail records the transfer and burns the tokens, and the row shows "Paid".

## Emails to the client [#emails-to-the-client]

The platform emails a client when a bank payment or a cash-out reaches an outcome. The email goes to the client the payment or cash-out belongs to, in the language of that client's account. A client with no email address on file gets none, and so does a platform with no mail transport configured. The credit or the cash-out itself is never affected, and no bank message, credit or approval waits for the email.

| Event | Message |
| --- | --- |
| A credit mints or is allocated to the client's wallet | Deposit credited |
| A parked credit is returned to the payer | Deposit returned |
| A checker refuses a cash-out | Cash-out rejected |
| The bank rejects the payment | Cash-out rejected, naming the bank as the reason |
| The bank confirms the payment | Cash-out paid |
| The bank returns the payout | Cash-out returned, with the returned amount |

Each email shows the amount and the reference. Its button opens **Transfers** in the client's portfolio, filtered to that reference, or the portfolio for a rejected or paid cash-out. If no Investor portal URL is configured, the button opens the client's portfolio in the Console without a transfer filter. An email goes out at most once per outcome, so a bank message that arrives again sends nothing new, and an email that fails to send is not retried. A credit that was ever held for screening sends no deposit email, even after a manager allocates it, retries its mint or returns it to the payer.

## When a second manager decides [#when-a-second-manager-decides]

A different **Bank rail manager** always approves a bank account, and a raise of the credit threshold or the mint cap always waits for a different bank rail manager, whatever the approval settings say. The credit threshold is the amount above which an incoming credit waits for mint approval, and the mint cap limits what the rail wallet may mint.

The organisation's "Bank rail" row under "Approvals" on [General settings](https://docs.settlemint.com/docs/console/organisation-settings/general#approvals) is off until an organisation owner or platform administrator selects **Turn on**, and the row then reads "Second person required". While it is on, a different manager decides:

- a cash-out over the checker threshold
- an allocation or a return of a parked credit
- a credit over the credit threshold
- a reserve adjustment
- the completion or abandoning of a rail wallet rotation

With the row off, these go ahead at once, and "Actions" records each one as "No second approval (approval off)". A credit that re-credits a returned payout waits for mint approval even then. You cannot approve your own proposal or decide your own request. When **Approvals required** for the row is greater than 1, each change in this list needs that many different people to approve it, and only an organisation owner who also holds the Bank rail manager role can decide it. A request nobody decides within 7 days expires.

## Operations cases [#operations-cases]

An operations case records a problem the platform cannot resolve itself. An organisation owner or platform administrator acknowledges the case and resolves it with an investigation note, or the platform resolves it when the problem clears. The [webhook events guide](https://docs.settlemint.com/docs/api-reference/webhooks/events#operations) describes cases.

An organisation owner or platform administrator opens "Organisation settings", then "Custody". The **Cases** tab appears there only on a deployment with custody operations. The page is titled "Custody", and the "Operations cases" table lists the cases. Expand a row to see its "Case id" and its "Reason". A bank rail manager who cannot open the tab asks an organisation owner or platform administrator to work the case.

The **Payments** table does not show a parked credit's case ID, and on the bank rail screens only an "Unbooked" cash-out shows its case ID. The "Reason" of a parked credit's case starts with "Bank credit", then the credit's "Bank transaction" value from "Payments". Give the owner that value to find the case. A manager with an API key can instead list the credits with `GET /api/v2/bank-rail/connections/{connectionId}/credits`. Each credit's `caseId` field holds the case ID.

## Parked credits [#parked-credits]

A parked credit shows its reason on **Payments**. Each credit has an operations case.

| Reason shown | What to do |
| --- | --- |
| No client matches the payment reference | Add the client on **Clients**, then **Allocate**. If the bank refunded the payer, **Return to payer**. |
| The client's wallet is blocked | Fix the wallet's eligibility, then **Allocate**. Or **Return to payer**. |
| The client's wallet needs action | Fix the wallet's eligibility, then **Allocate**. Or **Return to payer**. |
| More decimals than the currency allows | **Allocate** to the client, or **Return to payer**. |
| The rail wallet lost its supply authority | Fix the cause, then **Retry**. Nothing was minted. |
| The client's custody gateway fails a delivery check | Make the gateway pass its delivery checks, then **Retry**. Nothing was minted. |
| The mint transaction failed | Fix the cause, then **Retry**. Nothing was minted. |
| The mint would exceed the rail wallet's mint cap | Raise the link's mint cap through the API, as the [API guide](https://docs.settlemint.com/docs/api-reference/guides/bank-rail#approve-a-credit-before-it-mints) describes, then **Retry**. Nothing was minted. |
| Another manager did not approve the mint | **Retry** asks for approval again, and you cannot approve a mint you retried. Or **Return to payer**, which DALP refuses for a credit that re-credits a returned payout. |
| The payer's account is not an approved account of the client | Ask the client to propose the account and approve it on **Clients**, or turn off the payer check. Then **Retry**. A mint approval cannot replace approval of the payer account. Or **Return to payer**. |
| The AML check rejected this payment | Review the provider's finding. **Retry** asks for approval, and another manager decides. Or **Return to payer**. |
| The AML check is holding this payment for review | Wait for the provider's decision. **Retry** asks for approval once it answers, and another manager decides. Or **Return to payer**. |
| The token cannot hold this amount | Nothing was minted. Work it through the operations case. |

Whatever reason a credit shows, when the client's link was removed from "Clients" after the payment matched, **Allocate** asks for another link of the same client. A client with no link left has to be added again first, or the credit goes back to the payer.

Fiat screening exports include provider alerts. Each provider decision also creates a case linked to the investor, with the verdict and alerts.

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

- **The connection is live.** On the token's "Settings" tab, the connection's state reads "Active", and the token page shows "Payments", "Clients", "Cash-outs" and "Reconciliation". The state shows that DALP accepts the bank's logon. The token page does not show whether the bank has logged on. Once the bank has sent a balance report, check that the bank balance on "Reconciliation" reads "Newest bank report" with the report's time in place of "No report yet".
- **The reserve token is active.** On the "Settings" tab, the "Link state" of the token link reads "Active" and "Rail wallet identity" reads "Registered".
- **A client is set up.** The client appears on "Clients", with its payment reference or IBAN under "Deposit instructions".
- **A bank account is approved.** On "Clients", "Bank accounts" shows the account as "Active".
- **A credit arrived.** On "Payments", the credit shows "Minted" with a mint transaction, or "Allocated" with the client that received it. "Parked" and "Waiting for mint approval" mean the client has not received it yet.
- **A payout settled.** On "Cash-outs", the row shows "Paid". "Bank paid" means the bank has paid and the rail is still burning the tokens.
- **The books agree.** On "Reconciliation", the status reads "Clear".

## Troubleshooting [#troubleshooting]

| What you see | What it means and what to do |
| --- | --- |
| The **Bank rail** entry is missing from the sidebar, or a token page shows **Settings** alone | The entry needs the "Bank rail manager" role on a deployment that serves the bank rail. The other four tabs need a connection that is active or suspended and has a token link. |
| **Activate connection** is unavailable, with "Set the logon password first" beside it | The draft connection has no logon password. [Set the logon password](#set-the-logon-password), then select **Activate connection**. |
| The connection reads **Suspended** | A manager suspended it. It records nothing new from the bank and sends no payment instruction. Select **Activate connection** to resume. |
| **Rail wallet identity** reads **Pending registration** | An identity manager has to register the rail wallet's on-chain identity. Then select **Activate token** again. |
| **Remove** on a client is unavailable, with "This client still has a proposed or active bank account. Refuse or revoke it under Bank accounts, then remove the client." | Refuse or revoke the client's accounts on **Bank accounts**, then remove the client. |
| **Add client** is unavailable, with "Link the connection's token on the Settings tab before you add a client." | The connection has no token link. [Link the reserve token](#link-and-activate-the-reserve-token), then add the client. |
| **Add client** says "The wallet is blocked and cannot be linked." | The token's compliance blocks the client's wallet. Fix the wallet's eligibility, or pick another wallet. |
| **Activate token** is refused | The Console names the first blocker. Fix it and select **Activate token** again. [Link and activate the reserve token](#link-and-activate-the-reserve-token) lists the usual ones. |
| The token link reads **Suspended** with "The rail suspended this link" | The page gives the reason. The link still records the bank's credits but mints none. Fix the token, then select **Activate token again** and confirm with your wallet. A link suspended by a rail wallet rotation comes back when the rotation completes or is abandoned. |
| A payment shows **Parked** | [Parked credits](#parked-credits) lists the reason shown and what to do. |
| A cash-out shows **Released** | The row names the reason, for example "The bank rejected the payment" or "The payout deadline passed". A cash-out over the threshold that nobody decides within 7 days is also released, and its row shows "The payout deadline passed". This 7-day limit is fixed. The holder's tokens are free again. In **Supply delegate** mode the client withdraws them from the escrow. |
| A cash-out shows **Unbooked** | The bank paid but the tokens were not burnt, so the token's supply is larger than the reserve. Work it through the operations case the row names. |
| **Reconciliation** shows **Unexplained difference** | A bank fee, interest or a refund to a payer can cause it. [Explain a difference with a reserve adjustment](#explain-a-difference-with-a-reserve-adjustment). |
| **Reconciliation** shows **Break** and names other holders or delegates, or says the rail wallet lost its authority | The screen names the other accounts that hold the supply management role or are supply delegates, or says the rail wallet no longer holds its authority over the token. Fix the cause it names. |

## API routes [#api-routes]

Every task on this page also runs through the bank rail routes of the Platform API, and a few run only there:

- changing the bank name, the payout deadline or the settlement window
- adding a bank account for a client
- setting the credit threshold or the mint cap, and approving a raise of either
- recording and deciding a reserve adjustment
- changing the messages the bank may send on a connection

The [bank rail API guide](https://docs.settlemint.com/docs/api-reference/guides/bank-rail) covers them, and [API keys](https://docs.settlemint.com/docs/console/my-account/api-keys) says how to get a key to call them.


# Rail wallet compromised or lost

Source: https://docs.settlemint.com/docs/console/asset-lifecycle/bank-rail/wallet-incident
Replace the bank rail wallet when its key is compromised or lost: who you need, the order of the steps, and what happens to money in flight.

When the rail wallet's key is compromised, so someone else may hold it, or lost, so nobody can sign with it, contain the wallet first from "Bank rail", the token, **Settings**, then replace it with a rotation. The rail wallet is the key the bank rail signs mints, burns and escrow moves with. It holds supply authority on every linked token, which means it can create and destroy that token's supply. A rotation replaces the key with a new generation. It needs several people, because the people who manage a token are often not the bank rail managers. The [bank rail Console guide](https://docs.settlemint.com/docs/console/asset-lifecycle/bank-rail#rotate-the-rail-wallet) describes the token's "Settings" tab and the other screens used below.

Containing the wallet only stops DALP from signing. Whoever holds a compromised key keeps its on-chain power until people revoke it on each token, and keeps full control of the old escrow until its tokens are moved out, so the revokes come first on a compromised key.

![Settings tab of a bank rail token with Network, Supply mode, Link state, Rail wallet, Rail wallet identity and Checker threshold, and the Escrow card below](https://docs.settlemint.com/docs/screenshots/console-bank-rail-settings.light.en.webp)

[Screenshot] The "Settings" tab of the Demo bank euro token lists Token, Network, Supply mode, Link state, Rail wallet, Rail wallet identity and Checker threshold.

The "Escrow" card below the fields shows the "Controller wallet" with the **Rail wallet** badge. A bank rail manager reads the rail wallet here before containing it.

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

- Name at least two people for each role on each linked token, so one absence is less likely to stop a rotation. Write the names down where the bank rail managers can find them.
- Turn on the **Bank rail** approval row, because with it off one manager completes or abandons a rotation alone.
- Rehearse one full rotation on a test network before you need it, so each person has used their own screen once.
- A token with Booked movements needs a token admin. A token linked as Supply delegate needs a token governor. On the token's "Settings" tab, **Supply mode** reads "Booked movements" or "Supply delegate".

## Roles in a rotation [#roles-in-a-rotation]

| Role | What they do in a rotation | Where |
| --- | --- | --- |
| Bank rail manager | Contains the wallet and requests completion. | **Bank rail**, the token, **Settings** |
| Second bank rail manager | Approves or rejects completion while the **Bank rail** approval row is on. Cannot be the manager who requested it. | **Bank rail**, the token, **Settings** |
| Token admin or governor, per token | Revokes the old wallet's supply authority and grants it to the new wallet. | The checklist step, or the token's own permissions |
| Token custodian, per token | Empties the old escrow, moves the suspense, and freezes the old address. | The token's forced transfer sheet, and the Platform API for the escrow forced transfer |
| Identity manager | Registers the new wallet's on-chain identity. | **Identities** |
| Escrow manager | Creates the new escrow for each supply delegate link. | **Bank rail**, the token, **Settings**, **Create escrow** in the **Escrow** block |

## Symptoms [#symptoms]

- A mint, burn or escrow move came from the rail wallet that nobody asked for.
- The rail wallet's private key was exposed, or a person with access to it left under suspicion.
- Credits park with the reason "The rail wallet lost its supply authority", or "Reconciliation" shows a **Break** because another account holds a token's supply authority.
- Custody can no longer sign with the rail wallet, so no request from it leaves.

## Checks [#checks]

1. Open "Asset lifecycle", then "Bank rail", select the token, open "Settings" and read the **Rail wallet** card. A "Contained" state means someone already started a rotation, and the checklist shows where it stands.
2. Decide whether the key is compromised or lost. If anyone else may hold it, treat it as compromised. A compromised rotation cannot be abandoned, and a lost one can be reported as compromised later, so choose **Compromised** when in doubt.
3. On "Reconciliation", read **Rail wallets** and each token's supply line to see the balance the rail wallet holds and what is parked as suspense.

While the rail wallet is contained, the recall sheet on **Payments** refuses a request to execute a recall with the message that a bank rail manager contained the rail wallet and that the link moves to the new rail wallet when the rotation completes. Request the recall again after the rotation completes.

## Actions [#actions]

### Compromised key [#compromised-key]

1. Contain the wallet. A bank rail manager selects **Contain rail wallet**, chooses "Compromised", and confirms. Every token link is suspended and the rail prepares the new wallet. A compromised rotation cannot be abandoned, and containing releases every cash-out the bank has not been instructed to pay, as [Money in flight](#money-in-flight) describes.
2. Revoke the old wallet on every link. Each token admin or governor opens their checklist step, "Authority revoked on" the token, and selects **Revoke authority**. It does not need the new wallet, so it can start straight after containment. Until it is mined on every link, the card says the old key still holds supply authority.
3. Protect the old escrow. On each supply delegate link, a token custodian moves every holder's tokens out of the old escrow, the contract that locks a client's tokens while a cash-out is paid, back to its owner with the escrow forced transfer through the Platform API, as [Escrows](https://docs.settlemint.com/docs/console/asset-lifecycle/escrows#move-units-out-with-the-forced-transfer-api) describes. Freezing the old address does not satisfy this step: the rail refuses completion until the old escrow is empty. The step reads **Old escrow protected on** the token.
4. Register the new identity. An identity manager registers the on-chain identity of the new wallet. Fund the new wallet with gas, the network's fee currency, at the address the step shows.
5. Grant the new wallet. Each token admin or governor selects **Grant authority**. The rail refuses a grant on a compromised rotation until every link is revoked and the old escrow is empty, and while any other account holds supply authority on the token.
6. Create the new escrow. An escrow manager creates the escrow for the new wallet on each supply delegate link.
7. Move the suspense. Suspense is the tokens the rail holds for credits it could not pass on, plus the coins of credits still on their way to the client's custody gateway. A token custodian moves the amount shown at **Suspense moved on** the token from the old wallet to the new one with a forced transfer, and freezes the old address if it still holds tokens.
8. Request completion. A bank rail manager selects "Request completion". While the "Bank rail" approval row is on, a second bank rail manager checks the old and new addresses, selects "Approve", then **Approve and complete**. With the row off, the request is approved at once.

### Lost key [#lost-key]

The checklist keeps its normal order: the new identity is registered first, then each token's revoke, escrow, grant and suspense steps. Nothing is at risk while you work, because nobody can sign with a lost key. Step 3 stays mandatory: the rail refuses completion while the old escrow holds tokens. On a lost rotation the Platform API refuses a custodian's forced transfer of a lock that backs an unpaid cash-out, with the reason `not-compromised`, so those units leave only when each holder reclaims the lock after its date and withdraws. If no holder can reach the old escrow to empty it, abandon the rotation instead of completing it. A bank rail manager can select **Request abandon**, but only before anyone submits the first revoke or grant of the hand-over. While the "Bank rail" approval row is on, a second manager approves it. With the row off, it takes effect at once and the old wallet signs again. After that, the rotation can only complete. If the investigation later finds the key was compromised after all, a manager selects "Report compromised": the rotation becomes a compromised one at once and any abandon request is dropped.

### What blocks completion [#what-blocks-completion]

**Request completion** stays disabled with a reason until every earlier step is done. The rail also refuses completion while the old wallet has queued writes, which containment does not cancel, while the old escrow still holds tokens, while the old wallet holds tokens and is not frozen on the token, while the new wallet holds less than the credits parked in suspense and in transit, and while a credit is mid-send from the old wallet. The blocker names each credit in transit, and a mid-send credit clears when it lands or fails.

The rail also protects the old wallet from a grant that was already on its way when you contained it. Activating a token link, or changing the mint cap of a supply delegate link, queues a grant of supply authority to the rail wallet, and that grant can wait up to 24 hours for an approval, a custody signature or gas. Containment cannot cancel it. The rail therefore refuses completion, for a lost and for a compromised rotation, while:

- A grant to the old wallet is still queued, submitted or waiting for approval on a token linked to it. This includes the re-delegation of a mint cap that has not settled. The blocker names the token and the request. When the grant lands, the next blocker below applies. When it fails, the blocker clears.
- The old wallet holds supply authority on any token linked to it, including a link that still waits for activation. On a suspended link the checklist offers **Revoke authority**. A link that waits for activation is not in the checklist, so a token admin or governor revokes the old wallet's authority from the token's own permissions. The rail also refuses to remove a link that waits for activation while the wallet is contained, because the removal would hide a queued grant from these checks.

- The indexer is behind the chain, so the rail cannot tell whether a grant landed. Request completion again after a moment.

While a grant is in flight, the rail raises one security case in operations for the rotation. It names each token and request, and it resolves when the rotation completes or is abandoned.

## Role steps [#role-steps]

### Bank rail manager [#bank-rail-manager]

Contain first, then follow the checklist. Each step shows the role it needs and a **Copy link** button: send that link to the person, so they land on the exact screen. Request completion once every earlier step reads "Done". Before you sign, check the reason you chose, because a compromised rotation cannot be abandoned.

### Second bank rail manager [#second-bank-rail-manager]

Open the token's "Settings" tab and select **Approve** or "Reject" on the request. The dialog shows the "Old wallet" and "New wallet" addresses and how many token links move. Before you sign, check the new address against the one the identity manager and the token admins confirmed, and that the checklist shows every step "Done". Reject with a reason when anything differs.

### Token admin or governor [#token-admin-or-governor]

You need only the role on the token: token admin for a token with Booked movements, token governor for a token linked as Supply delegate.

1. Open the link a bank rail manager sent you. It opens the token's Settings tab at your step.
2. Find the step **Authority revoked on** your token. The status reads "Yours to do" when your account holds the role, or "Waiting on" another role when it does not.
3. Select **Revoke authority**. The old wallet loses the token's supply management role, or its place as supply delegate. Confirm with your wallet.
4. Later, when the step "Authority granted on" your token reads "Yours to do", select **Grant authority** and confirm with your wallet. The new wallet receives the role or becomes the supply delegate.

Before you sign, check the address in the dialog against the "Old wallet" and "New wallet" addresses on the card, and that your token is the one in the step name. Select **Open the token's holders** to see its current holders.

### Token custodian [#token-custodian]

You move tokens that sit on the old wallet or its escrow. Send the escrow forced transfer, `POST /api/v2/addons/escrows/{escrowAddress}/forced-transfers`, through the Platform API to return each holder's free and locked tokens to its owner, which also ends the cash-outs that were using them. At **Suspense moved on** your token, use the token's forced transfer sheet to move the shown amount from the old wallet to the new one. Freeze the old address afterwards if it still holds tokens. Before you sign, check that the destination is the new wallet for suspense and the lock's owner for an escrow, and the token and amount match the step.

### Identity manager [#identity-manager]

Register the on-chain identity of the new wallet address shown in the step. Before you sign, check that the address matches the **New wallet** on the card, not the old one.

### Escrow manager [#escrow-manager]

Create the new escrow for each supply delegate link, controlled by the new wallet. Before you sign, check that the controller is the new wallet and the link is the token the step names.

## Money in flight [#money-in-flight]

- Credits that arrive while the wallet is contained are held. The rail does not mint them, and each parks with "The rail wallet lost its supply authority". After completion they mint from the new wallet without a manual retry.
- Credits already parked move with the suspense. The new wallet must hold at least their total before completion.
- Credits whose coins are minted and wait for delivery to the client's custody gateway, or whose delivery failed or came back, move to the new wallet at completion, so their delivery sends from it. The new wallet must hold their coins too. A credit mid-send from the old wallet blocks completion until it lands or fails.
- Cash-outs that were not instructed to the bank are released, and holders withdraw their tokens. New cash-outs wait with the link inactive until completion. A cash-out already instructed but not paid expires at its deadline, and the holder reclaims the tokens.
- A paid cash-out whose tokens were not burnt shows "Unbooked". A token custodian forces the locked tokens from the old escrow to the rail wallet, then a bank rail manager selects **Recover** on the cash-out row, and the rail burns the tokens and shows "Paid".
- A frozen retired wallet's balance is a case to work, not a **Break**. Tokens sent to the old wallet after completion stay there until a custodian moves them.

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

- On the token's **Settings** tab, every checklist step reads "Done" and the token links read "Active".
- On **Reconciliation**, "Rail wallets" lists the new wallet as "Current rail wallet" and the old one as "Previous rail wallet", and the status reads "Clear".

## Frequently asked questions [#frequently-asked-questions]

### Can I undo containment?

Only for a lost key. A lost rotation can be abandoned until the first revoke or grant of the hand-over is submitted, and abandoning it makes the old wallet active again. A compromised rotation cannot, because the key may be in other hands.

### Why does the checklist ask for the revoke before the new identity?

A compromised key can mint and burn on every linked token until someone revokes it: without limit on a Booked movements link, and up to the link's mint cap on a supply delegate link, or without limit when that link has none. The revoke does not need the new wallet, so it goes first.

### Can the same person do every step?

Only the roles they hold. While the **Bank rail** approval row is on, completion needs two different bank rail managers. With the row off, one manager completes it. The checklist shows who each step waits on.


# Approvals

Source: https://docs.settlemint.com/docs/console/asset-lifecycle/custody-gateway-approvals
Set the custody gateway's approval rule, raise a held gateway change, and approve, run or cancel a change that an add-on approval holds.

The **Approvals** tab of the "Custody gateway" holds the gateway's approval rule and the proposals that wait for approval. The custody gateway is the add-on that screens client deposits and pays client withdrawals. An add-on approval holds one call to a checked function of an existing add-on until enough approvers have approved it. The role that may make the change is the requester's role, and the access manager is the contract that holds the add-on's roles and rules. You raise a held change where you make it, then approve, run or cancel it from [Actions](https://docs.settlemint.com/docs/console/essentials/actions) or from this tab. The [add-on approvals concept](https://docs.settlemint.com/docs/concepts/compliance-and-identity/addon-approvals) explains the model behind the rules.

An add-on approval does not hold the creation of a new airdrop, offering or other add-on. The custody gateway ships approval rules that hold the creation of a gateway only when it starts on a settings profile other than the add-on defaults. Creating a gateway on the defaults needs only the gateway "Manager" role, with no second approver. Airdrops and the other add-on entries are on [Airdrops](https://docs.settlemint.com/docs/console/asset-lifecycle/airdrops).

![Approvals tab of the custody gateway](https://docs.settlemint.com/docs/screenshots/console-custody-gateway-approvals.light.en.webp)

[Screenshot] The "Approvals" tab of the custody gateway shows the approval rule above the changes that wait for approval.

The "Require a second approval" section shows the status line, the switch, "Approvals per change" and "Save". Below it, "Waiting for approval" reads "No approvals pending" while no change is open, and the add-on's status, access manager and fee account follow.

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

- The custody gateway entry: the sidebar shows **Custody gateway** under "Asset lifecycle" to an Owner and a Platform admin, once the system has the custody gateway add-on.
- To approve or run a gateway change, you need the gateway "Manager" role. Every checked gateway function needs that role, and the rules the Console sets make the requester's role the approver.
- To change the approval rule itself, you need the "Gateway permission manager" role. Saving the rule, and approving or running a held rule change, needs that role. A Permission manager or System manager role, or a role on the add-on's access manager, also lists a proposal for you, which on its own does not let you approve it. Grant gateway roles on the "Add-on roles" tab of [Roles and permissions](https://docs.settlemint.com/docs/console/organisation-settings/admins-and-roles).
- **Your wallet verification.** Each approval, run and cancellation is signed by your own wallet and asks for your PIN.

## Steps [#steps]

The tab lists the add-on's state, "Active" or "Paused", its access manager and its fee account below the approval rule and its open proposals. When the add-on has no access manager, the tab shows only that list: **Access manager** reads "Not set", and a line reads "This add-on has no access manager, so its changes cannot require approval."

### Set the approval rule [#set-the-approval-rule]

Under **Require a second approval**, the status line says what is in force:

- "On. Every gateway change waits for approval, and so does turning this off."
- "Off. Gateway managers make changes without approval."
- "Approvals required, but anyone with the Gateway permission manager role can turn them off without approval."
- "Custom. Some changes have their own approval rule. Saving here sets one rule for all of them."

The third line means the rule does not cover changes to itself, so one holder of the **Gateway permission manager** role can turn every hold off without a second approval. Saving the rule again covers that change too.

Turn the switch on and enter **Approvals per change**, from 1 to 32. Select "Save" and confirm with your PIN. The Console sets one rule on every checked gateway function and on the rule-setting function of the access manager itself, so turning the rule off later needs approval too. The approver is anyone with the requester's role, and the approval window keeps the longest window already set, or seven days when none is set. A rule can cover more functions than one transaction can set, so the Console saves it in several transactions, each with its own PIN prompt: "This rule is saved in 3 steps. Each step asks you to confirm again." While the network is confirming a save, the tab reads "The last save was sent, but the new rule has not shown up yet. Refresh to check again."

The rule counts wallets, so grant the **Manager** and "Gateway permission manager" roles to one wallet per person. A person who holds either role on two wallets can meet a one-approval rule alone by calling the chain directly, and with the "Gateway permission manager" role that includes turning the rule off.

When the rule is already on, saving a new one is itself a held change, and the Console shows the block of the next step.

### Raise a proposal [#raise-a-proposal]

Make the change as usual, for example on the gateway's "Coins" or "Profiles" tab, or on a deposit or withdrawal. When the change is held, the Console does not send it. It shows **This change needs approval first** with "This change takes effect only after others approve it. Ask for approval, then run it from the request once it is approved." The block names the "Contract", and "Technical details" shows the "Function" selector and the "Call hash".

Select **Ask for approval** and confirm with your PIN. The Console reads "Approval requested. The approvers see it in their actions inbox and on the Approvals tab." You are now the proposer, and the request appears in your Actions inbox as "Waiting for other approvers".

A withdrawal request at or above the gateway's instant limit waits in review for the gateway managers' approval, and the record lists **Approval** under "Still to do". Give it with "Approve" on the request's row or in its record on the gateway's "Withdrawals" tab, and confirm with your PIN. While the approval rule is on, "Approve" shows the block above instead of sending: ask for approval, and once the proposal has its approvals, select "Run change" on it, or "Approve" on the request again. The request then waits for funds, or stays in review until the screener has cleared it too. A frozen request offers no "Approve" while it stays frozen, and a request whose client has a revoked or expired compliance claim is refused until the claim is restored.

### Raise an approved source or payout address for the client [#raise-an-approved-source-or-payout-address-for-the-client]

On the gateway overview, the **Whitelist** panel lists the addresses of the client the gateway belongs to, with when each was proved and whether it is an approved source or payout address. Select "Add source" or "Add payout" on a row, or "Raise removal" on a revoked entry that is still an approved source, and confirm with your PIN. The Console sends the same request as the direct routes, so a held change shows the approval block above.

### Review and approve [#review-and-approve]

An approver finds the proposal as an "Add-on approval" row in [Actions](https://docs.settlemint.com/docs/console/essentials/actions), under "Needs you", reading "Waiting for your approval" with "1 of 2 approvals" or similar. The same proposal is listed under "Waiting for approval" on the gateway's "Approvals" tab. Select **Review** in either place.

The **Approval request** sheet says "This add-on change runs only after it has the approvals it needs." It shows:

- the change in words, such as **Release a frozen withdrawal**
- the **Contract** and the call's arguments with labels
- **Requested by**
- **Expires**
- the **Approvals** progress
- **Approved by**

A change to an approval rule also shows the rule it writes:

- **Actions covered**
- **Approvals required**, or "No second approval"
- **Approval window**
- **Approver**
- **Back to the default**, where it clears an override

Select **Approve** and confirm with your PIN. The Console reports "Approval recorded." and the sheet then reads "You approved this. Waiting for other approvers." until the count is met.

### Run the change [#run-the-change]

Once the proposal has its approvals, the row reads "Ready to run" under "Needs you" for anyone whose wallet holds the requester's role, and the sheet reads "Approved. Someone with the requester's role can now run it." Select "Review", then **Run change**, and confirm with your PIN. The platform sends the approved call to the contract from your wallet. The Console reports "The change has run." and the proposal leaves the inbox.

The change runs once. If the call fails on chain, the proposal stays open with its approvals, and you can run it again.

### Cancel a request [#cancel-a-request]

The proposer, anyone who approved, and an approver who may still approve can cancel an open proposal that has not expired. Select "Review", then **Cancel request**. The Console asks you to confirm with "Cancel request" or "Keep request", then asks for your PIN. It reports "Request cancelled."

## What an add-on approval holds [#what-an-add-on-approval-holds]

A function that an add-on marks as checked asks the add-on's own access manager, the contract that holds the add-on's roles, before it runs. When it has a rule for that function, the call runs only after a proposal for the exact call data collects the approvals the rule needs. A function with no rule, or a rule of zero approvals, runs at once for a holder of its role. The Console calls that role the requester's role, and the API calls it the maker role.

| You want to | What the platform checks |
| --- | --- |
| Create a custody gateway for a client, or change one, for example approve a payout address, release a frozen withdrawal or approve a withdrawal at or above the instant limit | The gateway add-on's approval rule. A new gateway access manager starts with one approval and a seven-day window on every checked function. Creating a gateway is held only when it starts on a non-default settings profile, and a setting change is held only when it loosens the setting. |
| Create an offering or an XvP settlement | Your role. No add-on approval applies. Creating an offering also waits for a second organisation owner when the **Offerings** row under **Approvals** is on, as [Offerings](https://docs.settlemint.com/docs/console/asset-lifecycle/primary-offerings) describes. |
| Register an add-on factory, so that a new add-on type exists on the system | The system manager role. The write is in the `system-administration` protection group, so it waits for a second person when your organisation lists that group for maker-checker approval. |
| Change an offering's terms or its sale roles | The sale role the change needs. Terms are in the `token-administration` group and roles in the `role-management` group, held under the same maker-checker list. |

A held administrative change is a different mechanism from an add-on approval. It waits as an approval request in [Actions](https://docs.settlemint.com/docs/console/essentials/actions) until a second person decides it, and nothing reaches the chain before then. An add-on approval runs on chain, on the add-on's access manager.

The trading venue also marks some functions as checked: changing a price band, halting an instrument, delisting an instrument, pausing and resuming the venue, and busting a trade. Its factory sets no rule, so these run at once for the holder of the "Venue operator" role, of the "Venue admin" role for resuming the venue, or of the venue submitter role for a bust. The account that provisioned the venue holds the default administrator role on the venue's access manager, and it alone can set a rule, through the API. A proposal on any contract other than the custody gateway, its factory or the access manager reads "Unrecognized call" and has no "Approve" button.

## What approvers see [#what-approvers-see]

The Console and the Platform API treat every wallet you hold as one person, so the inbox row and the sheet follow your part in the proposal. The access manager on chain checks identities: it refuses an approval from any wallet registered to the proposer's identity, and counts one approval per identity. A wallet with no registered identity counts as a person of its own, and a Gateway permission manager can grant the approver role to more wallets, so review who holds that role.

| Your part | Inbox row | In the sheet |
| --- | --- | --- |
| You hold the approver role, and no wallet of yours proposed or approved | **Waiting for your approval**, under **Needs you** | **Approve** and **Cancel request** |
| You hold the approver role, but the Console cannot read the call | **Can't be approved here**, under **Needs you** | The **Function selector** and the raw **Call data**, and no button |
| You proposed it, or you already approved it, and it lacks approvals | **Waiting for other approvers**, under **Waiting on others** | **Cancel request** |
| A wallet of yours holds the requester's role and the approvals are met | **Ready to run**, under **Needs you** | **Run change**, and **Cancel request** when you proposed it or approved it |

Each row shows the approvals so far out of those needed, and its **Review** button opens the sheet, including for rows under "Waiting on others". You see one row per proposal. A person who proposed from one wallet and holds the approver role on another sees "Waiting for other approvers", because the platform never asks a person to approve their own proposal.

The platform lists a proposal for you only when you hold the Permission manager or System manager role, a role on that add-on's access manager, or the system role the access manager is bound to. The Investor portal lists the same rows without **Review**. It tells an approver "Waiting for your approval in the Console", or "This call can't be read, so it can't be approved here." for a call it cannot read.

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

- Open the gateway's **Approvals** tab. A proposal that ran or was cancelled is gone from "Waiting for approval", and "No approvals pending" shows when none is left.
- Opening a closed proposal reads "This change has run." or "This request was cancelled."

## Troubleshooting [#troubleshooting]

A refused proposal write answers `422` with `platform.addonApprovals.PROPOSAL_REFUSED`, DALP-12408, and its `reason` names the cause. Change the wallet, the proposal or the call before a retry, except where the table says to send the request again. The platform simulates every write from your wallet before it queues anything, so a refusal at that stage sends nothing. A write that passes can still fail on chain if the state changes before it is mined. The sheet shows the error's title and the fix in place.

| Code or reason | What happened | What to do |
| --- | --- | --- |
| `proposer-cannot-approve` | A wallet of yours raised the proposal, or you proposed it through the platform while working as any participant. | Ask another approver. |
| `already-approved` | A wallet of yours already approved it, or your earlier approve request is still being queued. | Wait for other approvers. Do not approve again from another wallet. |
| `checker-unauthorized` | The wallet does not hold the role the action needs, for example the approver role. | Act from a wallet that holds the role, or ask a gateway permission manager to grant it. |
| `not-maker` | **Run change** came from a wallet without the requester's role. | Run it from a wallet that holds the requester's role. |
| `not-approved` | The proposal does not have the approvals it needs yet. | Wait for the remaining approvals. |
| `proposal-not-open` | The proposal already ran or was cancelled. | Nothing to do. Raise a new proposal if you still need the change. |
| `proposal-expired` | The approval window ended. The sheet shows **Expired** and no button. | Raise the change again. |
| `proposal-superseded` | The rule's approver role changed after the proposal was made. | Raise the change again under the new rule. |
| `proposal-already-open` | An open proposal for this exact call already exists. | Approve or run the existing one. |
| `target-not-managed` | The contract does not use this access manager for its checks. | Propose on the access manager the contract names. |
| `invalid-proposal-call` | The call is too short to name a function, or it targets the access manager with a call other than setting a rule. | Correct the call data. |
| `refused` | The access manager refused the call for another reason. The error's `revert` carries the contract error. | Read the revert, then send the request again. |
| `platform.addonApprovals.APPROVAL_NOT_REQUIRED`, DALP-12407, `422` | No rule holds this call, so there is nothing to propose. | Send the call to the contract directly from a wallet that holds its role. |
| `platform.addonApprovals.APPROVAL_REQUIRED`, DALP-12411, `422` | Setting a rule is itself held. The error carries the call to propose: the access manager as target, the default administrator role and the call data. | Propose that call, collect the approvals, then run it or send the request again. |
| `GATEWAY_APPROVAL_REQUIRED`, DALP-9821, `422` | A gateway write is held. The error lists the calls to propose. The Console shows these as **This change needs approval first**. | Select **Ask for approval**. |

A proposal you cannot see answers `404` with `platform.http.NOT_FOUND`. Approving a proposal whose window ends before the next block answers `proposal-expired`. A rule write from a wallet with no administrator authority on the access manager answers `403` with `platform.http.ACCESS_DENIED`, DALP-12252. The full list of codes is in the [platform API error reference](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference).

## API routes [#api-routes]

Proposals and rules live under the access manager of the add-on. The custody gateway's "Approvals" tab shows its **Access manager** address.

| Task | Route |
| --- | --- |
| List proposals | `GET /api/v2/system/addon-access-managers/{accessManagerAddress}/proposals` |
| Read one proposal | `GET /api/v2/system/addon-access-managers/{accessManagerAddress}/proposals/{proposalId}` |
| Propose a call | `POST /api/v2/system/addon-access-managers/{accessManagerAddress}/proposals` |
| Approve a proposal | `POST …/proposals/{proposalId}/decisions` with `{"decision":"approve"}` |
| Run or cancel a proposal | `POST …/proposals/{proposalId}/transitions` with `{"transition":"execute"}` or `{"transition":"cancel"}` |
| List the rules in force | `GET /api/v2/system/addon-access-managers/{accessManagerAddress}/action-configs` |
| Set a rule for up to 50 functions | `POST /api/v2/system/addon-access-managers/{accessManagerAddress}/action-configs` |

The proposal list filters by `target`, `status` and `viewer`. `viewer=approver` keeps the open proposals you may still approve, and `viewer=maker` keeps the ones you proposed or may run. Each write is signed by your own wallet, needs your wallet verification and takes an `Idempotency-Key`. The request and response fields of each route are in [the v2 API reference](https://docs.settlemint.com/docs/api-reference/v2).


# Create a client gateway

Source: https://docs.settlemint.com/docs/console/asset-lifecycle/custody-gateway-create
Open a custody gateway for one client identity under a profile, wait for it to deploy and find its address.

A gateway serves one client identity under one profile. Create one for each client who deposits coins or withdraws them through the add-on. The wizard has three steps, "Client", "Profile" and "Review".

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

- The [add-on is set up](https://docs.settlemint.com/docs/console/asset-lifecycle/custody-gateway-setup) with at least one enabled coin, one profile, and a keeper and a screener.
- You have the client's identity address: the address of their OnchainID. A client identity can have one gateway per network.
- You know the client's country.

## Steps [#steps]

1. Open "Asset lifecycle", "Custody gateway" and the "Gateways" tab, then select "Create a gateway" above the list. The page is titled "Create a gateway".
2. In the "Client" step, enter the "Client identity". The line under the field reads "Identity:" followed by the identity name when the address matches an identity. "No identity with this address was found." means the address does not belong to a known identity, and "A gateway already exists for this identity on this network." means you do not need a second one.
3. Choose the "Country" and select "Next".
4. In the "Profile" step, choose a profile. With none to choose from the step says "Create a profile first." Create one on the "Profiles" tab and return.
5. In the "Review" step, check the "Client identity", "Country" and "Profile", then select "Create gateway" and confirm with your wallet verification.
6. Wait while the page reports "Sending the request." and "Deploying the gateway." The page says "The gateway is ready." once the gateway exists. If it says "Still deploying", you can leave the page and check the "Setup" tab later. Select "Try again" after "The gateway could not be created."

The gateway's address is fixed before it is deployed. A client who has the address can send coins to it, and the keeper records them once the gateway exists.

![The Create a gateway wizard on its Client step, with the Client identity and Country fields](https://docs.settlemint.com/docs/screenshots/console-custody-gateway-create.light.en.webp)

[Screenshot] The Create a gateway wizard on its Client step, with the Client identity and Country fields.

The steps "Client", "Profile" and "Review" run down the side of the wizard.

## After you create the gateway [#after-you-create-the-gateway]

Open the gateway from the "Gateways" list. Its "Overview" tab shows the "Client identity", "Profile", "Country", "Client wallet", "Default payout address" and "Screener override". A gateway has no client wallet when it is created, because an identity can hold several wallets. Until a gateway manager binds one through the [API](https://docs.settlemint.com/docs/api-reference/guides/custody-gateway-api#bind-the-client-wallet), the client's own routes answer 404. Clients see their gateway address in the [Deposit dialog](https://docs.settlemint.com/docs/concepts/operating/investor-portal-wallet-transfers).

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

- The "Setup" tab ticks "A gateway created", and the new gateway appears in the "Gateways" list with its "Deposits", "Withdrawals" and "Unsupported" tabs.

## Related pages [#related-pages]

- [Set up the custody gateway](https://docs.settlemint.com/docs/console/asset-lifecycle/custody-gateway-setup)
- [Review deposits and withdrawals](https://docs.settlemint.com/docs/console/asset-lifecycle/custody-gateway-review)
- [Wallet deposits and withdrawals in the Investor portal](https://docs.settlemint.com/docs/concepts/operating/investor-portal-wallet-transfers)


# Review deposits and withdrawals

Source: https://docs.settlemint.com/docs/console/asset-lifecycle/custody-gateway-review
Clear, freeze, refuse, return and recover a client's gateway records, follow a deposit that waits for custody, and clear a client flag.

Each gateway has its own records. Its "Deposits" tab lists every deposit with the stage it is in, its "Withdrawals" tab lists every withdrawal request, and its "Unsupported" tab lists coins the gateway does not accept. Most records move on their own. You step in when a record rests at a stage that waits for a person. [The stage reference](https://docs.settlemint.com/docs/api-reference/guides/custody-gateway-stages) lists every stage and who moves it.

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

- The screener actions need a wallet with the screener role, and the gateway manager actions need the gateway manager role. A button your wallet cannot use says "Your wallet needs the screener role for this action." or names the gateway manager role. [Set up the custody gateway](https://docs.settlemint.com/docs/console/asset-lifecycle/custody-gateway-setup) says how roles are granted.
- Some manager actions need a second approver. They then wait on the "Approvals" tab, as [Approve custody gateway changes](https://docs.settlemint.com/docs/console/asset-lifecycle/custody-gateway-approvals) describes.
- Every action asks you to confirm with your wallet verification.

## Find the records that wait for you [#find-the-records-that-wait-for-you]

1. Open "Asset lifecycle", "Custody gateway", then the gateway.
2. Open "Deposits". Search by deposit id or sender, and use "Open" and "Done" to separate records that still move from records that ended.
3. Read the "Stage" column. "Quarantined, awaiting screener", "Frozen", "Mint refused" and "Awaiting custody" are the stages that rest. The "Sender" column says "Sender confirmed" or "Sender unconfirmed".
4. Open "Withdrawals" for requests. Select "Frozen only" to list frozen requests. "In review" and "Awaiting payout address" are the stages that wait for a person or for the client.

Select a row to open its record, or open "Record actions" on the row for the actions that apply to it right now. The menu offers only the actions the record can take.

## Act on a deposit [#act-on-a-deposit]

| Action | Offered when | What happens |
| --- | --- | --- |
| **Confirm sender** | The deposit is open and its sender is not confirmed. | Records who sent the coins. Return, refuse and the return of a custodian's coins need it. |
| **Clear** | The deposit is "Quarantined" and the gateway is not paused. | The screener accepts it. The gateway mints the receipts and forwards the coins. |
| **Refuse** | The deposit is "Quarantined", its sender is confirmed and the gateway is not paused. | The coins go back to the confirmed sender. It cannot be undone. |
| **Freeze** | The deposit is "Quarantined" or "Awaiting custody" and was never frozen. | The record stops moving until the freeze expires or someone unfreezes it. The client's time limits pause while it is held. |
| **Unfreeze** | The freeze is live. | The record goes back to the stage it was frozen from. It is disabled once the record is reported. |
| **Renew freeze** | The record was frozen before, the freeze has ended and the record is not reported. | Moves the expiry out by another full period. |
| **Report** | The freeze is live and the record is not reported. | Marks the record as reported. The freeze no longer expires and nobody can unfreeze it. |
| **Return** | The sender is confirmed, the gateway is not paused, and the deposit is quarantined or holds its coins. | The value goes back to the sender. It cannot be undone. |
| **Recover** | The deposit holds its coins: frozen, or "Mint refused". | The coins move to the "Destination wallet" you name. It cannot be undone. |

Clear, Refuse and Confirm sender are the screener's. Freeze is open to the screener and to gateway managers. Unfreeze, Renew freeze, Report, Return and Recover are the gateway managers'. A "Mint refused" deposit is retried by the keeper once the cause is fixed, and you can return or recover it while it waits.

Frozen is not a separate stored stage. The "Stage" column shows "Frozen" while the freeze is live, and the record keeps the stage it was frozen from underneath.

## Act on a withdrawal [#act-on-a-withdrawal]

| Action | Offered when | What happens |
| --- | --- | --- |
| **Clear** | The request is "In review", needs screening and is not frozen. | The screener clears screening or the travel-rule check. |
| **Approve** | The request is "In review", needs approval and is not frozen. | Gives the gateway managers' approval the request waits for. Once screening is done, the request waits for funds. |
| **Reject** | The request is "In review" or "Awaiting payout address" and not frozen. | The receipts go back to the client. It cannot be undone. |
| **Freeze** | The request is open and was never frozen. | As for a deposit. |
| **Unfreeze**, **Renew freeze**, **Report** | As for a deposit. | As for a deposit. |
| **Return** | The freeze is live. | Returns the frozen request's receipts to the client. |
| **Unfulfil** | The request is "Claimable". | The reserved coins move back to funding and the request waits for funds again. |

Clear, Reject and Freeze are the screener's. Reject and Freeze are also open to gateway managers. Approve, Unfreeze, Renew freeze, Report, Return and Unfulfil are the gateway managers'. The client's own steps, cancel, collect and choosing a payout address, are not in this list.

A request whose automatic payout failed shows "Payout failed" with the reason in its row.

## Follow a deposit that waits for custody [#follow-a-deposit-that-waits-for-custody]

A coin can be set to wait for custody. The gateway then mints the receipts and holds them in the client's wallet until the custodian accepts the coins it forwarded. The deposit rests at "Awaiting custody" and the row says how much is "held for custody".

1. Open the deposit. The "Custodian answer" fact reads "Waiting for the custodian" until the custodian answers.
2. When the custodian accepts, the fact reads "Custodian accepted the coins" and the deposit settles. The keeper reports the answer. You take no step.
3. When the custodian sends the coins back, the fact reads "Custodian sent the coins back". Select "Return to sender" to send the coins to the confirmed sender and burn the held receipts. If the sender is not confirmed, "Confirm sender" first, or use "Recover" to send the coins to a wallet you name. Afterwards the fact reads "Coins returned to sender".

A deposit that is "Awaiting custody" can also be frozen. The freeze does not hide the custodian's answer: a return the keeper reports is still recorded, and the record stays frozen.

## Handle coins the gateway does not accept [#handle-coins-the-gateway-does-not-accept]

Open "Unsupported" for a gateway. It lists coins sent to the gateway that no enabled coin covers, with the status "Unsupported", "Returned", "Enabled", "Recovered" or "Ignored". The actions are "Confirm sender", "Return" to the confirmed sender, "Recover" to a wallet you name, "Enable as deposit" once a gateway manager has enabled the coin, and "Ignore", which closes the record and leaves the coins at the gateway address. "Enable as deposit" opens a new deposit record under the current terms.

## When a client is flagged [#when-a-client-is-flagged]

The gateway flags a client when a verification claim it requires is revoked or expires, or when screening reports a hit on a payout address. The flag freezes what the client could move.

1. Open the gateway's "Overview" tab. The "Client flag" card reads "The client is flagged. New withdrawals are refused until the flag clears." A client without a flag reads "The client is not flagged."
2. Read the flags, each with the verification it concerns by name, its trigger, "Verification revoked", "Verification expired" or "Screening hit", and when it was raised.
3. Read "Actions taken". Each row names an action, "Freeze withdrawal", "Freeze deposit" or "Suspend payout address", the record it hit and its state, "Waiting", "Sent", "Done" or "Refused". The fan-out freezes the client's open deposits and withdrawals and suspends its payout addresses. It also suggests freezing the whole client with the row "Suggest freezing the client", which points to the "Freeze client" button under "Pause, freeze and close". Nothing freezes the whole client until someone selects that button.
4. Clear the flag. When the provider issues or renews the claim, the flag clears on its own and the card says "Verification issued again" or "Verification renewed". To clear a reviewed flag yourself, select "Clear flag" and confirm. Clearing ends the flags listed on the card. A flag raised after the page loaded stays open.
5. Check what came back. Once no flag is open, the frozen withdrawals and deposits unfreeze. Reported records stay frozen, and suspended payout addresses stay suspended. The "After clearing" column says what happened to each: "Unfrozen", "Kept frozen, reported", "Kept suspended" or "Unfreeze refused". A freeze the gateway refused because the record was frozen before reads "Frozen before" once the flag clears, and "Freeze ends" says when an ended freeze ended.
6. If "A freeze ended while the flag stands" shows, open each record marked "Renew freeze" and renew it. Gateway managers approve the renewal with a checker.
7. Reinstate a suspended payout address. Clearing the flag does not do it. A gateway manager reinstates the address after review through the [API](https://docs.settlemint.com/docs/api-reference/guides/custody-gateway-api#reinstate-a-payout-address).

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

- The record's "Stage" column shows the stage you expected, and "Submitted. The record updates once the network settles it." appears after each action. Indexed reads can lag the chain by a short moment, so refresh the tab if the stage has not changed.

## Related pages [#related-pages]

- [Set up the custody gateway](https://docs.settlemint.com/docs/console/asset-lifecycle/custody-gateway-setup)
- [Deposit and withdrawal stages](https://docs.settlemint.com/docs/api-reference/guides/custody-gateway-stages)
- [When a client's claim is revoked or expires](https://docs.settlemint.com/docs/concepts/custody-and-signing/custody-gateway#when-a-clients-claim-is-revoked-or-expires)
- [Wallet deposits and withdrawals in the Investor portal](https://docs.settlemint.com/docs/concepts/operating/investor-portal-wallet-transfers)


# Set up the custody gateway

Source: https://docs.settlemint.com/docs/console/asset-lifecycle/custody-gateway-setup
Enable the coins clients can deposit, create profiles, review where payouts come from, and set up and rotate the keeper and screener wallets.

Set up the custody gateway add-on once for your organisation's system on a network. The add-on needs four things before a client can use a gateway: an enabled coin, a profile, a keeper and a screener, and the gateway itself. The **Setup** tab lists them as a checklist and ticks each one as you finish it. [How a custody gateway works](https://docs.settlemint.com/docs/concepts/custody-and-signing/custody-gateway) explains what each piece does.

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

- Your organisation admin has enabled the custody gateway add-on for the system. Until then the page says "Custody gateway is not enabled".
- You hold a role that can sign gateway changes. A wallet without it sees "You can't manage the custody gateway", and a button that needs a role the wallet lacks says which one.
- You have a custody provider configured under [Custody providers](https://docs.settlemint.com/docs/console/organisation-settings/custody). The keeper and the screener each sign from a wallet held by one.
- For every coin you enable, you have the coin's custody receipt token. The receipt is a separate token that stands for the coin, and it must carry the own-custody-gateway compliance rule bound to this add-on.

## Open the add-on [#open-the-add-on]

Open "Asset lifecycle", then "Custody gateway". The page has the tabs "Setup", "Coins", "Profiles", "Permissions", "Treasury" and "Approvals". "Approvals" lists changes that wait for a second approver and is the subject of [Approve custody gateway changes](https://docs.settlemint.com/docs/console/asset-lifecycle/custody-gateway-approvals).

![The Custody gateway Setup tab with a checklist of four steps: a coin enabled, a profile created, keeper and screener set up, and a gateway created](https://docs.settlemint.com/docs/screenshots/console-custody-gateway-setup.light.en.webp)

[Screenshot] The Setup tab of the custody gateway, with a checklist of four steps and the state of each.

The checklist lists "A coin enabled", "A profile created", "Keeper and screener set up" and "A gateway created", above the "Coins", "Profiles", "Permissions", "Treasury" and "Approvals" tabs.

## Enable a coin [#enable-a-coin]

1. Open the "Coins" tab and select "Enable coin".
2. Choose the "Coin" clients deposit and its "Custody receipt". The two must be different tokens.
3. Enter the "Freeze expiry (days)" and the "Paused exit after (days)". Both are required. The freeze expiry is how long a freeze lasts before it ends on its own. The paused exit is how long a gateway can stay paused before a client may leave it.
4. Select "Enable coin" and confirm with your wallet verification.

The add-on refuses a receipt whose decimals differ from the coin's, a receipt without the gateway compliance rule, and a freeze expiry or paused exit of zero. A coin that is already enabled cannot be enabled a second time. Other settings, such as fees, the cancel time limit and auto-collect, can be changed per coin through the [API](https://docs.settlemint.com/docs/api-reference/guides/custody-gateway-api).

## Create a profile [#create-a-profile]

A profile is a named set of settings that gateways share. Create at least one before you create a gateway.

1. Open the "Profiles" tab and select "Create a profile".
2. Enter a "Name" and the "Required claim topic", the numeric topic id of the verification claim a client must hold. A client whose claim is revoked or expires is flagged, as [Review deposits and withdrawals](https://docs.settlemint.com/docs/console/asset-lifecycle/custody-gateway-review#when-a-client-is-flagged) describes.
3. Select "Create profile".

Select "Remove" on a profile row to delete it. A profile that gateways still use cannot be removed.

## Check where payouts come from [#check-where-payouts-come-from]

The "Treasury" tab lists each enabled coin with its "Treasury" address and its "Payout mode": "Approval wallet" or "Vault". "No treasury: pooled requests wait for funding" means no treasury is set, so a withdrawal that needs the pooled funds waits until funding arrives. The tab is read-only. Changing a treasury needs the add-on's checker approval and is not available in the Console yet, so use the [API](https://docs.settlemint.com/docs/api-reference/guides/custody-gateway-api).

## Grant the manager role [#grant-the-manager-role]

The "Permissions" tab shows "Gateway managers" and "Signers". Gateway managers are roles, and you grant them on the add-on roles page rather than here.

1. On "Permissions", select "Open add-on roles". The page also sits under "Organisation settings", "Roles and permissions", "Add-on roles".
2. Select "Grant a role", choose "Manager" for the person and select "Grant role".

On a new system nobody holds a gateway role yet, so the page lists no holders and still offers "Grant a role". The first grant also creates the add-on's access manager in the same write. One grant covers every gateway of the add-on. Only a holder of the custody gateway permission manager role can grant or revoke these roles. Everyone else sees the page read-only.

## Set up the keeper and the screener [#set-up-the-keeper-and-the-screener]

The keeper moves deposits and runs the payout queue. The screener checks deposits and withdrawals. Both are service wallets held by a custody provider, not people.

1. On "Permissions", find the "Keeper" or the "Screener" card under "Signers".
2. Select "Set up", choose the "Custody provider" and confirm with your wallet verification.
3. Wait for the signer to become active. The card shows its state: "Pending", "Granted" or "Active". A request that needs a checker waits on the "Approvals" tab.
4. Set a "Low-balance threshold" so the card shows "Low balance" before the wallet runs out of gas. The card shows the wallet's "Balance".

With no provider configured the card says "Add a custody provider configuration before you set up a signer."

### Rotate a signer [#rotate-a-signer]

Rotate a signer when its wallet is lost, exposed or retired.

1. On the signer's card, select "Rotate".
2. Choose the "Custody provider" of the new wallet and confirm.
3. The card shows "Next signer" with the new wallet's state until it is active. The old wallet then shows as "Retired", and a wallet whose role was withdrawn shows as "Revoked".

Records the old wallet was handling keep their stage. The new signer picks them up once it is active.

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

- Return to the "Setup" tab. "A coin enabled", "A profile created" and "Keeper and screener set up" show as done. Next, [create a gateway for a client](https://docs.settlemint.com/docs/console/asset-lifecycle/custody-gateway-create), which completes "A gateway created".

## Related pages [#related-pages]

- [How a custody gateway works](https://docs.settlemint.com/docs/concepts/custody-and-signing/custody-gateway)
- [Create a client gateway](https://docs.settlemint.com/docs/console/asset-lifecycle/custody-gateway-create)
- [Review deposits and withdrawals](https://docs.settlemint.com/docs/console/asset-lifecycle/custody-gateway-review)
- [Approve custody gateway changes](https://docs.settlemint.com/docs/console/asset-lifecycle/custody-gateway-approvals)
- [Run the add-on through the API](https://docs.settlemint.com/docs/api-reference/guides/custody-gateway-api)


# 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.



# Asset lifecycle

Source: https://docs.settlemint.com/docs/console/asset-lifecycle
Offerings, venues, escrows, add-ons and the bank rail: the Console screens for work that spans more than one holder's position.

The "Asset lifecycle" group of the Console sidebar holds these screens:

- **Offerings** for a first sale.
- **Venues** for a trading venue and its settlement day.
- **Escrows** for the escrows of your system.
- One item for each add-on, a contract your system deploys to work with its tokens: each airdrop type and the **Custody gateway** have their own item.
- **Bank rail**, last, which mints a reserve token to a client's wallet when their bank transfer arrives and pays redemptions out to their bank account.


  - [Offerings](https://docs.settlemint.com/docs/console/asset-lifecycle/primary-offerings): Fund and activate a token sale, finalise it and deliver tokens or refund investors.
  - [Venues](https://docs.settlemint.com/docs/console/asset-lifecycle/venues): Provision a venue, list an instrument, pause the venue and find each other venue task.
  - [Escrows](https://docs.settlemint.com/docs/console/asset-lifecycle/escrows): Find every escrow, read who holds what, check open locks and trace each payment.
  - [Airdrops](https://docs.settlemint.com/docs/console/asset-lifecycle/airdrops): Open an airdrop add-on, read each distribution and find where other add-ons open.
  - [Approvals](https://docs.settlemint.com/docs/console/asset-lifecycle/custody-gateway-approvals): Set the gateway's approval rule and approve, run or cancel a held change.
  - [Bank rail](https://docs.settlemint.com/docs/console/asset-lifecycle/bank-rail): Connect the bank, link the reserve token, add clients and follow their cash-outs.



# Offerings

Source: https://docs.settlemint.com/docs/console/asset-lifecycle/primary-offerings
Fund and activate a token sale, follow it toward its caps, finalise it, and deliver the tokens or refund investors when the soft cap is missed.

**Offerings** lists every token sale across the organisation, and each sale opens a screen where you fund it, activate it, pause it, finalise it and settle the result. Each sale is a contract-governed first sale of a token that already exists, from the issuer to investors, at prices the issuer fixed per payment currency. A sale has a soft cap, the minimum that makes the raise a success, and a hard cap, the most it sells. Once it ends, someone finalises it, which records success or failure. [Trading](https://docs.settlemint.com/docs/console/my-assets/trading) is where a token changes hands afterward, at the price an order book gives, and [Issue asset](https://docs.settlemint.com/docs/console/asset-management/issue-new-asset) creates the token itself.

The same sale shows two different screens depending on who opens it. The list under **Asset lifecycle** and the operating console behind it belong to accounts with the system role "Permission manager" or "Asset manager", and to the Offering admin and Funds manager of a sale, who see only the sales they hold a role on. An account with none of these roles sees "Access restricted". An investor meets the sale through its own subscription view instead: an overview with a "Subscribe" control, plus tabs for their investment, their activity, pricing and documents. The operating console shows the whole raise, and it also shows your own vesting position read-only when the account operating the sale holds one. The Primary Offering concept page explains the sale and settlement model.

![The Offerings list with its filters and the Create offering button](https://docs.settlemint.com/docs/screenshots/console-primary-offerings.light.en.webp)

[Screenshot] The Offerings list shows every offering of the organisation, with the "Create offering" button for roles that may create one.

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

- **A role that opens the list.** You need the "Permission manager" or "Asset manager" system role to view sales across all tokens. An Offering admin or Funds manager sees only the sales of the tokens your organisation issued on which they hold that role. The list shows the "Access restricted" state to anyone else: "You need the Permission manager or Asset manager role, or a sale role on a token your organisation issued, to view offerings."
- A role to create: to start an offering you need the "Asset manager" role and at least one token that your account governs. Without the role, **Create offering** is disabled and its reason says that asset managers create offerings. With the role but no governed token, the Console disables "Create offering" and states the reason.
- A sale role to sign: signing any sale transaction also requires the matching on-chain role on the sold token, granted from the sale's **Permissions** tab. [Roles and approvals](#roles-and-approvals) lists which role each control needs.
- Approval, when it is on: when your organisation turns on the "Offerings" row under **Approvals** on [General](https://docs.settlemint.com/docs/console/organisation-settings/general#approvals), a second person approves what that row covers. See [Roles and approvals](#roles-and-approvals).

## Steps [#steps]

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

In the Console, open "Asset lifecycle", then **Offerings**. The page lists sales across the organisation, with filters for status, attention, token and currency. An account with the "Permission manager" or "Asset manager" role also sees an "Insights" tab beside it, which [Read the offerings insights](#read-the-offerings-insights) describes.

A live sale ending within 30 days shows the time left under its date in the "Ends" column, for example "in 25 hours" or "in 3 days". The count never rounds up: under two days it counts whole hours, and from two days on it counts whole days. A row's details sheet lists its start, presale end and end as a date and a time in UTC. In the list, a sale that starts and ends on the same UTC day shows a date and a time in UTC in its "Ends" and "Starts" columns, so two such sales on one day can be told apart. Every other sale shows the date alone.

A row carries at most one flag in the **Attention** column, and it marks a sale that needs a decision. When more than one applies, the row shows the first in this order:

- "Near hard cap" shows while a presale or public sale has sold 90% or more of its hard cap.
- "Presale ended" shows when a sale still in its presale phase has passed its presale end time.
- "Awaiting finalization" shows when the sale end time has passed and nobody has finalised the sale.
- "Refund grace window" shows for 30 days after a sale fails.

The **Needs attention** card on the "Insights" tab lists the same sales and offers "Finalize", "Move to public" and "Review".

### Create an offering [#create-an-offering]

From the list, select **Create offering** and complete the wizard. Once you choose the token, the wizard reads your Governance role on it. "Checks before signing" on the Review step confirms the role, and already shows on every step while the role is missing or cannot be read. "Subscription step", the unit every buyer's running total must be a whole multiple of, opens only when you hold Offering admin on that token. Without that role the field says so, and you use "Set subscription step" on the offering once you hold it. If the Console cannot read your roles on the token, the field stays open and the Governance check blocks signing until the roles can be read. In "Token and pricing", the Currency picker lists eligible payment tokens. It does not list people or the sale token itself, and its "Recent" list shows only tokens, never a wallet address you picked in another field. If you dismiss the picker without choosing, the field reports "Select a payment currency." The wizard rejects selecting the sale token as its own payment currency before wallet confirmation. The Review step shows the same end time that appears on the created offering's Schedule, including windows that cross a daylight-saving change. "Checks before signing" also asks the platform whether it would accept the offering as entered. It runs when every step is complete and valid. A refusal, for example a wallet that does not hold the Governance role on the token or a start time that is not after the next block, shows as a blocked check with its reason and fix, and signing stays off, so you learn it before the PIN. The check creates nothing and signs nothing. The platform checks again when you sign. If the check cannot answer, it does not block you and the creation returns its own refusal.

![Create offering wizard at the Token and pricing step](https://docs.settlemint.com/docs/screenshots/console-primary-offerings-create-offering.light.en.webp)

[Screenshot] The "Create offering" wizard opens on its first step, "Token and pricing".

### Open an offering [#open-an-offering]

Select a sale to open its operating console. The banner reads the sale's current state, funding, and soft cap position. The tabs cover the overview, purchases, currencies, whitelist, vesting, marketing, and permissions. The overview links the sold token to its token page when your organisation issued it, and to its external token page otherwise. **Cap table** is the one tab that appears only when your account holds Offering admin or Funds manager on the sold token.

The overview tab charts the commitments over time against the soft and hard caps, with a dashed projection to the close once the sale has run for 14 days. Below it, a sale manager sees the offering funnel. [Read the commitments chart](#read-the-commitments-chart) explains both.

### Run the operation the sale's state offers [#run-the-operation-the-sales-state-offers]

Open **Actions** and pick the control the sale's state offers. A sale moves from setup to active to ended in one direction only. Setup offers funding, terms, the subscription step, and activation. An active sale offers transition, pause, resume, extend, and end. An ended sale offers finalisation. A final sale offers the withdrawals. "Finalize offering" shows from the presale on and stays disabled until the sale has ended or its end time has passed, also while the sale is paused. The Console asks for wallet verification before each on-chain signature. The menu lists only the entries your sale roles cover.

An equivalent flow exists for integrations: the [token sale endpoints](https://docs.settlemint.com/docs/api-reference/v2) drive creation, activation, purchase, finalisation, refunds, and withdrawals.

## Fund and activate an offering [#fund-and-activate-an-offering]

The creation wizard fixes the commercial terms of the sale. It sets the token, the payment currencies, and the price in each currency. The wizard also sets the caps, purchase limits, and the optional presale with its discount and per-address cap. An optional vesting schedule delays delivery of purchased tokens and releases them over time. No Console screen and no Platform API endpoint changes these terms after creation. An Offering admin can still call the sale contract's setters directly while the sale is in setup, so check the terms the contract reports before activation.

During setup, "Actions" offers two more settings:

- **Set terms** records the hash of the terms documents you uploaded to the sale. While an uploaded terms document is not recorded, "Activate offering" stays disabled and says so. Terms can be recorded only once.
- **Set subscription step** changes the step that every buyer's running total must be a whole multiple of, and 0 switches the rule off.

Both are offered only during setup. An Offering admin can add, remove, or import presale addresses on the **Whitelist** tab at any time, but whitelist edits do not affect public-sale eligibility after the presale ends.

To reduce what one investor may take after you build your book, set a per-investor allocation in the "Allocation caps" section below the whitelist table on the "Whitelist" tab. Select **Set cap** to cap a wallet, or "Change cap" or "Remove cap" on a row. The cap covers every wallet of that investor. You can change it after activation until the sale takes no more purchases. The [token sale endpoints](https://docs.settlemint.com/docs/api-reference/v2) set the same allocations.

What this screen does own in setup is funding and the go decision. A sale that takes direct purchases must hold the full hard cap in tokens before activation, and the banner states whether it does. While an unfunded sale still takes direct purchases, the banner also says to set application mode before funding when the offering should take applications. A sale in application mode holds none of the offering and takes no funding. Its settlement mints each allocation, so activation needs the sale's own address to hold the Supply management role on the token. For such a sale the banner asks for that grant instead of funding: on the token's Permissions tab, grant the offering's address Supply management, then choose "Activate offering". Until the screen has read whether the sale takes applications, the banner shows a placeholder rather than either instruction.

**Fund offering** mints the shortfall it reads to the contract, so a partially funded sale is topped up. The entry shows to an Offering admin or Funds manager on the token, and the mint itself needs the token's Supply management role, because the mint happens on the token. "Activate offering" then enables the sale under its configured schedule, and setup is over: after purchases begin, the contract holds investor payments and the path in [How an offering moves through its states](#how-an-offering-moves-through-its-states) governs.

Activation and opening are separate moments. Activate before the configured start time and the sale stays closed to buyers, with a banner naming the exact date it opens. A purchase attempted early reverts on chain whatever any screen shows, so activating ahead of the start opens the sale at the configured time.

## Pause, extend or end an offering [#pause-extend-or-end-an-offering]

An active sale needs no operator input. Where a presale is configured, it rolls into the public sale on its own when the configured presale end passes. A sale with no presale starts in public sale. Either way, the sale stops taking purchases at its end time. A full hard cap does not end the sale: further purchases are refused, and the sale still waits for its end time or for "End offering" before it can be finalised. The presale can use a discounted price and its own per-address cap. It also requires the buyer to be whitelisted. Public-sale buyers still need to meet the offering's other eligibility rules. Whitelist edits made after the presale has passed change nothing about who can purchase, and the **Whitelist** tab warns about this once the offering has moved past presale.

Four controls interrupt that schedule, and each carries a different cost:

- **Transition to public sale** ends the presale early, and it is available only while the sale is in its presale phase.
- **Pause offering** stops new purchases on this sale only: nothing changes for the token itself, for its transferability, or for any other instrument that trades it, and "Resume offering" reopens purchases where they left off.
- **Extend offering** moves the end date later by a whole number of days, while the sale is active or paused. When vesting is configured, the end date cannot move past the vesting start.
- **End offering** ends the offering permanently. There is no resume from it, so it is the one control here whose cost is irreversibility, and the confirmation says so before you sign.

## Read why a purchase is blocked [#read-why-a-purchase-is-blocked]

Before an investor reaches a purchase at all, the Console evaluates their eligibility and shows one of three verdicts:

- **Eligible** means the current pre-check found no blocker. State can change before execution.
- **Action required** means every blocking reason is one the investor can resolve, such as an unverified identity or a missing, revoked, or expired claim, and the Console routes them into that flow directly.
- **Not eligible** names a rule only an administrator can lift.

A blocked investor can still open **Subscribe** and inspect the purchase sheet. Its submit control remains disabled until the eligibility blockers clear.

The purchase form validates before it submits. The form checks the first-purchase minimum, the subscription step, the cumulative buyer maximum, and any presale cap. Returning buyers can top up below the first-purchase minimum, but every top-up must keep the running total on the subscription step. A per-investor allocation is checked on chain only. An amount beyond the sale's remaining headroom is reduced to that headroom, with a notice. The sale contract takes the payment from the buyer's wallet, so the buyer first approves the sale to spend it, then submits the purchase. The buy flow asks for that approval only when the existing allowance is too small.

When a purchase still reverts on-chain, the Console tells the buyer two things. The spend approval is in place, so approving again is wasted effort. And the sale contract refused for a specific, named reason. The named reasons are the contract's own. The buyer was not eligible, was not on the whitelist, or had not accepted the terms. The sale contract sits on the system's compliance bypass list, so the token's transfer check does not stop tokens moving into it, and these eligibility checks run on the buyer. The purchase would have crossed the hard cap or the buyer's own maximum allocation. The sale had not started, was not active, or its soft cap rule blocked the operation.

## Run a book-built offering [#run-a-book-built-offering]

An offering can take applications instead of direct purchases. While the offering is in setup, an Offering admin selects **Set application mode** in the "Applications and allocation" section of the "Purchases" tab. Set it before "Fund offering". A sale that issues its shares at settlement holds none of the offering, so once such an offering is funded the section no longer offers "Set application mode" and says why: switching it on would issue each share twice. The offering then takes direct purchases. To take applications, create a new offering and set application mode before you fund it. A sale whose contract delivers the tokens it holds can still switch after funding. Application mode cannot be changed after activation, and an offering activated without it takes direct purchases only.

In application mode, investors apply with an escrowed payment that may exceed what the offering can deliver. The section lists each "Applicant" with the "Payment amount", the "Tokens requested", the allocation and refund, the "Status", and the "Lock-up". Until the allocation runs, the allocation and refund columns are projected from the current book.

After the sale ends and applications close, the Offering admin selects **Request allocation** and names the "Recipient of the payment". One run allocates the closed book pro rata, rounded down to whole tokens, finalises the offering, and settles every applicant: each investor is charged the price of the tokens they were allocated, rounded down in their favour, receives those tokens and the rest of their payment back in the same step, an applicant whose tokens cannot be delivered is refunded in full, and the tokens lost to rounding stay unissued with the issuer. When the sale missed its soft cap, no allocation is made and every applicant is refunded in full. When the allocation does not start within 30 days after the sale ended, every applicant reclaims their own payment with "Reclaim payment".

Two optional terms sit beside the applications table as the "Greenshoe" and "Lock-ups" cards. A greenshoe is extra supply the issuer may add when demand exceeds the hard cap, and a lock-up keeps delivered tokens from moving for a number of days. Only an Offering admin sets them, and only while the sale is in setup.

**Set greenshoe**, and "Change greenshoe" once one is set, asks for the size as a percentage of the hard cap, with up to two decimals and at most 655.35%. Zero removes the greenshoe. The exercise is "Automatic" or "Discretionary". An automatic greenshoe covers the demand above the hard cap, up to its size, when the allocation starts.

For a discretionary greenshoe, an Offering admin selects **Exercise greenshoe** once the sale has ended and before the allocation starts. The amount is a whole number of tokens, at most the smaller of the greenshoe capacity and the demand above the hard cap. On a token with a supply cap, the room the cap leaves above the hard cap also limits it. An exercise happens once and its amount cannot change. It joins the book, so an allocation run requested earlier must be requested again. Starting the allocation without an exercise leaves the offering at the hard cap and the greenshoe can no longer be used. The book totals then show "Base offering", "Greenshoe" and "Total offering".

**Set lock-ups**, and "Change lock-ups" once they are set, takes up to eight categories. Each category is a claim topic, a type of verified identity claim, with a number of days, and "Days locked for other investors" covers everyone else. The first category the investor's wallet is verified for sets the lock-up, so list the longest first. The longest lock-up is 1,826 days and zero locks nothing. A sale with lock-ups needs the Governance role on the token for the sale's address and an active lock-up rule on the token, or the offering cannot be activated. Grant the role on the token's permissions page. A lock-up set where every duration is zero needs neither. After the allocation is delivered, the "Lock-up" column on each application shows the locked amount, "Unlocks" with the date, and the category, or "Other investors" for the default.

**Request allocation** opens the allocation run. It asks for the "Recipient of the payment", and the wallet that signs the request needs both the Offering admin and the Funds manager role on the token. When offerings approval is on, a second person must approve the run, and the approval fails if the book changes before then.

## Finalise an offering [#finalise-an-offering]

A sale with no configured soft cap always finalises as a success. It records no payment per buyer, so investors have no refund claim on it. A sale with one finalises as a success only if total tokens sold reached it. Once the sale has ended, **Finalize offering** appears with a checklist beside it showing the soft cap status, the hard cap status, and the outcome those numbers predict. The checklist is a preview only. The on-chain finalise transaction is what decides and records the outcome. Until someone sends it, the sale sits in its ended state and every investor position stays undecided.

On a sale with a soft cap, a successful finalisation releases the tokens the sale held, on the vesting schedule when one is set. A sale without a soft cap does not wait for it: tokens transfer at purchase, or release on the vesting schedule. The server resolves the claimable figure each investor sees from the vesting schedule and any soft-cap hold. A zero after finalisation is always explained: the position sits before its vesting cliff, was already claimed in full, has not started vesting yet, or has nothing unlocked yet at this point in the schedule. Before finalisation, an ended sale shows a hold naming the undecided outcome, with the progress bar locked until the finalise transaction resolves it. Success also frees the issuer's own **Withdraw funds**: unlike a failed sale, there is no waiting period, so the funds manager can pull the raise the moment finalisation records success.

## Refund investors and withdraw funds [#refund-investors-and-withdraw-funds]

Failure opens refunds, and refunds are per currency: each payment currency settles as its own independent transaction, because no single on-chain step refunds them all at once. Claiming all currencies from one verification step drives each one in sequence and reports partial progress as it goes. A currency that reverts keeps its failed status with the decoded reason inline, and does not roll back one that already settled. Only the failed currency needs a retry. When everything is claimed, the section says so instead of showing an empty table.

The issuer's own **Withdraw funds** comes last. After a sale finalises as failed, that withdrawal stays locked for thirty days from the moment of failure. After that, the issuer can pull only the balance above the refunds that investors have not claimed yet. On a sale that took purchases before it ran the current sale implementation, those earlier contributions are not reserved, and only the thirty-day wait protects their refunds. The withdrawal itself asks for a recipient: it defaults to your own wallet, and a treasury address routes the raise elsewhere. The sale's own token is never offered as a withdrawable currency, because the contract was never holding it on the issuer's behalf. Recovering unsold tokens is the separate "Withdraw unsold tokens" control.

## Release a purchase the sale cannot deliver [#release-a-purchase-the-sale-cannot-deliver]

A sale with a soft cap holds every buyer's tokens until a successful finalisation, and a buyer can lose the right to receive them in that time: the wallet is frozen, or the identity verification lapsed. A freeze by the token's custodian is enough, so the issuer's roles together can return a buyer's purchase to the unsold pool and refund the payment. The "Cap table" tab shows each buyer's delivery state. It names each buyer by the user, participant or contact that owns the wallet, a smart account included, and shows the wallet address when the platform knows no name. When the sale can no longer deliver to a buyer, a funds manager sees **Refund undeliverable purchase** on that buyer's rows. The release returns the undelivered tokens to the unsold pool and records a refund of the undelivered share of the payment, in every currency the buyer paid in. The row then reads "Refund recorded", and "Pay out refund" pays one currency at a time to the buyer's wallet, or to the wallet that replaced it through identity recovery. A paid currency reads "Refund paid". The [token sale endpoints](https://docs.settlemint.com/docs/api-reference/v2) expose the same two steps.

A buyer can also lose the wallet itself. When identity recovery replaces a lost wallet, the sale cannot deliver to the old wallet, and nobody can sign from it. The cap table then shows **Deliver to recovered wallet** on that buyer's rows once tokens can be withdrawn. The sale never offers a release for a recovered buyer, so the buyer keeps the tokens they paid for. Before the first tokens vest, the rows show no action. It sends the tokens the buyer can withdraw now to the wallet that the identity registry names as the replacement. The vesting schedule still applies, so a vesting buyer gets each vested part the same way. Any wallet can send the delivery, because the sale takes the recipient from the identity registry and the caller cannot change it. The sale refuses the delivery for a buyer whose own wallet is not lost. That buyer withdraws as usual.

When a sale fails, the refund of a lost wallet's contribution cannot be claimed from that wallet either. The Platform API route `POST /api/v2/addons/token-sales/{saleAddress}/recovered-wallet-refund-claims` takes the lost wallet and pays the refund to the replacement wallet that the identity registry names. The sale refuses it for a wallet that is not lost.

A sale with vesting and no soft cap records no payment per buyer, so it cannot calculate a refund and does not offer the release. When this sale cannot deliver to a buyer, for example because the wallet is frozen, the cap table marks the buyer's rows **Undeliverable, held in sale**. The tokens stay in the sale, and the buyer keeps the right to them. A regulated issuer decides each case outside the platform, for example under a sanctions rule or a court order, and settles any repayment or seizure there. When the issuer lifts the freeze, or the buyer is verified again, the buyer withdraws as usual. Do not use a forced transfer to move held tokens out of the sale: the sale still counts them as owed to the buyer, so the transfer leaves the sale short for that buyer or for the unsold pool.

## Read the commitments chart [#read-the-commitments-chart]

The overview tab charts what investors committed in each period and the running total, grouped by day, week or month depending on the sale's length, with the soft and hard caps drawn as reference lines. Every viewer of the operating console sees it.

A sale that is still open also shows a dashed projection to its close, labelled with the projected total. It carries the last seven full days' pace forward, slows it each week by as much as the last seven days fell against the seven before, never speeds it up, and stops at the hard cap, reaching the cap on the day that pace would fill it. The projection appears once the sale has run for 14 days and has commitments, and until then the chart says there is no projection. A sale that already reached its hard cap, or no longer takes commitments, shows none.

Below the chart, a sale manager sees the offering funnel, counting investors: Whitelisted, Committed and Settled for an offering with a presale, and Committed and Settled for any other offering. **View as table** on either chart lists the same numbers as text.

## Read the offerings insights [#read-the-offerings-insights]

The **Insights** tab beside the offering list summarises all the organisation's offerings. It appears for an account with the "Permission manager" or "Asset manager" role. Its range and comparison controls work as on [asset Insights](https://docs.settlemint.com/docs/console/asset-management/insights#open-insights-and-choose-the-period).

- **Headline.** When an offering closes within a week, a line over the figures reads, for example, "The next offering closes in 3 days." It counts whole hours under two days and whole days from two days on, and never rounds up. Otherwise the line does not show.
- **Key figures.** "Raised (all offerings)" is the amount raised per payment currency, net of refunds, with the largest currency first and the others listed beside it. The amounts are never added across currencies. "Investors" counts unique buying wallets, so one person who buys from two wallets counts twice. "Soft cap reached" counts the offerings that reached their soft cap, out of all offerings. "Purchases" counts purchases in the selected range, with the change on the prior period.
- **Needs attention.** A card lists up to six offerings in this order, each with its button: awaiting finalisation with "Finalize", which opens the offering to finalise it there, near the hard cap with "Review", presale ended with "Move to public", and inside the refund grace window with "Review". "Show in list" opens "Offerings" filtered to those offerings. The card is absent when nothing needs attention.
- **Composition and trend.** The "Purchases" trend sits beside "Offerings by status". "Sold vs hard cap" shows up to eight offerings, with a tick on each bar for the soft cap. Beside it, "Investors by country" also says how many investors have no registered country.

The attention card and the status table read the 200 offerings with the latest start dates.

## Roles and approvals [#roles-and-approvals]

Two role systems meet on this screen. Organisation-wide system roles decide what you can open: "Permission manager" or "Asset manager" reaches the list of every sale and any sale's operating console. On-chain sale roles decide what you can sign: each entry under **Actions** requires a specific role held on the sold token's access manager, Offering admin or Funds manager for "Fund offering" and "Finalize offering", Funds manager for "Withdraw funds", and Offering admin for "Activate offering" and the remaining lifecycle controls. "Actions" lists only the entries your sale roles cover. An asset manager who was never granted a sale role can open every sale but sign none of its transactions. The offering then has no "Actions" menu. While the offering is in setup, its banner says your wallet lacks the Offering admin role. An Offering admin or Funds manager without an organisation-wide role still reaches "Offerings", which then lists only the sales of tokens your organisation issued on which you hold that role.

The **Permissions** tab is where that gap closes: it assigns Offering admin and Funds manager on this sale without granting full token administration. "Manage roles" is enabled only for an account with the Permission manager role on the token. For everyone else it is disabled, and its reason names the permission managers who grant offering roles. The "Cap table" tab follows the sale roles too: it shows only to an Offering admin or Funds manager on the sale's token, the two roles its request answers to. Editing the "Whitelist" tab needs Offering admin specifically. The "Allocation caps" section on that tab shows to Offering admin and Funds manager, and only Offering admin changes it. "Fund offering" takes either Offering admin or Funds manager on the offering's token. "Activate offering" and the other actions keep their own role. [Roles and permissions](https://docs.settlemint.com/docs/console/organisation-settings/admins-and-roles#change-offering-roles-on-an-offering) shows how a Permission manager of the token grants and revokes the two roles on this tab.

When your organisation turns on the "Offerings" row under **Approvals** on [General](https://docs.settlemint.com/docs/console/organisation-settings/general#approvals), creating an offering, opening it, ending it and running its allocation wait for a second person, who sees the offering terms. The approver is an organisation owner unless the approval policy names other approver roles, and the person who made the change cannot approve it. The platform holds the transaction until the approval is decided. The sale contract does not check the approval, and the row is off until an owner turns it on. An allocation run under that approval starts only once it is approved, and the approval fails if the book changes before then.

## How an offering moves through its states [#how-an-offering-moves-through-its-states]

Every offering moves one way through setup, active and ended, then success or failure. Pause and resume interrupt the active state, and an application-mode sale is finalised by its allocation run. In setup the issuer funds the sale contract and activates it. An optional presale admits whitelisted addresses under its own price and per-address cap, and the sale then moves to the public sale under the standard price. Without a presale, eligible buyers start in the public phase. When its end arrives, what happens next turns on one number: whether total tokens sold reached the soft cap, the minimum the issuer configured for the raise to count as a success.

[Figure] A primary offering's path from funding to delivery. A sale starts in setup, where the issuer funds the contract and activates it. Active, it runs an optional presale open only to whitelisted addresses, before opening as a public sale to any eligible investor. Ending checks the soft cap, but the outcome is not automatic: someone must send the Finalize offering transaction. It records a success, unlocking vesting for investors, when the soft cap was reached or none was configured, and a failure when the soft cap was missed. A failure opens refunds per currency, and holds the issuer's own withdrawal of the raise for thirty days. Labels: Funding to delivery; Setup; fund, then activate; Active; optional presale, then public; Ended; soft cap decides; Finalise: cap reached, or none set; Finalise: cap missed; Success; finalised, vesting unlocks; Failed; refunds open per currency; issuer withdrawal waits 30 days.

A sale moves from setup to active to ended, and finalising records success when the soft cap is met or none is set and
opens refunds when it is missed.

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

- **Offerings** shows the offering's status, and the matching tab on the offering shows what you did:
  - A funding shows in the banner, a purchase in "Purchases", a whitelist edit in "Whitelist" and a role grant in "Permissions".
  - A finalisation shows in the banner's success or failure state.
- For a book-built offering, the "Applications and allocation" section reads "The allocation is settled. Tokens are delivered and refunds are paid." when the run completes, and each application's "Status" reads **Settled**.
- When the sale missed its soft cap, each application reads **Full refund due**, and "Refunded in full" marks an application whose tokens could not be delivered, so its whole payment went back. A payment an investor took back after the 30 days reads "Reclaimed".

## Troubleshooting [#troubleshooting]

**Offerings is missing or says Access restricted**

Your account holds neither the "Permission manager" nor the "Asset manager" system role, and no Offering admin or
Funds manager role on a token your organisation issued. Ask an organisation administrator for one of those roles, or
ask a permission manager on the token to grant you a sale role from the sale's **Permissions** tab.

**Create offering is missing or disabled**

The control needs two things at once: the "Asset manager" role, and at least one token your account governs, because
creating an offering needs the Governance role on the token you sell. The wizard lists every token, then checks
Governance on the one you choose and blocks signing until you hold it there. Without the role, the control is disabled
and its reason says that asset managers create offerings. With the role but no governed token, the control is disabled
and names the Governance role. Ask an administrator for the role, or for governance on the token you intend to sell.

**Activate offering is disabled or refused**

An uploaded terms document whose hash is not recorded keeps it disabled: select **Set terms** first. A sale that takes
direct purchases must hold the full hard cap: select "Fund offering". A sale in application mode needs the sale's own
address to hold the Supply management role on the token, and a sale with lock-ups needs the Governance role on the
token for the sale's address and an active lock-up rule on the token.

**Actions is missing or lacks an entry**

You opened the console through an organisation-wide role, but the entries need an on-chain sale role on the sold
token. Without Offering admin or Funds manager the offering has no **Actions** menu. With one of them, the menu lists
only the entries that role covers: Fund offering and Finalize offering take either role, Withdraw funds needs Funds
manager, and the other entries need Offering admin. Have a permission manager on the token grant the role from the
sale's "Permissions" tab, then retry. The grant is an on-chain transaction, so allow it to settle first.

**A purchase reverts after the spend approval already succeeded**

Do not approve again for the same attempt: the toast already confirms the spend allowance is in place, and the failure
is the sale contract's own decoded refusal. Match that reason against [Read why a purchase is
blocked](#read-why-a-purchase-is-blocked), clear the underlying condition, an eligibility, whitelist, or terms gap,
the sale's own numbers, or its timing, and resubmit the same amount.

**A vesting position shows nothing claimable**

The tile's status label names the reason. Before finalisation it reads "Pending finalization". See [Finalise an
offering](#finalise-an-offering) for what unlocks it. After a successful finalisation it reads one of "You can claim
from" followed by the cliff date and time in UTC, **Fully claimed**, "Not started", or "Nothing claimable yet", each
resolved on the server from the vesting schedule.

**A refund claim fails for one currency**

The usual cause is the refusal "No contribution to refund, so no money moved": the sale holds no contribution from
this account in that currency. The payment was already refunded or reclaimed, or it was paid from another account or
in another currency, so the row is stale. No money moved. Refresh the page and check the account's balance instead of
retrying. Other failures include token restrictions or too little refundable balance. Read the reason and the prior
transaction outcome before retrying. Keep currencies that already settled unchanged.

**Withdraw funds is locked on a failed sale**

The refund grace period is running: for thirty days from the moment the sale failed, the contract protects the refund
pool and refuses the issuer's withdrawal. Wait out the window. After it, the issuer can withdraw only the balance
above the refunds that investors have not claimed yet, so a withdrawal can return zero while refunds stay unclaimed.
The sale's own token also never appears among the withdrawable currencies. Recover unsold tokens through "Withdraw
unsold tokens" instead.

## Frequently asked questions [#frequently-asked-questions]

### Can investors pay in more than one currency?

Yes. A sale lists one or more payment currencies, each with its own price in that currency, and every purchase spends exactly one of them. One investor can buy several times in different currencies, which is why a failed sale refunds per currency rather than in one combined amount: each currency's contribution is tracked and returned in its own units.

### Does pausing a sale change its schedule?

No. The start and presale end times are fixed at creation, and the clock keeps running while purchases are stopped. A pause spends part of the sale window rather than extending it, so a long pause near the end can leave little or no time to buy after "Resume offering". To give buyers that time back, use **Extend offering** to move the end date later. "End offering" stops the sale early, and it does so permanently.

### What happens to tokens that never sold?

They stay in the sale contract until a sale administrator recovers them with **Withdraw unsold tokens**, which the Console offers once the sale is finalised in either direction. Through the [token sale endpoints](https://docs.settlemint.com/docs/api-reference/v2), the withdrawal also works on a sale closed with "End offering" before finalisation, including a sale that was never activated. A sale that takes direct purchases must hold the full hard cap before activation, so one that ends short of that cap holds unsold tokens worth reclaiming. An application-mode sale holds none of the offering, because its settlement mints each allocation.

### What happens to a live sale during a stock split?

A sale that holds the offered token keeps running, re-based. Purchases so far, the remaining inventory, the price and the per-buyer limits move by the action's ratio, and the sale's holdings follow the units the action mints or burns for it. From the action's record date until its step lands, the sale is frozen for that token: purchases, allocation, delivery, claims, refunds and withdrawals are refused with a message that names the token and the action. Buy, claim or refund again once the action has finished. See [corporate actions](https://docs.settlemint.com/docs/console/asset-management/manage/corporate-actions) for how the freeze starts and ends.

### Who can see who the investors are?

The **Purchases** tab shows buyer wallet addresses to anyone operating the sale. Resolved identities, names, KYC status, and country, appear only in the "Cap table", whose request answers solely to a sale administrator or funds manager on that sale. In the Console, an investor's subscription view shows only their own purchases.

### Can the terms document change after investors accept it?

No. The platform records the terms hash on-chain once, during setup, and refuses a second set-terms call. The sale contract accepts a hash only while the sale is in setup, and investors can acknowledge only after a hash is recorded. Each acknowledgement event carries the hash it accepted. A buyer must acknowledge terms when the sale requires them. Retain the accepted hash and acknowledgement event as evidence.

### How do I replace a brochure or another offering document?

On the "Marketing" tab, open the document's menu and choose **Upload new version**. The dialog keeps the document type and starts with the current visibility, title, and description, and you choose the replacement file. After the upload, the new file is the current version and the earlier version stays in the list. The menu offers the action only on the current version, and only to an account that can delete that document. A terms document takes a new version only while the sale is in setup and before its hash is recorded.


# Announcements

Source: https://docs.settlemint.com/docs/console/asset-lifecycle/venues/announcements
Publish, schedule, edit, attach to and withdraw venue announcements for the whole venue or one instrument.

An announcement is a notice to the participants of the whole venue or of one instrument. A wallet that holds the "Venue operator" or "Venue admin" role on the venue writes one on the venue's **Announcements** tab, and those roles are granted on the venue's [Permissions](https://docs.settlemint.com/docs/console/asset-lifecycle/venues/permissions) tab. The platform adds the notice to each participant's notification list, which the Platform API serves, and emails the participants who have email switched on for it. [Participant alerts](https://docs.settlemint.com/docs/console/asset-lifecycle/venues/participant-alerts) sets the default for that email.

![The venue's Announcements tab with the Publish announcement button and the announcements table with Title, Audience, Severity, Status, Published and Actions columns](https://docs.settlemint.com/docs/screenshots/console-venue-announcements.light.en.webp)

[Screenshot] The DALP Demo Exchange "Announcements" tab, with search, the "Severity" and "Status" filters and the "Publish announcement" button.

The table lists two notices with severity "Warning" and status "On display", each with a "Withdraw" action. An opened
row shows the notice's **Announcement history**.

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

- **A wallet that operates the venue.** Publishing, editing or withdrawing a notice needs the "Venue operator" or "Venue admin" role and a wallet verification.
- **A PDF, if the notice needs a document.** Each file is limited to 10 MiB, or to the lower limit your deployment sets.

## Steps [#steps]

### Write and publish the notice [#write-and-publish-the-notice]

1. Select **Publish announcement**. Enter the "Title" and the "Message", and pick the "Audience": "Entire venue" or one instrument by its name. A notice on a private instrument reaches only that instrument's participants and operators.
2. To send the notice to specific participants, choose them under **Addressed to**. Only those participants see the notice and are notified, and the history shows the operator who it went to. Leave the field empty to reach everyone in the audience. On a private instrument, each participant you name must hold a wallet on that instrument.
3. Pick the **Category** and the "Severity". The categories are "Notice", "Broadcast", "Trading window" and "Corporate action". The severities are "Information", "Warning" and "Critical". A "Corporate action" notice follows each participant's email setting for corporate actions, and every other category follows the setting for announcements.
4. Leave **Display from** empty to publish now, or enter a later UTC date and time to schedule the notice. "Display until" sets when participants stop seeing it, and it must be later than the time the notice goes live. "Announcement date" is the date the notice carries, and it defaults to the day the notice goes live. "Announcement date" refuses a typed day that does not exist, such as `2026-02-30`, and shows a message under the field. The sheet's "Publish announcement" stays unavailable until you correct or clear that date.
5. Attach one PDF under "Attachment" if the notice needs a document, then select **Publish announcement** and verify your wallet. The notice appears in the table as "On display", or "Scheduled" when you set a later "Display from".

## Read the announcement history [#read-the-announcement-history]

The table on the "Announcements" tab lists every notice with its status: "Scheduled", "On display", "Display ended", "Withdrawn" or "Pending approval". A scheduled notice reaches participants, and sends its published webhook, only when it goes live. A notice whose display has ended stays in the table for operators. Open a row to read its **Announcement history**: the date it was announced, when it went or goes live, when it was updated or withdrawn, and when its display ends.

Participants see a notice in the announcement banner of the trading desk and in their notification list. The banner marks each notice's severity with its own icon, and a screen reader reads the severity before the title, such as "Warning: …". Only a **Critical** notice is announced as an alert and interrupts a screen reader. An "Information" or "Warning" notice does not interrupt, and a notice that arrives behind the lead one is heard as the new count of folded notices. With more than one notice on display, the banner shows the most severe one and folds the rest behind "Show 2 more announcements", which a screen reader hears as "2 more announcements". For scheduling, attachments, issuer announcements and publication windows, read [the trading venue concept](https://docs.settlemint.com/docs/concepts/issuing-and-markets/trading-venue#announcements).

## Approve or reject an issuer's notice [#approve-or-reject-an-issuers-notice]

A holder of the token's Governance or Supply management role can submit a notice about that token through the API, and it waits as "Pending approval". Its row offers **Approve** and "Reject", each after a wallet check. "Reject" first asks you to confirm, and "Keep" backs out. "Approve" puts the notice on display now, or at its go-live time when it is scheduled. One venue operator or venue admin approves it without a second person, and it then reaches holders on every instrument that trades the security, whichever venue lists it. "Reject" withdraws a notice that never went live: participants never see it, no webhook is sent, and its history reads "Rejected". If another operator already decided the notice, the list refreshes and shows the refusal.

## Edit, attach to or withdraw a notice [#edit-attach-to-or-withdraw-a-notice]

**Edit** changes the title, message or severity of a notice that is on display or whose display has ended. Enter a "Reason for the change", select "Save changes" and verify your wallet. Participants see the new text marked as updated. The reason stays with the previous version in the notice's revision history and is not shown to participants.

**Attach PDF** adds a document to a notice that is scheduled, on display or whose display has ended, up to five PDFs per notice. With five attached, the action says "A notice holds up to 5 PDFs." Each file has the same size limit as at publication.

**Withdraw** removes the notice from the participants' view and cannot be undone. A scheduled notice withdrawn before it goes live sends no webhook.

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

- Find the notice in the table on the **Announcements** tab and check its status: "Scheduled" until its "Display from" time, then "On display".

## Troubleshooting [#troubleshooting]

**A notice has no Edit or Withdraw action**

A notice with the status **Pending approval** offers "Approve" and "Reject" instead of "Edit" and "Withdraw". A notice
that is withdrawn cannot be changed or restored. Edit changes a notice that is on display or whose display has ended.

**Publishing is refused**

**Display until** must be later than the time the notice goes live. A PDF must fit the size limit, 10 MiB or the lower
limit your deployment sets, and a notice holds up to five PDFs. Publishing needs the "Venue operator" or "Venue admin"
role on a wallet of yours and a wallet verification. A refused "Announcement date", or an empty "Title" or "Message",
keeps "Publish announcement" unavailable. The message under the date field says what to correct. A "Display from" or
"Display until" with only part of its date and time filled in also keeps it unavailable: complete the field or clear
it.

## API routes [#api-routes]

Your systems receive the `trading-venue.announcement.published`, `trading-venue.announcement.updated` and `trading-venue.announcement.withdrawn` webhooks, which the [webhook event reference](https://docs.settlemint.com/docs/api-reference/webhooks/market-events#trading-venue) describes. The tab calls the trading venue routes in the [v2 API reference](https://docs.settlemint.com/docs/api-reference/v2).


# Desk administration

Source: https://docs.settlemint.com/docs/console/asset-lifecycle/venues/desk-administration
Propose and approve desk trading limits for trader wallets, and decide the venue configuration changes that wait for a second operator.

A desk is an internal trading limit an operator grants a trader wallet, separate from the eligibility a wallet needs to trade at all. On the **Desk administration** tab, a venue operator proposes a desk limit and a different operator approves it. A proposed limit constrains no order until that approval. The tab also lists the venue configuration changes that wait for a second operator, where a different operator approves or rejects each one.

![The venue's Desk administration tab with the desk limit form, the Proposals table and the Effective desk limits table](https://docs.settlemint.com/docs/screenshots/console-venue-desk-administration.light.en.webp)

[Screenshot] The "Desk administration" tab with "Desk name", "Trader wallet" and "Open-exposure cap" fields and the "Propose desk limit" button, above the "Proposals" and "Effective desk limits" tables.

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

- **A venue operator or venue admin.** Only venue operators and venue admins can read or propose desk limits. Anyone else sees the form disabled with the reason "Venue operators and venue admins manage desk limits on this venue."
- **A second operator, when the venue asks for one.** While the "Trading venues" row under "Approvals" on [General](https://docs.settlemint.com/docs/console/organisation-settings/general#approvals) is on, a different operator approves the proposal, and the server rejects self-approval.
- **An instrument on the venue.** A venue with no instrument reads "This venue has no instrument to set a desk limit on."

## Steps [#steps]

### Propose a desk limit [#propose-a-desk-limit]

Pick the **Instrument** by its pair, such as EUROC / AEDT. When the venue lists the same pair twice, the trading model tells the two apart.

Enter the "Desk name", choose the "Trader wallet", and enter the "Open-exposure cap", which must be above zero and counts the resting orders plus the new order in the quote token.

Select **Propose desk limit** and confirm with your wallet verification. While the "Trading venues" row is on, the Console reads "Desk limit proposed. A different operator must approve it." With the row off it reads "Desk limit active."

### Decide a proposal [#decide-a-proposal]

A different venue operator opens "Desk administration", finds the limit under "Proposals" with the "Proposed by" column, and selects **Approve** or "Reject", confirming with their wallet verification. An approved limit moves to "Effective desk limits", and a rejected one leaves the list.

**Proposals** lists only the proposals that wait for a decision. On a proposal you made, the row reads "Needs a different venue operator" and offers no "Approve" or "Reject". Another operator sees both. When nothing waits, the list says "No desk limit proposals are open".

## Approve or reject a venue configuration change [#approve-or-reject-a-venue-configuration-change]

**Venue configuration approvals** on "Desk administration" lists the changes to this venue that wait for a second operator. Expand a row to see what the change does. Each changed field appears under its own name, with its "Before" and "After" value. Each value reads as the operator entered it. Prices show in the quote token and sizes and notionals with the token symbol. Windows and periods show as durations such as "5m", and on and off settings, countries and fees show in words. A list such as the trading week, date exceptions, closed days, collection windows or fee tiers shows one line per entry. A field the stored state does not carry reads "Not set".

The "Actions" column appears only while a row has an action for you. Select **Approve change** to apply it or "Reject change" to drop it, and confirm with your wallet verification. A change you proposed offers neither, because a different operator must decide it. When nothing waits, the table reads "No venue configuration changes are waiting for approval".

## Which changes need a second operator [#which-changes-need-a-second-operator]

The **Trading venues** row under "Approvals" on the "General" page of "Organisation settings" decides whether these changes, sent through the Console or the Platform API, wait for a second operator. An exception there can turn it on or off for one venue. A venue admin can also turn the second operator on or off for this venue through the Platform API, and turning it off waits for a second venue admin like the changes below:

- desk limits and trade busts
- single order cancels and mass cancels. A venue submitter wallet that calls the venue contract directly cancels any order with no second person, and so does a venue operator wallet unless the venue's default admin set an on-chain approval rule for that cancel
- instrument listings, settings, fees, price bands, order limits, order types and closing method
- instrument halts, suspensions, resumptions, delistings and scheduled status changes, except an emergency halt the venue admin has allowed to skip approval, which runs at once
- removing a participant from an instrument
- the venue and instrument trading calendars, closed days and collection windows
- the venue price band, listing rules, VAT policy, retention period, fee tiers and admission. Admission, the venue calendar and closed days also wait for a second person while the **Administration** row protects the "Venue administration" group
- fee schedule changes
- pausing or resuming the venue
- turning the second operator off for the venue, or letting an emergency halt skip it. A venue with a single admin has to add a second admin first, because the proposer cannot approve their own change. Turning the second operator on, or stopping emergency halts from skipping it, applies at once

Only venue admins propose and decide a change to the venue price band, admission, listing rules, VAT policy, retention period, venue calendar or closed days, and the resumption of a paused venue. Deciding a change to an instrument's listing, settings, fees, price bands, order limits, order types, closing method, halt, status or participants also needs the Platform admin or Owner role. A fee schedule change is approved by a different platform administrator or organisation owner. The distinct-operator rule is per record: any venue operator may propose some changes and approve others, and the server refuses only a decision on a record that same operator proposed.

With the row off, none of them asks for a second person: a desk limit is enforced at once, a bust of an undelivered trade starts its undo at once, a new fee schedule version becomes the active schedule, the VAT policy is saved, and a cancel runs. Each change applied this way is logged as not approved by a second person. A bust of a delivered trade always waits for a second operator, because its reversal moves the holders' tokens with a forced transfer. Cancelling all of one participant's orders is a mass cancel limited to that participant, so it follows the same row: with the row off, one venue operator runs it at once after wallet verification.

An instrument listing on a venue whose row is on waits under **Venue configuration approvals** until a second operator approves it. The listing wizard ends with a link to this tab. Price bands and order limits you set in the wizard travel with the held listing, the approval row shows them to the second operator, and the approval applies them to the new instrument.

An approved desk limit is read at order intake as a ceiling on that trader wallet's exposure, on top of whatever eligibility or venue-wide authorisation already applies.

## When a proposal expires [#when-a-proposal-expires]

A desk limit, bust, mass cancel or fee schedule proposal that no second operator decides in time expires. The window is 24 hours by default. The platform operator can set a different window for desk limits, for busts, and for mass cancels and fee schedule changes together. A venue configuration change expires after 24 hours. A single order cancel does not expire, because its approval is refused once the order is no longer open.

The "Expires" column on the Mass cancellations tab and the "Due" column in the Actions inbox show the deadline of a proposal. An expired proposal shows **Expired** and offers no "Approve" or "Reject", and the server refuses a decision that arrives after the deadline. The platform closes an expired proposal within about a minute and records the expiry in the audit trail. An expired bust clears its flag in the same way as a rejection, so the delivery can proceed. If the change is still necessary, propose it again.

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

- A desk limit shows under **Effective desk limits**.
- With the "Trading venues" row on, it appears after a different operator approves it.
- With the row off, it appears at once.
- A proposal that is still open shows under "Proposals" with its "Proposed by" operator.

## Troubleshooting [#troubleshooting]

**A proposed desk limit has no effect**

A proposed desk limit does nothing until a different operator approves it. Until then, the limit that was effective
before still applies, or none. The server rejects a self-approval, so ask another venue operator to approve a limit
you proposed.

## API routes [#api-routes]

A venue admin turns the second operator on or off for this venue with `PUT /api/v2/addons/trading-venues/{venueAddress}/maker-checker`, after wallet verification. Turning the second operator off, or setting `allowEmergencyHaltWithoutApproval` to `true`, answers with the proposed change instead of the new setting and waits under **Venue configuration approvals** until a different venue admin approves it. The setting stays as it was until then. Turning the second operator on, or setting `allowEmergencyHaltWithoutApproval` to `false`, applies at once, and so does any change on a venue whose row is already off. While the "Administration" row protects the "Venue administration" group, an owner also approves the request first. The other desk limit and approval routes are in the [v2 API reference](https://docs.settlemint.com/docs/api-reference/v2).


# Held fills

Source: https://docs.settlemint.com/docs/console/asset-lifecycle/venues/held-fills
Find the fills the platform could not settle, read why each was held, and retry it or propose a bust.

When a fill cannot settle after the platform's automatic retries, or fails the same way on every attempt, the platform holds that fill with its decoded refusal reason. Both legs of the held fill, the base tokens and the quote tokens, stay locked in the venue's [escrow](https://docs.settlemint.com/docs/console/asset-lifecycle/escrows), and the trade stays pending delivery until an operator decides. The **Held fills** tab of the venue, titled "Held settlement fills", lists the 100 most recently held fills, and the filters reach older ones. An operator reads why each fill was held, then retries it or proposes a bust.

![The Held settlement fills tab with the Instrument, Reason and age filters, and No held settlement fills while every fill has settled](https://docs.settlemint.com/docs/screenshots/console-venue-held-fills.light.en.webp)

[Screenshot] The "Held settlement fills" tab with the "Instrument", "Reason", "Minimum age (seconds)" and "Maximum age (seconds)" filters.

With nothing held, the tab reads "No held settlement fills" and "Fills that fail to settle wait here for an operator to retry or bust them." When fills are held, the table shows "Trade", "Instrument", "Parties", "Amounts", "Reason", "Attempts" and "Age".

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

- **The Venue operator role on the venue.** Reading and acting on held fills needs it. A venue admin grants it on the venue's [Permissions](https://docs.settlemint.com/docs/console/asset-lifecycle/venues/permissions) tab.
- **A reason and your wallet.** Each action needs an operator reason and your wallet verification.
- **A second operator for a bust.** A bust follows the venue's "Trading venues" row under "Approvals" on [General](https://docs.settlemint.com/docs/console/organisation-settings/general#approvals) like any other bust. While the row is on, a different venue operator approves it.

## Steps [#steps]

### Find the held fill [#find-the-held-fill]

Open "Asset lifecycle", then "Venues", select the venue, then "More" and **Held fills**. The list shows the trade, the instrument, both parties, the base and quote amounts, the reason, the attempts with the last attempt, and the age.

Filter by **Instrument**, "Reason", "Minimum age (seconds)" or "Maximum age (seconds)". The filters stay in the page address, so you can hand the same view to a colleague.

### Read why it was held [#read-why-it-was-held]

Select **Open details** on a row. The "Held fill details" sheet shows the buyer, seller, quantity, price, first and last attempt, the attempt count and the "Attempt history", with links to the trade and both orders. "Retry now" and "Bust" sit in this sheet.

A failed settlement attempt keeps the trade in **Pending delivery**, keeps both legs locked, and retries on its own after a growing delay. The platform holds a fill instead when:

- the failure repeats on every attempt
- the venue refuses the fill on chain, for example with `InvalidDeliveryRecipient` on an instrument with a holding period when the buyer, seller or a fee recipient is the zero address, the escrow or an address on the token's compliance bypass list
- the fill owes VAT on chain that cannot be paid
- the batch runs out of automatic retries

A failing batch of several fills is split in halves until the platform isolates the failing fill, and only that fill is held.

### Retry the fill [#retry-the-fill]

In the sheet, enter the "Operator reason (required)", select **Retry now** and confirm with your wallet verification. The platform queues the fill for settlement again and records your reason in the audit trail. The fill leaves the list as soon as the retry is queued. For a reason the platform marks non-retryable, the sheet warns that the retry needs an explicit override, which the audit trail records. The action stays off until you tick "Confirm override for this non-retryable reason", and the platform refuses the retry without it. A retry, with or without the override, needs no second operator.

### Bust the trade instead [#bust-the-trade-instead]

Select **Bust** to propose a trade bust for the held trade, with the same reason and wallet step. The proposal is refused while either order of the trade is still open. It follows the venue's "Trading venues" row like any other bust. An approved bust undoes the trade, refunds the escrow lock of each closed order, and removes the held fill. [Trade busts](https://docs.settlemint.com/docs/console/asset-lifecycle/venues/trade-busts) covers the approval.

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

- Filter the held fills to the instrument you worked and check that a fill you retried has left the list.
- The fill leaves when the retry is queued, so check on [Settlement instructions](https://docs.settlemint.com/docs/console/asset-lifecycle/venues/settlement-instructions) that the trade moves from "Pending delivery" to **Delivered**.
- For a bust, open [Trade busts](https://docs.settlemint.com/docs/console/asset-lifecycle/venues/trade-busts) and check the proposal, then check that the trade reads "Undone" on [Settlement instructions](https://docs.settlemint.com/docs/console/asset-lifecycle/venues/settlement-instructions).

## Troubleshooting [#troubleshooting]

**Retry now is refused for a reason marked non-retryable**

A retry is not expected to change this reason, for example a refusal that repeats on every attempt. Confirm the
override to retry anyway, which the audit record keeps, or bust the trade.

**A bust from a held fill is refused**

An order from the trade is still open and must be cancelled on the
[Orders](https://docs.settlemint.com/docs/console/asset-lifecycle/venues/orders) tab, or another of the causes listed under [Trade
busts](https://docs.settlemint.com/docs/console/asset-lifecycle/venues/trade-busts#troubleshooting) applies.

## API routes [#api-routes]

| Task | Route |
| --- | --- |
| List the held fills | `GET /api/v2/addons/trading-venues/{venueAddress}/settlement/parked` |
| Retry one held fill | `POST /api/v2/addons/trading-venues/{venueAddress}/settlement/parked/{fillId}/retries` |

Integrations receive the `trading-venue.settlement-fill.parked` webhook when a fill is held, and `trading-venue.settlement-fill.aged` when it stays held past an age set for your deployment. The webhook and the route say parked where the Console says held. The request and response fields are in [the v2 API reference](https://docs.settlemint.com/docs/api-reference/v2).


# Venues

Source: https://docs.settlemint.com/docs/console/asset-lifecycle/venues
Provision a venue, open its detail, list an instrument, pause the whole venue, and find the screen for each other venue task.

A venue is a deployed contract that lists one or more instruments, each a base and quote token pair with its own tick size, lot size, price bands and fee schedule. From **Venues** you provision a venue, list an instrument and pause the venue, and each venue tab holds one other task, from orders and desk limits to settlement and the trading calendar. [Trading](https://docs.settlemint.com/docs/console/my-assets/trading) is the investor and desk workspace for trading on an instrument that already exists.

Pausing or freezing a token, on [Emergency halt and freeze](https://docs.settlemint.com/docs/console/asset-management/manage/pause-freeze), acts on the token contract and reaches every venue. An instrument halt stops one instrument on this venue, as [Instrument](https://docs.settlemint.com/docs/console/asset-lifecycle/venues/instrument) describes. Maker-checker is the two-operator pattern that desk limits and busts run on in the platform while the **Trading venues** approval row is on. On chain, the operations signer sends the approved bust.

![Detail page of the DALP Demo Exchange venue with the List instrument button and the Trading calendar tab](https://docs.settlemint.com/docs/screenshots/console-venue-operations.light.en.webp)

[Screenshot] The venue detail page with its header, its tabs and the "Overview" counts.

The header shows the venue name, the "Trading venue" label, the venue status badge and the "List instrument" button. Below it run the "Overview", "Desk administration", "Listing rules", "Permissions", "Trading calendar" and "Announcements" tabs, with the remaining tabs under "More". The "Overview" tab shows the "Instruments", "Open for trading", "Halted" and "Suspended" counts, the "Venue contract" address and a table of the venue's instruments.

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

- **An on-venue role for each action.** Inside a venue, the on-venue roles "Venue operator" and "Venue admin" gate individual actions, as [Which venue role each setting needs](#which-venue-role-each-setting-needs) lists.
- **A provisioned venue before the first listing.** The screen offers that step itself, as [Provision a venue](#provision-a-venue) describes.
- **The tokens and the parameters of the instrument.** Prepare the base and quote tokens, tick size, lot size, minimum notional, maker fees, taker fees, market-order protection band, and fee account before you list an instrument. The lot size must be exactly one whole base token, because the venue does not price fractional lots. The wizard holds the structure step until it reads the base token's decimals and offers "Try again" when that read fails, and the venue refuses any other lot size.
- **Which order types the instrument allows.** A trader can place a stop order only where the instrument allows Stop, and the venue holds the stop's balance from the moment it is placed.
- **The matching mode and visibility settled.** Those cannot change afterwards, so settle them first.
- **A second operator, when the venue asks for one.** While the venue's "Trading venues" row under "Approvals" on [General](https://docs.settlemint.com/docs/console/organisation-settings/general#approvals) is on, approving a proposal needs a second operator distinct from whoever proposed it.

## Steps [#steps]

### Provision a venue [#provision-a-venue]

Open "Asset lifecycle", then **Venues**. The list shows, each in its own column, a venue's instrument count and its instruments open for trading, halted and suspended.

Select **Provision venue**, or "Provision the first venue" when the list is empty. Both appear for organisation owners and platform administrators. The "Provision a trading venue" flow asks you to name the venue and confirm with your wallet. Provisioning deploys the venue from your system's Trading Venue factory.

The wallet you confirm with becomes the venue's "Venue admin" and holds the default administrator role on its access manager, which sets any approval rule on the venue's checked functions. The organisation's managed operations signer, the platform's signing service, receives the venue submitter role, which submits settlement and busts. Once provisioning completes, select **List first instrument**.

The platform cannot propose or approve on chain, so a venue with an approval rule on listing an instrument, changing a fee schedule or changing a holding period refuses that change in the Console and the Platform API with "The venue requires on-chain approval for this action" (409, `VENUE_ONCHAIN_APPROVAL_REQUIRED`) and sends no transaction. To allow the change again, the venue's default admin sets the rule's approval count to 0.

### Open the venue [#open-the-venue]

Select a venue in the list to open its detail page. The **Overview** tab counts the venue's instruments, those open for trading, those halted and those suspended, and lists every instrument with its status, matching mode and price band. Select an instrument row to open [the instrument](https://docs.settlemint.com/docs/console/asset-lifecycle/venues/instrument).

### Find the screen for your task [#find-the-screen-for-your-task]

| Task | Screen |
| --- | --- |
| Review, export and cancel orders | [Orders](https://docs.settlemint.com/docs/console/asset-lifecycle/venues/orders) |
| Decide a mass cancel and download its record | [Mass cancellations](https://docs.settlemint.com/docs/console/asset-lifecycle/venues/mass-cancellations) |
| Halt, suspend, delist, price bands, fees, calendar override | [Instrument](https://docs.settlemint.com/docs/console/asset-lifecycle/venues/instrument) |
| Propose a desk limit, decide a venue configuration change | [Desk administration](https://docs.settlemint.com/docs/console/asset-lifecycle/venues/desk-administration) |
| Set the defaults, order rule limits, starting values, admission minimums and retention | [Listing rules](https://docs.settlemint.com/docs/console/asset-lifecycle/venues/listing-rules) |
| Admission, venue roles, blocks | [Permissions](https://docs.settlemint.com/docs/console/asset-lifecycle/venues/permissions) |
| See why one wallet can or cannot trade | [Participant access](https://docs.settlemint.com/docs/console/asset-lifecycle/venues/participant-access) |
| Hours, half days and closed days | [Trading calendar](https://docs.settlemint.com/docs/console/asset-lifecycle/venues/trading-calendar) |
| Publish a notice | [Announcements](https://docs.settlemint.com/docs/console/asset-lifecycle/venues/announcements) |
| Choose default email alerts | [Participant alerts](https://docs.settlemint.com/docs/console/asset-lifecycle/venues/participant-alerts) |
| Undo a trade | [Trade busts](https://docs.settlemint.com/docs/console/asset-lifecycle/venues/trade-busts) |
| Read what each settlement moves | [Settlement instructions](https://docs.settlemint.com/docs/console/asset-lifecycle/venues/settlement-instructions) |
| Retry or bust a held fill | [Held fills](https://docs.settlemint.com/docs/console/asset-lifecycle/venues/held-fills) |
| Keep records out of retention | [Legal holds](https://docs.settlemint.com/docs/console/asset-lifecycle/venues/legal-holds) |
| Read trades and instrument status across venues | [Read the venues insights](#read-the-venues-insights) |

## List an instrument [#list-an-instrument]

Select **List instrument** in the venue header to configure the pair, the grid of tick size and lot size, the fees and the protection band. Review [which choices stay editable](https://docs.settlemint.com/docs/console/asset-lifecycle/venues/instrument#most-listing-choices-get-a-later-edit-some-do-not) before you submit the listing request.

The listing signer must hold the venue operator role, and the organisation's operations signer must hold the venue submitter role. Both tokens settle through the venue's escrow, so listing needs no token feature and no authorisation from the token's issuer. The escrow sits on the system's compliance bypass list, so the token's compliance rules do not refuse a deposit into it. A missing prerequisite refuses the listing and identifies the step and account to fix. When the venue contract itself refuses the listing, the API answers [DALP-14003](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference#domain-rule-errors) and names the venue's revert in `data.errorName` and `data.selector`. A fee above 1000 basis points, a zero tick size, a zero address, a pair already listed or permanently closed, and a paused venue each get their own reason and fix.

On the review chapter, **Checks before signing** also asks the platform whether it would accept the listing as entered. It runs once every other check has passed. A refusal, for example a listing the venue's listing rules do not admit or a pair that is already listed, shows as a blocked check with its reason and fix, and signing stays off, so you learn it before the PIN. The check stores nothing and signs nothing. The platform checks again when you sign, because the venue can change in between. If the check cannot answer, it does not block you and the listing request returns its own refusal.

The listing wizard starts from the venue's **Starting values for new instruments**, and the venue's "Order rule limits" cap the order types and time in force the new instrument can accept. A venue admin sets both on [Listing rules](https://docs.settlemint.com/docs/console/asset-lifecycle/venues/listing-rules).

## Pause or resume the venue [#pause-or-resume-the-venue]

The venue's state, "Venue accepting orders" or "Venue paused", sits next to its name on every tab. To stop the whole venue, select **Pause venue** in the header. On a phone it sits in the more-actions menu. A venue operator or venue admin can pause it after wallet verification. While the venue's "Trading venues" approval row is on, the pause waits under "Venue configuration approvals" on [Desk administration](https://docs.settlemint.com/docs/console/asset-lifecycle/venues/desk-administration#approve-or-reject-a-venue-configuration-change) until a different operator approves it, and a resume until a different venue admin approves it. Once it applies, the venue refuses new orders with the reason `venue-paused`, stops opening sessions, and stops new settlement batches. Due deliveries, cancels and payouts of free balances continue. The order ticket in the Console and in the Investor portal disables its place button and shows the pause reason beside it. An open trading desk picks up a pause or a resume without a reload. Existing orders stay on the book. Only a venue admin can select "Resume venue". Resuming the venue does not resume an instrument that was halted separately. Pause the venue for a venue-wide incident, and halt one instrument when only that instrument must stop.

## Read the venues insights [#read-the-venues-insights]

The **Insights** tab beside "All venues" shows how the venues trade, which instruments are live or halted, and where the venues are registered. Its range and comparison controls work as on [asset Insights](https://docs.settlemint.com/docs/console/asset-management/insights#open-insights-and-choose-the-period).

- **Key figures.** "Trades" counts trades across all venues in the range, with the trades of the last 24 hours. "Live instruments" shows the instruments open for trading now out of all listed, with how many are halted. "Venues" counts the venues, with how many have a live instrument. "Instruments traded in 24 hours" counts the instruments with at least one trade in that time, out of all listed.
- **Needs attention.** Cards count "Instruments halted", "Live instruments without trades in 24 hours" and "Instruments pending listing".
- **Composition and trend.** "Instruments by trades in 24 hours" and "Instruments by status" break the instruments down, "Trades" charts the trades over the range, and a map shows where the venues are registered.

## Which venue role each setting needs [#which-venue-role-each-setting-needs]

| Setting | Role |
| --- | --- |
| Pause the venue | Venue operator or venue admin |
| Resume the venue | Venue admin |
| Trading calendar and its closures, listing rules, default price band, VAT policy, retention policy, instrument groups | Venue admin |
| Fee tiers, a security's nationality list | Venue operator or venue admin |
| Decide a venue configuration approval | The role the change names |

The role must sit on one of your wallets. Without it, the control is disabled with a line that names the role it needs, or the wallet of yours that holds it, and the API refuses the request with `VENUE_ROLE_REQUIRED` before it asks for your wallet verification, so nothing is submitted.

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

- Return to **Venues** and confirm that the instrument count includes the new listing.
- Open the venue: the new instrument shows on "Overview" with its status and matching mode.
- After a pause, the header reads "Venue paused" and the order ticket is disabled.
- After a resume, it reads "Venue accepting orders".

## Troubleshooting [#troubleshooting]

**There is no List instrument button**

Either the venue does not exist yet or your session cannot list instruments. The Console shows **List instrument**
only to organisation owners and platform administrators, and only once your organisation has provisioned a venue,
because a listing with no venue behind it cannot succeed. Select "Provision the first venue" on the Venues list: name
the venue and confirm with your wallet, and it deploys from the Trading Venue factory registered in your system. If
the venue already exists, ask an organisation owner or a platform administrator to list the instrument. If the
platform reports that the factory itself is not available, the system deployment's add-on registration has not
finished indexing, or the trading-venue add-on was never installed. The [error
catalogue](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference) describes both refusals.

## API routes [#api-routes]

### Surveillance reports [#surveillance-reports]

The FIX drop copy, its replay and the daily surveillance files have no Console screen. A venue operator or venue admin reads them through the venue reports routes, and each route needs one of those roles on that venue.

| Task | Route |
| --- | --- |
| Preview a trading day's reports before a resend | `GET /api/v2/addons/trading-venues/{venueAddress}/reports/{tradingDay}/replay` |
| Ask the session to resend a completed day, with wallet verification | `POST /api/v2/addons/trading-venues/{venueAddress}/reports/{tradingDay}/replay-requests` |
| List the day's surveillance files, or what blocks them | `GET /api/v2/addons/trading-venues/{venueAddress}/reports/{tradingDay}/files?format=valcsv` or `format=olc` |
| Download one file | `GET /api/v2/addons/trading-venues/{venueAddress}/reports/{tradingDay}/files/{fileName}` |

A venue the drop-copy settings do not name, or a session that is not enabled, answers a replay call with 409 and DALP-14389, and so does a replay request for a day that has not ended. The preview answers for a running day. A file call answers the same 409 when the drop-copy settings do not name the venue or lack an exchange OMS name. A file name the day does not produce answers 404 with DALP-14390. [Controls and evidence](https://docs.settlemint.com/docs/concepts/issuing-and-markets/trading-venue#controls-and-evidence) explains the session, each report and each file column.


# Instrument

Source: https://docs.settlemint.com/docs/console/asset-lifecycle/venues/instrument
Halt, suspend or delist an instrument, edit its fees, price bands, holding period and calendar, and schedule collection windows.

An instrument is one base and quote token pair on a trading venue, with its own tick size, lot size, price bands and fee schedule. Its detail page holds the controls that decide what the instrument does next: the "Listing ceremony" checklist, the **Manage instrument** menu that halts, suspends or delists it, and the tiles that edit its fees, price bands, holding period, calendar and collection windows. [Venue operations](https://docs.settlemint.com/docs/console/asset-lifecycle/venues) covers the venue around it.

Halting or suspending an instrument here stops matching on this one venue only. It leaves the token's other transfer paths and other instruments' status unchanged, unlike [Emergency halt and freeze](https://docs.settlemint.com/docs/console/asset-management/manage/pause-freeze), which acts on the token contract itself. Shared token or network restrictions can still affect them.

![An instrument detail with the Manage instrument menu open on Halt instrument, Suspend instrument, Delist instrument and Schedule a change](https://docs.settlemint.com/docs/screenshots/console-venue-market-actions.light.en.webp)

[Screenshot] The EUROC / AEDT instrument with the "Manage instrument" menu open.

The instrument shows the "Session open" state. The open menu lists "Halt instrument", "Suspend instrument", "Delist instrument" and "Schedule a change", above the "Instrument structure" and "Fees" tiles.

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

- **A session and a wallet that operate the venue.** Instrument administration needs an organisation owner or platform administrator session and a wallet that holds the "Venue operator" role for the selected venue. The [error catalogue](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference) describes the refusal the API gives every other session.
- **A wallet verification and an operator reason.** A halt, suspension, resume, or delist needs the role, a wallet verification and an operator reason.
- **A second operator, when the venue asks for one.** While the venue's "Trading venues" row under "Approvals" on [General](https://docs.settlemint.com/docs/console/organisation-settings/general#approvals) is on, a second operator approves a halt, suspension, resume or delist, and the operator who proposed it cannot approve it. The row governs requests through the Console and the Platform API. A venue operator wallet that calls the venue contract directly is held only by the approval count the venue's access manager sets for that call.
- **The matching mode and visibility questions settled before you list.** Those cannot change afterwards. Listing a new instrument starts on the venue page, as [Venue operations](https://docs.settlemint.com/docs/console/asset-lifecycle/venues#list-an-instrument) describes.

## Steps [#steps]

### Open the instrument [#open-the-instrument]

Open "Asset lifecycle", then "Venues", select the venue and select an instrument row on the **Overview** tab. The detail holds the "Listing ceremony" checklist, the lifecycle controls described below, the fee schedule and price bands, the trading calendar, the close methodology and, on a private instrument, the approved participant wallets. Removing an approved wallet cancels its resting orders and releases its reserved balances, and the confirmation says so.

### Choose the operation [#choose-the-operation]

Select **Manage instrument** in the header for [halt, suspend, resume and delist](#halt-suspend-resume-or-delist). Use the tiles for the [fee schedule and price bands](#change-the-price-bands), the [holding period](#change-an-instruments-holding-period-or-valuation-price), the [calendar](#a-calendar-override-adds-one-exception-for-today-and-still-needs-saving) and the [collection windows](#collection-windows). While the venue's "Trading venues" row under "Approvals" is on, lifecycle, calendar, price band and fee changes sent through the Console or the Platform API wait for a second operator. A venue operator wallet that calls the venue contract directly changes fees, the fee account and the holding period with no second person.

### Review and submit [#review-and-submit]

Check the affected instrument and the values shown in the confirmation step before you confirm. A delisting cannot be undone, so it asks for a typed confirmation, as [Halt, suspend, resume or delist](#halt-suspend-resume-or-delist) describes. A [calendar override](#a-calendar-override-adds-one-exception-for-today-and-still-needs-saving) exists only on your screen until you select **Save calendar**. Complete every approval and wallet-verification prompt the operation presents.

## Read the instrument lifecycle [#read-the-instrument-lifecycle]

Every instrument carries one of five states, and what an operator can do next depends on which one it is in. An accepted instrument starts pending while its listing ceremony checks the registered feed writer, eligible fee account, trading schedule, trading model, valuation price, and price floor. A continuous instrument needs weekly trading days, its own or the venue's. An auction-only instrument needs a collection window in the instrument's or the venue's timezone. A private continuous instrument always needs a price floor. The instrument goes live only when every item is complete, a private listing still states its sponsorship and meets the venue's current minimum admission value and share count, and any go-live time set for the instrument has passed. An instrument that falls short stays pending until a later check finds it complete. The **Listing ceremony** checklist on the instrument detail marks each item "Complete", "Blocked", or "Awaiting" and refreshes itself every ten seconds while the listing is pending. A live instrument accepts orders and matches them under its price bands. From live, an operator can halt, suspend, or delist it. A halted instrument accepts no new orders and matches nothing while retaining pending orders, though Day and Good till date orders still expire on schedule. From halted, an operator can resume, suspend, or delist it. A suspended instrument has no pending orders because suspension cancels them across all validities. It can resume to live with an empty book. Delisting is available from every state except delisted and moves an instrument to its final state, where new trading remains disabled. Pending delivery obligations keep their own lifecycle.

[Figure] An instrument's lifecycle: pending, live, halted, suspended, delisted. An instrument starts pending while its listing ceremony completes: a registered feed writer, an eligible fee account, a trading schedule, a selected trading model, a valuation price, a price floor where the instrument requires one, and a listing that meets the venue's current listing rules. When the ceremony completes and any go-live time set for the instrument has passed, it goes live on its own. From live, "Halt instrument" moves it to halted and "Suspend instrument" moves it to suspended. From halted, "Resume trading" returns it to live and "Suspend instrument" moves it to suspended. From suspended, "Resume trading" returns it to live. From pending, live, halted and suspended, "Delist instrument" moves it to delisted, including a pending instrument whose ceremony has not completed. Suspension cancels every resting order, so a suspended instrument that resumes opens with an empty book. Delisted is final: every resting order cancels, every locked balance unlocks, the instrument closes for good, and no arrow leaves it. Labels: Instrument lifecycle; Pending; ceremony in progress; Live; orders match and settle; Halted; matching paused; Suspended; book cancelled; Delisted; permanent, no way back; Halt instrument; Resume trading; Suspend instrument; Resume trading; Suspend instrument; Delist instrument; Delist instrument; Delist instrument; Delist instrument.

Delisted is the only state with no arrow leaving it, and a pending instrument can be delisted before its listing ceremony completes.

## Halt, suspend, resume or delist [#halt-suspend-resume-or-delist]

Halting, suspension and delisting differ in what they do to orders already in flight. Halting and suspension are reversible, and delisting is not. All three start from **Manage instrument** in the header of the instrument detail.

**Halt instrument**

Stops matching and new order acceptance once the halt is recorded. A halt cancels no resting order and unlocks no balance. Orders that expire on their own schedule still expire, and a submitted settlement batch keeps its own execution outcome. Scheduled auctions wait too: an opening auction or collection-window clearing due during the halt runs at the first session step after you resume, and a session that ends while halted closes without its opening auction. A halt is meant to be temporary and cheap to reverse. Resuming reopens matching with the same wallet-verification step as any other Console admin change.



**Suspend instrument**

Stops matching and new order acceptance, then cancels every resting order across all validities. Each cancellation unlocks its amount back to free escrow balance and appears in the transition result and order activity. A suspension is reversible: resuming returns the instrument to live with an empty book.



**Delist instrument**

Shares the role and the wallet-verification step a halt uses, but it cannot be reversed. Every resting order on the instrument is cancelled, every locked balance behind those orders is unlocked, and the instrument closes permanently. The confirmation asks you to type a phrase built from the first six characters of the base and quote token addresses, so a delisting cannot be submitted against the wrong instrument.

After a successful halt, resume, or delist, the platform publishes a trading-window announcement for that instrument. The default announcement names the instrument and includes the operator's reason. An API caller can provide its own title or body, or set `announce` to `false` when the transition should stay silent. Halt and delist announcements carry warning severity. Resume announcements carry info severity. A request that repeats a transition another operator already made publishes nothing. A suspension publishes no announcement, and a suspend request that sends `announce` is refused.

On a venue whose **Trading venues** row is on, a halt waits for a second operator like any other instrument transition. A venue admin can let an emergency halt skip that wait by setting `allowEmergencyHaltWithoutApproval` with `PUT /api/v2/addons/trading-venues/{venueAddress}/maker-checker` in the Platform API. A halt request that then sends `emergencyHalt: true` halts the instrument at once, without a second operator, and records the halt under "Instrument emergency halt" as executed, with no checker. The same call with `makerCheckerRequired` set to `false` turns the second operator off for the whole venue. It, like turning the emergency halt bypass on, waits for a different venue admin to approve it under "Venue configuration approvals", and the venue keeps asking for a second operator until then. Resuming the instrument is its own request. The flag applies only to a halt: a request that sets it with any other target state is refused, and resume and delist always follow the row. The Console has no control for an emergency halt.

## Schedule a change [#schedule-a-change]

To make a halt, suspension, resumption or delisting happen later, choose **Schedule a change** from "Manage instrument", then set these fields:

- In **Move the instrument to**, pick "Instrument halted", "Instrument suspended", "Open for trading" or "Delisted", as the instrument's current state allows.
- Under **When**, choose "When the next session opens" or "After the session closes on a date".
- For a date, enter a **Date** in the instrument's time zone.
- Give the change a **Reason**.

The earliest date the **Date** field accepts is the current date in the instrument's time zone. The empty field shows that date as its example. The calendar greys out earlier days, and a typed earlier date shows "Enter a date on or after" and that date, so no request is sent.

## Most listing choices get a later edit, some do not [#most-listing-choices-get-a-later-edit-some-do-not]

| Choice | Can you change it after listing | Cost of a wrong guess |
| --- | --- | --- |
| Fees, price bands and order thresholds, the minimum notional, the trading calendar, the official close methodology, the indicative price publication setting, the attributes of a book level participants see, and, on a private instrument, the participant list | Yes, each has its own editor on the instrument detail | One edit |
| Matching mode, **Continuous** or **Auction only**, and visibility, public or **Private instrument** | No, fixed the moment the instrument lists | Choose deliberately before you list |
| The trading grid of tick size and lot size, the market-order protection band's width, and the auction remainder rule, **Carry to the book** or **Cancel remainders** | No, no editor exists on the instrument detail | Delist and relist |

A continuous instrument matches orders as they arrive. An auction-only instrument matches only in auction crosses. A private instrument restricts trading to approved participant wallets in either matching mode, and its participant list stays editable after listing. A private instrument never shows an indicative price or quantity. A public instrument's **Indicative price visibility** setting controls whether participants receive the indicative price and quantity during pre-open and collection: everyone, operators only, or nobody. A private instrument shows participants only the top of the book, one level a side, even when it listed before that rule with full depth stored. A public instrument keeps its own depth setting. The "Book shown" row of the "Trading style" tile on the instrument detail reports how many levels a participant with depth access sees and how many levels a participant with depth entitlement sees.

By default an instrument carries unfilled "Good till cancelled" and "Good till date" orders to the book after an auction, under the "Carry to the book" rule. You can choose **Cancel remainders** at listing. A carried order keeps its hold, and a "Good till date" order still expires on its date. When an auction is blocked or refused at the window close, a carry instrument keeps its resting orders. Only an instrument set to "Cancel remainders" cancels them.

A new continuous instrument allows "Day" orders alongside "Good till cancelled" and "Good till date". An auction-only instrument does not. A day order rests until the instrument's session closes. The venue then closes it as "Expired" and unlocks its locked balance, so an early close, a holiday, "Extend trading" or "Delay open" moves the expiry with the schedule. A day order expires at the close of its trading session: the session it was placed in, or the next scheduled session for a day limit order placed while the instrument is closed. It expires when that scheduled close passes even if the instrument stayed halted all session. On an auction-only instrument whose operator allows "Day", a day order expires when its collection window closes. A closed instrument accepts no other order, and a halted or suspended instrument does not open its session until it resumes. An instrument with no trading calendar, neither its own nor the venue's, refuses day orders.

Each instrument also sets which attributes of a book level its participants see. The price is always shown. The quantity and the order count are each optional, and a new instrument shows all three. You choose them in the listing wizard and change them later under **Participants see** in the instrument's order rules editor, where "Price" is locked on. A hidden attribute reaches participants as null over the API, in both the book read and the stream, and the order book ladder shows "Hidden" in place of a hidden size. The depth chart shows "This instrument does not show quantities, so there is no depth to chart." The venue operator always sees full depth with every attribute. A change to a hidden quantity sends participants no stream update.

The instrument's **Depth for participants without depth access** tile sets what a participant whose access does not include depth sees in the order book. "Top of book only", the default, shows the best bid and ask. "Nothing" shows no book: the order book panel shows only its title and the note "Your access to this instrument does not include the order book.", with no price step, column headers, last trade or auction matching price. A participant with depth access and the venue operator are not affected.

A private listing also asks who initiated it, under **Listing initiated by**: the issuer, for a sponsored listing, or a holder, for an unsponsored one. On a sponsored instrument the venue refuses an order, buy or sell, from a wallet whose registered country the security's country rules exclude, or whose country it does not know. The nationality rule changes order eligibility only. A restricted wallet keeps the instrument's public listing, prices, and depth, while private instrument visibility still follows the participant list. The wizard asks for the minimum admission value and share count the [listing rules](https://docs.settlemint.com/docs/console/asset-lifecycle/venues/listing-rules#set-the-admission-minimums-for-private-listings) set, and the venue refuses a private listing below either. An optional "Floor price" on the risk step, entered as a price on the instrument's tick grid, is saved with the price bands.

Maker and taker fees, in basis points and zero allowed, adjust through **Edit fee schedule** on the Fees tile, which opens the fee schedule in a side panel with the resting-order impact shown before a raise applies. On a delisted instrument "Edit fee schedule" is disabled, and the API refuses the change. The official close methodology opens through "Edit official close" on the Trading style tile and saves through "Save methodology", between "Last trade" or "VWAP" with its window in whole minutes. A VWAP close is the volume-weighted average price of the settled trades in that window before the close, rounded down to the tick. If nothing traded in the window, the close uses the same window length ending at and including the session's last trade. The configured no-trade fallback can use the auction price and then the previous official close, or the previous official close directly. A first session without a previous close uses the instrument reference price. A trade that settles after the session closes updates the official close once it settles, using the policy stored for that session. Price bands and order caps open through "Edit price bands" on the Risk controls tile.

The same sheet has a **Volatility interruption** group with "Threshold" (basis points, 1 to 10000), "Duration" (seconds, 1 to 86400) and "Reference price" ("Last trade" or "Previous close"). It is off until you fill it in, and clearing the threshold turns it off again, so no existing instrument changes behaviour. While it is on, a trade that would print further from the reference price than the threshold does not print. Fills inside the threshold stand, and continuous trading stops at the first resting order beyond it. The instrument collects orders for the set duration, then one single-price auction clears the book and continuous trading resumes. The auction price is not bound by the market-order protection band, but the static band, the price band and the floor still apply. While trading is interrupted, the instrument header shows "Interrupted · Volatility" with the time the auction runs, and the instrument page in the venue shows the same badge beside its status. The market data stream and the FIX drop copy report the interruption when it starts and when it ends. Each start and end is also written to the audit log as a system action, however it ends. A session change away from continuous trading, such as a close, ends the interruption without an auction. Changing the rule keeps a running interruption on its original timing, and clearing the threshold ends it at once without an auction: the orders collected meanwhile rest and trade against the next incoming order. The change follows the same approval and dating rules as any other band change.

The sheets that edit one setting, such as the minimum notional, the trading cut-off and the indicative price publication, say beside **Save** why it is off: "Change the value to save." while the value matches the stored one, "Fix the value marked in red to save." while the entry is not valid, and "Change this setting while the instrument is open for trading or halted." for a setting that changes only then.

### Change an instrument's holding period or valuation price [#change-an-instruments-holding-period-or-valuation-price]

You can set a listed instrument's holding period to any value from 0 to 30 days. Open the instrument detail and choose **Edit holding period** on the "Instrument structure" tile, or send an instrument update through the API. The change is its own update and asks for wallet confirmation. It needs the same venue-operator role as other instrument settings. Before an instrument's first auction, "Edit valuation price" on the same tile changes its valuation price. After the first auction the tile shows "Valuation is fixed after the first auction." instead. A delisted instrument cannot change either value. Both buttons are disabled, and the API refuses the change.

The new period applies to fills that settle on chain after the change lands. Trades already waiting for delivery keep their release time.

## Assign instrument groups [#assign-instrument-groups]

Groups such as equities or fixed income sort a venue's instruments, and a participant's access profile can allow or refuse trading by group. Every instrument read returns the instrument's group. A venue admin defines the groups through the Platform API with `PUT /api/v2/addons/trading-venues/{venueAddress}/instrument-groups/{code}`, and the Console has no editor for them. A code starts with a capital letter and holds up to 16 capital letters, digits, hyphens or underscores, and it is unique on the venue. Sending an existing code with a new name renames that group. Any caller who can see the venue lists its groups.

When the venue defines groups, the listing wizard offers **Instrument group**, with "No group" for an instrument that belongs to none. A listing that names a group the venue does not define is refused with "The venue refused the listing: the instrument group it names is not one this venue defines." When the groups cannot be read, the wizard says "The platform cannot read this venue's instrument groups" and offers "Try again", and you can still list the instrument without a group. A change of an instrument's group is written to the audit log with the group it left and the group it joined. The trading desk's instrument panel names the instrument's group, and the "Participant access" page shows which instrument groups the wallet may trade on each instrument, after its access profile and any override.

## Change the price bands [#change-the-price-bands]

On the instrument detail, open **Edit price bands** on the Risk controls tile. The instrument's "Price-band setting" offers "Inherit venue default", "Off for this instrument", or "Instrument override". The Risk controls tile says where the band comes from: "Inherited from the venue" or "Set on this instrument". That selection applies across the instrument's instrument models. Inheriting instruments follow later venue-default changes. An override uses its own static or dynamic policy.

![The Price bands & order thresholds sheet with the anchor, widths, order caps, floor price and the Price-band setting](https://docs.settlemint.com/docs/screenshots/console-venue-price-bands.light.en.webp)

[Screenshot] The "Price bands & order thresholds" sheet with the anchor, widths, order caps, floor price and the "Price-band setting".

The sheet lists "Anchor price", "Anchor mode", "Anchor-price width", "Last-trade width", "Min order quantity", "Max order quantity", "Max order notional" and "Floor price", then the "Price-band setting" set to "Inherit venue default", and "Save bands".

A dynamic band starts around the previous official close. While the override is dynamic, **Anchor mode** stays on "Roll on close" and says "A dynamic band always rolls the anchor to each official close." A trade at a bound widens only that side by one step, up to the maximum threshold. Between the session close and the official close, a band that rolls on close has no anchor, and every order, market orders included, is refused. When the official close lands, resting orders outside the new band are closed as Rejected with the reason "Above the price band's upper limit" or "Below the price band's lower limit". Orders inside stay on the book. If the session ends with no official close, the band re-anchors on its pre-close reference, otherwise on the previous close. Static and dynamic bounds include both endpoints and apply to continuous fills and auction clearing prices as well as limit-order admission.

Saving a tighter policy closes every resting order outside the new range as "Rejected" with the price-band reason and unlocks its locked balance. No separate prune action is required for those orders. An instrument whose band setting `outOfBandCarryOver` is `suspend` keeps them instead: each order outside the band is suspended, leaves the book with its reservation and time priority, and returns to the book when a later band covers it again. [Trading: how a resting order becomes a fill](https://docs.settlemint.com/docs/concepts/issuing-and-markets/trading-venue#trading-how-a-resting-order-becomes-a-fill) explains suspension and reinstatement. **Prune out-of-band orders** is a separate action for orders that stay resting outside the static or dynamic band width in basis points or over a quantity cap. The order ticket shows the configured range. Market orders retain their separate signed protection limit, but each fill must also stay inside the effective price band.

Before a tighter limit is saved, the band editor asks for **Preview impact**, and "Save bands" stays off with "Preview the impact before saving a tighter limit." until you run it. The preview counts the resting orders the change would close: "No resting orders fall outside the new limits.", or the number with "Saving cancels them and releases their reserved balances." The "Venue price band" on the "Listing rules" page asks for the same preview before any change to the default, summed over every instrument that inherits it, and a count of zero still lets you save. A width band or a quantity cap does not close an order on save. Those orders stay resting until you select "Prune out-of-band orders", whose confirmation states how many resting orders it cancels before "Prune orders" releases their reserved balances.

A floor, a maximum order size or value, or an anchor-based width saved before the price-band policy stays in force until you change it. **Off** disables only the new price-band policy. Raising the issuer floor also cancels resting orders below it. The separate "Market-order protection band", shown in basis points on the "Instrument structure" tile, remains set at listing, with no editor afterwards.

Raising the fee schedule above a resting order's signed fee cap does not silently charge the difference. The order still rests and can match, but the venue contract refuses to settle any fill of it at a fee above that cap, and the platform holds the fill on the **Held fills** tab for an operator to retry or bust. Before you apply the change, the fee-schedule screen reports the number of resting orders it affects, or says the venue has not reported the count when it cannot compute the figure.

## A calendar override adds one exception for today, and still needs saving [#a-calendar-override-adds-one-exception-for-today-and-still-needs-saving]

An instrument's trading calendar sets its normal weekly session and any dated holiday or half-day exception. An instrument without a weekly session of its own trades the venue's week: its calendar shows the venue's time zone and weekdays, and saving gives the instrument its own schedule. A private continuous instrument shows those weekdays without the pre-open, which it never runs. If the instrument's calendar, or the venue's week it shows, cannot be read, the card shows an error with Retry instead of an empty week. The card's next change, such as "Closes 29 Oct 2026, 14:59 UTC · 23:59 UTC+9", reads in UTC and then in the calendar's own time zone. The operator overrides "Delay open", "Extend trading" and "Close early" each prefill a dated exception for today on top of the calendar, and the exception takes effect when you select **Save calendar**. "Delay open" moves today's open 30 minutes later, "Extend trading" moves the close 60 minutes later, and "Close early" sets the close to the next minute, never at or before the open. An auction-only instrument has no daily trading hours and offers no overrides. On a day with no session, whether the weekday is disabled or a holiday exception suppresses it, the override buttons are disabled and the panel says today has no session to override, because there is nothing to delay, extend, or end early. The exception an override writes is marked with the override's name, as "Unsaved override: Delay open" until you save and "Override: Delay open" afterwards, and the mark is stored with the calendar, so an intervention stays distinct from a hand-entered half day after a reload. A day with no "Pre-open" time opens straight into trading, as [Skip the pre-open for a day](https://docs.settlemint.com/docs/console/asset-lifecycle/venues/trading-calendar#skip-the-pre-open-for-a-day) explains. A public continuous instrument can also set an optional "Closing auction from" time on a weekday or exception, as [Add a closing auction](https://docs.settlemint.com/docs/console/asset-lifecycle/venues/trading-calendar#add-a-closing-auction) explains.

## Collection windows [#collection-windows]

An auction-only instrument collects orders over collection windows instead of daily hours. On its instrument detail, the **Collection windows** tile lists each window as "Scheduled", "Collecting" or "Cleared", with only the five most recent cleared windows.

1. Select **Edit schedule** to open "Collection window schedule".
2. Enter one window that repeats every week with **Opens at (HH:MM)** and "Clears at (HH:MM)".
3. Check the **Windows to save** preview for the next 12 weeks in the instrument's time zone. It lists under "Skipped" each week that has "already started" or "clears on a closed day", and states how many upcoming windows the save replaces. A window that already started is kept.
4. Select **Save schedule**.

The platform stores the weekly pattern and keeps generating windows from it 90 days ahead. Once a window has ended, a new order or a reduction of an order's quantity is refused with "This instrument's collection window has ended; its orders wait for the clearing".

| What you see | Why | What to do |
| --- | --- | --- |
| "This instrument has no time zone yet. Set one on the venue calendar or the instrument calendar, then schedule windows." | Windows are entered in the instrument's local time | Set a time zone on either calendar |
| "No window is left to save. Every week has already started or clears on a closed day." | Every previewed week was skipped | Choose times that clear on an open day |
| "The calendar did not load in full, so closed days may be missing here. A week that clears on a closed day is refused when you save." | The preview could not load the closed days | Save anyway: the platform refuses a week that clears on a closed day |

## A stock split cancels the orders it re-based [#a-stock-split-cancels-the-orders-it-re-based]

A [stock split](https://docs.settlemint.com/docs/console/asset-management/manage/corporate-actions), forward or reverse, changes every holder's units and the share's reference price. A resting order keeps the quantity, price and escrow commitment its maker signed, so the venue cannot re-size or re-price it. It cancels the order instead.

Confirming a split cancels every open order on each instrument whose base or quote token it splits, stop orders included, and waits until each order's locked balance is back in free escrow balance before any unit moves. The venue keeps checking in the background as well: while a split on the instrument's base or quote token moves units, it cancels every open order on the instrument. Once the split has ended, the venue cancels every order accepted at or before the end and keeps the orders accepted after it. An aborted split counts once it has moved any holder's units or re-set the reference price. A split aborted while a chunk or the price update was still queued counts as moving units until that settles, and its end is the moment the last of them landed, so an order placed between the abort and that landing is cancelled too. Each cancellation appears in order activity with the reason "a stock split changed the instrument's units and price", and its locked balance returns to free escrow balance. An order with a trade still to settle is cancelled at once, and its balance is unlocked once that trade settles.

The sweep covers live, halted and suspended instruments alike. Halting an instrument before the split keeps its orders, as any halt does, until the split starts moving units. To give participants notice before then, suspend the instrument instead, which cancels every resting order straight away.

## A split re-bases escrow balances and held trades [#a-split-re-bases-escrow-balances-and-held-trades]

The venue's escrow holds tokens for each participant. When a split, bonus issue or other corporate action changes the units of a token the escrow holds, the platform counts each participant's escrow balance as if they held it directly, and the action mints to or burns from the escrow the sum of those amounts. Each free balance and each lock then moves to the new basis the next time it is read or used, with the action's own rounding. The escrow balances on the venue show the new amounts once the action has run.

A trade still in its holding period when the action runs is delivered on the new basis: the base quantity, the quote to the seller and each fee move by the action's ratio, and whatever the trade's escrow holds beyond that returns to the participant's free balance. Under a round-up-to-one action on the quote token, the lifted quote and fee amounts can come to more than the buyer's lock. That delivery is refused: the trade is undone with the reason Refused, both locks go back to the participants' free balances, and no operator has to act.

## Check that an instrument is trading [#check-that-an-instrument-is-trading]

Open the venue to see each instrument's status on its "Overview" tab, then open the instrument and confirm its calendar, bands, fees, controls, or participant access reflect what you submitted. To confirm an instrument is trading, read its **Instrument activity** card: the last price, the 24-hour volume, trades and range, and the price over the last 24 hours.

![An instrument's Instrument activity card with the last price, 24-hour volume, trades, range and price chart](https://docs.settlemint.com/docs/screenshots/console-venue-market-activity.light.en.webp)

[Screenshot] The "Instrument activity" card below the instrument settings.

The card shows "Last price" and its change, "24-hour volume", "24-hour trades", "Open" and "24-hour range", and the "Price, last 24 hours" chart with "View as table".

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

- The venue's "Overview" tab shows each instrument's status.
- The instrument's calendar, bands, fees, controls and participant access reflect what you submitted.
- The **Instrument activity** card shows the last price, the 24-hour volume, trades and range, and the price over the last 24 hours.

## Troubleshooting [#troubleshooting]

**The instrument action is unavailable**

Each state allows a different set of controls, and the instrument you are looking at may not offer the one you
expected. A pending instrument offers only delisting. Nothing else is available until its listing ceremony completes
on its own. A live instrument offers halt, suspend and delist. A halted instrument offers resume, suspend and delist.
A suspended instrument offers resume and delist. A delisted instrument offers no controls. The controls sit in the
**Manage instrument** menu on the instrument detail. The menu is missing when you are neither an organisation owner
nor a platform administrator, or when none of your wallets holds the venue operator role. It is disabled, with the
reason in its tooltip, when the venue operator role sits on another of your wallets. If the menu is enabled but the
submission is refused, that is the server's role check, described in the [error
catalogue](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference).

**An instrument is halted**

Open the instrument detail and read the latest operator reason before you resume trading. A halt blocks new orders and
matching, but every resting order and locked balance from before the halt is untouched, and a submitted settlement
batch keeps its own execution outcome. Day and Good till date orders still expire on schedule while it is halted, so
check the order activity before you resume. To resume, open "Manage instrument" and select **Resume trading**, enter a
reason and confirm. With the "Trading venues" row on, a second operator approves.

**A fee schedule or price band change did not do what you expected**

A fee schedule increase cancels no resting order. When an affected order matches, the venue contract refuses to settle
the fill at a fee above the order's signed cap, and the fill waits on the **Held fills** tab for an operator to retry
or bust it. Before you apply it, the screen tells you the number of resting orders that carry a signed fee cap below
the new schedule, or says the venue has not reported the count when it cannot compute it. Tightening a price band
behaves differently: saving a tighter policy closes every resting order outside the new range as "Rejected" and
unlocks its locked balance, as [Change the price bands](#change-the-price-bands) describes. If an operator also runs
"Prune out-of-band orders", the orders it removes end as "Cancelled" and their locked balances unlock.

**An operator calendar override had no effect**

The overrides prefill a dated exception for today in the calendar editor. If you selected "Delay open", "Extend
trading" or "Close early" and then navigated away, nothing was saved, so open the calendar again and select **Save
calendar** after the override. On a day with no session, because the weekday is disabled in the template or a holiday
already suppresses today, the override buttons are disabled and the panel says today has no session to override: there
is no open to delay, no close to extend, and no session to end early. Overrides never touch tomorrow's schedule or the
weekly template.

## Frequently asked questions [#frequently-asked-questions]

### Can a delisted instrument be reopened?

No. Reopening trading means listing a new instrument through the wizard rather than reactivating the old one, and that new instrument starts its own listing ceremony, with a fresh feed writer registration and fee-account eligibility.

### Do I need a second operator to halt, suspend or delist an instrument?

Only while the venue's **Trading venues** row under "Approvals" is on. That row covers halting, suspending, resuming and delisting an instrument, and every other venue configuration change that [Desk administration](https://docs.settlemint.com/docs/console/asset-lifecycle/venues/desk-administration#which-changes-need-a-second-operator) lists. With the row on, a halt can skip the second person only as an [emergency halt](#halt-suspend-resume-or-delist) through the Platform API.

### How is the market-order protection band different from the static and dynamic bands?

The [static or dynamic policy](#change-the-price-bands) sets the allowed limit prices and bounds all fills, including market orders and auction clearing prices. The market-order protection band is a separate limit fixed at listing. It bounds how far a market order may walk the book, and the order is signed at that protection edge. A price inside that protection limit must still satisfy the effective price band.

## API routes [#api-routes]

The instrument controls call the trading venue routes in the [v2 API reference](https://docs.settlemint.com/docs/api-reference/v2). The calendar reads are `GET /api/v2/addons/trading-venues/{venueAddress}/markets/{marketId}/calendar/effective-closures` and `GET /api/v2/addons/trading-venues/{venueAddress}/markets/{marketId}/calendar/trading-days`. Instrument groups are defined with `PUT /api/v2/addons/trading-venues/{venueAddress}/instrument-groups/{code}`, and an emergency halt uses `PUT /api/v2/addons/trading-venues/{venueAddress}/maker-checker`.


# Legal holds

Source: https://docs.settlemint.com/docs/console/asset-lifecycle/venues/legal-holds
Place a legal hold that keeps a venue's records out of the retention run, and request, review or reject its release.

A legal hold keeps the venue's records out of the monthly retention run until the hold is released. The **Legal holds** tab lists every hold with its scope, reason, who placed it and its status. [Venue retention](https://docs.settlemint.com/docs/concepts/issuing-and-markets/venue-retention#legal-holds) explains the run and the archive.

![The venue's Legal holds tab with the Place hold button and the Scope, Reason, Placed by and Status columns](https://docs.settlemint.com/docs/screenshots/console-venue-legal-holds.light.en.webp)

[Screenshot] The "Legal holds" table with "Scope", "Reason", "Placed by", "Status" and "Actions" columns, and the "Place hold" button above it.

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

- **The Owner or Platform admin role.** Only an Owner or a Platform admin can place or release a hold, from a wallet that holds the Venue operator or Venue admin role on this venue.
- **The Reporting approval row.** Releasing a hold follows the "Reporting" row under "Approvals" on [General](https://docs.settlemint.com/docs/console/organisation-settings/general#approvals), as [Release a hold](#release-a-hold) describes.

## Steps [#steps]

### Place a hold [#place-a-hold]

1. Select **Place hold**.
2. Set an **Instrument**, a "Participant (optional)" by wallet address, or a "Held from (optional)" and "Held until (optional)" window to narrow the hold, or leave them empty to cover the entire venue. An instrument you set must be one the venue lists. The end of the window is exclusive, and the start must be before the end. A record is held only when it matches every bound you set, so a narrow scope leaves other records open to the next retention run.
3. Enter a **Reason**.
4. Select **Place hold** in the sheet. The new hold appears with the status "Active" and a scope such as "Entire venue" or "Instrument: EUROC / AEDT".

## Release a hold [#release-a-hold]

Select **Request release** on an active hold and give a reason. What happens next follows the "Reporting" row under "Approvals" on the "General" page of "Organisation settings".

While the row reads "Second person required", the hold's status becomes "Release requested". A different Owner or Platform admin selects "Review release" and then **Approve release** or "Reject request". A rejection clears the request and the hold stays active. If the person who requested the release approves it, the sheet shows the refusal and the hold does not change.

While the row reads **Not required**, one person releases the hold alone and at once. The hold's row reads "Released", and the hold's detail names the approval policy as the releaser: "Approval policy, no second person required". Keep the row on "Second person required" while the venue is under a regulatory or litigation hold.

A platform administrator who has signed in as another user cannot place a hold or request or review a release, whatever the **Reporting** row says, because a legal hold must come from their own session.

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

- The hold appears in the table with the status **Active** and the scope you set.
- After a release, its row reads "Released", and its detail shows "Release requested by", "Release reason" and "Released by".
- Records outside every active hold follow the retention period again at the next monthly run.

## Troubleshooting [#troubleshooting]

**Place hold or Request release is disabled**

  Only an Owner or a Platform admin can place or release a hold, from a wallet that holds the Venue operator or Venue
  admin role on this venue. Anyone else sees **Place hold** disabled with "Only an organisation owner or a platform
  administrator can place or release a legal hold.", and each row's release button disabled with "Owner or
  administrator only".

A platform administrator signed in as another user sees "Place hold" disabled with "You are acting as another user, so
you cannot place a hold or request or review a release. That person must sign in and do it themselves.", and **Request
release** and "Review release" disabled with "Not while acting as another user". The API refuses all three too, so sign
in as yourself to act.

**The hold does not release**

While the "Reporting" row under "Approvals" reads "Second person required", a different person has to approve the
release. The person who requested it cannot approve it. Ask another Owner or Platform admin to select **Review
release**.



# Listing rules

Source: https://docs.settlemint.com/docs/console/asset-lifecycle/venues/listing-rules
Set the defaults every instrument inherits, the admission minimums for private listings, the retention period and the blocked countries of residence.

The **Listing rules** tab holds the rules the venue checks each time an instrument is listed, the defaults that each instrument uses unless it sets its own, the countries whose residents cannot trade here, and how long the venue keeps its records. Only a wallet with the Venue admin role can change them.

![The top of the venue's Listing rules tab: Instrument defaults, Listing rules, Admission minimums for private listings and Resuming a halted instrument](https://docs.settlemint.com/docs/screenshots/console-venue-listing-rules.light.en.webp)

[Screenshot] The top of the "Listing rules" tab, from "Instrument defaults" to "Resuming a halted instrument".

The tab opens with "Instrument defaults", then "Listing rules" and its "One trading model per security" switch, then "Admission minimums for private listings" and "Resuming a halted instrument". "Blocked countries of residence", "Data retention" and the "Save the listing rules" button follow further down the tab.

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

- **The Venue admin role.** Changing the listing rules needs the "Venue admin" role on one of your wallets. Without it the page reads "Only a venue admin can change the listing rules."
- **A second venue admin, when the venue asks for one.** While the "Trading venues" row under "Approvals" on [General](https://docs.settlemint.com/docs/console/organisation-settings/general#approvals) is on, another venue admin approves the change, as [Save the listing rules](#save-the-listing-rules) describes.

## Steps [#steps]

### Change the rules [#change-the-rules]

Change the sections the venue needs, each described below: the one trading model rule, the admission minimums, the resume cut-off, the instrument defaults, the order rule limits, the starting values for new instruments, the blocked countries of residence, the announcement pop-up and the data retention.

### Save the listing rules [#save-the-listing-rules]

On a venue that requires maker-checker, **Save the listing rules** proposes the change and does not apply it. The page says "Sent for approval. Another venue admin must approve it." and the stored rules stay as they are until another venue admin approves it. Review the proposal under "Venue configuration approvals" on [Desk administration](https://docs.settlemint.com/docs/console/asset-lifecycle/venues/desk-administration). While one change to the listing rules waits for a decision, a second save is refused with "A listing-rules change is already waiting for a second venue admin. Approve or reject it under Venue configuration approvals before you save another." Decide the open change or let it expire, then save again. The venue price band on the same page and "Edit price bands" on an instrument's Risk controls tile behave the same way: a held save keeps the sheet open with "Your change is held for approval", and a second save while a change is open names that open change as the cause. Save stays off while nothing differs from the stored setting.

## Limit a security to one trading model [#limit-a-security-to-one-trading-model]

The **One trading model per security** switch decides what the venue accepts: when on, a security listed for auction cannot also get a continuous instrument, and the reverse. Existing instruments stay listed, so a security can keep both an auction and a continuous instrument that were listed before the switch.

## Set the admission minimums for private listings [#set-the-admission-minimums-for-private-listings]

Set **Minimum value made available (USD)** and "Minimum shares made available". The venue refuses a private listing below either minimum, and the listing wizard asks for both values. Each minimum is a whole number no larger than 9,223,372,036,854,775,807, and the page and the API refuse a larger one and store nothing. Leave a field empty for the platform default, or enter 0 for no minimum. Pending listings are checked again before they go live, and a live instrument below a raised minimum stays listed.

## Set a resume cut-off [#set-a-resume-cut-off]

Under "Resuming a halted instrument", a halted or suspended instrument cannot resume within the number of minutes you enter in **Resume cut-off before close (minutes)** before the session close. Leave it empty for no cut-off.

## Set the instrument defaults [#set-the-instrument-defaults]

The "Instrument defaults" section holds the values that instruments inherit and links to "Trading calendar: hours and closed days". Set the **Venue price band** there. Its default is "Off". "Static" takes a minimum and maximum quote price. Both must fit every inheriting instrument's tick size exactly. An incompatible instrument prevents the change. "Dynamic" takes an initial percentage, an expansion step, and a maximum threshold.

## Limit the order types and time in force [#limit-the-order-types-and-time-in-force]

"Order rule limits" is a ceiling for every instrument on the venue. **Order types allowed on the venue** and "Time in force allowed on the venue" list the options an instrument may accept, and an instrument accepts the options it sets itself that are also ticked here. The ceiling applies to instruments already listed and to new ones. Tick everything for "No limit".

Orders already resting on the book stay and run their course. The limit applies to orders placed after the save. An instrument's own order rules are not rewritten, so ticking an option again restores it for instruments that still list it. A limit can narrow a private listing like any other.

A limit that would leave a listed instrument with no order type, or no time in force, is refused with "A listed instrument would be left with no order type or no time in force. Change that instrument's order rules first, or keep more of the options ticked." (DALP-14017). A listing that states an option outside the limit is refused the same way.

## Set the starting values for new instruments [#set-the-starting-values-for-new-instruments]

The "Starting values for new instruments" section holds five fields:

- **Default maker fee**
- **Default taker fee**
- **Default fee account**
- **Default market-order protection band**
- **Default holding period**

Fees and the protection band are in basis points, and the holding period is in seconds, within the ranges the listing wizard accepts. Leave a field empty for no starting value.

The listing wizard opens with these values filled in, and the person listing can change each one. A starting value is copied once, when the wizard opens. After the instrument is listed it keeps its own value, and a later change here leaves listed instruments alone.

## Block countries of residence [#block-countries-of-residence]

A participant whose residence claim is in a country under **Blocked countries of residence** cannot place orders on any instrument of the venue, and an instrument's own restricted countries add to the list. A participant's residence is the `residence` claim DALP issues from the country on their approved KYC profile. While either list is set, an order from a participant with no residence claim is refused. The refusal names the country, for example "Participants resident in US cannot trade this instrument."

## Show an announcement pop-up [#show-an-announcement-pop-up]

With **Flash new announcements on the trading screen** on, participants watching an instrument get a pop-up when an announcement for it or for the venue is published. The banner shows every announcement either way.

**Flash announcements from this severity** chooses "Info and above", "Warning and above" or "Critical only".

## Set the data retention [#set-the-data-retention]

"Data retention" on the "Listing rules" page sets how many years the venue keeps its orders, order events and trades. Leave **Retention period (years)** empty and the monthly run deletes nothing, or enter a whole number from 1 to 100. A new period warns that older records are copied to the venue archive and then deleted, and "Save retention period" stays off until you select "Preview", which shows what the next monthly run would remove. On a venue that requires maker-checker, the save reads "Your change is held for approval. The retention period stays as it is until another venue admin approves it." [Venue retention](https://docs.settlemint.com/docs/concepts/issuing-and-markets/venue-retention) explains the run and the archive, and a [legal hold](https://docs.settlemint.com/docs/console/asset-lifecycle/venues/legal-holds) keeps records out of it.

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

- Reopen **Listing rules** and check that each section reads as you saved it.
- On a venue whose row is on, the change shows under "Venue configuration approvals" on [Desk administration](https://docs.settlemint.com/docs/console/asset-lifecycle/venues/desk-administration) until another venue admin approves it.

## Troubleshooting [#troubleshooting]

**My listing-rules change does not apply**

A venue that requires maker-checker holds the change until another venue admin decides it under **Venue configuration
approvals** on [Desk administration](https://docs.settlemint.com/docs/console/asset-lifecycle/venues/desk-administration). While one change
waits, a second save is refused. Decide the open change or let it expire, then save again.

## API routes [#api-routes]

The tab reads and writes the venue's listing rules through the trading venue routes in the [v2 API reference](https://docs.settlemint.com/docs/api-reference/v2). The order rule limits and the starting values are the `orderRuleLimits` and `marketDefaults` groups of the same listing rules.


# Mass cancellations

Source: https://docs.settlemint.com/docs/console/asset-lifecycle/venues/mass-cancellations
Decide a proposed mass cancel as a second operator and download the orders each cancellation batch cancelled.

The **Mass cancellations** tab lists each operator action that cancelled at least one order on the venue's order book, and it is where a second venue operator decides a proposed mass cancel. A venue operator proposes the cancel from [Orders](https://docs.settlemint.com/docs/console/asset-lifecycle/venues/orders). Each batch keeps the reason and the orders it cancelled, so the venue can show a participant why their orders went for as long as it keeps the records, a period [venue retention](https://docs.settlemint.com/docs/concepts/issuing-and-markets/venue-retention) sets.

![The venue's Mass cancellations tab with Mass cancel approvals and Cancellation batches, both empty before any mass cancel](https://docs.settlemint.com/docs/screenshots/console-venue-mass-cancellations.light.en.webp)

[Screenshot] The "Mass cancel approvals" and "Cancellation batches" sections, both empty before any mass cancel.

"Mass cancel approvals" reads "No mass cancels proposed" and "A proposal appears here for a second operator to decide.", and "Cancellation batches" reads "No operator action has cancelled orders on this venue yet". Both offer "Cancel orders from the Orders tab". After the first cancellation, the batches table shows "When", "Action", "Applies to", "Reason", "Orders", "By" and "Cancelled orders", with a "Download" menu on each batch.

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

- **The Venue operator role on the venue.** Deciding a proposed cancel is a venue operator's task.
- **The Trading venues approval row.** Whether a second venue operator must approve a mass cancel follows the "Trading venues" row under "Approvals" on [General](https://docs.settlemint.com/docs/console/organisation-settings/general#approvals), and an exception there can turn it on or off for one venue. While the row is off, one operator proposes and runs the cancel alone.

## Steps [#steps]

### Decide a proposed cancel [#decide-a-proposed-cancel]

On a venue whose row is on, a second venue operator opens this tab, selects **Approve** or "Reject" on the proposed row and confirms with their wallet verification. The operator who proposed the cancel sees no buttons, because the same user cannot decide their own proposal. The row says another venue operator must decide.

A proposal stays open for 24 hours by default, and the "Expires" column and the row details show when it lapses. Once that time has passed, the proposal shows "Expired", offers no "Approve" or "Reject", and the server refuses a decision that arrives late. A cancel that is still needed is proposed again.

The approval applies the filter again when it is decided, so it cancels every open order that matches at that moment, including orders placed after the proposal. The count can differ from the one shown when the cancel was proposed.

The row shows how the cancel ended: waiting for a second operator, cancelling, cancelled with the number of orders out of those expected, rejected, stopped, or failed. Each approved cancel also leaves a batch in the **Cancellation batches** table.

## Download a cancellation batch [#download-a-cancellation-batch]

Select the **Download** menu on a batch and choose "Cancelled orders as CSV" or "Cancelled orders as XLSX". The file lists the batch's orders: order id, maker, instrument, side, price, quantity still open, validity, placed time, cancelled time and reason. An XLSX file holds at most 1,048,575 orders, so download a larger batch as CSV.

## Which actions record a batch [#which-actions-record-a-batch]

Suspending or delisting an instrument, blocking a participant and removing a wallet from a private instrument each cancel many orders at once, and so does an approved mass cancel. Cancelling all of a participant's orders is a mass cancel limited to that participant's wallet, and optionally to one instrument. It waits for a second operator while the venue's **Trading venues** row is on and runs at once while the row is off. Blocking a participant needs no second operator, even while the row is on. Each of these actions is recorded as one batch when it cancels at least one order. A mass cancel records one batch for each instrument it touched.

A reserved order is one that holds the participant's balance but has not reached the order book. A mass cancel also withdraws the matching reserved orders, and a withdrawn order is in no batch. A reserved order records its maker, its instrument and the token it holds, but not its order type or validity. So a side filter matches a reserved order by the token it holds, and a filter that names an order type or a validity withdraws no reserved order.

Every order the action cancelled carries the batch and the reason: your reason for a suspension, delisting, cancel-all, block or mass cancel, and "The wallet was removed from the private instrument" for a removal. The participant sees that reason on the order.

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

- The batch appears in the table with its action, the instrument or wallet it applied to, the reason, the number of orders and who ran it.
- Download the batch and check that the orders match what you expected to cancel.

## Troubleshooting [#troubleshooting]

**I see no Approve or Reject on a proposal**

The operator who proposed a cancel sees no buttons, because the same user cannot decide their own proposal. The row
says another venue operator must decide. Ask a different venue operator to open this tab.

**A proposal shows Expired**

Nobody decided it before its **Expires** time. An expired proposal cannot be approved or rejected and cancels nothing.
Propose the cancel again for the orders that are still open.

**A mass cancel stopped**

A run still cancelling an hour after its approval shows as stopped, and a stopped run does not resume. Propose the
cancel again for the orders that are still open.

**The XLSX download is refused**

An XLSX file holds at most 1,048,575 orders. Download a larger batch as CSV.

## API routes [#api-routes]

Integrations receive one `trading-venue.cancellation-batch.completed` webhook per batch, as the [webhook event reference](https://docs.settlemint.com/docs/api-reference/webhooks/market-events#trading-venue) describes. The tab reads batches through the trading venue routes in the [v2 API reference](https://docs.settlemint.com/docs/api-reference/v2).


# Orders

Source: https://docs.settlemint.com/docs/console/asset-lifecycle/venues/orders
Review and export every order submitted to a venue, read each order's trading member, and propose a mass cancel of the open orders.

The **Orders** tab lists every order submitted to the venue, for review and export. A venue operator also uses it to cancel the open orders that match the screen's filters, for example when an incident leaves orders that must go before the venue is safe to use again.

![The venue's Orders tab with each order's instrument, client, side, quantity, status and placed time](https://docs.settlemint.com/docs/screenshots/console-venue-orders.light.en.webp)

[Screenshot] The "Orders" table of a trading venue, with the "Filter", "Client" and "Export" controls above it.

The table has "Instrument", "Client", "Side", "Quantity", "Status" and "Placed (UTC)" columns. Each row also shows the order's type, filled quantity and validity. The "Filter", "Client" and "Export" controls sit above the table.

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

- **The Venue operator role on the venue.** Cancelling orders is a venue operator's task.
- **A second venue operator, when the venue asks for one.** The "Trading venues" row under "Approvals" on [General](https://docs.settlemint.com/docs/console/organisation-settings/general#approvals) decides whether a mass cancel needs a second venue operator. An exception there can turn it on or off for one venue. With the row on, the cancel waits for a second operator. With the row off, it runs as soon as the proposer confirms with their wallet verification. Cancelling all of one participant's orders never waits for a second person. Blocking a participant waits for one only while the "Administration" row protects the "Freezing" group. A venue operator or venue submitter wallet can also cancel any order, or all of one wallet's orders, directly on the venue contract, with no second person.

## Steps [#steps]

### Find and export orders [#find-and-export-orders]

Filter the "Orders" table by instrument, client, side, type, validity, status, reason, or date, and download the filtered rows as CSV or XLSX from the **Export** menu. When more than 1,048,575 orders match, the XLSX download is refused with that limit, so export CSV or narrow the filters. The Orders tab shows times in UTC. An order that arrives while you read raises the count on a button over the top of the table, such as "3 new", and the rows move only when you select it.

The **Quantity** and "Filled" columns show the order size in the instrument's base token, in the table and in the row details. Sorting by either column groups the orders by instrument and sorts each group by amount.

### Propose a mass cancel [#propose-a-mass-cancel]

The cancel uses the instrument, client, side, type and validity filters, and with none set it covers every open order on the venue.

1. Select **Cancel orders** below the table. The control stays disabled while the screen also filters by trading member, status, close reason or placed date, because the cancel cannot honour those filters. A line of text beside the control names the filter to clear.
2. Read the count in the sheet. It shows how many open orders match, with one row for each instrument. Orders that still hold their balance and have not reached the order book appear in their own row, so the rows add up to the total. When no open order matches, the sheet says so and you cannot propose.
3. Enter a "Reason" of 5 to 500 characters and type the venue's name in the field that reads "Type" and the venue's name "to confirm". Select **Propose cancel** and confirm with your wallet verification. The second operator sees the reason, and every cancelled order carries it to the participant.

### Hand the proposal to a second operator [#hand-the-proposal-to-a-second-operator]

On a venue whose row is on, a second venue operator decides the proposal on the [Mass cancellations](https://docs.settlemint.com/docs/console/asset-lifecycle/venues/mass-cancellations#decide-a-proposed-cancel) tab. On a venue whose row is off, the cancel runs at once and leaves a batch on **Mass cancellations** for download.

## Open an order [#open-an-order]

Select **Open order** in a row's details on the "Orders" table to read the whole order: its facts, its "History" and its "Fills". A limit order shows its "Limit price". Prices in the facts, the history and the fills read at the instrument's price step with the quote token, the same digits as the order book, for example "5.0000 EUROC". An open order with no fills says "No fills yet", and a closed one says "No fills". A fill's trade reference opens the batch that holds that trade on [Settlement instructions](https://docs.settlemint.com/docs/console/asset-lifecycle/venues/settlement-instructions#open-a-batch).

## Read an order's trading member [#read-an-orders-trading-member]

Every order on the venue has a trading member: the broker the venue operator assigned to the participant that owns the wallet, or the participant itself when it has no broker. Assign a broker on [Participant access](https://docs.settlemint.com/docs/console/asset-lifecycle/venues/participant-access#assign-a-trading-member). The "Orders" table shows the member in a **Trading member** column and in the order details, and a "Trading member" filter keeps the orders of one trading member. Once you choose a client or a trading member, the word "Client" or "Trading member" stays beside the name you chose, so the toolbar shows what each filter holds. A broker shows as the member with "via broker" beside it. The settlement instructions and the held fills name the member of the buyer and of the seller.

The platform works out the member as of the moment of the order, not as of today. Assigning, changing or clearing a broker therefore changes the member of later orders only. Every earlier order keeps the member it had when it was placed, and the **Trading member** filter follows the same rule. A trade, a held fill and a trade bust use the time of the trade, the fill and the bust. The audit log still holds each broker change with its reason. A wallet that several participants share has no member.

The platform kept only the current broker before this change, so an earlier broker is not recoverable. Orders from before a participant's current broker was assigned show the participant itself as the member.

Only venue operators see trading members. A trader or a broker never sees a trading member, another participant's name, or the counterparty's wallet or order. This holds for their orders, trades, activity and events, in the screens and in the Platform API. The settlement record on the network still names both wallets to anyone who reads it.

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

- Filter the **Orders** tab and confirm that the rows match the selected criteria, then open a row to inspect its details or export the filtered result.
- After a cancel, the proposal row on [Mass cancellations](https://docs.settlemint.com/docs/console/asset-lifecycle/venues/mass-cancellations) shows how it ended.

## Troubleshooting [#troubleshooting]

**Cancel orders is disabled**

Clear the trading member, status, close reason or placed date filter that the control names. When no open order
matches the other filters, the sheet says so and you cannot propose.

## API routes [#api-routes]

The tab reads orders through the trading venue routes in the [v2 API reference](https://docs.settlemint.com/docs/api-reference/v2).


# Participant access

Source: https://docs.settlemint.com/docs/console/asset-lifecycle/venues/participant-access
See everything that decides whether one wallet can trade on a venue, and change the broker and the access on a private instrument.

The **Participant access** page shows why one wallet can or cannot trade on a venue. It gathers the venue's admission policy, a block, the verifications the wallet's identity holds, freezes on the listed securities, private-instrument participant lists, the access profile of each instrument, and desk limits. Instrument status, the trading calendar and the token's compliance rules can still refuse an order and are not on this page.

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

- **The Venue operator or Venue admin role.** Only a holder of the venue operator or venue admin role on this venue can open the page. Anyone else gets a not-found answer.
- **The Platform admin or Owner role, to change access on a private instrument.** Saving a participant's access on a private instrument needs it.
- **A wallet to look at.** The page opens for one wallet address under the venue. A wallet counts as a participant of the venue when it is a venue member, appears on an instrument's participant list, or has an active block.

## Steps [#steps]

### Open the page for a wallet [#open-the-page-for-a-wallet]

Open it from the **View venue access** link under a wallet's address in a private instrument's participant list, or from the "Holders" tab of an asset. In the holders table, the row menu of a holder shows "View access on" and the venue's name for each venue that lists the asset as an instrument's security. The page opens under the venue, with the wallet's address in the breadcrumb.

### Read the sections [#read-the-sections]

| Section | What it shows | Where you change it |
| --- | --- | --- |
| Admission | The wallet's registered identity, whether the venue admits it, whether it is a venue member, whether the venue requires membership, the venue's visibility, and the account status with any restrictions on trading, securities transfers or withdrawals | **Edit admission** opens the venue's **Permissions** tab |
| Block | Whether the venue blocks the wallet, since when, and the reason | **Manage blocks** opens the **Permissions** tab |
| Required verifications | Each verification topic the venue requires, marked **Held** or **Missing** for the wallet's identity | **Edit requirements** opens the **Permissions** tab |
| Freezes | For each security listed on the venue, whether the wallet's address is frozen and how much of its balance is frozen, in the security's own units | The security's name opens its **Holders** tab |
| Private instrument memberships | The private instruments whose participant list includes the wallet, with the wallet's classification and the time it was added | The instrument's name opens the instrument, where you edit its participants |
| Access per instrument | For every instrument of the venue, the wallet's access profile and what remains after overrides: placing orders, the watchlist, order book depth, instrument groups, and whether the instrument denies the wallet | **Edit access** opens the participant access editor for a private instrument the wallet belongs to |
| Desk limits | The approved desk limits for the wallet, the instrument each applies to or all instruments for an older venue-wide limit, and the approval time | **Manage desk limits** opens **Desk administration** |

**Admitted** applies the same admission rule as order intake. A discoverable venue that requires no verification topics and no membership admits any wallet. Every other venue admits a wallet only when it has a registered identity that holds every required verification topic and, if the venue requires membership, is a venue member. When "Admitted" reads No, "Reason not admitted" says whether the wallet has no registered identity or its identity does not meet the admission requirements. The block is shown apart in its own section. A limit that is proposed and not approved does not appear under "Desk limits", because it constrains no order.

## Assign a trading member [#assign-a-trading-member]

To assign a broker, open the wallet's "Participant access" page. Its "Trading member" section names the participant, its broker and the trading member of its orders. Select **Assign broker** or "Change broker", search for the broker participant, enter a reason and confirm with your wallet. "Remove broker" makes the participant its own trading member again. A venue operator or venue admin makes the change, and it waits for a second person only while the "Administration" row under "Approvals" on [General](https://docs.settlemint.com/docs/console/organisation-settings/general#approvals) protects the "Venue administration" group. The reason goes into the audit log with the broker before and after. The change applies to orders placed from that moment on. Earlier orders keep their trading member, as [Orders](https://docs.settlemint.com/docs/console/asset-lifecycle/venues/orders#read-an-orders-trading-member) describes.

## Edit a participant's access on a private instrument [#edit-a-participants-access-on-a-private-instrument]

On a private instrument's participant list, **Edit access** opens the participant's access on that instrument. The editor holds these settings:

- **Access profile**: "Full access", "Watchlist only", or a profile the venue named.
- **Place orders**: "Follow profile", shown with the profile's value in brackets, or "Allow" or "Block".
- **See the instrument in watchlists**: "Follow profile", or "Allow" or "Block".
- **See order book depth**: "Follow profile", or "Allow" or "Block".
- **Instrument groups**: follows the profile, or "Only the groups I choose" with at least one group, or "All instrument groups".

Enter a "Reason for the change", select **Save access** and verify your wallet.

Saving replaces the whole access, so a setting you leave on "Follow profile" drops any earlier override.

Only a platform administrator or the organisation owner can save. A wallet barred from the instrument shows every setting off until the bar is lifted. An order on an instrument whose group the wallet may not trade is refused with "This account may not trade the instrument group of this instrument."

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

- Reopen the page for the wallet and check that the section you changed now reads as intended.
- **Admitted** reads Yes only when the wallet passes the venue's admission rules, and "Access per instrument" shows what remains after the access profile and any overrides.

## Troubleshooting [#troubleshooting]

**The page says the wallet is not a participant**

A wallet counts as a participant of the venue when it is a venue member, appears on an instrument's participant list,
or has an active block. For any other wallet the page reads "This wallet is not a participant of this venue" and
offers **Open permissions**, the tab where the wallet is admitted.

**The page says not found**

Opening the page needs the Venue operator or Venue admin role on this venue. Ask a venue admin to grant it on
[Permissions](https://docs.settlemint.com/docs/console/asset-lifecycle/venues/permissions).

## API routes [#api-routes]

| Task | Route |
| --- | --- |
| Read one wallet's access to the venue | `GET /api/v2/addons/trading-venues/{venueAddress}/participants/{walletAddress}/access` |
| Read or replace access on a private instrument | `GET /api/v2/addons/trading-venues/{venueAddress}/markets/{marketId}/participants/{walletAddress}/access` and `PUT /api/v2/addons/trading-venues/{venueAddress}/markets/{marketId}/participants/{walletAddress}/access` |

The first route answers a non-participant with a 404 and the code `TRADING_VENUE_PARTICIPANT_NOT_FOUND`. The request and response fields are in the [v2 API reference](https://docs.settlemint.com/docs/api-reference/v2).


# Participant alerts

Source: https://docs.settlemint.com/docs/console/asset-lifecycle/venues/participant-alerts
Choose which kinds of alert reach every venue's participants by email when they have made no choice of their own.

The **Participant alerts** tab sets which email alerts a participant gets until they choose their own under "Notifications" in the Investor portal. The defaults belong to the organisation and cover the participants of every venue, so a change made here reaches all of them.

![The Participant alerts tab with the Email switch for each alert kind](https://docs.settlemint.com/docs/screenshots/console-venue-participant-alerts.light.en.webp)

[Screenshot] The "Participant alerts" tab with the alert kinds "Order filled", "Other order changes", "Price alerts", "Announcements" and "Corporate actions", each with an "Email" switch.

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

- **A wallet that operates a venue.** The "Participant alerts" tab appears next to the venue list only when one of your wallets operates a venue. An operator of any venue in the organisation can read the defaults.
- **Organisation owner or platform admin.** Only an organisation owner or a platform admin can change the defaults, because they cover the participants of every venue. For anyone else the switches are disabled and a note says so.
- **Your wallet verification.** Saving the defaults asks for it, like other venue changes.

## Steps [#steps]

### Switch the alert kinds [#switch-the-alert-kinds]

Open "Asset lifecycle", then "Venues", and select **Participant alerts**.

Turn each kind's "Email" switch on or off, then select **Save alert defaults** and confirm with your wallet verification. The switches change together, so one save applies every change you made. A kind left off sends no email unless a participant switches it on under "Notifications" in the Investor portal. Participants who have never set their own alerts follow these defaults.

Without an Investor portal URL, the platform sends no alert email, even when an organisation default enables it, because the recipient has no alert settings page to stop these emails. The delivery is not retried, and the alert stays in the participant's notification list on the Console.

## Alert kinds [#alert-kinds]

Each kind sends an email when:

- **Order filled**: an order fills or partly fills.
- **Other order changes**: an order expires, is cancelled by the venue, is rejected or is refused at entry.
- **Price alerts**: a price alert that the participant set triggers.
- **Announcements**: a venue publishes an announcement for an instrument the participant can see. With this kind off, a participant gets no email even for a Critical notice, but still sees it in the trading desk banner and their notification list, as [Announcements](https://docs.settlemint.com/docs/console/asset-lifecycle/venues/announcements) describes.
- **Corporate actions**: a corporate action is announced for an instrument the participant can see.

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

- Reopen **Participant alerts** and check that each "Email" switch reads as you set it.


# Permissions

Source: https://docs.settlemint.com/docs/console/asset-lifecycle/venues/permissions
Set the venue's admission policy, admit and revoke identities, grant venue roles, and block a participant wallet.

The **Permissions** tab decides who may discover and trade on the venue, who runs it, and who is blocked. Roles here apply to this venue only. Admission, venue roles, participant depth and participant blocks each have their own card.

![The venue's Permissions tab with the Venue admin and Venue operator roles, each with Grant role and its current holders](https://docs.settlemint.com/docs/screenshots/console-venue-permissions.light.en.webp)

[Screenshot] The venue's "Permissions" tab with the cards of the venue roles.

The tab reads "Roles here apply to this venue only." Each venue role, such as "Venue admin" and "Venue operator", has an address field, the "Grant role" button and a "Current holders" table. The "Admission" card with "Admission policy" and "Admitted identities" follows further down the tab.

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

- **The Venue admin role, to change admission.** Changing admission needs the "Venue admin" role on one of your wallets. A venue operator can read the admitted identities and cannot change them.
- **A reason for each change.** Every policy save, admission and revocation needs a "Reason for the change", which the audit trail records.

## Steps [#steps]

### Set the admission policy [#set-the-admission-policy]

Under "Admission policy", fill in the fields below, then select **Save policy** and verify your wallet.

- **Required verification topics**: decimal topic IDs separated by commas or spaces.
- **Require membership**: switch it on so that only admitted identities may trade.
- **Admitted identities only**: switch it on to hide the venue from identities that are not admitted.

While the venue's "Trading venues" row is on, or the "Administration" row protects the "Venue administration" group, the change waits for a different venue admin on [Desk administration](https://docs.settlemint.com/docs/console/asset-lifecycle/venues/desk-administration#approve-or-reject-a-venue-configuration-change).

With **Admitted identities only** on, an order from an identity the venue does not admit is answered "No such instrument on this venue", the same answer as for an instrument that does not exist. The venue's instruments, public ones included, also stay out of the market list for a caller none of whose wallets the venue admits, and opening one by its address answers that the instrument does not exist. The platform operator and the venue's own operators still see them. With it off, the venue stays visible to everyone and the refusal names the cause: the wallet holds no registered identity the venue admits, or its identity does not meet the admission policy. [Participant access](https://docs.settlemint.com/docs/console/asset-lifecycle/venues/participant-access) shows the result for one wallet.

### Admit and revoke identities [#admit-and-revoke-identities]

The "Admitted identities" list shows each member and the date it was admitted, and you can search it by identity address. Enter up to 100 identity addresses in "Admit identities" and select **Admit**.

To remove a member, enter the "Reason for the change", open the row's actions menu and select **Revoke**. "Revoke" stays disabled until you enter a reason.

## Grant a venue role [#grant-a-venue-role]

Only a platform administrator can grant or revoke the venue admin role, and the change needs no second person. The platform submits that write as the organisation's operations signer, which holds the venue's admin authority on chain. To grant or revoke the operator or submitter role, one of your wallets must hold the venue admin role, and the change runs under your own signing wallet. Being the organisation owner does not let you change venue roles.

On the card of the role, enter the "Account address" and select **Grant role**, then confirm with your wallet verification. To end the role by itself, fill in "Remove access after", as [Can a venue role end by itself?](#can-a-venue-role-end-by-itself) describes.

- **Venue admin** grants and revokes the operator and submitter roles, and resumes a paused venue.
- **Venue operator** runs the venue: instruments, fees, price bands, halts, order cancels, bust proposals and pausing the venue. Its holder can also cancel any participant's orders and change an instrument's fees and fee account on the venue contract without a second person.
- **Venue submitter** submits settlement for the venue, and the platform's settlement accounts hold it. Its holder can also cancel any participant's orders on the venue contract without a second person, so grant it to no other wallet.

The "Current holders" table lists each holder with "Granted" and "Access ends". To take a role from a holder, open the row's actions menu, select **Revoke** and confirm with your wallet verification. When you cannot change the role, "Revoke" is disabled and says why. The row leaves the list once the change is on chain. Revoking the Venue submitter role from a settlement account stops that account's settlement until you grant the role back, and the prompt says so.

## Grant participant depth [#grant-participant-depth]

Participant depth lets a wallet see order book levels beyond the best bid and ask. Under "Participant depth entitlement", enter a valid wallet address and select **Grant depth** or "Revoke depth", then confirm with your wallet verification. Granting or revoking participant depth needs the Venue admin or Venue operator role, and waits for a second person while the "Administration" row protects the "Venue administration" group.

## Block a participant [#block-a-participant]

Under "Participant venue access", enter the "Participant wallet", a non-zero EVM address, and a "Reason" that the audit trail keeps. Select **Block participant** or "Unblock participant".

A block opens **Disable venue access**, which warns that the wallet's resting orders are cancelled, and asks for your wallet verification. Only the action that changes the wallet's current state is on. A venue operator or venue admin blocks a wallet, and the block or the unblock waits for a second person only while the "Administration" row under "Approvals" on [General](https://docs.settlemint.com/docs/console/organisation-settings/general#approvals) protects the "Freezing" group.

Once it is sent, the form clears and names the wallet with the outcome: "Blocked. This wallet can no longer trade or read market data on the venue." or "Unblocked. This wallet may trade on the venue again." A block applies to one wallet address and stops it from trading and from reading market data. Another wallet of the same identity is not blocked unless you block it too. The wallet's holdings and order history stay. Its cancelled orders appear as a batch on [Mass cancellations](https://docs.settlemint.com/docs/console/asset-lifecycle/venues/mass-cancellations). [Participant access](https://docs.settlemint.com/docs/console/asset-lifecycle/venues/participant-access) shows a wallet's block and everything else that decides its access.

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

- Reopen **Permissions** and check that the "Admission policy" reads as you saved it, that the identity shows under "Admitted identities", and that the holder shows under "Current holders" with the "Access ends" you set.

## Troubleshooting [#troubleshooting]

**Grant role and Revoke are disabled**

The buttons stay disabled for a role you cannot change, with a line that names the missing authority. Only a platform
administrator can grant or revoke the Venue admin role. Granting or revoking the other roles needs the Venue admin
role on the wallet that signs.

## Frequently asked questions [#frequently-asked-questions]

### Can a venue role end by itself?

Yes. Fill in **Remove access after** when you grant a role on the Permissions tab, or send `validUntil` with the role change through the API. The end must fall between one minute and one year from now. The platform submits the revocation at that time, and the role ends when the revocation lands on chain. The audit trail records it with the reason "grant expired".

The wallet that granted the role signs the revocation if it still holds venue admin. If not, the revocation goes to another venue admin wallet that signs this venue's time-boxed grants. If none is available, the organisation's operations signer, which can take venue admin at any time, takes it for that revocation only and gives it up in the same submission. A venue admin whose own admin role ends at a set time can grant a role only for a period that ends before their own. Granting the same role again replaces the end, and a grant without one is permanent. A queued revoke or permanent grant replaces the earlier end date only when it lands. The role list shows each holder's end under **Access ends**, or "No end date". The platform raises an operator alert on the first failed revocation, including one still pending 15 minutes after the end, and keeps retrying. Check that alert before you treat access as ended.

## API routes [#api-routes]

The tab reads and writes admission and roles through the trading venue routes in the [v2 API reference](https://docs.settlemint.com/docs/api-reference/v2).


# Settlement instructions

Source: https://docs.settlemint.com/docs/console/asset-lifecycle/venues/settlement-instructions
Read which token moves from whom to whom when a venue's trades settle, filter and export the batches, and follow a batch from pending delivery to delivered.

The **Settlement instructions** tab of a venue shows which token moves from whom to whom, and in what amount, before and after a trade settles, without a chain explorer. It is read-only. The organisation's operations signer, which holds the venue's submitter role, settles each matched trade on chain unless a fill is held or the trade is undone, and any wallet can trigger a delivery that has fallen due. An operator reads the batches that delivered and the ones that did not.

[Trading venue](https://docs.settlemint.com/docs/concepts/issuing-and-markets/trading-venue) explains how a fill becomes a delivered trade. A fill the platform could not settle waits on [Held fills](https://docs.settlemint.com/docs/console/asset-lifecycle/venues/held-fills), and a trade that must not settle is undone on [Trade busts](https://docs.settlemint.com/docs/console/asset-lifecycle/venues/trade-busts).

![The Settlement instructions tab with the Batch status selector, the filter bar and the export buttons](https://docs.settlemint.com/docs/screenshots/console-venue-settlement-instructions.light.en.webp)

[Screenshot] The "Settlement instructions" tab with its status selector, filter bar and export controls above the batch table.

The "Batch status" selector reads "All statuses". The filter bar holds "Search", "Instrument", "Participant", "Client classification", "Side", "Minimum price", "Maximum price", "Matched from" and "Matched to". Beside it sit the "Export CSV" and "Export Excel" buttons, the "Open XvP settlements" link, and "From date" and "To date" with "Export a date range", all above the batch table.

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

- **The Venue operator role on the venue.** Reading the settlement instructions needs the "Venue operator" role on the venue, the same as the trade-bust list.
- **The venue submitter role.** Settlement needs the organisation's operations signer to hold the venue submitter role. Provisioning a venue grants it, and revoking it on the venue's "Permissions" tab stops settlement for that venue until it is granted back. The Console warns about this when you revoke it.

## Steps [#steps]

### Open Settlement instructions [#open-settlement-instructions]

Open "Asset lifecycle", then "Venues", and select the venue. Select "More" in the tab row, then **Settlement instructions**.

### Read the batches [#read-the-batches]

Trades that settle in one transaction form one batch. A trade that has no settlement transaction yet is its own batch, shown as **Pending delivery**. The table names each batch by its reference, with its status, its trade count, its counterparties, the time it was "Matched", its chain id, and the buyer and seller fees in the quote token.

Each batch has one of four statuses, and the **Batch status** filter selects among them:

- "Pending delivery" means at least one trade in it still awaits delivery. It does not mean the batch is unsettled: on an instrument with a holding period, a batch that already has its settlement transaction stays in "Pending delivery" until the holding period ends and the trades deliver.
- "Delivered" means every trade delivered.
- "Undone" means every trade was undone.
- "Partly undone" means delivered and undone trades share it.

### Open a batch [#open-a-batch]

Open a batch to see each trade, named by its pair, quantity, and price, such as "EUROC / AEDT · 1 EUROC at 4.01 AEDT each", with a button that copies its trade id. The buyer and seller show by participant or contract name, with the address on hover. Each trade lists its legs: the securities, the cash, and the fee, and, where the venue collects it on chain, VAT paid to the venue's VAT recipient. Each leg names its asset by name and symbol, linked to the asset page, with the token address beneath, and its payer, payee and amount. A trade that has no settlement transaction yet shows its cash at gross value and no fee leg, because the fee is fixed when the settlement transaction lands. Once it has landed, the trade shows its fees even while the batch is still in "Pending delivery".

A fill's trade reference on an [order's page](https://docs.settlemint.com/docs/console/asset-lifecycle/venues/orders) lands here with the batch that holds the trade already open and highlighted, and the trade in view. When no batch the tab loaded holds that trade, for example because it is older than the 200 newest batches the tab loads, the tab searches for the trade id instead, and clearing **Search** brings back the whole list.

Each trade also shows its buyer fee and its seller fee next to the buyer and the seller, and the table shows the buyer fees and the seller fees of a batch in two columns, with "None" for a batch whose trades have no settlement transaction yet. The table shows every amount of a token to the longest exact fraction any of them needs on the page, so a Cash total of 3.99 beside fees of 0.02 and 0.01 reads with two decimals, and a page that holds a figure needing six decimals shows all of that token's figures with six. The fee leg is the sum of the two. In the export, a trade with no settlement transaction yet has empty fee cells. Batch totals leave out undone trades. A buyer's and a seller's **Trading member** shows beside them to a venue operator.

## Filter the batches [#filter-the-batches]

The filter bar narrows the trades in the list:

- **Participant** takes a wallet address and keeps trades where that wallet is the buyer or the seller.
- **Client classification** takes a class, Retail, Institutional or Proprietary, and keeps trades where a party has that class. The class is the one stored on the party's order when the venue accepted it, so a later change to the participant's class does not move an old trade, and a party with no class never matches.
- **Side** becomes available once you set a participant or a client classification: choose "Buy" or "Sell" to test only the buyer or only the seller. With both a participant and a class, the same party must match both.

The bar also filters by "Instrument", "Search", "Minimum price", "Maximum price", "Matched from" and "Matched to". A batch that matches lists only its matching trades. "Matched from" and "Matched to" refuse a typed day that does not exist, such as `2026-02-30`, and show a message under that field. Until you correct or clear the refused date, the list stays filtered by the last date that field accepted, or by none.

The tab loads the newest 200 batches and says when the venue has more. Filter by batch status to reach the rest.

## Export the batches [#export-the-batches]

**Export CSV** and "Export Excel" download the trades that match the current filters, up to 100,000 rows, not only the batches on screen. Narrow the filters when more match. While "Matched from" or "Matched to" holds a refused date, both buttons stay unavailable.

**Export a date range** downloads every batch between "From date" and "To date" as JSON, which is the form that carries the legs and the fees of each batch. The range follows the status filter and has no upper bound on batches, and it stops with a message instead of returning a list that could repeat or miss a batch when the batches change mid-export. Leave a date empty for no limit on that side. "From date" and "To date" count whole days in your browser's time zone, while "Matched from" and "Matched to" count whole UTC days. "From date" and "To date" refuse a "From date" after the "To date" or a typed day that does not exist, such as `2026-02-30`, and show a message under that field. "Export a date range" stays unavailable until you correct or clear that date.

## Follow a batch to delivery [#follow-a-batch-to-delivery]

Settling a trade is a chain transaction. The instrument's holding period, the delay between match and delivery, decides when that transaction runs. A holding period of zero delivers both legs and the fee inside the fill's own transaction, so an instrument with no window settles the moment it matches. A holding period greater than zero reports and prices the trade at the fill, keeps both legs and the fee locked in the venue's escrow, and delivers when the trade is due. Only a due delivery reaches the chain after the fill. Any address can trigger a due delivery even while the platform is down, and a fill that has not reached the chain still needs the platform.

A token's own transfer rules can refuse a delivery. Each leg runs the token's own transfer compliance path. A token that rejects the transfer inside the fill's own transaction fails that fill and returns the commitments to the resting orders, so no trade is left half settled. A due delivery undoes the trade without an operator decision, with both legs returned to their owners' free escrow balances, only for an outside cause: a paused token, a trade lock a custodian shrank, a frozen sending side, or a receiver added to the compliance bypass list during the holding period. Any other refusal parks that leg. The venue pays the legs it can and books the refused leg to its receiver's free escrow balance, and the batch shows "Delivered". The receiver withdraws the parked units once the token's rules accept its wallet again. An escrowed leg never lapses while it waits, though a holder of the token's custodian role can still move it out of the escrow with a forced transfer.

A stop order that has fired fills from the reservation it took when the trader placed it, so its fills settle like any other order's.

You do not start a settlement. You read it on **Settlement instructions**, where the batch status moves from "Pending delivery" to "Delivered" or "Undone", and the platform sends a settled-trade webhook for the delivery, which distinguishes a delivered trade from one still awaiting delivery. [Settlement reports](#settlement-reports) lists the records that keep them.

The participant's side of the same settlement is the trade blotter, the **Your trades** tab on the trading desk, read through `GET /api/v2/addons/trading-venues/{venueAddress}/blotter`. Each row is one side of one trade with its price, quantity, quote-token value, fee, status and undo reason, so a participant who asks whether a trade settled reads the same status you see on the batch. The blotter answers one page of fills at a time, newest first, and its `status` filter narrows it to the fills still pending delivery. The blotter lists only the trades of the caller's own wallets: a settling desk that does not trade reads every trade on "Settlement instructions" and the bust console instead.

## Close the day on Custody reconciliation [#close-the-day-on-custody-reconciliation]

The close is a reconciliation of one closed day, and it is the record that says what settled and what did not. It lives on **Reconciliation** under "Custody" in "Organisation settings", not on this tab, as [Custody reconciliation](https://docs.settlemint.com/docs/console/organisation-settings/custody-reconciliation) covers every column, refusal code and retry, and its "Download CSV" writes the day as a file with a trades section and a funds section. Closing the day needs the organisation's Owner role or Platform admin access.

## Settle off the order book [#settle-off-the-order-book]

A delivery versus payment that does not come from this venue is an XvP settlement. The tab links to it as **Open XvP settlements** when that add-on is deployed. A venue batch is proven by its settlement transaction and the trades it carries. An XvP settlement is proven by its resulting Settlement Verdict and its execution. Read [XvP settlement](https://docs.settlemint.com/docs/console/my-assets/settlements) for creating, approving, executing and cancelling one.

## How a trade settles [#how-a-trade-settles]

[Figure] A settlement day: fills settle in batches, a refused fill waits for an operator, and the day closes with an attestation and reports. A fill matched on an instrument settles as part of a batch, in one transaction, either inside the fill or after the instrument's holding period. A fill the platform cannot complete sits in the held list until an operator retries it or proposes a bust, and a second operator decides that bust while the venue's Trading venues row under Approvals is on. The day then closes with a reconciliation of the closed day, which the operator signs and, while the Custody operations row under Approvals is on, a second user attests from the report. The reports then read what the earlier stages recorded: matched trades, the trade journal, daily statistics, and every settlement leg with its fail. Labels: Settlement day; Fill matched; both legs locked in escrow; Batch settles; atomic, or when due; Day closes; reconciliation and attestation; Held fill; not retried on its own; Retry or bust; an operator decides; reports read what these stages recorded.

The held list is the one queue that needs a decision, and it feeds the day's close.

## Settlement reports [#settlement-reports]

The platform generates each report from the ledger it indexed, not from a second system's copy.

| What the reader needs | Report | What it holds |
| --- | --- | --- |
| Every trade and where its settlement stands | `venue-matched-trades` | Trade id, instrument, buyer, seller, both order ids, price, quantity, executed time, settlement status |
| The trade ledger with its outcome and its fee | `trade-journal` | Trade and instrument, both parties, price, quantity, both fees, status, undo reason, executed time |
| The day as the instrument closed it | `venue-daily-statistics` | Session date, open, high, low, official close, close methodology, volume, value, trades, orders and busts |
| Each settlement leg and its fail | `settlement-and-fails` | One row per venue trade leg and per XvP leg: settlement, token, outcome, attempts, intended and actual date, days late, amount, denomination, source, fail reason, settlement transaction |
| How long each difference has been open | `break-ageing` | Each break with its cause, owner and status, in the 0 to 1, 2 to 5, 6 to 10 and more than 10 business day buckets |
| The on-chain movement behind each delivered leg | `transfer-journal` | Block and log position, transaction hash, token, sender, recipient, amount, venue trade id and leg |
| A feed a surveillance provider can ingest | FIX drop copy | Each order, fill, cancel, expiry and bust as an execution report, an undone trade as a Trade Cancel report with its reason |

In `settlement-and-fails` a venue trade has two rows, its delivery leg in the instrument and its payment leg in the cash asset, and its settlement id is the trade id. The outcome reads settled once the settlement transaction is indexed, cancelled after a bust, failed when the trade was refused or its reservation was removed, with the fail reason naming which, and pending while delivery is still due. The intended date of a venue leg is the time the trade executed, so days late measures how long delivery took.

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

- Filter the batches to **Pending delivery** and check that every batch is waiting for a due time, not for a decision.
- Filter [Held fills](https://docs.settlemint.com/docs/console/asset-lifecycle/venues/held-fills) to the instrument you worked and check that a fill you retried has left the list.
- Open the bust you proposed on [Trade busts](https://docs.settlemint.com/docs/console/asset-lifecycle/venues/trade-busts) and check that the trade reads "Undone" on its batch, with the reason on the trade journal row.

## Troubleshooting [#troubleshooting]

**A batch stays on Pending delivery past its due time**

A held fill in that batch needs a decision, an open bust proposal flagged the trade, or the chain has not answered
yet. Open the held fills and the trade busts and check for the trades in the batch. A batch whose legs are locked and
whose fill is neither parked nor flagged delivers when the due delivery runs. Any address may call the venue
contract's due delivery directly, or wait for the platform's own run. A venue operator wallet can clear a flag on the
venue contract directly, so check the trade busts before you assume a flag still holds.

**The tab shows only the newest batches**

The tab loads the newest 200 batches and says "Showing 200 of N batches, and the table export holds only these." when
the venue has more. Filter by **Batch status**, or use "Export CSV", "Export Excel" or "Export a date range", which
read past the first 200.

## API routes [#api-routes]

| Task | Route |
| --- | --- |
| List the venue's settlement batches | `GET /api/v2/addons/trading-venues/{venueAddress}/settlement-instructions` |
| Export the matching trades | `GET /api/v2/addons/trading-venues/{venueAddress}/settlement-instructions/export` |

The request and response fields are in [the v2 API reference](https://docs.settlemint.com/docs/api-reference/v2).


# Trade busts

Source: https://docs.settlemint.com/docs/console/asset-lifecycle/venues/trade-busts
Propose undoing a trade that must not stand, have a second operator approve it, and follow the reversal before or after delivery.

A bust undoes a trade that a venue operator decides should not stand. The buyer and the seller are not asked, so keep the evidence for the decision in the reason. The **Trade busts** tab lists the trades eligible for a bust and the bust proposals on them. One venue operator proposes the bust within 24 hours of the trade, with a reason. While the "Trading venues" row under "Approvals" is on, a different venue operator approves or rejects it, and the user who proposed a bust cannot decide it, whichever wallet they sign with. While the row is off, one operator alone proposes and executes the bust of an undelivered trade. A bust of a delivered trade reverses it with forced transfers, so it always waits for a different operator, whatever the row says.

![The Trade busts tab with Bust proposals empty and the Eligible trades table filtered to one instrument](https://docs.settlemint.com/docs/screenshots/console-venue-trade-busts.light.en.webp)

[Screenshot] The "Bust proposals" section reading "No bust proposals yet", above the "Eligible trades" table.

The "Eligible trades" table has an "Instrument" filter and reads "No trades are left to bust" for the chosen instrument. When pending or delivered trades exist, each row carries "Propose bust…", and the proposals table shows "Trade", "Status" and "Actions".

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

- **The Venue operator role on the venue.** Proposing or deciding a bust needs the "Venue operator" role on the trade's venue.
- **A second operator.** While the venue's "Trading venues" row under "Approvals" on [General](https://docs.settlemint.com/docs/console/organisation-settings/general#approvals) is on, a different venue operator approves the proposal.
- **The custodian role, for a delivered trade.** A delivered trade is reversed with custodian forced transfers under the organisation's operations signer, so the signer needs the custodian role on both tokens. See [Reverse a delivered trade](#reverse-a-delivered-trade).

## Steps [#steps]

### Propose the bust [#propose-the-bust]

1. Open "Asset lifecycle", then "Venues", select the venue, then "More" and **Trade busts**.
2. Choose the instrument in the **Instrument** filter above "Eligible trades". On a venue with no instrument yet, the filter is disabled and reads "No instruments yet".
3. Find the trade under **Eligible trades**. It reads "Pending delivery" or "Delivered". A trade with an open proposal reads "Bust proposed", "Bust executing", "Bust failed" or "Bust needs reconciliation".
4. Select "Propose bust…" on the trade, enter a reason, and select **Propose bust**. The sheet states what the bust does to this trade: it releases a trade that has not delivered, and it reverses a delivered trade with forced transfers, which is possible only within 24 hours of the trade. Confirm with your wallet verification. "Keep trade" backs out.

The Console reads "Bust proposal created. A different operator must approve it." while the "Trading venues" row is on and for every bust of a delivered trade, and "Bust executed." when the row is off and the trade is undelivered.

### Decide the proposal [#decide-the-proposal]

A different venue operator opens "Trade busts", finds the trade under "Bust proposals", and selects **Approve** or "Reject", confirming with their wallet verification.

The operator who proposed a bust sees no **Approve** or "Reject" on it and is told another operator must decide.

While the proposal is open on a trade that still awaits delivery, the platform flags it on chain, and delivery skips a flagged trade for up to seven days after its due time, so scheduled delivery cannot settle it during the decision. A venue operator wallet can clear the flag on the venue contract directly, which lets the trade deliver during the decision. A rejection clears the flag and the trade delivers when it is due. An approval runs the undo at once.

## Undo a pending delivery [#undo-a-pending-delivery]

A proposal can target a pending delivery within 24 hours of the trade. An unflagged delivery must still be inside its holding period. A flagged delivery can remain pending after that period, and after the seven-day flag ends, so the platform can complete an approved undo and both owners recover their legs.

For a pending delivery, approval runs the undo at once: the organisation's operations signer, which holds the venue submitter role, submits one on-chain call that unlocks both legs. A venue operator's key cannot submit that call, but any wallet holding the venue submitter role can. The undo of a pending delivery moves no assets back and refunds no fee, because none has moved. Rejection clears the flag so the delivery can proceed. An unflagged delivery whose holding period has ended, a trade that is already undone, and a trade older than 24 hours cannot enter this flow.

## Reverse a delivered trade [#reverse-a-delivered-trade]

A trade that has already been delivered can be proposed on the same tab inside the same 24 hours, and its row reads **Delivered**. There the approved bust reverses the trade with custodian forced transfers under the organisation's operations signer: the base units go back to the seller, and the quote units, both fees and any VAT paid on chain go back to the buyer. The custodian role is the token role that may force a transfer, and the platform first checks that the tokens' compliance rules allow each reversal transfer. When the operations signer lacks the custodian role on a token, the platform queues the grant from your wallet when all three hold:

- your organisation issued the token
- your wallet is a listing signer on the venue, the wallet that lists instruments
- your wallet holds the role that administers the custodian role on that token

Otherwise an administrator of the token grants it on the token's **Permissions** page. The operations signer keeps the custodian role after the bust until a token admin revokes it there. Approval is refused until a queued grant has landed. The proposal is refused when the role is missing and the platform cannot grant it, when a compliance rule would block a reversal transfer or that check cannot run, or when a counterparty or the fee account cannot cover its leg. An instrument with a holding period of zero delivers in the fill's own transaction, so a bust there always takes this path.

## Resume an interrupted bust [#resume-an-interrupted-bust]

If the chain call completes before the platform records the result, **Resume** completes the remaining record updates. The trade becomes "Undone" and its market-data contribution is corrected.

Approving or resuming a bust waits for each reversal transfer to confirm on chain, one after another, for as long as the request allows, less a 15-second reserve. When the reversal is not confirmed in that time, the bust does not fail. It goes back to "Approved", and the trade reads "Bust executing", because its transfers may already be queued and still land. **Resume** then records the bust as executed when the transfers have landed, or sends them again when they have not. The platform sends each reversal transfer under an idempotency key, so the queue does not accept the same transfer a second time. When only some transfers landed, "Resume" sends the missing ones without checking the compliance rules again over the balances the reversal already moved. While a transfer is still waiting in the queue, "Resume" is refused and the bust keeps its state, so try again once it has been sent. A reversal the queue refuses outright still fails the bust, and "Resume" sends it again.

## Let a proposal expire [#let-a-proposal-expire]

A bust proposal that no second operator decides in time expires, 24 hours after it is proposed by default. An expired bust clears its flag in the same way as a rejection, so the delivery can proceed. Propose the bust again if it is still needed. [When a proposal expires](https://docs.settlemint.com/docs/console/asset-lifecycle/venues/desk-administration#when-a-proposal-expires) gives the window and what expiry does.

## After a bust [#after-a-bust]

A bust is a decision by operators. The venue also undoes a pending trade by itself at its due time, with the reason `refused`, but only for an outside cause: a paused token, a trade lock a custodian shrank, a frozen sending side, or a receiver added to the compliance bypass list during the holding period. That undo is not a bust and has no proposal. Any other refusal at delivery, such as a receiver whose identity claim lapsed, does not undo the trade. The refused leg is booked to the receiver's free balance in the venue's escrow, and the trade shows "Delivered". The receiver finds the parked units in the **Balances** panel on [Trading](https://docs.settlemint.com/docs/console/my-assets/trading) and withdraws them after the token's rules accept the wallet again, so the receiver must be verified again first. An unverified receiver also cannot fund a venue order from that balance: the order is refused with `MakerCannotReceiveToken`. To reverse such a trade, propose a bust of the delivered trade.

An undone lot does not return to the order book. The contract counts it as filled, and the platform keeps no original time priority for it, so the trader places it again as a new order with a new price-band check and a new place in the queue.

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

- Open **Trade busts** and check the proposal under "Bust proposals".
- For an undo of a pending delivery, confirm "Undone" on the trade's batch in [Settlement instructions](https://docs.settlemint.com/docs/console/asset-lifecycle/venues/settlement-instructions) and check that both legs are back in the owners' free escrow balances.
- For a delivered trade, the "Events" tab of the [escrow](https://docs.settlemint.com/docs/console/asset-lifecycle/escrows) shows the forced transfers.

## Troubleshooting [#troubleshooting]

**A trade bust cannot be proposed or remains incomplete**

An unflagged delivery whose holding period has ended is refused. A flagged delivery can remain pending through its
review deadline so the platform can complete an approved undo. A trade older than 24 hours, an already-undone trade, a
trade whose settlement is unconfirmed, a trade with an order still open, and duplicate open proposals are refused. A
delivered trade needs the custodian role on both tokens for the operations signer and reversal transfers that the
tokens' compliance rules allow. A proposal flags the trade, so scheduled delivery skips it while the review is open,
up to seven days past the due time. If the chain applied the undo but the record is incomplete, use **Resume** and
verify the unlocked balances. Escalate a reported reconciliation mismatch before signing it off.

**A proposal is refused with a named cause**

  The Console names the cause under the trade, and each cause has its own fix.

- "The trade's settlement is not confirmed on chain yet": wait for confirmation, then propose again.
- "An order from this trade is still open": cancel it on the
  [Orders](https://docs.settlemint.com/docs/console/asset-lifecycle/venues/orders) tab first.
- "The bust window for this trade has closed": the 24-hour window ended, or the holding period ended before the
  delivery was flagged.
- "A bust proposal for this trade is already pending": approve or reject it under "Bust proposals".
- "A counterparty does not hold enough to cover the reversal": ask the counterparty to top up, then propose again.
- "The fee account cannot cover the fee reversal": fund the fee account, then propose again.
- **Token compliance blocks the reversal**: a token admin reviews the compliance rules.
- "The compliance check for the reversal is unavailable": try again in a moment.
- **The token custodian role is missing**: a token admin grants it on the token's "Permissions" tab.

## API routes [#api-routes]

| Task | Route |
| --- | --- |
| Propose a trade bust | `POST /api/v2/addons/trading-venues/{venueAddress}/trade-busts` |
| Decide a trade bust | `POST /api/v2/addons/trading-venues/{venueAddress}/trade-bust-decisions` |

The request and response fields are in [the v2 API reference](https://docs.settlemint.com/docs/api-reference/v2).


# Trading calendar

Source: https://docs.settlemint.com/docs/console/asset-lifecycle/venues/trading-calendar
Set the venue's time zone, weekly hours, half days and closed days, and see how a save is checked against every instrument.

A change on the **Trading calendar** tab reaches every instrument of the venue that has no weekly session of its own. The tab holds the venue's time zone, its weekly hours, its "Half days" and its "Closed days", and the organisation "Holiday calendar" it extends. A day closed here shuts this venue alone. A day inherited from the shared holiday calendar shuts every venue that extends it, so an edit on [Holiday calendars](https://docs.settlemint.com/docs/console/organisation-settings/holiday-calendars) changes all of them, and the "Closed days" table names who closed it: "Platform administrator", "Organisation administrator", or the source a published calendar records, with any web address in it shown as a link named by its site, such as "mohre.gov.ae". [The trading calendar](https://docs.settlemint.com/docs/concepts/issuing-and-markets/venue-market-data#the-trading-calendar) explains how venue, instrument and holiday layers combine.

![The venue's Trading calendar tab with the holiday calendar, the time zone, No weekly hours set on every weekday, Half days and Save the trading week](https://docs.settlemint.com/docs/screenshots/console-venue-trading-calendar.light.en.webp)

[Screenshot] The venue's trading calendar with "Holiday calendar" and "Time zone", and each weekday reading "No weekly hours set" before hours are set.

The "Half days" section with "Add a half day" and the "Save the trading week" button follow the weekdays. The "Closed days" section with the "Close this day" button sits further down the tab.

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

- **The Venue admin role to change the calendar.** Changing the calendar or its closures needs the Venue admin role on one of your wallets. Without it the controls stay disabled and a line names the role.
- **A second venue admin, when the venue asks for one.** On a venue whose "Trading venues" row under "Approvals" on [General](https://docs.settlemint.com/docs/console/organisation-settings/general#approvals) is on, the change waits for a second venue admin under "Venue configuration approvals" on [Desk administration](https://docs.settlemint.com/docs/console/asset-lifecycle/venues/desk-administration).
- **A holiday calendar.** Select a holiday calendar before you save a trading week with any open day. An organisation without one reads "This organisation owns no holiday calendar yet. Create one in Settings first." See [Holiday calendars](https://docs.settlemint.com/docs/console/organisation-settings/holiday-calendars).

## Steps [#steps]

### Open the Trading calendar [#open-the-trading-calendar]

Open "Asset lifecycle", then "Venues", select the venue, and select **Trading calendar** in the tab row.

### Set the time zone and weekly hours [#set-the-time-zone-and-weekly-hours]

A venue with no saved week opens on "Pick a time zone and the days this venue trades," and each weekday reads "No weekly hours set". Once the week has a day, a day left off reads "No session".

Pick the venue's **Time zone**, enable the days the venue trades, and enter each day's "Pre-open", "Open", "Trade at last from" and "Close" times as HH:MM. "Pre-open", when orders are accepted before matching starts, and "Trade at last from", a closing session at the last price, are optional. A close of `24:00` means the end of the day, so the session ends at midnight and the next day's session begins where it ends: a week whose every day opens at `00:00` and closes at `24:00` never closes, and a `23:59` close leaves the last minute of the day closed instead.

### Select the holiday calendar [#select-the-holiday-calendar]

Choose the organisation **Holiday calendar** the venue extends. Once you edit, the page says "Select a holiday calendar before publishing a trading week." under the "Holiday calendar" field until you do. Nothing is marked in red until you change a value. Until then "Save the trading week" stays greyed out and the line under it names the first thing to fix.

### Add a half day [#add-a-half-day]

Under "Half days", enter the "Date" as YYYY-MM-DD, an optional description, and the "Pre-open", "Open", "Closing auction from", "Trade at last from" and "Close" times for that date, and select **Add a half day**. The time fields are named over the columns on a wide screen and above each input on a narrow one. A half day is a dated change of hours. A new half day must be a real date from 2024 through 31 December of the tenth year after the current year.

### Save the trading week [#save-the-trading-week]

Select **Save the trading week** to store the time zone, the weekly hours and the half days, and confirm with your wallet verification. The save checks every instrument on the venue, as [What a save refuses](#what-a-save-refuses) describes.

## Close and reopen a day [#close-and-reopen-a-day]

To close a day, choose its "Date" under "Closed days", optionally fill in "Description (optional)", and select **Close this day**, then verify your wallet. The date picker offers only dates between the current date in the venue's time zone and 31 December of the tenth year after the current year, and "Close this day" stays greyed out until you choose a date.

To reopen a future closed day, delete it from the **Closed days** table. The step is titled "Delete closure on" and the date, asks "Delete this future closure? Sessions will reopen if the date is otherwise open.", and offers "Keep closure" to back out.

## Skip the pre-open for a day [#skip-the-pre-open-for-a-day]

Leave the **Pre-open** time empty and that day has no pre-open phase: the instrument stays closed, refusing new orders, until the open, then goes straight into continuous trading at the open itself, with no opening auction and no randomised uncross window. An auction-only instrument without a pre-open still runs its opening call at the open over the orders it collected before the last close, then collects for the next one. Skipping the pre-open suits a private instrument with no opening price to discover. A private continuous instrument cannot schedule a pre-open at all: the platform rejects a calendar that sets a pre-open time on a weekday or an open exception for it, and the instrument always opens straight into trading at the open. A dated exception that states an open and a close but no pre-open keeps whatever the weekday says, so a half day on a day without a pre-open has none either.

## Add a closing auction [#add-a-closing-auction]

A public continuous instrument can set an optional **Closing auction from** time on a weekday or on a dated exception, in the venue calendar or the instrument's own calendar. It must be after the open and before "Trade at last from", or before the close when the day has none. From that time the instrument collects orders without matching them, as in a preopen, and one uncross at the end of the auction crosses them at a single price: at the Trade at last time when the day has one, otherwise at the close. The instrument's "Pre-open price rule" prices it, and that price becomes the day's official close. Leave the time empty and the day has no closing auction. The instrument calendar offers the field only for a public continuous instrument, and the platform refuses a closing auction time on an auction-only or private instrument. The operator overrides keep a closing auction time that still falls between the new open and close, and clear it for that day when it no longer does.

## Add a Trade at last session [#add-a-trade-at-last-session]

A public continuous instrument can set an optional **Trade at last from** time on a weekday or on a dated exception, in the venue calendar or the instrument's own calendar. It must be after the open and before the close. From that time until the close, orders trade only at the last price: the ticket shows that price locked and offers only limit orders. Leave the time empty and the day has no such session. The instrument calendar offers the field only for a public continuous instrument, and the platform refuses a Trade at last time on an auction-only or private instrument. The operator overrides keep a Trade at last time that still falls between the new open and close, and clear it for that day when it no longer does.

## What a save refuses [#what-a-save-refuses]

A save is refused when, for any instrument on the venue, a day in the next 90 days would have its pre-open after its open, its open at or after its close, a closing auction time that is not after its open and before its Trade at last time or close, or a Trade at last time that is not after its open and before its close. A save checks the next 90 days only, so a fault later than that is not refused at save. The refusal names up to five affected instruments, each with its first such date, and counts the rest. A day already saved with invalid times gets no session, and a session already under way keeps its times. A venue calendar can extend a holiday calendar only when the result stays at most eight calendars deep and forms no loop. Otherwise the save is refused with "The parent calendar cannot be used for this venue calendar" and nothing is stored. [The trading calendar](https://docs.settlemint.com/docs/concepts/issuing-and-markets/venue-market-data#the-trading-calendar) explains how venue, instrument and holiday layers combine.

## Check which dates an instrument is closed [#check-which-dates-an-instrument-is-closed]

Open the security on the trading desk and choose the **Effective holidays** tab. It lists every closed date from yesterday through the next 364 days, with its "Date", the "Holiday" name, or a dash when the closure has none, and the "Source": "Venue" for the venue's own calendar, "Shared calendar" for a holiday calendar the venue's calendar extends, or "Instrument" for a closed day of the instrument itself. The list comes from the same calendar merge that opens and closes the instrument's sessions, so every date it shows is a date the instrument does not trade. When two layers set the same date, a holiday closure wins over the instrument's own entry, the venue's own closure wins over a shared one, and the instrument's own entry wins over the venue's half day or other exception. The tab is read only, and you change a closure on the calendar it names. It does not list weekends and other days the weekly schedule never opens, and a shortened day is not a closure. With nothing to list it reads "No holidays or closed days in the next 12 months".

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

- Reopen **Trading calendar** and check that the time zone, the weekly hours, the half days and the closed days read as you saved them.
- A closed day appears in the "Closed days" table with its "Description".
- On a venue whose "Trading venues" row is on, the change shows under "Venue configuration approvals" until a second venue admin approves it.
- To confirm what an instrument sees, open its "Trading calendar" card on the [instrument](https://docs.settlemint.com/docs/console/asset-lifecycle/venues/instrument).

## Troubleshooting [#troubleshooting]

**Save the trading week is refused**

The Console names the cause under the button. "Select a holiday calendar before publishing a trading week." means no
holiday calendar is chosen. "Fix the times marked in red before saving." means a time is not HH:MM. A save is also
refused when, for any instrument on the venue, a day in the next 90 days would have its pre-open after its open, its
open at or after its close, or a Trade at last time outside the open and close, as [What a save
refuses](#what-a-save-refuses) describes.

**Close this day stays greyed out**

No date is chosen yet. The line "Select the date to close." says so. Choose a date: the picker offers only dates
between today in the venue's time zone and 31 December of the tenth year after the current year.

**The calendar controls are disabled**

Changing the calendar or its closures needs the Venue admin role on one of your wallets. The Console disables the
controls and names the role, or the wallet of yours that holds it.

## API routes [#api-routes]

| Task | Route |
| --- | --- |
| List the dates one instrument is closed, up to 366 dates | `GET /api/v2/addons/trading-venues/{venueAddress}/markets/{marketId}/calendar/effective-closures` |
| Read whether an instrument trades each date and its session | `GET /api/v2/addons/trading-venues/{venueAddress}/markets/{marketId}/calendar/trading-days` |

Any caller who can see the instrument reads both, for a range whose first and last dates are included. The tab reads and writes the venue's calendar through the trading venue routes in the [v2 API reference](https://docs.settlemint.com/docs/api-reference/v2).


# All assets

Source: https://docs.settlemint.com/docs/console/asset-management/all-assets
Find the tokens your organisation issued and open each one's token page from one table.

All assets lists the tokens your organisation issued on the selected network, across asset classes and templates, halted ones included, and the external tokens it registered there. Open a row to reach the asset's token page: its key figures, holders, activity, documents and features, and the **Actions** menu for every operation your roles allow. For totals and trends, open [Insights](https://docs.settlemint.com/docs/console/asset-management/insights). To register a token deployed outside the platform, open [External tokens](https://docs.settlemint.com/docs/console/asset-management/external-tokens).

The table follows the active organisation and network. When you belong to more than one organisation, or the organisation uses more than one network, you change them in the account menu at the top right. Search and column filters narrow that scope. When the table is empty and several networks are available, a network dropdown appears with the prompt "If your assets are on another chain, switch here."

![All assets table](https://docs.settlemint.com/docs/screenshots/console-all-assets.light.en.webp)

[Screenshot] One row per issued token, with the search field and filter controls above the table and a shortcut menu on each row.

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

- Select the organisation and network that own the asset in the account menu at the top right, under Organisation and Network. Each submenu appears only when there is a choice: more than one organisation for you, or more than one network for the organisation. The full "Assets" sidebar section appears for an account that holds the Asset manager role, the role that may create assets. If the section is absent, ask an organisation administrator to review your access. The **Issue asset** button above the table appears only for an account with the Asset manager role, and it is greyed out when that role sits on another of your wallets. While you have a saved draft, the button reads "Resume draft".
- An account without the Asset manager role whose wallet holds a role on an asset, such as Custodian or Supply management, sees the "Assets" section with only **All assets**. The asset class entries and "External tokens" do not appear. Its table lists only the assets that account holds a role on and adds a "Your roles" column with one badge for each role, such as "Custodian" or "Supply management". It has no "Insights" tab and no "Issue asset" button. With no such asset, the table reads "No assets with your roles".

## Steps [#steps]

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

Open "Assets" in the sidebar, then **All assets**. Assets appear newest first, 20 to a page.

The columns "Asset", "Lifecycle status", "Amount", "Holders", "Value", "Price" and "Created" show by default. Columns that do not fit the window are hidden. "Amount" is the total supply, "Holders" counts the wallets with a positive balance, and "Value" is the total supply at the current price, converted into your organisation's base currency. "Value" stays empty for an asset with no price, or when no exchange rate converts its price. "Holders" stays empty for an external token.

"Token name", "Asset class", "Asset type", "Instrument template", "Family", "Network" and "Identifier" start hidden. Select **View** to show them.

While no search or filter is applied, a deployment that is still running or that failed appears as a row at the top of the list, before the live assets. A running deployment shows "Deploying" with "In progress" under it. A failed one shows "Failed" and "Not created", with the "Reason" in the row detail. Under its name, a deployment row shows the instrument template it was started from. When the deployment used no template, or that template was deleted, the row shows the asset type instead, such as "Configurable asset". A failed deployment that created no token offers **Discard**, which only an Asset manager can complete. Its confirmation says that a failed deployment cannot be retried from this list and that you issue the asset again with "Issue asset".

### Narrow the results [#narrow-the-results]

Search by token name, symbol, or contract address. Add filters for "Asset class", "Asset type", "Instrument template", "Family" or "Status" to narrow the results. Selecting an asset class keeps every template of that class. An asset whose type belongs to no asset class is listed under "Unclassified". The filters and the search run on the server across all pages. **Export** in the table toolbar saves every matching row as CSV or JSON.

Each asset class also has its own entry under "Assets" in the sidebar. Its page lists the class's assets one template at a time. When the class has more than one template with assets, a **Template** select names each template with its asset count. The sidebar lists a class only while at least one asset of its templates exists on the selected network.

The "Asset class", "Asset type" and "Instrument template" menus show only values with matching assets under the current scope and filters. If an expected value is absent, clear the other filters and check the selected network.

The **Instrument template** column links each token to its template definition for the Permission manager, System manager and Asset designer roles. Every other account sees the name as plain text.

### Open the asset or act from the row [#open-the-asset-or-act-from-the-row]

Select the asset's row. Its token page shows the logo, the name, a status badge, the **Actions** menu, a strip of key figures, and tabs. [Read the token page](#read-the-token-page) describes each part.

On the "Holders" tab, the toolbar **Export** menu opens the sheet "Export holder register" for organisation owners, platform administrators and holders of a reporting role, on an asset that has the Historical balances feature or had it detached. Its tabs are "Register", "Registrar file", "Beneficial owners" and "Deliveries". "Beneficial owners" files a declaration of the owners behind a nominee wallet from a CSV file and reads the holder register looked through to those owners at the record block, with stale nominee wallets flagged. See [Issuer shareholder list](https://docs.settlemint.com/docs/api-reference/guides/issuer-shareholder-list#declare-and-read-them-in-the-console).

The row's shortcut menu offers **Copy address**. "View on Explorer" appears when the selected network has a block explorer configured.

A token whose deployment landed on the network but whose setup stopped part way shows "Setup incomplete" with the step that failed and its reason. Its menu adds "Finish setup" and "Dismiss". Only the user who issued the token, signed in with the same wallet, can finish the setup, and only an Asset manager can dismiss it. **Finish setup** asks for your PIN once and runs only the steps that did not complete, such as the role grants, the initial price, unpausing the token, or binding the conversion feature to its yield feature. "Dismiss" removes only the notice. The token stays on the network with the failed steps undone, such as a missing role grant or a token that is still halted.

## Edit the holder rule [#edit-the-holder-rule]

The "Compliance" tab opens with a **Holder rule** section when your roles let you read the asset's compliance configuration. It shows the token registry rule, which is the requirement the asset's identity registry checks on every receiving wallet. When the asset has an active identity verification module, the module's rule appears beside it. Both rules apply to transfers and mints. A custodian's forced transfer and a lost-wallet recovery check only the registry rule, so the module rule does not bind them.

An empty registry rule reads **No verification requirement**. Only wallets registered in the system identity registry and not marked lost can then receive the asset, and no rule can lower that floor.

A holder of the Governance role on the asset also sees **Edit holder rule**. It opens the expression builder with the current registry rule, and "Save holder rule" asks for wallet verification. Saving an empty rule removes the holder requirement once it applies. A holder rule change waits for a second person only while the "Administration" row under "Approvals" on [General](https://docs.settlemint.com/docs/console/organisation-settings/general#approvals) protects the "Compliance configuration" group. When the rule excludes a topic a holder can remove from their own identity, the platform refuses the save and the sheet shows its reason with a checkbox. Tick "I accept this warning" and save again to record the acknowledgement, or narrow the rule. An impersonated session cannot accept it.

A topic is a claim type on a holder's identity, such as `knowYourCustomer`. The topic list in the builder groups topics under Person, Asset, Issuer and Other. It includes the topics of the system and of the asset's own topic schemes, so a capacity topic your compliance team registered, such as `intermediary`, appears in its group.

When the asset has one active identity verification module and its rule differs from the registry rule, the same Governance role sees **Move module rule to the registry**. It asks you to confirm two writes: the registry stores the module's rule, then the module is removed from the asset. Wallet verification is asked once. The two writes cannot be sent as one, so the registry is written first. If the removal then fails, the rule sits in both places and the asset behaves as before, because both rules apply. The sheet offers "Retry removing the module rule".

Write the check every holder must pass outside the OR group that lets a capacity claim through: `sanctionsScreening AND (knowYourCustomer OR intermediary)`. The form `(sanctionsScreening AND knowYourCustomer) OR intermediary` lets a capacity claim skip sanctions screening.

## Read the token page [#read-the-token-page]

The header shows the logo, the name, a status badge and the **Actions** menu, which lists the operations open to you. Most operations that need a role none of your wallets holds are left out. A few stay greyed out with the reason instead, such as "Refresh mark" without the Governance role. An operation whose role sits on another of your wallets is greyed out and names that wallet. A Governance role holder replaces the logo from the header, as [Documents](https://docs.settlemint.com/docs/console/asset-management/manage/documents#replace-the-token-logo) describes.

### Key figures [#key-figures]

"Total supply" and "Holders" sit under the header, followed by "Price" and "Supply cap" when the asset has them. Each figure has an info button. Its popover says how the number is calculated and names its "Source", which is "Chain indexer" for total supply, holders and supply cap and "DALP API" for the price. "As of" gives the time of the latest indexed block, and a figure read from the indexer also names that block.

**Price** shows two decimals. When they round the exact price, it reads with ≈, such as ≈1.00 for 0.99725936, as the "Price" column of the asset lists does. A screen reader reads it as approximately that figure, and hovering over or selecting it shows the exact price. A price the two decimals show exactly carries no ≈.

### Tabs [#tabs]

"Overview", "Holders", "Activity", "Compliance", "Features" and "Documents" are always present. "Corporate actions", "Treasury", "Governance", "Blocklist", "Permissions" and "Transfer pre-check" appear when the asset or your roles allow them. "Permissions" appears on an asset with access management, and "Governance" on an asset with voting power. At most seven tabs show in the row, and the rest sit under **More**. To review, grant or revoke the roles on the "Permissions" tab, see [Roles and permissions](https://docs.settlemint.com/docs/console/organisation-settings/admins-and-roles#change-asset-roles-on-an-asset).

- **Overview** opens with the "Needs you" card when an action waits on you, and the "Supply" chart, titled "Supply and reserve" when it draws the reserve line of an asset with a collateral rule. Below them sit the reserve, "Largest holders" with "All holders", "Recent activity" with "All activity", and the "Details" card.
- **Holders** is the holder register. See [Holder register](https://docs.settlemint.com/docs/console/asset-management/manage/holder-register).
- **Documents** holds the asset's documents and notices. See [Documents](https://docs.settlemint.com/docs/console/asset-management/manage/documents).
- **Corporate actions** runs corporate events. See [Corporate actions](https://docs.settlemint.com/docs/console/asset-management/manage/corporate-actions).
- **Blocklist** freezes every token of one address. See [Emergency halt and freeze](https://docs.settlemint.com/docs/console/asset-management/manage/pause-freeze).
- **Transfer pre-check** tests a transfer against the asset's compliance rules. See [Transfers](https://docs.settlemint.com/docs/console/asset-management/manage/transfers#check-a-transfer-before-anyone-signs).

### Activity [#activity]

The **Activity** tab lists, newest first and 20 to a page, the events the token emitted, the events of its feature and identity registry contracts, and the events that name the token. Each row shows the date, the event with its two endpoints, the transaction hash and the amount. The "Contract" column starts hidden. A trade a trading venue settled in this asset shows as one swap row. A mint, burn or transfer shows as one row, without the ERC-20 `Transfer` to or from the zero address that the token emits beside it.

Filter by "Date", "Type" or "Contract". The date filter reads "Dates are in UTC." and covers whole days in UTC. Its chip shows the chosen day in your language's date format. "Flows by week" at the top of the tab plots the minted and burned amounts and the net issuance of each of the last 13 weeks, with the number of transfers between holders in a small chart beneath, its axis marked in whole transfers. Mints and burns are not counted there. When a range has mints or burns but no transfers, the note reads "No transfers between holders in the last 13 weeks. Mints and burns are shown above." Select a row to open a sheet titled with the event's name, with the transaction hash, the block, the sender and the event parameters. **Export CSV** downloads every event that matches the filters and says "Times are in UTC."

### Treasury [#treasury]

On an asset with maturity redemption, the **Treasury** tab lists the assets its contract holds with their symbol, balance, value and status. A tag next to the asset name, "Redeems at maturity" or "Yield", marks the asset that pays holders. A contract that holds nothing reads "No assets held yet".

### Instrument structure [#instrument-structure]

An asset that is one class of a multi-class instrument shows the **Instrument structure** section on its overview, with the instrument id, "This class" and the "On-chain attestation". The attestation reads "Attested on chain by a trusted issuer", "Attested on chain, but the issuer is not trusted for this topic", "The on-chain attestation was revoked", "The on-chain attestation cannot be read" or "The on-chain attestation does not match this token's pairing record". The section is absent when the asset carries no instrument structure claim.

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

- Confirm that the row shows the expected name and symbol and that its **Lifecycle status** and "Amount" match the token page.
- Copy the contract address from the row menu when you need to match the asset to a transaction or external record.

## Troubleshooting [#troubleshooting]

**An asset is not listed**

Clear the search and filters, then confirm the organisation and network in the account menu. Search by contract
address if you have it. If the table is empty and several networks are available, use the network dropdown in the
empty state to check the network where the asset was issued.

**Issue asset is missing**

Signal: no **Issue asset** control appears above the table. Cause: the button is shown only for an account that holds
the Asset manager role. Fix: ask an organisation administrator to grant it if issuing assets is part of your role.

**A filter option you expect is not in the list**

Signal: an asset class, type, or template you know exists does not appear as a selectable filter option. Cause: the
menus list only options with at least one matching asset under the current scope and the filters already applied. An
option with zero matches is left out. Fix: clear the other filters first, and check the active network, since an
option returns once assets that would match it are back in view.

**A token shows Setup incomplete without Finish setup**

Signal: the row shows "Setup incomplete" and its menu offers only **Dismiss**. Cause: only the user who issued the
token, signed in with the same wallet, can finish its setup, and a deployment that started before the platform kept
its create request cannot be finished at all. Fix: ask the user who issued the token to finish it. For an older
deployment, dismiss the notice. The token stays on the network.

## Frequently asked questions [#frequently-asked-questions]

### Does All assets show assets that belong to other organisations?

The table lists tokens issued by the active organisation on the selected network, and the external tokens that organisation registered there, which can include a token another organisation issued. Switch organisation in the Organisation submenu of the account menu to view its issued assets.

### What does the Created column show?

For an issued token, **Created** shows when it was created. For a deployment row, it shows when the deployment started. The table lists assets newest first.

### Do halted assets stay in the table?

A halted asset stays in the table. Its "Lifecycle status" reads "Halted", and you open its token page from the row to resume it. Use the **Status** filter to isolate halted assets during an incident review, or to exclude them from an inventory pass.

## API routes [#api-routes]

For an integration, use the token collection in the [Platform API reference](https://docs.settlemint.com/docs/api-reference/v2). The [pagination guide](https://docs.settlemint.com/docs/api-reference/guides/pagination) explains how to page through results.


# External tokens

Source: https://docs.settlemint.com/docs/console/asset-management/external-tokens
Register tokens deployed outside your organisation's system, and review the ones the platform registered on its own when they reached a managed wallet.

External tokens registers a token your organisation's system did not issue, so operators track it beside the assets they issued. That includes a token another organisation issued on its own DALP system. Once registered, your organisation's holding of that token shows as its own, and its totals count the balance it holds, not the issuer's whole supply. Whether the holding can move stays with the issuing system's rules, so its compliance, its halt and its freezes still apply. [All assets](https://docs.settlemint.com/docs/console/asset-management/all-assets) lists registered external tokens next to the issued ones.

A registration is a record, not a redeployment. The platform sends no transaction to the external contract and adds no DALP feature to it, and the token's page has no mint, burn, transfer or emergency halt control. Registration runs on the network you selected, and the token shows only on that network. It writes the address and token type to the on-chain registry from the wallet you act with. The registry has no removal, so a registration of the wrong address cannot be reversed. **Dismiss** only hides the token.

![External tokens page with the Tokens and To review summary, the token table and the Register external token button](https://docs.settlemint.com/docs/screenshots/console-external-tokens.light.en.webp)

[Screenshot] The External tokens page with its summary strip, its token table and the "Register external token" button.

The title row carries "Register external token". The "Tokens" cell counts the registered tokens and how many were auto-detected, and "To review" reads "Nothing to review". Each table row shows the token and its type, its status, the registration date with who registered it, and the supply at registration.

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

- Confirm that **External tokens** appears under "Assets" in the sidebar. The entry shows only to an account with the Asset manager role on the organisation's system, the role that also issues assets and that registering, dismissing and restoring need. The Permission manager role alone does not show it. Ask a holder of the Permission manager role to grant it if the entry is absent. Use the Network submenu of the account menu in the Console header to choose the network where the contract is deployed. Obtain the deployed contract address and its token type from the approved deployment record. "Confirm registration" signs with the wallet you act with, which must hold the Asset manager role on the system, so confirm it is the one your organisation authorises to register tokens before you submit.
- Some [instrument templates](https://docs.settlemint.com/docs/concepts/modeling-assets/instrument-templates) in [Issue asset](https://docs.settlemint.com/docs/console/asset-management/issue-new-asset) need an existing token underneath them as their [denomination asset](https://docs.settlemint.com/docs/concepts/modeling-assets/denomination-asset), such as a stablecoin or another ERC-20 to wrap. When a template needs an ERC-20 denomination asset and the organisation has none yet, the template picker shows **Register an external token** next to "Issue a stablecoin", and the empty denomination asset hint later in the wizard offers "Register an existing stablecoin" next to "Issue a stablecoin". Both open the same registration panel inside Issue asset, with the token type set to Stablecoin, which you can change before submitting. A template that needs a conversion target token offers only "Issue a conversion target token". Registering a token never creates a wrapped or derived asset by itself. That step happens afterwards, in Issue asset's own wizard.

## Steps [#steps]

### Read the table and the review findings [#read-the-table-and-the-review-findings]

Open "Assets", then **External tokens**. The page title is followed by the name of the network you selected. Below it, a summary strip has two cells. "Tokens" counts the tokens and shows how many were auto-detected and, for an account with the Asset manager role, how many are dismissed. "To review" counts the tokens that need a decision and splits them into lookalikes and tokens whose indexing stopped, or reads "Nothing to review".

Under the strip, each lookalike and each token with stopped indexing has its own finding. A finding's title shows the short contract address of the token it is about, so two findings for tokens with the same name read differently. Every finding offers **Open token**, which opens the token's page. A lookalike finding also offers "Dismiss" to an account with the Asset manager role. On a narrow screen, two or more findings fold into one that reads "2 tokens need review".

The table has four columns:

- **Token** shows the name, with the symbol and type under it, an "External" mark, and the "Lookalike" badge when it applies.
- **Status** shows one value, the first that applies of "Dismissed", "Paused", "Indexing stopped", "Catching up" and "Active".
- **Registered** shows the date and, under it, "Auto-detected" or the address that registered the token.
- **Supply at registration** shows the supply the contract reported when the token was registered, and does not update.

The **View** control can show "Contract address", "Decimals", "Standards", "Indexing", "Type", "Origin", and "State". "Origin" is "Auto-detected" or "Manual". "State" is "Active" or "Dismissed". Only an account with the Asset manager role sees dismissed tokens here or can filter to them. Search the table by name, symbol, or address, and filter by status, type, origin, or state.

Select **Register external token**, which shows only to an account with the Asset manager role, to open the registration side panel. Without the role, an empty table reads "An asset manager registers them."

### Enter and check the contract [#enter-and-check-the-contract]

Choose **Quick add a known token** to pick from a built-in list of well-known tokens on the active network, or enter the deployed address in "Contract address". The panel reads "Check a token contract on" followed by the network name. Quick add fills the address, and the type when it knows it, then runs the same eligibility check as manual entry. If you replace a suggested address, choose the type again because the field empties. About 350 milliseconds after you stop typing, the panel runs a live check against the chain and shows a preview card beneath the field. Once the contract answers ERC-20 metadata, the card shows its name, symbol, decimals and total supply, with a "Smart" badge when the contract implements DALP's SMART token standard.

The card ends in one of four states: still inspecting, unable to inspect the contract at all, eligible for registration, or blocked with one exact reason. An inspection failure is a lookup problem and says nothing about the contract. The check runs the same reads the registration runs, so an eligible card means those reads passed at that moment. A registration can still fail on chain after you sign, for example when someone registers the same token between the check and your signature. A blocked verdict names one of five causes:

- **No contract at this address**: no contract code at that address.
- **Already registered**: the organisation already registered the token by hand and it is active.
- **Already managed by this platform**: the token is one of your organisation's system's own factory-deployed or system contracts.
- **Not a token contract**: the contract does not answer the ERC-20 name, symbol and decimals a registration reads, as happens at a wallet contract.
- **Token details too long**: the contract reports a name longer than 50 characters or a symbol longer than 24, which DALP never shortens.

An auto-detected or dismissed token stays eligible, because registering it by hand brings it back. Compare the resolved name, symbol and decimals against the approved deployment record before continuing.

Use the **Token type** dropdown to choose from a fixed list: Bond, Equity, Fund, Stablecoin, Deposit, Cryptocurrency, or Other. The field has no default, so you must choose one. It sets a tracking category for this registration, and the chain enforces nothing based on it. "Register token" stays disabled until the address check resolves to eligible. A blocked contract names its single reason and keeps the button off until a different address clears the check. Selecting it with no type chosen shows "Choose the token type."

![Register external token side panel with Quick add, Contract address and Token type](https://docs.settlemint.com/docs/screenshots/console-register-external-token.light.en.webp)

[Screenshot] The panel opens with the "Quick add a known token" list, then the required "Contract address" and "Token type" fields.

### Register the token [#register-the-token]

Select **Register token**, then complete "Confirm registration" with your wallet. The Console records the existing contract in the external-token registry. Settlement lands one of three ways. An immediate success shows "External token registered successfully" and the table refreshes to include the new row. Historical indexing can continue after registration succeeds. An on-chain failure shows "Token registration failed on-chain. No changes were made." Read the reported error and correct its cause before retrying. A still-pending transaction shows "Registration is still processing. Track progress in Actions." instead, and the table updates once that transaction settles. Follow it on [Actions](https://docs.settlemint.com/docs/console/essentials/actions).

[Figure] One eligibility check gates whether Register token can be selected. An address entered on the active network feeds a live chain read, about 350 milliseconds after typing stops. When the read resolves eligible, the contract's identity is confirmed and Register token becomes selectable. When it resolves blocked, one of five exact reasons applies: no contract code at that address, the token is already registered, the token is one of your organisation's system's own factory-deployed or system contracts, the contract does not answer the ERC-20 metadata a registration reads, or its name or symbol is longer than DALP stores. Any one of the five keeps Register token disabled until a different address clears the check. Labels: Token address entered; Runs automatically, about 350 ms; after typing stops.; chain read resolves; eligible; blocked; Eligible; Register token enabled; Identity and supply confirmed.; Blocked; No contract at this address; Already registered; Already managed by this platform; Not a token contract; Token details too long; Any one reason disables Register token.; Register token stays disabled.

The address check runs about 350 milliseconds after you stop typing, then an eligible contract turns "Register token" on and a blocked one names its single reason.

## Review auto-detected tokens and lookalikes [#review-auto-detected-tokens-and-lookalikes]

Automatic registration is off by default. It runs only when your operator sets `FEATURE_EXTERNAL_TOKEN_AUTO_REGISTRATION` to `true` (the `features.externalTokenAutoRegistration` setting). While it is off, a token sent to a managed wallet is not registered until an account with the Asset manager role registers it by hand, and no row shows **Auto-detected**.

With the setting on, when an ERC-20 token or an ERC-3643 permissioned token that this platform did not issue lands in a wallet the platform manages for your organisation, the platform registers it on its own, at most 20 per organisation per day. The organisation's operations signer writes it to the on-chain registry, and no person confirms it, so anyone can start this by sending a token to a managed wallet. A token over the daily cap is not registered until the cap allows. Such a row shows **Auto-detected** under its registration date and is active straight away.

When another of the organisation's tokens has the same symbol or name, ignoring letter case and Unicode look-alike forms, the row also carries a "Lookalike" badge, and the list and the token's page show the **Possible lookalike token** warning. The warning shows both values exactly as stored, names the existing token as "Name (SYMBOL)", and links to its page. Compare the addresses before you use the token, because a lookalike can be a scam, and dismiss it when it is one.

## Dismiss or restore an external token [#dismiss-or-restore-an-external-token]

A settled registration's address has no edit control. The per-row menu offers "Copy address" and, when the network has a block explorer configured, "View on Explorer". An account with the Asset manager role also sees **Dismiss**, which hides the token from the organisation's holdings, portfolio, holder lists, token catalogue, token details and marks. Dismissing also stops the platform from registering it again. Accounts with the Asset manager role still see a dismissed token in this table. The registration itself stays on chain. The organisation's portfolio value drops the dismissed token once the next block is indexed, and later price changes or transfers of it no longer move that value.

To bring a dismissed token back, choose **Restore** in its row menu or in the header of its page. It opens the registration panel titled "Restore external token" with the address and type already filled in, and the token becomes active and returns to the portfolio value once you confirm with "Restore token". Registering the same address by hand does the same, and registering an auto-detected token by hand accepts it the same way. In each case the token takes the type you choose. When your organisation's system already holds the token in its registry and that type differs from the one on chain, the platform also queues a transaction that updates the type in the on-chain registry. The table then shows the type the on-chain registry ends with, so if two type changes for the same token land close together, the later one wins. When indexing runs behind, the registration is reported as queued, and the new type appears once indexing catches up.

## Read a registered token's page [#read-a-registered-tokens-page]

Select a token's row to open its page. The header shows the token mark, the name, the ticker when it differs from the name, and one status badge. Select the badge to see the registry state, the contract state, and the indexing state. The "Actions" menu offers "Copy address" and, when the network has a block explorer, "View on Explorer". An account with the Asset manager role also sees a "Dismiss" button in the header, or "Restore" on a dismissed token. While a lookalike warning shows, its "Dismiss" takes the place of the header button. A strip under the header shows "Supply at registration", with the date it was read when the platform recorded one. When the token is paused or its indexing stopped, a finding above the tabs says so, and paused takes precedence. An auto-detected token that looks like another token also shows the "Possible lookalike token" warning.

The **Overview** tab has a "Token" card with the full contract address and a copy button, the status, the token type, and the standards with any detected interfaces. A "Registration" card shows the registration date and time, the registering account, the decimals, and the indexing state with the reason it stopped. A "Recent activity" card links to the "Activity" tab, which lists the token's events from the block your organisation's system registered it. Earlier transfers stay out, including those of your own wallets, and the same cut-off applies to the "Activity" page and to investor statements. An account without the Asset manager role reads the page without "Dismiss" and "Restore", and the "Registration" card says that asset managers register, change, and dismiss external tokens.

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

- Check the **Status** column first. "Catching up" means registration is complete but historical supply and events are incomplete.
- "Indexing stopped" means the platform stopped tracking the token's balances and supply.
- Read the reason on the token's page.
- Registering the token again does not restart indexing.
- "Paused" means the token's issuer paused transfers on the contract.
- Open the registered token's row to reach its own page, and compare the contract address and supply with the approved deployment record and the block explorer.

## Troubleshooting [#troubleshooting]

**Register token cannot be selected**

Signal: the button stays disabled even though the address and token type fields look filled in. Cause: the eligibility
check has not resolved yet, or it resolved blocked. A blocked verdict names one of the five reasons that [Enter and
check the contract](#enter-and-check-the-contract) lists. Fix: wait for the preview card to finish, then read the
exact reason it names before assuming the form itself is wrong.

**The preview card cannot inspect the contract**

Signal: the card reports a lookup failure instead of naming an eligibility reason. Cause: usually the selected network
differs from the network the contract is deployed on, or a read failed for a moment. Fix: confirm the selected network
matches the deployment record, then retry the address.

**Check whether an address is already registered**

Paste the address into **Contract address** in the registration panel. When the organisation registered the token by
hand and it is active, the preview card reads "Already registered". An auto-detected or dismissed token stays
eligible, so search the table by address to find it.

**Nothing new appears after Register token**

Signal: the confirmation completed, but the table still does not show the new row. Cause: settlement is not always
immediate. A still-pending transaction shows "Registration is still processing. Track progress in Actions." instead of
the success message, and the table updates once it settles. Fix: check **Actions** for the pending transaction before
you repeat the registration.

**The resolved contract details do not match the approved deployment record**

Signal: the preview card names a symbol, decimals, or supply that disagrees with the record you were given. Cause:
usually the wrong address, sometimes a deployment record that is stale or wrong itself. Fix: stop and do not submit. A
registration cannot be removed, on chain or in the Console, so resolve the mismatch against your organisation's own
deployment record, or with whoever issued it, before you continue.

**A token you dismissed is gone from the table**

Signal: a dismissed token no longer appears in the table. Cause: only an account with the Asset manager role can see
dismissed tokens, and it can filter "State" to "Dismissed". Fix: sign in with an account that holds the role, filter
"State" to "Dismissed", and choose **Restore** in the token's row menu or on its page.

## Frequently asked questions [#frequently-asked-questions]

### Do I need to register the same contract again on another network?

Yes. Registration is per network, so a record applies only to the network selected in the account menu when you submit. Deploying the identical contract address on a second network is a separate registration with its own eligibility check and its own transaction, and it does not appear in this table until you register it while that network is active.

### If I close the registration panel I opened from Issue asset, do I lose that entry point?

No. Closing the panel leaves you on the Issue asset step you opened it from, and the same button opens it again with the type set to Stablecoin. The panel never changes the page address, so reloading does not reopen it. **Register external token** on this page opens the same panel with no token type chosen, because the field has no default.


# Assets

Source: https://docs.settlemint.com/docs/console/asset-management
The Assets group of the Console sidebar and the token page every asset operation starts from.

The **Assets** group lists the tokens your organisation issued in "All assets", reads them together in "Insights", issues a new one in "Issue asset" from an instrument template your organisation published, and registers a token deployed elsewhere in "External tokens". Every page for operating one asset starts on that asset's token page, which you open from "All assets". The page carries the tabs and the "Actions" menu those pages describe.


  - [All assets](https://docs.settlemint.com/docs/console/asset-management/all-assets): Find the tokens your organisation issued and open each one's token page from one table.
  - [Insights](https://docs.settlemint.com/docs/console/asset-management/insights): Read a one-page briefing on the organisation's assets: value, launches and activity.
  - [Issue asset](https://docs.settlemint.com/docs/console/asset-management/issue-new-asset): Configure and deploy an asset from a template your organisation published.
  - [External tokens](https://docs.settlemint.com/docs/console/asset-management/external-tokens): Register tokens deployed outside your system and review the ones the platform found.
  - [Holders](https://docs.settlemint.com/docs/console/asset-management/manage/holder-register): Read who holds an asset now or on a past date, and export the register.
  - [Documents](https://docs.settlemint.com/docs/console/asset-management/manage/documents): Upload, version and preview an asset's documents, publish notices and replace its logo.
  - [Booked movements](https://docs.settlemint.com/docs/console/asset-management/manage/booked-movements): Keep a share class token in step with a transfer agent's register.
  - [Yield and maturity](https://docs.settlemint.com/docs/console/asset-management/manage/yield-maturity): Set a yield schedule, claim yield, trigger maturity and fund the treasury.
  - [Token conversion](https://docs.settlemint.com/docs/console/asset-management/manage/conversion): Convert a convertible note, SAFE or warrant into a share token against a round.
  - [Corporate actions](https://docs.settlemint.com/docs/console/asset-management/manage/corporate-actions): Enter approved corporate event terms, review the holder impact and run the event.
  - [Cash dividend and distribution](https://docs.settlemint.com/docs/console/asset-management/manage/cash-dividend): Declare a cash dividend, preview entitlements, fund the treasury and confirm the snapshot.
  - [Coordinated distribution](https://docs.settlemint.com/docs/console/asset-management/manage/coordinated-distribution): Pay every share class of a multi-class instrument from one pool.
  - [Approve a corporate action](https://docs.settlemint.com/docs/console/asset-management/manage/corporate-action-approval): Send a corporate action to a second approver, decide it in the window and run it.
  - [Dealing](https://docs.settlemint.com/docs/console/asset-management/manage/fund-dealing): Set a fund's subscription terms and settle each dealing day's redemptions at the NAV.
  - [Transfers](https://docs.settlemint.com/docs/console/asset-management/manage/transfers): Move tokens, force a transfer as custodian, pre-approve transfers and recover tokens.
  - [Mint and burn](https://docs.settlemint.com/docs/console/asset-management/manage/mint-burn): Mint units to a recipient or burn units from a holder's wallet.
  - [Emergency halt and freeze](https://docs.settlemint.com/docs/console/asset-management/manage/pause-freeze): Halt transfers, mints, burns and redemptions, or freeze an amount at one address.
  - [Fee administration](https://docs.settlemint.com/docs/console/asset-management/manage/fee-administration): Set fee rates and recipients, freeze a rate and collect accrued management fees.
  - [Set price](https://docs.settlemint.com/docs/console/asset-management/manage/token-pricing): Set a token's price on its feed and see when the platform refuses a stale one.



# Insights

Source: https://docs.settlemint.com/docs/console/asset-management/insights
Read a one-page briefing on the organisation's assets: total value, launches, token activity, what needs attention, and how value is spread.

Insights answers questions about the whole organisation: what its assets are worth, whether launches keep up with creation, whether token activity picked up, and what waits on you. Every figure comes from indexed chain data and the organisation's prices, for the assets the active organisation issued on the active network and the external tokens registered to it there. Viewing Insights changes no token and writes nothing to **Activity**.

Insights lists no single asset or transaction. For one token, open [All assets](https://docs.settlemint.com/docs/console/asset-management/all-assets). For one transaction's result, hash and timestamp, open [Activity](https://docs.settlemint.com/docs/console/essentials/activity).

![Insights tab with the period controls, three key figures, one attention card and the composition bars](https://docs.settlemint.com/docs/screenshots/console-asset-insights.light.en.webp)

[Screenshot] The "Insights" tab with the period controls, three key figures, one attention card and the composition bars.

The "Compare with prior period" switch and the range selector sit under the tabs. Below them comes a strip of three figures with "Total value" widest, then one attention card that counts the assets created in the period, then the "Value by asset class" and "Assets by type" composition bars side by side.

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

- Insights needs the "Asset manager" role on the organisation's system, the role that issues tokens. Without it, the "Insights" tab of "All assets" opens a page that reads "This page isn't available for your account or organisation." Ask a holder of the "Permission manager" role to grant it.
- When the account menu at the top right offers Organisation and Network submenus, choose the scope you intend to review there. Every figure on this page reads only that scope.

## Steps [#steps]

### Open Insights and choose the period [#open-insights-and-choose-the-period]

Open "All assets" under "Assets" in the sidebar, then select the **Insights** tab. The page heading reads "Insights", and the key figures come first. Each block loads on its own, so one failed read leaves the others in place.

"Compare with prior period" and the range selector sit in one row under the tabs, over the key figures. The range selector sets one period for the whole page: "All", "YTD", "12 months", "6 months", "3 months", "1 month", "Last 7 days" or "Last 24 hours". It opens on the last month and keeps your choice while you stay on the page. A reload opens on the last month again.

**Compare with prior period** is on by default: every change figure and the dashed line on the trend chart then compare the chosen period with the period of the same length just before it. With "All" selected, the switch is off and cannot be turned on, and "All time has no earlier period to compare." sits beside it.

The indexer is the platform service that reads events from the network into the data this page counts. When it is behind the chain, a platform administrator or organisation owner sees "Figures are behind the chain" over the range selector, with how many blocks behind it is and the block it has reached. While it rebuilds, the message reads "The indexer is rebuilding". A "View status" link opens Platform status for an account that can open it. Each key figure has an info icon that explains how it is counted.

### Read the three figures [#read-the-three-figures]

The strip carries three figures.

- **Total value** is each asset's supply times its price, converted to the organisation's base currency and added up. The base currency is set when the organisation is deployed, and [Exchange rates](https://docs.settlemint.com/docs/console/organisation-settings/exchange-rates) marks it "base". An external token, one DALP did not issue, counts only through the balances your organisation's accounts hold, at its price. That includes a token the platform registered on its own when it reached a managed wallet, until an asset manager dismisses it on [External tokens](https://docs.settlemint.com/docs/console/asset-management/external-tokens). When any asset has no price to convert from, the label reads "Total value, priced assets only", and the sum leaves those assets out instead of counting them at zero.
- **Launched** shows launched assets out of all assets created in total, not only the ones created in the chosen period, with the launched share beneath. A token counts as launched the first time its transfers are resumed, either by "Open for transfers once issued" in [Issue asset](https://docs.settlemint.com/docs/console/asset-management/issue-new-asset) or by "Resume token operations" later, so an asset still in pre-launch counts as created but not launched. An external token counts as created and launched from the moment you register it, because DALP does not launch tokens it did not issue.
- **Token events** counts the transfers, mints, and burns recorded across the organisation's assets during the chosen period.

With comparison on, each figure also shows its change against the previous period, coloured by size and direction, and a small line traces the figure across the period. "Total value" and "Launched" compare the level at the end of each period, and "Token events" compares the number of events inside each period.

[Figure] Every change compares the chosen period with the period just before it. The page reads the chosen period and a prior period of the same length that ends where the chosen one starts. Total value and Launched compare the level reached at the end of each period. Token events compares the number of events counted inside each period. With comparison off, or with the range set to All, no change is shown. Labels: Prior period; Same length, just before; Level at the end of the period; Chosen period; Ends now; Level at the end of the period; Total value, Launched; compare the two end levels; Token events; compares the events inside each period; Comparison off, or range All: no change is shown.

The prior period has the same length as the chosen one and ends where it starts.

### Act on what needs attention [#act-on-what-needs-attention]

The cards below the figures are the items that may need you. Each card opens **All assets**. "Assets halted" opens it filtered to halted assets, and the other cards open the full list, which you narrow with "Status". For a Feeds manager, the "Value excludes unpriced assets" card offers "Set up price feeds" instead, which opens the data feeds settings.

- **Launches pending** counts created assets that have not launched yet. A non-zero count is highlighted because each one waits for a holder of the "Emergency" role to select "Resume token operations" on the token, as [Emergency halt and freeze](https://docs.settlemint.com/docs/console/asset-management/manage/pause-freeze) describes.
- **Assets halted** counts assets whose transfers are halted, which normally includes assets that have not launched yet.
- The third card depends on pricing. When any asset has no price to convert into the base currency, it reads **Value excludes unpriced assets** with "Set up price feeds" for a holder of the "Feeds manager" role, or "Review assets" for any other account. When every asset is priced, it reads "Assets created in range" and counts only the assets created during the chosen period, so it can differ from the "of … created in total" on the Launched figure.

A card whose count is zero is left out. The "Value excludes unpriced assets" card stays while any asset is unpriced, and with no card left the row of cards is absent. When a count has never loaded, its card becomes a notice such as "Check halted assets in the asset list", with **Open all assets**.

### Read the composition, the trend, and the map [#read-the-composition-the-trend-and-the-map]

The two composition blocks show the current position, whatever the chosen period, and the page labels them "Composition as of now". Each block shows the five largest groups and folds the rest into "Other". With exactly six groups, all six show by name.

- **Value by asset class** splits total value across asset classes as one bar and a ranked list. The "Count" option switches the same block to the number of assets in each class.
- **Assets by type** counts the assets of each asset type. It counts assets, not the supply issued under them.

**Features in use** sits under the two blocks and lists every feature that at least one asset uses, with the number of assets using it, the most used first. An asset can use several features, so it counts once under each of them and the numbers do not add up to the asset total. The card shows all features, without an "Other" group.

**System value** plots the total value across the chosen period. With comparison on, a dashed line traces the previous period under it, aligned to the same positions, so you read the two shapes against each other. A dot marks each point where at least one asset launched, which often explains a step up in value. A burn, a price change or an exchange-rate change moves the line either way.

**Assets by country**, at the bottom, shades each country by the number of asset contracts domiciled there. Assets with no stored country show beside the map as "No stored country", so the map total counts every asset.

### Inspect the source record [#inspect-the-source-record]

Open **All assets** and search by the asset name, symbol, or contract address to confirm what a count or composition is summarising. For a change in token events, open "Activity", filter by event type, and sort by time to find the events behind it. Base an operational decision on the record, since the figures are as current as the indexer.

## Insights on other screens [#insights-on-other-screens]

"Offerings" and "Venues" each have their own **Insights** tab, described on [Offerings](https://docs.settlemint.com/docs/console/asset-lifecycle/primary-offerings#read-the-offerings-insights) and [Venues](https://docs.settlemint.com/docs/console/asset-lifecycle/venues#read-the-venues-insights).

"Votes", under "Wealth", has one for accounts that manage votes, described on [Governance](https://docs.settlemint.com/docs/console/my-assets/votes).

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

- Confirm the organisation and network shown in the Console header.
- The page shows three figures, an attention card for each count over zero, and both composition blocks with values.
- An "Unavailable" figure with a "Try again" button, or a "Value by asset class" block that reads "No asset has a priced value yet." beside non-zero figures, is covered under [Troubleshooting](#troubleshooting).
- In **All assets**, compare the status of the assets concerned with the attention counts.
- In "Activity", compare the operations you find with the "Token events" figure for the same period.

## Troubleshooting [#troubleshooting]

**A recent transaction seems missing from the figures**

Signal: a transaction you know confirmed does not show up in a figure or on the chart. Cause: Insights reads from
indexed data, not the chain directly, so a lag between confirmation and indexing does not mean the transaction failed.
Fix: look for "Figures are behind the chain" over the range selector, which a platform administrator or organisation
owner sees, and select **View status** to open [Platform status](https://docs.settlemint.com/docs/console/organisation-settings/platform-status)
when the link is offered. Any other account confirms the transaction on "Activity", or on a block explorer for the
network, and waits for the figures to catch up rather than assume the operation failed.

**The page shows an empty state instead of the briefing**

Signal: the page reads **No assets yet** and says charts and statistics appear once you issue your first asset,
instead of any figure. Cause: the active organisation holds no assets on the active network, which the Console
distinguishes from a slow load. Fix: confirm the organisation and network chosen in the account menu match where
assets were issued. The empty state offers "Issue asset" to start a new asset.

**A figure reads Unavailable**

Signal: one figure shows "Unavailable" and a "Try again" button while the rest of the page renders normally. Cause:
each figure runs its own read, so one failed read never blanks the others. Fix: select **Try again** on that figure.
It repeats only that read.

**The total value says priced assets only**

Signal: the "Total value" label reads "Total value, priced assets only" and an attention card reads "Value excludes
unpriced assets". Cause: at least one asset has no price that converts into the base currency, so its value is left
out of the total rather than counted at zero. Fix: a holder of the "Feeds manager" role follows **Set up price feeds**
and adds the missing feed. Any other account asks that role holder to do so. The total and every value figure rise
once the price is available.

**No change figures or dashed line appear**

Signal: the figures show no change against an earlier period, and the chart has no dashed line. Cause: **Compare with
prior period** is off, or the range is "All", which has no earlier period. Fix: choose a bounded range and turn the
switch on.

## Frequently asked questions [#frequently-asked-questions]

### Why does Assets halted include assets that have not launched?

A new token starts halted and launches the first time its transfers are resumed, so an asset still pending launch shows as halted. **Assets halted** counts every asset halted right now, which is what the status column in "All assets" shows. "Launches pending" counts the assets that have never launched. Any halted asset beyond the pending launches was launched and then halted again.

### Why can the Launched change and the launch dots disagree with the created count?

**Launched** and the chart dots follow launches, which happen when an asset's transfers are first resumed, not when it is created. An asset created last month and launched today adds a dot today and raises this period's "Launched" figure, while the created count moved last month. Read "Launches pending" for the gap between the two.

### Does Insights update while I keep the page open, or do I need to reload it?

It refreshes as new blocks on the active network are indexed, so an on-chain change appears without a reload once the indexer has caught up.


# Issue asset

Source: https://docs.settlemint.com/docs/console/asset-management/issue-new-asset
Configure and deploy a new asset from an instrument template your organisation published, in the Console.

Issue asset deploys a new token from an instrument template that your organisation has published. The token is a composable token, one contract that carries the template's features, metadata fields and compliance rules from the moment it exists. The wizard creates only this kind of asset, called a DALP asset. The template you pick on the first step decides which later steps appear and which fields they ask for.

Decide the template, the role holders and the compliance values before you start. To list or edit tokens that already exist, use [All assets](https://docs.settlemint.com/docs/console/asset-management/all-assets).

![Issue asset on the Instrument step, with published templates in one table under Choose an instrument](https://docs.settlemint.com/docs/screenshots/console-issue-new-asset.light.en.webp)

[Screenshot] The first step, "Instrument", lists under "Choose an instrument" the templates your organisation has published in one table, with a search field and the "Class" and "Features" filters.

Each row carries a radio, the template's name with a short description, its class, its feature count and the assets
issued from it.

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

- You need the Asset manager role on the organisation's system, held by the wallet you act with. When no wallet of yours holds it, the **Issue asset** buttons on "All assets", the dashboard and the empty states are hidden, and a direct link shows "Not available". When the role sits on another of your wallets, the button is disabled and a line under it names that wallet and asks you to switch to it. A direct link still opens the page in that case, but the platform checks the role on the wallet you act with when you submit and refuses the creation until you switch.
- The wallet you act with issues the asset, so it also needs an on-chain identity. An Identity manager creates it, and the first step tells you when your wallet has none.
- Have your PIN or one-time code ready.
- Choose the active organisation before you start, since the deployed token belongs to whichever organisation is selected in the Console header.
- Every instrument template deploys through the system's **DALP asset** factory. Until a system manager registers that factory on [Factories](https://docs.settlemint.com/docs/console/organisation-settings/factories), Issue asset shows "No instruments yet" in place of the steps.
- If the template pays fees, yield, or a maturity redemption in a denomination asset, that asset must already exist in the organisation as a registered ERC-20 token. When none exists, the instrument-template picker disables that template's radio and labels the row "Needs a denomination asset", or "Needs a target token" for a template that converts into another token. The row's details offer **Issue a stablecoin**, or "Issue a conversion target token" for a target token, and, for a denomination asset, "Register an external token". Any token the organisation holds satisfies the check, and it need not be a stablecoin.
- If the denomination-asset field on "Instrument details" still has nothing eligible to choose, a "No eligible denomination assets exist yet" alert appears beside it. Its "Issue a stablecoin" link opens the wizard in a new tab, and its **Register an existing stablecoin** button registers a token that is already deployed without leaving the page. Reopen the dropdown afterwards to pick it up. Feature settings that take an ERC-20 token, in the wizard and in an asset type template, use the same picker. It lists only the organisation's tokens and accepts no other pasted or recent address. It checks that a contract is deployed at the chosen address on the current network, and the settings cannot be saved until one is. When the field is editable and no token qualifies, it shows the same alert. When you submit, the platform reads the token's symbol and decimals from the chain again. A token that looked eligible earlier still fails this check if its metadata cannot be read.

## Steps [#steps]

The steps run in a fixed order:

1. **Instrument**.
2. **General info**, titled after the template once you pick one, such as "Corporate Bond information".
3. **Instrument details**, when the template leaves values for you to set.
4. One step per compliance module the template's policy leaves open.
5. **Holder rule**.
6. **Asset permissions**.
7. **Token logo**.
8. **Review**.

Selecting the template also sets the asset class, so there is no separate asset class step.

A structure is a set of linked templates issued together, such as a dual-class share or a convertible note. For a structure, the draft card at the top of the step list names the structure and its number of classes. The list gives each class its own section, such as "Controlling class" and "Economic class", with that class's instrument under the heading. Each class's "General info" step shows the token name and symbol entered for it, or "Not set" until you enter them, so a class you have filled in stays in view while you work on the next.

Nothing reaches the chain until you confirm the summary with your wallet verification. A deployment that succeeds cannot be undone or deleted from the Console. A failed attempt keeps your entries, so you can correct them and try again.

### Choose the instrument [#choose-the-instrument]

Open "Assets", then "All assets", and select **Issue asset**. The page keeps the Console sidebar and top bar and shows the heading "Issue asset". On a wide screen a list of steps sits beside the form. On a narrower screen a bar with a "Steps" button replaces it. Each step ends with "Back" and a button that names the next step.

The first step, **Choose an instrument**, is one table of the templates your organisation has published and not hidden. Each row has a radio, the name with a one-line description, its class, how many features it includes, how many assets your organisation has issued from it and the date of the latest one. Search by name or description, narrow the rows with the "Class" and "Features" filters, or sort any column. Select a row, with its radio or anywhere on the row, to open its detail below it: the full description, the included features, with the ones you set at issue marked "You set", the compliance policy and its controls, and the asset class. A template that needs a token your organisation does not have yet keeps its radio disabled and shows a "Needs a denomination asset" or "Needs a target token" label. Select the row to see what is missing and how to add it.

Three DALP Library templates start published in every organisation: Common Equity, Corporate Bond and Fiat-Backed Stablecoin. Every other template appears after someone with the Permission manager, System manager or Asset designer role publishes it on [Instrument templates](https://docs.settlemint.com/docs/console/asset-design/instrument-templates). A structure, such as a dual-class share or a convertible note, is listed only when your organisation has published the structure and every template in it, and none of them is hidden. Both DALP Library structures start unpublished, so the list leaves them out until someone publishes them on the **Structures** tab of [Instrument templates](https://docs.settlemint.com/docs/console/asset-design/instrument-templates#publish-an-instrument-structure-for-your-organisation).

A template stays visible but disabled, with the label "Needs a feature factory", when one of its features has no feature factory on your organisation's system. Every DALP Library template that uses holds, such as Fiat-Backed Stablecoin, reads this way on a system that predates DALP 3.2 until its Hold factory is installed. Select the row to see which features are missing. A System manager gets **Open Factories**, which opens [Factories](https://docs.settlemint.com/docs/console/organisation-settings/factories) to deploy them. Anyone else reads that a System manager deploys them. Once the factory is indexed, the row is enabled.

When you hold one of those roles, a line under the list reads "You can publish more templates from the instrument templates overview." with an **Open instrument templates** link. When your organisation offers no template, the step shows "No instrument templates yet" in place of the list. With a managing role you get the same link. Without it, the step tells you to ask an asset designer or administrator. When a search matches nothing, the search box stays and the list reads "No results found", with "Try adjusting your filters to find what you're looking for."

This step also checks your wallet. When it has no on-chain identity, the step shows "Your wallet has no identity yet", names the wallet, and offers "Copy wallet address" and **Check again**. The continue button stays disabled until an Identity manager creates the identity, because creating the asset would fail after you enter your PIN.

Picking a template sets four things at once. The figure shows the four and which entries a change of template resets.

[Figure] One template choice on step one fixes four things at once. Picking a template on the first step fixes four things together: the asset class, whether a denomination asset must already exist, which compliance steps appear if any, and which fields the later steps ask for. Switching to a different template resets the instrument details, metadata values and compliance values to the new template's defaults. Labels: One choice, step one; Template; Asset class; fixed the moment you pick; Denomination requirement; only if the template needs one; Compliance steps; only when values are left open; Later-step fields; which fields the rest ask for.

Switching to a different template resets the instrument details, metadata values and compliance values to the new template's defaults.

### Enter the asset basics and instrument details [#enter-the-asset-basics-and-instrument-details]

The step after **Instrument** is titled after the template, for example "Corporate Bond information". A built-in template shows its name in your language. An organisation's own template shows its name as typed. Enter:

- **Name**: required, at most 50 characters. A name of only spaces is refused with "Name cannot be blank."
- **Symbol**: required, uppercase letters A to Z and digits only. The field takes up to 12 characters and fills itself from the name until you edit it.
- **Decimals**: a whole number from 0 to 18. The default is 18. An empty or out-of-range value reads "Decimals must be a whole number from 0 to 18."
- **Jurisdiction**: the country recorded on the token's identity at creation. It does not restrict which countries holders come from. Country compliance modules do that.
- **Base price** with its currency: required, except on a template with maturity redemption, where the price comes from the face value and denomination asset you set next. The price must be greater than zero. The field refuses zero and a negative price with the same message.

When an asset in your organisation already has the same name, symbol and decimals, a warning names it and suggests changing one of the three. The warning does not block the step. When the factory already holds an asset with the same name, symbol, decimals and asset type, the deployment view ends on "`<asset name>` was not issued".

**Instrument details** follows when the template leaves feature values or metadata fields for you to set. It shows only those values, within the minimum and maximum the template allows. Issue asset does not ask for a value the template fixed.

Each group of values is a section with its name on the left and its fields on the right. The template's own metadata comes first, in groups that fit the instrument: "Issue", "Issuer" and "Terms" for a bond, "Issuer" and "Reserve" for a stablecoin, "Identifiers", "Issuer" and "Share terms" for equity, and "Identifiers" and "Fund" for a fund. Any other template shows its fields in "Identifiers", "Issuer" and "Details". One section per configurable feature follows, such as "Maturity and redemption", "Fixed treasury yield", "Dividend yield" or "Management fee". Identifier fields such as ISIN and LEI carry a short line that gives the format, and a value that fails its check shows a warning under the field without blocking the step. Where values combine, a line under the fields shows the result as you type: what each coupon pays per token, the redemption amount on the maturity date, or the fee on a transfer, burn or mint of 1,000 tokens.

A value that a feature section already asks for is entered once, in that section. The metadata section shows it as read-only text, for example "Same as Maturity and redemption below" for a bond's maturity date and "Same as Management fee below" for a fund's management fee. Where a form shows one, it reads "Fixed by the template:" followed by the value. An amount that a feature holds in another token, such as a bond's face value in its denomination asset, is entered in whole units of that token, and the field shows that token's symbol once you choose it. A date field, such as a bond's **Issue date**, shows the day written out, for example "10 Nov 2026", the same way the "Maturity date" field and the review step show it.

A date field takes a day up to 100 years ahead. When the template sets a "Lower bound" or an "Upper bound" on the field, that day is the earliest or the latest it takes. It refuses a typed day outside that range, such as `9999-12-31`, and a day that does not exist, such as `2026-02-30`. A money amount, such as a tokenized bank deposit's "Insurance limit", cannot be negative. Each field shows a message under it when it refuses an entry. **Continue** stays unavailable until you correct the value or clear an optional date.

When the Console assistant is on and its data scope is **Send documents**, both steps offer to read a term sheet PDF of up to 20 MB and fill the fields it states. [What the assistant sends](https://docs.settlemint.com/docs/concepts/operating/assistant-data) covers that setting. Each filled field shows the page and words it came from. Check every field before you continue.

### Fill in the compliance details [#fill-in-the-compliance-details]

Each compliance module that the template's policy leaves open for issuers gets its own step under **Compliance details**, titled with the module's name, such as "Country allow list". A policy can apply the same module more than once. Each instance then gets its own step, marked "Inherited from template (N rules)" and "Rule 1 of N". The step shows the module's parameters with the policy's values filled in, and an "Applies to" line with the senders and receivers the rule checks. The scope comes from the policy and cannot be changed here.

A control the policy requires without configuring it gets a step too. A module the policy fixes for issuers, by turning **Make configurable in Issue asset** off, gets no step. Its values come from the policy and are installed as they are. [Policy templates](https://docs.settlemint.com/docs/console/compliance/policy-templates) explains that choice, and [Compliance modules](https://docs.settlemint.com/docs/concepts/compliance-and-identity/compliance-modules) describes each module's parameters.

When the country rules contradict each other, for example a country on both an allow list and a block list, the step and the summary show **Contradictory country rules** and explain who can no longer receive the asset. The warning does not block you, so read it before you continue.

When the Console assistant can draft, as set on [Assistant](https://docs.settlemint.com/docs/console/organisation-settings/assistant), each compliance step starts with "Write the policy". Write the policy in your own words and select **Read the policy**. "Fill N rules into the design" then writes each rule's values into the matching step and adds a step for a rule the policy does not bring, and a message says how many steps were filled. Nothing is installed until you create the asset. After creation, the platform stores the policy text with the asset.

A capital raise limit needs the system's price resolver add-on. Creation is refused when the system has none. The platform fills in the resolver and the price topic for you when it is installed.

### Choose the holder rule [#choose-the-holder-rule]

On **Holder rule**, state who may hold the token. The step has no default you did not choose. Pick one of three options:

- **Policy template**: use the identity verification rule of a compliance template. The step preselects your organisation's default template when it has a holder rule.
- **Custom expression**: build the rule from claim topics in the expression builder.
- **No holder requirement**: write no rule. Only wallets registered in the system identity registry and not marked lost can hold the token.

You cannot continue until you choose. Creation writes the rule to the token's identity registry and shows it as a **Writing holder rule** step of the deployment. You can change it later on the token's Compliance tab. See [Capacity topics](https://docs.settlemint.com/docs/concepts/compliance-and-identity/capacity-topics) for admitting custodians.

### Assign the initial permissions [#assign-the-initial-permissions]

On **Asset permissions**, decide which accounts hold which roles on the new token. Your own wallet is always listed with Permission manager, Governance, Supply management and Emergency. These four roles show "Required for the creator" and cannot be switched off. Together they let your wallet mint, launch and halt the token, change its features, compliance and documents, and grant any role on it to any wallet, your own included. Your wallet can add Custodian to itself and force a transfer, and a role grant waits for a second person only while the "Administration" row protects the "Role management" group. Move roles to other wallets from the token's page after it deploys when your rules keep them apart.

Select **Add permission** to give another account any of Permission manager, Custodian, Emergency, Funds manager, Governance, Offering admin and Supply management. Custodian can freeze balances, force a transfer out of any holder's wallet and recover a lost wallet's tokens, even while the token is halted. [Roles and permissions](https://docs.settlemint.com/docs/console/organisation-settings/admins-and-roles) describes each role. The zero address cannot hold a role. Removing a row offers an undo for a few seconds. When your organisation has [segregation of duties](https://docs.settlemint.com/docs/concepts/compliance-and-identity/roles-and-segregation-of-duties) rules, the platform checks the assignments when you submit, your own four roles included, and refuses a create that would give one account two roles those rules keep apart.

### Add a logo [#add-a-logo]

"Token logo" takes a PNG, JPEG or WebP image of at most 5 MiB and 2048 by 2048 pixels, and square images work best. Select **Skip for now** to keep the generated disc. You can add or replace the logo later from the token page. When the upload fails, retry it or skip the step.

### Review [#review]

**Review** shows one section for each step you completed: "Instrument", "Basics", "Instrument details", "Compliance", "Holder rule", "Permissions" and "Logo". "Compliance" shows the policy and one row per control with its settings in words, and "Holder rule" shows the rule and the floor.

Each section has an **Edit** link that returns to that step, and your answers stay. When the template links no policy, a finding above the sections reads "Compliance: None" and "Asset will deploy without compliance controls." The button at the bottom is "Issue asset".

The token starts halted. Select **Open for transfers once issued** under "On issue" to launch it as part of the deployment. Left off, an account with the Emergency role must launch the token with "Resume token operations" before mint and transfer operations work.

When a feature pays in a denomination asset, the summary reads that asset's decimals first. While it loads, the create button stays disabled with "Loading denomination details before creation…". When the read fails, a **Retry** button appears and the create button stays disabled until a retry succeeds.

While you read the summary, the Console asks the platform whether the creation would be refused, using the same checks the creation runs: your role, the active system, the template and its factory, the feature factories the template's features need, the denomination asset, the payout treasury, the issuer identity and the price feed signer. A refusal appears once, as a finding above the sections with its fix, and the create button stays disabled until you correct the cause. The check changes nothing and asks for no PIN. When the check itself cannot run, the summary says so and does not block you, because the creation repeats every check and refuses the same way.

A paired structure is checked the same way, once for each class. The review of a structure lists every class under its own heading. A refusal appears once, as a finding under the class it concerns, and the accept button stays disabled until every class clears the check. Terms that only an accepted issuance run can issue, such as a distribution waterfall, are checked when you accept, not before.

Select **Issue asset** and confirm with your PIN or one-time code in "Confirm asset creation". When the platform refuses the denomination asset or a payout treasury before anything deploys, the wizard returns you to "Instrument details" with the field marked. Any other refusal keeps you on the summary and shows an error notification with its reference.

The Console then opens the deployment view. Its card is titled "Issuing" followed by the asset name, and holds a live list of steps. **Go to activity** in the card footer leaves the page, and the deployment keeps running. When the wallet that pays for the deployment runs short of gas, a "Waiting for gas" notice and a funding prompt appear in the card, and the deployment continues once the wallet is funded. When the connection to the live view drops, a status line reads "Reconnecting. Still deploying…" while the deployment continues on the server. Do not submit again.

The view ends on one of three screens:

- "`<asset name>` is issued": the card shows the asset and its address, and the Console opens the new asset's page. **Open asset** opens it by hand and "Issue another asset" starts a new draft.
- "`<asset name>` was not issued": a notice shows the reason as the platform wrote it, followed by the reference in your language and a "Copy reference" button. The step list shows where it stopped, with the step named in your language. "Back to review" returns you to the summary with your entries in place. **Try again** asks for your PIN and submits the same draft again as a new deployment. When the asset itself was already created and only its setup failed, "Try again" is not offered, because it would create a second asset. The notice says so, and "Open All assets" leads to the row where you finish the setup or discard it.
- "Deployment status unknown": the connection ended or the live view failed before the deployment reported a result, and the asset is most likely still deploying. This screen has no button back to the wizard. Select **Go to activity** and follow the deployment there, and search "All assets" for the name and symbol before you submit again.

A structure deploys one class at a time in its declared order, each with its own steps and summary, and "Review" comes before the first deployment. When a later class fails, the classes already deployed stay live. The footer offers **Resume** followed by the class name, which retries that class with its draft intact.

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

- The deployment succeeded when the card reads "`<asset name>` is issued" and the Console opens the new token's page. On that page, compare the features, compliance rules and role holders with the summary you confirmed. When the logo upload failed, a message says the token was created without it and offers **Open token**.
- A token you did not open for transfers shows "Pre-launch" until a holder of the Emergency role selects **Resume token operations**.
- When the Console opens "Activity" after a successful deployment, the token exists but the Console could not resolve its page. Find it on **All assets** by name or symbol and make the same comparison.

## Troubleshooting [#troubleshooting]

**The Issue asset button is missing or disabled**

Signal: no **Issue asset** button appears, or a direct link shows "Not available". Cause: no wallet of yours holds the
Asset manager role on the organisation's system. Fix: ask a Permission manager to grant the role, then reload. When
the button is disabled with a line that names another wallet, the role sits on that wallet. Switch to it to issue.

**Continue stays disabled on the first step**

Signal: "Your wallet has no identity yet", and a line under the continue button says your wallet needs an identity
before you can issue an asset. Cause: the wallet you act with has no on-chain identity. Fix: copy the wallet address,
ask an Identity manager to create the identity, then select **Check again**. A new identity can take a moment to show.

**Continue stays unavailable on Instrument details**

Signal: the continue button stays unavailable. Cause: a required field is empty, or a field refuses its entry, such
as a day that does not exist, a day outside the field's range or a negative amount. A refused entry shows a message
under its field. Fix: fill every required field, correct a refused value, or clear an optional date. An identifier
warning, such as on an ISIN, does not block the step.

**The template you need is not listed**

Signal: the first step lists fewer templates than the instrument templates catalogue holds, or shows "No instrument
templates yet". Cause: your organisation has not published the template, or has hidden it from Issue asset. Only
Common Equity, Corporate Bond and Fiat-Backed Stablecoin start published. When Issue asset shows "No instruments yet"
instead of its steps, the system has no "DALP asset" factory: ask a system manager to register it on
[Factories](https://docs.settlemint.com/docs/console/organisation-settings/factories). Fix: with the Permission manager, System manager or Asset
designer role, follow the link under the list, or open "Asset design", then **Instrument templates**, and publish the
template. Without that role, ask an asset designer or administrator to publish it. Then reopen "Issue asset".

**Your saved template is no longer available**

Signal: a resumed draft shows "Your saved template is no longer available. Pick another one." and the continue button
is unavailable. Cause: the template you picked earlier was unpublished, hidden or deleted after you saved your draft.
Fix: pick another template, or have the earlier one published again and select it.

**A template cannot be selected**

  Signal: the template's radio is disabled and its row carries a "Needs a denomination asset" or "Needs a target token"
  label. Cause: the template pays fees, yield or a maturity redemption in a denomination asset, or converts into a
  target token, and your organisation has no such token yet. Fix: select the row to open its details. **Register an
  external token** opens the register sheet on the same step and keeps your draft. "Issue a stablecoin", or "Issue a
  conversion target token", restarts Issue asset on the instrument step, filtered to the asset class that token needs.
  Once the token exists, the radio is enabled.

Signal: the row carries a "Needs a feature factory" label and its details name the features. Cause: one of the
template's features has no feature factory on your organisation's system, so the token factory would refuse the
deployment. Fix: a System manager deploys the missing factories from **Open Factories**, or with System updates.
Once the factory is indexed, the radio is enabled. The API refuses the same create with
`TOKEN_CREATE_FEATURE_FACTORY_NOT_REGISTERED` before anything is signed.

**Selecting a template shows an error about its compliance rules**

Signal: **Couldn't apply the template's compliance rules**. Cause: the template's policy names a control that this
environment does not have, names the issuer while your wallet has no identity or wallet on this network, or could not
be loaded. Fix: read the message under the title. Ask an Identity manager to create your identity and try again, pick
another template, or ask your administrator to correct the policy.

**A field is marked after you submit**

Signal: the wizard returns to **Instrument details** with a message on the denomination asset or a treasury field.
Cause: the platform refused the value before anything deployed, for example a denomination asset whose ERC-20 symbol
and decimals cannot be read, or a token contract named as a payout treasury. Fix: choose another token, or name a
wallet as the treasury or leave it empty to pay from the issuing wallet. Then submit again.

**Deployment fails after submission**

Signal: the deployment view ends on "`<asset name>` was not issued" with an error and a "Copy reference" button.
Cause: a deployment failed after submission, for example because the asset duplicates one the factory already holds,
or because the create was refused in simulation before it was sent. A refusal in simulation reads "The create
broadcast was not sent", and nothing reached the chain. Fix: read the error. When "Try again" is offered, nothing was
deployed: fund the wallet or correct what the error names, then select **Try again**, or "Back to review" to change
your entries first. Copy the reference before you contact support.

**The deployment view says it is reconnecting**

Signal: the status line "Reconnecting. Still deploying…" above a list of steps that has stopped updating. Cause: the
live connection to the deployment dropped, but the deployment continues on the server. Fix: wait, and do not submit
again. When the connection recovers, the list continues. When it does not, the view moves to **Deployment status
unknown**.

**A deployment ends with no result**

Signal: "Deployment status unknown" with a "Go to activity" button and no way back to the wizard. Cause: the
connection ended or the live view failed before the deployment reported a result. Fix: do not submit again. Select
**Go to activity** and follow the deployment there. The way back to the wizard is missing on purpose, because
submitting your entries again could start a second deployment.

**A funding prompt appears mid-deployment**

Signal: a "Waiting for gas" notice and a prompt to fund a wallet appear in the deployment card. Cause: the account
that pays for the deployment ran short of gas. Fix: fund the wallet as prompted. The deployment continues once the
funds arrive.

## Frequently asked questions [#frequently-asked-questions]

### If I navigate away partway through, do I lose my progress?

No. The platform saves your draft to your account when you select **Continue**, and again a moment after you stop typing, so Issue asset opens it again in any tab or browser and after you sign in again. The page meta reads "Draft saved" once it is stored, and a notice offers "Try again" when a save fails. What you typed stays on the page meanwhile. There is one draft per person, organisation and network, and it is deleted 30 days after its last save. While a draft exists, the "Issue asset" button on All assets reads "Resume draft". The draft does not hold your PIN or a picked logo. A multi-class structure keeps its drafts in the browser tab only.

Leaving Issue asset for another part of the Console asks "Leave with an unfinished draft?" first. "Leave" keeps the saved draft. "Discard draft" deletes it. The **Discard draft** button beside the page title does the same after you confirm "Discard this draft?".

A draft stays with the person who started it and cannot be handed on.

### None of the available templates fit. Where do I create a new one?

On [Instrument templates](https://docs.settlemint.com/docs/console/asset-design/instrument-templates), under **Asset design** in the sidebar. Check there first for a DALP Library template that fits and is still unpublished. Once a template is published, it appears on the first step of Issue asset.

### Can I add or remove role holders after the asset deploys?

Yes, from the token's own page. **Asset permissions** in this wizard sets only who holds a role at deployment.

### Can an integration check a name or predict an address before it creates an asset?

Yes, through the Platform API, without changing anything. `GET /api/v2/system/factory-address-availability-checks` answers whether a name, symbol and decimals are still free. It also answers that they are free when the system has no factory of that type. `POST /api/v2/system/factory-address-predictions` returns the address of the new token's access manager. Call it with the wallet that will create the asset, because the address depends on that wallet. It answers `422` when the system has no factory of that type.

### Can an integration create an asset without a template?

Only on a deployment whose operator turned on legacy asset creation, as [Upgrade a deployment to DALP 3.2](https://docs.settlemint.com/docs/deployment/upgrade-to-3-2#decide-on-legacy-asset-creation) describes. With that setting off, the default, `POST /api/v2/tokens` refuses every classic asset type with HTTP 422 and `TOKEN_CREATE_ASSET_FAMILY_DEPRECATED`, with or without a template. With it on, `POST /api/v2/tokens` takes `templateId` as optional when `type` is `bond`, `equity`, `deposit`, `fund`, `stablecoin`, `precious-metal` or `real-estate`, and requires it when `type` is `dalp-asset`, the type every instrument template deploys. A classic asset created without a `templateId` is not held to any template, so publication, "Hide from Issue asset" and a template's policy do not apply to it. The caller still needs the role that creating a token requires.

With a `templateId`, a classic type is checked only for a template that is published and not hidden in your organisation. A template that declares features is refused for a classic type with `TemplateFeaturesUnavailable`, because a classic token cannot take features. The template's parameters and metadata apply only to `dalp-asset`.

### If I leave the token halted, can I launch it later?

Yes. In the Console, your wallet always receives the Emergency role at creation, whether or not you select "Open for transfers once issued". Launch the token later: on its page, open "Actions" and select **Resume token operations**. To let another wallet launch it, grant that wallet the Emergency role on "Asset permissions" or later from the token's page.


# Booked movements

Source: https://docs.settlemint.com/docs/console/asset-management/manage/booked-movements
Keep a share class token in step with a transfer agent's register: while the feature is attached, units move only when the administrator books a movement.

Booked movements keep a share class token in step with a share register that a transfer agent or fund administrator keeps off chain. The register stays the source of truth. Every change to a holding is a movement. An investor can request it, or the administrator can enter it directly, and only the administrator's booking, with the reference of its register entry, moves the units, in the same transaction. While the feature is attached, the token refuses every mint, burn, transfer, forced transfer and wallet recovery that is not the booking of a movement. The platform stores the register reference you enter and does not check it against your register, so match the two on [Reconciliation](https://docs.settlemint.com/docs/concepts/records-and-evidence/reconciliation).

The movements page and the Investor portal call the feature "Booked movements". The token's **Features** tab lists it as "Register lines", and the Platform API calls each movement a register line.

Each share class is its own token. The Share-Class Mirror template records the class name in its **Share class** field, and a movement belongs to one token, so a switch between classes is a redemption booked on one class token and a subscription booked on the other.

![Booked movements page of a share-class mirror token with the Configuration panel and the Requested movements table](https://docs.settlemint.com/docs/screenshots/console-booked-movements-page.light.en.webp)

[Screenshot] The "Booked movements" page with the "Configuration" panel and the "Requested movements" table.

The title row carries "Book a movement". The "Configuration" panel shows the movement count, the requested movements waiting for the administrator, and "Investors can request" with "Edit". The "Requested movements" table lists each movement's number, type, parties, amount and request date, with a "Book" action.

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

- **A token with Booked movements.** Issue the token from the Share-Class Mirror template on [Issue asset](https://docs.settlemint.com/docs/console/asset-management/issue-new-asset). The template attaches Historical balances, Hold and Booked movements and has no compliance policy, because the register decides who may hold the class. Historical balances lets a [dividend yield](https://docs.settlemint.com/docs/concepts/modeling-assets/token-features/income#dividend-yield) feature attach later and pay on the booked balances. A new token starts halted unless you check "Open for transfers once issued". Select "Resume token operations" in the token's "Actions" menu to launch it before the first booking. An account with Governance plus Supply management and Custodian, or Governance plus the admin role, can also attach Booked movements to an existing token, under "Attach a feature" on the token's "Features" tab, where the sheet asks which moves investors can request, or through the [token feature endpoints](https://docs.settlemint.com/docs/api-reference/v2). Attach Hold first, from "Attach a feature" on the same tab, or the attach is refused.
- **The right role on the token.** The "Who can do what" table lists the role each task needs. The token's Permissions tab shows who holds each role.
- **Verified recipients.** The token checks the recipient's identity on each booking. A booking that sends units to a wallet without a verified identity reverts, and a requested movement then stays requested. Register the investor's identity before you book their first subscription.
- **Wallet verification.** Booking, rejecting, cancelling and saving the request settings each ask for your wallet verification, the PIN code or authenticator code you set up under [Security](https://docs.settlemint.com/docs/console/my-account/security). The investor's requests and withdrawals in the Investor portal ask for it too.

## Who can do what [#who-can-do-what]

| Task | Who can do it |
| --- | --- |
| Open the Booked movements page | Any signed-in user, when the feature is attached. Administrators with the Supply management or Governance role see every movement. Anyone else sees the movements their own wallets give, receive or opened. |
| Book or reject a requested movement, book directly, mint or burn | An administrator with the Supply management role |
| Force a transfer on a token with Booked movements | An administrator with the Supply management role. The **Forced transfer** page also asks for the Custodian role, but **Book a movement** with **Transfer** moves a holder's units without their request on Supply management alone. |
| Change the moves investors can request | An administrator with the Governance role |
| Request a subscription, transfer or redemption | An investor, for their own wallet |
| Cancel a requested movement before it is booked | The investor who opened it, or a Supply management administrator |

## Steps [#steps]

### Open the movements page [#open-the-movements-page]

Open the token and select its **Features** tab. Under "Records", the "Register lines" section shows two counts, "Requested" and "Movements", and the link "Open the register". The link opens the "Booked movements" page. A token without the feature shows "Booked movements are not enabled for this asset" on that page.

The page holds one panel and two tables:

- The **Configuration** panel shows the number of movements, the number of requested movements with "waiting for the administrator" while any wait, and "Investors can request" with the moves investors may request.
- The **Requested movements** table appears only while at least one movement waits.
- The **Movement history** table lists every movement with its "Movement" number, "Type", "From", "To", "Amount", "Register reference", "Corrects", "Status" and "Decided" date. "Opened" is a column you can show. A movement's status is "Waiting for the administrator", "Booked in the register" or "Cancelled". The table filters by type and status.

A user who lacks Supply management sees **Book a movement** disabled, and a user who lacks Governance sees "Edit" disabled. Each gives "Supply management holders book movements. Governance holders set what investors can request." as the reason.

### Book or reject a requested movement [#book-or-reject-a-requested-movement]

In **Requested movements**, open the row's actions. A Supply management administrator sees "Book" and "Reject". An investor who opened the request and holds no Supply management role sees "Cancel request" on their own rows only.

"Book" opens "Book movement #" followed by the movement number. Enter the "Register reference", the entry number or identifier your register gave this movement, such as `DBMF-REG-0003`, and continue. The "Review the booking" step repeats the movement and says "The units move as soon as you book the movement." Select **Book movement** and confirm. The platform releases the units the request reserved under the Hold feature and moves them in the same transaction. If the transaction reverts, nothing moves and the request stays requested with its units held. The movement shows "Booked in the register" with its reference.

"Reject" opens "Reject movement #" followed by the number: "The investor's units are released and the movement is cancelled." The review notes "A rejected movement can't be booked again. The investor can send a new request." Select **Reject movement** and confirm. No units move, and the movement records who cancelled it.

The **Book movement**, "Reject movement" and "Book directly" sheets, and the "Mint", "Burn" and "Forced transfer" sheets on a token with Booked movements, ask the platform whether it would accept the write while you fill the form. A refusal shows in the sheet with its reason and fix, for example that the movement is already booked, that the holder's unfrozen balance falls short of the amount, or that a register reference is missing, and the review button stays off until you change the entry. You learn it before you enter your wallet verification. The check books nothing and signs nothing. If it cannot answer, it does not block you and the write returns its own refusal. The Investor portal's request and withdraw sheets run the same check, so an investor sees the refusal before the wallet verification as well.

![Book movement #3 sheet with the Register reference field](https://docs.settlemint.com/docs/screenshots/console-booked-movements-book-sheet.light.en.webp)

[Screenshot] The sheet is titled "Book movement #3" and its "Details" step asks for one required field, "Register reference", the reference of this movement in the register.

"Review" shows the movement before you confirm.

### Book a movement directly [#book-a-movement-directly]

Select **Book a movement** on the title row. The sheet books a move that no investor requested: "Record a move in the register and apply it to the token in one step."

1. Choose the **Type of movement**: "Subscription", "Redemption", "Transfer" or "Correction".
2. Enter the parties. A subscription asks for **To**, the holder who receives the units. A redemption asks for "From", the holder whose units leave. A transfer asks for both, and the two must differ.
3. Enter the **Amount**. When units leave a holder, the sheet shows "Available to move" with the holder's balance less frozen units and less the units their open requests hold. A larger amount shows that it is more than the amount available, and the sheet cannot continue.
4. Enter the **Register reference**.
5. Continue to "Review the movement", which notes that the movement is booked and the units move right away. Select **Book movement** and confirm.

![Book a movement sheet set to Subscription, with To, Amount and Register reference](https://docs.settlemint.com/docs/screenshots/console-booked-movements-direct-sheet.light.en.webp)

[Screenshot] The "Book a movement" sheet set to "Subscription", with "To", "Amount" and "Register reference".

"Amount" takes whole units of the token, and "Review" stays disabled until the fields are filled.

### Correct a booked movement [#correct-a-booked-movement]

A booked movement is not edited after booking. To fix a mistake, book a new movement that corrects it. In "Book a movement", choose **Correction**. Enter "From", "To" or both, as the correction needs, the "Amount" and the "Register reference", then pick the booked movement it fixes in "Movement to correct". The list shows the most recent booked movements by number and register reference.

For example, a subscription of 1,000 units booked as `DBMF-REG-0003` should have been 100 units. Book a correction from the holder for 900 units with the reference `DBMF-REG-0004` and pick `DBMF-REG-0003` in **Movement to correct**. The holder then holds 100 units, and the "Corrects" column of the correction names the original movement.

### Mint, burn or force a transfer [#mint-burn-or-force-a-transfer]

On a token with Booked movements, the "Mint tokens", "Burn tokens" and "Forced transfer" pages in the token's **Actions** menu book a movement. Each page takes one row only and adds a required "Register reference" and an optional "Corrects movement", which lists booked movements and defaults to "No correction". The page cannot continue until you enter a reference. On success the message reads "Movement booked".

A mint books a subscription to the recipient. A burn books a redemption from the holder. A forced transfer books a transfer between the two holders. A booked movement is not charged a transaction fee, so the mint and burn pages show no fee. On a token without Booked movements, these pages stay as [Mint and burn](https://docs.settlemint.com/docs/console/asset-management/manage/mint-burn) and [Transfers](https://docs.settlemint.com/docs/console/asset-management/manage/transfers) describe them.

### Choose what investors can request [#choose-what-investors-can-request]

In the "Configuration" panel, a Governance administrator selects **Edit** beside "Investors can request". The sheet "Moves investors can request" has one checkbox each for "Subscription", "Transfer" and "Redemption": "Choose which moves an investor can ask for. Administrators can always book any movement." A Supply management administrator can book any movement type, subject to the checks under [What the platform checks](#what-the-platform-checks). You can clear all three, and the panel then shows "None". The review notes "Investors can no longer request the moves you switch off. Movements already requested stay in the queue." Select "Save settings" and confirm.

A token issued from the Share-Class Mirror template starts with all three moves allowed. An issuance or attach that names no moves allows all three.

## What the investor sees in the Investor portal [#what-the-investor-sees-in-the-investor-portal]

The holding page of a mirror token shows a **Booked movements** card: "The administrator books each movement in the register. Your holding changes when they do." The card lists the investor's own movements, newest first. It shows the units still free to request as "Available to request".

- **Request a move.** The card shows "Request subscription", "Request transfer" and "Request redemption" for each move the token allows. Transfer and redemption are unavailable while no units are free. The sheets "Request a subscription", "Request a transfer" and "Request a redemption" ask for the amount, and a transfer also asks for the "Recipient". An amount larger than the free units shows "You can request at most" the free amount with "Open movements hold the rest." Select "Send request". The message reads "Request sent. It is waiting for the administrator to book it in the register."
- **Follow a move.** Each row reads, for example, "Transfer of 40 DBMF to" an address, with its status: "Waiting for the administrator", "Booked in the register" with its register reference, "Refused by the administrator", "Withdrawn by you", "Withdrawn by the requester" when another holder withdrew a transfer to the investor, or "Cancelled".
- **Withdraw a request.** A requested movement the investor opened shows "Withdraw". The sheet "Withdraw request" says "Withdraw this request. Your units are released straight away." The message reads "Request withdrawn."

The Console holding page of a mirror token (**Wealth**, "Portfolio", then the holding) shows the same "Booked movements" card to a signed-in holder, with the same request, follow and withdraw steps, the same checks and the same messages. A token without Booked movements shows no card. On a bank cash-out, "Create redemption line" opens the same "Request a redemption" sheet in the Console.

A transfer from the holding page's ordinary transfer sheet becomes a requested transfer too. It waits as **Waiting for the administrator** and the balance does not change until the administrator books it. When a movement changes state, the card refreshes the holding balance.

![Booked movements card on an Investor portal holding page](https://docs.settlemint.com/docs/screenshots/portal-holding-booked-movements.light.en.webp)

[Screenshot] The holding page with the "Booked movements" card, its request buttons and the investor's movements.

The card shows the units available to request and three movements: two requested transfers waiting for the administrator, with "Withdraw" on the one the investor opened, and a subscription booked in the register with its register reference.

## What the platform checks [#what-the-platform-checks]

### On a request [#on-a-request]

- The token allows this kind of move. A subscription names the investor as the receiver and holds nothing, and an investor has at most one open subscription request per token.
- A transfer or redemption moves the investor's own units. The request holds the amount through the Hold feature until the movement is booked or cancelled, so the investor cannot spend those units elsewhere. The amount cannot exceed the units that are free.
- The amount is more than zero, and the two parties differ.
- The sending wallet is not marked lost, and the token has the Hold feature.
- The participant account that owns the sending wallet does not carry the `securities-transfers` restriction. An administrator lifts it from the participant's account, as [Restrict a wallet](https://docs.settlemint.com/docs/console/participants/restrict-a-wallet) describes.

### On a booking [#on-a-booking]

- The caller holds Supply management, and the movement is still requested.
- The register reference is not empty. A correction names a movement that is booked.
- The move passes the token's own checks. A booking to a wallet that is not verified reverts, and a requested movement then stays requested with its units held.
- A burn or forced transfer cannot spend frozen units or units that open requests hold. The API refuses an amount larger than the holder's balance, less frozen units, less held units, before it sends a transaction. A mint is not checked against a balance.

### On a cancellation [#on-a-cancellation]

The investor who opened the movement or a Supply management administrator can cancel it. Anyone else is refused. The movement records who cancelled it, and the Investor portal shows the difference as "Withdrawn by you" or "Refused by the administrator".

## What a mirror token refuses [#what-a-mirror-token-refuses]

The token refuses every move that is not the booking of a movement. A plain transfer, a mint, a burn, a custodian forced transfer and a wallet recovery sent straight to the contract all revert with [DALP-4481](https://docs.settlemint.com/docs/api-reference/errors/error-code-reference/dalp-4400-4499): "This token only moves through a movement the administrator books." To move a lost wallet's units, cancel its open requests, unfreeze any frozen units, then book a transfer from the lost wallet to its replacement. The booking does not check that the recipient is the wallet paired through identity recovery, and it carries no freeze across, so freeze the units again on the replacement if they must stay frozen.

Other token features and add-ons that move units are refused the same way. Features that do not move units, such as dividend yield, keep working. A dividend yield feature pays holders on their booked balances.

The Platform API turns its own supply and transfer calls into movements, so a client that calls these routes books or requests a movement instead of being refused:

| Call | Route | On a token with Booked movements |
| --- | --- | --- |
| Mint | `POST /api/v2/tokens/{assetId}/mints` | Books a subscription to the recipient. Needs `registerReference`, takes an optional `corrects`, and takes one movement per call. |
| Burn | `POST /api/v2/tokens/{assetId}/burns` | Books a redemption from the holder, under the same rules. |
| Forced transfer | `POST /api/v2/tokens/{assetId}/forced-transfers` | Books a transfer between the two holders, under the same rules. The booking needs Supply management. |
| Transfer | `POST /api/v2/tokens/{assetId}/transfers` | Opens a transfer request from the calling wallet to the recipient for the amount, one transfer per call. A transfer that spends an allowance is not converted, and the contract refuses it. |

A mint, burn or forced transfer without `registerReference`, or with more than one movement, is refused with [DALP-14068](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference#client-request-errors): "A token with booked movements needs a register reference and one movement per call". The same code refuses `registerReference` or `corrects` on a token without the feature.

## Feature combinations [#feature-combinations]

Booked movements needs the Hold feature, which reserves the units of an open request. The Platform API refuses an issuance or attach without Hold, and refuses to detach Hold while Booked movements is attached.

Booked movements cannot sit beside Management fee, Conversion, Conversion minter, Supply delegate or Maturity redemption, because each of these moves the token outside a movement. A template, issuance or attach that combines them is refused.

Corporate actions that move units are not offered on a mirror token: "Stock dividend", "Distribution paid in tokens", "Bond coupon paid in tokens", "Bonus issue", "Rights issue", "Capital decrease", "Stock split", "Reverse split", "Spin-off", "Buyback" and "Partial redemption". A "Cash dividend" or a cash distribution stays available once dividend yield is attached. A fund token with Booked movements also takes no [dealing requests](https://docs.settlemint.com/docs/console/asset-management/manage/fund-dealing), because its subscriptions and redemptions are movements.

The feature cannot be replaced with a new instance, because open requests and the units they hold would stay on the old one. The refusal reads "This feature cannot be replaced while its requested lines may hold units. Change its requestable kinds through the settings route instead." Change the requestable moves on the existing feature instead.

## Detach and attach the feature again [#detach-and-attach-the-feature-again]

Book or cancel every requested movement before you detach the feature, so no units stay held.

An account that can set the feature list (Governance with Supply management and Custodian, or with the admin role) can detach the feature with **Detach** in the actions menu of the "Register lines" section on the "Features" tab, or through the token feature endpoints. While the feature is detached, the token no longer refuses plain moves, the API cannot request, book or cancel the detached instance's movements, and the movement lists keep them as history. A movement that was still requested shows as "Cancelled", dated from the detach, but its units stay held on the chain. Attach the same instance again to book or cancel it and release the units. An attach that names the same moves investors could request when the instance was created brings that instance back: its requested movements show as requested once more and can be booked or cancelled. An attach with any other set starts a new instance with no movements.

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

- On the **Booked movements** page, open "Movement history" and find the movement.
- A booked movement reads "Booked in the register" with its "Register reference" and a "Decided" date.
- A rejected or cancelled one reads "Cancelled", and a request nobody has decided still reads "Waiting for the administrator" and stays in "Requested movements".
- A correction names the movement it fixes in "Corrects". Then open the "Holders" tab and compare the holder's balance with the booked amount, and check the entry on "Activity" against the transaction.
- If the balance does not match, the booking did not land, so read the transaction on "Activity" and the table under Troubleshooting.
- In the Investor portal, the holding page shows the same status on the investor's "Booked movements" card and refreshes the balance when a movement changes state.

## Troubleshooting [#troubleshooting]

Each code below refuses the request as sent. Fix the cause first. Codes about a movement's state can clear once the state changes. The DALP-14000 codes come from the Platform API and the DALP-4400 codes from the token contract.

| Code | Message | What to do |
| --- | --- | --- |
| [DALP-4481](https://docs.settlemint.com/docs/api-reference/errors/error-code-reference/dalp-4400-4499) | This token only moves through a movement the administrator books. | Request the move, or ask the administrator to book it. |
| [DALP-14068](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference#client-request-errors) | A token with booked movements needs a register reference and one movement per call | Send one movement with `registerReference`, or drop both fields on a token without the feature. |
| [DALP-14058](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference#domain-rule-errors) | The movement could not be acted on | The feature is not attached, the movement does not exist on it, or it is already booked or cancelled. List the movements again. |
| [DALP-14096](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference#domain-rule-errors) | The movement was not found | No movement with this number is visible to you on this token. Use a number from the list. |
| [DALP-14097](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference#domain-rule-errors) | A subscription request is already open | Wait until the open subscription request is booked or cancelled. |
| [DALP-14453](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference#domain-rule-errors) | The participant cannot transfer securities | Ask an administrator to lift the `securities-transfers` restriction on the participant account. |
| [DALP-9482](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference#domain-rule-errors) | The holder has insufficient available tokens | Reduce the burn or forced transfer, or wait until open requests end or units are unfrozen. |
| [DALP-4482](https://docs.settlemint.com/docs/api-reference/errors/error-code-reference/dalp-4400-4499) | Movement not found | Check the movement number against the token's list. |
| [DALP-4483](https://docs.settlemint.com/docs/api-reference/errors/error-code-reference/dalp-4400-4499) | Movement cannot change state | Refresh the register and check the movement's state. |
| [DALP-4484](https://docs.settlemint.com/docs/api-reference/errors/error-code-reference/dalp-4400-4499) | Request kind not allowed | Request a move the token allows, or ask Governance to allow it. |
| [DALP-4485](https://docs.settlemint.com/docs/api-reference/errors/error-code-reference/dalp-4400-4499) | Subscription request already open | Wait until the open subscription request is booked or cancelled. |
| [DALP-4486](https://docs.settlemint.com/docs/api-reference/errors/error-code-reference/dalp-4400-4499) | Movement parties invalid | Name two different parties, at most one of them the zero address. |
| [DALP-4487](https://docs.settlemint.com/docs/api-reference/errors/error-code-reference/dalp-4400-4499) | Register reference missing | Enter the register reference. |
| [DALP-4488](https://docs.settlemint.com/docs/api-reference/errors/error-code-reference/dalp-4400-4499) | Corrected movement invalid | Name a booked movement to correct. |
| [DALP-4489](https://docs.settlemint.com/docs/api-reference/errors/error-code-reference/dalp-4400-4499) | Request kinds invalid | Choose any combination of subscription, transfer and redemption. |
| [DALP-4490](https://docs.settlemint.com/docs/api-reference/errors/error-code-reference/dalp-4400-4499) | Wallet marked lost | Request from another wallet, or have the administrator book the recovery. |
| [DALP-4491](https://docs.settlemint.com/docs/api-reference/errors/error-code-reference/dalp-4400-4499) | Hold feature missing | Attach the Hold feature to the token. |
| [DALP-4492](https://docs.settlemint.com/docs/api-reference/errors/error-code-reference/dalp-4400-4499) | Booked movements feature detached | Attach the feature again if you still need it. |

The Console shows **Requested movements could not load** with "Check your connection and try again." and a retry when the queue cannot be read. The Investor portal shows "Your requests are unavailable right now." with "Retry", and "Your account doesn't have access to this information." when the caller cannot read the token's movements. A failed request or withdrawal reads "Your request could not be sent:" or "Your request could not be withdrawn:" followed by the reason.

## Frequently asked questions [#frequently-asked-questions]

### Does booking move the units, or is there a separate settlement step?

Booking is the move. The booking records the register reference and moves exactly the movement's amount in the same transaction, so a booked movement and its unit move succeed or revert together.

### Why is an investor's transfer not refused outright?

The investor's wallet or app sends an ordinary transfer, and the Platform API turns it into a transfer request that holds the units. Nothing moves until the administrator books it. A transfer sent straight to the contract, outside the Platform API, is refused with DALP-4481.

### Can the administrator book a move the token does not let investors request?

Yes. The request settings limit what investors can ask for. A Supply management administrator can book a subscription, redemption, transfer or correction at any time, from any holder and without that holder's request. No setting under **Approvals** holds a booking for a second person.

## API routes [#api-routes]

| Task | Route |
| --- | --- |
| List movements | `GET /api/v2/tokens/{assetId}/features/register-lines/lines` |
| Read one movement | `GET /api/v2/tokens/{assetId}/features/register-lines/lines/{lineId}` |
| Request a movement | `POST /api/v2/tokens/{assetId}/features/register-lines/lines` |
| Book a requested movement, or book directly | `POST /api/v2/tokens/{assetId}/features/register-lines/bookings` |
| Cancel a requested movement | `POST /api/v2/tokens/{assetId}/features/register-lines/lines/{lineId}/cancellations` |
| Set the moves investors can request | `PUT /api/v2/tokens/{assetId}/features/register-lines/settings` |
| Check a request, booking or cancel first | `POST /api/v2/tokens/{assetId}/features/register-lines/preflights` |

The request and response fields of each route are in [the v2 API reference](https://docs.settlemint.com/docs/api-reference/v2).

A booking names either a requested `lineId` with its `registerReference`, or `from`, `to`, `amount` and `registerReference` for a direct booking, with an optional `corrects`. A zero address as `from` books a subscription, and a zero address as `to` books a redemption. The list filters by `state`, `kind`, `holder` and `corrects`. A list filtered by `holder` also returns that holder's balance, the units their open requests hold, and the units still available. A Supply management or Governance administrator lists and reads every movement of the token. Any other caller lists and reads only movements where one of their wallets gives, receives or opened the request, and gets not found for the rest.

The check route takes an `action` of `request`, `book`, `bookDirect` or `cancel` with the fields of the matching write and no wallet verification. It answers `{ "data": { "action", "clears": true } }` when the write would be accepted now, and the error of the write when it would not. The mint, burn and forced transfer check at `POST /api/v2/tokens/{assetId}/preflights` takes the same optional `registerReference` and `corrects` as those writes.

Each webhook event for a booked movement carries `registerLine` with `lineId`, `registerReference` and, for a correction, `correctsLineId`, so a reconciliation job can match it to the register entry. [Reconciliation](https://docs.settlemint.com/docs/concepts/records-and-evidence/reconciliation) covers that job. Composable Token explains how a feature such as Booked movements decides what a token can do, [Token features](https://docs.settlemint.com/docs/concepts/modeling-assets/token-features) covers the Hold and dividend yield features a mirror token uses, and [Booked movements](https://docs.settlemint.com/docs/concepts/records-and-evidence/booked-movements) describes the line model behind each movement.


# Cash dividend and distribution

Source: https://docs.settlemint.com/docs/console/asset-management/manage/cash-dividend
Declare a cash dividend or distribution, read the preview of holder entitlements, fund the treasury, get any approval required, and confirm the holder snapshot.

A cash dividend and a distribution paid in cash are declarations: a corporate action that fixes an amount per share, records which holders are entitled on a record date, and lets each holder claim the payment afterward. You enter the terms, read the preview of holder entitlements, fund the treasury and confirm. The "Actions" menu lists **Cash dividend** on an asset with share capital and "Distribution" on any other asset, and the two carry identical terms. [Corporate actions](https://docs.settlemint.com/docs/console/asset-management/manage/corporate-actions) covers the other event types and the "Corporate actions" tab, and the [dividend yield](https://docs.settlemint.com/docs/concepts/modeling-assets/token-features/income#dividend-yield) feature reference covers the on-chain rules behind the claim.

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

- **The dividend-yield feature and the governance role.** The asset needs the dividend-yield feature attached, and your account needs the governance role on the asset. An emergency halt does not block recording either event. An account with the emergency role can pause the dividend feature itself, which stops every holder claim until it resumes.
- **A second person, where your organisation requires one.** When the organisation has turned on approval for "Corporate actions" in [General](https://docs.settlemint.com/docs/console/organisation-settings/general#approvals), an organisation owner or a platform administrator approves the plan. The approval starts off, and a dividend recorded while it was off still runs on one signature after it is turned on. [Approve a corporate action](https://docs.settlemint.com/docs/console/asset-management/manage/corporate-action-approval) covers the decision.
- **A funded treasury.** The treasury must hold the total payable when you record, or the sheet reads "The dividend exceeds the amount this treasury can move." and does not record. Recording adds an estimated liability, based on the total supply, to the dividend feature's outstanding total. No cash is set aside, so a holder's claim fails while the treasury is short.

## Steps [#steps]

### Enter the terms [#enter-the-terms]

A cash dividend asks for an amount per share, a country code, and three dates: the ex-date, the first day the asset trades without the dividend, the record date, the day holders are counted, and the payment date. The Console rejects a set whose order is wrong and does not reorder it: the record date cannot come before the ex-date, and the payment date cannot come before the record date. Dates may fall on the same day. A cash dividend also asks whether it is a regular or a special dividend. A special dividend is a one-off distribution. The kind is a label: both kinds follow the same date rules, and their dates may lie in the past as long as the token's historical balances cover the record date. The sheet shows the claim deadline. After it, an account with the governance role can reclaim the unclaimed amount, which closes the dividend, and holders who have not claimed can no longer claim on chain.

Type an amount in digits, using your language's decimal separator. An amount the field cannot read, such as `1,5` in English or `1e21`, is named as unreadable. Type a date in your language's numeric format, or as the Console prints it, such as `4 Nov 2026` or `4 Nov 2026, 00:00 UTC`. A day that does not exist, such as `2026-02-30`, is reported as not a valid date. Holders are recorded at the start of the record date, so the record date must begin after the token was created. While any date is unreadable or refused, the sheet blocks the draft and asks you to fix the dates.

Enter the amount per share in the denomination asset's display units. The Console converts it to base units, so do not convert it yourself.

Withholding is applied off-platform. The platform computes no per-holder withholding, and the country code selects no withholding rate: it is stored on the declaration for reference only. Enter the amount per share net of any withholding the issuer applies off-platform, because every entitled holder is paid the amount exactly as declared.

### Record the declaration [#record-the-declaration]

Select **Create dividend draft** or "Create distribution draft" to record it. Despite the name, this declares the dividend on chain. Preview and the cancel button become available after recording. The cancel button reads "Cancel cash dividend", or "Cancel distribution" on a distribution.

### Cancel a declaration [#cancel-a-declaration]

Cancelling the action does not remove the on-chain declaration, so the platform rejects the cancellation of such a record while its dividend is still declared. The dialog then offers the dividend's cancel first: select **Cancel cash dividend**, which cancels the dividend on chain. Once the dividend reads as cancelled, the same button cancels the action. The record then reads "Dividend cancelled", and "Preview allocations" and "Pay dividend" or "Pay distribution" are disabled because nothing is left to pay. If the dividend's status cannot be read, the sheet says so next to the disabled "Cancel cash dividend" and offers "Check again". An action cancelled before any transaction was sent reads "Cancelled" in the history. After the dividend's holder snapshot is recorded, the dividend can no longer be cancelled, so confirm the action instead.

### Read the preview [#read-the-preview]

The preview opens once the record date has passed on chain. Select **Preview allocations** and verify with your wallet to compute it. It renders in the declaration sheet. After you close the sheet, the action has its own record page on the "Corporate actions" tab: select "Resume", "Review" or "View" on its run in the "In flight" card to open it. A finished declaration opens from its row in "History". The record page shows the same preview and carries every later step. It leads with the aggregate the approval is usually written against: the entitled holder count, the totals, and the remainder. The per-holder allocation table sits below it, paged, so a large holder book does not bury the summary. The first figure in a row is the holding the entitlement was calculated over, which can differ from the balance the holder carries when you read the preview: the column is titled with the asset's symbol and the record date, such as "EQKBDTS9 held on" followed by the date, and a holder the record-date read cannot place shows a dash there instead of a figure. When you confirmed the declaration without a record date, the title drops the date and reads "EQKBDTS9 held", and the snapshot cell above the table says "Live register". Preview calculates allocations without changing holder balances.

The preview flags these cases. A holder whose entitlement floors to zero needs no acknowledgement: the preview names the count in one line under the holder table. A holder the operator leaves out, for example one whose identity is no longer verified, is a warning you have to acknowledge before you continue. A funding shortfall renders as a funded-against-declared comparison with its own acknowledgement. When approval is off, the shortfall does not block you, and holders who claim while the treasury is short are refused until it is funded. When approval is on, the second person cannot approve a plan that shows a shortfall. Where an earlier run under the same snapshot identity already applied to a holder, that holder is listed as excluded with the reuse as the stated reason, and the entitled count excludes them. The preview also excludes units the treasury held at the record date from the entitled count, the totals, and the amount required, and shows them as **Treasury units excluded** when the treasury held any. Treasury shares earn no dividend, so if the treasury held every unit, no other holder is entitled and preview fails.

### Fund the treasury [#fund-the-treasury]

A second person cannot approve a plan that shows a funding shortfall, so fund the treasury with the required denomination asset and preview again before the plan goes for approval. Each preview reads the treasury balance freshly, so a stale shortfall does not carry forward once you have topped up. On a cash dividend you can fund from the preview with **Fund dividend**. Once that funding lands, the notice reads "Funded since this preview". Until a new preview lands, the old shortfall and its acknowledgement are hidden and "Pay dividend" or "Pay distribution" stays disabled. Reading the figures again needs your wallet authorisation, so the Console does not do it on its own: select "Preview again" to continue. Each new preview restarts the approval.

### Get the plan approved [#get-the-plan-approved]

When the organisation has turned on approval for "Corporate actions", preview sends the plan to a second person. The sheet, and the action's record page after it, read **Waiting for a second person**, and "Pay dividend" or "Pay distribution" stays unavailable until the plan is approved. While the approval is off, or nobody else could give it, the sheet reads "This action runs without a second signature" and you confirm the plan yourself. [Approve a corporate action](https://docs.settlemint.com/docs/console/asset-management/manage/corporate-action-approval) covers the decision, its 72-hour window, and when the approval is skipped.

### Pay the dividend or distribution [#pay-the-dividend-or-distribution]

Open the action's record page once the plan is approved. If the treasury funding falls between the preview and the confirmation, the confirmation is refused and you preview again. Funding added after the preview is recorded with the confirmation.

"Pay dividend" or "Pay distribution" becomes available only after a preview has rendered and the required acknowledgements are complete. Select **Pay dividend** or "Pay distribution" when the result matches the approval. It sends the previewed totals and the Merkle root, a compact fingerprint of every holder's entitlement, and commits the dividend snapshot, and holders claim payment afterward.

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

- Open the action's record page from "History" on the "Corporate actions" tab.
- A confirmed declaration reads **Payment scheduled** until its payment date and "Settled" after it.
- Payment happens when each holder claims, so compare claimed amounts with the allocation before you report the payout as made.
- A frozen holder cannot claim a dividend, and a custodian cannot push one to them, until the freeze is lifted.
- A declaration you stopped reads "Cancelled" in History.
- Before you cancel the action itself, its record reads "Dividend cancelled" once the dividend is cancelled on chain.
- The record page of an action whose dividend is cancelled offers no preview. "Close this record" ends the action, and "Keep this record" leaves the page without changing it.

## Troubleshooting [#troubleshooting]

A payout-ineligible refusal and "The holder book moved after the preview" are covered under [Corporate actions](https://docs.settlemint.com/docs/console/asset-management/manage/corporate-actions#troubleshooting).


# Token conversion

Source: https://docs.settlemint.com/docs/console/asset-management/manage/conversion
Convert a convertible note, SAFE or warrant into a share token against a published round, as an issuer, a custodian or a holder, and read what each side sees.

Token conversion turns units of a convertible instrument, such as a convertible note, a SAFE or a warrant, into newly minted units of a share token at the price of a funding round. The issuer publishes each priced round as a trigger. Holders then convert their own units against an open trigger, or a custodian converts for them. The platform settles the convertible units under the token's [debt method](#how-a-conversion-is-priced) and mints the shares in the same transaction. The terms themselves, such as the discount, the cap and the debt method, are fixed when the token is created and are listed under [Conversion](https://docs.settlemint.com/docs/concepts/modeling-assets/token-features/conversion#conversion) in the token features catalogue.

Two token features work together. The conversion feature sits on the convertible token and holds the terms: the target token, the denomination asset that prices every round, the discount, the price cap and the conversion window. The [conversion minter](https://docs.settlemint.com/docs/concepts/modeling-assets/token-features/conversion#conversion-minter) sits on the target token, the share token that holders receive. It mints only for the conversion features on its list of authorised converters, so the target token's governance role, together with its Supply management or admin role, decides which convertibles may mint into it. A conversion can also be recorded as a corporate action, with **Record conversion** in [Corporate actions](https://docs.settlemint.com/docs/console/asset-management/manage/corporate-actions) records the event and links back to this page.

![Conversion page of a convertible note with the Configuration panel and Publish trigger](https://docs.settlemint.com/docs/screenshots/console-conversion-page.light.en.webp)

[Screenshot] The page heading "Conversion" with the "Convert" button beside it.

The **Configuration** panel lists the target token, the denomination asset, the discount, partial conversions, the conversion minter, active triggers and the conversion window with its badge and an "Edit" button. "Publish trigger" sits under the facts. Further down the page, "Force convert" sits in the danger area, followed by the "Triggers" and "Conversion history" tables.

A token gets the conversion feature only when it is created. Issue asset sets the conversion feature from the instrument template, and the Console has no control to attach it later. An asset without it shows "Conversion is not enabled for this asset" on its Conversion page.

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

- The target token carries the conversion minter. The target is a token already registered in your organisation, and it cannot be the convertible token itself. The conversion minter comes from the target's template, or an account that can set the target's feature list (Governance with Supply management and Custodian, or with admin) attaches it later through the Platform API. The Console offers no attach control for it.
- The minter lists the conversion feature as an authorised converter. The template can name converters at issuance. Otherwise an account with the governance role and the Supply management or admin role on the target token adds the conversion feature's address with **Add converter**. A conversion against a minter that does not list the feature fails.
- The conversion window is open, or opens when you need it. The Warrant template requires a window start and a window end, so a warrant cannot be created without a window. The window applies to forced conversions too, so after it closes nobody can convert.
- Interest is bound, if interest converts. The **Include accrued interest** switch on the conversion step of Issue asset converts a holder's accrued interest with the principal. When the token carries exactly one interest yield or fixed treasury yield feature, creation binds the conversion feature as the only feature allowed to use that interest. The Console states: "This is permanent. Creating the token binds the conversion feature as the only feature allowed to use the interest, and this cannot be undone." If the bind fails, creation stops at the step "Binding the conversion feature to the yield feature", and "Finish setup" on the asset list runs it again.

## Roles and controls [#roles-and-controls]

Each issuer action needs a role on the token it changes, and every write asks for wallet verification. None of them waits for a second person: one account with the governance role sets the round price, and one account with the custodian role can force a holder to convert at it.

| Action | Role | Token | Where in the Console |
| --- | --- | --- | --- |
| **Add converter**, **Remove converter** | Governance. **Add converter** also needs Supply management or admin | Target token | **Authorized converters** table on the Conversion page |
| **Publish trigger**, **Disable trigger** | Governance | Convertible token | Configuration panel and triggers table on the Conversion page |
| Change the conversion window | Governance | Convertible token | **Edit** on the **Conversion window** row |
| **Force convert** | Custodian | Convertible token | Danger area at the foot of the Configuration panel |
| **Convert** | None. The holder converts the holder's own units | Convertible token | Holding page, or the Conversion page title row |

The controls follow the account's roles:

- "Convert", "Add converter", "Disable trigger" and "Remove converter" show only to an account that holds their role.
- "Publish trigger", "Edit" and "Force convert" stay visible to everyone else but are greyed out.

When another wallet of the same user holds the role, the control is greyed out with "The role for this action sits on wallet `{wallet}`. Switch to that wallet to use it." A user who lacks one of the three controls in the Configuration panel sees the note "Governance holders publish triggers and set the conversion window. Custodians force a conversion."

## Steps [#steps]

### Open the token's conversion page [#open-the-tokens-conversion-page]

Open "All assets", select the convertible token, and open its Features tab. The conversion section shows the target token, the denomination asset, the discount and whether partial conversions are allowed. Select **View conversion details** to open the Conversion page. The same page opens on the target token, where it shows the minter side.

On the convertible token, the **Configuration** panel lists "Target token", "Denomination asset", "Discount", "Partial conversions", "Conversion minter", "Active triggers" and "Conversion window". Three rows change with the terms:

- **Partial conversions** reads "Allowed" or "Not allowed".
- **Conversion minter** reads "Found on the target token" when no minter was named at creation. The conversion feature then looks up the minter on the target token.
- The **Conversion window** row shows its dates, the time left before it closes while it is open and has an end, and a "Window open" or "Window closed" badge. With no start and no end the row reads "Unrestricted", and with one side set it reads "From" or "Until".

Below the panel sit the "Triggers" and "Conversion history" tables. Both tables shorten each trigger ID and conversion ID to its first and last characters. Open a row to see the full identifier with a "Copy" button. Prices carry the symbol of the denomination asset, "Principal" carries the convertible token's symbol, and "Target received" carries the target token's symbol. On the target token, the **Minter administration** panel shows "Total issuances", "Total minted" and the number of authorised converters, and the "Authorized converters" table lists each converter.

### Authorise the converter on the target token [#authorise-the-converter-on-the-target-token]

Skip this step when the target token's "Authorized converters" table already lists the conversion feature. Otherwise open the Conversion page of the target token and select "Add converter" in the table toolbar or its empty state. Enter the address of the conversion feature on the convertible token in "Converter address", and confirm with **Add converter**.

Only a contract that reports the conversion feature interface can be authorised. The minter does not check who deployed it, so authorise only the conversion feature address of a convertible your organisation issued. Because an authorised converter mints, adding one needs the Supply management or admin role on the target token besides Governance. Removing one needs Governance only. For a wallet or any other contract, the sheet shows "Enter the loan token's conversion feature contract address. A wallet or other contract can't be authorized as a converter." To stop a convertible from minting, select **Remove converter** in the converter's row menu.

### Set the conversion window [#set-the-conversion-window]

Read the "Conversion window" row on the convertible token. To change it, select **Edit** on that row. The "Set conversion window" sheet takes a "Window start" and a "Window end". The sheet fills in the current time as the start and an end 24 hours ahead. Both fields are required, so saving also sets a start. The end must lie in the future and after the start. The governance role can set a new window at any time, with an end earlier or later than before, so bringing the end forward or moving the start later closes the window on holders. A start in the future counts as closed until it arrives. The review step shows both moments with their time in UTC. Confirm with "Set window".

### Publish the round as a trigger [#publish-the-round-as-a-trigger]

Select **Publish trigger** in the Configuration panel, or in the empty triggers table. The "Publish conversion trigger" sheet asks for:

- **"Trigger ID":** a new identifier, 0x followed by 64 hexadecimal characters. An identifier already used on this token is refused. The Console does not generate one. Any unused 32-byte value works, for example a hash of the round name.
- **"Denomination asset":** the asset that prices the round. It must be the denomination asset of the conversion terms, and it must be a deployed token with ERC-20 metadata.
- **"Round price per share":** the price per share that the funding round set, in the denomination asset, as a decimal such as 2.5.
- **"Expiration date":** when the round closes for conversions. It must lie in the future and on or before the conversion maturity date, and starts 24 hours ahead.
- **"Metadata hash":** the hash of the round's off-chain details, such as the signed term sheet, 0x followed by 64 hexadecimal characters. The platform stores the value as entered and does not compare it with any document. Record which file you hashed and with which algorithm, so a reviewer can recompute it.

As you type the price, the sheet shows the "Discount", the "Price cap" or "No cap", the **Effective price per share**, and "Cap applies" when the cap lowers the price.

When the target token holds fewer decimals than the convertible token, the sheet warns "The target token holds fewer decimals", because every conversion then loses the rounded-off part. Check the effective price against the approved round terms, as [How a conversion is priced](#how-a-conversion-is-priced) explains, then confirm with **Publish trigger**.

![Publish conversion trigger sheet with the decimals warning and the trigger fields](https://docs.settlemint.com/docs/screenshots/console-conversion-publish-trigger.light.en.webp)

[Screenshot] The "Publish conversion trigger" sheet opens with the warning "The target token holds fewer decimals".

The fields "Trigger ID", "Denomination asset", "Round price per share", "Expiration date" and "Metadata hash" follow the warning. Under the price, a line asks you to enter the round price to see the price holders convert at.

### Let holders convert [#let-holders-convert]

Holders convert their own units while the trigger is active, unexpired and the window is open. No role is needed. A holder converts from the holding page in the Console or the Investor portal, as [What the holder sees](#what-the-holder-sees) describes. A holder can also select **Convert** beside the heading of the Conversion page. While the window is closed, that button is greyed out with "The conversion window is closed."

### Force a conversion when the terms make it mandatory [#force-a-conversion-when-the-terms-make-it-mandatory]

When the instrument terms require conversion without the holder's action, an account with the custodian role selects "Force convert" in the danger area of the Configuration panel. The "Force convert tokens" sheet takes the "Holder address", the "Principal amount" and the "Trigger ID". It shows the holder's "Current principal" and warns: "This force conversion overrides the holder's normal consent path and cannot be undone through the holder flow." The review step shows the estimated output in the target token's decimals and any part lost to rounding. Confirm with **Force convert**. A principal amount of 0 converts the holder's whole unconverted balance. A mandatory round needs one forced conversion per holder.

A forced conversion follows the same trigger and window rules as a holder's conversion. A forced full conversion closes the holder's interest accrual, so interest still unsettled stays claimable as cash yield and can no longer be converted into shares.

### Close a round before its expiry [#close-a-round-before-its-expiry]

To stop conversions against a round before its expiry, open the row menu of the active trigger in the "Triggers" table and select **Disable trigger**. The sheet states "Disable an active conversion trigger. This cannot be undone." A trigger stopped this way cannot be turned back on. To reopen the round, publish a new trigger with a new identifier.

## How a conversion is priced [#how-a-conversion-is-priced]

A trigger carries a round price per share in the denomination asset. The contract subtracts the discount from the round price, then lowers the result to the price cap when one is set. That is the effective price. The holder receives the converted value divided by the effective price, rounded down to the decimals of the target token. The converted value is the principal, with each convertible unit counted as one unit of the denomination asset, plus the accrued interest when the terms include interest. So one convertible unit must carry a face value of one unit of the denomination asset: a note with a face value of 1,000 USD, priced in a USD stablecoin, is issued as 1,000 units.

For example, a note carries a discount of 20%, set as 2,000 basis points, and a price cap of 1.80. The issuer publishes a round at 2.50 per share. The discount brings the price to 2.00, and the cap lowers it to 1.80. A holder who converts 900 notes receives 900 divided by 1.80, which is 500 shares.

The platform records the fraction lost to rounding with the conversion, and the conversion history shows it under the shares received. At the same 1.80, 250 notes converted into a share token with no decimals show "138" with "0.888888888888888888 lost to rounding". Nothing pays the fraction out. A conversion that would give zero shares is refused, and no units move.

The debt method, set at creation, decides what happens to the converted units. Burn destroys them. Lock moves them to the escrow address named when the token was created. The platform places no hold on that address, so whoever controls it controls the locked units. Mark as converted leaves them in the holder's wallet, but they can no longer be transferred or burned, and a forced transfer keeps that restriction.

## What the holder sees [#what-the-holder-sees]

The holder sees the conversion on the page of the holding. In the Console and the Investor portal, open "Wealth", then **Portfolio**, and select the holding's name in the holdings table.

1. The **Convert** control appears only when the token has a configured conversion feature and the holder has an available balance. It is the main button when nothing waits to be claimed or redeemed. Otherwise it sits in the "Actions" menu. Until the holder's claims and the token's features load, the item is greyed out with "Available once your claims and this asset's features have loaded".
2. The "Convert tokens" sheet opens with the balance card **Your conversion balance**, which shows "Available principal" and "Total converted".
3. The **Conversion round** list shows every open round, each as "Price" with the round price and "Open until" with the expiry date and time in UTC, or "No expiry". The sheet selects the only open round on its own. With no open round, it reads "No conversion round is open right now. Once the issuer publishes one, you can convert here." and the submit button stays greyed out. The sheet reads the newest 200 published triggers, so an older round cannot be picked there.
4. When the token's interest yield feature is bound to this conversion, the holder chooses what to convert: "Principal" or **Interest only**. "Interest only" converts the interest the holder is owed and leaves the principal as it is.
5. The **Principal amount** field takes the amount to convert, and 0 converts all available principal. When the terms do not allow partial conversions, the sheet reads "This token converts your whole principal at once."
6. The review step **Conversion preview** shows the round, the amount or "All available principal", and the "Effective price" per share. In the Console it also shows the "Estimated output" in the target token's decimals and how much is lost to rounding. The Investor portal preview shows the round, the amount and the effective price.
7. After **Confirm conversion** and wallet verification, the message reads "Tokens converted successfully" with the token name and symbol. The shares arrive in the holder's wallet as a holding of the target token. The convertible units leave the wallet, move to escrow, or stay in it marked as converted, per the debt method, and "Total converted" rises.

![Convert tokens sheet on a holding page with the conversion balance, three open rounds and the principal amount](https://docs.settlemint.com/docs/screenshots/console-conversion-convert-sheet.light.en.webp)

[Screenshot] The "Convert tokens" sheet with the conversion balance, the open rounds and the principal amount.

The sheet shows "Your conversion balance" with "Available principal" and "Total converted", then the "Conversion round" list with each open round's price and closing date, then "Principal amount". This token allows no partial conversions, so the amount is the whole principal, with "This token converts your whole principal at once."

The sheet names each round by the date it was published, in UTC, such as "Round published 1 Jan 2026". The price and the closing date sit on the line below the name. The review step repeats all three.

## What the platform checks [#what-the-platform-checks]

Every conversion, by a holder or a custodian, passes these checks before any unit moves:

- **The trigger.** It exists, is active, has not expired, and uses the same denomination asset as the conversion terms.
- **The window.** The current block time lies inside the conversion window. The Platform API checks the window before it queues the request, and the contract checks it again.
- **The amount.** The holder holds the amount. An amount of zero converts the whole unconverted balance. A part of that balance is refused unless partial conversion is allowed. An amount below the minimum conversion amount is refused.
- **The price and the output.** The effective price is greater than zero, and the output in target units is at least one base unit.
- **The interest.** When a holder's full conversion closes interest accrual, every convertible period must be settled first. Before the conversion, the Platform API converts the holder's unsettled interest into the target token, in up to 10 rounds, each its own transaction. A forced conversion skips this check.
- **The mint.** The target token has a conversion minter, the minter lists the conversion feature, and the conversion identifier is new. A failed mint reverts that conversion transaction, so the convertible units stay where they were. Interest settled in earlier rounds stays converted.

When a trigger is published, the platform checks that the identifier is new, that the denomination asset matches the terms and has ERC-20 metadata, and that a set expiry lies in the future.

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

- On the Conversion page of the convertible token, the **Conversion history** table shows one row per conversion, with "Conversion ID", "Principal", "Target received" and "Status". "Holder", "Effective price", "Initiated" and "Forced" open from the "View" menu.
- A completed conversion shows the status **Minted**, and a forced one shows "Yes" under "Forced".
- In the **Triggers** table, the "Conversions" count of the trigger rises.
- On the target token, "Total issuances" and "Total minted" in the **Minter administration** panel rise by the same conversion.

## Troubleshooting [#troubleshooting]

**The conversion is refused because the window is not open or has closed**

The Platform API compared the chain time with the conversion window and stopped before it sent anything. A request
before the start returns [DALP-9460](https://docs.settlemint.com/docs/api-reference/errors) "The conversion window has not opened". Submit it
again after the start. A request after the end returns [DALP-9461](https://docs.settlemint.com/docs/api-reference/errors) "The conversion window
has closed", and retrying cannot reopen it. An account with the governance role can set a new window with a future
end. The platform does not check this against the instrument terms, so confirm the terms allow it first. If the
contract finds the window shut instead, the refusal is [DALP-4058](https://docs.settlemint.com/docs/api-reference/errors) "Conversion window not
open" or [DALP-4057](https://docs.settlemint.com/docs/api-reference/errors) "Conversion window closed".

**The trigger cannot be used**

The contract refused the trigger and no unit moved. [DALP-4324](https://docs.settlemint.com/docs/api-reference/errors) "Trigger expired" means
the expiry has passed, and [DALP-4325](https://docs.settlemint.com/docs/api-reference/errors) "Trigger not active" means an account with the
governance role turned the trigger off. Neither can be reversed, so the issuer publishes a new trigger and the holder
converts against it. [DALP-4326](https://docs.settlemint.com/docs/api-reference/errors) means no trigger with that identifier exists on this
token: check the Trigger ID against the **Triggers** table.

**Publishing a trigger is refused**

[DALP-4323](https://docs.settlemint.com/docs/api-reference/errors) "Trigger already exists" means the identifier was used before on this token:
choose a new one. [DALP-4421](https://docs.settlemint.com/docs/api-reference/errors) "Conversion trigger expiry timestamp is in the past" means
the expiry passed before the transaction was mined. [DALP-4064](https://docs.settlemint.com/docs/api-reference/errors) "Denomination mismatch"
means the trigger names another asset than the conversion terms. When the denomination address has no ERC-20 metadata,
the Platform API refuses the request with [DALP-9073](https://docs.settlemint.com/docs/api-reference/errors) before it sends anything, and the
sheet shows "No contract exists at this address on" with the network name when no contract exists there. In the price
preview, "No price to convert at" means the discount brings the price to zero, and "Price too large" means the
contract cannot hold the price. Enter another price.

**The amount is refused**

[DALP-4256](https://docs.settlemint.com/docs/api-reference/errors) "Partial conversion disabled" means the terms require the whole balance: enter
0 to convert all available principal. [DALP-4044](https://docs.settlemint.com/docs/api-reference/errors) "Below min conversion amount" means the
amount is under the minimum the terms set. [DALP-4126](https://docs.settlemint.com/docs/api-reference/errors) means the amount exceeds the
holder's balance, and [DALP-1016](https://docs.settlemint.com/docs/api-reference/errors) "Exceeds unconverted balance" means it exceeds the units
still unconverted. [DALP-4370](https://docs.settlemint.com/docs/api-reference/errors) means the output rounds down to zero target units: convert
a larger amount.

**The holder's interest is still settling**

A holder's full conversion that closes interest accrual waits until every convertible period is settled. The Platform
API first converts the holder's unsettled interest into the target token, in up to 10 rounds, each its own
transaction. When interest is still settling after those rounds, it refuses with
[DALP-9080](https://docs.settlemint.com/docs/api-reference/errors) "Convert is settling this holder's accrued-interest backlog to target tokens"
and HTTP status 409. The interest rounds already done stay converted. This refusal is retryable: the holder submits
the conversion again after the settlement lands. The contract's own refusal for the same case is
[DALP-9081](https://docs.settlemint.com/docs/api-reference/errors) "Convert needs the accrued-interest backlog settled first."

**An interest-only conversion is refused**

When the holder chooses **Interest only** and has no unsettled convertible interest, or the conversion feature has no
interest provider or more than one, the Platform API refuses with [DALP-9487](https://docs.settlemint.com/docs/api-reference/errors) "The holder
has no convertible interest to convert" and HTTP status 409. No interest is converted. Retrying at once returns the
same error. Convert principal instead. With one interest provider, convert interest only after it accrues.

**The mint fails on the target token**

[DALP-4056](https://docs.settlemint.com/docs/api-reference/errors) "Conversion minter missing" means the target token has no conversion minter.
An account that can set the target token's feature list attaches it through the Platform API, then the holder retries.
[DALP-4334](https://docs.settlemint.com/docs/api-reference/errors) means the minter does not list this conversion feature: add it with **Add
converter** on the target token. In both cases the conversion reverts as a whole, and the holder keeps the convertible
units.

**A holder cannot move converted units**

Under the mark-as-converted debt method, converted units stay in the wallet but cannot be transferred or burned. A
transfer of them returns [DALP-1007](https://docs.settlemint.com/docs/api-reference/errors) **Cannot transfer converted tokens**. Only the
unconverted balance moves.

## Frequently asked questions [#frequently-asked-questions]

### Can a holder convert after the window closes?

No. The window applies to every conversion, forced ones included, so a warrant lapses at the end of its window. An account with the governance role can set a new window with an earlier or later end. The platform does not check that change against the instrument terms, so confirm the terms allow it first.

### Does the issuer have to convert every holder?

No. Each holder converts at a time of the holder's choosing while a round is open. The custodian role exists for terms that make conversion mandatory, and it converts one holder per request.

## API routes [#api-routes]

The Platform API offers the same operations. The convert, trigger and converter routes sit under the feature name `conversion-minter`, and `assetId` is the convertible token, except for the converter routes, where it is the target token. The [Platform API reference](https://docs.settlemint.com/docs/api-reference/v2) describes each request and response.

| Method | Route | Use |
| --- | --- | --- |
| `POST` | `/api/v2/tokens/{assetId}/features/conversion-minter/conversions` | Convert the caller's units. `scope` set to `interest` converts interest only. |
| `POST` | `/api/v2/tokens/{assetId}/features/conversion-minter/forced-conversions` | Force a conversion for a holder. Custodian role. |
| `POST` | `/api/v2/tokens/{assetId}/features/conversion-minter/triggers` | Publish a trigger. The price is a whole number scaled to 18 decimals, and the expiry is optional. Governance role. |
| `POST` | `/api/v2/tokens/{assetId}/features/conversion-minter/trigger-disablements` | Turn a trigger off. Governance role. |
| `PATCH` | `/api/v2/tokens/{assetId}/features/conversion-minter` | Change the conversion window. Governance role. |
| `POST` | `/api/v2/tokens/{assetId}/features/conversion-minter/authorized-converters` | Add a converter on the target token. Governance role, plus Supply management or admin. |
| `DELETE` | `/api/v2/tokens/{assetId}/features/conversion-minter/authorized-converters` | Remove a converter from the target token. Governance role. |
| `GET` | `/api/v2/tokens/{assetId}/conversion/triggers` | List the triggers with their effective price, expiry and status. |
| `GET` | `/api/v2/tokens/{assetId}/conversion/records` | List the conversions. |
| `GET` | `/api/v2/tokens/{assetId}/conversion/events` | List the trigger events. |
| `GET` | `/api/v2/tokens/{assetId}/conversion/holder-state` | Read one holder's available principal, total converted and whether interest-only conversion is available. |
| `GET` | `/api/v2/tokens/{assetId}/conversion/converts-to` | List the tokens this token converts into. |
| `GET` | `/api/v2/tokens/{assetId}/conversion/converted-from` | List the tokens that convert into this token. |


# Coordinated distribution

Source: https://docs.settlemint.com/docs/console/asset-management/manage/coordinated-distribution
Pay every share class of a multi-class instrument from one pool: record the terms, preview the split, get any approval, fund the pool and settle each class.

A coordinated distribution is a corporate action that pays every share class of a multi-class instrument from one pool, at one record date. The pool is split across the classes by the instrument's [distribution waterfall](https://docs.settlemint.com/docs/concepts/modeling-assets/token-features/income#distribution-waterfall), a token feature that holds the cash and keeps one share of the pool, a leg, per class. Each class's holders then claim their part as a per-share dividend. [Corporate actions](https://docs.settlemint.com/docs/console/asset-management/manage/corporate-actions) covers the other event types and the shared record, preview and confirm path.

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

- The event is listed under **Corporate actions** in the asset's "Actions" menu only on the share class that carries both the distribution-waterfall and dividend-yield features. An emergency halt does not block it.
- Your account needs the Governance role on the asset. When the organisation has turned on approval for **Corporate actions**, a second person approves the plan: an organisation owner or a platform administrator, who cannot be the one who recorded it or ran its last preview. While it is off, or nobody else could approve, the run goes ahead on your signature alone.
- A class that admits only holders with an investor classification, such as Professional investor, needs each holder to carry that verification before they can receive units of the class. Only a trusted claim issuer for that topic can add it, so the asset's issuer needs that trust first: a user with the Verification policy manager role grants it under **Compliance**, [Trusted issuers](https://docs.settlemint.com/docs/console/compliance/trusted-issuers).
- Each class needs holders before preview, or the preview has nobody to pay. The classes a **Dual-Class Share Structure** issuance creates refuse a mint until their compliance rules admit the recipient. The controlling class carries an identity allow list that starts empty unless you added identities during issuance, so a mint fails with "Compliance check failed" unless the recipient's identity is on that list. Add the identity to the allow list the issuance installed, and add no second allow list rule, because a mint must pass every installed rule. The economic class requires each recipient to hold a KYC claim and a "Professional Investor" claim from a trusted issuer. See [Identity allow list](https://docs.settlemint.com/docs/concepts/compliance-and-identity/compliance-modules#identity-allow-list) and [Claim expiry](https://docs.settlemint.com/docs/concepts/compliance-and-identity/compliance-modules#claim-expiry).

## Steps [#steps]

### Record the terms [#record-the-terms]

Enter a pool amount instead of an amount per share and the three dates. **Issuer-event determination (optional)** names a priority order: left blank, the pool pays on the ordinary ranks, and a named kind applies only while a valid determination claim of that kind is in force. The pool is paid in the class's dividend asset. Record stores the terms and declares nothing yet.

### Preview the split [#preview-the-split]

Preview is available once the record date has passed on chain, and until then it stays unavailable. It declares one dividend per class and, once each class's snapshot is ready, shows the split per class in the order the waterfall pays and every holder of every class with the amount they can claim. Classes that share a rank are paid pro rata. Each class is named by its role, such as Controlling class or Economic class. A class the pool does not reach shows as not reached. Where your organisation requires it, a second person then approves that plan, as [Approve a corporate action](https://docs.settlemint.com/docs/console/asset-management/manage/corporate-action-approval) describes.

### Fund the pool and confirm [#fund-the-pool-and-confirm]

Before you confirm, the sheet shows the pool, your wallet's balance in the dividend asset, and how much your wallet lets the waterfall spend. When that approval is below the pool, select **Approve pool spending** and sign. When the balance is below the pool, send the missing amount to your wallet first. Until both cover the pool, "Pay distribution" cannot be selected, and the sheet footer says why. If the sheet cannot read your balance or approval, it still offers "Approve pool spending", which approves the whole pool.

**Pay distribution** funds the instrument's waterfall once from the executing wallet and records each class's snapshot in the order of the waterfall's class ranking, which is when holders can claim. While the funding or a class record is still queued, the run stays open and offers "Pay distribution" again. Select "Pay distribution" again after the transaction settles to finish the run. If the funding transaction fails on chain, no money moves and the run goes back to approved, so select "Pay distribution" again to fund it.

## Stop or cancel a run [#stop-or-cancel-a-run]

You can stop a funded run. Classes already open for claims stay open until their claim deadline, and the other classes are cancelled. Stopping is not available while a class is being recorded. Stop the run after it settles. Cancelling an unfunded run cancels its class dividends. A rejected plan or an expired approval also ends the run and leaves its class dividends declared until someone cancels them. Open the run from the "In flight" card on the "Corporate actions" tab and select **Cancel class dividends** to cancel them. See [Coordinated distributions across share classes](https://docs.settlemint.com/docs/api-reference/guides/corporate-actions#coordinated-distributions-across-share-classes) for the checks confirm runs and when a stop is allowed.

## Reclaim and release class money [#reclaim-and-release-class-money]

After a coordinated distribution is completed or cancelled, the record shows a **Class money** panel. It has one row per share class: the state of the class, the amount still in the waterfall, and the wallet that funded the run. A class reads "Open for claims until" its deadline, then "Claim deadline passed", "Ready to release to the funding wallet", "Release in progress", "Released", or "Nothing left". A class the record cannot read says so. After you release a class, its row keeps the amount released, the wallet it went to, when, and the release transaction.

Select **Reclaim** on a class after its claim deadline to take back what holders did not claim. Then select "Release" to return what the class still holds to the funding wallet. One account with the Governance role does both, with its own wallet verification, and neither waits for a second person. Release always returns the money to the wallet that funded the run. Release is not available while holders can still claim, after the class is released, or when nothing is left. If a release fails, select "Release" again. An account that can set the token's feature list (Governance with Supply management and Custodian, or with the admin role) can replace a class's dividend feature on the token, which closes that class on chain. "Release" is then available behind a warning, even before the claim deadline, and holders who have not claimed lose their on-chain claim. They stay on the unpaid record. Until nothing waits on a class, the run stays in the asset's in-flight strip.

## Mark unpaid holders as paid [#mark-unpaid-holders-as-paid]

Below the "Class money" panel, **Unpaid holders** lists, per class, each holder the class owed and did not pay once its claims closed: holders who did not claim, and holders left out because their identity was lost. Pay them outside the platform, then select "Mark paid" on the holder, enter the payment reference, and confirm with your wallet. The platform stores the reference as entered and the wallet that marked it. It does not check that the payment happened, and nothing is written on chain. The row then reads "Paid outside the platform" and shows when it was marked, by which wallet, and the reference. If you marked the wrong holder or typed the wrong reference, select "Reopen" on the row, enter a reason, and confirm with your wallet. The holder is unpaid again and you can mark it with the right reference. The cleared payment stays in the row's "History" with who reopened it, when and why. Marking needs the Governance role, and an auditor can read the list. A class whose claims are still being indexed shows a note, and its holders appear shortly. While a class can still be claimed or reclaimed, the section says holders are listed once the class money is reclaimed.

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

- The record reads **Settled** once "Pay distribution" has funded the waterfall and recorded each class's snapshot, or "Class money to recover" while a class still holds money to reclaim or release.
- The "Class money" panel lists one row per share class.
- After the deadline and a "Reclaim" and "Release", the class row keeps the amount released, the wallet it went to and the release transaction, and "Unpaid holders" lists nobody the class still owes.


# Approve a corporate action

Source: https://docs.settlemint.com/docs/console/asset-management/manage/corporate-action-approval
Send a corporate action for a second person's approval, decide it within the approval window, and run it once it is approved.

Once the organisation turns on approval for **Corporate actions**, a corporate action waits for a second person before it runs. The operator sends the plan, an organisation owner or platform administrator approves or rejects it within the approval window, and the operator runs it. The approval covers a stock split in either direction, a bonus issue, a rights issue, a spin-off, a decrease of capital, a partial redemption, a buyback, a payment in tokens, a cash dividend, a distribution paid in cash and a coordinated distribution. [Corporate actions](https://docs.settlemint.com/docs/console/asset-management/manage/corporate-actions) covers entering the terms and reading Review before you send the plan. [Cash dividend and distribution](https://docs.settlemint.com/docs/console/asset-management/manage/cash-dividend) and [Coordinated distribution](https://docs.settlemint.com/docs/console/asset-management/manage/coordinated-distribution) cover the steps before and after the approval of a declaration.

When holders applied for excess shares in a rights issue, the approver of its close sees the same **Excess applications** table the operator reviewed: each applicant's shares applied for and allotted, what they paid and their refund. Approving the close approves that allotment, so issuing the excess shares goes through the same approval as the rest of the close.

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

- **The role that covers the action, for the operator.** The operator who records the action needs supply management on the asset for an action that mints or burns, and governance for a cash dividend, a distribution or a coordinated distribution.
- **A second person.** The second person is an organisation owner or a platform administrator. The platform refuses a decision from the person who recorded the action or ran its last preview.
- **Approval turned on.** The second signature applies only when the organisation has turned on approval for "Corporate actions" in [General](https://docs.settlemint.com/docs/console/organisation-settings/general#approvals), and the "Corporate actions" approval starts off. [When approval is skipped](#when-approval-is-skipped) covers an action that runs without one.

## Steps [#steps]

### Send the plan for approval [#send-the-plan-for-approval]

On Review, the main button of a supply change that needs approval reads **Send for approval**. A cash dividend, a distribution paid in cash and a coordinated distribution go to a second person when you select "Preview allocations" and enter your PIN, which you can do once the record date has passed on chain. For a supply change, the record then reads "Waiting for approval" and "Needs 1 approval", with the date you sent it and the date the approval closes. When the "Corporate actions" approval needs more approvers, it reads "Needs 2 approvals" and so on, and an approver who has decided reads "You approved this. Waiting for other approvers." For a declaration, it reads "Waiting for a second person". A supply change also holds the asset's in-flight slot, so no other supply change can start on the asset until this one finishes or is cancelled.

### Decide the plan [#decide-the-plan]

The second person opens the record from the **In flight** card on the "Corporate actions" tab, or with "Review" on the approval request on [Actions](https://docs.settlemint.com/docs/console/essentials/actions). Every record has its own page in the Console, `/token/<class>/<template>/<address>/corporate-actions/<id>`, with the sidebar in place and a breadcrumb back to the "Corporate actions" tab. "Close" in its footer returns there. The page is titled "Approve the" and then the terms. A line names who proposed the action, when, and the date the decision closes. Read the plan before you decide. For a redemption that pays cash, the "Cash payment" card shows the price per token, the total paid out, and the wallet it is paid from. "Treasury balance" and "Short by" show only when the treasury is short.

The second person then selects **Approve** or "Reject" in the footer and enters their own PIN. Closing the PIN dialog sends no decision. The "Reason" field appears after they select "Reject". A rejection needs a reason, ends the action, and keeps the reason on the record, and the person who proposed the action reads it. An action that froze custodial contracts, such as a stock split or bonus issue, is the exception: it reads "Releasing custody" until every freeze has lifted, which takes someone with the token's supply management role selecting "Release frozen custody" and the release landing on chain. [Release frozen custody](https://docs.settlemint.com/docs/console/asset-management/manage/corporate-actions#release-frozen-custody) covers the step. A lapsed approval does the same, and so does an action its proposer cancels while it waits for approval.

If the plan shows a funding shortfall, **Approve** cannot be selected and a line beside it names the amount needed and the amount available. Ask the operator to fund the treasury and preview again.

When the assistant is on for your organisation, the record page where the second person decides opens with an **Assistant brief**. It states in one sentence what the stored plan does, then marks each check "Matches", "Differs", "Unsure" or "Not stated". The checks cover whether the plan's total follows from the terms, whether the register moved since the preview, and, for a cash payment, whether the treasury covers the total. The brief reads the stored plan, so it never resets the approval. The assistant writes it and can be wrong, so check the plan itself. The brief refuses nothing: "Approve" and "Reject" stay available whatever the brief says, and the page is complete without it. See [What the assistant sends](https://docs.settlemint.com/docs/concepts/operating/assistant-data#the-approval-brief) for what leaves DALP.

## Refresh or reopen the approval window [#refresh-or-reopen-the-approval-window]

While the record waits, the operator who recorded it can select **Preview again**, for example after funding the treasury, to refresh the plan without recording a new action. The new preview replaces the plan, clears any earlier decision, and restarts the decision window: 72 hours from that preview, or until the election deadline when that is later. The record page's "Decide by" line shows when the window closes and moves forward with each preview.

Other operators do not see **Preview again**, because whoever ran the last preview cannot then decide the record. That operator and the one who recorded it see no "Approve" or "Reject" either. Their page says who can reopen approval: the one who recorded it previews again, or an account with the role that covers the action cancels it.

When nobody decides inside the window, the record reads **Approval expired** and names the deadline. The one who recorded it selects "Preview again" to reopen approval, or selects "Send for approval" again from Review, or an account with the role cancels the action. On a cash dividend or distribution, that cancel also cancels the declared dividend and asks for your wallet authorisation. Starting a coordinated distribution on the same token cancels a blocking cash dividend or distribution action in the same way. The record keeps reading "Approval expired" and the dividend stays declared until someone acts.

The person who recorded the action and the person who last previewed it get an email when it is approved, rejected or its approval lapses. Holders get an email and a notification once it is approved.

## Run the approved action [#run-the-approved-action]

After the approval, you reopen the run from the **In flight** card. Review opens with "Approved by" and the approver's name, and the main button reads the action's verb, such as "Burn shares". Enter the PIN again to run it. If you cannot run the action, one alert names the approver and the role you need, with a link to see who holds it on the asset's Permissions tab.

Review asks you again for each acknowledgement the plan needs, such as an underfunded treasury. The second person's approval does not count as yours, because you are the one who sends the plan to holders. The main button stays disabled until you tick each one. For an action that pays cash, the button also stays disabled while Review cannot read the denomination asset, and a line beside the button says what Review waits for. If the operator previews again before the run, the platform clears the approval, so ask for a new one.

An approved action that carries a holder election waits on Review until holders have chosen and the final allocation is read. [Corporate actions](https://docs.settlemint.com/docs/console/asset-management/manage/corporate-actions) describes that wait and the progress the record page shows once the run starts.

## When approval is skipped [#when-approval-is-skipped]

While the "Corporate actions" approval is off, or when the organisation has no other owner who could approve, the sheet reads "This action runs without a second signature", the run has no **Waiting for approval** step, and the action runs on the signature of whoever confirms it.

- **Approval off.** The warning reads "Your organisation has turned off the second signature for corporate actions, so this one executes on the signature of whoever confirms it." An organisation owner or a platform administrator can turn the approval off with their own wallet verification. That change waits for a second person only while an Administration protection group is protected.
- **No other owner.** The warning reads "This organisation has nobody who could give the second signature, so this action executes on the signature of whoever confirms it. Adding a second owner turns the approval gate back on, and this action then needs a second signature before it runs." Only other owners count here, so an organisation whose only owner recorded the action runs it without a second signature, even when a platform administrator exists.
- **A second owner joins, or approval is turned on, before a waived action is confirmed.** Confirming it is refused until a second person approves.
- **A cash declaration recorded without a second signature.** A dividend or distribution paid in cash that was recorded without one still runs without one, whichever reason waived it, even after the approval is turned back on.

The **Approval** column of the "Start a corporate action" card reads "Needs approval" or "Not needed" for each action. A bond coupon paid in cash, a maturity redemption and a conversion never need a second signature.

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

- On Review, an approved plan reads **Approved by** with the approver's name, and a rejected one ends the action with the reason kept on the record.
- A plan nobody decided inside the window reads "Approval expired".
- Once you run an approved action, its progress shows on the record page, as [Corporate actions](https://docs.settlemint.com/docs/console/asset-management/manage/corporate-actions) describes.

## Troubleshooting [#troubleshooting]

**Decision not sent**

When the platform refuses a decision, the PIN dialog closes and a **Decision not sent** alert says which rule refused
it. The platform refuses an approval while the plan shows a funding shortfall. It also refuses a decision made after
the approval window closes. That late attempt expires the record and, on a cash dividend or distribution, cancels its
declared dividend.

**Approval expired**

Nobody decided inside the window. The one who recorded the action selects **Preview again** to reopen approval, or an
account with the role that covers the action cancels it.



# Corporate actions

Source: https://docs.settlemint.com/docs/console/asset-management/manage/corporate-actions
Enter approved corporate event terms on an issued asset, review what changes for each holder, get any approval required, and run the event.

The **Corporate actions** tab of an issued asset, and the "Corporate actions" group of its "Actions" menu, enter the terms of an approved corporate action and run it against the holders. Deciding the event, its economics and who approves it happens in your institution's own process, outside the Console, before you open this screen. When the organisation has turned on approval for "Corporate actions", a second person decides the plan of an action type that needs approval before it runs, unless the organisation has no other organisation owner, as [Approve a corporate action](https://docs.settlemint.com/docs/console/asset-management/manage/corporate-action-approval) describes.

The Console groups thirteen event types under **Actions** as "Corporate actions", listed as seventeen entries: a stock split appears once per direction, and a cash dividend, a bond coupon and a distribution each also appear paid in tokens. An asset lists "Cash dividend" and "Stock dividend" on share capital, and "Distribution" and "Distribution paid in tokens" on any other capital, never both pairs.

- Cash dividend
- Stock dividend
- Bond coupon
- Bond coupon paid in tokens
- Distribution
- Distribution paid in tokens
- Bonus issue
- Rights issue
- Capital decrease
- Stock split
- Reverse split
- Spin-off
- Maturity redemption
- Partial redemption
- Conversion
- Buyback
- Coordinated distribution

Three checks decide what the menu lists.

The first check is what the asset carries: its attached features and its instrument capital. The asset type plays no part. A cash dividend needs dividend-yield attached. A bond coupon needs fixed-treasury-yield. A maturity redemption, a partial redemption, and a bond coupon paid in tokens need maturity-redemption. A conversion needs the conversion feature, so a SAFE or a warrant offers it. A bonus issue and a rights issue need share capital. A capital decrease, a stock split, a spin-off, a buyback, and a stock dividend or distribution paid in tokens need share capital or unit capital. Shares carry share capital. Fund units and real-estate fractions carry unit capital. A SAFE, a warrant, a bond, or a deposit carries neither. An asset with the [Booked movements](https://docs.settlemint.com/docs/console/asset-management/manage/booked-movements) feature lists no event that changes its supply or pays in tokens, because its units move only through a booked movement. It still lists a cash dividend or distribution when it has dividend yield. An event the asset cannot run is not listed.

The second check is your role. An event that passes the first check but needs a role you do not hold is not listed. When no event is left for your role, the menu shows no "Corporate actions" group and the **Corporate actions** tab says which roles start a corporate action. Check the role list in [Before you start](#before-you-start).

The third check applies only to the seven types that change token supply.

- Bonus issue
- Rights issue
- Capital decrease
- Stock split, in either direction
- Spin-off
- Partial redemption
- Buyback

These seven are blocked while the asset is halted, showing "Resume token operations before starting this action." A halt does not block a cash dividend, a distribution or a bond coupon paid in cash, a maturity redemption, a conversion, or a coordinated distribution. Their in-kind entries, "Stock dividend", "Bond coupon paid in tokens" and "Distribution paid in tokens", change supply, so a halt blocks them too.

Each type takes one of three shapes, and the shape decides what you see.

A bond coupon, a maturity redemption, and a conversion are program links: each records the event against a feature the asset already runs, its program, described in [Yield and maturity](https://docs.settlemint.com/docs/console/asset-management/manage/yield-maturity) and [Token conversion](https://docs.settlemint.com/docs/console/asset-management/manage/conversion). Each opens a sheet titled with the action and the asset name, such as "Maturity redemption · Northwind Bond". The sheet gives one line on what recording does and one button named for the action: "Record coupon", "Record redemption" or "Record conversion". A bond coupon sheet also lists the coupon terms before the button: "Yield rate", "Denomination asset", and "Start date" and "End date" in UTC. The button asks for your PIN once. When the record succeeds, the sheet reads Done and links to the yield tab, the maturity tab, or the conversion tab, the program that already serves the event.

Recording a maturity redemption also matures the bond on chain, so the record reads **Matured, redemption open** once that transaction confirms. It is refused before the maturity date and once the bond has already matured, and the redemption treasury must already hold the full payout. Before the maturity date the sheet shows "Not matured yet" with the maturity date in your language and time zone, and the button stays disabled. Holders then redeem their own tokens. Nothing is paid to them automatically. The record shows the redeemed amount and the outstanding amount, and the maturity tab shows the same two amounts. The record completes when every holder has redeemed and nothing is outstanding. A record that reads "Matured, redemption open" cannot be cancelled. No preview, confirm, or cancel appears, because a holder claims against that program whenever they choose.

A cash dividend and a distribution are declarations, which [Cash dividend and distribution](https://docs.settlemint.com/docs/console/asset-management/manage/cash-dividend) covers from the terms to the payment. Record stores the terms and already declares the dividend on chain. Preview opens once the record date has passed on chain, then computes the holder allocations, and the review screen's main button commits the reviewed snapshot. The two carry identical terms and differ only in the vehicle they run on.

A coordinated distribution is a declaration that pays every share class of a multi-class instrument from one pool, at one record date. It is listed only on the share class that carries both the distribution-waterfall and dividend-yield features, and [Coordinated distribution](https://docs.settlemint.com/docs/console/asset-management/manage/coordinated-distribution) covers it from the terms to each class's money and the holders a class did not pay.

The seven types that change supply are staged batch runs. They share one lifecycle: Terms, Review, the PIN that records the plan, an approval where your organisation requires one, Progress, then Done. Nothing is stored until the PIN.

The seven types that change supply and the three payments in tokens run in the Console's in-frame wizard, at the asset's own address: `/token/<class>/<template>/<address>/corporate-actions/new?type=<action>`. The sidebar and top bar stay in place, the page carries the action and the asset name as its title and a breadcrumb back to the asset's "Corporate actions" tab, and a step rail lists Terms, Review and Progress with the step you are on marked. Each step is a page, so the address bar and the rail always agree, and the browser's back button moves between them. Review opened from its address, after a reload, or with the back and forward buttons reads the holders again from the terms the wizard restored, and opens on Review. When those terms cannot be reviewed, or the holders cannot be read, it opens Terms with a notice that Review could not be reopened, and the address changes to match. Progress opened before the PIN opens Terms the same way. Choosing another action leaves this wizard for that one. Leaving with terms entered asks you to confirm first, and leaves no record. The **Corporate actions** tab's rows and the asset's "Actions" menu open the same wizard.

After the PIN, **Cancel** followed by the action name is available before execution starts and "Stop execution" while it runs. A stock split, a reverse split, a bonus issue, a rights issue, a spin-off, a capital decrease, a partial redemption, a buyback, and a payment in tokens add a second person's approval between the first PIN and the run when the organisation has turned on approval for "Corporate actions".

"Stock dividend", "Bond coupon paid in tokens" and "Distribution paid in tokens" pay holders in new units of the asset instead of cash. A stock dividend is the in-kind form of a cash dividend on an equity. Each is a staged batch run with the same Terms, Review and PIN steps. It asks for a numerator, a denominator and an optional record date, and mints the floored ratio amount to every holder. It takes the asset's in-flight slot, the one run that changes supply an asset can have open at a time. The terms read as one sentence, such as "For every 20 shares held, holders receive 1 new share". A stock dividend or a distribution paid in tokens needs no attached feature, only share or unit capital. A bond coupon paid in tokens needs the maturity-redemption feature. A payment in tokens waits for a second person's approval when the organisation has turned on approval for "Corporate actions", the same way a bonus issue and a spin-off do, because all three mint units that cannot be taken back. Leave the record date empty to count holders at the moment you open Review.

The Console shows the main button only after Review has rendered. Review is titled with the action and the asset name, such as "Stock split · Northwind Coffee Shares". It shows each holder's balance before, after and the change, so you can compare the computed allocation with the approval before it reaches holders.

The main button of Review applies the reviewed allocation. It is named for the action, such as "Split shares", "Burn shares", "Pay stock dividend" or "Pay dividend", and opens the PIN dialog directly. When the action needs an approval first, the button reads **Send for approval**. For cash dividends and distributions, recording has already made an on-chain declaration. The button commits the dividend snapshot, and holders claim payment afterwards. Once a supply change applies to a holder, that change stands. Stop execution stops further execution from being dispatched. Transactions already submitted can still settle, so check the reconciled holder results afterwards. The stop sheet states this in its first line, before the per-state counts.

![The Corporate actions tab of an equity with the Start a corporate action card listing each action and its Start button](https://docs.settlemint.com/docs/screenshots/console-corporate-actions-tab.light.en.webp)

[Screenshot] The "Corporate actions" tab shows the "Start a corporate action" card, a table with the columns "Action", "Approval" and "What it does", and a "Start" button on each row.

The "Approval" column reads "Not needed" or "Needs approval".

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

- Open the issued asset and its **Actions** menu, then confirm the intended event appears under "Corporate actions".
- Obtain, from the institution's authorised product owner, the event type, its economics, its entitlement basis, any holder inputs, and its funding.
- Keep the approval reference outside the Console. Nothing in this workflow records or displays that reference for you.
- Your own role covers the event:
  - Governance covers cash dividend, distribution, coordinated distribution, bond coupon, maturity redemption, and conversion.
  - Supply management covers minting for bonus issue, rights issue, stock split, spin-off, a stock dividend, and a bond coupon or distribution paid in tokens.
  - Supply management covers burning for capital decrease, reverse split, partial redemption, and buyback.
  - A stock split in either direction also needs the "Permission manager" role on the asset to run when the share has a price feed, because the split moves the share's recorded price.
  - A stock split in either direction cancels the resting orders on every venue instrument that trades the share: every order while the split moves units, then every order accepted at or before its end. Their locked balances return to free escrow balance. [A stock split cancels the orders it re-based](https://docs.settlemint.com/docs/console/asset-lifecycle/venues/instrument#a-stock-split-cancels-the-orders-it-re-based) covers which orders go.
  - When the organisation has turned on approval for **Corporate actions**, an organisation owner or a platform administrator approves or rejects a stock split in either direction, a bonus issue, a rights issue, a spin-off, a capital decrease, a partial redemption, a buyback, a payment in tokens, a coordinated distribution, or a cash dividend or distribution paid in cash. That person cannot be the one who recorded it or ran its last preview. When the organisation has no organisation owner other than the person who recorded the action, approval is skipped and the action runs on that person's signature. [Approve a corporate action](https://docs.settlemint.com/docs/console/asset-management/manage/corporate-action-approval) covers who decides and when approval is skipped.

## Funding, approval and roles by event type [#funding-approval-and-roles-by-event-type]

Entitlement basis and funding differ by event type. Recording a cash dividend adds an estimated liability, based on the total supply, to the dividend feature's outstanding total, due against the balance each holder carries at the record date. No cash is set aside. The Console checks the treasury when you record it: the treasury must already hold the total payable, or the sheet reads "The dividend exceeds the amount this treasury can move." and does not record. Preview checks the funding again. The **Dividend yield** page of the token's "Features" tab also shows the need to an account with the governance role: from the moment you record a cash dividend, "Committed next" includes its estimated amount, and "Available funding" shows what the treasury can pay. A bond coupon has no entitlement snapshot: a holder claims accrued yield whenever they choose, against the treasury balance at that moment, so the treasury needs the funds when holders claim. A distribution follows the cash dividend pattern, and a maturity redemption and a conversion follow the bond coupon pattern.

The approval for "Corporate actions" in [General](https://docs.settlemint.com/docs/console/organisation-settings/general#approvals) starts off. The **Approval** column of the "Start a corporate action" card shows the rule of each action type, "Needs approval" or "Not needed". The column does not read your organisation's setting: it reads "Needs approval" for a stock split even while the "Corporate actions" approval is off. A bond coupon paid in cash, a maturity redemption and a conversion never need a second signature.

An event your role does not cover is not listed, so an event you expected may be missing for that reason. Check the role list in [Before you start](#before-you-start). A run you cannot advance shows a note that names the role its next step needs, with a link to the asset's Permissions tab where you can see who holds it. Preview, Confirm and Cancel are hidden from an account without that role. Until a run is approved, its holder figures are read live, and that read needs the same role, so its Review shows a note that the figures need that role in place of the figures and holder table. Once the run is approved, its Review shows the figures stored with the approval to anyone who can open it.

A bonus issue, a forward stock split, and a rights issue mint new units on the asset itself. When the asset's minting is closed, they stay listed and are blocked with "Minting is closed for this asset." A reverse split, a capital decrease, and a spin-off do not depend on that, and the role message above comes first when both apply.

## Steps [#steps]

### Choose the event [#choose-the-event]

Open **Actions** and choose the event from its group. The Console lists the entries the asset can run, in the order of the list at the top of this page. The group lists entries only after the asset's features have loaded. Until then a disabled row says it is checking which corporate actions apply. If the features could not be loaded, the menu shows a disabled "Corporate actions" row that reads "Corporate actions could not be loaded. Reload the page to try again." An event missing from the list means the asset lacks the feature or the capital it needs. The [token features catalogue](https://docs.settlemint.com/docs/concepts/modeling-assets/token-features) describes the features behind the events: [dividend yield](https://docs.settlemint.com/docs/concepts/modeling-assets/token-features/income#dividend-yield) for a cash dividend or distribution, [fixed treasury yield](https://docs.settlemint.com/docs/concepts/modeling-assets/token-features/income#fixed-treasury-yield) for a coupon, [maturity redemption](https://docs.settlemint.com/docs/concepts/modeling-assets/token-features/income#maturity-redemption), [conversion](https://docs.settlemint.com/docs/concepts/modeling-assets/token-features/conversion#conversion), and the [distribution waterfall](https://docs.settlemint.com/docs/concepts/modeling-assets/token-features/income#distribution-waterfall) with dividend yield for a coordinated distribution. The Console checks this before your role, so a different role does not bring a missing event back: attach the feature from the asset's Features tab, or issue the asset from a template that declares the capital.

An entry that appears but sits disabled says why on the entry itself. Each visible locked entry names an emergency halt or another action already in flight, together with the required remedy. Where the reason is a run already in flight, the entry links straight to that run's progress.

The asset's "Corporate actions" tab offers the same events in its **Start a corporate action** card. The card lists each action the asset offers with "What it does", whether it needs approval, and a "Start" button, and a blocked action shows its reason in the row. Besides a halt, which reads "Resume token operations before starting this action.", and a run in flight, a row can read "Minting is closed for this asset.", or, on a share class whose payouts go through a distribution waterfall, say to raise a coordinated distribution from the controlling class instead. On a matured bond, "Partial redemption" is blocked whether or not it pays cash, because holders redeem a matured bond themselves. A run in flight shows once above the table, not on each row.

A halted asset, a run already in flight, and a role you lack show as plain blocking messages where they stop you. The sheet shows no row of readiness badges. Whether the platform holds balances for a past record date is reported when the holders are read, so it surfaces on Terms when you select **Review holders →** and on Preview for a declaration.

![The Actions menu of an equity, opening with the Corporate actions group](https://docs.settlemint.com/docs/screenshots/console-manage-asset-menu.light.en.webp)

[Screenshot] The "Actions" menu opens with the "Corporate actions" group, which opens a submenu of the events the asset can run, followed by the asset's other controls.

### Enter terms and record the event [#enter-terms-and-record-the-event]

Complete every field the sheet shows with the approved terms. Which fields appear depends on the event's shape, not one generic form.

While you fill a cash dividend, a distribution or a coordinated distribution, and while a bond coupon, maturity redemption or conversion sheet is open, the Console asks the platform whether it would record the event now. A refusal appears in the sheet as a finding with its fix, for example that your role cannot start this one or that the token cannot run it. The button stays disabled, so you learn the refusal before the PIN. The check stores nothing and signs nothing. The record can still be refused if the asset changes between the check and the PIN.

Enter amounts in the display units named by the field. A dividend's amount per share uses the denomination asset's decimals. Supply allocations use the issued token's units. The Console converts display amounts to base units. Do not convert the amount yourself. Doing so applies the decimals twice, so on a token with 6 decimals the amount comes out a million times too large.

A cash dividend or distribution asks for an amount per share, a country code, whether it is regular or special, and three dates: ex-date, record date and payment date. [Cash dividend and distribution](https://docs.settlemint.com/docs/console/asset-management/manage/cash-dividend) covers each field, the date rules, the amount format and withholding.

A ratio event asks for a numerator and a denominator. The ratio events are the bonus issue, the stock split, the spin-off and the rights issue. A rights issue asks for a **Rights issue action**: "Mint rights now", "Through an existing sale", "Tradable rights token", or "Close a rights issue" to end a tradable issue after its subscription period. "Through an existing sale" asks only for the sale, with no ratio: every holder is added to that sale's whitelist and nothing is minted. "Tradable rights token" mints rights into the "Rights token" you choose: an empty token from your organisation with the hold feature attached, which a venue needs before it can list the token. The rights issue does not create that token. Issue it first in the standard asset flow, which the field links to as "Issue a rights token in the standard asset flow". The field disables a token that is the share token, already holds units, uses different decimals from the share, lacks the hold feature, or on which you lack the Supply management role. A spin-off also requires a child token, chosen from the organisation's empty tokens that carry share or unit capital and are not a class of another instrument. The child field lists every candidate and disables each one it cannot use, with the reason: the child already holds a supply, it carries neither share nor unit capital, it is a class share of another instrument, or you lack the Supply management role on it, because the spin-off mints into the child. The last reads "You need the Supply management role on this child to mint into it." A bonus issue, a stock split in either direction, a rights issue on "Mint rights now", and a spin-off also offer an optional record date. When a bonus issue or split names one, the preview counts the holders at that date and the Snapshot cell shows it. Leave it empty to count holders at the moment you preview. A set date can be previewed once it is reached. After the first minute, the token needs historical balances, and preview then counts the holders as they were at that date. A transfer after that date does not change them. Terms show the result live with a rounding note. The note says "whole" when the output token has 0 decimals, or when the action rounds to whole shares or whole rights. Otherwise it says the result is exact, or rounded down to the token's decimal places.

A stock split asks for its direction under **Split direction**, "Split" or "Reverse split", and the ratio has to point the same way. A split needs more new shares than old shares, and a reverse split fewer. A ratio that points the other way is refused on the "New shares" field with "A split needs more new shares than old shares." or "A reverse split needs fewer new shares than old shares.". A ratio that leaves the count unchanged, such as 1 old share to 1 new share, is refused in either direction with "The ratio must change the number of shares.". Review stays closed until the ratio matches. Under "Percentage", a split needs more than 100% and a reverse split less, so 100% is refused as well.

A reverse split also asks how to round under **Fractions**. "Round down" drops the part of each result below the token's smallest unit. "Whole shares" rounds each result down to a whole share, so a holder who would end with less than one share ends with none. "At least one share" rounds the same way, but a holder who would end with less than one share gets exactly one. If that holder held less than one share before the split, the platform mints the difference.

With "Whole shares" or "At least one share", select **Pay cash for fractions** to pay each holder for the part of the holding that does not convert to a whole share. Choose the "Denomination asset", and under "Price per token" enter the amount paid for one whole share before the split. The active smart-wallet treasury pays each holder in the same transaction as that holder's burn. A holder rounded up to one share is not paid. No other ratio event pays for a fraction.

Every ratio field can also be entered as a percentage. Above the ratio sentence, **Enter the ratio as** switches between "Ratio" and "Percentage". Under "Ratio", the percentage the ratio gives shows below the sentence. Under "Percentage", enter the figure the issuer announced, such as 10.59, with at most four decimal places. The line below shows the exact ratio it becomes, here "Ratio: 1,059 for every 10,000." The percentage is a share of each holder's current holding: 10.59% gives 10.59 rights or new shares per 100 shares held, and a 1-for-18 reverse split leaves each holding at about 5.5556% of its size. The platform stores and runs the whole-number ratio, never a rounded percentage. When a ratio such as 1 for 18 has no exact four-decimal percentage, the percentage shows rounded and the exact ratio is kept unless you change the percentage. Review, the approval heading, the history and the rights terms card show the percentage next to the ratio, marked with ≈ when it is rounded.

A capital decrease, a partial redemption, and a buyback open a holder-book editor. The three send the same announced holder list and share one editor. It seeds itself from the current holder book, so you select the holders the approval covers, prefill them pro rata from one declared total, then edit or exclude individual rows. Export the rows to CSV, edit them outside the Console, and import them back when the approval is easier to reconcile in a spreadsheet. The editor does not open Review until the allocated amounts balance against the declared total.

A buyback also asks **Who**. "Named holders" is the editor above. "All holders" calls every holder at one price and replaces the editor with a summary of four rows: "Holders", which shows the count now and then 0, "Units burned", "Cash paid", which appears once you choose the cash asset, and "Call protection", which says whether a call is open yet. The price per unit is the field you fill in, not a row. The summary uses the current balances, and the list of holders is fixed when you open Review. An all-holders buyback always pays cash, so choose the cash asset and enter a price.

On an asset with the dividend-yield feature, **Compute call price** works the price out from the call date, the issue date, the issue price, the Target Return and the add-on, shows the dividends already paid, and "Use this price" copies the result into the price field. Computing needs the Governance role on the asset, and the panel says so when you lack it.

A capital decrease, a partial redemption and a buyback burn units from each selected holder's wallet, and the holder does not sign. While approval for **Corporate actions** is on, each of them waits for a second person, whether or not it pays cash. Check that the approval covers every row before you run it.

The amount and price fields on these sheets read `1.5k`, `2m` and `3b` as 1,500, 2,000,000 and 3,000,000,000 exactly, and the total and each price show the token symbol inside the field. Under **Total to burn**, a line shows the holders' combined balance with a "Max" button. Under a price or total, a line shows its fiat equivalent at the token's price, for example "≈ $3,000.00", or says that no price is set for the token. Percentages, basis points and ratios keep their own inputs.

A partial redemption can also pay cash for the burned units. Select **Add a cash payment** above the editor, choose the "Denomination asset" from the indexed tokens, and enter the "Price per token" paid for one whole redeemed token. The redeemed token cannot pay its own redemption. The "Paying treasury" is the active smart account, which pays every holder and must hold enough of the denomination asset before the run. Review then shows the payment as a "Cash payment" card with the price per token, the total paid out, and "Paid from". Without an active smart-account custody account the Console cannot add a cash payment, so choose one first. Leave the box clear for a burn with no cash.

A bond coupon, a maturity redemption, and a conversion need no extra fields. Selecting the button both records the event and finishes it, then sends you to the program that serves it. The dialog is titled with the action and the asset, such as "Bond coupon · Gulf Bond", before and after the record. On a bond that has already matured, **Record redemption** is blocked with "This bond has already matured. Holders redeem their own tokens."

A supply change or a payment in tokens can let each holder choose whether to take part. Below the terms, turn on **Let holders choose before a deadline**. The "Let holders choose whether to take part" form asks for "Holders can choose until", a date and time in the future that it repeats in UTC, and at least two options. Each option has a "Name" and a "Result", "Gets the allocation" or "Gets nothing", and exactly one option gets the allocation. Mark one option "Default": holders who do nothing get it. Turning it on fills a deadline 24 hours ahead and two options, "Take part", which gets the allocation and is the default, and "Decline", which gets nothing. A buyback or partial redemption that pays cash, a rights issue through an existing sale and the close of a rights issue cannot carry an election, and the platform refuses one on a reverse split that pays cash for fractions.

The PIN records the action, and the sheet waits for the deadline. After it, and after the second person's approval when your organisation requires one, one more PIN runs it. Holders choose on their holding page, in the Console or the Investor portal: the sheet says "Choose by" the deadline and what each option gives them, and **Save choice** records the choice, which they can change until the deadline. "Save choice" stays unavailable until they select an option other than the one already saved.

For a supply change or a payment in tokens, the Terms step shows the result live as you type, with no PIN. Select **Review holders →** to read the holders. The button shows "Reading holders…" while the platform computes the plan, and nothing is stored. A refusal of the read shows on Review with the platform's message and its error reference. Retry appears only when the platform says the same read can pass on another try. A refusal that another try cannot change, such as a share whose reference price cannot follow the split, shows no Retry, and the action bar says "The platform refused this review. The message above says what to change." Select "← Change terms" to change them. Leaving the wizard discards the terms and leaves no record behind, because nothing is stored until the PIN.

For a cash dividend or a distribution paid in cash, select **Create dividend draft** or "Create distribution draft" to record it. Recording also declares the dividend on chain. Preview and cancel then become available, as [Cash dividend and distribution](https://docs.settlemint.com/docs/console/asset-management/manage/cash-dividend) describes.

### Review, then run it [#review-then-run-it]

A supply change or a payment in tokens opens Review after **Review holders →**. On a capital decrease, a partial redemption or a buyback of named holders, the button counts them, such as "Review 12 holders →". Review leads with a summary strip: "Holders receiving", the holders whose allocation is above zero, the supply before and after, and the snapshot. A reverse split, a capital decrease, and a redemption or buyback that pays no cash only burn, so the count reads "Holders giving up shares". The snapshot reads "Live register" when the holders are counted now, and the record date and time in UTC, such as "26 Oct 2026, 00:00 UTC", when you set a record date. A stock split of a share with a price feed also shows "Recorded share price" before and after, because the split moves the share's price by the inverse of its ratio. A run that needs approval adds an "Approval" cell that reads "Needs a second person". The record page where the second person decides, and the record page you reopen, show the same cells. A holder who rounds down to zero shows in the "Gets nothing" cell, which appears only above zero. A stock split leaves such a holder's holding as it is, so Review counts it in the supply before and after and not in "Gets nothing". A spin-off shows the child token's supply before and after, in the child's units.

While holders can still choose, the strip and the table already apply the choices made so far. A holder who declined counts in neither and shows no change, and the same figures stand once the deadline passes.

Below the strip, the holder table lists only the holders whose allocation is above zero, 25 per page, so its rows always match that count. Before, After and Change are right-aligned, and on a narrow screen, or when a Cash column is shown, Before and After share one cell under the holder. A rights issue reads the share symbol held and the rights symbol received, counted in rights. Search and View appear above 10 rows, and Export downloads every row, not only the page on screen. A holder tagged "rounded down" or "left out" has a **Why** entry in the row menu. It opens one sentence that says what happened to that holder. A rights issue through an existing sale is titled "Review the rights issue through an existing sale": its table lists every holder it adds to the sale with the holding of each and no Change column, the strip counts "Holders added to the sale" and shows no total, and once approved the main button reads "Allot rights".

A "Close a rights issue" review adds a **Rights issue close** card above the holder table. It shows "Rights issued", "Rights exercised", "Rights lapsed", "Rights burned at close" and "New shares to issue", then the rights burned per holder.

When holders who exercised in full have applied for extra shares, the card ends with an **Excess applications** table. You see it before you send the close, the second person who approves it sees it on the approval page, and the settled record keeps it. Excess shares come only from lapsed rights, are shared in proportion to what each holder applied for and are rounded down to whole shares. The table lists each applicant with "Applied for", "Allocated", "Paid", "Refund" and "Status". "Status" reads "To settle" until the close lands and "Settled" after. Cash for shares that are not allocated is refunded in the tokenised deposit. Below the table, "Excess demand", "Lapsed pool used" and "Total refund" add the columns up. "New shares to issue" counts the allocated excess shares as well as the exercised rights. A close with no excess applications shows no table.

![Review step of a 1-for-10 bonus issue with the summary strip and the holder table](https://docs.settlemint.com/docs/screenshots/console-corporate-action-preview.light.en.webp)

[Screenshot] The page is titled "Bonus issue · Capped Tech Shares", with the "Terms", "Review" and "Progress" steps.

The summary strip shows "Holders receiving", the supply before and after, and the "Snapshot" reading "Live register". The table lists each holder's "Before", "After" and "Change", with "Export" above it, and "Issue bonus shares" sends the plan.

A holder who rounds to zero needs no acknowledgement. The acknowledgements that stay are the ones with a real risk, such as a treasury that is short of the cash the plan pays out. A tick box for each shows above the main button, and the button stays disabled with a one-sentence reason until you tick each one.

Select the main button. The PIN dialog opens once, and closing it sends nothing. The platform then creates the record, stores the plan, and starts the run, or sends the plan for approval when the action needs one. A run moves to Progress and then Done. If a holder balance changed while Review was open, the platform does not run the old plan. Review shows the new figures with "Holdings changed since you opened this review. Check the new figures.", clears every ticked box, returns the table to page 1, and waits for a fresh click on the main button.

For a cash dividend, a distribution paid in cash and a coordinated distribution, the sheet keeps its record, preview and confirm steps. The preview computes each holder's allocation without changing balances, and names any holder whose entitlement floors to zero, any holder the operator leaves out, and any funding shortfall. While approval for **Corporate actions** is off, a shortfall asks for an acknowledgement and does not block you. While it is on, the second person cannot approve a plan with a shortfall, so fund the treasury and preview again. [Cash dividend and distribution](https://docs.settlemint.com/docs/console/asset-management/manage/cash-dividend) and [Coordinated distribution](https://docs.settlemint.com/docs/console/asset-management/manage/coordinated-distribution) cover the preview of each.

A stopped bonus issue, stock split, rights issue, capital decrease, partial redemption, or buyback that still has holders left offers **Continue this action**, on its record page and in its History row menu. It opens the wizard with the stopped run's terms copied, and you can change them. Terms opens prefilled, and Review then shows "N holders left; M already applied" in a line under the summary. Continue is blocked, with the reason shown, while another run holds the in-flight slot, while the asset is halted, while minting is closed for a minting event, and once an earlier Continue already created a follow-up of that run, which reads "This run was already continued." A spin-off cannot be continued, because the child token must be empty. If a batch from the stopped run is still settling, the read of the holders is rejected until it is reconciled.

Select the main button of the review screen, named for the action, only when the result matches the approval. For a cash dividend or distribution, it sends the previewed totals and the Merkle root, a fingerprint of every holder's entitlement. An action that changes supply runs its reviewed allocation without those dividend-only fields. If holder balances, rights exercises or the rights that holders still hold moved after the preview, the platform refuses the confirmation and the sheet reads "The holder book moved after the preview". The action stays open and keeps the asset's in-flight slot until you cancel it. Before execution nothing was applied: select **Cancel** and the action name, such as "Cancel buyback" or "Cancel rights issue" for a close, then start a new action with a fresh Review. A rights-issue close refused after its new shares were minted shows "Stop execution" instead, so select it. The Console cannot raise a follow-up of a close, and the platform refuses a new close of the same rights issue, so raise the next close through the Platform API as a follow-up of the stopped one with the `followsUpOn` field, as [Corporate actions](https://docs.settlemint.com/docs/api-reference/guides/corporate-actions) describes. That close burns the rights as they stand and mints no share again.

When the action needs approval, the record reads "Waiting for approval" and holds the asset's in-flight slot. A cash dividend, a distribution paid in cash and a coordinated distribution are approved on the record after their preview. [Approve a corporate action](https://docs.settlemint.com/docs/console/asset-management/manage/corporate-action-approval) covers the decision, "Preview again", an expired approval and the "Assistant brief". After the approval, reopen the run from the **In flight** card. Review opens with "Approved by" and the approver's name and asks again for each acknowledgement the plan needs. The main button then reads the action's verb, such as "Burn shares", and the PIN runs it.

While holders can still choose, the record page of an action with a holder election shows one alert: **Holders can choose until** the deadline, and how many of the eligible holders have chosen. The main button is disabled and reads "Review after" the deadline. A cancelled or stopped action shows neither the alert nor that button, even before the deadline, because holders have nothing left to choose. On an action with a holder election, "Preview again" is refused once a holder has chosen or the deadline has passed, with "The election is locked because a holder has chosen or the deadline has passed. Use the stored preview.", so cancel the action and start it again. After the deadline the review table shows an Option column with each holder's option and a marker on the default, and one line sums the outcome: how many holders take part and the units they take, how many do not, and how many were defaulted.

An approved action that carries a holder election reopens on Review as well. The main button stays disabled while holders can still choose and while the final allocation is being read. A failed read of the election or the allocation shows the platform's message, its error reference and, when another try can pass, Retry. Once the allocation is final, Review shows it as the one set of holder figures, and one PIN runs it.

The record page then stays open through execution. It shows live progress from the record: per-state counts, the transactions that have confirmed, and a count of settled batches. If no batch settles for a while it says so. Acceptance of the request is not settlement, so the page keeps showing progress until the record reaches a terminal status, and only after it has observed the change from non-terminal to terminal does it show the outcome. Reopening an already settled record keeps its details visible.

[Figure] The event type picks the path: supply changes review then run on one PIN, declarations record then preview, program links complete on record. Choosing an event starts one of three paths. A supply change or a payment in tokens opens Terms, then Review, which reads the holders and stores nothing. One PIN on the main button creates the record and runs it, or sends it for approval first. Cancel closes the sheet before the PIN, and stopping a run cannot reverse applied changes. A cash dividend, a distribution paid in cash, and a coordinated distribution are recorded first, then previewed and confirmed. Recording a cash dividend or distribution already creates its on-chain obligation. Bond coupon, maturity redemption, and conversion records complete on record. Holders use their existing programs. Reopen an unfinished record from the In flight card. Labels: Event sequence; Choose the event; Supply changes; and payments in tokens; Terms, then Review; One PIN runs it; Review stores nothing until the PIN.; Stopping cannot undo applied changes.; Three event types; bond coupon, maturity redemption,; and conversion; Completes on record.; No Preview, Confirm, or; Cancel button appears.; Each is a holder claim against; a program, not a batch to preview.; Cash dividend, distribution, coordinated distribution:; record, then preview, then confirm.

The chosen event takes one of three paths: review then one PIN, record then preview and confirm, or a single record
that completes it.

## Units a contract holds for its owners [#units-a-contract-holds-for-its-owners]

Some holders of the asset are contracts that hold units for other people: a trading venue's or a custody gateway's escrow, a token sale, an XvP settlement and an airdrop. For an action that changes every holder's units by a ratio, such as a stock split, a bonus issue or an in-kind dividend, the platform counts these units per owner, as if each owner held them directly, from the indexed balances at the record date. The contract receives the sum of its owners' amounts, and confirming the action writes the action's step to the contract, so its own records follow:

- **Escrow.** Each free balance and each lock moves to the new basis the next time it is used. An escrow is sized from its records one by one, so the action's rounding gives each record what the escrow holds for it.
- **Token sale.** A live sale keeps running. Purchases so far, the remaining inventory, the price and the per-buyer limits move by the action's ratio.
- **XvP settlement.** A settlement that is still open is cancelled, and its deposits are refunded on the new basis. A settlement whose secret is already revealed settles its re-based flows.
- **Airdrop.** Each claim pays its committed amount scaled by every action since the airdrop was set up. An airdrop counts as one holder, so a claim rounds down to the action's unit and is never lifted to one share.
- **Custody gateway.** A queued withdrawal moves to the new basis the next time it is touched. One the action rounds to zero ends as returned, with no receipts left to pay out.

### Freeze until the step lands [#freeze-until-the-step-lands]

The contract's records are re-sized after its units move, so the contract must not let anyone move the asset in between. Creating the action therefore freezes every contract that holds the asset at that moment. From the record date until the action's step lands, an escrow refuses deposits, withdrawals, reclaims, new locks and payouts from a lock (it takes an unlock only of a whole lock, which then moves to free balance once the step lands), a token sale refuses purchases, claims and refunds, an XvP settlement refuses new deposits, settles, cancels, withdrawals and refunds, an airdrop refuses claims, and a custody gateway refuses new requests, claims and ordinary returns. The venue's order cancels, a gateway return caused by the action, and the action's own mint, burn and step still go through. Once the step lands, the settlement cancels a still-open settlement and refunds its participants on the new basis. Each of these refusals names the asset and the action.

The freeze needs a record date that is still ahead when the action is created. An action without one, or with one that has passed, is refused with "The custodial contracts holding this token are not frozen for this corporate action". So is a confirm when a contract started holding the asset after the action was created: abort the action and create it again.

A stock split first cancels the orders resting on every venue market that trades the asset and waits for their locked balances to return to free escrow balance, as [the venue instrument page](https://docs.settlemint.com/docs/console/asset-lifecycle/venues/instrument) describes. Confirm then mints or burns each contract's units and writes each contract's step, and writing the step lifts that contract's freeze in the same call, so a contract is never unfrozen before its records follow its units. If a run stops between the units and the steps, the contracts stay frozen and withdrawals stay refused until you confirm again. The run then finishes and each contract owes what it holds. Abort clears the freeze only while no unit chunk or step has been sent. After that, abort is refused and the action has to be confirmed again to finish. A contract that held the asset when the action was created but had none left by the record date is unfrozen when the action completes or aborts. If a contract holding the asset keeps no step log, creating or confirming the action is refused: move the asset out of it or upgrade it first.

The record shows each contract the action wrote to under `custodialSteps` in the API.

### Release frozen custody [#release-frozen-custody]

An action that froze custodial contracts does not end the moment it stops. This applies to a stock split, a bonus issue, a non-tradable rights issue, and a cash dividend, distribution or bond coupon paid in kind. Whether it was cancelled, a checker rejected it, its approval lapsed or its run finished, its status reads "Releasing custody" until the chain shows that no contract still carries the freeze and no freeze it sent can still land. While it does, a new split, bonus issue, rights issue, spin-off, capital decrease, buyback, partial redemption or payout in kind on the token is refused with an error that names the releasing action. Minting, burning and cash payouts stay open. The platform never lifts a freeze without a signed request, and a checker does not need the supply management role, so someone with that role finishes the job.

Anyone with the token's supply management role, the same role that wrote the freeze, sees **Release frozen custody** on the action's record page and in the Actions inbox. After a rejection, a lapsed approval or a cancellation, the inbox shows it next to the "Rejected, release custody next", "Expired, release custody next" or "Cancelled, release custody next" outcome. The release asks for their wallet verification. On a cancelled, rejected or lapsed action it lifts the freeze on every contract the action marked, including one that drained before the record date, and the action reads "Cancelled" once the chain shows no freeze left. A run that stopped part way because a transaction of its holder batch failed is such an action too: the release first updates the records of each custodian whose units already moved, and lifts the freeze of the others. A custodian whose units never arrived keeps its records as they were. On a finished run it sends again any custodian step that has not landed and lifts the freeze on each contract that took no step, and the action reads "Settled" once the chain shows no freeze left. While any part of a release (a custodian step, a catch-up or a freeze lift) waits in the transaction queue or for a custody approval, "Release frozen custody" is greyed out and a line under it says the release is waiting, so no second release goes out. When the platform cannot read the transaction queue, the button stays available and a line beside it says so. Releasing again is safe, because a request that already waits is not sent twice. If the release fails you can release again, and the new release is sent even when the queue refused the earlier one. The record page reads the action again every few seconds while it is releasing, and the Actions inbox and the Corporate actions tab show the new status on their next read. An action whose freeze never landed on chain, and whose freeze request failed or is no longer queued, ends at once and shows no release. An action cancelled while its creation is still placing the freeze reads "Releasing custody" until that freeze is placed and released. If a freeze lands after the action was cancelled, the action reads "Releasing custody" again and offers the release.

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

- Open the **History** card on the "Corporate actions" tab and find the row for the event you ran. The table is server-paginated, newest first, and filters by type and status. Read its terms under the action name, its status and its result, then compare them with the approval. The hidden columns "Holders counted", "Left over" and "Transactions" open from the View menu or under the row. The result reads, for example, "12 holders updated", "3 of 12 updated" for a run stopped part way, "Recorded" or "Cancelled". A maturity redemption row shows the amount redeemed of the total, such as "Redeemed 100 of 100 BOND", because holders redeem their own tokens. Once every holder has redeemed, it reads "Settled", the same status the maturity tab shows. A rejected action reads "Rejected". "Awaiting approval", "Approved", "Approval expired" and "Dividend cancelled" show on the run in the "In flight" card and on its record page.
- A record that has not completed or been cancelled stays resumable: select **Resume**, "Review" or "View" on its run in the "In flight" card to reopen it at the stage it reached. The card sits at the top of the "Corporate actions" tab and shows only while a run is open. Each run shows a stepper of "Declared", "Waiting for approval", "Running" and "Done". A run that needs no approval skips the second step. A finished run opens on a record that says what the action was, then gives the outcome and a table of each holder's balance before, after and the change, with the counts of holders applied and skipped. The history table lists finished runs only.
- Left-out holders have their own list. It lists each left-out holder with the amount that was planned for them, their holder state, and the transaction that was attempted, and it exports to CSV. It shows no reason code per holder, and the Console says so. When a batch stopped before it reached some holders, the record lists them under **Holders not updated** with the reason the transaction queue gave. From that list you can start a follow-up run under the original terms, and holders that already applied are excluded from it automatically.
- Do not treat a staged run as finished until its remaining count reads zero or a cancellation is recorded against the row. For a cash dividend or a distribution, treat it as finished once the status reads **Settled**, or "Cancelled" if you stopped it. The history table refreshes itself when a run changes state. A row that looks stale needs a reload.
- For a payout, compare the paid amount with the allocation. For a supply event, compare each minted or burned amount. For an entitlement event, such as bond coupon, maturity redemption, or conversion, confirm the recorded entitlement. These three carry no preview data.

## Troubleshooting [#troubleshooting]

**The event is not listed**

The asset lacks the feature or the capital the event needs. Attach the feature from the asset's Features tab, or check
the instrument capital its template declares, before changing permissions.

**The event is listed but cannot be selected**

The entry can be disabled by a permission, emergency halt, or another action in flight. Follow the reason shown on the
entry. If the **Corporate actions** tab reads "You need the" followed by a role, such as "Governance", and "role on
this asset to start a corporate action.", your account holds none of the roles the asset's actions need. Check the
role list in [Before you start](#before-you-start). If you see "Resume token operations before starting this action.",
that only appears for the seven types that change supply and the three payments in tokens, and only while the asset is
halted. Fix: request the required role, or confirm whether the approved intervention permits resuming operations. Cash
dividend, distribution, bond coupon, maturity redemption, and conversion never show the halt message. An emergency
halt does not block them.

**No preview or confirm button appears after recording**

Signal: the sheet closes right after you record, and no "Preview allocations", "Confirm", or "Cancel" button ever
showed. Cause: this is expected for a bond coupon, a maturity redemption, and a conversion. Each completes the moment
you record it, since each is a holder-initiated claim against a program the asset already exposes, not a
Console-driven batch. Fix: nothing further to do in this workflow. Confirm the record landed by checking the
**History** card on the "Corporate actions" tab.

**The treasury is short of the cash to pay out**

Signal: the "Cash payment" card on Review shows "Short by", or the preview of a cash dividend shows a funding
shortfall. Cause: the treasury does not hold enough of the denomination asset to cover the computed payment. Fix:
transfer enough of the denomination asset to the paying treasury, then open Review again, or select **Preview
allocations** again for a cash dividend. Do not run the action against a shortfall. Each new read of the plan takes
the current treasury balance, so a stale shortfall does not carry forward once you have topped up.

**Review says holdings changed**

Signal: Review shows "Holdings changed since you opened this review. Check the new figures." Cause: a holder balance
moved between the moment Review read the holders and the moment you entered the PIN, so the platform did not run the
old plan. Fix: read the new figures against the approval, tick each acknowledgement again, and select the main button
once more. Nothing was sent to holders.

**Confirmation reports snapshot drift**

Signal: the sheet shows "The holder book moved after the preview". Cause: holder balances, rights exercises or the
rights that holders still hold moved after the preview, or a funded coordinated distribution no longer matches its
approved split, so the stored allocation no longer applies. The platform refused the confirmation and left the action
open. Fix: when the action has not started executing, nothing was applied. Select **Cancel** and the action name, then
start a new action, whose Review reads the current balances. When the sheet offers "Stop execution", part of the
action already ran, such as the new shares of a rights-issue close or the funding of a coordinated distribution. Stop
it and check the applied holders. For a rights-issue close, raise the next close through the Platform API as a
follow-up of the stopped one. Confirming the same action again is refused while the change stands.

**Confirmation asks for a new preview**

Signal: the sheet shows **This action needs a new preview**. Cause: the action has no preview it can confirm, for
example because a new preview of a coordinated distribution has not finished. Fix: preview it again, then confirm.

**A run stops after some holders**

Signal: the run in the **In flight** card still shows holders waiting, such as "10 updated, 0 left out, 2 waiting",
and its status stays "Executing" for longer than expected. Cause: processing stopped partway, or a stop landed
mid-run. This applies to the seven types that change supply. Fix: reopen the row, which stays resumable until it
completes or is cancelled, and compare the updated, left-out, and waiting counts against the approval before you
decide to retry or stop. Open the left-out holder list for the per-holder detail: each row carries the planned amount,
the holder state, and the transaction that was attempted. The list carries no reason code per holder. When a batch
stopped before reaching some holders, the record names them under "Holders not updated" with the reason the
transaction queue gave. A follow-up run under the original terms retries only the holders that did not apply. Stopping
leaves already-applied holders exactly as they are. It does not roll them back.

**A run has stopped settling batches**

Signal: the sheet reports that no batch has settled for a while. Cause: execution has gone quiet. Fix: inspect the
pending transaction hashes and platform health while keeping the run record available. The notice alone does not
establish whether execution is progressing. Request acceptance does not mean settlement. A stalled notice does not
mean the run completed. Do not start an overlapping action on this asset while one is in flight. The menu blocks
overlapping runs.

**The run waits for approval**

The record reads **Waiting for approval** until a second person decides. [Approve a corporate
action](https://docs.settlemint.com/docs/console/asset-management/manage/corporate-action-approval#troubleshooting) covers a decision that was
not sent and an approval that expired.

**Review does not open on a holder-book event**

Signal: on a capital decrease, a partial redemption, or a buyback, the holder-book editor is filled in but "Review N
holders →" stays disabled. Cause: the allocated amounts do not balance against the declared total. The editor holds
Review back until they do. Fix: prefill pro rata from the declared total, or adjust the rows until the difference the
editor shows reaches zero. Excluding a row removes its amount from the allocation, so an exclusion changes the balance
too.

**Recording a cash dividend is refused as payout-ineligible**

Signal: recording a cash dividend, or a distribution paid in cash, is refused with the 409 error DALP-14021,
`CORPORATE_ACTION_PAYOUT_INELIGIBLE`, and nothing is declared. Cause: the payout token would refuse the transfer from
the treasury to some of the parties that would be paid, so their claims would fail. The check covers holders with a
positive payout, the treasury and the venue fee accounts only when they also hold the dividend token on the record
date, and the fee recipient when the payout token charges a transfer fee. A holder fails when it is not verified in
the payout token's identity registry or when the payout token's compliance refuses the payout. The refusal counts the
failing parties in `ineligibleCount`. The eligibility read lists at most the 250 largest holders, so the count can
exceed the parties it lists. Fix: read the dividend's denomination eligibility to see which parties fail and why, make
those holders or the fee recipient eligible to receive the payout token, fund the treasury's fee-token balance and
allowance when the payout token charges an external fee, or choose another payout token, then record the dividend
again. The [payout eligibility
check](https://docs.settlemint.com/docs/api-reference/guides/corporate-actions#check-payout-eligibility-before-declaring) describes each rule.

## Frequently asked questions [#frequently-asked-questions]

### Is a reverse split a different workflow from a stock split?

No. A reverse split is a stock split recorded with the ratio direction set to reverse instead of forward. Both use the same numerator and denominator fields, and the Console refuses a ratio that points against the chosen direction: a split needs more new shares than old shares, a reverse split fewer. The Console lists the two separately in the event menu so the direction you intend is unambiguous before you record it, but every later step treats them the same way.

### Can I record a stock split or buyback while another one is already running on this asset?

No. Bonus issue, rights issue, capital decrease, stock split in either direction, spin-off, partial redemption, buyback, a stock dividend, and a bond coupon or distribution paid in tokens share one in-flight slot per asset. Until one of them completes or is cancelled, including while it waits for approval, the others are disabled in the menu and say so, with a link to the run that holds the slot. The same block stops primitive mint and burn on that token. Maturity redemption, conversion, and a dividend, bond coupon or distribution paid in cash never hit this limit.

### Does the platform withhold tax on a cash dividend or distribution?

No. Withholding is applied off-platform, so declare the net amount. The country code on the declaration selects no withholding rate. [Cash dividend and distribution](https://docs.settlemint.com/docs/console/asset-management/manage/cash-dividend) covers the declaration.

### Can I edit an event's terms after I record it?

No. The Console has no control to edit a stored record. If the terms are wrong before you confirm, cancel the record and create it again with the correct terms. If some holders already applied under the wrong terms, stopping the run stops the remaining ones, but a fresh record does not automatically repair the applied changes. Review the applied holders and correct them with a separately approved action.


# Documents

Source: https://docs.settlemint.com/docs/console/asset-management/manage/documents
Upload, version and preview an asset's documents, publish notices to its holders, and replace its logo from the asset's Documents tab.

The **Documents** tab stores an asset's prospectus, term sheet, reports, legal opinions and holder notices. To publish a document or a notice to holders, upload it on that tab with the visibility "Holders only". A holder then finds it on the "Documents" tab of the holding in the Investor portal, when signed in with a wallet that holds the asset. A webhook endpoint subscribed to `token.document.published` receives one event, which carries the publish time.

Each document has a type, a visibility level, a version number and a fingerprint, a SHA-256 hash that the platform computes from the stored file at upload. A new version replaces the old one in the Console without deleting it.

The visibility level decides who can list and download a document:

| Visibility | Who can read it |
| --- | --- |
| **Public** | Every reader of the asset. |
| **Holders only** | A wallet that holds a positive balance of the asset, took part in one of its [offerings](https://docs.settlemint.com/docs/console/asset-lifecycle/primary-offerings) with units or money not withdrawn or refunded, or holds any role on the asset. |
| **Restricted** | A wallet with the Governance or Permission manager role on the asset. |

A document above your level appears in no list, and a download request for it answers `404` with the error `DALP-9486`, as for a document that does not exist. A read counts the roles and balances in the wallets of the participant you work as, which is your own participant when you work as yourself. Uploading checks only the wallet that signs your actions. [My participants](https://docs.settlemint.com/docs/console/my-account/acting-as-participants) explains how to switch participants.

![Documents tab of an asset with document cards, the Check a document button and the Upload document button](https://docs.settlemint.com/docs/screenshots/console-asset-documents.light.en.webp)

[Screenshot] The "Documents" tab with "Check a document" and "Upload document" in the toolbar, and one card for each document showing its preview image, title, file type, version, visibility and upload date.

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

- Open the asset from [All assets](https://docs.settlemint.com/docs/console/asset-management/all-assets). Uploading, publishing a new version and deleting need the Governance role on the asset, held by the wallet that signs your actions. Without it, the tab lists the documents you may read, and its empty state reads "Governance role holders upload them."
- Prepare the file. The tab accepts PDF, JPEG, PNG, WebP, DOCX, XLSX and CSV files up to 50 MiB. A brand logo accepts only PNG, JPEG and WebP images up to 5 MiB and 2048 by 2048 pixels.

## Steps [#steps]

### Open the asset's documents [#open-the-assets-documents]

Select the asset, then select the **Documents** tab. The tab shows each document as a card with a preview image when the platform could render one, the title, the file type, the version, the visibility and the upload date. Filter the list by "Type", "Visibility" or "Uploaded", or export it from the toolbar. The list shows the latest version of each document, newest first. "Check a document" compares a file you hold with what the issuer anchored on chain, as [How holders read documents](#how-holders-read-documents) describes.

### Upload the document [#upload-the-document]

Select **Upload document** and fill in the dialog:

- **Select document type**: the document type.
- **Select visibility**: the visibility, which starts at "Public". Choosing "Distribution report" or "Holder notice" while it reads "Public" switches it to "Holders only". To publish any other type to holders, choose "Holders only" yourself.
- **Title**: the name to show in place of the filename.
- **Description**: optional.

Add the file and select **Upload**.

The types on offer depend on the asset type. A bond offers types such as "Prospectus", "Term sheet", "Credit rating" and "Interest schedule", and an equity offers "Shareholder agreement". Every asset type also offers types such as "Legal opinion", "Regulatory filing", "Compliance report", "Distribution report", "Holder notice" and "Other".

The platform refuses and deletes a file whose stored size differs from the declared size. A brand logo is always stored as "Public", whatever visibility you choose.

![Upload document dialog with document type, visibility, title, description and file fields](https://docs.settlemint.com/docs/screenshots/console-asset-documents-upload.light.en.webp)

[Screenshot] The "Upload document" dialog with "Select document type", "Select visibility", "Title", "Description", a drop area for the file, and the "Upload" button.

### Check the upload [#check-the-upload]

**Document uploaded successfully** appears, and a card with "v1" and its visibility tops the list. Select the card to open it in the viewer, which reads "File integrity verified" when the bytes match the fingerprint recorded at upload.

## Publish a new version [#publish-a-new-version]

Open the menu of the document's card and select **Upload new version**. The dialog, titled "Upload new version", keeps the document type, with the hint "A new version keeps the document type.", and fills in the visibility, title and description of the current version. Change them if needed, add the new file and select "Upload".

The new file takes the next version number. The Console lists only the latest version. Through the Platform API, `filter[isLatest]=false` lists earlier versions within your visibility, but a download of one answers `DALP-9486`, even for a reader who knows its identifier. **Upload new version** appears only on the latest version and only to a Governance role holder. A new "Holders only" version sends its own `token.document.published` event.

## Preview and verify a file [#preview-and-verify-a-file]

Select a card, or **View** in its menu, to open the viewer. The viewer opens every accepted file type in the browser, whether PDF, Word, Excel, CSV or image. While the viewer is open, it hashes the file in the browser and compares the result with the recorded fingerprint, so you see "Verifying file integrity…", then "File integrity verified" or "File integrity failed". A match shows the file is unchanged since upload. It does not prove who wrote the document or that its content is right, and the fingerprint is not on chain. To prove a file against the chain, anchor it as [Filings](https://docs.settlemint.com/docs/console/reporting/filings) describes. "Download" stays available either way, and the arrows move to the previous or next document.

- A PDF opens with page navigation, page thumbnails, zoom and text search across pages.
- A Word document opens read only, with page navigation, zoom and controls to show or hide its existing comments and tracked changes. Those controls do not edit the file.
- An Excel workbook opens with its sheet tabs, zoom and a search across the loaded sheets.
- A CSV file opens with a text search and zoom from 75 to 200 percent.

The preview never saves a change back to the stored file.

## Draft a holder notice [#draft-a-holder-notice]

The Console assistant can draft a notice to holders for a cash dividend or a distribution. It needs the Governance role on the asset, and the assistant on for your organisation with the "Drafts" and **Holder notices** capabilities, as [What the assistant sends](https://docs.settlemint.com/docs/console/organisation-settings/assistant#keep-only-some-capabilities-on) describes. Without the role, the assistant answers "You don't hold Governance on this asset, so I can't draft this."

1. On the asset's page, open search and ask the assistant, for example "Draft a notice for the March dividend". [Search](https://docs.settlemint.com/docs/console/essentials/search) explains how to ask the assistant a question.
2. The assistant looks at the asset's 10 latest [corporate actions](https://docs.settlemint.com/docs/console/asset-management/manage/corporate-actions) that you can read, and uses those that are previewed, approved or running, with an approval that is granted or not required. It takes the only one, or asks "Which action is the notice for? Name its type or record date." when several could fit. It answers instead of drafting in these cases:
   - "I can only draft notices for dividends and distributions." The action is of another type.
   - "I can only draft a notice for an action that is previewed, approved or running, not for one that is cancelled, completed or waiting for approval." No action qualifies.
   - "Add the amount and the dates to the action first, then I can draft its notice." The amount, the record date or the payment date is missing.
3. The Console opens the "Documents" tab with the upload dialog filled in: the type "Holder notice", which you cannot change, the visibility "Holders only", which you can change, a title, a description and the **Notice text**. A line under the title names the corporate action and its record date, and says that every figure is read from its terms.
4. Read the text. The amount per unit, the record date and the payment date, and the ex date and claim deadline when the action has them, come from the corporate action's terms. The assistant writes only the sentences around them, and the Console fills the figures in. The figures sit in the text as plain text that you can edit, and nothing checks an edited figure again before upload, so a changed figure is published as written. Edit only the wording.
5. Choose the **Notice language**, either English or Deutsch. The default is Deutsch in the German Console and English in every other language. Switching the language loads the standard wording of the other language in place of the text you have not edited.
6. Select **Upload**. The browser builds a PDF from the text and uploads it the same way as any other file.

When the drafted wording fails the platform's checks, the dialog uses the standard wording and says "This notice uses the standard wording: the drafted wording did not pass the checks." The checks refuse:

- A number the assistant wrote itself instead of a figure read from the corporate action, or a missing figure.
- A link, a domain or an address.
- A character outside the Latin alphabet and plain punctuation.
- Wording that gives advice, guarantees or promises a return, or that speaks of cancelling, delaying or conditions.
- More than six paragraphs, or a paragraph over 700 characters.

Read the text before you upload: the checks filter wording, cannot judge whether a sentence describes a figure correctly, and do not review the notice legally.

Upload stops when the notice no longer matches its corporate action. The dialog checks again when the window regains focus and once more when you select **Upload**:

- "The corporate action changed after this notice was drafted. Close this dialog and ask for a new draft." The plan changed, the action was aborted or completed, or its approval was denied.
- "The figures for this notice could not be read from the corporate action. Close this dialog and ask for a new draft." The action can no longer be read. The same sentence can show as a message before the dialog opens, and then no draft opens.
- "The PDF cannot show these characters: …" The text holds characters the PDF font cannot draw, such as Arabic or Japanese script. The check runs when you select **Upload**. Remove the characters to upload.

## Replace the token logo [#replace-the-token-logo]

A Governance role holder replaces the asset's logo from the asset header. Select the logo, labelled **Upload logo**, and choose a PNG, JPEG or WebP image of at most 5 MiB and at most 2048 by 2048 pixels. The browser fits the image into a 256 by 256 pixel PNG and uploads it as a public "Brand logo" document, then the header shows the new logo. Each upload adds a new "Brand logo" document, which the "Documents" tab lists. The control is not offered on an external token.

A file that fails a check shows the reason under the logo, such as "Only PNG, JPEG or WebP files are accepted." or "The image is larger than 2048 by 2048 pixels." An upload that fails after the checks offers **Try again**.

## Delete a version [#delete-a-version]

Select **Delete** in the card's menu, or in the viewer. The dialog "Delete document" names the document and says "Holders can no longer open or download it. This cannot be undone." Confirm with "Delete". One Governance role holder deletes alone, and no webhook event reports it. The version disappears from every list. When it was the latest version, the previous version becomes the latest again. The platform keeps the record and the file for the audit trail, and no list or download returns that version again.

## How holders read documents [#how-holders-read-documents]

A holder opens the holding from the portfolio in the [Investor portal](https://docs.settlemint.com/docs/concepts/operating/investor-portal), or from [Portfolio](https://docs.settlemint.com/docs/console/my-assets/portfolio) in the Console. The holding page has the tabs "Overview" and **Documents**, and "Activity" when the asset records balance history.

- The side column of "Overview" lists up to four documents with **View all documents**, which opens the "Documents" tab. With none, it reads "No documents are shared with holders yet".
- The **Documents** tab lists the latest version of each document the holder may read, newest first, with its type, its upload date and a "Download" action. A holder notice shows the type "Holder notice".
- **Check a document** on the same tab compares a file the holder received with what the issuer anchored on chain. The browser hashes the file and sends only the hashes. [Filings](https://docs.settlemint.com/docs/console/reporting/filings) describes how an issuer anchors files.

## Check a term sheet against the chain [#check-a-term-sheet-against-the-chain]

On a bond, deposit, fund or equity, the **Term sheet check** card at the top of the tab compares each of the three newest term sheets with the values the asset holds on chain. A term sheet that is not a PDF shows "Only PDF term sheets can be checked." Each row names the term, the value the document states with its page, the value on chain and the result: "Matches", "Differs", "Not stated" or "Unsure". The terms depend on the asset type, such as the coupon rate and maturity date of a bond or the management fee of a fund.

The card needs the assistant on, the "Term sheet check" capability and the data setting "Send documents", which [Assistant](https://docs.settlemint.com/docs/console/organisation-settings/assistant#keep-only-some-capabilities-on) sets. A Governance role holder who opens the tab runs the check once for a term sheet nobody has checked, and **Check again** reads it again. Anyone else sees the stored result or "This term sheet has not been checked yet." When any term differs, the asset's overview shows the finding "Term sheet differs from the chain".

The term sheet check and the assistant work from text the platform extracts from a PDF. The file is not sent to them. The platform reads a PDF after the upload is confirmed, or on the first request when no text is kept, and keeps the text. Deleting the version deletes its text. It reads the first 150 pages, at most 12,000 characters a page and 300,000 in total. A page with almost no text, such as a scan, counts as image-only, and its text is not read. A file that is password protected, damaged, larger than 20 MiB or slower than 20 seconds to read is not read. Only a PDF is read. A reader who cannot download the document cannot read its text either.

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

- The card shows "v1" and the visibility you chose.
- For a "Holders only" document, a webhook endpoint subscribed to `token.document.published` receives one event for this version, and a holder sees it on the holding's **Documents** tab.
- A "Public" or "Restricted" document sends no event.

## Troubleshooting [#troubleshooting]

**Upload document is missing**

Signal: the toolbar shows only **Check a document**. Cause: the wallet that signs your actions does not hold the
Governance role on this asset. Fix: ask a holder of the Permission manager role on the asset to grant you the
Governance role, or switch to the wallet that holds it.

**The document type you need is not in the list**

Signal: "Select document type" does not offer the type. Cause: each asset type offers its own set of types, and a new
version keeps the type of the document it replaces. Fix: choose "Other" and name the document in "Title", or upload a
new document instead of a new version.

**Failed to upload document**

Signal: the toast **Failed to upload document** appears. Cause: the file is of a type the tab does not accept, it is
larger than 50 MiB, or the upload link expired before the file reached storage. Fix: check the file type and size,
then upload again. Each attempt requests a new upload link.

**File integrity failed**

Signal: the viewer reads **File integrity failed**. Cause: the bytes the browser received do not match the fingerprint
the platform recorded at upload, or the browser could not fetch the file. Fix: do not send the file on. Download it
again, and if the check still fails, publish a new version from the original file.

**A holder cannot see a document**

Signal: a holder reports that the document is missing from the holding. Cause: the document is "Restricted", the
wallet holds no balance, allocation or contribution, or the document is an earlier version. Fix: check the visibility
on the card and confirm the holder's balance on the **Holders** tab. Publish a new version with "Holders only" when
the visibility was wrong.

**The holder notice cannot be uploaded**

Signal: **Upload** cannot be selected and the dialog shows a notice. Cause: the corporate action changed, was aborted,
completed or could not be read, or the text holds characters the PDF cannot draw. Fix: close the dialog and ask for a
new draft, or remove the characters the dialog names.

## Frequently asked questions [#frequently-asked-questions]

### Does a holder get an email when I publish a document?

No. Publishing a **Holders only** document sends the `token.document.published` webhook. Deleting a version sends nothing. The event names the document, the network, the asset, the document type, the title and the publish time, never the file. A receiving system reads the file through the documents API, which applies its own visibility rules. See [Webhook events](https://docs.settlemint.com/docs/api-reference/webhooks/events).

### Can I upload documents through the API?

Yes. The documents routes of the [Platform API reference](https://docs.settlemint.com/docs/api-reference/v2) follow the same steps: request an upload link, send the file, then confirm. The browser sends and fetches each file through a signed storage link, so the documents routes carry the document's details and never the file itself. The fingerprint is a SHA-256 hash. [Files](https://docs.settlemint.com/docs/api-reference/guides/files#asset-documents) describes the routes, the links and their lifetimes. A download link is valid for one hour.

### Can I restore a deleted or replaced version?

A deleted or replaced version cannot be restored. To bring back an earlier text, upload that file again as a new version.


# Fee administration

Source: https://docs.settlemint.com/docs/console/asset-management/manage/fee-administration
Set transaction and management fee rates and recipients, freeze either rate for the life of its feature instance, and collect accrued management fees.

Fee administration sets the rates and recipients of an asset's transaction fee and management fee, freezes either rate, and collects accrued management fees. Seven controls in the asset's "Actions" menu do this. To read the current rates, the recipient or the frozen state, open the asset's **Features** tab and read the "Transaction fee" or "Management fee" card.

Transaction fee sets three rates, mint, burn, and transfer, each in basis points, where one basis point equals 0.01% of the operation's value. The token collects that fee automatically: every operation it applies to splits the moment it runs into the amount the recipient receives, the net leg, and the fee, the fee leg, which lands directly in the fee recipient's balance. A zero-value operation, an operation that involves the fee recipient, a custodian forced transfer, forced burn or wallet recovery, a booked movement, and an operation whose fee rounds down to zero pass through without a split.

Management fee works differently. It sets a single annual rate that accrues continuously against the token's time-weighted average supply, the average amount outstanding since the last collection, weighted by how long each amount stayed outstanding. Nothing moves until someone runs **Collect management fee**, which mints the amount accrued so far straight to the recipient. The external transaction fee and the transaction fee accounting feature have their own controls on their own feature card or page, and the [token features catalogue](https://docs.settlemint.com/docs/concepts/modeling-assets/token-features) describes both.

Six of the seven controls check the Governance role. **Collect management fee** checks no role: any account can run it, and the caller cannot choose the amount or the recipient, which follow the accrual. Visibility is separate from permission. None of the seven appear in "Actions" until an operator attaches the corresponding feature, transaction fee or management fee, to the asset and its configuration finishes indexing. The six governance controls then show only to a user who holds at least one role on the asset, on any of their wallets, and the menu disables any of them that the signed-in wallet cannot run. "Collect management fee" shows to every user. The role gates changes to the configuration. A rate, a recipient and a frozen flag are stored in the fee feature attached to the token, and each stays in force after the Governance role changes hands.

Freezing transaction fee rates and freezing the management fee rate each set a one-way flag on that fee's feature contract. The fee features define no function that clears the flag, so rate-setting on that feature instance stops for every Governance holder. Replacing the feature starts a fresh, unfrozen instance with a rate that can change again, so a freeze binds only the instance it was set on. An account with the Governance role, together with Supply management and Custodian or the admin role, replaces it with **Replace** in the fee's section menu on the Features tab, or through the Platform API. The freeze does not reach the same controls on both fees. A transaction fee freeze locks the three rates only: setting the transaction fee recipient keeps working. A management fee freeze locks the rate and the recipient: the contract refuses a recipient change, and the Console disables "Set management fee recipient" with "The management fee is frozen". Collecting management fees keeps working after either freeze. After a management fee freeze the recipient cannot change, even if its key is lost, until an account that can set the feature list replaces the whole feature. Confirm the recipient before you freeze. No fee control reopens a frozen fee.

![Set management fee rate page with the Fee rate (basis points) field](https://docs.settlemint.com/docs/screenshots/console-management-fee-rate-form.light.en.webp)

[Screenshot] The "Set management fee rate" page at its "Details" step.

The page explains that the rate is annual, in basis points, and that 100 basis points equals 1%. Its "Details" step asks for one field, "Fee rate (basis points)", which starts at 0 rather than the current rate.

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

- Open the asset's **Permissions** tab and confirm that one of your wallets holds the Governance role, which every control except "Collect management fee" needs. The Console disables the controls for a wallet that does not hold it.
- The fee controls appear only once the asset carries their fee feature and its configuration has finished indexing:
  - The transaction fee controls, "Set transaction fee rates", "Set transaction fee recipient" and "Freeze transaction fee rates", need the transaction fee feature.
  - The management fee controls, "Set management fee rate", "Set management fee recipient", "Freeze management fee rate" and "Collect management fee", need the management fee feature.
- A frozen transaction fee disables its rate and freeze controls with the message "Fee rates are frozen and cannot be changed."
- A frozen management fee disables its rate, recipient and freeze controls with "The management fee is frozen".
- Setting the transaction fee recipient and collecting management fees never check frozen state.
- Freezing either fee asks you to type the asset's symbol before wallet verification runs.

## Steps [#steps]

### Open the fee control [#open-the-fee-control]

Open "All assets", select the asset, and open **Actions**. Each fee action opens on its own page under the asset, with a breadcrumb back to the asset, and "Cancel" returns you to where you came from. The menu lists up to seven fee controls, grouped by mechanism:

- "Set transaction fee rates", "Set transaction fee recipient" and "Freeze transaction fee rates" for the per-operation mechanism.
- "Set management fee rate", "Set management fee recipient", "Freeze management fee rate" and "Collect management fee" for the accrual mechanism.

The same controls sit on each fee's own page. Open it with **View transaction fee details** or "View management fee details" on the fee's card on the Features tab. The transaction fee page has "Set transaction fee rates", an "Edit" button on the "Fee recipient" row, and "Freeze transaction fee rates". The management fee page has an "Edit" button on the "Annual rate" and "Fee recipient" rows, "Collect management fee" in its title row, and "Freeze management fee rate" at its foot. A page hides a control when none of your wallets holds its role. It greys the control out, naming the wallet, when another of your wallets holds the role, and greys out a frozen fee's controls with the frozen message.

Pick a rate-setting or recipient-setting control for routine configuration changes. Both are reversible for as long as the fee stays unfrozen. Reach for **Freeze transaction fee rates** or "Freeze management fee rate" only when the rate is meant to stop changing forever, since neither this page nor any other control in the Console reopens a frozen rate. Use "Collect management fee" whenever accrued value needs to reach the recipient now, since nothing collects it automatically the way transaction fee does.

![The Actions menu of an ETF with the management fee feature, listing its four management fee controls](https://docs.settlemint.com/docs/screenshots/console-fee-actions-menu.light.en.webp)

[Screenshot] The "Actions" menu of an asset with the management fee feature, showing its four management fee controls.

The menu lists "Set management fee rate", "Set management fee recipient", "Freeze management fee rate" and "Collect management fee" among the other controls. The transaction fee controls show the same way on an asset with the transaction fee feature.

### Enter the rates, recipient or symbol [#enter-the-rates-recipient-or-symbol]

For **Set transaction fee rates**, the mint, burn, and transfer fields open with the current rates. Change the rates you need as whole basis points, each from 0 to 10000, where 10000 equals 100%. At 10000 the whole amount of a transfer goes to the fee recipient. The burn rate also applies when a holder redeems at maturity, and the holder is paid only for the units that burn. The confirm step shows each changed rate as old → new and each unchanged rate as its current value. Review all three before submitting, since one submission updates all three rates at once.

For **Set management fee rate**, enter a single annual rate as whole basis points, again 0 to 10000. The field starts at 0 rather than the current rate, unless the page opens from a draft that carries a rate, so enter the full rate you want. The rate accrues against time-weighted average supply, so a change applies to value that accrues from this point. When the old rate is above zero and fees have accrued, changing the rate first settles them: the contract mints that amount to the current recipient, as "Collect management fee" does, and "Total collected" can therefore increase. When the accrued amount still rounds down to zero, nothing settles and the carried accrual is charged at the new rate. Submitting the rate that is already set settles nothing.

For **Set transaction fee recipient** or "Set management fee recipient", pick the recipient address from the same eligibility-checked picker ordinary transfer uses. That check filters a fee recipient exactly as it filters an ordinary transfer recipient: an address that cannot receive this token does not appear as a choice, and the token checks the recipient again whenever a fee leg moves value to it. If the recipient later loses eligibility, the next operation that owes a fee to it fails, instead of the fee quietly not arriving.

On the second generation of the management fee feature, which [Fees](https://docs.settlemint.com/docs/concepts/modeling-assets/token-features/fees#management-fee) describes, a recipient change first settles the fees accrued so far, as a rate change does: the contract mints them to the old recipient, and fees accrued after the change go to the new recipient. When the accrued amount still rounds down to zero, nothing settles, and that amount keeps growing and goes to the new recipient at the next collection. The first generation switches without settling, so its next collection mints everything accrued since the last one to the new recipient. An organisation moves its management fees to the second generation when a Permission manager or System manager runs [System updates](https://docs.settlemint.com/docs/console/organisation-settings/system-updates), once the platform runs DALP 3.2. The Console shows no generation badge, so when the old recipient is owed the fees, run "Collect management fee" before the change. That pays the old recipient on either generation.

Freezing cannot be undone on the feature instance, so confirm the rate and, for the management fee, the recipient first. For "Freeze transaction fee rates" or "Freeze management fee rate", there is no rate or recipient to enter. Each page states what the freeze locks. The transaction fee page says the rates "stay as they are forever. Nobody can change them again. The fee recipient can still be changed." The management fee page says the rate and fee recipient "stay as they are forever. Nobody can change them again." Both pages then ask you to type the asset's symbol to confirm. Only an exact, case-sensitive match of the symbol, ignoring leading and trailing spaces, lets you continue to **Freeze permanently** and wallet verification.

**Collect management fee** has no fields at all. Confirming submits directly to wallet verification, and the amount collected is whatever has accrued since the last collection. Collecting mints that amount as new tokens straight to the recipient, so every holder's proportional share of the asset shrinks. The collection mint is booked as a fee movement: a transaction fee on the same token does not split it, and an external transaction fee does not charge it, but identity and compliance checks still run. If the recipient has lost eligibility since it was set, the mint fails the same eligibility check an ordinary mint to that address would fail, and the whole collection reverts instead of partially completing.

### Confirm with wallet verification [#confirm-with-wallet-verification]

Confirm with wallet verification, the same as any other Console admin change. A rate, recipient or freeze change waits for a second person only while the **Administration** row under "Approvals" on [General](https://docs.settlemint.com/docs/console/organisation-settings/general#approvals) protects the "Token administration" group. "Collect management fee" never waits.

A rate or recipient change that fails a check reverts and leaves the configuration unchanged. A management fee change that first pays out accrued fees fails when the asset refuses that payment: for example while the asset is halted, or while the recipient set before the change is frozen on the token or no longer eligible to hold it. A rate change pays out first when fees have accrued at a rate greater than zero, and on the second generation a recipient change does too. Once a rate change lands, it applies to whatever runs after it, not to the rate that was live when someone submitted a transaction. A mint, burn, or transfer already sent but not confirmed still charges whichever rate is live the instant it executes, so a rate change can alter the fee on an operation a holder already signed. Freezing cannot be undone, and each freeze sheet says so in its description: "Permanently freeze the transaction fee rates. This action is irreversible." for the transaction fee control, "Permanently freeze the management fee rate. This action cannot be undone." for the management fee control.

Collecting management fees is not reversible either. Once a collection mints tokens to the recipient, those tokens exist like any other holding, and the Console has no control to reverse a collection.

[Figure] Freezing locks the rate lever outright. The transaction fee recipient and management fee collection stay available regardless. Six of the seven fee controls require the Governance role, and "Collect management fee" requires none. Once a rate is frozen, no function on that feature instance reverses it, so rate-setting for that fee is blocked for every Governance holder. Setting the transaction fee recipient and collecting management fees are unaffected by frozen state. Setting the management fee recipient does not appear in either lane here: freezing the management fee blocks it too. Labels: Freeze needs Governance role; Rate lever; Set fee rates; Freeze fee rates; No function anywhere; reverses a freeze.; Recipient and collect; Set tx fee recipient; Collect management fee; Frozen state on either fee's; rate never changes what these; two controls are allowed to do.; Rate locked; permanently; Stays available.

Freezing locks the rates and, for the management fee, the recipient, while setting the transaction fee recipient and collecting management fees keep working.

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

- After a rate or recipient change, open the asset's **Features** tab and find the "Transaction fee" or "Management fee" card. Each shows the current rate or rates and the "Fee recipient", and a "Frozen" badge once the fee is frozen.
- **View transaction fee details** or "View management fee details" opens the fee's page with the full configuration, including its "Frozen state" or "Rate frozen" row.
- After "Collect management fee", the card's **Total collected** figure increases by the collected amount, and "Last collected" updates to reflect the new collection. A "Set management fee rate" submission can move that same figure too, whenever it settles fees accrued under the rate you just replaced. On the second generation, a "Set management fee recipient" submission moves it the same way when it settles fees accrued for the old recipient. That is expected.
- After freezing either fee, confirm the card now shows the **Frozen** badge. Then confirm the Console disables "Set transaction fee rates", or "Set management fee rate" and "Set management fee recipient", the next time you open "Actions". "Set transaction fee recipient" and "Collect management fee" stay selectable and complete normally.
- A rate change, a recipient change, a freeze, or a collection each lands as its own entry in the asset's **Activity**, with the transaction hash, the same way other admin changes do. Match the entry there if you need to confirm exactly when a change took effect and who made it.

## Troubleshooting [#troubleshooting]

**Fee controls are missing from Actions**

Signal: none of the seven fee controls appear. Cause: the asset carries neither the transaction fee feature nor the
management fee feature, or it carries one whose configuration has not finished indexing yet, in which case the Console
treats it as not configured. Fix: open the **Features** tab. If no fee card exists, a Governance holder attaches one
from "Attach a feature". If a fee feature was just attached, wait for the configuration to finish indexing and reopen
the menu.

**A fee control is greyed out**

Signal: a control shows in the menu, greyed out. Cause: your wallet lacks the Governance role on this specific asset,
or the fee is frozen. A frozen fee shows its own message, "Fee rates are frozen and cannot be changed." or "The
management fee is frozen", even when you also lack the role, because no role reopens it. A missing role shows "You
need the Governance role on this asset to manage its fees." When another wallet of yours holds the role, the control
names that wallet instead. "Collect management fee" is never disabled for a missing role. Fix: if the card shows no
"Frozen" badge, ask an administrator to grant the Governance role, scoped to this asset. If it does, someone already
froze that fee for every Governance holder, and only "Replace" in the fee's section menu on the Features tab or
through the Platform API starts a new, unfrozen instance.

**Freeze confirmation does not continue**

Signal: the freeze page does not advance to wallet verification. Cause: the typed text does not exactly match the
asset's symbol. The check is case-sensitive and ignores only leading and trailing spaces. Fix: retype the symbol
exactly as the field label shows it.

**A mint, burn, or transfer reverts even though rates and roles look fine**

Signal: an ordinary mint, burn, or transfer reverts on an asset that carries the transaction fee feature, even though
the operation itself would normally succeed. Cause: the transaction fee recipient no longer passes the eligibility
check that gates every operation on this token. The fee leg the token creates on every qualifying operation goes
through the same check as the operation itself, so an ineligible fee recipient blocks the whole operation, not just
its fee. Eligibility can change after the recipient was set, so this can surface long after that change. Fix: restore
the recipient's eligibility, or use **Set transaction fee recipient** to point at an eligible address instead.

**Collect management fee reverts instead of minting**

Signal: "Collect management fee" reverts rather than completing. Cause: the asset refuses the minted fee amount. The
management fee recipient no longer passes the same eligibility check as a transfer recipient, its address is frozen on
the token, or the asset is halted. Fix: if the asset is halted, collect once **Resume token operations** has run. If
the recipient's address is frozen, have a Custodian unfreeze it. If the recipient lost eligibility, restore it. Then
retry the collection. On the first generation of the feature, "Set management fee recipient" can instead point at an
eligible address first, and that address then receives the whole accrual. This does not work once someone has used
"Freeze management fee rate". On the second generation a recipient change pays the old recipient first, so it fails
for the same reason until the old recipient can receive again.

**Set management fee recipient reverts**

Signal: a management fee recipient change reverts, and the **Management fee** card still shows the old "Fee
recipient". Cause: on the second generation of the feature, the change first mints the fees accrued so far to the old
recipient, and the asset refuses that mint. The asset is halted, the old recipient's address is frozen on the token,
or the old recipient is no longer eligible to hold the token. Fix: if the asset is halted, change the recipient once
"Resume token operations" has run. Resuming only for this change also reopens transfers for every holder. If the old
recipient's address is frozen, have a Custodian unfreeze it. If the old recipient lost eligibility, restore it. Then
change the recipient. The change pays the old recipient the fees accrued so far, so a recipient you replace because it
is frozen or ineligible receives those fees before the new recipient takes over. A change goes through without a
payment while the rate is zero, or while the fees accrued so far round down to zero.

**Collect management fee reports zero collected**

Signal: "Collect management fee" completes without reverting, but the collected amount is zero and "Total collected"
does not change. Cause: no time has passed since the last collection, or the accrued amount rounds down to zero at the
current rate and supply. The fee formula weights supply by elapsed time, so a very short gap between collections can
legitimately accrue nothing. The accrued amount is the time-weighted average supply since the last collection,
multiplied by the annual rate, multiplied by the elapsed time, divided by a year. A short elapsed time or a low rate
can round that product down to zero even with a healthy supply. Fix: nothing to fix. Wait longer between collections,
or check the card's **Accrued (est.)** figure before collecting to confirm there is a meaningful amount to collect.

## Frequently asked questions [#frequently-asked-questions]

### What still works after a freeze?

Setting the transaction fee recipient and collecting management fees. A transaction fee freeze locks only the three rates, and no freeze stops collection. A management fee freeze also locks the recipient.

### Why is there no collect control for the transaction fee?

Transaction fee pays itself out inside every mint, burn, and transfer it applies to, so there is nothing left to collect afterward. The "Transaction fee" card's "Total collected" figure and the **Collections history** on the transaction fee page record the fees already paid.


# Dealing

Source: https://docs.settlemint.com/docs/console/asset-management/manage/fund-dealing
Set a fund's subscription terms, follow investors' requests before the 12:00 UTC cut-off, and settle a dealing day's redemptions at the published NAV.

The **Dealing** tab of a fund token is where its supply manager sets the subscription terms, follows the investors' requests and settles each dealing day at the NAV, the net asset value that the fund's price feed published. Investors lodge subscription and redemption requests before the 12:00 UTC cut-off of a dealing day. A fund token takes these requests only when it does not use register lines, the holder register that the [Booked movements](https://docs.settlemint.com/docs/console/asset-management/manage/booked-movements) feature keeps. The Fund dealing concept page explains the model: the calendar, the five redemption request statuses and the settlement order. [Corporate actions](https://docs.settlemint.com/docs/console/asset-management/manage/corporate-actions) covers the buyback review.

A redemption day settles from the Console or the API and pays out through a buyback corporate action. A subscription day settles through the API only, with `POST /api/v2/tokens/{assetId}/subscription-settlements`: the platform prices each open request at the NAV, pulls the investor's cash and mints the units. The **Subscription requests** list in the Console is read-only and has no settle button.

![The Dealing tab of a fund with open redemption requests and the Settle dealing day button](https://docs.settlemint.com/docs/screenshots/console-fund-dealing.light.en.webp)

[Screenshot] The "Dealing" tab as a supply manager sees it.

Under the "Settle dealing day" button, "Redemption requests" lists one row per request with "Holder", "Units", "Status", "Dealing day", "Cut-off", "NAV" and "Cash". Below it, "Subscription requests" starts with the line "This list is read-only.", and its rows continue below the frame.

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

- **A fund without register lines.** The Features tab of the token shows whether Booked movements is attached. The "Dealing" tab and the Dealing requests card appear only for a token of the fund type that does not use register lines. Any other token has no "Dealing" tab. The platform also refuses a request on a fund token that cannot settle a cash buyback: a redemption request with DALP-14076 and a subscription request with DALP-14081 and the reason `token-not-subscribable`.
- **The Primary market module.** Fund dealing belongs to the Primary market licensed module, which the deployment switches on with `features.tokenSale` ([Switch application layers on or off](https://docs.settlemint.com/docs/deployment/install/values-secrets#switch-application-layers-on-or-off)). With it off for the deployment, the "Dealing" tab, the Dealing requests card and the Funds section of Invest are absent and the dealing routes answer `404`. When your organisation switched it off, the requests and terms stay readable under a read-only banner, the write buttons are hidden, and every dealing write refuses with `403` and `platform.module.DISABLED` ([DALP-20531](https://docs.settlemint.com/docs/api-reference/errors)).
- **The Supply management role.** A supply manager holds the Supply management role on the token. The token's Permissions tab shows who holds it.
- **Subscription terms.** Settling a redemption in the Console pays in the stablecoin of the subscription terms, so a fund needs terms before its first settlement. The API takes the stablecoin in the settle call and does not read the terms.
- **A NAV after the cut-off.** The fund's price feed must publish a NAV after the cut-off of the dealing day and before the cut-off of the next dealing day. A value published before the cut-off does not count. [Market data](https://docs.settlemint.com/docs/concepts/records-and-evidence/market-data) explains how a fund takes its price from a feed.
- **A stablecoin.** The settlement pays in an ERC-3643 token of the stablecoin type that the platform has indexed, which is a token it has read from the network. The terms sheet lists every indexed stablecoin, but a settlement accepts only an ERC-3643 one and refuses any other with DALP-14101. Choose an ERC-3643 stablecoin when you set the terms. The stablecoin's price feed must name the same currency as the NAV.
- **A second approver, if you want one.** A redemption buyback waits for a second person only while the "Corporate actions" approval in [General](https://docs.settlemint.com/docs/console/organisation-settings/general#approvals) is on. An organisation owner or a platform administrator turns it on.
- **Wallet verification.** Setting the terms, requesting a redemption, cancelling a redemption request and settling a day each ask you to confirm with your wallet. Lodging or cancelling a subscription request does not.

## Who can do what [#who-can-do-what]

A bank rail redemption is a separate flow that [Bank rail](https://docs.settlemint.com/docs/console/asset-lifecycle/bank-rail) covers.

| Task | Who can do it |
| --- | --- |
| Read the subscription terms | Any signed-in user |
| Set the subscription terms | A supply manager of the token |
| Lodge a subscription request | An investor, for one of their own wallets. From Invest any wallet of the investor can subscribe. From the holding page the wallet must already hold units. |
| Request a redemption | A holder, for their own wallet, with no token role needed |
| Cancel a request | The holder or investor who made it |
| Read every request of a token | A supply manager of the token |
| Read your own requests | Any holder or investor, for their own wallets |
| Settle a dealing day | A supply manager of the token. A subscription day settles only from the receiving treasury of the terms. |

A supply manager cannot cancel an investor's request. A cancellation by anyone but the investor or holder who made the request answers as not found.

## Steps [#steps]

### Set the subscription terms [#set-the-subscription-terms]

Open the fund from "All assets" and select **Dealing** under "More". The "Subscription terms" card shows "Stablecoin", "Receiving treasury", "Minimum cash per request" and "Last updated". While the fund has no terms, the card says "No subscription terms are set yet."

A supply manager sees **Set terms** while no terms exist and "Edit terms" afterwards. The sheet asks for the stablecoin investors pay in, the treasury wallet that receives the cash and an optional minimum. Leave the minimum empty for no minimum. "Save terms" asks for your wallet verification and then saves.

The platform refuses terms in these cases:

- The stablecoin is not a token indexed on the same network, or it is the fund token itself.
- The receiving treasury is the zero address or the fund token.
- A minimum is set and is zero or less.
- The token is not a fund without register lines. The Console says "This fund does not accept subscriptions."

### Investors lodge and cancel requests [#investors-lodge-and-cancel-requests]

An investor who holds no units yet subscribes from [Invest](https://docs.settlemint.com/docs/console/my-assets/invest). Its "Funds" section lists every fund that has subscription terms and does not use the register lines feature, and each fund card has a **Subscribe** button. The card also lists the investor's own subscription requests for that fund, with "Cancel" before the cut-off.

The "Dealing requests" card sits on the holding page of the fund, which an investor opens from Wealth, then [Portfolio](https://docs.settlemint.com/docs/console/my-assets/portfolio), once a wallet holds units. It has two buttons, "Subscribe" and **Request redemption**. The Investor portal shows the same "Funds" section on Invest and the same card on its holding page. The API serves the same requests to an integration.

**Subscribe** opens a sheet with the cash amount in the subscription stablecoin. The amount field reads your number in your language and accepts the suffixes k, m and b. Under it, a line shows the amount in the stablecoin's price currency, or "No price set for …, so no fiat equivalent." when the stablecoin has no price. From Invest the sheet uses the investor's main wallet and has no wallet picker. From the holding page it shows a wallet picker when the investor has more than one wallet that holds units. An investor the fund's rules exclude sees "This fund isn't open to your account. Ask the fund manager to check your eligibility, then try again." The sheet shows "Minimum: …" when the terms set one and "This is below the fund's minimum." when the amount is under it. When the fund has no terms the sheet says "This fund has not opened subscriptions."

**Request redemption** opens a sheet with the units to redeem, the same amount field with its fiat line, and the line "Available: …". The request locks no units on the chain, so a holder who moves the units away before settlement has the request rejected with "The holder no longer had enough units". The button is off while no wallet of the holder has available units. An amount over the available units shows "This is more than your available balance." The sheet asks the holder for wallet verification before it sends the request.

Both sheets say that the request can be cancelled until the cut-off of its dealing day. The request takes its dealing day from the moment the platform records it. A request recorded before 12:00 UTC on a weekday belongs to that day. A request recorded later, and any request on a weekend, belongs to the next weekday.

The card lists each request as "Subscription" or "Redemption" with its amount, a status badge with the text "Open", "Cancelled", "Settling", "Settled" or "Rejected" and the line "Dealing day … · cut-off …". A subscription request stays **Open** until a supply manager settles its dealing day through the API. It then shows "Settling" until the cash and the units are on the chain, then "Settled" or "Rejected". The card shows no NAV, units or reason. The API record of the request carries the NAV, the units, the cash and the rejection reason. The settle sheet in the Console settles a redemption day only.

While a request is open and its cut-off is ahead, its row shows **Cancel**. A redemption cancellation asks for wallet verification first. A subscription cancellation does not. After the cut-off the button is gone, and a call to the API is refused.

### Follow the request lists [#follow-the-request-lists]

The **Dealing** tab of the fund has up to four sections:

- **Redemption requests** with the columns "Holder", "Units", "Status", "Dealing day", "Cut-off", "NAV", "Cash" and "Reason".
- **Subscription requests** with "Investor", "Cash", "Dealing day", "Status" and "Cut-off". This list is read-only.
- **Subscription terms**, from the first step.
- **Fund register** with each holder's units and value, and "Export CSV". It is the list of holders, not the register lines feature. It shows only to a platform administrator, an organisation owner, or a holder of the Permission manager, Auditor, Compliance manager or System manager system role.

A supply manager sees every request in the two lists and the buttons "Edit terms" and "Settle dealing day". Anyone else who can open the tab sees the requests of their own wallets.

A rejected redemption shows one of three reasons in **Reason**: "The holder no longer had enough units", "The units were worth no cash at this NAV" or "The holder cannot receive the stablecoin". A rejection is final, so the holder lodges a new request once the cause is fixed. The new request takes its dealing day from the moment the platform records it.

### Settle a redemption day [#settle-a-redemption-day]

After the cut-off, and after the fund's price feed has published a NAV for the day, a supply manager selects **Settle dealing day** on the redemption list. The sheet asks for:

- **Dealing day.** It opens on the last weekday before the current date in your local time and cannot be moved later than the current date. Open requests up to and including this day settle together.
- **Stablecoin.** This is read-only. It is the stablecoin of the subscription terms. With no terms the sheet says "Set the subscription terms first. They name the stablecoin."
- **Paying treasury.** Pick the wallet that holds the stablecoin for the payments.

The review step shows "Settlement" with the three values. **Settle dealing day** asks for your wallet verification and sends the call. The Console confirms with "Dealing day … settled". That message means the platform stored the plan. No cash has moved.

The settlement prices the requests and drafts one buyback corporate action that burns the units and pays each holder in the stablecoin. The requests it takes show as **Settling**. A settlement that finds every request rejected is stored without a buyback.

The buyback follows the organisation's approval policy for corporate actions. That approval is off by default. Once an organisation owner or a platform administrator turns on the **Corporate actions** approval in [General](https://docs.settlemint.com/docs/console/organisation-settings/general#approvals), an organisation owner or platform administrator approves the previewed buyback, and that person cannot be the supply manager who settled the day or the person who last previewed the buyback. While the approval is off, or while the organisation has no other owner who could approve, the buyback runs without a second signature. A supply manager then confirms the buyback, which burns the units and pays the cash, as [Corporate actions](https://docs.settlemint.com/docs/console/asset-management/manage/corporate-actions) describes.

The status of a request updates the next time someone settles, lists or creates a redemption request on the token. When a holder's payment is on the chain, that holder's requests change to **Settled**. The API record of the request carries the transaction hash.

If the buyback completes, or is aborted before its confirmation starts a transaction, the unpaid requests return to **Open** with their original dealing day and cut-off, and the next settlement takes them again.

### Settle a subscription day [#settle-a-subscription-day]

A supply manager settles a subscription day through the API, with `POST /api/v2/tokens/{assetId}/subscription-settlements`. The Console has no control for it. The call names the dealing day only, and the stablecoin and the receiving treasury come from the subscription terms.

The call must come from the receiving treasury of the terms, and that wallet must be a smart wallet, because each batch goes out as one transaction. When it is not, select **Edit terms** and name a smart wallet as "Receiving treasury".

Before the day settles, each investor approves the receiving treasury to spend at least the total cash of all their open requests in the stablecoin. No dealing screen asks for this approval. The investor sets it with `POST /api/v2/tokens/{assetId}/approvals` on the stablecoin, naming the receiving treasury as the spender. This is an ordinary stablecoin allowance. The receiving treasury can spend it outside a settlement too, and what is left of it stays after a request is cancelled or settled, so an investor approves no more than the open requests need.

The platform prices every open subscription request of that day or an earlier one at the day's NAV, pulls the cash from each investor and mints the units in one transaction per batch of up to ten investors. The platform rejects a request, records its reason and settles the rest of the day when the investor no longer holds the cash, has not approved the receiving treasury to spend it or cannot receive the fund token, or when the cash buys less than the smallest unit of the fund token. The API record of each request carries its NAV, units, cash and transaction hash.

## What the platform checks [#what-the-platform-checks]

### On a subscription request [#on-a-subscription-request]

Every refusal by the subscription rules answers HTTP 409 with [DALP-14081](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference#domain-rule-errors). None is retryable as sent. The `reason` field says which rule applied. A new request can return one of the first seven reasons, and a cancellation one of the last three.

| Reason | What it means and what to do |
| --- | --- |
| `token-not-subscribable` | The token is not a fund without register lines. The platform checks this first. Use a fund token that takes dealing. |
| `terms-not-found` | The fund has no subscription terms. A supply manager sets them first. |
| `investor-not-caller` | The wallet is not one of the caller's wallets. Send one of your own. |
| `amount-not-positive` | The amount is zero or less. Send a larger amount. |
| `below-minimum` | The amount is under the minimum of the terms. Send at least the minimum. |
| `investor-ineligible` | The investor cannot receive the token under its identity and compliance rules, or the platform could not verify that. Resolve the identity or compliance cause first. |
| `idempotency-conflict` | The key already recorded a request for another wallet or amount. Use a new key. |
| `request-not-found` | On a cancellation, no request of this token with that identifier belongs to the caller. List your requests and use an identifier from the list. |
| `request-not-open` | On a cancellation, the request is no longer open: it is cancelled, settling, settled or rejected. Read the request for its status. |
| `cut-off-passed` | On a cancellation, the cut-off of the request's dealing day has passed. The request stays open. |

The request records the stablecoin of the terms at that moment.

A retry with the same idempotency key returns the first request only while the token, the terms, the wallet and the amount still pass their checks. The platform runs those checks before it looks for the key and does not repeat the eligibility check on a retry.

### On a subscription settlement [#on-a-subscription-settlement]

Settling a subscription day answers HTTP 409. Every reason except `requests-changed` comes back as DALP-14081, which is not retryable as sent. `requests-changed` comes back as its own code, DALP-14749, which is retryable: send the same call again.

| Reason | What it means and what to do |
| --- | --- |
| `terms-not-found` | The fund has no subscription terms. A supply manager sets them first. A repeat of a stored idempotency key is answered before this check. |
| `token-not-subscribable` | The token is not a fund without register lines, or it does not take subscription settlements. The platform checks this after it finds the terms. Use a fund token that takes dealing. |
| `not-a-dealing-day` | The date is a Saturday or Sunday. Send a weekday. |
| `nav-unavailable` | The feed published no NAV in the day's window, the fund has no price feed set up, the platform has no feed directory, the NAV value cannot be read as a positive decimal, or the NAV prices one unit at zero of the stablecoin. Publish the NAV, then settle again. |
| `no-open-requests` | No subscription request is open for this dealing day or an earlier one. Settle a day that has open requests. |
| `stablecoin-unsupported` | The terms name a stablecoin that is not an indexed ERC-3643 token of the stablecoin type, or is the fund token itself. Set the terms again with another stablecoin. |
| `currency-mismatch` | The NAV and the stablecoin are not priced in the same currency, or one of them names no currency. Choose a stablecoin priced in the NAV's currency. |
| `treasury-not-executor` | The call executes from another wallet than the receiving treasury of the terms. Settle from the receiving treasury, so the allowance each investor gave is the one spent. |
| `requests-changed` | Open requests changed while the platform prepared the settlement. It stored nothing. Send the same call again. |
| `settlement-key-reused` | The idempotency key belongs to a settlement of another dealing day. Use a new key. |

A subscription settlement drafts no corporate action. It sends the transfers and the mint itself, and no row under **Approvals** holds it, so the supply manager who settles from the receiving treasury takes the cash and mints the units with no second person. A repeated call with the same key and dealing day sends again only the batches whose requests are still settling, under the same transaction keys, and then returns the stored settlement. It mints no unit twice. A new key for a day that is already settled takes only requests that are still open through that day. When there are none, the call is refused with `no-open-requests`.

When a batch's transaction is refused or reverts on the first call, the platform returns that batch's requests and every later batch's requests to **Open** and fails the call. Batches that landed before it stay settled. On a repeat call with the same key, a refused batch returns only its own requests to "Open". The platform still sends the other batches, then fails the call. The next settlement takes the reopened requests.

Each request the settlement leaves out records one reason:

| Reason | What it means |
| --- | --- |
| `insufficient-cash` | The investor no longer holds the cash. |
| `cash-not-allowed` | The investor's remaining allowance to the receiving treasury does not cover the cash. |
| `investor-ineligible` | The fund token would not let the investor receive units. |
| `stablecoin-changed` | The request was lodged in another stablecoin than the terms now name. |
| `zero-units` | The cash buys less than the smallest unit of the fund token at that NAV. |

### On the subscription terms [#on-the-subscription-terms]

Setting the terms answers HTTP 409 with the same DALP-14081 and returns `token-not-subscribable` or one of these four reasons.

| Reason | What it means and what to do |
| --- | --- |
| `stablecoin-is-token` | The stablecoin is the fund token itself. Choose another stablecoin. |
| `stablecoin-not-indexed` | The platform has not indexed the stablecoin on this network. Choose one the picker lists. |
| `treasury-invalid` | The receiving treasury is the zero address or the fund token. Choose another wallet. |
| `amount-not-positive` | The minimum is zero or less. Leave it empty or set a positive amount. |

### On a redemption request [#on-a-redemption-request]

Every refusal answers HTTP 409 except DALP-14074, which answers HTTP 404. None is retryable as sent.

| Code | Reason | What it means and what to do |
| --- | --- | --- |
| DALP-14074 | `request-not-found` | No such request belongs to your wallets on this token. This covers another holder's request, another token's request and an unknown identifier. List your requests and use an identifier from the list. |
| DALP-14075 | `holder-not-caller` | The holder is not the wallet that signs the request. Leave the holder out or send the signing wallet. |
| DALP-14076 | `token-not-redeemable` | The token is not a fund that can settle a cash buyback without register lines, or the platform could not read it. Use a fund token that takes dealing. |
| DALP-14077 | `exceeds-available-units` | The amount is over the available units less the wallet's open and settling requests. Frozen units are not available. Send a smaller amount or cancel an open request. |
| DALP-14078 | `cut-off-passed` | A cancellation came at or after the cut-off. The request stays open. |
| DALP-14079 | `request-not-open` | A cancellation hit a request that is not open. The platform answers this before it checks the cut-off. Read the request for its status. |
| DALP-14080 | `idempotency-key-reused` | The key belongs to a request for another token or amount. Use a new key. |

The amount of a redemption request is a positive whole number of base units, with no minimum. When you send the create call again with the same token and amount, it returns the stored request as it stands. A create call without an idempotency key gets one from the server and cannot be repeated. Both a new request and a repeat answer HTTP 201.

### On a settlement [#on-a-settlement]

Every refusal answers HTTP 409. Only DALP-14103 is retryable by sending the same call.

| Code | Reason | What it means and what to do |
| --- | --- | --- |
| DALP-14098 | `not-a-dealing-day` | The date is a Saturday or Sunday. Send a weekday. |
| DALP-14099 | `nav-unavailable` | The feed published no NAV in the day's window, the fund has no price feed set up, the platform has no feed directory, or the NAV gives a price of zero. Publish the NAV, then settle again. |
| DALP-14100 | `no-open-requests` | No request is open for this dealing day or an earlier one. Settle a day that has open requests. |
| DALP-14101 | `stablecoin-unsupported` | The asset is not an indexed ERC-3643 token of the stablecoin type, or it is the fund token. Send another stablecoin. |
| DALP-14102 | `currency-mismatch` | The NAV and the stablecoin are not priced in the same currency, or one of them names no currency. Choose a stablecoin priced in the NAV's currency. |
| DALP-14103 | `requests-changed` | Open requests changed while the platform prepared the plan. It stored nothing. Send the same call again. |
| DALP-14104 | `settlement-key-reused` | The idempotency key belongs to a settlement of another day, stablecoin or treasury. Use a new key. |

A settlement is also refused with DALP-12067 while another corporate action on the token is unfinished, including the buyback of an earlier settlement. Wait for it to complete or stop it, then settle again.

A settlement on a token that does not take redemption requests is refused with DALP-14076. A repeat with the same key and values returns the stored settlement even when the day or the token would now be refused.

The settle sheet shows a message for each refusal. For example, `nav-unavailable` reads "No NAV is published for this dealing day, or it cannot price this stablecoin. Publish a NAV on the fund's price feed, then settle again." and `requests-changed` reads "A request changed while the settlement was being prepared. Check the list, then settle again."

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

- On the **Dealing** tab, the redemption requests of the settled day change from "Open" to "Settling" once you settle, and to "Settled" once each holder's payment is on the chain.
- A settled row shows the "NAV" and the "Cash" the holder received, and a rejected one names its "Reason".
- Subscription terms you saved show on the "Subscription terms" card, with "Last updated".
- Check the buyback in [Corporate actions](https://docs.settlemint.com/docs/console/asset-management/manage/corporate-actions) for the units burned and the cash paid.
- After a subscription day, the "Subscription requests" list shows each settled request as "Settled" or "Rejected", and the API record of each request carries its NAV, units, cash and transaction hash.

## Troubleshooting [#troubleshooting]

**The token has no Dealing tab**

The tab shows only for a fund token that does not use register lines. Opened from a link on any other token, the
screen says "Dealing is not available for this asset". Use [Booked
movements](https://docs.settlemint.com/docs/console/asset-management/manage/booked-movements) for a fund with register lines.

**A redemption request stays Settling**

The buyback has not paid that holder, or the platform has not read the payment. The platform reads the buyback when
someone settles, lists or creates a redemption request on the token, and marks the request **Settled** once the
holder's payment is on the chain. If the buyback was aborted after its confirmation started a transaction, the
platform does not reopen the unpaid requests. They stay "Settling" and their units stay counted against the holder's
available units. A "Settling" request cannot be cancelled, so the holder cannot request a redemption of those units
again.

## Frequently asked questions [#frequently-asked-questions]

### Who approves a redemption, and how is the cash paid out?

The holder's request needs no approval. The settlement turns the day's open requests into one buyback corporate action, which burns the units and pays each holder in the stablecoin from the paying treasury. [Settle a redemption day](#settle-a-redemption-day) says who approves and confirms the buyback.

### Which NAV prices a request?

Both kinds of request get the latest NAV that the fund's price feed published, by block time, from the dealing day's cut-off up to the next dealing day's cut-off, and never later than the moment of settlement. The platform refuses the day when the feed published none. A request from an earlier day is priced at the NAV of the day you settle.

For a redemption, once a request of the day has been paid, every later settlement of the day uses the same NAV. The price per unit and each holder's cash are rounded down. For a subscription, the units are the cash divided by the NAV, rounded down to the token's decimals. The cash taken is those units multiplied by the NAV, rounded up to the stablecoin's smallest unit, so it is never more than the requested cash. A request whose cash buys less than the smallest unit of the token is rejected and mints nothing.

### Can a settlement include requests from earlier days?

Yes. A settlement takes every open request of the chosen dealing day or an earlier one, so a day missed earlier is settled with the next.

## API routes [#api-routes]

| Task | Route |
| --- | --- |
| Read the terms | `GET /api/v2/tokens/{assetId}/subscription-terms` |
| Set the terms | `PUT /api/v2/tokens/{assetId}/subscription-terms` |
| Lodge a subscription request | `POST /api/v2/tokens/{assetId}/subscription-requests` |
| List subscription requests | `GET /api/v2/tokens/{assetId}/subscription-requests` |
| Cancel a subscription request | `POST /api/v2/tokens/{assetId}/subscription-requests/{requestId}/cancellations` |
| Request a redemption | `POST /api/v2/tokens/{assetId}/redemption-requests` |
| List redemption requests | `GET /api/v2/tokens/{assetId}/redemption-requests` |
| Cancel a redemption request | `POST /api/v2/tokens/{assetId}/redemption-requests/{requestId}/cancellations` |
| Settle a redemption day | `POST /api/v2/tokens/{assetId}/redemption-settlements` |
| Settle a subscription day | `POST /api/v2/tokens/{assetId}/subscription-settlements` |

The request and response fields of each route are in [the v2 API reference](https://docs.settlemint.com/docs/api-reference/v2).

A supply manager lists every request of the token. Any other caller lists only requests for their own wallets. The lists filter by `dealingDay` and `status`, and by `investor` for subscriptions or `holder` for redemptions. A `holder` that is not one of the caller's wallets gives an empty page, not an error.

The redemption list is paginated, sorted by creation time with the newest first and never cached.

The redemption settle call answers HTTP 201 with the NAV, its feed, block time and transaction, the price per unit, the corporate action, and the totals of holders, settling requests, rejected requests, units and cash. The subscription settle call answers HTTP 200, or HTTP 202 while a batch is still queued, with the settlement's NAV, its feed, block time and transaction, the price per unit, the stablecoin and receiving treasury, and the same totals.


# Holders

Source: https://docs.settlemint.com/docs/console/asset-management/manage/holder-register
Read who holds an asset now or on a past date, open one holder's figures, see how the supply is split, and export the register for the issuer or the Registrar.

The **Holders** tab lists every wallet that holds the asset, now or at the end of a past day, counted from the platform's index of transfers. It shows what each holder can move now and what is frozen, locked or reserved.

The tab exports the register at a record block, the block whose balances the list reports. The export is either the issuer's official list or a file in the Registrar's layout. The Registrar is the firm that keeps the issuer's register of members.

| Need | Where | What you get |
| --- | --- | --- |
| Who holds the asset now | The holders table | Balance, share of supply, and the available, frozen, locked and reserved parts. |
| Who held it on a past date | **As of** with a date | Balance and share of supply at the end of that day in UTC. |
| How the supply is split | **Who holds the supply** at the top of the tab | The five largest holders, or the holders in five bands of share. |
| One holder's figures | Select the holder | A sheet with every figure and the full address. |
| The rows on screen as a file | **Export**, then **This table as CSV** | A CSV of every row that matches the filters. |
| The official list for the issuer | **Export**, then **Holder register…** | A PDF, CSV or XLSX list at a final record block, checked against total supply. |
| The register in the Registrar's layout | **Export**, then **Registrar file…** | One CSV in the Registrar's layout, a row per wallet, and a check of the Registrar's own file against the chain. |

![Holders tab with the As of button, the Export menu, the Who holds the supply card and the holders table](https://docs.settlemint.com/docs/screenshots/console-holder-register.light.en.webp)

[Screenshot] The "Who holds the supply" card with a bar that splits the supply between the five largest holders and everyone else.

Below the card, the holders table shows the columns "Holder", "Frozen", "Reserved", "Balance", "Share", "Last activity"
and "Status", and the toolbar holds "As of today" and the **Export** menu.

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

- Open the asset from [All assets](https://docs.settlemint.com/docs/console/asset-management/all-assets) and select **Holders**.
- A past date and the register exports need the Historical balances feature, which the Console adds only at issuance, when the asset's template includes it. Without it, the "As of" calendar offers only the current day, and the **Export** menu holds only "This table as CSV". An asset whose feature was later detached keeps the register exports, which read the blocks before the detachment.
- The register entries of the **Export** menu need reporting access: an organisation owner, a platform administrator, or a wallet with the Permission manager, Auditor, Compliance manager or System manager role on the organisation's system. Everyone else sees only "This table as CSV".

## Steps [#steps]

### Read the current register [#read-the-current-register]

The table shows 20 rows a page, largest balance first. The columns are:

- **Holder**: the name of the user, participant or contact that owns the address, the name of the token or system contract it is, or the short address when nothing names it.
- **Frozen**, "Reserved", "Balance" and "Share": the frozen units, the units a hold reserves, such as an open trading venue order, the total balance, and the balance as a percentage of total supply.
- **Last activity** and "Status": the last balance change, and "Active", "Partly frozen", when some of the balance is frozen, or "Frozen", when the address is frozen or the whole balance is.
- **Available**, "Locked" and "Next unlock": what the holder can move now, the units a time lock or lock-up holds, and the next unlock date. These three start hidden. Open "View" to show them.

"Available" is the balance less what is frozen, reserved or locked. Use the **Status** filter to list holders whose address is frozen, or the others. "Active" in the filter also returns partly frozen holders.

### Read how the supply is split [#read-how-the-supply-is-split]

The card "Who holds the supply" sits at the top of the tab, or "Who held the supply on" a date in a past view. Its bar shows the five largest holders and "Everyone else". Switch **Distribution view** to "Share bands" to count the holders in five bands of the supply: "Over 25%", "10 to 25%", "5 to 10%", "1 to 5%" and "Under 1%". A holder on a band's lower edge counts in the larger band. The card reads the 100 largest holders and counts every holder after them in "Under 1%". The card is left out when nobody holds the asset.

### Show a past date [#show-a-past-date]

Select **As of today** in the table toolbar and pick a day in the calendar. The table shows the register at the end of that day in UTC, and the button reads "As of" with the date. Picking the current day shows the current register. The calendar offers no future day and none before the token was created or its balance history began.

A past view shows only the holder, the balance and the share of supply, sorted by balance. The other columns and the "Status" filter do not show. The date stays in the address as `?asOf=`, so you can share the view. **Back to today** returns to the current register.

### Open one holder [#open-one-holder]

Select a holder's name. A sheet opens with the balance, the share, the available, locked, frozen and reserved amounts, the status, the next unlock, the last activity and the full address with a copy button. In a past view the sheet lists only the balance, the share and the address. The address stays in the URL as `?holder=`, so a link reopens the same sheet.

### Export the register [#export-the-register]

Open **Export** in the table toolbar:

- **This table as CSV** exports every row that matches the filters, not only the loaded page. In a past view the filename carries the date, such as `token-holders-as-of-2026-10-12.csv`.
- **Holder register…** opens the sheet "Export holder register" on its "Register" tab. The sheet opens at the block you entered in the table's "As of" control. In a past-date view it opens at the last final block at or before the end of that day, and shows the date and that block in the "As of" row. If the network has no block that early, the sheet says so and reads nothing until you choose "Newest final block" or "Block". Otherwise it opens at the newest final block.

  Choose **Block** to enter another record block. A final block is one a chain reorganisation can no longer change, so the record block can trail the newest block by a short time. The sheet shows the record block and its time, the number of holders, "Units held", "Total supply" and "Adds up".

  Choose the **Format**, which is CSV by default, then select "Download CSV", "Download XLSX" or "Download PDF", whichever matches the format.

  An owner of the organisation or a platform administrator also sees **Deliver to issuer**, which schedules a delivery of the list to the issuer. The "Deliveries" tab shows it.

- **Registrar file…** opens the "Registrar file" tab, which exports the register in the Registrar's layout and reconciles a file the Registrar sends back. It uses the block the "Register" tab read, and its buttons stay unavailable until that read answers.
- **Beneficial owners…** opens the "Beneficial owners" tab. A nominee is a firm, such as a custodian or broker, that holds the security in its own wallet for others.

  Under "Declare beneficial owners", enter that wallet in "Nominee wallet", choose a CSV file of the owners in the layout [Issuer shareholder list](https://docs.settlemint.com/docs/api-reference/guides/issuer-shareholder-list) describes, and select **File declaration**. A user whose wallet is the nominee wallet can file for it, and an organisation owner or a platform administrator can file for any nominee wallet. The declaration is a platform record, not an on-chain fact. It is stored only when its units add up to the wallet's balance at the record block, and nothing checks the owners it names.

  Under **Register by beneficial owner**, the tab lists the register with each declared wallet replaced by its owners, and says whether it adds up to the total supply at the record block. A wallet whose balance changed after its declaration is listed whole as a direct holding, so the owners behind it are missing from this register until the nominee files again.

- **Issuer deliveries…** opens the "Deliveries" tab, with the lists the platform produced for the issuer. The menu entry counts the deliveries still pending.

On a [mirror token](https://docs.settlemint.com/docs/concepts/records-and-evidence/mirror-tokens), the sheet also has a **Reconciliation** tab. It lists the daily reconciliation runs with their "Date", "Outcome" ("Clear", "Break" or "No statement"), number of "Breaks", "Version" and "Cut-off".

Select **View** on a run to see each investor line that does not match the statement, with its ISIN when the token records one, the statement and on-chain quantities and the difference. "Export CSV" saves those lines.

When **Adds up** reads "No", the sheet says "Units held do not add up to total supply at this block. Do not send this list." "Deliver to issuer" is then unavailable. The download still works. [Issuer shareholder list](https://docs.settlemint.com/docs/api-reference/guides/issuer-shareholder-list) describes the file columns, the deliveries, the Registrar exchange and every refusal.

## Read your own balance at a block [#read-your-own-balance-at-a-block]

1. Select **As of today**.
2. Enter the block under **Block number**.
3. Select **Apply**.

In place of the table, a card titled "Your balance at block" and the block number appears. It shows your balance at that block, and the block and time at which that balance last changed. The balance is that of the wallet that signs your actions, the wallet of the participant you are working as. A block ahead of the indexed chain shows a notice that names the latest indexed block, and the balance at that block. A user without a wallet sees "Sign in with a wallet to see your historical balance." The block stays in the address as `?atBlock=`. For a user with reporting access, the **Export** menu then holds the register entries, without "This table as CSV", and opens the export sheet at that block.

## Act on holders from the table [#act-on-holders-from-the-table]

"Burn", "Freeze", "Unfreeze" and the lock-up actions each need a role on the asset and are not offered in a past view.

- **Burn** in a row's menu opens the burn form for that holder with the whole balance filled in, frozen units included, on a burnable asset. The burn releases as much of a partial freeze as it needs, and the chain refuses it for an address that is fully frozen. It needs the Supply management role. See [Mint and burn](https://docs.settlemint.com/docs/console/asset-management/manage/mint-burn).
- Tick holders, then choose **Freeze** or "Unfreeze" to freeze or release part of each selected balance in one signed request, with a reason. Both need the Custodian role, and without it the action reads "You do not have the custodian role for this token." See [Emergency halt and freeze](https://docs.settlemint.com/docs/console/asset-management/manage/pause-freeze).
- **Set lock-up** and "Clear lock-up" in a row's menu set or clear a holder's lock-up on an asset with a lock-up rule, for a Governance role holder.
- **Copy address** and "View on Explorer" copy the holder's address or open it on the network's block explorer. They need no role and stay available in a past view.
- **View access on** a venue, in a row's menu, opens the holder's participant page on each trading venue that lists the asset. It shows for an organisation owner, a platform administrator or a Venue manager.
- **View profile**, in a row's menu, opens the participant page of the user or entity that owns the holder's wallet. It shows only when your search can name that wallet, so an external wallet or a wallet outside your organisation has no "View profile".

While a write you signed is confirming, the rows it changes show the old balance, the new one and "Confirming…" until the platform has read the block that confirms it. When it settles, the rows stay where they were even if the new balances change the order. A holder the write adds waits behind the "1 new" pill, and choosing it puts the rows back in balance order.

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

- In the export sheet, **Adds up** reads "Yes" for the record block you chose, and the downloaded file carries that block in its name.
- A past view names its date on the "As of" button and in the name of the exported file.

## Troubleshooting [#troubleshooting]

**The calendar offers only the current day**

Signal: **As of** lets you pick the current day and no other. Cause: the asset has no Historical balances feature, so
the platform keeps no balance history for it. Fix: none for this asset, because the feature is added at issuance only.
Export today's register with "This table as CSV", and issue later assets from a template that includes the feature.

**A link shows a notice instead of the table**

Signal: the tab reads, for example, "No balance history for" a date, or that the date is in the future or "The date in
this link is not valid". Cause: the asset cannot answer for that date. Fix: select **Back to today** or pick a day the
calendar offers.

**Export holds only This table as CSV**

Signal: the menu has no "Holder register…" or "Registrar file…". Cause: your account has no reporting access, or the
asset has no Historical balances feature. Fix: ask a Permission manager to grant you the Auditor, Compliance manager
or System manager role, or check the asset's **Features** tab.

**Adds up reads No**

Signal: the export sheet says not to send the list. Cause: the holders' balances do not equal total supply at that
block. Fix: do not send the list or the downloaded file. Contact support with the asset and the block.

## Frequently asked questions [#frequently-asked-questions]

### Is the holder register the same as a cap table?

No. The holder register lists every wallet that holds the asset, now or at a past moment. A cap table lists the investors of one primary offering, on the **Cap table** tab of that offering.

### Does the register look through a custodian's wallet?

The holders table does not. Units in a custodian's shared wallet appear under that wallet. The **Beneficial owners** tab of the export sheet lists the register looked through to the owners a nominee declared, as [Export the register](#export-the-register) describes. On an external token, the register counts only the wallets your organisation watches.

## API routes [#api-routes]

`GET /api/v2/reporting/fund-registers` reads one register across the class tokens of a fund, on one network or several, with up to 8 classes, each given once as a network and a token address. It needs reporting access. Each class is read at its own newest final block. The answer gives each holder's units per class, each class's totals and whether they add up to its supply, and the fund's totals valued at each class's NAV. The fund's total value stays empty when a class has no NAV or the classes quote different currencies. For one class, the asset's "Dealing" tab has a **Fund register** section. The [Platform API reference](https://docs.settlemint.com/docs/api-reference/v2) lists the request and the answer.


# Mint and burn

Source: https://docs.settlemint.com/docs/console/asset-management/manage/mint-burn
Mint new units to a recipient or burn units from any holder's wallet, from the asset's token page.

Mint and burn are the Console controls that add or remove units of an asset on request. Mint creates new units and assigns them to one or more recipients, which raises total supply. Burn permanently removes units from a holder's balance, which lowers total supply. A minted unit lands in a recipient's balance. A burned unit has no recipient. Offerings, [corporate actions](https://docs.settlemint.com/docs/console/asset-management/manage/corporate-actions), a management fee collection, a fund's subscription settlement, a holder's redemption at maturity and a supply delegate that a Governance holder registers change supply too.

To move units between holders with total supply unchanged, use [Transfers](https://docs.settlemint.com/docs/console/asset-management/manage/transfers). To stop a holder's units from moving, use [Emergency halt and freeze](https://docs.settlemint.com/docs/console/asset-management/manage/pause-freeze).

![Mint tokens page with an empty Recipient and Amount row, Add recipient and the total against the mint limit](https://docs.settlemint.com/docs/screenshots/console-mint-burn-form.light.en.webp)

[Screenshot] The "Details" step shows one row with "Recipient" and "Amount".

Below the row come "Add recipient", then the requested total with "Max mintable (applies to entire transaction)" and "Subject to compliance limits". When a fee applies, the previewed fee shows in the same summary.

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

- Both operations need the asset's Supply management role on one of your wallets. When none of your wallets holds any role on the asset, "Mint tokens" and "Burn tokens" do not appear. When you hold another role but not Supply management, they show greyed out. When the role sits on another of your wallets, the entry cannot be selected and shows "The role for this action sits on wallet" and the wallet address, followed by "Switch to that wallet to use it." Neither operation can run while the asset is halted, or while a corporate action that changes the asset's units is in progress. Mint also needs room under the applicable supply ceiling. Burn needs the asset to carry the burnable feature and the target holder to have a positive balance. Frozen units count towards that balance, and no freeze protects a balance from a burn: a burn ignores a freeze of the whole address and releases only the frozen units it needs.
- No row under "Approvals" holds a mint or a burn for a second person, so one Supply management holder acts alone. On a token with Booked movements, these pages book a movement instead and ask for a **Register reference**, as [Booked movements](https://docs.settlemint.com/docs/console/asset-management/manage/booked-movements#mint-burn-or-force-a-transfer) describes.

## Steps [#steps]

### Open mint or burn [#open-mint-or-burn]

Open "All assets" and select the asset. For a mint, open "Actions" and choose **Mint tokens**.

For a burn, open "Actions" and choose **Burn tokens**, then pick the holder.

From the "Holders" tab you can also open a row menu and choose **Burn**. The burn form then opens with that address and its whole balance filled in. For a burn, the row shows the address's balance as its cap. Under an amount, a line shows its fiat equivalent at the token's price, for example "≈ $2,000.00". When the token has no price, the line says that no price is set for the token, so there is no fiat equivalent.

Each form opens on its own page under the asset, with a breadcrumb back to the asset, and **Cancel** returns you to where you came from. Both forms accept more than one row. A mint can name multiple recipients in the same operation, each with its own address and amount, added or removed before you submit. A burn opened from one holder's row can still add rows for other addresses in the same submission.

![The Actions menu of an equity, listing Mint tokens and Burn tokens among its controls](https://docs.settlemint.com/docs/screenshots/console-manage-asset-menu.light.en.webp)

[Screenshot] The "Actions" menu lists "Mint tokens" and "Burn tokens" among the other controls the asset and the signed-in account allow.

The "Holders" tab carries the per-address burn control.

### Enter the allocations [#enter-the-allocations]

For a mint, add each recipient address and amount. Each address must be a verified holder of the token, and the chain refuses a mint to an address frozen on the token. An address that is not verified blocks its own row with an ineligibility message until you enter one that qualifies. **Max mintable (applies to entire transaction)** shows the lowest of the room left under the token's own cap, under a maximum-supply compliance rule that applies to every transfer, and under the collateral claim. The form blocks continuing with "Total amount exceeds allowed limit" once the running total would cross it. Other compliance rules that limit supply, such as a capital-raise, token-supply or issuance-volume limit, have no figure the Console can compute, and the form relies on the chain to reject a mint over them. On an asset with any compliance rule that limits supply, a maximum-supply rule included, the form adds "Subject to compliance limits". With no limit of any kind, the form reads "No minting limit". When a mint fee applies, total supply still rises by the full amount you entered, but the recipient's own balance rises by less. The review screen names the net amount the recipient keeps and the fee amount.

For a burn, each row is capped at the address's total balance, frozen units included, as the form hint "The total balance, including frozen units, can be burned." says. When the address holds frozen units, the row adds "of which" the frozen amount "is frozen". A partial freeze does not stop the burn, but a full freeze does: the chain refuses a burn from an address frozen on the token, so a custodian forced-transfers the units out or lifts the freeze first. The asset's own configuration sets whether a burn fee applies, its rate, and who receives it. You choose none of that here. When a burn fee applies, the amount you enter is what leaves the holder's balance, but total supply falls by a smaller net figure. The one exception is a row whose holder is also the fee recipient: no fee applies on that row, and the full amount comes off supply. Review the total requested across all rows and the fee the Console previews before continuing.

### Confirm the supply change [#confirm-the-supply-change]

Select "Review". The review step names the account the transaction runs from and its signing key, then shows the supply before and after and each recipient, or for a burn each address, with its amount. Check the operation, addresses, amounts and fees. When a fee applies, the review also names the account it goes to. A confirmed burn cannot be undone, and a fresh mint creates new units without returning the destroyed ones. Select **Confirm mint** or "Confirm burn" and confirm with your wallet verification. The chain updates total supply and the affected balances in one transaction, so every row applies or none does.

A mint sent to the wrong address has no recall control. To correct it, burn the units from that address, which needs Supply management, or move them with a forced transfer on [Transfers](https://docs.settlemint.com/docs/console/asset-management/manage/transfers), which needs the Custodian role.

![Review step of Mint tokens with the executing account, the supply change and one recipient](https://docs.settlemint.com/docs/screenshots/console-mint-burn-review.light.en.webp)

[Screenshot] The "Review" step shows "This transaction will execute from:" with the account and its "Signing key", then "Review mint" with "Current supply" and "New supply", then "Recipients" with each amount.

The "Confirm mint" button sends the transaction.

## What limits a mint [#what-limits-a-mint]

A fixed supply cap is a flat maximum set on the token itself. Collateral-backed capacity ties the ceiling to a collateral claim a trusted issuer has signed and filed. What the chain checks is that such a claim is present, correctly formed, and unexpired, and it takes the amount from the claim. The chain does not check that the reserve the claim describes exists. Minting stops once the claimed amount is used up, so the cap follows the issuer's attestation. A compliance-module cap comes from a compliance rule attached to the token and enforced on-chain. The Console computes the room left only for a maximum-supply rule that applies to every transfer, and leaves every other rule that limits supply to the chain.

[Figure] Mint adds to total supply up to a ceiling. Burn removes from it up to a balance. Mint increases supply subject to the token's configured limits: a fixed supply cap, collateral capacity, or a compliance-module cap. The strictest applicable limit controls the operation. The Console limits burn to the holder's total balance, frozen units included, and a burn releases only the partially frozen units it needs, and a fully frozen address refuses the burn. Burning destroys units without transferring them to a recipient. Labels: Mint; Fixed supply cap; Collateral-backed capacity; Compliance-module cap; The strictest configured limit applies.; adds, within the ceiling; Total supply; removes, within the balance; Burn; Holder's total balance; Frozen units count towards it.; No recipient. The tokens cease to exist.

Mint adds supply up to the smallest of a fixed cap, collateral-backed capacity and a compliance-module cap, and burn removes units with no recipient.

## Mirror tokens [#mirror-tokens]

A [mirror token](https://docs.settlemint.com/docs/concepts/records-and-evidence/mirror-tokens) stands for a holding kept off chain. On one, the Mint and Burn sheets show where the holding sits and require the external reference, the custodian's or registrar's transaction id. Each mint or burn takes one movement, and a burn takes only your wallet's own units.

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

- Confirm "Tokens minted successfully" or "Tokens burned successfully".
- Open the asset overview to compare total supply against what you expected: the full requested amount for a mint, or the net amount after any burn fee for a burn.
- Open **Holders** to compare each affected balance.
- If a fee applied, check the recipient's or holder's balance against the net figure the review screen named, not the amount you entered.

## Troubleshooting [#troubleshooting]

**Continue stays blocked although every row is valid**

Signal: on a mint or a burn, every address and amount row looks valid, no cap warning shows, and **Continue** still
does not respond. Cause: checks outside the row data itself can hold it closed. The fee preview at the bottom of the
form reads "unavailable" while the token's fee configuration is still loading or failed to load, and "Continue" waits
for a definite fee before it lets you proceed. When fees use a different token, the Console checks the paying wallet's
fee-token balance and allowance. The operation stays blocked until the check succeeds and both cover the fee. The
panel identifies any shortfall. On a burn, "Continue" also waits until the Console has read the balance of every
address in the form. While that read is loading or has failed, no row shows a balance. Fix: wait for the fee preview
and each row's balance to resolve and retry. If either keeps reading "unavailable" or stays empty, reload the form. If
a separate fee-token panel names an insufficient balance or allowance, fund or approve that token for the paying
wallet, then reopen the form.

**The Mint tokens entry is missing from the menu entirely**

Signal: "Actions" opens but has no **Mint tokens** entry at all, not even a greyed-out one. Cause: none of your
wallets holds any role on this token. A wallet that holds another role but not Supply management sees the entry greyed
out instead. Fix: ask an administrator to grant the Supply management role on this asset to the wallet that signs your
actions, which is the wallet of the participant you are working as.

**Mint tokens cannot be selected**

Signal: the **Mint tokens** entry is visible in the "Actions" menu but greyed out. Cause: one of these gates is
closed. Your wallets hold a role on the asset but not Supply management, and the menu then shows no message. The asset
is halted, the role sits on another of your wallets, a corporate action that changes the asset's units is in progress,
the asset has matured and minting is closed, or, on a collateral-backed asset, no collateral is recorded, collateral
capacity is exhausted, or its status is still loading or failed to load. A fixed supply cap and a compliance-module
cap never grey out this entry. Both are checked only once you open the form and enter an amount. Fix: read the message
the menu shows next to the entry. It names the gate, for example "Token operations are halted. Resume token operations
to perform this action." or a message that the corporate action "is in progress on this asset. Minting waits until it
finishes." A halted asset needs resumed operations first, a role on another wallet needs that wallet, a corporate
action needs to finish or be aborted, and a collateral gate needs more collateral filed or the status to finish
loading. The collateral messages read "Minting is blocked until sufficient collateral is added.", "Reading
collateral…" and "Collateral could not be read."

**The requested mint total is rejected inside the form**

Signal: the address and amount rows look valid, the form shows "Total amount exceeds allowed limit", and continuing
stays blocked. Cause: the running total across all recipient rows exceeds whichever supply ceiling binds, the fixed
cap, the collateral-backed capacity, or a maximum-supply compliance rule that applies to every transfer. Fix: reduce
the total requested, or split it into a smaller mint now and a second one once more capacity is available.

**A mint recipient address does not clear**

Signal: the address field shows "This recipient is not a verified holder of this token." and **Continue** stays
blocked. Cause: the address has not completed the eligibility check this token requires. This is separate from your
own role and from any supply cap. Fix: confirm the address has completed whatever verification this token requires
before it can receive tokens, or enter a different, already-eligible address.

**A holder row has no burn control at all**

Signal: the row's menu has no **Burn** entry, not even a disabled one. Cause: the asset does not carry the burnable
feature, the holder's balance is zero, your wallet does not hold the Supply management role on the token, or the table
shows a past date. Fix: confirm the asset supports burning, confirm the holder has a balance greater than zero, switch
the register back to the current day, and confirm the role on the wallet that signs your actions.

**A holder row shows Burn but it is disabled**

Signal: the **Burn** entry appears on the row but cannot be selected. Cause: the asset is halted, or a corporate
action that changes the asset's units is in progress. Fix: the message on the entry names which one applies. A halted
asset needs resumed operations, and a corporate action needs to finish or be aborted.

**A burn amount is capped below the balance**

Signal: the amount field caps out below the amount you want to burn. Cause: the same address appears in more than one
row in the same submission. The Console totals those rows and checks the sum against that one balance, not each row on
its own. Fix: lower the amount, or combine the rows for that address into one row.

**Mint or burn is blocked while a corporate action runs**

Signal: the **Mint tokens** entry, or a holder row's "Burn" entry, is disabled and the menu shows "Stock split is in
progress on this asset. Minting waits until it finishes." or "Stock split is in progress on this asset. Burning waits
until it finishes.", with the name of whichever corporate action is running. Cause: an asset takes one corporate
action that changes supply at a time, and a run that has not completed or been aborted also blocks a direct mint or
burn. A mint or burn sent over the API in that window is refused with HTTP 409 `CORPORATE_ACTION_IN_FLIGHT`
(`DALP-12067`), and `data.corporateActionId` names the run that holds the asset. A run that has ended and is only
releasing the custody it froze (status "Releasing custody") does not block a mint or burn, and neither does an action
whose approval was rejected, cancelled or lapsed before it ran. Fix: wait until the run completes, or abort it from
the [Corporate actions](https://docs.settlemint.com/docs/console/asset-management/manage/corporate-actions) screen, then mint or burn again.

## Frequently asked questions [#frequently-asked-questions]

### Why does the mint form show Subject to compliance limits instead of a number?

The Console can turn only the maximum-supply compliance rule into an exact remaining amount, because its maximum is a single token-denominated total on the module's own configuration. The Console counts it only when they apply to every transfer. Other modules that limit supply, such as a capital-raise, token-supply or issuance-volume limit, cap minting on-chain too. Nothing the Console reads exposes enough to compute a reliable remaining figure for them, so the form shows **Subject to compliance limits** in place of a number. When an asset with any module that limits supply also has a computable limit, the form shows that number and adds "Subject to compliance limits" beneath it. The chain enforces those modules on a mint whatever the form shows.

### Is the Supply management role the same role that controls emergency halt and freeze?

No, they are separate roles. Mint and burn both check for the Supply management role, while emergency halt and resume check the emergency role and freeze and forced transfer check the custodian role, described on [Emergency halt and freeze](https://docs.settlemint.com/docs/console/asset-management/manage/pause-freeze). An account can hold any combination of these on a given asset, so having one does not carry over to the others.

### Does burning a holder's tokens need that holder's approval?

No. An account with the Supply management role opens the burn from the holder's row in the **Holders** tab and confirms it with their own wallet verification. The holder does nothing and is not asked.

### Does a burn need the same eligibility check a mint recipient does?

No. A mint recipient must already be a verified holder of the token because minting can hand tokens to an address that has never held them before. A burn never introduces a new address. It only reduces a balance that is already listed on the **Holders** tab, so there is no equivalent eligibility gate to clear, only the balance cap from the burn form.


# Emergency halt and freeze

Source: https://docs.settlemint.com/docs/console/asset-management/manage/pause-freeze
Halt holder transfers, mints, burns and redemptions across an asset, or freeze a stated amount at one address so its holder cannot move it.

An emergency halt stops every holder transfer, mint, burn and redeem on one asset until an authorised operator resumes token operations. A custodian's forced transfer and a lost-wallet recovery still run while it is halted. The contract and API call this state `paused`. A partial freeze holds back a stated amount at one address so those units cannot move, while transfers continue everywhere else. Halt when the concern is with the asset itself, for example a suspected issue with the contract. Freeze when the concern is with one holder's position and the rest of the market should keep trading.

Forced transfer sits in the same menu and moves tokens out of a holder's address without consent. It cannot be undone, and [Transfers](https://docs.settlemint.com/docs/console/asset-management/manage/transfers) covers it. To stop one wallet on every token it holds, use [Restrict a wallet](https://docs.settlemint.com/docs/console/participants/restrict-a-wallet). It freezes the address on each token where you hold the custodian role with one request, stores a reason, and lifts the freezes together. Each token it freezes then lists the wallet on its **Blocklist** tab.

![The Emergency halt token operations page with the State change comparison from Active to Halted](https://docs.settlemint.com/docs/screenshots/console-emergency-halt-page.light.en.webp)

[Screenshot] The "Emergency halt token operations" page shows the "State change" card, with the "Current state" "Active" next to the "Target state" "Halted".

The **Emergency halt** button on that page submits the change after wallet verification.

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

- **The Emergency role, to halt or resume.** Emergency halt and resume need the "Emergency" role on the asset.
- **The Custodian role, to freeze or unfreeze.** Freeze and unfreeze need the "Custodian" role on the asset, and the controls appear only on an asset that carries the custodian capability. A Permission manager grants both roles.
- **Your roles kept apart, where your rules ask for it.** The two roles are separate, so authority to halt the whole asset and authority to freeze one holder's balance can sit with different people. The platform keeps them apart only when your organisation's segregation of duties rules say so. The Custodian role that freezes also carries forced transfer.
- **The wallet that holds the role.** Each control appears only when one of your wallets holds its role. When the role sits on another of your wallets, the entry cannot be selected and shows "The role for this action sits on wallet" and the wallet address, followed by "Switch to that wallet to use it."
- **A second person, when your organisation asks for one.** A halt or resume sent through the Console or the Platform API waits for a second person only while the "Administration" row under "Approvals" on [General](https://docs.settlemint.com/docs/console/organisation-settings/general#approvals) protects the "Pausing" group, and a freeze or unfreeze only while it protects the "Freezing" group. A wallet that holds the role and calls the token contract directly needs no second person.
- **A record of the reason for a halt.** A halt has no reason field, so record the reason outside the Console when your institution's process requires it. A freeze records its reason in the audit trail.

## Steps [#steps]

### Open the control [#open-the-control]

Open "All assets", select the asset, and open **Actions**. Each action opens on its own page under the asset, with a breadcrumb back to the asset, and "Cancel" returns you to where you came from. Pick the control that fits the intervention:

- Choose **Emergency halt** or "Resume token operations" for the whole asset. The menu shows whichever one the current state allows.
- Choose **Freeze partial balance** or "Unfreeze partial balance" for a specified amount at one address.
- To freeze or release part of several balances at once, tick the holders on the "Holders" tab and choose **Freeze** or "Unfreeze", as [Holder register](https://docs.settlemint.com/docs/console/asset-management/manage/holder-register#act-on-holders-from-the-table) describes.

![The Actions menu of a live equity, listing Emergency halt, Freeze partial balance and Unfreeze partial balance](https://docs.settlemint.com/docs/screenshots/console-manage-asset-menu.light.en.webp)

[Screenshot] On a live asset, "Actions" lists "Emergency halt" for the whole asset and "Freeze partial balance" and "Unfreeze partial balance" for one address, among the other controls.

### Halt or resume the asset [#halt-or-resume-the-asset]

There is no address or amount to enter. Read the **State change** card, which shows the asset's current state next to the state your change produces, both drawn from what the Console knew when the page opened. The comparison cannot see a change a colleague makes after the page opens, so the page also asks the platform whether the change would be refused now and shows the reason, for example that your wallet does not hold the Emergency role. When a colleague has already halted or resumed the asset, the card shows the asset's actual state on both sides and the page says so plainly, for example "Bond A is already halted, so there is nothing to change." The submit button stays disabled until the check passes. When the check cannot run, the page says so and the change is still checked when you confirm.

Select **Emergency halt** or "Resume token operations" and confirm with your wallet verification. The contract changes only the halt state and moves no tokens.

## Freeze part of a balance [#freeze-part-of-a-balance]

Enter the target address and amount, choose the reason and optionally add a note, then select **Review** and confirm with your wallet verification. The platform records the reason and note in the audit trail. Under the amount, a line shows its fiat equivalent at the token's price, for example "≈ $2,000.00". When the token has no price, the line says that no price is set for the token, so there is no fiat equivalent.

![Freeze partial balance page with Address to freeze, Amount to freeze, Reason and Note](https://docs.settlemint.com/docs/screenshots/console-freeze-partial-form.light.en.webp)

[Screenshot] The "Details" step shows the required "Address to freeze", "Amount to freeze" and "Reason" fields, then the optional "Note" field with its 500-character limit.

**Review** stays disabled until the required fields are filled.

The amount you can freeze is capped at that address's available balance, its total balance minus whatever is already frozen there. The contract rejects a freeze that asks for more than that remainder instead of freezing what it can. To freeze everything the address holds, enter its available balance. The part already frozen stays frozen. An unfreeze is capped at what is frozen at that address, and you can release any amount up to that total in one request. Releasing a freeze does not increase the holder's total balance.

An emergency halt does not block the freeze controls: freeze and unfreeze carry no halt check in the Console or in the contract, so a custodian can still freeze or release a balance while the asset is halted. When the intervention needs both, the order does not matter.

The "Block" and "Unblock" sheets on the asset's **Blocklist** tab, which freeze or unfreeze every token of one address, check the change before the PIN. While you fill in the address, the sheet asks the platform whether the change would be refused now, for example because your wallet does not hold the Custodian role on the asset, and shows the reason and the fix. "Review" stays disabled until the check passes. "Unblock" is refused while an active [wallet restriction](https://docs.settlemint.com/docs/console/participants/restrict-a-wallet) covers the address on this asset, because unfreezing one token would undo part of the restriction. Lift the restriction instead. The Platform API answers the same request with 409 `TOKEN_ADDRESS_RESTRICTION_ACTIVE`.

Through the Platform API, these routes require a `reason`, which is a reason code and a note of up to 500 characters:

- An address freeze, `PUT /api/v2/tokens/{assetId}/address-freezes`.
- A partial freeze, `POST /api/v2/tokens/{assetId}/partial-freezes`.
- A partial unfreeze, `POST /api/v2/tokens/{assetId}/partial-unfreezes`.
- A batch partial freeze or unfreeze, `POST /api/v2/tokens/{assetId}/partial-freezes/transitions`.

The note is optional, except for the code `other`, which needs one. A request without a reason is refused. The platform stores it with the freeze or unfreeze and records it in the audit trail, and [Reason codes](https://docs.settlemint.com/docs/console/participants/restrict-a-wallet#reason-codes) lists the seven codes.

## Reverse a control or force a transfer [#reverse-a-control-or-force-a-transfer]

A halt, resume, freeze or unfreeze is reversed by its opposite transaction: resume undoes a halt and unfreeze releases a frozen amount. The opposite transaction needs the same role, your wallet verification and gas, and the contract enforces no cooldown. Transfers that reverted while the asset was halted stay reverted.

Forced transfer is the one control in the menu that moves tokens. It runs while the token is halted, ignores a block on the sending address and skips the compliance modules. It still checks the receiving wallet's identity and refuses a blocked receiving address. A freeze does not block it either: if the free balance is too small, the operation unfreezes enough units to cover the shortfall, then moves the tokens, and the remaining frozen balance stays frozen. The forced transfer form shows the sender's frozen amount in the pre-check and, on the review step, how much of the freeze the transfer releases, before you enter your wallet verification. A lost-wallet recovery also runs while the token is halted. Use freeze to hold a balance in place, and use forced transfer only when tokens must move out of a wallet regardless of who holds them or what is frozen there.

[Figure] Emergency halt and freeze are reversible. The third control in the same menu is not. An emergency halt stops ordinary token operations across the asset and requires the emergency role. A partial freeze restricts an amount at one address and requires the custodian role. Reversing either state requires another authorised transaction and can incur gas costs. Freeze controls stay available while the asset is halted. A forced transfer also requires the custodian role, moves tokens, and has no undo control. It can bypass the halt at the contract level. Labels: Actions menu; Emergency halt; Emergency role; Whole asset; every holder at once; Reversible; resume with authorisation; Freeze controls stay; available while active.; Partial freeze; Custodian role; One address; a stated amount; Reversible; unfreeze with authorisation; Leaves every other address; untouched.; Forced transfer; Custodian role; One address; sends tokens out; Cannot be; undone; The only one of the three; that moves tokens.

Freeze and forced transfer both need the custodian role: a freeze restricts a balance until unfrozen, and a forced
transfer moves it with no undo control.

## What a halt and a freeze leave unchanged [#what-a-halt-and-a-freeze-leave-unchanged]

A halt and a resume leave every recorded balance unchanged. The halt check runs when a transfer executes on chain, not when it is submitted. A transfer that is still unmined when the halt lands reverts. It does not queue or wait for operations to resume. A partial freeze does not stop the frozen address from receiving new tokens, only from moving the frozen portion out. Every confirmed halt, resume, freeze and unfreeze appears as its own entry on the asset's **Activity** tab with the transaction hash and the sending wallet. Auditors with access to the asset, and anyone reading the chain, can see when a control changed and which wallet changed it.

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

- After an emergency halt or resume, refresh the token page and read the status badge beside the asset name.
- After a partial freeze or unfreeze, open **Holders** and check the address's frozen amount and its status badge.
- Open "Activity" and match the entry to the transaction hash before you close the intervention.

## Troubleshooting [#troubleshooting]

**The control is missing**

Freeze and unfreeze only appear on an asset that carries the custodian capability, and forced transfer needs the same
capability. A DALP asset always carries these controls in its contract, and only a token of an older asset family can
lack them. A control is also absent when none of your wallets holds its role on this asset: the emergency role for
emergency halt and resume, the custodian role for freeze, unfreeze and forced transfer. Confirm the asset's configured
capabilities and your roles before you assume the control has moved somewhere else.

**The control cannot be selected**

The role for the control sits on another of your wallets. The menu names that wallet: "The role for this action sits
on wallet", the address, then "Switch to that wallet to use it." Switch the wallet that signs your actions, which is
the wallet of the participant you are working as, to the one the menu names. Roles are asset-scoped, so a role on one
asset does not carry to another.

**Two operators change the emergency state at once**

If a colleague halts or resumes the asset after you open the page, the page still shows the state it read when it
opened. The platform refuses your change before anything is queued with [DALP-9488](https://docs.settlemint.com/docs/api-reference/errors), HTTP
409. A request that reaches the chain anyway fails there: a halt that finds the asset already halted fails with
[DALP-1109](https://docs.settlemint.com/docs/api-reference/errors), and a resume that finds it already active fails with
[DALP-9059](https://docs.settlemint.com/docs/api-reference/errors). An asset on an older token implementation reports the two codes the other way
round. The Console shows the same message for every case: the asset's name followed by "is already halted. Nothing was
changed." or "is already active. Nothing was changed." There is nothing to undo. Refresh the token page and check that
the status badge shows the state you wanted.

**A partial freeze fails**

The requested amount exceeds the address's available balance, its total balance minus whatever is already frozen
there. Check the **Holders** tab for the address's current available amount before you retry, and freeze that amount
or less. To freeze the whole current balance, freeze its available portion. The existing frozen portion already
remains blocked.

**An unfreeze fails**

The requested amount exceeds what is frozen at that address. Open **Holders** and read the address's frozen amount
before you retry. You can only unfreeze up to that figure, never more, even if the total balance is larger.

## Frequently asked questions [#frequently-asked-questions]

### Can I halt transfers for one holder instead of the whole asset?

An emergency halt applies to the whole asset. To restrict one holder, use a partial freeze. If that holder then tries to move more than the freeze left free, the refusal does not mention the freeze. The platform refuses the transfer before signing with an ordinary insufficient-balance error, [DALP-9482](https://docs.settlemint.com/docs/api-reference/errors), and a transfer that reaches the chain reverts with [DALP-1101](https://docs.settlemint.com/docs/api-reference/errors). Both report an available balance that already has the frozen amount subtracted, so it reads lower than the units the holder has. To stop the holder's whole wallet on every asset it holds, [restrict the wallet](https://docs.settlemint.com/docs/console/participants/restrict-a-wallet) instead.

### Can I freeze balances at more than one address in a single request?

Yes. On the "Holders" tab, tick the holders and choose **Freeze** or "Unfreeze". Every selected holder needs a balance that is not frozen for a freeze, or a frozen balance for an unfreeze, and the action needs the custodian role. The "Freeze partial balance" entry in "Actions" targets one address and one amount. The reverse case, one wallet on many tokens, has its own control, [Restrict a wallet](https://docs.settlemint.com/docs/console/participants/restrict-a-wallet).

### Who can unfreeze tokens that another administrator froze?

Any holder of the Custodian role on that asset can unfreeze, including a different account from the one that froze. The role is scoped to the asset, not to the operator who acted first, so a second custodian-role holder can review and reverse a colleague's freeze without needing the first operator's wallet or involvement. Check **Holders** for the current frozen amount before you unfreeze, since another operator may have already changed it.

### Does a partial freeze stop a burn or redemption?

A partial freeze stops a holder's own redemption but not an administrative burn. A redemption the holder submits, including a redemption at maturity, reverts like an ordinary transfer if it needs more than the free balance: the frozen amount stays exactly as it was, and the redemption fails rather than reaching into it. The underlying administrative burn behaves like a forced transfer: short on free balance, it draws down enough of the frozen amount to cover the difference and completes anyway, leaving less frozen than before. The Console's burn form works the same way: it offers the holder's total balance, frozen units included. A full freeze, which lists the address on the **Blocklist** tab, does stop the administrative burn: the chain refuses to burn from a frozen address with [DALP-1076](https://docs.settlemint.com/docs/api-reference/errors). To take the units, a custodian forced-transfers them out of the frozen address first, or lifts the freeze.


# Set price

Source: https://docs.settlemint.com/docs/console/asset-management/manage/token-pricing
Set a token's price on its own price feed, read it in another currency, and see when the platform refuses a stale price.

Set a token's price by hand from its **Actions** menu. The price is held in the token's own price feed, an on-chain record of the latest price and the time it was observed. Valuations, portfolio totals, value history, the token price read of the Platform API and value-based compliance rules read that feed, with two exceptions [How the platform reads the price](#how-the-platform-reads-the-price) describes: holdings value a bond from its face value and its denomination asset's price, and the on-chain price resolver can fall back to a base price claim. The platform reads the price in the currency a caller asks for, converts it through exchange-rate feeds, and refuses a price older than its feed's staleness window.

Four sources write to a token's price feed:

- A holder of the token's "Permission manager" role sets the price by hand, as this page describes.
- [Issue asset](https://docs.settlemint.com/docs/console/asset-management/issue-new-asset) seeds it when a token is created with a declared price.
- A holder of the "Feeds manager" role publishes a value from the feed's row on Data feeds.
- A price source publishes a provider's price after the platform checks it, as described in [Price sources](https://docs.settlemint.com/docs/console/organisation-settings/price-sources).

Feed registration and staleness windows are set on [Data feeds](https://docs.settlemint.com/docs/console/organisation-settings/data-feeds), and the currencies a price can convert into are set on [Exchange rates](https://docs.settlemint.com/docs/console/organisation-settings/exchange-rates).

![Edit token price page with Current price above the Price and Currency fields](https://docs.settlemint.com/docs/screenshots/console-token-set-price-sheet.light.en.webp)

[Screenshot] The "Edit token price" page with "Current price" above the "Price" and "Currency" fields.

On a token that already has a price, the page is titled "Edit token price" and shows "Current price" at the top, then the "Price" field, the "Currency" field and a **Review** button. On a token without a price, the page is titled "Set token price" and has no "Current price".

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

- You need the Permission manager role on the token. The **Actions** menu shows only to a user who holds a role on the token. Its price item is absent when none of your wallets holds Permission manager, and greyed out with the wallet's address when another of your wallets holds it.
- You need your PIN or other wallet verification to confirm the write.
- Your account needs an on-chain identity on the active network.
- The organisation needs an operations signer bound, with a claim key on the organisation's identity, the key that lets the signer sign for that identity. Without one, the platform refuses the price.
- The system needs its price feed factory installed.

## Steps [#steps]

### Open the token's price form [#open-the-tokens-price-form]

Open "All assets" under "Assets", select the token, then select **Actions** in the token header.

Select "Set price" for a token with no price yet, or "Edit price" for a token that has one. The page is titled "Set token price" or "Edit token price", and it opens under the asset with a breadcrumb back to it. When the token already has a price, the page shows it as "Current price" at the top.

### Enter the price and the currency [#enter-the-price-and-the-currency]

Enter the price per token in **Price** as a positive decimal number, for example `100.50`. Zero, a blank and a negative number are refused with "Enter a price greater than zero, such as 100.50." Use no more decimal places than the token's price feed stores: 8 for a feed the platform created, or the decimals a feeds manager chose for a feed registered on Data feeds. A longer price is refused beside the field, for example "Enter a price with at most 8 decimal places. The data feed stores no more.", and "Review" stays closed until you shorten it. The platform does not round the price you enter.

Choose the currency in **Currency**. The form offers 12 currencies, USD, EUR, GBP, JPY, CHF, CAD, AUD, AED, SGD, SAR, MYR and ZAR. The form preselects the token's current currency, or USD for a token with no price.

Note (The currency of an existing price cannot change): On a token that already has a price, keep the preselected currency. The feed keeps the currency it was created with. If you choose another currency, the review step shows it, but the platform writes your number in the feed's currency. 100 entered as EUR on a USD feed becomes 100 USD. Convert the price into the feed's currency first, using the rate on [Exchange rates](https://docs.settlemint.com/docs/console/organisation-settings/exchange-rates). To change the currency, a feeds manager replaces the feed from its row on Data feeds.

### Review and confirm [#review-and-confirm]

Select **Review**. The review step shows "Token" with its name and symbol, "Current price" when the token has one, and "New price".

Select **Confirm price** and complete wallet verification.

The platform queues the price as a transaction, and the Console shows **Setting price…** while that transaction is queued or running. It shows "Token price updated successfully" only after the transaction completes on chain. If the transaction fails, the Console shows an error instead and no success message. If it has not settled when the Console stops watching, the Console shows "Still processing. Track progress in Actions." and the price may not be set yet. Valuations read the new price after the indexer records it, so check it against the [You should see](#you-should-see) list before you rely on it.

Note (No second approval gates a price set by hand): One person enters and confirms the price. Read the review step before you confirm. A price that comes from a price source can wait for a second person, as described in [Price sources](https://docs.settlemint.com/docs/console/organisation-settings/price-sources).

## How a token's price is declared [#how-a-tokens-price-is-declared]

The first price set for a token creates its price feed in the same request. The platform creates an issuer-signed feed, one that accepts a price only when a claim key of an identity that the trusted issuers registry trusts for the token's price topic signed it. The feed has 8 decimal places and the description `SYMBOL / CURRENCY`, for example `NWC / USD`. The part after the slash is the feed's currency. Every later price goes to that feed, and the feed keeps the currency it was created with.

The organisation's operations signer, the custody account the platform uses to sign on the organisation's behalf, signs every declared price under the organisation's on-chain identity. The platform checks that the person who sets the price holds the "Permission manager" role on the token, and asks for wallet verification. The feed itself checks only the signature, so a holder of a claim key on a trusted identity can publish to it without going through the platform.

Setting a price is a transaction that the platform queues. Valuations read the new price once the indexer, the platform service that records on-chain events, has recorded the feed update. Each set-price request is recorded on the organisation's [Audit trail](https://docs.settlemint.com/docs/console/reporting/audit-trail) with the price and currency before the change and the price and currency requested.

A token created with a declared price gets its feed and first price at creation. For a precious-metal token the declared price is the weight per token times the spot price per unit. A token whose asset-type template requires the maturity redemption feature gets no price feed at creation. The template decides: a create request that sends maturity redemption settings for a template without the feature still gets its declared price published. If the organisation has no operations signer bound when the token is created, the token is created without a price.

## How the platform reads the price [#how-the-platform-reads-the-price]

### In the currency you ask for [#in-the-currency-you-ask-for]

The token price read answers in the currency you name, or in USD when you name none. In the feed's own currency it returns the price and the time of the observation. In another currency it converts the price through the organisation's exchange-rate feeds, using only rates that are inside their own staleness windows and at most three conversions. The answer lists each conversion: the currency pair, the rate, the exchange-rate feed's address, the rate's update time, and whether the rate was inverted.

When no path of fresh rates reaches the currency you asked for, the read returns the price in the feed's currency with `convertible` set to `false`, the reason `no_fx_path`, and `availableCurrencies`, the currencies the price can reach. Prices are exact decimals with 18 decimal places, and each conversion rounds down at the last place.

The read uses only the token's own price feed. It does not fall back to a last known price, to a value derived for a bond from its denomination asset, or to a base price stored as a claim on the token's on-chain identity.

### A stale price is refused [#a-stale-price-is-refused]

A price is stale when its observation is older than the feed's staleness window. The window that applies is the feed's own window, or the global default when the feed has none. Both are set on [Data feeds](https://docs.settlemint.com/docs/console/organisation-settings/data-feeds). A window can also be set to never expire.

The token price read refuses a stale price with [DALP-0343](https://docs.settlemint.com/docs/api-reference/errors), HTTP 503, and `data.reason` set to `stale-feed`. The same code answers every case where the token has no usable price, and `data.reason` names which one:

| `data.reason` | What the platform found | What to do |
| --- | --- | --- |
| `no-feed` | No price feed is registered for the token. | Set a price, or map the token in a price source. |
| `feed-not-indexed` | The feed is registered but the indexer has not recorded it. | Read again after the indexer catches up. |
| `registration-date-missing` | The indexed feed has no registration date. | Read again after the indexer catches up. |
| `inactive-feed` | The feed is not active. | Check the feed on Data feeds. |
| `unsupported-quote` | The feed's description does not name a fiat currency. | Replace the feed with one described as `SYMBOL / CURRENCY`. |
| `unanswered-feed` | The feed has never published a value. | Set a price. |
| `stale-feed` | The latest observation is older than the feed's staleness window. | Publish a fresh price. |

On chain, the price resolver applies the same windows and reverts with [DALP-1111](https://docs.settlemint.com/docs/api-reference/errors), "Stale feed". The error names the token, the price topic, the observation's update time and the window it was measured against. A value-based compliance rule that reads a stale feed price refuses the action. On a token with a capital-raise limit, a mint is refused with a compliance failure whose reason is a stale price, until a fresh price is published. These checks do not use the last known feed price.

The on-chain resolver has one path the API read does not. When a token has no price feed, the resolver can fall back to a base price stored as a claim on the token's on-chain identity. It accepts only a claim from an issuer that the trusted issuers registry trusts for the base price topic. A new resolver starts with this fallback on, and a feeds manager can turn it off. A claim carries no time, so no staleness window applies to it.

### Valuations and history [#valuations-and-history]

The indexer records every change to a token's indexed price, with the price in its own currency and in the organisation's base currency. A change to a relevant exchange rate adds a new base-currency value. The price in effect at a moment is the last one recorded at or before that moment. Portfolio values and profit and loss at a past date, and the 24-hour price change of a holding, use this history.

Holdings value a bond, or a token with the maturity redemption feature, from its face value times the indexed price of the asset it redeems into. That derived value needs no price feed on the bond and follows its denomination asset's price and the relevant exchange rates. When you attach the maturity redemption feature to a token that already has its own price feed, the platform removes that feed after queueing the attach, so a feed that no longer prices the token does not stay active. If the removal fails, the attach still goes ahead and the platform logs a warning. The token price read still needs the bond's own price feed.

An external token that no DALP system issued records no price history, because each system that registers it prices it separately.

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

- On the token's "Placement" tab, the **Price** card in the "Price feeds" section shows the new price.
- **Status** reads "Fresh", "Stale" or "Not judged yet" against the feed's staleness window on chain time.
- **Price from** reads "Maintained by hand".
- **Observed** and "Published" show the observation time and the publication time.
- **Signed by** names the operations signer.
- **Usable until** shows when the price goes stale. A feed whose window never expires reads "Not limited" there.
- The "Price" column of the **All assets** table shows the same price and currency.
- **Price history** opens the feed's page on Data feeds.

## Troubleshooting [#troubleshooting]

**Set price cannot be selected in Actions**

A greyed-out item means the role sits on another of your wallets, which the menu names: switch to that wallet. When
the item is missing, none of your wallets holds **Permission manager**. Ask a holder of that role to grant it, or to
set the price.

**The price is refused after wallet verification**

[DALP-12353](https://docs.settlemint.com/docs/api-reference/errors) means the wallet that signed does not hold the token's administrator role,
shown in the Console as **Permission manager**. [DALP-0345](https://docs.settlemint.com/docs/api-reference/errors) means your account has no
on-chain identity on the active network, or the organisation has no eligible operations signer for price declarations.
[DALP-0346](https://docs.settlemint.com/docs/api-reference/errors) means the system has no price feed factory installed. Ask an administrator to
install the price feed system. A retry alone clears none of these.

**The price is refused for having too many decimal places**

The token's price feed stores a fixed number of decimal places, 8 for a feed the platform created. The Console refuses
a longer price beside the field, and the Platform API answers [DALP-12245](https://docs.settlemint.com/docs/api-reference/errors), HTTP 400.
Shorten the price to the feed's decimal places and submit it again. Nothing was queued, so there is no failed
transaction to clear.

**A token shows no price**

The **Price** card says "This token has no price feed." when no price has ever been set or mapped. Set a price, or map
the token's ISIN in a price source.

**A price read or a mint fails because the price is stale**

The latest observation is older than the feed's staleness window. Publish a fresh price, by hand or from the price
source. Change the window on Data feeds only when the asset's pricing rules accept older prices.

**The read answers in the feed's currency instead of the one I asked for**

No chain of up to three fresh exchange rates links the two currencies. Check `availableCurrencies` in the answer for
the currencies the price can reach, and check on Exchange rates that the currency you need is tracked and its rate is
current.

**The token is priced in the wrong currency**

The feed keeps the currency it was created with, so a new price with another currency does not change it. A feeds
manager can replace the token's price feed with one described in the right currency, from the feed's row on Data
feeds. Everything that read the price before the replacement read it in the old currency.

## API routes [#api-routes]

The [Platform API](https://docs.settlemint.com/docs/api-reference/v2) offers three routes for a token's price:

- `POST /api/v2/tokens/{assetId}/price` sets the price, with `price` as a decimal string, `currencyCode` and `walletVerification`. The platform answers 202 with the queued transaction by default. Send `Prefer: wait=<seconds>` to wait for settlement. An empty transaction hash means the feed already held that price. A retry with the same idempotency key does not create a second feed or publish twice. A price with more decimal places than the token's price feed stores is refused with [DALP-12245](https://docs.settlemint.com/docs/api-reference/errors), HTTP 400, before anything is queued. The platform judges it against the decimals of the feed already registered for the token, or the 8 decimal places of the feed a first price creates, and never rounds it.
- `GET /api/v2/tokens/{assetId}/price?currency=EUR` reads the price in the named currency, with each conversion step.
- `GET /api/v2/tokens/{assetId}/price-history?preset=trailing1Month` reads the price over a window. `preset` is one of `allTime`, `ytd`, `trailing12Months`, `trailing6Months`, `trailing3Months`, `trailing1Month`, `trailing7Days` and `trailing24Hours`. Each point carries the price in the base currency in force at that time, and `null` where the price was cleared. The series is empty when the token had no price in the window, and the time before its first price is left out rather than reported as zero. The route answers token not found for a token issued to another organisation, as the token read does.

### Set a price [#set-a-price]

The request body carries the price, the currency and the wallet verification. The PIN in this example is illustrative:

```json
{
  "price": "100.50",
  "currencyCode": "EUR",
  "walletVerification": { "verificationType": "PINCODE", "secretVerificationCode": "482913" }
}
```

Without a `Prefer` header the platform answers 202 with a handle. Poll `statusUrl`, also sent as `Location`, and do not resend the request:

```json
{
  "transactionId": "0198f1a2-3c4d-7e8f-9a0b-1c2d3e4f5a6b",
  "status": "QUEUED",
  "statusUrl": "/api/v2/transaction-requests/0198f1a2-3c4d-7e8f-9a0b-1c2d3e4f5a6b"
}
```

With `Prefer: wait=30`, a write that settles in time answers 200 with the feed, the transaction hash, the price and the currency:

```json
{
  "data": {
    "feedAddress": "0x9fE46736679d2D9a65F0992F2272dE9f3c7fa6e0",
    "txHash": "0x2a8f0d4c1b6e39a7c05d8f21b4e7a63c9d0f5b18e24a7c36d91b0f8e5a3c7d24",
    "price": "100.50",
    "currencyCode": "EUR"
  },
  "meta": {
    "txHashes": ["0x2a8f0d4c1b6e39a7c05d8f21b4e7a63c9d0f5b18e24a7c36d91b0f8e5a3c7d24"]
  },
  "links": { "self": "/api/v2/tokens/0x71C7656EC7ab88b098defB751B7401B5f6d8976F/price" }
}
```

### Read a converted price [#read-a-converted-price]

`price` is a whole number scaled by `decimals`. In this answer to `GET …/price?currency=USD`, the feed holds 100 AED, the AED to USD rate is 0.2723, and `27230000000000000000` with 18 decimals is 27.23 USD:

```json
{
  "data": {
    "tokenAddress": "0x71C7656EC7ab88b098defB751B7401B5f6d8976F",
    "price": "27230000000000000000",
    "currency": "USD",
    "decimals": 18,
    "source": "feed",
    "sourceCurrency": "AED",
    "convertible": true,
    "updatedAt": "2026-08-14T09:30:00.000Z",
    "conversionPath": [
      {
        "from": "AED",
        "to": "USD",
        "rate": "272300000000000000",
        "feedAddress": "0x9fE46736679d2D9a65F0992F2272dE9f3c7fa6e0",
        "updatedAt": "2026-08-14T09:30:00.000Z",
        "inverse": false
      }
    ]
  },
  "links": { "self": "/api/v2/tokens/0x71C7656EC7ab88b098defB751B7401B5f6d8976F/price" }
}
```

When no chain of fresh rates reaches the currency, the answer keeps the feed's currency and lists the currencies it can reach. This answer to `GET …/price?currency=JPY` is illustrative:

```json
{
  "data": {
    "tokenAddress": "0x71C7656EC7ab88b098defB751B7401B5f6d8976F",
    "price": "100000000000000000000",
    "currency": "AED",
    "decimals": 18,
    "source": "feed",
    "sourceCurrency": "AED",
    "convertible": false,
    "targetCurrency": "JPY",
    "reason": "no_fx_path",
    "message": "No conversion path from AED to JPY exists in the configured price feeds directory.",
    "availableCurrencies": ["EUR", "USD"],
    "updatedAt": "2026-08-14T09:30:00.000Z",
    "conversionPath": []
  },
  "links": { "self": "/api/v2/tokens/0x71C7656EC7ab88b098defB751B7401B5f6d8976F/price?currency=JPY" }
}
```


# Transfers

Source: https://docs.settlemint.com/docs/console/asset-management/manage/transfers
Move tokens, force a transfer as custodian, manage transfer pre-approvals, check a transfer before it is signed, and recover lost or stray tokens.

**Transfer tokens** moves the available holdings of the participant you are working as, from that participant's executor wallet, to an eligible recipient. The same "Actions" menu holds these other controls:

- **Forced transfer** moves tokens out of a holder's address without that holder's consent.
- **Approve transfer** and "Revoke transfer approval" pre-authorise a transfer that a compliance rule would otherwise block, or cancel that authorisation.
- Two recovery controls move units that their owner cannot move.

The **Transfer pre-check** tab tests a transfer without submitting it.

[Emergency halt and freeze](https://docs.settlemint.com/docs/console/asset-management/manage/pause-freeze) hold tokens in place. Forced transfer moves them, and the Console states that it cannot be undone, as it does for the two recovery controls. Halting the asset does not stop it: the token lets a custodian's forced transfer through while it is halted, and the Console keeps **Forced transfer** available to a Custodian during a halt. A partial freeze does not stop a forced transfer either. One that needs more than an address's free balance unfreezes exactly enough to cover the shortfall first, then moves the tokens.

![Transfer tokens page with a recipient, an amount of 10, the transferable balance and the total](https://docs.settlemint.com/docs/screenshots/console-transfer-form.light.en.webp)

[Screenshot] The "Details" step of "Transfer tokens", with one recipient and an amount of 10.

The step shows "Recipient" with the chosen account, then "Amount" with the transferable balance and "Max" under it, then "Add recipient", then the "Total" against the transferable balance. **Review** moves to the next step.

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

- The requirement differs for each control. Ordinary transfer needs no role. **Transfer tokens** is left out of the menu only when the participant you are working as has no executor wallet. The asset must also be live, and the executor wallet needs an available balance, or the item stays in the menu but cannot be selected. Transfer-path compliance then applies on the chain: the token checks every configured rule, including a transfer-approval module if the asset carries one, before balances change. A recipient on the system compliance bypass list skips the rules that judge the recipient, such as country lists, investor count and transfer approval.
- Forced transfer needs the Custodian role and the asset's custodian capability, the same capability freeze and unfreeze need. On an asset with the custodian capability, "Forced transfer" appears to anyone who holds a role on the asset, and only a wallet that holds the Custodian role can select it. When the role sits on another of your wallets, the item cannot be selected and shows "The role for this action sits on wallet" and the wallet address, followed by "Switch to that wallet to use it." On the chain only the Custodian role gates a forced transfer. In the Platform API, a forced transfer, "Recover lost wallet" and "Recover stray ERC-20" wait for a second person only while the "Administration" row under "Approvals" on [General](https://docs.settlemint.com/docs/console/organisation-settings/general#approvals) protects the **Forced transfers** group.
- Approving or revoking a transfer pre-approval needs the asset to carry a [transfer-approval compliance module](https://docs.settlemint.com/docs/concepts/compliance-and-identity/compliance-modules#transfer-approval) and your account's identity to be one of its configured approval authorities. Without both, neither control appears in the menu at all. The module blocks an ordinary transfer between two identities until a configured approval authority pre-approves it, for whatever amount and expiry the module allows. Two exemptions skip that check. Any one approval authority can exempt a recipient wallet, meant for a fee collector, and every later transfer to that wallet then needs no approval. A transfer to an address on the system compliance bypass list, [which DALP manages](https://docs.settlemint.com/docs/concepts/compliance-and-identity/compliance-policy#who-manages-the-compliance-bypass-list-and-how-does-an-address-end-up-on-it), needs none either. Approving and revoking act on the compliance module and leave the token untouched, so both controls stay available while the asset is halted.

## Steps [#steps]

### Open the transfer control [#open-the-transfer-control]

Open "All assets", select the asset, and open **Actions**. Each action opens on its own page under the asset, with a breadcrumb back to the asset, and "Cancel" returns you to where you came from. Choose one of these:

- **Transfer tokens** moves the active participant's holdings.
- **Forced transfer** moves a holder's tokens without their consent.
- **Approve transfer** and "Revoke transfer approval" manage a compliance pre-approval instead of moving anything.

![The Actions menu of an equity, listing Forced transfer and Transfer tokens among its controls](https://docs.settlemint.com/docs/screenshots/console-manage-asset-menu.light.en.webp)

[Screenshot] On this equity, "Actions" lists "Forced transfer" and "Transfer tokens" among the asset's other controls.

"Transfer tokens" is unavailable here, because the signed-in wallet holds none of the token. "Approve transfer" and "Revoke transfer approval" appear only on an asset whose compliance requires transfer approval, and only to its configured approval authority.

### Enter the recipient, amount or approval values [#enter-the-recipient-amount-or-approval-values]

For "Transfer tokens", choose or enter the address under "Recipient" and the number of tokens under **Amount**. The line under the amount shows how much is transferable, and "Max" fills in all of it. Under that, a line shows its fiat equivalent at the token's price, for example "≈ $2,000.00". When the token has no price, the line says that no price is set for the token, so there is no fiat equivalent.

**Add recipient** adds another recipient row, and the total under the rows sums them. Select "Review" and check the recipients and amounts before confirming. The recipient field refuses the zero address and the asset's own contract address, and warns when the recipient is the wallet the tokens come from: an address that can only lose the tokens never reaches the summary.

The review step also runs the **Pre-trade compliance check** for each recipient with an amount. When every recipient clears, one panel reads "Transfer will clear". Otherwise a panel shows for each recipient that would not clear, labelled with its address when there are several. It reads "Transfer will revert" in red, or "Waiting for approval" in amber when the only thing holding the transfer is the transfer-approval rule: the transfer is valid and waits for an approval authority. A wallet with the System manager, Identity manager, Verification issuer or Compliance manager role on the organisation's system, or the Custodian role on the asset, sees each blocker the check can establish under "Resolvable by you", "Requires operator action", "Held for approval" or "Cannot be resolved". "Resolvable by you" lists only what the wallet you act as can fix itself: a blocker on the other side of the transfer reads "Resolvable by the sender" or "Resolvable by the recipient", and carries no button to issue a claim for it. Other wallets see a frozen address, a short balance or a halted asset by name, and anything else as one "Cannot be resolved" entry.

"Confirm transfer" stays disabled while the check runs and when any recipient would revert. A transfer that is only "Waiting for approval" can still be confirmed. Beside the button the review names the failed checks, for example "The pre-trade compliance check says this transfer will fail. Failed checks: Block addresses. Change the recipient or the amount." When the check cannot run, the review says "Compliance could not be verified right now. The transfer will still be checked on-chain.", and you can still confirm, because the chain refuses an ordinary transfer that breaks a rule.

For "Forced transfer", enter the address to seize from, the recipient address, and the amount. A **Pre-check** panel checks the three inputs as you type:

- **Sender balance** reads "Holds only" with the balance when the sender holds less than the amount. When the sender's balance drops while the form is open, the platform refuses the amount above the buttons, and the panel reads the sender's balance again, so this line and the amount's available figure show the balance the platform checked.
- **Recipient** reads "Passes the identity checks" or "Fails the identity checks". For a recipient address frozen on the token as a whole, it reads "The address is blocked. Unblock it first." and the forced transfer cannot be submitted on any asset. The DALP 3.2 token contract refuses it too. A token on an older implementation does not check it, so a forced transfer sent straight to such a contract can still deliver units into a frozen address. The Console requires the recipient to be registered and verified for the token, and the chain applies the same identity check to a forced transfer.
- **Compliance rules** names the rules that would block a normal transfer and says "The forced transfer overrides this."

When the address to seize from is a DALP escrow, the platform refuses the transfer above the buttons and names the escrow, because a token forced transfer would leave the escrow's balances and locks wrong. Move an escrow's units from [Escrows](https://docs.settlemint.com/docs/console/asset-lifecycle/escrows) instead.

A failing recipient, an amount greater than the sender's balance, or the same address on both sides keeps "Continue" from going ahead. The confirmation screen is styled as a warning and names the same three fields. Read it before you continue. The button that submits it reads **Transfer tokens**, the name of the ordinary transfer's menu item, so check the review screen's heading and warning styling before you select it.

For **Approve transfer** or "Revoke transfer approval", enter the sender wallet, the recipient wallet, and the exact token amount. Revoking needs the same three values as the approval you are cancelling. The module keys each approval on that identity pair and, in one of its configured modes, the exact amount, so entering the wrong amount for the right pair matches nothing and fails. It never touches the nearest approval.

### Confirm with wallet verification [#confirm-with-wallet-verification]

Confirm with wallet verification, the same as any other Console admin change.

An ordinary transfer that fails a check reverts. Nothing moves and nothing needs undoing. Forced transfer is different. Its confirmation screen states plainly, "This will forcibly transfer tokens from the source address to the recipient", then adds, "This action bypasses standard transfer restrictions and cannot be undone". The bypass is real. A forced transfer skips the compliance rules, the sender's address freeze, the halt and the units another feature holds for a pending move, so it moves tokens even from a sender the token would refuse. The chain still checks the recipient's identity and refuses a recipient whose address is frozen on the token. A token feature that refuses forced moves, such as Booked movements, still refuses it.

No Console control reverses a confirmed forced transfer. A new transfer or forced transfer back restores the position, and it needs its own authorisation.

Approving a transfer creates a record the compliance module honours later. Its confirmation note states, "This will approve the transfer of the specified amount from the sender to the recipient. The approval can be revoked before the transfer is executed". Revoking is final for that specific approval: its own confirmation note states, "This will permanently revoke the transfer approval. The transfer will no longer be allowed to proceed unless re-approved". Nothing has moved when you revoke, so a fresh approval can follow if the transfer is still wanted.

[Figure] Two paths move tokens. Only one answers to every guard the token defines. Ordinary transfer requires an executor wallet, a live token, and a pass through transfer-path compliance, which includes any transfer-approval pre-approval the asset requires. Forced transfer requires only the Custodian role. At the contract level it skips transfer-path compliance and the sender's address freeze. The token and the Console both let it run while the asset is halted. Forced transfer can even draw down frozen tokens by unfreezing what it needs first. Both paths still require the recipient to pass the token's identity check, and both refuse a recipient whose address is frozen. Ordinary transfer's outcome is a normal balance movement. Forced transfer's outcome cannot be undone, and the Console states this directly before you confirm it. Labels: Token movement requested; Ordinary transfer; Executor wallet; Token operations active; Transfer-path compliance; Includes any transfer-approval; pre-approval the asset requires.; Forced transfer; Custodian role only; Skips transfer-path compliance; and the sender's freeze.; It still runs; while the asset is halted.; Can draw from frozen tokens; by unfreezing what it needs.; Recipient must still be verified; Tokens move; Tokens move; cannot be undone.

Forced transfer skips transfer-path compliance, the sender's freeze and a halt, but the recipient's identity check and freeze still apply.

## Check a transfer before anyone signs [#check-a-transfer-before-anyone-signs]

Open the asset and select its **Transfer pre-check** tab. It answers why a transfer would not go through, without submitting anything, and shows to a Custodian on the asset and to a wallet with the System manager, Identity manager, Verification issuer or Compliance manager role on the organisation's system.

Enter the "Sender", the "Recipient" and the "Amount", then select **Run check**.

The check reads the chain the way the transfer would: the token's compliance rules, the recipient's identity, a halt, a freeze on either address and the sender's free balance. The answer reads **Transfer will clear**, "Transfer will revert", or "Waiting for approval" when the transfer-approval rule is the only thing holding it. A transfer that would revert lists the blockers the check can establish under who can resolve them: "Resolvable by you", "Resolvable by the sender", "Resolvable by the recipient", "Requires operator action" or "Cannot be resolved". When the recipient's identity is refused, the list stops at the identity blockers. Under the reason, an identity blocker names the rule that refused it: "Refused by the token identity registry rule", "Refused by the token identity verification module rule" or "Refused by the global identity verification control". A country, identity or address list bound system-wide refuses a wallet the same way as one bound to the token, and its blocker names the list's type with no source line. A transfer that waits for approval lists the approval authorities under "Needs approval from", with an "Approve transfer" button. A short balance also marks the "Amount" field with "Not enough transferable units". When the check cannot run, the tab says "The compliance check could not be completed. Please try again." The blocker detail follows the roles of the wallet that signs your actions, which is the wallet of the participant you are working as. A pass describes the chain at the moment of the check, so a verification revoked before the transfer still makes it revert. [Transfer-path compliance](https://docs.settlemint.com/docs/concepts/compliance-and-identity/transfer-path-compliance) explains where the rules run.

An operator blocker carries a button that opens the control that resolves it:

- **Take action** on a frozen address opens that address on the asset's "Blocklist" tab. On an address or identity block list rule it opens the "Compliance" tab. On an unregistered identity it opens the participant who owns the wallet, where you register the identity, or the users list when no single user owns the wallet.
- **Approve transfer** opens the "Approve transfer" page.
- A paused asset has no button: resume it with **Resume token operations** in "Actions".

## Recover tokens [#recover-tokens]

Two recovery controls in **Actions** move units that their owner cannot move.

**Recover lost wallet** moves the whole balance of a lost wallet to its replacement. Like a forced transfer, it runs while the asset is halted and skips the compliance rules. It needs no role on the asset: the replacement wallet is the one that signs, and it recovers its own lost wallet. The custodian's override is the Platform API's "Force token recovery" operation, which needs the Custodian role. An Identity manager first marks the wallet as lost and pairs its replacement through identity recovery. Until then, the page shows "Identity recovery must be ready" and does not let you continue. It accepts only the replacement wallet the Identity manager paired, and the chain refuses any other. The page shows what the lost wallet holds and refuses the asset's own address, the same address on both sides, and a wallet that holds none of the asset. A frozen part stays frozen on the replacement wallet, and a wallet-level freeze carries over. Confirm the acknowledgement, then "Recover tokens". The move cannot be undone.

**Recover stray ERC-20** sends another ERC-20 token that was sent to this asset's contract by mistake to a recipient you choose. It needs the Emergency role. Enter the "ERC-20 contract", the "Recipient" and the "Amount". The page reads the contract first and refuses each of these:

- The asset's own address. The message points to **Forced transfer** for units of the asset itself.
- An address that does not answer as an ERC-20 token, with "This address is not an ERC-20 token."
- An amount with more decimals than the token has, or more than the asset's contract holds when that balance is indexed.

When the contract cannot be read, the page says "The contract could not be read. Check the address and try again." The Platform API checks before it submits that the address is an ERC-20 token, and refuses one that is not. When it cannot reach the network to check, it answers with a retry delay. Confirm the acknowledgement of the token, recipient and amount, then **Recover tokens**.

## Where a transfer shows [#where-a-transfer-shows]

After "Transfer tokens" or "Forced transfer", open **Holders** and compare the sender and recipient balances with the amount you moved.

Then open **Activity** and match the entry to the transaction hash. Every forced transfer lands as its own entry there too, labelled from the event name, alongside ordinary transfers, emergency halts, and freezes.

After "Approve transfer" or "Revoke transfer approval", open the asset's "Features" tab, find the "Transfer approvals" tile, and choose **View transfer approvals**. The tile counts pending and total approvals. The page it opens lists them in these columns:

- **From** and "To": the sender and recipient, each shown by name when the Console knows one, such as a contact, and as a shortened address otherwise.
- **Amount**: the approved amount.
- **Status**: "Pending", "Consumed" or "Revoked". A newly created approval shows "Pending". A confirmed revocation appears as "Revoked" after indexing.
- **Expires**: starts hidden. Turn it on from the table's column settings or read the expiry in the row details.

A pending row also carries its own inline **Revoke** control, a second way to revoke.

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

- After "Transfer tokens" or "Forced transfer", **Holders** shows the sender and recipient balances changed by the amount you moved.
- **Activity** holds an entry that matches the transaction hash.
- After "Recover lost wallet", **Holders** shows no balance for the lost wallet and the moved balance on its replacement.
- After "Approve transfer" or "Revoke transfer approval", the "Transfer approvals" tile counts the pending and total approvals, and the approval's row shows "Pending" or, after a confirmed revocation and indexing, "Revoked".

## Troubleshooting [#troubleshooting]

**Transfer tokens is missing**

Signal: **Transfer tokens** does not appear in "Actions" at all. Cause: no executor wallet is available for the
participant you are working as. Fix: select or create an executor wallet for that participant.

**Transfer tokens cannot be selected**

Signal: **Transfer tokens** is visible but greyed out. Cause: either the asset is halted, or the executor wallet holds
no available balance in this token. The menu's own message names which one applies. Fix: resume token operations only
when the approved intervention permits transfers to resume. If balance is the issue, confirm the selected participant
and executor before moving funds.

**Forced transfer is missing or cannot be selected**

Signal: **Forced transfer** is absent from the menu, or present but greyed out. Cause: the item is absent when the
asset does not carry the custodian capability, or when none of your wallets holds any role on this asset. It is greyed
out when your wallets hold another role but not Custodian, or when the Custodian role sits on another of your wallets,
and in that case the menu names that wallet. A halt does not grey it out. Fix: confirm the asset's configured
capabilities, switch to the wallet the menu names, or ask an administrator for the Custodian role on this asset.

**A forced transfer is rejected before confirmation**

Signal: forced transfer fails before you reach the confirmation screen, naming the recipient. Cause: the same
recipient-eligibility check as an ordinary transfer applies here. A manually entered address that is not registered or
not eligible for this token is caught before submission. Fix: confirm the recipient's identity registration and
eligibility for this token the same way you would for an ordinary transfer. Forced transfer waives the sender's
checks, never the recipient's.

**Approve transfer or Revoke transfer approval do not appear**

Signal: neither control shows in **Actions**, even though the asset moves tokens under compliance rules. Cause: both
need the asset to carry a transfer-approval compliance module, which most assets do not, and your account's identity
to be one of that module's configured approval authorities specifically. Lacking either keeps both controls out of the
menu entirely, with no disabled state to explain why. Fix: confirm the asset's compliance module configuration, then
confirm your identity is listed as an approval authority on that specific module. Authority is granted per module.

**A pre-approved transfer still reverts**

Signal: a transfer between two identities fails compliance even though someone approved it earlier. Cause: three
separate things end an approval early. An approval can expire, since every module configuration sets an expiry capped
at 365 days. An approval can already be consumed, since some of the module's modes release a single transfer and mark
the approval used. Or the identity that granted it can have since been removed from the authority list, which
invalidates the approval even though it was valid when created. Fix: open the asset's **Transfer approvals** page from
its tile on "Features" and check the row's status and expiry before assuming the transfer itself is wrong. A pending
status does not by itself prove that an approval is usable. Also inspect other compliance checks, which a transfer
approval does not waive.

**Revoke transfer approval fails**

Signal: revocation fails immediately, before wallet confirmation. Cause: no active, unconsumed approval exists for the
exact sender, recipient, and, depending on the module's configured mode, amount you entered. A mistake in any one of
the three matches nothing. Fix: open the asset's "Transfer approvals" page from its tile on "Features", copy the
sender, recipient, and amount directly from the "Pending" row you intend to cancel, or use that row's own inline
**Revoke** control instead of re-entering the values by hand.

## Frequently asked questions [#frequently-asked-questions]

### Who sees the Transfer approvals tile?

The tile appears on "Features" for an asset with a transfer-approval module, to anyone who can read the asset's compliance configuration and to every configured approval authority. Its page lists every pending, consumed, and revoked approval. Only the inline **Revoke** control on a "Pending" row is gated to a configured approval authority. Any configured authority can revoke a pending approval, including one that another authority granted. A viewer without that standing sees the same rows but has no way to act on them from there.

### Why doesn't a new approval or revocation show up right away?

The table reads from indexed compliance events rather than a live contract call, so a submitted approval or revocation needs a moment to reach the indexer before its row appears or its status changes. A successful wallet confirmation means the change is on its way, not that it has landed on the table yet. Refresh the **Transfer approvals** page after a short wait before assuming something went wrong.

### Does an expired approval show a different status than a pending one?

No. Status changes only on an on-chain event: creation sets it to "Pending", consumption sets it to "Consumed", and revocation sets it to "Revoked". Passing the expiry date fires no event, so an approval nobody used or revoked keeps showing "Pending" indefinitely. Compare the row's **Expires** column yourself instead of trusting the status badge to reflect expiry.

### Does a forced transfer charge the same fee as an ordinary transfer?

No. A transaction fee feature configured on the asset exempts every forced transfer and recovery from the fee split, so the move delivers the exact amount you enter with nothing withheld. The recipient of a forced transfer gets the full amount. The configured fee still applies to an ordinary transfer through **Transfer tokens**. If the confirmation screen previews a fee on a forced transfer, the transfer still delivers the full amount.

### Where do I configure who can act as an approval authority?

Not here. **Actions** only uses a transfer-approval module that already exists. Naming its approval authorities, and setting the expiry window and approval mode the module enforces, happens when the asset's compliance modules are configured, covered on [Compliance modules](https://docs.settlemint.com/docs/concepts/compliance-and-identity/compliance-modules#transfer-approval).


# Yield and maturity

Source: https://docs.settlemint.com/docs/console/asset-management/manage/yield-maturity
Set a first yield schedule, claim yield, trigger maturity, redeem at maturity and fund the treasury that pays them.

The yield and maturity pages of an asset operate two features of a composable token: a [fixed treasury yield](https://docs.settlemint.com/docs/concepts/modeling-assets/token-features/income#fixed-treasury-yield) schedule and a [maturity redemption](https://docs.settlemint.com/docs/concepts/modeling-assets/token-features/income#maturity-redemption). On them you fund the treasury that pays both, approve its allowance, claim yield, trigger maturity and redeem a matured position, one operation at a time. [Corporate actions](https://docs.settlemint.com/docs/console/asset-management/manage/corporate-actions) covers scheduled dividend and coupon payments to every holder. Dividend yield and interest yield have their own sections on the Features tab.

A yield schedule pays holders in fixed intervals for as long as it runs. Each period completes, then holders claim what accrued in it. Maturity redemption is a single event that cannot be reversed. Once a bond matures, on its scheduled date or earlier under an emergency trigger, holders redeem for the denomination asset, the single asset a payout-bearing feature pays a holder per unit, subject to their available balance, the token's restrictions, treasury funding and any transaction fee burn rate. A burn fee sends part of the redeemed units to the fee recipient, and the holder is paid only for the units that burn. From maturity on, the token refuses every mint and every ordinary transfer, so only a redemption or a custodian's forced transfer moves the bonds.

![Fixed treasury yield page of a bond, with Claim yield, the Treasury row and the Schedule configuration panel](https://docs.settlemint.com/docs/screenshots/console-manage-yield-maturity.light.en.webp)

[Screenshot] The "Fixed treasury yield" page carries "Claim yield", greyed with its reason.

The "Treasury" row shows the treasury account with "Edit", and the **Schedule configuration** panel shows the start date, end date, yield rate, payment interval and total periods. The dates read to the minute in UTC. When the start and the end fall in the same minute, both show their seconds, so a schedule shorter than a minute never shows the same date twice. The Bond coupon sheet's terms show the start and end dates the same way.

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

- Open the asset's **Features** tab. A yield or maturity section there means the asset carries that feature, from issuance or attached later.
- An account with Governance plus Supply management and Custodian, or Governance plus the admin role, attaches maturity redemption from the "Attach a feature" list on that tab, entering the maturity date, face value, denomination asset and treasury.
- When an asset has no yield feature, its yield page shows "Set yield schedule" to an account that can attach features the same way, which attaches fixed treasury yield and sets its first rate, interval and dates in the same step.
- Setting a treasury, setting a yield schedule for the first time and triggering regular maturity need the Governance role on that asset.
- Triggering early maturity needs the Emergency role.
- Before any payment or redemption operation, compare the section's **Treasury balance** with the amount the top-up dialog states as required: "Required for full payout" for yield, "Required for full redemption" for maturity.

## Who can change what [#who-can-change-what]

Once a feature is configured, no control on these pages changes its rate, interval, dates or maturity date. A Governance holder can still change the treasury address and can exclude any account from yield accrual from the next period on. Governance can also name, once, another feature on the token that may consume or close a holder's accrued yield, such as a conversion. A treasury change waits for a second person only while the "Administration" row under "Approvals" on [General](https://docs.settlemint.com/docs/console/organisation-settings/general#approvals) protects the **Token administration** group.

A control your role does not allow is hidden, except **Edit** on the maturity treasury row, which stays greyed with "Governance manages these settings." A state that rules a control out, such as a halted token or a bond that has already matured, keeps it visible and greyed with the reason beside it.

The Custodian role gates a third operation that is not self-service: after maturity, a Custodian can redeem holders' bonds on their behalf, up to 100 holders per call, without the holder's request. The bonds burn and the payout goes to the holder.

Everything else, funding a treasury, approving its allowance, claiming yield, and redeeming a matured position, needs no admin role at all. Only the treasury's own wallet can approve an allowance for it, and only a holder with a positive available balance can redeem. The redeem sheet, in the Console and in the Investor portal, refuses an amount above that balance with "More than the 1,400.25 HLOG29 available." for a balance of 1,400.25 HLOG29, and does not move on to review until the amount fits. In the Investor portal, the claim yield sheet also asks the platform whether it would accept the claim when it opens. A refusal, for example no completed period with yield left to claim, shows in the sheet with its reason and fix and the claim button stays off, so a holder learns it before the PIN. The check claims nothing and signs nothing, and the platform checks again when the holder signs.

## Treasury health [#treasury-health]

In the maturity section and the "Maturity" panel, a treasury-health indicator gives the same signal at a glance. An approval here is the treasury's allowance for the feature to spend its denomination asset. The indicator shows one of three states:

- **Treasury healthy**, green: the approvals and the balance cover the projected next-period need.
- **Balance low**, yellow: the approvals are in place but the balance falls short.
- **Approval below ceiling**, red: at least one approval is below what it must cover.

The yield section shows a funding status instead: "Funded", "At risk", or "Underfunded", measured against what holders can claim now plus what the next period commits. For a wallet treasury whose approval falls short, it shows "Approval needed" instead.

The treasury allowance, required and available amounts show two decimals, or more when two would read zero. When that rounds the exact amount, the figure reads with ≈. Every shortfall rounds up: the funding gap, the approval gap and the top-up amount never read smaller than the real gap, and one gap reads the same figure wherever it appears.

## Steps [#steps]

### Open the yield or maturity page [#open-the-yield-or-maturity-page]

Open "All assets", select the asset, and find the yield or maturity section on its Features tab. Choose **View yield details** or "View maturity details" to open the feature page.

When the asset has no yield feature yet, the feature page shows that state directly, with a **Set yield schedule** button that attaches the fixed treasury yield feature with its first schedule.

Once a schedule exists, the yield page offers these controls:

- **Claim yield** at the top of the page, greyed with its reason until a claim is waiting for your wallet.
- **Edit** on the treasury row.
- **Top up yield treasury** in the Treasury panel.
- **Approve allowance**, a line that shows when the treasury's approval falls short of what the schedule needs, greyed with the treasury wallet's address for any other wallet.

The "All periods" table lists every period of the schedule. Its **Progress** column shows how much of each period's time has passed: 100% for a completed period, the elapsed share for the active one, and 0% for a scheduled one. How much of a period's yield holders have claimed shows under "Claimed / Total" when you expand its row.

The maturity page offers these controls:

- **Mature bond**, shown only to the Governance role. It stays greyed until the scheduled date arrives and disappears once the bond has matured.
- **Trigger early maturity**, shown only to the Emergency role. It stays greyed once the date has passed, since the contract then accepts only the regular path. It asks you to type the token symbol before it continues.
- **Edit** on the treasury row, which opens "Set maturity treasury".
- **Top up redemption treasury**, "Approve allowance" and "Redeem at maturity".

An account holding both roles sees both maturity controls, and the scheduled date decides which one is greyed with its reason beside it. A **Redemptions** table under the panels lists each holder's redeemed amount, payout and transaction.

### Check the rate, dates and treasury [#check-the-rate-dates-and-treasury]

Check the rate, interval, start and end dates, treasury address, treasury balance, denomination asset, or maturity date shown for the selected feature. Compare them with the approved instruction. The yield rate is the rate paid each payment period, shown with its period, such as 0.03% per day. Unless the interval is a year, the annual yield rate beside it scales that rate to a 365-day year, so 0.03% per day reads as about 10.95% a year. The [fixed treasury yield entry](https://docs.settlemint.com/docs/concepts/modeling-assets/token-features/income#fixed-treasury-yield) shows the arithmetic. A treasury change asks for the new treasury address, a top-up or redemption for an amount, and an allowance change for the new allowance. Top up is not offered to the treasury's own connected wallet, since funding a treasury from itself has no effect. On the yield page the allowance change is enabled only for the wallet the treasury is set to, and every other account sees it greyed with that wallet named. On the maturity control it only appears to that wallet. Before confirmation, each dialog, whether for a claim, a regular maturity, or an early maturity, asks you to review the displayed effect.

![Set yield treasury sheet with the Treasury field on the Details step](https://docs.settlemint.com/docs/screenshots/console-yield-maturity-operation.light.en.webp)

[Screenshot] The "Set yield treasury" sheet asks for the new "Treasury" address on its "Details" step, and its "Review" step shows the effect before confirmation.

### Confirm and wait for the success message [#confirm-and-wait-for-the-success-message]

Submit the transaction and wait for the Console success message before you leave the dialog. If the Console reports a failure, look for the transaction in **Activity** and check the feature's state before retrying, because a failed response does not show whether the chain operation completed.

Maturity cannot be reversed on either path. Early maturity's confirmation screen says so: "Once triggered, the bond will be immediately matured and holders will be able to redeem their tokens. This cannot be undone." Regular maturity shows no such warning.

Before the issuer confirms early maturity, the Console shows the outstanding units, the payout at face value, and the treasury's available redemption cover when that read has completed. If the treasury read is unavailable, the sheet marks that figure unavailable instead of presenting a value it has not read. The maturity panel labels the configured date as the scheduled maturity date and keeps the actual matured-at date separate after either path.

The two paths differ in one precondition. Regular maturity checks that the treasury holds the full redemption amount at that moment, and refuses to proceed if it falls short. Before you enter your PIN, the **Mature bond** sheet shows the required payout, the treasury's available balance and, when the treasury is short, the funding gap, all in the denomination asset. While the treasury is short, or its balance is not indexed yet, the sheet keeps "Confirm" greyed with the reason beside it, so you top up first instead of entering a PIN for a maturity the platform would refuse. If the platform still refuses, because the balance changed after the sheet read it, the sheet names the check that failed. The check reads the balance only, not the allowance, and nothing locks the funds afterwards, so the treasury wallet can move them or lower its allowance once the bond has matured. Early maturity does not check treasury funding, so an operator can open redemption during a wind-down without full funding. With an underfunded treasury, earlier redemptions can use the available funds. A later redemption reverts if the treasury cannot cover its payout. It does not burn the tokens for a partial payment caused by that shortfall. Confirm the treasury is adequately funded before triggering early maturity if you want to avoid that outcome. The contract accepts the call either way.

Claims and redemptions are final. Setting a treasury takes effect immediately. Repeat the same operation, **Set yield treasury** or "Set maturity treasury", with the prior address, under the same Governance role and another wallet confirmation, to put it back. Maturity is the exception: once the bond matures, its treasury address freezes for good, so a change made before maturity is the last one available, though funding that frozen address directly still works. Approving an allowance follows the same rule as any token-spending approval: a new approval for a lower amount, including zero, revokes what came before, at the cost of one more wallet confirmation. Funding a treasury through top up is a plain transfer to that address, and neither feature locks the tokens there afterward. Whoever controls the treasury wallet decides if and how those tokens move again.

A treasury change also takes effect the instant it is mined. A claim or redemption submitted earlier but mined afterward reads whichever treasury is current at that later block, not the one the sender saw when they submitted it. When the newly set treasury has not approved the feature, or does not hold enough of the denomination asset, that pending transaction fails. The failure carries the same insufficient-allowance or insufficient-balance reasons covered under Troubleshooting below. It does not wait or fall back to the previous treasury.

[Figure] Yield repeats every period. Maturity happens once and does not reverse. A yield schedule repeats. Each period completes, the treasury must be funded and have approved the feature to spend from it, and then the holder can claim, with no admin role needed for the claim itself. That cycle runs again every period for the life of the schedule. Maturity does not repeat. On the scheduled date, a Governance holder triggers Mature bond, and the contract checks the treasury is funded at that moment. Before that date, the Emergency role can run Trigger early maturity instead, with no such check. Either path lands on the same matured state, and the contract defines no way back from it. A funded treasury remains what redemption needs. The regular path had it at the moment of maturity, but the treasury can move it afterwards, and a bond that matures early may still need funding before every holder can redeem in full. Redemption itself, unlike maturity, can happen more than once, as different holders, or the same holder in stages, redeem their positions. Labels: Feature already attached; Yield schedule; Period completes; Treasury funded, approved; Claim yield; Repeats every period.; No admin role for the claim.; Maturity; Scheduled date, or emergency; Governance on schedule.; Emergency only before it.; No check; Funding confirmed; Matured; no path back; Treasury funded; Redeem; Repeatable per holder.

Yield repeats every period, while maturity happens once and only then makes redemption possible.

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

- Refresh the same feature page. After first-time yield setup, compare the schedule and rate with the approved instruction.
- After a treasury change, compare the saved address.
- After maturity, confirm the Console reports "Bond '[name] ([symbol])' matured successfully" for the regular path, or "Bond '[name] ([symbol])' early maturity triggered successfully" for the emergency one.
- Open **Activity** from the Console sidebar and confirm the entry matches this asset and operation, with a successful result.
- Each entry decodes the full underlying event.
- A treasury change lists both the old and new address, and a claim lists the exact amount paid alongside the period range it settles.
- A redemption lists the tokens surrendered alongside the amount paid, with no period range, since maturity carries no period concept.
- When the operation creates a payment obligation, confirm the displayed treasury balance covers what the top-up dialog stated as required.
- For a maturity redemption, do not rely on the treasury-health indicator alone to confirm that: it tracks the next period's projected need, not the full redemption amount, so a green reading can still leave a redemption short.

## Troubleshooting [#troubleshooting]

**A control is missing**

Your account has no role for that operation, or the asset lacks the feature entirely. A yield control your role allows
but the feature's state blocks is greyed with its reason, not missing. A maturity operation your account cannot use is
missing from the maturity page, except the treasury "Edit", which stays greyed with "Governance manages these
settings." No section on the Features tab means the feature is not attached. The Governance role can attach maturity
redemption from the "Attach a feature" list on that tab. For yield specifically, an asset without a yield feature
shows a **Set yield schedule** button on the yield page, offered to the Governance role, and that button attaches the
feature.

**Mature bond cannot be selected**

Signal: **Mature bond** is absent or disabled before you expect maturity. Cause: the scheduled maturity date has not
been reached yet, and the contract rejects the call until then. Fix: wait for the scheduled date, or use "Trigger
early maturity" instead if the situation and your account's Emergency role justify acting before it.

**Early maturity cannot be selected**

Signal: **Trigger early maturity** is absent or disabled. Cause: either your account lacks the Emergency role, or the
scheduled maturity date has already been reached, at which point the contract accepts only "Mature bond". Fix: check
which reason the Console names. Ask for the Emergency role if that is missing, or use "Mature bond" once the date is
reached.

**Claim yield is not offered**

Signal: **Claim yield** is greyed with "No yield is waiting for your wallet to claim." even though the schedule is
active. Cause: one of three conditions. The schedule's first period has not completed yet, so nothing is claimable. A
period becomes claimable in the first second after its end time. Your account's accrued yield was already fully
consumed, typically by a conversion into another instrument. Or nothing has accrued since your last claim. Fix: check
the current period against the schedule's start date and interval. If a claim was recently made, confirm whether a new
period has completed since.

**Claim yield settles fewer periods than you left unclaimed**

Signal: after a claim, **Claim yield** still offers yield for older periods. Cause: one "Claim yield" call settles at
most 104 periods. Fix: select "Claim yield" again until no yield is waiting for your wallet.

**Redeem at maturity is not offered even though the bond has matured**

Signal: the bond's status shows matured, but **Redeem at maturity** is missing for your account. Cause: redemption
needs a positive available balance in the bond, not only permission. An account with the redeem permission but no
holding of this bond does not see the control. Fix: confirm the connected account holds the bond by checking
"Holders".

**Redeem at maturity is offered but fails**

Signal: the control is visible but disabled, or submission fails, with the Console naming a specific reason. Cause:
the reasons resolve in order, and the Console names only the first that applies: the bond has not matured, the
treasury's solvency is still being verified, the treasury has not approved the feature to spend the denomination
asset, the treasury holds none of the denomination asset, or the token is halted. Fix: read the named reason and
address that one first. A further reason underneath only becomes visible once the first is resolved.

**Approve allowance does not appear**

Signal: **Approve allowance** is not offered, even though the treasury needs funding. Cause: the control needs a
wallet that can grant a spending allowance, and both features draw that line the same way. An ordinary wallet treasury
qualifies. A contract treasury qualifies only when that same contract is the account you have connected, so a
smart-account treasury under your own control can approve where a third-party vault contract cannot. The control
appears only while the allowance is below what the feature needs. On the yield page, any other account sees "Approve
allowance" greyed with the treasury wallet named. On the maturity page, only the treasury account itself sees it. Fix:
connect the treasury's own wallet or smart account. If a separate contract holds the treasury role, use its supported
payout or approval mechanism. A missing Console control does not prove the contract can pay without setup.

**Top up appears to do nothing, or is missing for my account**

Signal: **Top up redemption treasury** or "Top up yield treasury" is absent for the account that is itself set as the
treasury. Cause: this is expected. Funding a treasury from its own wallet has no effect on the balance it holds, so
the control does not offer it to that wallet. Fix: use a different account with the top-up permission and available
tokens to send to the treasury, not the treasury's own connected wallet.

**The maturity section's treasury-health indicator reads yellow or red**

Signal: the badge in the "Maturity" panel header, labelled **Balance low** or "Approval below ceiling", is not green.
Cause: the two colours name two different shortfalls, not one shared warning state. Yellow means the approval is
sufficient but the live balance is below the projected next-period need. Red means at least one approval is below its
required ceiling, regardless of balance. Fix: for yellow, top up the treasury. For red, approve the feature to spend
enough from it. Yield carries no equivalent badge.

**Set treasury is missing or disabled**

Signal: **Set yield treasury** or "Set maturity treasury" does not appear, or appears disabled. Cause: changing a
treasury address needs the Governance role on this specific asset. Without it, the control stays out of reach
regardless of any other permission you hold. On a matured bond, the maturity treasury "Edit" stays greyed with "The
bond has matured, so its treasury can no longer change". Fix: ask an administrator for the Governance role, scoped to
this asset. After maturity, fund the existing treasury instead.

## Frequently asked questions [#frequently-asked-questions]

### If I miss claiming a period, does the yield expire?

The schedule does not expire an unclaimed period. The schedule tracks each period's claimed and unclaimed yield separately, so an amount you did not claim when its period completed stays tracked afterward. What can make a specific claim disappear is covered under Troubleshooting: the schedule's first period has not completed, a conversion consumed your accrued amount, or nothing has accrued since your last claim.

Two further causes can leave you with less than what accrued. If other holders exhaust a period's shared payout cap, or you convert your own accrued yield into another instrument, before you claim, your claim cursor still advances past that period at zero payout. The period counts as settled, not owed. And a single **Claim yield** call settles at most 104 periods. A longer unclaimed backlog needs more than one call.

### Do all holders receive their matured redemption at once?

No. Maturity makes redemption possible. Each holder redeems on their own initiative, or a Custodian redeems on their behalf, and a holder needs a positive available balance to see the control. The treasury may need more than one top-up as different holders come through, since only the balance available at the moment of each redemption has to cover it.

### Does freezing a holder stop their yield, dividends, or redemption?

A freeze stops a holder's redemption on the DALP 3.2 token contract and on a legacy bond, a bond of the [seven original asset families](https://docs.settlemint.com/docs/deployment/upgrade-to-3-2#decide-on-legacy-asset-creation). A freeze of the whole address also stops dividend claims. No freeze stops yield. A freeze blocks the holder's own movement of the asset's tokens, and a redemption burns those tokens. A fully frozen address cannot redeem at all, and a partial freeze lets the holder redeem only the balance that is not frozen. The frozen amount stays frozen. An asset issued from an instrument template is the exception until [System updates](https://docs.settlemint.com/docs/console/organisation-settings/system-updates) moves it to the DALP 3.2 token contract: its redemption at maturity ignores both kinds of freeze and pays a frozen holder in full. A yield claim burns no tokens. It pays the denomination asset from the treasury, so a frozen holder keeps accruing yield and can claim it. A dividend claim is refused for an address frozen as a whole, whether the holder claims it or a custodian pushes it, singly or in a batch, until the freeze is lifted. A partial freeze does not stop a dividend claim.

### Does topping up the treasury also approve it to spend those tokens?

No, they are two separate steps. Topping up is a plain transfer of the denomination asset into the treasury address. It changes the balance the treasury holds, nothing else. Approving is a separate allowance grant that lets the yield or maturity feature spend from that balance when a holder claims or redeems. The treasury-health indicator watches both together, so a green status means the balance and the allowance are both sufficient.

### How are dividends paid across share classes?

An instrument with several share classes can pay every class from one pool in rank order. One class carries a distribution waterfall, and each class's dividend feature uses the waterfall as its treasury. A holder's claim draws only on the amount the waterfall allocated to that holder's class, so a claim on a class with no allocation fails. The token page shows the waterfall as awaiting a coordinated distribution until the first pool is funded.

The ranks and the two payment orders come from the terms the instrument was issued with. [Paying several share classes from one pool](https://docs.settlemint.com/docs/concepts/issuing-and-markets/corporate-action#paying-several-share-classes-from-one-pool) explains the mechanism, and the [distribution waterfall entry](https://docs.settlemint.com/docs/concepts/modeling-assets/token-features/income#distribution-waterfall) lists the terms and works through the numbers.

### Can the treasury be a smart contract instead of an ordinary wallet?

Yes, for both features. The Console tracks whether a treasury address is a contract and adjusts what it offers accordingly, the same distinction covered under Troubleshooting for a missing approve control.


# Compliance providers

Source: https://docs.settlemint.com/docs/console/compliance/compliance-providers
Connect an identity or screening vendor so its verdicts issue and revoke verifications on participants' on-chain identities automatically.

A compliance provider connects one account at an identity or screening vendor, such as Sumsub, Onfido or Elliptic, to your organisation, so the vendor's verdicts become verifications on participants' on-chain identities without anyone issuing them by hand. An approved verdict issues the verification, a rejection or a severe screening alert revokes it, and every transfer check afterwards reads the result. A revoke removes only this provider's verification: a participant who also holds a valid verification on the same topic from another trusted issuer still passes, so review who else is trusted for the topic. The provider verifies only participants your integration registers as subjects at the vendor through the Platform API, a step with no Console screen.

A verification, also called a claim, is a signed record on a participant's on-chain identity that says the participant passed one category of check, such as KYC. Each category is a verification topic. A token's compliance rules require topics, and they accept a verification only from a trusted issuer, an identity the system trusts to sign verifications for that topic. When no vendor is connected, a person with the "Verification issuer" role adds verifications by hand on [Verify a participant](https://docs.settlemint.com/docs/console/participants/verify-a-participant).

![Compliance providers table with Provider, Topics, Status, Last activity and Actions columns](https://docs.settlemint.com/docs/screenshots/console-compliance-providers.light.en.webp)

[Screenshot] The "Compliance providers" list with an "Add compliance provider" button and one row per provider, showing its name, its topics as active out of total, its status badge and its last activity.

A failed or pending row offers "Retry provisioning", an active row offers "Pause", and a paused row offers "Resume".

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

- **A role that opens the page.** The sidebar shows "Compliance providers" only to the "Permission manager", "System manager" and "Compliance manager" roles.
- **A signing wallet with one of those roles.** Every change on the page also needs the wallet that signs your changes to hold one of those roles. When it does not, the list reads "Read only. The wallet that signs your changes needs one of these roles:" followed by the roles, and the write actions stay disabled.
- **Your wallet verification.** Connecting, replacing credentials, adding or editing a topic, rotating a secret, revoking and reactivating a topic each ask for your [wallet verification](https://docs.settlemint.com/docs/console/my-account/security#wallet-verification), the PIN or authenticator code that confirms a signature.
- **A second approver, when your organisation requires one.** When the "Compliance configuration" group is protected under [Approvals](https://docs.settlemint.com/docs/console/organisation-settings/general#approvals), each change on this screen waits on [Actions](https://docs.settlemint.com/docs/console/essentials/actions#decide-an-administrative-change) until another person approves it, and nothing changes until then.
- **The vendor account.** Have the credentials [Supported vendors](#supported-vendors) lists for your vendor and, for Sumsub, the level already set up at Sumsub.
- **The topic.** The topic the vendor attests must appear on [Verification topics](https://docs.settlemint.com/docs/console/compliance/verification-topics).
- **A claim validity that matches your re-verification cycle.** A verification is refused after its valid-until date only on an asset that runs [Claim expiry](https://docs.settlemint.com/docs/concepts/compliance-and-identity/compliance-modules#claim-expiry), so add that module to assets that must enforce it.
- **An integration that registers subjects.** Each participant must be registered with the provider through the Platform API before a verdict counts. [Onboard an investor](https://docs.settlemint.com/docs/api-reference/guides/onboard-an-investor) walks through it.

## Steps [#steps]

### Open Compliance providers [#open-compliance-providers]

Open "Compliance", then **Compliance providers**. The list has the columns "Provider", "Topics", "Status", "Last activity" and "Actions", and shows up to 200 providers, 25 to a page. The "Actions" cell offers "Retry provisioning" on a failed or pending provider, "Resume" on a paused one and "Pause" on an active one. Providers whose own status is failed or paused sort first, then the rest by most recent change.

The status badge sums up the provider's topics: "Failed" when any topic failed, "Pending" when any topic is still being set up, the shared status when every topic agrees, and "Mixed" when they differ. **Last activity** shows the latest verdict state over "Last verdict at" and its date, or "Verdict recorded" when the state is not known. For an alert it shows the severity over "Last alert on" and the date. For a refused event it shows the outcome over "Last webhook on" and the date. A provider with none of these reads "No activity yet".

### Choose the vendor [#choose-the-vendor]

Select **Add compliance provider**. The wizard "Add a compliance provider" has three chapters: "Provider", "Connect" and "Review and sign". On "Provider", pick the vendor. "Filter by what you need verified" narrows the list to vendors that attest one topic, and each vendor card lists "Verifications it can issue" and "What you need from your account".

![Add a compliance provider wizard at the Provider chapter](https://docs.settlemint.com/docs/screenshots/console-compliance-providers-new-provider.light.en.webp)

[Screenshot] The "Provider" chapter of the "Add a compliance provider" wizard asks "Which provider checks your investors?".

A filter narrows the cards by what you need verified, such as KYC or AML. Each card names a provider and the verifications it can issue, and a side panel lists what you need from your account with that provider, for Sumsub an app token, a secret key, a KYC level name and a webhook signing secret.

The wizard keeps your choices in this browser for 7 days, for the signed-in user and organisation, so you can leave and come back. It keeps the level name, the region and the webhook IP addresses, but never a token, key or secret: you enter those again when you return.

### Set the topic, threshold and claim validity [#set-the-topic-threshold-and-claim-validity]

On "Connect", the **Topic and threshold** section sets three values for the first topic.

- **Verification topic**: one of the topics the vendor attests. A vendor with one topic shows it without a choice. You add more topics on the provider page later.
- **Severity threshold**: the alert severity, on a scale of 0 to 100, at or above which an alert revokes the verification. An alert below it is recorded and changes nothing. The threshold has no effect for a vendor that sends no monitoring alerts. The choices are "Low (25/100)", "Medium (50/100)", "High (80/100)" and "Critical (95/100)". "High (80/100)" is the default.
- **Claim validity**: how long a verification issued from an approved verdict stays valid. Enter a whole number and pick "Days", "Months" or "Years", or keep "Never expires", the default. A month counts as 30 days and a year as 365 days, and the total can be at most 68 years, 828 months or 24,855 days. The validity runs from the time the vendor reports for the verdict.

The platform writes the valid-until date into the verification. An asset refuses a lapsed verification only when it runs the Claim expiry compliance module, and on such an asset the participant must be verified again.

![Connect chapter for Sumsub with the verification topic, severity threshold and claim validity](https://docs.settlemint.com/docs/screenshots/console-compliance-providers-connect.light.en.webp)

[Screenshot] The "Connect" chapter for Sumsub shows the verification topic, severity threshold and claim validity.

The "Topic and threshold" section shows "KYC (Know Your Customer)" under "Verification topic", the "Severity threshold" picker on "High (80/100)" and the "Claim validity" field on "Never expires". **Continue to Review and sign** stays unavailable until the credential fields in the next section are filled.

### Enter and test the credentials [#enter-and-test-the-credentials]

In "Credentials", fill in every field the vendor asks for, then select **Test connection**. The platform sends the credentials to the vendor and shows the answer: "Sumsub accepted these credentials." or "Sumsub rejected these credentials.", with the vendor's own message when it gives one. For Sumsub, the test also checks that the level name exists. "Test connection" stays disabled until every required field is filled in, and changing a credential after a passing test means you test again.

### Review and sign [#review-and-sign]

On "Review and sign", read **What signing does**: signing registers the vendor as a trusted issuer for the topic, and after that its verifications count when investors are checked. The chapter lists checks that must pass before you can sign. It blocks signing when the credentials are not tested or were rejected, when the claim validity is not valid, when your signing wallet lacks the roles, or with "KYC (Know Your Customer) is not registered on this platform" when the topic does not exist yet. Create a missing topic on "Verification topics" and come back.

Select **Sign and connect** with the vendor's name and confirm with your wallet verification. Setting up the provider's identity on chain can take longer than one request, for example while the network is busy. The Console then keeps waiting on the same step until the setup finishes, for up to three minutes. The outcome reads one of these:

- **Sumsub is connected**: the provider is active and registered as a trusted issuer.
- **Sumsub is waiting for approval**: your organisation's transaction policy holds the registration until its approvers approve it.
- **Sumsub could not be connected**: the provider stays on the list as "Failed", with "Retry provisioning".

### Point the vendor at each topic's webhook URL [#point-the-vendor-at-each-topics-webhook-url]

Select **Open provider**. The "Verification topics" table on the provider page has one row per topic, with the columns "Topic", "URL", "Status", "Severity threshold", "Claim validity" and "Last activity". The Console masks the end of each URL.

Select **Reveal** to see it, or copy it, then paste it into the webhook settings at the vendor, together with the same signing secret you entered in the wizard. Treat the URL like a credential: it identifies this provider to the platform.

![A provider page with the Provider actions menu and the Verification topics table with the Topic, URL, Status, Severity threshold, Claim validity and Last activity columns](https://docs.settlemint.com/docs/screenshots/console-compliance-provider-detail.light.en.webp)

[Screenshot] The provider page shows the "Provider actions" menu and the "Verification topics" table.

The header holds "Test connection", "Replace credentials" and "Provider actions". The "Verification topics" table has one row per topic with its masked URL and a "Reveal" button, its status, severity threshold, claim validity and last activity, and an "Add topic" button in the table toolbar.

## Change a connected provider [#change-a-connected-provider]

### Add a topic [#add-a-topic]

Select **Add topic** in the "Verification topics" toolbar. The dialog "Add a verification topic" offers only topics the vendor attests that this provider does not hold yet, and asks for the topic's "Severity threshold", "Claim validity" and "Webhook signing secret". Confirm with your wallet verification. The provider keeps its identity and credentials, and the platform registers it as a trusted issuer for the new topic. "Add topic" is disabled with "Topics can be added once the provider is active." while the provider is pending, and with "Every available topic is already added." when nothing is left.

### Change a topic's threshold or claim validity [#change-a-topics-threshold-or-claim-validity]

In the topic row's menu, select **Edit topic**. The panel changes the severity threshold and the claim validity, and asks for your wallet verification. You can edit an active or paused topic. The new values apply to events that arrive afterwards. Verifications already issued keep the valid-until date they were issued with.

### Replace the credentials [#replace-the-credentials]

Select **Replace credentials** in the page header, or in "Provider actions" on a phone. Enter the full set again, because credentials are write-only, then confirm with your wallet verification. The new credentials must be for the same vendor product, and the vendor must accept them before anything is saved. If the vendor refuses them, the old credentials stay in place. Webhook signing secrets are not part of this sheet: you rotate them per topic.

### Rotate a webhook signing secret [#rotate-a-webhook-signing-secret]

Note (The Console stages a rotation but cannot finish it): Only the Platform API, the platform's HTTP interface, promotes or cancels a rotation, and only for the provider's first topic, the one you chose when you connected. The Console therefore offers "Rotate secret" on that topic's row only, and not on topics you added later. Have Platform API access ready before you start.

1. In the first topic's row menu, select **Rotate secret**.
2. Enter the **New signing secret** and choose a "Grace window" of "15 min", "1 hour", "6 hours" or "24 hours".
3. Select "Stage rotation" and confirm with your wallet verification.
4. Update the vendor's dashboard inside the window.
5. Promote the rotation through the Platform API before the window ends.

During the window the platform accepts events signed with either the current or the new secret. Only one rotation per topic can be pending. Once the window has passed without promotion, the platform accepts only the current secret again and refuses a late promotion. The expired rotation stays pending and blocks a new one until you cancel it through the API.

## Pause, revoke and reactivate [#pause-revoke-and-reactivate]

Note (A pause drops the vendor's events): While a topic is paused, the platform refuses the vendor's events and keeps no copy. A rejection or alert sent during a pause has no effect unless the vendor sends it again after you resume. Before you pause a screening provider, plan how its alerts will be resent.

A pause has no on-chain effect. A revoke removes the provider's trusted-issuer registration, which changes every transfer check that runs afterwards. A provider revoke cannot be undone.

| You choose | What changes | Verifications already issued | The way back |
| --- | --- | --- | --- |
| **Pause** on a topic row | The topic's webhook URL refuses new events. The vendor gets a not-found answer. | Still count, subject to the token's own compliance rules. | **Resume** on the same row. |
| **Pause** in **Provider actions** or on the list | Every topic of the provider refuses new events. | Still count. | **Resume**. It also resumes topics you paused one by one. |
| **Revoke topic** on a topic row | The provider is no longer a trusted issuer for that topic. Its other topics keep working. Offered on an active topic only, so resume a paused one first. | Stay on identities but stop counting for that topic. | **Reactivate topic** trusts the provider for the topic again, keeping the URL and secret. |
| **Revoke** in **Provider actions** | The provider is removed from the trusted-issuer registry for every topic, and its webhook URLs stop accepting events. | Stay on identities but stop counting. | None. Connect the vendor again to create a new provider. |

An event that the platform had already accepted when you paused can still be processed afterwards. It is then recorded as **Rejected: provider paused** and changes no verification.

**Revoke topic** is disabled on the provider's last topic that is active or paused, with "This is the last active topic on the provider. Revoke the whole compliance provider instead." To stop that topic, revoke the provider.

The revoke dialog, titled with the vendor's name such as "Revoke compliance provider Sumsub?", names every topic it removes. Connecting the same vendor again creates a new provider with a new on-chain identity, and the platform never registers the revoked identity again, so each participant needs a new verification from the new provider.

## Read what the vendor sent [#read-what-the-vendor-sent]

For a vendor that sends alerts, **Monitoring history** in "Provider actions" lists each recorded monitoring alert with its "Subject", "Topic", "Severity", "Outcome" and "Created" time in UTC. Open a row to see and copy its "Event reference". You can filter by topic and search. Verdicts do not appear in this list. The outcomes are:

- **Applied**: the alert revoked the verification, or was below the threshold and was recorded.
- **Duplicate delivery**: the vendor sent an alert the platform had already processed.
- **Pending**: the alert is still being processed.
- **Rejected: out of order**: a newer event for the same subject and topic was already processed.
- **Rejected: unknown subject**: the platform could not map the event, or its subject was never registered with this provider.
- **Rejected: topic mismatch**: the alert's topic is not the topic row's, or the provider is no longer a trusted issuer for the topic on chain.
- **Rejected: provider paused**: the provider or topic was paused when the alert was processed.
- **Rejected: over the cap**: the provider reached its limit of fee-paid verifications. The limit is shared by all the provider's topics. The default is 10,000 verifications in a rolling 24 hours, and the limit and window are configurable per organisation. The cap counts issued verifications only. A revocation is never refused for the cap.
- **Rejected: cannot be sponsored**: the provider's issuing account is not set up to sign for the provider's identity, so the platform refuses to pay for a transaction that would fail.
- **Failed**: processing failed.

![Sumsub monitoring history with the All topics filter and the empty state Monitoring is active, no alerts yet](https://docs.settlemint.com/docs/screenshots/console-compliance-provider-monitoring.light.en.webp)

[Screenshot] The title names the provider, "Sumsub monitoring history", and an "All topics" filter sits above the list.

Until an alert is accepted, the page reads "Monitoring is active, no alerts yet" and "Provider alerts will appear here after signed provider webhooks are accepted." Once alerts arrive, the table lists "Subject", "Topic", "Severity", "Outcome" and "Created".

## How a provider verifies a participant [#how-a-provider-verifies-a-participant]

1. **The topic exists.** The topic the vendor attests, such as "KYC (Know Your Customer)", is registered on [Verification topics](https://docs.settlemint.com/docs/console/compliance/verification-topics).
2. **You connect the provider.** The platform creates an on-chain identity for the provider and registers it as a [trusted issuer](https://docs.settlemint.com/docs/console/compliance/trusted-issuers) for that topic. Each topic gets its own webhook URL, the address where the vendor sends its results.
3. **The participant becomes a subject at the vendor.** A subject is the vendor's record for one participant, wallet or transaction, linked to the participant's identity. Your integration registers subjects through the Platform API. The API creates the applicant at the vendor, links a wallet, or registers a transaction for screening. The Console has no screen for this step. A result for a participant who was never registered as a subject changes nothing. With Sumsub, an investor can also complete the vendor's check inside the investor portal.
4. **The vendor sends a signed result.** The platform checks the signature with the topic's webhook signing secret, or, for Jumio, checks Basic-Auth credentials and the sender's IP address. It refuses an event whose timestamp is more than 5 minutes away from the time it arrives.
5. **The platform changes the verification.** An approved verdict issues the topic's verification on the subject's identity, signed by the provider's identity, and the platform pays the network fee. A rejected verdict revokes it. A monitoring alert at or above the topic's severity threshold revokes it, and an alert below the threshold is recorded and changes nothing. A revoke removes only this provider's verification.
6. **Every later check reads it.** A transfer counts the verification only while the provider stays a trusted issuer for the topic. An asset that runs the [Claim expiry](https://docs.settlemint.com/docs/concepts/compliance-and-identity/compliance-modules#claim-expiry) compliance module also refuses a verification past its valid-until date.

[Figure] One provider carries trust from an external service to every compliance check. The external verification service signs webhook events carrying verdicts and monitoring alerts, and never writes on chain itself. The compliance provider you create on this screen holds an issuer identity on chain, registered per topic, and turns those events into issued or revoked claims. Every later compliance check reads that registration at check time, not at issue time, so claims count only while the topic stays registered. Labels: External service; Signed events; verdicts and; monitoring alerts; never writes on chain; This screen; Compliance provider; issuer identity on chain; registered per topic; issues and revokes claims; Every later check; Compliance check; reads trust at; check time; not at issue time.

The vendor never writes to the chain, and a check counts the verifications built from its results only while the provider is a trusted issuer for the topic.

## Supported vendors [#supported-vendors]

KYC checks a person's identity, KYB checks a business, AML screens against sanctions and watch lists, and KYT screens wallets and transactions. The vendor list is fixed. Each vendor product is its own provider with its own on-chain identity, so Sumsub, Sumsub AML and Sumsub KYT are three providers. The wizard asks for different credentials per vendor. Every credential is write-only: the platform stores it in its secret store and never shows it again.

| Vendor in the Console | Topics it attests | What the wizard asks for | Sends monitoring alerts |
| --- | --- | --- | --- |
| **Sumsub** | KYC | **App token**, **Secret key**, **Webhook signing secret**, **KYC level name** | Yes |
| **Sumsub AML** | AML | **API token**, **Secret key**, **Webhook signing secret**, **AML level name** | Yes |
| **Sumsub KYT** | KYT | **API token**, **Secret key**, **Webhook signing secret**, **KYT level name** | Yes |
| **Chainalysis** | KYT | **API key**, **Webhook signing secret** | Yes |
| **ComplyAdvantage** | AML | **API token**, **Webhook signing secret** | Yes |
| **Elliptic** | AML | **API key**, **API secret**, **Webhook signing secret** | Yes |
| **Jumio** | KYC | **API token**, **API secret**, **Region**, **Basic-Auth credentials**, the webhook IP list | No |
| **Middesk** | KYB | **API key**, **Webhook signing secret** | No |
| **Onfido (Entrust)** | KYC, KYB | **API token**, **Webhook signing secret**, **Region** | No |
| **Persona** | KYC, KYB | **API token**, **Webhook signing secret**, optionally **Default inquiry template ID** | No |
| **Trulioo** | KYC | **API key**, **API secret**, **Webhook signing secret** | No |
| **Veriff** | KYC | **API key**, **API secret**, **Webhook signing secret** | No |

A Sumsub level name must match a level that already exists in that Sumsub account. Jumio's region is `amer-1`, `eu-1` or `sg-1`, and Onfido's is `EU`, `US` or `CA`. For Jumio, the webhook IP field takes one IP address or address range in CIDR notation, such as 34.107.16.0/24, per line, and the platform refuses webhooks from any other address. A vendor that sends monitoring alerts gets a "Monitoring history" page. The others return one verdict per subject.

The investor portal shows Sumsub's own verification screen. DALP passes it English as the language and the portal's light or dark theme. The rest of its look comes from the WebSDK 2.0 customisation on the level in your Sumsub account, which Sumsub documents in [Customise WebSDK](https://docs.sumsub.com/docs/sdk-customization).

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

- The provider page shows the status "Active", and each topic row reads "Active".
- Select **Test connection** in the page header: "The provider accepted the stored credentials." confirms the vendor still accepts what DALP holds. The health line under the title reads "Credentials are on file" once the health check has run.
- Then register one test participant as a subject through the Platform API and run its check at the vendor. For a verdict vendor, the topic row's "Last activity" changes to "Last verdict at" with the time, and the participant's Verifications tab shows a new active verification from the provider's identity. For a vendor that sends alerts, open **Monitoring history** from "Provider actions" and look for a row with the outcome "Applied".

## Troubleshooting [#troubleshooting]

**Test connection says the vendor rejected the credentials**

The message under the result is the vendor's own. Until you reload the page, the header badge and the health line also
read "Credentials rejected", with the time of the test. Nothing is stored, so a reload shows the stored status again.
Correct the field it names, then test again. For Sumsub, check that the level name matches a level in that Sumsub
account exactly.

**Last activity reads Rejected instead of a severity**

The latest webhook from the vendor was refused or failed. "Last activity" shows its outcome, such as "Rejected:
unknown subject", with "Last webhook on" and the date. For a vendor that sends alerts, "Monitoring history" lists each
one.

**Review and sign says the topic is not registered on this platform**

The topic the vendor attests is missing from your system. Create it on [Verification
topics](https://docs.settlemint.com/docs/console/compliance/verification-topics), then return to the wizard. Your choices are still there, but
enter the credentials again.

**The provider stays Pending**

The status explanation reads "Provisioning is in progress." The registration is either still running or held by your
organisation's approval step in the transaction queue, where a transaction waits until it is approved, for example
under your custodian's approval policy. Ask whoever approves your organisation's transactions to approve it. If it
does not complete, select **Retry provisioning**.

**The provider shows Failed**

The status explanation reads "Setup did not finish. Retry provisioning to continue." Select **Retry provisioning** in
"Provider actions" or on the list row.

**Review and sign says another provider of this vendor is still being created**

An organisation holds one live provider per vendor on a system, and an earlier connection of the same vendor is still
being set up, for example from another browser tab or by another administrator. The platform refuses the second one
before it writes anything on chain. Open the providers list and wait for the earlier provider to turn Active, Pending
or Failed, then continue with that one. If no earlier provider appears and the refusal persists, connecting again
succeeds 15 minutes after the earlier attempt started.

**The provider is Active but nothing happens**

Check that the vendor's webhook settings use the topic row's full URL and the same signing secret you entered, and,
for Jumio, that the vendor's IP addresses are among the accepted webhook IP addresses. For a vendor that sends alerts,
check **Monitoring history** for "Rejected: unknown subject": the participant was never registered as a subject with
this provider.

**The health line says some stored credentials could not be found**

A credential or signing secret the provider needs is missing from the secret store. Replace the credentials with
**Replace credentials**. For a missing signing secret on the provider's first topic, stage a rotation and promote it
through the Platform API, or cancel a stale pending rotation through the API. On a later topic the Console and API
offer no way to replace the secret, and the last resort is to revoke the provider and connect the vendor again, which
ends every verification the provider issued.

## Frequently asked questions [#frequently-asked-questions]

### Can two providers serve the same topic?

Yes. Each provider is its own trusted issuer, so a second provider can register for a topic another provider already serves. To move to a new vendor, connect it on the topic, let it issue new verifications, then revoke the old provider once no participant depends on its verifications.

### Can I read the credentials back?

No. Credentials and signing secrets are write-only and never appear in the Console or in an API response. Keep the source values in your own secret store.

### Does pausing a provider take verifications away?

No. Pausing changes nothing on chain, and verifications the provider already issued keep counting until a revoke, or until their valid-until date on an asset that runs the Claim expiry compliance module. But a rejection or alert the vendor sends during the pause is refused and revokes nothing unless the vendor sends it again after you resume.

## API routes [#api-routes]

Every action on this screen has an endpoint in the [Platform API reference](https://docs.settlemint.com/docs/api-reference/v2). Subject registration, which has no Console screen, uses the compliance subject endpoints under `/api/v2/compliance/subjects`.

Creating a provider (`POST /api/v2/compliance/providers`) answers `202` with `{ requestId, state: "running", statusUrl }`, and the setup continues on chain. Read `statusUrl` (`GET /api/v2/compliance/provider-create-requests/{requestId}`) until it answers `200` with the provider, or the refusal the setup ended with. Send `Prefer: wait=N`, with N from 5 to 99 seconds, to wait for the setup in the same request: the answer is `200` with the provider when it finishes in time, and `202` otherwise.


# Global controls

Source: https://docs.settlemint.com/docs/console/compliance/global-controls
Configure compliance controls that apply to every token bound to your organisation's compliance engine, whatever product line issued it.

A global control is one compliance module, such as an address block list or an issuance cap, installed on your organisation's system compliance engine rather than on a single token. Each control carries one or more rules, and each rule pairs the module's parameters with a scope that decides which transfers it checks. Every bound token inherits the result. A token is bound when its factory deployed it against this system's compliance engine, and an older token joins only after a factory migration binds it. A global control reaches your organisation's tokens on the active network only. See compliance policy for how the global layer and the token layer fit together.

Use this screen only when a rule must hold on every token, whatever product line issued it. **Issue asset** offers no way to remove an inherited global control. Policy templates and a token's own compliance tab add rules on top of it and never replace it.

| Where the rule lives | What it reaches | Choose it when |
| --- | --- | --- |
| Global control | Every bound token, including ones issued after the rule lands, minus the rule's own carve-outs. | Every token must follow it. |
| [Policy template](https://docs.settlemint.com/docs/console/compliance/policy-templates) | Tokens issued from a template that carries the policy. | It defines one product line, not every one. |
| The token's compliance tab | One token, on top of everything it inherits. | Only that instrument needs it. |

![Global controls before any rule is installed, with No global rules yet and the Add control button](https://docs.settlemint.com/docs/screenshots/console-global-controls-rules.light.en.webp)

[Screenshot] With no rule installed, the "Global controls" page shows "No global rules yet" and an "Add control" button.

The card reads "No global rules yet", explains that a global control is a rule that applies to every asset your organisation issues, on top of each asset's own rules, and carries **Add control**. Once rules are installed, the page lists them, and each row names the control, summarises its parameters and scope, and carries an on or off switch, "Edit" and "Remove".

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

- **The Compliance manager role.** You need it to change anything here. Any other role that can open the page sees it read only, under the notice "Only a Compliance manager can change global controls." The Permission manager role opens the page read only. The System manager role cannot add or edit a rule here either, but it can register a control's contract and replace the contract an installed control type runs, which changes how every rule of that type behaves, so review who holds it.
- **A second approver, when your organisation requires one.** When the "Compliance configuration" group is protected under [Approvals](https://docs.settlemint.com/docs/console/organisation-settings/general#approvals), each change on this screen waits on [Actions](https://docs.settlemint.com/docs/console/essentials/actions#decide-an-administrative-change) until another person approves it, and nothing changes until then.
- **The active organisation.** The controls you manage belong to the active organisation. If you belong to more than one, switch from the "Organisation" submenu of the account menu at the top right first.
- **The network.** On a deployment with more than one network, the page reads and writes the active network's controls.
- **Your wallet verification.** The Console confirms each change with your wallet verification and submits it as a signed transaction from your wallet. Installing a rule, switching it and removing it each add an entry to the organisation's [audit trail](https://docs.settlemint.com/docs/console/reporting/audit-trail). The screen shows current state only.

## Steps [#steps]

### Open Global controls [#open-global-controls]

In the sidebar, open "Compliance", then **Global controls**. The page holds one list of the rules already installed. Each row names the control, summarises its parameters and scope, and carries an on or off switch, "Edit", and "Remove". An organisation with no global rule shows "No global rules yet" instead, with "Add control" for a compliance manager.

Select **Add control**. The sheet of the same name lists the controls you can install, grouped by category, with a search box and a filter for each category. A control you already installed is marked "Added", and picking it again adds a second rule of the same kind. The sheet lists only controls registered in the system's module registry, and of those only the current-generation variants and the issuance volume limit, so it is shorter than the full module catalogue. [Compliance modules](https://docs.settlemint.com/docs/concepts/compliance-and-identity/compliance-modules) explains the generations. Without the Compliance manager role, the rows offer "View" instead of "Edit", and there is no switch, "Remove", or "Add control" to use.

![The Add control sheet open over Global controls, listing eligibility, restriction and transfer controls with a search box and category filters](https://docs.settlemint.com/docs/screenshots/console-global-controls.light.en.webp)

[Screenshot] The "Add control" sheet lists the controls, grouped by category, starting with "Eligibility", "Restrictions" and "Transfer controls".

The category filters above the list each show a count, and **All** shows the total. Each row names the control and says in one line what it does, such as "Block investors from specific countries" for "Country block list".

### Pick a control and add a rule [#pick-a-control-and-add-a-rule]

Select a control in the **Add control** sheet. Its editor opens with the module's parameters under "Configuration" and the scope under "Applies to". A control you have not installed yet is marked "Not enabled". To change a rule that is already installed, select "Edit" on its row instead. Parameters differ per module. The [compliance module reference](https://docs.settlemint.com/docs/concepts/compliance-and-identity/compliance-modules) states what each one permits or refuses, with units. Check that reference before committing, because some parameters lock. The issuance volume limit locks its period length and window mode when enabled. The capital raise limit locks its parameters at installation, while its scope stays editable. Changing a locked value requires a new instance and resets that instance's tracking.

### Decide the rule's scope [#decide-the-rules-scope]

Under "Applies to", keep "All transfers" or choose **Selected transfers** and build the filter. Choosing "Selected transfers" reveals three independent dimensions, "Sender", "Receiver", and "Token", each with its own filters.

"Sender" and "Receiver" each take an **Include** card and an "Exclude" card, filtered by "Verification topics" and "Countries". The include hint on each card reads "Only transfers matching these criteria are checked by this rule." An empty include card matches everyone, so a rule with only excludes checks everything except the carve-outs.

**Token** takes the same pair of cards, but filtered by verification topics only, which is how you keep a global rule off tokens it should not touch. A token that carries no distinguishing claim topic cannot be singled out this way, so you scope by the topics a token carries. The filter cannot pick a token by name.

The checkbox **Track transfers outside this scope** decides whether the rule still counts transfers it does not check. The hint reads "Transfers outside this scope are not checked, but they still update this rule's counts and quotas." Review this setting for stateful modules that count supply, holders, or other activity outside their enforcement scope: with the box cleared, such a module shows a warning that its counts, quotas and approvals drift and that missed transfers are not replayed.

### Save and confirm [#save-and-confirm]

Choose **Save & enable** for a control you have not installed yet, or "Save" otherwise, then enter your wallet verification in the "Confirm compliance change" dialog. A success toast, "Compliance control enabled" or "Compliance control updated", means the transaction landed and the rule is already live for every bound token in scope. The toast does not prove the rule behaves as you intended, and the checks under [You should see](#you-should-see) do.

## Turn a rule off or remove it [#turn-a-rule-off-or-remove-it]

To pause a rule and keep its settings, turn its switch off. Turn it on again to resume checking.

Note (Removing a rule is permanent, and a replacement starts from zero): The removal dialog warns that the control "stops checking transfers on every asset and its counts are deleted." Operations the rule already allowed or blocked keep their outcomes, and adding the same kind of control again later creates a fresh instance with fresh tracking. A capacity rule that had counted issuance against its window starts that window over at zero. When you add the control again, nothing on its row shows the earlier tally.

Select **Remove** on the rule's row, read the dialog, and confirm with your wallet verification.

## When a change takes effect [#when-a-change-takes-effect]

Installing, reconfiguring or removing a control changes later compliance checks for every token in the rule's scope at once. A compliance check runs at the moment an operation executes on chain, not when someone submits it. A transfer that completed under the old rule keeps its outcome and is never revisited. One still pending is checked against whatever rule set is live when it executes. [When a module refuses](https://docs.settlemint.com/docs/concepts/compliance-and-identity/compliance-modules#when-a-module-refuses) shows what a refusal looks like and which reason code names your rule.

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

- Refresh the page and confirm the rule's row shows the parameters and scope you intended, with its switch on.
- For the full proof, open one bound token's compliance tab and confirm the control appears as a **Global** row in its "Rules" table.
- Open the token's "Transfer pre-check" tab and run one sender, recipient and amount that should pass and one that should fail, as [Verify a participant](https://docs.settlemint.com/docs/console/participants/verify-a-participant) describes.
- Confirm the results match the intended policy.

## Troubleshooting [#troubleshooting]

**A token's compliance tab says Set in Compliance › Global controls**

The token's compliance tab lists a global control with the status **Global** and the setting "Set in Compliance ›
Global controls", and offers no action on it there. Change the rule on this screen, which the sidebar lists under
"Compliance".

**The page is read only**

The notice "Only a Compliance manager can change global controls." means your account lacks that role for this
organisation. The Permission manager and System manager roles cannot write rules from this screen: the platform
refuses their writes, so the Console disables the controls. Ask someone with the Permission manager role to grant
**Compliance manager** on [Roles and permissions](https://docs.settlemint.com/docs/console/organisation-settings/admins-and-roles), then reload.

**A control I expect is not in the Add control sheet**

This screen offers only controls registered in the system's module registry, and of those only the current-generation
variants and the issuance volume limit, even where an older generation still runs elsewhere on the platform. A control
whose type the registry does not hold needs a system manager to register it through the Platform API first. A control
you already installed stays in the sheet, marked **Added**.

**A rule row says its scope is unavailable and saving is blocked**

The row reads "Its settings could not be read." when the Console could not read the rule's on-chain scope. The editor
then blocks saving rather than let an edit overwrite filters it cannot see: "Cannot save: rule scope failed to load.
Refresh the page and try again." Refresh and reopen the rule. The block clears once the scope loads.

**A change reached the wrong transfers or tokens**

Open the rule, adjust its scope or parameters, and save again. The correction applies to every future check the moment
it lands. Operations that already completed under the earlier configuration are not revisited.

**A capital raise limit rule does not accept new parameters**

That module's configuration is immutable once applied, so only its scope can change in place. To change the limit
itself, remove the rule and add a new one, and account for the reset: the new instance starts its tracking window with
nothing counted.

**Mints stop after adding a global capital raise limit**

The limit converts each mint to fiat through the system's price resolver and refuses the mint when the price is
missing, zero, negative or stale. A global rule applies to every token, so a token with no valid price cannot mint
while the rule covers it. Give the token a price feed, or scope the rule away from it under **Applies to**.

## Frequently asked questions [#frequently-asked-questions]

### What skips a global control?

Three paths skip some or all of the checks. A recipient on the system's compliance bypass list skips the checks that judge whether it may hold the token. A Custodian's forced transfer and a wallet recovery move tokens without any compliance module, global or token-level. [Compliance policy](https://docs.settlemint.com/docs/concepts/compliance-and-identity/compliance-policy) lists exactly what each path skips. DALP manages the bypass list: token and add-on factories add the contracts they deploy, such as settlements, escrows and token sales. No Console screen or Platform API route edits the list directly. A System manager can change the list by registering a custom token factory or add-on, or by pointing a registered one at new code, because every registered factory and add-on can add and remove addresses. A Compliance manager can change it with a direct call to the system compliance contract.

## API routes [#api-routes]

The [system compliance module endpoints](https://docs.settlemint.com/docs/api-reference/v2) cover installing, reconfiguring, scoping, switching off and on, and removing a control, and each one needs the Compliance manager role. The install-or-reconfigure endpoint creates an instance when its address is omitted, and refuses when the system already has a global control of that type. Supplying an instance address updates that binding. The scoped install endpoint creates an instance and sets its scope in one transaction, and a companion endpoint replaces an existing instance's parameters and scope together. The Console adds every rule through the scoped install, so it can add a second rule of the same kind. One more endpoint registers a control's implementation in the system's module registry, which a control needs before any rule can use it. That endpoint needs the System manager role. A system manager finds it in a control's sheet as **Use a custom contract for this control**.


# Compliance

Source: https://docs.settlemint.com/docs/console/compliance
The Compliance group of the Console sidebar: policy templates, global controls and the identity evidence every check reads.

The **Compliance** group sets the rules every ordinary transfer and mint is checked against. Its screens divide the work:

- **Policy templates** attach compliance rules to an instrument template.
- **Global controls** apply rules to every bound token.
- **Verification topics** name the kinds of identity evidence those rules read.
- **Trusted issuers** may attest those topics against a participant's on-chain identity.
- **Compliance providers** issue those verifications from a vendor's verdicts.

Set up the evidence first, because a rule that requires a topic no trusted issuer attests fails every holder. A Custodian's forced transfer, a wallet recovery and an address on the compliance bypass list skip those checks, as [Compliance policy](https://docs.settlemint.com/docs/concepts/compliance-and-identity/compliance-policy) describes. [Compliance modules](https://docs.settlemint.com/docs/concepts/compliance-and-identity/compliance-modules) explains what each rule checks.


  - [Policy templates](https://docs.settlemint.com/docs/console/compliance/policy-templates): Assemble reusable compliance rules for instrument templates and asset issuance.
  - [Global controls](https://docs.settlemint.com/docs/console/compliance/global-controls): Configure compliance controls that apply to every token bound to your compliance engine.
  - [Verification topics](https://docs.settlemint.com/docs/console/compliance/verification-topics): Define the verification topics that classify identity evidence.
  - [Trusted issuers](https://docs.settlemint.com/docs/console/compliance/trusted-issuers): Authorise identity issuers for specific verification topics.
  - [Compliance providers](https://docs.settlemint.com/docs/console/compliance/compliance-providers): Connect an identity or screening vendor to issue and revoke verifications automatically.



# Policy templates

Source: https://docs.settlemint.com/docs/console/compliance/policy-templates
Assemble reusable compliance rules for instrument templates and asset issuance.

A policy template bundles compliance controls into one named rule set. A control is one enforceable rule, such as an investor eligibility check or a country restriction, that decides whether a regulated operation like a transfer or a subscription can proceed. Publishing a template makes it a choice an instrument template, the reusable product definition an issuer picks during asset issuance, can link. Each instrument template links at most one published policy. The rules land on an asset only when that asset is issued, so a later edit changes the next issuance and never an asset that exists.

On this screen you decide which rule sets your organisation has, what each one enforces, and which values an issuer may still change per asset in "Issue asset". You do not need this screen to issue an asset, because the instrument template you pick in "Issue asset" already carries its policy.

Every write on this screen, including saving a draft, publishing, editing and deleting, lands in the organisation's [audit trail](https://docs.settlemint.com/docs/console/reporting/audit-trail) with your name and your role at the time.

![Policy templates catalogue with Name, Jurisdictions, Source, Status and Updated columns](https://docs.settlemint.com/docs/screenshots/console-policy-templates.light.en.webp)

[Screenshot] The catalogue lists each policy template with its name, jurisdictions, source, status and last update.

Each row shows the policy's name, its jurisdictions or "Global", its source, whether it is a draft or published, and its last update. A row expands to show the description and the configured and required controls. Use the jurisdictions filter to narrow the catalogue by scope.

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

- **Role.** Creating and changing templates needs the Permission manager or Compliance manager role in the organisation that will own the policy. The platform refuses saves from any other role. An Asset designer or Asset manager sees the catalogue and every template's detail page but no "Create template" button, and uses the screen to choose the policy an instrument template links. An Asset designer sees published templates only.
- **A second approver, when your organisation requires one.** When the "Compliance configuration" group is protected under [Approvals](https://docs.settlemint.com/docs/console/organisation-settings/general#approvals), each change on this screen waits on [Actions](https://docs.settlemint.com/docs/console/essentials/actions#decide-an-administrative-change) until another person approves it, and nothing changes until then.
- **Agreed values.** Agree the covered jurisdictions and every rule value before you publish, because publishing cannot be undone. Record who approved them if your sign-off process needs it.
- **A starting point.** Start from the DALP library for a common regulatory framework, from one of your own templates for a variation, or from a blank template when neither fits.

## Steps [#steps]

### Open Policy templates [#open-policy-templates]

Open "Compliance", then **Policy templates**. The catalogue is a table that shows your organisation's templates next to the platform-provided DALP library set, one row per template. Its columns are "Name", "Jurisdictions", "Source", "Status" and "Updated".

Search, or filter by "Jurisdictions", "Source" and "Status", to check whether a usable rule set already exists before you create a near-duplicate. Sort by "Name", "Status" or "Updated", and page through the table at the bottom.

The **Jurisdictions** column lists each jurisdiction a template covers and reads "Global" for a template with none. "Status" reads "Draft" or "Published".

Select the arrow at the start of a row to expand it. The expanded row shows the template's description, the controls it configures, and the controls it requires. Selecting the row itself opens the template's detail page.

### Choose a starting point [#choose-a-starting-point]

Select **Create template**, then pick one of the three cards on the "Start" step.

![Create a policy template screen with the library, clone and blank starting points](https://docs.settlemint.com/docs/screenshots/console-policy-templates-designer-start.light.en.webp)

[Screenshot] The "Start" step, with one card each to start from the DALP library, clone one of your templates, or start blank.

| Start from | What you get | Choose it when |
| --- | --- | --- |
| **Start from DALP library** | A draft copied from a platform-maintained regulatory framework | A library framework's controls match your product and you only tune their values |
| **Clone one of yours** | A draft copied from one of your organisation's templates | A close rule set exists and needs a variant for another jurisdiction or share class |
| **Blank** | An empty draft with no inherited controls | Nothing existing is close, or every control must be chosen deliberately |

The DALP library includes starting points for frameworks such as the Markets in Crypto-Assets Regulation (MiCA) and the SEC Regulation D Rule 506(b) exemption for private placements. A library template carries the transfer and issuance rules DALP can enforce for that framework, and its description lists only those rules. The framework's other obligations, such as a MiCA white paper or Regulation D's bar on general solicitation, stay with you.

A copy does not stay connected to its source, so a later change to the library or to the source template never reaches your draft. [Library frameworks and the legacy generation](#library-frameworks-and-the-legacy-generation) covers the Shari'ah framework and legacy templates.

### Set the scope and the controls [#set-the-scope-and-the-controls]

Name the template on the "Basics" step, choose jurisdictions on the "Scope" step, then enable and configure controls on the **Controls and rules** step. Template names are unique within an organisation. The jurisdiction list is a label: it records where the rule set is meant to apply and feeds the catalogue's jurisdiction filter. It does not restrict where the rules apply, which a country rule does. Leaving it empty shows the template as "Global".

Select **Add control** to open the controls catalogue, then pick a control to open its editor. The control joins the template only when you set its rule values and save, so "Continue to Review" never waits on a control you did not save. The catalogue lists only controls compatible with the template's module-set generation. What each control enforces is described on [Compliance modules](https://docs.settlemint.com/docs/concepts/compliance-and-identity/compliance-modules).

Two toggles on each control decide what happens at issuance:

- **Make configurable in Issue asset** is on once you save a control. While it is on, the control gets its own step under "Compliance details" in [Issue asset](https://docs.settlemint.com/docs/console/asset-management/issue-new-asset), pre-filled with your values, and the issuer can change them. When it is off, the control's row reads "Fixed for issuers", and "Issue asset" installs your values unchanged.
- **Required** marks a control that tokens using this template must configure.

Turn "Make configurable in Issue asset" off and turn **Required** on when a regulator owns the number. Both hold at issuance only. After issuance, the holder of the asset's Governance role manages its rules on the asset itself.

### Review and publish [#review-and-publish]

Note (Publish template on the Review step does not ask first): "Publish template" on this step publishes at once, with no confirmation dialog, and publishing cannot be undone. There is no unpublish. Select "Save as draft" to keep the template editable and out of instrument templates' choices.

The **Review** step summarises the name, status, description, jurisdictions, and the number of configured controls, then shows the readiness list. The list names each required control that is missing or incompatible, together with its fix.

"Publish template" stays unavailable until the list is empty, and the platform runs the same check again when you publish. Select "Save as draft" or "Publish template". A published policy stays selectable until you delete it. "Publish template" on the detail page asks for confirmation first. Both paths end on the template's detail page.

## Edit a published template [#edit-a-published-template]

A published organisation template stays editable in place. On its detail page, **Edit** in the header changes the name, the description, and the jurisdictions in one sheet. "Add control" under "Controls and rules" opens a searchable list of controls. The version rises by one on each save, and the platform refuses an edit that would leave a published template unable to pass the readiness check.

The "Used by" card lists each instrument template that links the policy, with its status: "Draft", "Unpublished" or "Published". Change a live asset's rules on that asset's compliance tab. You cannot edit or delete a DALP library template: duplicate it into an organisation draft when you need a variation.

![A policy template's detail page with the Basics, Scope, Used by and Controls and rules sections](https://docs.settlemint.com/docs/screenshots/console-policy-template-detail.light.en.webp)

[Screenshot] The template's detail page shows the "Basics", "Scope", "Used by" and "Controls and rules" sections.

The "Used by" section lists the instrument templates that link the policy, and the "Controls and rules" section lists the controls the template configures and requires.

## Delete a template [#delete-a-template]

Note (Link a replacement first): An instrument template that linked the deleted policy loses the link but keeps working, a published one included. The missing link does not block publishing or issuance, so the assets it issues next start without these rules. The "Used by" card on the detail page and the delete confirmation both list the instrument templates the delete unlinks.

1. Open the template's detail page and read the **Used by** card. It names each instrument template that links this
   policy and shows whether it is a draft, unpublished or published.
2. Link a replacement policy on every instrument template listed there.
3. Open the **Actions** menu and select "Delete". The "Delete template?" dialog names the template and lists the
   instrument templates the delete unlinks. When a published instrument template is among them, the dialog says so. The
   delete stays possible.
4. Select **Delete template**.

Deleting removes the policy and its compliance module configuration. Assets already issued keep their rules, and inherited global and identity controls still apply. A platform-managed template cannot be deleted.

## How a policy reaches an asset [#how-a-policy-reaches-an-asset]

[Figure] A policy is published, linked to an instrument template, then installed at issuance. Inside the policy templates catalogue a draft becomes a published policy, and publishing is permanent. An instrument template links one published policy. Issue asset reads the linked policy and installs its rules on the new asset, which keeps them. Editing the template after publishing raises its version and reaches assets issued afterward, never an asset that already exists. Labels: Draft; editable; Published; permanent; Every edit raises the version.; selectable once published; Instrument template; links one published policy; Issue asset; installs the rules; Issued asset; keeps the rules installed at issuance; Edit after publishing; reaches later issuance; never an asset already issued.

Rules travel one way: publishing makes a policy selectable, an instrument template links it, and issuance installs a copy on the asset.

## Library frameworks and the legacy generation [#library-frameworks-and-the-legacy-generation]

The library holds "Shari'ah / AAOIFI - Islamic Finance", a starting point for an Islamic finance token. It carries an identity verification control and a transfer approval control. It does not check Shari'ah or AAOIFI compliance, which stays with the issuer. The library ships the verification expression empty, which requires no claim, so a copy published unchanged admits any holder. It names the issuer as the only approval authority, and "Issue asset" replaces that placeholder with the on-chain identity of the person who issues the asset.

Set both in your copy: the claims a verified investor must hold, and the identities, such as the Shari'ah board, that approve a transfer. The framework lists no jurisdictions because Shari'ah compliance is an issuer governance framework, so the catalogue shows it as "Global". You can still scope your copy to jurisdictions. The "Sukuk Ijara" and "Sukuk Murabaha" instrument templates attach it.

On a deployment whose operator turns on legacy policy templates, which are off by default, the catalogue gains a "Module set version" column that identifies the generation, where 1 is the earlier, legacy generation. The catalogue then opens filtered to the current generation, and removing that filter lists legacy templates too. The "Blank" card also offers a "Legacy template" switch that picks the generation. That choice is fixed when the template is created, and instrument templates offer current-generation policies only, so take the legacy generation only for a product line that still needs it. [Compliance modules](https://docs.settlemint.com/docs/concepts/compliance-and-identity/compliance-modules) explains how the generations differ.

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

- Open the policy's detail page. Check that the status badge reads "Published" and that the jurisdictions, version, and configured controls match what your compliance owner reviewed.
- Then open an instrument template, go to its compliance step, and confirm the policy appears among the choices there. That step opens filtered when the instrument template sets a jurisdiction, so select the chip that reads **Applies to** and the country to turn the filter off when the policy covers a different jurisdiction.

## Troubleshooting [#troubleshooting]

**Publishing is unavailable**

The template has readiness gaps, or you lack the role. The "Review" step and the detail page list every gap: configure
the named required control on **Controls and rules**, or remove it from the required controls when it is incompatible
with the template's generation. When the list is empty and publishing is still refused, check that you hold the
Permission manager or Compliance manager role.

**A template refuses edits**

DALP library templates cannot be edited or deleted. Duplicate one into an organisation draft and adjust the copy. When
one of your organisation's templates refuses a change, check that you hold the Permission manager or Compliance
manager role.

**Creating or renaming fails on the name**

Template names are unique within an organisation, and the refusal says a template with this name already exists. Pick
a distinct name, or delete the earlier template when it is obsolete.

**A control is missing from the catalogue**

A control introduced for the current generation never appears in a legacy template, because the catalogue only offers
controls compatible with this template's generation. The generation cannot be changed after creation. Rebuild the rule
set as a current-generation template instead.

**The policy is missing from an instrument template's choices**

Only published, current-generation policies are offered when linking. Check the status badge on the policy's detail
page: a draft must be published first, and a legacy-generation policy never appears in the instrument template wizard.
The wizard's compliance step also opens filtered to the instrument template's jurisdiction. Select the chip that reads
**Applies to** and the country there to turn the filter off and list policies for every jurisdiction.

**An instrument template lost its policy**

Deleting a policy clears the link on every instrument template that used it rather than deleting those templates.
Before you delete, the **Used by** card on the policy's detail page lists them. Open each affected template and link a
replacement before the next issuance. Without a link, newly issued assets start without the deleted policy's rules.

## Frequently asked questions [#frequently-asked-questions]

### Can I unpublish a policy template?

No. Publishing a policy template is permanent. Only [instrument templates](https://docs.settlemint.com/docs/console/asset-design/instrument-templates) can be unpublished. To retire a rule set, follow [Delete a template](#delete-a-template). Deletion removes it from the choices without touching any asset already issued. An unlinked published policy enforces nothing on its own, but remains selectable for future instrument templates.

### How is a policy template different from global controls?

They differ in scope. A policy template's rules reach only assets built from instrument templates that link it. [Global controls](https://docs.settlemint.com/docs/console/compliance/global-controls) apply to bound tokens, including existing ones, within each rule's scope, and an issuer cannot remove them during asset creation. Together the two layers form the asset's compliance policy, the full rule set a transfer or subscription is checked against. A recipient on the compliance bypass list, a Custodian's forced transfer and a wallet recovery skip some or all of those checks, as [Compliance policy](https://docs.settlemint.com/docs/concepts/compliance-and-identity/compliance-policy) lists. Use global controls for a floor every asset must meet, and policy templates for the rules a specific product type or jurisdiction adds on top.

### Can another organisation see or use my policy templates?

No. The catalogue is scoped to your organisation: you see your own templates plus the platform's DALP library set, and other organisations see theirs. A DALP library template is shared platform-wide but read only. Copying it with **Start from DALP library** creates an organisation-owned draft that only your organisation can see, edit or publish.

### Is there an API for policy templates?

Yes. Every action on this screen is a call in the [Platform API](https://docs.settlemint.com/docs/api-reference/v2), under the same role rules. Reading one template also returns `usedBy`, the instrument templates that link it, each with its name and whether it is a draft or published. [API routes](#api-routes) shows create and publish.

## API routes [#api-routes]

Creating a draft and publishing it are separate calls. After creation, configure the draft's controls and review its readiness before publishing. Replace the example template identifier with the identifier returned by creation.

**API**

```bash
curl -X POST "https://your-instance.example.com/api/v2/settings/compliance-templates" \
  -H "X-Api-Key: sm_dalp_..." \
  -H "Content-Type: application/json" \
  -d '{"name": "EU transfer restrictions", "description": "Transfer restrictions for Northwind Coffee securities issued in the EU", "jurisdictions": ["EU"]}'

curl -X PUT "https://your-instance.example.com/api/v2/settings/compliance-templates/0193a1c2-7e4b-7a10-9c3d-5b2f8e6a1d40/publish" \
  -H "X-Api-Key: sm_dalp_..."
```

**CLI**

```bash
dalp create settings compliance-templates \
  --body '{"name": "EU transfer restrictions", "description": "Transfer restrictions for Northwind Coffee securities issued in the EU", "jurisdictions": ["EU"]}'

dalp replace settings compliance-templates publish 0193a1c2-7e4b-7a10-9c3d-5b2f8e6a1d40
```

Both calls need a credential that holds the Permission manager or Compliance manager role. Link the published policy from [Instrument templates](https://docs.settlemint.com/docs/console/asset-design/instrument-templates).


# Trusted issuers

Source: https://docs.settlemint.com/docs/console/compliance/trusted-issuers
Authorise identity issuers for specific verification topics.

A trusted issuer is an on-chain identity, such as a [compliance provider](https://docs.settlemint.com/docs/console/compliance/compliance-providers) or your own compliance team's identity, whose signed verifications your system accepts. On this screen a verification policy manager decides whose verifications count across the whole system, and for which verification topics. A token can add its own trusted issuers on top, as [Can an issuer be trusted for one asset only?](#can-an-issuer-be-trusted-for-one-asset-only) explains. An eligibility check confirms that a participant's identity carries the verifications a rule requires. Every check reads the trust you set here at the moment it runs.

Use this screen when you onboard a new source of verifications, when an issuer's scope of authority changes, or when your system must stop trusting one. Connecting a compliance provider registers the provider's identity here for you, so you do not add a provider by hand. This screen does not issue verifications to anyone: a participant gets verified on [Verify a participant](https://docs.settlemint.com/docs/console/participants/verify-a-participant), and the evidence categories themselves are defined on [Verification topics](https://docs.settlemint.com/docs/console/compliance/verification-topics), which must exist before you can assign them here.

![Trusted issuers registry](https://docs.settlemint.com/docs/screenshots/console-trusted-issuers.light.en.webp)

[Screenshot] The "This system" tab lists trusted issuer identities with their assigned verification topics and whether each entry is system-owned or inherited from the global directory.

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

- **A role that can open the page.** The sidebar shows "Trusted issuers" to the "Permission manager", "System manager", "Verification policy manager", "Feeds manager" and "Compliance manager" roles.
- **The Verification policy manager role.** Only this role can add, change or remove an issuer in the system registry. Everyone else sees the table under the line "Only a Verification policy manager can change the trusted issuers of this system.", with no add button and no row menus.
- **A second approver, when your organisation requires one.** When the "Compliance configuration" group is protected under [Approvals](https://docs.settlemint.com/docs/console/organisation-settings/general#approvals), each change on this screen waits on [Actions](https://docs.settlemint.com/docs/console/essentials/actions#decide-an-administrative-change) until another person approves it, and nothing changes until then.
- **A verification topic.** At least one must exist before you can add an issuer.
- **A registered identity.** The issuer's address must already be a registered identity in the system.
- **Your wallet verification.** Adding, editing and removing an issuer each confirm with it.

## Steps [#steps]

### Open Trusted issuers [#open-trusted-issuers]

Open "Compliance", then **Trusted issuers**. The "This system" tab is selected by default and lists each issuer with its "Issuer identity", "Assigned topics" and "Source".

The table names an issuer by the wallet of the participant behind it, calls your organisation's own identity "This system", and shows **No participant linked** when the identity has no linked wallet or no name the Console can show.

A row whose source reads "Global" is inherited from the directory and shows the text **Managed globally** instead of a menu. Only a directory administrator changes such an entry, and not from this screen.

### Decide which topics to grant [#decide-which-topics-to-grant]

Grant only the topics this issuer's own checks cover. A valid claim from the issuer then counts for those topics, and other required claims, expiry checks and asset rules can still block a movement. A topic you grant that the issuer does not verify widens its authority past its evidence.

A topic you leave out makes every check that requires it fail for this issuer's claims, which is right only when you limit the issuer on purpose, such as during a phased rollout. The same choice applies when you later change the issuer's topics on **Edit topics**.

### Add an issuer [#add-an-issuer]

1. Select **Add trusted issuer**.
2. In **Issuer identity address**, choose or paste the issuer's identity contract address, not its signing wallet. The field searches the participants and contacts you can see and takes a pasted `0x` address, as [Address fields](https://docs.settlemint.com/docs/concepts/operating/address-fields) describes.
3. Choose at least one topic under **Verification topics**.
4. Select **Add issuer** and confirm with your wallet verification.

An address without a registered identity is refused. The Console reports: "This address must be a registered identity before it can be added as a trusted issuer."

Entering an address that is already a trusted issuer turns the sheet into an update instead of a duplicate. Its current topics load into the picker, and the review step lists exactly what you are adding and removing. Drop a topic the issuer already holds and that same review step warns: "Removing a topic only removes the issuer association. Existing claims issued for that topic will not be revoked."

![Add trusted issuer sheet with the issuer identity address and verification topics](https://docs.settlemint.com/docs/screenshots/console-trusted-issuers-add-form.light.en.webp)

[Screenshot] The "Add trusted issuer" sheet with an "Issuer identity address" field and a "Verification topics" selection.

## Change an issuer's topics [#change-an-issuers-topics]

Open the menu at the end of the issuer's row and select **Edit topics**. The address cannot change. The selection must differ from the current set before "Review" activates. Removing a topic ends only the authorisation: claims already issued for that topic are not revoked, but from then on a claim this issuer signs for that topic no longer satisfies a check. On each participant's "Verifications" tab, those claims then show "Issuer not trusted for this topic" instead of "Active".

One row is your organisation's own identity. The system signs your exchange-rate feeds and your assets' base price claims with it, and it also writes each participant's "Residence" claim from the country on their approved KYC profile. So it must stay trusted for these topics:

- "Base price"
- "Price feed"
- "Document hash"
- "Instrument structure"
- "Residence"
- "Retail participant"
- "Institutional participant"
- "Proprietary participant"

The row for this identity is named "This system". The sheet shows these topics locked above the picker, in the order the row lists them, with "These topics are required by the system for this identity and can't be removed.", and you cannot remove them. Because the locked topics already count as a selection, the picker no longer asks for at least one more. If the identity does not hold one of them yet, the note says so and saving grants it. A change through the Platform API that leaves one of these topics out is refused with a conflict that names the missing topics.

## Remove an issuer [#remove-an-issuer]

Removing an issuer deletes its registry entry, with no paused state. From the next check on, its claims stop counting, and a participant whose only evidence came from it fails checks, often as a missing required claim rather than one naming the removed issuer. The participant's **Verifications** tab shows each such claim as "Issuer not trusted for this topic". Check the current trust registry when you investigate such a failure.

1. Open the issuer's row menu and select **Remove issuer**.
2. Confirm the dialog, then confirm with your wallet verification.

You cannot remove your organisation's own identity. Its **Remove issuer** item is unavailable and says the system requires this identity, and the Platform API refuses the removal with a conflict. Without that identity, your exchange-rate feeds would reject every update.

To restore trust after a removal, add the same identity address back with the topics it should hold. The claims it issued count towards verification again, because checks read the current registry rather than its history. Between removal and re-add, every check treats that issuer's claims as absent evidence.

## The three trust tiers [#the-three-trust-tiers]

A token resolves its trusted issuers across three tiers. The **This system** tab holds the issuers your own system trusts, and it is the only one you can change here. The "Global directory" tab lists the platform directory of issuers that every system inherits. Inherited entries also appear in your system table with the source "Global", and nothing on this screen edits them.

A trusted issuer in the global directory counts towards every check in your system, the same as one you added, and you cannot remove it here. A token with its own trusted issuer registry adds a third tier for that one asset.

## What a change records [#what-a-change-records]

Each of these changes is an operation the organisation's [Audit trail](https://docs.settlemint.com/docs/console/reporting/audit-trail) records, with your name and the role you held at the time.

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

- Look for "Trusted issuer added successfully" or "Trusted issuer topics updated successfully", then confirm the issuer's row appears in the **This system** tab with the source "System" and exactly the topic set you selected.
- If the toast reads "Still processing. Track progress in Actions.", follow the change in "Actions" instead of submitting it again. The table updates once the transaction confirms.
- To prove the trust chain end to end, issue a verification against one of the issuer's topics and run a transfer through the token's **Transfer pre-check** tab, as [Verify a participant](https://docs.settlemint.com/docs/console/participants/verify-a-participant) describes.

## Troubleshooting [#troubleshooting]

**The issuer address is rejected**

The address has no registered identity in the system. Register the participant and its identity first, on
[Users](https://docs.settlemint.com/docs/console/participants/users) or [Entities](https://docs.settlemint.com/docs/console/participants/entities), then add it here.

**No verification topics are selectable**

The picker stays disabled until you choose an issuer address, and it can only offer topics that exist. Select the
issuer first. If the list is empty, create the topic on [Verification
topics](https://docs.settlemint.com/docs/console/compliance/verification-topics) and return.

**A row shows Managed globally instead of a menu**

The entry is inherited from the global directory, and this screen cannot change directory entries. Ask a directory
administrator to adjust it. Your system-level rows stay editable.

**Review stays inactive on Edit topics**

The selected set matches the issuer's current topics, or is empty. Change the selection so it differs and keeps at
least one topic. To drop every topic, remove the issuer instead.

**The page shows no add button or row menus**

The line "Only a Verification policy manager can change the trusted issuers of this system." means your account lacks
the "Verification policy manager" role on this system. Ask someone with the Permission manager role to grant it, or
hand the change to someone who holds it.

## Frequently asked questions [#frequently-asked-questions]

### Can an issuer be trusted for one asset only?

Yes, when the token has its own trusted issuer registry, and not from this screen. A token without one uses the system and global issuers alone. The token's Governance role adds a token-level entry on that token's own trusted issuers screen, and that entry's claims count for that asset. Removing it leaves the inherited system and global trust intact. Use this screen when the issuer should count for the whole system.

### Why can I see the Global directory tab but not change it?

This screen never edits the directory. Unless you are a directory administrator, the tab shows the notice "You are viewing the global trusted issuers in read-only mode. Contact a directory administrator to make changes." instead of the table. A directory administrator can browse and search the directory per network, but the Console still offers no way to add, edit, or remove an entry there. A directory administrator changes the directory outside this screen, and every system inherits the result.

## API routes [#api-routes]

The trusted issuer endpoints in the [Platform API reference](https://docs.settlemint.com/docs/api-reference/v2) cover register, replace the topic set, add or remove one topic, and remove, for deployments that manage trust from code.


# Verification topics

Source: https://docs.settlemint.com/docs/console/compliance/verification-topics
Define the verification topics that classify identity evidence.

A verification topic names one category of identity evidence a participant can hold, such as a know-your-customer check or an accredited-investor status, and fixes the shape of the data a claim on it carries. On this screen you decide which categories exist for your system, which is your organisation's deployment on one network. The screen also shows the global categories every system inherits. The evidence itself lives on each participant's [on-chain identity](https://docs.settlemint.com/docs/concepts/compliance-and-identity/onchain-identity).

Come here first: [trusted issuers](https://docs.settlemint.com/docs/console/compliance/trusted-issuers), [compliance rules](https://docs.settlemint.com/docs/concepts/compliance-and-identity/compliance-policy) and [data feeds](https://docs.settlemint.com/docs/console/organisation-settings/data-feeds) all reference a topic by an identifier derived from its name. A topic must exist before any of them can use it, and its name can never change. Come back when a topic's data shape must change or a topic no longer applies. You do not need this screen to review one participant's evidence, which sits on the participant's own identity record.

![Verification topics registry](https://docs.settlemint.com/docs/screenshots/console-verification-topics.light.en.webp)

[Screenshot] The page separates system and global topic registries and lists each topic's name and identifier.

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

- **A role that can open the page.** The sidebar shows "Verification topics" to the Permission manager, System manager, Verification policy manager, Feeds manager and Compliance manager roles.
- **The Verification policy manager role.** Only this role can add, edit or delete a topic in the "This system" tab. Everyone else sees the table under the line "Only a Verification policy manager can change the verification topics of this system.", with no add button and no row menus. A Permission manager grants the role on [Roles and permissions](https://docs.settlemint.com/docs/console/organisation-settings/admins-and-roles).
- **A second approver, when your organisation requires one.** When the "Compliance configuration" group is protected under [Approvals](https://docs.settlemint.com/docs/console/organisation-settings/general#approvals), each topic change waits on [Actions](https://docs.settlemint.com/docs/console/essentials/actions#decide-an-administrative-change) until another person approves it, and nothing changes until then.
- **A directory administrator, for the global tab.** The "Global directory" tab shows the directory's topics to a directory administrator only, and it is read only on this screen for everyone.

## Steps [#steps]

### Open Verification topics [#open-verification-topics]

Open "Compliance", then **Verification topics**. The "This system" tab lists every topic your system resolves, with a "Source" column separating the topics it owns from the ones it inherits. The "Global directory" tab shows the directory those inherited entries come from.

### Add a topic [#add-a-topic]

Select **Add verification topic** in the "This system" tab, name the topic, and pick its kind. Two kinds can be created here.

![Add verification topic sheet with the topic name and kind](https://docs.settlemint.com/docs/screenshots/console-verification-topics-add-form.light.en.webp)

[Screenshot] The "Add verification topic" sheet, where you name the topic and pick its kind, "Verification (claim)" or "Feed (SCALAR)".

"Verification (claim)" is for identity evidence. Under "Verification fields", select **Add field** for each value a claim must carry. Give each field a "Data type": text, a number, a yes or no value, or a wallet address. A variable name is optional.

The registry stores this layout on chain but does not check issued claims against it, so a claim counts towards the topic whatever data it carries. The layout tells consumers how to read the data. Claim values are public on the network, so define no field that holds personal data. [Does a holder's personal data end up on a blockchain?](https://docs.settlemint.com/docs/concepts/compliance-and-identity/onchain-identity#does-a-holders-personal-data-end-up-on-a-blockchain) explains what reaches the ledger.

"Feed (SCALAR)" is for numeric data feeds and carries a fixed signature you cannot edit.

Set the topic's **Subject**, what the topic describes: "Person", "Asset", "Issuer" or "Any subject", the default. The subject groups topic choices in pickers and filters the table. "Add verification" on a user or entity offers only "Person" and "Any subject" topics, and on an asset it leaves out "Person" topics. The subject never stops a claim or a compliance rule from using the topic.

Choose a stable, descriptive name. The identifier every consumer stores is derived from it, and it cannot change later. Topic names are unique within a system, ignoring case and surrounding spaces. The **Topic name** field refuses a name an existing topic already uses, including the name a built-in topic is shown under, such as "KYC (Know Your Customer)", and "Review" stays unavailable until you choose another. The Platform API refuses a name that differs from an existing topic's name only by case or surrounding spaces. For feed topics the Console suggests a `FEED:` name prefix so they stay recognisable next to verification topics.

If two topics still show the same name, for example two added through the API before this check, the topic pickers and the "Delete topic" dialog add each topic's subject and source in brackets, such as "KYC (Know Your Customer) (Person · Global)".

Select "Review", then **Create topic**, and confirm with your wallet verification. The registration is an on-chain transaction.

### Decide who a rule may exclude with it [#decide-who-a-rule-may-exclude-with-it]

Set **Use in exclusions** while you add the topic. The setting controls whether a compliance rule may refuse the holders of this claim, such as a rule that blocks anyone holding a sanctions-hit claim. That only works while the holder cannot delete the claim: whoever can remove it from their own identity passes the rule meant to stop them. The platform stores the setting off-chain before it registers the topic, and does not create the topic when the setting cannot be stored.

| Setting | What it permits | Choose it when |
| --- | --- | --- |
| **Allowed** | A rule may exclude holders of this claim with no extra step. | The claim sits on an identity the holder does not manage. |
| **Allowed with acknowledgement** | A rule may exclude these holders, but whoever saves the rule accepts the risk by name. | A holder could remove the claim to pass a rule. |
| **Not allowed** | No rule saved through the Console or the Platform API may exclude these holders. | The holder is the party the control exists to stop. |

A topic you add starts at "Allowed with acknowledgement". The built-in know-your-customer, anti-money-laundering, know-your-transaction, Regulation S, sanctions screening and residence topics start at "Not allowed". The chain does not read this setting, so it does not stop a module write signed outside DALP. Under "Not allowed", use an identity block list, a country block list, or a positive claim the participant must hold instead.

The value you choose is saved with the topic in the same request, before the registration goes on chain, so the new row shows it as soon as the topic appears. If the value cannot be saved, the sheet reports the create as failed and nothing is registered.

Changing the setting later does not re-grade rules already saved. The new value applies from the next rule write. The change happens off chain, needs no transaction, and lands in the [Audit trail](https://docs.settlemint.com/docs/console/reporting/audit-trail) together with the value it replaced.

## Edit a topic's signature [#edit-a-topics-signature]

Open the topic's row menu and select **Edit**. The "Edit topic" sheet changes the data fields a claim must carry, the subject and "Use in exclusions" together, and "Update topic" asks for one wallet verification for all of them. The topic keeps its name and its identifier, so every consumer stays pointed at it. A signature that uses data types the sheet cannot build appears read only, with "This topic's signature uses data types that aren't editable here. Update it through the API." Use the [claim topic endpoints](https://docs.settlemint.com/docs/api-reference/v2) for those.

If the signature or subject change lands but the exclusion setting does not, the sheet reports that the topic was updated but its exclusion policy was not, and offers **Save exclusion policy** without a second PIN. If the signature or subject change is still processing, the sheet does not save "Use in exclusions" and tells you so. Set it again once the change completes.

## Delete a topic [#delete-a-topic]

Note (Deleting a topic in use fails every holder silently): A compliance rule that requires a deleted topic fails every holder the same way it fails someone who was never verified. The check reads the topic registry at the moment the operation executes, so the deletion also reaches operations submitted earlier but executed after it, and the failure carries no message naming the deleted topic.

1. Check the topic's consumers: its assignments under "Trusted issuers", "Compliance providers" and "Data feeds", plus any compliance rule that requires it on "Global controls", a policy template or a token's "Rules" table. The Console does not block deleting a topic that is still assigned, and the confirmation dialog does not list what is still attached, so you must check them yourself.
2. Open the row menu and select **Delete topic**. The dialog "Delete this verification topic?" warns that the deletion cannot be undone and that verifications using the topic may stop counting.
3. Confirm the dialog, then confirm with your wallet verification.

Only topics your system owns can be deleted here. A row whose "Source" reads "Global" shows **Managed globally** in place of the menu. Only a directory administrator can remove a global entry, and not from this screen.

Deletion does not touch the claims themselves. They stay on participant identities and stop counting while no topic resolves for their identifier. Because the identifier is derived from the name, adding a topic under the same name restores the identifier. Existing claims can count again when their issuer remains trusted and the claims remain valid. Review the restored data signature against existing claim data before relying on those claims. A topic added under a different name has a different identifier, and every issuer authorisation, provider mapping, and rule must be repointed to it by hand.

## What a change records [#what-a-change-records]

Creating, editing, or deleting a system topic is an operation the organisation's [Audit trail](https://docs.settlemint.com/docs/console/reporting/audit-trail) records, with your name and the role you held at the time.

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

- Confirm the toast that says the topic was created successfully, then find the new row in the **This system** tab with "Source" reading "System". Then open "Trusted issuers" and confirm the topic is selectable when you assign topics to an issuer: a topic no issuer can attest exists in the registry but can never be satisfied.

## Troubleshooting [#troubleshooting]

**The Global directory tab shows only a notice**

The tab shows the directory's topics to a directory administrator only. Everyone else sees **You are viewing the
global verification topics in read-only mode. Contact a directory administrator to make changes.** A directory
administrator sees the table, and the Console offers no add or remove controls for global entries to anyone.

**A topic's row has no actions menu**

Check the row's **Source** first: inherited topics show "Managed globally" and cannot be edited or deleted from the
"This system" tab. On a system-owned row, a missing menu means your account lacks the permission to update topics.

**A holder or operation starts failing compliance for no clear reason**

Check for a recent topic deletion before assuming the holder's own evidence is the problem.

**A deleted topic is still needed**

Add a topic with the same name, then confirm the issuer authorisations and rules that used it still stand before
relying on it again. The new topic takes the **Use in exclusions** value you choose while you add it, not the value
the deleted topic had.

**The exclusion policy does not save from an impersonated session**

The Console refuses this write from an impersonated session, because the audit record must name the person who
decided, not the operator standing in for them. This includes adding a topic with any value other than the default.
Ask the account holder to set **Use in exclusions** from their own session instead.

## Frequently asked questions [#frequently-asked-questions]

### What is the difference between a verification topic and a feed topic?

A verification topic classifies identity evidence, and a feed topic carries published numeric data. A verification topic is attested by a trusted issuer and required by a compliance rule, with data fields you define per topic. A feed topic has a fixed numeric signature you cannot edit, and data feed configurations consume it. The `FEED:` naming prefix the Console suggests exists so the two stay distinguishable in every list that mixes them.

### Can I rename a verification topic?

No. The topic identifier that every issuer authorisation, rule, and claim references is derived from the name, so a rename is impossible without abandoning the identifier. If the name is wrong, add a topic under the correct name, repoint each consumer to it, and delete the old one once nothing references it. Expect claims issued under the old topic to stay behind: they belong to the old identifier, and issuers must attest the new topic again.

### Why does a global topic show a Shadowed badge?

A registry below the global directory has registered the same topic identifier with a different signature. The systems that resolve the downstream entry decode claim data by the shadowing signature, not the directory's, so the same identifier can mean differently shaped data in different systems. Review the conflict before changing either entry. The badge marks the disagreement and changes neither entry.

### Why can I open this page but not add a topic?

Viewing and managing are gated separately. The sidebar shows the page to the Permission manager, System manager, Verification policy manager, Feeds manager and Compliance manager roles, because topics feed all of those surfaces. Creating, editing and deleting system topics needs the "Verification policy manager" role, and the Console hides those controls when your account lacks it, instead of letting a request fail.

### Do topics apply per token as well?

Yes. A token with an attached topic scheme registry can carry token-level topic schemes on top of the system and global topics it inherits, and those are managed from the token's own screens rather than here. Inherited entries stay read only at the token level, the same way global entries stay read only on this page. A token without an attached registry uses the inherited chain alone.

## API routes [#api-routes]

The claim topic endpoints in the [Platform API reference](https://docs.settlemint.com/docs/api-reference/v2) cover create, replace the signature, set the exclusion policy, and delete, for deployments that manage topics from code.


# Actions

Source: https://docs.settlemint.com/docs/console/essentials/actions
Use Actions to review scheduled, pending, and completed work for the active participant, and to run the one control each row offers.

Actions lists the scheduled, pending and completed operations of the active participant, meaning the person or organisation selected in **Working as**, and runs the one control each row offers. A row does not by itself mean you can act on it: whether the page offers a control depends on the row's type, whether it is still pending, and whether it names a usable target. Once an operation has finished, [Activity](https://docs.settlemint.com/docs/console/essentials/activity) holds its indexed on-chain record.

A pending row ends in the "Execute" column, and the row's type decides what that column shows. The **Pending** tab holds two tables while something waits on someone else. "Needs you" lists the rows whose next step is yours, and only it has the "Execute" column. "Waiting on others" lists the rows that wait on other people: it shows who each row waits on and when it is due, and it has no control except "Review" on an "Add-on approval" row. Once the signed weight meets the threshold, the approval returns to "Needs you" and reads "Executing" until it runs. When nothing waits on others, the tab shows one table.

![Actions page with Pending, Upcoming, and Completed tabs](https://docs.settlemint.com/docs/screenshots/console-actions-pending.light.en.webp)

[Screenshot] The "Pending" tab of "Actions" lists the pending actions of the active participant, one row for each action.

The tab bar holds "Pending", "Upcoming" and "Completed", each with a count badge. Above the table, the toolbar holds the "Search actions" field, filters, export and the column picker. Each row shows the action, its parties, when it is due, and an "Execute" cell with the control for that row. When rows wait on someone else, a "Waiting on others" table follows with its own count, and the first table takes the heading "Needs you" with the count the "Pending" tab shows.

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

- Sign in and select the intended participant with **Working as** in the account menu at the top right.
- Every row and every control this page offers scopes to that one participant.
- A Custody Approval is decided in your custody provider's own system, so this page shows the row but offers no control for it.
- Know which provider your organisation uses.

## Steps [#steps]

### Confirm Working as [#confirm-working-as]

Confirm the participant shown after **Working as** before you read or act on anything. When the top bar is narrow, the account menu button shows only an avatar, so open the menu to see the participant. In the account menu, "Working as" is a submenu. It shows only when you can work as at least two participants, and the top-bar button then shows your organisation's name over your own. While you work as someone else, the button reads "Working as" followed by that participant's name, takes a violet tint, and a "Working as" bar under the top bar offers "Return to yourself". To pick another participant, open the account menu, point at "Working as", and choose a participant, or select "View all participants" there to open [My participants](https://docs.settlemint.com/docs/console/my-account/acting-as-participants). Switching participant changes the whole queue.

### Choose the status tab [#choose-the-status-tab]

Open the tab that holds the work you want:

- **Pending** holds active work.
- **Upcoming** holds scheduled work that is not active.
- **Completed** holds history: executed operations and rows that expired before anyone acted on them. An expired row is not retryable from this page. Treat it as closed.

A **Cast vote** or poll ballot row shows under "Upcoming" before the vote opens and under "Pending" while you can act on it. If you held voting power and did not vote, it ends under "Completed" as expired. If none of your wallets held voting power at a vote's or poll's record date, the row appears on no tab once that date has passed, and the "Pending" count leaves it out. A vote or poll you already voted on stays under "Completed".

### Read what the row offers [#read-what-the-row-offers]

Before you look for a control, find the row in "Needs you" or "Waiting on others", then read its **Execute** cell against the [Execute table](#what-each-execute-cell-does). A row in "Waiting on others" has no control, except "Review" on an "Add-on approval" row. A row whose type this Console version does not recognise shows "Execute" greyed out and reading "Unavailable".

An **Add-on approval** row tells you that you or a colleague proposed a change to an add-on, such as a custody gateway, and that the change runs only after it has the approvals its rule needs. The row names the change in words, such as "Release a frozen withdrawal", or "Unrecognized call" when the Console cannot read it, and reads from the wallet that proposed it to the contract it changes. Its status reads "Waiting for your approval", "Can't be approved here" or "Ready to run" in "Needs you", and "Waiting for other approvers" in "Waiting on others", with how many of the required approvals the proposal has.

**Review** opens the add-on's "Approval request" sheet on this page. This sheet is separate from the "Approval request" row type, which holds an administrative change.

In the sheet an approver selects **Approve**, a holder of the requester's role selects "Run change" once the approvals are met, and the proposer or an approver selects "Cancel request". Each asks for your PIN. A call the Console cannot read has no "Approve" button.

You see one row for each proposal. If you proposed the call from one wallet and hold the approver role on another, the row reads "Waiting for other approvers", because nobody approves their own proposal. See [Add-ons and add-on approvals](https://docs.settlemint.com/docs/console/asset-lifecycle/custody-gateway-approvals#review-and-approve) for the whole flow and its errors.

A held price row tells you that a price from a price source moved past its tolerance, or corrects a price already published, and that it waits for a second person. The row's type reads "Review held price", and its name reads `<ISIN> from <source>`, or `Correction to <ISIN> from <source>` when the price corrects one already published. Only a feeds manager or the governor of the token sees it, and never a person who set up the source or requested its delivery. **Review held price** opens the "Held prices" tab of that source with the price open in a review sheet. You approve or reject it there, with your PIN, and the row leaves "Pending". See [Price sources](https://docs.settlemint.com/docs/console/organisation-settings/price-sources).

A **Checker approval** row is a transaction from a wallet that names you as its checker, and it waits for your decision. Its name is the operation, or for a multisig co-signature, `Co-signature by <signer> on <wallet>, requested by <maker>`, and its "Parties" read from the signing key to the multisig wallet. "Approve" lets the transaction run, and "Reject" fails it. Only the named checker sees the row, and it leaves "Pending" once you decide or the approval window closes. A transaction you started from a wallet you check never reaches you: it fails at once, because another person must start it. If the named checker leaves the organisation, a transaction waiting for them fails and does not run.

A named button on a recognised row usually opens a sheet right here. Besides the link rows in the [Execute table](#what-each-execute-cell-does), five types leave the page instead:

- A **Multisig signer invite** row, whose button reads "Accept invite", normally goes to a dedicated accept screen. It is a different multisig row from a multisig approval: an invitation to join a wallet as a new signer rather than a request to co-sign an existing one.
- **Cast vote** normally goes to that token's own governance page, and opens a sheet here only when this Console cannot resolve that page for the token involved.
- **Activate voting power** also normally goes to that token's own governance page, and opens a sheet here only when this Console cannot resolve that page for the token involved.
- **Claim parked amount** goes to the settlement it belongs to.
- An **Approval request** for a corporate action goes to that action on its token page.

On a narrow screen the row keeps what tells it apart and folds it under the action's name instead of dropping it:

- On **Completed**, the "Completed", "Executed by" and "Outcome" columns fold there.
- On **Upcoming**, "Opens" folds there.
- On **Pending**, "Due" folds there.

A button that acts on the row names what it does: "Approve", "Execute", "Claim", "Update", or a short verb of its own, with the action and its subject as its accessible name.

### Act only where a control exists [#act-only-where-a-control-exists]

Follow the control offered by the row:

- For a recognised row that submits in place, select the named button and confirm the sheet.
- For a **Multisig signer invite**, "Cast vote" or "Activate voting power" row, select the button and follow wherever it opens: the accept screen for a signer invite, where you choose which of your keys signs for the new wallet, or the token's own governance page for a vote.
- For a multisig approval, the row shows the collected weight against the threshold, such as `1 / 2 weight`, and the time left before the approval expires. Co-signing a Smart Wallet multisig starts from the row: select "Sign", check "Counted weight" against the threshold and the "Deadline" in the "Co-sign approval" sheet, select **Co-sign**, and confirm with your wallet verification. The sheet calls each of your own keys "You", in "Started by" and in the signer list alike. While you work as the multisig wallet, an approval that waits on your own seat shows here too, and the sheet offers that seat as "You". Once the signatures reach the threshold, the row stays in "Waiting on others" and says the signature threshold is reached and the platform submits the transaction to the chain next. When your signing wallet pays its own gas and holds none, "Co-sign" stays disabled with the reason "Top up gas to co-sign."
- For a checker approval, select **Approve** or "Reject" in the row.
- For an **Approval request** row on a corporate action, the button reads "Review" when you decide it and "Open request" when you proposed it, and it opens that action on its token page, where you approve or reject it.
- An administrative change you may decide has no such button: follow [Decide an administrative change](#decide-an-administrative-change). The row stays in **Pending** until someone decides it, the request expires, or the plan is previewed again.
- For a custody approval, wait for your custody provider to act on it.

Before confirming, check the participant and operation. An active button means the Console can open the operation. The platform still checks permission when you submit it.

## Decide an administrative change [#decide-an-administrative-change]

An organisation turns on maker-checker approval for administrative changes by protecting the groups of changes it wants held, under Administration in the [Approvals section of General](https://docs.settlemint.com/docs/console/organisation-settings/general#approvals). An organisation with no group protected runs these changes directly. The groups are Role management, Compliance configuration, Approval policy, Freezing, Pausing, Forced transfers, Recovery, Token administration, System administration, Custody administration, Venue administration and Platform settings. Once a group is protected, each v2 write in that group waits as a pending approval until a second person decides it. This holds for a write from a session and for a write from an API key. A change to the protection list is held as well. The frozen v1 API cannot hold a request, so it refuses a v1 write in a protected group and names the v2 route that holds it. Platform-wide administrator routes and decisions on other approvals are never held. The bank rail credit, recall, reserve adjustment and cash-out operations sit outside these groups, because each goes through the bank rail's own approval request.

The person who submitted the change, the maker, cannot approve it. Another organisation owner or platform administrator decides it from their own session. When the approval policy names approver roles for administrative changes, only a member who holds one of them approves or rejects, and an owner or platform administrator who holds none of them is refused. A change to the approval policy itself is still decided by an owner or a platform administrator. An impersonated session, in which a platform administrator acts as another user, cannot decide it. Open the row details to read what the change targets and sets, with secret values hidden, and the digest, a fingerprint of the full request. **Approve** from the details: the approval carries that digest, and the platform refuses it if the held change differs. The row itself offers "Reject", which needs a reason that stays visible in the row details. Approval runs the stored change once, with the standing the submitter holds at that moment. If the submitter was removed, banned, demoted below the needed role, or lost the API key, the platform refuses the approval with `APPROVAL_REFUSED` and runs nothing. Expiry closes the request without changing state.

For a pending administrative approval, open the row's details first. They show four things:

- The method and path the maker called, as the **Operation**.
- The record it targets, as the **Target**.
- The values it sets, under **Changes**, with secret values replaced by `[REDACTED]`.
- The **Digest** of the full request.

Those secret values are stored encrypted until the approved change runs, so a pending approval never holds a password or credential as plain text. Request headers are never shown. A change to the approval policy reads as one row per family, exception or protection list, from the setting as it stands now to the setting the change asks for, for example `Second person required → Not required`, `Approvals required: 1 → 2` or `Freezing → None`. The setting before the change is read when you open the page, so a rule another change moved since the request was made shows its current value. The row itself reads "Open the details to review the change before approving." and offers only **Reject**, under a text box that reads "Explain why this change should not be applied". "Reject" works only once the box holds text.

Your **Approve** or "Reject" is recorded at once, and you cannot withdraw it. A rejection closes the request. An approval runs the change once the last required approval is in, unless the platform refuses it, as [Troubleshooting](#troubleshooting) describes.

Select **Approve** in the details only when the current state still supports the original request. The details sheet closes once your decision is recorded.

Select **Reject** when the change should not proceed. A rejection leaves the underlying asset or organisation unchanged.

When the organisation asks for more than one approval for the change's family, the row shows the progress under the change name, for example `1 of 2`, and the detail sheet repeats it under **Approvals**. The change goes ahead only after that many different owners or platform administrators have approved, and the maker never counts. A platform administrator counts through the platform role on their account, whatever their role in the organisation. Each person approves once. After you approve, the row moves to "Waiting on others" and reads "You approved this. Waiting for other approvers." in place of "Approve" and "Reject", and its detail sheet shows the same line. It no longer counts toward "Pending". A second "Approve" or "Reject" from you, for example from another open tab, is refused and changes nothing. See [General](https://docs.settlemint.com/docs/console/organisation-settings/general#approvals).

## Review an assistant finding [#review-an-assistant-finding]

**Assistant finding** rows come from a watcher that an organisation owner or a platform administrator switched on in the assistant settings, or from an AI app. A watcher's row shows only while the assistant and that watcher are on. The row names what the watcher found, such as "Payout not funded", "Filing not submitted", "Verifications expiring" or "Unmatched bank credit". Only organisation owners and the members whose system role owns that work see a watcher's finding: asset managers for payouts, auditors for filings, compliance managers and identity managers for verifications, and bank rail managers for credits.

**Review** opens a sheet with the brief: what the watcher found, each check it ran with its verdict, and the figures behind each check. The watcher builds the brief from DALP data in fixed wording. Below the two act levels, it signs and submits nothing.

What the sheet offers depends on the finding:

- **Open draft** opens the asset page with the prepared control and its values filled in, such as "Fund schedule" for a bond coupon. You check the values and confirm with your wallet verification, as for any other change.
- **Record choice** records the option you pick for an unmatched bank credit. It moves no funds. You then do the step in the bank rail. The watcher does not post that credit again until its condition clears.
- **Save answer** gives the one date the watcher could not read, such as the date the treasury is funded. The date must be after the current date and within 366 days. The watcher holds the finding back until that date.
- **Snooze** hides the finding for one day, three days or one week.
- **Dismiss** closes the finding with a reason and an optional note. The watcher does not post the same finding again until its condition clears.

The **Payout funding** watcher can also run the treasury transfer itself, under the organisation's agent principal: an agent identity of the organisation, whose key the platform holds, acting within a mandate. Only the organisation owner raises a watcher to "Act with veto window" or "Act", and only while the organisation has an active agent principal and its kill switch is off.

At "Act with veto window", the sheet of the finding also shows **Scheduled transfer**. It says when the agent principal runs the transfer, four hours after the finding is posted, and that it does so unless a member vetoes it first. At "Act", the agent principal runs the transfer within its mandate with no veto window.

**Veto transfer** stops the transfer, a toast reads "Vetoed. The transfer will not run." and the watcher does not post the finding again until its condition clears.

Once the agent principal has acted, the same place shows the outcome instead:

- **Done by an agent** reads "Done by `<agent>`" with the transaction, or "Queued" or "On chain" before a hash is known, and says "This transfer cannot be undone."
- **Not run** gives the reason the transfer did not run, such as "The mandate has expired." or "The organisation's kill switch is on.", and says "Nothing was transferred. You can still open the prepared draft."

[Assistant](https://docs.settlemint.com/docs/console/organisation-settings/assistant#set-a-watchers-level) explains the watcher levels.

A finding also closes without you when a later run of its watcher no longer finds the condition, for example once the payout is funded or the filing is submitted.

The "Assistant finding" type also carries two other rows:

- **Request from an app** is a change that an AI app prepared for you through the hosted MCP server, and only the member whose app prepared it sees it. "Review" opens its sheet, and "Open draft" opens the control with the values filled in. Opening the draft closes the request as accepted, whether or not you then sign. A request from an app shows only while the assistant is on.
- **Watcher run failed** appears when a watcher run fails, for example because a read did not answer or the organisation has no active system on its default network. It names the failure and says when the watcher runs again, and the next successful run closes it.

## Read the columns and tabs [#read-the-columns-and-tabs]

This page organises work into three tabs, each with its own sort order:

- **Pending** holds active work, soonest first.
- **Upcoming** holds scheduled work, also soonest first.
- **Completed** folds in both finished and expired rows, sorted most recent first.

Each tab's label carries a live count next to it, and the page's URL reflects the tab you are on, so a link to a specific tab reopens on that tab directly. The count on "Pending" and the **Actions** badge in the sidebar include only the rows in "Needs you", never the rows in "Waiting on others". While both tables show, each heading carries its own count, so "Needs you" repeats the number on the tab and "Waiting on others" holds the rest. Pointing at the "Pending" count shows what it counts, for example "3 actions waiting for you", and a screen reader reads the tab the same way.

The list itself updates live as events arrive. If the live connection drops, the page reconnects on its own. If reconnecting fails, the page says "Live updates stopped" above the list and offers **Reconnect**, which opens the connection again. An expired session asks you to sign in again.

Each tab shows its own columns by default:

- **Pending** shows "Action", "Parties", "Due" and "Execute".
- **Upcoming** shows "Action", "Parties" and "Opens".
- **Completed** shows "Action", "Outcome", "Decision", "Decided by", "Decided at", "Completed" and "Executed by".

**Decision** reads "Approved" or "Rejected" for an approval someone decided, "No second approval (approval off)" for a change that went ahead without a second approval, and a dash otherwise. Every row also has a "View details" menu.

Some columns start hidden, and the column picker shows them:

- **Type** starts hidden on every tab.
- **Status** starts hidden on "Pending" and "Upcoming".
- **Waiting since** starts hidden on "Pending".
- **Expires** starts hidden on "Completed".

The expiry column always shows on "Pending", where it is "Due". On "Upcoming" and "Completed" it reads "Expires" and appears only when a row has an expiry. "Amount" appears only when a row carries an amount. A narrow table also hides its lower-priority columns, and the **View** button counts them.

A row waiting on a custody approval sits in "Waiting on others". Its type reads **Custody approval**, its name is the operation, and its "Waiting on" column names the custody provider with "Signing the transaction with your custody provider" instead of a control. The "Waiting on" column, and the line that says why a row cannot run yet, read in the language you chose for the Console.

Search matches the action's stored name, its type key, such as `ClaimYield`, or its target address, not the translated labels on screen, and the **Type** filter counts the rows of each type on the tab. The counts stay the same when you pick a type, so you can see how many rows each other type holds before you switch.

**Export** downloads the current list through "Export as CSV" or "Export as JSON".

On "Pending" you can tick several rows and approve or reject them together when every ticked row is a **Checker approval**. Otherwise the page reads "Only pending checker approvals can be decided together. Deselect the other actions." Each tab keeps its own saved views, so a view saved on "Completed" does not show on "Pending". [Tables](https://docs.settlemint.com/docs/concepts/operating/table-views) explains selection and saved views. Rows that arrive while you read wait behind a "2 new" pill instead of moving the list.

## What each Execute cell does [#what-each-execute-cell-does]

[Figure] The Execute column of a pending row shows a button, a decision, or no working button. Rows in the Needs you table end in the Execute column, and the row's type decides what it shows. A button named for the action, such as Claim yield or Relay permit, opens a sheet on this page or takes you to the screen that runs the operation, and it is greyed out with a reason when the Console cannot run the row. A decision in the row, such as Approve and Reject on a checker approval or Sign on a multisig approval, records or collects your decision without leaving the page. An add-on approval shows its status and a Review button that opens the proposal on this page. Some rows show no working button: a link to the screen that decides the row, or a greyed Unavailable for a type this Console version does not run. Rows that wait on other people sit in the separate Waiting on others table, which has no controls except Review on an add-on approval. Labels: The Execute column depends on the row.; Pending tab, needs you; Rows that wait on others have no controls.; Named for the action.; A named button; Claim yield, Relay permit.; Greyed out with a reason.; Approve, Reject, Sign.; A decision in the row; Checker and multisig approvals.; Sign opens a co-sign sheet.; Link or Unavailable.; No working button; Review filing.; Custody waits under; Waiting on others.

The "Execute" column of a pending row shows a named button, a decision in the row or no working button, and rows waiting on others have no controls.

What a row's **Execute** cell shows depends on its type:

| The cell shows | Row types | What it does |
| --- | --- | --- |
| A button named for the action | `Claim yield`, `Claim dividend`, `Relay permit`, `Redeem bond`, `Mature bond`, `Update KYC information`, `Approve settlement`, `Execute settlement`, `Cast vote`, `Accept invite` on a `Multisig signer invite` row, `Review request`, `Open request`, and similar | Opens a sheet on this page, or takes you to the screen that runs the operation. The button is greyed out, with the reason, when the Console cannot run the row. |
| `Approve` and `Reject` | A checker approval, and a reconciliation break resolution that you review | Records your decision in the row, with no sheet. These two buttons need no wallet verification. |
| `Reject` and a reason box | An administrative change that you may decide | The row reads "Open the details to review the change before approving." `Approve` is only in the row's details. See [Decide an administrative change](#decide-an-administrative-change). |
| `Sign` or `View` | A multisig approval | Opens the co-sign sheet on this page. `Sign` shows while you may still sign. `View` opens the same sheet read-only. |
| A link | `Review on the venue page` on a venue approval, `Review filing` on a filing approval, `Review destination` on a withdrawal destination review, `Open invitations` on an invitation role authorisation, `Review held price` on a held price | Opens the screen that decides the row. The decision is not made on this page. |
| `Review` | An `Allocation run` or an offering approval, such as `Create offering`, that you may decide | Opens a review sheet on this page with the terms the approval binds, then `Approve` and `Reject`. Only an approver sees `Review`, never the person who requested it. |
| `Review` | An `Assistant finding` | Opens the finding's sheet on this page. The sheet records your choice on the finding and signs nothing. |
| Status text and `Review` | An `Add-on approval`: `Waiting for your approval`, `Can't be approved here` or `Ready to run`, with how many of the required approvals the proposal has | Opens the `Approval request` sheet on this page, where you approve, run or cancel the proposal with your PIN. |
| A greyed `Unavailable` | A row type this Console version does not run | Nothing to press. |

The control describes the row. It does not change with your role on the asset, and an active button is not confirmation that you are permitted to run the operation. Authorisation is decided only after you confirm, by the platform and the contract behind the operation. Selecting a button and confirming it submits the operation immediately for a row whose sheet opens here. You cannot undo it from this page. The [Submissions](https://docs.settlemint.com/docs/console/essentials/submissions) tray offers **Undo** or "Cancel" while that is still possible.

## How a row waits on others [#how-a-row-waits-on-others]

A Custody Approval always waits in **Waiting on others**, because your custody provider, the service that holds your signing keys, signs outside the Console. A multisig approval waits there when you have no signature to give, for example after you signed and other signers still need to sign, or when your co-signature waits for your checker to approve it. An add-on proposal waits there when other approvers must approve it first.

An administrative change you requested does not appear on this page while it waits. Once it is decided, it shows under **Completed** with its decision. The exception is an approved corporate action that you still have to run: it stays in "Needs you" with an "Open request" button. A Smart Wallet multisig co-signature request that still needs your signature stays in "Needs you", with a "Sign" button that opens the co-sign sheet on this page.

## Relay permit rows [#relay-permit-rows]

A `Relay permit` row is a signed permit that waits to be put on the chain. A permit is a message that a token holder signs to let another address, the spender, move up to a set amount of the holder's tokens until a deadline, without the holder sending a transaction. The holder signs it on the Permit tab of the asset's page, and the row then appears for each wallet that has the [custodian role](https://docs.settlemint.com/docs/console/organisation-settings/roles-and-segregation-of-duties) on that asset.

The **Relay permit** button opens a sheet that names the asset, the holder, and the spender. The sheet does not show the amount or the deadline, so check both in the signed permits list on the same Permit tab before you confirm. Confirm with your transaction PIN or transaction code, the second check you set up for actions that sign on your behalf. You set it up under [Security](https://docs.settlemint.com/docs/console/my-account/security). The platform then sets the spender's allowance on the holder's tokens to the amount the holder signed, and it replaces any allowance that the spender already had from that holder. An allowance is the amount a spender may move. Once the relay is confirmed the spender can move up to that amount, and the relay itself moves no tokens. To take an allowance back, the holder signs a permit for 0, and a custodian relays it like any other. The holder sends nothing.

Each permit has a nonce, a counter that the token's permit feature keeps for each holder and raises by one whenever one of that holder's permits is used. A permit works only when its nonce equals the holder's counter, so a holder's permits relay in the order they were signed, and a signed permit becomes a row only after the one before it is used. For example, a holder whose counter reads 3 signs two permits, for 500 and for 200 units. The permit for 500 has nonce 3 and becomes a row at once. The permit for 200 has nonce 4 and becomes a row after a custodian relays the first. The row moves to **Completed** for every custodian wallet as soon as one custodian relays the permit. Unlike other expired rows, a permit that nobody relays before its deadline disappears from every tab, including "Completed", and the holder signs a new one.

## When no network serves the scope [#when-no-network-serves-the-scope]

The page header names the network you picked in the "Network" submenu of the account menu at the top right. When the network scope you picked has no active network, the page shows no tabs or tables. If the organisation has no active network at all, it reads "No network is active". An organisation owner or platform administrator also reads "Add a network, or retry one that failed to deploy, on Networks in Organisation settings." with an **Open Networks** button that opens [Networks](https://docs.settlemint.com/docs/console/organisation-settings/networks). Anyone else reads "Ask an organisation owner to add a network."

If other networks are active, the page reads "No network serves this scope" and "Pick a network under Network in the user menu." with a **Pick network** button, which opens the account menu on its "Network" submenu. The account menu shows that submenu only when multi-network support is on and more than one network is active. Without it, ask an organisation owner to add a network for this scope on [Networks](https://docs.settlemint.com/docs/console/organisation-settings/networks).

## Where else waiting work shows [#where-else-waiting-work-shows]

The **Actions** entry in the sidebar and the "Submissions" button in the top bar both show the "Pending" count, which counts the rows in "Needs you" and never the rows that wait on others. A screen reader reads the number as, for example, "3 actions waiting for you". With work waiting, a link above the tabs of the Submissions sheet reads the same and offers "Open actions", which opens this page on "Pending". [Submissions](https://docs.settlemint.com/docs/console/essentials/submissions) describes the tray.

An asset's Overview carries a **Needs you** card with the pending rows for that asset that you can run now, with the same control each row has here. The card shows at most six rows. With more than six, or with rows the card does not list, a link such as "View all 8" opens the asset's own pending queue. Rows that wait on someone else sit under "Waiting on others" on the card, closed until you open it. "Upcoming" and "Completed" links open the same tables this page uses, filtered to the asset, with "Back to Overview". With nothing waiting on you, no assistant finding and no failed read, the card is not shown.

## Read Outcome, Decision and Due [#read-outcome-decision-and-due]

On "Completed", **Outcome** is the row's final state. "Completed" means the operation ran. "Expired" means nobody acted before the row ended, and an expired row cannot be run from this page. An approval request that someone rejected reads "Not applied", because the change it asked for never ran.

**Decision** answers a different question: how a second person decided an approval. It reads "Approved, confirm next" when the approval is recorded and the operation still has to be run, "Approved", "Rejected", "Expired" when nobody decided before the approval lapsed, "Rejected, release custody next", "Expired, release custody next" or "Cancelled, release custody next", "Cancelled" when the maker cancelled a corporate action before anyone decided, or "No second approval (approval off)" when the organisation's policy let the change go ahead alone. It stays a dash for rows that needed no approval. "Rejected, release custody next", "Expired, release custody next" and "Cancelled, release custody next" mark a rejected, lapsed or cancelled corporate action whose custodian contracts still carry its freeze. Its maker and everyone with the token's supply management role see "Release frozen custody" on the row, and nobody else sees it as pending.

On "Pending", **Due** shows the time left before the row ends, such as "in 3 hours" or "tomorrow", and "Overdue" once that time has passed. On "Upcoming" and "Completed", the same value sits in the "Expires" column. The Console shows the time and does not lock the row: a button stays active after the time passes until the platform records the row as expired and moves it to "Completed". Run a row before its "Due" time, and treat "Overdue" as a row that may already be closed.

## Roles and effects by row type [#roles-and-effects-by-row-type]

Each row type is run by the person its own feature names, and the effect on holders is described on that feature's page. This table gives the role and the effect for the types a reader asks about most. Use the linked page for the full rules.

| Row type | Who runs it | What it does | Where it is explained |
| --- | --- | --- | --- |
| **Claim yield** | A holder, with no admin role | Pays the holder the yield that has accrued, once the treasury is funded and has approved the feature to spend. | [Yield and maturity](https://docs.settlemint.com/docs/console/asset-management/manage/yield-maturity) |
| **Mature bond** | The governance role on the asset, or the emergency role for early maturity | Marks the bond as matured so holders can redeem. Maturity cannot be undone. | [Yield and maturity](https://docs.settlemint.com/docs/console/asset-management/manage/yield-maturity) |
| **Redeem bond** | A holder with a positive available balance, with no admin role | Redeems the holder's matured position. | [Yield and maturity](https://docs.settlemint.com/docs/console/asset-management/manage/yield-maturity) |
| **Claim dividend** | A holder who was entitled on the record date | Pays the holder the declared dividend once the issuer has funded it. | [Cash dividend](https://docs.settlemint.com/docs/console/asset-management/manage/cash-dividend) |
| **Approve settlement** | A local sender named in one of the settlement's flows | Locks the sender's asset in the settlement contract. | [Settlements](https://docs.settlemint.com/docs/console/my-assets/settlements) |
| **Execute settlement** | Whoever the settlement page offers the button to, once every flow is approved | Runs the settlement as one transaction: every local leg pays out, or none does. | [Settlements](https://docs.settlemint.com/docs/console/my-assets/settlements) |
| **Claim parked amount** | The wallet that the refund or delivery is parked for | Sends the parked amount to an address the holder chooses. | [Settlements](https://docs.settlemint.com/docs/console/my-assets/settlements) |
| **Cast vote** | A holder with voting power at the record date | Records the holder's vote on the token's own governance page. | [Votes](https://docs.settlemint.com/docs/console/my-assets/votes) |
| **Relay permit** | A wallet with the custodian role on the asset | Sets the spender's allowance to the amount the holder signed. The relay itself moves no tokens. | [Relay permit rows](#relay-permit-rows) |
| **Checker approval** | The wallet's named checker, never the person who started the transaction | **Approve** lets the transaction run, and **Reject** fails it. | [Maker-checker](https://docs.settlemint.com/docs/concepts/custody-and-signing/maker-checker) |

The role column describes who can complete the operation. [What each Execute cell does](#what-each-execute-cell-does) explains when a button is active.

## How each kind of action ends [#how-each-kind-of-action-ends]

For a direct execution, confirm the row now appears under **Completed** with its "Completed" and "Executed by" columns filled. That is the only confirmation this page gives, and it can take a moment to move tabs.

For a custody approval, watch the toast instead of this page. While the provider decides, a toast reads **Awaiting custody approval**, with an "Open actions" button that opens this page, and it stays until no custody approval is pending.

When the provider decides, the toast says how the request ended:

- **Custody approval completed** on success.
- A named ending when the request ends without a signature, such as **Rejected by an approver**, "Blocked by an approval policy", "The approval window closed" or "The gas sponsorship expired". The toast also says that nothing was sent.
- **The custody provider reported an error** when it is not known whether the request took effect. Check it in the provider's approval console before you try again.
- **Custody approval failed** for any other failure.

For a **Multisig signer invite**, the accept screen itself confirms the outcome: it tells you the join succeeded. The wallet's creator still has to finalise the draft before the wallet is active, so there is nothing further to check on this page for that row. For a multisig approval, the status line above the button and the co-sign sheet show the signed weight against the threshold. The sheet re-reads signed weight each time it opens, so trust it over anything remembered from this page.

For an administrative approval, the row moves to **Completed** after approval or rejection, with "Decision", "Decided by" and "Decided at" filled in. An approved change runs through the original operation, and its [Audit trail](https://docs.settlemint.com/docs/console/reporting/audit-trail) record links the maker, checker and transaction. A rejected or expired request has no on-chain change. An expired request leaves the page without a row. Open a rejected row's details to read the rejection reason.

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

- A direct execution appears under **Completed** with its "Completed" and "Executed by" columns filled.
- A custody approval ends in a toast: **Custody approval completed** on success, or a named ending that says nothing was sent.
- A multisig approval shows the signed weight against the threshold in the status line and the co-sign sheet.
- An administrative approval moves to **Completed** with "Decision", "Decided by" and "Decided at" filled in.

## Troubleshooting [#troubleshooting]

**A button is greyed out**

Signal: a named button appears greyed out on a row you expected to run. Cause: this page enables the button only under
four conditions together: the row's type is recognised, its status is **Pending**, it names the record it applies to,
and, for a dividend, the issuer has funded it. Your role is not one of the conditions, so a greyed-out button never
means a missing permission, and an active button can still be refused after you confirm. Fix: read the reason the
button gives. "This version cannot run this type of action." and "Only a pending action can be executed." have no fix
on this page. A row that reads "This action does not name the record it applies to, so it cannot open." lacks data
that this page cannot supply. "Cast vote" needs the governor and the proposal, "Cast poll ballot" needs the poll,
"Claim dividend" needs the token, the dividend and the feature it claims from, "Claim yield" needs the token and the
feature or schedule it claims from, and "Relay permit" needs the stored permit with its token, owner and spender.
"Awaiting funding: the issuer has not funded this dividend yet." clears once the issuer funds the dividend.

**A custody approval has no Approve or Deny button**

Signal: a **Custody approval** row shows no button anywhere, and it sits in "Waiting on others". Cause: the decision
happens in your custody provider's own system, outside the Console, so the row has no control here. Fix: ask an
approver to approve or reject the transaction in your custody provider. The row leaves "Waiting on others" once the
provider decides. A toast tells you how it ended: "Custody approval completed", a named ending such as "Rejected by an
approver", or "Custody approval failed".

**A multisig approval has no Sign button**

Signal: a multisig approval row shows no **Sign** button, or a button that reads "View". Cause: "Sign" shows only in
"Needs you", while you are a signer who has not signed yet and the threshold is not met. After you sign, the row moves
to "Waiting on others", which has no button, while other signers still need to sign. Once the threshold is met, it
returns to "Needs you". In "Needs you", once the approval is executing, executed, expired, cancelled, or failed, the
button reads "View" and opens the same co-sign sheet read-only, with a line above it that gives the state, for example
"Executing", "Executed", "Expired", "Cancelled", or "Failed". Fix: open "View" to read the signed weight against the
threshold. If you already signed, wait for the other signers. If a row reads "Waiting for your checker to approve your
co-signature", your checker has to approve before your signature counts.

**Accept invite does nothing, or opens a screen that does not let you join**

Signal: selecting **Accept invite** on a "Multisig signer invite" row either does nothing at all, or opens the accept
screen without letting you join. Cause: a silent click means the row's stored invite link no longer matches a shape
this Console can open. Nothing on screen reports that failure. Once the accept screen does open, several states can
block you there instead. "Your wallet already signs here" means every wallet you can sign with already holds a seat on
this multisig or is waiting to join it. "No wallet to sign with" means none of your accounts can sign for this
multisig yet. "Address already in use" means one of your keys took a seat on that draft after the page loaded, for
example from another tab. "Key already a signer" means the key you picked already signs for the wallet. Any other
terminal screen, "Invitation expired", "Invitation revoked", "Already accepted", "Invitation void" or "Invitation not
found", means the invitation can no longer be used. The row leaves "Pending" once the invitation is accepted, revoked
or expired, or once the draft is no longer open. Fix: for a silent click, reload the page and select "Accept invite"
again. For "No wallet to sign with", select "Add a wallet", create your wallet, then open the invitation again. For
"Address already in use" or "Key already a signer", open the invitation again and pick another key, or add a wallet:
the seat is still open. For every other terminal state, you cannot retry or accept from either screen. Ask the
wallet's creator to send a new invitation if you still need to join.

**I already signed, but the operation hasn't executed**

Signal: you signed in the co-sign sheet, but the multisig operation has not run. Cause: the threshold is met and the
operation awaits execution. The sheet shows only "The threshold is met. This action is awaiting execution." and not
the later execution steps. Fix: do not sign again. The sheet does not let you, and it shows your signature as
read-only once recorded. Check this page's **Completed** tab or [Activity](https://docs.settlemint.com/docs/console/essentials/activity) for the
result, because the sheet does not update to a final state.

**An administrative change is waiting for approval**

Signal: a role, policy, compliance, freeze, pause, transfer, or recovery change appears as a pending approval and no
chain state has changed. Cause: the platform holds the validated request until a different eligible owner or platform
administrator decides it. Fix: open the row from your own session as an eligible approver, not an impersonated one.
**Approve** only if the current state still supports the request. Otherwise reject it with a reason. The maker cannot
approve their own request, and the request expires without applying the change.

**An add-on approval has no Approve button**

Signal: **Review** on an "Add-on approval" row opens the "Approval request" sheet, but the sheet offers no "Approve".
Cause: one of four states. The row reads "Can't be approved here" because the Console cannot read the call, and the
sheet shows the raw call data instead. A wallet of yours proposed the change or already approved it, and the sheet
reads "You approved this. Waiting for other approvers." or offers only "Cancel request". The proposal has its
approvals, and the sheet reads "Approved. Someone with the requester's role can now run it." Or the window ended while
the sheet was open, and the sheet reads "Expired". An expired proposal then leaves this page. Fix: ask another
approver, or a holder of the requester's role to select "Run change". An expired proposal cannot be revived: raise the
change again.

## Frequently asked questions [#frequently-asked-questions]

### Can you run something from the Upcoming tab before it becomes Pending? [#can-i-run-something-from-the-upcoming-tab-before-it-becomes-pending]

No. The **Upcoming** tab has no "Execute" column. It shows "Action", "Parties" and "Opens" by default, plus "Expires" when a row has an expiry, and the column picker adds "Type" and "Status". A control appears once the row's status moves to "Pending". Check back after the row's scheduled time passes.

### What happens when an operation I run from a row fails?

The failure shows in the Submissions tray, which names the next step as "Try again", "Edit and retry", "Top up and retry", "Top up and edit", "Check status" or "Contact support to resolve." The row stays under "Pending", because this page reads the platform's record and a failed write changes none of it. When the tray reads **Outcome unknown**, do not run it again until the tray confirms what happened. [Submissions](https://docs.settlemint.com/docs/console/essentials/submissions) describes each phase and failure.

### Why did a Pending row you were about to act on disappear? [#why-did-a-pending-row-i-was-about-to-act-on-disappear]

Most often someone else acting for the same participant already executed it, or it expired and folded into "Completed". The list updates live, so a row can leave "Pending" between your last look and your click. Check **Completed**: an executed row shows its "Executed by" column, and an expired row sits there too, sorted most recent first. Neither state is retryable from this page.

### Can you narrow the queue down to one row type when it gets busy? [#can-i-narrow-the-queue-down-to-one-row-type-when-it-gets-busy]

Yes. The **Type** filter on the toolbar lists every row type the Console can show, so "Multisig approval" and "Custody approval" are their own named options alongside every type this page can run. Combine it with the search box, which matches the stored action name, type key or target address, or with the tab you are already on, to cut a long "Pending" list down to the handful of rows you came to work through.


# Activity

Source: https://docs.settlemint.com/docs/console/essentials/activity
Use Activity to inspect indexed events for your wallets, trace each one to its blockchain transaction, and download transaction confirmations.

Activity is the indexed event history of one participant's wallets on the active network. A blockchain event is a record of something a transaction did on chain, and Activity shows only events the indexer has already processed and made searchable, never work that is still in flight, which [Submissions](https://docs.settlemint.com/docs/console/essentials/submissions) shows. Use it after an operation to confirm what happened. Whether pending work still needs your approval is answered on [Actions](https://docs.settlemint.com/docs/console/essentials/actions). A second tab, **Confirmations**, lists the transaction confirmations the platform issues for token movements on your wallets.

The list covers the wallets of one participant: your own, or the participant you work as through "Working as". It reads one organisation and the active network, so a switch of participant or network changes the events you see, the same way it changes [Portfolio](https://docs.settlemint.com/docs/console/my-assets/portfolio). Every signed-in, onboarded user sees **Activity** in the sidebar, with no role needed. Reading Activity changes no on-chain state and no pending operation.

![Activity Events tab with the time range control, the events chart and the events table](https://docs.settlemint.com/docs/screenshots/console-activity-events.light.en.webp)

[Screenshot] The "Events" tab shows the time range control, the "Events over time" chart and a table of indexed events for your wallets on the active network.

Each row shows the time, the event with its source and destination, the transaction and the amount.

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

- You must be signed in.
- Check the participant after **Working as** in the account menu at the top right, and the network the page header names, because both narrow what Activity returns.
- Have the event name, asset, account address, transaction hash or approximate time you need to investigate.

## Steps [#steps]

### Open Activity [#open-activity]

Select **Activity** in the Console sidebar. The page has two tabs, "Events" and "Confirmations", and the line under the title reads "For", then your wallets, then "on" and the active network. When more than one wallet is in that line, each shows its short address under its name, so two wallets with the same participant name read apart.

The time range control over the table offers "24 hours", "7 days", "30 days" and "All". It opens on 30 days, and the page address keeps your choice as `?range=`. The "Events over time" chart over the table counts the events of that range per hour for 24 hours and per day for 7 and 30 days. When the chart counts per day over 60 days or more, as "All" can, it turns into a calendar of days shaded by how busy each day was. The chart counts the same events as the table, so its buckets add up to the table total. Drag across the strip under the chart to show only the events of that stretch of time in the table, and select **Clear selection** to return to the whole range. The strip does not work from the keyboard, so use the table's filters and time sort to reach the same events. On a narrow screen, such as a phone, the page leaves the chart out so the first rows fit on the first screen.

### Find the event [#find-the-event]

The table lists the events of the chosen range, newest first, 20 to a page. Search, sort, filters and paging run on the server, so the table reaches every event in the range, and the page address keeps them so a link or a reload restores the same view.

- **Search activity** matches the event name, the asset name, symbol and address, the transaction hash, and the contract, sender, account, relayer, meta-transaction signer and paymaster addresses. A full address also finds every event that involves it. Search does not read the event's decoded values.
- Sort by "Time" or "Event".
- Filter by **Event**, which can also exclude an event type, and by "Asset". The "Network" filter appears when your scope spans more than one network. Each "Asset" and "Network" option shows how many events it matches.
- The table shows "Time", "Event", "Transaction" and "Amount". **View** adds "Asset", "Block" and, when more than one network serves your scope, "Network". The amount carries a plus or minus sign from your side of the movement.

Each row names a source and a destination. A transfer goes from its sender to its recipient. A mint starts at "System" and a burn ends at "Zero address". A role grant or revoke ends at the account that gains or loses the role. An event with no named recipient ends at the contract that emitted it.

A mint, burn or transfer of a DALP asset shows as one row. The asset also emits the standard ERC-20 `Transfer` event for the same movement, from or to the zero address for a mint or burn. Activity does not list that `Transfer` a second time, and the total, the pager and the **Event** filter counts leave it out. A plain ERC-20 token emits only `Transfer`, so its transfers still show. An operation sent through a smart wallet names its contract "Smart wallet entry point". A smart wallet itself shows its address.

When a new block adds events that match your view, a button such as "3 new events" appears over the table. The rows do not move until you select it, and selecting it returns you to the first page.

For a very long history, counting the events can take longer than the 25 seconds Activity allows. The table then still lists the events and pages through them, and the "Events over time" chart still draws the range with its own count. The pager shows only the current page number, the "Event", "Asset" and "Network" filters offer no options, and the new events button does not appear. Choose a shorter time range or search for something narrower so the count fits within that limit.

**Export** saves every event that matches the current filters as CSV or JSON, not only the page on screen. It reads the full set page by page and shows its progress, for example "Loaded 40 of 120 rows…", while it runs.

### Inspect event details [#inspect-event-details]

Select a row, or **View details** in its row menu, to open the event. The row menu also offers "Copy transaction hash", "View on explorer" and, for a mint, burn or transfer whose transaction is final, "Download confirmation (CSV)".

The event opens with its name in your Console language, its category and the date in UTC, then the source, destination and amount. The details then show:

- **Contract** names the contract that emitted the event.
- **Initiated by** names the account that authorised the operation, marked "You" when it is yours.
- **Transaction** carries "Copy transaction hash" and "View on explorer", followed by "Block" and "Network".
- **Event data** lists the event's decoded values with readable labels: a date value reads as a date and time, a list or record reads as numbered rows with each address named, and each flow of an XvP settlement reads as Asset, From, To and Amount rows.
- **Involved addresses** lists the other accounts the event touches.
- **Technical** holds the raw hashes, the encoded values and the transaction index.

The page address keeps the open event as `?event=`, so a reload or a copied link reopens it, even when the event is no longer on the loaded page. A link to an event that does not exist on your wallets shows "Event not found".

A trade that a trading venue settled shows as one row that reads, for example, "Swap: 10 EQ for 1,000 USD", with "10 EQ" as its amount. Its event details name the seller and the buyer, **Sold** for the asset delivered, and "Paid" for what the buyer spent: the quote amount plus the buyer fee, so a 1,000 USD trade with a 1.50 USD buyer fee reads "Paid 1,001.5 USD". The transfers that settled it fold under the swap. Each transfer names who sent and who received it. A party your role may not see reads "Counterparty".

For a relayed or sponsored operation, a **Relayed** section names the "Relayer type". An ERC-4337 UserOperation shows "User Operation", "On-chain sender", "Sponsored by" and "Sponsored amount" when they are known. An ERC-2771 forwarder shows "Relayer", "Meta-transaction signer" and "On-chain sender". Read these with "Initiated by" to see who authorised the operation and who submitted it.

## Download a transaction confirmation [#download-a-transaction-confirmation]

A transaction confirmation is the record the platform issues for each token movement on your wallets once its block is final, meaning the chain can no longer undo it. Open the **Confirmations** tab of Activity to list them, newest first. The tab loads 50 at a time, and "Load more" reads the next 50. Each row shows "Time", "Movement", "Asset", "Amount", "Wallet", "Counterparty" and "Transaction", and "View" adds "Block".

![Activity Confirmations tab with the transaction hash search, the Export button and the confirmations table](https://docs.settlemint.com/docs/screenshots/console-activity-confirmations.light.en.webp)

[Screenshot] The "Confirmations" tab shows the confirmations the platform issued for token movements on your wallets, with the "Search by transaction hash" field and the "Export" button above the table.

1. To find one confirmation, type the full transaction hash in **Search by transaction hash**. A partial hash shows "Enter the full 66-character transaction hash, starting with 0x." The page address keeps the hash as `?search=`.
2. Open the row menu and select **Download confirmation (CSV)** or "Download confirmation (XLSX)". The menu also offers "Copy transaction hash" and "View on explorer".
3. To save the list itself, use **Export**, which saves every confirmation that matches as CSV or JSON.

You can also download a confirmation from an event. The event details of a mint, burn or transfer show a "Confirmation" section and a **Download confirmation** button. Until the transaction is final, the section reads "No confirmation yet. It is available once the transaction is final." and the download gives the same message. When the tab reads "No confirmations yet", no token movement on your wallets is final yet.

## Activity for a participant or an entity [#activity-for-a-participant-or-an-entity]

An operator reads the same kind of event history for someone else from that record's own page. The activity log of a user participant opens from the user's page under [Users](https://docs.settlemint.com/docs/console/participants/users), and the activity log of an entity from the entity's page under [Entities](https://docs.settlemint.com/docs/console/participants/entities). A participant's log lists the indexed events of that participant's wallets. An entity's log lists the indexed events that involve the entity's account address. A record you are not allowed to read returns no rows and no error, so an empty log can also mean you may not read that record.

You can read an entity's log when its address is one of your wallets, a smart wallet that you control, or a data feed registered to the system. The Identity manager and Verification issuer roles also reach the organisation's wallets and registered identity addresses, and the Permission manager, System manager, Auditor and Gas manager roles also reach the system's paymaster and the organisation's bundler wallet.

On those pages, the **Activity log** tile counts the record's events over a range you pick: the last 24 hours, the last 7 days or the last month. It opens on 24 hours. It draws the count as a small chart, states it as, for example, "12 events in the last 24 hours", lists the two most recent events under "Most recent", and links to the full list with "View full activity". The range ends at the time of the network's latest block.

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

- For a recent submission, wait until the [Submissions](https://docs.settlemint.com/docs/console/essentials/submissions) tray reaches "Complete". Then find the event under the intended participant and network, and confirm its **Transaction** matches the hash of the operation you submitted.
- While the tray reads "Indexing", the platform is still waiting for its indexed view to catch up.

## Troubleshooting [#troubleshooting]

**The event is not present yet**

Signal: you know a transaction went through, but no matching row appears. Cause: Activity shows only fully indexed
events, and indexing is the last phase a submission passes through before the tray reports Complete. A transaction
that confirmed on chain moments ago can still be sitting in Indexing rather than Complete. Fix: open the Submissions
tray to see the live phase, and reload the Activity page once the tray shows Complete rather than assuming Confirming
or Indexing means the row already exists here.

**The account that authorised an operation is not the account that submitted it**

Signal: "On-chain sender" names an address you do not recognise. Cause: the operation went through an ERC-4337 bundler
or an ERC-2771 forwarder, so the account that submitted the transaction is not the account that authorised it. Fix:
read **Initiated by** for the account that authorised the operation, and the "Relayed" section for the relayer, the
sponsor and, when known, the meta-transaction signer.

**Activity shows no events**

Signal: the Events tab reads "No events on your wallets yet" or, for a shorter range, "No events in the last 30 days".
Cause: your wallets have no indexed events in the chosen range on the active network. Fix: select the button under the
message, such as **Show all events**, to widen the range. When your identity is not registered, "No events on your
wallets yet" also links to "Register your identity". When the tab reads "No network serves this scope" and "Pick a
network under Network in the user menu.", open the account menu at the top right, point at "Network" and pick a
network there. When the tab reads "No network is active", the organisation has no active network. An organisation
owner or platform administrator selects "Open Networks" to add one on
[Networks](https://docs.settlemint.com/docs/console/organisation-settings/networks), or to retry a network that failed to deploy. Anyone else
reads "Ask an organisation owner to add a network."

**Activity cannot load**

Signal: the events area shows the Console's general loading error instead of your events. Cause: the events read
failed. Fix: confirm the participant in **Working as** and the active network, then reload the page.

## API routes [#api-routes]

The [Platform API](https://docs.settlemint.com/docs/api-reference/v2) serves the same reads, from indexed data only:

- `GET /api/v2/users/me/events` lists your events with the filters, search, sort and cursor paging the Console uses. The first page carries the total and the counts per Event, Asset and Network option. When counting takes longer than 25 seconds, the first page still returns its rows and `meta.nextCursor`, leaves out `meta.total` and `meta.facets`, and sets `meta.totalsSkipped` to `timeout`. A missing total then means it was not counted, not that it is zero. A retry counts again and often runs out of time again, so narrow the time range or search to get the counts. Pass `counts=false` when you only need the rows. A page without `meta.total` leaves `links.last` out, because the last page is not known.
- `GET /api/v2/users/me/activity-metrics` counts your events per bucket over a window, for the same wallets and filters, so its total equals the list total.
- `GET /api/v2/participants/{participantId}/activities` and `GET /api/v2/participants/{participantId}/activity-metrics` read a participant's events and their counts. A participant you cannot read returns an empty page.
- `GET /api/v2/system/accounts/{accountAddress}/activities` and `GET /api/v2/system/accounts/{accountAddress}/activity-metrics` read one account's events and their counts, under the same access check.
- `GET /api/v2/reporting/confirmations` lists confirmations and filters by `transactionHash`.


# Ask

Source: https://docs.settlemint.com/docs/console/essentials/ask
Ask the assistant a question about the page you are on, read the sources behind the answer, and keep the conversation open beside the page.

Ask opens the assistant beside the page you are on, so you can question what the page shows without leaving it. The assistant reads only that page's subject, as you. Figures in an answer come from reads made as you, and the platform removes any sentence whose figure does not match a read. The text around the figures is written by a model and can be wrong, so check a claim against **Sources** before you act on it.

On a page Ask can read, the search field reads **Search, or ask about** with the page's name. On any other page search works as usual. [What the assistant sends](https://docs.settlemint.com/docs/concepts/operating/assistant-data) says which model receives a question and what DALP masks before it leaves.

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

- Your organisation must have the assistant on, and the page must have something to ask about: an asset, a user who has a participant, a trading venue, the audit trail, or the filings, filing calendar, obligations and anchor registry.
- A member who holds a system role can also ask about the whole organisation from the operator dashboard, Actions, Activity, All assets, Portfolio, Users and Entities.
- When the assistant is off, search shows no **Ask** row.
- On a page Ask cannot read, the panel says "Ask works on pages it can read, such as an asset, a participant or a venue. Open one to ask about it."

## Steps [#steps]

### Ask from search [#ask-from-search]

Type a question that ends in a question mark, or one of at least three words that opens with a question word such as "who", "what" or "which", and the **Ask** row moves to the top. Press `Enter` to send it. Text of more than 140 characters also moves "Ask" to the top. Any other text keeps search first and lists "Ask" last.

- Press `Tab` to open an empty question field. It offers your last three questions about this page from the past 30 days, or three example questions you can click when you have none.
- To ask whatever you typed, hold `⌘`, or `Ctrl` outside macOS, and press `Enter`.
- In the question field, `Enter` sends, `Shift` + `Enter` adds a new line, and the round button at the end of the field sends too.
- Press `Esc` to stop a running answer and go back to the list.

The answer fills in below the question, with the figures taken from the data of the page you asked about.

### Keep the conversation open beside the page [#keep-the-conversation-open-beside-the-page]

Press `⌘` + `J`, or `Ctrl` + `J` outside macOS, or choose the **Ask panel** button, the chat icon in the top bar, to keep the conversation open beside the page. On an asset page, text over 140 characters offers "Draft from this" first, which prepares a control with values filled in, as [Assistant plans](https://docs.settlemint.com/docs/console/essentials/assistant-plans) describes. On any page, text over 4,000 characters is not sent, and the field says the text is too long.

### Read the answer [#read-the-answer]

Under a settled answer the assistant offers up to three next questions you can click. They come from a fixed list, not from the model. The field empties when you send. Type again after an answer to ask a follow-up. A follow-up appears below the earlier answers, which stay readable. The assistant remembers the last three answers in the thread, and the fourth question starts a new thread.

An answer can show a small table of the rows it cites, and "Sources" lists up to eight records it relied on: select one and choose **Show on page** to open the page with that record marked. On the latest answer, the line that names what the assistant read opens a list of those reads. A read the DALP CLI also offers shows its `dalp` command with a copy button.

Select the question to edit it. Under the answer, "Try again" asks it again, and "Helpful" and "Not helpful" rate the answer. "Not helpful" also opens a form where you can send your administrators a reason and an optional note.

When you have three questions or fewer left, the footer says how many and the time your allowance starts over, for example "3 questions left until 14:00 UTC". If the assistant is busy, it says to try again in a minute, or names the time in UTC for a longer wait.

## Ask about a period [#ask-about-a-period]

On an asset page, ask about a period, such as "what changed this week?" or "summarise last month", and the answer leads with a strip of figures: transfers, volume, net supply change and active holders, each with the same figure for the period before it. The figures are totals for the whole period, not for the rows on screen. A period can span at most 93 days, and a week or month that is still running is marked as running.

## Choose the answer language [#choose-the-answer-language]

Answers come in the language the Console is set to, whatever language you type the question in. With the Console in Arabic, "Who holds the most?" gets an answer in Arabic. The line under the question field says so: "AI answers follow your interface language and can be wrong". To read answers in another language, pick it from the account menu. See [Languages](https://docs.settlemint.com/docs/console/organisation-settings/languages).

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

- Select a source under "Sources", then choose **Show on page**.
- The page opens with the record marked, and its values match what the answer cited.

## Troubleshooting [#troubleshooting]

**Search offers no Ask row**

Signal: the search field reads "Search" and no **Ask** row appears. Cause: the assistant is off for your organisation,
or the page has nothing to ask about. Fix: ask an organisation owner whether the assistant is on, or open a page it
can read, such as an asset.

**The field says the text is too long**

Signal: pasting text shows a message that the text is too long. Cause: text of more than 4,000 characters is not sent.
Fix: paste only the part with the instruction.



# Assistant plans

Source: https://docs.settlemint.com/docs/console/essentials/assistant-plans
Turn a request that needs several changes into an ordered plan, check each step against DALP's reads of the asset, and open each control for you to sign.

A request that needs several controls, such as a coupon payment, a holder notice and a filing, opens a plan instead of a single draft. The plan lists the steps in the order you wrote them, with the values taken from your words and what each step does to the asset before you sign anything.

A plan never signs and never submits. It is a prepared order of work. Every step is signed in the control that owns it, with the wallet verification that control already asks for.

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

- Your organisation must have the assistant on, and you open the plan from an asset page.
- Each step still needs the role its own control asks for, so the plan says when you do not hold it.
- [Ask](https://docs.settlemint.com/docs/console/essentials/ask) covers the assistant in search and the panel beside the page.

## Steps [#steps]

### Ask for a plan [#ask-for-a-plan]

Open [Search](https://docs.settlemint.com/docs/console/essentials/search) on an asset page and ask for the changes you want, separating them the way you would say them: "pay the Q3 coupon on all Brightline bonds, notify holders, then file it".

- The assistant splits the request where one instruction ends and the next begins: at a sentence end, a semicolon, a comma between two phrases, or the word "then".
- Each part is matched to one of the controls search already drafts. A part that matches nothing is left out, and a request that matches only one control is answered as a single draft.
- A plan holds at most six steps. Parts after the sixth are cut.

The plan does not list a part it left out or cut, so compare its steps with your request before you work it.

### Read each step before you sign it [#read-each-step-before-you-sign-it]

Each step shows the control it opens, the values drafted from your words, and the words it took them from. Under that, it shows what the step does to the asset, simulated against the state read when the plan was built, at the time the plan shows:

- the total supply before and after.
- the balance of each holder the step moves, before and after.
- the paying treasury and its balance in the denomination asset, for a step that pays cash.
- the five largest holders, with the balance each would hold after the step.

The steps are simulated in order, so each one is applied on top of the step before it. A step that pays out after a step that mints sees the larger supply.

The simulation is DALP's own calculation over its indexed reads of the asset, not a run of the transaction. It checks the role, the pause, the supply cap, the treasury and the balances of the ten largest holders, and marks a check it could not make as "not checked". It does not apply the token's compliance rules, so a step that reads "This step goes through on the state read." can still be refused when you sign it.

A step that cannot go through says so, in plain words: the token is paused, a holder's balance is too small, the supply would pass its cap, the treasury does not cover the payment, or you do not hold the role the control needs. The rest of the plan still shows its own outcome.

### Work the plan [#work-the-plan]

Choose a step to open its control with the values filled in, then preview, approve and sign it there. When you come back, the plan shows the step as done.

A step that changes balances is marked done when the chain shows its effect. A step that leaves no trace on chain, such as a holder notice, is marked done by you with **Mark done**. That mark records that you marked it, not that the notice went out.

A plan is saved for you and the asset. Open Search on the same asset and your open plans are listed under **Open plans**, before the suggestions. Open one to carry on where you left it. Choose "Refresh simulation" after the asset has moved, so the figures and the outcome reflect the state you are about to sign against. Choose "Abandon plan" for a plan you no longer want. A plan whose steps are all done closes itself. A closed plan, abandoned or completed, still shows its steps but no longer offers to open a step or mark it done.

## What leaves DALP [#what-leaves-dalp]

A plan asks the model two things per step: which control the words ask for, and which values they give. Those values are the model's reading of your words, shown next to the words they came from, so check them in the control before you sign. Every figure, verdict and check in a plan comes from DALP's indexed reads of the asset and its own calculation, not from the model. The names, masking and data scope on the [Assistant data](https://docs.settlemint.com/docs/concepts/operating/assistant-data) page apply to those questions as they do to any other.

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

- After you sign a step that changes balances, reopen the plan from Search on the same asset: the step reads as done once the chain shows its effect, and **Refresh simulation** shows the figures the next step starts from.


# Dashboard

Source: https://docs.settlemint.com/docs/console/essentials/dashboard
Dashboard opens after sign-in with one ranked list of what waits on you, then key figures, system status, what changed since your last look, and pinned views.

Dashboard is the page the Console opens after sign-in, and it puts what waits on you first: one **Needs attention** list, ranked by urgency, with an action on each row. Below it come your key figures, the health of the services your work depends on, what changed since your last look, and the saved views you pinned. Most rows link to, or open, the screen where the work is done.

Two controls act from Dashboard itself. **Register identity** submits after your wallet verification, and "Clear all" dismisses failed submissions without retrying them.

Each panel shows only what your roles allow, and each panel loads on its own, so one slow or failed read never holds back the others.

![Console Dashboard in the operator view, with the Issue asset button, the key figures strip, Needs attention, System status and Since you last looked](https://docs.settlemint.com/docs/screenshots/console-dashboard-overview.light.en.webp)

[Screenshot] The operator view of Dashboard shows the key figures strip and the "Needs attention", "System status" and "Since you last looked" panels.

The header holds the "Issue asset" button. Below it, the key figures strip shows "Assets under management" and the other figures the user's roles reach. Each figure shows its change over 7 days, and here every figure reads "No prior 7 days yet", because none has a value greater than zero from 7 days before to compare against. "Needs attention" and "System status" sit in the left column, and "Since you last looked" fills the right column. "Pinned views" and "Your holdings" follow further down.

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

- Your account and organisation must have finished onboarding.
- Dashboard follows the participant you work as, so check **Working as** in the account menu first.
- The roles that participant holds decide which of the two views opens and which panels show.

## Steps [#steps]

### Check which view you have [#check-which-view-you-have]

Dashboard picks its view from the roles you hold on your organisation's system, the set of platform contracts it runs on the selected network. A system role is an organisation-wide permission such as permission manager, asset manager, identity manager, verification issuer, compliance manager or gas manager. Holding tokens is not a system role.

| You hold | You see | In this order |
| --- | --- | --- |
| Any system role | The operator view | **Key figures** for your roles, then **Needs attention** and **System status** beside **Since you last looked**, then **Pinned views**, then **Your holdings**. |
| No system role | The holder view | **Key figures** for your portfolio, then **Needs attention**, then **Change in value** beside **Allocation**, then **Since you last looked** beside **Upcoming events**, then **Pinned views**. |

**Working as** sets whose data and authority the Console uses, so switching
participant can change which view you see. While you work as a person or a shared account other than yourself, Dashboard
is scoped to that account and shows the holder view for its portfolio. A shared account has the kind Multisig wallet in
the Console. Working as an organisation keeps the operator view, because the organisation is the account.

The header carries an **Issue asset** button when you may create assets. It opens the asset designer, which [Issue a new asset](https://docs.settlemint.com/docs/console/asset-management/issue-new-asset) describes. When the right to create assets sits on another of your wallets, the button is greyed out and says why.

### Work through Needs attention [#work-through-needs-attention]

One list gathers everything that waits on you. Each row carries a severity label, and the list is sorted by it, most urgent first: "Unavailable", "Blocked", "Needs review", "Approval", "Pending", "Invitation". The count beside the panel title, such as "3 pending", adds up what waits, so a row for 3 actions counts 3. With nothing waiting, the panel does not show at all.

| Row | Severity | Who sees it | Its control |
| --- | --- | --- | --- |
| "Couldn't load your actions." or another source | **Unavailable** | Anyone whose read of that source failed | **Try again** |
| A failed submission, such as "2 actions need your review" | **Needs review** | You, for submissions started in this browser | **Review submissions**, and **Clear all** |
| "Set your transaction PIN", "Save your recovery codes", "Verify your identity" | **Blocked** | You, until each account setup step is done | **Set PIN**, **View codes**, **Verify your identity** |
| "Low on gas: Token creator wallet" | **Blocked** | Operator view, for each of your wallets that pays its own gas on the selected network | **Fund wallet** |
| "3 more wallets are low on gas" | **Blocked** | The same, once more than four of your wallets are low | **Open transaction funding** |
| A network whose transaction funding needs work | **Blocked**, Pending or **Unavailable** | Permission manager, gas manager or system manager | **View funding**, or **Open Wallet type** when funding is not set up |
| "3 actions wait for you" | **Approval** | Anyone with rows in Needs you on [Actions](https://docs.settlemint.com/docs/console/essentials/actions) | **Open actions** |
| "2 filings await approval" | **Approval** | Anyone with filings to approve on Actions | **Review filings** |
| "Set up your identity on Example network" or "Finish registering on Example network" | Pending | You, on an added network that is not the organisation's default | **Register identity**, confirmed with your wallet verification |
| "4 asset launches are pending" | Pending | Asset manager | **View assets** |
| "2 users have a pending identity registration" | Pending | Identity manager | **Review identities** |
| "5 KYC profiles await review" | Pending | Identity manager or verification issuer | **Review KYC profiles** |
| "1 offering to settle" | Pending | Anyone with an ended token sale to claim from or be refunded by | **Open holdings** |
| "Invitation to join Northwind Coffee" | **Invitation** | You, for each pending invitation that has not expired | **Review invitation** |

The row for actions counts the rows in Needs you on Actions, apart from filing approvals, which have their own row. It names up to two of those same rows, claims first, and ends with "and 1 more" when there are others, so an action that waits on someone else is neither counted nor named. A withdrawal destination to review is named by its customer, the same name Actions shows, or reads "Review withdrawal destination" when no name resolves. A link control shows only when you can open the page it points to.

**Fund wallet** opens a dialog titled with the wallet's name. It says "Confirm the network, then send the amount shown to the address." Send that amount of the network's gas token to the address from a wallet you control. How a paying wallet is funded is set on the transaction funding settings, which [Transaction funding](https://docs.settlemint.com/docs/console/organisation-settings/transaction-funding) covers.

A low-gas row names the wallet by its contract name, or by the role its funding request funds when the wallet has no name.

While a paying wallet is low on gas or a funding request is open, Dashboard reads wallet balances and funding requests again every 30 seconds, without a reload. The platform's indexer records native balances on its own schedule, so a funded wallet's row can stay until the indexer records the new balance. Once no wallet is low and no request is open, Dashboard stops these reads, and a wallet that runs low after that gets its row the next time you open Dashboard.

A row for a failed submission names the latest failure and up to two others, with a count of the rest. **Review submissions** opens the Submissions tray on the entries that need review. "Clear all" acknowledges every failed entry and removes the row without retrying anything.

### Read your key figures [#read-your-key-figures]

The operator view opens with one figure for each role that has one. Each figure opens the page that lists its records.

| Figure | Who sees it | What it counts | Opens |
| --- | --- | --- | --- |
| Assets under management | Asset manager | Each asset's supply times its price, converted to your base currency. | All assets |
| Assets live | Asset manager | Assets that have launched, shown against all assets created in the organisation, as "of 12 created". | All assets, filtered on the Live and Halted statuses |
| Identities | Identity manager | Active identities in the identity registry, counted from the indexed chain. | Users |
| Active verifications | Verification issuer | Active claims issued on identities, counted from the indexed chain. | Users, **Insights** tab |

Each figure shows its change over the last 7 days under the value, and a trend line to its right. Pointing at the line gives the date and value of a point. A figure that started the 7 days at zero shows that there is no prior period instead of a percentage. A figure whose read fails shows "Unavailable" with **Try again**. On a phone the strip scrolls sideways.

The holder view opens with "Portfolio value", "Available" and "Unrealized gain" instead.

**Available** is the value you can move now, without frozen and locked balances, and it names the amount that is frozen or locked.

**Unrealized gain** is the current value minus each holding's cost basis, with its percentage on that cost. [Portfolio](https://docs.settlemint.com/docs/console/my-assets/portfolio) explains how these are valued.

### Check System status [#check-system-status]

**System status** shows the health of the services your work depends on. Each row links to its detail page, and every row's badge uses one of five words: "Healthy", "Attention", "Critical", "Unknown" or "Not needed".

| Row | Who sees it | What it says |
| --- | --- | --- |
| Indexer | Organisation owner or platform administrator | "In sync at block 1,204,311", how many blocks the indexer is behind, "Rebuilding indexed data", "No indexer has reported yet" or "No recent health sample". The indexer is the service that reads the chain into the data Dashboard shows. |
| Transaction funding | Any operator | For permission manager, gas manager and system manager: the worst funding status across your networks, with the networks it applies to. For other operators with a wallet that pays its own gas: whether that wallet is funded. **Not needed** when no wallet pays its own gas. |
| Trusted issuers | Verification policy manager | The count of active trusted issuers and how many changed in the last 7 days. |

When the indexer falls behind or is rebuilding, an organisation owner or platform administrator also sees a finding above the key figures. It reads "Figures are behind the chain" or "The indexer is rebuilding", names the block it has reached, and offers **View status**. The finding leaves on its own once the indexer catches up.

A failed read of wallet gas or transaction funding shows once, on its "System status" row with **Try again**, and adds no row to "Needs attention".

### See what changed since you last looked [#see-what-changed-since-you-last-looked]

The panel covers the events since your previous visit to Dashboard and says when that was, for example "Last looked 2 hours ago". Coming back within 30 minutes counts as the same visit, so a reload or a second tab does not reset it. On your first visit, the panel covers the last 7 days.

Above the events, the panel counts supply moves, new holders, corporate actions, settlements and filings, and each count links to the page that lists them. The supply, holder, corporate action and settlement counts cover only changes that involve one of your wallets, the same events Activity lists, and each says so, such as "19 supply moves involving you". The asset activity chart on [Asset insights](https://docs.settlemint.com/docs/console/asset-management/insights) shows system-wide totals, so a mint another member signed to someone else's wallet appears there but not here.

These counts cover the newest 200 such changes in the window. Past that, each reads as a floor, such as "180+ settlements involving you". The filings count covers your organisation's filings and shows only to someone who may read reporting.

The panel then lists the latest events, five on a wide screen and three on a phone. Each line names the event, the wallets it moved between, with "You" for your own wallets, an "Amount" on the right when the event moves a value, and when it happened. Events that belong to one transaction share one line, labelled with the most specific event. **See all activity** opens [Activity](https://docs.settlemint.com/docs/console/essentials/activity). With nothing new, it says "Nothing changed since you last looked."

### Use pinned views and your holdings [#use-pinned-views-and-your-holdings]

**Pinned views** shows the saved views you added to home, in your order, each read again with the access you hold now and with an "Open view" link. "All saved views" opens the full list. With no saved views at all, the panel is not shown. With saved views but none pinned, the panel says "No saved views on home yet" and "Add a saved view to home to see it here."

To pin one, open the view's actions and choose **Add to home**, as [Saved views](https://docs.settlemint.com/docs/console/personal/saved-views) explains.

In the operator view, **Your holdings** lists your three largest holdings with their balance, price, value and share of the total, to one decimal place (for example "23.0%"), then "and 4 more holdings" and "Open portfolio". It shows only once your identity is registered and you hold something.

## Read the holder view [#read-the-holder-view]

The holder view puts your portfolio first. **Change in value** charts your portfolio value over 7 days, 1 month or all of its history, and "Allocation" splits the value by asset class, largest first. Each row names the class the way the Console sidebar does, with the number of holdings, the amount in your base currency and the share of the total. The amounts add up to the portfolio value.

**Upcoming events** lists your dividend payments and fixed income coupons due in the next 30 days, through the end of the thirtieth day in UTC, at most 10, and is not shown when nothing is scheduled. With no holdings, one Portfolio card reads "You hold no assets yet." with "Browse offerings" when you can open Invest.

Before your identity is registered, the holder view shows **Get ready to invest** instead of the portfolio panels. It lists two steps: "Verify your identity", which you complete from your profile, and "Identity review", which your identity manager completes. The card leaves once the identity is registered.

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

- Check that the view matches your roles: key figures for a system role, "Portfolio value" for none. Then cross-check one number against its own page.
- The count on the "actions wait for you" row, plus the filings row, matches the **Pending** count on [Actions](https://docs.settlemint.com/docs/console/essentials/actions) for the same participant.
- A key figure matches the page it opens, such as Assets live against All assets.

## Troubleshooting [#troubleshooting]

**A row reads Couldn't load followed by a source**

Signal: "Needs attention" shows an "Unavailable" row such as "Couldn't load your actions." Cause: the read behind that
row failed, and Dashboard shows the failure rather than an empty list that would look like nothing waits. Fix: choose
**Try again**. If it fails again, open the page the source belongs to, such as Actions, to check it directly.

**You expected the operator view but see your portfolio**

Signal: Dashboard opens on **Portfolio value** and the holder panels. Cause: the active participant holds no system
role on the organisation's system for the selected network. Asset roles, such as custodian on one asset, do not count.
Fix: check which participant you work as and which network is selected, then ask a Permission manager to grant the
system role you need, as [Roles and segregation of
duties](https://docs.settlemint.com/docs/concepts/compliance-and-identity/roles-and-segregation-of-duties) describes.

**A key figure or status row you expected is missing**

Signal: a figure such as Identities, or the Trusted issuers row, does not show. Cause: each figure and row belongs to
one role, listed in the tables on this page, and the Indexer row shows only to an organisation owner or platform
administrator. Fix: confirm the role is granted on the organisation's system for the selected network.

**A wallet is low on gas but no row shows**

Signal: you know a wallet is short of gas, but "Needs attention" has no row for it. Cause: low-gas rows cover only
your own wallets that pay their own gas on the selected network, and only in the operator view. A network that charges
no gas, or whose gas a paymaster sponsors, raises no low-gas row. A paymaster is a contract that pays fees on your
wallet's behalf. Fix: select the network the wallet uses, or, as a permission manager, gas manager or system manager,
open the Transaction funding row of **System status** to see the funding status of each network.

**A figure says there is no prior period**

Signal: a key figure shows no percentage change and no trend line. Cause: the figure started the 7 days at zero, so
there is nothing to compare against, for example on a system younger than 7 days. Fix: wait. The change appears once
the figure has a value at the start of a 7-day window.



# Dashboard, Actions and Activity

Source: https://docs.settlemint.com/docs/console/essentials
The three Console screens above the sidebar groups, plus the submissions tray, search, the assistant and keyboard shortcuts that work on every screen.

The top of the Console sidebar holds three items outside any group:

- **Dashboard** opens after sign-in.
- **Actions** lists the work waiting for the participant you are working as.
- **Activity** is the log of events on your wallets once the platform has indexed them.

Submissions, Search, Ask, assistant plans and the keyboard shortcuts work from any screen, so their pages sit here too.

How the Console frame behaves around every screen is explained in [How the Console frame works](https://docs.settlemint.com/docs/concepts/operating/console-navigation), and the parts many screens share in [Tables](https://docs.settlemint.com/docs/concepts/operating/table-views), [Form drafts](https://docs.settlemint.com/docs/concepts/operating/form-drafts) and [Address fields](https://docs.settlemint.com/docs/concepts/operating/address-fields).


  - [Dashboard](https://docs.settlemint.com/docs/console/essentials/dashboard): The page after sign-in: what waits on you, key figures, system status and pinned views.
  - [Actions](https://docs.settlemint.com/docs/console/essentials/actions): Review scheduled, pending and completed work and run the control each row offers.
  - [Activity](https://docs.settlemint.com/docs/console/essentials/activity): Inspect indexed wallet events, trace each to its transaction and download confirmations.
  - [Submissions](https://docs.settlemint.com/docs/console/essentials/submissions): Follow each write through its phases, undo it while possible and fix a failure.
  - [Search](https://docs.settlemint.com/docs/console/essentials/search): Find pages, assets, users, entities, contacts and contracts without leaving a screen.
  - [Ask](https://docs.settlemint.com/docs/console/essentials/ask): Ask the assistant about the page you are on and read the sources behind the answer.
  - [Assistant plans](https://docs.settlemint.com/docs/console/essentials/assistant-plans): Turn a request that needs several changes into an ordered plan you sign step by step.
  - [Keyboard shortcuts](https://docs.settlemint.com/docs/console/essentials/keyboard-shortcuts): Move between pages, start a main action and search a table from the keyboard.



# Keyboard shortcuts

Source: https://docs.settlemint.com/docs/console/essentials/keyboard-shortcuts
Move between Console pages, start a page's main action and search its table from the keyboard, and turn the one-key shortcuts off.

The Console and the Investor portal respond to a small set of keys. Some open a page, some start the main action on the page you are on, and three work from anywhere with `⌘` held, or `Ctrl` outside macOS. To explore what exists, use the sidebar. To reach a record by name or address, use [Search](https://docs.settlemint.com/docs/console/essentials/search).

A key cap beside a label tells you the key. Issue asset shows `N`, Add contact shows `N`, Edit shows `E`, and an empty table search field shows `/`. A screen reader announces the key from the control, not from the key cap.

![Keyboard shortcuts list over Dashboard, with Go to, Everywhere and On this page groups and the Single-key shortcuts switch on](https://docs.settlemint.com/docs/screenshots/console-keyboard-shortcuts-list.light.en.webp)

[Screenshot] Under "Go to", the list shows a go-to chord for each page that has one and the signed-in investor can open: Dashboard, Actions, Activity and Portfolio.

Under "Everywhere" the list shows `Ctrl` + `K`, `Ctrl` + `B` and `?`. "On this page" is empty, and a note under the groups reads "This page has no shortcuts of its own." The "Single-key shortcuts" switch sits at the bottom, set to On.

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

- The keys need a hardware keyboard.
- **Single-key shortcuts** are on in a browser profile until someone switches them off there, and the `g` chords cover only the pages your roles can open.

## Steps [#steps]

### Open the keyboard shortcuts list [#open-the-keyboard-shortcuts-list]

Open the account menu and choose **Keyboard shortcuts**. You can also press `?` on any page. The list opens over the current page, grouped under "Go to", "Everywhere" and "On this page", with the "Single-key shortcuts" switch at the bottom.

### Switch off Single-key shortcuts [#switch-off-single-key-shortcuts]

Use the **Single-key shortcuts** switch in the list. The word beside it changes from "On" to "Off". Switch the group off when a key you press by habit should never start an action. `⌘` + `K`, `⌘` + `J` and `⌘` + `B` keep working.

The setting belongs to your browser profile, not your account. Switching it off applies to everyone who signs in through that browser profile. Other browsers and other computers keep their own setting.

## Keys that work everywhere [#keys-that-work-everywhere]

These keys use `⌘` on macOS and `Ctrl` on Windows and Linux. They keep working when you turn the one-key shortcuts off.

| Keys | What happens | Where |
| --- | --- | --- |
| `⌘` + `K` | Opens [Search](https://docs.settlemint.com/docs/console/essentials/search). Press it again to close the dialog. | Console and Investor portal |
| `⌘` + `J` | Opens the Ask panel beside the page. It does nothing unless the page offers the assistant. | Console |
| `⌘` + `B` | Shows or hides the sidebar. | Console and Investor portal |

The first `Tab` on a page, in the Console and the Investor portal, shows a **Skip to main content** link in the top corner. Press `Enter` on it to move focus past the sidebar and the top bar to the page itself.

## Keys that open a page [#keys-that-open-a-page]

Press `g`, then one letter. While you wait, a line at the bottom of the screen lists the letters you can press. The chord ends on any other key or after 1.5 seconds. A page you cannot open has no letter.

| Keys | Opens | Where |
| --- | --- | --- |
| `g` then `d` | Dashboard | Console and Investor portal |
| `g` then `a` | All assets | Console |
| `g` then `i` | Actions | Console and Investor portal |
| `g` then `v` | Activity | Console and Investor portal |
| `g` then `p` | Portfolio | Console and Investor portal |
| `g` then `s` | General | Console |

The Investor portal has no All assets or General page, so it has no `a` or `s` chord. When the sidebar is collapsed, hovering a page's icon shows its chord next to its name.

## Keys that act on the page [#keys-that-act-on-the-page]

| Key | What happens |
| --- | --- |
| `/` | Moves focus to the page's table search field and selects what is in it. |
| `n` | Starts the page's main create action, such as Issue asset on All assets or Add contact on Contacts. |
| `e` | Opens the edit screen of a contact, and the Edit sheet of a compliance provider or a policy template. |
| `?` | Opens the list of shortcuts that work on the page you are on. |

A key that targets a control does nothing while that control is disabled, for example Add contact while the page is still loading. The `?` list shows only the shortcuts the open page offers, under **On this page**, beside the keys that work everywhere.

## When the keys do not fire [#when-the-keys-do-not-fire]

The single-key shortcuts (`g`, `/`, `n`, `e` and `?`) stay quiet while you type in a field, while a dialog, sheet or menu is open, and while you hold `⌘`, `Ctrl` or `Alt`. Typing "new" into a search field therefore never starts a create action.

## Where the key caps appear [#where-the-key-caps-appear]

| Control | Key cap | Page |
| --- | --- | --- |
| Issue asset | `N` | All assets |
| Add contact | `N` | Contacts, in the Console and the Investor portal |
| Edit | `E` | A contact's page, which opens its edit screen, in the Console and the Investor portal. A compliance provider's page and a policy template's page, which open the Edit sheet, in the Console |
| Table search field | `/` | The search field `/` focuses, the first on the page, while it is empty |

The key caps are hidden on screens narrower than 640 pixels and on touch screens, where a key press is not the way you reach the control. The same keys still work on a narrow window with a keyboard attached.

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

- After you switch **Single-key shortcuts** off, close the list and press `n` on All assets.
- Nothing starts, and the key caps beside Issue asset and the table search field are gone.
- The "Keyboard shortcuts" entry in the account menu still opens the list, and `⌘` + `K` still opens Search.

## Troubleshooting [#troubleshooting]

**A key does nothing**

Signal: pressing `n`, `e`, `/` or `g` has no effect. Cause: the single-key
shortcuts are off, a field has focus, a dialog or menu is open, or the control the key targets is disabled or missing
from the page. Fix: press Escape to leave the field or dialog, then press the key again. Open **Keyboard shortcuts**
from the account menu to check the switch.

**The key caps disappeared**

Signal: Issue asset, Edit and the table search field no longer show a key. Cause: the single-key shortcuts are off in
this browser, the window is narrower than 640 pixels, or the screen is a touch screen. Fix: open "Keyboard shortcuts"
from the account menu and switch **Single-key shortcuts** back on, or widen the window.

**g shows a line at the bottom of the screen and then nothing opens**

Signal: the line listing letters appears, and the next key opens no page. Cause: the letter you pressed belongs to a
page you cannot open, or the 1.5 seconds ran out. Fix: press `g` again and choose a letter from the line.

## Frequently asked questions [#frequently-asked-questions]

### Do the shortcuts work in every language?

Yes. The keys are letters and symbols, so they stay the same when the Console is shown in another language. Only the labels around them are translated.

### Can I change which key does what?

No. The keys are fixed. You can turn the single-key group off as a whole.

### Why does the search shortcut work when I switch the single-key shortcuts off?

The setting covers only keys that one press triggers. Keys pressed with `⌘` or `Ctrl` held are a separate group and stay on.


# Search

Source: https://docs.settlemint.com/docs/console/essentials/search
Use Console search to find pages, assets, users, entities, contacts, and system contracts you already have access to, without leaving your current screen.

Console search opens over the current screen and jumps to a page, an asset, a user, an entity, a contact or a system contract you already know exists. It suits a record you can name by symbol, name or wallet address. To see what exists, use the listing screen instead.

Asset results come from the wallets and roles of one participant: your own, or the participant you work as through **Working as**. User and entity results follow that participant's roles too. Contacts, pages and system contracts do not change with the participant you work as. Typing a query changes nothing on-chain or in the platform. Choosing a record result opens a page or copies an address. Choosing an "On this page" or "Actions on recent assets" row does what that control does on the page, and the "Ask" row sends your question to the assistant.

![Search dialog open over the Console with its search field](https://docs.settlemint.com/docs/screenshots/console-search-dialog-open.light.en.webp)

[Screenshot] Over the current page, the "Search" dialog shows its search field and the "On this page" group of the page's own actions.

Results appear in groups once you type at least two characters.

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

- You must be signed in, and the active organisation needs a system provisioned on the active network.
- Without one, every record category returns empty, contacts included, however exact your query is.
- Asset, user and entity results also depend on the roles of the participant you work as.

## Steps [#steps]

### Open Console search [#open-console-search]

Select **Search** in the top bar, or press `⌘` + `K`, or `Ctrl` + `K` outside macOS. The key caps on the button show the one that applies to your computer, and [Keyboard shortcuts](https://docs.settlemint.com/docs/console/essentials/keyboard-shortcuts) lists the other keys. Type at least two characters. A shorter query shows "Type at least two characters" until you add another. Results load about 300 milliseconds after you stop typing. A dialog opens over the current page and groups results under these headings, showing only the groups that have a match:

- **On this page**
- **Actions on recent assets**
- **Pages**
- **Contacts**
- **Assets**
- **Users**
- **Entities**
- **System contracts**

### Review the results [#review-the-results]

Read the grouped results. Each result shows its name or address so you can confirm you selected the right record before you act. Each record category shows at most 10 results, so a broad query can omit the record you need. Narrow the query rather than assuming a miss means the record does not exist.

### Select a result [#select-a-result]

Selecting a page opens it. Selecting an asset opens its token detail page, a user opens their user detail page, and a contact opens its contact page. Selecting an entity opens its entity detail page when that participant has a provisioned wallet. Without one the row is disabled. Each of these is a link, so you can also open it in a new tab. Selecting a system contract copies its address to your clipboard, because no page shows a system contract. The row is labelled **Copy address** and the copy shows a "Copied to clipboard" toast, or "Sorry, we couldn't copy that to your clipboard" when the browser refuses clipboard access.

## What search covers [#what-search-covers]

The first group, **On this page**, lists the open page's own actions, tabs and sections, and choosing one runs it, opens it or scrolls to it.

| Category | Scope and access |
| --- | --- |
| Pages | The pages your sidebar shows you. No extra permission. |
| Contacts | Your own account, across every organisation you belong to. Anyone signed in can search it. |
| Assets | Active network, organisation, and system. Anyone signed in. A system role beyond the basic lookup permissions shows every match. Otherwise only assets your wallets hold or manage. |
| Users | Active organisation and network. Needs user-search permission, except for your own account. |
| Entities | Active organisation and network. Needs entity-list permission. An exact multisig or signer-key address also finds it. |
| System contracts | Active network. Anyone signed in can search it. |

Contacts read your own account, pages follow your own sidebar, and users, entities and system contracts scope to the active organisation and network. Finding your own account by your own wallet address needs you to work as yourself.

Console search lists sidebar pages and five categories of records, and it shows a group only when it has a match:

- **Pages** lists up to eight sidebar pages: first those whose name holds every word you type, then those your words describe in other terms, so "what is waiting for me" lists Actions. It lists only pages the sidebar shows you.

- **Contacts** lists entries from your personal address book, which stay the same no matter which organisation is active. It still needs the active organisation to have a system to search against. See Troubleshooting if every category comes back empty.
- **Assets** lists tokens in the active organisation and network. When the participant you work as holds a system role that grants more than looking up accounts, reading identities and claims, and creating XvP settlements, you see every match. Otherwise you see only assets that one of that participant's wallets holds, or holds an operating role on, such as custodian or supply management, even with no balance. The asset admin role alone does not count. Every user sees the line "Assets your active wallet holds or manages." under the group, even when their role shows every match.
- **System contracts** lists platform-registered contracts on the active network, such as token factories and registries, alongside compliance modules, shown by their contract type and address.

The **On this page** group comes first. It lists the page's title-row actions, the actions in the asset's Actions menu such as freeze or approve, the page's tabs, and, once you type, the titles of its sections. Every word you type must appear in the label. A recent-asset row also matches the asset's name or symbol. Together, the two groups show at most eight rows. An asset action you cannot run, from the asset's Actions menu or a recent asset, is not a row: once your query names it, a line below the "On this page" and "Actions on recent assets" groups reads "Unavailable:" followed by the action and the reason. While the Console still checks what you can do, the line reads "Checking what you can do:" and names the action. A title-row button you cannot use is left out. Choosing a section closes the dialog, scrolls to it and outlines it briefly. Tabs under "More" are not listed, and neither are the actions or settings of a page you have not opened.

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

- For a page, an asset, a user, a contact, or an entity, confirm the Console opened the matching page.
- For a system contract, confirm the "Copied to clipboard" toast appeared, then paste your clipboard somewhere you can check it and confirm the address matches the result you selected.

## Troubleshooting [#troubleshooting]

**Search finds nothing for a term I expect to match**

Signal: a query for a setting, a form field, or a menu item on another page returns no result. Cause: search lists
sidebar pages by name, the open page's own actions, tabs and sections, and five categories of records: contacts,
assets, users, entities, and system contracts. It does not look inside pages you have not opened. Fix: search for the
page by its sidebar name, open it, then search again to reach its actions, tabs and sections.

**An asset I expect to see is missing**

Signal: a token you know exists, and that you believe you should be able to find, does not appear in results. Cause:
without a system role beyond the basic lookup permissions, as [What search covers](#what-search-covers) explains,
search shows only assets that the wallets of the participant you work as hold, or have an operating role on. While you
work as someone else, your own wallets do not count. Fix: switch **Working as** to the participant whose wallet holds
or manages the asset, select "Return to yourself" when it is your own, or ask a user with organisation-wide asset
access to run the search.

**I can't find a user**

Signal: a colleague or counterparty you know is registered does not show up under **Users**. Cause: user results need
your own role to include a user-search permission. Without it, that category never populates for anyone but yourself.
Fix: without that permission, you can still find your own account by searching your name, your email address or your
role name. The Console adds your own record, shown by your name, whenever the query matches one of them, regardless of
permission. Your full wallet address finds it too while you work as yourself. For anyone else, ask an administrator to
grant user search, or ask them to look the user up on your behalf.

**I can't find an entity**

Signal: a counterparty organisation or participant you know is registered does not appear under **Entities**. Cause:
this category needs the same entity-list access as the [Entities](https://docs.settlemint.com/docs/console/participants/entities) registry.
Without it, the category never populates, however exact the query. Beyond permission, names only match the
organisation's own participants: pasting the exact address of a multisig your organisation reaches through a signer
seat, or of a key that holds a current seat on that multisig, also finds it under its own name, while a name query
never does, and adding someone as a member alone does not make their wallets searchable. Fix: ask an administrator to
grant entity-list access, or open Entities yourself if you already have it, or ask a colleague with access to look the
record up on your behalf.

**An entity result cannot be selected**

Signal: a row under **Entities** is greyed out and does not respond. Cause: that participant has no wallet provisioned
yet, and entity detail pages are keyed by wallet address, so there is no page to open. Fix: open
[Entities](https://docs.settlemint.com/docs/console/participants/entities) and provision a wallet for that record.

**Every category comes back empty**

Signal: a query you expect to match something returns no groups at all, not even Contacts, which does not otherwise
depend on the active organisation. Cause: search needs the active organisation to have a system provisioned on the
active network. An organisation still being onboarded, or one you have switched to on a network it has no system on,
returns nothing for every category until that changes. Fix: switch to a network the organisation has a system on, or
finish onboarding it, then run the search again.

## Frequently asked questions [#frequently-asked-questions]

### Can I search using part of a name or address?

Mostly. Contacts, users, entities, and system contracts match your query as a substring anywhere in the record's name or address, so part of a wallet address or part of a company name is enough. Assets are the exception. A token's name or symbol still matches as a substring anywhere, but a token's address matches only from its start: type 0x followed by an even number of hex digits, or the full address. Without the leading 0x, a fragment matches token names and symbols but not token addresses. Your own account has a further exception, matching your name, email address or role name, covered under "I can't find a user".

### Does search find pages?

Yes. Pages come after the open page's own groups, "On this page" and "Actions on recent assets", under the heading **Pages**. Type any word of a sidebar page's name, or ask in your own words: "what is waiting for me" or "my pending approvals" lists [Actions](https://docs.settlemint.com/docs/console/essentials/actions), and "show my holdings" lists [Portfolio](https://docs.settlemint.com/docs/console/my-assets/portfolio). Search sets aside words such as "what", "is", "my" and "show", and lists a page when each remaining word matches its name or one of its search words. Search lists only the pages the sidebar shows you, so a page you cannot open does not appear.

### Can search start an action on an asset I opened earlier?

Yes. Search remembers the last five assets you opened. Type an action such as "mint" and the **Actions on recent assets** group lists matches like "Mint tokens on NWC". Choosing one opens the asset and the same sheet its Actions menu opens. The page checks your role and the asset's state again first, so when the Actions menu would refuse the action, you see its reason in a message instead of a sheet. The group stays hidden until you type, and it leaves out the asset you are already on.

### Can I ask the assistant a question from search?

Yes, when your organisation has the assistant on and the page has something to ask about. Search then shows an **Ask** row, and [Ask](https://docs.settlemint.com/docs/console/essentials/ask) describes how to question the assistant, keep the conversation open beside the page and read its sources.

### Does search cover transactions or on-chain events?

No. Search covers only pages, contacts, assets, users, entities and system contracts, so a query for a transaction hash or an event name returns nothing here. Open [Activity](https://docs.settlemint.com/docs/console/essentials/activity) instead, where **Search activity** matches an event name or a transaction hash.

### Can I search across every organisation I belong to in one query?

No. Assets, users and entities scope to the active organisation and network, so the same query in another organisation can return different matches. Contacts belong to your account, so the same address book returns in every organisation.

### Do I need to press Enter to run the search?

No. The query runs on its own, about 300 milliseconds after you stop typing. Enter chooses the selected result, as a click would. The dialog selects the first result when results load, so Enter opens or copies that top result. Press the down arrow first to choose another.


# Submissions

Source: https://docs.settlemint.com/docs/console/essentials/submissions
Follow each write you submit through its phases, undo or cancel it while that is possible, and read what to do when it fails.

The **Submissions** button in the top bar opens a tray that follows every write you submit, from the moment you confirm it until the indexer has processed the resulting transaction. The tray is available on every private page and keeps working when you move to another page, so you can start the next task while the last one finishes.

A submitted operation moves through the tray in order: preparing, awaiting approval or signing, submitting, confirming and indexing, then it reports **Complete**. A submission can also end early as "Still processing", "Failed" or "Cancelled", from any live phase. A submission the platform stopped waiting for that can still go through reads "May still go through". Undo appears only for an operation that shows its result on screen before the chain confirms it. It is available while that operation is preparing, awaiting approval or signing, and never while a custody provider holds the request.

![The Submissions tray open over Dashboard, with the All, Needs review and In progress tabs](https://docs.settlemint.com/docs/screenshots/console-submissions-tray.light.en.webp)

[Screenshot] The "Submissions" tray shows each submission you sent with its current phase.

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

- You must be signed in and onboarded.
- The tray lists the submissions started in this browser, plus up to 200 of your transactions that the platform still reports as in flight, which a newly opened tab loads.
- Work you started in another browser therefore shows while it runs, but a failed submission shows only in the browser that recorded it.
- The button shows how many submissions need review and how many actions wait for you, and its tooltip also counts the submissions in progress.

## Steps [#steps]

### Open the tray [#open-the-tray]

Select **Submissions** in the top bar. The tray has the tabs "All", "Needs review" and "In progress". While the tray holds no submission, the "All" tab reads "No submissions yet" and "Needs review" reads "No submissions need review".

While work waits for you on [Actions](https://docs.settlemint.com/docs/console/essentials/actions), a link above the tabs reads, for example, "3 actions waiting for you" and offers **Open actions**. Those are work items waiting on you, not your own submissions.

### Read the phase of a submission [#read-the-phase-of-a-submission]

[Figure] A submission passes through the tray phases before Activity lists its event. A submitted operation tracks through its live phases in the Submissions tray, an overlay fixed above every private page. The phases run in order: preparing, then awaiting approval or signing, then submitting, then confirming, then indexing, then complete. Undo is offered while preparing, awaiting approval, or signing, and is gone once submitting starts. A transaction that is Completed on chain shows as Indexing, and becomes Complete when the indexer confirms the event. Still processing, may still go through or failed can end the sequence early, from any live phase. After completion, check Activity for matching indexed events under the intended participant and network. Labels: Submissions tray, live on every page; Preparing; Awaiting approval, then Sign in wallet; Submitting; Confirming on-chain; Completed maps to Indexing; Not Complete until the indexer confirms it; Indexing; Complete; Any live phase can also end as; Still; processing; May still; go through; Failed; After Complete,; check the matching; event.; Activity page, history only; Find the matching indexed event; Active participant and network.

The tray shows **Indexing** while the platform waits for the indexer to process the confirmed transaction. Activity lists indexed events and no pending submissions.

### Act on a submission [#act-on-a-submission]

Each write you submit appears in the tray with its phase and a line that tells you whether you can leave the page, such as "Confirming on-chain. Safe to leave this page."

- **Progress.** While a phase runs, the row shows the time since you submitted. Once the platform has accepted the request, the row also shows "Step n of 6". The six steps are preparing, signing, submitting, confirming, indexing and "Complete", and awaiting approval shares the signing step. Where the platform reports them, the row also shows the confirmations counted against the number required, such as "2/12 confirmations", and how many blocks the indexed view runs behind the chain. A mint, burn, transfer or forced transfer started in this browser tab names the amount it moves under the asset, such as "10 BND".
- Waiting labels: **Awaiting approval** means an approver holds the request. It reads "Awaiting" followed by the provider's name and "approval" when a custody provider holds it. The name is the provider the custody configuration was added as, so a request held by a configuration added as IBM Digital Asset Haven reads "Awaiting IBM Digital Asset Haven approval". A held row also shows when the approval expires and, when the provider reports a count, the approvals it has counted against the number it needs, such as "1 of 2 approved", in the language of the page. Once the deadline has passed at a provider that cannot withdraw the request, the row says the request is still open there and must be rejected in the approval console of that provider. "Waiting for funds" means the wallet that pays for the request cannot cover the fee. The request continues on its own once the funds arrive, as [Transaction funding](https://docs.settlemint.com/docs/console/organisation-settings/transaction-funding#fund-an-open-request) describes. "Recorded on-chain" means the platform is rebuilding its indexed data and your lists catch up on their own.
- Details: **Details** opens the submission's details sheet. While the platform is still working on the request, its "Current status" and the line under its title read the same as the row, such as "Awaiting" with the provider's name and "approval", or "Cancelling" after you asked to withdraw a held request. Once the platform reports the request complete, the sheet reads "Completed", also while the row still shows "Indexing".
- Cancelling: the tray offers **Cancel** from the moment the platform accepts the request until it confirms, except while you sign it in your wallet. An operation that offers "Undo" shows "Undo" instead. A dialog states the cost before you confirm. Before the request reaches the network, nothing has been sent and cancelling costs nothing. After it is sent, a replacement transaction cancels it, and that costs gas. For a request that a custody provider holds, the platform withdraws the approval request at the provider, and the tray offers "Cancel" only where the provider supports that. The platform can still refuse a cancellation, and the message then starts "Could not cancel." and gives the reason. [Transaction lifecycle](https://docs.settlemint.com/docs/concepts/settlement/transaction-lifecycle#running-the-queue-day-to-day) explains the replacement.
- Server adjustments: the Console can show a result before the chain confirms it. When the confirmed record differs, the settled row lists the fields that changed under **Adjusted by the server**. The marks stay visible when your system asks for reduced motion.
- **Failures.** A failed row names the next step: "Try again", "Edit and retry", "Top up and retry", "Top up and edit", "Check status" or "Contact support to resolve." When the platform cannot tell whether a submission went through, the row reads "Outcome unknown" and the details sheet tells you not to retry until the outcome is confirmed.
- **May still go through.** The platform stopped waiting for the request, but a custody provider still holds it or the network may still include it. The row shows no step and says not to try again until you have checked the request in the custody provider console or on the network. Where you may read it, the row and the details sheet show the platform's reason in English. When the platform settles the request, the row moves to Complete or Failed. If the row has not changed, open "Details" to read the latest status.
- **Several operations.** Two or more submissions of the same action, such as several mints, collapse into one expandable row named after that action, with a count for each phase. A different action, such as "Create asset", keeps its own row and never counts toward another action's row. A page refresh keeps in-flight work in the same browser tab and checks each operation against the platform's status. Other open Console tabs show the same phase. The operation you started last follows its status live. Any other submission still in flight checks its status every 10 to 15 seconds, so many pending submissions never slow the rest of the Console. Screen readers hear each phase label once, as a polite announcement, and the elapsed time is not announced.

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

- Wait until the tray reports **Complete**, then find the matching indexed event on [Activity](https://docs.settlemint.com/docs/console/essentials/activity) under the participant and network you used.

## Troubleshooting [#troubleshooting]

**The tray shows Indexing for longer than expected**

Signal: an operation reads as complete elsewhere but the tray stays on "Indexing". Cause: the tray shows "Complete"
only after the indexer confirms the event, so a transaction confirmed on chain reads "Indexing" for a short while.
Fix: wait for "Complete". If the tray stays on "Indexing" well past the usual delay, select **Try again** where the
tray offers it.

**The tray says May still go through**

Signal: the row shows "May still go through". Cause: the platform stopped waiting for the request, but the request can
still run, for example because a custody provider holds the order. Fix: check the request in the custody provider
console or on the network. Let it run or stop it there. Do not submit it again while it can still run.



# Console

Source: https://docs.settlemint.com/docs/console
Every Console screen, grouped the way the Console sidebar groups it, with what each group is for and where its pages start.

The Console is where an organisation issues, operates and oversees its assets, with one sidebar group for each area of work. Your Console lists only the groups that your roles, organisation settings and add-ons allow, so it can show fewer groups than the cards here. Each page in a group documents one screen, and names at its top the Console path that opens it and the roles that can open it.

Two kinds of role open screens. The organisation role, Owner or Member, opens the owner screens, such as the organisation's general settings. Most other screens open from an on-chain role that a **Permission manager** grants in [Roles and permissions](https://docs.settlemint.com/docs/console/organisation-settings/admins-and-roles). Being the owner does not grant an on-chain role.

What a screen shows depends on who you are working as. The account menu at the top right names the organisation. While you work as another participant, it reads **Working as** and that participant's name. Actions and new transactions then belong to that participant, and Portfolio shows only its holdings. Switching reopens the page you are on in the new context. [My participants](https://docs.settlemint.com/docs/console/my-account/acting-as-participants) covers the switch.


  - [Dashboard, Actions and Activity](https://docs.settlemint.com/docs/console/essentials): The Dashboard, Actions and Activity, with the submissions tray, search and the assistant.
  - [Wealth](https://docs.settlemint.com/docs/console/my-assets): What the participant you work as holds and can acquire, from Portfolio to Votes.
  - [Personal](https://docs.settlemint.com/docs/console/personal): Your private contacts and watchlists, and the saved views you keep or share.
  - [Assets](https://docs.settlemint.com/docs/console/asset-management): Issue an asset, operate any asset the organisation issued and register external tokens.
  - [Asset lifecycle](https://docs.settlemint.com/docs/console/asset-lifecycle): Offerings, trading venues, escrows, add-ons and the bank rail, for work with many holders.
  - [Organisation participants](https://docs.settlemint.com/docs/console/participants): The organisation's users, entities, KYC profile sections and the agents that act for it.
  - [Asset design](https://docs.settlemint.com/docs/console/asset-design): The Asset design group of the Console sidebar: the product shapes an issuer picks from.
  - [Compliance](https://docs.settlemint.com/docs/console/compliance): The rules, topics, issuers and providers that decide who may hold and move an asset.
  - [Reporting](https://docs.settlemint.com/docs/console/reporting): Obligations, filings, the anchor registry, statements, daily reports and the audit trail.
  - [Organisation settings](https://docs.settlemint.com/docs/console/organisation-settings): General settings, roles, theme, assistant, custody, networks, funding, feeds and webhooks.
  - [Platform admin](https://docs.settlemint.com/docs/console/platform-admin): The seven screens that act on the whole platform, shown only to a platform administrator.
  - [Account menu](https://docs.settlemint.com/docs/console/my-account/profile): Your profile and KYC, security, API keys and participants, opened from the account menu.



# My participants

Source: https://docs.settlemint.com/docs/console/my-account/acting-as-participants
View every participant you can work as, switch which one your actions apply to, and create a new participant when your organisation needs one.

**My participants** lists every Participant you can work as and lets you switch which one your wallet work applies to. It is also where you create a new participant. Your own account is a participant, and so is every other wallet, person record or organisation record shared with your account.

Switching changes whose wallet you act for. Your entitlement decides which participants you may enter, and once you are in, the action runs with that participant's roles and the record names you as the person who acted. This split is Delegated Authority. Registering a participant in another organisation is on its [participant page](https://docs.settlemint.com/docs/console/my-account/participant).

![My participants page with the You section, an empty participants list and a Create participant button](https://docs.settlemint.com/docs/screenshots/console-my-account-acting-as-participants.light.en.webp)

[Screenshot] The "You" section lists your own identities, each with "Work as" and "Make my default", or the "Your default here" and "Working now" markers on the one in use.

Below it, "Organisation and shared participants" shows the "No participants" empty state, and the **Create participant** button sits at the top right.

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

- You can work as another participant only when you already hold a way in: a seat as signer on its wallet, or, for the organisation's own participant, the organisation's Identity manager role or the Permission manager role on the wallet you act from. This page shows those participants and grants none.
- "Create participant" appears once your active organisation has a system the Console can read.
- The sheet sets the wallet type, or lets you choose one when the **Self-custody** module is on for your organisation and your organisation uses advanced accounts.
- A weighted multisig also needs an EOA or single-sig participant of your own, already in that organisation, to seat as its first signer.

## Steps [#steps]

### Open My participants [#open-my-participants]

The account menu sits at the right end of the Console's top bar. Its button shows the active organisation's name, and under it your own name, or "Working as" followed by the participant's name while you work as anyone other than yourself. When the top bar is narrow, the button shows only the avatar. While you work as someone else, the button turns violet. Select it, then select **My participants**. This works from any screen, even when you have a single participant. In the same menu, "On-chain identity" opens the identity tab of the participant you work as.

When you can work as more than one participant, or while you work as someone else, the menu also has a **Working as** submenu. Point at "Working as" to open it. A card at the top names the participant you work as, with a "Search participants" field under it. While you work as someone else, "Return to yourself" comes next. Up to three participants you switched to recently in this organisation, in this browser, follow under "Recent", then the others under "Participants". A participant you cannot work as is dimmed, and selecting it shows why. The submenu leaves out multisig wallets: each one you sign for opens as its own account under "Shared accounts" in the sidebar. "View all participants" at the bottom opens "My participants".

**My participants** lists your own identities under the "You" heading, then the participants you can work as under the "Organisation and shared participants" heading. That table has these columns:

- **Name**
- **Type**
- **Your role**
- **Identity address**
- **Identity**
- **Actions**

The participant you work as carries a **Working now** badge.

### Switch the active participant [#switch-the-active-participant]

Select **Work as** on the row of the participant you want, or select the participant in the "Working as" submenu of the account menu. The Console reloads the page you are on for the selected participant. If that page cannot show for the selected participant, the Console opens the nearest parent page that can. While you work as anyone other than yourself, a violet "Working as" bar opens every page with the participant's name and "Return to yourself". While that bar shows, Portfolio, Activity, search and role checks use the selected participant's wallets alone, so a screen your own role opens can be unavailable until you return to yourself. A multisig where you hold a signer seat is the exception: you keep opening it, reading its signers and co-signing its approvals through your own seat. Check that bar before reading holdings or submitting an operation.

Switching does not change your account settings or your active organisation. It does change the participant your API keys act for: a key request without an `X-Participant` header uses your current choice within 30 seconds.

To return to yourself, select **Return to yourself** on the violet bar, or in the "Working as" submenu. The Console sets your own participant active again in one step. The bar disappears, and the account menu button is no longer violet and names you.

Most action sheets start with a **From** line that names the account the transaction runs from. While you work as yourself it shows your name and "your own wallet". While you work as someone else it shows that participant's name and type on a violet strip, and for a multisig wallet it adds the signer weight the wallet needs against its total signer weight, such as "needs 2 of 3". When the sheet cannot load the participant, it says so and asks you to close the sheet and open it again.

When you work as a multisig wallet, the sheet also shows a **How this is signed** panel before the submit button. It says how many signatures the wallet needs and whether your signature is enough, shows how much of the threshold your signature covers, and lists each signer. Your own seat reads "You" and "signs now". A signer the platform manages reads "asked to co-sign", and an external address reads "signs outside the platform". A wallet with weighted signers shows each signer's weight. When your signature is not enough, the submit button reads "Sign and request" followed by the number of co-signatures still needed, and the other signers co-sign from "Actions" before the transaction runs.

Note (Work as can be unavailable, and the reason is specific): A participant can appear in the table but stay unavailable to work as. Its row still shows **Work as**, disabled, with the reason written beside it. ["Work as" is disabled and I do not understand the reason](#act-as-is-disabled) covers each reason and what it needs.

## Make a participant your default [#make-a-participant-your-default]

A person participant of yours that is not your default offers **Make my default** on its row. Once you select it, the row shows "Your default here".

## Create a participant [#create-a-participant]

1. Select **Create participant**. The "Add participant" sheet opens.
2. Enter an optional **Display name** and choose a wallet type if the sheet offers one, as [Choose a wallet type](#choose-a-wallet-type) describes.
3. Pick the **Key** that signs for the participant's wallet. The key list holds the custody providers your organisation set up for the active network, among those your deployment enables. Each key option names the provider its configuration was added as, followed by "(this organisation holds the key)" or "(the person holds the key)".
4. Select **Create participant**.

An EOA or Smart wallet participant provisions once you confirm, though its custody account can still be settling at the custody provider. When that happens, the Console reports "Participant created. Its custody account is still settling and is not usable yet." When the person holds the key, the participant stays inactive until that person, its owner, connects the wallet and signs the proof of control.

![Add participant sheet with the Display name field, the Smart wallet type selected and the Key picker](https://docs.settlemint.com/docs/screenshots/console-my-account-acting-as-create-participant.light.en.webp)

[Screenshot] The "Add participant" sheet shows an empty "Display name" field, the "Smart wallet" type selected and the "Key" picker.

## Create a multisig participant [#create-a-multisig-participant]

1. Select **Create participant** and choose "Smart wallet with signers".
2. In the **First signer wallet** picker, pick which of your own eligible accounts becomes the first signer. The picker reads "None of your wallets can sign in this organisation" if you have none.
3. Select **Save draft and continue** to open a draft. Nothing is on-chain yet. The Console reports "Draft saved.", and the draft appears in the "Multisig drafts" section of "My participants", where "Resume" opens its signer editor and "Delete" discards it after asking.
4. Add the rest of the signers. **Add one of your wallets** adds an account of your own, after you set its "Signing weight". "Add platform signer (invite link)" invites a person with a platform account. "Add external signer (address)" adds a bare address that never has to accept anything.
5. Set the **Threshold**. Leave it unset and the draft deploys requiring every seated signer to sign.
6. Select **Create multisig · N of M**, where N is the draft's threshold and M its seat count.

The invite dialog takes a signing weight and an optional delivery email. It shows the invite link once, so save it before you close the dialog. The invite lasts seven days, and you can revoke it while it is pending. After seven days unused, the invite expires: its row reads **Expired** with no weight, it no longer blocks "Create multisig · N of M", and the wallet deploys without that seat. Clear the row with its remove button. An invited signer joins outside the create sheet, through the invite link you send them, which leads to an accept page in the Console.

**Create multisig · N of M** becomes available once the seated signer weight can reach the threshold and no invite is still pending. The check counts every seated signer's weight, including an external address that never signs through the Console. So "Create multisig · N of M" can become available while you and your invited signers hold too little weight to reach the threshold. The Console then shows a warning but does not block the step. Add more of your own or invited signers before you finalise.

"Create multisig · N of M" also waits for the Console to read the custody providers of the active network, because the new wallet's custody account is opened with one. If that read fails, the draft says "The custody providers could not be loaded, so the smart wallet cannot be created." with a "Retry" button. If no custody provider serves the network, it says "No custody provider serves this network, so the smart wallet cannot be created." Set up a custody provider for the network first.

**Create multisig · N of M** deploys the multisig on-chain, and the deployment cannot be undone. It too can leave a custody account still settling. When that happens, the Console reports "Multisig · N of M created. The custody account of its signer is still settling." The multisig stays unusable until that finishes.

[Figure] How a multisig draft reaches deployment. A multisig draft opens with its creator seated as the first signer. More signers join by adding an existing account, sending an invite link, or adding an external address. An invite is accepted on its own accept page, opened from the link, or the creator revokes it, and either way the draft updates once that is resolved. The draft can finalise only once its signer weight can meet the threshold and no invite is left pending. Finalising deploys the multisig on-chain, and the deployment cannot be undone. The creator can delete the draft instead, at any point before it finalises. Labels: Draft opened; creator seated as first signer; Signers added; own account, invite, or address; Threshold achievable; and no invite left pending; Finalised; deployed on-chain, permanent; signer seated; threshold reachable; finalise; Invite pending; signer opens the invite link; joins, or the creator revokes it; Draft deleted; creator only, while still open; invite sent; joins; delete draft.

A multisig draft opens with its creator as first signer, can finalise once the threshold is reachable with no invite
pending, and can be deleted by its creator before it finalises.

## Choose a wallet type [#choose-a-wallet-type]

The basic wallet type depends on your organisation, and you cannot change it from the sheet. It is "EOA", an externally owned account, when advanced accounts are off, and "Smart wallet", a single-key smart account, when they are on. Advanced accounts is the organisation setting that gives participants smart wallets.

When the **Self-custody** module is on for your organisation, the "Add participant" sheet also offers "Smart wallet with signers", a weighted multisig. It needs advanced accounts, and without them the sheet shows it as unavailable. When the module is off, the sheet shows no choice, only a note that names the one type.

| Wallet type | When the sheet offers it | What you get |
| --- | --- | --- |
| EOA | Your organisation has advanced accounts turned off. | A wallet address with no smart-wallet features. |
| Smart wallet | Your organisation has advanced accounts turned on. | A single-key smart account, provisioned through your organisation's paymaster. |
| Smart wallet with signers | The "Self-custody" module is on for your organisation and your organisation has advanced accounts turned on. With advanced accounts off, the option reads "Needs advanced accounts. Turn on advanced accounts for this organisation to create a smart wallet with signers." Choose it when more than one party must agree before a transaction executes. | A smart account that signs once its seated signers reach the threshold. |

A participant's wallet type is fixed at creation. The Console has no control that converts an EOA into a smart account or a single-sig into a multisig. Correcting a wrong choice means creating a new participant, and the old one keeps its own history. This page has no delete or archive control for a participant you created. Only a multisig draft can be deleted, by its creator, before it is finalised.

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

- Selecting "Work as" reloads the page you are on for the new participant, so "My participants" stays open.
- The participant you switched to now carries the **Working now** badge in place of its "Work as" button, and its identity tab, holdings, and any pending items reflect it rather than the participant you worked as before.
- A participant you created appears under "Organisation and shared participants".

## Troubleshooting [#troubleshooting]

**Work as is disabled and I do not understand the reason**

The reason names what is missing. "No wallet, so you cannot work as this participant" means the participant has no
wallet that can act in this organisation. "No smart wallet, so you cannot work as this participant" means an
organisation participant has no smart wallet yet, in an organisation that uses advanced accounts. "Holds 2 signing
keys. Revoke all but one, or use lost-wallet recovery, to act as this participant" means the participant signs
directly and holds more than one live key, so none of them is the address that can act for it. On your own
participants in the **You** card, the reason can instead say why their wallet cannot sign here, for example "This
organisation can sign for too few of this smart wallet's signers to reach its threshold."

**A participant I manage has no identity contract**

Identity provisioning is a separate step that runs right after a participant is created. A transient failure can leave
the participant record without an identity contract. Open that participant's identity tab, which explains the gap and
offers **Create identity** to provision the missing identity.

**I cannot add signers to a multisig draft**

If the "First signer wallet" picker shows "None of your wallets can sign in this organisation" and does not let you continue, you have no EOA or single-sig participant of your own in this organisation. Create one first, then start the multisig again. It becomes the first signer.

If you already have signers seated but **Create multisig · N of M** stays disabled, an invite is still pending. It resolves when the person you invited opens the invite link and joins, or when you revoke it. An invite link expires after seven days. An expired invite reads "Expired", no longer blocks "Create multisig · N of M", and leaves its seat empty.

For an expired invitation, clear the row with its remove button and send a new invite. For a lost link on a pending invite, revoke it and send a new one. A valid pending invitation can still be accepted. Check with the signer before replacing it. An invite link is shown once, at the moment you create it, so revoke and re-invite rather than trying to recover a lost one.

**A participant I expect to see is missing from the table**

This table lists only the participants you hold a way into, not every participant that exists. Ask the participant's
owner to seat you as a signer on its wallet, or an organisation owner to give you the role that reaches it. This page
has no control that grants access to a participant you cannot already see.

**Can I undo creating a participant or registering it in an organisation?**

Only a multisig draft. Its creator can delete it before finalising, and nothing of it remains. A deployed multisig and
every other participant you created stay, and this page has no control that removes them. An identity manager can
remove a registration with "Remove registration", as [On-chain
identity](https://docs.settlemint.com/docs/console/my-account/onchain-identity#register-change-or-remove-a-registration) describes.

**A button is disabled and says the role sits on another participant**

The role for the action sits on a wallet that belongs to a participant you can work as, so the button is disabled
while you work as someone else. Point at or select the button. The reason names that participant and offers **Work
as** followed by its name. Select it and the Console switches to that participant on the same page. When the
participant is a multisig wallet, the reason also gives its signing threshold, and the action you take there waits for
the other signers. When you cannot work as the participant, the reason says the participant is not available for
actions, and when no participant of yours owns the wallet, it names only the wallet address.

## Frequently asked questions [#frequently-asked-questions]

### Can I work as two participants at the same time?

Not from Console browser tabs, since they all share one active participant for the session. **Working as** two at once needs the Platform API, where each request names its participant in the `X-Participant` header and concurrent requests can name different ones. [Delegated Authority](https://docs.settlemint.com/docs/concepts/compliance-and-identity/delegated-authority) explains how a request names its participant.

### What happens if my access to the active participant is revoked while I am using it?

The platform checks your access on every request, so a revocation takes effect on the first request after the platform sees the change. A screen that only reads data then loads for your default participant, which is you unless you made another participant your default, and the Console moves to it. A notice titled "You can no longer work as" followed by the participant's name tells you that you lost access, and reads "You can no longer work as this participant" when the Console has no name for it. An action that changes data for the participant you lost access to does not run. A dialog with the same "You can no longer work as" title says "You lost access to this participant, so the action did not run and nothing was sent." and offers **Continue as yourself**. Select it. Before you run the action again, check that it should still run for the participant the account menu now names. The platform records the refusal in the audit trail. Through the API, a read that names a participant you lost answers in your own context with an `X-Participant-Dropped` response header, and a write returns `DALP-0524`.

### Does creating a participant make it the one I work as?

No. Creating a participant adds it to your list. To work as it, select **Work as** on its row once it is ready.

### What do the Type and Your role columns show?

The "Type" column reads one of three values:

- **Person**: your own participant, a participant you create with "Create participant", or a person you work as through a wallet you sign for.
- **Multisig wallet**: a deployed multisig, which never shows "Person". The same label appears on its page under "Shared accounts".
- **Organisation**: the active organisation's own record.

The "Your role" column reads one of four values:

- **Owner**: a "Person" row your account holds, including your own participant.
- **Signer**: a "Person" row you reach through a wallet you sign for, and every "Multisig wallet" row.
- **Identity manager**: only the "Organisation" row.
- **Admin**: only the "Organisation" row.

### Why does the Organisation row show Identity manager instead of Admin?

The list shows the "Organisation" row when you hold the organisation's identity manager role, its administrator role, or both. With both, **Your role** reads "Identity manager". With the administrator role alone, it reads "Admin". For what each role lets an operator do, see [Delegated Authority](https://docs.settlemint.com/docs/concepts/compliance-and-identity/delegated-authority).

### Do I need to finish setting up a multisig participant in one sitting?

No. An open draft keeps its state, and **Resume** in the "Multisig drafts" section of "My participants" reopens it in a later session. Nothing deploys until you finalise. A stale draft can need a revoke and a new invite before "Create multisig · N of M" is available.


# API keys

Source: https://docs.settlemint.com/docs/console/my-account/api-keys
Create and manage the API credentials that authenticate Platform API requests on your behalf, without a signed-in Console session.

API keys is where you create and manage the [API credential](https://docs.settlemint.com/docs/api-reference/guides/authentication-api-keys) values that let a script, service, or integration call the Platform API as you, without a signed-in Console session. Use this page to connect an external system to the platform, to limit what one integration can do, and to end an integration's access when it is retired. A key belongs to one organisation, your role there decides what it can do, and the key's scope sets only whether it can read, or read and write. Send the key in the `X-Api-Key` header. The platform does not accept it as a bearer token.

Your own sign-in and your wallet's signing authority are on [Security](https://docs.settlemint.com/docs/console/my-account/security): the PIN, recovery codes, two-factor authentication, passkeys and sessions. Scope enforcement, the rate limit and the errors a request can return are on [Authenticate with API keys](https://docs.settlemint.com/docs/api-reference/guides/authentication-api-keys).

![API keys page with three active keys in a table and a Create API key button](https://docs.settlemint.com/docs/screenshots/console-my-account-api-keys.light.en.webp)

[Screenshot] The table lists three keys with "Name", "Scope", "Status", "Created" and "Last used" columns, and a masked preview of each key under its name.

Two keys are "Read only" and one is "Read & Write", all "Active" and not used yet. The table toolbar holds a search box and a "View" control that reports two hidden columns, and the page header has the "Create API key" button.

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

- Set up a transaction PIN on [Security](https://docs.settlemint.com/docs/console/my-account/security) if you do not have one. The Console cannot create a key until you have a transaction PIN or a transaction code and a confirmed set of recovery codes. Until then, "Create API key" opens the setup wizard.
- If your deployment requires two-factor sign-in and your account signs in with a password or passkey, the platform refuses to create a key, or to widen one, with `LOGIN_TWO_FACTOR_REQUIRED` until you set up two-factor sign-in on [Security](https://docs.settlemint.com/docs/console/my-account/security). This applies in the Console and to `dalp login`. On a deployment with no identity provider configured, the Console sends you to set up two-factor sign-in before it opens any page. An account linked only to your identity provider, with no password or passkey, is exempt.
- Switch to the organisation the key is for from the Organisation submenu of the account menu at the top right. The key stays with that organisation, and the Console has no control that moves an existing key to another organisation, so a second organisation needs its own key.
- Decide the key's scope and expiration first: [Choose a scope and an expiration](#choose-a-scope-and-an-expiration) compares the options. You can change both later with **Edit key** until the key expires, and the key value stays the same.
- A key can act for you without a sign-in, so the Console asks you to confirm each new key with your transaction code, your identity provider code when you hold that authenticator instead, or your transaction PIN when you hold neither. Every new key sends you a security email. No key can be created during a cooling-off period, the hold on your signing that [Security](https://docs.settlemint.com/docs/console/my-account/security) describes.

## Steps [#steps]

### Create a key [#create-a-key]

Select **Create API key** and enter a name of up to 32 characters that identifies the integration. Once the name reaches 26 characters, the field shows a count against that limit. A longer name, typed or pasted, is refused with "That is over the 32-character limit, so nothing was changed." instead of being cut. Spaces at the start or end of the name are not saved, and a name of only spaces shows "This field is required". Then set the scope and expiration you decided on. The sheet opens on "Read & Write" and "Never", so confirming without touching either control creates the widest, longest-lived key the Console offers. Select "Create API key", then confirm with your transaction code, your identity provider code when you hold that authenticator instead, or your transaction PIN when you hold neither.

![Create API key sheet with an empty name field, Scope set to Read & Write and Expiration set to Never](https://docs.settlemint.com/docs/screenshots/console-my-account-api-keys-create.light.en.webp)

[Screenshot] The "Create API key" sheet shows an empty "Name" field, "Scope" set to "Read & Write" and "Expiration" set to "Never".

The sheet reads "Generate a new API key for programmatic access." and notes what each scope allows. "Cancel" and "Create API key" sit at the bottom of the sheet.

### Copy the key value now [#copy-the-key-value-now]

The Console shows the full key value once, in the **API key created** dialog, with a copy button. Copy it into the integration or secret store that uses it before you close the dialog.

Note (The full key value is shown once and cannot be retrieved again): After you close the creation dialog, the Console shows only a masked preview of the key. Store the value now. If you closed the dialog first, revoke the key and create a replacement.

## Review your keys [#review-your-keys]

The table lists your keys for the organisation you are working in, with their name, scope, status, creation date, and last-used date. The status is "Active", "Disabled", or "Expired". Each name shows a masked preview of its key value underneath. The "Key" column, which repeats that preview, and the "Expires" column are hidden at first. Show them from the table's column settings. Under the page description, "API reference" and "OpenAPI document" open your deployment's own API documentation in a new tab.

## Edit, enable, or check a key [#edit-enable-or-check-a-key]

Open the row menu on a key. **Edit key** changes the name, the scope, and the expiration, and keeps the key value and its organisation. A new expiration counts from the day you save it, and "Keep current" leaves it as it is. Extend a key before its expiration date: once it expires, the platform deletes it at its next cleanup. A rename saves without your PIN or code. Changing the scope or expiration asks for your transaction code, your identity provider code when you hold that authenticator instead, or your transaction PIN when you hold neither, and the platform emails you about the change.

A key whose status is "Disabled" does not authenticate. Choose **Enable** in the row menu to turn it back on. "Enable" always asks for your transaction code, your identity provider code when you hold that authenticator instead, or your transaction PIN when you hold neither. The platform deletes keys that have expired at its next cleanup, so an "Expired" row leaves the table. Create a replacement for it.

Expand a row to see **Requests left**. Every key you create here has no request limit and shows "Unlimited". A key that the platform has given a request limit shows the requests left in its current counting window and, under "Resets", when the count starts again, or "Full budget available" when no window is running. A key with a fixed request total shows what remains of that total. [Authenticate with API keys](https://docs.settlemint.com/docs/api-reference/guides/authentication-api-keys#rate-limit) explains how the window counts.

## Revoke a key [#revoke-a-key]

A revoke cannot be undone, so create a replacement before you revoke a key an integration still needs. Open the row menu on a key and choose **Revoke**. The Console asks "Are you sure you want to revoke" followed by the key's name, and warns that any application using the key loses access. Confirm to revoke it. The Console reports "API key revoked successfully." and the row leaves the table. Requests with the key stop authenticating within 30 seconds.

## Choose a scope and an expiration [#choose-a-scope-and-an-expiration]

A key belongs to one organisation. The Console issues the key for the organisation you are working in, and the platform resolves every request the key makes through that organisation. What the key can do there depends on your own role in that organisation. The key's scope sets only whether it can read, or read and write. Your keys are private to your account: another member of your organisation never sees them in this table.

A key acts for the participant your account is working as in this organisation. Without an `X-Participant` header, a key request follows your current **Working as** choice in the Console and picks up a change within 30 seconds. Send `X-Participant` on every request from an integration that must not move.

**Read only**

Can call only the routes the Platform API declares as reads, within your role's permissions. Any route that creates, updates, or deletes data refuses it, whatever HTTP method the request sends. Choose it for reporting, monitoring, or any integration that only reads data: a bug in that integration's code cannot turn into a write.



**Read & Write**

Can do everything your role allows in the organisation, on every route that accepts an API key. A request made with a key is not asked for wallet verification, so a Read & Write key signs transactions from your wallet without your PIN or transaction code. Treat its value like your PIN and your session together. Choose it only for an integration that creates, updates, or cancels something. A script that only pulls reports gains nothing from write access and carries more risk if the key leaks.

| Expiration | What it costs | Choose it when |
| --- | --- | --- |
| Never | The key keeps authenticating with no deadline. A leaked or forgotten key stays valid until you revoke it, and time alone never stops it. | You watch the key's "Last used" date and the [audit trail](https://docs.settlemint.com/docs/console/reporting/audit-trail), and you revoke the key yourself. |
| 30, 60, or 90 days | The key fails on that date with the same authentication error as an invalid key. Issue and deploy the replacement before then, or the integration stops. | The integration's owner reviews and rotates its keys on a schedule, and a fixed deadline enforces that schedule. |
| 1 year | The same fixed-date failure as the shorter options, further out. A leaked key stays valid for up to a year unless someone revokes it sooner. | The integration is long-running and low-risk and is reviewed once a year, so a 90-day rotation would only add work. |

Choose an expiration that matches the integration's rotation schedule. Record who replaces the key before that date.

## When your keys stop or keep working [#when-your-keys-stop-or-keep-working]

Some changes to your account act on your keys without any step on this page:

- Changing your password on [Security](https://docs.settlemint.com/docs/console/my-account/security), resetting it through the emailed link, or having a platform administrator set it for you turns off every key you hold, in every organisation. The keys stay in the table as **Disabled** until you enable them again. If the platform cannot turn them off, it refuses the new password and your old one stays in place, so a password change never leaves your keys on.
- Leaving an organisation, or being removed from it, stops your keys for that organisation within 35 seconds. Their rows do not change.
- During the cooling-off period after a wallet security change, your keys keep authenticating and reads keep working, but every request that signs a transaction returns 403 `WALLET_VERIFICATION_HELD` (`DALP-17440`) with `heldUntil` until the period ends. Retry after that time. No key can be created or turned back on, and no key's scope or expiration can change.
- A platform administrator banning you stops your keys within 30 seconds until the ban ends. Closing your account stops them for good.
- A platform administrator can revoke every key you hold, in every organisation, from your account page under Platform admin › [Platform users](https://docs.settlemint.com/docs/console/platform-admin/users#revoke-a-persons-api-keys). The keys stop within 30 seconds and leave your table. They cannot be turned back on, so create new ones if you still need API access.
- A platform administrator ending your sessions leaves your keys working. To end a member's API access in one organisation, an organisation owner removes the member from the organisation, which stops their keys for it within 35 seconds.

## Create a key from code or the command line [#create-a-key-from-code-or-the-command-line]

[Authenticate with API keys](https://docs.settlemint.com/docs/api-reference/guides/authentication-api-keys) documents key creation and management through the API, including request and response shapes. For command-line access, [Install and set up the command-line tool](https://docs.settlemint.com/docs/api-reference/cli/install) explains how `dalp login` creates a key.

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

- The new key appears in the table with its name, scope, the status "Active", and its creation date. Its **Last used** column stays empty until the integration makes its first authenticated request.

## Troubleshooting [#troubleshooting]

**I closed the dialog before copying the key**

The full value cannot be shown again: the table shows only a masked preview after creation. Revoke that key and create
a replacement.

**An integration using this key stopped working**

Check the key's row first: its status, its scope, and its expiration in the expanded row. An "Expired" key, a
"Disabled" key, a revoked key, and a key whose organisation you left all fail the same way, with `DALP-14386`, which
looks like a wrong key. A "Disabled" key keeps its row. A revoked key leaves the table at once and an expired key at
the next cleanup. A key for an organisation you left is in no table you can open. A read-only key sent to a write
route fails with a distinct scope error, and a key the platform gave a request limit fails with a distinct rate-limit
error once its window is full. Wait until the window resets. A new key does not help. [Authenticate with API
keys](https://docs.settlemint.com/docs/api-reference/guides/authentication-api-keys) lists the exact codes. For the wrong scope, change it with
**Edit key**, which keeps the key value. For an expired or revoked key, create a new key and update the integration to
use it.

**I need to shut off access for one integration without touching the others**

Revoke only that integration's key from its row. Revoking asks you to confirm and names the key in the dialog, because
any integration still using that key loses access within 30 seconds, and a revoke cannot be undone. Your other keys
keep working.

**All my API keys stopped working at once**

A password change or reset turns off every API key you hold in that one step, and so does a platform administrator
setting your password for you. It does not delete them. If every key failed around the same time, check whether your
password changed recently on the [Security](https://docs.settlemint.com/docs/console/my-account/security) page. The keys show as "Disabled", so
choose **Enable** in the row menu for the ones you still need before you reissue anything. Enabling restores the same
key without a redeploy.

## Frequently asked questions [#frequently-asked-questions]

### Can I rename an API key after I create it?

Yes. Choose **Edit key** in the row menu to change the name, the scope, or the expiration. The key value does not change. To replace a key that leaked, create a new one, move the integration onto it, then revoke the old key from its row.

### Can I see how many requests a key has left?

Yes, in the expanded row of the key, under **Requests left**.

### Does an API key expire on its own if I never use it?

No. Expiration is a fixed date set when you create or edit the key, never a measure of activity. A key set to expire in 90 days stops authenticating on that date whether it made one request or ten thousand. A key set to never expire keeps working with no use at all, until you revoke it.

### Can I search for one key if my account has built up a lot of them?

Yes. The table has a search box, column sorting, and filters. The search runs on the keys the table has loaded.

## API routes [#api-routes]

Key management runs under `/api/auth/api-key/*`, not `/api/v2`: create, list, read one, update and delete. [Authenticate with API keys](https://docs.settlemint.com/docs/api-reference/guides/authentication-api-keys) documents each route with its request and response shapes. For command-line access, [Install and set up the command-line tool](https://docs.settlemint.com/docs/api-reference/cli/install) explains how `dalp login` creates a key.


# Bank accounts

Source: https://docs.settlemint.com/docs/console/my-account/bank-accounts
Propose your own bank account for cash-out payouts from the Console account menu and follow its approval by your bank.

Bank accounts lists your own bank accounts that cash-outs are paid into, and lets you propose a new one. A proposed account receives no payout until a second person at your bank approves it.

The Investor portal has the same page in its account menu, with the same table and the same steps.

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

- Your provider must have set you up as a client of a bank for an asset you hold. The **Bank accounts** item shows in the account menu only after that. Without it, the address shows "Not available".

## Steps [#steps]

### Open the page [#open-the-page]

Open the account menu and select **Bank accounts**.

### Propose an account [#propose-an-account]

1. Select **Propose a bank account**.
2. Pick the **Token** when the sheet asks for one. It asks only when you are a client for more than one asset or bank.
3. Enter the **Account holder** and the "Bank".
4. Under **Account details**, choose "IBAN" and enter the IBAN. Or choose "Account number and bank identifier" and enter the "Account number" and the "BIC or bank identifier".
5. Select **Review**, check the summary and select "Propose account".

The account must be your own. The sheet removes the spaces from what you typed before it sends the account.

## Read the list [#read-the-list]

| Column | What it shows |
| --- | --- |
| Token | The asset the account is for. Shown only when you have more than one. |
| Bank | The bank that holds the account. |
| Account | The last four characters of the account. |
| State | **Proposed**, **Active**, **Refused** or **Revoked**. |
| Proposed | When you proposed the account. |
| Decided | When your bank approved, refused or revoked it. |

Only an **Active** account can receive a payout. A "Proposed" account shows "Waiting for your bank's approval". The page does not show the reason your bank gave for a refusal or a revocation.

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

- The new account appears in the table with the state **Proposed** and the text "Waiting for your bank's approval". After your bank approves it, the state is "Active" and the "Decided" column shows the date.

## Troubleshooting [#troubleshooting]

**The account menu has no Bank accounts item**

Your provider has not set you up as a client of a bank yet. Ask your provider to link you to the bank for the asset
you hold.

**The sheet refuses the IBAN or the account number**

The sheet shows the reason under the field and keeps what you typed. An IBAN starts with two capital letters and two
check digits, and its check digits must match the rest of the number. An account number and a bank identifier use
capital letters and digits only.

**The page says your bank accounts could not be read**

Select **Try again**. Nothing has changed on your accounts.

**The Withdraw dialog says there is no payout account**

A bank cash-out needs an **Active** account for that asset. Select "Bank accounts" in the Withdraw dialog to open this
page, propose the account and wait for your bank's approval.

**The Withdraw dialog says your participant account is restricted**

A cash-out is refused while your participant account is suspended, closed, terminated or restricted from withdrawals,
whatever accounts you have. Ask an administrator of your organisation to lift a suspension, closure or restriction on
your participant account status, then request the cash-out again. A terminated account cannot be restored.

## API routes [#api-routes]

`GET /api/v2/users/me/bank-accounts` lists your accounts and `POST /api/v2/users/me/bank-accounts` proposes one. [Bank rail](https://docs.settlemint.com/docs/api-reference/guides/bank-rail) describes both.


# On-chain identity

Source: https://docs.settlemint.com/docs/console/my-account/onchain-identity
View a participant's On-Chain Identity in the Console, set it up on another network, and recover a user who lost their wallet.

The **Identity** tab of a participant shows the On-Chain Identity that regulated tokens check before a wallet may hold or receive them: whether it exists on the selected network, whether the organisation's identity registry has registered it, and which verifications it carries. Any user can open this tab for a participant they can work as. An identity manager also registers identities and recovers users who lost their wallet. [On-Chain Identity](https://docs.settlemint.com/docs/concepts/compliance-and-identity/onchain-identity) explains the identity, its claims, the identity registry and trusted issuers.

A Participant is the platform's record of one person or organisation. A verification is a claim an issuer signed onto the identity, such as a know-your-customer result. Reading the **Identity** tab changes nothing.

![My participants detail page for an investor's participant with the Identity tab open, showing the Status card and the Chains section](https://docs.settlemint.com/docs/screenshots/console-my-account-onchain-identity.light.en.webp)

[Screenshot] The "My participants" detail page for an investor's participant.

The header marks the participant "Working now" and reads "Person", "Present on this chain", "Owner" and the number of accounts. The tabs are "Overview", "Identity", "Wallets" and "Holdings", with "Identity" open. Its status card lists "Kind", "Identity", "Identity contract", "Registration status", "Verification status" and "Country / jurisdiction". Below it, the "Chains" section explains that it shows the participant's identity on every network your organisation is connected to, and that an identity installed there is filed as a pending registration that your identity manager approves. The list of networks is masked in this capture.

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

- To view an identity, you need a participant you can work as. [My participants](https://docs.settlemint.com/docs/console/my-account/acting-as-participants) explains the participant list.
- To install an identity on another network, your organisation must have more than one network connected, and the participant's wallet must be one the platform holds through a custody provider, the service that keeps and uses the signing keys.
- To recover a user, you need the identity manager role, the system role that manages the identity registry, including registering and recovering identities and onboarding users.

## Steps [#steps]

### Open the Identity tab [#open-the-identity-tab]

Select **On-chain identity** in the account menu. The Console opens the "Identity" tab of the participant you work as, or of your own participant when you work as no one else. [Navigation](https://docs.settlemint.com/docs/concepts/operating/console-navigation#the-top-bar) describes the top bar.

Other links open the same tab. They include the "Complete verification" link on an offering's eligibility check, the "Open identity steps" button on a Wealth page before your identity is registered, and the Register action on the portfolio's "Identity not registered" notice. A link that came from another page shows a **Back** button that returns you there.

To open another participant's identity, select "My participants" in the account menu, open the participant, and select the **Identity** tab.

### Read the status summary [#read-the-status-summary]

The Status card describes the network selected in the account menu. The Identity row says whether the identity contract exists on that network: "Present on this chain" or "Not created on this chain". The Registration status row says where the organisation's identity registry on that network stands:

| Registration status | What it means | What to do |
| --- | --- | --- |
| Approved | The identity registry holds an active entry for this identity. Each token still applies its own verification rule. | Nothing. |
| Pending approval | A request to register is waiting for an identity manager to accept it. | Ask an identity manager to accept it on [Entities](https://docs.settlemint.com/docs/console/participants/entities). |
| Not registered | The identity contract exists, and the registry holds no active entry for it. Also shown after a request is rejected. | On another network, use the prompt in [Set up your identity on another network](#set-up-your-identity-on-another-network). On the default network, ask an identity manager to register it. |
| Requires an identity | No identity contract exists on this network, so there is nothing to register. | On another network, install it from the "Chains" list. On the default network, ask an identity manager to create it. |

Verification status counts the active verifications on the identity, or shows "No active verifications". Country / jurisdiction shows the country the registration recorded, which compliance rules read.

The identity contract row of the Status card also offers **View on explorer** and "Show QR code".

### Check each network in the Chains list [#check-each-network-in-the-chains-list]

The **Chains** list shows the participant's identity on each network the organisation is connected to, with the default network marked "Default". Each row shows whether the identity is present and its registration status on that network.

When the identity is missing on a network, the row offers **Install identity on this chain**. [Set up your identity on another network](#set-up-your-identity-on-another-network) gives the steps.

### Review the verifications [#review-the-verifications]

The Verifications section lists the active verifications on the identity, each with its topic. A verification that an issuer revokes leaves this list. A failed read shows "Failed to load verifications. Please try again." rather than an empty list, so reload before you conclude that the identity has none.

The section also shows **Issue verification**. Only a user with the verification issuer role, the system role that issues verifications, can use it. For everyone else it is unavailable and shows the reason. [Verify a participant](https://docs.settlemint.com/docs/console/participants/verify-a-participant) covers issuing and revoking.

## Set up your identity on another network [#set-up-your-identity-on-another-network]

You set up an identity on a network other than the default from the **Chains** list or from the dashboard. Either way, an identity manager in your organisation accepts the registration from the "Pending participant registrations" panel, which [Entities](https://docs.settlemint.com/docs/console/participants/entities) describes.

### From the Chains list [#from-the-chains-list]

1. On the **Identity** tab, find the network's row in "Chains" and select "Install identity on this chain".
2. Verify your wallet in **Confirm the identity install**.

The install creates the identity, binds the wallet, and files a pending registration. The row reads "Installing identity…" until the install finishes. A failed install shows the error and offers **Retry the identity install**.

The platform checks the install only after you confirm it. It refuses the install when:

- the organisation is not connected to the network
- the participant's custody provider is not enabled there
- the participant holds no key managed by a custody provider to carry there
- the key is in self custody, so only the participant can sign
- the participant's smart wallet, an account contract that signers control, has more than one signer

After a refusal the button becomes unavailable, with a note that says why. When the platform refuses the install and the participant has its own account on that network, the row offers **Create identity** instead, and that account creates the identity.

### From the dashboard [#from-the-dashboard]

When your organisation uses more than one network and you switch to one that is not the default, the dashboard's Needs attention panel checks your identity there. It shows "Set up your identity on [network]" when you have no identity on that network, and "Finish registering on [network]" when the identity exists but is not registered.

1. Select **Register identity** on the prompt.
2. Verify your wallet in the **Register identity** dialog.

With no identity, the prompt creates one. With an identity that is not registered, it files a pending registration. The prompt does not appear on the default network. It does not appear on a Canton network either, which only a deployment that has switched Canton on offers.

## Register, change or remove a registration [#register-change-or-remove-a-registration]

An identity manager registers an identity from the user's detail page under "Organisation participants", then "Users". When the user's wallet has no identity, the page offers "Create identity". When the identity exists but is not registered, it offers **Register identity**, which asks for the country to record. Registering activates every wallet of the same owner that is not active yet, in one transaction. [Users](https://docs.settlemint.com/docs/console/participants/users) describes the detail page.

For a registered user, the identity card offers "Change country" and **Remove registration**. Removing a registration takes the wallet out of the identity registry, so the wallet can no longer receive tokens that check the registry. The identity contract and its verifications stay on the ledger.

## Recover a user who lost their wallet [#recover-a-user-who-lost-their-wallet]

If you lost access to your wallet, ask an identity manager in your organisation to recover it. Afterwards you set up your sign-in and transaction PIN again on [Security](https://docs.settlemint.com/docs/console/my-account/security).

An identity manager recovers a user who lost access to their wallet, or whose wallet is compromised. The recovery gives the user a new wallet and a new identity and moves their tokens across.

Identity recovery is the "Recovery" protection group of the Administration approval family, and that group starts on. The identity manager who executes a recovery therefore needs a second person: another owner or administrator of the organisation approves the recovery, or a platform administrator does, and only then does the platform run it, as the identity manager who asked. The wizard reads "Waiting for a second person" until that decision. An owner who turns the "Recovery" group off in [Approvals](https://docs.settlemint.com/docs/console/organisation-settings/general#approvals) lets one identity manager recover a wallet alone, and so does an organisation that holds no owner or administrator besides the person recovering.

Note (Recovery cannot be undone): It permanently replaces the user's wallet and identity on the ledger, marks the lost wallets as lost so they can never receive tokens again, signs the user out of every session, and resets the sign-in code, passkeys, transaction PIN, transaction code and recovery codes. It does not change the user's password or stop their API keys. When the account itself may be compromised, have the user change their password, which also disables their API keys, or remove the user from the organisation.

1. Open "Organisation participants", then "Users", and open the user. Open the **Verifications** tab and note each verification and its issuer, so you can compare the list after the recovery.
2. Open the "Security" tab. In the "Identity recovery" card, select **Recover identity**. The button is unavailable when the user has no wallet address.
3. In the **Validation** step, check the user's name, email and "Lost wallet" address, the Identity status with the OnchainID address, the identity contract's address, and its status, and the Token balances that the recovery moves. The step reads "This identity can be recovered" or lists the blocking reasons. A recovery is blocked when the wallet is already marked lost, when the user has no identity contract, or when the identity has no registration at all. An identity whose registration is still pending can be recovered, and its status reads "Registration pending". Select "Next".
4. In the **Impact summary** step, read the "Destructive operation" warning and the changes listed under "What will happen". The list says "KYC claims will need re-verification". That applies to verifications from issuers other than your organisation's own issuer, which the recovery does not carry across, and to any of your organisation's own verifications it cannot issue again. The Console does not list which verifications moved, so compare the new "Verifications" tab with the list you noted in step 1. Select "Next".
5. In the "Execute recovery" step, type "RECOVER IDENTITY" to confirm, select **Execute recovery**, and enter your transaction PIN or transaction code in "Verify your identity". Nothing runs yet: the step reads "Waiting for a second person" until another owner or administrator of the organisation approves the recovery. Close the wizard and follow the approval on [Actions](https://docs.settlemint.com/docs/console/essentials/actions). The recovery starts once it is approved.

![Identity recovery dialog on the Validation step, with user information, identity status and token balances](https://docs.settlemint.com/docs/screenshots/console-participants-identity-recovery.light.en.webp)

[Screenshot] The Identity recovery dialog with four steps, Validation, Review, Execute and Summary.

The Validation step shows User information with the name, email and lost wallet address, Identity status with the OnchainID address and its status, Token balances that the recovery moves, and whether the identity can be recovered, with any blocking reasons.

The **Execute recovery** step shows each stage as it runs: creating the new wallet, the new identity and the new smart wallet, authorising the smart wallet on the new identity, disabling the lost wallets, registering the new wallets in the identity registry, revoking sessions, and recovering tokens. When a recovery runs longer than the request, it continues in the background and the Console follows its status.

The recovery also reissues every verification that your organisation's own issuer identity signed on the lost identity. A verification from another issuer does not move, so ask each other issuer to reissue its verifications on the new identity. When mail delivery is configured, the user receives an email that an administrator recovered their wallet. Without mail delivery, tell the user yourself.

When the recovery finishes, the "Recovery complete" step shows the new wallet address, the new OnchainID address and the number of tokens recovered. A token that could not move is listed under "Tokens not recovered" with its reason, such as a paused token. Those positions stay on the lost wallet. A user with the custodian role on that asset recovers each one from the asset: open the asset, choose "Actions", then **Recover lost wallet**.

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

- The Identity row reads "Present on this chain", the Identity contract row shows an address, and Registration status reads Approved.
- Verification status shows the count of active verifications, and the Verifications section lists one row for each.

## Troubleshooting [#troubleshooting]

**The Identity tab says the identity is not available**

The tab reads "Identity not available yet". The participant has no identity on the network selected in the account
menu. Install it from the **Chains** list on the same tab, or switch to a network where the "Chains" list shows it as
present.

**Install identity on this chain became unavailable after I confirmed**

The platform refused the install, and the note under the button gives the reason. When the organisation is not
connected to the network or the custody provider is not enabled there, an organisation owner connects the network or
enables the custody provider first. When the participant's key is in self custody, the participant signs on that
network itself.

**Registration status stays at Pending approval**

An identity manager has not accepted the registration yet. Ask an identity manager in your organisation to accept it
from the **Pending participant registrations** panel on Entities.

**Verification status shows no active verifications after I completed KYC**

A know-your-customer submission becomes a verification only after a reviewer approves it and an issuer issues it. When
the identity is registered, approving the submission also issues a **Residence** verification for the participant's
country. A draft, a submission under review, or one sent back for changes adds nothing. Check your submission on
[Profile](https://docs.settlemint.com/docs/console/my-account/profile), and check that you opened the identity of the participant you submitted
as.

**The recovery stopped because the recovery attempts are exhausted**

The message reads "Identity recovery attempts are exhausted; contact support." The platform allows 16 recovery
attempts for the same user on a network, and this user has used them all. Contact support.

**The recovery stopped and cannot continue**

The message starts with "Identity recovery cannot continue; contact support." and ends with the reason the custody
provider gave when it refused to open the replacement wallet. The first attempt ends as **Recovery failed** with that
refusal, and every later attempt stops with this message and the same reason. Contact support with the reason.

**The recovery was refused because the lost wallet's custody account is shared with another organisation**

One organisation cannot recover a wallet on behalf of another. The organisation that shares the custody account
handles the recovery.

**The recovery was refused because the organisation has no claim issuer to issue its verifications again**

The recovery reissues the organisation's own verifications on the new identity, so it needs the organisation's issuer
identity. The message says the organisation has no operations binding, the record that links the organisation to the
issuer identity that signs its verifications, or that the binding names no claim issuer. The recovery stops before it
creates the new wallet. Contact support to configure the organisation's issuer, then run the recovery again.

**On-chain identity in the account menu opens My participants instead**

The Console could not resolve a participant for you, so it opens the participant list. Reload the page and select
**On-chain identity** again. If the list opens again, check on [My
participants](https://docs.settlemint.com/docs/console/my-account/acting-as-participants) that you have a participant in this organisation.

## Frequently asked questions [#frequently-asked-questions]

### Does a revoked verification disappear from the identity?

It depends on who revoked it. The **Identity** tab lists only active verifications, so a revoked one leaves the list either way. A revoke by the issuer leaves the claim on the identity, marked revoked. A revoke made as the participant's own identity removes it, and its history shows "Verification removed". [On-Chain Identity](https://docs.settlemint.com/docs/concepts/compliance-and-identity/onchain-identity) explains how the ledger keeps that history.

### Who else can see this identity?

A system manager, an identity manager or a verification issuer can read any identity in the organisation. A system manager is the role that sets up the platform, runs its upgrades and holds its core configuration. Other users read only the identities of the participant they work as. An identity manager or verification issuer sees the user's verifications on the user's detail page, which also shows revoked ones.

### Are registration and verification the same thing?

No. Registration means the organisation's identity registry holds the wallet with its country. Verification means an issuer signed a claim onto the identity. The Console and Platform API issue a verification only to an identity the registry holds, and a token may require a registered wallet, specific verifications, or both.


# Participant

Source: https://docs.settlemint.com/docs/console/my-account/participant
Open one participant to rename it, manage its custody accounts, co-sign a multisig change and read its holdings.

A participant page is where you manage one Participant, the platform's record of a person, organisation or wallet that acts on the ledger. From it you rename the participant, register it in another organisation, change the custody accounts that sign for it, co-sign its multisig changes and read its holdings. Changing a custody account changes which key signs for the participant from then on. The header offers **Rename** and "Work as this participant".

![Participant page with the Overview, Approvals, Identity, Wallets and Holdings tabs](https://docs.settlemint.com/docs/screenshots/console-my-account-participant-overview.light.en.webp)

[Screenshot] A participant page with its summary and its tabs.

The header holds the name and the approval threshold of a multisig wallet, and the tabs read Overview, Approvals, Identity, Wallets and Holdings.

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

- You must be able to open the participant from [My participants](https://docs.settlemint.com/docs/console/my-account/acting-as-participants).
- Which controls the page offers depends on the participant. Your own participant represents you. A participant you work as is one you hold a way into, such as a signer seat on its wallet. A participant you can open but not work as shows its details without the controls that change it.
- Custody account changes ask for your wallet verification.

## Steps [#steps]

### Open the participant [#open-the-participant]

Select the participant in the "Organisation and shared participants" table or in the "You" card of **My participants**. The tabs read, in order:

- **Overview**, which shows a "Summary" card with "Type", "Identity", "Registration status", "Role" and "Accounts".
- **Approvals**, on a multisig wallet only, with a count.
- **Identity**.
- **Wallets**.
- **Holdings**.

### Rename a participant [#rename-a-participant]

Select **Rename** next to "Work as this participant". The sheet opens with the current name.

Enter the new name and select **Save name**. The page heading, the breadcrumb and the participants table show the new name once it is saved, and so does the account menu button while you work as that participant. Spaces at either end are dropped, and a blank name is refused.

**Rename** appears only when you may use it. The user a person participant belongs to renames it, as long as they still hold it, because the same person participant shows in every organisation that user belongs to. A system manager, identity manager or verification issuer of the holding organisation renames any other participant, such as the organisation's own record. Working as a participant, or only being able to open it, does not let you rename it. An impersonated session, one a platform administrator opened as the user, never can.

## Register the participant in another organisation [#register-the-participant-in-another-organisation]

1. Work as the participant.
2. Open its row menu and select **Register in organisation**.
3. Choose the **Target organisation**, select "Register" and confirm with your wallet verification.

"Registration submitted" confirms the request.

**Register in organisation** appears only on the participant you work as, and only when there is an organisation left to register into: one you belong to where this participant is not active and has no request awaiting approval. The picker still lists an organisation that holds a pending registration with no request filed. That is how a finalised multisig, which registers itself as pending in its own organisation, files its request there. Once your request awaits approval in every organisation left, the overview shows "Register in organisation" disabled with the reason beside it.

The request goes to that organisation's identity managers, who accept or reject it under **Pending participant registrations** on [Entities](https://docs.settlemint.com/docs/console/participants/entities). After a rejection you can ask again.

## Read the participant's identity [#read-the-participants-identity]

The **Identity** tab shows the participant's on-chain identity, its registration and its verifications. [On-chain identity](https://docs.settlemint.com/docs/console/my-account/onchain-identity) documents it.

## Manage the participant's custody accounts [#manage-the-participants-custody-accounts]

A custody account is one signing account of the participant, held by one custody provider on one network. Open the participant and select its **Wallets** tab. You can change its custody accounts when the participant is your own or you work as it. Otherwise the tab shows the same wallets without "Add wallet", "Remove wallet" or the account buttons.

Each wallet card on the "Wallets" tab has a **Custody** list of the custody accounts that sign for that wallet. Each account shows the provider its configuration was added as, "Managed custody" or "Self custody", and its state. The participant's own primary account carries a "Primary" badge. On a multisig wallet the card also lists the keys other signers hold, and none of those carries the badge, even when it is that signer's own primary account. An account whose provider is not healthy also shows "Unhealthy" or "Quarantined".

### Add a custody account [#add-a-custody-account]

1. Select **Add wallet**. The "Add a wallet" panel offers each provider configuration that is enabled for new accounts and healthy, named by the provider it was added as.
2. Select a provider. A managed provider, such as Fireblocks or DFNS, creates the account at that provider. "Privy embedded wallet" or "Dynamic embedded wallet" opens that provider's own wallet flow. "Browser wallet" links a wallet you already hold by signing a message with it.
3. When an existing account of the participant must approve the new one, pick one healthy active account on the same network in the "Choose an existing signer" panel. The platform does not pick one for you.

"Custody account is ready" confirms the account, and the account's wallet gets its own card. When no provider is available, the panel says "No providers available for new accounts", and an organisation owner or a platform administrator must enable a provider, or recover a quarantined one, first. When no account can approve, the Console says "This change needs approval from another live key, but none is available to approve it." A new account does not become a signer of the participant's smart wallet. Signers join a smart wallet through its signers card.

A participant that signs directly, without a smart wallet, holds one live key: that key's address is the address its roles and tokens sit on, so a second key could never act for it. For such a participant **Add wallet** is disabled once it holds a live key, with the reason beside it, and the platform refuses a second key the same way. To replace the key, use lost-wallet recovery, which moves its tokens to the new wallet, or remove the only key first and then add the new one. A participant that already holds two or more keys shows the count, and it cannot be worked as until all but one are revoked or recovery replaces them. Participants with a smart wallet are not affected.

### Make an account primary [#make-an-account-primary]

Select **Make primary** on the account's row. The button shows only on an active, eligible account that is not already primary. "Primary custody account changed" confirms the change. The primary account grants no extra authority. It is the account a Platform API request uses when the request names no account, as [Which custody account does a Platform API request use?](#which-custody-account-does-a-platform-api-request-use) explains.

### Revoke or archive an account [#revoke-or-archive-an-account]

Select one of these on the account's row and confirm:

- **Revoke** stops an active account from signing, and it always needs another live key of the participant to approve it. When the platform knows a revoke cannot complete, "Revoke" stays visible but cannot be selected, and the reason shows under it.
- **Archive** retires an active or revoked account. It needs that approval only when another live key exists. "Archive" is refused while any of the participant's wallets holds tokens. An account that still signs for a smart wallet shows no "Archive" button until that smart wallet is removed with "Remove wallet".

### Remove a wallet [#remove-a-wallet]

Archive the custody accounts that still use the wallet and move its tokens out first. Then select **Remove wallet** on its card and confirm with your wallet verification. The platform unregisters the wallet in each organisation and on each network where it is registered, then archives it. The dialog warns when the address still holds tokens.

The wallet signs its own unregistration only while its registration in that organisation is still pending and its own custody account is active. Otherwise the organisation's managed signer unregisters it, always once an identity manager has approved the registration, and that signer must hold the identity manager role in the organisation. Before the organisation's signer sends the unregistration, the platform checks the wallet's balance of every token in the organisation on the network itself, so tokens that arrived after the last balance shown still block the removal. It also refuses the removal while a holder lock that the issuer of a token in the organisation set on your identity has not reached its unlock time.

While the organisation protects its Recovery changes with [maker-checker](https://docs.settlemint.com/docs/concepts/custody-and-signing/maker-checker), another owner has to approve the removal first. The dialog closes and a message reads "Sent for approval", with a note that another owner approves or rejects it in **Actions**. The wallet stays on the tab, unchanged, until that owner approves. The platform checks what still depends on the wallet only when the removal runs after approval, so a removal it would refuse can be sent for approval first and refused afterwards.

The platform tracks each of these changes as a custody account request. When one stops halfway, the tab shows "Finish an account change already in progress" with a button such as **Finish adding an account**. Continue it there before you start another change.

### Add a signer to a deployed multisig [#add-a-signer-to-a-deployed-multisig]

On the wallet's signers card, any seated signer can add one of their own keys, invite a person by email or link, or add an address. This is a signer invitation, not an invitation to the organisation. Unlike an invite on a draft that has not deployed yet, accepting it does not seat the key straight away. It opens an add-signer change that the signers co-sign from **Actions** until their weight reaches the wallet's threshold, and the key joins once that change executes.

The card's **Invites** list shows each invite that still waits as "Waiting for acceptance", "Waiting for co-sign" or "Expired". An invite leaves the list once it joins, ends or is revoked. You can revoke an invite there while it shows "Waiting for acceptance". A new signer joins at weight 1. When you chose another weight, the card offers "Set weight" to that value as a second co-signed change.

## Co-sign a multisig change [#co-sign-a-multisig-change]

A deployed multisig you sign for is also an account of its own. It appears in the sidebar under "Shared accounts", and its page carries the approval threshold in the header and an **Approvals** tab after "Overview". The tab counts and lists the wallet's pending approvals that wait on a seat you can sign with, each with its collected weight and time left. That is a seat of the participant you work as, and, while you work as the wallet itself, your own seat too. "Co-sign" opens the same co-sign sheet as "Actions", and the sheet offers that seat's account. When the seat belongs to your own participant, you co-sign there without switching to the wallet, or while you work as the wallet.

You do not need a seat to see that a signer change waits for co-signatures. When you can open the participant's **Wallets** tab, as its owner or as a user who works as it, the card shows "Change pending co-sign" while a change is open, so you know who to ask before you plan other work on that wallet. To read the signatures on a change or to co-sign it, you still need a seat.

## Review a participant's holdings [#review-a-participants-holdings]

The **Holdings** tab lists the assets the participant holds, with the columns "Asset", "Organisation", "Amount", "Account", "Status", "Value" and "Transfer". A line above the table reads "Balances as of" followed by a date, and a holding that includes a frozen balance says so. With no holdings, the tab reads "No holdings".

The tab has these controls and values:

- **Filter by account type** shows "All accounts", "Smart wallet" or "Key account".
- **Status** reads "Transferable", "Restricted" or "Transfer restricted".
- **Transfer** starts a transfer for a holding the acting account may move, and a disabled "Transfer" gives the reason: "Held in key account", "You are not the acting account for this holding" or "No available balance to transfer".

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

- After a custody account change, the card shows the new state of the account, and the confirmation reads "Custody account is ready" or "Primary custody account changed".
- After a rename, the page heading, the breadcrumb and the participants table show the new name.

## Troubleshooting [#troubleshooting]

**Register in organisation is disabled**

Your request already awaits approval in every organisation left, and the reason beside the button says so. Ask that
organisation's identity managers to accept it under **Pending participant registrations** on
[Entities](https://docs.settlemint.com/docs/console/participants/entities).

**A second managed account on the same network is refused**

Add further accounts from the participant's **Wallets** tab, which accepts more than one managed account per network.
Outside it, the platform creates at most one managed custody account per network for your own participant. A second
request answers "You already have a managed custody account on this network" (`409
custody.user.PERSONAL_ACCOUNT_LIMIT`). Two requests for a participant's first account on a network never create two
accounts. A second request from you for the same participant and network, sent while the first is still running, waits
up to 20 seconds and answers with the first request's account. Any other overlapping request is refused as a conflict.
Wait for the first request to finish, then refresh the tab.

**Archive is refused for a custody account**

The platform names the blocker. "A wallet of this participant still holds tokens, so the key cannot be archived yet."
means: move the tokens to another wallet, then archive again. "A smart wallet on this key is still live, so the key
cannot be archived." Select **Remove wallet** on that smart wallet's card, which unregisters and archives it, then
archive the key again.

**Remove wallet is refused**

  The dialog names what still depends on the wallet. "Archive the custody accounts that still use this wallet before
  removing it" lists the accounts to archive first. "This wallet still signs for" names the smart wallet it controls,
  and "This wallet still holds" names the tokens to move out. "The wallet's registration is not indexed yet. Try again
  in a moment." means the platform is still recording the registration. Wait a few seconds, then select **Remove
  wallet** again.

"An organisation this wallet is registered in has no managed signer that can unregister it. Either none is set up on
this network, or it does not hold the identity manager role." means that organisation's managed signer must remove the
registration, because it is approved or the wallet's own account is no longer active, and the organisation either has
no managed signer on the network or its signer does not hold the identity manager role. Nothing is unregistered in any
organisation. An organisation administrator adds the managed signer or grants it the identity manager role, then you
select **Remove wallet** again.

"This wallet's holder still has a holder lock on" names the tokens whose issuer locked them for your identity. The
organisation's managed signer removes an approved wallet, and while a holder lock is active the platform does not
remove it, because tokens could otherwise leave the lock through that wallet. Nothing is unregistered in any
organisation. Wait until the lock ends, or ask the token's issuer to clear the holder lock, then select **Remove
wallet** again.

In the Platform API, `data.reason` is `organization-signer-missing` for both signer cases, `holds-balance` when the
wallet still holds tokens and `holder-locked` when a holder lock is active.

## Frequently asked questions [#frequently-asked-questions]

### Why can't an identity manager rename a person participant?

A person participant belongs to one user, and the same participant shows in every organisation that user belongs to. Renaming it from one organisation would rename the user everywhere, so only the user it belongs to can rename it from its page. Identity managers can still rename the other participants of their own organisation.

### Which custody account does a Platform API request use?

A request uses the participant's primary account for the organisation and network. To use another one for a single request, send its identifier in the `X-Custody-Account-Id` header, as `GET /api/v2/users/me/custody-accounts` returns it. The platform never falls back to another account. A request with no header, when the participant holds eligible accounts on the network but none is primary, is refused with `409 PRIMARY_CUSTODY_ACCOUNT_REQUIRED`, which reads "Choose a primary custody account for this participant and network". A header that is empty or not an account identifier is refused with `400 dapi.runtime.INVALID_REQUEST_CUSTODY_ACCOUNT`. A header naming an account the participant does not hold on that network is refused with `409 CUSTODY_ACCOUNT_SELECTION_INVALID`. A selected or primary account that is not active and eligible, or a participant with no eligible account on that network, is refused with `409 REQUEST_CUSTODY_ACCOUNT_UNAVAILABLE`.

### How does an integration follow a custody account request?

Read `GET /api/v2/users/me/custody-account-requests/{requestId}` for its operation and state, or append `/stream` to the same path from a page on the same origin as the platform. The stream sends the current state first and then each change, and it ends when the request reaches a final state, or after three minutes. A stream request from another origin gets `404`. For a participant you work as, use the same routes under `/api/v2/participants/{participantId}/custody-account-requests/{requestId}`.


# Profile

Source: https://docs.settlemint.com/docs/console/my-account/profile
Check your Console account email, fill in and submit your own KYC information for review, and set the profile image that appears next to your name.

**Profile** shows your own Console account: your email, your KYC information and the image that appears next to your name. You fill in and submit your KYC information here for review by an identity manager in your organisation, and you see where that review stands. [Users](https://docs.settlemint.com/docs/console/participants/users#review-a-users-kyc-profile) describes the review. The page never shows or edits anyone else's account.

KYC, know your customer, is the identity check a regulated asset relies on. Your participant is the platform's record of you, and its on-chain identity is the record that regulated tokens check. Approving your information does not add the KYC verification. When your identity is registered and the approved information has a country, the approval adds a **Residence** verification for that country, issued by your organisation's identity. A verification issuer, the person in your organisation who signs verifications, then adds the KYC verification to your participant's on-chain identity, or a connected compliance provider adds it from its own check. Regulated tokens check that on-chain verification. Your Console name and password play no part in it. A token that requires the KYC verification refuses to send its tokens to a wallet without it.

The page shows the **Information** card, which holds your KYC information, with the "Profile image" card and the "Email" card beside it. Under single sign-on, a "Name" card shows your name read-only. Your password and transaction PIN are on [Security](https://docs.settlemint.com/docs/console/my-account/security). When your organisation offers more than one language, you pick yours from the account menu. An organisation owner sets the languages on [Languages](https://docs.settlemint.com/docs/console/organisation-settings/languages).

![Profile page with the Information card, the Profile image card and the email card](https://docs.settlemint.com/docs/screenshots/console-my-account-profile.light.en.webp)

[Screenshot] The Profile page with the "Information" card beside the "Profile image" and "Email" cards.

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

- Gather the details a reviewer expects: your legal first and last name, date of birth, country of residence, residency status and national ID, plus any section your organisation adds. Have the documents your organisation's policy asks for as JPEG, PNG, WebP or PDF files of at most 25 MiB each.
- The platform encrypts each document and keeps it in your deployment's object storage, never on the ledger. Identity managers in your organisation open it when they review your information, and a platform administrator of your deployment can retrieve it.
- When your deployment signs you in through an identity provider, the provider manages your name and email, and the page shows both read-only.

## Steps [#steps]

For a first submission, fill in the fields and select **Save**, then create a draft, upload your documents and select "Submit for review". Saving complete fields sends the changed fields to a reviewer, and submitting a draft sends your documents. Each becomes a version a reviewer decides. To correct a field after a request for changes, a save alone is enough.

### Fill in your information [#fill-in-your-information]

The **Information** card lists these fields, in this order:

- **First name**
- **Last name**
- **Country of residence**
- **National ID**
- **Identity details**, a section with "Date of birth" and "Residency status"
- any profile sections your organisation defines

A date of birth must be a real date that is not in the future. If you clear "First name", **Save** stays disabled.

Enter or correct your details, then select **Save**. "Save" is enabled only when a value differs from what is saved, and only the changed values are sent. The Console confirms with "Profile saved". Once your first and last name, country of residence, national ID and every required field are filled in, each save sends the changed fields to a reviewer: the status badge reads "To review" and the fields lock until the review finishes. You can still create a draft and add documents while that review runs.

Some fields cannot change:

- While a version is under review, every field is locked with "This version is under review. You can edit your information again once the review finishes."
- While your latest version is the approved one, the values are read-only with "This KYC-approved value cannot change. Contact support to request an update." When your organisation sends your profile back for a new KYC check, you can edit it again.
- A field your organisation marks immutable reads "This value is immutable and cannot change." once it is filled in.

Each field you changed shows "Waiting for review" until a reviewer decides it, then "Approved" or "Changes requested". When a reviewer asks for a change, the field shows "Requested change:" followed by the reviewer's note.

### Add documents and submit for review [#add-documents-and-submit-for-review]

Under "Identity documents", select **Create new draft** when you have no draft. The draft starts from your latest version. "Create new draft" and uploads stay disabled while you have unsaved field changes, so select "Save" first.

For each document, pick its type under **Document type**: "Passport", "Driver's License", "National ID Card", "Proof of Address" or "Other Document". Then drop or browse for the file, and confirm that it appears in the document list.

Before you submit, check every field and document: once submitted, the version is locked until the review finishes. Select **Submit for review**. The Console confirms with "KYC submitted for review", and the status badge on the "Information" card reads "To review".

## Set your profile image [#set-your-profile-image]

The "Profile image" card sets the image that appears next to your name across the platform. Select **Upload image** and choose a PNG, JPEG or WebP file of at most 5 MiB and at most 2048 by 2048 pixels. The browser checks the file first and explains a refusal, such as "The file is larger than 5 MiB." It then converts the image into two square PNG sizes, and the new image replaces the old one at once.

After an upload, the card offers "Replace image" and "Remove image". **Remove image** stops using your upload immediately and shows your ENS avatar or the generated mark instead.

The line under the image says which image is in use. Without an upload, the platform shows the ENS avatar of your wallet when it has one. ENS is the naming service that can attach an image to a wallet address. Otherwise it shows a generated mark with your initials.

When the deployment has ENS configured, **Refresh from ENS** reads your wallets' avatars again. It says when the address has no avatar, when the stored avatar is current, when the hourly avatar budget is spent, or when a platform administrator suppressed the address's avatar. You can refresh the same address again 10 minutes after the last refresh. A refresh tried sooner disables the button and shows "Available again in about N minutes."

## Change your email [#change-your-email]

The **Email** card shows your address in "Current email". When email changes are on for your deployment, enter the new address in "New email" and select "Save". The Console says "Please check your email to verify the change."

An email change needs a sign-in within the last 5 minutes and a verified current address. If either is missing, the Console answers "Request failed". If your current address is not verified, verify it first. Then sign out, sign in again and repeat the change within 5 minutes.

The platform first sends a confirmation link to your current address. Opening it sends a verification link to the new address, and your email changes only when you open that second link while signed in to the same account. When another account already uses the new address, the Console still says "Please check your email to verify the change." but sends no link.

When email changes are off, the card says "Email changes are disabled in this environment." Under single sign-on, it says "Your email is managed by your identity provider."

## How a review moves [#how-a-review-moves]

Each save and each submitted draft is a version. Until your information is complete, the badge reads "Incomplete". A complete save or a submitted draft makes it "To review", and a reviewer then decides it. When the reviewer approves, the badge reads "Approved". When the reviewer rejects the version or asks for changes, or your organisation needs your information checked again, the badge reads "Update required" and the fields carry the reviewer's notes. To act on it, correct the fields and select **Save**, or create a new draft, upload the documents and submit it. A version a reviewer has already decided stays as it was.

A new submission does not touch what is already approved. Your participant keeps the verifications already issued from an earlier approved version. A draft or a version under review never suspends them.

The card lists your earlier versions under **Version history**, taken from your 10 newest versions, each with its status in the history's own labels, such as "Under Review", "Approved" or "Rejected". These history labels are capitalised differently from the badge in the card header. The list leaves out your newest version and drafts, so a version shows there once a newer one replaces it. The row of your approved version carries a "Current" marker once a newer version replaces it. "View Details" opens a version in a side panel.

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

- After **Save**, your changes show in the fields and the Console says "Profile saved".
- After "Submit for review", the status badge reads "To review".
- Once a reviewer approves, the badge reads "Approved".
- A rejection or a request for changes turns it to "Update required" and adds the reviewer's notes to the fields.
- After an image upload, the line under the image reads "Your uploaded image is in use."

## Troubleshooting [#troubleshooting]

**A field is greyed out and I cannot edit it**

The note under the field says why: the version is under review, the value is already approved, or the field is
immutable. Under single sign-on, your name and email are managed by the identity provider. A fixed email can also mean
that email changes are off for your deployment.

**I cannot upload a document**

Uploads need a draft version and no unsaved field changes. Select "Save" first, then **Create new draft** if no draft
exists. Files must be JPEG, PNG, WebP or PDF and at most 25 MiB.

**My submission was rejected or sent back for changes**

The badge reads "Update required". Read the reviewer's notes on the fields, correct the information and select
**Save**. To replace documents, create a new draft, upload them and submit it. The reviewed version does not change.

**My participant's identity still shows unverified after I submitted**

When your identity is registered, approval adds a **Residence** verification. Any other verification needs an issuer
to issue it. Check the status badge on this page. [My participants](https://docs.settlemint.com/docs/console/my-account/acting-as-participants)
and [On-chain identity](https://docs.settlemint.com/docs/console/my-account/onchain-identity) explain how a verification shows against your
participant.

**My profile image upload is refused**

The card names the reason: only PNG, JPEG or WebP files, at most 5 MiB, at most 2048 by 2048 pixels, and an image the
browser can read. A failed upload leaves your current image in place.

## Frequently asked questions [#frequently-asked-questions]

### Can I keep more than one KYC draft at a time?

No. You hold one draft at a time. **Create new draft** starts a draft from your latest version and leaves that version unchanged.

### Does my Console name change my verified legal name?

No. Your verified name is the first and last name in the last KYC version a reviewer approved. Your Console name is not part of it.


# Security

Source: https://docs.settlemint.com/docs/console/my-account/security
Set up how you sign in to the Console and how you approve transactions, with a password, sign-in code, passkeys, transaction PIN, and transaction code.

Security protects Console sign-in and transaction signing, and the page has one section for each. The **Sign in** section holds your password, sign-in code, passkeys, and active sessions. They protect signing in to the Console itself. The "Approve transactions" section holds your transaction PIN, transaction code, and transaction recovery codes. They protect the signing authority of your Smart Wallet, the wallet the Console uses to authorise the transactions your account submits. You can be signed in and still unable to sign a transaction until one of them is set up.

Open Security the first time you sign, to add a transaction code or a stronger sign-in method, to reset a forgotten PIN, to replace recovery codes that run low, or to end a session on a device you no longer trust. To start, you need a transaction PIN and saved recovery codes. A sign-in code, passkeys and a transaction code are optional.

![Security page scrolled to the Approve transactions section, with the Transaction PIN, Transaction code and Transaction recovery codes cards](https://docs.settlemint.com/docs/screenshots/console-my-account-security.light.en.webp)

[Screenshot] The "Approve transactions" section with the "Transaction PIN", "Transaction code" and "Transaction recovery codes" cards.

The page is scrolled below the "Password" card, so only the foot of the Passkeys card with "Add passkey" and the foot of the Sessions card, its rows masked here, show from the Sign in section. In "Approve transactions", the "Transaction PIN" card reads "Enabled" with **Forgot PIN?**, "Remove" and "Change PIN", the "Transaction code" card reads "Not set" with "Set up", and the "Transaction recovery codes" card reads "Enabled" with "Regenerate recovery codes". The "Close account" row with "Ask to close my account" follows.

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

- A new Console account can sign in and browse as soon as it exists. It can sign transactions and create an [API key](https://docs.settlemint.com/docs/console/my-account/api-keys) once it has a transaction PIN or a transaction code and a confirmed set of recovery codes. Until it has both, every signing action and every new API key opens the setup wizard instead of the verification prompt.
- You need to be signed in with a password or through your organisation's identity provider. Setting up your first PIN and recovery codes asks for nothing else. [What confirms each change](#what-confirms-each-change) lists the method each change asks for.
- When your deployment signs in through an identity provider, the **Password** card says "This field is managed by your identity provider and can't be changed here.", and the Sign-in code and Passkeys cards do not show.

## Steps [#steps]

### Set your PIN and save your recovery codes [#set-your-pin-and-save-your-recovery-codes]

When the Transaction PIN card shows "Not set", select **Set PIN**. The "Signing setup" wizard opens:

1. At "Set your transaction PIN", enter a 6-digit PIN in **PIN** and again in "Confirm PIN". When your account already holds another wallet factor, the wizard then asks you to confirm it is you with that factor under "Confirm it is you".
2. At "Back up your transaction recovery codes", the wizard shows 16 recovery codes. Each code is two groups of five letters and digits. Use "Copy all" or "Download" to store them, tick "I have stored these recovery codes in a safe place", then select **Finish setup**.

The set counts only after you confirm it. If you close the wizard before the end, it asks "Close setup?", and signing stays blocked until you finish.

When you already hold a transaction code and confirmed recovery codes, **Set PIN** does not open the wizard. It asks for the new PIN twice, then for your transaction code or a recovery code under "Confirm the new PIN".

## Change your password [#change-your-password]

On the **Password** card at the top of the "Sign in" section, enter your "Current password", enter the new password in "New password" and again in "Confirm password", then select "Save". The new password must meet your deployment's password rules, by default at least 12 characters from three of the four character types, and it cannot repeat a recent password. When the platform refuses a password, the message names the rule it broke.

Note (A password change interrupts sessions and API access): Changing your password signs you out of all other devices and disables the API keys on your account. The keys remain stored. If the platform cannot reach the key store, it refuses the change and your old password stays, so try again in a moment. Review which integrations still need access before you turn a key back on with **Enable** or through the [API key management endpoints](https://docs.settlemint.com/docs/api-reference/guides/authentication-api-keys).

## Set up a sign-in code, or add a passkey [#set-up-a-sign-in-code-or-add-a-passkey]

On the Sign-in code card, select **Set up**, enter your password, scan the QR code with your authenticator app, and enter the code it shows. The Console then shows sign-in backup codes and asks you to tick "I have saved my backup codes" before you can finish.

On a deployment that requires a sign-in code, the Console sends you to a setup page for it before any other page opens, and the page says the code is required. Where the code is optional, the same page says so.

To add a passkey instead, or as well, select **Add passkey** and follow your device's prompt.

You can remove either sign-in method. Select **Remove** on the Sign-in code card and enter your password to turn it off. To remove a passkey, select "Delete passkey" on its row and confirm. That passkey can no longer sign you in, and your other sign-in methods keep working.

## Review your sessions [#review-your-sessions]

The **Sessions** card in the "Sign in" section lists the devices where you are signed in, and marks the one you are using with a "Current session" badge. Select "Revoke session" on a row and confirm to sign that device out. The Console reports "Session revoked. That device is signed out." Select "Revoke other sessions" and confirm to sign out every device except this one. The card says "You have no other active sessions." when there is nothing to revoke. The current session has no revoke control, so end it by signing out.

A session a platform administrator opens by impersonating you shows on this card too, with the line "Opened by &lt;name&gt;, a platform administrator" under it. Revoke it like any other session to end the administrator's access.

## Add a transaction code [#add-a-transaction-code]

A transaction code is a code from an authenticator app, 6 digits by default, that approves a transaction in place of your PIN. Select **Set up** on the Transaction code card, and confirm with your transaction PIN or a recovery code when the Console asks. Scan the QR code with your authenticator app, or enter the key shown under it, then enter the code the app shows and select "Turn on". By default the app lists the entry as "DALP transactions". Your sign-in code, if you have one, is the separate "DALP" entry.

From now on, the dialog that confirms a transaction asks for your transaction code first. Adding it starts your organisation's cooling-off period unless it is your first way to approve transactions, as [What happens after a wallet security change](#what-happens-after-a-wallet-security-change) explains.

## Remove your PIN or transaction code [#remove-your-pin-or-transaction-code]

You can remove your transaction PIN or your transaction code, but always keep one of them, because without either one your wallet cannot approve a transaction. Select **Remove** on the card and confirm in the dialog that opens. Removing the PIN asks for your transaction code, your transaction PIN or a recovery code. Removing the transaction code asks for your transaction code or a recovery code. Removing either starts the cooling-off period.

When that item is your only way to approve transactions, "Remove" opens a short prompt instead: "Add another way to approve transactions first". Select "Set up transaction code" or "Set PIN" in the prompt to add the other item right there, then select "Remove" again.

## Regenerate your recovery codes [#regenerate-your-recovery-codes]

To replace the set, select **Regenerate recovery codes** and confirm with your strongest method, as [What confirms each change](#what-confirms-each-change) lists. Store the new codes, tick "I have stored these recovery codes in a safe place", then select "Continue". Until you confirm, the previous set keeps working, so closing the dialog before that leaves your old codes in place. Once you confirm, every old code stops working, unused ones included. Showing the new set sends the security change email and starts the cooling-off period when one applies, and closing the dialog does not undo the hold.

## Reset a forgotten PIN [#reset-a-forgotten-pin]

Select **Forgot PIN?** on the Transaction PIN card or inside the verification dialog. Enter the new PIN twice, then one unused recovery code under "Confirm with a recovery code". With no recovery code left, select "Forgot PIN?" on the Transaction PIN card, and your transaction code confirms the new PIN. In that case the verification dialog sends you to the Security page. After a reset inside the verification dialog, the Console offers "Sign transaction" to finish the action with the new PIN.

A reset spends the code it used. When that was your last unused code, the platform replaces the set in the same step. The Console never shows the new codes, so you cannot use them. After a reset from the Transaction PIN card, the setup wizard opens at its recovery-code step straight away. After a reset in the verification dialog, it opens the next time you sign. Until you save and confirm a set, you have no recovery codes you can use.

## Ask to close your account [#ask-to-close-your-account]

The Security page ends with one row, "Close account". Select **Ask to close my account** to open a side panel with the steps to close it: empty your wallets, give each organisation another owner, and hand over your checker duties. Each step reads done or says what is left to do. The last step asks an administrator to close your account. Open steps do not stop you from asking. They tell you, and the administrator, what still has to happen before the account can be closed. When an on-chain identity is bound to your account, the last step says its record stays once it is closed, because an identity cannot be removed.

Confirm with your password and type your email. When your account signs in through single sign-on, confirm with wallet verification instead: your transaction PIN, your transaction code or an identity provider code. Select **Send request**. The side panel then shows the request waiting for an administrator, and you can select "Withdraw request" until an administrator acts. Once you close the panel, the row says when you asked, and "View request" opens the panel again.

An administrator closes the account once no step is left, or keeps it and tells you why. Closing ends sign-in and every session, and when an on-chain identity is bound to the account its record stays. It also stops the account's [API keys](https://docs.settlemint.com/docs/console/my-account/api-keys) for good. A closed account stays closed: signing in says "This account is closed.", and the password field stays empty until you enter another email. You receive an email at every step, and a declined request shows the reason on this page.

## Which second factor finishes sign-in [#which-second-factor-finishes-sign-in]

With a sign-in code set up, Console sign-in opens **Sign-in code** and asks for the code from your authenticator app. "Forgot authenticator?" switches to one of your backup codes. "Trust this device" lets that browser skip the code on later sign-ins, and the trust lapses after 30 days.

Codes sent by email or text message do not finish Console sign-in. They belong to the Investor portal, where an investor can choose how to receive a code when their organisations allow it. [Sign-in codes for the Investor portal](https://docs.settlemint.com/docs/getting-started/sign-in-codes) covers the codes and the organisation setting that offers them.

Your organisations decide which methods sign-in accepts. When an organisation you belong to stops allowing the authenticator app, Console sign-in refuses your authenticator and backup codes with `TWO_FACTOR_METHOD_DISABLED`, and a device you trusted loses that trust. Ask an owner of that organisation to allow the authenticator app again, because no other code finishes Console sign-in.

## Wallet verification [#wallet-verification]

The platform asks for a second proof at the moment you sign, on top of your signed-in session. A session left open on a shared desk, or a stolen session cookie, is then not enough to move an asset, mint a token or change custody from the Console. An [API key](https://docs.settlemint.com/docs/console/my-account/api-keys) with Read & Write scope is enough, because API key requests are not asked for wallet verification. The proof is separate from the sign-in code that finishes sign-in.

### The methods [#the-methods]

The verification dialog offers the methods your account holds:

| Method | What you enter | How you get it |
| --- | --- | --- |
| **Transaction PIN** | Your 6-digit PIN | You set it on the Transaction PIN card or in the setup wizard. |
| **Transaction code** | A 6-digit code from your authenticator app | You turn it on from the Transaction code card. It is separate from your sign-in code. |
| **Identity provider** | A 6-digit code from your identity provider's authenticator | Offered under single sign-on when your account holds an authenticator at the provider and the deployment configures [wallet verification on the provider entry](https://docs.settlemint.com/docs/deployment/sso). |
| **Recovery code** | One unused recovery code | In the Console, a recovery code resets a forgotten PIN through **Forgot PIN?** and confirms changes to your PIN and transaction code. It is not offered for a transaction. The Investor portal's dialog does accept it for signing. |

The dialog selects your transaction code by default when you hold one, then an identity provider authenticator, and your transaction PIN otherwise. When you hold more than one method, buttons at the top of the dialog switch between them. A code is accepted once: a replayed transaction code, or a spent recovery code, is refused.

### When the Console asks for it [#when-the-console-asks-for-it]

The Console opens the verification dialog before every action your wallet signs, such as a transfer, a mint or a custody change. It also asks before actions that change your security or create access: creating an API key, changing its scope or expiration, or turning it back on, changing or removing your PIN, adding or removing your transaction code, regenerating your recovery codes, and, under single sign-on, asking to close your account. Integrations that call the API with an API key send no verification. While the key's owner is in a cooling-off period, every request of theirs that signs a transaction returns 403 `WALLET_VERIFICATION_HELD` until it ends, and reads keep working.

If you hold neither a transaction PIN nor a transaction code, or your recovery codes are missing, the dialog opens the setup wizard instead of the prompt. When the wizard finishes, the Console returns you to the action. If you close the wizard, the dialog shows "Finish setting up your PIN and recovery codes before you sign." with **Continue setup**.

Some actions refuse your PIN once you hold a transaction code: regenerating recovery codes, creating, changing or re-enabling an API key, and shortening your organisation's cooling-off period, the wait after a security change during which signing is on hold. API key changes also refuse it while you hold an identity provider authenticator. For recovery codes and API keys, the dialog hides the PIN when you hold a transaction code or an identity provider authenticator.

If a PIN still reaches the platform while you hold a transaction code, for example from a script that calls the API with your signed-in session and a `walletVerification` body, the platform refuses the regeneration with "Regenerating recovery codes needs your transaction code or a recovery code." A recovery code is still accepted.

Changing an API key refuses both a PIN and a recovery code while you hold a transaction code or an identity provider authenticator. The dialog that shortens the cooling-off period still offers your PIN, but when you hold a transaction code the platform refuses it and saves nothing, so confirm again with your transaction code.

### One verification authorises one request [#one-verification-authorises-one-request]

A verification from your Console session is bound to the one request you confirmed. Before it sends a signing request, the Console asks the platform for a challenge that names the action, its target and a digest of what you are about to send. The platform spends that challenge once, and it expires after 5 minutes. A verification captured on its way to the platform therefore cannot authorise any other request. Someone who holds both your session and your PIN can still start a new request, which is what the lockout, the change emails and the cooling-off period are for. When a challenge has expired, confirm the action again.

### Lockout after wrong codes [#lockout-after-wrong-codes]

Wrong PINs, recovery codes, transaction codes and codes the identity provider rejects share one count and one lock. After a wrong code, the dialog names the factor it checked, for example "That PIN is not correct.", with the attempts left before verification locks. After five wrong codes, the next attempt starts a 15-minute lock without checking its code, and the dialog says "Too many failed attempts. Try again in" the number of seconds left. Every method is locked until the lock ends.

Attempts more than 15 minutes apart start a fresh count, and a successful verification clears it. A failure that is not a wrong code does not count. When the platform cannot reach the identity provider or the credential store, the dialog says "Verification is temporarily unavailable. Try again shortly." or "Verification is busy right now. Try again shortly.", and your attempts are not used.

### Recovery codes [#recovery-codes]

A set of 16 recovery codes lets you reset a forgotten PIN without the old PIN or your password. Each code works once.

- The Transaction recovery codes card shows how many codes remain. It warns "You are running low on recovery codes. Regenerate a fresh set so you can still reset your PIN if you forget it." when one or two remain, and "You have no recovery codes left. Regenerate a fresh set to restore PIN recovery." when none remain.

No Console screen or API route shows or sets your PIN or recovery codes for you. An identity manager in an organisation you belong to can reset your transaction PIN, remove your sign-in code, end your sessions in that organisation and send you a password reset link. A PIN reset also signs you out on every device in every organisation and starts a cooling-off period, and you set a new PIN before you sign again. Through an API key, the identity manager is not asked for wallet verification. A second approver confirms these changes only when your organisation protects the **System administration** group under [Approvals](https://docs.settlemint.com/docs/console/organisation-settings/general#approvals).

### What confirms each change [#what-confirms-each-change]

Changes to how you approve transactions never accept your account password. A dialog offers a recovery code only while you have an unused one.

| Change | What confirms it |
| --- | --- |
| Set up a sign-in code | Your password |
| Change your PIN | Your transaction code, your current transaction PIN or a recovery code |
| Set a PIN when a transaction code is your only method | Your transaction code or a recovery code |
| Add a transaction code | Your transaction PIN or a recovery code |
| Remove a transaction code | The transaction code or a recovery code, never the PIN |
| Regenerate recovery codes | Your strongest method: your transaction code once you have one, otherwise your identity provider's authenticator code, otherwise your PIN |
| Reset a forgotten PIN | One unused recovery code, or your transaction code once no recovery code is left |

Keep at least one unused recovery code somewhere safe before you need it.

### What happens after a wallet security change [#what-happens-after-a-wallet-security-change]

Every change to how you approve transactions sends you an email: a transaction PIN set, changed, removed or reset, a transaction code added or removed, or recovery codes regenerated. The email says what changed, when, and from which browser, operating system and network address. If that was not you, sign out of all sessions, change your password, and tell your organisation's administrator. When an identity manager resets your transaction PIN, the email says so.

When the change alters or removes a transaction PIN or transaction code you already held, adds a second one, or replaces recovery codes you had confirmed, it also starts a cooling-off period. The period is 24 hours unless your organisation set another length on [General](https://docs.settlemint.com/docs/console/organisation-settings/general#set-the-cooling-off-period). If you belong to several organisations, the longest of their periods applies, whichever organisation you work in, and you can leave an organisation only once your hold ends. While the hold lasts, the verification dialog refuses every signing request with "Your wallet security settings changed recently, so signing is on hold until" the end time, and the email names the same time. Your API keys can still read, but cannot sign, for the same period, and no new key can be created.

Setting up your first transaction PIN and recovery codes sends the email but starts no hold. Setting up a transaction PIN or transaction code again after an identity manager reset your PIN starts a new hold, even when the PIN was your only way to approve transactions. Under single sign-on, adding or removing the authenticator app you use at the identity provider counts as a change too, from the moment the platform next asks the provider. The first time the platform asks, an authenticator you already had there starts no hold, and it sends no email when you already hold a transaction PIN, transaction code or recovery codes. When it is your only way to approve transactions, you get the security email.

When the cooling-off period is 0, nothing is held and the emails say nothing about a hold, but every change is still emailed. When your hold ends, you get one email saying so. If your organisation changes the period and that moves the end of your hold, you get one email with the new end.

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

- The Transaction PIN card shows "Enabled" once your PIN is set, and the Transaction code card shows "Enabled" once your code is turned on.
- The Transaction recovery codes card shows how many codes remain.
- The Sign-in code card and your passkeys each show as active once added.
- The next time you start a signing action, the verification dialog asks for your transaction code or PIN instead of opening the setup wizard.

## Troubleshooting [#troubleshooting]

**Changing my password shows Request failed**

The platform turns off your API keys before it stores the new password. When it cannot reach the key store, it refuses
the change, keeps your old password and leaves your keys as they were. Your old password still works. Try the change
again in a moment. If an identity provider manages your password, follow that provider's reset process and review
Console [API keys](https://docs.settlemint.com/docs/console/my-account/api-keys) separately.

**I was asked to set up a PIN in the middle of signing**

The Console opens the setup wizard in place of the verification prompt whenever you hold neither a transaction PIN nor
a transaction code, or your confirmed recovery codes are missing. Finish the wizard, including the recovery-code
confirmation, and the Console returns you to the action.

**I forgot my PIN**

Select **Forgot PIN?** on the Transaction PIN card or in the verification dialog. Set a new PIN, then enter one unused
recovery code. If that code was your last one, the setup wizard opens to save a new set: straight away after a reset
from the Transaction PIN card, or at your next signing action after a reset in the verification dialog. With no
recovery code left, your transaction code confirms the new PIN. With neither, ask an identity manager in your
organisation to reset your transaction PIN.

**I have run out of recovery codes and cannot reset my PIN**

A reset needs an unused recovery code or your transaction code. Regenerate a fresh set from the Transaction recovery
codes card while you still can, because regenerating asks for your transaction code once you have one, and your
transaction PIN until then. Under single sign-on with an identity provider authenticator and no transaction code, it
asks for your identity provider code instead.

**Remove asks me to add another way to approve transactions first**

The Console keeps one way to approve transactions on your account. When the item you remove is your only one, set up
the other item from the prompt, then select **Remove** again.

**The PIN card says my PIN setup did not finish**

This happens when your first PIN setup stopped before it ended. If you sign in with an email and a password, select
**Set PIN** and enter the same PIN you chose the first time. That finishes the setup. If you sign in through your
organisation's identity provider, select "Replace PIN" on the Transaction PIN card and set a new PIN. The Console
accepts the new PIN only in the first 5 minutes after you sign in. After that, the card says "Sign in again to replace
your PIN." Select "Sign in again", sign in, and the PIN setup opens. If you already have a transaction code or saved
recovery codes, "Set PIN" asks for one of them, and the new PIN replaces the one that did not finish. If you do not
remember the first PIN and hold neither, ask an identity manager in your organisation for help.

**Verification is locked**

After five wrong codes, the next attempt starts a 15-minute lock on every wallet verification method without checking
its code. The dialog shows the seconds left. Wait for the lock to end, then try again with the right code. A wrong
code from any method counts towards the same lock.

**Signing is on hold after a security change**

Your organisation's cooling-off period starts when you change a transaction PIN, transaction code or confirmed
recovery codes you already held, when you add a second one, or when you set one up again after an identity manager
reset your PIN. The dialog and the change email name the time the hold ends. Signing works again after that time. If
you did not make the change, tell your organisation's administrator at once.

**I cannot revoke my current session**

The session you are using is marked "Current session" and has no revoke control of its own. Sign out to end it. Use
the sessions card to revoke other devices one at a time or all other sessions at once. Each revoke asks you to confirm
first, and cancelling leaves every session as it was. A session revoked or deleted elsewhere stops working everywhere,
and an expired session cannot sign you in. Sign in again to continue.

**The sessions list does not load**

When your sign-in is not recent enough for a sensitive read like this, the sessions card asks you to sign in again
instead of showing a partial list. Sign in again and the list loads.



# Holding

Source: https://docs.settlemint.com/docs/console/my-assets/holding
Open a holding to read its position, terms and eligibility, start a transfer, redeem, claim or conversion, and follow the balance over time.

A holding page shows one position of the participant selected in **Working as**, you or the participant you act for: what it is worth, what is available, the asset's terms and eligibility, and the operations the holder can start on it. Reading it changes nothing. An operation from the header changes the balance once its block is indexed. You reach it from a row on [Portfolio](https://docs.settlemint.com/docs/console/my-assets/portfolio).

![Holding page with the header actions, the key figures strip and the Overview tab](https://docs.settlemint.com/docs/screenshots/console-portfolio-holding.light.en.webp)

[Screenshot] A holding page with the header actions, the key figures strip and the Overview tab beside its side column.

The header offers the primary action and the "Actions" menu, a strip of key figures follows, and the "Overview" tab sits beside a side column with "Position", "Terms", "Eligibility", "Documents" and "Technical details".

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

- Confirm the participant you work as and the network. The page reads one network's wallets. While you work as someone else, it reads that participant's wallets only, as [Portfolio](https://docs.settlemint.com/docs/console/my-assets/portfolio) does.
- Each operation in the header asks for your PIN or an authenticator code and submits as soon as you confirm. This page cannot cancel a submitted operation.
- [Portfolio](https://docs.settlemint.com/docs/console/my-assets/portfolio#start-a-holder-operation) lists the condition of each holder operation.
- A holder of the asset's **Custodian** role can freeze all or part of a balance, move tokens out of a wallet with a forced transfer, and move a lost wallet's balance to a replacement wallet, without the holder signing.

## Steps [#steps]

### Open the holding [#open-the-holding]

Select a holding row to open its page. The breadcrumb reads "Wealth", "Portfolio" and the asset name, and the **Portfolio** crumb takes you back to the holdings list.

### Read the figures and tabs [#read-the-figures-and-tabs]

A strip of key figures follows the header: "Position value", "Principal" or "Balance", "Next coupon" or "Next interest", "Ready to claim", "Available", "Frozen", "Locked" with its next unlock under it, and "Value", as they apply to the asset. A holding without a reliable market price shows a dash and "No market price" in "Position value", "Principal" and "Value", never the token quantity. A **Position value** or "Principal" with a known face value shows that face value instead, marked "At face value · no market price".

When a coupon period becomes claimable, it moves from "Next coupon" and "Next payments" to **Ready to claim**. Under the figures, at most one finding states what most affects the holding, such as "You can't receive more" followed by the asset's symbol, "This bond has matured", a frozen amount or "Matures on" followed by the date.

The page has the tabs "Overview", "Activity" and "Documents", with **Activity** only when the asset keeps a balance history, and its side column shows "Position", "Terms", "Eligibility", "Documents" and "Technical details".

When the asset keeps a balance history, **Balance over time** charts your balance after each recorded change. "Activity" lists each change with its amount and the balance after it. A change made by a corporate action names that action, such as "Stock split 3-for-2", "Reverse split 1-for-3" or "Bonus issue". Any other change reads "Received" or "Sent". For a fixed-yield asset, "Next payments" lists up to four upcoming payment dates with the amount your current balance earns.

### Start an operation from the header [#start-an-operation-from-the-header]

The header offers one primary action, "Claim", "Redeem", "Convert" or "Transfer". When the primary action is not "Transfer", "Transfer" sits beside it. **Convert** shows only when the asset has a conversion feature and you hold an available balance.

The **Actions** menu holds:

- "Trade", which opens the trading desk of an instrument where the asset is the base.
- "Research", which opens the instrument page of a listed instrument.
- "Copy contract address" and, when the network has a block explorer, "View on explorer".
- "Redeem" or "Convert" when they are not the primary action.
- In the Investor portal, "Delegate voting power" when the token carries voting power. The sheet takes the address that votes with your voting power, your own wallet or another one, then asks for your PIN.
- On an asset with a maturity date that cannot be redeemed yet, a greyed-out "Redeem · at maturity on" entry with the date.

The "Actions" menu holds these entries:

- **Trade**, which opens the trading desk of an instrument where the asset is the base.
- **Research**, which opens the instrument page of a listed instrument.
- **Copy contract address**.
- **View on explorer**, when the network has a block explorer.
- **Redeem** or "Convert", when they are not the primary action.
- A greyed-out **Redeem · at maturity on** entry with the date, on an asset with a maturity date that cannot be redeemed yet.

The primary action, "Transfer", "Redeem" and "Convert" stay greyed out with "Available once your claims and this asset's features have loaded" until those reads settle. **Transfer** is also greyed out when nothing is available, with "Nothing is available to transfer", or "Nothing can be transferred until the freeze lifts." when part of the balance is frozen.

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

- After a submitted operation indexes, the headline figure, "Position value", "Principal" or "Balance", and **Available** change, and the matching event appears in [Activity](https://docs.settlemint.com/docs/console/essentials/activity).

## Troubleshooting [#troubleshooting]

**An action is greyed out in the header**

Signal: the primary action, "Transfer", "Redeem" or "Convert" is greyed out. Cause: the page has not finished reading
your claims and the asset's features, nothing is available to transfer, or part of the balance is frozen. Fix: read
the reason beside the action, wait for the reads to settle, and check **Available** and "Frozen" in the key figures.
Ask the asset's custodian about a frozen amount.

**The page shows Unknown asset, You don't hold this asset or Asset unavailable**

Signal: the holding page shows one of these states in place of the position. Cause: **Unknown asset** means the
address is not an asset in this organisation. "You don't hold this asset" means none of the accounts the page reads
holds it. "Asset unavailable" means the read failed. Fix: confirm the participant in "Working as" and the network, and
reopen the holding from [Portfolio](https://docs.settlemint.com/docs/console/my-assets/portfolio).

**The claim sheet in the Investor portal refuses before you enter your PIN**

Signal: in the Investor portal, the claim yield sheet shows a refusal with its reason and fix, and the claim button
stays off. Cause: the Investor portal's claim sheet checks the claim with the platform when it opens. The Console does
not run this check. The check does not submit or sign anything, and when it cannot answer, the claim returns its own
refusal. Fix: follow the fix in the sheet.



# Wealth

Source: https://docs.settlemint.com/docs/console/my-assets
The Wealth group of the Console sidebar: Portfolio, Invest, Trading, Settlements and Votes.

The Wealth group shows what you hold and can acquire, or, when you act for another person or organisation, what that participant holds:

- its positions and transfers in **Portfolio**
- the offerings and funds open to it in **Invest**
- its orders in **Trading**
- the multi-party exchanges it takes part in under **Settlements**
- the votes on assets it holds in **Votes**

A holding opens from Portfolio, and an offering from Invest. Trading, Settlements and Votes appear when the organisation has the trading venue, XvP settlement and governance add-ons. Switch the participant in the account menu, and Portfolio, Holding, Invest, Offering and Trading show that participant's data. [Portfolio](https://docs.settlemint.com/docs/console/my-assets/portfolio) explains which wallets it counts.


  - [Portfolio](https://docs.settlemint.com/docs/console/my-assets/portfolio): Review positions, value history and income, and collect pending returns ten at a time.
  - [Holding](https://docs.settlemint.com/docs/console/my-assets/holding): Read a holding's position and terms, then transfer, redeem, claim or convert.
  - [Invest](https://docs.settlemint.com/docs/console/my-assets/invest): Find the offerings and funds open to the active participant, then subscribe.
  - [Offering](https://docs.settlemint.com/docs/console/my-assets/offering): Review an offering's terms and progress, subscribe, and claim tokens or a refund.
  - [Trading](https://docs.settlemint.com/docs/console/my-assets/trading): Place orders on a permissioned venue, track buying power and escrow, and follow fills.
  - [Settlements](https://docs.settlemint.com/docs/console/my-assets/settlements): Run a multi-party exchange in which every local leg moves in one transaction or none does.
  - [Votes](https://docs.settlemint.com/docs/console/my-assets/votes): Vote on assets you hold, follow results and, with the Governance role, manage votes.



# Invest

Source: https://docs.settlemint.com/docs/console/my-assets/invest
Find the Primary Offerings and funds open to the active participant, open an offering to subscribe, and request a fund subscription from its card.

**Invest** lists each Primary Offering open to the active participant, the person or organisation selected in "Working as". Use "Invest" to find an offering and open it, where you subscribe, or to request a subscription to a fund from its card. Once a position exists, [Portfolio](https://docs.settlemint.com/docs/console/my-assets/portfolio) is where you track and act on it. Below the offerings, a "Funds" section lists the funds that take subscriptions, whether or not you already hold units. "Offerings" show only what you could still acquire.

![Invest page with one open offering card for CAPTECH, showing Raised against Target, Opens, Closes and View offering](https://docs.settlemint.com/docs/screenshots/console-invest-offerings.light.en.webp)

[Screenshot] The Invest page shows one card for each open offering, here CAPTECH.

The card shows "Raised" against "Target" with a progress bar, the "Opens" and "Closes" dates, and **View offering**. No "Your position" row appears because the active participant has not bought anything yet.

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

- Confirm the participant beside **Working as**, since eligibility, purchase records, and claimable or refundable amounts are all scoped to that participant.
- The organisation needs the "Offering" add-on for offerings and the "Primary market" module for funds.
- An offering appears when the participant has bought into it or can discover it, and its sale is live or is a presale open to the participant. [How an offering reaches you](#how-an-offering-reaches-you) explains both checks.

## Steps [#steps]

### Open Invest [#open-invest]

Under "Wealth", select **Invest**.

### Find an offering [#find-an-offering]

Compare the cards' raised amount and progress against target, and their opening and closing dates. A card shows "Your position" only when the active participant has already purchased a nonzero amount. Otherwise the card has no "Your position" row. Each card also carries a status badge, the shortened contract address and the offering's cover photo when it has one. Use "Search by address…" to narrow the list. When nothing matches, the list reads "No offerings match that address" and "Check the address and try again." A long list splits into pages. With no open offering and no fund, the page reads "No open offerings".

### Open the offering [#open-the-offering]

Select the card to open the offering's page. A screen reader names the card by **View offering** and the token symbol. [Offering](https://docs.settlemint.com/docs/console/my-assets/offering) describes its tabs, how to subscribe, and how to claim tokens or a refund.

## Subscribe to a fund [#subscribe-to-a-fund]

The **Funds** section lists each fund that has subscription terms. A fund with no terms is not listed, and neither is a fund that uses register lines. The section sits below the offerings. Its heading is "Funds", and the offerings above it get the heading "Offerings" only when both sections have cards.

Each fund card shows the fund's name and symbol and a **Subscribe** button. Select it to open the subscription sheet for that fund. The sheet uses your main wallet, so it has no wallet picker. Enter the cash amount in the fund's subscription currency and confirm. The sheet shows the fund's minimum when the terms set one. When you have no wallet, "Subscribe" is off and the card says "You need a wallet before you can subscribe to a fund."

Subscribing to a fund records a request. The platform records the cash amount and its dealing day, and does not price the request, take the cash or issue units at that point. The card lists your requests for the fund with their status, and offers **Cancel** until the dealing day's cut-off. After the cut-off a request stays "Open". If the fund's rules exclude you, the sheet shows "This fund isn't open to your account. Ask the fund manager to check your eligibility, then try again." For the full flow, see [Fund dealing](https://docs.settlemint.com/docs/console/asset-management/manage/fund-dealing).

## How an offering reaches you [#how-an-offering-reaches-you]

Three things are decided separately. An offering is listed when the active participant has bought into it or can discover it, and the sale is a live public sale, a presale the participant is whitelisted for, or a presale past its presale end. Otherwise the list omits it without an error. **Subscribe** appears on a listed offering's page when the sale's phase is open, an accepted payment currency exists, headroom remains, and the organisation's "Primary market" module is not read-only. After you buy, the sale resolves to a claimable success, a refundable failure or a pending state.

[Figure] Listing, the Subscribe control and the sale outcome are decided separately. An offering must be visible to the active participant and in an investable phase to appear. Subscribe also requires an accepted payment currency and remaining capacity. The entered amount must pass the subscription limits. After a successful sale, the participant can claim tokens, subject to any vesting schedule. After a failed sale, the participant can claim refunds by currency. An unresolved sale remains pending. Labels: A row shows only if visible and in phase.; Participated or discoverable, in an investable phase.; Can you buy right now?; Active phase, an accepted currency, and headroom.; Subscribe appears.; Yes; Amount still checked against seven; further limits before it submits.; Subscribe is not there at all.; No; No closed-window or paused text.; The absence itself is the signal.; A submitted purchase reaches an outcome.; For a resolved, participating position.; Claim tokens.; Success; Shown on My; investment.; Vesting may apply.; Claim a refund.; Failed; Per currency,; independently.; Claim all runs in order.; Undecided.; Pending; Progress locked; at zero.; Claiming disabled,; reason shown.

The Subscribe control appears only when the sale phase, an accepted payment currency, the remaining headroom and a
writable "Primary market" module all pass.

Browsing offerings and opening their pages changes nothing. What a purchase commits, and how a refund is protected when a sale fails, is on [Offering](https://docs.settlemint.com/docs/console/my-assets/offering#before-you-start).

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

- The offering you expect appears as a card with its raised amount, target and dates.
- A card shows "Your position" once you have bought a nonzero amount, and the offering's page then offers **My investment**.
- A fund request shows on the fund's card with its status.

## Troubleshooting [#troubleshooting]

**No open offerings appear**

Signal: the page reads "No open offerings" instead of any cards. Cause: no offering is listed for the active
participant and no fund takes subscriptions. Fix: confirm the participant in
**Working as**, then check back during an offering's active window. If you
expected an offering, ask the issuer whether it is open to you.

**The page asks for the offering add-on**

Signal: the page reads "Offerings need the offering add-on" instead of any cards. Cause: the organisation has no
**Offering** add-on and no fund takes subscriptions. Fix: ask a system manager to deploy the "Offering" add-on.
Offerings appear on the page once it is deployed.



# Offering

Source: https://docs.settlemint.com/docs/console/my-assets/offering
Open one Primary Offering to review its terms and progress, subscribe within its limits, and claim tokens or a refund once the sale settles.

An offering page shows one Primary Offering: its progress against target, its pricing and schedule, and your purchases. From it you subscribe, and claim tokens or a refund once the sale settles. You reach it from a card on [Invest](https://docs.settlemint.com/docs/console/my-assets/invest). Whether **Subscribe** appears is decided separately from whether the offering is listed, as [How an offering reaches you](https://docs.settlemint.com/docs/console/my-assets/invest#how-an-offering-reaches-you) explains.

![Offering page with the Overview, My activity, Pricing and Documents tabs and the Subscribe button](https://docs.settlemint.com/docs/screenshots/console-invest-offering.light.en.webp)

[Screenshot] An offering page with its progress against target, its tabs and the Subscribe button.

The Overview tab shows progress, pricing, investor count, schedule and the chart of commitments over time, and the header offers "Subscribe" when the offering allows it.

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

- Confirm the participant you work as in **Working as**: eligibility, purchases and claimable or refundable amounts belong to that participant. [Delegated authority](https://docs.settlemint.com/docs/concepts/compliance-and-identity/delegated-authority#attribution-needs-both-records) explains how the records name you and the participant you acted as.
- Have your PIN or authenticator code ready, because confirming a purchase asks for it.
- A purchase cannot be cancelled or edited once you confirm it. The payment currency leaves your wallet for the offering's contract when the purchase executes. If the sale fails, you claim the refund yourself from "My investment".
- Claiming tokens or a refund cannot be undone either. Browsing the offering changes nothing.

## Steps [#steps]

### Read the offering [#read-the-offering]

Select the card to open the offering's page. **Overview** shows progress, pricing, investor count, the minimum raise and any vesting schedule, and the chart of commitments over time. A "My investment" tab appears once you hold a position, a refund or an application, and "My activity" and "Pricing" are always present. A "Documents" tab appears once the offering's sold token has resolved. It lists the token's public documents, plus holder-only documents once you hold the token.

### Subscribe, if the offering allows it [#subscribe-if-the-offering-allows-it]

1. Select **Subscribe**. When it is missing, see [Troubleshooting](#troubleshooting).
2. Choose a payment currency. The picker lists only the currencies the offering accepts.
3. Enter an amount in your own number format. Under the payment amount, the fiat equivalent uses the price that [Portfolio](https://docs.settlemint.com/docs/console/my-assets/portfolio) shows for that currency, so it appears when you hold the currency and its price is reliable. Under the token amount, it shows when the token has a reliable price. When the amount is more than the headroom, what is left before the offering's cap, the Console reduces it to the headroom and says so on the confirmation card.
4. Accept the terms when the sheet asks, select **Review**, then confirm with your PIN or authenticator code.

If you sign with your own wallet rather than a platform-managed custody account, the sheet hands the purchase to that wallet after you confirm. A smart account signs the payment approval and the purchase together, in one prompt. A plain wallet signs each step in turn, and the sheet shows which step it is waiting for.

If a step fails or the request expires before you sign, nothing further is sent. A payment approval, the amount of the payment currency the offering may take, that already landed stays in place, so selecting **Subscribe** again continues from it.

## Claim tokens or a refund [#claim-tokens-or-a-refund]

Open the **My investment** tab. A refund or a token withdrawal goes to the custody account that bought. When several of your accounts hold a position in the offering, "My investment" reads each account and picks the account that is owed. It names the wallet that is paid, or offers a picker with each account's amount when more than one account is owed. The account shown signs the claim, so the PIN step does not ask which account signs. An account that signs in your own wallet signs its refund or withdrawal there.

On a failed offering, **Claim all** on "My investment" claims the refund one payment currency at a time. A currency that reverts shows its reason and a retry, and a currency that already settled stays settled. [Portfolio](https://docs.settlemint.com/docs/console/my-assets/portfolio#settle-ended-offerings) settles every ended offering you are owed with one verification.

## What the Console checks before you submit [#what-the-console-checks-before-you-submit]

Before it lets you submit, the Console checks the amount against the sale start, the remaining headroom, presale whitelisting, the first-purchase minimum, the offering's subscription step, your maximum allocation and the presale per-address cap, in that order. When the offering sets a subscription step, your total in the wallet that buys must be a whole multiple of it.

An allocation the issuer set for you personally is checked when the purchase executes, and a purchase above it is refused with a stated reason. The sale contract also checks the token's compliance rules when the purchase executes, and a refusal names its reason. A purchase that reverts moves no payment. The Console shows no eligibility verdict before you sign. The Investor portal does, and [Investor portal](https://docs.settlemint.com/docs/concepts/operating/investor-portal) describes it.

## When your tokens or refund arrive [#when-your-tokens-or-refund-arrive]

- Without a minimum raise and without vesting, the tokens arrive in your wallet with the purchase.
- Without a minimum raise but with vesting, the tokens unlock on the vesting schedule, and **My investment** offers each vested amount as it unlocks.
- With a minimum raise, claimable tokens appear only after the sale succeeds and finalises, and a refundable contribution appears only after the sale fails and finalises. Until then the position shows as pending, with its progress at zero and the claim button off, labelled with the reason.

If the sale fails, the issuer cannot withdraw your contribution until you claim the refund, and the refund claim has no deadline. A contribution taken before the offering's contract had this protection is protected only for the 30-day grace period after the sale fails, so claim that refund promptly.

## Offerings that take applications [#offerings-that-take-applications]

An offering in application mode takes applications instead of purchases. Its payment waits in escrow until the issuer allocates the offering, and the tokens and any refund arrive together. The Console has no "Apply" control. In its place the offering page says that the offering takes applications and that you apply in the Investor portal, which offers **Apply** with the same eligibility and terms checks. You can also apply through the Platform API.

Your application shows on **My investment**, with its payment amount, tokens requested, status, allocation and refund. "My activity" lists purchases only, so on an offering that takes applications it reads "No applications yet" until you apply and "Your application is on My investment" after.

An application-mode offering can lock each allocation for a period that depends on your investor category. After the issuer runs the allocation, your application shows the locked amount, when it unlocks, and the category, or **Other investors** when the default lock applies. Until the unlock time, the token refuses any transfer that would leave your wallet holding less than the locked amount.

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

- A successful subscription shows a confirmation naming your allocation and amount paid, plus the first vesting unlock date when the offering vests.
- The offering's **My investment** tab then shows your position. [When your tokens or refund arrive](#when-your-tokens-or-refund-arrive) says what it shows next.

## Troubleshooting [#troubleshooting]

**Subscribe is missing on an offering I expected to buy into**

Signal: you open an offering's page and there is no **Subscribe** button. Cause: "Subscribe" appears only when the
offering takes purchases, the sale's phase is active or about to start, an accepted payment currency exists, headroom
remains against the cap, and the organisation's "Primary market" module is not read-only. When one of these rules it
out, the button is omitted without a message. Four cases show a message in its place: the offering takes applications,
the page could not tell whether the offering takes applications or purchases, the page could not check whether the
offering has started, and the offering failed with a refund still owed to you. The second and third messages offer
"Try again", and the failed offering's message offers "See refunds". Fix: for an offering in application mode, apply
in the Investor portal. Otherwise check the offering's opening and closing dates and its raised amount against target.
If the window has not opened, has closed, or the offering is fully subscribed, this page offers no way to buy.

**My payment currency isn't in the picker**

Signal: a currency you expected to pay with does not appear in the payment currency selector inside the buy sheet.
Cause: the picker lists only the currencies the offering accepts. Fix: choose one of them.

**My purchase amount was reduced**

Signal: the amount you typed changes on its own before you submit. Cause: the Console reduces your entry to the
offering's remaining headroom and shows a warning notice on the confirmation card explaining the reduction. Fix: read
the notice before confirming. A smaller result means the offering has less headroom than you assumed.

**My purchase looked approved, but it still failed**

Signal: a spend approval step completed, but the purchase itself did not go through. Cause: an on-chain condition can
still make the purchase revert after your approval succeeds. The Console shows the decoded on-chain reason. Fix: read
the reason in the failure message, and retry after that condition, such as headroom or eligibility, has changed.

**The Investor portal shows Not eligible or Action required**

Signal: in the Investor portal, "Subscribe" or "Apply" is off and the note beside it reads **Not eligible** or "Action
required". The Console shows no such verdict. Cause: the portal checks the offering's minimum purchase against the
sale token's compliance rules. Fix: follow the action the portal names. [Investor
portal](https://docs.settlemint.com/docs/concepts/operating/investor-portal) describes it.

## Frequently asked questions [#frequently-asked-questions]

### Does an offering's vesting schedule change whether I can subscribe?

No. Vesting only changes when claimed tokens unlock after a sale succeeds. It has no part in whether "Subscribe" appears on an active offering. An offering with a long vesting schedule accepts a subscription the same way one with none does. Only the claim timeline differs afterwards, shown on the offering's **My investment** tab once your position resolves.

### If I hold positions in several offerings, do I claim or refund each one separately?

Yes, and within a single failed offering as well. [Claim tokens or a refund](#claim-tokens-or-a-refund) gives the steps. Refunds are claimed one payment currency at a time, never as one combined transaction across offerings or currencies. The **Claim all** button on a failed offering's "My investment" tab drives each currency in sequence, so a reverted currency shows its decoded reason and a retry option without rolling back a currency that already settled. A separate offering's claims are independent transactions. "Claim all" on [Portfolio](https://docs.settlemint.com/docs/console/my-assets/portfolio#settle-ended-offerings) settles every ended offering you are owed with one verification, and still sends each claim and refund as its own transaction.

### Can I subscribe to the same offering more than once?

Yes. Each purchase is checked on its own against the offering's current headroom, your maximum allocation, and, during a presale, the per-address cap. Only the first purchase into an offering is checked against its minimum amount. A later purchase into an offering you already hold a position in adds to that position rather than starting a new one, subject to the same limits as any other purchase. When the offering sets a subscription step, the new total in the wallet that buys must still be a whole multiple of it.

### The payment currency picker shows a currency I don't hold. Is that a mistake?

No. The picker lists every currency the offering accepts, regardless of what your connected wallet holds. When you confirm a purchase your balance cannot cover, the platform refuses it before anything is sent. The sheet returns to the amount step and states what you hold and what the purchase needs.


# Portfolio

Source: https://docs.settlemint.com/docs/console/my-assets/portfolio
Review the active participant's positions, value history and income, collect pending returns up to ten per verification, and start holder operations from a row.

**Portfolio** shows the holdings of the person or organisation selected in "Working as", and every figure covers that participant's wallets only. While you work as someone else, the page shows none of your own holdings until you select "Return to yourself". Use "Portfolio" to inspect what a participant already owns, check what it has earned, collect pending returns, and start a "Transfer", "Redeem", "Claim yield" or "Claim dividend" operation from a holding. To acquire a new position through an open offering, use [Invest](https://docs.settlemint.com/docs/console/my-assets/invest) instead.

The page has the tabs **Holdings**, "Insights", "Returns" and "Statements". "Holdings" shows what the participant owns now: balance, value, available amount, frozen amount, cost basis, and unrealised profit or loss, the gain or loss on what it still holds. "Insights" shows where the value sits.

**Returns** shows what the holdings have paid, as a lifetime total and the amount still to claim, by income type and by asset, and lists realised profit or loss, the gain or loss on what the participant sold or transferred away. A position with a balance on "Holdings" shows nothing on "Returns" until it pays something.

**Statements** holds the participant's statements. When the organisation has custody operations or a bank rail turned on, a "Transfers" tab lists the participant's deposits, withdrawals, bank payments and cash-outs. The [Investor portal](https://docs.settlemint.com/docs/concepts/operating/investor-portal) shows the same tabs and holding pages, with the same figures and rules.

![Portfolio page with the Portfolio value, Unrealised P&L and Income earned figures, the Holdings tab and the Needs you card](https://docs.settlemint.com/docs/screenshots/console-portfolio-overview.light.en.webp)

[Screenshot] The Portfolio page on the Holdings tab, with the three value figures and the "Needs you" card.

On the Holdings tab, the Needs you card comes first when an action waits on you, and each row carries the button for its action.

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

- Every signed-in, onboarded user sees **Portfolio** under "Wealth" in the sidebar. While the active participant has no registered on-chain identity, the page shows "Register your identity to hold and trade assets" with an "Open identity steps" link. A participant with an identity and no holdings sees "No holdings yet" with a "Browse offerings" link to Invest. Every money figure is stated in the organisation's base currency and computed by the platform. The Console formats the figures and does not add them up.
- Confirm who is active before you read anything as fact. While you work as someone else, a **Working as** bar sits under the top bar and the account menu button reads "Working as" followed by that participant's name. Otherwise the account menu button shows your own name. An operation you submit while working as another participant is sent from that participant's account. [Delegated authority](https://docs.settlemint.com/docs/concepts/compliance-and-identity/delegated-authority#attribution-needs-both-records) explains how the records name you and the participant you acted as.
- Confirm the network too. When the organisation uses more than one network, you pick it in the "Network" submenu of the account menu at the top right. It scopes the page to one blockchain network at a time, and a holding on a different network does not appear.
- Viewing "Portfolio" changes nothing, but the holder operations and **Collect all** on the "Returns" tab write. Each submits as soon as you confirm your PIN or an authenticator code from your authenticator app or identity provider, and this page has no control to cancel a submitted operation. A "Transfer" changes what the recipient holds. A "Redeem" cannot be undone: it burns the position and pays its face value in the denomination asset. [Start a holder operation](#start-a-holder-operation) lists the condition for each of the four operations.
- A holder of the asset's **Custodian** role can freeze all or part of a balance, move tokens out of a wallet with a forced transfer, and move a lost wallet's balance to a replacement wallet, without the holder signing. Someone with the asset's "Supply management" role can also burn tokens from a holder's wallet without the holder signing, as [Mint and burn](https://docs.settlemint.com/docs/console/asset-management/manage/mint-burn) describes. A frozen amount shows under "Frozen".

## Steps [#steps]

### Review portfolio value [#review-portfolio-value]

Open "Wealth", then **Portfolio**. On a tab other than "Holdings", the breadcrumb ends with the tab, such as "Wealth", "Portfolio" and "Returns", and the page title names the tab.

Three figures sit over the tabs and stay the same on every tab:

- **Portfolio value** with its change over 24 hours.
- **Unrealized P&L** with its percentage on cost. A gain too small for two digits reads `<0.01%`, a loss `>-0.01%`.
- **Income earned**, with a line under it. That line gives the amount you collected this year. When that is zero, it gives the amount pending collection, for example "$110.77 pending collection", and when both are zero, it reads "None collected this year".

Each figure opens the tab that explains it. When some holdings have an incomplete cost basis, **Unrealized P&L** adds up only the holdings that have one. The figure starts with `≈`, shows no percentage on cost, and the line under it says which holdings it leaves out, for example "Excludes 1 holding with an incomplete cost basis: MANOR". The line wraps onto up to three lines inside the figure's tile. When the list is longer still, it ends in an ellipsis. Hover or focus the line to see every excluded holding with its name. When no holding has a cost basis yet, the line reads "No cost basis yet". When the cost basis is incomplete and no partial total can be given, it reads "Unknown: some holdings have an incomplete cost basis". [How cost basis and profit or loss are computed](#how-cost-basis-and-profit-or-loss-are-computed) explains the figures.

The value chart sits on the **Holdings** tab over the holdings table, and again on the "Insights" tab. It plots the participant's held balances at price over a selectable range. An asset with no price counts as zero on the chart. It opens on the last month, one of eight ranges from the trailing 24 hours up to all time. On "Holdings" you pick the range in the chart's header and the comparison sits under the plot. On "Insights" both controls sit under the tabs. A portfolio with no value to chart shows no chart on "Holdings".

**Compare with prior period** draws the period of the same length just before the range as a dashed line. All time has no earlier period, so for that range the switch is off and cannot be turned on, with the reason beside it. The chart leaves out pending income, because the participant does not hold it yet. Collected income becomes a balance, so a payout can move the chart as well as the "Returns" figures.

### Inspect holdings [#inspect-holdings]

When an action waits on you, such as an approval, an invitation, a vote or a yield or dividend to claim, a **Needs you** card sits over the table. It counts those actions and lists up to six with their deadline. "View all" opens Actions for the rest. Actions that wait on someone else sit in a closed "Waiting on others" disclosure under the rows. The card does not appear when nothing waits on you.

Use **Search holdings…** to find a holding. The table shows "Symbol", "Balance", "Value", "Unrealized P&L" and the row actions. A holding whose value equals its cost shows an unrealized P&L of `$0.00`, the same zero the figure over the tabs adds up.

Add "Token name", "Contract address", "Cost basis", "Average cost", "24h", "Available" and "Frozen" through the **View** control in the toolbar. A value that rounds the exact balance times the price to the cent starts with `≈`.

Hover **Unrealized P&L** for the "Total return", the "24h change" and a chart of the "Last 30 days". When a holding's cost basis is unknown, both "Cost basis" and "Unrealized P&L" show a warning mark, and hovering it reads "Unknown: some acquisitions of this asset had no price, so its cost basis and unrealized P&L cannot be calculated."

Expand a row to see its token name, cost basis, average cost, available and frozen amounts, and contract address. Select a row to open the holding page, described under [Holding](https://docs.settlemint.com/docs/console/my-assets/holding). "Export" saves every holding that matches the search and filters as CSV or JSON.

## Deposit into your gateway [#deposit-into-your-gateway]

When your organisation has custody operations or a bank rail turned on and you have a custody gateway, **Deposit** sits in the page header beside "Claim all". It opens the same deposit dialog as the Investor portal.

- "From a wallet" shows your gateway address as a code and a QR code, with the coins it accepts. Send only those coins to that address. While the gateway is paused, the dialog says not to send a deposit until it resumes.
- "By bank transfer", when your bank link is set up, shows the account to pay and the payment reference or virtual IBAN that makes the payment yours, and says when that bank connection is paused.
- When you have no gateway and no bank link, "Deposit" does not appear.

## Withdraw from your gateway [#withdraw-from-your-gateway]

**Withdraw** sits beside "Deposit" when your organisation has custody operations or a bank rail turned on. It opens the same withdraw dialog as the Investor portal, described in [Wallet deposits and withdrawals](https://docs.settlemint.com/docs/concepts/operating/investor-portal-wallet-transfers#withdraw-coins-to-your-payout-address).

- **To a wallet** shows the "Auto-collect" switch and "New withdrawal". The request sheet lists your custody receipts and the payout addresses approved for your gateway, prices the fee for the amount you enter, and asks for your transaction PIN or code. A refused request shows the reason and keeps the sheet open.
- **To my bank account**, when your bank link is set up, requests a cash-out as [Bank transfers](https://docs.settlemint.com/docs/concepts/operating/investor-portal-bank-transfers#how-to-cash-out) describes. In the Console the booked step lists the redemption lines you already requested, and offers no way to request a new one. With no active payout account for the token, the method shows "Bank accounts", which opens [Bank accounts](https://docs.settlemint.com/docs/console/my-account/bank-accounts) so you can propose your own account. While your participant account is suspended, closed, terminated or restricted from withdrawals, the request is refused and the dialog says an administrator can lift a suspension, closure or restriction, but a termination is final.
- When you have no gateway, the dialog says "No gateway yet". While the gateway is paused, "New withdrawal" is off.
- Under "New withdrawal" the dialog lists your withdrawals, open ones first. "View all" opens the "Transfers" tab.

Prove the wallets your withdrawals go to on [Withdrawal destinations](https://docs.settlemint.com/docs/console/personal/withdrawal-destinations).

## Start a holder operation [#start-a-holder-operation]

The first enabled operation of a row shows as a button in the row, and the others sit in the row menu. On a phone every operation sits in the menu. The operations have different requirements and results:

| Operation | Offered when | What it changes |
| --- | --- | --- |
| **Transfer** | Always. When the selected account has nothing available, it is greyed out with "The selected account has no available balance to transfer." | Reduces the sender's balance and increases the recipient's balance. |
| **Redeem** | The asset has a maturity date, and that date has passed. | Burns the position, reducing what the issuer has outstanding, and pays its face value in the denomination asset. |
| **Claim yield** | A pending yield claim exists for the token's yield schedule. | Pays already-earned yield into the participant's wallet. |
| **Claim dividend** | A pending dividend claim exists for the token. It stays greyed out with "Awaiting funding: the issuer has not funded this dividend yet." until the issuer funds it. | Pays the dividend into the participant's wallet. |

Each operation opens its own sheet. On the **Transfer** sheet, the confirm step also shows a "Pre-trade compliance check" for each recipient and amount, which says whether the transfer would clear before you sign.

When that check says the transfer would revert, rather than wait for approval, "Confirm transfer" stays disabled and the reason beside it names the failed checks. Confirming with your PIN or authenticator code submits the operation.

## Settle ended offerings [#settle-ended-offerings]

When a Primary Offering you bought into has ended and still owes you something, it is listed in the "Offerings to settle" card on the Holdings tab. A successful sale with tokens you can take now shows "Claim tokens". A failed sale with money to return shows "Claim refund". "Claim all" settles offerings you bought into, and "Collect all" on "Returns" claims income from assets you already hold.

Select a row's button to settle that one offering without leaving Portfolio. A sheet lists what you receive: the tokens, or the refund in each currency you paid. Confirm with your PIN or authenticator code.

**Claim all** settles every listed offering at once. The button carries the number of offerings, for example "Claim all (3)". It is hidden while the list loads, when the list cannot be read and when nothing is owed. The sheet lists each offering with its claim or refunds, and one verification covers all of them.

Each claim and each refund is its own transaction, so the sheet shows one result per claim or refund. "Claimed" or "Refunded" means it settled. "Processing" means the transaction was accepted and shows in your activity once it is mined. "Failed" gives the reason, and the others still go through. "Try again" resends only the offerings that failed. An offering that owes this account nothing says "Nothing to claim from this account", and "Open offering" takes you to its page, where you can settle from the account that is owed.

One **Claim all** settles at most 20 offerings. When more are listed, the sheet says how many are left, and a second "Claim all" settles them. When the organisation's primary market is read-only, "Claim all" and the row buttons are disabled with that reason. The claims sign from the participant's custody account. [When the raise falls short](https://docs.settlemint.com/docs/concepts/issuing-and-markets/primary-offering#when-the-raise-falls-short) explains refunds. The Investor portal uses the same sheet.

## Read allocation on Insights [#read-allocation-on-insights]

**Insights** shows where value sits: "Value by asset class", "Largest holdings" and "By country". Each answer is a card of bars with the value and its share of the portfolio. Value on assets that have no country shows as "No country". The "Holdings by country" map sits below the value trend. Over the cards, an attention row flags "Servicing events in the next 14 days", "Holdings partly frozen" and a missing identity registration, and is absent when none applies.

## Read returns [#read-returns]

**Returns** shows what the holdings have paid.

**Income mix** charts the lifetime total by return type, fixed income, dividend, and interest, not by individual asset. A return type drops off it once it has nothing pending and nothing collected, so an accrued payout that is not claimed yet still shows. A type that earned something never reads 0%: a share too small to round reads `<0.1%`, and the largest share reads `>99.9%` while another type earned something, so the shares never add up to more than 100%.

**Upcoming events** lists up to ten dividend payments and the next coupon of each fixed income holding, due in the next 30 days, through the end of the thirtieth day (UTC). A coupon is due when its period ends, and its amount is what your current balance earns over that period. Interest accrues continuously and has no payment date, so it never appears here: with nothing due, the list says interest is shown under "Returns by asset". A dividend or coupon leaves the list once its payment time is reached, and from then on it counts as "Pending" and "Collect all" offers it. Every figure on the tab, and "Collect all", judge that moment by the same clock: the time of the latest block the platform has indexed.

**Returns by asset** breaks earned and pending totals down per holding, plus what each has already collected. Use the "Type" filter to show only fixed income, dividend, or interest holdings. "Next event" shows the next dividend payment date for a dividend holding and the end of the next coupon period for a fixed income holding. An interest holding reads "Accrues daily, claim anytime", or "Accrual starts" with the date while its accrual has not begun. A dash means nothing is scheduled, or, for an interest holding, that its accrual is paused, you are excluded from it, or it no longer runs for you. The footer under the table totals the rows you can see:

| Footer figure | Shows |
| --- | --- |
| **Total earned** | Lifetime income for the listed holdings, computed as everything collected plus everything still pending |
| **Pending** | Earned income you can still claim, which falls as you claim it |
| **Collected** | Income already paid out to you |

The footer starts with the number of distinct assets it covers, and it changes with the filter. Filter by "Type" to see what one return type is worth, or which holding moves the total. Each footer total adds the row figures as they are shown, each rounded to the cent, so the rows always add up to it. A total starts with `≈` when a row it adds was rounded.

**Income earned** over the tabs is the lifetime total, collected plus pending, added up from the "Returns by asset" rows the same way. The line under it gives the amount collected since the start of the year.

**Annual rate** gives every holding's rate per year. A fixed income asset pays its rate each period, so the column scales that rate to a 365-day year, the figure its holding page shows beside the period rate.

**Realized disposals** lists the latest 100 sales and transfers away, with "Date", "Asset", "Quantity", "Proceeds", "Cost of disposal" and "Realized P&L", and states the "Realized total" beside its title. When every disposal is listed and each has a known "Realized P&L", the total adds the row figures as they are shown. Otherwise it covers all disposals, including those beyond the latest 100. A row whose figure cannot be computed explains why when you hover it.

**Export P&L** downloads "Realized disposals", the "Realized series" or the "Unrealized series" as a CSV file, including disposals beyond the latest 100.

For a holding that earns interest, **Rate history** charts the annual rate after each change.

## Collect all returns [#collect-all-returns]

**Collect all** claims the returns the participant can collect now, across fixed treasury yield, dividends and interest, up to ten per wallet verification. Use it when several holdings owe income at the same time, in place of claiming each one from its holding. The button sits in the header of the "Returns" tab, beside "Export P&L", and carries the number of returns waiting, for example "Collect all (3)".

The button keeps its place from the moment the tab opens. It is unavailable while the list of collectable returns loads, and when nothing is collectable it reads "Collect all", stays unavailable, and gives the reason "Nothing left to collect."

1. If the participant has two or more custody accounts that can sign, its wallets on this network, choose the account in the **Collect from** selector beside the button. Without a choice, the primary account collects, or the first account that can sign when none of them is primary. The choice holds until you reload the page.
2. Select **Collect all (3)**. The "Collect all returns" sheet opens with one row per return: the asset, the return type, which is "Fixed income", "Dividend", or "Interest", the amount in the asset that pays it, marked "Estimated", and the status "Ready".
3. Select **Collect all**, then enter your PIN or an authenticator code from your authenticator app or identity provider. That one verification covers every row in the round.
4. Follow the rows as they change status. A line under the rows counts the result, for example "2 of 3 collected".
5. If the sheet says "7 more returns will be collected in the next round.", select **Collect next 7** and verify again. If a row failed, the button reads "Try again". Close the sheet when you are done. The "Returns" figures and the "Collect all" count reload.

![Collect all returns sheet listing four returns, each with its type, estimated amount and Ready status](https://docs.settlemint.com/docs/screenshots/console-portfolio-returns-collect-all.light.en.webp)

[Screenshot] The "Collect all returns" sheet with the account the transaction executes from and one row per return.

The sheet opens with the account the transaction executes from and its signing key, then one row per return: the asset name and return type, the amount marked "Estimated" with the symbol of the asset that pays it, and the status "Ready". "Cancel" and **Collect all** sit at the foot of the sheet.

[How Collect all claims your returns](#how-collect-all-claims-your-returns) explains what is collected, what the platform checks, and what each row status means.

## Download a statement [#download-a-statement]

The **Statements** tab lists the statements of the participant's wallets. A statement shows the opening and closing balances and the movements of one wallet over a period, and your organisation's statement policy sets how often they are produced. Each one appears once its period has closed. The table shows "Period", "Wallet", "Status" and "Download". "Reconciled" means the opening balances plus the listed movements equal the closing balances for every security. "Incomplete" means they do not, and the statement says not to rely on it.

Select a download in a row, in "CSV", "Excel workbook" or "PDF". The button reads "Preparing…" while the file is made. When it fails, the Console shows "The statement could not be downloaded. Try again." With no statement yet, the tab reads "No statements yet". The **Statement pages** control pages through a long list.

## Follow your transfers [#follow-your-transfers]

The **Transfers** tab shows when your organisation has custody operations or a bank rail turned on. It lists the gateway deposits and withdrawals, bank payments and cash-outs of the participant you work as, the same rows the Investor portal shows on its "Transfers" tab, as [Wallet deposits and withdrawals](https://docs.settlemint.com/docs/concepts/operating/investor-portal-wallet-transfers) and [Bank transfers](https://docs.settlemint.com/docs/concepts/operating/investor-portal-bank-transfers) describe.

- Transfers still on their way sit under "In progress", the rest under "History", newest first, each with its stage in plain words.
- Search by amount, stage or reference, and narrow the list with the type filter.
- "Cancel" sits on a withdrawal you can still cancel. It asks for your transaction PIN or code and gives your receipts back.
- With nothing yet, the tab reads "No transfers yet". An organisation without custody operations or a bank rail shows no tab, and the address reads "Transfers are not available".

When you keep the organisation's books, its movements stay off this tab and show on [Custody books](https://docs.settlemint.com/docs/console/organisation-settings/custody-books).

## Which account a claim pays [#which-account-a-claim-pays]

A participant can hold the same asset through several custody accounts, and a yield, dividend or interest payment is owed to the account that held the balance. Each claim sheet asks every custody account the participant has on the network what it can claim now.

- When one account is owed, the sheet locks to that account and shows it as "The wallet that is paid".
- When several are owed, a picker lists each account with its amount.
- When none is owed, the sheet says "Nothing is owed to any of your accounts" and you cannot submit the claim.
- An account the platform cannot read blocks only itself, and a notice names the wallets that could not be checked.

The account on the sheet signs the claim, so the verification step does not ask which account signs, and the amount shown is the amount that wallet receives. A participant with one account sees no extra step.

## How cost basis and profit or loss are computed [#how-cost-basis-and-profit-or-loss-are-computed]

The cost basis is what a position cost, kept as a weighted average for each wallet and asset in the organisation's base currency.

- **Acquisitions.** A mint, or a transfer received from a wallet of another participant or from a wallet no participant holds, adds the quantity and its cost, and the average cost becomes the total cost divided by the quantity held.
- **Disposals.** A burn, or a transfer to a wallet of another participant or to a wallet no participant holds, is booked at the average cost at that moment. A disposal larger than the position is limited to the quantity held.
- **Moves between your own wallets.** A transfer between two wallets of the same participant moves the quantity and its average cost, with no profit or loss. When the sending wallet's cost is unknown, the receiving wallet's cost becomes unknown too.
- **Prices.** A trade settled on a trading venue uses the trade's quote amount: the buyer's cost includes the buyer's fee, and the seller's proceeds exclude the seller's fee. Every other movement uses the latest price recorded for the asset before the movement, or the asset's current price when no price is recorded.
- **Unknown cost.** An acquisition with no price makes the position's cost unknown, and a later priced acquisition does not make it known again. The Console then shows the cost basis and the unrealised profit or loss as unknown. A holding acquired before the asset had any price, such as a mint that lands before the issuer's first price, takes that first price once it is published.

Unrealised profit or loss is the current value minus the cost basis, with each rounded to the cent once. The percentage divides the exact difference by the exact cost basis and is rounded to two decimals.

Realised profit or loss is the proceeds of a disposal minus the disposed quantity at the average cost, rounded down. A disposal with no usable price records zero proceeds and is marked "No price was available when this sale happened, so its proceeds and profit are not calculated." A disposal whose cost is unknown has no realised figure and is marked "The cost of some units sold is not recorded, so the profit is not calculated."

## How Collect all claims your returns [#how-collect-all-claims-your-returns]

**Collect all** verifies the wallet once and then claims each listed return as its own transaction. The platform sends the claims one at a time. A claim it cannot confirm in time is marked "Unconfirmed", and the platform sends the next one. A claim that fails is recorded on its row and does not stop the claims after it, and it does not undo the claims before it. Every claim pays the wallet of the participant named in "Working as".

A round claims in a fixed order: fixed treasury yield first, then dividends by payment date, then interest. Each dividend is its own return, so a token with two open dividends gives two rows. One fixed treasury yield claim can pay several completed periods at once. Returns past the first ten stay **Ready** and wait for the next round, which needs a new verification.

### What counts as collectable [#what-counts-as-collectable]

The list covers the participant's holdings in the current organisation, on the network picked in the account menu. The platform measures dates against the time of the latest indexed block. It reads the three return types in one snapshot, so every row reflects the same block.

| Return type | Row label | Listed when |
| --- | --- | --- |
| [Fixed treasury yield](https://docs.settlemint.com/docs/concepts/modeling-assets/token-features/income#fixed-treasury-yield) | **Fixed income** | The feature is attached to the token, the wallet holds the token or the feature already tracks it as a holder, and at least one completed period is unclaimed. |
| [Dividend yield](https://docs.settlemint.com/docs/concepts/modeling-assets/token-features/income#dividend-yield) | **Dividend** | The wallet is entitled to an amount greater than zero, the dividend is **Recorded** or **Payable**, its payment date has arrived, its claim deadline has not passed, and the wallet has not claimed it. |
| [Interest yield](https://docs.settlemint.com/docs/concepts/modeling-assets/token-features/income#interest-yield) | **Interest** | The feature is attached to the token and not paused, the wallet holds the token or the feature already tracks it as a holder, and accrued interest is greater than zero. |

A return that meets none of these rules is left out of the list.

### Who can collect [#who-can-collect]

Starting a collection needs no token role, but a claim whose feature requires a role the wallet lacks fails with "Your wallet is not allowed to collect this return." The claims sign from the custody account of the participant named in "Working as" on the selected network. That account must sign on the platform side.

A wallet that signs in the browser cannot be collected in a batch: its rows fail with "This wallet signs in the browser, so this route cannot ask it to sign. Use the browser-wallet route.", and you claim those returns one at a time from the holding. In the Console, when none of the participant's custody accounts on the network can sign, the **Returns** tab shows "None of your custody accounts can sign a claim right now. Check their status in Settings." and "Collect all" stays unavailable.

### What the platform checks [#what-the-platform-checks]

- **Verification.** A wrong PIN or authenticator code stops the request before any claim is sent.
- **Collectable returns.** When you confirm, the platform reads the collectable returns again and claims those, not the list the sheet opened with. A row it no longer finds collectable goes back to "Ready".
- **Fixed treasury yield.** Right before it submits a fixed treasury yield claim, the platform reads the yield feature on the network to confirm that a completed, unclaimed period remains.
- **Feature rules.** Each claim runs under the rules of its feature and the token's compliance rules, as a claim from the holding would.

### Amounts: estimated and paid [#amounts-estimated-and-paid]

Until a claim lands, its row shows the amount quoted when the sheet opened, marked **Estimated**. Interest keeps accruing, and another fixed treasury yield period can complete, before the claim lands, so a claim can pay more than its quote. Once the claim lands, the row shows the amount the claim paid, as recorded by the indexer, the platform service that reads events from the network. If that record cannot be read yet, the row keeps the quote and the "Estimated" mark.

Both amounts show at most six decimal places. A paid amount with more decimals than that is rounded and marked `≈`: hover over it, focus it or tap it to see the exact amount the wallet received.

### Row statuses [#row-statuses]

| Status | Meaning |
| --- | --- |
| **Ready** | Listed and not sent yet. |
| **Collecting** | The claim is sent. The Console follows it until it settles. |
| **Collected** | The claim settled and paid the wallet. |
| **Unconfirmed** | The claim was sent, and its result is not confirmed. The row shows a **Reference ID**. Check that transaction before you collect the return again. |
| **Failed** | The claim did not go through. The row gives the reason, and **Try again** starts a new round. |
| **Skipped** | The platform did not send a claim for this return. The row gives the reason. |

A failed or skipped row shows one of these reasons:

| Row status | Reason shown | What happened |
| --- | --- | --- |
| **Skipped** | "Nothing left to collect." | The fixed treasury yield check found no completed, unclaimed yield to pay. |
| **Skipped** | "Not indexed yet. Try again shortly." | The fixed treasury yield state is not indexed yet, or the dividend claim was refused before it was sent. |
| **Skipped** | "This return is no longer attached to the asset." | The feature that pays it is no longer attached to the token. |
| **Failed** | "The transaction reverted." | The network or the transaction queue rejected the claim. |
| **Failed** | "The transaction queue is unavailable. Try again shortly." | The claim could not be queued. A browser-signing wallet shows its own message here instead. |
| **Failed** | "Your wallet is not allowed to collect this return." | The wallet lacks a role the claim requires. |
| **Failed** | "Compliance rules rejected this transfer." | The token's compliance rules refused the payout. |
| **Failed** | "The return could not be read. Try again shortly." | Any other failure. |

A claim that the queue accepted and that then fails on the network shows the decoded contract error, or "The collection did not complete.", followed by its **Reference ID**. If the whole request fails before any result comes back, every row that was collecting fails with "The collection could not start:" and the error.

**Try again** and "Collect next" both start a new round. The platform reads the list again, so a round claims only what is still listed as collectable.

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

- A submitted operation shows its progress in the Submissions tray while it runs.
- The holdings table reads again each time the network indexes a new block, so a finished "Transfer", "Redeem" or claim shows in the balance once its block is indexed.
- The matching event appears in [Activity](https://docs.settlemint.com/docs/console/essentials/activity).

## Troubleshooting [#troubleshooting]

**A cost basis or unrealised profit or loss figure shows a warning mark**

Signal: a holding's "Cost basis" and "Unrealized P&L" show a warning mark instead of an amount, and hovering it reads
"Unknown: some acquisitions of this asset had no price, so its cost basis and unrealized P&L cannot be calculated."
Cause: at least one acquisition of that position had no price when it was booked, so the platform cannot know what the
position cost. Fix: ask your organisation's administrator to have a holder of the "Feeds manager" role publish a price
for the asset. An acquisition that came before the asset's first price takes that price once it is published. The
**Unrealized P&L** figure over the tabs sums the other holdings, starts with `≈` and names the holdings it leaves out.

**Transfer is greyed out on a holding the participant owns**

Signal: **Transfer** is greyed out and reads "The selected account has no available balance to transfer." Cause: the
account the transfer would send from has nothing available, because its balance is frozen, on hold or pending in
another transfer. Fix: add "Available" and "Frozen" through "View" to see how the balance splits, then ask the asset's
custodian why the balance is frozen or held, or wait for the pending transfer to clear.

**Redeem, Claim yield or Claim dividend does not appear on a row**

Signal: you expect "Redeem", "Claim yield" or "Claim dividend" on a holding, and it is missing. Cause: each one has
its own condition, and [Start a holder operation](#start-a-holder-operation) lists them. Fix: for **Redeem**, wait for
the asset's maturity date. This page has no path to redeem early. For a claim, confirm in
[Actions](https://docs.settlemint.com/docs/console/essentials/actions) that a claim is pending for the participant.

**No holdings appear**

Signal: the page reads "No holdings yet" or "Register your identity to hold and trade assets". Cause: the active
participant holds no tokens in this organisation on the active network, or has no registered identity. Fix: confirm
the participant named in "Working as" and the network in the account menu.
Select **Open identity steps** to register the identity, or "Browse offerings" to invest.

**Collect all is unavailable on the Returns tab**

Signal: the **Collect all** button on the "Returns" tab is unavailable and gives the reason "Nothing left to collect."
Cause: the platform found nothing the participant's wallet can collect now on the selected network. A dividend before
its payment date or after its claim deadline, a fixed treasury yield period that has not completed, and interest on a
paused feature are all left out. When none of the participant's custody accounts on the network can sign, the Console
shows "None of your custody accounts can sign a claim right now. Check their status in Settings." beside the
unavailable button. Fix: confirm the participant in "Working as"
and the network in the account menu. For the signing message, ask your organisation's administrator to check the
custody accounts.

**The Returns tab says the collection could not start**

Signal: the tab shows "The collection could not start:" followed by an error, and a "Try again" button, and **Collect
all** stays unavailable. Cause: the platform could not read the list of collectable returns. Fix: select "Try again".
Nothing was claimed, because the list is read before any verification.

**A row shows Unconfirmed**

Signal: a row in the "Collect all returns" sheet shows **Unconfirmed** with the message "The collection was sent, and
its result is not confirmed yet. Check the reference before you collect it again." and a "Reference ID". Cause: the
claim was sent, but the Console could not confirm whether it settled. The claim can still land. Fix: keep the
reference and wait. Then reopen the "Returns" tab and check the "Collected" figure for that asset in "Returns by
asset" before you collect it again.

**A row fails with a message about a browser wallet**

Signal: a row fails with "This wallet signs in the browser, so this route cannot ask it to sign. Use the
browser-wallet route." Cause: the participant's wallet signs each transaction in the browser, and **Collect all** only
claims through accounts that sign on the platform side. Fix: claim that return on its own from the holding.

## API routes [#api-routes]

The same flow is available through the [Platform API](https://docs.settlemint.com/docs/api-reference/v2), for the wallet the request acts for:

- `GET /api/v2/portfolio/returns/collectable` lists every return the wallet can collect now, in claim order. It writes nothing. An empty list means there is nothing to collect. Send the `X-Custody-Account-Id` header to read what one account can claim. [Which custody account does a Platform API request use?](https://docs.settlemint.com/docs/console/my-account/participant#which-custody-account-does-a-platform-api-request-use) explains the header.
- `POST /api/v2/portfolio/returns/collections` takes the `walletVerification` in its body and claims up to ten returns. It answers `200` with one result per item: `collected`, `queued`, `failed` or `skipped`. Failed and skipped items carry a `reason` and a `message`. `remaining` counts the collectable returns the request did not attempt. Send the same `Idempotency-Key` header again to replay the settled claims instead of paying twice. Send a new request to collect what remains.
- `GET /api/v2/portfolio/returns/collections/{transactionHash}` lists what the wallet claimed in one transaction, with the amount each claim paid. Read it after a claim settles. An empty list means no claim by this wallet is indexed for that transaction yet.


# Settlements

Source: https://docs.settlemint.com/docs/console/my-assets/settlements
Create a multi-party exchange, approve and lock your leg, then execute, cancel or withdraw after expiry. Every local leg moves in one transaction or none does.

An XvP Settlement exchanges asset amounts the parties agreed beforehand. A local flow is a transfer on this chain, and an external flow is one on another chain. Each sender of a local flow approves the settlement, which locks the amount it owes. Before a secret is revealed, execution moves every local leg in one transaction, or none moves. After a reveal commits a cross-chain settlement, a delivery the token refuses is parked for its recipient and the other deliveries complete. An external flow needs its own funded contract on the other chain. [XvP Settlement](https://docs.settlemint.com/docs/concepts/settlement/xvp-settlement) explains the atomicity and net-position model behind every step on this page.

Use a [transfer](https://docs.settlemint.com/docs/console/asset-management/manage/transfers) to send tokens without a reciprocal exchange. Use [Trading](https://docs.settlemint.com/docs/console/my-assets/trading) to trade against an order book. A settlement uses amounts agreed before creation. It does not discover a price.

![Settlements list with the Create XvP settlement action](https://docs.settlemint.com/docs/screenshots/console-settlements-list.light.en.webp)

[Screenshot] The "Settlements" list with a "Create XvP settlement" button and one row per settlement.

Each row shows the settlement's name and type, "Status", "Approvals", "Expiry" and a row menu under "Actions".

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

- **Approving.** Your wallet must be the sender of a local flow and hold the amount it owes. Any signed-in account can create a settlement, but nothing moves from a sender's wallet until that sender approves its own leg, and the contract checks the sender itself.
- **Approve and Revoke approval.** Only the settlement's local senders can run them.
- **Execute settlement and Reveal secret.** Any account can run them, once the status allows it.
- **Withdraw assets.** Any party to the settlement can run it: its creator, a sender or recipient of a flow, or an approver.
- **Cancel settlement.** Only an account that sends or receives a flow on this chain can run it.
- **What the Console shows.** The Console shows only the steps your account and the settlement's status both permit. The contract accepts execute, reveal and withdraw calls from any account, whatever the Console shows.

## Steps [#steps]

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

In the Console, select **Settlements** under "Wealth" in the sidebar. The entry appears once your organisation has the XvP settlement add-on. With the "Permission manager" or "Asset manager" system role, the list shows every settlement the add-on has created. Without either role, it shows only the settlements where one of your wallets is the creator, a sender or recipient of a flow, or an approver.

The list includes settlements in every status, and each row shows the settlement's name, type, status, approval progress and expiry. The creation date is one of the columns you can switch on in the table's view options. A settlement that waits for your approval reads "Needs your approval" and has an "Approve" button on its row. A local participant can also use the row's "Cancel settlement" shortcut to open the cancel dialog.

### Create a settlement [#create-a-settlement]

Select **Create XvP settlement**. The wizard has three steps, starting with "Asset flows", which defines who sends what to whom, one flow per transfer.

![Create XvP settlement wizard at the Asset flows step](https://docs.settlemint.com/docs/screenshots/console-settlements-create-flows.light.en.webp)

[Screenshot] The first step, "Asset flows", opens with one local flow, "Flow 1", and its "From address", "To address", "Asset" and "Amount" fields.

**Add local flow** describes a transfer that executes on the current chain. "Add external flow" describes one on another chain that this settlement does not execute itself. Each flow sets a from address, a to address, an asset, and an amount, and an external flow also names its chain and the asset's decimals. A field left empty, the amount included, reads "This field is required" under it. A from or to address whose capitalisation does not match its checksum is refused on the field rather than rewritten, so a mistyped paste is caught before the settlement is created. "Import flows" loads a whole set from a JSON file. A settlement needs at least one local flow and holds at most 100.

**Settlement configuration** names the settlement and sets the "Expiry date" after which it can no longer execute. The wizard proposes a date seven days out. "Auto-execute on final approval" runs the settlement the moment the last approval or reveal lands, instead of waiting for a manual execution.

When any flow is external, this step also asks for "Secret management". Choose "Enter hashlock" if you already hold the matching secret outside the Console, or "Enter secret" to type or generate one. The platform then derives the hashlock when it creates the settlement and stores the secret encrypted off-chain. The settlement's secret tile shows the hashlock to share with the counterparty. Only the creator of a cross-chain settlement handles the secret. A counterparty only approves.

If the form shows "Country", it uses that value when registering the settlement contract's identity. **Review settlement** then shows the settlement type the Console derived from the chains involved, every flow, and every setting before you confirm.

### Approve, then execute or wait [#approve-then-execute-or-wait]

Open a settlement from the list to reach its detail page. If you are a local sender named in one of the flows, select "Approve" on its list row, or **Approve settlement** in the page header, to lock your asset in the contract. If another wallet of yours is the sender, the button is disabled and tells you to switch to the wallet that sends a flow in this settlement. If your custody account signs in your own wallet, the sheet asks that wallet to confirm the approval, together with any spending allowance the lock needs, and records the approval once the wallet signs.

"Actions" lists the other steps your account can take. The approvals panel counts how many of the settlement's local senders have approved so far. Once every local sender has approved, a settlement with only local flows becomes ready immediately, while a settlement with a cross-chain flow waits for whoever holds the secret to reveal it. When the settlement is ready, select "Execute settlement". Executing cannot be undone. With "Auto-execute on final approval" on, the final approval runs it, or on a cross-chain settlement the reveal does.

## Manage an existing settlement [#manage-an-existing-settlement]

**Actions** on a settlement's detail page holds five more steps, and the Console states each one's consequence before you confirm.

| Action | What it does | Choose it when | Consequence |
| --- | --- | --- | --- |
| **Reveal secret** | Unlocks a cross-chain settlement for execution. | Every external hashed timelock contract the settlement depends on already holds funds. | Cannot be undone. A counterparty can use the secret from the moment it lands on-chain, and **Cancel settlement** disappears once revealed. |
| **Revoke approval** | Unlocks your own asset and returns it to your wallet, unless the token refuses the delivery, in which case the settlement holds it for **Claim parked amount**. | You want out before the settlement executes, expires, or cancels. | Stays available on a local-only settlement even after everyone has approved. On a cross-chain settlement it disappears once every sender has approved. |
| **Cancel settlement** | Closes the settlement for every party and refunds every locked asset. | Before every sender approves, or on any settlement with only local flows. | Once a cross-chain settlement reaches full approval, this becomes **Propose cancel**, a vote every local sender and recipient must join. |
| **Withdraw assets** | Returns every local participant's locked asset in one transaction, except a refund the token refuses, which stays parked for its sender to claim. | The settlement expired without executing. | Any party to the settlement can trigger it, and it runs once for the whole settlement. |
| **Claim parked amount** | Sends a refund, or on a revealed cross-chain settlement a settled delivery, that a token refused and the settlement holds for you, to an address you choose. | The settlements list marks the settlement with **Parked amount to claim**. | If the chosen address does not accept every listed asset, nothing moves and you can claim again to another address. |

Revealing the secret cannot be undone. Select **Reveal secret** only once every external hashed timelock contract the settlement depends on holds funds. The Console warns that counterparties can use the secret the moment it lands on-chain, whether or not you execute. A reveal before an external leg holds funds lets a counterparty take the secret without delivering their side.

After the cutoff date, **Reveal secret** no longer appears, so an unrevealed cross-chain settlement can only be withdrawn. The reveal also commits the settlement: "Cancel settlement" disappears, withdrawal after expiry no longer applies, and the settlement can only execute.

After you revoke, you can approve again whenever you are ready. On a cross-chain settlement that reached full approval, cancelling or letting the settlement expire are the only ways left to back out.

Cancelling closes the settlement for every party, but the Console asks for it differently depending on how far the settlement has gone. Before every sender has approved, or on a settlement with only local flows, **Cancel settlement** closes it directly and refunds every locked asset.

Once a cross-chain settlement reaches full approval, cancelling becomes a vote instead: "Propose cancel" records your consent and the Console names how many more votes are needed. Every local sender and recipient in the settlement's flows gets a vote, not only its senders. When yours is the last vote needed, the Console shows a direct cancellation instead. If a needed participant never votes, the only other way out is to wait for the cutoff date and withdraw.

A refund that a token refuses stays parked in the settlement. On a cross-chain settlement whose secret is revealed, a delivery the token refuses at execution is parked too. On any other settlement, that refusal makes the execution fail and nothing moves. The settlements list marks such a settlement with "Parked amount to claim" for the wallet it is parked for.

Select **Claim parked amount** under "Actions". Under "Send to", choose "My wallet" or "Another address". Before you confirm, the Console checks that each listed asset accepts that address. The address must accept every listed asset: if one refuses, nothing moves, and you can claim again to another address. Once the settlement's secret is revealed, a parked refund cannot be claimed: the settlement can only execute. The Console hides "Claim parked amount" until it has executed.

The **Escrow** tile on a settlement's detail page lists, for each participant and asset, the amount "Locked" into the settlement, the amount "Parked" for them, and the amount "Refunded". It appears once anyone has locked an asset or has an amount parked. Before execution, the locked amount minus the refunded amount is still in the settlement. Execution delivers the locked amounts and leaves the tile's totals as they were.

To find the settlements whose contract still holds money, add the **Escrow** filter in the settlements list and choose "Holds escrow". The filter keeps a settlement that holds a parked amount, and one that was cancelled, or passed its cutoff date without a revealed secret, while a participant has locked more than the settlement refunded. "Withdraw assets" or "Claim parked amount" returns that money.

## What approving locks [#what-approving-locks]

Only the local senders named in the flows approve, and each approval locks that sender's assets in the settlement contract as soon as it clears. The contract pulls them through an ERC-20 allowance, so the approval sheet shows your current allowance for each asset and says whether approving sets it to the amount the settlement locks. They stay there, unavailable to you, until the settlement executes, someone cancels it, or you revoke.

Passing the cutoff date does not free them by itself: it only stops the settlement from executing, and someone still has to select **Withdraw assets** afterwards to return them. Short of its cutoff date, nothing in the settlement times it out, and "Pending" or "Waiting for secret" lasts as long as the remaining senders take to act.

The settlement contract sits on the compliance bypass list, so your deposit into escrow skips the recipient-side checks, and execution applies them. A holder of a token's "Custodian" role can still freeze or move an escrowed amount of that token. [What if a sender falls out of compliance after approving?](#what-if-a-sender-falls-out-of-compliance-after-approving) covers the compliance check at execution.

## Settlement statuses [#settlement-statuses]

The Console shows one of seven statuses on every settlement, and each tells you what you can still do:

- **Pending** means at least one local sender has not approved yet.
- **Waiting for secret** means every sender has approved, but the settlement includes a cross-chain flow whose secret nobody has revealed.
- **Ready** means nothing stands between the settlement and execution.
- **Expired** means the cutoff date passed without execution.
- **Ready after reveal** means the secret is revealed, so the settlement stays executable past its cutoff date.
- **Executed** means the settlement ran and is closed for good.
- **Cancelled** means the settlement was cancelled and is closed for good. A cancelled settlement can never execute.

Executing, revealing a secret and cancelling cannot be undone, and each says so before you confirm.

[Figure] Approval, execution, and cancellation of a settlement. A settlement starts awaiting approval and moves to fully approved once every local sender approves. From there, executing pays every leg in one transaction and cannot be undone. A successful cancellation refunds every locked asset. Revoking an approval refunds that sender without closing the settlement. Expiry requires a separate withdrawal to refund locked assets. Labels: Awaiting approval; senders still to approve; Fully approved; ready, or waiting on a secret; every sender approves; Executed; value moved, cannot be undone; Cancelled; every locked asset refunded; execute; cancel; cancel.

Approving locks a sender's assets, execution transfers them, cancellation refunds them, a revoked approval refunds
only that sender, and expiry needs a separate withdrawal, unless a revealed secret keeps the settlement executable.

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

- After approval, execution, or withdrawal, check the Settlement Verdict and the settlement status. An operation is done when its transaction confirms, and the status then changes.
- Return to the settlements list and confirm it shows the expected status. Approved senders move it towards "Ready" or "Waiting for secret", execution moves it to "Executed", and a cancellation or a passed cutoff moves it to "Cancelled" or "Expired".
- Open the settlement's detail page and confirm the approvals panel, the flows table, and, once revealed, the secret panel show your action. The approvals panel names the sender and timestamp behind every approval, and the secret panel names who revealed the secret and when. The full event history is on chain, as [XvP Settlement](https://docs.settlemint.com/docs/concepts/settlement/xvp-settlement) describes.
- Once a settlement reaches "Executed", "Cancelled", or "Expired", its status no longer changes. A parked amount on it stays marked "Parked amount to claim" until its owner claims it.

## Troubleshooting [#troubleshooting]

**Approve settlement shows an insufficient balance**

The approval sheet names the assets and the amount still needed before it lets you approve. Add funds to the sending
wallet and try again. Approval locks, for each asset, the net amount the sender owes across all its flows in the
settlement, and it cannot partially lock a smaller balance even when your wallet holds most of what is needed. Check
the sending wallet against the flow's asset and chain as well as its amount, since a shortfall on the wrong asset
produces the same message as a shortfall on the right one.

**The configuration step does not accept a cross-chain settlement**

Any external flow makes a hashlock or a secret mandatory, because a cross-chain settlement cannot execute atomically
without one. The **Settlement configuration** step blocks with "External flows require a valid hashlock or secret.
Enter an existing hashlock, or enter or generate a secret before continuing." Pick "Enter hashlock" if you hold the
matching secret outside the Console, or "Enter secret" and let the platform derive the hashlock when it creates the
settlement.

**Creation fails on a flow that pays its own sender**

The settlement contract refuses a flow whose sending and receiving address are the same, since such a flow never moves
anything from one party to another, so creating the settlement fails. It does allow the same address to appear across
different flows of one settlement. This supports circular obligations between counterparties. Review each flow's own
sender and recipient before you create.

**A settlement shows a cross-chain warning after creation**

A settlement with an external flow warns that the platform cannot verify an external contract or a counterparty's
behaviour on another chain. Before you reveal the secret, confirm outside the Console that the external hashed
timelock contract holds funds and matches the flow. A reveal without that check lets a counterparty take the secret
without delivering.

**A fully approved settlement is still waiting**

A settlement with a cross-chain flow does not become ready when every local sender approves. It waits until whoever
holds the secret reveals it. After twelve hours in that state the Console adds its own reminder: "All approvals in,
still waiting for secret reveal." **Reveal secret** no longer appears after the cutoff date. An unrevealed settlement
that reaches that date cannot execute. Its locked assets then wait for one "Withdraw assets", which any party can
select after the cutoff. If you did not expect the wait, confirm with whoever created the settlement whether anyone
can still reveal the secret before the cutoff.

**Execute settlement fails or the status does not change**

**Execute settlement** is one transaction: on a settlement whose secret is not revealed, every local leg pays out, or
none does. On a cross-chain settlement whose secret is revealed, a leg the token refuses is parked instead of failing
the execution. When it fails, the Console shows an error naming why, and the settlement's status does not change and
no leg has paid out. Correct whatever the error names and select "Execute settlement" again.

**Cancel shows a vote count instead of closing the settlement**

Once a cross-chain settlement reaches full approval, cancelling needs the consent of every local participant,
recipients included, so no single party can unwind a shared exchange alone once everyone has locked value into it.
"Cancel settlement" becomes **Propose cancel**, and the Console shows how many votes remain. If a needed participant
does not vote, the settlement cannot be cancelled. After the cutoff date, any party can select "Withdraw assets".

**A settlement's expiry is approaching**

The Console flags any settlement inside 24 hours of its cutoff with "Settlement expires soon". Execute it before the
cutoff if it is ready. If it is not ready in time, it expires, and any party to the settlement can then select
**Withdraw assets** to return the locked assets.

## Frequently asked questions [#frequently-asked-questions]

### How large can one settlement be?

A settlement holds up to 100 flows, and each flow moves one asset from one sender to one recipient, so the number of parties is limited only by how many distinct addresses those flows name. When one address appears in several flows, the contract settles its net position per asset rather than paying each flow separately, so a party that both sends and receives the same asset only moves the difference.

### Can I change a settlement after creating it?

No. The flows, amounts, expiry date, and auto-execute setting are fixed the moment the settlement is created, and nothing under **Actions** edits them. To correct a mistake, back out of the existing settlement, by revoking, cancelling, or letting it expire, and create a new one with the right values. Counterparties re-approve the new settlement from scratch.

### What do "Local" and "HTLC" mean in the list's type column?

"Local" means every flow executes on the current chain, so full approval alone makes the settlement ready. "HTLC" means at least one flow describes a transfer on another chain, so the settlement is protected by a hashed timelock: it needs a hashlock at creation and a revealed secret before it can execute. The Console derives the type from the flows. You never choose it directly.

### What if a sender falls out of compliance after approving?

Execution re-checks every funded local flow against the asset's compliance rules at the moment it pays out, so a party whose status changed between approval and execution blocks the whole settlement, and the error names the failing leg. The one exception is a cross-chain settlement whose secret is already revealed: it is committed, so the re-check is skipped and the settlement executes. On that revealed settlement, a delivery the token refuses is parked for its recipient to claim with **Claim parked amount**.

## API routes [#api-routes]

The [Platform API reference](https://docs.settlemint.com/docs/api-reference/v2) documents settlement creation, approval, and execution for integrations. The [CLI command guide](https://docs.settlemint.com/docs/api-reference/cli/commands) explains how to call those endpoints from the command line.


# Trading

Source: https://docs.settlemint.com/docs/console/my-assets/trading
Place orders on a permissioned venue, track buying power, amounts reserved for orders and what sits in venue escrow, and follow fills through delivery or undo.

Trading is the Console workspace for choosing a listed instrument and placing an order against its order book. The order book is the running list of resting buy and sell interest an instrument keeps until a matching order arrives. This is the secondary market. [Primary Offerings](https://docs.settlemint.com/docs/console/asset-lifecycle/primary-offerings) runs a token's first sale at a price the issuer fixed, and once that sale has delivered units to investors, they change hands here at whatever price the book gives instead of a fixed one. To move tokens without a price, use a transfer. When both parties already agree every amount, use [XvP settlement](https://docs.settlemint.com/docs/console/my-assets/settlements). To list, change or halt an instrument, use [Venue operations](https://docs.settlemint.com/docs/console/asset-lifecycle/venues).

Signing an order does not complete the exchange. Placing the order locks its amount in the venue's escrow. You sign a request naming the side, order type, quantity, and expiry, and the venue's book decides whether and when that request becomes a fill. The workspace shows the venue's order book and trades. Market Data explains the separate on-chain price feeds. Transfer-Path Compliance explains why a match does not prove delivery: each delivery leg must pass its token's checks, so the book can match two orders and settle nothing.

![Trading page listing instrument cards with the Tradable now and All visible filter](https://docs.settlemint.com/docs/screenshots/console-trading-markets.light.en.webp)

[Screenshot] The Trading page lists one card per instrument with its status, last price, change and 24-hour volume, under a filter that switches between Tradable now and All visible.

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

- Your wallet must be eligible for the selected instrument. It must meet the identity requirements its tokens enforce and, on a private instrument, be approved on its participant list.
- Your wallet approves the venue's escrow for the part of each leg that your free escrow balance does not cover. [Authorise the venue's escrow](#authorise-the-venues-escrow) gives the step.
- For a buy, the full amount is the principal plus the maximum fee, shown on the ticket as "Order amount plus maximum fee".
- When the venue charges VAT on fees, the line reads "Order amount plus maximum fee, VAT included" on an instrument that collects VAT on chain, where the maximum fee holds it, or "Order amount plus maximum fee, VAT not reserved" on one that only reports it.
- For a sell, it is the base quantity alone. No fee is locked. The fee comes out of what you receive, so a sell ticket shows **Minimum proceeds**: the quote amount you get if the full quantity fills at the limit price, or at the protection-band floor for a market order, after the maximum fee.
- The approval to the escrow is the only one you give.
- The session must accept the selected order type, and your spendable balance must cover the new order on top of what your open orders already lock.

An order you sign while working as another participant is signed for that participant. [Delegated authority](https://docs.settlemint.com/docs/concepts/compliance-and-identity/delegated-authority#attribution-needs-both-records) explains how the records name you and the participant you acted as.

## Steps [#steps]

### Select an instrument [#select-an-instrument]

Open **Wealth**, then "Trading". The page lists each instrument as a card with its status, last price and 24-hour volume. "Tradable now" shows the instruments you can trade now, and "All visible" adds the instruments you can see but cannot trade now. Select a card to open that instrument's workspace. The workspace header shows a breadcrumb back to the "Trading" list, the pair with its mode, one status badge, the last price, the best bid and ask with the spread, the session and 24h figures, and the 52-week range, which reads "52-week range (since first trade)" for an instrument younger than a year. The figures sit on one line. Those that do not fit move, from the last one back, behind a button at the end of the line that counts them, for example "3 more", so the bid and ask stay next to the last price. Each price in the header ends with the quote symbol, for example "4.0000 EUROC", and each quantity with the base symbol. The panels below carry the order book, recent trades, chart, your balances, and your orders. "Recent trades" shows the quote symbol under its "Price" head and the base symbol under its "Quantity" head, as the order book does, and writes its times with the chart axis's clock and the page language's separators. The row between the asks and the bids in the order book shows the same last price as the header, with the spread beside it, and reads "No trades yet" while the instrument has no trade that stands. A trade that is undone is not a last price: the header, the order book and "Recent trades" all leave it out. When settlement undoes a trade the live view already showed, "Recent trades" drops it at once and the header corrects its last price and its session volume and value, without waiting for the next trade. An instrument you cannot find may be private: only approved wallets see and trade a private instrument, so ask the venue operator if you expect a pair that is not offered.

### Read the instrument terms [#read-the-instrument-terms]

Select the **Instrument** tab to read the base and quote tokens' terms. When collateral is reported, "Collateral" shows the amount and, when outstanding supply is positive, its percentage of that supply. In the Console and Investor portal, amounts and percentages use the figure face. The translated words around them use the body face and follow your language's word order.

### Check the session and instrument [#check-the-session-and-instrument]

Read the status badge in the header before entering an order, and select it to see what the session means, when it next changes, in UTC and in the time zone of the instrument's trading calendar, and how long ago the last instrument update arrived. When the instrument is open and its data is current the badge reads **Session open · Live**. A paused venue, an instrument halt, a stale or lost data stream, or a non-continuous session replaces that text, and the first that applies in that list wins. "Session closed" refuses every new order except a "Day" limit order, which waits for the next session. "Pre-open" and "Opening auction" collect limit orders without matching, and the instrument opens at an undisclosed instant inside its published window, so nothing crosses until then. "Closing auction" also collects orders without matching, and one uncross at its end crosses them at a single price, which becomes the day's official close. The auction ends at the Trade at last time when the day has one, and at the session close otherwise. "Interrupted · Volatility" means a trade would have printed beyond the instrument's volatility threshold from its reference price: new orders are collected without matching, the badge details name the time trading resumes, and a single-price auction crosses the orders then. An instrument whose calendar has no preopen skips that phase: it goes from "Session closed" straight to trading at the scheduled open, and the badge details name the open time instead of a window. "Session open · Live" means continuous trading is running on current data. While orders are collected, the header leads with the indicative price and matchable quantity when the instrument's publication setting makes them visible. When the setting withholds the price from you and the bids and asks already meet, the header reads "Not published" and the order book's middle row reads "Indicative price not published". When no price would match yet, both read "No indicative price yet". Check the instrument status too: an instrument showing "Instrument halted" accepts nothing until an operator resumes it, and your resting orders wait untouched through the halt. On the trading desk header, "Open price" is the opening auction price of the current session, or the first trade of the session when the auction set no price. The first candle on the chart opens at the first trade, so the two can differ.

### Enter the order [#enter-the-order]

Choose **Buy** or "Sell", then the order type: "Limit", "Market" or "Stop". Select the time in force: "Good till cancelled", "Good till date", "Day", "Immediate or cancel", or "Fill or kill". [Choose an order type and time in force](#choose-an-order-type-and-time-in-force) compares them. Enter the price, quantity, or expiry the chosen combination requires. The price and quantity fields take the amount in your own number format with the token's symbol and read a suffix such as `1.5k`. Text the field cannot read as an amount blocks the order. An entered price reads at the instrument's price step, so a book price of 4.0320 stays 4.0320. The order types and the time in force sit on one row: when a language's order type names need more room than the ticket has, as three Thai order types do, the order types wrap onto a second row instead of pushing the time in force selector out of the ticket.

Then read the amount the venue locks, under **Reserved for this order**, before you commit. The ticket shows the exact amount, with the order amount and maximum fee beside it, so those parts add up to the total you read. When a buy is blocked, the ticket names the amount it needs, rounded up, and your buying power, rounded down, at the digits of the instrument's price step, or of its lot size for a sell, so a blocked order never reads as affordable. The review step shows the same reserved amount and maximum total.

"Estimated VAT" on the ticket is written at the digits of the price step, rounded down. In the review, prices, fees, VAT and totals in the quote token share enough decimal places to show every amount exactly, with the price step as the minimum. Trailing zeros align those figures. Base quantities keep the lot size's precision.

Your buying power is your wallet's available balance plus your free escrow balance, the figure "Balances" shows. "Balances" writes every other amount the same way, at the digits of the price step for the quote token and of the lot size for the instrument, rounded down. An amount that has more digits shows "≈" before it: point at it or move focus to it to read the exact amount. In Arabic, "≈" stays immediately before the digits, beside the amount and its currency. Prices, quantities and percentages keep the same fixed-width face as in English in both the Console and Investor portal. The "Withdraw" confirmation names the exact amount it moves. Until you lower the quantity or the price, you cannot select "Place buy order". A sell of more than you can sell stops at the ticket the same way.

The desk header also shows **Price band** with the lower and upper limits while the instrument has a bounded band. Check the "Price band" line under the limit price: it shows the band in force and follows a band change while the ticket is open. A limit price can equal either bound, but outside it the ticket says so and you cannot review the order. When a dynamic band has no anchor yet, the ticket says the instrument accepts no orders.

The price band follows the instrument's setting: the venue default, **Off**, or an override. A static policy fixes minimum and maximum quote prices. A dynamic policy starts around the previous official close and expands only the side reached by a trade, up to its cap. A dynamic band that rolls on close has no anchor between the session close and the official close, so every order is refused until the official close lands. A market order is signed at its separate protection-band edge. Each fill must also stay inside the effective price band. If an operator saves a tighter policy, excluded open orders are closed as "Rejected" with the price-band reason and their reserved balances are released.

To place a stop order, choose **Stop** as the order type. A stop asks for a "Trigger price" and a limit price, and takes "Good till cancelled", "Good till date" or "Day". The venue reserves the balance when you place the stop and holds it while the stop is armed, so you see the reserved amount before you commit. A sell stop must trigger below the current market price and a buy stop above it. When the instrument trades at the trigger price, the order joins the order book at your limit price. While the stop is armed, "Open orders" shows the "Stop armed" status with "Triggers at" and the trigger price beneath it, in the Investor portal too. Cancel an armed stop from "Open orders" to release the balance.

When the instrument has a minimum order quantity, a smaller quantity names the minimum under **Quantity** and you cannot select "Place buy order" or "Place sell order" until you raise it. On a bond past its trading cut-off, or on a venue an operator has paused, the ticket says so beside the button and accepts no order, so nothing reaches the venue to be rejected. A halted or delisted instrument gets the same treatment, and the ticket names which of the two it is. A delisting is final, so on a delisted instrument every ticket control is also turned off: buy or sell, the order type, time in force, and the price, quantity and expiry fields. The same holds in the Investor portal order ticket, for "Place buy order" and "Place sell order". A pause or a resume reaches an open trading desk without a reload.

### Authorise the venue's escrow [#authorise-the-venues-escrow]

When your approval to the venue's escrow is missing or no longer covers the shortfall this order needs, the ticket offers "Authorize". Select it, approve the named venue escrow for the amount the ticket shows, and verify your wallet. An order your free escrow balance already covers needs no approval. [Trading authorization required](#troubleshooting) covers the cases where the ticket names another reason instead.

### Place the order [#place-the-order]

Select **Place buy order** or "Place sell order". The ticket turns into "Review your order" with the figures you are about to sign. Select "Confirm buy order" or "Confirm sell order" and verify your wallet, which signs and places the order.

## Set a price alert [#set-a-price-alert]

A price alert watches one instrument and fires once, on the first trade that prints at or beyond its price. Select **Set alert** in the trading workspace to open "Set a price alert". Choose "At or above" or "At or below" under "Alert when the price is", enter a price on the instrument's tick size, in your own number format with the quote token's symbol, select "Create alert" and verify your wallet.

When the alert fires, the platform adds it to your notification list, which the Platform API serves, and emails you if email is on for price alerts. A venue operator sets the organisation default on the **Participant alerts** tab of Venues, and you change your own setting under "Notifications" in the Investor portal or through the notification preferences endpoint of the Platform API. The platform also sends the "trading-venue.price-alert.triggered" webhook, which the [webhook event reference](https://docs.settlemint.com/docs/api-reference/webhooks/market-events#trading-venue) describes. The price comes from a matched trade before settlement, so treat it as a signal until "trading-venue.trade-settled.final" arrives for that trade.

Your alerts are under **Price alerts** on the "Watchlists" page of the "Personal" group, with their instrument, condition, status, which is "Active" or "Triggered", and creation date. Other users cannot list, change or delete them. Select "Delete" and verify your wallet to remove one. The Investor portal also offers an alert on a percentage move from the previous official close, and lets an investor change an alert that has not fired.

## Choose an order type and time in force [#choose-an-order-type-and-time-in-force]

| Order type | How it meets the book | Choose it when | What it costs |
| --- | --- | --- | --- |
| **Limit** | Rests at your price until it fills, expires, or you cancel it. | The price matters more than the timing. | It may never fill, and its lock holds part of your balance while it waits. |
| **Market** | Takes the prices resting on the book now, inside the market-order protection band. | Completing the trade now matters more than the exact price. | You accept every price inside the band, and the session must be in continuous trading. |
| **Stop** | Joins the book at your limit price once the instrument trades at the trigger price. | You want to act only once the price reaches a level. | The balance stays reserved while the stop is armed, and the stop may never trigger. |

Time in force decides how long a resting order waits. **Good till cancelled** is the default. It signs an expiry so far ahead that it never lapses, so the order rests on the book until it fills or you cancel it. "Good till date" lets you set the expiry yourself, in UTC, down to the minute. The ticket marks the expiry field only after you enter or clear a date: an empty field you have not touched stays plain, and you cannot place the order until it holds a future expiry. "Day" rests until its trading session closes, when the venue expires it, so an early close, a holiday, an extended session or a delayed open moves the expiry with it. A "Day" limit order placed while the session is closed belongs to the next session. An instrument with no trading calendar has no session close to end it, so the ticket does not offer "Day" there. "Immediate or cancel" takes whatever fills at once and cancels the rest, so it never rests. "Fill or kill" fills the whole quantity at once or not at all. Choose "Good till date" when a stale order would be a risk if it rested indefinitely. Choose "Immediate or cancel" when a partial fill now is worth more than a full fill later. A market order never rests, so for "Market" the ticket offers only "Immediate or cancel" and "Fill or kill".

A venue can also limit the order types and the time in force that all its instruments accept, so the ticket for an instrument offers only what the instrument accepts after the venue's limit. If an option you expect is missing, the venue may have limited it. The limit applies to new orders, and an order that was already resting stays on the book.

The session state also limits what the ticket offers. An auction takes limit orders only, so during pre-open and the opening or closing auction the ticket turns off **Market**, "Immediate or cancel" and "Fill or kill". During a Trade at last session, the ticket offers only limit orders, with the price locked to the last price and no "Immediate or cancel" or "Fill or kill".

## What an order locks, and when a fill settles [#what-an-order-locks-and-when-a-fill-settles]

[Figure] How an order moves from the session gate to settlement. A signed order names its side, type, quantity, and time in force. The session gate decides what happens next: an open session sends it to the book, an auction holds it uncrossed while it collects orders, and a closed session refuses it unless it is a Day limit order, which rests for the next session. The book matches the order inside the instrument's price bands on its tick and lot grid. Every match then passes compliance on both legs before it settles. A passing match settles on-chain and the fill moves value. A blocked match does not settle, and the platform parks the fill with the refusal reason for a venue operator to review. Labels: Signed order; side, type, quantity, time in force; Session gate; closed refuses, open matches,; auction collects; Refused; session closed; Collected; for the auction; Book matches the order; price bands, tick and lot grid; Compliance checks both legs; Settled; the fill moves on-chain; Blocked; the fill does not settle; it is parked with its reason.

One order passes the session gate, the book and compliance on both legs, then settles on-chain or parks with its
refusal reason.

A fill can wait out the instrument's holding period, a delay before delivery. Delivery transfers the net legs under the tokens' rules. A venue operator can undo a pending delivery before its deadline. The platform does not offer an undone lot again, and its owner can place it as a new order.

Placing an order locks part of your balance in the venue's escrow. You still own it. For a buy, the venue locks the quote notional plus the maximum fee in the venue's escrow. It deposits from your wallet only the shortfall, the part your free escrow balance does not already cover. A sell locks the base quantity the same way, and pays its fee out of the quote proceeds instead. A locked leg leaves the escrow at delivery. If the token refuses a delivery to your wallet at that moment, the leg stays in the escrow as free balance instead (see below). Cancelling takes the order off the book at once after you verify your wallet, and the confirmation names the order it cancels, with its side, quantity and price. The locked amount returns to your free escrow balance once the platform's refund transaction confirms. Your free escrow balance stays in the escrow until you withdraw it. The **Balances** panel shows the free and locked amounts per leg, with a "Withdraw" action that sends free balance to your wallet.

The trading interface does not expose your identity or remaining position to a counterparty. Public chain records can still reveal the participating addresses and transfers. **Order history** and "Your trades" record fills and closed orders.

A venue operator can undo a trade within 24 hours of it through a trade bust in [Venue operations](https://docs.settlemint.com/docs/console/asset-lifecycle/venues). A second operator approves the bust while the venue's **Trading venues** row under "Approvals" is on. With that row off, one operator alone busts an undelivered trade. A bust of a delivered trade always needs a second operator. Before delivery, a bust releases the locked legs. After delivery, it reverses the transfers with a forced transfer of both legs, which no trader signs: the platform grants the token's Custodian role on both tokens to your organisation's operations signer for this purpose. "Your trades" marks the result "Undone", and the tokens go back to their owners. The undone lot does not return to the book, and the filled figure of the orders leaves it out. The venue also undoes a trade at its due time, without an operator, when an outside cause blocks delivery: the token is paused, a custodian shrank the trade's locked amount, the sending side is frozen, or a receiver is added to the compliance bypass list during the holding period. Only the order on the side that failed shows "Settlement failed", with the reason. Every other order on the trade keeps its own status and close reason and adds a note that a trade was undone, and an order that is still open stays open for the rest of its quantity.

Any other refusal at the due time does not undo the trade. If the token refuses to pay you, for example because your identity claim lapsed during the holding period, the trade still delivers: the counterparty's leg is paid and your leg waits as free balance in the venue's escrow, so you cannot get out of the trade by making yourself unable to receive. "Your trades" shows the trade as delivered. **Balances** shows the units in your free amount, and you withdraw them with "Withdraw" once the token's rules accept your wallet again. The withdraw runs the token's compliance and freeze checks, so an unverified or frozen wallet cannot take the units out. It cannot sell them on the venue either: while the token's identity registry does not verify you, or the token's rules would refuse the escrow paying you, an order that needs units from your free balance is refused with `MakerCannotReceiveToken`. Complete verification first, then withdraw or sell.

On an instrument with a holding period, the venue also refuses a fill when the buyer, the seller or a fee recipient is the zero address, the escrow, or an address on the token's compliance bypass list, because it could not pay or book to that address at delivery. This is refused with `InvalidDeliveryRecipient`. An instrument with a zero holding period delivers at the fill and has no pending-delivery window.

## Read the chart, order book and order tables [#read-the-chart-order-book-and-order-tables]

### The price chart [#the-price-chart]

Pick a range under the chart, or from the range menu in the chart toolbar on a narrow chart: **1D**, "5D", "1M", "3M", "6M", or "All". The workspace opens on "1D". The "Candle interval" control reads "Auto" with the interval it chose, for example "Auto · 5m": it takes the finest interval that fits the range in at most 500 candles, or 190 for 1-day candles, and otherwise 1-week candles, so "1D" shows 5-minute candles and "1M" shows 4-hour candles. "All" shows 1-week candles once the history is longer than about six months. A market with less history than the range starts at its first candle. Pick an interval yourself and it stays across ranges until you pick "Auto" again. A range shows at most 500 candles, so a fine interval shows only the newest part of a long range. The price axis fits the candles of the range, so older prices outside it do not flatten the chart. With the orders overlay on, the axis also stretches to reach an open order priced just beyond the candles, so the order keeps its line on the chart. An order far outside the candles' range is not drawn, and the chart counts it above or below the range instead. Drag the price axis to zoom the prices, and double-click the axis to fit it again. Every price-axis label carries the instrument's price step, in figures of equal width, so a price below 4 reads 3.9990 and its separator sits in the same column as every other label's. The time axis shows clock times, and a tick that falls on midnight shows its date, so a range of several days reads by day. 1-day and 1-week candles show dates only.

The chart draws a candle, bar or line point only for an interval that holds a trade, so every candle stands for trades you can find in **Recent trades**. An interval without a trade, including the hours the instrument's session is closed, stays empty on the time axis. Hovering an empty interval shows the prices of the last interval that traded before it, and nothing when no earlier interval in the range traded. The same range and interval show the same trade history in every language, whether the orders panel is open or hidden. A range with only one interval that traded shows one candle. The indicators skip intervals without trades too. An indicator without enough candles shows how many it needs in the legend, for example "Needs 21 candles", or "Needs 21 candles with trades" when the range has enough candles but too few of them traded.

The Open, High, Low and Close summary keeps each label whole and wraps onto more lines when the chart is narrow. Working-order labels sit in their own column beside the price axis, at their order prices, so the last-price tag can stay visible without covering them. The Investor portal chart follows the same layout.

The chart marks your own fills, but only your newest 200 fills in the instrument, so an older fill on a long range has no mark. "Your trades" lists every fill. The Investor portal chart marks your newest 200 fills from the day before the range's first candle onwards, so on a long range with more fills than that, the oldest fills have no mark there either.

### The orders panel and the order book [#the-orders-panel-and-the-order-book]

On a phone, scroll the page to read every order-book level. Each side takes the space its levels need, and **Recent trades** follows the last bid.

**Toggle orders panel**, at the end of the chart tabs, hides the row with your orders and trades and gives its height to the chart and the order book. Dragging the top edge of the row down hides it too. To bring the row back, select the toggle again, drag the bottom edge of the chart and order book row up, or select "Show the orders panel" on the "Orders (n)" bar, which counts your open orders in this market: the same number as the "Open orders" tab, suspended orders included. The workspace keeps your choice across a reload. On a screen under 800 pixels tall the row starts collapsed until you choose. On a narrow screen, where the panels stack, the row always shows. With the row open, the order book keeps its price steps, column headers, the whole spread row and at least one ask and one bid level, however many orders you have. The orders table scrolls inside its own area.

**Price step**, above the order book, groups its levels into price buckets. The first option is the instrument's own price step, one tick, which shows every resting price. The next options are 2, 5, 10, 50 and 100 ticks, each named by the price it adds up to, for example "0.0100". On a book whose levels sit more than 100 ticks apart the larger options move up by powers of ten, so the coarsest option always spans more than one gap between levels. A bucket sits on a multiple of its step: bids round down and asks round up, so a bucket never shows a better price than the orders inside it. Its size is the sum of the levels it holds, and its total is the running total down to its deepest level. Selecting a bucket fills the order ticket's price with the bucket's price, at the instrument's price step. The Investor portal's trading desk groups its order book the same way. The desk remembers your choice. A market that does not offer the saved step opens at the nearest finer one.

### The order tables [#the-order-tables]

The four tables under the chart (**Open orders**, "Your trades", "Order history" and "Rejected orders") are dense: the units sit in the column heads, for example "Price (EUROC)" and "Quantity (RHE30)", and the cells show bare numbers. "Side" reads as a coloured "Buy" or "Sell" tag. The "Actions" column at the end of a working order holds that row's Amend and Cancel controls, as it does in the Console. Each table shows 50 rows a page, newest first, and scrolls inside its area. Its page controls move to older rows, and the count on its tab covers every row, not only the page shown. A table reads its rows when you open its tab. In the Console, your own fills, order changes and deliveries show without a reload, also when they come from another window or the API. In the Investor portal, an order you place or cancel there shows at once. A change from another window or the API, such as an order placed or cancelled there or a trade that filled and settled, shows within a minute, or as soon as you return to this window. Another trader's activity on the book does not reread your tables. A "Reason" or "Closed by" column that is empty on every row is hidden. A "Reason" is shown in full: a long refusal wraps onto more lines, so its row grows taller, and it is never cut off with an ellipsis. In "Your trades", the download icon at the end of a row opens the CSV and XLSX transaction confirmation of that trade. The icon is muted, and its tooltip gives the reason, when the trade has no final transaction yet.

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

- Confirm the order appears under "Open orders" or "Order history". An accepted order can first show "Reserving balance" and joins the book once its commitment confirms on chain.
- Confirm completed fills in "Your trades" and the updated amounts under "Balances".
- When an order closes without filling, the "Reason" column in "Order history" names why.
- In the Investor portal, select **History** on a row in "Order history" to read the steps of that order: who acted, the reason, and the change in status, price and quantity at each step. The steps you took yourself, from "Order accepted" on, name "You" as the actor, and "Price" and "Quantity" carry their units, for example "Price (EUROC)" and "Quantity (RHE30)".
- An order that the venue closed without a cancellation, such as a fill-or-kill order that could not fill, ends with an "Order closed" step.

## Troubleshooting [#troubleshooting]

**Trading authorization required**

The ticket shows this instead of a plain rejection because the fix is different: your approval to the venue's escrow
is missing or no longer covers the shortfall this order needs. Approve the named venue escrow for the amount the
ticket shows, then retry. Check the remaining approval before later orders. An order you placed a moment ago still
counts while its escrow commitment is on its way: until it lands, the ticket adds what it will pull to this order's
amount, so one approval covers both and the first order keeps the approval it needs. While the venue is paused, the
instrument is past its trading cut-off, the quantity is below the minimum or the price is outside the band, the ticket
names that reason instead of offering "Authorize". A pending or refused ordering-access check, or an order larger than
the wallet's buying power or holdings, does not hide "Authorize": a new self-custody trader's wallet only becomes able
to trade and receive funds once they authorise, so the ticket offers it and keeps **Place buy order** or "Place sell
order" unavailable until the access check clears and the wallet covers the order.

**Order rejected**

  Signal: the ticket names the check that failed. Each check has its own fix:

- Eligibility: your wallet is not registered to trade this instrument. Contact an administrator.
- Desk limit: the order exceeds the limit your desk approver set, on an institutional desk. Reduce the order or request a reviewed limit change, which a different operator must approve.
- Grid: the price or quantity does not land on the instrument's tick and lot grid. Enter a price on the instrument's tick grid and a quantity in whole lots, and check the minimum notional.
- Price band: the rejection states your price and both ends of the allowed range, so a buy at 150.01 against a range from 50.00 to 150.00 is refused with exactly those three numbers. The range is the one that applied when the venue checked your order, so choose a price inside it before resubmitting. When the range has no upper end, the rejection states the minimum price alone. A dynamic band with no reference price blocks trading until an official close sets one, or an operator does. An issuer price floor and an anchor-based width still apply when they are configured, even with the band set to **Off**.
- Instrument state: the instrument is not live, most often because an operator halted it. Wait for it to resume.
- Cut-off (`maturity-cutoff-reached`): the instrument is past its trading cut-off. For a bond, the cut-off is the moment the bond matures, or the number of days before maturity that an operator chose for the instrument. For a rights token, it is the trading end of its rights issue. No order can be placed after it. Fills matched before the cut-off still settle, and on a bond they keep settling until the bond has matured.
- Balance: this order plus what you already have reserved would exceed your spendable balance. Cancel an open order or submit a smaller one.
- Order cap: you reached the open-order limit for this instrument. Cancel an open order first.
- Size: the order is above the instrument's maximum order size or value, or under its minimum, and the rejection states the order's own size or value beside the limit. Change the order to fit.
- Expired or fee: the order sat too long before reaching the book, or the fee schedule rose above the fee cap you signed. Neither can be repaired in place, so submit a fresh order.
- Signature: the venue could not verify the order was signed for this session. Contact an administrator rather than resubmitting the same order.
- Rate limit: you sent orders too quickly. Wait a moment and try again.

The ticket keeps a refusal until you cancel or amend an order, and a venue pause stays until the venue resumes. "Rejected orders" counts only the refusals the venue saved. A refusal the venue did not save has no row there, so once the ticket clears it nothing else records it. Note the reason before you cancel or amend.

The [error catalogue](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference) describes every refusal these checks return through the API.

**An open order disappears without a fill**

  **Order history** carries several "Status" values for an open order that never fills, and the "Reason" column beside
  them explains most. "Expired" means its time in force ran out before it filled, and "Reason" adds "Expired
  before it could fill". "Cancelled" means the order left the book before it filled completely. A direct cancellation shows
  "Cancelled", and the "Closed by" column names "You", "Venue operator", or "Platform". An order you cancel directly on the venue contract, from your own wallet, shows "You" once the cancellation is final on chain. When the platform sends the on-chain cancel on the venue operator's behalf, the column shows "Platform". "Removed" means the venue took the order off the book because the instrument's fee schedule rose above the fee cap the order signed. A partial fill that leaves less than the lowest minimum notional the instrument has had since listing shows "The remaining
  quantity fell below the minimum order value". An order the price band no longer admits shows "Rejected" with the reason "Above the price band's upper
  limit" or "Below the price band's lower limit". This happens to a resting order outside the new band when an
  operator saves a tighter band, or when a roll-on-close band re-anchors at the official close. An instrument set to
  suspend orders outside the band shows "Suspended" in the open orders instead, keeps the locked balance, and
  returns the order to the book in its original place once the band covers its price again. An operator who prunes orders left outside a tightened price band
  or size limit also ends them as "Cancelled", and so does removal from a private instrument's participant list. In each of
  these cases the locked balance behind the order returns to your free escrow balance.

A match can also fail to settle when the fee schedule rose above your signed fee cap, when a freeze, a forced
transfer or a compliance rule change hit your wallet or the token, or when the other leg failed compliance. The platform then holds the fill with the refusal reason until a venue operator retries or busts it. On an
instrument with a holding period, a paused token, a shrunk trade lock, a frozen sending side or a receiver on the compliance bypass list at the due time undoes the trade instead, and the order
on the failing side shows **Settlement failed** with the reason. Any other refusal parks that leg in the receiver's escrow balance and the trade delivers. If none of the fee, band,
or minimum-notional cases explain it, ask an administrator whether a freeze, a forced transfer, or a blocked match
touched your account.

**Market data disconnected**

The Console empties the order book and recent-trades tape until the stream reconnects. An empty book here means the
data is unavailable, not that no orders rest, so wait for the connection status to recover before you read either
view. A working order you already placed is unaffected. Only the live display is missing.

## Frequently asked questions [#frequently-asked-questions]

### What price does a market order get?

A market order takes the prices resting on the book, best first, up to the edge of the market-order protection band. The band sits around the instrument's reference price, which the operator sets at listing as "Day 1 reference price", or around the last trade price when the instrument has no reference price. The ticket and the venue use the same anchor, so an instrument with a reference price takes market orders before its first trade.

The ticket signs the order at the band edge, which is the worst price you accept. A buy reserves and shows **Maximum total** at that edge, and a sell shows "Minimum proceeds" there. With neither a reference price nor a last trade, the ticket asks for a limit price.

The remainder beyond that band is refused rather than filled deep: the order closes as **Rejected** under "Rejected orders", with the reason "Outside the market-order protection band". On a thin book a market order can fill partially and close the rest, so check the depth panel before you size one. A fill at a better price spends less, and the unused part of the reservation releases once the fill settles.

An instrument sets which attributes of a level it shows you: the price is always shown, and the size and the order count are optional. The ladder shows "Hidden" in place of a size the instrument hides, and the depth chart says the instrument does not show quantities. A private instrument shows you only the best bid and ask. When your access to the instrument does not include depth, the ladder shows only the best bid and ask and says so, or, on an instrument that shows such participants no book, says that your access does not include the order book. The **Depth** chart tab is not offered.

### Can other traders see who I am?

The Console does not show counterparty identity in the trading view. The order book shows resting quantity aggregated per price level, and the recent-trades tape shows price, quantity, and time. The fill your counterparty sees carries their own order, side, price, quantity, and fee, and nothing that identifies you. Venue operators work with wallet addresses when administering participants.

### Do my resting orders survive a session close?

Yes, until its time in force ends. A closed session accepts only new **Day** limit orders, which wait for the next session, and cancels nothing. A "Good till cancelled" or "Good till date" order survives the close and is still on the book at the next session's open. A "Day" order expires when its session closes. To set that lifetime yourself, give the order a "Good till date" expiry, or cancel it before the session ends.

### Can I change an open order instead of cancelling it?

Yes, for an open limit order. Select **Amend** on the order in "Open orders" and change the limit price or the open quantity, which take amounts in your own number format like the ticket does. A smaller quantity at the same price keeps the order's ID and its place in the queue, and the platform releases the reserved balance for the reduction. A new price or a larger quantity replaces the order with a new one at the back of the queue, and anything already filled stays on the original order. A change that would take the order below the instrument's minimum order value is refused, so cancel the order instead.

### Which fee do I pay in the end?

You pay the fee charged on each fill at the instrument's schedule, shown per fill in **Your trades** in the quote token. Charged fees in that column share the longest exact decimal precision among the listed fees, with the price step as the minimum. Trailing zeros align the fees, and even a fee of one smallest token unit remains visible. The fee reads "Not charged yet" until the fill's settlement transaction lands, and shows the charged fee from then on, even while the fill awaits delivery.

On a buy, the lock covers the worst case, the larger of the maker and taker rates rounded up on the quote notional, and whatever it locked beyond the fee charged unlocks when the order closes. On a sell, no fee is locked: the venue deducts the fee from the quote proceeds when the fill settles. The ticket's "Estimated fee" line estimates at the taker rate either way. The ticket's "Estimated fee", "Estimated VAT" and a sell's minimum proceeds are exact and share one decimal precision, the same as the review step, so VAT is never shown rounded.


# Votes

Source: https://docs.settlemint.com/docs/console/my-assets/votes
Cast your ballot on a vote about an asset you hold, follow its result, and, with the Governance role, create, queue, execute or cancel votes.

A governance vote puts a proposed change in front of a token's holders and records their weighted ballots on-chain. On a vote about a token you hold, you cast a ballot weighted by your activated voting power at the vote's record date. A vote that passes changes the token only when someone executes it, through a timelock, a contract that enforces a waiting period between approval and execution. Holders of the Governance role on the token create, queue, execute and cancel votes. [Corporate Action](https://docs.settlemint.com/docs/concepts/issuing-and-markets/corporate-action) explains how the changes a vote can carry, such as a new yield schedule or maturing the token, fit into a tokenised security's broader lifecycle.

A vote records a holder decision. It does not stop a role holder from changing the same parameter directly on the token's management screens, with no vote and no delay. Any holder of the Governance role on the token can cancel a vote while it is **Pending** or "Queued", including one the holders approved. A holder of the System manager role can replace the governor and timelock code for every token at once, with no vote and no delay.

Ballot weight comes from voting power, a per-holder balance the vote reads as of its record date, a future moment the creator picks. A holder's own ballot carries weight only if their voting power is activated, and not delegated away, before that date. A holder who delegated away can delegate back to themselves at any time, but the change counts only for a vote whose record date falls after the delegation.

![Votes list with a Next action column](https://docs.settlemint.com/docs/screenshots/console-governance-votes-list.light.en.webp)

[Screenshot] The votes list, with one row for each vote on an asset you hold.

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

- To cast a ballot, you need voting power on the token that is activated and not delegated away as of the vote's record date, and no other role. Delegating needs a registered identity.
- In the Investor portal, the holding page's **Actions** menu offers "Delegate voting power" on a token that carries voting power, so a holder can activate or delegate before a vote is announced instead of waiting for a vote page to offer it.
- The **Votes** sidebar entry appears for every account once the system has the token governance add-on. The "Create vote" control, the "All votes" and "Insights" tabs, and the "Actions" menu appear for organisation owners, platform administrators, accounts with the "Asset manager" or "Permission manager" system role, and holders of the Governance role on a token.
- Creating or cancelling a vote needs the Governance role on the token the vote targets, and the chain checks that role itself. Any account can call queue or execute on the chain once a vote is Succeeded or Queued. The Console shows these controls only to accounts that manage votes.
- The Console asks you to confirm your wallet before any of these steps runs. When the account you act with is a [multisig wallet](https://docs.settlemint.com/docs/concepts/custody-and-signing/multisig), the Console first asks you to select signing keys, and the transaction runs once the collected signer weight reaches the wallet's threshold. The other signers co-sign from "Actions", or from the "Approvals" tab of the shared account's page under "My participants".

## Steps [#steps]

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

In the Console, open **Wealth** and select "Votes" in the sidebar. The page lists the votes on assets you hold, with a "Next action" column naming the step each vote is waiting on. When it is your turn to vote, the column holds a "Cast vote" button that opens the vote with the cast sheet, and the status dot is amber. When you had no voting power at the record date, the column says so. In the Investor portal, a vote that has not started yet says "Activate voting power" there while you have not activated voting power on its token. Opening a vote from any list lands on the same vote page, where you cast a ballot when you hold the token and manage the vote when you can.

Accounts that manage votes also see the tabs **On my holdings**, "All votes" and "Insights", and the "Create vote" button in the page header. "All votes" lists every vote across tokens next to the polls. The "All votes" list shows each vote's title and mode, its status, "Voting deadline" and "Next action". The token, the proposer and the creation date are columns you can switch on in the table's view options.

The token's **Governance** tab carries the same list scoped to that token, the "Delegate…" action under "Your delegate", the "Attach voting power" control when the token has no voting power yet, and the voting-power distribution. Delegating needs no token role, the same rule as "Delegate voting power" in the asset's "Actions" menu: until your identity is registered, both are disabled, and the "Governance" tab links the reason to your identity steps.

### Cast a ballot [#cast-a-ballot]

A ballot cannot be changed once cast. Select the vote in the list, or **Cast vote** in its "Next action" column. While your account can act, the "Your eligibility" card says so. When your account cannot act, the card names the reason instead. The reasons are: voting not open yet, power delegated away, power not activated while the record date is still ahead, no voting power at the record date, a ballot already cast, or a vote already closed. For an account that holds none of the token and had no voting power at the record date, the card reads "You do not hold" followed by the token symbol and ", so you cannot vote on this proposal." When you had no voting power at the record date, the card gives that date and says you can activate voting power to vote on future proposals. An account that manages votes and holds the token sees the card next to the manager controls.

Select **Cast vote** and choose For, Against, or Abstain on a Resolution, or one option on a Multi-option vote, with an optional reason. The reason is recorded with your ballot and appears beside your address in the vote's ballots table. Abstain counts towards quorum and never towards the approval threshold. The results update as more ballots arrive, and the token's votes list then shows "Ballot cast" as that vote's next action instead of "Cast vote".

In the Investor portal, the sheet also checks the ballot with the platform once you choose. A refusal shows its reason in the sheet and **Review** stays off. The check does not submit or sign anything, and the platform checks again when you sign.

On a poll, which collects signed ballots off-chain and never queues or executes, a holder casts a poll ballot from **Actions** or with "Vote" on the poll's page. The ballot is a signed message, never a transaction. It names the poll, the network, the token, your address, the option you chose and a hash of the poll's definition. A self-custody wallet asks you to sign it, and a wallet the platform manages signs it through its custody signer. The platform stores the signed ballot off-chain and accepts one ballot per wallet. When none of your wallets held voting power at the poll's record date, the poll's page offers no "Vote" and says you cannot vote in this poll. Polls have their own table on the "All votes" tab. An account that manages votes, with the Governance role on the poll's token, ends a poll with "Close poll". On an open poll, closing ends voting and recounts every ballot at the record-date balance. On a poll that has not opened yet, nobody has voted, so closing cancels it. A closed poll cannot be reopened.

## Create a vote [#create-a-vote]

Select **Create vote** in the header of the Votes page. The wizard has four steps. "Proposal" sets the token, the "Vote mode", a title and description, and optional "Supporting documents": up to 20 files of up to 25 MB each, in PDF, JPEG, PNG, WebP, Word or Excel format. Choose "Resolution" for a yes or no decision that can also carry executable changes, "Multi-option resolution" when holders pick between two or more named options, and "Poll" only for an off-chain signal that decides nothing on-chain. A token without the voting-power feature cannot receive a vote. The wizard offers "Attach voting power" in place when you hold the Governance role, and names the role to ask an administrator for when you do not.

![Create vote wizard at the Proposal step](https://docs.settlemint.com/docs/screenshots/console-governance-create-vote.light.en.webp)

[Screenshot] The first step, "Proposal", with the token, the "Vote mode", a title and a description.

**Ballot** defines the named options for a Multi-option vote or a Poll, at least two. Each option must differ from the others, ignoring case and surrounding spaces: a repeated option is marked on its field, for example "Option 3 repeats Option 1", and the wizard does not continue until you change it. For a Resolution vote it instead composes what the vote carries from a catalogue, such as a new supply cap or a revised fee rate. Leave the list empty for a plain resolution that decides without changing the token. "Set metadata" takes a key and a value in plain text, such as a fee rate written as you want holders to read it. The Console stores that text on the token, so you never encode it yourself. Tick "Lock this value so it cannot change later" to make the entry permanent once the vote executes. A vote cannot set a key that is already locked on the token, a key that the token keeps off chain, or a key that an earlier action in the same vote locks: the field says so under the key, and the step does not continue until you change it. Set an off-chain key from the token's Metadata tab instead. The step checks that the timelock already holds the authority those changes need and offers "Grant governance role to timelock" if not. Only a permission manager on the token can grant it, so ask one before you create the vote.

**Rules and timing** sets the record date, the voting period, quorum, the approval threshold and the execution delay. A governor is the on-chain contract that receives every vote for a token and enforces its rules.

- The record date must sit at least 24 hours and at most 90 days ahead, and voting power counts only as it stands at that moment, so a later record date gives holders more time to activate.
- The voting period is 1, 3, 7, 14 or 30 days, with 7 as the default.
- **Quorum (%)** is a percentage of the token's entire supply of voting units at the record date, where 100 equals that whole supply, and it starts at 5. Only activated voting power can vote, which is why the step shows the activated share and warns when the quorum you typed exceeds it. When the first vote for a token is created in the Console, its governor gets a 5% quorum floor, and the network then refuses every vote on that token below 5%, the first vote included. A first vote created through the Platform API can set a different floor. For a resolution or a multi-option resolution, a quorum below 5% or above 100% shows "Enter a quorum from 5% to 100%." under the field once you leave it, and the step stays blocked until you correct it. The floor does not apply to a poll, which is counted off-chain. The sentence that says when the vote passes appears only while the quorum and the approval threshold are within range.
- **Approval threshold (%)** is the share of For plus Against that For must reach, so 100 there means unanimous agreement between the two, not the whole supply. A threshold of 0 keeps a simple majority, where For only has to beat Against. The approval threshold you set on the first vote for a token becomes that token's floor: a later vote can set a higher threshold, never a lower one. A holder of the Governance role can raise the floor with a direct call to the token's governor contract. The Console has no control for it. A Multi-option vote passes on quorum alone, so the threshold does not decide it, and the help under the field says so. On a token's first vote it still sets the floor.
- The execution delay is 1, 2, 7, 14 or 30 days, the waiting period holders get between approval and execution.

**Review and sign** shows every setting before you confirm and create the vote. Each action is listed with its settings in words, so a "Set metadata" action shows its key, its value as text and whether it is locked. Creating a vote for a token that has no governor yet deploys the governor and timelock pair first, then submits the vote. The review step says so when that applies.

When the network refuses the vote, the page names the condition that failed, such as a record date that is already past on the network's clock, and tells you what to change. The network's clock can differ from your computer's. "Back to review" returns you to the wizard with your settings kept, and "Details" shows the error code to quote to support.

## Manage an existing vote [#manage-an-existing-vote]

**Actions** on a vote's page holds three more controls, filtered by the vote's status, and each one opens a wallet-verification dialog before it runs. The menu appears for accounts that manage votes. "Cancel vote" also needs the Governance role on the vote's token for the wallet that signs, so it is hidden without it. Queueing cannot be undone and does not change the token. Only execution changes it.

Queueing schedules a **Succeeded** vote on the timelock. Select "Queue for execution". The vote moves to "Queued" and its delay starts counting from that moment, using whichever is longer of the delay you set when creating the vote or the timelock's own minimum. The vote's details card shows the resulting "Earliest execution" moment.

Executing carries out everything a **Queued** vote holds, in one transaction, and it cannot be undone. Until the chain's clock reaches the "Earliest execution" moment, "Execute" is greyed out. Choosing it shows "Executable from" with that moment instead of a verification dialog. Select it once the delay has passed. If execution fails, the vote stays at "Queued", so nothing partially applies. The Console decodes the revert reason when it can. When it cannot, usually because the node it queried has pruned older transaction history, it shows the raw value and states that history is unavailable. "Retry execution" and "Cancel vote" both stay available from that failure until a retry is submitted. An execute that reaches the timelock before the delay has passed fails with a message that the delay has not passed yet, and "Retry execution" stays hidden until the "Earliest execution" moment. A corrective change needs another authorised operation, which can be a new governance vote.

Cancelling closes a vote for good, and any holder of the Governance role on the token can do it, including someone other than its creator. Select **Cancel vote** on a "Pending" or a "Queued" vote. The confirmation states that cancelling cannot be undone. A vote that is "Active" or already "Succeeded" cannot be cancelled directly. Wait for it to close on its own, or, once it reaches "Queued", cancel it there.

## Vote statuses [#vote-statuses]

Quorum is the minimum share of voting power that must take part for a vote to count. The Console shows one of seven statuses on every vote.

- **Pending** means the record date has not arrived and voting has not opened.
- **Active** means holders can cast ballots now.
- **Succeeded** means voting closed with quorum reached. For a Resolution vote it also means For finished ahead of Against and any configured approval threshold was met. A Multi-option vote succeeds on quorum alone, and its winning option is read from the tallies.
- **Defeated** means voting closed short of quorum or short of the threshold, and it is final: no queue or execute control ever appears on a Defeated vote again.
- **Queued** means a Succeeded vote is scheduled on the timelock, counting down its execution delay.
- **Executed** means the vote's changes were carried out, and it is closed for good.
- "Canceled" means a Pending or Queued vote was cancelled, and it is closed for good.

A Queued vote does not expire. It stays ready to execute until someone executes or cancels it.

[Figure] How a vote reaches its outcome. A vote starts Pending until its record date arrives and voting opens, making it Active. When voting closes with quorum reached, and, on a Resolution vote, its approval threshold also met, it becomes Succeeded and is ready to queue. A Multi-option vote succeeds on quorum alone. Falling short of quorum, or, on a Resolution vote, short of the threshold, closes it as Defeated instead. A Succeeded vote is queued onto the timelock, where its execution delay counts down, and executing it applies the changes for good. A vote can also be cancelled while it is still Pending or while it sits Queued, which closes it permanently. Defeated, Executed, and Cancelled never change again. Labels: Pending; voting not open yet; Active; ballots being cast; Succeeded; quorum cleared; Queued; execution delay counting down; Executed; changes applied, final; record date arrives; voting closes and passes; queue; execute; Defeated; quorum or threshold missed; closed for good; Cancelled; cancel from Pending or Queued; closed for good; misses quorum or threshold; cancel while Pending; cancel.

A vote moves from Pending to Active, Succeeded, Queued and Executed, or ends as Defeated or Cancelled, and final
states never change.

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

- Return to the votes list and confirm the vote shows the expected status: a queue moves it to Queued, an execution to Executed, and a cancellation to "Canceled".
- A fresh ballot increases recorded turnout.
- On a Resolution, the threshold compares For votes with Against votes.
- Open the vote's detail page and confirm the results panel and the ballots table show your action.
- The results panel shows quorum, approval-threshold, and turnout progress against the voting power recorded at the record date.
- The ballots table names every voter, their weight, their reason, and when they voted.
- A queued vote's details card shows its **Earliest execution**.
- Once a vote reaches Defeated, Executed or "Canceled", its status no longer changes.

## Troubleshooting [#troubleshooting]

**A vote is heading towards Defeated on quorum**

The results panel shows quorum progress against the total voting power recorded at the record date. If turnout is
short of that number as the deadline nears, the vote is on track to close as **Defeated**. Nothing you do after the
record date changes who counts towards quorum. If you created the vote, the only way to make the same change again is
a new vote with a later record date, so more holders can activate their voting power first.

**A Resolution vote reaches quorum but still shows Defeated**

Quorum counts every ballot cast, Abstain included. The approval threshold works differently: it weighs only For
against Against, and Abstain never counts towards it. A vote can clear quorum and still fail because For did not beat
Against, or because For fell short of the configured threshold share. Check the approval-threshold progress on the
results panel, not only quorum, when a vote you expected to pass does not.

**A Queued vote sits without executing**

Nothing but an execute or a cancel moves a vote out of **Queued**. Check the "Earliest execution" moment on the
details card. Before it arrives, "Execute" in "Actions" is greyed out, and choosing it shows "Executable from" with
that moment. If you expected someone else to act after that moment, ask whoever holds the Governance role on that
token.

**Execute fails or shows an undecoded value**

Whether or not the Console can decode the revert reason, the vote stays at **Queued** and nothing has partially
applied. Correct whatever the reason names, if you can, and select "Retry execution", or select Cancel vote instead if
the vote should not run at all.

**Cast vote is not available**

The **Your eligibility** card names the reason: voting has not opened yet, power delegated away, power not activated
while the record date is still ahead, no voting power at the record date, a ballot already cast, or a vote already
closed.

**Create vote is not visible, or creation is blocked**

The "All votes" and "Insights" tabs and the **Create vote** control appear only for organisation owners and
administrators, accounts with the "Asset manager" or "Permission manager" system role, and Governance role holders. A
permission manager on the token can grant the Governance role. Creating a vote for a token then needs the Governance
role on that token. A token without the voting-power feature needs it attached first, which needs the same role. A
composed change the timelock cannot run also blocks creation, and granting that authority to the timelock is a call
for a permission manager on the token, so ask one when the wizard reports the authority as missing.

## Frequently asked questions [#frequently-asked-questions]

### Does executing a plain resolution or a Multi-option vote change the token?

No. Only a Resolution vote that carries changes from the catalogue changes the token when it executes. A plain resolution with nothing composed, and every Multi-option vote, carries nothing executable: queueing and executing it completes the vote's lifecycle through the timelock and fixes the recorded outcome, but no token parameter moves. Acting on a multi-option result, or on a plain resolution, means an administrator applying the decision through the token's management screens, or a follow-up Resolution vote that carries the change.

### Can a vote created outside the Console appear in the list?

Yes. A vote submitted directly to a token's governor still appears in the votes list and on its own detail page, marked with a **Created externally** badge. Its description is shown exactly as recorded on-chain, and it carries no Console-managed title, rich text, or document links. The same statuses, ballots, and manage controls apply to it as to a vote created in the wizard.

### Does voting lock my tokens, or stop me from selling?

No. Casting a ballot locks no tokens. Your weight is your voting power as it stood at the record date, so a later sale or delegation does not change the weight of a vote whose record date has passed.

### How do I export the ballots for an audit?

Open the vote from "All votes" and select **Export CSV**. The export carries the vote's summary: status, mode, the quorum and approval-threshold settings, and the required and recorded totals. A resolution's totals are For, Against, and Abstain. A multi-option vote lists each option with its number, its name, and its votes. Each ballot follows as a row with the voter address, their choice, the weight the ballot counted, the voter's weight at the record date, whether the voter's balance is frozen, their reason, when it was cast, and the name of the option it chose. On a multi-option vote the choice reads `option`, next to the option's number. The export button sits next to the "Actions" menu, so it needs the same access.

### Does delegating voting power move my tokens?

No. Delegation assigns your voting weight to another address so the delegate can vote on your behalf. Your token balance does not move. The [voting power](https://docs.settlemint.com/docs/concepts/modeling-assets/token-features/balances-and-holds#voting-power) feature keeps that weight, with its own checkpoints. Reclaim the weight at any time by delegating back to yourself, which removes it from the previous delegate.

### What happens when two options tie on a Multi-option vote?

The results panel reports the leading option while voting runs and the winning option once it closes. On an equal top count it states that the leading options are tied instead of naming a winner. Because a Multi-option vote succeeds on quorum alone and carries nothing executable, a tie does not block anything on-chain: the vote still closes as Succeeded when quorum was met, and whoever acts on the result decides how to break the tie.

## API routes [#api-routes]

An equivalent create, cast, queue, execute, and cancel flow is available outside the Console. See the [API explorer](https://docs.settlemint.com/docs/api-reference/v2) for the request and response shapes, or [CLI commands](https://docs.settlemint.com/docs/api-reference/cli/commands) for the command-line equivalent.


# Accounting

Source: https://docs.settlemint.com/docs/console/organisation-settings/accounting
Read the posting record DALP keeps for each committed event, see why one did not post to your Xero ledger, and retry it in the Console.

Accounting lists the posting records of your organisation: one record for each committed platform event, with what DALP did with it. DALP posts each final money event that the organisation's rule table maps, such as a trade settlement, a fee or a paid dividend, to the organisation's own Xero ledger as a manual journal, and the record says whether that journal posted, is waiting, or could not post and why.

Use the page to check what reached Xero and to send a record that failed back to be posted once you have fixed the cause. The page does not connect Xero or change the rule table, the account mapping or the posting policy: an administrator does both through the Platform API, as [Post DALP events to a ledger](https://docs.settlemint.com/docs/api-reference/guides/accounting-feed) describes.

![Accounting page with the Xero connection state beside the title and the posting records table, empty for an organisation without an accounting configuration](https://docs.settlemint.com/docs/screenshots/console-organisation-accounting.light.en.webp)

[Screenshot] The "Accounting" page shows the Xero connection state under the title, then the posting records table with its "Status" filter.

In the shot, the organisation has stored no accounting configuration yet, so Xero reads "Not connected" and the table reads "No postings yet". Once the organisation posts, each row shows a record's event, status, amount, Xero journal and what happened to it.

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

- The organisation has stored an accounting configuration. Until it does, the table reads "No postings yet", and events from before the first configuration are never posted.
- The organisation has connected its own Xero app. Until then, records wait to post and the connection state beside the title reads "Not connected".
- You are working in the organisation whose ledger you want to check, because the page shows the active organisation's records only.

## Steps [#steps]

### Find the records that did not post [#find-the-records-that-did-not-post]

Open the **Status** filter in the table toolbar and choose "Failed", "Not mapped" or "Not posted". The table lists the newest records first, 25 to a page.

### Read what happened [#read-what-happened]

The **What happened** column says in plain words why the record is held back, such as "Xero refused the journal." or "An account in the journal has no Xero account code.", with the message of the last failure under it. Expand the row for the record's detail, including the "Last failure" in full and the journal lines DALP built.

### Fix the cause [#fix-the-cause]

Fix what the record names before you retry it. A missing account code or rule is fixed in a new configuration version, and a refusal from Xero is fixed in Xero, for example by correcting the account there. A new configuration version decides every "Not mapped" record again on its own, so those records post on the next pass without a retry. Do not edit or delete the narration of a DALP journal in Xero, because DALP finds its journals by it: correct a posted journal with a new journal instead.

### Select Retry posting [#select-retry-posting]

Open the row's actions menu and select **Retry posting**. The Console confirms "Queued to post again", the record reads "Waiting to post", and the "Retries" count in its detail goes up by one. The retry is not held for a second approver.

The posting job runs once a minute, so a retried record changes on its next pass, within about a minute. A "Not mapped" or "Not posted" record is decided again with the newest configuration version. A "Failed" record whose journal DALP already sent to Xero keeps that journal: when the last send was less than six minutes ago, DALP sends the same journal again as built. Otherwise DALP first looks the journal up in Xero, marks the record "Posted" when Xero holds it, and builds the journal again from the newest configuration version when Xero does not. So after a configuration fix, wait six minutes from the last send before you retry such a record.

## Table columns [#table-columns]

Each row is one posting record:

- **Status** shows the record's badge, from the table under [Statuses](#statuses).
- **Event** shows the journal narration with the event type under it, or only the event type when DALP built no journal.
- **Amount** shows the total of the journal's debit lines in the ledger currency, or a dash when DALP built no journal.
- **Xero journal** shows the start of the Xero manual journal id with a copy button. A record in a daily journal shows "Daily journal of" and the day, or "Daily journal 2 of" and the day for a supplementary journal of that day, with the Xero id once Xero accepted the journal. A record with no journal in Xero shows "Not in Xero yet".
- **What happened** shows why the record is held back and the last failure message, or a dash when nothing holds it back.

With no records, the table reads "No postings yet" and "Money events appear here once the organisation stores an accounting configuration."

## Record detail [#record-detail]

Expand a row to read:

- **Source event**: the `source_id` of the committed event, which stays the same when the event is delivered again.
- **Received**: the date and time DALP took the event in.
- **Configuration version**: the version that decided the record.
- **Posting policy**: "One journal per event" or "One journal per day".
- **Attempts**: how many times DALP tried to post the record.
- **Retries**: how many times someone retried it.
- **Xero organisation**: the start of the id of the Xero organisation the record posted to, with a copy button.
- **Last failure**: the message of the last failure, from Xero or from DALP's own check.
- **Journal lines**: one row per line of the journal DALP built, with "Account key", "Debit or credit", "Amount" and "Description". The account key is the organisation's own name for an account, which the account mapping turns into a Xero account code.

## Statuses [#statuses]

| Badge | Meaning |
| --- | --- |
| Waiting to post | DALP has not decided or posted the record yet. A record waits while Xero is not connected, and after a retry. |
| In a daily journal | Under "One journal per day", the record is decided and waits for its day's journal. |
| Posted | Xero accepted the journal, or the record's daily journal netted to zero. |
| Failed | Xero refused the journal for good, the event's data was gone before DALP copied it, or the Xero organisation the journal was built for is no longer connected. |
| Not mapped | No rule covers the event, or the configuration cannot turn it into a Xero journal. |
| Not posted | A test event, an event that is not final, or an event the rule table marks as having no accounting effect. DALP posts no journal. |

## Xero connection [#xero-connection]

The connection state sits beside the page title, next to the word "Xero", and reads one of three badges.

- **Connected**: DALP can post, and "Last refreshed" gives the day DALP last refreshed the Xero grant.
- **Needs reconnecting**: Xero refused the stored grant, for example because someone removed the app's connection in Xero. Posting pauses until an administrator connects again.
- **Not connected**: the organisation has no Xero connection.

While the state is not "Connected", the page adds "Records wait to post until an admin connects Xero." When the state cannot be read, the page reads "The Xero connection could not be read."

## Xero connect outcomes [#xero-connect-outcomes]

When an administrator connects Xero, Xero returns the browser to this page with the outcome, and the page shows a notice between the title and the table:

| Notice | What happened |
| --- | --- |
| "Xero is connected. Records post on the next pass." | DALP stored the grant and the Xero organisations it connected. |
| "Xero consent was declined, so nothing changed." | The administrator declined at Xero, or no longer has the access the page needs. |
| "The Xero sign-in expired or was already used. Connect again." | The consent link was unknown, expired or already used, or a different user was signed in. |
| "Xero did not complete the connection. Connect again." | Xero refused to complete the sign-in, for example because the app's secret or redirect URI is wrong. |
| "Your Xero sign-in has no Xero organisation. Pick one when you connect again." | The grant connected no Xero organisation. |
| "This Xero organisation is already connected to another organisation." | A Xero organisation in the grant belongs to another DALP organisation. |

## When Retry posting is unavailable [#when-retry-posting-is-unavailable]

**Retry posting** works for a record that reads "Failed", "Not mapped" or "Not posted" and still keeps its event data. For any other record the action is unavailable, and it says why:

- "A posted record cannot post again. Correct it with a new journal in Xero." shows on a "Posted" record.
- "This record is already queued to post." shows on a record that reads "Waiting to post" or "In a daily journal".
- "DALP no longer keeps this event's data, so it cannot post again." shows on a record whose event data is gone. DALP keeps a record's event data until 30 days after it reads "Posted" or "Not posted", so only a "Not posted" record, or one whose data was gone before DALP copied it, loses it. Book such an event by hand.

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

- After **Retry posting**, the confirmation "Queued to post again" and the record reading "Waiting to post", with "Retries" one higher in its detail.
- After DALP's next pass, the record reading "Posted" with the Xero journal id in "Xero journal", or "In a daily journal" under the daily policy until its day's journal posts.
- When the cause is still there, the record back at "Failed" or "Not mapped" with the reason in "What happened".

## Troubleshooting [#troubleshooting]

**Accounting is not in the sidebar**

The entry appears under Business operations only for an organisation owner or a platform administrator with an active
organisation. [Roles and permissions](https://docs.settlemint.com/docs/console/organisation-settings/admins-and-roles) lists the roles.

**Every record reads Waiting to post**

Check the connection state beside the title. While Xero reads "Not connected" or "Needs reconnecting", DALP posts
nothing and raises a "Xero connection needs attention" case. An administrator connects Xero again, as [Connect
Xero](https://docs.settlemint.com/docs/api-reference/guides/accounting-feed#connect-xero) describes, and the waiting records post on the next
pass.

**A retried record failed again**

The cause is still there. Read "Last failure" in the record's detail, fix the cause in Xero or in a new configuration
version, then retry again. DALP also raises an "Accounting posting failed" or "Accounting event blocked" case for a
record that cannot post, which your team works with its other [operations
cases](https://docs.settlemint.com/docs/console/organisation-settings/custody-books#work-an-operations-case).

## Frequently asked questions [#frequently-asked-questions]

### Can a retry post the same journal to Xero twice?

No. DALP sends each journal with an idempotency key and a narration marker. Within six minutes of a send it sends the same journal again, which Xero matches by the key. After that it looks the marker up in Xero first, and records a journal Xero already holds instead of posting it a second time. A "Posted" record cannot be retried at all. Correct a posted journal with a new journal in Xero.

### Does a Not mapped record need a retry after a configuration fix?

No. A new configuration version decides every "Not mapped" record again on the next pass. Retry a "Failed" record once its cause is fixed, such as a journal Xero refused.

## API routes [#api-routes]

`GET /api/v2/accounting/postings` lists the records the table shows, and `POST /api/v2/accounting/postings/{postingId}/replays` is the route behind **Retry posting**. `GET /api/v2/accounting/xero/connection` reads the connection state. All three need a Console session, and an API key is refused. [Read and retry posting records](https://docs.settlemint.com/docs/api-reference/guides/accounting-feed#read-and-retry-posting-records) describes the calls and their errors, and the request and response shapes are in the [Platform API reference](https://docs.settlemint.com/docs/api-reference/v2).


# Roles and permissions

Source: https://docs.settlemint.com/docs/console/organisation-settings/admins-and-roles
Review, grant and revoke the on-chain roles of the organisation's system, of each asset and of each offering, per person, in the Console.

Roles and permissions shows who holds each on-chain role in the organisation, and lets a **Permission manager** grant and revoke a person's roles and check the result. An on-chain role is a permission held by a wallet in an access manager contract, which checks it before a privileged call such as a mint, a freeze or a compliance change. A few system roles, such as "Auditor", unlock Platform API and Console actions only. Roles sit in three scopes: system roles on the organisation's system access manager, asset roles on one token's access manager, and offering roles, which are asset roles on the token an offering sells.

On-chain roles are separate from the roles that control sign-in. The organisation role, Owner or Member, and the platform role, Administrator or Member, grant no contract authority. The "Roles and permissions" page and several other Console screens open for a holder of an on-chain role, whatever the person's organisation role.

The organisation's own wallet, whose key the platform manages, also sends role changes: it grants the on-chain roles an invitation names when the invitee accepts, and revokes a time-bound system role when it ends. An owner changes a person's organisation role on [Users](https://docs.settlemint.com/docs/console/participants/users).

[Role Grant](https://docs.settlemint.com/docs/concepts/compliance-and-identity/role-grant) explains the model, and the [Roles and segregation of duties reference](https://docs.settlemint.com/docs/concepts/compliance-and-identity/roles-and-segregation-of-duties) lists every role and what it permits.

A person can have two wallets. The signing wallet holds the key that approves their transactions. When the organisation uses smart wallets, a smart wallet executes those transactions. The access manager checks the wallet that executes the call, so in an organisation that uses smart wallets the smart wallet must hold the role.

![Roles and permissions, People tab, listing people with their role groups and risk](https://docs.settlemint.com/docs/screenshots/console-organisation-admins-roles.light.en.webp)

[Screenshot] The People tab of Roles and permissions lists each person with their role group counts and risk.

Each row shows the person's email, when they were last active, a count for each of the Platform, Compliance, Assets and Oversight role groups, and a Risk column that names critical roles and counts elevated ones. A notice above the table appears when only one person holds the Permission manager role.

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

- To open the People and Roles tabs, you hold **Permission manager** or "System manager" on the organisation's system. Anyone else, an "Auditor" included, sees "You are not authorized to manage permissions." A holder of "Gateway permission manager" without either role lands on the "Add-on roles" tab only.
- To change system roles, you need **Permission manager** on the system, held by the wallet that executes your transactions. When none of your wallets holds it, the page header shows "Permission managers change roles." and the "Grant role" button and the row controls do not show. When only another of your wallets holds it, the editor opens but its role boxes stay inactive.
- To change asset or offering roles, you need **Permission manager** on that token. On an asset, when another of your wallets holds it, the control stays inactive and says "The role for this action sits on wallet …. Switch to that wallet to use it." When none of your wallets holds it, the asset's "Permissions" tab shows "Permission managers grant and revoke roles on this asset." and the offering's tab shows "Permission managers grant and revoke offering roles on this token." The "Offerings" list opens for a holder of "Permission manager" or "Asset manager" on the system, or of "Offering admin" or "Funds manager" on an asset.
- Set up a transaction PIN or a transaction code for your wallet, because every role change asks for it.
- Select the network whose system you mean to change. The page header reads "On" followed by the network name, and a role on one network gives no authority on another.

## Steps [#steps]

### Review who holds each system role [#review-who-holds-each-system-role]

Open "Organisation settings", then **Roles and permissions**. The page opens on the "People" tab. "People" and "Roles" each have their own link, so a reload keeps the tab you were on. An organisation with the custody gateway add-on also has an "Add-on roles" tab with its own link.

The "People" tab lists one row per person, in these columns:

- **Name**, then on a wide screen "Email" and "Last active".
- **Platform**, "Compliance", "Assets" and "Oversight", one per role group with a count of the roles the person holds in it.
- **Risk**, which names the two critical roles, "Permission manager" and "System manager", and counts the elevated ones, such as "2 elevated". The [reference](https://docs.settlemint.com/docs/concepts/compliance-and-identity/roles-and-segregation-of-duties#on-chain-roles) lists the elevated roles.

An asset role counts once per role and shows how many assets grant it, such as "3 assets" beside "Custodian". A person who holds a role through several wallets counts once, and the role counts include every wallet the person holds, not only the signing and operations wallets the row names. Expand a row to see every role by group and the person's signing wallet, with a copy button.

Narrow the list with "Role", "Role group" and "Risk" in the toolbar, and search with "Search by name or wallet…". The search also matches the identifiers of the roles a person holds, such as `complianceManager`, but not the role labels the table shows. When exactly one person holds "Permission manager", not counting contracts or the organisation's own wallets, a notice says so and warns "If this wallet is lost, nobody can grant or revoke roles again." Grant "Permission manager" to a second person, so that the loss of one wallet does not stop role changes.

### Grant or revoke system roles for one person [#grant-or-revoke-system-roles-for-one-person]

Choose **Grant role** in the page header, select a person's row, or choose "Change roles" on the row. On the "Roles" tab, "Add holder" opens the same editor with that role already selected.

1. Under "Account", search for the person. The change reaches every wallet the organisation can act on for that person: their signing wallet and, when the organisation uses smart wallets, their smart wallet. The editor shows the roles of one wallet and says "Roles shown reflect the participant's primary wallet. Changes apply to every wallet they own." To change one address only, choose **Use specific wallet instead**.
2. Select or clear roles in the four groups. The editor shows the person's asset roles read-only under **Asset roles**, because those change on each asset.
3. Watch the status line under the roles. While you change the selection, the Console asks the platform whether it would accept the change. A refusal shows in the editor with its fix, for example that the change would remove the last "Permission manager" or that it breaks a segregation pair. A segregation refusal names each pair, such as "Custodian cannot be held with Governance on the same contract.", and says what to do. When the rule asks for a reason, which the editor cannot send, the line says to make the grant through the Platform API. The rules are set in [General](https://docs.settlemint.com/docs/console/organisation-settings/general#segregation-of-duties). **Review** stays disabled, so you learn the refusal before you confirm. The check stores nothing and signs nothing. The platform checks again when you save, because the roles can change in between.
4. Choose **Review**. The summary lists the roles under "Grant" and "Remove".
5. Choose **Save** and confirm with your transaction PIN or transaction code.

The system role editor has no end date. A time-bound system role exists only through the Platform API.

With a person selected, the editor does not remove "Permission manager". To take that role away, switch to **Use specific wallet instead** and remove it from one wallet at a time. The platform sends all grants first, then all revokes. It sends a revoke of "Permission manager" and any revoke on your own wallet last, so you keep the authority to finish the change.

### Grant or revoke the same roles for several people [#grant-or-revoke-the-same-roles-for-several-people]

On the "People" tab, select the people and choose **Grant roles** or "Revoke roles" in the selection bar. Pick the roles, check the line that counts who changes, such as "3 people change", then confirm once with your wallet verification. One batch covers at most 50 people. The Console sends every person you select, and the platform refuses a larger batch with "Send at most 50 participants in one batch". Select 50 people or fewer and send the rest in a second batch.

The sheet states how the platform sends the batch. With a smart wallet it reads "Your smart wallet sends every change as one transaction, so the batch lands whole or not at all." With a signing wallet it shows "Changes are sent one call at a time": if one call fails, the calls before it stay applied. In **Revoke roles**, you cannot select "Permission manager". Remove it per person from the role editor, one wallet at a time. When the revoke removes a role you hold yourself, the sheet warns "You are in this selection". Picking a role you do not hold shows no warning, even with yourself selected.

## Export an access review [#export-an-access-review]

On the "People" tab, select the people to include, or select every row, and choose **Export CSV** in the selection bar. The selection bar shows only to a "Permission manager". The file has one row per person with "Name", "Wallet", "Role" and "Risk". "Wallet" is the person's signing wallet. "Role" lists every system role the person holds and, for each asset role, the number of assets that grant it.

A **System manager** has no selection bar and exports the table as it shows with "Export" in the toolbar.

The file shows who holds which role at the time of the export. It does not name the assets, show end dates, or include wallets that hold only asset roles, venue roles or add-on roles. Take those from each asset's **Permissions** tab and from the "Roles" tab. For who changed a role and when, use the [Audit trail](https://docs.settlemint.com/docs/console/reporting/audit-trail): its entry for a role change shows the roles before and after the change.

## Copy roles to smart wallets [#copy-roles-to-smart-wallets]

When the organisation uses smart wallets, a person's roles must sit on the smart wallet that executes their transactions. A person whose signing wallet holds roles their smart wallet lacks shows **Out of sync**.

- On the "People" tab, open the row's menu and choose **Sync permissions** to copy the missing system roles.
- On an asset's "Permissions" tab, the "Warning" column carries the same flag. Choose **Sync permissions** on the row.
- On the "Overview" tab of an asset with such holders, a banner reads "Roles not migrated to smart wallets". A "Permission manager" of the asset chooses **Migrate roles**, which grants the missing roles to the smart wallets of up to 200 listed people in one run. Anyone else sees "The token admin must migrate these roles. Ask them to open this token and run the migration."

The sync grants only the missing roles. It leaves the signing wallet's roles in place.

## Grant add-on roles [#grant-add-on-roles]

The **Add-on roles** tab shows the roles of the custody gateway add-on, which sit in an access manager of their own: "Manager", "Keeper" and "Screener". It reads "One grant covers every gateway of the add-on. Managers change gateway settings and approve each other's changes. Keepers and screeners are the signers that move and check deposits." It is the only tab a holder of "Gateway permission manager" sees, and it shows only to an organisation with the custody gateway add-on.

![Add-on roles tab of Roles and permissions listing wallets with their custody gateway roles](https://docs.settlemint.com/docs/screenshots/console-addon-roles.light.en.webp)

[Screenshot] The "Add-on roles" tab lists each wallet with its custody gateway role, with "Search wallets" and a "Grant role" button.

1. Select **Grant role**. The sheet "Grant a role" opens.
2. Choose the "Role" and enter the **Wallet address**.
3. Select **Grant role**. The tab confirms "The `<role>` role grant to `<wallet>` is submitted." and a refusal reads "The role could not be granted."
4. To remove a role, select "Revoke" on the wallet's row, then **Revoke role**, or "Keep role" to stop. The tab confirms "The `<role>` role revocation from `<wallet>` is submitted."

The tab lists "Wallet" and "Role" columns. Without the custody gateway permission manager role it says "Only holders of the custody gateway permission manager role can grant or revoke these roles." When the add-on is not deployed on the network, it reads "Custody gateway is not enabled on this network", and an organisation owner deploys the add-on first. With no holder yet, it reads "Nobody holds a gateway role yet" and "Grant the manager role so someone can set up the gateway."

## Change asset roles on an asset [#change-asset-roles-on-an-asset]

Open the asset and its **Permissions** tab. The table lists each holder with "Address", "Roles", "Ends" and "Warning".

1. Choose **Grant role** for a new holder, or "Change roles" on a holder's row. For a new holder, search for the person under "Account", or choose "Use specific wallet instead" for one address. On a person's row, the change reaches every wallet of that person.
2. Select or clear roles. The editor groups the asset roles in four groups. "Administration" holds "Permission manager", "Compliance" holds "Governance", "Operations" holds "Supply management", "Custodian" and "Emergency", and "Other" holds "Funds manager" and "Offering admin". To let a person mint and burn the token, grant **Supply management**. The [reference](https://docs.settlemint.com/docs/concepts/compliance-and-identity/roles-and-segregation-of-duties#asset-roles) states what each role permits.
3. To make the roles you add time-bound, set **Ends**. The field is optional, and the platform removes the roles you add at that time. The Console checks the end when you confirm the change: an end less than two minutes ahead fails with "Choose an end at least two minutes from now." The Platform API accepts an end one minute ahead. The end applies only to roles the change adds.
4. Watch the status line under the roles. While you change the selection, the Console asks the platform whether it would accept the change. A refusal shows in the editor with its fix, for example that the change would leave the asset with no "Permission manager" without an end, or that it breaks a segregation pair. **Review** stays disabled, so you learn the refusal before you confirm. The check stores nothing and signs nothing. The platform checks again when you save, because the roles can change in between.
5. Choose **Review**. The summary lists the roles under "Grant" and "Remove" and repeats the end.
6. Choose **Save** and confirm with your transaction PIN or transaction code.

## Change offering roles on an offering [#change-offering-roles-on-an-offering]

Open the offering under "Asset lifecycle", then "Offerings", and its "Permissions" tab. The table lists each "Account" with its "Role". Choose **Manage roles**, search for the person in "Assign offering roles", select or clear "Offering admin" and "Funds manager", then continue and confirm. Give the two roles to different people: one runs the sale and the other withdraws what it collects.

This pair is one of the platform's default segregation pairs. The platform refuses a grant that puts both roles on one wallet only after the organisation saves and enables its segregation rules, which the [reference](https://docs.settlemint.com/docs/concepts/compliance-and-identity/roles-and-segregation-of-duties#what-the-platform-enforces) describes. Until then, nothing stops one wallet holding both.

## Read the Roles tab [#read-the-roles-tab]

The **Roles** tab shows the same data by role: one row per role, with the people and contracts that hold it. A person who holds a role through several wallets is listed once, with the number of wallets, and for an asset role the number of assets. A role the organisation's own wallet holds also carries "Organisation wallet", and that wallet is listed under the organisation's name.

A system role held by one person, not counting contracts or the organisation's own wallets, carries "Single holder", and a role nobody holds carries "No holder". The top of the tab counts the roles with a single holder, such as "9 roles have a single holder", and the people with only asset roles, such as "2 people hold only asset roles". The second figure counts each person once, however many wallets they hold.

Those people are not on the "People" tab: you manage them on each asset's "Permissions" tab. Contract roles, which only platform contracts hold, stay behind "Show contract roles". Search with "Find a role by what it allows".

## Where each role is changed [#where-each-role-is-changed]

| Scope | Roles | Where you change them | Who can change them | End date in the Console |
| --- | --- | --- | --- | --- |
| System roles | The 15 roles in the Platform, Compliance, Assets and Oversight groups | **Organisation settings**, then **Roles and permissions** | A holder of **Permission manager** on the system | No |
| Asset roles | **Permission manager**, **Governance**, **Supply management**, **Custodian**, **Emergency**, **Funds manager**, **Offering admin** | The asset's **Permissions** tab | A holder of **Permission manager** on that asset | Yes, the **Ends** field |
| Offering roles | **Offering admin** and **Funds manager** | The offering's **Permissions** tab | A holder of **Permission manager** on the sold token | No |

An offering role sits on the sold token's access manager, so it covers every offering of that token, not one sale. Each change in any of the three places is an on-chain transaction that you confirm with your wallet verification. Trading venue roles and the roles of the custody gateway add-on sit in access managers of their own: the **Add-on roles** tab shows the add-on roles, and [Venue operations](https://docs.settlemint.com/docs/console/asset-lifecycle/venues) covers the venue roles.

## Read roles without changing them [#read-roles-without-changing-them]

Three screens show roles without the controls to change them.

- A person's user page: open "Organisation participants", then "Users", select the person and open **Roles & permissions**. The page opens for a holder of "System manager", "Identity manager" or "Verification issuer" on the system. "Organisation" shows their organisation role, "Member since" and, for a time-bound owner, "Owner role ends". "System and asset roles" lists the system roles their wallets hold and, per asset role, how many assets grant it. The on-chain roles are read-only there, and an organisation owner can still change the organisation role. A user who can grant roles sees "Manage roles", which opens the People tab.
- An asset you manage nothing on: when you hold no role on an asset, every tab of the asset shows **Settings are read-only** with "You don't hold a role that manages this asset, so its settings are read-only. Actions open to every holder or requester stay available." The banner has no action. The "Permissions" tab still lists every holder.
- The People and Roles tabs as a System manager: a **System manager** without "Permission manager" sees both tabs with "Permission managers change roles." in the header and no change controls.

## Where a role change shows [#where-a-role-change-shows]

A saved change shows a "Roles changed" toast, or "Roles granted" or "Roles revoked" after a bulk change, and the tables reload. The access manager enforces a grant or revoke once its transaction confirms on chain. The Console tables read the platform's record of the chain, which updates a few moments after the transaction confirms. When a row still shows the old roles, reload the tab.

At the end of a time-bound grant, the platform revokes the role on chain and the row drops it. For an asset role it also sends the `access-control.role-grant.expiring` webhook event once the end is less than 24 hours away, and `access-control.role-grant.expired` after the revoke. A grant whose end has already passed when the platform first checks it sends only `access-control.role-grant.expired`. A time-bound system role sends neither event. Every grant and revoke also reaches [webhook subscribers](https://docs.settlemint.com/docs/api-reference/webhooks/events) as `access-control.role-granted.provisional` or `access-control.role-revoked.provisional`.

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

- System roles: the person's row on the **People** tab shows the new group counts and risk, and the role's row on the "Roles" tab lists them as a holder.
- Asset roles: the holder's row on the asset's **Permissions** tab shows the new roles. A time-bound role shows in "Ends", such as "Custodian until Nov 20, 2026, 5:00 PM".
- Offering roles: the account shows with the role on the offering's **Permissions** tab.
- The person's view: the control the role unlocks becomes active for them on the wallet that holds it, and the **Roles & permissions** tab of their user page lists the role.

## Troubleshooting [#troubleshooting]

**The requested roles conflict.**

The grant would put two roles the organisation keeps apart on one wallet. The message names each pair and its scope,
such as "Custodian cannot be held with Governance on the same contract." Grant the second role to another person, or
remove the conflicting role in the same change. The platform always keeps **Auditor** apart from every other system
role it grants. It checks the organisation's own pairs only after the organisation enables its rules. The platform
runs these checks before it sends a role change. The access manager contract does not check role pairs, so a role
change sent to the contract outside DALP is not checked. The Console also refuses a grant that breaks a `warn` pair,
because the grant needs a written reason and the Console has no field for one. Send that grant through `POST
/api/v2/system/role-sets` or the token route with a `reason`. The [segregation
reference](https://docs.settlemint.com/docs/concepts/compliance-and-identity/roles-and-segregation-of-duties#what-the-platform-enforces) lists
the default pairs and the modes.

**The last system Permission manager cannot be revoked**

On a token, the same refusal reads "The token's last Permission manager cannot be removed". Without a **Permission
manager**, nobody can grant or revoke a role on that access manager again, so the platform refuses a change that would
remove the last holder. On an asset, a holder whose "Permission manager" role has an end does not count. Grant
"Permission manager" to another person first, then remove the one you no longer need. A system on the current access
manager version, and a token whose access manager counts its administrators, also refuse the change on chain, even
outside the Console.

**The system's administrator count is not initialised**

The system's access manager was upgraded but has not counted its **Permission manager** holders yet. Until a holder of
"Permission manager" or "System manager" on the system completes the upgrade by counting the holders, it refuses any
change to who holds "Permission manager". Other roles change as normal.

**The role expiry is not allowed**

An asset role change was refused for its end. Either the end was less than one minute after the request, or you tried
to grant **Permission manager** on the asset while your own "Permission manager" role there has an end. Pick a later
end, or ask a holder whose role has no end to make the grant. On the system route, an end less than one minute away
returns "expiresAt must be at least one minute in the future." instead.

**Some role changes may already have been applied.**

A batch sent from a signing wallet failed part-way, and the calls before the failure stayed applied. When the message
names a transaction, open it to see each call's outcome. Reload the **People** tab, then send only the changes that
are still missing.

**Participant has no on-chain wallet**

The role editor shows this warning with "The selected participant has no resolved wallet. Submitting will have no
effect." The person has no wallet the organisation can act on, so the change has nothing to reach. Finish the person's
onboarding on [Users](https://docs.settlemint.com/docs/console/participants/users), then grant the role.

**The participant has no usable wallet**

An asset role change for a person was refused, because the person has no wallet or one of their wallets is outside the
organisation. Choose **Use specific wallet instead** and pick a wallet the organisation holds for that person.

**The role is granted but the person still cannot act**

Check that the wallet that executes their transactions holds the role. In an organisation that uses smart wallets,
look for **Out of sync** and sync the roles. Check that the role is on the correct network and covers the action they
try: an asset role on one token gives nothing on another, and an organisation role gives no contract authority.

## API routes [#api-routes]

The Console screens call the Platform API, and an integrator can call the same routes. Each role write route needs a wallet verification. The settings route does not. The [API v2 reference](https://docs.settlemint.com/docs/api-reference/v2) holds the request and response schemas. For a time-bound system role, the `expiresAt` value must be at least one minute after the request.

| Route | What it does |
| --- | --- |
| `POST /api/v2/system/role-sets` | Grants and revokes system roles for one participant, one participant's wallet or one address. Takes `expiresAt` and a segregation `reason`. |
| `POST /api/v2/system/role-set-batches` | Grants and revokes the same system roles for up to 50 participants. Takes one `expiresAt` for the roles it grants. |
| `GET /api/v2/system/participants/roles` | Lists people with their system roles, for a **Permission manager** or **System manager**. |
| `GET /api/v2/system/asset-role-grants` | Lists wallets with the asset roles they hold and on how many assets. |
| `GET /api/v2/system/role-conflicts` | Lists every wallet that holds a pair the organisation's segregation rules name, for a **Permission manager** or **Auditor**. |
| `POST /api/v2/tokens/{assetId}/role-sets` | Grants and revokes asset roles on one token, with an optional `expiresAt`. |
| `GET /api/v2/tokens/{assetId}/participants/roles` | Lists a token's holders with their roles, end times and drift flags. |
| `POST /api/v2/addons/token-sales/{saleAddress}/role-sets` | Grants and revokes **Offering admin** and **Funds manager** on the sold token. |
| `POST /api/v2/settings` | Saves an organisation setting, such as `ROLE_SEGREGATION`, the segregation rules. Answers to an organisation owner or a platform administrator, with no wallet verification. |


# Assistant

Source: https://docs.settlemint.com/docs/console/organisation-settings/assistant
Turn the Console assistant on or off, add the organisation's OpenRouter key, choose what it may send, switch capabilities and watchers, and allow AI apps.

The **Assistant** page holds the organisation's settings for the Console assistant, the helper that answers questions about the page a member has open and drafts control changes for them to review. Each setting is a row on one card, in this order:

- **Assistant in search**
- **Model access**
- **Data sent to the model**
- **Capabilities**
- **Watchers**
- **MCP server**
- **Usage**

A change to a switch saves as you make it, with "Saving…" and then "Saved" beside it.

What the assistant sends to the model, who can keep it and what DALP masks first is explained on [What the assistant sends](https://docs.settlemint.com/docs/concepts/operating/assistant-data). This page covers the controls.

![Assistant page in Organisation settings with the Assistant in search switch, Model access, Data sent to the model and Capabilities](https://docs.settlemint.com/docs/screenshots/console-organisation-assistant-settings.light.en.webp)

[Screenshot] The "Assistant" page in "Organisation settings".

The **Assistant in search** switch comes first. "Model access" names the key in use, the free assistant or the organisation's own OpenRouter key, with a note on where questions go. "Data sent to the model" offers "Mask" and "Send documents" with a "What is sent" link. "Capabilities" lists six switches, followed by "Watchers", "MCP server" and "Usage".

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

- You are an organisation owner or a platform administrator. The "Assistant" entry under "Organisation settings" appears for those two roles only. Anyone else who reaches the page sees the switches in their saved state but cannot change them and, in place of "Model access", "Organisation owners and platform administrators manage model access."
- You may need a key. Where the installation has a free assistant, the organisation can use it without a key. Where it has none, "Model access" reads "This installation has no free assistant. Add your organisation's OpenRouter key to use the assistant." and nobody sees the assistant until you add a key, even with "Assistant in search" on: "Turned on, but nobody sees the assistant until you add a key."
- An OpenRouter key is optional. An OpenRouter key starts with `sk-or-`. The organisation's own key runs on its own OpenRouter account and quota.
- Raising a watcher needs an organisation owner. A platform administrator who is not an owner can change a watcher only when one of their wallets holds the system role that watcher concerns, and cannot raise its level. Raising a level needs the organisation owner, as [Set a watcher's level](#set-a-watchers-level) explains.

## Steps [#steps]

Skip the section on adding the organisation's key if the organisation uses the free assistant.

### Turn on the assistant [#turn-on-the-assistant]

1. Open "Organisation settings", then **Assistant**.
2. Turn on **Assistant in search**. While it is off, the row reads "Nobody in this organisation sees the assistant." and the assistant sends no question to a model.

### Add the organisation's key [#add-the-organisations-key]

1. In "Model access", select **Add your own key**.
2. In **OpenRouter key**, enter the full key. The field takes `sk-or-` followed by 8 to 250 printable characters, without spaces, and the form says "Enter a full OpenRouter key: sk-or- followed by at least 8 characters, without spaces." until the key fits.
3. Select **Save key**.

DALP stores the key encrypted and shows "Stored encrypted. After saving, only the last 3 characters are shown." The row then reads "Key", "OpenRouter key ending" with the last three characters, and the "Model" the key uses. Select **Replace** to store a new key in its place. The field is then labelled "New OpenRouter key".

### Choose what the model receives [#choose-what-the-model-receives]

1. In "Data sent to the model", choose **Mask** to replace holder names, emails and wallet labels with handles and send no documents or memos.
2. Or choose **Send documents** to send the document pages and memos the assistant reads as written, including any names inside them. The Console asks "Send documents to the model?" and "Document pages and memos the assistant reads will leave DALP and go to OpenRouter and the model provider it routes to. Names inside them are not masked." Select "Allow sending" to confirm.

On the free assistant, with no key stored, document pages and memos are sent by default. Choose "Mask" to keep them in DALP. Select **What is sent** to see what is always sent, what is sent unless you choose "Mask", and what is never sent. "Read the details" opens [What the assistant sends](https://docs.settlemint.com/docs/concepts/operating/assistant-data).

## Turn the assistant off [#turn-the-assistant-off]

Nobody in the organisation sees the assistant after you turn off **Assistant in search**, and the assistant sends no question to a model. A connected AI app sends what it reads to its own model provider, which "MCP server" controls. The other settings stay as they were.

## Remove the organisation's key [#remove-the-organisations-key]

1. In "Model access", select **Remove**.
2. Read the confirmation, then select **Remove key**, or "Keep key" to stop. The text is "Remove the OpenRouter key? Everyone moves to the free assistant." Where the installation has no free assistant it is "Remove the OpenRouter key? Nobody can use the assistant until a key is added again."
3. When documents are being sent and the installation has a free assistant, the confirmation adds "Documents will still be sent, through the free assistant. Choose Mask to stop that."

Removing the key leaves the **Data sent to the model** choice as it was.

## Keep only some capabilities on [#keep-only-some-capabilities-on]

Each capability under **Capabilities** has its own switch, and all six are on until an owner or a platform administrator turns one off. The page says "Turn a capability off and nobody in this organisation sees it. The assistant switch above turns them all off at once."

- **Answers**: questions about the asset, participant, trading venue or audit trail you are looking at.
- **Drafts**: a control change prepared from a request or a pasted text, for you to review and sign.
- **Term sheet check**: compares a term sheet with the terms on the chain and fills "Issue asset" from one. It needs documents allowed.
- **Holder notices**: the wording of a notice to holders for a corporate action.
- **Approval checks**: the brief and the one-line check on a pending approval.
- **Typed filters**: a phrase typed above a table, turned into filters.

With "Answers" off and **Drafts** on, only an asset page offers the assistant, for drafts, and every other page shows plain search. "Drafts" also covers reading a written compliance policy into rules, on the Compliance tab of an asset and in the Asset designer, so that reading is refused while "Drafts" is off. A capability that is off is refused on the server as well, so a hidden screen is not the only guard.

## Switch a watcher on [#switch-a-watcher-on]

A watcher reads DALP data on a schedule and posts what needs attention to the Actions inbox of the people whose roles it concerns. Every watcher stays off until you switch it on. **Watchers** lists those of the four watchers this page lists that your roles concern, or "No watchers for your roles" when there are none:

- **Payout funding**: every hour, checks that each treasury can pay the dividends, distributions and coupons due in the next 14 days, and prepares the top-up when it cannot.
- **Filing deadlines**: every six hours, finds filings due in the next 14 days that have no submission.
- **Verification expiry**: every six hours, finds holder verifications that an asset's compliance rules require and that expire within 30 days.
- **Unmatched credits**: every hour, finds bank credits that match no client after 24 hours and proposes what to do with each.

Turn on the watcher's switch. Each row then shows "Last run", "Next run" ("Off" while the watcher is off) and "Open items".

Select **Run now** to request a run, which then reads "Run requested".

**Show activity** lists the latest runs with what each "Found", "Posted", "Cleared" and "Executed", and "Hide activity" closes the list. A watcher sends nothing to the model, so it needs only the assistant switched on, not a key.

## Set a watcher's level [#set-a-watchers-level]

Each watcher shows its "Level", its "Track record" and what is "Needed to raise" it. Choose another option in **Level**. Lowering a level takes effect at once, and the next run uses it. An option the watcher cannot take is unavailable, and the line under "Level" says why.

- **Observe**: runs and logs what it finds. Posts nothing.
- **Suggest**: posts what it finds to the Actions inbox, without a draft.
- **Prepare**: posts what it finds with a prepared draft or options for a member to take. A new watcher starts here, or lower when it cannot prepare anything.
- **Act with veto window**: schedules the action under the organisation's agent principal and carries it out unless a member vetoes it within the window.
- **Act**: the platform carries out the action with the agent principal's platform-held key, inside its on-chain mandate, with no member's signature, and reports it.

An agent principal is an account the platform signs for on the organisation's behalf, limited by an on-chain mandate. The two act levels stay out of reach until the organisation has an active agent principal. The platform checks the agent's mandate when the action runs and refuses an action the mandate does not cover. Only the organisation owner raises a level. Raising it to "Prepare" or higher also needs the watcher's track record to meet the minimum. The owner sets that minimum, down to 0 items and 0 percent, and can change it in the same request as the raise, so the track record does not hold back an owner.

**Needed to raise** shows the minimum as "\{n\} resolved in 90 days, \{n\}% taken unchanged", and the owner edits it with "Change", "Resolved items" and "Taken unchanged (%)", then "Save" or "Cancel".

**Track record** reads "Last 30 days" and "Last 90 days" with the proposals taken, changed and rejected, or "no proposals resolved". The reasons the line gives include "Only the organisation owner can raise this watcher to Act." and "The last 90 days fall short of the track record needed for Act."

Only **Payout funding** has an action: the transfer of a treasury's shortfall in the payout asset. At "Act with veto window" it waits four hours after the item is posted, and anyone who sees the item, an organisation owner or a holder of the watcher's system role, can select "Veto transfer" on it in the Actions page before then. A veto closes the item as rejected. A transfer cannot be undone once the agent principal has run it.

**Backtest** replays a watcher's checks once a day over indexed history and says how often it would have fired, as "Would have fired \{n\} times in the last 30 days", without posting or changing anything. "Hide backtest" closes it.

**Stop all watchers** drops every watcher to "Observe" at once, after you confirm with "Stop all watchers" or choose "Keep them running".

## Connect AI apps through MCP [#connect-ai-apps-through-mcp]

**MCP server** lets members connect their own AI apps, such as Claude or ChatGPT, to DALP through the Model Context Protocol. An app reads what the member can read and prepares actions in the Actions inbox for the member to sign. An app with "Prepare actions" access can also run a mint, burn, pause, resume, block or unblock from the account of one of the organisation's agent principals, inside that agent's on-chain mandate, with no signature. The member's own wallet must also hold the permission for that action on the asset. Turn the switch on. While it is off the row reads "Off. Members cannot connect apps to DALP." A person who cannot change it sees "Only an owner can change this setting."

While the assistant is on, **Connected apps** lists each connection with these columns:

- **App**
- **Member**
- **Access**, which is "Read" or "Prepare actions"
- **Connected**
- **Last used**, which reads "Never" before first use

Select "Revoke" on a row, then **Revoke access**. For an owner the confirmation says "The app loses access for every member who connected it. Members can connect it again."

## Read the usage [#read-the-usage]

**Usage** shows the questions asked in the last 7 days, the questions refused because the assistant was busy, the limits that apply, and the answers rated helpful and not helpful. It reads "No questions in the last 7 days." when there are none. "See these questions in the audit trail" opens them for a reader who can open the [Audit trail](https://docs.settlemint.com/docs/console/reporting/audit-trail). The row appears only to an owner or a platform administrator. [What the assistant sends](https://docs.settlemint.com/docs/concepts/operating/assistant-data#limits-on-questions) lists the limits.

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

- **Assistant in search** is on and the switch reads "Saved".
- **Model access** reads "Using" the free assistant, or "OpenRouter key ending" with the last three characters of your key and the "Model".
- **Data sent to the model** shows the option you chose.
- A member who opens the search dialog on a page the assistant covers now sees the assistant, as [Search](https://docs.settlemint.com/docs/console/essentials/search#can-i-ask-the-assistant-a-question-from-search) describes.

## Troubleshooting [#troubleshooting]

| What you see | What it means and what to do |
| --- | --- |
| "Assistant settings unavailable" with "Nothing was changed. Try again." | The settings could not be read. Reload the page and try again. **Usage** and **Watchers** report their own failures, "Usage is unavailable." and "The watchers could not be read.", without blocking the other settings. |
| Nobody in the organisation sees the assistant | Check that **Assistant in search** is on, that **Model access** names the free assistant or shows a key, and that the capability you expect is on under **Capabilities**. With no free assistant and no key, add a key first. |
| "The key could not be saved." or "Enter a full OpenRouter key: sk-or- followed by at least 8 characters, without spaces." | Copy the whole key again. It must start with `sk-or-` and contain no spaces. |
| **Send documents** is unavailable, with "Only an organisation owner can allow this." | The person cannot change the settings. Ask an owner or a platform administrator to choose it. |
| "The assistant setting could not be saved." or "The data setting could not be saved." | The change was not stored. Try the switch again. |

## API routes [#api-routes]

The page reads and changes its settings through `GET /api/v2/settings/assistant` and `PATCH /api/v2/settings/assistant`. Watchers use `/api/v2/assistant/watchers`, with `/api/v2/assistant/watchers/{watcherId}` to switch one on or change its level, `/api/v2/assistant/watchers/{watcherId}/runs` to list and request runs, `/api/v2/assistant/watchers/{watcherId}/backtest` for the backtest and `POST /api/v2/assistant/watcher-stops` to stop them all. Connected apps are at `/api/v2/assistant/mcp-clients` and `DELETE /api/v2/assistant/mcp-clients/{clientId}`. Request and response fields are in [the v2 API reference](https://docs.settlemint.com/docs/api-reference/v2).


# Legacy custody books

Source: https://docs.settlemint.com/docs/console/organisation-settings/custody-books
Find current gateway records, Cases, destination review and reconciliation after the custody journal screens were retired.

The custody journal's deposit, withdrawal, position, policy and fee screens have been retired. Operators use gateway records for current gateway deposits and withdrawals. Generic organisation Cases, withdrawal-destination review and registrar reconciliation remain available with their current access and approval rules.

[Figure] From retired custody books to current gateway evidence. The old watch and journal workflows are retired. Current gateway records and receipt holdings provide current evidence. Cases and registrar reconciliation remain separate. Labels: Retired; custody watch and journal; Current; gateway records, receipts; Separate; Cases and registrar; reconciliation.

The custody watch and journal are retired, current gateways use records and custody receipts, and Cases and registrar reconciliation stay separate.

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

- The journal screens described by older custody integrations are retired. Enabling custody operations does not restore a retired tab.
- Organisation owners and platform administrators can read Cases, including when custody operations are off.
- Reconciliation, destination review and gateway operations keep their own feature, role and approval requirements.

## Steps [#steps]

The former ordered custody-book workflow is retired. Use gateway detail and records for current deposits and withdrawals, Cases for organisation investigations, and Reconciliation for registrar breaks and destination review. The following historical tasks are reference questions, not steps that create a replacement journal.

### Read the deposits list [#read-the-deposits-list]

The former organisation Deposits table is retired. Current gateway detail and records show gateway deposits and their stage history. They do not recreate a global custody-journal table or its customer-identifier contract.

### Release, return or refuse a held deposit [#release-return-or-refuse-a-held-deposit]

The former held-journal deposit actions are retired. Read the current gateway deposit and act only through the decisions its stage, role and checker requirements permit. Current holds have different causes. The old release, return and refusal dialogs do not apply to them all.

The withdrawal requests table lists every customer's withdrawals, newest first, 50 to a page. Each row shows "Customer", "Status", "Amount", "Destination" and "Requested". The destination shows its network's name, or "Network &lt;chain ID&gt;" when the Console does not know the network. A "Network" column appears when the page holds withdrawals from more than one network. Open a row for its "Asset", "Network" and "Destination". Filter by customer with the **Customer ID** field.

Withdrawal-destination review remains available after the journal screens are retired. Open Reconciliation and use Withdrawal destinations awaiting review, or follow Review destination from Actions. Clear or refuse the proved address with a reason under the current reviewer and address-uniqueness rules. A cleared proof does not automatically authorise that address for gateway payouts.

Open **Cases**. "Operations cases" lists every operations case in the platform's order. Each row names the case in words, such as "Held by screening", "Screening unavailable", "Withdrawal needs an operator", "Deposit reversed by a chain reorganisation", "Unexpected custody outflow", "Privileged action on a custodied token" or "Upgrade scheduled for custodied tokens", and shows "State", "Customer", "Related to" and "Raised". Select the "Case", "State", "Customer" or "Raised" header to sort the whole list by that column on the platform.

Open a row for the "Reason", the "Raised" time, the "Expires" time in UTC, or "Expired" once it has passed, the "Case id" and, once resolved, the "Resolution". An open case shows "No resolution recorded" in the "Unknown transactions report". **Resolve** opens "Resolve this operations case", where you write an "Investigation note" and select "Resolve".

The old parked-withdrawal consume and release screen is retired. Current gateway requests expose their actual evidence, stages and authorised decisions. There is no replacement parked-payout resolver or automatic translation of an uncertain journal payout.

### Work an operations case [#work-an-operations-case]

Generic organisation Cases remain available after the custody books are retired. Owners and platform administrators can acknowledge an open case or resolve it with a note, page through the list, and inspect its state. If somebody else changes its state or row version, read the current case before deciding again. Cases no longer enrich rows with journal deposits or withdrawals, offer their actions, or show an unknown-transactions report.

![Custody Cases tab with organisation cases and acknowledge or resolve actions](https://docs.settlemint.com/docs/screenshots/console-organisation-custody-cases.light.en.webp)

[Screenshot] The Cases table lists organisation cases with their acknowledge or resolve actions.

The Cases table shows organisation cases and their acknowledge or resolve actions. An open row offers Acknowledge or Resolve with a note. It remains available to owners and platform administrators when custody operations are off.

### Read customer positions [#read-customer-positions]

The old customer Positions tab and attribution report are retired. Current custody receipt holdings and gateway records may answer an investor's holdings and stage questions. They do not reproduce the old Spendable and Reserved balances or their location attribution.

### Set the withdrawal approval policy [#set-the-withdrawal-approval-policy]

The legacy withdrawal approval-policy screen and route are retired. Current gateway profiles, settings and checker requirements belong to the add-on. Registrar break approvals remain separately governed by the organisation's approval family. There is no automatic translation of the old withdrawal limits or checker windows.

The old per-asset custody fee-schedule editor is retired. Current gateway settings define its fee mode and terms, and gateway records show the resulting fee evidence. The old schedule versions and journal fee history are not regenerated from those records. [What a withdrawal costs](https://docs.settlemint.com/docs/concepts/custody-and-signing/custody-deposits-and-withdrawals#what-a-withdrawal-costs-and-how-the-fees-are-booked) explains the retired journal fee flow.

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

- The former journal outcome labels are retired. Each current action shows on its own surface: the gateway stage and history, the destination-review result, the case resolution and note, or the registrar break status.
- A historical journal policy or fee version is not proof of a current gateway change.

## Troubleshooting [#troubleshooting]

A missing journal tab is expected because those screens are retired. For current surfaces, distinguish a feature or authority refusal from a gateway stage restriction. Read current Cases again after a conflicting decision, and follow the destination-review refusal guidance when proof review fails. Enabling custody operations does not bring the old journal screens back.

## API routes [#api-routes]

The former deposit, held-deposit, withdrawal, position, movement, policy, fee and daily reconciliation API groups are retired. Current gateway settings and records, destination whitelist operations, generic organisation Cases, and break or reserve operations remain available through their current roles and scopes. Consult the [Platform API reference](https://docs.settlemint.com/docs/api-reference/v2) for the served routes.


# Custody reconciliation

Source: https://docs.settlemint.com/docs/console/organisation-settings/custody-reconciliation
Work the reconciliation break register in the DALP Console: assign breaks, record investigations and resolve or write them off with a second approval.

Custody reconciliation keeps every difference a registrar file reconciliation finds on record in a break register. A break stays open until a later clean run closes it, until a resolution or write-off is applied after the required approvals, or at once when the custody-ops approval family is off. The **Reconciliation** tab shows that register.

A separate reserve check compares the supply of a custody receipt, the token that represents coins held at custody addresses, with the coins held at those addresses. A difference it finds raises an operations case labelled "Balance difference". The [concept page](https://docs.settlemint.com/docs/concepts/records-and-evidence/reconciliation#custody-reconciliation) describes both. The platform does not read the custody provider's own statements, so compare those statements separately, outside the platform.

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

- Select the active organisation. You need its Owner role, or platform administrator access.
- Custody operations must be enabled on the deployment. Without them, the "Custody" page does not show the "Reconciliation" tab. If you open the tab's link directly as an Owner or platform administrator, it reads that custody operations are not enabled for the deployment. Anyone else who opens a Custody link directly sees the Not available page.
- The **Custody operations** row under "Approvals" on the organisation's [General](https://docs.settlemint.com/docs/console/organisation-settings/general#approvals) page decides whether resolving or writing off a break waits for a second person.

  It reads "Not required" until an owner or platform administrator turns it on, and while it reads "Not required", the change applies at once. With it on, a second Owner or platform administrator must approve. When the row's "Approvals required" count is more than 1, that many different people must approve.

  The user who asks cannot approve their own request, a member who is neither an Owner nor a platform administrator cannot approve, and a session that an administrator has borrowed to act as another user cannot approve. Approval follows the platform's maker-checker rule: the maker asks and a different checker decides.

## Steps [#steps]

### Open the break register [#open-the-break-register]

In the sidebar, open "Custody" under "Business operations", then **Reconciliation**.

The tab shows the "Reconciliation break register". A registrar file reconciliation, which compares a registrar's holder file with the chain, opens a break for every holder line that does not match, but only when an Owner or platform administrator ran it. The platform identifies a break by wallet, asset and cause.

The register shows up to 200 matching breaks, longest age first. If more than 200 match, narrow "Status" or "Cause" to reach the rest. Each row shows "Wallet", "Asset", "Trade", "Amount", "Cause", "Age", "Owner", "Status" and "Actions". "Asset" and "Amount" show the token's symbol and unit where the platform knows them, and base units where it does not. When nothing matches, the table reads "No breaks match these filters".

- **Cause** is "External" for a break that a registrar file reconciliation opened. The filter also offers the other causes a break can carry, including "Other".
- **Age** counts weekdays from the break's first sighting to the latest run that saw it. It changes only when a run touches the break. It falls in the buckets 0 to 1, 2 to 5, 6 to 10 and more than 10 days. The organisation's holiday calendars do not apply.
- **Amount** shows a dash in the table, and "Unavailable" in the break's sheet, when the platform does not know the break's amount. The platform keeps that amount empty and never writes it as zero.

The register opens on "Open" breaks. "Status" and "Cause" are menus. Choose a value to narrow the list, or "All" to drop that filter. Choose a member in "Owner" and select **Assign** to give a break an owner, or choose "Unassigned" to remove it. When the member directory cannot be read, the field takes the member id instead.

A later registrar file reconciliation keeps updating an open break instead of creating a duplicate. A run that finds the same wallet, asset and cause clean sets the break to "Resolved automatically", with no note or approval. The platform rejects a pending resolution request when the break's amount changes or when a clean run clears the break.

A closed break is never edited again, and it cannot be assigned or moved: its sheet says the break is closed and offers no status change. If a difference returns after a resolution, the platform opens a new break linked to the closed one. A write-off covers the difference it was approved for. While the same amount keeps showing in every run since the write-off, no new break opens. A clean run ends that cover, so if the difference returns or changes, the platform opens a new linked break. The approved write-off, its note and its maker and checker stay as recorded.

### Review withdrawal destinations [#review-withdrawal-destinations]

Below the register, the "Withdrawal destinations awaiting review" table lists the addresses that investors proposed as withdrawal destinations and proved they control by signing. Each row shows the customer, the destination address and when it was proved. The **Actions** inbox also lists each one as a "Review withdrawal destination" row, with a "Review destination" link to this tab.

Select **Clear** to make a destination active, or "Refuse" to reject it for good. Both ask for a reason. The user who proved a destination cannot review it, and neither can an administrator who proved it while acting as that user. Their row shows that another custody operator must review it, with no buttons. On each network, an address can be active on only one investor's entry. Clearing another investor's entry for that address on the same network is refused.

## What the platform checks [#what-the-platform-checks]

- **Scope.** Each organisation sees only its own breaks. Reading or changing a break needs the organisation's Owner role or platform administrator access.
- **Precision.** Every amount is an integer in the asset's smallest unit, carried as text, so no total loses precision.
- **Audit.** The platform records the read as a sensitive read and the assignment and status change as changes. The assignment and status change need a fresh session, not a cached one.

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

- In the break register, filter to **Open** and check that every remaining break has an owner.
- Filter to "Resolved" or "Written off" to check that a break you closed shows the approved change.
- In "Withdrawal destinations awaiting review", check that each address you cleared or refused no longer awaits review.

## Troubleshooting [#troubleshooting]

**The tab shows an access message instead of the register**

Custody is managed by organisation owners and platform administrators, so ask an Owner for access. If the message says
custody operations are not enabled, the deployment has them switched off and the Console hides the register.

**A resolved or written-off status did not apply**

With the "Custody operations" approval on, the change waits for a second user. Check that a different Owner or
platform administrator approved the request in the "Actions" inbox, then open the break with "Review" and select
**Complete checker approval**. The control stays on the sheet after a reload. If the approver rejected the request or
it expired, the same control closes it and the sheet offers "Save status" again. A different note or status than the
one approved is refused while the request waits.

## API routes [#api-routes]

The Console reads and writes the break register through routes that serve the Console only. The platform marks them as Console routes, so the [Platform API reference](https://docs.settlemint.com/docs/api-reference/v2) does not publish them. The published reporting routes offer a `break-ageing` report, which reports the register's breaks by age. A reporting obligation can include it in its report set. `GET /api/v2/reporting/capabilities` lists it when the deployment's report catalogue includes it.


# Custody

Source: https://docs.settlemint.com/docs/console/organisation-settings/custody
Manage the organisation's custody provider catalogue, credentials, and execution health.

Custody manages the organisation's [custody provider](https://docs.settlemint.com/docs/concepts/custody-and-signing/custody-provider) catalogue. Add provider configurations, choose which ones accept new accounts, and manage their credentials and execution health. Each existing custody account keeps its provider binding when you add or turn off another configuration.

Account creation and execution have separate controls. Turning off **New accounts** removes a configuration from account creation.

**Quarantine execution** stops signing and sending transactions through that configuration and requires an audit reason.

![Custody page on the Providers tab with the Platform key store card and its Availability, Investors and Connection rows](https://docs.settlemint.com/docs/screenshots/console-organisation-custody.light.en.webp)

[Screenshot] The "Custody" page on the "Providers" tab, with "Add provider" at the top.

The "Platform key store" card shows its execution health and the rows "Availability" with "New accounts", "Investors" with "Default provider" and "Offered to investors", and "Connection" with "Networks" and "Signing", then "Latest audit event". The card ends with "Quarantine execution" and "Delete provider".

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

- Check that the **Organisation** submenu of the account menu shows the organisation you mean to change. Prepare the provider's network identifiers and, for a managed provider, its metadata and credentials. The form offers only the credential sources supported by that provider.
- The page opens on **Providers**. An organisation owner or a platform administrator also sees the "Cases" tab beside it, and, where custody operations are on for the organisation, the "Reconciliation" tab as well. [Custody reconciliation](https://docs.settlemint.com/docs/console/organisation-settings/custody-reconciliation) covers that tab, and [Legacy custody books](https://docs.settlemint.com/docs/console/organisation-settings/custody-books) names the retired deposit, withdrawal, position and policy screens with the current operator surface for each task.

## Steps [#steps]

**Step 1 of 2**

### Review the provider catalogue [#review-the-provider-catalogue]

In the sidebar, open `Custody` under `Business operations`. The page opens on `Providers`. An organisation owner or platform administrator also sees `Cases`, even when custody operations are off. Cases lists organisation operations cases with acknowledge and resolve controls and notes. When custody operations are on, the `Reconciliation` tab sits beside it. See [Custody reconciliation](https://docs.settlemint.com/docs/console/organisation-settings/custody-reconciliation). Each configuration shows its provider, network scope, signing type, execution health, and availability for new accounts. `Default for new investors` identifies the configuration offered during investor onboarding.

A configuration can be available for new accounts while its execution health needs attention. Check both states before directing participants to it.

**Step 2 of 2**

### Add a provider configuration [#add-a-provider-configuration]

Select **Add provider** at the top of the page. In the sheet, fill the form in this order:

1. **Provider.** Select the provider. Each one shows a line that says where the keys are held and who signs, with a "Self-custody" or "Built-in" badge.
2. **Network identifier.** For an EVM network the identifier is a positive integer chain ID, and the platform refuses anything else with "Enter the network identifier as a positive whole number (the EVM chain ID)."
3. For a provider that DALP manages, choose the "Ledger" and the **Credential source**: "Platform vault" or "Organisation credentials". The onboarding custody provider step uses the same form, without the network field, and labels the source "Credentials" with "Held by the platform" and "Supplied by this organisation".
4. **The provider's own fields.** Supply the labelled fields the form shows for that provider. Credential fields are masked and write-only: use the show control to check what you typed. The platform never displays a stored credential. A provider without a known field set uses a masked key and value editor. A browser wallet does not require server-held signing credentials.
5. For a configuration on your organisation's own credentials, you can select **Exclusive to this organisation**. Keys from an exclusive configuration are used only in this organisation, and accounts from other organisations cannot be used with it: a member who already has an account in another organisation creates a new one here. You choose this when you add the configuration and cannot change it afterwards. The option is not offered for platform credentials or a browser wallet, and the provider card shows the setting read-only.
6. **Reason (optional).** Up to 1,000 characters, recorded in the audit trail.
7. Select **Add and probe provider**. The platform checks the configuration before making it available for account creation. If the probe fails, correct the reported network, connection, or credential issue before trying again.

Privy and Dynamic offer embedded wallets, which a member creates inside the Console and signs with personally. Neither stores a signing credential on the platform. Each one asks for its own fields:

- **Privy tenant** chooses whose account the wallets live in: "Platform-managed Privy" or "Organisation Privy tenant". Privy then needs the "Privy app ID", and "Privy client ID (optional)" can stay empty.
- **Dynamic tenant** chooses whose account the wallets live in: "Platform-managed Dynamic" or "Organisation Dynamic environment". Dynamic then needs the "Dynamic environment ID".

Once the configuration is enabled for new accounts, a member creates the wallet with **Add wallet**, as [Manage the participant's custody accounts](https://docs.settlemint.com/docs/console/my-account/participant#manage-the-participants-custody-accounts) describes.

![Add provider sheet listing the custody providers to choose from, with the Network identifier field and the Add and probe provider button](https://docs.settlemint.com/docs/screenshots/console-organisation-custody-add-provider.light.en.webp)

[Screenshot] The "Add provider" sheet over the "Custody" page.

Under "Provider" is the list of providers, each with a line that says where the keys are held and who signs. Below it are the "Network identifier" field and the "Add and probe provider" button.

For Utila, enter the fields that [Utila fields](#utila-fields) lists.

## Switch new accounts on or off [#switch-new-accounts-on-or-off]

Use the **New accounts** switch in the "Availability" row of the configuration. Its value reads "Available", "Paused while unhealthy" or "Disabled". A configuration can be available for new accounts while its execution health needs attention. Check both states before directing participants to it.

Switching "New accounts" off on a configuration that is offered to investors or is the default opens "Disable new accounts?". For an offered configuration it says "This provider is offered to investors. Disabling new accounts also withdraws it from investors. Enabling new accounts later does not offer it again. You must turn on "Offered to investors" yourself." For the default it adds that the switch removes it as the default and the owner must designate the default provider again. Select **Disable and withdraw** to continue or "Cancel" to keep it.

## Make a provider the default and offer it to investors [#make-a-provider-the-default-and-offer-it-to-investors]

The **Investors** row holds two settings:

- **Default provider** reads "Default for new investors" on the default and "Not the default" on the others, which carry "Make default". To use a healthy, enabled configuration during investor onboarding, select "Make default".
- **Offered to investors** reads "Investors can choose it" or "Not offered". The default is always offered to investors, and its "Offered to investors" switch is locked with "Always offered while it is the default investor provider".

Both "Make default" and "Offered to investors" stay locked with "Available once the provider is healthy and open to new accounts." until the configuration reads "Healthy" and "New accounts" reads "Available".

To let investors choose another healthy configuration enabled for new accounts, turn on **Offered to investors** on it. When more than one configuration is offered, the investor portal asks the investor to choose during onboarding between an embedded wallet, a browser wallet and a managed account, and suggests the default. A Privy configuration is offered as the embedded wallet. Any other embedded-wallet configuration is listed as not available and cannot be selected. When only the default is offered, the investor goes straight to it.

A configuration that is not offered is never listed, and the platform refuses a participant that an investor creates on it. An Owner of the active organisation or a platform administrator can still create a participant's managed account on it, provided it is healthy, enabled for new accounts, and lists the account's network. When the organisation offers no configuration to investors, any member can create managed accounts on a healthy configuration that is enabled for new accounts, for the participants they create. Turning off new accounts on a configuration withdraws its offer.

Changing this selection does not move existing accounts to another provider. Check **Default for new investors** after saving.

## Add a network to a managed provider [#add-a-network-to-a-managed-provider]

You cannot remove a network from a configuration after you add it, so add a chain only when the configuration will serve it.

In the "Connection" row of a configuration whose "Signing" reads "Managed by DALP" and whose provider supports EVM, select **Add network** beside "Networks". Enter the "EVM chain ID" and select "Add network", or "Cancel".

An invalid entry reads "Enter a positive whole number." and a success toasts "Network added to custody provider". The platform checks that the provider can sign on that network before adding it. Existing networks and accounts stay in place. "Networks" shows a network the organisation runs or may add by its name, and any other network by its chain ID. Adding the same chain again makes no change. You can then select the network on **Networks**, under "Infrastructure" in the sidebar.

For Utila, the platform checks the chain against the networks stored in the configuration's **Networks** field, not against anything you type in this step. "Add network" is refused for a chain that has no line there. To add a chain to a Utila configuration, first rotate the credentials with the new `chain ID network name` line added to "Networks", as [Rotate managed credentials](#rotate-managed-credentials) describes, then enter the chain ID here and select "Add network".

## Use the provider actions menu [#use-the-provider-actions-menu]

The **Provider actions** menu in the card header holds four actions:

- **Test connection** checks the provider connection.
- **Reconcile wallet roles** reapplies, at the provider, the role the platform records for each wallet of that configuration, so a custodian policy can tell an investor wallet from an infrastructure wallet. On DFNS, Fireblocks and Ripple Custody it also renames each wallet that still carries a name the platform chose, so the name states the wallet's role and the organisation's current name. On Ripple Custody it rewrites the account description for that role too, and each rename waits for approval under your Ripple policies like any other account intent. A wallet name that a person chose stays as it is.
- **Rotate credentials** is offered only for a configuration whose credentials DALP manages.
- **Copy configuration ID** toasts "Configuration ID copied".

## Rotate managed credentials [#rotate-managed-credentials]

Open the "Provider actions" menu and select **Rotate credentials**. The sheet "Rotate credentials for `<provider>`" says "Replace credentials at the provider. The configuration is probed after rotation." and has no reason field.

Fill in only the metadata and credential fields you want to change. A field left empty reads "Leave empty to keep the current value." and keeps its stored value. "Replace every credential" appears only for a configuration on organisation credentials, not for the platform vault, and replaces the whole credential set with the fields you enter ("Enter the whole credential. Optional fields left empty are removed."). Then select **Probe and rotate credentials**. The platform probes the replacement against the provider and saves it only when the probe succeeds. A failed probe leaves the current credentials in place. Rotation preserves the configuration's provider and credential source.

For Utila, the rotation form opens with the stored metadata, **Networks** included, and the platform saves the fields as the form holds them when you rotate. Edit "Networks" to add, change or remove a chain line. A chain with no line has no signing lane, so do not remove the line of a chain that has accounts.

To add a chain: bind the chain in "Networks", leave every credential field empty so the stored key stays, and rotate. The platform probes with the new "Networks" before it saves them. Then select "Add network" for the chain. Fill in only the key, standby key or "Signing agent secret" you replace, and leave the others empty to keep their stored values.

Select "Replace every credential" to remove the optional standby key or "Signing agent secret": the credentials you enter then replace the whole set.

To undo a rotation, rotate again with the earlier values. Each rotation is probed before it is saved, so the earlier values must still work in the provider.

If another administrator rotates the same configuration at the same time, a version conflict can reject one request. Refresh the configuration and check the saved state before retrying. Do not assume that an error means no change was saved.

## Quarantine or recover execution [#quarantine-or-recover-execution]

Select **Quarantine execution** in the danger area at the foot of the card. The sheet "Quarantine `<provider>`" asks for the "Audit reason for quarantine or recovery" ("Recorded in the audit log."). "Quarantine execution" stays unavailable until the reason is not empty, and "Cancel" closes the sheet. The card then shows the notice "Execution is quarantined and signs nothing" and the health reads "Quarantined". Each notice names its provider in its title, and a screen reader announces "Recover execution" together with that title, so several quarantined providers stay apart.

Correct the underlying incident, then select **Recover execution** on that notice, enter a new reason and confirm in "Recover `<provider>`". The Console probes the provider first and recovers the configuration only when the probe succeeds. When the probe fails, it reads "The provider failed the probe, so execution stays quarantined. Fix the provider, then recover again."

## Delete a provider [#delete-a-provider]

**Delete provider** sits beside "Quarantine execution" in the danger area. The sheet "Delete `<provider>`" says "Deletes the configuration. The platform refuses while any account or custody record still uses it." Select "Delete provider" to confirm. The Console toasts "Unused provider deleted". There is no reason field.

## Utila fields [#utila-fields]

**Utila custody** appears in the provider list only when the deployment operator has switched Utila on with `custody.providers.utila.enabled`, as [Prerequisites](https://docs.settlemint.com/docs/deployment/prerequisites) describes. If the provider list does not show it, ask the platform operator who runs the deployment to switch it on. Before you start, the Utila vault admin creates the service account and the platform operator lists the DALP egress addresses, as [Set up Utila custody](https://docs.settlemint.com/docs/deployment/utila-setup) describes. Then enter:

| Field | What to enter |
| --- | --- |
| **Network identifier** | The chain ID of the chain the configuration serves. The form fills it in when the organisation deploys on one chain. |
| **Vault ID** | The ID of the Utila vault that holds the wallets. |
| **API base URL** | Optional. Leave it empty to use the Utila address the deployment uses. It must be https on a `utila.io` host, on port 443, with no path. The form accepts other values, and the probe refuses them. |
| **Networks** | One line per network: the chain ID, a space, then the Utila network name. For example: `11155111 networks/ethereum-testnet-sepolia`. Do not repeat a chain ID. |
| **Service account email** | The email of the Utila service account. |
| **Service account private key (PEM)** | The private half of the RSA key whose public half you gave Utila. Paste the whole PEM block, including the BEGIN and END lines. |
| **Standby private key (PEM)** | Optional. A second RSA key of the same service account, for a rotation without a gap. |
| **Signing agent secret** | Optional. The secret that a Utila signing agent you run presents to DALP, as the setup page describes. At least 32 characters. The form shows "Use at least 32 characters." and the platform refuses a shorter value. |

**Network identifier** names the network the configuration serves. "Networks" maps every network the configuration will serve to its Utila network name, so list each of them there. The form marks every optional field with `(optional)` after its label. List the chain from "Network identifier" in "Networks" too. A chain with no Utila network in "Networks" is refused, and the refusal names the fix. The form shows "Enter one network per line: a chain ID, a space, then the network name." for a line that does not follow the format.

## Provider card [#provider-card]

Each configuration is a card, named for its provider. From the top:

| Row | Shows |
| --- | --- |
| **Header** | The provider name, a health badge (**Healthy**, **Unhealthy** or **Quarantined**) and the **Provider actions** menu. |
| **Availability** | **New accounts**: **Available**, **Paused while unhealthy** or **Disabled**. |
| **Investors** | **Default provider**: **Default for new investors** or **Not the default**. **Offered to investors**: **Investors can choose it** or **Not offered**. |
| **Key sharing** | **Keys**, for a configuration that can be exclusive: **Used only in this organisation** or **Can be shared with other organisations**. |
| **Connection** | **Networks**. **Signing**: **Managed by DALP** or **External, signed by the user**. **Custodian tenant**: **Not recorded**, **Named by the custodian**, **Pinned by an administrator**, **Derived from the connection** or **The platform**. |
| **Latest audit event** | "`<action>` by `<actor>`, `<time>`", in UTC, with the reason typed for a quarantine or recovery in brackets. |
| **Danger area** | **Quarantine execution** and **Delete provider**. |

The latest audit event names one of these actions:

- **Quarantined**
- **Recovered**
- **Custodian tenant recorded**
- **Custodian tenant backfilled**
- **Designated as the investor provider**
- **Offered to investors**
- **Withdrawn from investors**
- **Designation as the investor provider removed**
- **Switched off for new accounts**
- **Switched on for new accounts**

A quarantine or recovery also shows, in brackets, the reason typed for it. Quarantine, recovery, designation as the investor provider, offering the configuration to investors or withdrawing it, and switching new accounts off or on each record an audit event. Disabling new accounts on a configuration that was offered to investors, or that was the investor provider, also records that it was withdrawn or is no longer the investor provider. Adding a configuration, rotating its credentials and deleting it are recorded in the [Audit trail](https://docs.settlemint.com/docs/console/reporting/audit-trail) with the configuration before and after. They do not appear under **Latest audit event**.

## Custody providers and the custody gateway [#custody-providers-and-the-custody-gateway]

The provider configurations on this page hold the platform's own custody accounts. They do not create gateways, enable coins or grant gateway roles. A client's custody gateway is set up on the custody gateway add-on under "Asset lifecycle". A coin set to wait for custody on the add-on holds the client's receipts until the custodian accepts the coins. [Set up the custody gateway](https://docs.settlemint.com/docs/console/asset-lifecycle/custody-gateway-setup) says how, [Create a client gateway](https://docs.settlemint.com/docs/console/asset-lifecycle/custody-gateway-create) opens one, and [Review deposits and withdrawals](https://docs.settlemint.com/docs/console/asset-lifecycle/custody-gateway-review) covers the records it produces.

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

- Refresh the catalogue and confirm the configuration's network scope, health, and account-creation state.
- For an investor-provider change, confirm **Default for new investors** moved to the intended configuration.
- After quarantine or recovery, check the recorded action and reason on "Latest audit event".

## Troubleshooting [#troubleshooting]

**No custody providers enabled**

Add a provider configuration and confirm that it is healthy and available for new accounts. Participants need an
available configuration before they can create custody accounts.

**A credential rotation fails**

Read the reported error before retrying. Check the field values, the provider connection and the network scope.
Rotation cannot change the provider or credential source. Create a separate configuration for that change.

**Disabling new accounts did not stop existing accounts**

This control affects account creation. Use quarantine when execution through the configuration must stop, and record
the reason. Existing accounts retain their provider binding.

**Add provider or Add network is refused with CUSTODY_PROVIDER_CONFIG_INVALID**

The platform answers HTTP 422 when the provider has no signing lane on the network. A caller error does not clear on
retry. For Fireblocks, the message says either that the workspace lists no blockchain with that chain ID, in which
case you ask Fireblocks to enable it for the workspace, or that Fireblocks has retired the native asset of that chain,
in which case you choose a custody provider that signs on it. Probe the provider configuration again after the change.
When a participant creates an account on a network that the selected provider does not serve, the same code carries
the requested network and the networks the provider does serve.

**Delete provider is rejected**

The platform checks whether the configuration is still in use before deleting it. Keep the configuration while
accounts depend on it. Turn off new accounts or quarantine execution when that is the required outcome.

For historical tab names and their current operator surfaces, read [Legacy custody books](https://docs.settlemint.com/docs/console/organisation-settings/custody-books). The reference explains which journal tasks are retired and where Cases, destination review and reconciliation remain.


# Data feeds

Source: https://docs.settlemint.com/docs/console/organisation-settings/data-feeds
Register and maintain trusted on-chain data feeds for subjects and topics.

Data feeds registers the trusted on-chain values the organisation's tokens read by subject and topic. A published value and its staleness window here are the same data a token's Price feeds section shows and the same window the on-chain price resolver checks before it accepts a value.

Reach for this page when a token needs a trusted value, a price or another on-chain reference figure, that the platform does not already supply. A feed does not have to be fed by hand: the **Sources** tab connects a price provider to a token's price feed, as [Price sources](https://docs.settlemint.com/docs/console/organisation-settings/price-sources) describes.

![Data feeds page on the Feeds tab with the Create feed button, the staleness setting and the feeds table](https://docs.settlemint.com/docs/screenshots/console-organisation-data-feeds.light.en.webp)

[Screenshot] The "Feeds" tab of "Data feeds", with the staleness setting and "Change" under the title.

The table lists each feed with its "Feed" name and address, "Topic", "Latest value", "Updated", "Status" and "Source", and each row has "Publish update". **Create feed** sits at the top of the page.

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

- You need the Feeds manager role and a system that has the feeds directory installed.
- Without the directory, the sidebar does not list Data feeds and opening it reads **Not available**.
- Any member can open a feed's detail page read-only.
- A governor of the feed's subject token can publish a value there, when it is a trusted issuer for the topic, and can set that feed's staleness window.
- Replacing or removing a feed needs the Feeds manager role.

## Steps [#steps]

### Select Create feed [#select-create-feed]

On the "Feeds" tab, select **Create feed**. The "Create data feed" sheet opens with the description "Register a new data feed in the directory." It has two steps, "Details" and a review.

![Create data feed sheet on its Details step with the Scope, Data format, Topic name and Source type fields](https://docs.settlemint.com/docs/screenshots/console-data-feeds-create-feed.light.en.webp)

[Screenshot] The "Create data feed" sheet opened from "Create feed", on its "Details" step.

The step asks for "Scope", "Data format", "Topic name", "Source type" and "Decimals", with "Cancel" and **Review** at the bottom.

### Fill the Details step [#fill-the-details-step]

1. Choose a **Scope**: "Global", "Asset-scoped" or "Identity-scoped". For a scoped feed, enter the "Subject address" the feed belongs to. A subject and topic pair can hold only one feed.
2. Choose a **Data format**. "Numeric (Scalar)" stores one signed integer per update. "Document (Bytes)" is listed but cannot be selected.
3. Choose a **Topic name** from "Select a topic". Only topics with an int256 value schema are listed, and a topic that already has a feed for this scope is marked "Already has a feed" and cannot be chosen. If no topic exists, "Create one in Verification topics."
4. Choose a **Source type**. With "Issuer-signed", a trusted issuer signs each value and publishes it here, and the sheet asks for "Decimals", a whole number from 0 to 18. With "Chainlink (external)", you register an existing Chainlink-compatible feed contract, and the sheet asks for its "Feed address". DALP reads the decimals from that contract, which must answer `decimals()` and `latestRoundData()`, or registration fails.
5. Write a **Description**. A description in the form BASE / QUOTE, such as EUR / USD, follows the Chainlink convention.

"Scope", "Data format", "Decimals" and "Description" are fixed when the feed is created. A replacement feed must keep the same topic and decimals.

### Review and create [#review-and-create]

Select "Review", check the values, then select **Create feed**. Select "Cancel" to close the sheet without registering anything. The feed appears in the table.

An issuer-signed feed created here keeps only its latest round on-chain and accepts only values greater than zero. You cannot configure it to keep bounded or full on-chain history, or use it for a value that can be zero or negative, such as an interest rate or an exchange-rate movement. The indexed API can still serve past accepted observations. An external feed is an existing contract registered in the directory. Its own contract determines its value and history rules.

## Publish an update [#publish-an-update]

In a feed's row, open the actions menu and choose "Publish update", or open the feed's detail page and select "Publish update" in its header. The "Publish update" sheet shows the feed's "Topic", "Scope", "Current value" and "Decimals". Enter a "Value", which must be greater than zero, and select **Publish update**. The value is stored on-chain as a fixed-point number at the feed's decimals and is submitted under your issuer identity, which must be trusted for the feed's topic. For anyone else the action is disabled and reads "Only a trusted issuer for this topic can publish updates." A feed that a price source feeds still takes a value you publish by hand.

## Change the staleness window [#change-the-staleness-window]

Under the page title, the line **Feeds go stale after** followed by a duration, or "Feeds never go stale", shows the global window. It applies to every feed without its own window.

To change the global window, select "Change". In "Set global staleness window", choose a "Window", "Custom window" or "Never expires", set the "Maximum age" in seconds for a custom window, and select **Save global window**.

To set one feed's window, click its row to open the feed's detail page, then choose "Actions" › "Set staleness window". In the "Set staleness window" sheet, choose "Custom window", "Never expires" or "Use the global default", and select **Save window**. A window set here overrides the global default for this feed only, and choosing "Use the global default" removes the override. The detail page's "Staleness window" card shows whether the window is "Set on this feed", the "Global default" or "Never".

## Create a stable adapter [#create-a-stable-adapter]

In the feed list, open the row's actions menu and choose **Create adapter**. The "Create stable adapter" sheet shows the feed's "Feed address", "Scope" and "Topic". It creates a stable AggregatorV3-compatible address that resolves the feed through the directory. You need the Feeds manager role. The sheet notes that this is often unnecessary for a Chainlink feed, because Chainlink feeds already have stable addresses. Once an adapter exists, the row offers "Copy adapter address" instead, and the detail page's "Configuration" card shows the adapter. [Stable adapters](#stable-adapters) explains what the adapter fixes.

A stable adapter gives consumers a new address to read and leaves the feed itself unchanged. After you create an adapter for an issuer-signed feed, its row and detail page still offer "Publish update", the "Configuration" card still shows its "Rules", and the "Source" column still reads "Issuer-signed". In the **Source** filter, "Adapter" means a feed not created here that has an adapter, and "External" means a feed not created here that has none.

## Replace a feed [#replace-a-feed]

On the feed's detail page, choose "Actions" › "Replace feed". The "Replace feed" sheet shows the "Current feed address". Enter the "New feed address" and a "Description", then select **Replace feed**. The sheet warns "Replacing this feed may impact valuations and compliance calculations that depend on it." The new feed must use the same topic and decimals as the current one, or the replacement fails. The switch is immediate, and the latest value is cleared until the new feed reports one.

## Remove a feed [#remove-a-feed]

On the feed's detail page, choose "Actions" › "Remove feed". The "Remove feed" dialog reads that removing the feed unregisters it from the directory, and shows its "Feed address" and "Scope". Select **Remove feed** to confirm, or "Keep feed" to leave it registered. A removed feed's detail page reads that it was removed from the feeds directory and can no longer be replaced or removed.

Note (Removing a feed does not remove the on-chain contract): Removing a feed unregisters it from the directory only. A contract that already holds the feed's address directly, rather than looking it up through the directory each time, keeps working as before. New directory lookups fail after removal. For a token's price, the on-chain price resolver then falls back to the token's base-price claim from a trusted issuer, which carries no time and so is never judged stale. This fallback is on by default, and the Console has no control to turn it off. The Console asks you to confirm in the Remove feed dialog with your transaction PIN or transaction code before it lets a removal through, since the effect on downstream consumers is not always visible from this page alone.

## Staleness window [#staleness-window]

A staleness window is the maximum age of a published value. The on-chain price resolver refuses a value older than the window. A token whose compliance includes the capital raise limit values each mint through the resolver, so its mints fail until a fresh price is published. **Never expires** rejects no price for its age. The global default is 86,400 seconds, which is 24 hours.

Set the window to the maximum age your operation accepts. A shorter window requires more frequent publication. A longer window permits older values and must still meet the asset's pricing requirements. A token's own governance holder can set that token's feed staleness without the Feeds manager role. Only the platform-wide global window requires it.

## Stable adapters [#stable-adapters]

A stable adapter gives consumers a fixed address for directory reads. Replacing a feed swaps the address the directory resolves for that subject and topic to a new feed contract, so an integration that stores the old feed address continues to read the old contract. An integration that hard-codes the adapter's address once keeps reading the current feed, because the adapter looks the feed up through the directory on every read. Check that the new feed still provides the data and precision the consumer expects.

[Figure] A stable adapter resolves the current feed through the feeds directory. A DeFi integration stores the stable adapter's address once. On every read, the adapter asks the feeds directory for the feed registered under its subject and topic, and reads the current feed. After a replace, the same directory entry points to the replacement feed, so the integration reaches it through the same adapter address. Labels: after a replace; DeFi integration; External; Stores one address; Stable adapter; Fixed address; AggregatorV3 interface; Feeds directory; On every read; Subject and topic; Replacement feed; New contract; Same directory entry; Current feed; Resolved now; Answers the read.

A stable adapter looks up the current feed through the feeds directory on every read, so a replaced feed reaches the integration at the same address.

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

- Confirm the feed row shows the expected "Feed" name and address, "Latest value", "Updated" time and **Status**.
- The same feed appears on the token's "Placement" tab in the "Price feeds" section, since both surfaces read the same feed and capability data.
- The on-chain price resolver refuses a value older than the staleness window you set here.

## Troubleshooting [#troubleshooting]

**Data feeds reads Not available**

The system has no feeds directory, or you lack the Feeds manager role. The feeds directory comes with a system update,
so check **System updates** first.

**A published value is rejected downstream**

Check the staleness window. The on-chain price resolver only accepts a value inside the window you set. A value older
than that window fails even though the publish itself succeeded here.

**Mints keep failing even though the feed looks healthy**

Compare the observation time with the permitted age and check the publisher. Publish a fresh value when the current
one is stale. Change the window only if the asset's pricing requirements permit older values. A failed mint does not
by itself justify accepting stale data.

## Frequently asked questions [#frequently-asked-questions]

**Replacing a feed instead of creating a new one**

Replace keeps the existing directory entry and its downstream references, only swapping the underlying value source,
so directory consumers resolve the replacement contract. Check its units, decimals, and topic before switching. Create
a new feed instead for a new subject or topic. Replacing an unrelated feed to reuse its address risks pricing
consumers against the wrong figure.



# Exchange rates

Source: https://docs.settlemint.com/docs/console/organisation-settings/exchange-rates
Enable tracked currencies and inspect the latest recorded exchange rates.

Exchange rates controls which currencies the organisation tracks on-chain and shows the latest rate recorded for each. Asset values, portfolio totals and value history read these rates when they convert into a tracked currency, so a stale or missing rate can prevent a current valuation in that currency.

No one in the organisation enters or approves a rate. The platform fetches each rate on a schedule from the deployment's exchange-rate source, which the platform operator configures, and the organisation's operations signer writes it on-chain. The deployment sets how often rates refresh, at most once every 5 minutes.

The base currency and the initial target currencies, the currencies the organisation converts into from its base currency, are written once, when the organisation is deployed. This tab is where you add to that set afterward. It carries no control to change the base currency, and it has no effect on a token's own price, which [Token pricing](https://docs.settlemint.com/docs/console/asset-management/manage/token-pricing) controls separately.

![Exchange rates page with target currencies and latest rates](https://docs.settlemint.com/docs/screenshots/console-organisation-exchange-rates.light.en.webp)

[Screenshot] The page shows a "Target currencies" section listing enabled currencies, with the organisation's base currency marked "base", above a "Latest rates" table of currency pairs, rates, update times, and freshness states.

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

- You need the Feeds manager role to open the tab, and the system needs its feeds directory installed.
- To add a currency you also need the organisation's Owner role or platform administrator access.
- Anyone else sees "Organisation owners and platform administrators add currencies." in place of the **Add currency** button.
- Tracked currencies belong to the active organisation, so confirm you are in the right one before you add anything.

## Steps [#steps]

### Select Add currency [#select-add-currency]

Open "Data feeds" under "Infrastructure" and select the "Exchange rates" tab. The "Target currencies" section reads "Each one adds a permanent on-chain feed that cannot be removed." Select **Add currency**.

![Currency field on the Exchange rates page opened from Add currency](https://docs.settlemint.com/docs/screenshots/console-exchange-rates-add-currencies.light.en.webp)

[Screenshot] The currency field opened from "Add currency", with "Cancel" and "Add currencies" buttons.

### Pick currencies [#pick-currencies]

In the **Pick currencies to add** field, search and select one or more supported currencies. While the list loads it reads "Loading the currencies you can add." When every supported currency is already enabled it reads "All supported currencies are already enabled."

### Select Add currencies [#select-add-currencies]

Select **Add currencies**. With no currency picked, the form reads "Pick at least one currency to add." Adding a currency creates an on-chain feed for it. An integration adds currencies through the same [settings endpoints](https://docs.settlemint.com/docs/api-reference/v2) this screen calls.

Note (Adding a currency cannot be undone): No screen offers to remove a currency. While its feed is registered in the feeds directory, the API refuses a settings write that drops it with [DALP-14368](https://docs.settlemint.com/docs/api-reference/errors). Add only currencies the organisation needs valuations in.

## Read the latest rates [#read-the-latest-rates]

The **Latest rates** section reads "The most recent rate recorded for each tracked currency." Its table lists "Pair", "Rate", "Updated" and "Status". "Rate" and "Updated" sort. Under "Updated", an "Observed" line gives the time the rate was observed at its source. "Status" reads "Fresh", "Stale" or "Unknown".

It judges that observation time against the feed's [staleness window](https://docs.settlemint.com/docs/console/organisation-settings/data-feeds#staleness-window), the same check the platform runs before it accepts a price, so a rate written a minute ago from an old observation can read "Stale". "Base currency" and "Quote currency" are available as filters. The toolbar carries "Search pairs", export and column-visibility controls.

An empty table reads "No exchange rate feeds yet".

The table shows the rate last recorded. Reloading the page does not force a new rate, and the page has no manual refresh control.

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

- Confirm the currency appears under **Target currencies**.
- The Console confirms the save with "Currencies added. New feeds will appear once on-chain creation completes." The currency's rate follows once that feed exists and the platform records a first value.
- Until then, anything priced in that currency has no rate to convert with.

## Troubleshooting [#troubleshooting]

**No exchange rate feeds yet**

The table reads "Rates appear here once your organisation tracks a currency and its first rate is recorded." Add a
target currency, then wait for its first rate.

**A valuation is missing or stale for a currency**

Check this page for the currency's rate freshness first. Asset values, portfolio totals, and value history all read
the same rate this page shows, so a stale or missing rate can explain a valuation problem. Also check the token price
and indexed balance.

**A newly added currency has no rate yet**

The rate appears once the on-chain feed created for the currency records a first value. Until then, anything priced in
that currency shows no value.

**The currency list does not load**

The picker reads "Couldn't load the currencies you can add. Refresh to try again." Refresh the page. If the **Target
currencies** section reads "Couldn't load enabled currencies. Refresh to try again.", refresh for that too.

**Adding currencies fails**

The Console reads "Could not save the new currencies. Please try again." Check **Target currencies** before retrying.
A currency that was added no longer appears in the picker, so the picker alone does not show whether the save
succeeded. A currency the deployment's exchange-rate source does not quote fails on the currency itself, and a retry
never clears that. See the [error reference](https://docs.settlemint.com/docs/api-reference/errors) for the full set of save failures and which
ones are retryable.

## Frequently asked questions [#frequently-asked-questions]

### How is this page different from Data feeds?

[Data feeds](https://docs.settlemint.com/docs/console/organisation-settings/data-feeds) registers trusted on-chain values by subject and topic: a price, or any other reference figure a token reads. Exchange rates is a separate, narrower tab. It tracks only currency-conversion pairs, the rates valuations convert through. A token's own price is set elsewhere.


# Factories

Source: https://docs.settlemint.com/docs/console/organisation-settings/factories
List the token and add-on factories a system deploys through, and register a factory type that has none as a system manager.

A system, the set of DALP contracts an organisation runs on one network, creates assets and add-ons through factories, the contracts that deploy new instances of one type. Until a factory of a type is registered on the system, nothing of that type can be created there. Factories lists the token and add-on factories a system has and registers the ones it lacks.

A token factory deploys tokens. The "DALP asset" factory deploys every asset issued from an instrument template. The type-specific factories, such as "Bond", "Equity" or "Fund", serve existing assets of those legacy types. The sheet offers them for registration only when the platform operator has turned legacy asset creation on. An add-on factory deploys instances of one add-on type, such as an airdrop, a fixed yield schedule, an XvP settlement or a token feature.

![Factories page with the Register factory button in the header and the table of token and add-on factories with the columns Name, Kind, Type and Address](https://docs.settlemint.com/docs/screenshots/console-organisation-factories.light.en.webp)

[Screenshot] The "Factories" page under "Infrastructure".

The header carries the page description, the network chosen in the sidebar and **Register factory**, and reads "Every type this deployment can register already has a factory." when no type is left to register. The table lists the factories with the columns "Name", "Kind", "Type" and "Address", and "Kind" reads "Token" or "Add-on".

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

- You need the System manager role.
- The page works on the active network and names it in the header as "On" and the network.
- When [multi-network support](https://docs.settlemint.com/docs/console/organisation-settings/networks) is on and the organisation has more than one active network, pick the network in the **Network** submenu of the account menu first.
- The "Type" list offers only the types in the network's system directory, the on-chain list of types a system on that network can register.

## Steps [#steps]

### Open Register factory [#open-register-factory]

Choose **Register factory** in the page header. The sheet says "Requires the System manager role." When every type the deployment can register already has a factory, "Register factory" cannot be selected and the header reads "Every type this deployment can register already has a factory."

### Choose the kind, type and name [#choose-the-kind-type-and-name]

1. Choose the **Kind**, "Token" or "Add-on".
2. Pick a **Type**. The list offers only system directory types that have no factory yet, so a type never appears twice. While the platform runs with legacy asset creation off, it offers no legacy token type.
3. Type a **Name**. The field notes "Current registries do not store the name. The factory list shows each factory under its type." Only a version 1 registry stores it.

### Review and register [#review-and-register]

Select "Review". The confirmation step repeats the "Type" and the "Name". Select **Register**, then confirm with your wallet verification in "Verification code". The sheet reports "Token factory registered" or "Add-on factory registered", and the row appears in the table.

## Read the factory list [#read-the-factory-list]

The page is one table of both kinds of factory, with the columns "Name", "Kind", "Type" and "Address". "Kind" reads "Token" or "Add-on" and doubles as a filter. "Type" shows the name of the asset or add-on type in the language of the viewer.

The toolbar has **Search factories…** and the view options. The list refreshes as blocks arrive, so a factory registered a moment ago appears without a reload. A system with no factories says "No factories registered yet". A failed read shows "The factories could not be loaded." with "Check your connection and try again." and a retry button, which reads both lists again.

The table does not open the add-on a factory created. [Airdrops](https://docs.settlemint.com/docs/console/asset-lifecycle/airdrops#add-on-types-and-where-each-opens) lists where each add-on type opens. A factory is one contract among the contracts a deployment runs, which [EVM contract set](https://docs.settlemint.com/docs/platform/evm-contract-set) lays out.

## Where a missing factory shows [#where-a-missing-factory-shows]

A missing factory shows in the Console in four places:

- **Issue asset** offers no instrument template while the system has no "DALP asset" factory, because every template deploys through it.
- The Classification step of the instrument template wizard warns "Deploy the Configurable Asset under Factories before creating templates." The Configurable Asset in that warning is the "DALP asset" factory.
- **Issue asset** disables an instrument template, or a structure, when one of its features has no feature factory on the system. The row reads "Needs a feature factory", and its details name the features and, for a system manager, offer "Open Factories".
- Under Asset lifecycle in the sidebar, an airdrop family without a factory still appears. A system manager reads "Push airdrop is not deployed. Open Factories to deploy it." and the entry opens Factories. Anyone else reads that a system manager deploys it in Factories.

In each case a system manager registers the missing factory on this page. When the sidebar points to Factories for a type the directory lacks, the **Type** list does not offer it and this page cannot register it.

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

- Check that the new row shows in the table with the "Kind" and "Type" you picked.
- After a "DALP asset" factory, **Issue asset** offers instrument templates.
- After an airdrop factory, the airdrop entry in the sidebar opens the airdrop page.

## Troubleshooting [#troubleshooting]

**Register factory cannot be selected**

Every type this deployment can register already has a factory, and the header says so. If you expected another type,
the network's system directory does not list it, so this page cannot register it.

**The page reads Not available**

Only a system manager sees Factories. Anyone without the System manager role who opens the address sees **Not
available** inside the Console frame, and the page reads no factory data. Ask a system manager for the role.

**The page reads Couldn't check access**

The Console could not read your roles. Select **Try again**. If you lose the System manager role while the page is
open, the header reads "Only a system manager registers factories." and "Register factory" disappears.

**The Type list is empty**

The list offers only types of the network's system directory that have no factory yet. An empty list means every
offered type is registered, or the network has no system directory.

## API routes [#api-routes]

A token factory is registered through `POST /api/v2/system/factories` and an add-on factory through `POST /api/v2/system/addon-factories`. A request from a browser session carries a wallet verification, which the Console collects for you. A request from an API key sends none, and is refused only while the key holder is in the cooling-off period after a wallet security change.

Registration is a transaction on the system, so by default the API answers 202 with a queued status and a status link, and the factory is usable once that transaction settles. Send `Prefer: wait=N` to hold the response until it settles, as [Idempotency and async settlement](https://docs.settlemint.com/docs/api-reference/guides/idempotency-async-settlement) explains.

An add-on request also registers the add-on types that the requested type depends on. A request whose types all have a factory already registers nothing and answers 200 with the system.

The platform refuses a registration in these cases:

| What the platform observed | Answer | What to do |
| --- | --- | --- |
| The wallet your request acts as does not hold the System manager role. | 403 | Act as a participant whose wallet holds the System manager role, then send the request again. |
| A browser-session request carried no wallet verification proof. | 400, `platform.http.REQUEST_INVALID` (DALP-12251) | Request a challenge from `POST /api/v2/step-up-challenges` for this request and send it in the `X-Step-Up-Challenge` header with the wallet verification, or use an API key. |
| The type is not in the network's system directory, the network has no system directory, or the type is a legacy token type while legacy asset creation is off. | 422, DALP-14339, reason `factory-type-unusable`, with the refused type in `typeIds` | Choose a type the Register factory sheet offers. |
| The add-on type is a token sale or a trading venue, and its module, **Primary market** or **Secondary market**, is switched off for your organisation on [General](https://docs.settlemint.com/docs/console/organisation-settings/general#switch-a-module-on-or-off). | 403, `platform.module.DISABLED` (DALP-20531), with the module in `data.module` | Ask an organisation owner to switch the module on, then send the request again. |
| The add-on type is a token sale or a trading venue, and the deployment does not offer its module at all. | 422, DALP-14339, reason `factory-type-unusable` | Choose another add-on type, or ask the operator of the deployment to offer the module. |
| The system's add-on registry runs a version that cannot wire that add-on type's instances. | 409, DALP-14367, reason `addon-instance-wiring` | Choose another add-on type. On [System updates](https://docs.settlemint.com/docs/console/organisation-settings/system-updates), an "Add-on registry" row in the state "Upgrade available" means the registry runs an older release. |
| A precondition for that add-on type is not met. The API never registers the paymaster signer. | 412, DALP-14333, reason `addon-blocked` | Meet the precondition the error message names, then send the request again. |
| The platform refuses to send the registration from the wallet your request acts as, because of the organisation, the network or a platform setting. | 412, DALP-14321, reason `executor-refused` | Read the reason in the error message, correct that wallet's set-up for this organisation and network, then send the request again. |
| The system, its registries or, for the price resolver, its feeds directory are not indexed yet. | 503, dependency unavailable | Retry once the indexer has caught up with the network. |


# General

Source: https://docs.settlemint.com/docs/console/organisation-settings/general
Change the organisation's name, logo, modules, languages, time zone, terms, sign-out, signing holds, segregation of duties and approvals.

General holds the settings that apply to the whole active organisation and have no page of their own, in six sections:

- **Profile** holds the name, logo and modules.
- **Language and time zone** holds the languages people can pick and the display time zone.
- **Terms and disclosures** holds the documents that participants, the people and entities your organisation onboards, accept, and the redemption funding switch.
- **Security** holds idle sign-out and the cooling-off period.
- **Segregation of duties** holds the role pairs one wallet may not hold together.
- **Approvals** holds the second-person approval rules.

A section index beside the cards jumps to each section, and every section has its own address, such as `/org-settings/general#security`, that you can share.

Name and logo changes carry no on-chain effect and change nothing about who can act for the organisation or which networks it can use. Both show wherever the Console shows the organisation, including the account menu at the top right. DALP writes the current name into every invitation email it sends on the organisation's behalf, and into the wallet names it sets at the custody provider when it creates a managed wallet or reapplies its role.

![General organisation settings page with the section index beside the Profile section](https://docs.settlemint.com/docs/screenshots/console-organisation-general.light.en.webp)

[Screenshot] A section index in a card lists "Profile", "Language and time zone", "Terms and disclosures", "Security", "Segregation of duties" and "Approvals".

The "Profile" card holds three rows. "Name" shows the organisation name with an "Edit" button. "Logo" shows a 48-pixel tile with "Upload" or "Replace" and, once a logo is set, "Remove". "Modules" lists the modules the deployment offers. The logo saves immediately, and the name waits for "Save". The other sections follow as their own cards.

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

- **Who can change what.** You need the Owner role on the active organisation to change the profile and the settings here. Member does not carry that permission. In the Console, the "Segregation of duties" section follows the same rule as the profile. The "Approvals" section is the exception: an owner or a platform administrator, the role that administers the whole DALP deployment, can change it. A platform administrator who is a member of the organisation, in any organisation role, can turn an approval family off or lower its count. From a session in which they impersonate a member, they can turn a family on or raise a count, but not loosen either. Through the API, a platform administrator can also change the settings rows.
- **Approvals start off.** Every approval family starts off, so a new organisation asks nobody for a second approval until an owner turns a family on in [Approvals](#approvals). The "Recovery" group under Administration is the one exception: it starts on, so an identity recovery waits for another owner or administrator until an owner turns that group off.
- **Read-only view.** Any other member who opens a General link sees the Not available page. A platform administrator who is not an owner of the organisation sees the name, the logo and the settings as values, with no "Edit", "Upload", "Remove" or switch controls and one line under the title, "Organisation owners manage these settings." There is no not-authorised alert. The server still enforces the permission on every save. Approvals is the exception: a platform administrator can change its rules, as [Approvals](#approvals) describes.
- **Limits.** The name accepts up to 32 characters, trimmed of leading and trailing spaces, and cannot be left blank. The logo is optional and accepts SVG, PNG, JPEG, or WebP up to 500 KB. The file is stored on the organisation record itself, and there is no image-dimension requirement.

## Steps [#steps]

### Open General [#open-general]

Open "Organisation settings", then **General**. The name and logo you edit here belong to the active organisation, not your personal account.

### Change the name [#change-the-name]

On the "Name" row of "Profile", select "Edit", type the new name, and select **Save**. "Cancel" or `Esc` leaves the name as it was. A counter such as "12/32" shows how many of the 32 characters you have used. The Console does not cut a longer name: it shows "Please use 32 characters at most." and does not save it. A name that another active organisation already uses is refused under the field with "Another organisation already uses this name. Choose a different name." The Console confirms a save with an "Updated successfully" toast.

### Set or remove the logo [#set-or-remove-the-logo]

To set a logo, select **Upload** on the "Logo" row, or "Replace" when one is already set. "SVG, PNG, JPEG or WebP, up to 500 KB." is printed beside it. A read-only view shows "No logo" when none is set. Selecting a logo file saves it as soon as you choose it, and a "Logo uploaded" toast confirms it.

To remove an existing logo, select **Remove**. It takes effect right away and a "Logo removed" toast offers "Undo" for a few seconds, which puts the logo back and shows "Logo restored".

Supply a square image: the Console renders the logo into a fixed square everywhere it appears, a 48-pixel tile here and a small avatar in the account menu's **Organisation** submenu. Anything that is not already square gets cropped, and SVG survives that shrink better than a raster file does.

Note (Only a logo removal has an undo): Each save overwrites the previous name or logo. Removing a logo takes effect at once, and its toast offers **Undo** for a few seconds. After that, or for any other save, the Console keeps no earlier version to revert to: if you need the previous name or logo again, you must re-enter or re-upload it yourself.

## Switch a module on or off [#switch-a-module-on-or-off]

The **Modules** row lists the modules your deployment offers this organisation, with a switch for each. It reads "Choose which of the modules your deployment offers this organisation uses. A module that is switched off stays viewable but cannot be changed." When the deployment offers none, the row reads "Your deployment offers no modules."

Turning a module off opens "Switch off `<module>`?" and says "`<module>` becomes read-only for your organisation. Nobody can change its records until an admin switches it on again." The dialog first checks what is still open and lists it, or reads "Nothing is open in `<module>`." when nothing is. It checks these kinds:

- "Open token sales"
- "Open dealing requests"
- "Running trading sessions"
- "Open multisig wallet drafts"
- "Withdrawals in progress"
- "Changes waiting for approval"

A kind it could not check reads "`<kind>`: could not check". Select **Switch off** to confirm or "Keep on" to leave the module on. After a save the row reads "Modules saved".

## Choose the languages [#choose-the-languages]

The "Language and time zone" section holds the **Languages** row and, below it, the "Display time zone" row. In the "Languages" row, an organisation owner chooses which of the ten languages people in the organisation can pick, and [Languages](https://docs.settlemint.com/docs/console/organisation-settings/languages) covers that row.

## Set the display time zone [#set-the-display-time-zone]

The investor portal shows every time, chart axis, statement date and deadline in the display time zone, with its short name, whatever time zone the investor's browser uses. An investor in Brussels and an investor in Dubai then read the same trade at the same clock time, and that time matches the instrument's own trading day. For Asia/Dubai the portal writes `GST`, short for Gulf Standard Time.

The **Display time zone** row shows the zone in use and where it comes from:

- **Set for your organisation.** An owner chose a zone from the searchable list. "Search time zones" filters it, and the list reads "No time zone matches." when nothing fits.
- **Follows the venue calendar.** No zone is stored, and every trading venue calendar of the organisation uses the same zone.
- **No venue calendar zone applies, so times show in UTC.** No zone is stored, and the venue calendars set no zone or set different ones.

Choose **Use the venue calendar zone** to clear a stored zone. A save toasts "Display time zone saved". The Console itself keeps showing UTC.

## Publish trading terms and risk disclosures [#publish-trading-terms-and-risk-disclosures]

The "Terms and risk disclosures" row, in the "Terms and disclosures" section, publishes the documents that participants must accept before they can trade or withdraw. Choose "Terms" or "Risk disclosure", enter a numeric version and either the document text or a file reference, then select **Publish**.

Set **Require participants to accept this version again** when an update should prompt every participant. Without it, an acceptance of an earlier version with the same major number still counts. The Console publishes a version that takes effect at once. Through the API, a future effective date keeps the version out of the gate until that date.

The row counts published versions and recorded acceptances. **Export acceptances** downloads the participant, document, version, time, and request metadata as CSV. The Investor portal shows the current effective versions after sign-in and opens the rest of the portal only after the participant accepts each one.

## Show redemption funding to holders [#show-redemption-funding-to-holders]

The "Terms and disclosures" section also holds the **Redemption funding** row. Its switch is named by the text beside it: "Hidden from holders" until you turn it on, and "Shown to holders" afterwards, so a screen reader announces the same words a sighted reader sees. It controls what a holder sees when they redeem a matured bond, and whether a refused yield claim names the yield treasury and the amount owed. A link on a bond's maturity tab opens this row.

- **Off:** the holder's redeem sheet shows no treasury figure and no shortfall notice. The role holders this section names still see the figures. If the treasury cannot pay, the redemption is refused with "This redemption cannot be completed", and a yield claim the treasury cannot pay is refused with "The yield treasury cannot pay this claim yet", without the treasury or the amount owed.
- **On:** the holder's redeem sheet, in the Console and in the investor portal, shows the treasury's available balance in the denomination asset. When the requested payout is more than that balance, the sheet shows the shortfall and blocks the redemption. A redemption or yield claim the treasury cannot pay is refused with an error that names the treasury and the amounts.

The redeem sheet reads the switch each time it opens. A change applies the next time a holder opens the sheet, with no page reload, and the sheet hides the treasury figure until that read settles.

An account that holds a management role on the asset always sees the treasury figures, whatever the switch says: custodian, emergency, funds manager, governance, sale admin or supply management. So does an account with the "Permission manager", "Auditor", "System manager" or "Token manager" role on the system, and the bond's maturity treasury wallet. Only an organisation owner can change the switch in the Console.

## Set idle sign-out [#set-idle-sign-out]

The "Security" section opens with the **Idle sign-out** row. It signs a person out after the chosen time without activity. In the Investor portal, that means no mouse, keyboard or page-visibility activity. Everywhere, it also means no request has reached the platform for that long. The choices are "Off", 15 minutes, 30 minutes, 1 hour, 2 hours or 4 hours. "Off" is the default and keeps people signed in until their session ends. A choice saves at once and the row reads "Idle sign-out setting saved". The row lists a stored value outside its choices as an extra choice.

## Set the cooling-off period [#set-the-cooling-off-period]

The "Security" section holds the **Cooling-off after a wallet security change** row, after "Idle sign-out". These changes to a member's wallet signing factors count as a wallet security change:

- a transaction PIN set, changed, removed or reset
- a transaction code added or removed
- recovery codes regenerated

After one, DALP emails the member what changed, when and from where, and refuses every transaction that needs their wallet verification, the PIN, transaction code or recovery code that confirms a transaction, for the period this row sets. The row shows the period in hours when it divides evenly, "24 hours" by default, and "Off" at `0`. A whole number of minutes from 0 to 10080, which is seven days, is accepted, and anything else reads "Enter a whole number from 0 to 10080." Setting it to `0` turns the hold off. The security email is always sent. Select **Save** to store a new period, which toasts "Cooling-off period saved".

The hold starts when a change alters or removes a factor the member already held, adds a second one, or replaces a confirmed set of recovery codes, and when an identity manager resets the member's PIN, so a new member who sets up their first PIN and recovery codes is not held. A member who sets a factor up again after an identity manager reset their PIN is held again from that setup.

While it stands, every signing request the member sends is refused with the instant the hold ends, in the Console and in the investor portal alike, and the same instant is in the email. A member of several organisations is held for the longest period any of them sets, so switching organisation never shortens the hold. A later security change restarts the period from that change.

Only an organisation owner can change the row in the Console. Anyone else who opens the page sees the value without a control.

Making the period longer saves at once. Making it shorter, or turning it off, weakens the hold for every member, so the Console opens **Shorten the cooling-off period** and asks for your wallet verification first. While you hold a transaction code, the platform accepts only that code and refuses a PIN or recovery code without saving. The save is refused while your own hold stands.

Members who are held at that moment are not a reason to refuse: their hold end is recomputed under the new period, and each of them whose hold end moves gets one email with the period that now applies to them and the new hold end, or that the hold has ended. A longer period can also bring back a hold that had already ended. That member gets the same email. No other member is emailed about the change.

An API key cannot shorten the period.

When a member's hold runs out, DALP emails them that their signing hold has ended, once per hold, within about five minutes. If the email cannot be sent, DALP tries again five minutes later. A hold that runs out on its own while the period is **Off** ends without this email.

## Segregation of duties [#segregation-of-duties]

The **Segregation of duties** section sets which pairs of on-chain roles one wallet may not hold together, and what happens to a grant that would put a pair on one wallet. The "Check role grants" row holds the switch. It reads "Role grants are not checked" or "Role grants are checked against the rules". The switch starts off, so no grant is compared with the rules until an owner turns it on. Roles already granted stay as they are, and the conflict report lists the pairs held today whether the switch is on or off.

Below the switch, a table lists the rules with the columns **Roles**, "Applies" and "When broken". An organisation that never saved the setting sees the default pairs, each set to refuse the grant. The first change you save stores the whole rule set, so the defaults you leave in place stay in it.

- **Applies** reads "On the same contract" or "Anywhere in the organisation". A same-contract rule breaks only when both roles sit on the same token, token sale or venue. An organisation-wide rule breaks wherever the wallet holds the two roles in the organisation's system.
- **When broken** reads "Refuse the grant" or "Ask for a reason". A grant that breaks a refusing rule is turned away. A grant that breaks a rule that asks for a reason goes ahead only with a reason, which the audit trail keeps.

To change the rules, turn the switch on or off, choose another value in **When broken** on a row, or open a row's menu and choose "Remove rule". To add a rule, go to "Add a rule" under the table, choose the "First role" and the "Second role", set "Applies" and "When broken", and choose "Add rule". A pair takes one rule for each place it applies. "Choose two different roles." and "This pair already has a rule in that scope." tell you why a rule is not added. Each change saves at once and toasts "Segregation of duties saved".

Only an owner can change the rules in the Console. Anyone else who opens the page sees the rules without a switch, a menu or **Add a rule**.

The Console's role editors send no reason. A grant that breaks a rule that asks for a reason is therefore turned away there, with the line "The organisation allows this grant with a reason. Send it through the Platform API." The alert above the buttons names each pair that conflicts, such as "Custodian cannot be held with Governance on the same contract." [Roles and permissions](https://docs.settlemint.com/docs/console/organisation-settings/admins-and-roles) shows where the editor shows it, and the [Roles and segregation of duties reference](https://docs.settlemint.com/docs/concepts/compliance-and-identity/roles-and-segregation-of-duties) lists the roles and the default pairs.

## Approvals [#approvals]

The **Approvals** section chooses which changes wait for a second person. It lists ten families: Offerings, Corporate actions, Trading venues, Reporting, Bank rail, Custody operations, Withdrawals, Prices, Wallets and Administration. Each row reads "Second person required" or "Not required" and has a "Turn on" or "Turn off" button. Its screen-reader label names the family, such as "Turn off approval for offerings".

The Reporting row and its obligation exceptions read the same way, although the row also controls publishing an obligation, which never waits for a second person. The row's description says what waits while the family is on, or what goes ahead while it is off. A save toasts "Approval rule saved".

The person who makes a change never approves it. A different person who may approve that kind of change decides it on the **Actions** page.

- **Offerings:** creating an offering, opening it for sale, ending it and running the allocation of an oversubscribed offering wait for a second person. The approver sees the sale terms before deciding: the token, the caps, the purchase limits, the start, the duration, the network, the payment currencies with their price per token, the country by name, the presale discount as a percentage and the terms fingerprint.
- **Corporate actions:** recording a corporate action waits for a second person.
- **Trading venues, Reporting and Administration:** the row sets the organisation-wide choice. A venue, a reporting obligation or an Administration protection group that has its own choice appears under "Exceptions": a venue by its name and network, an obligation by its name, a group by its label. Each exception has its own "Turn on" or "Turn off" button and a "Remove" button that returns it to the family's choice.

  To add one, pick from the list under the row ("Choose a venue", "Choose an obligation" or "Choose a protection group"), then select "Require approval for this one" when the family is off, or "Turn off approval for this one" when it is on.

  Until you pick, the button stays disabled and the row says why, for example "Choose a venue to add an exception." The list offers the venues on the network the Console is set to, and the first 100 obligations.

- **Reporting:** while it is on, releasing a venue legal hold waits for a second person, and the platform publishes a reporting obligation only while the organisation has at least two members with the Owner role. Otherwise publishing is refused with `DALP-0719`. An obligation exception changes only that obligation's publishing check, with "Turn on the check for this one" and "Turn off the check for this one".
- **Bank rail:** the row decides whether these changes wait for a different Bank rail manager: a cash-out over the checker threshold, a credit over the credit threshold, the allocation or return of a parked credit, a reserve adjustment, a raised or removed credit threshold or mint cap and the completion or abandoning of a rail wallet rotation.

  Three controls wait for a different manager whatever the row says: approving a client's bank account, executing or abandoning a recall, and the re-credit of a returned payout. The "Approvals required" count applies to the family's changes only. When it is above 1, only an organisation owner who also holds the Bank rail manager role can decide them.

  [Bank rail](https://docs.settlemint.com/docs/console/asset-lifecycle/bank-rail#before-you-start) lists the changes from the manager's side.

- **Custody operations:** resolving a reconciliation break waits for a second person. [Custody reconciliation](https://docs.settlemint.com/docs/console/organisation-settings/custody-reconciliation) shows it from the reconciler's side.
- **Withdrawals:** the row remains but governs nothing. Withdrawal approvals are retired, so withdrawals go ahead without a second person.
- **Prices:** a held price from a price source waits for a second person before it is used. [Price sources](https://docs.settlemint.com/docs/console/organisation-settings/price-sources#held-prices-and-the-second-approver) explains the hold.
- **Wallets:** the row decides whether pushing a wallet's entitlements waits for a second person. A wallet approval that names its checker always waits for that person, whatever the row says.

Under the state of each family that is on, except Reporting, **Approvals required** sets how many different people must approve before a change in the family goes ahead. It starts at 1 and goes up to 10. The person who made the change never counts.

The count you set here applies to every kind of change in the family, and a venue or protection group follows it. Through the API an owner can also give one kind of change its own count, approver roles and expiry, and give a venue or protection group its own count. The row then shows the highest count among the family's kinds. The Reporting row has no count, because nothing in Reporting would read one: one different person decides a legal hold release, and publishing an obligation needs two members with the Owner role. A change that is already waiting keeps the count it started under. Approver roles set on administrative changes never apply to a change of these approval rules: another owner or a platform administrator still approves that.

Raising the count saves at once. Lowering it weakens a control, so the Console opens "Ask for fewer approvals for `<family>`?" and asks for your wallet verification, as "Turn off" does. Select **Lower the count** to continue or "Keep the current count" to cancel. While any Administration protection group is protected, the lower count then waits for another owner or platform administrator to approve it. "Actions" shows a change that needs several approvers with its progress, for example `1 of 2`. If you ask for more approvers than the organisation has people who may approve the change, it cannot be completed and lapses.

"Turn on" saves at once. **Turn off** weakens a control, so it opens "Turn off second-person approval for `<family>`?" and asks you to confirm with your wallet verification. "Turn off approval" sends the change and "Keep approval on" cancels it.

A similar confirmation, which also asks for your wallet verification, guards every other change that removes a second-person check: turning an exception off, adding an exception that turns approval off, and, while the family is off, removing an exception that required approval ("Remove the exception for `<name>`?", with "Remove exception" and "Keep exception"). An obligation exception removes no second-person check, so its confirmation reads "Allow publishing `<name>` with fewer than two owners?" instead, with "Allow publishing" and "Keep the check". The change then applies at once.

While any Administration protection group is protected, the change waits for approval instead: the row keeps its current state and reads "Turn-off waiting for approval" until another owner or a platform administrator decides. That approver can be a platform administrator, so no owner of the organisation is necessarily asked.

The row says who asked, when, and when the request lapses, in UTC: it names the member who asked, or reads "someone else" when the name is not known. On a turn-off you asked for yourself, the row offers **Withdraw request** in place of "Turn off". It cancels the request at once, with no PIN: the family keeps asking for approval, and the request leaves Actions so nobody can approve it.

Only the member who asked can withdraw it. Another owner approves or rejects it instead. A request already waiting keeps the rule it started under.

A request raised while its family is off runs without a second person. **Actions** and its detail sheet show it as "No second approval (approval off)". While any Administration protection group is protected, every edit of the list of protection groups and every change that switches a family or exception off or lowers a count waits for an owner or platform administrator to approve it, whatever the number of owners. Turning a family on and raising a count apply at once, with no PIN. A session in which a platform administrator acts as another user cannot switch an approval off, lower a count or remove an exception. Sign in as yourself to do it.

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

- A name or logo save confirms with a toast: "Updated successfully", "Logo uploaded", "Logo removed" or "Logo restored".
- The modules, idle sign-out and redemption funding rows confirm in the row itself, such as "Saved".
- Display time zone, cooling-off and approval saves confirm with the toasts each task names.
- The new name or logo is already visible on General itself and everywhere else that reads the organisation directly, no reload needed.
- If your account belongs to more than one organisation, the **Organisation** submenu of the account menu can lag behind: it reads a separate list that refreshes only on a full page reload, or once idle five minutes when you switch back to the tab.
- In-app navigation between Console pages does not trigger that refresh.

## Troubleshooting [#troubleshooting]

**The “Edit”, “Upload” and “Remove” buttons are missing**

The controls show only to an owner of the organisation. A platform administrator who is not an owner sees the values
and one line saying that organisation owners manage these settings. Ask an organisation owner to make the change, or
to make you an owner. A member who is neither sees no **General** in the sidebar, and a General link opens the Not
available page.

**The new logo or name is not visible elsewhere**

If General itself still shows the old name or logo, the save did not go through. Check for "Request failed" under the
name field or in a toast rather than reloading, since General already reflects a successful save without one. The
Organisation submenu, for an account in more than one organisation, is different: it can lag by design, so give it a
full reload before treating it as a bug.

**The logo upload is rejected**

The Console checks the file in a fixed order: an empty file fails first, then an unrecognised image type, then a
mismatch between the file's declared type and its actual contents, then anything over 500 KB. A renamed file extension
does not get past the content check, so if the upload fails, confirm the file is an SVG, PNG, JPEG, or WebP under 500
KB and not a different file renamed to look like one.

**Save fails with “Request failed”**

A name save shows "Request failed" under the name field, and a logo save shows it in a toast. The server rejected the
request after the Console already let you submit it. This can happen if your role's permission changed since the page
loaded, or from a temporary network problem. The message includes a reference id. If retrying does not clear it, share
that id with your platform administrator.

## Frequently asked questions [#frequently-asked-questions]

### Does renaming the organisation change its slug?

No. Name and slug are separate fields on the organisation record, and the Profile section only ever sends the field you changed: a name edit sends the name, a logo change sends the logo. Nothing in this workflow reads or writes the slug, so anything keyed on the slug stays as it was.

### What happens if two people edit the profile at the same time?

The last save wins. The update request carries no version check, so if a colleague saves a name change moments after you save a logo change, both land, because they touch different fields. Two people changing the same field in the same window is different: whichever save reaches the server second overwrites the first, with no conflict warning to either person.

### Does an API key need the Owner role to change the General settings?

For the name and logo, yes: the request must come from an owner of the organisation, whether it uses a session or a supported API key. The settings rows written through `/api/v2/settings` and the approval rules also accept a platform administrator. Scope bounds which kind of request a key may make. It does not widen what its underlying account may do at the organisation level. Create the key under an owner's account, or have an owner create it for your integration.

### Does this page change my own name or login details?

No. Your account menu has its own page called Profile, which holds your email, password and identity details. General changes only organisation-wide settings, and its Profile section changes only the organisation's name and logo. An account can belong to more than one organisation, and each keeps its own name and logo here, independent of every other one that account can switch into.

## API routes [#api-routes]

- The `IDLE_TIMEOUT_MINUTES` setting behind **Idle sign-out** is written through `POST /api/v2/settings`, which accepts `off` or a whole number of minutes from 5 to 240.
- The `SIGNING_FACTOR_COOLDOWN_MINUTES` setting behind the cooling-off row is written through `POST /api/v2/settings`. A value below the current one needs `walletVerification` in the body. Deleting the setting, which returns it to the default, is refused while the current period is longer than the default. Set it to `1440` with `walletVerification` instead. Both checks run again against the value stored at the moment of the write, so a save that another administrator's longer period, saved just before it, turns into a shortening is refused with `403`. Verify and save again. A held signing request answers `403 WALLET_VERIFICATION_HELD` with `heldUntil` and `retryAfterSeconds` in its data.
- The approval rules are `GET /api/v2/operations/approval-policy` and `PUT /api/v2/operations/approval-policy`, where each family carries `requiredApprovals` and, under `kinds`, each kind of change its own `enabled`, `requiredApprovals`, `approverRoles` and `expiryHours`. A `PUT` with `kind` sets only that kind. A `PUT` that weakens a rule needs `walletVerification`: turning a kind off, lowering its count, adding an approver role, making its expiry longer, or setting roles or an expiry where the kind used the action's own. A `PUT` that is held answers `202` with the approval id. The setting `CORPORATE_ACTION_MAKER_CHECKER_ENABLED` reads and writes the **Corporate actions** row.
- The display time zone is readable with `GET /api/v2/settings/display-time-zone`, which answers the zone and its source.
- The redemption funding switch controls the v2 reads `GET /api/v2/tokens/{assetId}/stats?metric=bondStatus` and `GET /api/v2/tokens/{assetId}/treasury/health`. While it is off, any other caller gets a 403 `TREASURY_DISCLOSURE_WITHHELD` answer from both. The frozen v1 read `GET /v1/token/{tokenAddress}/stats/bond-status` is outside the switch: any member of the organisation can still read it.


# Holiday calendars

Source: https://docs.settlemint.com/docs/console/organisation-settings/holiday-calendars
Create the calendars your organisation owns and close the days on which its filing deadlines and trading venues do not count.

Holiday calendars is where your organisation keeps its own calendars: named lists of closed days, the dates on which business does not happen. The platform reads them in three places.

A filing deadline rule that counts business days skips every closed day, a trading venue does not trade on a day its calendar closes, and a bank rail connection counts its payment days, cut-off and deadlines on its calendar, as [Set when the bank takes payments](https://docs.settlemint.com/docs/console/asset-lifecycle/bank-rail#set-when-the-bank-takes-payments) describes.

Saturday and Sunday need no entry, because the deadline calculation never counts them as business days. A bank rail connection set to **No holiday calendar** counts every day as a business day, weekends included.

Each calendar can extend a base calendar: a calendar the platform ships for a whole market, such as the TARGET2 settlement calendar. An extending calendar inherits every day its base closes and adds the days that only your organisation observes, such as an office closure or a local holiday. Other organisations cannot see the days your organisation closes. Platform administrators publish and maintain the base calendars on [Base calendars](https://docs.settlemint.com/docs/console/platform-admin/base-calendars).

![Holiday calendars list with each calendar's name, jurisdiction, closed days this year and next closure](https://docs.settlemint.com/docs/screenshots/console-organisation-holiday-calendars.light.en.webp)

[Screenshot] The "Holiday calendars" table, with one row for each calendar your organisation owns.

The table has the columns "Calendar", "Jurisdiction", "Closed this year" and "Next closure", and each row holds a **Close a day** button. A trading venue's calendar also appears, with "Trading venue" as its jurisdiction and "Managed on the venue" in place of the button. "New calendar" sits at the top of the page.

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

- **Owner or platform administrator.** You need the Owner role in the organisation, or to be a platform administrator. The sidebar shows "Holiday calendars" in the "Business operations" section of the settings sidebar only for those two. The Platform API accepts the same two roles and refuses a create or a closed day from anyone else. A member can read the organisation's calendars through the Platform API but cannot change them.
- **A closed day is permanent.** The "Close a day on `<calendar>`" dialog says so: "A closed day is added, never removed. Only your organisation sees it. A correction published later never moves a deadline that was already computed." Check the date before you confirm, because this page has no control that reopens a day. A venue-only closed day follows its own rule: on the venue's "Trading calendar" tab a venue administrator can edit or delete one dated from the current date onward.
- **The name.** The platform derives the calendar's identifier from the name, so the Console has no rename. Two names that differ only in case or punctuation, such as "Q1 Closures" and "q1-closures", produce the same identifier and the second one is refused. Accented Latin letters fold to plain ones, and a letter from another script such as Chinese forms no identifier.
- **What it extends.** Choose the base calendar for the market whose days you want to inherit, or another of your organisation's calendars. Choose "Extends nothing" only when you intend to list every closed day yourself. For a reporting deadline rule that uses calendar dates or business days, each named calendar must contain at least one closure known when the deadline is computed. An empty calendar cannot serve that rule: adding a filing period is refused, and the refusal's `data.violations` reads "Holiday calendar `<id>` for `<jurisdiction>` has no closure effective for this deadline."

## Steps [#steps]

### Create a calendar [#create-a-calendar]

Select **New calendar** at the top of the page. The sheet reads "Closed days on this calendar are seen by your organisation alone."

1. Enter a **Name**.
2. Choose a **Jurisdiction**: a country, or a regional code such as EU. The jurisdiction labels the calendar in the table and in every list where it is offered. It does not change which days are closed.
3. In **Extends**, choose the calendar to inherit from: the list offers "Extends nothing", the platform's base calendars and your organisation's own calendars, each shown as the name with its jurisdiction. Another organisation's calendar is never offered, and a venue's own calendar is not offered as a parent.
4. Optionally add a **Reason (optional)** of up to 1,000 characters, which the platform records in the audit trail with the change.
5. Select **Create calendar**. Until the form is complete the button stays unavailable and says "Enter a name to publish." or "Choose a jurisdiction to publish."

The message "A calendar with this name already exists. Choose another name." means the name produces an identifier your organisation already uses. Choose a different name. A name that forms no identifier reads "Calendar name can't form an identifier. Use Latin letters or digits, and replace any letters from other alphabets." A new calendar closes no day of its own until you close one.

## Close a day [#close-a-day]

1. On the calendar's row, select **Close a day**. The dialog "Close a day on `<calendar>`" opens.
2. Choose the **Date** in the calendar, or the dialog says "Choose the date to close." The calendar offers days from 1 January 2024 through 31 December of the tenth year after the current year.
3. Choose a **Reason**: "Public holiday", "Bank holiday", "Settlement holiday", "Exchange holiday", or "One-off closure". The reason is a label for whoever reads the calendar later. It does not change how a deadline or a venue treats the day: every closed day is closed in the same way.
4. Optionally enter a **Name (optional)** of up to 120 characters for the day, such as "Christmas Eve", and a "Reason (optional)" of up to 1,000 characters for the audit trail.
5. Select **Close a day**. A second dialog names the day, for example "Close 24 Dec 2026?", and says "A closed day is added and never removed, so 24 Dec 2026 stays closed for good." Check the year: every calendar and venue below this calendar in a chain stops counting it as a business day. Type the day as the dialog shows it, then select "Close 24 Dec 2026" to add it, or "Keep 24 Dec 2026 open" to go back and change the date.

Closing a day that the base calendar or this calendar already closes is harmless: the day stays closed once. Closing the same day again with another reason, or as another owner or platform administrator, adds a second line under that year, and the day still counts once. Close a weekend day only for a venue that trades at the weekend: a filing deadline never counts Saturday or Sunday.

## Read the calendars [#read-the-calendars]

The page lists the calendars your organisation owns in a table, and **Search calendars** filters it. The table has four columns:

- **Calendar** shows the name and what it extends, such as "extends TARGET2 settlement calendar".
- **Jurisdiction** shows the calendar's jurisdiction.
- **Closed this year** counts the closed days, such as "3 days".
- **Next closure** shows the next closed day, or "None scheduled" when there is none.

The last cell of each row holds **Close a day**, or for a venue's own calendar the link "Managed on the venue" to the venue's "Trading calendar" tab. With no calendar, the page reads "No organisation calendars yet" with "Create one to close a day of your own."

Expand a row to read its closed days. A note such as "Extends TARGET2 settlement calendar" names the chain, and the days are grouped under a heading for each year with its count, such as "3 closed days". The columns are "Date", "Name" (shown when some day has a name), "Reason" and **Added by**.

In "Added by" an inherited day shows "from" and the name of the calendar that closes it, for example "from Northwind closures". Days closed on your organisation's calendars show "Organisation administrator", also when a platform administrator closed them, and a platform base day shows "Platform administrator". The [Audit trail](https://docs.settlemint.com/docs/console/reporting/audit-trail) names the person who closed each day.

A day from a published source shows that source, with any web address in it shown as a link named by its site. A calendar with no closed day reads "This calendar has no closed days yet".

The list can also show two kinds of calendar that you did not create on this page. A calendar that carries a base calendar's name is the extension the platform creates when a venue administrator picks that base for a venue. It mirrors the base, and the platform refuses a closed day on it. A venue's own calendar shows "Trading venue" as its jurisdiction and "Managed on the venue" where the "Close a day" button would be, because only the venue's **Trading calendar** tab can close a day on it.

## How a calendar chain decides a closed day [#how-a-calendar-chain-decides-a-closed-day]

A calendar's closed days are its own days plus every day closed by the calendars above it in its chain. "Extends" names the calendar directly above. A chain holds at most eight calendars, and the platform refuses a parent that would make the chain longer or make a calendar extend itself through another one.

[Figure] Closed days flow down a calendar chain, and nothing below can reopen them. Three calendars form a chain. The base calendar, published by a platform administrator, closes 25 December. An organisation calendar extends the base: it inherits 25 December and adds its own one-off closure on 31 December. A venue calendar extends the organisation calendar: it inherits both days and can close a day for that venue alone. Each calendar below sees every day closed above it, and no calendar can reopen an inherited day. Filing deadlines skip the closed days of the calendars their rule names, and a venue does not trade on its calendar's closed days. Labels: TARGET2 settlement; Base calendar; Platform administrator; 25 Dec, own; Extends; Northwind closures; Holiday calendar; Organisation Owner; 25 Dec, inherited; 31 Dec, own; Extends; One trading venue; Venue calendar; Venue admin; Both days, inherited; Reopens neither; Filing deadlines skip the closed days of the calendars their rule names.; A venue does not trade on a day its calendar closes.

Each calendar sees every day closed above it, and it can add days but never remove one it inherits.

The chain has three levels. A venue administrator chooses a venue's trading week and parent calendar, and can add, edit and delete venue-only closed days dated from the current date onward. The table shows who manages each level.

| Level | Who manages it | Where | Who sees its closed days |
| --- | --- | --- | --- |
| Base calendar | A platform administrator | [Base calendars](https://docs.settlemint.com/docs/console/platform-admin/base-calendars) | Every organisation whose calendar extends it |
| Holiday calendar | An Owner of your organisation or a platform administrator | This page | Your organisation only |
| Venue calendar | Venue administrator | The venue's **Trading calendar** tab, under [Venues](https://docs.settlemint.com/docs/console/asset-lifecycle/venues/trading-calendar) | That venue only |

The platform ships four base calendars. "TARGET2 settlement calendar", "UK bank holidays (England and Wales)", and "US federal holidays" carry closed days computed from their published rules for 2024 through 2040. "ADGM business days (UAE public holidays)" carries only the UAE public holidays that have been announced, because the UAE can move a holiday. Each later date is added once it is announced.

### Closed days and computed deadlines [#closed-days-and-computed-deadlines]

Every closed day records when the platform learned about it. When the platform computes a filing deadline, it counts only the closed days it knew about at that moment. A day closed afterwards does not move a deadline that was already computed, so a deadline that a filer has relied on stays fixed. Changing the calendar a calendar extends, which only the Platform API can do, replaces what it inherits: the old parent's days stop applying, and the new parent's days count only from the moment of the change.

The venue's **Trading calendar** tab states the rule for venues: "A day closed here shuts this venue alone. A day inherited from the shared calendar shuts every venue that extends it." [Trading calendar](https://docs.settlemint.com/docs/console/asset-lifecycle/venues/trading-calendar) explains what an instrument does on a day with no session.

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

- The message "The day is closed." confirms the write, and the day appears under its year in the calendar's expanded row with the reason you chose. For a new calendar, "The calendar is stored." confirms it, and the row shows "extends" and the parent you chose under its name.
- To check the effect, open a calendar that extends this one: the day appears there with "from" and this calendar's name in the **Added by** column. A venue that extends this calendar shows the day in its "Closed days" on the venue's "Trading calendar" tab.

## Troubleshooting [#troubleshooting]

**Calendars could not be read**

The error card "Calendars could not be read" says "The calendars this organisation owns could not be read. Reload to
try again." when the organisation's own calendars fail to load. When only the base calendars fail, the page still
shows the table, with a **Base calendars** line and a retry control. Reload the page. If the message stays, check
[Platform status](https://docs.settlemint.com/docs/console/organisation-settings/platform-status) for a platform fault before you retry.

**The calendar or the day could not be saved**

A failed create reads "The calendar could not be stored." and a failed closed day reads "The day could not be closed."
Check the form for a name that is taken or a date outside the allowed range, then try again.

**The Create calendar button stays disabled**

**Create calendar** needs a name that is free and a jurisdiction. A name that collides with an existing calendar shows
the message "A calendar with this name already exists. Choose another name." under the field. A name made only of
punctuation, or containing a letter or digit from another script such as Chinese, Cyrillic or Arabic, produces no
identifier, so the button stays disabled until the name uses only Latin letters and digits. Accented Latin letters are
fine: "Café" gives "cafe". If another administrator creates that name while your form is open, your create is refused.
The existing calendar stays unchanged, and your form keeps its inputs. Choose another name and create again.

**A day was closed by mistake**

A closed day cannot be removed, by your organisation or by a platform administrator. Deadlines computed before the
mistake keep their dates. Deadlines computed after it skip the day, and a venue that extends the calendar does not
trade on it. If the mistake must not affect a venue, point the venue at a different calendar in **Holiday calendar**
on its "Trading calendar" tab.

**Creating a calendar with a parent is refused**

A chain holds at most eight calendars. The platform refuses a parent whose chain is already eight calendars long, with
"The holiday calendar would reference itself", the same message as a cycle. Choose a parent higher up the same chain,
or a base calendar directly.

**A deadline did not move after a day was closed**

This is expected when the deadline was computed before the day was closed. A deadline counts only the closed days the
platform knew about when it computed the deadline, so a later closure applies to deadlines computed after it.

**Holiday calendars is not in the sidebar**

The entry appears only for an organisation owner or a platform administrator with an active organisation. Ask an owner
of your organisation to make the change, or to give you the Owner role if your organisation intends that. [Roles and
permissions](https://docs.settlemint.com/docs/console/organisation-settings/admins-and-roles) lists the roles.

## Frequently asked questions [#frequently-asked-questions]

### Can I reopen a day that a base calendar closes?

No. The Console has no control that removes an inherited day. Through the Platform API, changing a calendar's parent stops the old parent's days counting for deadlines computed after the change and for every venue that extends the calendar. Deadlines computed before it keep their dates. If your organisation trades or files on a day a base closes, create a calendar that extends nothing and close every day yourself, or ask a platform administrator whether a different base calendar fits your market.

### Does a day my organisation closes affect another organisation?

No. Days closed on your organisation's calendars are visible to your organisation only. Only a day closed on a base calendar reaches every organisation whose calendar extends that base.

### Can I delete a calendar?

No. Neither the Console nor the Platform API deletes a holiday calendar. A calendar you no longer need stays in the list. Stop using it by pointing each venue at another calendar on its **Trading calendar** tab and each reporting obligation at another calendar through the API.

### Do I have to close Saturdays and Sundays?

Not for filing deadlines: the deadline calculation never counts Saturday or Sunday as a business day. A venue's trading week is set separately on its **Trading calendar** tab, so a weekend closure matters only for a venue that trades on a weekend day.

### Why does my list show a calendar named after a base calendar?

A venue administrator picked that base calendar for a venue. The platform then creates a calendar for your organisation that extends the base, and the venue's own calendar extends that one. It mirrors the base. The Console shows **Close a day** on it, but the platform refuses the write with "The holiday calendar was not found". To add days for venues on top of a base, create your own calendar that extends the base, close the days there, and point each venue at it on its "Trading calendar" tab.

## API routes [#api-routes]

The Platform API exposes the same operations under the organisation settings calendar endpoints: `GET /api/v2/settings/calendars` lists your calendars, `GET /api/v2/settings/calendar-bases` lists the base calendars, `PUT /api/v2/settings/calendars/{calendarId}` creates or updates a calendar (send `If-None-Match: *` to refuse an id that exists), and `POST /api/v2/settings/calendars/{calendarId}/closures` adds a closed day.

The Console gives a calendar it creates the id `org:<organisationId>:<slug>`. A parent that would make a cycle or a chain longer than eight answers 409 `PLATFORM_HOLIDAY_CALENDAR_CYCLE` (DALP-14351), and an id that is taken answers 409 `PLATFORM_HOLIDAY_CALENDAR_EXISTS` (DALP-14352).

A create or update through the API can also change an existing calendar's name, jurisdiction, or parent, which the Console does not offer. The request and response shapes are in the [Platform API reference](https://docs.settlemint.com/docs/api-reference/v2).

A filing deadline rule names the calendars it counts against when you configure a reporting obligation through the API. [Reporting obligations](https://docs.settlemint.com/docs/concepts/records-and-evidence/reporting-obligation) explains how a deadline rule uses them.


# Organisation settings

Source: https://docs.settlemint.com/docs/console/organisation-settings
Every Console settings screen, from General to Webhooks, in the three groups the Organisation settings sidebar shows.

**Organisation settings** opens a sidebar of its own with three groups.

- The first group, with no heading, holds the organisation itself: "General", "Roles and permissions", "Theme" and "Assistant".
- **Business operations** holds "Custody" and "Holiday calendars".
- **Infrastructure** holds "Platform status", "Networks", "Factories", "System updates", "Transaction funding", "Data feeds" and "Webhooks".

Some pages have no sidebar entry of their own. Languages covers the "Language and time zone" section of General. Custody books and Custody reconciliation open from Custody, and Platform status transactions from Platform status. Price sources and Exchange rates are the "Sources" and "Exchange rates" tabs of Data feeds.


  - [General](https://docs.settlemint.com/docs/console/organisation-settings/general): Change the organisation's name, logo, modules, languages, time zone, terms and approvals.
  - [Languages](https://docs.settlemint.com/docs/console/organisation-settings/languages): Choose the languages your organisation offers and your own Console language.
  - [Roles and permissions](https://docs.settlemint.com/docs/console/organisation-settings/admins-and-roles): Review, grant and revoke on-chain roles for the system, each asset and each offering.
  - [Theme](https://docs.settlemint.com/docs/console/organisation-settings/theme): Set Console branding and the issuer name and disclaimer printed on statements.
  - [Assistant](https://docs.settlemint.com/docs/console/organisation-settings/assistant): Turn the assistant on or off, add the OpenRouter key and choose what it may send.
  - [Custody](https://docs.settlemint.com/docs/console/organisation-settings/custody): Manage the organisation's custody provider catalogue, credentials, and execution health.
  - [Custody books](https://docs.settlemint.com/docs/console/organisation-settings/custody-books): Review customer withdrawals, work operations cases and review withdrawal destinations.
  - [Custody reconciliation](https://docs.settlemint.com/docs/console/organisation-settings/custody-reconciliation): Work the reconciliation break register and review withdrawal destinations.
  - [Holiday calendars](https://docs.settlemint.com/docs/console/organisation-settings/holiday-calendars): Create your own calendars and close the days that filing deadlines and venues skip.
  - [Accounting](https://docs.settlemint.com/docs/console/organisation-settings/accounting): See what DALP posted to your Xero ledger, why a record did not post, and retry it.
  - [Platform status](https://docs.settlemint.com/docs/console/organisation-settings/platform-status): Review live platform health across its service areas and outbound deliveries.
  - [Transactions](https://docs.settlemint.com/docs/console/organisation-settings/platform-status-transactions): Find a transaction, read its queue and chain detail and recover a stuck one.
  - [Networks](https://docs.settlemint.com/docs/console/organisation-settings/networks): Turn on multi-network support, add networks, track deployments and create bundler wallets.
  - [Factories](https://docs.settlemint.com/docs/console/organisation-settings/factories): List the token and add-on factories a system deploys through and register a missing type.
  - [System updates](https://docs.settlemint.com/docs/console/organisation-settings/system-updates): Compare deployed components with the latest DALP release and upgrade them in one run.
  - [Transaction funding](https://docs.settlemint.com/docs/console/organisation-settings/transaction-funding): See who pays gas, fund the paying wallets and move from EOA to smart wallets.
  - [Data feeds](https://docs.settlemint.com/docs/console/organisation-settings/data-feeds): Register and maintain trusted on-chain data feeds for subjects and topics.
  - [Price sources](https://docs.settlemint.com/docs/console/organisation-settings/price-sources): Connect a provider's prices to token price feeds by ISIN and act on a stale feed.
  - [Exchange rates](https://docs.settlemint.com/docs/console/organisation-settings/exchange-rates): Enable tracked currencies and inspect the latest recorded exchange rates.
  - [Webhooks](https://docs.settlemint.com/docs/console/organisation-settings/webhooks): Create webhook endpoints, choose their events and inspect, resend and replay deliveries.



# Languages

Source: https://docs.settlemint.com/docs/console/organisation-settings/languages
Choose which of the ten languages your organisation offers, pick your own Console language from the account menu, and read how Arabic runs right to left.

An organisation owner chooses which of the ten Console and Investor portal languages the people in the organisation can pick, and English is always one of them. The Investor portal is the app your investors use. Each person then picks their own language from the account menu, and Arabic shows the whole layout right to left.

![Language and time zone section of General with a checkbox for each of the ten languages](https://docs.settlemint.com/docs/screenshots/console-organisation-general-languages.light.en.webp)

[Screenshot] The "Language and time zone" card holds the "Languages" row and ten checkboxes, one per language by its own name.

The "Languages" row carries the note "People in your organisation can choose from these languages." "English" is selected and shows "Always on". Below it, the "Display time zone" row shows the zone in use.

| Language | Name in the language menu | Code |
| --- | --- | --- |
| English | English | `en-US` |
| German | Deutsch | `de-DE` |
| Arabic | العربية | `ar-SA` |
| Japanese | 日本語 | `ja-JP` |
| French | Français | `fr-FR` |
| Dutch | Nederlands | `nl-NL` |
| Malay | Bahasa Melayu | `ms-MY` |
| Indonesian | Bahasa Indonesia | `id-ID` |
| Thai | ไทย | `th-TH` |
| Korean | 한국어 | `ko-KR` |

In every Console language, the language menu shows each language that the organisation offers by its own name, as in the second column. Arabic is the only one of the ten that reads right to left. The Console and the Investor portal serve their own fonts for Arabic, Thai, Japanese and Korean, also behind an organisation's own theme font, so these scripts and the language names in the menu display on a computer that has no font for them installed. The Arabic text is Modern Standard Arabic. A browser that asks for a regional form of Arabic, such as `ar-AE` for the United Arab Emirates, gets this Arabic.

The **Language and time zone** section of General also holds the display time zone. [General](https://docs.settlemint.com/docs/console/organisation-settings/general) covers the rest of that page, and [Profile](https://docs.settlemint.com/docs/console/my-account/profile) covers your own account details.

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

- **To choose the organisation's languages,** you must be an owner of the active organisation, which is the organisation you are signed in to. "Organisation settings" and its "General" page show in the sidebar for organisation owners and platform administrators. A platform administrator who is not an owner of the organisation sees the languages but cannot change them in the Console.
- **To pick your own language,** you need no role. The language menu shows only when your organisation offers more than one language. Before you sign in, the sign-in screens offer all ten.

## Steps [#steps]

### Open the Language and time zone section [#open-the-language-and-time-zone-section]

Open "Organisation settings", then "General", and select **Language and time zone** in the section index at the side of the page. The section has its own address, `/org-settings/general#language-and-time-zone`.

### Select or clear languages [#select-or-clear-languages]

The **Languages** row shows the text "People in your organisation can choose from these languages." and one checkbox for each of the ten languages. Select the checkbox of a language to offer it. Clear the checkbox to stop offering it. "English" stays selected and shows "Always on".

Note (Clearing a language moves its users to English): When you clear a language, every staff member and investor who uses it gets English, at the latest the next time they reload the page or sign in again. Tell them before you clear it.

Each change saves at once. The row shows "Saving…" and then **Languages saved**. The checkboxes are unavailable while the save runs.

During organisation onboarding, the **Languages** field shows the same ten checkboxes, all selected, so a new organisation starts with all ten languages. An organisation that never saved a choice also offers all ten.

## Pick your own language [#pick-your-own-language]

Any signed-in user can do this from the account menu. It is not a setting of the organisation.

### Open the account menu [#open-the-account-menu]

Select your name in the Console header to open the account menu. On the sign-in screens and during onboarding, use the language button in the header instead.

### Choose a language [#choose-a-language]

Select **Language**, then select a language in the list. The current language has a check mark, and selecting it again changes nothing. The list is unavailable for a moment while the Console loads the new language. The Console then changes language without a page reload.

![Account menu open with the Language entry above the theme control](https://docs.settlemint.com/docs/screenshots/console-account-menu-language.light.en.webp)

[Screenshot] The account menu lists "Profile", "My participants", "On-chain identity", "API keys" and "Security", then "Language" and the theme control.

"Language" opens a submenu that lists the languages the organisation offers by their own names, such as "English", "Deutsch" and "العربية", with a check mark on the current language. On a phone the languages sit in the account menu under a "Language" heading instead, so nothing opens over the other rows.

## What the language changes [#what-the-language-changes]

Most of the Console's labels and messages have a translation in each of the ten languages. A text with no translation, and some text the chain or the platform sends, shows in English.

- Numbers use the decimal mark and grouping of the language, and the digits 0 to 9 in every language, Arabic included. Amounts, counts, table page numbers, chart axes, dates and the fields where you type a number all show 0 to 9, the same digits as the addresses and codes beside them.
- A number field's example, such as `e.g., 1,000,000` or German `z. B. 1.000.000`, uses the language's word for "for example" and its grouping, so Arabic reads `مثال: 1,000,000`.
- In the Investor portal, the order ticket, the amend order dialog, the order review rows, the signing line and the amounts the ticket works out, such as the order value and the amount reserved, also show 0 to 9.
- A number field accepts a number typed in the form of the language, such as German **1.234,56**, Arabic-Indic digits, or Japanese full-width digits. It also accepts the digits 0 to 9. When you leave the field, it shows the number with the digits 0 to 9.
- Dates and relative times show in the language, on the Gregorian calendar in every language. An Arabic date is a Gregorian date, not a Hijri date, and a Thai date shows the year 2026, not the Buddhist Era year 2569.
- Lists of names, currencies, roles and countries use the list form of the language, such as "A, B, and C" in English, "A, B und C" in German and "A、B、C" in Japanese.
- The compliance templates, asset classes, instrument templates and instrument structures that come with the platform show their names and descriptions in the language. A name your organisation typed stays as typed. An entry that comes with the platform and has no translation shows its stored English text.
- A compliance rule summary shows in the language, with the plural forms and country names of the language.
- The audit trail names each recorded operation as one action phrase in the language, such as "Place order" or "View asset" in English.
- The title of a failed transaction that a smart contract refused shows in the language on the activity details sheet and the dashboard Needs attention item, with the amounts and accounts of the refusal filled in. The Why and What to do next texts stay in the English the platform sends, under the caption "Original chain or server text" in the language, unless the Console has its own text for that refusal. A refusal the Console has no title for shows the platform's English title.
- A failed submission in the Submissions tray, and on the dashboard Needs attention item, shows the title, reason and next step that the Console wrote in the language you use now, also after you change language. A submission that failed before this was recorded, and text that the platform or a form wrote itself, shows as recorded. Text the platform sent keeps its own left-to-right direction inside Arabic text, so its sentences end where they should.
- The message that reports a refused change, such as a compliance rule change, shows its next step in the language when the platform sent the standard next step for that error. A next step the platform wrote for that one refusal shows in the English the platform sends.

## Arabic reads right to left [#arabic-reads-right-to-left]

When you select Arabic, the page direction changes to right to left, so the layout, menus and reading order mirror. Selecting a left-to-right language restores the layout at once.

The language menu stores your choice in a language cookie in that browser. When the cookie names Arabic, the platform sets the direction before it sends the page, so the page does not change direction while it loads. On a new device, the first page after sign-in can open in the browser's language and then change to the language saved on your account.

- A chart keeps its axes left to right, so time still runs from left to right. The legend and the text around the chart follow the page direction. The axes of a vote result chart also follow the page direction. The date and time on an axis read as one right-to-left phrase, so a day stays with its month and the time follows them.
- Figures keep the same fixed-width face as in English, including the trading prices, quantities and percentages in the Console and Investor portal. Arabic words in compact amounts keep their joined letters. The approximation sign **≈** stays beside its amount, before the digits, and the currency stays with the amount. When a chart breakdown or the dashboard allocation card shows less than one percent, the less-than sign stays before the percentage, and the Required and Warning levels on the collateral chart keep the percent sign beside their number.
- Text your organisation typed, such as an English template name, takes the direction of its own words. When an English name is too long for its space on an Arabic page, the platform cuts the end of the English text and shows an ellipsis on its right.

## How the platform picks a language [#how-the-platform-picks-a-language]

The platform picks a language in this order:

1. Before it sends a page, the platform uses the language in the browser's language cookie. The cookie holds the last language that browser used.
2. With no cookie, it uses the first language in the browser's language list that is one of the ten. It goes down the list from the most preferred language. A regional form matches its base language, so `de-AT` gets German.
3. With no match, it uses English.
4. After you sign in, the Console changes to the language saved on your account. The saved language comes before the cookie and the browser list.

At each step, a language the organisation does not offer becomes English.

Error messages from the sign-in and account screens, such as a wrong password, use the language in the cookie. Without a cookie, they use the browser's language. When the browser's language is not one of the ten, they use English.

## Language of emails [#language-of-emails]

The platform picks the language of each email for its recipient. It uses the first of these that applies:

1. The language saved on the account of the recipient's email address.
2. When the recipient has no account yet or never selected a language, the language of the person who sent the email, for an email that has a sender, such as an invitation.
3. English.

When the email belongs to an organisation that does not offer the picked language, the email is in English. The organisation has no separate default language for emails.

- An investor who sees the Investor portal in Arabic only because of the browser language has no saved language. An email to that investor is then in the sender's language, or in English when the email has no sender. The investor gets emails in Arabic after selecting Arabic in the account menu while signed in.
- An Arabic email reads right to left. Dates use the Gregorian calendar in the organisation's display time zone and name that zone. Dates, times and amounts show the digits 0 to 9 in every language, Arabic included. Amounts use the grouping and decimal mark that go with those digits, such as **1,234.56**.

## The Investor portal [#the-investor-portal]

The Investor portal uses the same ten languages and follows the same organisation setting. Before sign-in it offers all ten. After sign-in it offers the organisation's languages, and a saved choice outside them becomes English. When the portal cannot read the organisation's languages, or the read takes longer than two seconds, it offers all ten for that page.

The language button is next to the theme button on the sign-in and onboarding screens, and the account menu has the same **Language** entry as the Console. An Arabic portal page shows right to left. A token symbol in Arabic text keeps its own direction.

The pages an investor opens after sign-in read in the chosen language, with the Console's wording. That includes the **Working as** page and its "Register in organisation" dialog, the "Invest" page with its offering cards, the title of each page in the browser tab, the Export, View and page controls of every table, and the reason shown when the platform refuses a withdrawal or a register line request.

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

- **Your own language.** Menus, labels, dates and numbers change at once, and the account menu shows the check mark next to the language you selected. In Arabic the layout changes to right to left. When you are signed in, the platform saves the choice on your account. When you sign in with the same account on another device or in the Investor portal, the platform changes to the saved language after sign-in, if your organisation offers it. A choice made before sign-in stays in that browser only.
- **The organisation's languages.** The row shows "Languages saved" and the checkboxes show the new set. Your own language menu shows the new set without a page reload. Other people get the new set at the latest when they reload the page or sign in again. From then on, a person whose language you cleared sees English. Their saved choice stays on their account. If you offer that language again, it applies again after they reload the page or sign in again.

## Troubleshooting [#troubleshooting]

**The language menu is missing**

Your organisation offers only English, so there is no other language to select. Ask an organisation owner to offer
more languages on **General**.

**The Console went back to English**

The organisation stopped offering the language you used, or your browser asks for a language the organisation does not
offer. Select another language from the account menu, or ask an organisation owner to offer yours again. Your saved
choice applies again the next time the Console loads after the organisation offers it.

**The language changes after you sign in**

After sign-in, the Console uses the language saved on your account, which comes before the sign-in screen's language.
Select the language you want from the account menu to save a new one.

**An investor gets emails in English**

The investor has no saved language, or the organisation does not offer the saved one. Ask the investor to select their
language in the Investor portal account menu while signed in, and check that the organisation offers it.

**The language checkboxes are unavailable**

The checkboxes are unavailable while a save runs. When they stay unavailable, your role cannot change organisation
settings in the Console, and the page header shows "Organisation owners manage these settings." Ask an organisation
owner to make the change.

**A language change does not save**

The row shows the reason the platform gives, or "The languages could not be saved" when it gives none. The checkboxes
keep the languages that were stored before. Reload the page to load the current languages and your current role, then
try again.

**Some text stays in English**

Names and descriptions your organisation typed show as typed. A text that comes with the platform and has no
translation in your language shows in English, and so do the Why and What to do next texts of a refused transaction
when the Console has no text of its own for that refusal.

**The sign-in screen offers a language the organisation turned off**

Before sign-in there is no organisation, so the sign-in screens offer all ten languages. After sign-in, the language
menu offers only the organisation's languages, and a choice outside them becomes English.

## API routes [#api-routes]

The [Platform API](https://docs.settlemint.com/docs/api-reference/v2) gives access to the same settings:

- `GET /api/v2/users/me` returns your saved language as `language`, or `null` when you never selected one.
- `PATCH /api/v2/users/me` with a body such as `{ "language": "ar-SA" }` saves your language. Any signed-in user can set their own.
- `GET /api/v2/settings/enabled-languages` returns the organisation's `languages` and their `source`. The `source` is `organization` when the organisation saved a list, and `default` when it never saved one. With `default`, `languages` holds all ten. The route needs no sign-in, and without a signed-in organisation it returns all ten.
- `POST /api/v2/settings` with the key `ENABLED_LANGUAGES` saves the organisation's set. The value is the list as JSON text, such as `"[\"en-US\",\"ar-SA\"]"`. The platform refuses a list that leaves out `en-US`, names a language twice, or names a code outside the ten. The route accepts an organisation owner or a platform administrator.

[Error handling](https://docs.settlemint.com/docs/api-reference/errors) explains the response to a refused request.


# Networks

Source: https://docs.settlemint.com/docs/console/organisation-settings/networks
Turn on multi-network support for an organisation, add networks from the platform catalogue, follow each network's deployment, and create its bundler wallet.

Networks lets an organisation work on more than one network. An owner turns on multi-network support, adds a network from the platform's catalogue, and the platform deploys the organisation's system on that network and shows its progress. A platform administrator curates the catalogue and its node connections for the DALP Instance on [Platform networks](https://docs.settlemint.com/docs/console/platform-admin/networks).

Every organisation starts with one network. [Onboarding](https://docs.settlemint.com/docs/getting-started/onboarding) offers a choice when a platform administrator has turned on **Offer network choice at onboarding**, and otherwise starts the organisation on the default network. That first network is the organisation's default network and does not change.

The organisation holds one system per network: the registries, permissions and compliance rules it deploys there. Members and organisation settings stay shared across all of its networks.

On-chain roles do not: the deployment grants the Permission manager, System manager, Asset manager, Compliance manager, Verification policy manager, Identity manager and Verification issuer roles on the new system to the wallets of the person who added the network, and every other member's roles there are granted on [Roles and permissions](https://docs.settlemint.com/docs/console/organisation-settings/admins-and-roles).

Turning on multi-network support does not deploy anything. Adding a network starts a deployment.

![Organisation networks page with the multi-network support row and the Your networks table](https://docs.settlemint.com/docs/screenshots/console-organisation-networks.light.en.webp)

[Screenshot] The "Networks" heading with the "Add network" button, the "Multi-network support" row with its value and its "Turn on" or "Turn off" button, and the "Your networks" table listing each network with its status, chain ID and bundler wallet.

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

- You need to be an organisation owner or a platform administrator. For everyone else, the sidebar does not list Networks, and opening the page directly shows "This page isn't available for your account or organisation." The server applies the same rule to every change on this page and refuses other callers with [DALP-9167](https://docs.settlemint.com/docs/api-reference/errors).
- To add a network, the network must be enabled in the platform catalogue, and its system factory, the contract that creates an organisation's system on that network, must be in place. You also need a way to sign on that network: an active, eligible primary managed custody account of your own there, or a managed custody provider of the organisation that is enabled, healthy and covers the network. [Custody](https://docs.settlemint.com/docs/console/organisation-settings/custody) covers provider coverage.

## Steps [#steps]

### Turn on multi-network support [#turn-on-multi-network-support]

On the "Multi-network support" row, which reads "Deploy your organisation to networks beyond its default network.", select **Turn on**. The change applies at once, the Console confirms "Multi-network support turned on", and the toast offers "Undo" for a few seconds. A later change to the setting, including "Undo", replaces that toast, so only the latest outcome shows. Until support is on, the page reads "Turn on multi-network support first." under the title, and "Add network" stays disabled.

### Add a network [#add-a-network]

Adding a network starts the deployment at once, and there is no draft to come back to. Select **Add network**. The "Add a network" dialog reads "Choose a network enabled for this deployment. Deployment starts immediately and you can watch its progress here." Choose a network in "Network", which opens as "Select a network", then select "Add network". The Console confirms "Network deployment started".

The picker lists the enabled catalogue networks the organisation has not added, other than its default network, for which you have a way to sign. When it lists none, the dialog reads "No additional networks available yet" and "Only networks your current custody coverage supports can be added." A hint under the field reads "Networks need an eligible custody account or a healthy managed provider. Add network coverage in Custody." and links to [Custody](https://docs.settlemint.com/docs/console/organisation-settings/custody).

The new system uses the organisation's stored default currency, currencies and wallet kind. An owner sets who pays gas on that network on [Transaction funding](https://docs.settlemint.com/docs/console/organisation-settings/transaction-funding).

### Follow the deployment [#follow-the-deployment]

A network moves from "Pending" to "Deploying" to "Active". While it deploys, a panel before the table shows its steps. The deployment runs on the server, so leaving the page does not stop it, and the page shows the reached state when you come back. [Network states](#network-states) shows the path.

Only one network deployment runs at a time for an organisation. Wait for it to finish before you add another.

## Retry a failed deployment [#retry-a-failed-deployment]

When a deployment does not finish, the row reads "Failed", and a notice before the table reads "Deployment to" and the network's name and "failed". Its description is the failure reason, or "The deployment did not finish. Open the row for the steps that failed." when there is none. Open the row to see the steps that failed. Select **Try again** on the notice. The retry starts a new attempt for that network, which returns the row to "Pending". It is refused like an add while another network deployment runs.

## Create the bundler wallet [#create-the-bundler-wallet]

The bundler wallet submits smart-account requests on a network. The deployment creates it, and its address shows in the "Bundler wallet" column once the network is "Active". When an active row has no bundler wallet, owners and platform administrators see **Create bundler wallet** on it.

Selecting it creates the wallet, or reuses the one that exists, and the row then reads "Bundler wallet created" or "Bundler wallet already exists". It also reports the funding state: "The wallet is funded." or "The wallet needs funds. A funding request is open." On a network that charges gas, a balance below the wallet's top-up level opens a funding request for that level, which you settle on [Transaction funding](https://docs.settlemint.com/docs/console/organisation-settings/transaction-funding). The level comes from the network's live fee quote. When the network has no fresh fee quote, or the request cannot be recorded, the action fails and you can select it again later.

Creating it needs your wallet to hold the "Permission manager" role on that network's system. A refusal shows "Bundler wallet not created" with the reason, such as "Account abstraction is turned off for this deployment."

## Turn off multi-network support [#turn-off-multi-network-support]

Select **Turn off** on the "Multi-network support" row. The organisation then works on its default network only. While any network other than the default is "Pending", "Deploying" or "Active", the button is disabled and the row says which network keeps support on. An "Active" network reads, for example, "local2 is added and in use, so multi-network support stays on. Turning it off first needs that network removed, and removing a network is not available yet."

When every blocking network is still "Pending" or "Deploying", the row reads, for example, "local2 is still being added, so multi-network support stays on. Turn off becomes available once that network finishes deploying or fails." When both kinds block, the row names only the active networks. The server refuses the change with [DALP-9169](https://docs.settlemint.com/docs/api-reference/errors), naming the networks that block it. A "Failed" or "Disabled" network does not block it. This page has no control to remove a network once it is added, so an active added network keeps support on.

## Read a network's details [#read-a-networks-details]

The **Your networks** table has the columns "Network", "Status", "Chain ID" and "Bundler wallet". The default network is marked "Default" beside its name. The toolbar has "Search networks…", a "Status" filter with "Active", "Pending", "Deploying", "Failed" and "Disabled", and the view options. An empty table reads "No networks yet". A failed read reads "The networks could not be loaded." with "Check your connection and try again."

Open a row to see its facts: "System", the system address, "Native currency", and "Explorer", a link to the explorer's host. A network with none of these reads "No more details for this network yet". A "Failed" row opens the deployment steps instead.

## Network states [#network-states]

[Figure] How an added network moves through its states. Adding a network starts it at Pending. It moves to Deploying and then to Active when the deployment finishes. A deployment that does not finish moves the network to Failed. Try again on a failed network starts a new attempt at Pending. Pending, Deploying and Active networks other than the default block turning multi-network support off. A failed network does not. Labels: Add network; starts a deployment; Pending; blocks turning off; Deploying; blocks turning off; Active; blocks turning off; Failed; does not block; does not finish; Try again: new attempt.

An added network moves from "Pending" to "Deploying" to "Active", and "Try again" restarts a "Failed" one at "Pending".

## Stay on one network or use several [#stay-on-one-network-or-use-several]

**Stay on one network**

Assets deploy on one network, and there is one set of transaction history to reconcile. Choose this when every participant uses the same network.



**Turn on multi-network support**

The organisation adds systems on further networks, and members switch the network the Console works on. Each asset lives on the network where it was issued, and the organisation tracks activity on each network separately. Choose this when participants need different networks.

## Two switches with similar names [#two-switches-with-similar-names]

Two separate settings decide whether an organisation can use more than one network. Their names differ only in letter case. Setting one does not set the other.

| Switch | Scope | Who sets it | What it gates |
| --- | --- | --- | --- |
| `multi_network_enabled` | The whole platform. Read as `meta.onboardingNetworkChoice` at `GET /api/v2/admin/networks`. | A platform administrator, with the **Offer network choice at onboarding** switch on **Platform networks**. | The network that a new organisation's first system can deploy to. When the setting is off, a new organisation can deploy only on the platform default network. |
| `MULTI_NETWORK_ENABLED` | One organisation. Read at `GET /api/v2/settings/MULTI_NETWORK_ENABLED`. | An organisation owner or a platform administrator, when they select **Turn on** here. | Everything after onboarding: the **Add network** action, the Network submenu in each member's account menu, and requests that name a non-default network. |

The platform setting decides which networks the platform lets an organisation start on. The organisation switch decides whether that organisation adds and uses networks beyond its default.

### Set them in this order [#set-them-in-this-order]

1. Set the platform setting first, and only if the first system of a new organisation must deploy to a network that is not the platform default. A platform administrator turns on **Offer network choice at onboarding** on "Platform networks" before that organisation completes onboarding.
2. Complete onboarding. The organisation picks its first network, and that network becomes its default.
3. Set the organisation switch after onboarding. An owner or a platform administrator selects **Turn on** in the "Multi-network support" row. Then add each further network with "Add network".

Skip step 1 when the organisation starts on the platform default network. Adding a network after onboarding needs only the organisation switch. The platform setting never replaces step 3.

Note (The platform setting does not enable the organisation switch): If only `multi_network_enabled` is set, this page still shows the "Multi-network support" row as "Off" with its "Turn on" button, and "Add network" stays unavailable. Select **Turn on**. A platform administrator can do this in any organisation they are a member of. The platform setting is not a substitute for that switch.

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

- The row of the added network reads **Active**.
- When the organisation has more than one active network, the account menu at the top right shows a Network submenu that lists them.
- Members switch to a network from that submenu, and every Console read follows the selected network.

## Troubleshooting [#troubleshooting]

**The page shows Off, although the platform offers a network choice at onboarding**

The platform setting `multi_network_enabled` and the organisation setting `MULTI_NETWORK_ENABLED` are separate. The
organisation setting stays off until an owner or a platform administrator selects **Turn on**. Read it at `GET
/api/v2/settings/MULTI_NETWORK_ENABLED` to see the value for the active organisation.

**A network is missing from the picker**

The picker lists only enabled catalogue networks that the organisation has not added and that you can sign on. Ask a
platform administrator to confirm the network is enabled on [Platform
networks](https://docs.settlemint.com/docs/console/platform-admin/networks). If it is, check custody coverage: the picker needs an active,
eligible primary managed custody account of yours on that network, or a healthy managed custody provider of the
organisation that covers it.

**The dialog refuses to add a network**

  The dialog shows one of four messages:

- "This network is already part of your organisation." covers a network the organisation has added, including a row
  that reads "Disabled".
- "This network is still being set up. Wait for the deployment to finish, then check its status." means its setup is
  "Pending" or "Deploying".
- "This is your organisation's default network and cannot be added again." names the default network.
- "This network is not enabled for your deployment. Choose another network." means the platform catalogue does not
  offer it.

The server returns [DALP-14111](https://docs.settlemint.com/docs/api-reference/errors) with the network and a reason: `already-added`, `deploying`, `default-network` or `not-enabled`.

**Adding a network is refused because another deployment is running**

Only one network deployment runs at a time per organisation. The server refuses a second one with
[DALP-14357](https://docs.settlemint.com/docs/api-reference/errors). Wait for the running deployment to reach "Active" or "Failed", then add the
network.

**Adding a network is refused because no custody provider covers it**

The server refuses with [DALP-14069](https://docs.settlemint.com/docs/api-reference/errors) when you hold no usable managed account on the
network and no healthy managed custody provider of the organisation covers it. The dialog reads **No custody provider
can open an account on this network.** under the Custody hint. On
[Custody](https://docs.settlemint.com/docs/console/organisation-settings/custody), add the network's EVM chain ID to a provider, enable account
creation, or restore the provider's health, then add the network again. Adding coverage keeps the provider's existing
networks.

**Adding a network is refused because the network has no system factory**

The network is in the catalogue, but the contract that creates an organisation's system is not deployed on it. The
server refuses with [DALP-14308](https://docs.settlemint.com/docs/api-reference/errors). Ask a platform administrator to prepare the network.

**Adding a network is refused because your account cannot sign there**

Your custody account on that network cannot send the deployment, for example because it no longer exists. The server
refuses with [DALP-14321](https://docs.settlemint.com/docs/api-reference/errors). Check your custody account and the organisation's provider for
that network, then add it again.

**A member cannot select a network you added**

The Network submenu of the account menu shows only when multi-network support is on and the organisation has more than
one active network. Check that the added network reads **Active**. A network that is "Pending", "Deploying" or
"Failed" is not offered.

## Frequently asked questions [#frequently-asked-questions]

### Does turning multi-network support on or off change the default network?

No. The default network is fixed at onboarding. Turning support on adds networks next to it, and turning it off limits the organisation to the default network.

### Can I remove a network once it is added?

No. This page has no control to remove a network. **Try again** on a failed network starts a new deployment attempt for that same network. A platform administrator manages which networks the platform offers on [Platform networks](https://docs.settlemint.com/docs/console/platform-admin/networks).

## API routes [#api-routes]

Over the API, a request names its network in the `X-Chain-Id` header. A request without the header acts on the organisation's default network. A header that is not a whole number in range is refused with [DALP-9084](https://docs.settlemint.com/docs/api-reference/errors), `CHAIN_ID_HEADER_INVALID`. A request for a network the organisation cannot use is refused with the reason, never sent to another network:

- With multi-network support off, a request for any network other than the default is refused with [DALP-9085](https://docs.settlemint.com/docs/api-reference/errors), `CHAIN_NOT_AVAILABLE_FOR_ORGANIZATION`.
- A request for an added network whose status is anything other than **Active** is refused with [DALP-9086](https://docs.settlemint.com/docs/api-reference/errors), `CHAIN_NOT_READY`, which carries the network's status.
- A request for a network the organisation has not added is refused with [DALP-9085](https://docs.settlemint.com/docs/api-reference/errors).

An organisation that existed before multi-network support keeps its system as its default network. Nothing changes for it until an owner turns support on. The organisation switch is read at `GET /api/v2/settings/MULTI_NETWORK_ENABLED`, and the platform setting at `GET /api/v2/admin/networks`, as `meta.onboardingNetworkChoice`.


# Transactions

Source: https://docs.settlemint.com/docs/console/organisation-settings/platform-status-transactions
Find a transaction on Platform status, read its queue and on-chain detail, and recover a stuck one with force fail, force retry or set next nonce.

The Transactions view of Platform status lists the transactions the platform submitted, with their state in the queue and on the chain, and is where an operator recovers a stuck one. Open it when the Transactions panel on [Platform status](https://docs.settlemint.com/docs/console/organisation-settings/platform-status) is degraded, or when one transaction does not go through.

Selecting a row opens the **Transaction detail** sheet with the queue state, the on-chain detail, the error and the receipt. Its "Operator actions" change the transaction, so each one needs a reason, which the platform stores with the action.

![Platform status Transactions view with the Search transactions box, the Status filter and a table with Operation, Time, Status and Chain columns](https://docs.settlemint.com/docs/screenshots/console-organisation-platform-status-transactions.light.en.webp)

[Screenshot] The "Transactions" view under "Platform status", with the "Search transactions…" box and the "Status" filter above a table with the columns "Operation", "Time", "Status" and "Chain".

Each row shows the operation name with the sending address under it. The "From" and "Tx hash" columns are hidden, and "View" adds them back along with the gas and timing columns.

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

- The platform accepts an action only for a transaction sent from, or recorded for, your organisation's wallets.
- A platform administrator can run these actions on the transactions of any organisation they are a member of.
- None of the three actions asks for wallet verification.
- Decide the reason you will record before you open the action.

## Steps [#steps]

### Open the Transactions view [#open-the-transactions-view]

On [Platform status](https://docs.settlemint.com/docs/console/organisation-settings/platform-status), select **Details** on the "Transactions" panel. Select "Platform status" in the breadcrumb to return.

### Find the transaction [#find-the-transaction]

The table lists each transaction with "Operation", "Time", "Status" and "Chain". "From", "Tx hash" and more columns are hidden until you add them with **View**: "Transaction ID", "Nonce", "Gas price (wei)", "Gas used", "Effective gas price (wei)", "Block", "Processing time (s)", "Last updated" and "Trace ID".

Use **Search transactions…** to narrow the list, then select the row.

"Status" reads the transaction's state in the queue, such as "Queued", "Confirming", "Completed", "Failed" or "Stopped after retries".

### Export the transactions [#export-the-transactions]

Use this to compare what transactions cost and how fast they settle across networks, for example a test network against production.

1. Narrow the list with **Search transactions…** and the filters, if you want only some transactions.
2. Select "Export", then **Export as CSV**.

The file holds every transaction that matches the search and filters, not only the page on screen, and every column, including the ones "View" hides. The Console reads the list page by page, so a long list takes a moment and **Export** shows how far it has got. If transactions arrive while it reads, the export stops with a message that the rows changed. Run it again.

The file only holds transactions your organisation can see here. Its gas and timing columns read as follows:

- **Gas price (wei)** is the price the platform set when it signed the transaction.
- **Gas used**, "Effective gas price (wei)" and "Block" come from the receipt, so they stay empty until the transaction is mined.
- **Processing time (s)** is the time from the request arriving to its last update, and stays empty while the transaction is still moving.

### Read the transaction detail [#read-the-transaction-detail]

The **Transaction detail** sheet has these sections:

- **Queue** shows the "Status", "Sub-status", "Kind", "Operation", "Transaction ID", "From", "Chain", "Created" and "Updated".
- **On-chain** shows the "Transaction hash", "Nonce", "Gas price", "Confirmation checks" and "Trace ID". For a transaction its own wallet signed, "Nonce" is the nonce the transaction was sent with, shown once it is broadcast. For a smart-wallet transaction, it is the sequence of the wallet's user operation on its nonce lane. A transaction a relayer or the custody provider sent for the sender shows a dash, because the sender's nonce is not the one that transaction used.
- **Receipt** shows the "Outcome", "Block", "To", "Gas used" and "Effective gas price" once the transaction is mined. Before that it reads "No receipt yet. It appears once the transaction is mined." or, with no hash, "No transaction hash yet, so there is no receipt." A failed read shows "The receipt could not be read."
- **Error** appears when the platform recorded an error for the transaction, below "Operator actions". It shows "Failure reason", "Error", "Revert reason", "Contract error code" and "Revert data" where each is set. "Failure reason" names the contract error and its arguments when the platform recognises it, or gives the stored message when it does not. "Revert data" holds the raw value, with a copy button, for support or a block explorer.

### Recover a stuck transaction [#recover-a-stuck-transaction]

The **Operator actions** card reads "Recover a stuck request. Each action is recorded with your reason." For a completed or cancelled request it reads "This request has finished, so no action applies." An open request offers "Force fail" and "Set next nonce", a failed one offers "Force retry", and a dead-lettered one, "Stopped after retries", offers "Force fail" and "Force retry". Each action needs a "Reason":

- **Force fail** ends a transaction that has not finished, or a dead-lettered one, and marks it failed. It releases the request's nonce. On a dead-lettered transaction it refuses while the chain, the bundler or the custody provider shows that the call can still land, and the sheet shows the reason. It also refuses a paymaster-sponsored transaction whose operation is still with the bundler, because that operation can still run on chain. Such a transaction ends on its own when the bundler settles the operation. A toast confirms "Request marked failed."
- **Force retry** puts a failed or dead-lettered transaction back on the queue. Enter "Gas price in wei (optional)" to replace a stuck transaction, or leave it empty. A toast confirms "Request queued again."
- **Set next nonce** moves the sender's next nonce to the number you enter in "Next nonce". Use it to clear a nonce gap. Submit with "Set nonce". A toast confirms "Next nonce updated."

When the platform refuses an action, the sheet shows the platform's reason and stays open. A request that has left the queue reads "This request is no longer in the queue, so nothing changed. Reload the list to see its current state." When it accepts, the sheet closes and the list refreshes.

Note (Check the evidence before you force a transaction): A force action overrides the platform's own settling. Confirm on the chain, with the bundler or with the custody provider that the call cannot still land, and record that in the reason.

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

- Reopen the transaction. After "Force fail", its **Status** reads "Failed".
- After "Force retry", it returns to the queue and moves on to "Completed", or fails again with a new "Failure reason".
- After "Set next nonce", the sender's following transactions leave the nonce gap.

## Troubleshooting [#troubleshooting]

**“Force fail” is refused**

The sheet shows the reason. A dead-lettered transaction is refused while the chain, the bundler or the custody
provider shows that the call can still land. When the reason asks you to check the transaction that took the nonce,
repeat the force-fail through the API. Set `takerHash` to the hash of that transaction. Set `takerChecked` to
`other-call` to fail the request, or to `same-call` to keep it dead-lettered until the sweep settles it from that
receipt.

**“Force retry” is refused with DALP-200383**

Platform status does not show `mayStillLand`. The Submissions tray shows such a request as "May still go through" to
the person who submitted it. Read it with `GET /api/v2/transaction-requests/{transactionId}` first. For an unreserved
dead letter that may still land, the server refuses the retry with `DALP-200383`. The Console cannot send an
attestation that the original call was stopped. After independently confirming the stop, with the provider for custody
calls, an operator can use the API with `custodianStopped: true` when the chain does not show the call and no nonce
reservation or recorded submitted nonce remains. DALP records this operator attestation. It does not verify the stop.
This never overrides a visible call, an unresolved nonce slot or the checks on a signed nonce reservation. Force retry
also refuses a step of a role set. Send a new role set to repeat the change.

## API routes [#api-routes]

The Console lists transactions with `GET /api/v2/platform-status/transactions-list` and runs each operator action with `POST /api/v2/transaction-requests/{transactionId}/transitions`. An API key of an organisation owner or a platform administrator can call both. `GET /api/v2/transaction-requests/{transactionId}` returns a request's state, including `mayStillLand`. Through the transitions route, force fail also takes `takerHash` and `takerChecked`, and force retry takes `custodianStopped`. The Console sends none of them. See the [Platform API reference](https://docs.settlemint.com/docs/api-reference/v2).


# Platform status

Source: https://docs.settlemint.com/docs/console/organisation-settings/platform-status
Review live platform health across its service areas and outbound deliveries, plus the figures and history behind them.

Platform status reports the health of the platform's service areas and outbound deliveries, with the figures and the history behind each verdict. Use it to identify the service that needs investigation. The page only reads. The actions that recover a stuck transaction are on the [Transactions](https://docs.settlemint.com/docs/console/organisation-settings/platform-status-transactions) detail view.

Check this page first when something elsewhere in the Console looks wrong, to see whether a platform area is degraded. A green page does not rule out a fault in one operation. For a SettleMint-hosted environment, the public [SettleMint status page](https://status.settlemint.com/) reports platform-wide availability and incident history outside the Console. Use this page for this deployment's telemetry. Use the status page when you need SettleMint's published service status. The [SettleMint Trust Centre](https://trust.settlemint.com/) publishes SettleMint's security and compliance documentation.

![Platform status page with the overall status badge and a card for each service area](https://docs.settlemint.com/docs/screenshots/console-organisation-platform-status.light.en.webp)

[Screenshot] The "Platform status" page with the "All systems operational" badge.

Each service area has a card: "Data freshness", "Transactions", "Platform API", "Workflows", "Webhooks" and "Email". Each card shows a status bar, figures for the last 24 hours and a "Details" link to a detail view.

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

- You need to be an organisation owner or a platform administrator.
- The check runs every time the page loads, rather than once when you first navigate to it.
- Holding the System manager or Permission manager role does not open the page.
- The same rule applies to every detail view: Data freshness, Platform API, Transactions, Workflows, Webhooks, Email, FIX sessions, Batch jobs, and Scheduled jobs.
- A person who does not pass it sees no sidebar entry, and the page reads "You are not authorized to view platform status." if they open its address.

## Steps [#steps]

### Read the overall status [#read-the-overall-status]

The header shows the overall status pill, the **Version** of the running platform, and, when your deployment sets a Grafana address, a "Dashboards" link that opens it in a new tab. [How the overall status is chosen](#how-the-overall-status-is-chosen) explains the pill. While the status loads it reads "Computing overall status…". If the read fails, it reads "Status unavailable" with "All status panels failed to load." and a "Try again" button. A line under the pill reads "No data from" and the areas that have nothing to report.

### Resolve held bundles [#resolve-held-bundles]

When the custody provider holds bundles, a notice above the panels reads "1 bundle waits at the custody provider", and the number changes with the count. With none held, the notice does not show. An approval rule at the custody provider holds these bundles, so every user operation in them waits.

The notice lists the "Provider", the "Reference", the "Chain" and "Held for" of each bundle. "Provider" names the provider the custody configuration was added as, such as "IBM Digital Asset Haven". Select **Copy the provider reference** to copy the reference, open the request at the custody provider by that reference, and approve or reject it there.

The notice shows the oldest bundles and reads "This list shows the 20 oldest of 25 held bundles." when more are held. If the list cannot be read it says "The held bundles did not load. A bundle the custody provider holds may be missing from this page."

### Open the panel that is not operational [#open-the-panel-that-is-not-operational]

Each area is a panel with a verdict badge, a 24-hour trend and its figures. A panel says what its trouble costs only while it is degraded or in an outage. Select a panel's **Details** link to open its detail view, then read its status and recent signals to decide what to check next. To recover a stuck transaction, open "Transactions" and follow [Platform status transactions](https://docs.settlemint.com/docs/console/organisation-settings/platform-status-transactions). [Panels and figures](#panels-and-figures) lists what each panel counts.

### Read the history [#read-the-history]

Below the panels, the **30-day history** grid reads "Status by UTC hour for the last completed days. Short incidents color only the hours affected." Hover a cell to see its date, UTC hour range and verdict. Use the grid to tell a brief incident from one that ran all day, and whether the latest signal is a one-off blip or part of a growing trend. While the history loads, and when no hour has data, the grid keeps the same size and the legend still lists every verdict. Hours with no data read "No data".

Note (Check service health alongside the failed operation): A degraded service can explain failures elsewhere, but it does not establish the cause of every failed operation. Record the affected service and inspect the operation's own error or transaction state before retrying. Escalate a service incident with both sets of evidence.

## How the overall status is chosen [#how-the-overall-status-is-chosen]

The Platform Health summary uses the worst verdict across the four core areas. Webhooks, when you can manage webhooks, and Email, FIX sessions, Batch jobs and Scheduled jobs join it only while they are degraded or in an outage. One degraded area makes the summary amber, even if the others are healthy.

| Area | What it shows | Open it when |
| --- | --- | --- |
| Data freshness | How many of the platform's chains the indexer is keeping in sync, how long it was unhealthy in the last 24 hours, and the current delay behind the chain tip | Indexed data such as balances, transaction history and feed values looks out of date |
| Transactions | Submitted and failed transactions in the last 24 hours, and RPC health | A transaction is not going through |
| Platform API | Request volume and 4xx and 5xx error rates | The Console itself feels slow or throws unexpected errors |
| Workflows | Completed and stalled counts for background processing | A task that should finish in the background (a migration, a scheduled job) seems stuck |

The header pill and the panel badges use different words for the same four verdicts:

| Verdict rank | Header pill | Panel badge |
| --- | --- | --- |
| 0, lowest | **No data yet** | **No data** |
| 1 | **All systems operational** | **Operational** |
| 2 | **Degraded service** | **Degraded** |
| 3, highest | **Service disruption** | **Outage** |

The header shows the highest rank among the areas that answered. An area that reads "No data" contributes no verdict, but it is never read as healthy: "All systems operational" appears only when every area answered with a measured verdict. When the measured areas are all operational and at least one area has nothing to report, the header reads **Partially reporting** in grey instead, and a line under it names the areas with no data. A degraded or outage verdict elsewhere still shows its own colour and label, with the same line naming the silent areas beneath it.

## Panels and figures [#panels-and-figures]

Every figure covers the "Last 24 hours" and appears once, in the panel of its service. "Delay now" is the current reading, not an aggregate. "Indexer head" is a running total across every connected chain. A panel with nothing to measure shows a dash for each figure. Data freshness, Transactions, Platform API and Workflows load from one read. If that read fails, all four show an error and a **Try again** button. That state means the page could not reach the platform, not that the platform has no data. The other panels load on their own. While a panel loads, it shows its outline: the same bars, legend and figure rows, so nothing moves when the figures arrive.

The Webhooks panel reads its bars, its "Delivered" and "Success" figures, and its "Failing endpoints" figure separately. When one read fails, the panel keeps what the others returned and marks only the figures that read feeds with a dash and "Unable to load this section". When the bars read fails, the panel shows an error and a **Try again** button where the bars would be.

| Panel | Figures |
| --- | --- |
| Data freshness | **Chains in sync**, **Delay now**, **Queryable data behind** (only when reported), **Indexer head** and **Unhealthy, last 24h** |
| Transactions | **Submitted** and **Failed** |
| Platform API | **Requests**, **4xx rate** and **5xx rate** |
| Workflows | **Completed**, **Stalled**, **Stall rate per completion**, **Success rate** and **Completion time (p95)** |
| Webhooks | **Delivered**, **Success** and **Failing endpoints** |
| Email | **Emails sent**, **Emails failed** and **Average send time** |
| FIX sessions | **FIX attempts**, **FIX failures** and **Average FIX time** |
| Batch jobs | **Batch runs**, **Failed batch runs** and **Average batch run** |
| Scheduled jobs | **Scheduled runs**, **Failed scheduled runs** and **Average scheduled run** |

The Workflows figures describe volume and throughput, and they can look strong while the panel reports degraded. A degraded Workflows verdict means work completes slowly. An outage means it does not complete.

The Webhooks detail page also counts the events queued or waiting to retry across every endpoint, up to 10,000 (a count at the ceiling reads "10,000+"), shows how long ago the oldest of them was queued, and ranks the last 24 hours' failures by class.

## Outbound panels [#outbound-panels]

The Email, FIX sessions, Batch jobs, and Scheduled jobs panels count every attempt the platform makes to reach something outside it: an email handed to the mail server, a FIX logon or message sent to a counterparty, a document generated in the background, or a run of a scheduled job.

They use the same rule as the transaction failure verdict: with 20 or more attempts in the last 24 hours, failures on one in twenty make the panel degraded and failures on half make it an outage. With fewer attempts, any failure makes it degraded and three make it an outage. The header counts these panels only when one is degraded or in an outage.

A platform administrator also sees attempts that belong to no organisation, such as scheduled jobs.

Each of these panels opens a detail view with an hourly chart of succeeded and failed attempts, a table of the sources behind the area (the email template, the FIX session, the job), and the most recent failures with their reason code. A reason is a short code such as the mail server's reply code or the FIX reject reason, never an address, a message text, or document content. Both tables export to CSV.

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

- Confirm that the selected detail view identifies the affected area and its current state.
- No saved setting exists to check here: verifying means the signal matches what you already know is happening, or points you at the service that needs attention next.

## Troubleshooting [#troubleshooting]

**Platform status is not in the sidebar**

The entry shows only to an organisation owner or a platform administrator. Ask one of them to open it, or to make you
an organisation owner.

**A signal looks stale**

Each read on this page is cached for 30 seconds. The four core panels and the Transactions and Workflows detail lists
refresh when a new health sample arrives. Reload the page to refresh the other areas. **Completion time (p95)** is
recomputed about every 5 minutes, so it can trail the other Workflows figures by about 5 minutes.

**A notice says bundles wait at the custody provider**

An approval rule at the custody provider holds each listed bundle. Open the request at the custody provider by its
reference and approve or reject it there. A held bundle is a fault in the provider's rules for the bundler wallets,
not a step a user must take, so it never appears in a user's Actions. See [Resolve held
bundles](#resolve-held-bundles).

**Data freshness says indexer telemetry is not arriving**

At least one chain registered for indexer health has no current sample. A sample older than three of its own collector
ticks no longer counts as current, so the area stops showing the last verdict it saw and reads No data instead, even
when the other chains are healthy. This is a fault in the health collector, not proof that the indexer is healthy or
down: check whether indexed data elsewhere in the Console is current, and treat it as a monitoring outage until
samples return.

**Data freshness shows chains out of sync**

The verdict comes from each network's latest indexer sample, and the tile's first line names the reason. Degraded
means the indexer is 10 or more blocks behind the chain tip, is ahead of the tip it was checked against, or has
indexed no new block for 5 minutes while blocks wait. Outage means it is more than 100 blocks behind, or has indexed
no new block for 15 minutes while blocks wait. An indexer at the chain tip is in sync, however long the chain has gone
without a new block. A chain that stops producing blocks shows under Transactions. While a chain is out of sync,
anything reading indexed data (balances, transaction history, feed values) reflects an older state than what is
on-chain. Open the data freshness detail view to see the current delay and how long it was unhealthy before assuming a
specific balance or history view elsewhere in the Console is wrong.

**Workflows shows a stalled count above zero**

A stalled workflow is background work that started in the last 24 hours but has not progressed, distinct from one that
failed outright. The count covers the same day as the completed count it is compared with, so a status row left
running long ago cannot keep the area in outage. Open the workflows detail view to see which one is stuck. It still
lists older runs that never finished. A growing stalled count or work that exceeds its expected processing time
requires investigation.

**The header reads “Status unavailable” instead of a verdict**

This means none of the four areas answered the page's own query, a failed page load, not a platform verdict. A real
degraded or outage state still shows its own colour and label instead. Try again reloads the status read, the held
bundles and the history. If Try again keeps failing, check your own connection or session before assuming the platform
is down.

**An area reads “No data yet”**

The area has no current telemetry: either it has not produced any yet, most often right after it first comes online,
or its collector stopped. It never outranks a real degraded or outage state sitting elsewhere, and it never lets the
header read "All systems operational". The header names it under the verdict instead. If it does not clear after a
normal refresh, treat it as a stale signal.

## Frequently asked questions [#frequently-asked-questions]

### If Data freshness shows a delay, does that mean a transaction of mine failed or is missing?

No. Data freshness reports how far the indexer that feeds the Console's reads (balances, transaction history, feed values) sits behind the chain tip. It says nothing about whether a submission reached the chain. A transaction that already confirmed on-chain can still look briefly missing here if the indexer has not caught up yet. Check Transactions instead for submission and confirmation health.

### Why does the header briefly read "Computing overall status…" in grey?

The header reads "Computing overall status…" until the status read answers. A normal page load or reload passes through this state briefly, so it is not a sign that anything is wrong. If it does not clear, reload the page. If the read fails, the header reads "Status unavailable" and offers Try again.


# Price sources

Source: https://docs.settlemint.com/docs/console/organisation-settings/price-sources
Connect a provider's prices to token price feeds by ISIN, see the checks a price passes before it is published, decide held prices and act on a stale feed.

A price source connects one price provider, such as a custodian's end-of-day file, a market-data vendor or a trading counterparty, to the price feeds of your tokens. The platform fetches the provider's prices, checks each one, and publishes the prices that pass to the token's price feed.

The organisation's operations signer, the custody account the platform uses to sign on the organisation's behalf, signs each published price. Use this page to add a source, map its instruments, decide held prices and act when a feed goes stale.

Use [Token pricing](https://docs.settlemint.com/docs/console/asset-management/manage/token-pricing) to set a price by hand, and [Data feeds](https://docs.settlemint.com/docs/console/organisation-settings/data-feeds) for feed registration and staleness windows.

A source works with ISINs. An ISIN, short for International Securities Identification Number, is the 12-character code that identifies a security. The provider names each price by ISIN, and you map each ISIN to the token whose feed receives the price. A token that has no price feed gets one when you map it, quoted in the mapping's currency.

![Sources tab of Data feeds with the list of price sources](https://docs.settlemint.com/docs/screenshots/console-data-feeds-price-sources.light.en.webp)

[Screenshot] The "Sources" tab lists each source with its protocol, the number of mapped instruments, the time of its last delivery and its status, and an "Add source" button.

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

- You need the "Feeds manager" role to see the "Sources" tab, add a source and manage it. The system needs its feeds directory installed.
- You need your PIN for the steps that save a credential, save settings, trust a host key, map an instrument, activate or resume a source, remove a credential, and approve or reject a held price.
- To decide a held price you need the "Feeds manager" role or the "Governance" role on the token, and you must not be in the group the price excludes.
- Turn the **Prices** approval on in [General](https://docs.settlemint.com/docs/console/organisation-settings/general#approvals) before you activate a source if held prices must be reviewed. [Held prices and the second approver](#held-prices-and-the-second-approver) explains the rule.
- Have the provider's connection details and credential ready. A platform operator prepares the deployment first: the endpoint allow list, a fixed outbound address for Bloomberg and the stale-feed alert, described in [Price source prerequisites](https://docs.settlemint.com/docs/deployment/price-source-prerequisites).

## Steps [#steps]

### Add the source [#add-the-source]

On the "Sources" tab, select **Add source**. It opens the "Add source" page, which reads "Connect a vendor price source. It is saved inactive."

Under **How the source delivers prices**, choose one method:

- **File** for a file on an SFTP server. A file source then asks for its "File format", "CSV" or "ISO 20022 reda.001".
- **FIX** for a FIX market data session.
- **REST** for a vendor request. A vendor request then asks for its "Vendor", "Bloomberg Data License" or "LSEG DataScope Select".

The fields that follow match that choice, in the sections "Source", "Protocol", "Prices", "Credential", "Publishing" and "Timing". [Connection fields](#connection-fields) lists them.

A source keeps its delivery method for its whole life, because its credential and connection fields follow from it. To change the method later, add a new source and map the ISINs again.

These values decide when a price reaches the feed:

- **Publish after a move of (bps)** sets how far a price must move from the last published price before it is published. A basis point, bps, is one hundredth of a percent.
- **Or at least every (hours)** is the heartbeat: a newer price is published after this interval even when it moved less than the threshold. A heartbeat never re-stamps an old price. Leave it empty for no heartbeat.
- **Hold above (percent)** sets how far a price may move before it is held.
- **Expected every (hours)** is how often the provider delivers.
- **Expected lag (hours)** is how long after its observed time a price normally arrives.
- **Stale after (hours)** is the age at which a price counts as stale. It applies only when the feed's staleness window, its own or the global default on Data feeds, is set to never expire.

The heartbeat plus the expected interval plus the expected lag must be shorter than the staleness bound. The bound is the feed's staleness window, its own or the global default, when that window is finite, else "Stale after". Otherwise the form refuses the source with "The heartbeat plus the expected interval plus the expected lag comes to `<total>`, which is not shorter than the `<bound>` staleness bound. Shorten one of them or raise Stale after." The form fills `<total>` and `<bound>` with the two durations. The rule keeps the feed from going stale between two deliveries.

The form refuses a host that is a loopback, private or metadata address, and a FIX session without TLS outside the deployment's endpoint allow list. Use the provider's public host name.

Enter the credential and select **Add source**. A "Confirm the credential" dialog asks for your PIN. The credential is stored in the platform secret store and is never shown again. The source is saved as "Draft".

If the source was saved but the credential was not, the page says "The source was added without its credential". Enter the credential again and select **Save credential**, or select "Open source" and add it there.

### Test the connection [#test-the-connection]

Open the source and select the "Connection" tab. **Test connection** opens a session with the source and checks that it answers. It fetches and publishes nothing. The result says "The source answered" or "The connection failed" with the reason, and names the egress IP address the provider saw, so you can give it to the provider to allow.

For an SFTP source, a host key the server offers that is not trusted yet shows its fingerprint. Compare it with the fingerprint your provider published, select **Trust this host key** only if the two match, and confirm with your PIN.

### Map the instruments [#map-the-instruments]

Open the "Instruments" tab and select **Map instrument**. The sheet asks for five values:

- **ISIN**, the code the provider names the price by.
- **Token**, the token whose feed receives the price.
- **Price field**, the field that holds the price in a delivery.
- **Price basis** is "Per unit" or "Percent of par". "Percent of par" needs the "Par amount", the value one token stands for in the price currency. The token price is then the quoted price times the par amount divided by 100. A quote of 98.50 with a par amount of 1,000 gives a token price of 985.
- **Currency**, the three-letter ISO code of the price currency, such as EUR.

The sheet shows whether the platform creates a feed for the token, the token's face value, and the price per token that the latest delivery of the ISIN would give. Confirm with your PIN. When the source is active and the platform already holds a delivery for the ISIN, that price goes through the checks as the feed's first price. Otherwise the feed waits for the next delivery.

The currency must match the currency of the token's existing price feed, and the platform refuses a different one with [DALP-14712](https://docs.settlemint.com/docs/api-reference/errors). A token whose feed another source already maps cannot be mapped again, and the platform refuses it with [DALP-14710](https://docs.settlemint.com/docs/api-reference/errors). One ISIN can feed several tokens. An active FIX source requests prices for a new mapping within about 10 seconds, and the provider's snapshot then prices the feed.

The table has the columns "ISIN", "Token", "Price field", "Basis", "Currency", "Price", "Last seen" and "Actions". With nothing mapped it reads "No instruments mapped" and "Map an ISIN to a token to publish its price to a feed."

**Unmatched ISINs** lists the ISINs that arrived without a mapping, and "Map" on a row opens the sheet with the ISIN filled in. With none it reads "No unmatched ISINs".

**Unmap** ends a mapping after a confirmation that prices for the ISIN stop reaching the token's feed from this source. The feed keeps its last price, an open held price on that feed is cancelled, and an open stale-feed case for it is resolved.

### Activate the source [#activate-the-source]

Select **Activate** and confirm with your PIN. The source needs a saved credential, or the page says "Add a credential on the Connection tab to activate." After activation, the source fetches on its schedule and publishes the prices that pass the checks.

If a mapped token has nobody who can approve a held price, a callout says "Some tokens have no one who can approve a held price" and names the tokens. Grant the "Feeds manager" role to another person, or the "Governance" role on the token, before a price is held. Without one, a held price waits with nobody able to decide it.

## Decide a held price [#decide-a-held-price]

A held price appears in two places. The **Held prices** tab of the source lists it, with the number of open held prices in the tab label and the columns "Instrument", "Last published", "Received" and "Reason". With none it reads "No held prices".

The **Actions** page shows a row that names the ISIN and the source, with "Review held price", for each price you may decide. A held price with nobody eligible to decide it reads "No one can approve this yet".

Open it to see the **Review held price** sheet. It shows the "Source", the "Received price", the "Last published" price, the "Change" against the source's hold tolerance, the "Price field", the "Observed" time and the "Reason held", which reads "Moved past tolerance" or "Correction".

The **Evidence** section shows the record, its sequence number, when it was recorded and the evidence digest, and "Show the raw payload" opens the provider's message.

Compare "Received price" with "Last published" and the "Reason held". Select **Approve** to publish the price, or "Reject" and give a reason. Both ask for your PIN. A price you may not decide says "This price needs another approver."

If the platform refuses your decision, the sheet names the reason and shows the current state: "A newer price was published", "The price changed since you opened it", "This price is past its bound", "Someone already decided this price", "This price changed while you were deciding", "The source is paused" or "The source has stopped". Read the sheet again before you decide a second time. A paused source can still have a held price rejected, and cannot have one approved.

Note (Governors review from Actions): A governor of a token who is not a feeds manager does not see "Data feeds" in the sidebar. The "Review held price" row in "Actions" opens the **Held prices** tab, which lists only the prices that governor may decide. The governor cannot read the source itself, so the page shows no source settings, and the evidence shows only the record that produced the price.

## Review deliveries [#review-deliveries]

The **Deliveries** tab lists each delivery with the time it was "Received", its "Status", its "Records", and how its prices settled: "Rejected", "Accepted", "Dropped", "Held" and "Published". "Status" reads "Received", "Failed validation", "Malformed file", "Evidence lost" or "Blocked egress".

Select **Load older deliveries** for earlier ones. With none the tab reads "No deliveries yet" and "Run Test connection on the Connection tab to see the egress IP to allow."

## Fetch, pause and resume a source [#fetch-pause-and-resume-a-source]

The source page header shows "Instruments", "Published today", "Held" and "Last delivery". "Published today" counts from 00:00 UTC.

- **Fetch now** asks an active SFTP, Bloomberg or LSEG source to fetch at once instead of waiting for its schedule. It asks for no PIN. The button reads "Fetching" while it runs, then says how many deliveries the fetch produced, or "Nothing new from the provider". A FIX source streams its prices and offers no "Fetch now". The person who requests a fetch cannot decide a price it holds.
- **Source actions** holds "Pause", "Resume" and "Rotate credential". A paused source publishes nothing. "Resume" asks for your PIN.

## Replace or remove the credential [#replace-or-remove-the-credential]

Choose "Source actions" › **Rotate credential**. It opens the "Replace credential" sheet, which reads "Enter the new credential. The previous one stays in use until the provider accepts the new one."

Select **Replace credential**. The Console confirms "Credential replaced". Rotating the credential does not exclude you from deciding held prices.

On the "Connection" tab, the credential panel shows the last characters the saved credential ends in and its version, never the credential. It offers "Replace", "Add credential" and **Remove**. "Remove" deletes the credential after your PIN, and an active source refuses the removal, so pause it first.

The settings panels on the "Connection" tab edit the connection, the publishing values and the timing. **Save** asks for your PIN.

## Retire a source [#retire-a-source]

**Retire source**, on the "Connection" tab, ends the source for good after a confirmation. The source stops fetching, its feed and ISIN mappings are freed for another source, it cannot be activated again, and its held prices still waiting for a decision are cancelled. A retired source keeps its settings read-only.

## Read the source list [#read-the-source-list]

The **Sources** tab lists each source with "Source", "Protocol", "Instruments", "Last delivery" and "Status", and "Search sources" filters it by name. A source that has delivered nothing reads "No delivery yet". An empty list says "No price sources yet".

"Status" reads "Draft", "Active", "Paused", "Retired", "Retrying" or "Needs attention". "Retrying" means the last fetch failed and the source tries again on its own. "Needs attention" carries the reason: the provider refused the credential, a connection setting needs a change, or the last delivery could not be read.

## Connection fields [#connection-fields]

The **Source** section holds the "Name". The fields in the other sections follow the delivery method:

| Method | Fields |
| --- | --- |
| File session | **Host**, **Port**, **Username**, **Remote path**, **Temporary file suffix**, **Time zone**, and the column names **ISIN column**, **Price column**, **Currency column**, **As-of column** and **Price type column** (leave the last empty when the file holds one price type) |
| FIX session | **SenderCompID**, **TargetCompID**, **TLS server name**, **TLS**, **Session start**, **Session end**, **FIX version**, **Reset sequence numbers** (**Never**, **On every logon** or **On the first logon of a session**) and **Entry types**, each a **MDEntryType** code mapped to a **Price type**, used once |
| Vendor request | **Account**, "Catalog", **Request fields**, separated by commas, **Run at**, as HH:mm times separated by commas, and **Credentials expire (optional)** |

The **Credential** section asks for a "Credential type", "Password" or "Private key", with "Password" or "Private key" and "Passphrase (optional)" to match, or for a vendor "Logon username", "Client ID" and "Client secret". The credential is stored in the platform secret store, is write-only and is never shown again. Select "Cancel" to leave the page without saving.

## Held prices and the second approver [#held-prices-and-the-second-approver]

A price that moves further from the last published price than the source's hold tolerance, or that corrects a price the source already delivered for the same instrument, price type and observed time, is a held price. What happens to it depends on the organisation's **Prices** approval rule, in the "Approvals" section of [General](https://docs.settlemint.com/docs/console/organisation-settings/general#approvals):

- With "Prices" set to **Second person required**, the price waits in a queue and nothing is published until a second person approves it. This maker-checker control covers held prices only.
- With "Prices" set to **Not required**, the platform publishes the price without a second person and records it as not approved by a second person. Actions shows it as "No second approval (approval off)".

Every approval rule starts off in a new organisation, so turn **Prices** on before you activate a source if held prices must be reviewed.

When the rule is on, a feeds manager or a governor of the token decides the held price. A person who set up the source, changed its settings, mapped or unmapped an instrument, trusted its host key, or requested the delivery with **Fetch now** cannot decide it. Rotating the credential does not exclude you. This rule keeps one person from deciding a held price on a source they control. It does not cover a value published by hand on Data feeds or Token pricing, which a trusted issuer publishes with no second person, or a price that moves less than the hold threshold.

## What the platform checks before it publishes [#what-the-platform-checks-before-it-publishes]

Every delivered price becomes an observation with its ISIN, price, currency, price type, observed time and source. The raw delivery is kept off chain as evidence with its hash. The checks run in this order, and the first that applies decides the outcome:

1. A repeat of a price already recorded, with the same value, is dropped as a duplicate.
2. A price at or below zero is refused as invalid.
3. A price for an ISIN with no mapping is recorded as unmapped and listed under **Unmatched ISINs**.
4. A token price, after the price basis is applied, that the feed's decimals cannot hold exactly is refused as invalid.
5. A currency other than the feed's currency is refused as a currency mismatch. It is not held.
6. An observed time earlier than the feed's latest is refused as out of order, and its time is not moved forward. A time more than 60 seconds ahead of the chain is refused as future dated. A time up to 60 seconds ahead waits until chain time reaches it.
7. A different value for the same instrument, price type and observed time is a correction and is held. A FIX message with a higher sequence number than each earlier price that differs from it is not a correction.
8. A move from the last published price beyond **Hold above (percent)** is held.
9. The first price of a feed, a move of at least the publish threshold, or a newer price after the heartbeat interval is published. Any other price is skipped.

A held price then follows the organisation's **Prices** approval rule, as described in [Held prices and the second approver](#held-prices-and-the-second-approver).

A feed has at most one open held price. A later price that would also be held attaches to it as the latest candidate, and an approval publishes that newest candidate. A later price that passes the checks replaces the held price. Freshness counts from the provider's observed time, not from the moment of publishing, so a late approval does not make a feed look fresher than the provider's price is.

## When a feed goes stale [#when-a-feed-goes-stale]

The platform checks every mapped feed once a minute against the chain's time. A feed is stale when its latest observed price is older than the staleness bound: the feed's staleness window, its own or the global default, when that window is finite, else the source's **Stale after**. A feed with no price yet counts from the time it was mapped. A feed with neither bound is not judged. A paused source is still judged, and a retired one is not.

For each stale episode the platform opens one operations case. The "Cases" tab of [Custody](https://docs.settlemint.com/docs/console/organisation-settings/custody) lists it as **Stale price feed**. Only an organisation owner or a platform administrator sees that tab, whether or not the custody books are turned on. The case detail names the token, the bound, since when the feed is stale, the source and the cause:

- The source is paused.
- The source is failing with a transient, credential, configuration or data failure.
- A price is held awaiting review.
- A price is awaiting custody approval before it is published.
- Deliveries since the last publish were dropped as older than the feed's newest price.
- The latest delivery could not be published.
- The latest delivery was refused by the checks.
- The latest delivery has been received but not processed yet.
- The source has delivered no price since the last publish.

The case resolves when a fresh price lands, when the feed is unmapped, or when the source is retired. A feed that turns fresh and then stale again reopens it. Platform operators also get a stale-feed metric and alert rule, described in [Price source prerequisites](https://docs.settlemint.com/docs/deployment/price-source-prerequisites).

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

- Open the token's "Placement" tab and read the **Price** card in the "Price feeds" section. "Price from" names the source and the price field, and "Vendor" names Bloomberg or LSEG for a vendor source. The card shows when the provider observed the price, when it was published and by whose approval for a held price, the operations signer under "Signed by", and "Usable until".
- **View evidence** opens "Price evidence", the record the provider delivered for that price. On the source, the "Deliveries" tab lists each delivery and how its prices settled.

## Troubleshooting [#troubleshooting]

**A source needs attention**

Open the source and read the status. If the provider refused the credential, replace it from **Source actions**. If a
connection setting needs a change, the "Connection" tab names it. Check the timing too: the heartbeat, the expected
interval and the expected lag together must stay shorter than the staleness bound. If the last delivery could not be
read, open "Deliveries" and check the status of the latest one. A source stopped by a credential or configuration
failure publishes nothing until you change the cause, then select "Pause" and then "Resume" in "Source actions".

**A delivery shows “Blocked egress”**

The provider refused the platform's outbound address. Run **Test connection** on the "Connection" tab to see the
egress IP, and ask the provider to allow it.

**A price that moved past the tolerance was published without review**

The organisation's "Prices" approval rule is **Not required**. Turn it on in the "Approvals" section of General.
Prices delivered after that wait for a second person.

**Nobody can approve a held price**

The row on the **Held prices** tab reads "No one can approve this yet", and its review sheet reads "No eligible
approver". Only a feeds manager or a governor of the token can approve a held price, and never a person who set up the
source or requested the delivery. Grant the "Feeds manager" role to another person, or the "Governance" role on the
token. Then open the price again.

**An ISIN arrives but no price reaches the feed**

Check **Unmatched ISINs** on the "Instruments" tab: an ISIN with no mapping publishes nothing. Check that the source
is active, because a draft or paused source publishes nothing. Check that the mapping's currency matches the currency
of the token's feed. Then check "Deliveries" for how the prices settled.

**I cannot approve a price I expected to decide**

You set up the source, changed its settings, mapped or unmapped an instrument, trusted its host key, or requested the
delivery. Any of these puts you in the group that cannot decide its held prices. Ask another feeds manager, or the
governor of the token, to decide it.

**The “Price” card shows “Stale”**

The price is older than the feed's staleness window on chain time. Open the **Stale price feed** case on the "Cases"
tab of Custody, which names the cause. A held price waits for review, a paused source publishes nothing, and a source
that stopped delivering needs its provider checked.

## API routes [#api-routes]

The same work is available through the [Platform API](https://docs.settlemint.com/docs/api-reference/v2) under `/api/v2/price-sources` and `/api/v2/held-prices`. A feeds manager uses them with a signed-in session or an API key, and a governor reads and decides the held prices of their own tokens. Activating a source, editing its settings, setting or removing its credential, trusting a host key, mapping instruments and deciding a held price need a signed-in session and wallet verification, so an API key is refused for them. [Read and submit price feeds](https://docs.settlemint.com/docs/api-reference/guides/feeds) lists the routes and their error codes.


# System updates

Source: https://docs.settlemint.com/docs/console/organisation-settings/system-updates
Compare the organisation's deployed system components with the latest DALP release and upgrade them in one run.

System updates compares the contracts of the organisation's system with the release directory of the selected network and upgrades the ones that are behind. The release directory is the on-chain list of the contract versions in the latest DALP release, and the platform operator sets one for each network. The organisation chooses only whether and when to run the upgrade. The page applies to the system as a whole and has no per-token setting. [System Version](https://docs.settlemint.com/docs/platform/system-version) explains how a component falls behind and what an upgrade changes.

Upgrading the platform itself is a separate task: the platform operator runs it with Helm, as [Upgrades and migrations](https://docs.settlemint.com/docs/deployment/upgrades-migrations) describes. System contracts, registries, factories and tokens stay on the versions they run until a System updates run upgrades them. Identity contracts do not: they take their code from the platform's shared identity factory, so when the platform operator registers a new identity implementation, every identity on that network, the organisation identity included, runs it from the next call.

![System updates page with the Release status figures, the Upgrade button and the components table](https://docs.settlemint.com/docs/screenshots/console-organisation-system-updates.light.en.webp)

[Screenshot] The "System updates" page under "Infrastructure".

The "Release status" strip shows "Need an upgrade", "Up to date", "Tokens affected" and "Not verified", the title row carries the **Upgrade** button, and the components table lists "Component", "State", "Tokens affected" and "Area".

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

- Hold the Permission manager or System manager role on the system, on the wallet you sign with. The Roles and permissions screen calls the first role Permission manager. The **You can't view System updates** card lists it as Admin. Only an account that holds one of them sees the sidebar entry and the page.
- Select the network whose system you want to upgrade. The page follows the network selected in the account menu's Network submenu and shows the network under the title as "On" followed by the network name.
- Use a signing wallet that holds a management key on the organisation identity, the on-chain identity contract of the organisation. The run writes to that identity, and those writes fail without a management key, so the platform checks the key before it starts the run.
- Have your wallet verification ready: your transaction PIN, or your transaction code when your account has an authenticator.

## Steps [#steps]

### Read the figures and the table [#read-the-figures-and-the-table]

The **Release status** strip counts the components that "Need an upgrade", how many verified components are "Up to date" out of all components, the "Tokens affected" that "Move to a new version", and the components that are "Not verified".

The system and release directory addresses sit in a collapsed **Contract addresses** section. The table lists each component. [Component states](#component-states) explains what each state means.

### Select Upgrade [#select-upgrade]

The **Upgrade** button on the title row names how many components it upgrades, for example "Upgrade 3 components". Select it. When you cannot, the reason shows next to the button: [Why Upgrade is unavailable](#why-upgrade-is-unavailable) lists the reasons.

### Confirm in the sheet [#confirm-in-the-sheet]

The sheet is titled "Upgrade 3 components?" and reads "Upgrades them to the latest DALP release." It lists the components under **What the upgrade changes**, marks a component the run installs with "Installs new", and counts the tokens that move.

The count on the button also includes internal data steps that have no row, and a line such as "2 more internal data steps are included." counts them. A line starting "Not included:" names the components left out and why.

Read the consequence. Every change is written to the network and cannot be undone. If a later step fails, the steps already applied stay. When tokens move their stored data to the new version, that step cannot be interrupted once it starts.

The sheet also says which wallet case applies: "Your organisation keeps standard wallets. The upgrade prepares Advanced accounts infrastructure but does not switch any wallet." or "Your organisation stays on Advanced accounts. The upgrade brings its Advanced accounts infrastructure up to date." The switch to smart wallets belongs to the Wallet type row of [Transaction funding](https://docs.settlemint.com/docs/console/organisation-settings/transaction-funding#change-the-wallet-type).

On an organisation on Advanced accounts, the run also grants each smart wallet the system and token roles that its custody account's signing wallet holds, and registers the smart wallet under the member's identity. A member has one smart wallet per network.

When none of a member's custody accounts is registered, the run moves the roles of the custody account that controls that smart wallet, or, before it exists, of their primary custody account, or of their only one once it is active. Any other unregistered custody account keeps its roles on its own signing wallet, and the run moves nothing for it.

When none of a member's custody accounts is registered and their identity is registered only on another wallet of theirs that no custody account holds, the run registers the member's smart wallet under that identity.

When those other wallets hold more than one identity, the run registers that smart wallet under none of them, finishes its other steps, and then fails with an error that names the participant and the identities. Have an identity manager remove the wrong registration with **Remove registration** on the participant's page, then run the upgrade again.

Type the organisation's name in the confirmation field, which reads "Type" followed by the name and "to confirm this applies to your organisation", then select **Upgrade 3 components** at the bottom of the sheet. "Keep current versions" closes the sheet and changes nothing.

### Upgrades that touch custodied tokens [#upgrades-that-touch-custodied-tokens]

When a custodian organisation holds tokens that a factory deployed, the run refuses to upgrade that factory until an upgrade was scheduled for it and its notice period has ended. The run stops and states when the upgrade may run, or that none was scheduled. The system's organisation schedules the upgrade through the Platform API, and an emergency upgrade skips the wait. [Custodian watch](https://docs.settlemint.com/docs/concepts/custody-and-signing/custodian-watch) explains the notice and who receives it.

### Verify the upgrade [#verify-the-upgrade]

Confirm with your wallet verification: your transaction PIN, or your transaction code when your account has an authenticator. The sheet asks for it once. A toast reads **The upgrade started**, and the progress card takes the place of the figure strip.

## Follow the progress [#follow-the-progress]

The progress card replaces the figure strip while the upgrade runs. Its title and status line tell you where the run is:

| Title and status line | Meaning and controls |
| --- | --- |
| "Upgrade in progress", "Starting the upgrade…" | The run has started and its step list is loading. |
| "Upgrade in progress", a line that starts "Every stage runs in order" | The step list follows the step that runs. A stage with nothing to change finishes at once, and you can leave the page. |
| "Upgrade in progress", "Connection lost, reconnecting. The upgrade keeps running." | The live view dropped and reconnects on its own. The run continues on the platform. |
| "Upgrade in progress", "We lost the live view of this upgrade. It may still be running." | The live view ended without a result. **Reload progress** reads the run again, and **Dismiss** hides the card. |
| "Upgrade complete", "The upgrade finished. Your organisation still uses standard wallets." | Every step succeeded. The line ends "Your organisation stays on Advanced accounts." for an organisation on Advanced accounts. **Done** returns to the summary and reloads the comparison. |
| "Upgrade stopped", the step and "stopped" | A step failed. The card reads "The steps before it stay applied. Try again continues from this step.", shows the error and an error reference, and offers **Try again** and **Dismiss**. |

Reload the page while the upgrade runs and the running upgrade comes back, and Upgrade stays unavailable with "An upgrade is already running."

After a failure, **Try again** reopens the sheet. The new run continues from the failed step, because the steps before it stay applied and finish at once. "Dismiss" hides the failure. A failed run does not reappear after a reload, and the table shows what is still pending. The page does not show the result of a finished run after a reload. Only an upgrade in flight is read back.

## Read a component's details [#read-a-components-details]

Select a component's name to open its detail sheet. It has these sections:

- **Summary** shows the "State", the "Identifier", "What it does", the "Change", "Why" and the "Area". For a global compliance module replacement, the "Change" reads "Replaces a retired version. Your rules stay as they are."
- **Factory** and "Token versions" appear for token factories and per-token components. A version the platform could not read shows "Could not be read".
- **Versions** shows "Running now" and "Latest release".
- A component the run leaves out because your signing wallet lacks the compliance manager role reads "Your signing wallet does not hold the compliance manager role. Ask a compliance manager to run System updates, or switch to a wallet that holds the role." with an **Open Roles and permissions** button.

The organisation wallets row adds an **Organisation wallets** section that lists each wallet and why it is held back: "Not registered under the organisation identity.", "Its registration awaits acceptance." or "Registered under another identity." Wallets the upgrade creates itself show under "Not created yet", and the "Deploying admin" line says when the upgrade has no country to register them with. An identity manager fixes each case in the Console: registering the deploying admin with a country or changing its country under Participants › Users, accepting a pending registration under Participants › Entities, or removing a registration from the holder's page.

## Component states [#component-states]

The components table has the columns "Component", "State", "Tokens affected" and "Area". A row also carries a "Global" or "Experimental" badge where it applies, and a reason line under the name. Each row has one of these states:

| State | Meaning |
| --- | --- |
| **Upgrade available** | The release directory holds a newer version of an installed component. |
| **Not installed** | The release directory has a component the system does not have. The run installs it. |
| **Needs compliance manager** | A global compliance module replaces a retired version, and that replacement needs the compliance manager role on the signing wallet. The run leaves it out. |
| **Not verified** | The platform could not read the version of the component's tokens. For the organisation wallets row, the system has no organisation identity indexed. Neither case means an upgrade is available. |
| **Up to date** | The deployed component matches the release directory. |

The **State** filter hides up-to-date rows when the page opens. Remove the chip to see every row. With every row hidden the table reads "Every component is up to date" and "Remove the State filter to see all 12 components." with the real count. When a search matches nothing it reads "No components match".

"Search components" narrows the table by name, and the **Area** filter narrows it by group: "Core system", "Identity", "Token infrastructure", "Compliance", "Registries", "Token factories", "Add-ons", "Pricing", "Compliance modules", "Advanced accounts" and "Reporting".

Experimental components stay out of a run unless you switch on **Include experimental**, which also asks for the comparison again.

## Why Upgrade is unavailable [#why-upgrade-is-unavailable]

| Reason shown | What it means |
| --- | --- |
| "Checking the release directory…" or "Refreshing the comparison…" | The comparison is loading. Wait for it. |
| "An upgrade is already running." | A run is in flight for this system. Follow it on the page. |
| "The remaining upgrades need the compliance manager role on your signing wallet." | Only global compliance module replacements are left. Sign with a wallet that holds that role. |
| "Only experimental upgrades are left. Switch on Include experimental to add them." | Only experimental components are pending. |
| "Nothing to upgrade, but 2 components could not be verified." | No upgrade is pending, and the versions of some components could not be read. |
| "Every component runs the latest release." | The system matches the release directory. |

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

- After "Done", the **Need an upgrade** figure drops by the number of components the run upgraded, and the "State" filter no longer lists them.
- Components the run left out, such as experimental ones and global compliance module replacements that need the compliance manager role, keep their rows and their reasons.

## Troubleshooting [#troubleshooting]

**The page says you can't view System updates**

Your account holds neither the Permission manager role (shown as Admin on that card) nor the System manager role on
this system. Ask a member who holds one of those roles to run the upgrade.

**The page says your roles could not be read**

The Console could not read your roles. The page reads "Your roles could not be read" and "Check your connection and
try again." Select the retry button.

**The page says your role is on another wallet**

One of your other wallets holds the role. The page names that wallet. Switch to it and open the page again.

**The page says there is nothing to upgrade on this network, or no release directory**

**Nothing to upgrade on this network** means the organisation has no system on the selected network. An organisation
owner deploys one from Networks, and "Open Networks" takes you there. A title that says the network has no release
directory means the platform operator has not set one for that network, so nothing can be compared or upgraded.

**The comparison could not be loaded**

The network did not answer, so the versions could not be compared. Nothing was changed. Select Try again on the error
card.

**The upgrade did not start after the verification**

The sheet shows the reason and an error reference, and nothing is written to the network. A signing wallet without a
management key on the organisation identity is refused with [DALP-14328](https://docs.settlemint.com/docs/api-reference/errors). Switch to a
wallet that holds the key. After a recent change to your wallet security, signing is held for a cooling-off period.
Wait until it ends and start again.

**The upgrade stopped partway**

The failed step, its error and an error reference stay on the page. Fix the cause the error names, then select Try
again. Steps that already finished stay applied.

## API routes [#api-routes]

The page calls these four routes of the Platform API, and each one answers 403 to a caller without the Permission manager or System manager role:

- `GET /api/v2/system/migration-comparison` returns the comparison. Add `includeExperimental=true` to count experimental components.
- `POST /api/v2/system/migrations` starts a run, with an optional `includeExperimental` in the body. A browser session sends `walletVerification` in the body. A request from an API key sends none and is refused only while the key holder is in the cooling-off period after a wallet security change. A new run answers 202 with its `migrationId`. When a run is already in flight, or you repeat a request with the same `Idempotency-Key`, the platform answers 200 with the existing run and starts nothing.
- `GET /api/v2/system/migrations/{migrationId}/stream` streams the progress of a run in your organisation. A request from a browser session must show that it comes from the same origin as the Console, through its `Sec-Fetch-Site`, `Origin` or `Referer` header. Without that evidence the stream answers 403. A request from an API key needs no such evidence.
- `GET /api/v2/system/migrations/active` returns the run in flight, or nothing.

The [Platform API reference](https://docs.settlemint.com/docs/api-reference/v2) lists the first three routes.


# Theme

Source: https://docs.settlemint.com/docs/console/organisation-settings/theme
Set the organisation's Console branding and the issuer name and disclaimer on its statements, or, as a platform administrator, theme every organisation.

Theme sets the palette, fonts, images, and favicons every member of the active organisation sees across the Console. The same logo, colours, and fonts style the PDF investor statements, and the **Documents** section sets the legal entity name, entity details, and disclaimer those statements print. Saving writes a new theme version with no separate publish step, and open Console tabs pick it up on their next navigation.

Theme changes nothing about which accounts can act for the organisation or what the organisation can transact. Those stay under "Roles and permissions" and "Networks".

![Theme editor with a section list, image, font, and colour settings](https://docs.settlemint.com/docs/screenshots/console-organisation-theme.light.en.webp)

[Screenshot] A section list on the left beside the settings in cards: "Branding", "Sign-in page", "Browser icons", "Typography", "Colours", "Documents" and "Global theme".

Each image shows its light and dark versions side by side, each with a "Replace" button. **Colours** has a "Light" and "Dark" switch and lists each colour by name with its id beneath.

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

- Only an owner or a platform administrator edits the theme. The sidebar shows **Theme** only to them, and the server applies the same rule when you save, so a member cannot save a change. If "Theme" is missing from your sidebar, ask an organisation owner or a platform administrator to make the change.
- Check readability yourself. The editor validates that a colour value parses, not that text stays legible against its background. The Console applies your draft to itself as you edit, so use the Console as your readability check before you save, and check body text, links, and controls in both light and dark modes. A hard-to-read palette or broken image stays until someone corrects it or selects **Reset to defaults**, which also discards every image.
- Image slots accept SVG, PNG, JPEG or WebP, and the browser icon slots take one type each: "Favicon" accepts ICO, PNG or SVG, "Apple touch icon" at 180 × 180 px and "Favicon 96" at 96 × 96 px accept PNG only, and "Favicon SVG" accepts SVG only. Each image has a 5 MB size limit. An upload link expires after 15 minutes, so a slow upload that misses that window needs a fresh attempt rather than a resume.

## Steps [#steps]

### Open Theme [#open-theme]

Open "Organisation settings", then **Theme**.

The "Theme sections" list on the left jumps to the sections in four groups:

- **Identity** holds "Branding", "Sign-in page" and "Browser icons".
- **Appearance** holds "Typography" and "Colours".
- **Statements** holds "Documents".
- **Platform** holds "Global theme", for a platform administrator.

### Change something and save [#change-something-and-save]

Change images, fonts or colours, or fill in "Documents", as [Change the images](#change-the-images), [Set typography](#set-typography), [Change colours](#change-colours) and [Set the statement details](#set-the-statement-details) describe. When something is unsaved, a bar at the foot of the page, "Unsaved theme changes", counts the unsaved changes and offers "Discard" and "Save theme".

Select **Save theme** to write the new theme version. While it saves, the bar reads "Saving…". When "Save theme" is unavailable, the bar says why beside it: "An image is still uploading.", "A colour value is invalid: `<colour name>`." or "A stylesheet URL is invalid: `<font>`."

## Change the images [#change-the-images]

The "Branding", "Sign-in page" and "Browser icons" sections hold these image slots:

- **Logo**: "Shown in the sidebar and on documents."
- **Logo icon**: "Square mark for compact places."
- **Background image**: the Console gives it no description line.
- **Sign-in logo**: "Uses the logo when left empty."
- **Overlay**: "Shown behind the form at reduced opacity."
- **Favicon**: a browser icon
- **Apple touch icon**: a browser icon
- **Favicon 96**: a browser icon
- **Favicon SVG**: a browser icon

Each image shows its light and dark versions side by side. Select **Upload**, or "Replace" when one is set, on the version you want to change. Screen readers announce the default SettleMint logo as "SettleMint". Once you upload a logo of your own, they announce it by the logo's alternative text.

## Set typography [#set-typography]

**Typography** sets the "Sans-serif" face ("Used for most of the interface.") and the "Monospace" face ("Used for addresses, code and figures."). The sans-serif face sets words. The monospace face sets figures, such as amounts, prices, percentages and dates, also where a figure sits inside a sentence, and identifiers such as addresses.

For each face, choose the **Source**:

- **Default** keeps the faces the Console serves from its own origin, so a deployment without a route to the internet renders them.
- **Custom CSS URL** names a stylesheet you host, which adds a brand face without the Console requesting another host. Enter its "Stylesheet URL" and the "Family".

With a custom URL, the browser requests that one stylesheet, and the Content Security Policy of the Console refuses a stylesheet on a different origin, so it must be served from the Console's own origin. Ask the platform operator who runs the deployment to host it there. The address must be `https://` on a public host name such as `cdn.example.com`: the field says "Use an https:// address. Plain http, data: and javascript: addresses are not loaded.", "Use a public host name, for example cdn.example.com. IP addresses and internal names are not loaded." and "Use an address of at most 2048 characters." The Console and the v1 and v2 theme writes refuse an IP address, a name with no dot such as `localhost`, and a name ending in `.local`, `.localhost`, `.internal`, `.localdomain` or `.home.arpa`. This keeps a theme from sending a visitor's browser to an address on a private network.

Three more settings apply to each face:

- **Weights** takes a comma-separated list ("Blank uses the defaults.").
- **Preload** loads the font before the page renders.
- **Sample** previews the face.

## Change colours [#change-colours]

**Colours** has a "Light" and "Dark" switch, and lists each colour by name with its id beneath, grouped under "Text", "Accent", "Surfaces", "Status", "Charts" and "Other".

Success, warning and info each have three colours named for what they paint: "Success background" is the fill of a badge or button, "Text on success background" is the colour drawn on that fill, and "Success text" is the state colour used for text on the page. Error has the first two. In the default theme the text on a success, warning or info fill is near-black in both sets, so its swatch reads dark beside the coloured swatch of its background. That pair is the default and does not mean a value was lost.

Select **Edit `<colour>` colour** to open the editor, where a value is a hex, oklch, hsl, rgb or var colour. An invalid value reads "Enter a valid colour (hex, oklch, hsl, rgb, or var)." and blocks the save.

**Revert** puts a colour back to its saved value.

## Set the statement details [#set-the-statement-details]

The **Documents** section sets what the PDF investor statements print: "Legal entity name", "Entity details" and "Disclaimer".

- **Legal entity name** prints as the issuer. When it is empty, the logo's alternative text prints.
- **Entity details** hold the address, licence and contact details, each on its own line.
- **Disclaimer** prints under Important information. Blank lines start a new paragraph, and the standard disclaimer prints when it is empty.

## Reset the theme [#reset-the-theme]

To return to the platform default theme, open the "Actions" menu on this page, choose **Reset to defaults**, and confirm in the dialog "Reset the theme to defaults?" by selecting "Reset theme", or "Keep my theme" to cancel. Reset saves the default theme at once and the Console confirms "Default theme restored". It does not wait for "Save theme", and it discards the logo and every other image along with the palette.

Note (Reset to defaults clears the whole theme): Reset does not selectively clear the palette while keeping your logo and other images, and it keeps no backup to restore from. It saves the platform default theme, so the organisation's logo, background, sign-in page image, and favicon set are all discarded along with the palette. If any of those images matter to the organisation, keep the original files before you reset. If only the palette needs correcting, edit the colours back by hand instead.

## Turn on the global theme [#turn-on-the-global-theme]

Note (Turn on replaces the theme of every organisation): While a global theme is on, every organisation's PDF investor statements print this organisation's **Legal entity name** as the issuer, its "Entity details" and its "Disclaimer", and every organisation's emails carry its branding.

A platform administrator also sees "Global theme". **Turn on** makes the saved theme of this organisation the theme of every organisation, at once and without a question. The card reads "Used for every organisation" while it is on and "Not global" while it is off. While it is on, owners cannot change their own theme.

The **Reason for the global theme change (optional)** field on the card is recorded in the audit trail with "Turn on" or "Turn off".

After "Turn on" or "Turn off", a toast offers **Undo** for 8 seconds, which gives the global theme back to whoever held it before. Unsaved changes are not included.

**Turn off** applies at once.

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

- The Console shows **Theme saved** and the unsaved-changes bar disappears.
- Reload "Theme": the saved version now loads as the new baseline, and any other open Console tab in the organisation picks up the same theme on its next navigation.
- Check the palette once more in both light and dark modes.
- PDF investor statements read the saved theme and the "Documents" details when each one is generated, so a statement made before your save keeps the old look: generate a new one to check the logo, fonts, and entity details.
- Signed-out screens show a theme in two cases.
- When the deployment has a single organisation, they show its theme.
- When a global theme is set, they show the global theme instead.
- In any other deployment they show neither, so your "Sign-in page" changes cannot be seen on a signed-out screen.
- After a platform administrator selects "Turn on" under "Global theme", the Console confirms "Global theme turned on".

## Troubleshooting [#troubleshooting]

**Theme editing is disabled**

The page shows "Theme editing disabled" and names the organisation whose global theme is active. While a global theme
is on, no owner can change this organisation's theme, and the notice replaces the whole editor, "Global theme"
included. A platform administrator opens the **Organisation** submenu of the account menu, switches to the
organisation the notice names, and turns the global theme off under "Global theme" there. This organisation then uses
its own saved theme again. If you are not a platform administrator, ask one to turn the global theme off.

**An image upload fails**

Check the file against the slot: SVG, PNG, JPEG or WebP for images, and for browser icons ICO, PNG or SVG in
"Favicon", PNG only in "Apple touch icon" and "Favicon 96", SVG only in "Favicon SVG", and at most 5 MB. An upload
link expires after 15 minutes, so a slow upload needs a fresh attempt. **Save theme** stays disabled while an image is
still uploading.

**A palette value is rejected**

Correct the invalid colour value shown by the editor, then save again. The editor blocks the save until every colour
parses.

**Save theme stays disabled**

The bar says why in words beside the button: "An image is still uploading.", "A colour value is invalid:" followed by
the colour name, or "A stylesheet URL is invalid:" followed by the font. Wait for uploads to finish, correct the named
colour, or give the font's custom stylesheet an `https://` address on a public host name. The Console never loads a
plain `http://`, `data:` or `javascript:` stylesheet, or one on an IP address or an internal name. A theme saved with
such an address before this rule still opens, but that stylesheet is not loaded.

**Unsaved changes from an earlier visit are offered after a reload**

Unsaved changes stay in this browser, per user and per organisation, so a reload does not lose in-progress work. A
draft does not follow you to another browser. The editor does not apply a kept draft on load: select **Restore
changes** to continue it or "Discard changes" to clear it. A draft is discarded when it was made against an older
saved version or introduces an invalid stylesheet URL. A draft with an invalid colour is offered like any other, but
its colour is never applied, the field names it, and Save stays blocked until you correct it. A draft belongs to one
organisation, so switching organisations does not carry it over.

**Saving fails with a version conflict**

Another save landed on this theme after you opened the editor, often from a second owner or platform administrator
editing it around the same time. Note your changes, then reload **Theme** to load the latest saved version. A draft
made against the older version is discarded on reload, so reapply your changes on top of the newer save.



# Transaction funding

Source: https://docs.settlemint.com/docs/console/organisation-settings/transaction-funding
See who pays gas on the selected network, fund the wallets that pay it, change the gas payer, and move the organisation from EOA wallets to smart wallets.

Transaction funding decides who pays the network fee, called gas, for the organisation's transactions, and keeps the wallets that pay it funded. The page shows the network selected in the **Network** submenu of the account menu at the top right: who pays gas there, which shared gas wallets pay it, which wallets wait for funds, and where to send a top-up. The account menu shows that submenu only when multi-network support is on for the organisation and it has more than one active network. Otherwise the page shows the organisation's default network.

When a wallet runs short on a network that charges gas, the platform pauses the write and the Console shows a funding request at the top of the page. [How gas is paid and funded](https://docs.settlemint.com/docs/concepts/custody-and-signing/gas-funding) explains the pause, the funding window and the three gas payers.

The page also holds the **Wallet type** row, which sets the kind of wallet every user of the organisation holds. Every change made on this page, including a gas payer change, a sponsorship change, a refund split change, a signing key rotation, a paymaster deposit and a withdrawal, is recorded in the organisation's [Audit trail](https://docs.settlemint.com/docs/console/reporting/audit-trail) with who made it. A top-up is a transfer you send from another wallet, so the platform keeps no record of it beyond the wallet's higher balance. A withdrawal also appears on the transactions page.

![Transaction funding page with the Gas card, its Gas payer row and Wallets row, and the Wallet type card below it](https://docs.settlemint.com/docs/screenshots/console-organisation-transaction-funding.light.en.webp)

[Screenshot] One "Gas" card with a "Gas payer" row and a "Wallets" row that lists the shared gas wallets, and below it the "Wallet type" card that names the current wallet type.

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

- The sidebar shows **Transaction funding** under "Infrastructure" to the Permission manager, Gas manager and System manager roles. Reading the page and sending a top-up transfer to a shared gas wallet need nothing else. The Console calls the system's `admin` role "Permission manager".
- **Withdraw:** needs the Permission manager role. In the Console it also asks for your wallet verification. Through the API, a request from an API key sends no wallet verification and is refused only during the cooling-off period after a wallet security change. A withdrawal from the paymaster deposit also needs the System manager role, because the paymaster contract checks that role on the account that signs.
- **Change the gas payer with EOA wallets:** in the Console, needs the organisation's Owner role or platform administrator access. The row says "Only an organisation owner or platform admin changes the gas payer." to anyone else.
- **Change the gas payer with smart wallets, deposit into the paymaster or set gas tank alarms:** needs the Permission manager, Gas manager or System manager role. A deposit also needs your wallet verification. The row says "Only a permission manager, gas manager or system manager changes the gas payer." to anyone else.
- **Set the refund split:** needs the System manager role and your wallet verification, because the splitter contract accepts the change only from an account that holds that role.
- **Rotate the signing key:** needs the System manager role.
- **Change the wallet type:** needs an organisation owner or platform administrator. A platform administrator can start this one-way switch in any organisation they are a member of. The row shows only on a deployment that offers smart wallets.
- When the organisation uses more than one network, select the network in the **Network** submenu of the account menu before you start. If the organisation has no active network, the page reads "No network is active", with the same "Open Networks" button for an organisation owner or platform administrator as on [Actions](https://docs.settlemint.com/docs/console/essentials/actions). When the page has no EVM network to show, it reads "Select a network under Network in the user menu to see how its gas is paid." The user menu is the account menu at the top right: select an EVM network in its "Network" submenu.

## Steps [#steps]

Keeping the page healthy takes four steps. [Change the gas payer](#change-the-gas-payer), [Withdraw from an idle wallet](#withdraw-from-an-idle-wallet) and [Change the wallet type](#change-the-wallet-type) are separate tasks.

### Read who pays on the network [#read-who-pays-on-the-network]

In the sidebar, open **Transaction funding** under "Infrastructure". Under the title, the page reads "On `<network>`". It follows the network selected in the "Network" submenu and changes when you switch network there.

One "Gas" card holds two rows. The **Gas payer** row states who pays on that network and has a "Change" button.

| Wallet type and gas payer | Row value |
| --- | --- |
| EOA wallets, Relayer-paid | The relayer wallet pays every write |
| EOA wallets, Self-pay | Each wallet pays its own writes |
| Smart wallets, Paymaster-paid | The paymaster deposit pays every operation |
| Smart wallets, Self-pay | Each smart wallet pays its own operations |

On a network that charges no gas, the row reads "No fee on this network" instead. For a viewer who may not change the payer, **Change** is unavailable. Point at it to read who can.

A network still being set up says so instead of listing wallets. While a network finishes a move to smart wallets, the row says the gas payer shown can still change. When the read fails, the page reads "Transaction funding could not be read." with a **Try again** button. A network whose gas payer the platform has not read yet, such as one added a moment ago, reads "Not read yet" instead of a failure. The Console home System status shows a "Checking" badge with "Not read yet" next to the network, and leaves the network out of Needs attention until a read has happened. The status updates on its own once a new block brings the payer's balance.

On a network that charges no gas while the relayer or the paymaster pays, a notice at the top of the page explains that this saves no fee there. Select **Switch this network to Self-pay** to open the gas payer sheet with Self-pay preselected. Select "Keep relaying" or "Keep sponsoring" to hide the notice while you stay on the page. A screen reader announces each button together with the notice title, so you hear which notice it acts on.

### Fund an open request [#fund-an-open-request]

When the network refuses a write because a wallet cannot pay its gas, the platform opens a funding request. Bundler setup and repair are the exception: they open one from a balance check, for the bundler wallet's top-up level that [Shared gas wallets](#shared-gas-wallets) explains. The page shows one notice at the top for each request open on the network, for example "Bundler wallet needs 0.25 ETH". Each notice reads "Operations wait until it is funded." and shows when the request was raised. For a shared gas wallet, the notice also shows its balance. For a wallet the page cannot name, it also shows the address. With no open request, the page shows no notice.

Select the notice's button, for example **Fund 0.25 ETH**, to open the top-up sheet for that wallet. When the platform could not size the amount, the notice reads "needs gas" and the button reads "Fund". [When a wallet runs out of gas](https://docs.settlemint.com/docs/concepts/custody-and-signing/gas-funding#when-a-wallet-runs-out-of-gas) explains what waits and for how long.

For a smart wallet that pays its own gas, the amount covers the gas its EntryPoint deposit does not cover plus the native currency the operation sends, such as a deposit into the paymaster, so one transfer of that amount lets the write continue.

### Check the shared gas wallets [#check-the-shared-gas-wallets]

The **Wallets** row is a table of every shared gas wallet the platform runs for the organisation on the network, in use or idle, with the columns "Wallet", "Status" and "Balance", and a last column of actions. [Shared gas wallets](#shared-gas-wallets) explains each wallet and status. Each row has a "Top up" button and a menu, "More actions for `<wallet>`", with "Withdraw". Open a row for what the wallet does and its top-up level. When "Top up" or "Withdraw" is unavailable, point at it to read why.

In Self-pay with EOA wallets, no shared wallet pays. The row reads "Each wallet pays its own gas. A wallet that runs dry shows here as a funding request." On a network that charges no gas it reads "This network charges no gas." instead, and the "Balance" column shows the empty-value placeholder for every wallet, because no balance is needed there. The same placeholder stands for a wallet the indexer has not seen yet.

### Top up a wallet [#top-up-a-wallet]

Select **Top up** on a shared gas wallet in use, or the button on a funding request. "Top up" is enabled only on a network that charges gas and for a wallet that pays fees now. The sheet "Top up on `<network>`" opens with that wallet preselected under "Wallet to fund". You can choose another wallet on the network there.

The sheet shows the address under **Send to this address** with a copy button, a QR code that holds the same address, and the warning "Send `<currency>` on `<network>` only. Funds sent on another network do not reach this wallet." When a request is open for the selected wallet, the sheet shows "Needs at least `<amount>` to continue" and "Recommended: `<amount>` (covers follow-on operations)". When the wallet already holds enough, the sheet says nothing needs to be done and when the request closes. Without a request, the sheet can suggest an amount, as [Size a top-up](#size-a-top-up) explains.

Note (A confirmed transfer cannot be undone): The Console cannot reverse a transfer once it confirms. Funding the wrong wallet can need that wallet's custodian to recover the funds. A transfer to the paymaster or the refund splitter moves into the paymaster deposit, which needs an authorised withdrawal to come back out. Confirm the address and the network immediately before you send.

Send the transfer from the wallet or service your organisation uses for on-chain transfers. Keep the sheet open: it reads "Watching for the deposit…" and changes to "Deposit received." when the wallet's balance rises, or when the request closes. For the refund splitter, which forwards every deposit, the sheet watches the bundler wallet and the paymaster deposit together.

For the paymaster deposit, the sheet also shows "Deposit from a wallet". Enter an amount in the network currency, in your own number format and with a suffix such as `1.5k` if you like, select **Deposit**, and confirm with wallet verification. The deposit goes from the wallet of the account you are signed in with into the paymaster, and the sheet reads "Deposit sent. The balance updates once it lands." A refusal reads "The deposit was refused."

## Change the gas payer [#change-the-gas-payer]

Select **Change** on the "Gas payer" row. The "Change gas payer" sheet applies to the selected network only, and every other network keeps its own payer. When the deployment offers smart wallets, the sheet names the organisation's "Wallet type".

Under **Gas payer on `<network>`**, choose the payer:

- **EOA wallets:** "Self-pay" or "Relayer-paid". "Paymaster-paid" is listed only on a deployment that offers smart wallets, and it is unavailable with the note "Needs smart wallets: set under Wallet type."
- **Smart wallets:** "Self-pay" or "Paymaster-paid". "Relayer-paid" is unavailable, with the note "EOA wallets only: smart wallets go through the bundler instead."

On a network that charges no gas, the sheet recommends Self-pay. Add a note in "Reason (optional)" to record one in the Audit trail. Select **Save payer** to apply the choice, or "Keep current payer" to close the sheet. "Save payer" stays unavailable until you choose a different payer. The Console confirms with "Gas payer saved." and closes the sheet. When the save fails, the sheet shows the reason and the stored payer stays.

A switch changes how new transactions on that network are paid. A transaction the platform already prepared for the relayer still goes through the relayer. Users keep the same wallet addresses, so a switch moves no assets and changes no permissions. The transactions that deploy the organisation are paid by the deploying wallet, whatever you choose.

Switching a network to Relayer-paid creates a relayer wallet on that network, and until it holds enough, user transactions on that network wait for funding. Switching back to Self-pay stops the relayer paying, and the relayer keeps its balance. It shows as **Idle** in the "Wallets" table, where a Permission manager can [withdraw](#withdraw-from-an-idle-wallet) it.

Switching that network back to Relayer-paid later reuses the same relayer wallet and its balance.

The collapsible advanced section at the bottom of the sheet draws "How a write reaches the chain" for the payer you selected and holds the settings that follow. With EOA wallets it is "Advanced: relayer top-up levels". It shows the "Forwarder" contract's address on the network, or "Not deployed", and the relayer's top-up level. On a network that charges no gas, it reads "Top-up level: not needed".

With smart wallets it is "Advanced: bundler, gas tank and sponsorship". Under "Contracts on `<network>`" it shows "EntryPoint v0.7" and "Paymaster", or "Not deployed", the "Gas tank alarms" and "Refund split" buttons, and the "Signing key" block once the organisation has a paymaster on the network. Without the Permission manager, Gas manager or System manager role, these controls are unavailable.

Custody credentials are on [Custody](https://docs.settlemint.com/docs/console/organisation-settings/custody) and on-chain roles on [Roles and permissions](https://docs.settlemint.com/docs/console/organisation-settings/admins-and-roles).

## Set gas tank alarms [#set-gas-tank-alarms]

Select "Gas tank alarms" to open "Low-balance alarms". Enter "Warning at (days of runway)" and "Critical at (days of runway)": whole numbers of at least 1, with the critical alarm fewer days than the warning alarm. Unset, they read 7 and 3 days. Select **Save alarms**. The warning days also size the suggested top-up.

## Set the refund split [#set-the-refund-split]

A sponsored operation's gas cost can return in part after it settles. The refund splitter divides each amount it receives between the bundler wallet and the paymaster deposit. Select "Refund split" to open "Refund split (advanced)", and enter the **Bundler wallet share** in basis points, a whole number from 0 to 10,000. The rest goes to the paymaster deposit.

The split is stored in the splitter contract, so "Save refund split" asks for your wallet verification, "Confirm the refund split", to sign the update. The contract accepts the update only from an account that holds the System manager role, so "Save refund split" stays unavailable for anyone else and its tooltip reads "You need the System manager role to configure the gas reserves."

The split only divides value that reaches the splitter. The bundler wallet and the paymaster deposit still pay their own costs.

## Rotate the signing key [#rotate-the-signing-key]

The signing key is the custodial key that signs sponsored operations. The "Signing key" block shows the current key and when it was set. Rotate it when it may be compromised: select **Rotate signing key** and enter your verification code. The platform accepts a rotation from the System manager role only, and any other role gets "You need the System manager role to rotate the signing key." The current key stops working as soon as the new one takes effect. While the network confirms the change, the block reads "A new key is waiting for network confirmation".

## Read the refund splitter's balance history [#read-the-refund-splitters-balance-history]

Open the **Refund splitter** row. It holds a small table with the columns "Recorded" and "Balance": the balances the platform recorded over the last 30 days, each with the time it was recorded. With nothing recorded, it reads "No balance snapshots yet". When the history cannot be read, it reads "The balance history could not be read."

## Withdraw from an idle wallet [#withdraw-from-an-idle-wallet]

The platform cannot reverse a withdrawal once it confirms, so check the destination before you send.

In the "Wallets" table, open the menu of an idle wallet and select **Withdraw**. On a network that charges gas, an idle relayer wallet or bundler wallet that holds a balance offers it to the Permission manager role. An idle paymaster deposit offers it to a user with both the Permission manager and the System manager role. Where "Withdraw" is unavailable, the menu item or the opened row says why. A relayer left funded after a gas payer change can be emptied here, once the writes queued before the change have gone through it.

The sheet "Withdraw from `<wallet>`" shows the wallet's "Balance" and "Withdrawable now". Part of the balance stays in the wallet to pay for the withdrawal itself, including a resend at a higher fee, and the sheet names that amount.

Once "Send to" holds an address, the platform prices that amount for sending the whole withdrawable amount there. The withdrawal accepts the amount the sheet shows unless the network balance differs from the one shown, or the fee or the wallet's own writes changed since. When the wallet's own signed writes are still on their way to the network, including the bundles of the bundler wallet, the sheet also shows what they hold.

The platform counts each signed write at its worst-case gas cost, so the node admits the withdrawal beside them. Whatever those writes do not spend becomes available once they confirm. The whole paymaster deposit is withdrawable, because the account you sign with pays the withdrawal's gas.

Enter the address in **Send to** and the amount, which reads your own number format, groups the digits as you type and accepts a suffix such as `1.5k`, or select "Withdraw all", which takes everything withdrawable at the moment the platform sends the withdrawal.

The sheet blocks an address with a wrong checksum, the zero address, the wallet itself, and an address that does not accept a plain transfer of the network's currency.

Select "Review withdrawal", check "From", "To", "Amount" and "Network", then select **Withdraw** and enter your verification code. The sheet then reads "Sent `<amount>`", or says the withdrawal is queued and links to "Open transactions", where it shows with its outcome, including if it pauses or fails.

## Change the wallet type [#change-the-wallet-type]

Wallet type sets the kind of wallet every user of the organisation holds, on every network. An EOA wallet, or externally owned account, is a plain wallet controlled by one key. A [smart wallet](https://docs.settlemint.com/docs/concepts/custody-and-signing/smart-wallet) is a contract wallet with weighted signers, approval policies, and recovery.

The organisation starts on EOA wallets unless it chose smart wallets during [onboarding](https://docs.settlemint.com/docs/getting-started/onboarding). Come here when the organisation needs approval rules, key recovery, or batched operations. EOA wallets already issue and transfer assets, so the move is optional. It is also one-way: once the organisation uses smart wallets, the platform does not accept a move back.

The **Wallet type** row sits in its own card below the "Gas" card and shows only when the deployment offers smart wallets, through its account-abstraction feature. It names the current type, "EOA wallets" or "Smart wallets". On EOA wallets it says "Each wallet signs with its own key. No setup, no migration." and "One-way, for the whole organisation.", and states how many of the organisation's active networks are ready for smart wallets, for example "2 of 3 networks ready for smart wallets". When none is ready, it reads "No network can host smart wallets yet, so the switch cannot start." instead.

1. Read the card. Select **Review the switch**. The "Migrate to smart wallets" sheet opens, and nothing starts until you confirm at the bottom.
2. Read the sheet in order. It starts with **What each wallet type gives you**, a table that compares the two types, with the active type marked "Current":

   | Aspect               | EOA wallets                                  | Smart wallets                                      |
   | -------------------- | -------------------------------------------- | -------------------------------------------------- |
   | Signing              | One key per wallet signs every write.        | Weighted signers and approval policies per wallet. |
   | Gas                  | Self-pay or Relayer-paid, per network.       | Self-pay or Paymaster-paid, per network.           |
   | Recovery             | The key is the wallet. Lose it, lose access. | Recovery signers can replace a lost key.           |
   | Batched operations   | One write per transaction.                   | Several writes in one operation.                   |
   | Needs on the network | Nothing extra. A forwarder for Meta-tx.      | An EntryPoint and a bundler.                       |

   The table names any active network that has no EntryPoint and bundler yet. Then the sheet warns "Writes pause for a few minutes." Writes already in flight finish first, and anything new waits and resumes on its own.

![Migrate to smart wallets sheet with a wallet type comparison, network readiness and what happens](https://docs.settlemint.com/docs/screenshots/console-organisation-wallet-type-review-switch.light.en.webp)

[Screenshot] The "Migrate to smart wallets" sheet.

The sheet starts with a table that compares what each wallet type gives you, then lists each active network as "Ready" or "Not ready", the steps under "What happens", and the confirmation field at the bottom.

3. Under **Before you start**, the sheet lists each active network of the organisation as "Ready" or "Not ready". A network is ready when its EntryPoint and bundler are in place. A network that is not ready keeps its writes on EOA wallets until it is. A last row, "Gas after the switch", states that every network starts on Self-pay.
4. When a write on the organisation relayer is paused or still in flight, the sheet lists it under **A relayer write has not finished**. A paused write waits for relayer funds: top up the relayer on that network, or cancel the write. A cancelled write is not sent again, so submit it again after the switch. The sheet reads readiness again each time it opens, so a write that finished in the meantime no longer shows.
5. Under **What happens**, the sheet lists the steps:

   1. A smart wallet deploys for every existing wallet, on each ready network.
   2. Each existing key becomes the signer of its smart wallet. Holdings stay where they are.
   3. Every network starts on Self-pay. You switch on a paymaster per network afterwards with **Change gas payer**.
   4. When some networks are not ready, the sheet names them. They stay on EOA wallets until they have an EntryPoint and a bundler.

6. Under the consequence line "Every wallet in the organisation moves to a smart wallet, once. It cannot be undone.", type `MIGRATE` in the field labelled "Type MIGRATE to confirm". "Start migration" stays unavailable until the field holds that word. It also stays unavailable while no network is ready for smart wallets or a relayer write has not finished. Point at the button to read which one applies. The switch would queue writes that cannot land, so the platform refuses it and spends no gas. Select **Start migration**, or "Not now" to close the sheet without a change.

The Console confirms with "Migration to smart wallets started." and closes the sheet. When the start fails, the sheet shows the reason, for example "The migration could not start. Try again.", and the organisation stays on EOA wallets. For anyone who is not an organisation owner or platform administrator, the Console hides the **Review the switch** button and the sheet. The API accepts the change from the same two roles and denies it to everyone else.

Note (The move to smart wallets cannot be undone): The platform does not accept a request to return to EOA wallets. On-chain state written for a participant, such as identity registrations and role grants, follows the address that wrote it. [Smart wallet](https://docs.settlemint.com/docs/concepts/custody-and-signing/smart-wallet) explains why a move back would strand that state.

## Shared gas wallets [#shared-gas-wallets]

A shared gas wallet is a wallet the platform runs for the organisation on one network to pay gas. Which ones are in use depends on the wallet type and the gas payer. Every other shared wallet on the network is idle.

| Wallet | What it does | In use with |
| --- | --- | --- |
| Relayer wallet | Submits and pays every write under Relayer-paid. | EOA wallets, Relayer-paid |
| Bundler wallet | Fronts the gas for every smart wallet operation and is paid back in the same transaction. | Smart wallets, Self-pay or Paymaster-paid |
| Paymaster deposit | The deposit at the EntryPoint contract that pays the bundler back. | Smart wallets, Paymaster-paid |
| Refund splitter | Catches gas refunds under Paymaster-paid and splits them between the bundler wallet and deposit. | Smart wallets, Paymaster-paid |

The **Status** column reads:

- **In use** for a wallet the current gas payer uses, and "Low" when its balance is below 0.1 of the network's currency, for example 0.1 ETH.
- **Collects refunds** for the refund splitter, where a balance is unswept refunds and zero is normal.
- **Idle** for a wallet the current gas payer does not use. It keeps its balance until it is withdrawn.
- **Not seen yet** for a wallet the gas payer uses that the platform has no record of on the network. A bundler wallet that a deployment creates is listed within seconds of the platform indexing the deployment's system.

The **Balance** column shows the balance in the network currency, or "No reading yet" when the platform has no reading, which is different from zero. On a network that charges no gas, it stays blank. The opened row shows the wallet's job, its address with a copy button and an explorer link, and a note: "Top-up level `<amount>`." for a paying wallet, "Holds refunds that have not been swept yet." for the refund splitter, or "Left over from an earlier mode." for an idle wallet that still holds a balance.

An opened relayer row also shows "Last balance increase seen": the time the platform's read saw the balance rise, not the time the transfer was mined. The other wallets never show it, because bundle refunds raise their balances.

Every 30 minutes on a smart-wallet network that charges gas, the platform checks the bundler wallet against a top-up level it sizes from the network's live fee quote. The level is the gas ceiling of one bundle, times the maximum fee per gas the network quotes, times the custody provider's reserve multiple: 3 for Fireblocks, 4 for Ripple and 1 for the others. It never exceeds 10 of the network's currency. Below a fifth of that level, the platform refills the wallet from the refund splitter to the level, or to more, up to 10, when pending operations reserve more. When the network has no fresh fee quote, the check waits for the next run instead of guessing an amount.

The page does not list wallets that deployment configuration names for platform tasks. [Operator wallet](https://docs.settlemint.com/docs/concepts/custody-and-signing/operator-wallet) covers those.

## Size a top-up [#size-a-top-up]

When a request is open, send at least the amount the sheet names as needed. The recommended amount also covers fee changes before the transfer lands. [Operator wallet](https://docs.settlemint.com/docs/concepts/custody-and-signing/operator-wallet) covers how a funding requirement calculates it.

Without an open request, the sheet suggests the amount that covers the organisation's warning days at the last seven days' rate of reserve spend, as "About `<amount>` covers `<days>` more days at last week's rate." For example, with a warning at 14 days and 0.07 of the native currency spent over the last week, it suggests about 0.14. With no spend recorded, it shows no suggestion. The warning days are the [gas tank alarms](#set-gas-tank-alarms).

Check this page at least once per funding window, 30 minutes by default, rather than after a write fails. A wallet that empties pauses the work it pays for, and that work resumes once the wallet is funded, but only inside the funding window.

## Choosing how to respond [#choosing-how-to-respond]

Check the latest balance, the wallet's job, and any open request before you fund a wallet that reads **Low**.

| Response | When it is right | What it costs |
| --- | --- | --- |
| Top up now | The wallet needs currency for its expected work. | The transfer fee. Paused work resumes once the platform observes the funding. |
| Wait for a transfer already sent | A top-up you sent is still unconfirmed on the network. | Part of the funding window. Work still waiting when it closes fails with `DALP-9087`. |

Note (A Low status is not the alert firing): The paging alert compares against the same 0.1 mark, which has no deployment setting, but holds for fifteen minutes before it fires, so a brief dip that a top-up is already fixing does not page anyone. Treat **Low** on this page as your earliest signal.

## What the platform does on the wallet type switch [#what-the-platform-does-on-the-wallet-type-switch]

Before the switch, the platform grants each smart wallet the on-chain roles its signing wallet holds. When roles have drifted and you do not hold the system admin role, the platform stops the switch and the failure names the smart wallets that need the grant.

The platform also registers each smart wallet under the identity its signing wallet holds.

When none of a person's custody accounts is registered and their identity is registered only on another wallet of theirs that no custody account holds, the platform registers that person's smart wallet under that identity, using the custody account that controls it, or, before it exists, their primary custody account, or their only one.

When those other wallets hold more than one identity, the platform cannot choose one, so it stops the switch before any write and the failure names the participant and the identities. Have an identity manager remove the wrong registration with **Remove registration** on the participant's page, then start the switch again.

When the organisation paid gas through the relayer on a network, the relayer stops paying for new writes and keeps its balance. It shows as **Idle** in the "Wallets" table, where the Permission manager role can withdraw the balance.

A write from an EOA wallet that was queued before the switch still goes through the relayer, and the relayer pays its gas. This covers a write that waits for its wallet checker across the switch. A write queued after the switch follows the network's new gas payer. Keep enough in the relayer for those queued writes before you withdraw its balance.

## After the migration [#after-the-migration]

The **Wallet type** row shows a lock and "Smart wallets", with "Applies to every wallet in the organisation, on every network." and "Since `<date>`. This cannot be switched back." When the date is unknown, it reads only "This cannot be switched back." Gas is set per network with "Change" on the "Gas payer" row. The row names any active network that has no EntryPoint yet, where wallets stay EOA wallets, and counts the networks ready for smart wallets, for example "2 of 3 networks ready for smart wallets". A "Deployment" row shows a progress bar of deployed smart wallets for each network that reports them. The comparison table is part of the migration sheet and is not shown after the switch.

Under **Deployment**, one line per active network shows how many of the organisation's smart wallets are deployed on that network, for example "Polygon Amoy: 3 of 5 smart wallets deployed". A smart wallet counts when it belongs to a participant that a member of the organisation acts as, or to one of the organisation's own participants. It counts as deployed once the platform has seen the wallet created on the network. A network with no smart wallets yet has no line.

### Tokens needing role migration [#tokens-needing-role-migration]

For the network selected in the "Network" submenu, the page lists tokens whose participants still hold roles on their signing addresses rather than on their smart wallets. The section is titled **Tokens needing role migration** and says "These tokens have participants whose signing-address roles haven't been migrated to their smart wallets. Each token's admin must run the migration from the token's page." Its columns are "Token", "Symbol", hidden until you add it, "Affected participants" and "Token admins". When no token needs a role migration, the page does not show this section.

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

- **A top-up:** after it confirms on the network, the sheet reads "Deposit received.", and the wallet's balance and status update on the page. A request the top-up covers leaves the page, and writes that waited on it continue.
- **A withdrawal:** it lowers the wallet's balance by the amount sent and shows on the transactions page.
- **A gas payer change:** the "Gas payer" row shows the new payer for the selected network. When the organisation uses more than one network, select another network in the "Network" submenu to confirm that its gas payer did not change.
- **The wallet type switch:** the "Wallet type" row reads "Smart wallets" with the date it started, and the "Gas payer" row of each ready network reads that each smart wallet pays its own operations until you choose "Paymaster-paid" for it.
- Check transaction outcomes in [Activity](https://docs.settlemint.com/docs/console/essentials/activity): a funded wallet does not confirm that a specific transaction settled.

## Troubleshooting [#troubleshooting]

**The balance has not changed after a top-up**

Confirm that the transfer used the address and network the sheet showed, then wait for its on-chain confirmation. The
platform reads the shared gas wallets' balances every few seconds, so a confirmed deposit shows within seconds. A
transfer to the refund splitter moves on to the bundler wallet and the paymaster deposit, so check those rows.

**A write failed with DALP-9087**

The network refused the write for gas and the funding window closed before the wallet was funded, or the caller
declined the pause. The error names the wallet and the shortfall. That wallet can be a participant's own wallet, which
this page does not list as a shared gas wallet. Fund it, then submit the write again.
[DALP-9087](https://docs.settlemint.com/docs/api-reference/errors) covers the error.

**User transactions wait after a switch to “Relayer-paid”**

The relayer wallet on that network holds too little to pay for them. Select **Top up** on the relayer wallet, or the
button on its notice. Waiting transactions resume once the top-up lands, within the network's funding window.

**The gas payer choices are unavailable**

With EOA wallets, the Console offers **Change** to an organisation owner or a platform administrator. With smart
wallets, the Permission manager, Gas manager or System manager role can change it. Relayer-paid works with EOA wallets
only and Paymaster-paid with smart wallets only. The [move to smart wallets](#change-the-wallet-type) cannot be
undone.

**“Withdraw” does not appear or the withdrawal fails**

**Withdraw** is in the menu of an idle relayer wallet, bundler wallet, or paymaster deposit that holds a balance, on a
network that charges gas, for the Permission manager role. The menu item says why when it is unavailable. A failed
withdrawal names its cause: the address is not a wallet the organisation pays fees from on this network, the selected
account lacks the System manager role a paymaster withdrawal needs, or the amount is more than the wallet can send
now. For the last one, go back and select "Withdraw all".

**Turning sponsorship off or rotating the signing key affects an operation already in flight**

Check the operation's status before retrying. The paymaster checks a sponsorship ticket against its current signer, so
a ticket signed with the previous key can fail if the rotation confirms first.

**The wallet type row is missing**

The deployment does not offer smart wallets, or you do not hold the Permission manager, Gas manager or System manager
role that shows Transaction funding. The row has no sidebar entry of its own. An old bookmark to the Wallet type page
opens Transaction funding.

**“Review the switch” is missing**

The button shows only to an organisation owner or a platform administrator. Ask one of them to start the migration.

**“Start migration” stays unavailable**

Type `MIGRATE` exactly, in capitals. The button also stays unavailable while no network is ready for smart wallets, or
while a relayer write has not finished. Top up the relayer or cancel the write, then open the sheet again.

**The migration fails to start**

The sheet shows the reason. The platform denies the write unless you are an organisation owner or a platform
administrator. When the failure names smart wallets whose roles drifted, ask a holder of the system admin role to
start the migration. When it names a relayer write that has not finished, top up the relayer or cancel that write,
then start again. When the switch waits for its own write, start again once that write lands. When it says the
organisation's system is not indexed yet, wait until the network's system finishes indexing, then start again.

**A network still uses EOA wallets after the migration**

That network has no EntryPoint or bundler yet. Its wallets stay EOA wallets until the network is ready.

**“Wallet type could not be read”**

The row shows "Wallet type could not be read" with "The organisation's wallet type did not load. Try again." Retry
from the error card in the row.

## Frequently asked questions [#frequently-asked-questions]

### Does funding a wallet bring back a sponsored operation that already expired?

No. A sponsored operation carries its own expiry, separate from the funding wait. The platform renews an expired sponsorship on its own for a bounded number of rounds, and funding plays no part in that. An operation that still fails with an expired sponsorship needs the participant to submit it again. [What happens when a wallet empties](https://docs.settlemint.com/docs/concepts/custody-and-signing/operator-wallet#what-happens-when-a-wallet-empties) explains when renewal applies.

## API routes [#api-routes]

The Platform API reads and changes the same funding state. A system route acts on the organisation's default network unless the request sends `X-Chain-Id` with another chain ID. Amounts are decimal strings in wei, the currency's smallest unit.

| Task | Route |
| --- | --- |
| List funding requirements | `GET /api/v2/organizations/funding-requirements` |
| Read whether a write waits for funds | `GET /api/v2/transaction-requests/{transactionId}` |
| Follow a write as it pauses and resumes | `GET /api/v2/transaction-requests/{transactionId}/stream` |
| Read the bundler wallet's balance | `GET /api/v2/system/bundler/balance` |
| Read a paymaster deposit | `GET /api/v2/system/paymasters/{address}/balance` |
| Deposit into the paymaster from your account | `POST /api/v2/system/paymasters/{address}/deposits` |
| Read how much a payer wallet can withdraw | `GET /api/v2/system/payers/{address}/withdrawable` |
| Withdraw from a payer wallet or paymaster deposit | `POST /api/v2/system/payers/{address}/withdrawals` |
| Change the gas payer with EOA wallets | `PUT /api/v2/organizations/networks/gas-payer` |
| Turn sponsorship on or off with smart wallets | `PUT /api/v2/system/paymasters/config` |

[How gas is paid and funded](https://docs.settlemint.com/docs/concepts/custody-and-signing/gas-funding#fund-through-the-api) describes what each route returns and how to decline the funding pause. The request and response fields of each route are in the [v2 API reference](https://docs.settlemint.com/docs/api-reference/v2), under Transaction funding, Transactions and Organisation deployment.


# Webhooks

Source: https://docs.settlemint.com/docs/console/organisation-settings/webhooks
Create webhook endpoints, choose their events, and inspect, resend and replay their deliveries in the Console.

Webhooks creates webhook endpoints and shows the delivery history of each one. An endpoint is an HTTPS address on one of your systems, the consumer, and the platform sends it the organisation's platform events, such as a confirmed token transfer, as signed POST requests. The signature lets the consumer verify that a request came from the platform.

Configure an endpoint when another system needs to react to the organisation's platform events. An endpoint receives only the events that happen after it was created. To build the consumer, with its headers, signature check and event catalogue, see [Receive DALP webhooks](https://docs.settlemint.com/docs/api-reference/guides/webhooks) and the [webhooks reference](https://docs.settlemint.com/docs/api-reference/webhooks).

![Webhooks page with delivery health cards, the hourly deliveries chart and the endpoints table](https://docs.settlemint.com/docs/screenshots/console-organisation-webhooks.light.en.webp)

[Screenshot] The "Webhooks" page opens with four cards, then the "Deliveries per hour, all endpoints" chart, then a table of endpoints.

The four cards are "Endpoints", "Deliveries (24h)", "Success rate (24h)" and "Failing endpoints". Each endpoint row shows its "Status", "Listening to" and delivery counts. **Create endpoint** sits at the top of the page.

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

- You need the Owner role in the active organisation, or platform administrator access.
- The Webhooks entry appears under Infrastructure only for those roles.
- Webhook management uses organisation permissions, not an on-chain contract role.
- A platform administrator can create and edit endpoints, full payloads included, in whichever organisation is active, and each change is recorded in that organisation's Audit trail.
- Endpoints belong to the active organisation, so confirm you are in the right one before creating or reviewing one.

## Steps [#steps]

### Select Create endpoint [#select-create-endpoint]

At the top of the page, select **Create endpoint**.

### Enter the URL [#enter-the-url]

Enter the **Endpoint URL** and, optionally, a "Display name" of up to 80 characters. The "Display name" field counts the characters as you approach that limit, and refuses a longer value instead of cutting it. The URL must use https and resolve to a public address unless the deployment operator has trusted it. A plain http:// URL that the operator has not trusted is refused under the field with "This server only accepts endpoint URLs that start with https://", and nothing is created. When the deployment runs a built-in test receiver, "Use the DALP test receiver" fills in its address. That receiver answers 200 and stores nothing, so you can watch deliveries before your own consumer exists.

![Create webhook endpoint sheet with the endpoint URL, display name and event subscriptions](https://docs.settlemint.com/docs/screenshots/console-webhooks-create-endpoint.light.en.webp)

[Screenshot] The "Create webhook endpoint" sheet, with the "Endpoint URL" field and "Use the DALP test receiver" under it, an optional "Display name", and the "Subscriptions" the endpoint receives.

### Choose subscriptions [#choose-subscriptions]

Under **Subscriptions**, choose which events the endpoint receives. The checkboxes `*.pending`, `*.provisional`, `*.final` and `*.retracted` match the last part of an event name, and the form starts with `*.provisional`, `*.final` and `*.retracted` selected. `transaction.request.*` sends the five transaction request events and starts unchecked. A retracted event needs the state it retracts: if you select `*.retracted`, also select `*.pending`, `*.provisional` or `*.final`, or the platform refuses to save the endpoint.

The state checkboxes skip every event whose name ends in another word, such as `funding.requirement.raised`, `token.corporate-action.announced` or `operations.case.opened`. [Subscriptions](https://docs.settlemint.com/docs/api-reference/webhooks/subscriptions#events-the-default-subscriptions-do-not-deliver) lists every event they skip. To receive those, add them in **Event names**: search the published event catalogue, pick a family prefix, or type an exact name or a prefix such as `token.corporate-action.*`. The sheet refuses a name that matches no published event.

A broad subscription such as `*` also receives event types the platform adds later, and it sends every event the organisation produces to that URL, so the consumer must filter on its side. A narrow subscription keeps delivery volume down, but each new need means editing the endpoint's subscriptions, and an edit replaces the whole list.

### Save the signing secret [#save-the-signing-secret]

Create the endpoint, then copy the signing secret, which starts with `dalp_whsk_`, from the "Save this signing secret now" dialog before you select **I've saved it**. The Console cannot show the secret again, and your consumer needs it to verify the signature on every delivery.

## Review deliveries [#review-deliveries]

The page shows delivery health across all endpoints for the last 24 hours. It loads the first 100 endpoints and says so when more exist. The list shows each endpoint with "Endpoint", "Status", "Listening to", "Success (24h)", "Delivered", "Failed" and "Last delivery", and the "URL" column is hidden by default. "Listening to" counts the event patterns the endpoint subscribes to, such as "1 pattern" or "3 patterns". Hover the count to read the patterns.

**Status** reads "Enabled", "Recovering", "Auto-disabled" or "Disabled".

Open an endpoint. The header holds the "Send test event" and "Edit" buttons and the **Actions** menu, which repeats both and adds "Replay events", "Roll secret", "Disable" or "Enable", and "Delete".

**Overview** shows the last 24 hours as the cards "Deliveries (24h)", "Success rate (24h)", "Response time (24h)", "Waiting" and "Test deliveries (24h)", with two delivery charts. "Response time (24h)" is the median time the consumer took to answer, with a line beneath it that gives the time 95 percent of attempts stayed within. "Waiting" counts the events queued or waiting to retry, up to 10,000: a larger backlog reads "10,000+". Test deliveries are counted apart and stay out of the success rate.

**Endpoint details** shows the "ID", "URL", "Listening to", "Payload" shape, whether "Signed receipts" are required, the "Event schema version", the "Signing secret" version, the "Breaker" state, "Failures in a row:" and "Created". The circuit breaker switches the endpoint off after 30 failed attempts in a row.

**Event deliveries** lists one row per event with its attempts nested under it, in the columns "Status", "Event", "Event ID", "Attempts", "Last response", "Response time", "Next retry" and "Time". A "Live" indicator shows new events as they arrive, and "Load older" reads earlier ones.

The **Status** filter narrows the list to "Delivered", "Failed", "Retrying", "Pending" or "Cancelled" events. "Response time" shows the time of each event's latest attempt, and an attempt with no recorded response time shows a dash.

When the endpoint requires signed receipts, **Receipts** lists each stored receipt with its "Verification" result.

Click an event to open its **Webhook event** sheet. It shows each attempt with its request, response and timings. It also shows the event's "Chain of custody": one entry, called a hop, for each successful delivery, named "Sent to endpoint" with a hash of the exact body sent, and a "Root hash" computed over those hashes. [Delivery statuses](#delivery-statuses) explains each status.

## Send a test event [#send-a-test-event]

A test event is marked "test", reaches the endpoint even while "Enabled" is off, and never moves the circuit breaker. Each API server accepts at most 10 test events a minute for an endpoint, and at most 100 for an organisation. Confirm that its row in **Event deliveries** reaches "Delivered" with a 2xx response from your consumer.

## Resend a failed event [#resend-a-failed-event]

For one failed event, open its "Webhook event" sheet and select **Resend**. The platform adds one attempt to the same event with the same event ID, and earlier attempts keep their recorded outcome. Only the latest attempt of an event can be resent.

## Replay events [#replay-events]

To send past events again, choose **Replay events** in the "Actions" menu. The sheet offers two kinds of replay:

- **Block range** replays every event recorded for this endpoint in a range of blocks on the active network. Leave "To block" empty to replay up to the latest block with a recorded event. A range of more than 10,000 blocks asks you to confirm with "Replay anyway".
- **One event** replays one event from the endpoint's recent deliveries.

Each replayed event gets a new event ID and is marked as a replay, so the consumer must deduplicate it on its payload identifiers rather than on the event ID. The platform refuses a replay while the endpoint is switched off or its circuit breaker is open, and an organisation can start at most 10 replays a minute on each API server. When the limit is reached the sheet reads "Replays are limited to 10 a minute: continue in a minute."

On an endpoint whose breaker opened, a callout on "Overview" titled "DALP disabled this endpoint after repeated failures" offers **Reactivate and replay failed events** with the count of failed events. While the platform probes the endpoint it reads "DALP is probing this endpoint before it resumes deliveries". The button reads "Reactivate" when no failed event is left to replay and "Replay failed events" with a count once the endpoint is enabled again.

## Edit an endpoint [#edit-an-endpoint]

Select **Edit**. The "Edit endpoint" sheet reads "Change where events go, which events are sent, and how they are signed." It holds:

- **URL**: if deliveries are waiting, a dialog asks before they go to the new URL.
- **Subscriptions**: which events the endpoint receives.
- **Payload**: "Thin" leaves out the fields the event catalogue marks as personal data, such as a transfer's `from` and `to` addresses. Amounts, token addresses and transaction hashes stay, and a transaction hash identifies the addresses on the network. "Full" includes personal data and needs the GDPR acknowledgement. Choosing it opens "Switch to fat events", which lists every field that leaves DALP, and you confirm with "Acknowledge, switch to fat events".
- **Require signed receipts**: the endpoint must answer each delivery with a signed receipt. "Receipt timeout" sets how many seconds, from 1 to 60, the platform waits for a receipt before it marks the attempt as timed out and retries the event.
- **Enabled**: disabling cancels the deliveries still queued for the endpoint, and events that happen while it is disabled are not sent later.

Save the sheet. The Console confirms **Endpoint saved**. An edit of the subscriptions replaces the whole list.

If the endpoint changed after the sheet loaded it, the platform refuses your save, changes nothing, and the sheet shows "This endpoint changed while you were editing". Any saved change triggers this: an edit by another administrator or by you in another tab, "Actions" › "Disable" or "Enable", or an update through the Platform API. Rolling the secret, or the circuit breaker switching the endpoint off or back on, does not.

The [Audit trail](https://docs.settlemint.com/docs/console/reporting/audit-trail) shows who changed the endpoint and its old and new values. Reloading replaces the edits you made in the sheet, so note the ones you want to keep first. Select **Reload the saved endpoint**. The sheet stays open with the endpoint as it is stored now. Make your changes again and save.

## Roll the signing secret [#roll-the-signing-secret]

Choose "Actions" › **Roll secret**.

In the "Rotate signing secret" sheet, select **Rotate**. The new signing secret, which starts with `dalp_whsk_`, appears once in the "Save this signing secret now" dialog: copy it before you select "I've saved it", because the Console cannot show it again and the dialog stays open until you confirm. Rotation keeps the previous secret valid for 24 hours, and the platform signs each delivery with both secrets during that overlap. The "Previous secret" is retained only during the rotation overlap. A "Needs test" or "Safe" badge shows whether a delivery signed with the new secret has succeeded.

**Revoke previous now** ends the overlap early, but only after a delivery signed with the new secret has succeeded: send a test event under the new secret first. The previous secret then reads "Revoked".

## Disable or enable an endpoint [#disable-or-enable-an-endpoint]

Choose "Actions" › **Disable**. The dialog titled "Disable" followed by the endpoint's name reads that new events skip this endpoint while it is disabled and are not sent later, and that deliveries still queued for it are cancelled. Enabling it again only delivers events that happen after that. The Console confirms "Endpoint disabled".

Choose "Actions" › **Enable** to switch it on again, and the Console confirms "Endpoint enabled".

## Delete an endpoint [#delete-an-endpoint]

Choose "Actions" › **Delete**. The dialog "Delete this webhook endpoint?" reads that the endpoint stops receiving deliveries, including retries already scheduled, and that its delivery history stays available for the retention period. Select "Delete", or "Cancel" to keep it. The Console confirms "Endpoint deleted".

## Delivery statuses [#delivery-statuses]

The platform records an event for each endpoint whose subscriptions match it. It retries a failed delivery for up to three days from when it recorded the event, with exponential backoff and jitter: each wait roughly doubles, with a random spread so that failing endpoints do not retry in step.

HTTP 408, 429 and 5xx responses, redirects and connection failures are retried, and a retryable failure moves the event to "Retrying". Any other 4xx response stops delivery of that event. A terminal failure, or the end of the three-day retry window, moves the event to "Failed". A 2xx response moves the event to "Delivered" unless the endpoint requires signed receipts.

On such an endpoint, a receipt that does not arrive in time moves a delivered event back to "Retrying", and a receipt whose hash does not match moves it to "Failed". An event appears in **Event deliveries** once the outcome of its first attempt is recorded, and an event still waiting when you turn off or delete its endpoint shows as "Cancelled".

[Figure] The delivery statuses of one webhook event. The platform records an event for an endpoint whose subscriptions match it and attempts delivery. The event is listed once the outcome of an attempt is recorded. A 2xx response delivers it, unless the endpoint requires signed receipts and the receipt fails. A retryable failure moves the event to Retrying until the next attempt. A terminal failure, or the end of the retry window, moves it to Failed. An event still waiting when its endpoint is disabled or deleted is Cancelled. Labels: retryable; failure; next; attempt; terminal; failure; window; ends; endpoint; disabled; Event recorded; Start; Matches a subscription; Attempt; Listed once its; outcome is recorded; Delivered; 2xx response, unless a; required receipt fails; Cancelled; Endpoint disabled or; deleted while it waits; Retrying; Waits for a backoff; with jitter; Failed; Terminal failure, or; the retry window closed.

A webhook event ends as Delivered, Failed or Cancelled, or waits as Retrying, depending on the response, the retry window and its endpoint.

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

- Select **Send test event** and confirm that its row in "Event deliveries", marked "test", reaches "Delivered" with a 2xx response from your consumer. For a retryable failure, the first retry waits about 30 seconds and later waits double. Check a terminal failure directly instead of waiting for another attempt.
- If the endpoint requires signed receipts, confirm the receipt as well as the HTTP response: **Receipts** on the "Event deliveries" tab shows whether each receipt verified.
- The organisation's [Audit trail](https://docs.settlemint.com/docs/console/reporting/audit-trail) records each of these changes with your name and role at the time: creating an endpoint, every edit with its old and new values, deleting an endpoint, rotating a secret and revoking the previous one, and each test event, resend and replay request. An edit entry covers the URL's origin, subscriptions, payload shape and acknowledged personal-data fields, signed receipts and whether the endpoint is enabled. The trail does not record individual delivery attempts. The endpoint's own **Event deliveries** tab holds those.

## Troubleshooting [#troubleshooting]

**The signing secret was not saved**

Choose "Roll secret" in the endpoint's "Actions" menu, then **Rotate** in the "Rotate signing secret" sheet. Copy the
new secret from the "Save this signing secret now" dialog before you select "I've saved it".

**A rotated secret breaks signature verification**

Rotation keeps the previous secret valid for 24 hours, and the platform signs each delivery with both secrets during
that overlap, so a consumer that still verifies with the old secret keeps accepting deliveries. Update the consumer to
the new secret before the 24 hours end. **Revoke previous now** ends the overlap early, but only after a delivery
signed with the new secret has succeeded: send a test event under the new secret first.

**An event never arrived and deliveries have stopped**

Check the event's age against the three-day retry window. Once an event passes that window, or once a delivery fails
in a way the platform treats as non-retryable, the platform stops automatic attempts. Read the last failure in the
"Webhook event" sheet, fix the consumer, then use **Resend** or "Replay events".

**Deciding how broadly to subscribe an endpoint**

A broad subscription such as `*` never needs revisiting when the platform adds an event type the consumer should know
about. It sends every event, so the consumer must filter on its side. A narrow subscription keeps delivery volume
down, but each new need on the consumer side means editing the endpoint's subscriptions. An edit replaces the whole
list.

**The endpoint shows Auto-disabled**

After 30 consecutive failed attempts, the platform opens the endpoint's circuit breaker and switches the endpoint off.
Events that happen while it is off are not queued for it, and no replay can recover them later. The platform probes
the endpoint and resumes deliveries on its own after two successful probes. The endpoint then reads "Recovering" until
the next delivery succeeds. To resume at once, fix the consumer, then select **Reactivate and replay failed events**
on the endpoint's "Overview" tab. It re-enables the endpoint and replays up to 10 of the failed events loaded in
"Event deliveries". Use "Replay events" for the rest.



# Agents

Source: https://docs.settlemint.com/docs/console/participants/agents
Create software agents that act for the organisation inside a mandate the chain enforces, change or revoke a mandate, and halt every agent at once.

An agent is software that acts for the organisation without a person approving each step. A payout run for coupons and dividends is one example. Each agent acts inside a mandate that the chain enforces: the contracts and functions it may call, the most it may move of each metered asset in one transaction and in one period, and the date the mandate ends. The agent signs with a managed custody key that the platform holds, and only an organisation owner creates agents and changes their mandates. A mandate does not restrict recipients, and its ceilings meter only `transfer`, `transferFrom` and `approve` on the assets it lists. [Agents and mandates](https://docs.settlemint.com/docs/concepts/custody-and-signing/agent-mandates) explains what the chain refuses and how the starter mandate is set.

Each row on the list is one agent. The list opens with the newest agent first, shows 20 agents per page, and refreshes on its own while an agent reads **Setting up**. "Search agents" filters it. Opening a row opens the agent's page, where the owner reads the mandate and the limits used this period, replaces the mandate, manages the roles of the agent's account or revokes the agent. The foot of the list holds "Halt all agents", the organisation's kill switch, which revokes every agent at once.

![The Agents page before any agent exists, with the Create agent button, No agents yet and the Halt all agents control](https://docs.settlemint.com/docs/screenshots/console-agents.light.en.webp)

[Screenshot] The "Agents" page before any agent exists, with "Create agent" in the header.

The page describes itself as "Agents act for your organisation inside a mandate that the chain enforces. Only owners create agents and change mandates." With no agent, it reads "No agents yet" and "Create an agent to let software run coupon and dividend payouts within limits you set." The "Halt all agents" control sits below. Once an agent exists, the table, searched with "Search agents", shows "Name", "Status", "Account", "Created" and "Revoked".

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

- **Your wallet verification.** Creating an agent, replacing a mandate, revoking an agent and halting or resuming all agents each ask for your wallet verification before the change is sent.
- **The halt is off.** While all agents are halted, "Create agent" is unavailable and the page says "Turn off the halt to create agents." [Halt all agents](#halt-all-agents) shows how to turn it off.
- **The mandate you want.** Decide which contracts and functions the agent needs, which assets it may move, the ceiling for one transaction and for one period, and the date it should stop. The sheet starts from a starter mandate for coupon and dividend payouts that you review and change.
- **A reason, for revoking and halting.** Revoking an agent and halting all agents are final for the agents they stop, and both ask for a reason of up to 500 characters. To stop one agent, revoke that agent instead of halting all of them.

## Steps [#steps]

### Open the Create agent sheet [#open-the-create-agent-sheet]

Select **Create agent**. The sheet opens with an "Agent name" field and the starter mandate the platform proposes. While the proposal loads, the mandate area shows a placeholder. Reading the proposal creates nothing.

### Name the agent [#name-the-agent]

Enter the **Agent name**, up to 120 characters. The sheet shows "Enter a name for the agent." until you do.

### Review the mandate [#review-the-mandate]

The mandate editor holds four settings. Change what the agent should not get, and add what it needs.

1. **Expires** sets the date and time the mandate ends. It must be in the future.
2. **Ceiling period** is the window the per-period ceilings count over. Choose "1 hour", "1 day" or "7 days". When you edit a mandate whose period is none of these three, the list shows its period as a fourth choice.
3. **Allowed contracts and functions** lists each contract the agent may call and, under it, the functions it may use there. The editor names the known functions, such as "Fund coupon payments", "Pay a coupon to a holder", "Declare a dividend", "Pay a dividend to a holder", "Approve spending of an asset" and "Transfer an asset", each with its own add button.

   To add a function the editor does not name, enter its 4-byte selector in "Function selector", such as `0x12345678`, and select "Add function". Select "Add contract" and enter a "Contract address" to allow another contract. Every contract needs at least one function, and the Console says "Choose at least one function for this contract." when one has none. Remove a contract with "Remove this contract".

4. **Ceilings per asset** lists each asset the agent may move. Select "Add asset", enter the "Asset address", and set the "Ceiling per transaction" and the "Ceiling per period". Both fields take the amount in your own number format, group it when you leave the field, and accept a `k`, `m` or `b` suffix such as `1.5k`. Every asset needs both ceilings.

   A ceiling limits only `transfer`, `transferFrom` and `approve` on that asset. Another function the mandate allows, such as a mint or a payout call, counts against no ceiling, so allow only the functions the agent needs.

Under the editor the footer names the first thing that blocks you, such as "Set an expiry in the future.", "Add at least one contract." or "List each contract once."

### Confirm and create [#confirm-and-create]

Continue to the confirmation, which reads "Create this agent with this mandate" and summarises the "Agent name", "Expires", "Ceiling period", the number of allowed contracts and the number of assets. Select **Create agent** and confirm with your wallet verification. The Console shows "Agent created" and opens the agent's page. A new agent reads "Setting up" until its account exists on the chain, and "Active" after that.

## Open an agent [#open-an-agent]

Select a row to open the agent's page. It has two tabs, **Overview** and "Activity log", and a status badge beside the name.

The **Overview** tab shows these cards:

- **Identity** with "Status", "Account", "Signer", "Mandate owner", "Identity", "Created" and, for a revoked agent, "Revoked" and "Revoked by". "Revoked by" reads "The kill switch of this agent" or "The kill switch of the organisation".
- **Mandate** with "Expires", "Ceiling period" and "Allowed contracts and functions". A mandate with no contract reads "The agent may not call any contract."
- **Limits this period** with, for each asset, how much the agent has used of its ceiling for the period, and its "Ceiling per transaction". When the mandate sets no asset or native ceilings, the card reads "The mandate sets no asset or native ceilings. Ceilings meter only transfers, approvals and native value. A ceiling does not meter any other call the mandate allows." The card means nothing is metered: the agent can still make every call the mandate allows.

An active agent's header also has **Manage roles** when the agent has an account and your account may grant roles. It opens the roles sheet with the agent's account already chosen. A role you grant that account lets the agent call that role's functions on any contract the mandate lists, and no ceiling meters those calls.

A notice at the top of the **Overview** tab explains an agent that is not active: "The agent is being set up", "Setting up the agent failed" or "This agent is revoked". When the chain does not answer, the page says "The mandate could not be read from the chain. Try again in a moment."

## Edit a mandate [#edit-a-mandate]

Select **Edit mandate** in the header of an active agent. The sheet reads "Replace the mandate of" the agent's name and "The new mandate applies as soon as the change lands on the chain." It holds the same editor as the create sheet, filled with the current mandate. Change it, continue to the confirmation, select "Replace mandate" and confirm with your wallet verification. The Console shows "Mandate replaced".

The new mandate replaces the old one entirely: it drops the previous allowed calls, asset rules and counters, and starts a new period count. You can replace the mandate of an active agent only.

## Revoke an agent [#revoke-an-agent]

On the "Overview" tab of an active agent, the danger row "Revoke agent" ends the agent's mandate for good. Select **Revoke agent**, enter the "Reason", and confirm with your wallet verification, or select "Keep agent" to stop. The sheet says the agent stops at once, and that revoking is final: the agent can never act again, and the only way to grant new limits is to create a new agent. The Console shows the agent's name followed by "revoked", and the agent reads "Revoked".

## Halt all agents [#halt-all-agents]

Halting is not a pause. The halt revokes every agent of the organisation that is not already revoked, and cancels each agent's transactions that are still waiting in the queue. An agent the halt revokes stays revoked after you turn the halt off, so you create each agent again with a new mandate.

To halt, select the danger row **Halt all agents** below the list, enter the "Reason", and confirm with your wallet verification, or select "Keep agents running" to stop.

While the halt is on, a banner reads "All agents are halted", with your reason and "Halted on" followed by the date, and the danger row shows "Turn off halt" instead. Select **Turn off halt**, enter the "Reason", and confirm, or select "Keep halt on" to stop. Turning the halt off lets the organisation create agents again.

## Agent statuses [#agent-statuses]

| Status | What it means |
| --- | --- |
| **Setting up** | The agent's account is being created on the chain. The page updates when the agent is ready. |
| **Active** | The mandate is on the chain and the agent can act within it. |
| **Revoked** | An owner revoked this agent, or the halt revoked it. This is final. |
| **Failed** | The agent never became active. Create a new agent to try again. |

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

- After you create an agent, its page shows the badge **Active**, and "Mandate" and "Limits this period" show the expiry, the allowed contracts and the ceilings you set.
- After you replace a mandate, the **Mandate** card shows the new values and the used amount in "Limits this period" starts again.
- After you revoke an agent, its badge reads **Revoked**, "Revoked by" reads "The kill switch of this agent", and "Edit mandate" and "Manage roles" are gone.
- After a halt, every live agent reads **Revoked** with "The kill switch of the organisation" and the banner "All agents are halted" shows on the list.

## Troubleshooting [#troubleshooting]

**“Create agent” is unavailable**

All agents are halted, and the page says "Turn off the halt to create agents." Select **Turn off halt** and confirm.
Through the Platform API, a creation while the halt is on fails with `DALP-199552`.

**The sheet does not continue**

The footer names the first problem with the mandate or the name. The Console stops an empty contract list, a contract
without a function and an asset without both ceilings. Through the Platform API, `DALP-199554` refuses an expiry that
is not in the future, a contract, asset or function listed twice, a `transfer`, `transferFrom` or `approve` on a
contract that has no asset ceiling, and any other function on an asset that has one. `data.rule` names the rule. This
is a caller error, and sending the same mandate fails again.

**An agent stays on “Setting up”**

The agent's account is still being created on the chain, and the page updates by itself. If the agent then reads
**Failed**, it never became active. Create a new agent with the same mandate.

**The mandate could not be read from the chain**

The agent is active but the chain read did not answer. Reload the page in a moment. The mandate and the limits show
again once the read succeeds.

**“Edit mandate” or “Manage roles” is missing**

Both show only on an active agent. A revoked agent, an agent that is still being set up and a failed agent have no
header actions, and the platform refuses a change to them with `DALP-199553`. **Manage roles** also needs an account
on the agent and your permission to grant roles.

**“Agents” is missing from the sidebar**

Only an organisation owner opens the page, and the platform refuses every agent route for anyone else with
`DALP-199555`. Ask an owner to make the change.

## API routes [#api-routes]

The Platform API serves the same actions under `/api/v2/agents`, and every route is owner only. `GET /api/v2/agents` lists the agents and `POST /api/v2/agents` creates one. `GET /api/v2/agents/mandate-proposal` returns the starter mandate the sheet starts from. `GET /api/v2/agents/{agentId}` reads one agent with its mandate and usage, `PUT /api/v2/agents/{agentId}/mandate` replaces the mandate, and `POST /api/v2/agents/{agentId}/revocation` revokes the agent. `GET /api/v2/agents/kill-switch` reads the halt and `PUT /api/v2/agents/kill-switch` turns it on or off. See the [API reference](https://docs.settlemint.com/docs/api-reference/v2) for the schemas.


# Entities

Source: https://docs.settlemint.com/docs/console/participants/entities
Review the identities registered in the system, register an existing on-chain identity, and accept or reject requests to register here.

Entities lists every identity registered in the system's identity registry on the active network: tokens, the system itself, contracts, smart wallets and key wallets, people's wallets included. It is also where an identity manager registers an identity that already exists, such as an investor's identity another organisation created or a participant's new wallet, in the organisation's identity registry. Registration lists a participant's wallets, under one country, in the registry that every regulated token of the organisation checks before it lets a wallet hold or move value. A person's sign-in, KYC and roles are on [Users](https://docs.settlemint.com/docs/console/participants/users), and the entity that represents your organisation holds its own KYC profile here.

Each row joins two addresses. The contract address is the account the identity belongs to: the token or system contract, or the wallet. The identity address is its on-chain identity, the separate contract that holds its claims and that the identity registry lists. **Registered** means the registry lists the identity as active. It does not mean any token accepts the entity, because each token also checks the verifications its compliance rules require, at the moment of the operation.

![Entities table with name, identity address and status columns, and two columns hidden](https://docs.settlemint.com/docs/screenshots/console-participant-entities.light.en.webp)

[Screenshot] The "Entities" page, with "Register existing identity" in the header.

The page describes itself as "Every identity registered in the system: assets and tokens, the system itself, contracts and wallets." The table shows "Name", with each entity's type under its name, then "Identity address" and "Status". The "Contract address" and "Type" columns are hidden by default, and the toolbar reads "2 hidden".

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

- **The Identity manager role.** Registering an identity, and deciding registration requests, needs the "Identity manager" role. The other roles that open the screen read the table and the entity pages. An account that holds none of them sees "Access restricted".
- **An identity that already exists.** "Register existing identity" creates nothing. To create a new participant with its own wallet and identity, use "Create participant" on "My participants", which opens the "Add participant" sheet that [My participants](https://docs.settlemint.com/docs/console/my-account/acting-as-participants) describes. To register a user of your organisation, you can also use "Register identity" on the user's page in [Users](https://docs.settlemint.com/docs/console/participants/users#register-a-users-identity).
- **The identity address.** Have the participant's identity address. A wallet or contract address does not work.
- **The country.** Have the country to record for the participant's wallets. Country allow and block lists read this registration country, not the KYC profile's country.

## Steps [#steps]

### Register an existing identity [#register-an-existing-identity]

Select **Register existing identity**. Enter the "Identity address": the identity of a participant in your organisation, or of one that asked to register here. Choose the "Country". The platform writes it to the identity registry as an ISO 3166-1 numeric code, and country allow and block lists read it when a transfer is checked. Review the summary, enter your transaction PIN or transaction code, and confirm.

![Register existing identity sheet on the Details step, with the required Identity address and Country fields, over the Entities table](https://docs.settlemint.com/docs/screenshots/console-participant-entities-register.light.en.webp)

[Screenshot] The "Register existing identity" sheet open over the "Entities" table, with two steps, "Details" and "Review".

On the "Details" step, the required "Identity address" field carries the hint "The on-chain identity contract address of the participant." and the required "Country" field carries the hint "All wallets will be registered under this country." The sheet ends with "Cancel" and "Review" buttons.

One registration covers every active wallet the participant holds on the network, its smart wallet included, under the one country you chose. The participant does not need to agree. When some of the participant's wallets are already registered here, the registration adds only the unregistered wallets bound to the participant's identity, under the same identity and the country you choose. Nothing forces that country to match the one the participant is already registered under, so choose the same one. "Accept" on a "New wallet" row fills it in for you.

### Accept or reject a registration request [#accept-or-reject-a-registration-request]

A participant that already exists, for example an investor whose identity another organisation created, can ask to register in yours. Each request shows in **Pending participant registrations** with the participant's name, kind and request date. The panel shows only to an identity manager, only while a request waits, and lists the 20 newest requests. A Canton party request shows "Canton party" and has no actions, because the registry operator approves Canton parties.

Select **Accept** to open the registration sheet with the request's identity address filled in, and the country too when the request proposes one. Choose or confirm the country, enter your transaction PIN or transaction code and confirm. The request leaves the panel once the indexed identity registry shows the identity as active. Accept needs both an identity address and a wallet address on the request.

When a registered participant adds a wallet, the panel shows a **New wallet** row that names the wallet "for an approved identity". The row has no "Reject". "Accept" opens the sheet as "Register new wallet" with the wallet named. It starts at "Review" with the identity's registered country, or at "Details" when the registry holds no country for the identity. "Register wallet" registers the named wallet and any other bound wallet of the participant that is not registered yet.

Select **Reject** and confirm to remove a request. Rejecting needs no verification code. The participant can ask again later, which reopens the same request, so a rejection only removes the request from the queue. It records no compliance decision. A direct registration of a rejected participant is refused until the participant asks again.

## Open an entity [#open-an-entity]

Select a row to open the entity. The page shows the contract address, the identity address and a registered or pending badge, with the tabs "Overview", "Verifications", "Activity log" and "Data feeds", and, on your own organisation's entity, "KYC". An identity with no linked account shows an empty "Overview", and its "Activity log" reads "No identity yet". The activity log lists the on-chain events tied to the entity's account, the registration transaction included.

To take a user's wallet out of the registry, use **Remove registration** on the user's page, which [Users](https://docs.settlemint.com/docs/console/participants/users#register-a-users-identity) describes.

## Review the verification profile of your own organisation [#review-the-verification-profile-of-your-own-organisation]

The entity that represents your own organisation has a **KYC** tab. The tab holds the organisation's KYC profile, its know-your-business record: the same field-by-field review that Users runs for a person, applied to the organisation. The tab shows only on the page of an entity whose identity address belongs to your organisation, and only to an identity manager or a verification issuer. On any other entity page the tab is absent, and opening its address directly shows the not-found page.

The profile card shows the status, the country, and the organisation details: legal name, registration number, registered address, and legal entity identifier (LEI). Legal name and registration number are required. Each field shows its review state: waiting for review, approved, or changes requested, with the name of the person who edited or reviewed it. A verification issuer reads the card. An identity manager also edits it.

1. Edit the fields and select **Save**. The saved fields wait for review.
2. Select **Approve all** to approve every field of the latest version, or "Request changes" to name the fields that need correction and write a note.
3. Read the **Version history** card below the profile for every version, the latest marked "Current", with its status and when it was created.

The person who edited a field cannot approve it or request changes on it. The Console hides "Approve all" and "Request changes" while a field you edited waits for review, and another identity manager must review it. A platform administrator who edited the field while [impersonating](https://docs.settlemint.com/docs/concepts/custody-and-signing/maker-checker#impersonated-sessions-cannot-decide) that person cannot approve it or request changes on it either. Saving an edit to an approved profile removes its approval, so the Console asks you to confirm before it saves. The edited fields then go back for review.

## Read the data feeds of an entity [#read-the-data-feeds-of-an-entity]

An entity's detail page can show a **Data feeds** tile summarising the market data feeds related to it: a "Related feeds" count and a "Last updated" time, rather than a list of the feeds themselves. A feed counts as related for one of two reasons, and the tile's count does not say which applies:

- The feed is scoped to this entity's own contract or identity address, so the feed describes the entity. This does not say who published it.
- The entity is a trusted issuer for the feed's topic, so it may attest to that kind of data even though the feed belongs to another contract.

If the count is higher than you expected, select **View feeds** to open the individual feeds it covers, since a trusted-issuer relationship can inflate the count without this entity publishing anything itself. "Last updated" is a single aggregate: the most recent publish time across every related feed, or "Never" when none of them has published yet. The tile shows a "No data feeds configured" state when no feed relates to the entity, or when the deployment has no feeds directory installed.

## Columns in the Entities table [#columns-in-the-entities-table]

The table opens with the most recently registered identities first.

The **Type** column reads "Token", "Asset", "Bond", "Equity", "Fund", "Deposit", "Stablecoin", "Real Estate", "Precious Metal", "System", "Smart wallet", "Operator wallet", "Wallet" for a key account, or "Contract". In the "Name" column, each entity's type shows under its name. An entity with no name shows its address in its place.

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

- Find the participant in the table and confirm its status reads **Registered** and the identity address matches the one you registered.
- On a user's own page, the header reads "Identity registration: registered". Then check the verifications the target token requires, on [Verify a participant](https://docs.settlemint.com/docs/console/participants/verify-a-participant), because registration alone does not make the participant eligible.

## Troubleshooting [#troubleshooting]

**No participant found at this address on this chain**

The address you entered is not the identity of a participant on the active network, or the identity belongs to a
participant that is not in your organisation and has no pending request to register here, for example one you
rejected. Check that you entered the identity address, not the participant's wallet or contract address, and that the
active network is the one the participant's identity lives on. A rejected participant asks to register again first.

**The registration is refused as already registered**

Every wallet of the participant is already registered in this organisation. Nothing is left to register. When the
participant added a wallet, its request shows as a "New wallet" row in **Pending participant registrations**.

**The new wallet is not bound to the identity**

The platform refuses with `DALP-12402` when no new wallet of a registered participant is bound to its identity. Retry
once the participant adds the wallet's key to its identity.

**The registration is refused for a participant you rejected**

After a rejection, a direct registration of that participant is refused until the participant asks to register again.
Its new request then appears in **Pending participant registrations**.

**“Accept” is unavailable on a request**

The request carries no identity address or no wallet address, and the row says "The request has no identity yet, so
there is nothing to register." Ask the participant to complete its identity first. **Reject** stays available.

**The KYC tab is missing**

The tab shows only on the entity that holds your organisation's own identity address, and only to an identity manager
or a verification issuer.

**“Approve all” or “Request changes” is missing or refused**

The buttons do not show while a field you edited waits for review: ask another identity manager. When the Console says
the profile changed, reload the page and review it again.

**Registered, but a token still refuses the entity**

Registration does not make a participant eligible. Open [Verify a
participant](https://docs.settlemint.com/docs/console/participants/verify-a-participant) and confirm the identity holds the verifications the
token requires, from an issuer the token trusts.



# Organisation participants

Source: https://docs.settlemint.com/docs/console/participants
The Organisation participants group of the Console sidebar: who signs in, which identities are registered, what KYC collects and which agents act.

The **Organisation participants** group holds the organisation's users, with their verifications, wallet restrictions and identity insights. It also holds the identities registered in the system under "Entities", the "Profile sections" every member's KYC profile collects, and the software "Agents" that act within a mandate, the on-chain limit on what an agent may call and move.

The organisation owner manages invitations, wallet restrictions and agents. "Users", "Entities" and "Profile sections" open from an on-chain system role, such as Identity manager, which a Permission manager grants in [Roles and permissions](https://docs.settlemint.com/docs/console/organisation-settings/admins-and-roles). The Owner role grants no on-chain role.

Verifying a participant and restricting a wallet start on a user's page, so their pages follow "Users". To act for a participant, use [My participants](https://docs.settlemint.com/docs/console/my-account/acting-as-participants) in the account menu.


  - [Users](https://docs.settlemint.com/docs/console/participants/users): Invite or create the people who sign in, and check their wallet, KYC and eligibility.
  - [Verifications](https://docs.settlemint.com/docs/console/participants/verify-a-participant): Confirm a participant is registered, add the verification a token needs, check a transfer.
  - [Wallets](https://docs.settlemint.com/docs/console/participants/restrict-a-wallet): Freeze a wallet on every token where you are Custodian, record why and lift it later.
  - [Insights](https://docs.settlemint.com/docs/console/participants/insights): Read identity and verification counts for the organisation and network you selected.
  - [Entities](https://docs.settlemint.com/docs/console/participants/entities): Review the identities registered in the system and register an existing on-chain identity.
  - [Profile sections](https://docs.settlemint.com/docs/console/participants/profile-sections): Choose which fields every member's KYC profile collects, and order or retire sections.
  - [Agents](https://docs.settlemint.com/docs/console/participants/agents): Create software agents inside a mandate the chain enforces, and halt every agent at once.



# Insights

Source: https://docs.settlemint.com/docs/console/participants/insights
Read identity and verification counts for the selected organisation and network, and open the participant record for one participant's state.

Insights is a read-only dashboard on a tab of **Users**, next to "Users" and "Invitations". It counts the on-chain identities of people in the registry of the current organisation and network (contract and token identities are not counted), counts the verifications issuers have signed for those identities, and charts how both moved over time. Use it for a trend or a total, such as whether pending registrations are growing or how many verifications the organisation has issued.

Reading the page changes nothing. For one participant, open their record under [Users](https://docs.settlemint.com/docs/console/participants/users) or [Entities](https://docs.settlemint.com/docs/console/participants/entities): an aggregate shows that something changed, not which participant changed or why.

![Identity insights with the range controls, key figures, attention counts, composition, trend and map](https://docs.settlemint.com/docs/screenshots/console-participant-insights.light.en.webp)

[Screenshot] Identity insights opens with the range dropdown on "1 month" and "Compare with prior period" switched on, directly under the tabs.

Below the range controls sit the key figures "Registered identities", "Active verifications" and "Verifications per identity", then the attention counts that are not zero, here "Users pending identity registration" and "Topics with no active verification". A count of verifications revoked in the range joins them when it is not zero. Two composition bars follow, "Active verifications by topic" and "Verification status", then the "Identities and verifications" trend chart and the "Participants by country" map.

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

- **The role.** The tab opens for the "Identity manager", "Verification issuer" or "Permission manager" role. A Permission manager who is not an organisation owner and holds none of the System manager, Identity manager or Verification issuer roles has no sidebar entry here and opens the tab at `/participants/users/insights`.
- **The organisation.** Every number on the screen counts one organisation on one network. Both are chosen in the account menu, outside this screen, so confirm them before you read a figure. Every figure counts the active organisation only.
- **The network.** The network is the ledger behind the current view, and a deployment can run more than one. The same organisation can show different totals on two networks, because each network keeps its own ledger. A number that looks like it dropped can belong to a different network than the one you checked yesterday.

## Steps [#steps]

### Set the range [#set-the-range]

Pick the range in the range dropdown. Leave **Compare with prior period** on to see each figure's change against the period just before the range. [What each section shows](#what-each-section-shows) lists which figures follow the range.

### Work the attention counts [#work-the-attention-counts]

Each count opens the list where you act on it. **Users pending identity registration** opens "Users" filtered to pending registrations. The revoked count opens "Users", where each participant's verification history shows which verification was revoked and when. "Topics with no active verification" opens "Verification topics", the list of the system's topics, and its count shows in the warning colour.

The count covers enabled topics that no registered participant identity holds an active verification for, and that list does not mark which ones they are. A count of zero is not shown, and when all three counts are zero the section does not appear. A count that could not be read shows "Unavailable" instead.

### Compare the identity and verification figures [#compare-the-identity-and-verification-figures]

Read **Registered identities** against its registered share and its "not yet registered" count, then read "Active verifications" against issued and revoked. The trend chart draws registered identities across the range, and its caption states how active verifications moved over the same range. A matching fall in active verifications and rise in revoked ones is consistent with revocation, but simultaneous changes can offset each other. Inspect the verification history rather than assigning a cause from the totals.

### Investigate the participant [#investigate-the-participant]

Open **Users** or "Entities", find the participant, and read its registration status and verification history on its detail page.

## What each section shows [#what-each-section-shows]

The key figures describe the registry: how many identities exist, how many of them are registered, how many verifications are active, issued and revoked, and how many identities still wait for registration. The count revoked in the selected range sits in the attention counts. The sections go in this order:

| Section | What it shows |
| --- | --- |
| Key figures | **Registered identities** (with the registered share of every identity created and how many still wait for registration), **Active verifications** (not revoked or removed, expired verifications included, with how many were issued and revoked), and **Verifications per identity** (active verifications divided by registered identities, **coverage depth**). |
| Needs attention | Up to three counts that link to where you act on them, each shown only when it is not zero: **Users pending identity registration**, verifications revoked in the selected range, and **Topics with no active verification**. |
| Composition, as of now | **Active verifications by topic**, the five topics with the most active verifications and the rest folded into **Other**, or all six when exactly six topics have one, and **Verification status**, active, revoked and removed as shares of every verification issued. |
| Trend | **Identities and verifications**: registered identities across the range, with the prior period as a dashed line. The chart description states how active verifications moved over the same range. |
| Participants by country | **Participants by country**, active participant identities per country of residence. |

One range drives every time-based figure on the page. It opens on "1 month" and the range dropdown offers "All", "YTD", "12 months", "6 months", "3 months", "1 month", "Last 7 days" and "Last 24 hours". The range moves the key-figure deltas and trend lines, the revoked count among the attention counts, and the trend chart. It does not move the composition, the map, the users pending identity registration or the topic count: those show the registry as it stands now, which is why the composition section is labelled as of now.

**Compare with prior period** is on by default. With it on, each key figure that has a history shows its change against the period of the same length just before the range, and the trend chart draws that prior period as a dashed line. "Verifications per identity" has no history and always shows its "coverage depth" line. The "All" range has no prior period, so the toggle is turned off there and a line beside it says why. The figures refresh as new blocks confirm on the selected network. When the indexer is behind or rebuilding, a platform administrator or organisation owner sees a warning above the range that says so.

A composition with nothing to count says **No data yet** and "The breakdown appears once there is data to show." instead of drawing an empty bar. The trend chart says "No data yet" and "The chart fills in once there is activity in this range." when the range holds no data.

## Identity counts and verification counts move independently [#identity-counts-and-verification-counts-move-independently]

The identity figures count participants and where they are in registration. The verification figures count signed verifications and whether they are still in force. A participant can be fully registered with no verifications. The verification figures count only the verifications on registered identities, so an identity that leaves the registry takes its verifications out of them. **Verifications per identity** divides one group by the other, so read it as an average, never as a guarantee that every identity holds that many.

| Figure | What it counts | Rises on | Falls on |
| --- | --- | --- | --- |
| Identities created, in the detail line | The identities in this organisation's registry on the current network that are registered or still waiting for registration. | A new registration. | A removal or a wallet recovery. |
| "Registered identities" key figure | The identities the registry treats as confirmed. | A registration is confirmed. | A removal or a wallet recovery. |
| The "not yet registered" count, in the detail line | The identities the registry has recorded but not confirmed, the same state a participant's own [Identity](https://docs.settlemint.com/docs/console/my-account/onchain-identity) tab reports as **Pending approval**. | A new registration awaiting confirmation. | Confirmation, or a removal. |
| "Users pending identity registration" | The users whose registration status is **Pending registration**, the status the [Users](https://docs.settlemint.com/docs/console/participants/users) list filters on. It counts users, not identities, so it can differ from the "not yet registered" count in the detail line. | A user whose registration is pending. | The registration completes, or the user is removed. |
| "Active verifications" | The verifications that are neither revoked nor removed. | A new verification. | A revocation, a removal, or the identity leaving the registry. |
| Issued, in the detail line | The verifications held by the registered participant identities on this network: active, revoked and removed together. | A new verification. | The identity leaves the registry, through a removal or a wallet recovery. |
| Revoked, in the detail line | The verifications on those identities whose latest change is a revocation by the issuer. A revoke made without the issuer identity removes the verification instead, and it counts under "Removed". | A revocation. | The identity leaves the registry, or the same issuer issues the verification again. |

The identities-created count is always the sum of the registered and "not yet registered" identities, so the registered share is read against identities that are still in the registry. An identity that is removed, or whose wallet was recovered under a new identity, leaves all three counts together.

**Active verifications** nets out only revocations and removals. It never subtracts expiry. A verification whose expiry timestamp has passed stays in "Active verifications" until someone revokes or removes it, even though a token whose rules include "Claim expiry" already refuses the participant once that verification has expired. Read this count as how many verifications have not been revoked or removed, not as how many pass eligibility.

The revoked count does not say who revoked a verification or why. Check the participant's verification history for that.

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

- Open one participant the count includes, for example a user under "Users pending identity registration", and confirm their header reads "Identity registration: pending".
- The detail record shows the present state of one participant, and Insights shows the totals for the organisation and network.

## Troubleshooting [#troubleshooting]

**“Access restricted”**

The page shows "Access restricted" without one of the roles. Ask a permission manager for the "Identity manager",
"Verification issuer" or "Permission manager" role in [Admins and
roles](https://docs.settlemint.com/docs/console/organisation-settings/admins-and-roles).

**A chart and participant record seem different**

Confirm the organisation and network first: a different organisation or network is the first cause to rule out. Then
check the page range, and check which figure you read: issued verifications fall only when an identity leaves the
registry, while "Active verifications", the identities-created count, the "Registered identities" key figure and
"Users pending identity registration" also fall for other reasons. The detail page and the aggregate both read indexed
records, so check that the indexer is not behind before you compare them.

**“Active verifications” dropped but “Revoked” did not rise by the same amount**

"Active verifications" can drop for a reason the revoked count never includes: a removal. A removal takes the
verification off the identity rather than marking it revoked. It happens when someone revokes without the issuer
identity, from the Console's "Revoke verification", the API or the identity itself. "Verification status" shows
removals as their own share. Open the affected participant's verification history and look for a **Verification
removed** event.

**“Users pending identity registration” keeps growing and “Registered identities” does not**

A user stays pending until an identity manager registers their identity, from **Register identity** on the user's page
or by accepting their request on [Entities](https://docs.settlemint.com/docs/console/participants/entities). Nothing on this page moves it along.
Open "Users" filtered to pending registrations and register each identity, or check "Pending participant
registrations" on "Entities".

## Frequently asked questions [#frequently-asked-questions]

### Why is there no organisation or network switcher visible on this page?

The account menu button at the top right names the active organisation when the top bar is wide enough, but the menu only offers a choice when there is something to switch to. It shows an Organisation submenu only for an account that belongs to more than one organisation or may create one, and a Network submenu only when multi-network support is on and the organisation has more than one active network. A single-organisation, single-network deployment still scopes every number on this page to that one pair.

### Can I look further back than the default month?

Yes, using the range dropdown under the tabs. For a custom window it does not offer, such as a specific start and end date, query the same identity and verification statistics through the [Platform API](https://docs.settlemint.com/docs/api-reference/v2).


# Profile sections

Source: https://docs.settlemint.com/docs/console/participants/profile-sections
Choose which fields every member's KYC profile collects: create sections, add their fields, and order, retire or delete them.

Profile sections let your organisation decide which facts the KYC profile of each member collects. A "Permission manager" or "System manager" groups fields into sections and sets each field's type. For each field they also set whether it is required and whether the member or an "Identity manager" fills it in. An identity manager is the system role that reviews KYC profiles. Every member's KYC profile in the organisation then shows those sections in the order they set.

A member of the organisation is a participant, the off-chain subject that KYC data belongs to. The member fills the form in on [Profile](https://docs.settlemint.com/docs/console/my-account/profile), and a reviewer decides it from [Users](https://docs.settlemint.com/docs/console/participants/users).

Every profile holds four fixed fields, first name, last name, country and national ID, and then the sections in your order. One section, Identity details, comes from the platform with a **DALP Library** badge: you cannot edit it, but you can retire it for your organisation.

![Profile sections list with the DALP Library Identity details section, two organisation sections, and Create section](https://docs.settlemint.com/docs/screenshots/console-profile-sections.light.en.webp)

[Screenshot] A table with "Name", "Description" and "Fields" columns.

In the table, "Identity details" carries the "DALP Library" badge and has no move buttons. The organisation's own sections, here "Source of funds" and "Tax residency", end in "Move up" and "Move down" arrows. **Create section** sits above the table.

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

- Your account needs the "Permission manager" or "System manager" role. The Platform API refuses every profile section route for any other role. A compliance officer usually decides which facts to collect, an account with one of these roles enters them here, and an identity manager reviews the profiles.
- **Filled by** decides who writes a field and whether the member reads it. The member's current profile and the member's version history in the Platform API both leave out "Identity manager" values. An identity manager reading the profile sees every field.
- Decide the fields before you create them. A field locks once a participant holds a value for it, or once any KYC version in your organisation has filled it. After that you cannot remove the field, change its type or change its **Filled by** setting, which the API calls its audience. You also cannot remove one of its choices or change a "Fixed once set" field to "Managers only".

## Steps [#steps]

### Create a section [#create-a-section]

Select **Create section**. In the "Create profile section" sheet, enter a name, an optional description and an optional reason for the change, then select "Create". The platform records the reason with the change. The name is required and holds at most 255 characters. Two sections of one organisation cannot share a name, and the check ignores case. The platform refuses a duplicate with error `DALP-0463`, HTTP 409.

The platform derives the section's short name, called a slug, from the name. A name whose slug belongs to a platform section, such as Identity details, is refused. The Console shows **Section created** and opens the new section so you can add fields.

### Add the fields [#add-the-fields]

On the section page, select **Add field** in the "Profile fields" card. Enter a label and the Console builds the key from it. The key starts with a letter and holds only letters and digits. Choose the type, then set these options.

| Option | What it does |
| --- | --- |
| Type | Text, number, date, choice list, ISIN, address, basis points, percentage, currency, country, LEI, CUSIP, FIGI, amount or URL. |
| Filled by | **User** fields are filled by the member. **Identity manager** fields are filled only by an identity manager. They are hidden from the member's current profile and from the member's version history in the Platform API. |
| Required | The member must fill a **User** field before the profile can be submitted. A required **Identity manager** field does not block submission. |
| Default value | Pre-fills the field for every member. |
| Options | For a choice list, currency or country field, the allowed values, separated by commas. |
| Bounds | Text fields set **Min characters** and **Max characters**. Number, date, amount, basis points and percentage fields set a lower and upper bound. |
| Changes | **Fixed once set** cannot change after a value is saved. **Managers only** lets a saved value change and adds no limit beyond **Filled by** on who changes it. |

Select **Add field** in the sheet to store the field. The Console does not offer a storage choice, because every profile field is stored off-chain. Select a field in the table to edit it later. Change the field in its sheet and select "Save". Deleting a field cannot be undone. To remove a field nobody has filled, select "Delete field" in the same sheet and type the field key to confirm.

## Put the sections in order [#put-the-sections-in-order]

The list shows 24 sections per page in display order, with each section's name, description and field count, and leaves out retired sections. Use **Move up** and "Move down" on a section. Platform sections have no move buttons. The Console shows "Order saved". The order applies to every member's KYC profile. The buttons are off while you filter or search the list.

## Retire a section [#retire-a-section]

Open the section and select **Retire section**. For one of the organisation's own sections, the Console retires it at once, shows "Section retired" and returns to the list. The notification has an "Undo" action for 8 seconds. Undo makes the section active again, and the Console shows "Section restored". After the notification closes, only the Platform API can restore the section, with an update that sets `retired` to `false`.

A retired section keeps its name, so no other section can take that name while it is retired. Members are no longer asked for its fields, and the fields stop showing in profiles and stop counting towards a complete profile. Earlier KYC versions keep the values they recorded. The Console offers no edits on a retired section.

Retiring Identity details, or any platform section, is permanent for your organisation: neither the Console nor the Platform API can restore it. Other organisations keep the section. The Console first asks "Retire this section?". Select **Retire section** to confirm or "Keep section" to cancel. The notification that follows has no "Undo" action.

## Delete a section nobody has filled [#delete-a-section-nobody-has-filled]

Open one of the organisation's own sections and select **Delete section**. The Console deletes the section at once, shows "Section deleted" and returns to the list. The notification has an "Undo" action for 8 seconds. Undo creates the section again with the same identifier, name, description, fields and position, and the Console shows "Section restored".

If another section took the name in the meantime, Undo is refused with "A section with this name exists again. Rename that section, then restore this one." After the notification closes, the deletion is final. Platform sections have no delete action. If a participant holds a value for one of the section's fields, or any KYC version filled one, the platform refuses.

The Console then shows the platform's refusal, which tells you to retire the section instead.

## What a KYC profile holds [#what-a-kyc-profile-holds]

A KYC profile has two parts.

- **Fixed fields.** First name, last name, country and national ID are in every profile. They belong to no section, and you cannot remove or reconfigure them.
- **Sections.** Each section is a named group of fields that your organisation defines. The platform also provides one section, Identity details, which holds date of birth and residency status. It shows in every organisation with a "DALP Library" badge, and nobody can edit it. Each organisation can retire it for itself.

The platform stores every section field off-chain. It records each filled value under the section's short name and the field key, for example `identity-details.dob`. Each submitted version stays in the profile's history, so the history of what was collected stays readable. A profile is complete only when the fixed fields are filled and every required **User** field in every active section is filled. Retired sections and fields filled by an identity manager do not count.

## Section fields stay off chain [#section-fields-stay-off-chain]

Section fields never go on chain: the platform refuses a section field that asks for on-chain storage. What a regulated token reads is a verification, an issuer-signed record attached to the participant's on-chain identity. Approval does put facts derived from the profile on chain. When the identity is registered, approving the profile adds a Residence verification for the profile's country, issued by the organisation's identity. An issuer can then add a KYC verification, whose value the Console calculates from the approved profile.

When an issuer adds a verification on one of these investor topics, the platform refuses it unless the participant behind the target identity has an approved KYC profile in your organisation: KYC, AML, KYT, KYB, Qualified institutional investor, Professional investor, Accredited investor, Accredited investor verified and Regulation S. The check covers a verification the platform submits for an EVM identity and one it submits for a Canton party. When a connected [compliance provider](https://docs.settlemint.com/docs/console/compliance/compliance-providers) returns an approved verdict, the platform issues the matching verification without that check.

No contract reads the profile, because the profile stays off chain, so the platform runs this check before it submits the verification. A token accepts a valid verification from any issuer trusted for its topic on [Trusted issuers](https://docs.settlemint.com/docs/console/compliance/trusted-issuers) or on the token's own trusted issuers screen. So a compliance provider you trust for an investor topic can make a participant eligible without an approved KYC profile in your organisation. [Verify a participant](https://docs.settlemint.com/docs/console/participants/verify-a-participant) covers issuing the verification and [On-chain identity](https://docs.settlemint.com/docs/console/my-account/onchain-identity) the identity it attaches to.

## Who sees what [#who-sees-what]

A field's audience decides who fills it in and whether the member reads it. The member's current profile omits identity manager fields. The member's own version history in the Platform API omits them too, and leaves out a section that has no value left for the member to read. An identity manager who reads the member's version history receives the stored values of every field. The Console's version history does not list section values.

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

- Open **Profile sections** again. A new section appears in the list with the number of fields you added, and a retired section no longer appears.
- Sign in with a test member account of the organisation and open [Profile](https://docs.settlemint.com/docs/console/my-account/profile).
- Do not save the form in a live organisation, because a saved value locks its field.
- The KYC form shows the user fields of every active section in the order you set. It does not show fields that an identity manager fills.

## Troubleshooting [#troubleshooting]

When the platform refuses a create, save or delete, the Console shows an error notification with the platform's message. After a refused create or save, a "Reference ID" follows when the response includes one.

**The Profile sections entry is missing from the sidebar**

Your account holds neither the "Permission manager" nor the "System manager" role. An "Identity manager" does not see
the entry, and the Platform API refuses the routes for them. Ask a "Permission manager" to grant one of the two roles.

**A field is locked**

Once any participant holds a value for a field, or any KYC version filled it, the platform refuses to remove the
field. It also refuses to change its audience or type, to remove one of its choices, or to change a "Fixed once set"
field to "Managers only". Only KYC versions and values in your organisation count. The refusal is error `DALP-12112`,
named `PROFILE_SECTION_STORAGE_LOCKED`, and its `data.keys` lists the locked fields. This is a caller error, and
repeating the same change fails again. It does not mean stored values are lost. After a refused save the Console lists
the keys in the error message and disables the **Filled by** selector for those fields. Keep those fields as they are
or add a new field with the settings you want. You can still remove a field that nobody has filled.

**The platform refuses to delete a section**

The refusal is error `DALP-12151`, named `PROFILE_SECTION_HOLDS_VALUES`. A participant holds a value for a field of
the section, or a KYC version recorded one, and deleting the section would leave that value without a field
definition. Retire the section instead. Earlier versions keep its values. This is a caller error, and repeating the
delete fails again. It does not mean the delete partly ran. The section and its values are unchanged.

**The platform refuses a section name**

A name whose slug matches a platform section, such as Identity details, returns error `DALP-12140`, named
`PROFILE_SECTION_SYSTEM_SLUG_TAKEN`, and `data.slug` names the slug. Choose a name that produces a different slug.
This is a caller error, and the same name fails again. It does not mean your organisation already has a section with
that name. A name another section of your organisation already uses returns error `DALP-0463`, named
`SETTINGS_TEMPLATE_NAME_ALREADY_EXISTS`, HTTP 409. Choose a different name.

**A platform section cannot be changed or deleted**

Platform sections are shared by every organisation, so the Platform API refuses to change or delete one. The refusal
is error `DALP-12113`, named `PROFILE_SECTION_SYSTEM_READONLY`, HTTP 403. This is a caller error, and repeating the
change or delete fails again. It does not mean your role lacks a permission, which also answers HTTP 403, so match on
the error code rather than the status. Create a section of your own with the fields you need and retire the platform
section for your organisation if you do not want it.

**A section is not found**

Error `DALP-12110`, named `PROFILE_SECTION_NOT_FOUND`, means no section with that identifier is visible to the active
organisation. Sections of another organisation answer the same way. List the sections and retry with an identifier
from the list. This is a caller error, and repeating the same request fails again.

## Frequently asked questions [#frequently-asked-questions]

### Can a member see the fields an identity manager fills?

No. The member's current profile and the member's version history in the Platform API both omit identity manager fields, as [Who sees what](#who-sees-what) describes. An identity manager reading the same profile sees every field.

### What happens to values already collected when a section is retired?

Nothing is deleted. The fields stop showing on profiles and stop counting towards a complete profile. Earlier KYC versions keep what they recorded.

### Can the national ID be a configurable field?

No. First name, last name, country and national ID are fixed fields outside the sections.

## API routes [#api-routes]

The Platform API serves the sections under `/api/v2/settings/profile-sections`. The routes are list, create, read, update, delete, retire and reorder. Each needs the "Permission manager" or "System manager" role. Each field must set `storage` to `offchain` and name its `audience`. A field without `storage` is refused. A field key holds letters, digits, underscores and hyphens. The Console builds keys of letters and digits only.

The list excludes retired sections unless you filter on the retired flag, and a retired section stays readable by its identifier. An update that sets `retired` to `false` restores one of your organisation's own retired sections. See the [API reference](https://docs.settlemint.com/docs/api-reference/v2) for the schemas.


# Wallets

Source: https://docs.settlemint.com/docs/console/participants/restrict-a-wallet
Freeze a wallet on every token it holds here where you are Custodian, record why, and lift the restriction when the review or order ends.

A wallet restriction freezes one wallet, in one request, on every token it holds in this organisation where you hold the **Custodian** role, and stores the reason. A freeze stops the wallet from sending and receiving that token, and the balance stays where it is, except that a holder of the "Custodian" role can still move it with a forced transfer. Use a restriction when a review or an order requires a wallet to stop on the organisation's tokens, for example an anti-money-laundering (AML) review, a sanctions match or a court order.

Without a restriction you freeze the address on each token separately, from that token's **Blocklist** tab. That takes one submission per token, and a token you miss stays open to the wallet. A restriction sends all the freezes in one request with one reason, and keeps one record of the outcome on each token. One lift then releases every freeze it applied. A restriction is reversible, and neither the restriction nor the lift moves or removes tokens. [Controls that stop movement](#controls-that-stop-movement) compares it with the other controls.

![Restrict wallet sheet over a participant's Wallets tab, with the Reason picker, the Note field and the Review button](https://docs.settlemint.com/docs/screenshots/console-participant-wallet-restrict.light.en.webp)

[Screenshot] The "Restrict wallet" sheet names the wallet and warns that it "will be frozen on every token it holds in this organisation".

Its "Details" step holds a required "Reason" picker and a "Note" field with a 500-character counter. "Review" stays off until you choose a reason and, for "Other", add a note.

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

- **The Custodian role on each token.** The "Custodian" role is granted per token, from the token's own page, and the Owner role does not include it. The platform checks the role token by token: it freezes the wallet on every token where you hold the "Custodian" role and reports each other token as failed, with a code, a message and a fix. If you hold the role on none of the wallet's tokens, the Console refuses the request. [Roles and duties](https://docs.settlemint.com/docs/concepts/compliance-and-identity/roles-and-segregation-of-duties#asset-roles) lists what the role permits.
- **Who restricts in the Console.** The Console offers the restriction actions to the organisation's owner, and only the owner and platform administrators can list or read restrictions. The "Wallets" tab sits on the user's page, which also needs the "System manager", "Identity manager" or "Verification issuer" role. Any other member who holds the "Custodian" role, a compliance officer included, restricts and lifts through the Platform API or the CLI and keeps the restriction id from the first response. [API routes](#api-routes) shows the calls. Ask the owner for the list of active restrictions.
- **Your wallet verification.** The Console asks for your transaction PIN or transaction code before it sends the change. A request made with an [API key](https://docs.settlemint.com/docs/console/my-account/api-keys) skips that check.
- **The reason and the note.** A wallet has one active restriction at a time and its reason cannot change, so decide both before you start. To record a different reason later and keep the wallet stopped meanwhile, add its address to the address block list first, then lift and restrict again.
- **The network.** A restriction covers the tokens of one network, so select the network first if your organisation uses more than one.
- **The tokens it covers.** A restriction freezes the tokens the wallet holds when you run it. To also stop tokens it receives later, add its address to the address block list in [Global controls](https://docs.settlemint.com/docs/console/compliance/global-controls) as well. [Controls that stop movement](#controls-that-stop-movement) compares the four controls.

## Steps [#steps]

The Console restricts the wallet on every token it holds in the organisation. To restrict a listed set of tokens, use the Platform API or the CLI.

### Open the wallet [#open-the-wallet]

Open the user's page and select the **Wallets** tab. If you do not see it, open "More": a user's page with more than seven tabs moves one of them there. Each wallet the participant owns offers "Restrict wallet". Pick the wallet that holds the tokens: a participant can own more than one wallet, and a restriction covers only the one you pick.

### Choose the reason [#choose-the-reason]

Select "Restrict wallet" and choose the **Reason** that fits the review or order. [Reason codes](#reason-codes) lists the seven reasons. Add a "Note" of up to 500 characters when a colleague needs context to lift the restriction later, such as a case reference. "Review" stays unavailable until you choose a reason and, for "Other", add a note. The platform stores the reason and the note with the restriction and with every freeze it sends.

### Confirm with wallet verification [#confirm-with-wallet-verification]

Review the summary and enter your transaction PIN or transaction code. The platform sends one freeze for each token where you hold the "Custodian" role, and it waits for each freeze to settle on the chain before it shows the result.

### Read the result for each token [#read-the-result-for-each-token]

The Console shows **Restriction result** with the counts "Frozen", "Already frozen", "Queued", "Failed" and "Lifted", and lists every token under "Tokens" with its outcome. [Token statuses](#token-statuses) explains each outcome and what to do next. A failed token shows the code, message and fix the platform recorded.

The wallet card shows a badge that reads "Restricted: " and the reason, such as "Restricted: AML review". The badge shows whenever the wallet has an active restriction, whatever each token's outcome, so the wallet is stopped only on the tokens that read "Frozen" or "Already frozen".

## Apply a restriction again [#apply-a-restriction-again]

Select **Apply again** on the wallet card of a restricted wallet and confirm with your wallet verification. The Console sends the same reason and note for every token the wallet holds. The platform freezes the tokens the restriction does not cover yet, retries each freeze that failed, and resumes each freeze that was accepted but has not settled. Use it for a token the wallet acquired after the restriction, a "Freeze failed" token or a token that stays "Queued". For a restriction created with a list of tokens, call the Platform API or the CLI, as [API routes](#api-routes) shows.

A paused token is frozen like any other. The result flags it as `paused`, and the freeze holds when transfers resume.

## Lift a restriction [#lift-a-restriction]

Open the participant's **Wallets** tab again. A restricted wallet shows the "Restricted: " badge with its reason, and the card offers "Apply again" beside "Lift restriction". Select "Lift restriction" and confirm with your wallet verification, or select "Keep wallet restricted" to stop. The Console then lists every token with its outcome, as it did when you restricted the wallet.

The lift needs the **Custodian** role on at least one token of the restriction. Without it, the lift is refused as if the restriction did not exist, even when no token has an unfreeze left to send. The lift first sends any freeze still pending and waits for every queued freeze to settle, so a freeze that lands late cannot outlast the lift. It then unfreezes each token that shows "Frozen", which needs the "Custodian" role on that token. Two outcomes stay in place:

- A token that showed `already-frozen` stays frozen, because the wallet was frozen there before the restriction. Once the "Restricted: " badge is gone from the wallet card, you can release it with **Unblock** on that token's "Blocklist" tab.
- A token that showed `failed` has nothing to undo and does not hold the lift back.

The restriction's status turns to lifted once every freeze it applied is removed. If an unfreeze fails, the restriction stays active and the token shows "Lift failed" with the cause. If a freeze on a token where you hold the "Custodian" role is still settling after the lift waits for it, the lift sends no unfreeze, the restriction stays active and the token keeps "Queued". Apply the fix, or wait for the transaction to settle, and lift again: the platform sends only the unfreezes that are still missing.

While the restriction is active, the wallet cannot be released one token at a time. **Unblock** on the "Blocklist" tab of any token the restriction lists is refused before the PIN, and the Platform API answers an address unfreeze for that token with 409 `TOKEN_ADDRESS_RESTRICTION_ACTIVE`, naming the restriction. Lift the restriction to release the wallet. "Block" still works.

## Reason codes [#reason-codes]

The reason is a code and a note. The code is a label for your records and for filtering restrictions, and it does not change what the freeze does. The note is free text of 1 to 500 characters. It is optional for every code except `other`, which needs one.

| In the Console | Code | Use it when |
| --- | --- | --- |
| **AML review** | `aml-review` | An anti-money-laundering review of the wallet is open. |
| **Sanctions screening** | `sanctions-screening` | The wallet matched a sanctions list, or screening of it is not finished. |
| **Fraud investigation** | `fraud-investigation` | The wallet is part of a fraud investigation. |
| **Court order** | `court-order` | A court order requires the freeze. |
| **Regulatory request** | `regulatory-request` | A regulator asked for the freeze. |
| **Client request** | `client-request` | The owner of the wallet asked for the freeze. |
| **Other** | `other` | No other code fits. Describe the reason in the note. |

The single-token freeze calls accept the same optional `reason`, with the same codes and note limit. [Pause and freeze](https://docs.settlemint.com/docs/console/asset-management/manage/pause-freeze) names them.

## Token statuses [#token-statuses]

The platform decides each token's outcome on its own, so one failed token never stops the others. For each token in scope it first checks your "Custodian" role on the token. With the role, it checks whether the wallet is already frozen there. If the wallet is not, it sends the freeze and records how the transaction ends.

[Figure] The first check that applies decides each token's status. Restrict wallet applies to each token in turn. First the platform checks the custodian role on the token: without it the token is failed. With the role it checks whether the wallet is already frozen on the token: if so the token is already-frozen and nothing is sent. Otherwise it sends the freeze. A freeze the chain rejects leaves the token failed, a freeze that has not settled leaves it queued, and a freeze that settles leaves it frozen. A later lift unfreezes frozen and queued tokens, leaves already-frozen tokens frozen, and has nothing to undo on failed tokens. Labels: Restrict wallet; one reason, every token; for each token; Custodian role?; held on this token; no; yes; Already frozen?; before the restriction; yes; already-frozen; Lift: leaves it frozen; no; Send the freeze; one transaction per token; rejected; settles; not settled yet; failed; Lift: nothing to undo; frozen; Lift: unfreezes it; queued; Lift: unfreezes it.

The first check that applies decides each token's status, and a lift reverses only the freezes the restriction
applied.

| Console badge | API status | What it means | What to do |
| --- | --- | --- | --- |
| **Frozen** | `frozen` | This restriction froze the wallet on the token. | Nothing. A lift unfreezes it. |
| **Already frozen** | `already-frozen` | The wallet was frozen on the token before the restriction. The platform sends nothing for it. | Nothing. A lift leaves it frozen. |
| **Queued** | `queued` | The platform accepted the freeze, and the transaction has not settled. | Select **Apply again**. The platform resumes the accepted transaction. |
| **Freeze failed** | `failed` | The freeze did not happen. The `failure` field holds a `code`, a `message`, and a `fix`. | Apply the fix, then select **Apply again**. |
| **Queued** | `pending` | The platform recorded the token and has not sent its freeze. | Select **Apply again**. |
| **Lift queued** | `lift-queued` | The platform accepted the unfreeze, and the transaction has not settled. | Lift the restriction again. |
| **Lifted** | `lifted` | The platform unfroze the wallet on the token. | Nothing. |
| **Lift failed** | `lift-failed` | The unfreeze did not happen. The restriction stays active, and `failure` holds the cause and the fix. | Apply the fix, then lift the restriction again. |

The `code` in a `failure` names the cause. For a cause the DALP error catalogue lists, it is the DALP error code: `DALP-0712` when you lack the "Custodian" role, and `DALP-0706` when the token is not available in the active system, the organisation's deployment on the selected network. When the transaction queue refuses or fails the transaction, it is the queue code, for example `UNPROCESSABLE_CONTENT` for a transaction that reverted.

The restriction also reports a `summary` that counts the tokens by outcome: `total`, `frozen`, `queued`, `failed`, `alreadyFrozen`, and `lifted`. The `queued` count includes `pending` and `lift-queued` tokens, and the `failed` count includes `lift-failed` tokens.

## What the restriction does not cover [#what-the-restriction-does-not-cover]

### Tokens the wallet acquires later [#tokens-the-wallet-acquires-later]

A restriction freezes the tokens the wallet holds when the request runs. A token the wallet receives afterwards, or a token minted to it, is not frozen. Two options cover it:

- To freeze a token the wallet has acquired since, select **Apply again**, or repeat the restrict request as [Repeat a request safely](#repeat-a-request-safely) describes. The platform adds the missing freezes to the same restriction.
- To stop the wallet from receiving tokens at all, add its address to the address block list.

The address block list is the **Block addresses** control in [Global controls](https://docs.settlemint.com/docs/console/compliance/global-controls). On every token bound to the platform's compliance engine, including tokens issued later, it rejects a transfer or a mint that names a listed address as sender or recipient. It differs from a token's "Blocklist" tab, which lists the addresses frozen on that one token.

The list belongs to the organisation's system, not to one token. A block list rule blocks a listed address on every bound token in that rule's scope while the rule is on, so check the rule's "Applies to" scope before you rely on it. A custodian forced transfer and a token recovery skip the block list, as they skip every compliance rule. You need the "Compliance manager" role to change it, and lifting a restriction does not remove the address from it. The [Block addresses](https://docs.settlemint.com/docs/concepts/compliance-and-identity/compliance-modules#block-addresses) reference describes the module.

In the Console, open "Compliance", then "Global controls", select the **Block addresses** control, and add the wallet address to its list. [Add a wallet to the address block list](#add-a-wallet-to-the-address-block-list) shows the Platform API call.

### Partial freezes and forced transfers [#partial-freezes-and-forced-transfers]

A restriction uses the address freeze only. It never creates, changes or removes a partial freeze, so a partial freeze the wallet already had stays as it was before and after the lift. A custodian forced transfer ignores the freeze on the sending wallet, so a restriction does not stop a holder of the "Custodian" role from moving the wallet's tokens out. The chain does refuse a forced transfer into the restricted wallet and a Supply management burn from it. [Transfers](https://docs.settlemint.com/docs/console/asset-management/manage/transfers) describes forced transfers.

### Unfreezes outside the restriction [#unfreezes-outside-the-restriction]

While a restriction is active, DALP refuses an unblock of the wallet on any token the restriction lists and releases those freezes only through the lift, as [Lift a restriction](#lift-a-restriction) describes. An AI app that runs an unblock as one of the organisation's agents through the [hosted MCP server](https://docs.settlemint.com/docs/api-reference/cli/hosted-mcp) is refused the same way. The token contract holds only the freeze and knows nothing of the restriction, so a holder of the **Custodian** role on the token can still unfreeze the wallet with a direct call to the contract, outside DALP. The restriction then still reads active while the token no longer holds the freeze. To confirm a freeze still holds, check the token's "Blocklist" tab, not the restriction. To restore one, use "Block" on that tab: a restriction never stops a "Block".

## Controls that stop movement [#controls-that-stop-movement]

Four controls stop movement, and each acts at a different scope. Choose by what must stop.

| You need to stop | Use | What to weigh |
| --- | --- | --- |
| One wallet, on the tokens it holds now | A wallet restriction | It freezes only what the wallet holds when you run it. |
| One wallet, on every token including ones it receives later | The address block list in [Global controls](https://docs.settlemint.com/docs/console/compliance/global-controls) | One rule serves every bound token in its scope, and changing it needs the "Compliance manager" role. |
| Part of one balance on one token | A partial freeze on [Pause and freeze](https://docs.settlemint.com/docs/console/asset-management/manage/pause-freeze) | Each submission covers one address and one token. |
| One asset, for every holder | A pause on [Pause and freeze](https://docs.settlemint.com/docs/console/asset-management/manage/pause-freeze) | It stops every holder of the asset. |

None of the four stops a custodian forced transfer.

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

- Open the user's "Wallets" tab and confirm the "Restricted: " badge shows the reason you chose.
- In **Restriction result**, confirm "Failed" and "Queued" are 0.
- Open each frozen token, open its "Blocklist" tab, and confirm the wallet is listed. The address details show the reason of the active restriction. Check the "Blocklist" tab again before you report on or lift the restriction, because an unfreeze sent on chain outside DALP removes the freeze while the restriction still reads active.
- The organisation owner or an integration can also read the restriction through the API and check that `data.summary.failed` is 0 and that every token you expect is `frozen` or `already-frozen`. To match a freeze to the chain, compare the token's `transactionHash` in the restriction with the entry on that token's "Events" tab.
- After a lift, confirm the badge is gone and the wallet no longer appears on the "Blocklist" of the tokens the restriction froze. A token that showed `already-frozen` still lists the wallet.

## Troubleshooting [#troubleshooting]

**A token shows Freeze failed**

Read the `failure` of that token: it holds a `code`, a `message` and a `fix`. A token where you lack the "Custodian"
role fails with `DALP-0712`. Ask a holder of the token's admin role to grant you "Custodian" from the token's page,
then select **Apply again**, or repeat the restrict request as [Repeat a request safely](#repeat-a-request-safely)
describes. The platform already froze the wallet on the other tokens, and it sends only the freezes that are still
missing.

**A token stays Queued**

The platform accepted the freeze and the transaction has not settled. Select **Apply again**, or repeat the restrict
request as [Repeat a request safely](#repeat-a-request-safely) describes. The platform resumes the accepted
transaction instead of sending a second one, and it records the outcome.

**A token the wallet received later is not frozen**

A restriction freezes the tokens the wallet holds when you run it. Select **Apply again**, or repeat the restrict
request as [Repeat a request safely](#repeat-a-request-safely) describes, to freeze the new token. Or add the wallet
to the address block list to stop it from receiving tokens at all. [What the restriction does not
cover](#what-the-restriction-does-not-cover) describes both.

**The lift leaves the restriction active**

At least one unfreeze failed or has not settled, or a freeze is still settling. The token shows "Lift failed", "Lift
queued", or "Queued", and a failed token states its cause. Apply the fix, usually the "Custodian" role on that token,
or wait for the transaction to settle, and lift again. The platform sends only the unfreezes that are still missing.

**The lift returns 409 with DALP-17460**

A freeze on one of the restriction's tokens had not settled when you lifted, so the platform sent no unfreeze and the
restriction stays active. Wait for the freeze to settle, then lift again. The freeze has settled when no token of the
restriction shows **Queued**.

**The wallet is still frozen on a token after the lift**

The token showed "Already frozen", so the wallet was frozen there before the restriction and the lift leaves it. If
that freeze should end too, check that the "Restricted: " badge is gone from the wallet card, then open the token's
"Blocklist" tab and use **Unblock** for the address. If the badge still shows, follow "The lift leaves the restriction
active" first.

## Frequently asked questions [#frequently-asked-questions]

### What happens to a transfer the wallet already submitted?

The chain checks a freeze when a transfer executes, not when it is submitted. A transfer from or to the wallet that executes after the freeze lands reverts. A transfer that executed before the freeze keeps its result.

### Can I change the reason of an active restriction?

No. The reason, the note and the scope are fixed when you create the restriction, and a restrict request with a different reason, note or scope returns 409. To record a different reason, add the wallet's address to the address block list in [Global controls](https://docs.settlemint.com/docs/console/compliance/global-controls) first, lift the restriction and restrict the wallet again, then remove the address from the list. Without the block list, the wallet is unfrozen between the lift and the new restriction.

### Can I restrict more than one wallet in one request?

No. A request names one wallet, and the Console restricts one wallet at a time. To restrict more than one wallet, send one request for each.

## API routes [#api-routes]

The Platform API and the CLI offer four operations: restrict, list, read and lift. Authenticate with an [API key](https://docs.settlemint.com/docs/api-reference/guides/authentication-api-keys), which acts with the permissions of the user who created it and skips the wallet verification. While that user is in a cooling-off period after a wallet security change, a request that sends a transaction returns 403 `DALP-17440`. A request made with a Console session sends the verification as `walletVerification` in the body. The calls use your organisation's default network, and the `X-Chain-Id` header selects another one. The [Platform API reference](https://docs.settlemint.com/docs/api-reference/v2) lists every field and response.

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

Send the wallet address, the scope, and the reason. Scope `all` freezes every token the wallet holds when the request runs. Scope `tokens` freezes the 1 to 50 token addresses you list, including tokens the wallet does not hold yet.

```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" }
  }'
```

The CLI sends the same body. The generated command follows the HTTP verb and the path, so `POST /api/v2/restrictions` becomes `dalp create restrictions`:

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

The call waits for the freezes to settle and returns 200 with the restriction. A token whose transaction has not settled by then shows `queued`, and the call then returns 202 with the same body and a `Location` header, the restriction's own URL. The organisation owner or a platform administrator reads that URL until no token shows `queued`, because each read settles the queued tokens from the queue. Any other caller gets 404 `DALP-17457` on that URL, so it sends the same restrict request again instead, which resumes the accepted transactions. A partial result is a normal response: read `data.summary` and the `status` of each entry in `data.tokens`. Here the caller is the organisation owner, who holds the **Custodian** role on two of the wallet's three tokens. The platform froze those two, one of them paused, and could not freeze the third.

```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
    },
    "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"
      }
    ]
  },
  "links": {
    "self": "/api/v2/restrictions/0198f1a2-3c4d-7e8f-9a0b-1c2d3e4f5a6b"
  }
}
```

The record also states who created the restriction and when, and who lifted it, when, and with which note.

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

Find the active restriction for a wallet by listing the restrictions, newest first. The list filters by `walletAddress`, `participantId`, `status` (`active` or `lifted`), `reasonCode`, and `createdAt`, and [Pagination](https://docs.settlemint.com/docs/api-reference/guides/pagination) describes the query model. Each row states the reason, the actors, the times, and the `summary`. Read one restriction by its identifier to see its tokens.

```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_..."
```

In the CLI, `dalp get restrictions` lists the restrictions and `dalp get restrictions <restrictionId>` reads one. Run `dalp get restrictions --help` for the filter options.

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

Send `status` as `lifted`, with an optional `note` of up to 500 characters. The platform stores the note with the lift and with each unfreeze.

```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" }'
```

The response shows the restriction after the lift. As with the restrict request, a token whose lift has not settled shows `lift-queued`, and the call returns 202 with a `Location` header that the owner or a platform administrator reads until none does. Any other caller sends the same lift request again. The platform unfroze the two frozen tokens and recorded the new transactions. The third token stays `failed`, because there was nothing to undo, and it does not keep the restriction active.

```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
    },
    "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"
      }
    ]
  },
  "links": {
    "self": "/api/v2/restrictions/0198f1a2-3c4d-7e8f-9a0b-1c2d3e4f5a6b"
  }
}
```

Send the same lift request again to retry the unfreezes that failed and to finish a freeze that was still settling. A restriction that is already lifted comes back unchanged, and the platform sends nothing. Every lift request, a repeat included, needs the **Custodian** role on at least one token of the restriction.

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

Send a restrict request again with the same reason code, the same note, and the same scope kind, and the platform continues the active restriction instead of creating another. The repeat does three things:

- It adds a freeze for each token in scope that the restriction does not cover yet.
- It retries each token that failed.
- It resumes each freeze that was accepted but has not settled, without sending a second transaction.

Send a different reason, note or scope kind and the platform returns 409. When the wallet holds no token any more, only the organisation owner and platform administrators can continue the active restriction. Any other caller gets 422. A caller who may not read restrictions still gets the restriction back from a restrict or a lift, with less in it. The response leaves out the free-text reason and the lift note. It lists only the tokens where that caller holds the **Custodian** role, and `summary` counts only those.

Both write calls also accept the optional `Idempotency-Key` header. The repeat rules hold without it, because the platform keys the transaction of each token by the restriction.

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

Read the registered compliance modules and find the entry whose `typeId` is `address-block-list-v2`. [Global controls](https://docs.settlemint.com/docs/console/compliance/global-controls) owns this control. The steps below assume the organisation has one block list binding. Note its `moduleAddress`. If `globalConfigs` is empty, the platform has no block list yet, and a configure call without `instanceAddress` creates it. If `globalConfigs` holds a binding, its `moduleAddress` is the `instanceAddress` to send, and `parameters.addresses` is the current list.

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

A configure call on an installed control replaces the whole list with the `values` you send. An address you leave out is removed from the block list and can send and receive again. Copy every address from `parameters.addresses` into `values`, then add the new one. The binding must be enabled, and the call needs the **Compliance manager** role. In this example the first address was already on the list and the second is the wallet.

```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"
      ]
    }
  }'
```

Read the module again at `/api/v2/system/compliance-modules/<moduleAddress>`. The `parameters.addresses` of its binding lists the new addresses once the change is indexed.

### Errors [#errors]

| Status | Error | Cause | What to do |
| --- | --- | --- | --- |
| 403 | [DALP-9485](https://docs.settlemint.com/docs/api-reference/errors) | You hold the Custodian role on none of the tokens the request covers. | Ask an administrator to grant the role on at least one token, then send the request again. |
| 403 | [DALP-17440](https://docs.settlemint.com/docs/api-reference/errors) | The API key's user is in the cooling-off period after a wallet security change, and the request sends a transaction. Nothing was stored. | Wait until `data.heldUntil`, then send the request again. |
| 404 | [DALP-17457](https://docs.settlemint.com/docs/api-reference/errors) | No restriction in this organisation has that identifier, you may not see restrictions, or you hold the Custodian role on none of its tokens. | Use the identifier from the request that created the restriction, or ask the owner to list restrictions. |
| 409 | [DALP-17458](https://docs.settlemint.com/docs/api-reference/errors) | The wallet already has an active restriction with a different reason, note, or scope kind. | Send the reason, note, and scope kind of the active restriction again to continue it, or lift it first. The organisation owner can read them. |
| 409 | [DALP-17460](https://docs.settlemint.com/docs/api-reference/errors) | A lift found a freeze still settling on a token where you hold the Custodian role, so it sent no unfreeze. | Wait for the freeze to settle, then send the lift again. The error is safe to retry. |
| 422 | [DALP-17459](https://docs.settlemint.com/docs/api-reference/errors) | The wallet holds no token in this organisation, or none of the listed tokens exists in the active system. | List tokens that exist in the active system, or add the wallet to the address block list. |


# Users

Source: https://docs.settlemint.com/docs/console/participants/users
Invite or create the people who sign in, check a user's wallet, identity registration, KYC and eligibility, and review their KYC profile.

Users lists the people who sign in to the organisation. From it you invite or create a user, open a user to see whether their on-chain identity is registered and their KYC profile approved, and review that profile.

A login and an identity are separate records. The login decides who can sign in to the Console or the Investor portal. The on-chain identity, a contract the organisation's identity registry records for a wallet, is what a regulated token checks before it lets the wallet hold or receive value. A user can sign in with no registered identity, but cannot hold a regulated token until the identity is registered, so the user's page in the Console shows both records. A counterparty with no login belongs in [Contacts](https://docs.settlemint.com/docs/console/personal/contacts), and a token or other contract identity belongs in [Entities](https://docs.settlemint.com/docs/console/participants/entities).

![Users page with the Users, Invitations and Insights tabs, the Create or invite user button and the users table](https://docs.settlemint.com/docs/screenshots/console-participant-users.light.en.webp)

[Screenshot] The "Users" tab lists each user with name, type, identity registration, KYC status and country.

The email column is hidden by default and you turn it on from the column picker. "Search users…" matches name, email, national ID, the user's wallets and the identity address registered to one of them. The "Create or invite user" button sits in the page header.

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

- **Two kinds of role.** Owner and Member are organisation roles: they decide who manages invitations and settings, and they grant no on-chain authority. "System manager", "Identity manager", "Verification issuer" and "Permission manager" are on-chain system roles, which a Permission manager grants in [Roles and permissions](https://docs.settlemint.com/docs/console/organisation-settings/admins-and-roles).
- **The tabs you see.** The page has up to three tabs, "Users", "Invitations" and "Insights", and each shows only when you may open it. The "Users" tab and a user's page need the "System manager", "Identity manager" or "Verification issuer" role. Only an organisation owner manages invitations and sees the "Invitations" tab. Without "Users" or "Invitations" the page shows "Access restricted". [Insights](https://docs.settlemint.com/docs/console/participants/insights) says who opens the "Insights" tab.
- **A custody provider, for direct creation.** Direct creation needs the "Identity manager" role and a managed custody provider on the active network, the service that creates and holds wallet keys for the organisation. An administrator sets one up in [Custody](https://docs.settlemint.com/docs/console/organisation-settings/custody). Invitations need neither, because the invitee sets up their own wallet when they accept.
- **A reviewer role, for KYC.** Reviewing a KYC profile on the "KYC" tab needs the "Identity manager" or "Verification issuer" role.

## Steps [#steps]

### Start the invitation or the account [#start-the-invitation-or-the-account]

Select **Create or invite user**. "Send invitation email" is on by default. Enter the invitees. When you may grant at least one on-chain role, the field is "Email addresses" and takes up to 100 addresses, separated by commas, spaces or new lines. Otherwise the field is "Email" and takes one address. Choose the "Organisation role", "Member" or "Owner", and optionally the "On-chain permissions" the invitees receive when they complete onboarding. The roles offered are the ones you may grant. Select "Send invitations".

Clear **Send invitation email** to create the account now instead. Enter the "Email" and an optional "Name" of up to 255 characters, then select "Create user". Direct creation makes the login, a person participant, a wallet on the organisation's managed custody provider and an on-chain identity in one step. It does not register the identity and grants no on-chain role. The checkbox shows only when you may both invite and create. When you may do only one of the two, the sheet offers only that one.

![Create or invite user sheet with Send invitation email on, the Email addresses field, Organisation role and On-chain permissions](https://docs.settlemint.com/docs/screenshots/console-participant-users-create-form.light.en.webp)

[Screenshot] The "Create or invite user" sheet with "Send invitation email" ticked.

The sheet is described as "Send an invitation by default, or create the wallet and identity now without emailing the recipient." It shows an "Email addresses" field, an "Organisation role" picker set to "Member", and an "On-chain permissions" list of protocol-level roles, each with its description. With "Send invitation email" cleared, the sheet shows "Email" and "Name" instead.

### Confirm with your wallet verification [#confirm-with-your-wallet-verification]

The Console asks you to **Verify your identity** with your transaction PIN or transaction code before it sends invitations or creates the user. Direct creation waits for the managed custody provider. "Checking custody provider…" shows while the Console reads it, and the sheet refuses to create with "No custody provider serves this network, so no user can be created." when none serves the active network.

## Manage invitations [#manage-invitations]

The **Invitations** tab lists the invitations sent from this organisation. The table shows "Email", "Expires at", "Status" and "Actions". "Expires at" has a date only for a pending invitation. An invitation that was accepted, rejected or cancelled cannot expire, so its cell stays empty. The statuses are "Pending", "Accepted", "Rejected", "Canceled", "Expired" and "Accepted, roles not granted". The row menu offers "Copy invitation link", "Resend invitation" and "Cancel invitation". With no invitation the tab shows "No invitations yet".

- **Copy invitation link** copies the link to share with the invitee. When email is not configured, the Console shows the link to share when it creates the invitation.
- **Resend invitation** asks you to confirm, then sends the invitation again. An invitation that expired while pending keeps its row actions.
- **Cancel invitation** cannot be undone. It asks you to confirm, or select "Keep invitation" to stop. The invitation stays in the list as "Canceled" for the audit trail, and the invitee's link stops offering sign-up. To give access again, send a new invitation.

## Open a user [#open-a-user]

Select a user to open their page. The header shows the name, the type (or **Owner** for an organisation owner who holds an admin role) and the global eligibility verdict: "Eligible under global rules", "Needs action under global rules" or "Blocked by global rules". That verdict covers the organisation's system-level rules only, so a token with its own requirements can still refuse the user. On a network with an EVM identity registry it also shows the identity registration status, and to an identity manager or verification issuer it shows the KYC review status, such as "KYC review: Approved". That is the reviewer's decision on the KYC profile, not the on-chain KYC verification a token checks. The tabs are "Overview", "Holdings", "KYC", "Verifications", "Roles & permissions", "Wallets", "Activity log" and "Security". "KYC" shows to an identity manager or verification issuer, and "Security" to an identity manager. A user with no participant in this organisation shows a notice in place of positions and transactions.

The **Account** is the wallet that acts for the user. In an organisation that uses smart accounts, on a network that is ready for them, it is the user's smart wallet. Otherwise it is their signing key. The "Register identity" confirmation names the same address.

The **Overview** tab shows the user's facts, their top positions and last five transactions, and these panels:

- The KYC status of the user's profile, with a link to the **KYC** tab, for an identity manager or verification issuer.
- **Access**, with the organisation role and the system roles the user holds.
- **Platform account**, for a platform administrator only, with the user's platform role, sign-in state and a link "Open in Platform users".
- **Global eligibility**, described in [Read the global eligibility verdict](#read-the-global-eligibility-verdict).
- The identity's verifications, with a link to the **Verifications** tab and [Verify a participant](https://docs.settlemint.com/docs/console/participants/verify-a-participant).
- **User setup checklist**, for an identity manager or verification issuer, which lists the open steps: "Create identity on-chain", "Register in the identity registry", "Issue KYC verification" once the profile is approved and no KYC claim exists, "Update KYC information", and "Re-issue KYC verification" after the profile changed. On a Canton network it also lists "Allocate party on the network".

The **Wallets** tab lists the user's wallets, and [Restrict a wallet](https://docs.settlemint.com/docs/console/participants/restrict-a-wallet) covers the restriction actions on its cards. The "Roles & permissions" tab shows the organisation role and the system and asset roles held by the user's wallets, and [Change a user's organisation role](#change-a-users-organisation-role) covers the button on it.

## Register a user's identity [#register-a-users-identity]

On a network with an EVM identity registry, the header shows one identity action once the Console has looked up the account's identity. **Create identity** shows when the wallet has no identity contract. It deploys one for the wallet on the network in view, and the page moves to the next state on its own once the indexer records it. "Register identity" shows when the identity contract exists but is not registered. It opens the registration sheet, where you choose the country recorded for the wallet and confirm with your transaction PIN or transaction code. Country allow and block lists read this registration country, not the KYC profile's country. Both actions are enabled for an identity manager and disabled with a reason for other accounts. Once the identity is registered, neither shows.

Until registration completes, the user can sign in and receive roles but cannot hold or receive a regulated token, because every token checks the identity registry before it moves a balance. Registration alone is not eligibility: a token that requires a verification, such as KYC, still refuses the wallet until a trusted issuer adds it. [Verify a participant](https://docs.settlemint.com/docs/console/participants/verify-a-participant) covers that step, and [Onboard an investor](https://docs.settlemint.com/docs/api-reference/guides/onboard-an-investor#from-first-sign-in-to-a-verified-holder) follows the whole sequence from first sign-in to a verified holder.

For a registered user, the identity card on the **Overview** and "Verifications" tabs offers "Change country" and "Remove registration" to an identity manager. "Remove registration" asks "Remove this registration?" and your wallet verification. It takes the wallet out of the identity registry, so the wallet can no longer receive tokens that check the registry until it is registered again. The identity contract and its verifications stay on the ledger. To stop a wallet without removing its registration, use [Restrict a wallet](https://docs.settlemint.com/docs/console/participants/restrict-a-wallet).

## Review a user's KYC profile [#review-a-users-kyc-profile]

A user's KYC profile is the know-your-customer record the organisation keeps for them: first name, last name, country, national ID, the fields that [profile sections](https://docs.settlemint.com/docs/console/participants/profile-sections) add, and supporting documents. Each organisation keeps its own profile for a person. Changes collect in a draft version, and each submitted version stays in the profile's history. The investor fills it in from Profile in the [Investor portal](https://docs.settlemint.com/docs/concepts/operating/investor-portal) or the Console and selects **Submit for review**.

1. Open the user, then the **KYC** tab. The "Users" list filters by KYC status, and the dashboard shows "3 KYC profiles await review", with the current count, when profiles wait for a decision.
2. Read the profile card, its fields and documents, and the versions table, which lists the versions that reached review with their status.
3. Select a version in the table to read it, then decide it with **Approve**, "Reject" or "Request update". Each opens its own page under the user's "KYC" tab, with a breadcrumb back to the tab and "Cancel" to return without deciding. "Approve" takes optional notes. "Reject" needs a reason of at least 10 characters, which the investor sees. "Request update" sends the investor a message of at least 10 characters and opens an action for them in the Console or Investor portal. After the decision the Console returns to the "KYC" tab.
4. On the profile card, an identity manager can also approve every field with **Approve all**, ask for changes on named fields with "Request changes", or correct a field and select "Save", which leaves the version for another reviewer to approve.

The person who submitted or corrected a version cannot approve, reject or request an update on it, and the Console hides those buttons for them. When a platform administrator submitted or corrected the version while [impersonating](https://docs.settlemint.com/docs/concepts/custody-and-signing/maker-checker#impersonated-sessions-cannot-decide) the member, that administrator cannot review it either. A correction an identity manager saves waits for a different reviewer, an identity manager or verification issuer who did not edit the version, to approve it. An owner who is the organisation's only reviewer needs a second one before their own profile can be approved.

The platform refuses an approval that would leave a required field empty, or a field that still needs changes, and writes nothing. The investor receives an email with the outcome when the platform has mail delivery and the user has an email address. [Audit trail](https://docs.settlemint.com/docs/console/reporting/audit-trail) lists the operations the platform records, with who performed each one and their role at the time, and records each opening of a participant's KYC record as a sensitive read.

Approving a profile does not issue the on-chain KYC verification. The overview checklist then shows **Issue KYC verification**, and a verification issuer adds it from [Verify a participant](https://docs.settlemint.com/docs/console/participants/verify-a-participant). Only an issuer that [Trusted issuers](https://docs.settlemint.com/docs/console/compliance/trusted-issuers) lists for the topic adds a verification a token accepts. When the identity is registered and the approved profile has a country, the approval does add a Residence verification for that country, issued by the organisation's identity.

## Read the global eligibility verdict [#read-the-global-eligibility-verdict]

**Global eligibility** says whether the user passes the organisation's system-level compliance rules on the selected network: "Eligible", "Needs action" or "Blocked". It lists each reason, such as "Wallet is on the global address blocklist." or a missing, revoked or expired required verification (a verification whose issuer is not trusted for its topic counts as missing), and links to "Compliance › Global controls" or "Verifications" where you fix it. A user with no wallet shows "No wallet on file. Eligibility cannot be evaluated yet."

The verdict first comes from indexed data and is marked **From indexer**. Select "Recheck now" to run a live check on the network. The live result replaces the indexed one and is marked "Live check". When the live check times out, the tile keeps the indexed verdict, marks it "Live check" and adds "Live check timed out for one or more modules." Read the verdict after a timeout as the indexed one. The verdict covers the organisation's global controls only. Whether the user may hold a particular asset, or make a particular transfer, depends on that token's own check.

## Change a user's organisation role [#change-a-users-organisation-role]

The **Roles & permissions** tab opens with an "Organisation" card that shows the user's "Organisation role", "Owner role ends" when the owner role has an end, and "Member since". An organisation owner sees "Change organisation role" on the card. The button does not show to other accounts.

1. Select **Change organisation role**. A dialog opens.
2. Under **Organisation role**, choose "Member" or "Owner". "Member" "Reads the organisation's settings." "Owner" "Changes settings, invites people, removes members and changes roles." The current role carries a "Current" badge.
3. For **Owner**, optionally set "Owner role ends". At that time the platform returns the user to member. Leave it empty to keep the owner role until someone changes it. The end must be at least two minutes away, and the field does not show when you change your own role.
4. Select **Save role**.

When you change your own role to **Member**, the dialog warns that you can then no longer change settings, invite people or change roles. The card also lists the system and asset roles the user's wallets hold. They are read-only here, and "Manage roles" opens [Roles and permissions](https://docs.settlemint.com/docs/console/organisation-settings/admins-and-roles) for an account that may grant them. You change an on-chain role there.

## Manage a user's security [#manage-a-users-security]

The **Security** tab shows to an identity manager. Its cards show the user's wallet address, "Sign-in code", "Transaction PIN", "Transaction code" and "Active sessions", with the count of sessions and, for each session, the device, the IP address, when it was last active and a "Revoke" button. Below them:

- **Reset credentials** sends the user a password reset email. It shows only when email is configured and the user has an email address. The email says that an administrator of your organisation started the reset, names your organisation, and tells the user to contact an administrator of your organisation if they did not expect it. It is sent in the user's language, and it does not say the user asked for the reset.
- **Unlock user** clears the user's password lockout after repeated wrong passwords.
- **Identity recovery** replaces a lost or compromised wallet and cannot be undone. "Recover identity" creates a new wallet and deploys a new on-chain identity, moves the user's tokens to the new wallet, revokes all their sessions and resets their sign-in code, passkeys, transaction PIN, transaction code and recovery codes. Their password and API keys stay. Verifications from your organisation's own issuer are reissued, and other issuers must reissue theirs. It is unavailable until the user has a wallet address, and it restores an EVM identity contract only. A recovery waits for another owner or administrator of the organisation to approve it, because the "Recovery" group under [Approvals](https://docs.settlemint.com/docs/console/organisation-settings/general#approvals) starts on. An owner turns that group off to let one identity manager recover a wallet alone. [Recover a user who lost their wallet](https://docs.settlemint.com/docs/console/my-account/onchain-identity#recover-a-user-who-lost-their-wallet) gives the steps.

The danger area at the foot of the tab holds **Reset sign-in code**, "Reset transaction PIN", "Revoke all sessions" and, for an organisation owner, "Remove member". Each of the first three asks you to confirm with your transaction code, or with your transaction PIN when you have no transaction code, and has a button to keep things as they are: "Keep sign-in code", "Keep PIN" and "Keep sessions".

- **Reset sign-in code** removes only the authenticator app the user signs in with. Their transaction PIN, transaction code, recovery codes and sessions stay. The user sets up a sign-in code again from their own Security page.
- **Reset transaction PIN** removes the user's PIN and signs them out everywhere. They set a new PIN after signing in, and their recovery codes and transaction code stay. The platform emails them about the reset, and the organisation's [cooling-off period](https://docs.settlemint.com/docs/console/organisation-settings/general#set-the-cooling-off-period) holds their signing.
- **Revoke all sessions** signs the user out of this organisation on every device.

An action is unavailable, with its reason shown, when there is nothing to reset: **No sign-in code set up**, "No transaction PIN set" or "No active sessions". On your own account the reset and revoke actions are unavailable with "Manage your own security from your Security page." and "Remove member" does not show.

## Remove a member [#remove-a-member]

Removing a member cannot be undone. It removes the user from the organisation, revokes all their sessions, and cancels the approvals the member started and the approvals waiting on them as checker. It cannot revoke a role on chain, so the platform refuses to remove a member while a wallet they act or sign with still holds a system role or a role on one of the organisation's assets. The user's **Roles & permissions** tab lists the system and asset roles their wallets hold. Revoke them first in [Roles and permissions](https://docs.settlemint.com/docs/console/organisation-settings/admins-and-roles) and on each asset's "Permissions" tab. The identity registration and the wallet's holdings stay.

**Remove member** is in the danger area of the "Security" tab. It shows only to an organisation owner, and never on the owner's own account. While the member holds a system role, it is unavailable with "Revoke this member's system and asset roles first. A role stays active on chain after the member leaves."

Select it, read "Remove member from organisation?", and confirm with "Remove member", or select "Keep member" to stop. The Console does not check asset roles, so when the member still holds one, the removal fails with "The member still holds on-chain roles" and the member stays. The Console returns to the "Users" tab after a removal.

## View a user in My participants [#view-a-user-in-my-participants]

The user's header has a **View in my participants** button when the user's participant is one you may act for. It opens that participant's page under "My participants". [My participants](https://docs.settlemint.com/docs/console/my-account/acting-as-participants) describes that screen.

## Refresh your own ENS avatar [#refresh-your-own-ens-avatar]

An identity manager who opens their own user page sees **Refresh the ENS avatar** in the header when the deployment has ENS available. It reads the ENS avatar of each of your participant's wallets again. An ENS avatar is the image a wallet owner publishes through the Ethereum Name Service. A wallet can be refreshed once every ten minutes, and inside that window the control says "Available again in about 4 minutes.", with the remaining minutes. When nothing new is stored, the control says why, such as that the address has no ENS avatar or that the hourly avatar budget is spent.

## Columns on the Users tab [#columns-on-the-users-tab]

The **Type** column shows the first match in this order: "Pending" while a user's roles are still being set up, "Admin" for an administrator or a holder of the permission manager or system manager role, "Trusted issuer" for a verification issuer, "Asset manager" for a token manager, and "Investor" for everyone else. "Identity registration" reads "Registered" when the user's identity is active in the system's identity registry and "Registration pending" otherwise, including for a user whose wallet has no identity. The column's filter calls the second state "Pending registration". A user with no wallet on the selected network shows no status. The "Country" column shows the country of the user's KYC profile. When the profile has no country, it shows the country recorded at identity registration, marked "From registration". The country filter and sort read the KYC country only.

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

- For an invitation, the sheet lists each address with its own result, and an address that failed stays in the field for another try. Open "Invitations" and confirm each recipient with status "Pending".
- When email is not configured, the Console shows "Invitation created. Share the link manually because email is not configured." with the link to share, and "Copy invitation link" in the row's menu copies it again.
- For a direct creation, the Console shows "User has been created successfully with wallet and identity." Open the user and confirm the wallet and the identity address. The header reads **Identity registration: pending** until an identity manager registers the identity, which [Register a user's identity](#register-a-users-identity) describes.
- For a KYC decision, the version's status in the versions table changes and the user's header shows the new KYC status.

## Troubleshooting [#troubleshooting]

**Access restricted**

Your account holds none of the **System manager**, "Identity manager" or "Verification issuer" roles, and you are not
the organisation owner. Ask a permission manager for one of the roles in [Admins and
roles](https://docs.settlemint.com/docs/console/organisation-settings/admins-and-roles).

**Create user is refused because no custody provider serves the network**

The organisation has no managed custody provider for the active network, or the providers could not be read. An
administrator enables one in [Custody](https://docs.settlemint.com/docs/console/organisation-settings/custody). Invitations still work, because
the invitee sets up their own wallet when they accept.

**The toast says the custody account is still settling**

"User created. Their custody account is still settling and is not usable yet." means the user exists and the managed
wallet is still being provisioned. Do not register the identity or create the user again until the custody account has
settled.

**An invitation shows Accepted, roles not granted**

The invitee joined, but the on-chain roles on the invitation could not be granted. Check the user's roles, and grant
the missing ones in [Roles and permissions](https://docs.settlemint.com/docs/console/organisation-settings/admins-and-roles).

**Copy invitation link says the invitation has expired**

"This invitation has expired. Resend it to send a new link." An invitation that expired while pending shows the status
"Expired" and keeps its row actions. Select **Resend invitation**, or cancel it with "Cancel invitation" and send a
new one. Cancelling cannot be undone.

**Approve is missing on the KYC tab**

You submitted this version yourself, the version is not under review, or it is not the latest version. Ask another
reviewer to decide it.

**The country reads From registration**

The user has no country on their KYC profile, so the list shows the country recorded at identity registration. The
country filter reads the KYC country only, so this user does not match a country filter until their profile has a
country.



# Verifications

Source: https://docs.settlemint.com/docs/console/participants/verify-a-participant
Confirm a participant has a registered identity, add the issuer-signed verification a token requires, and check the transfer before you submit it.

A participant can receive a regulated token in an ordinary transfer or mint only when its identity is registered in the identity registry, the system's list of identities that tokens recognise, and carries the verifications the token's rules require. On the participant's **Verifications** tab you add a verification by hand, then check the intended transfer on the token's "Transfer pre-check" tab before you submit it. A custodian forced transfer or a token recovery checks only that the recipient is registered.

A verification, also called a claim, is a signed record on the participant's on-chain identity that says the participant passed one category of check, such as KYC.

Each category is a verification topic, defined on [Verification topics](https://docs.settlemint.com/docs/console/compliance/verification-topics), and a token counts a verification only when it comes from a trusted issuer for that topic, set on [Trusted issuers](https://docs.settlemint.com/docs/console/compliance/trusted-issuers).

When your organisation connects a [compliance provider](https://docs.settlemint.com/docs/console/compliance/compliance-providers), the platform issues and revokes these verifications from the vendor's verdicts. You issue one by hand when no provider covers the topic or when your own team makes the decision.

Issuing a verification moves no balance. Transfer-path compliance, the check a token runs on every transfer, reads the verification when a transfer executes, so a verification issued while an earlier transfer still waits to execute counts for that transfer too.

![A participant's Verifications tab with the On-chain identity card and a table of KYC, AML and Residence verifications](https://docs.settlemint.com/docs/screenshots/console-participant-verifications.light.en.webp)

[Screenshot] The "Verifications" tab of the participant's detail page.

An "On-chain identity" card names the identity, its registration, its wallet and its country. Below it, the "Verifications" table lists every verification on this identity with its name and issuer address, its "Status", and its "Verification data", such as the claim value and how long it stays valid, with "Add verification" above it. A participant with no on-chain identity shows "No verifications yet" with the reason instead of the list.

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

- **The Verification issuer role.** Everyone who may open a user's page can read the "Verifications" tab. In the Console, only an account that holds the "Verification issuer" role issues or revokes a verification by hand. The platform also issues Residence when a reviewer approves the KYC profile of a registered identity, and a connected compliance provider issues and revokes verifications for its topics.
- **An issuer identity.** You issue from your signing wallet's active registered identity, or the on-chain identity of the participant you act as on this network, as [My participants](https://docs.settlemint.com/docs/console/my-account/acting-as-participants) explains. A "Verification policy manager", the role that decides which issuers each topic trusts, must have made that identity a trusted issuer for the topic on [Trusted issuers](https://docs.settlemint.com/docs/console/compliance/trusted-issuers).
- **The topic.** Know which topic the target token's compliance rules require, and have the evidence that supports the values you enter.
- **An approved KYC profile, for investor topics.** For KYC, AML, KYT, KYB, Qualified institutional investor, Professional investor, Accredited investor, Accredited investor verified and Regulation S, the participant's latest KYC profile must be approved. The Console and the Platform API refuse these topics for any other profile status. The token itself checks only that a trusted issuer signed the verification, so an issuer that signs outside DALP is not held to this check. An "Identity manager" or "Verification issuer" approves the profile on the participant's "KYC" tab, and the person who submitted it cannot.

## Steps [#steps]

### Confirm the identity is registered [#confirm-the-identity-is-registered]

Open "Organisation participants", then "Users" or "Entities", and open the participant. On a user, the header reads **Identity registration: registered** when the registry marks the identity active and not lost, or "Identity registration: pending" when it does not. The "On-chain identity" card on the "Verifications" tab says "Registered" or "Pending registration". The platform refuses to issue a verification to an identity that is not registered, so register it first from the same detail page.

On the "Identity and verifications" tile, select **Manage verifications** to open the participant's "Verifications" tab. The tab opens with the "On-chain identity" card above the "Verifications" table.

### Open Add verification [#open-add-verification]

Select **Add verification** in the toolbar of the "Verifications" table. When the button is disabled, point at it to read why. [Troubleshooting](#troubleshooting) lists the reasons.

An identity with no verifications yet shows "No verifications yet" and "This identity has no associated verifications." in the table, with the button above it. A participant with no on-chain identity has no table and no button: the tab shows "No verifications yet" with the reason, such as "This participant has no on-chain identity yet. Verifications can be issued after the identity is registered."

### Select the topic [#select-the-topic]

The sheet "Issue verification" has two steps: "Details" and "Review". On "Details", first choose the topic the token requires under **Verification topic**. The list shows your system's topics whose subject is "Person" or "Any subject", in alphabetical order. It is not the token's required set, so you choose the right one yourself. Topics whose subject is "Asset" or "Issuer", such as "Collateral" or "Issuer licensed", are not offered on a participant. Issue them on an asset's identity. The list also leaves out "Instrument structure", which the platform issues when a structured instrument's final class deploys.

The list still shows "Residence", but the platform refuses it, because it issues Residence itself from an approved KYC profile. A topic you are not a trusted issuer for shows "You are not a trusted issuer for this topic" and cannot be chosen. When your identity is trusted for no topic, the "Verifications" tab says "You cannot issue verifications because your acting identity is not a trusted issuer for any topic." A verification policy manager gets a link to "Trusted issuers", and everyone else is asked to contact one.

**Issuer event determination** is issued on an asset's identity, not a participant's. [Record an issuer event determination](#record-an-issuer-event-determination) covers it.

### Enter the details [#enter-the-details]

Once you choose a topic, its fields appear below it on **Details**.

- **KYC, AML and the other investor topics.** The Console fills the value in for you: "This value is calculated automatically for this verification type. No manual entry is needed." For KYC the value comes from the participant's approved profile. When the profile is not approved, including while a newer version waits for review, the step shows "No approved KYC profile" and "Review" stays disabled. The optional "Expiry date" sets the day after which the verification no longer counts. Leave it empty for a verification that never expires.
- **Issuer and asset topics.** Typed fields, such as a jurisdiction, licence details, a document hash or coordinates.
- **Custom topics.** One field for each value in the topic's signature, the list of values the topic defines.

Select **Review**, then check the summary against your evidence before you sign.

### Sign and issue [#sign-and-issue]

Select **Issue verification** and confirm with your transaction PIN or transaction code. Wait for "Verification issued successfully". The verification list reloads, and the new row shows "Active", the topic you chose and your issuer identity.

Selecting a row opens its "Verification history": each event, added, changed, revoked or removed, with its transaction, block, sender and event data.

### Check the intended transfer [#check-the-intended-transfer]

Open the asset under "Assets", select its **Transfer pre-check** tab, enter the intended "Sender", "Recipient" and "Amount", and select "Run check". The check simulates the transfer without signing anything and lists the blockers it can establish. Resolve each one before you submit the real transfer. A passing check describes the state now. The token checks every configured rule again when the transfer executes, not only this verification.

## Revoke a verification [#revoke-a-verification]

The row menu offers **Revoke verification** on an active verification when your account holds the "Verification issuer" role and your identity is either the participant's own identity or the verification's issuer. A revoke cannot be undone: to restore the participant's standing, issue a new verification. Confirm the dialog, then enter your transaction PIN or transaction code.

The same control takes one of two paths. When you revoke as the issuer, the platform revokes the verification through your issuer identity, and the record stays on the identity marked revoked. The dialog names both outcomes. When you revoke as the participant's own identity, the platform removes the verification from that identity instead, which needs the signing wallet to hold the on-chain authority to remove verifications from it. The identity no longer holds the record, and its history shows **Verification removed**. If more than one verification matches, the platform refuses instead of choosing one.

## Record an issuer event determination [#record-an-issuer-event-determination]

This task applies to an asset's own identity, not to a participant. An issuer event determination records that an event of a named kind occurred on an instrument, with a reference to the notice that records it. You issue it on the asset's own identity from the asset's "Verifications" tab, with **Add verification** and the topic "Issuer event determination". The topic has two fields: "Determination kind", such as "Early redemption approved" in the Console's example, and "Document reference". Holders and counterparties rely on the signed record as the issuer's official determination, so check both fields before you sign.

A distribution request can name a determination kind that has a priority row in the distribution waterfall, the ranked list that decides who a [coordinated distribution](https://docs.settlemint.com/docs/console/asset-management/manage/coordinated-distribution) pays first. The waterfall uses that row only when, at the moment the distribution is funded, the asset's identity holds a determination whose **Determination kind** matches the row's kind exactly. The issuer must be trusted for the topic and must report the determination as valid. An absent, untrusted or invalid determination leaves the distribution on its ordinary ranking.

## From registration to the transfer pre-check [#from-registration-to-the-transfer-pre-check]

The token's pre-check runs once the identity is registered and the verification issued, and it checks every rule against current state.

[Figure] Check participant eligibility before transfer. Register the participant identity and issue the required verification from a trusted issuer. Use "Transfer pre-check" with the intended token, sender, recipient, and amount. A passing check describes current conditions and does not guarantee a later transfer. Review any failing rule. Submit a transfer only when it is the intended operation, then verify its transaction and resulting balances. Labels: Identity; Verification issued; Pre-check requested; Rules checked; every rule passes; any rule fails; Check passes; conditions pass at check time; Blocked; failing rule named, nothing moves.

The pre-check evaluates the intended operation against current state, and a confirmed transfer records the outcome
under the rules applied at execution.

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

- The participant's **Verifications** tab shows the new verification as "Active", with the expected topic, your issuer identity and a green shield in the trusted column, whose tooltip says the issuer is in the trusted issuers registry.
- The transfer pre-check for the intended transfer reports no blockers.
- "Active" means the verification is not revoked, its issuer is trusted for its topic, and its validity date, when it has one, has not passed. The status names the first reason a verification stops counting: "Revoked" after a revoke, "Issuer not trusted for this topic" when [Trusted issuers](https://docs.settlemint.com/docs/console/compliance/trusted-issuers) does not, or no longer, list the issuer for the topic, and "Expired" once its validity date passes.
- A verification whose issuer lost trust for its topic stops counting for every token that relies on your system's trusted issuers for the topic, even though nothing changed on the verification itself. A token that lists the issuer in its own trusted issuers can still accept it.
- If you then submit an ordinary transfer, its confirmed transaction is the record that the participant passed the token's rules at that moment. A forced transfer or a recovery skips those rules and is not such a record.

## Troubleshooting [#troubleshooting]

**Add verification is disabled**

Point at the button to read the reason. "You are not authorized to issue verifications." means your account lacks the
"Verification issuer" role. A line that names a wallet means the role sits on that wallet, so switch to it. "This
identity can't receive verifications yet." means the identity has no account on this network yet. When the participant
has no on-chain identity at all, the tab shows "No verifications yet" with the reason instead of the button.

**A topic is disabled in the picker**

Your identity is not a trusted issuer for that topic. Ask a verification policy manager to add the topic to your
identity on **Trusted issuers**, or ask an issuer who is trusted for it to issue the verification.

**The issue is refused because the KYC profile is not approved**

The topic is an investor topic, and the participant's latest KYC profile is not approved. Ask the participant to
complete their KYC profile and select **Submit for review**. Issue the verification once an identity manager or
verification issuer approves the profile.

**The issue is refused because the identity was not found in the registry**

The participant's identity exists but is not registered. Register it from the participant's detail page, then issue
the verification again.

**The verification is active but the transfer still fails**

Run the **Transfer pre-check** and read the blocker it names. The token can require another topic, accept only issuers
your identity is not among, or enforce a rule unrelated to verifications, such as a country restriction or a holder
cap. Fix the blocker the check names and run it again.

**The participant held the token before but now fails**

Run the **Transfer pre-check** against current state. A revoked or expired verification, a changed token rule or an
issuer that is no longer trusted each changes the result on its own. On the "Verifications" tab, a verification whose
issuer lost trust for its topic shows "Issuer not trusted for this topic": issue it again from an issuer that is
trusted for the topic, or restore the topic on [Trusted issuers](https://docs.settlemint.com/docs/console/compliance/trusted-issuers).

## Frequently asked questions [#frequently-asked-questions]

### Does a verification issued here work for every token?

It works for every token that requires the same topic and trusts the issuer. The verification sits on the participant's on-chain identity, not on a token, so any token whose rules ask for that topic reads the same record.

### If a verification is revoked, does the participant lose the tokens they already hold?

No. The balance stays where it is. A revoked verification blocks the next transfer that depends on it and leaves settled transfers untouched. Moving or freezing an existing balance is a separate action on the token.

### What happens if I issue a verification for a topic that already has one?

A verification is keyed by its issuer and its topic together, so issuing the same topic again from the same issuer identity replaces that issuer's earlier verification. An issuer with a different identity adds a second verification for the same topic. Check the issuer on the existing row before you submit.

### Which holders would fail an asset's identity rule?

When your organisation has the Console assistant on, ask it on the asset's page what the identity rule means or which holders it would block. [Search](https://docs.settlemint.com/docs/console/essentials/search) explains how to ask. The answer states the asset's identity rule in words and shows a block with the holders who fail it. The check covers the 50 largest holders and says so.

It asks each one the same eligibility question a transfer asks, and counts a holder as failing the rule when the reason is a missing verification, a revoked verification or an identity the token does not accept. A holder refused for another reason is counted separately. The block names at most five failing holders, largest first, with the reason for each.

The check stops after four seconds and reports how many holders it did not check, so a partial result never reads as complete.


# Contacts

Source: https://docs.settlemint.com/docs/console/personal/contacts
Save counterparty names and wallet addresses for reuse in issuance, transfer and settlement forms, and learn what a saved contact does not check.

Contacts is your personal address book in the Console: a name saved next to one wallet address, so address pickers in issuance, transfer and settlement forms offer the counterparty by name instead of a pasted 42-character address. A contact is a label on an address. It creates no login, grants no permission and registers no on-chain identity. Every operation that later uses the address runs its own eligibility and compliance checks.

Every contact belongs to the account that saved it. No other user can list, read, change or delete it, and there is no shared organisation address book.

A contact is not tied to an organisation either: you see the same contacts in every organisation you belong to, and the Investor portal shows the same address book to an investor. Removing a member from an organisation does not remove their contacts. A contact is not a [user](https://docs.settlemint.com/docs/console/participants/users), which is a person who signs in, and not an [entity](https://docs.settlemint.com/docs/console/participants/entities), which is a contract identity the organisation tracks.

![Contacts page with search and Add contact action](https://docs.settlemint.com/docs/screenshots/console-contacts-list.light.en.webp)

[Screenshot] The page lists your saved contacts, sorted by name.

Each row shows the contact name with the wallet's avatar and short address, and the created date. The updated date and the full wallet address are hidden columns that you turn on from the column picker. A contact whose wallet is one of your own wallets carries a **Me** badge. An empty list shows "No contacts yet" with "Add contacts to quickly reuse wallet addresses." A failed load shows "Failed to load contacts. Please try again." instead of an empty table.

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

- Your account must have finished onboarding.
- Get the counterparty's `0x` wallet address and confirm it through your institution's approved channel before you save it.

## Steps [#steps]

### Open Contacts [#open-contacts]

Open "Personal", then **Contacts**. Before you add a contact, search the list with "Search by name or wallet…", because each wallet can appear on only one of your contacts.

### Add the contact [#add-the-contact]

1. Select **Add contact** to open its form page.
2. Enter the "Contact name", from 1 to 120 characters. The field counts the characters as you approach that limit and refuses a longer name instead of cutting it. Two contacts can share a name.
3. In "Wallet address", open the picker, then pick a known participant or contact by name, or paste the `0x` address and select it from the list. Typing alone does not fill the field: you must select an entry.
4. Select **Save contact**. "Cancel" returns to Contacts without saving.

![Add contact page with a contact name and wallet address](https://docs.settlemint.com/docs/screenshots/console-contacts-add-form.light.en.webp)

[Screenshot] The "Add contact" page with the "Contact name" field and the "Wallet address" picker.

The page is described as "Store counterparty wallets you reuse during settlement or issuance." The "Contact name" field shows a character count, and the form ends with "Cancel" and "Save contact" buttons. **Save contact** stays disabled until the name has a character other than a space and an address is selected.

The picker accepts a `0x` address only. It refuses a name ending in ".eth" with "Names ending in .eth are not supported here. Paste the 0x address instead." It also refuses a pasted address whose capitals do not match its checksum, with "The capitals in this address do not match its checksum, so it may be mistyped. Copy it again from the source.", and offers nothing to select. The platform stores the address in lowercase, so the same address in different capitals is the same wallet. The picker also refuses the zero address, which belongs to no one and can only lose what is sent to it, and states the reason under the field.

### Review the saved contact [#review-the-saved-contact]

The Console shows "Contact saved" and returns to Contacts. Open the contact from the list. The header shows the name with the wallet's avatar, the shortened wallet address with a copy button, "Edit", and an **Actions** menu with "Copy address" and "Delete". The menu also offers "View on explorer" when the network has a block explorer configured.

To compare the full address with your approved source, use the copy button or "Copy address", or turn on the "Wallet address" column on Contacts. Below the header, the page brings together what the platform already shows you elsewhere about that wallet:

- **Activity with this contact** lists the latest ten events that name the wallet and that you can see in Activity, newest first. Select a row to open the event, or "View all in Activity" to search Activity for the wallet.
- **Open settlements** lists the XvP settlements, the exchanges where both sides' assets move together or not at all, with the wallet that are still pending, waiting for a secret or ready, when the organisation has the XvP add-on. You see the settlements the Settlements page would show you.
- **Identity** names the users and participants in the active organisation that hold the wallet, each linked to its own page. It shows the wallet's on-chain identity registration only when you hold the system manager, identity manager or verification issuer role, or when the wallet is your own. It also shows the date you added the contact.
- **Holdings** lists the wallet's balances when it belongs to a participant whose holdings you may read. When you may not read them, the section is not shown.

![Contact page with the wallet address, the Edit button and the Activity with this contact section](https://docs.settlemint.com/docs/screenshots/console-contact-detail.light.en.webp)

[Screenshot] A contact page with its header, activity, open settlements, identity and holdings.

The header shows the name, the shortened wallet address with a copy button, "Edit" and the "Actions" menu. The "Activity with this contact", "Open settlements", "Identity" and "Holdings" sections follow.

## Edit or delete a contact [#edit-or-delete-a-contact]

Select **Edit** on the contact page to open the "Edit contact" page. Change the name or the wallet, then select "Save changes". The Console shows "Contact updated" and returns to the contact. "Cancel" or the contact breadcrumb returns without saving. An edit overwrites the contact: the contact page keeps no history of earlier names or addresses. Turn on the "Updated" column to see when a contact last changed.

To delete a contact, open "Actions" and select **Delete**. The Console deletes it at once, returns you to the list, and shows "Contact deleted" with "Undo" for 8 seconds. Undo saves the contact again with the same name and wallet, and its created date starts over. After the message closes, add the contact again to restore it.

An operation that already used the address keeps its own record of it. Nobody is told when you save, edit or delete a contact, including the counterparty. Each save, edit and delete is still recorded in the [audit trail](https://docs.settlemint.com/docs/console/reporting/audit-trail) as **Create or update contact** or "Delete contact", with you as the actor.

## Refresh a contact's avatar [#refresh-a-contacts-avatar]

A contact's avatar comes from the ENS avatar of its wallet, the image a wallet owner publishes through the Ethereum Name Service, when the deployment has ENS configured. Select **Refresh the ENS avatar** on the contact page to read it again. The control shows only when the deployment has ENS configured.

You can refresh one wallet's avatar once every ten minutes. Inside that window the control is disabled and says "Available again in about 4 minutes.", with the remaining minutes. When the refresh stores nothing new, the control says why: the address has no ENS avatar, the stored avatar is already current, an administrator suppressed the avatar of this address, or the hourly avatar budget is spent and the next refresh reads the address.

## Where the picker offers your contacts [#where-the-picker-offers-your-contacts]

When you pick a wallet that receives tokens, the address picker offers your contacts next to the organisation's participants. It does not offer contacts where a form asks for a participant. An entry that is both a contact and a participant appears once.

When the form names a token, the picker hides each contact the token would refuse as a recipient, and says how many it hid, such as "2 hidden, not eligible for NWC.". It names the two causes it cannot tell apart: a required verification is missing, or the issuer of the verification is not trusted for the token. Verifying again does not help in the second case, because an issuer trusted for the topic has to issue the verification. **Show all** shows them anyway. The hiding uses the same recipient check the form runs on the recipient you pick: an active registration in the token's identity registry or in the identity registry of your organisation's system, its deployment on that network, plus the claims and allow lists the token's compliance requires. A token that your organisation's system did not deploy hides every contact. A hidden contact stays in your address book.

In a large organisation the picker checks participants one page at a time. When it lists only the first matches, it says "Showing the first 25. Keep typing to narrow the list." and "Some participants may be hidden, not eligible for NWC." instead of counts. **Show all** still shows them, and typing narrows the list until the counts return.

## What a saved contact does not check [#what-a-saved-contact-does-not-check]

[Figure] Every operation checks the address. Saving a contact does not. Saving a contact stores an address without establishing eligibility. Selecting that contact and entering the same address by hand lead to the same operation checks. Issuance, transfer, and settlement enforce their own rules when they run. A saved contact does not bypass those rules. Labels: Picked from Contacts; From a saved contact; No check happens at this step; Entered directly; Typed or pasted; No check happens here either; Eligibility and compliance check; Every operation runs its own check; Runs on every operation, wherever the address came from; The operation proceeds; Check passes; Issuance, transfer, or settlement continues; The operation is rejected; Check fails; Same as an address typed by hand.

A picked contact and a pasted address reach the same operation check, because saving a contact checks nothing.

Picking a contact fills the address field. It does not review the address. Nothing in the platform compares the saved address with the source you copied it from, so compare the full address with that source before you send value to it.

A contact carries no compliance status. If the counterparty's wallet loses eligibility after you save it, the contact does not change and is not flagged. The next operation that uses the address evaluates it at that moment.

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

- Search for the contact name or wallet on **Contacts** and confirm that one row shows it.
- Copy the full wallet address from the contact page and compare it, character by character, with your approved source.
- Open a transfer form for a token, open the recipient picker and type the contact name. The picker offers the contact by name, or counts it as hidden when the token's recipient check refuses its wallet.

## Troubleshooting [#troubleshooting]

**Saving refuses the wallet as a duplicate**

The form shows "You already have a contact for this wallet. Open that contact to rename it." Another of your contacts
already holds the wallet, in any capitals. The platform saves nothing and leaves the existing contact unchanged. Open
that contact and edit it instead.

**The contact does not appear**

Clear the search, or search for part of the wallet address instead of the name. Search matches any part of the name or
the address. If the page shows "Failed to load contacts. Please try again.", reload the page.

**A contact link opens the contacts list instead**

The contact no longer exists, or it belongs to another user. Contacts are private, so a link that another user shares
with you never opens their contact.

**The picker hides a contact for a token**

The token's recipient check refuses the contact's wallet for that action. Ask the counterparty to complete
registration and the verifications the token requires, which [Verify a
participant](https://docs.settlemint.com/docs/console/participants/verify-a-participant) describes, or select **Show all** when you need the
address for another reason.

**The Refresh the ENS avatar control is missing**

The deployment has no ENS configured, so the platform cannot read avatars. The contact keeps the avatar it has.



# Personal

Source: https://docs.settlemint.com/docs/console/personal
The Personal group of the Console sidebar: your private contacts and watchlists, the saved views you keep or share, and the wallets your withdrawals go to.

The **Personal** group holds your own working tools: the "Contacts" you pick from in issuance, transfer and settlement forms, the "Watchlists" that hold the instruments you follow and your price alerts, the "Saved views" you keep from an answer of the Console assistant, and the "Withdrawal destinations" your withdrawals go to when custody operations are on. The Console assistant is the chat that answers from your organisation's data.

Contacts and watchlists are private to you. A saved view stays private until you share it with the organisation. [Watchlists](https://docs.settlemint.com/docs/console/personal/watchlists) covers the lists and [Trading](https://docs.settlemint.com/docs/console/my-assets/trading) covers price alerts.


  - [Contacts](https://docs.settlemint.com/docs/console/personal/contacts): Save counterparty names and wallets to reuse in issuance, transfer and settlement forms.
  - [Watchlists](https://docs.settlemint.com/docs/console/personal/watchlists): Follow assets in named lists, read prices and holdings, and see your price alerts.
  - [Saved views](https://docs.settlemint.com/docs/console/personal/saved-views): Keep the reads behind an assistant answer as a named view, then share and pin it.
  - [Withdrawal destinations](https://docs.settlemint.com/docs/console/personal/withdrawal-destinations): Prove the self-custody wallets your withdrawals go to.



# Saved views

Source: https://docs.settlemint.com/docs/console/personal/saved-views
Save the reads behind an assistant answer as a named view that runs them again with your access, then order it, share it and pin it to your Dashboard.

A saved view keeps the reads behind an answer from the Console [assistant](https://docs.settlemint.com/docs/console/organisation-settings/assistant), the chat that answers from your organisation's data. The reads are the queries that drew the answer's tables and figures. Each time the view opens, every block, one table or set of figures, runs its read again with the access of whoever opens it, so the view shows current data under that person's own permissions. You name your views, order them, share them with the organisation and pin them to your Dashboard.

![Saved views page showing its empty state, the message No saved views yet, with a hint to ask a question and save the answer as a view](https://docs.settlemint.com/docs/screenshots/console-saved-views-page.light.en.webp)

[Screenshot] The Saved views page before any view is saved, with its "No saved views yet" message.

Once you save a view, the page lists your views and the views shared with your organisation beside the blocks of the selected view.

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

- Saving a view needs the assistant switched on for the organisation, because an answer only exists while it is on.
- Existing views open and read again with the assistant switched off.

## Steps [#steps]

### Save an answer as a view [#save-an-answer-as-a-view]

Ask the assistant a question that draws at least one table or one set of figures, then select **Save as view** under the answer.

- The dialog reads "Save this answer as a view" and states what the view keeps: "A view keeps the reads behind this answer, not their results. Each time it opens it reads them again, with what you can see then."
- **Name** starts as your question. A question longer than 80 characters is cut to its first 79 and ends with "…". Change it before you save. A name holds 1 to 80 characters, on save and on rename.
- A block is kept only when its read can be run again: holders, events, holdings, assets, markets, orders, the audit trail, and figures. A rule reading and a check are not offered. A view holds between 1 and 6 blocks.
- A table is kept only when the answer cites at least one of its rows. The view keeps the first 6 blocks. From each block it keeps the identifiers of the first 5 cited rows or the first 8 figures, the read's route, the input it ran with and the units of its figures. It keeps no row values and no answer text, but a cited row's identifier can be a holder's wallet address.
- The platform checks every block before it stores the view: the route must be one that block kind runs again, a rows block must name rows of its own kind, a figures block must name figures of its own read, and an input may hold at most 2,000 characters. When one block fails, the platform refuses the whole view.
- A save past 50 views of your own is refused. In the Console the dialog shows only "The view could not be saved." The Platform API refusal says "You have 50 saved views. Remove one to save another."
- The view stores the scope the answer read, and the platform checks that you can still read that scope when you save.
- After a save the button becomes **Open saved views**, which opens the new view.

### Open Saved views [#open-saved-views]

Select **Saved views** under "Personal" in the sidebar. With no views yet, the page says "No saved views yet" and explains how to save one from an answer. Otherwise it lists your own views and the views shared with your organisation in your order, with the selected view's blocks beside the list. The page lists at most 100 views. On a narrow screen the list scrolls sideways above the view instead.

### Read the blocks of a view [#read-the-blocks-of-a-view]

Each block runs its read again with your access and draws the rows the view kept, as the same table or figure tiles the answer showed.

| What shows in place of a block | Why |
| --- | --- |
| "You cannot see this part of the view." | The read was refused for you. The other blocks still draw. |
| "This part of the view could not be loaded." | The read failed for another reason. **Try again** runs it again. |
| "This part of the view cannot be shown here." | The page cannot draw that kind of block. |

In a view another member shared, the platform also filters each table by your own access. Each time your views load, on this page or under "Pinned views" on Dashboard, the platform runs each table's read again as you and keeps only the cited rows that read returns now, so you never see the identifiers of rows you cannot read. A table whose read is refused keeps its place and shows "You cannot see this part of the view." A read that fails shows "This part of the view could not be loaded." with **Try again**, and one that returns none of its cited rows draws no rows. Figures blocks, and every block of your own views, are not filtered this way.

## Order, share and remove a view [#order-share-and-remove-a-view]

Each view has an **Actions** menu. Every view you can see offers "Add to home" or "Remove from home". It also offers "Move up", except on the first view in your list, and "Move down", except on the last. Your own views also offer "Rename", "Share with the organisation" or "Stop sharing", and "Remove view".

- A shared view carries a **Shared** badge, and the list names who shared it. A pinned view carries an "On home" badge. Only the owner renames, shares or removes it. "Stop sharing" removes the view from every colleague's list and home.
- Sharing shows every member of the organisation the view's name and the scope it reads. A member sees a cited row's identifier only when their own read returns that row, as [Read the blocks of a view](#read-the-blocks-of-a-view) describes. The name starts as your question, so rename the view before you share it if the question names something private.
- **Remove view** asks "Remove `<name>`?" and states "The view is removed for you and for everyone it is shared with. The data it reads is not changed."
- A view you have not moved sits after the views you ordered, newest first. Your order and your home placement are yours alone, shared views included, and sharing a view never changes a colleague's list or home.
- A list that fails to load shows "Saved views could not be loaded." with **Try again**. A rename, share, move or remove that fails shows "The change could not be saved."

## Pin a view to home [#pin-a-view-to-home]

**Add to home** puts the view on Dashboard under "Pinned views", below the panels that need you and what changed, with its blocks and an "Open view" link. "All saved views" opens the full page. With views but none pinned, "Pinned views" says "No saved views on home yet". [Dashboard](https://docs.settlemint.com/docs/console/essentials/dashboard) explains the panels above it.

## Views built from a period summary [#views-built-from-a-period-summary]

A figures block saved from a period summary reads again through the period summary read, with the asset and the window the view stores. A trailing period, such as the last 7 days, reads up to the moment the view opens. A window with fixed dates reads the same period each time. A view never stores the totals, because they age and a reader whose access changed would see numbers they may no longer open.

The table toolbar of Holders, the blocklist, Users and **Actions** has a "Saved views" menu of its own, which keeps filters, sort and columns under a name. [Tables](https://docs.settlemint.com/docs/concepts/operating/table-views) covers that menu.

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

- Open **Saved views**. The new view appears in your list, and its blocks draw the rows the view kept.
- A pinned view also shows under "Pinned views" on [Dashboard](https://docs.settlemint.com/docs/console/essentials/dashboard).

## Troubleshooting [#troubleshooting]

**The list says Saved views could not be loaded**

The read of your views failed. Select **Try again**.

**A rename, share, move or remove fails**

The platform refused or could not store the change. Repeat it. Only the owner of a view renames, shares or removes it.

**The dialog says The view could not be saved**

The platform refuses a view past 50 views, a block it cannot run again, or one whose scope you can no longer read.
Remove a view you no longer need, or save an answer that cites rows of a supported table.



# Watchlists

Source: https://docs.settlemint.com/docs/console/personal/watchlists
Follow assets in lists you name, read their prices and your holdings, trade from a row, and see your price alerts.

Watchlists is where you keep the assets you follow. You name your own lists, add an asset from a search or with the **Watch** star on any asset page, and read each asset's last price, change and your holding beside the instruments it trades as. A row opens the trading workspace for its instrument. Under the lists, "Price alerts" shows the alerts you set on instruments.

A watchlist is yours alone. Nobody else in the organisation sees it, and it belongs to the organisation you are signed in to, so another organisation shows its own lists. Following an asset places no order and changes nothing about the asset or your access to it.

![Watchlists page with no lists yet, a New list button and an empty Price alerts section](https://docs.settlemint.com/docs/screenshots/console-watchlists-page.light.en.webp)

[Screenshot] The Watchlists page with no lists yet, a "New list" button and an empty "Price alerts" section.

With no list yet, the page says "No watchlists yet" and "Create one, or select Watch on any asset.", with a **New list** button. Below it, "Price alerts" says "No price alerts yet". Once you add a list, "My lists" sits beside the assets of the selected list.

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

- Your account must have finished onboarding. The asset search lists EVM assets only. On a deployment that has Canton switched on, it returns nothing while a Canton network is selected.
- Prices come from the venue the asset trades on. An asset that no venue lists as an instrument still sits in your list, with **Not tradable on the venue yet** in place of a price.

## Steps [#steps]

### Open Watchlists [#open-watchlists]

Select **Watchlists** under "Personal" in the sidebar. With no list yet, the page says "No watchlists yet" and "Create one, or select Watch on any asset." with a "New list" button. Otherwise "My lists" shows each list with its name, a "Default" badge on the default list and the number of assets it holds. On a narrow screen the lists run sideways above the selected list.

### Create a list [#create-a-list]

1. Select **New list** to open "New watchlist".
2. Enter a name in **Watchlist name**, up to 80 characters.
3. Select **Create**. The dialog says the list "Saves to your account at once, with no PIN", so no wallet verification is asked. The new list opens.

### Add an asset [#add-an-asset]

Type in **Search by name or symbol** above the list. The results show up to 8 assets, each with its symbol, name and type. Select "Add" beside the asset. An asset already in the list shows "In this list" instead. With no match the search says "No asset matches" followed by your text in quotation marks. "Escape" clears the search.

A notification confirms the addition, as "`{symbol}` added to `{list}`" with the asset's symbol and the list's name, and carries an **Undo** action that removes the asset again for 8 seconds.

### Read the table [#read-the-table]

Each row is one asset. The columns are **Asset**, "Instruments", "Last", "Change", "Previous close", "Open", "Value", "Bid / Ask", "You hold" and "Status", and a column of row actions. The toolbar offers the column picker only, with no search, filter or export. On a narrow screen the table folds some columns away, and the picker shows or hides each one.

- **Asset** shows the symbol, a badge for the asset type and the name. Rows sit in groups by asset type.
- **Instruments** lists the instruments the asset trades as. Each is a link to its trading workspace. A pin marks the instrument you pinned. An instrument the Console cannot load shows as dashed text that is not a link.
- **Last**, "Change", "Previous close", "Open", "Value" and "Bid / Ask" describe the asset's first instrument, the pinned one when you pinned one. A figure the venue has not produced yet shows a dash. "Change" is red when it is negative.
- **You hold** shows your balance of the asset, or a dash when you hold none.
- **Status** shows the instrument's phase as a badge, such as "Open for trading", "Instrument halted" or "Delisted".

### Trade, look closer or remove an asset [#trade-look-closer-or-remove-an-asset]

- **Trade** opens the trading workspace for the asset's first instrument. It is disabled, with "Not tradable on the venue yet", when the asset has no instrument. [Trading](https://docs.settlemint.com/docs/console/my-assets/trading) covers placing an order.
- The eye icon, **Quick view**, opens a panel with the asset's "Name", "Symbol", "Type" and "Address", and under "Instruments for" its symbol each instrument with its phase and a "Pin" or "Unpin" button. "Pin" makes that instrument the one the row's prices and "Trade" use. "Trade" opens the workspace, and "Research" opens the asset's instrument page. An asset with no instrument shows "This asset is not listed as an instrument on any venue".
- The **Actions** menu of a row offers "Move up", "Move down" and "Remove". "Remove" takes the asset off this list only, with a notification and an "Undo" action that puts it back for 8 seconds.

## Order your lists and assets [#order-your-lists-and-assets]

Each list has an **Actions** menu, named for the list, with "Rename", "Make default", "Move up", "Move down" and "Delete list". The default list has no "Make default", and the first and last lists have no "Move up" and no "Move down" respectively.

- **Rename** opens "Rename watchlist" with the current name. Change it, up to 80 characters, and select "Save". "Cancel" closes it.
- **Make default** makes the list the one "Watch" adds to. One list is the default at a time. With no list marked, the oldest list counts as the default.
- **Delete list** removes the list and its entries from your account, with a "Watchlist deleted" notification and an "Undo" action for 8 seconds. "Undo" restores the list and says "Watchlist restored". Deleting needs no wallet verification.
- **Move up** and "Move down" on a row swap the asset with its neighbour in its group. They are disabled, with "Clear the sort to reorder", while a column sort is on.

## Follow an asset from anywhere [#follow-an-asset-from-anywhere]

The **Watch** button with a star appears on an asset's page, on an instrument's page, in the trading workspace and in the holding briefing on your Dashboard. Select it to add the asset to your default list, or to take it out of that list when it is already there. With no list at all, it creates one called "Watchlist" and adds the asset. Once an asset is in a list the button reads "Watching · " followed by the list name, or "Watching · 3 lists" for three.

The arrow beside it opens **Save** followed by the asset's symbol and "to", with a checkbox for each of your lists, so you add or remove the asset per list. "New list" creates a list from there, and "Manage watchlists" opens this page.

## Price alerts [#price-alerts]

Below the lists, **Price alerts** shows the alerts you set on instruments, each with its instrument, condition, status and creation date. [Trading](https://docs.settlemint.com/docs/console/my-assets/trading#set-a-price-alert) explains how to set, read and delete one. Other users never see yours.

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

- Open **Watchlists** and select the list. The asset shows as a row, and the count beside the list's name includes it. The "Watch" button on the asset's own page reads "Watching · " followed by the list name.

## Troubleshooting [#troubleshooting]

**The page says your watchlists could not be loaded**

The page shows "Your watchlists could not be loaded." when the read of your lists fails, and the same message in the
table when the read of one list's assets fails. Select **Try again**.

**An asset does not appear in the search**

The search matches the name and the symbol of EVM assets only. Check the spelling, or search for part of the name. On
a deployment that has Canton switched on, the search returns nothing while a Canton network is selected.

**Every price shows a dash**

The asset has no instrument on a venue you can read, or the venue has not produced that figure yet. **Last**,
"Change", "Previous close", "Open", "Value" and "Bid / Ask" fill in when the instrument trades. An asset with no
instrument shows "Not tradable on the venue yet" and a disabled "Trade".

**Move up and Move down are disabled**

A column sort is on. The rows follow the sort until you clear it, so the menu says "Clear the sort to reorder".

**A deleted list or removed asset did not come back**

**Undo** is on the notification for 8 seconds, and the Console has no other restore action. Create the list again, or
add the asset from the search.

## Frequently asked questions [#frequently-asked-questions]

**Can a colleague see my watchlist?**

No. A watchlist belongs to one user in one organisation, and the Console has no way to share it.

**Does following an asset notify me when it moves?**

No. A watchlist only shows prices. A price alert notifies you when an instrument trades at or beyond a price, and you
set one from the trading workspace.

## API routes [#api-routes]

The same lists are available through the [Platform API](https://docs.settlemint.com/docs/api-reference/v2) under `/api/v2/addons/trading-venues/watchlists`, which lists, creates, renames, reorders and deletes your lists, adds and removes assets, and reorders the assets in a list. Your session is enough, and no request asks for wallet verification. [CLI commands](https://docs.settlemint.com/docs/api-reference/cli/commands) covers the command-line equivalent.


# Withdrawal destinations

Source: https://docs.settlemint.com/docs/console/personal/withdrawal-destinations
Prove the self-custody wallets your withdrawals go to, and read the wallets your custodian holds for you, from the Personal group of the Console.

A withdrawal from your custody wallet goes only to a wallet you proved and a custody operator cleared. **Withdrawal destinations** is where you prove a wallet whose key you hold, and where you read the wallets your custodian holds for you. It is the same page as [Withdrawal destinations in the Investor portal](https://docs.settlemint.com/docs/concepts/operating/investor-portal-wallet-transfers#prove-a-self-custody-wallet-as-a-withdrawal-destination), with the same rows, sheet and refusals. [Custody deposits and withdrawals](https://docs.settlemint.com/docs/concepts/custody-and-signing/custody-deposits-and-withdrawals) explains how a destination is proved, cleared and revoked.

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

- The page needs custody operations turned on for your organisation. Without them, **Withdrawal destinations** is missing from the sidebar, and opening `/personal/wallets` shows "Withdrawal destinations are not available" instead of the list.
- To add a wallet you need a browser wallet holding its key, connected to the network you withdraw on.

## Steps [#steps]

### Open the page [#open-the-page]

Select **Withdrawal destinations** under "Personal" in the sidebar. "Self custody" lists the wallets you added, with the "Wallet", the "Network", the date "Added" and the "State". "Managed custody" lists the wallets your custodian holds for you. A managed custody wallet takes no signature here, because the key stays with the custodian.

### Add and prove a wallet [#add-and-prove-a-wallet]

1. Select **Add a wallet**, then "Connect wallet", and approve the connection in your browser wallet. The connected wallet is the destination, on the network the wallet is connected to.
2. Select **Add wallet** and approve the signature request. Signing sends no transaction and costs no gas. The row shows "Awaiting clearance".
3. A custody operator reviews the wallet. Cleared, it shows "Active" and withdrawals can go to it. Refused, it shows "Refused" with the operator's reason under the state.

### Sign again or remove a wallet [#sign-again-or-remove-a-wallet]

A row in "Awaiting signature" has no accepted signature yet. Select **Sign the challenge** on the row, connect the same wallet on the same network, and sign. The platform issues a fresh challenge for the same entry.

**Remove** asks you to confirm, then moves the row to "Removed". A removed wallet takes no new withdrawal, and adding it again needs a new signature and a new clearance.

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

- A wallet is ready when its row reads "Active". It then appears as a destination in the **Withdraw** sheet on [Portfolio](https://docs.settlemint.com/docs/console/my-assets/portfolio#withdraw-from-your-gateway) for a withdrawal on that network.


# Platform assistant

Source: https://docs.settlemint.com/docs/console/platform-admin/assistant
Switch the Console assistant on or off for every organisation on the platform, and see whether the platform has a free assistant key.

**Platform assistant** holds one switch that turns the Console assistant on or off for every organisation on the DALP Instance, and one line that says whether the platform has a free assistant key, the key the deployment supplies for organisations that have none of their own. The switch is on until a platform administrator turns it off, and it sits above each organisation's own assistant settings: while it is off, no organisation can use the assistant, whatever its own settings say.

What the assistant sends to a model is set per organisation, by an organisation owner or a platform administrator on the **Assistant** page in "Organisation settings". [Assistant data](https://docs.settlemint.com/docs/concepts/operating/assistant-data) describes it.

![Platform assistant page with the Assistant on this platform switch and the Free assistant key line](https://docs.settlemint.com/docs/screenshots/console-platform-admin-assistant.light.en.webp)

[Screenshot] The "Platform assistant" page with the "Assistant on this platform" switch and a line under it that says what the switch does now.

Below the switch, the **Free assistant key** row says whether a platform key is configured.

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

- You need the platform administrator role. It is set on your account, not in one organisation, and an organisation **Owner** does not have it. The platform refuses the page and its requests to every other account.
- The deployment sets the free assistant key. The **Free assistant key** row only reports whether the platform has one.

## Steps [#steps]

### Open Platform assistant [#open-platform-assistant]

Open "Platform admin", then **Platform assistant**. The page loads the current state of the switch and of the key. If the load fails, the page shows "Platform assistant switch unavailable" with "Nothing was changed. Try again." and a retry control.

### Switch the assistant on or off [#switch-the-assistant-on-or-off]

Select the **Assistant on this platform** switch. The change saves at once, with no confirmation. While it saves, the page shows "Saving…", and when it finishes, "Saved". If the save fails, the page shows "The platform switch could not be saved." and the switch keeps its earlier state. A saved change writes an [Audit trail](https://docs.settlemint.com/docs/console/reporting/audit-trail) entry with your name and the old and new state. The entry belongs to no organisation, because the change reaches every organisation, so no organisation's Audit trail lists it. A platform administrator reads it through the platform-wide query of the [audit trail](https://docs.settlemint.com/docs/concepts/records-and-evidence/audit-trail).

When the switch is on, the line under it reads "Organisations can use the assistant unless they turned it off themselves." When it is off, the line reads "The assistant is off for every organisation, including those with their own key. Questions are refused until you switch it back on."

### Read the free assistant key [#read-the-free-assistant-key]

The **Free assistant key** row reads one of two lines:

- "A platform key is configured. Organisations without their own key use it."
- "No platform key is configured. Only organisations with their own key can use the assistant. The key is set in the deployment, not on this page."

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

- After you switch the assistant off, the line under the switch changes to the off message, and a member who asks the assistant a question is refused.
- After you switch it on, the line changes to the on message.
- Reload the page to confirm that the switch kept the state you chose.

## Troubleshooting [#troubleshooting]

**Platform assistant is missing from the sidebar**

The entry appears only for a platform administrator. Ask a platform administrator to change your platform role on
[Platform users](https://docs.settlemint.com/docs/console/platform-admin/users).

**The switch is on but an organisation still cannot use the assistant**

The platform switch only allows the assistant. An organisation turns it off for itself on its own "Assistant" page in
"Organisation settings", and an organisation with no key of its own needs the platform to have a free assistant key.
Read the **Free assistant key** row: when it says no platform key is configured, only organisations with their own key
can use the assistant.

**The page says the platform switch could not be saved**

The switch keeps its earlier state and nothing changed. Select the switch again.

## API routes [#api-routes]

The page reads and writes the switch through `GET /api/v2/assistant/platform` and `PATCH /api/v2/assistant/platform`. Both are limited to a platform administrator. The [Platform API reference](https://docs.settlemint.com/docs/api-reference/v2) has the request and response shapes.


# Base calendars

Source: https://docs.settlemint.com/docs/console/platform-admin/base-calendars
Publish the platform-wide holiday calendars that every organisation can extend, and close days on them for every organisation at once.

A base calendar is a holiday calendar the platform offers to every organisation: a named list of closed days for one market, such as the TARGET2 settlement calendar. An organisation does not edit a base calendar. It extends one: its own calendar, created on [Holiday calendars](https://docs.settlemint.com/docs/console/organisation-settings/holiday-calendars), inherits every day the base closes and adds days of its own. Filing deadlines that count business days skip those closed days, and a trading venue does not trade on them.

**Base calendars** is where a platform administrator publishes these calendars and keeps their closed days current. A day closed here reaches every organisation calendar and every venue that extends the base, directly or through another calendar. No organisation can remove the day from the base. A calendar stops inheriting it only when its owner points it at another parent.

Use this page when a market publishes a holiday that a base calendar does not carry, or when organisations on the platform need a base for a market the platform does not ship. Do not use it for a closure that applies to one organisation only: that organisation closes the day on its own calendar, and no other organisation sees it.

![Base calendars list with each calendar's name, jurisdiction, closed days this year and next closure](https://docs.settlemint.com/docs/screenshots/console-platform-admin-base-calendars.light.en.webp)

[Screenshot] The "Base calendars" table, one row for each base calendar, with the columns "Calendar", "Jurisdiction", "Closed this year", "Next closure" and "Actions", where each row offers "Close a day".

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

- You need to be a platform administrator. **Base calendars** appears under "Platform admin" in the sidebar only for a platform administrator, and the platform refuses every read and write on this page from any other account, including an organisation owner.
- Have the market's published source for the date in front of you. A base calendar has no review step, and a closed day reaches every organisation that extends the calendar as soon as you confirm. Publishing a base calendar cannot be undone.
- Decide the calendar's name before you publish it. The platform derives the calendar's identifier from the name, so the Console offers no rename, and organisations see the name in every list where the calendar is offered. Use Latin letters or digits: accented letters are fine, but a name with a letter from another script forms no identifier.

## Steps [#steps]

Skip **Publish a base calendar** when the calendar already exists.

### Open Base calendars [#open-base-calendars]

Open "Platform admin", then **Base calendars**. The table lists every base calendar with its "Calendar" name, its "Jurisdiction", the days it has "Closed this year" and its "Next closure". When you expand a row, its closed days appear grouped by year. Each day shows its reason and its source. A day closed on this page reads "Platform administrator". A shipped day shows its dataset tag, such as "seed:target2:v1", or for ADGM the government announcement it came from. The screen shows the kind of administrator, while the platform stores the administrator's user ID with the day and the audit trail entry names them.

### Publish a base calendar [#publish-a-base-calendar]

Select **Publish calendar**. In the sheet, enter a "Name" and choose a "Jurisdiction": a country, or a regional code such as EU. The Console refuses a "Name" that matches an existing calendar. The jurisdiction is a label and does not change which days are closed. You can add a "Reason (optional)", which the platform stores on the [Audit trail](https://docs.settlemint.com/docs/console/reporting/audit-trail) entry for the change. That entry belongs to no organisation, because the change reaches every organisation, so no organisation's Audit trail lists it. A platform administrator reads it through the platform-wide query of the [audit trail](https://docs.settlemint.com/docs/concepts/records-and-evidence/audit-trail). Select "Publish calendar". A base calendar published through this Console form extends nothing.

Publishing cannot be undone. The Console and the Platform API have no delete for a base calendar, and organisations can extend it from the moment it is published.

The calendar is offered to every organisation as soon as "The base calendar is published." appears, even before it closes any day. An organisation that extends an empty base inherits nothing until you close days on it. A deadline calculation refuses a calendar with no closed day effective on the date it computes for, because every day would count as a business day. Publish the relevant closed days before organisations use the new base for reporting.

### Close a day [#close-a-day]

On the calendar's row, select **Close a day**. Choose the "Date" in the calendar and choose a "Reason": "Public holiday", "Bank holiday", "Settlement holiday", "Exchange holiday" or "One-off closure". You can also enter a "Name (optional)" for the day. The calendar offers days from 1 January 2024 through 31 December of the tenth year after the current year. The reason is a label for readers of the calendar. Every closed day counts the same way for deadlines and venues, whatever its reason.

Select "Close a day". A second dialog names the day, for example "Close 24 Dec 2026?". Check the date against the published source, type the date exactly as the dialog shows it, then select **Close 24 Dec 2026** to add it.

## What the platform ships [#what-the-platform-ships]

Four base calendars are present on every platform before an administrator adds anything:

| Calendar | Jurisdiction | What it closes |
| --- | --- | --- |
| "TARGET2 settlement calendar" | EU | The published TARGET2 closing days, computed for 2024 through 2040 |
| "UK bank holidays (England and Wales)" | GB | The UK bank holidays for England and Wales, computed from their rules for 2024 through 2040 |
| "US federal holidays" | US | The US federal holidays, computed from their rules for 2024 through 2040 |
| "ADGM business days (UAE public holidays)" | AE | Only the UAE public holidays already announced |

The ADGM calendar holds announced dates only, because the UAE can move a public holiday after the rules would place it. Close each new UAE holiday on it once the date is announced. The other three calendars need a new closed day only when the published rules change or a one-off closure is declared. Their computed dates end with 2040. The shipped calendars use the identifiers `target2`, `uk-bank-england-wales`, `us-federal` and `adgm`.

## How a closed day takes effect [#how-a-closed-day-takes-effect]

Every day closed on this page records when the platform learned about it, and the shipped days count as known from the start. A filing deadline counts only the closed days the platform knew about when it computed that deadline. A day you close applies to deadlines computed after you close it and leaves earlier deadlines where they are, so close a missed holiday before deadlines that need it are computed.

A venue's **Trading calendar** tab states the rule under "Closed days": "Days from the shared calendar shut every venue that uses it." A day you close on a base therefore shuts every venue whose calendar chain reaches the base. [Trading calendar](https://docs.settlemint.com/docs/console/asset-lifecycle/venues/trading-calendar) explains what an instrument does on a day with no session. [Reporting obligations](https://docs.settlemint.com/docs/concepts/records-and-evidence/reporting-obligation) describes how a deadline rule counts business days from the calendars it names.

A closed day stays on the calendar it was closed on and is never removed. The dialog states the rule: "A closed day is added, never removed. Every organisation that extends this calendar sees the day closed and cannot reopen it. A correction published later never moves a deadline that was already computed." A base that extends another base loses the parent's days if a platform administrator changes its parent through the API, so treat a parent change as a change to every extending calendar.

[Figure] A day closed on a base calendar reaches every calendar that extends it. A platform administrator closes 26 December on the base calendar UK bank holidays for England and Wales. Three calendars extend that base: one organisation's calendar, a second organisation's calendar, and the extension the platform creates when a venue picks the base directly. Each of them inherits 26 December. No organisation can reopen it, and a day an organisation closes on its own calendar stays with that organisation. Labels: UK bank holidays; Closes 26 Dec; Base calendar; Extended by; Organisation A calendar; 26 Dec inherited, plus its own days; Organisation B calendar; 26 Dec inherited, plus its own days; Venue extension; 26 Dec inherited, mirrors the base; No one; below the; base can; reopen a; day it closes.; Days an; organisation; closes stay; with it.

One closed day on a base calendar reaches every calendar that extends it, across every organisation.

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

- "The day is closed." confirms the write, and the day appears under its year in the calendar's expanded row with "Platform administrator" as its source.
- To see the effect from an organisation's side, open [Holiday calendars](https://docs.settlemint.com/docs/console/organisation-settings/holiday-calendars) in an organisation whose calendar extends this base: the day appears there with "from" and the base calendar's name in the **Added by** column.

## Troubleshooting [#troubleshooting]

**Base calendars is not in the sidebar**

The entry appears only for a platform administrator. An organisation owner manages the organisation's own calendars on
[Holiday calendars](https://docs.settlemint.com/docs/console/organisation-settings/holiday-calendars) instead.

**Publish calendar stays unavailable**

**Publish calendar** needs a free name and a jurisdiction. "A calendar with this name already exists. Choose another
name." means the name produces the identifier of an existing base calendar. A name that matches an existing calendar
apart from case and spacing is refused too, such as "US Federal Holidays" for the shipped "US federal holidays". Names
that differ only in punctuation, such as "Bank holidays" and "bank-holidays", produce the same identifier. Accented
Latin letters fold to their plain letter, so "Café" gives "cafe", and a name with no letter or digit, or with a letter
or digit from another script such as Chinese, Cyrillic or Arabic, produces no identifier at all. If another
administrator publishes that name while your form is open, your publish is refused. The existing calendar stays
unchanged, and your form keeps its inputs. Choose another name and publish again.

**A day was closed on the wrong date**

The day stays closed on the base and on every calendar that extends it. Deadlines computed before the mistake keep
their dates. Close the correct date as well, and tell the organisations that extend the calendar, because their
deadlines computed from now on skip both days and their venues do not trade on either. The Console has no list of the
calendars that extend a base, so tell every organisation on the platform.
[Organisations](https://docs.settlemint.com/docs/console/platform-admin/organisations) lists them.

**An organisation reports a deadline that ignores a new holiday**

The deadline was computed before the holiday was closed on the base. A deadline counts only the closed days the
platform knew about when it computed it, so the new holiday applies to deadlines computed after it.

## Frequently asked questions [#frequently-asked-questions]

### Can an organisation stop inheriting a base calendar's day?

Not one day on its own. An organisation calendar that extends a base inherits every day the base closes. To stop inheriting them, the organisation changes its calendar's parent or creates a calendar that extends nothing and closes its own days.

### Does a base calendar need weekend closures?

No. A filing deadline never counts Saturday or Sunday as a business day, and each venue sets its own trading week. Close a weekend day on a base only if a venue that trades at weekends must not trade on it.

### Who sees a day an organisation closes?

Only that organisation. A day reaches other organisations only when it is closed on a base calendar.

## API routes [#api-routes]

The platform administration calendar endpoints are `GET /api/v2/admin/calendars` to list base calendars, `PUT /api/v2/admin/calendars/{calendarId}` to publish or update one, and `POST /api/v2/admin/calendars/{calendarId}/closures` to add a closed day. Send `If-None-Match: *` with the `PUT` to refuse an id that exists. Without it, a `PUT` to an existing id replaces its name, jurisdiction and parent. Anyone who is not a platform administrator is refused with `platform.http.ACCESS_DENIED`. The Console offers none of these updates. A base that extends another base inherits its closed days. The request and response shapes are in the [Platform API reference](https://docs.settlemint.com/docs/api-reference/v2).


# Platform admin

Source: https://docs.settlemint.com/docs/console/platform-admin
The seven Console screens that act on the whole platform, shown only to a platform administrator.

The **Platform admin** group holds the screens that act on the whole platform rather than on one organisation. Only an account with the "Administrator" platform role sees it, and owning an organisation does not give that role. From "Platform users" an administrator can also act inside any organisation by impersonating one of its members, and from "Organisations" can archive an organisation.


  - [Organisations](https://docs.settlemint.com/docs/console/platform-admin/organisations): Review every organisation on the platform, and archive or restore one.
  - [Platform users](https://docs.settlemint.com/docs/console/platform-admin/users): List, inspect and maintain any account: role, ban, sessions, password and closure.
  - [Platform networks](https://docs.settlemint.com/docs/console/platform-admin/networks): Add a network to the catalogue, manage its RPC endpoints and set what onboarding offers.
  - [Indexing scope](https://docs.settlemint.com/docs/console/platform-admin/indexing-scope): Choose which announced systems the Ledger Data reads expose on each network.
  - [Platform assistant](https://docs.settlemint.com/docs/console/platform-admin/assistant): Switch the Console assistant on or off for every organisation on the platform.
  - [Base calendars](https://docs.settlemint.com/docs/console/platform-admin/base-calendars): Publish the holiday calendars every organisation can extend, and close days on them.
  - [Operator wallets](https://docs.settlemint.com/docs/console/platform-admin/operator-wallets): Read the native balance of each operator wallet and see which ones run low.



# Indexing scope

Source: https://docs.settlemint.com/docs/console/platform-admin/indexing-scope
Choose which announced systems the Ledger Data reads expose on each network.

Indexing scope sets which announced systems the Ledger Data reads return on each network in the platform's catalogue. The Ledger Data is the platform's off-chain layer that turns on-chain activity into queryable data. A system is announced once the platform has recorded its address on a network, whether or not an organisation is linked to it.

On every network the indexer follows, it indexes each announced system and the contracts it deploys, in scope or not. Excluding a system deletes nothing and does not stop the indexer. It sets a scope flag that the platform's reads filter on, so the system's data stays indexed and current while reads stop returning it. An organisation's Console screens that read an excluded system show no data for it, and the organisation gets no notice of the change.

The page does not change what an organisation can do on-chain. The contracts of an excluded system stay as they are on the network.

![Indexing scope page grouped by platform network](https://docs.settlemint.com/docs/screenshots/console-platform-admin-indexing-scope.light.en.webp)

[Screenshot] The page groups announced systems by network and shows each one's status: "Hidden from reads", "Catching up", "Attention", or "In reads".

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

- You need the **Administrator** platform role on your own account. Both the Console and the server check it. It is one of the two platform roles, "Administrator" and "Member", and is set on your account, not in an organisation.

## Steps [#steps]

### Open Indexing scope [#open-indexing-scope]

Open "Platform admin", then **Indexing scope**. Each network lists its announced systems, 50 at a time. Select "Show more" for the rest. A system on a chain the platform's catalogue does not carry appears under a plain `Chain <id>` heading instead of a network name.

### Change the scope [#change-the-scope]

Use the **Include in reads** switch on a system's row to change its scope. Both directions apply at once for every organisation that uses the system, with no confirmation and no second approver. After you exclude a system, a message offers "Undo" for a few seconds, which includes the system again. Excluding a system also excludes every contract it deployed, even ones you never selected.

## What excluding a system does [#what-excluding-a-system-does]

A system is either included or excluded. There is no reduced sampling rate and no partial history window. Include a system when an organisation's screens need to read its activity, token list, balances or history. Exclude a system when its data must not appear in platform reads, for example a system that a failed deploy announced and no organisation uses. Excluding a system does not reduce the indexer's workload.

Each change writes an [Audit trail](https://docs.settlemint.com/docs/console/reporting/audit-trail) entry with your name and the old and new scope. The entry belongs to no organisation, because the change reaches every organisation, so no organisation's Audit trail lists it. A platform administrator reads it through the platform-wide query of the [audit trail](https://docs.settlemint.com/docs/concepts/records-and-evidence/audit-trail).

[Figure] Excluding a system: what the scope flag reaches, and what it leaves alone. Setting the scope flag marks a system excluded and carries down to every contract that system deployed, even ones never selected individually, so reads hide the whole hierarchy at once. The flag only changes what reads return: the indexed data for the system and its contracts is untouched, shown dashed off to the side, and the indexer keeps it up to date. Labels: Scope flag; Set here; System excluded; Hidden from reads; Contracts it deployed; Cascades, no opt-out; Indexed data; Untouched, still indexed.

Excluding a system also excludes everything it deployed, and a dashed line marks the indexed data that exclusion never reaches.

Note (Re-including a system needs no replay): The indexer keeps indexing an excluded system, so its data is already current when you include it again. The system shows **Catching up** only until the indexer confirms it has processed the chain to its current head.

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

- Confirm that the system shows the expected scope state.
- The platform applies the scope filter at read time, so the change applies to the next read.
- A system's state is one of "Hidden from reads", "Catching up", "Attention", or "In reads".
- A newly included system shows "Catching up" until the indexer has processed the chain to its current head and finished any contract backfill, then settles to "In reads".
- "Attention" means at least one of the system's child contracts failed to index.
- The platform shows "Attention" instead of "Catching up" even while backfill is still running: a system that is both failing and behind still needs a platform administrator to look at it.

## Troubleshooting [#troubleshooting]

**The page is empty and reads No systems announced yet**

The platform has no systems available for scope selection. Confirm that an organisation has announced a system on a
network in the platform's catalogue.

**An organisation reports missing indexed data for a system**

Check whether indexing scope excludes that system on the network it runs on: exclusion hides the system's data from
reads. Including it again makes the data readable.

**Excluding a system also hid data for a contract you expected to keep**

Check whether the affected contract was deployed beneath the system you excluded: exclusion cascades down the whole
hierarchy, as [Change the scope](#change-the-scope) describes.

## Frequently asked questions [#frequently-asked-questions]

### Is a newly announced system indexed automatically?

The indexer indexes every announced system on a network it follows. An announcement alone does not add the system to the scope, so its data stays out of reads until you include it. A system the platform deployed for an organisation is in scope from the start.

### Can I exclude a system for one organisation but leave it included for another?

No. Indexing scope is a property of the system on that network, not of any organisation that uses it. Two organisations can legitimately point at the same system address. Toggling that system's scope changes what reads expose for both of them together, and the Console has no control that scopes reads to a single organisation's view of a shared system.

### What does **No organisation** next to a system mean?

It means no organisation's account points at that system's address. One cause: a deploy that fails partway through announces the system address on-chain without linking any organisation to it in the platform's records. The system still shows up for scope selection, and including or excluding it works the same as for any other system.

### Does disabling a network in the platform's network catalogue also change the scope of its systems?

No. A disabled network still lists its systems with a working **Include in reads** switch on each, because the scope you set applies as soon as the platform re-enables the network. Disabling a network is a separate control in the [platform's network catalogue](https://docs.settlemint.com/docs/console/platform-admin/networks). It does not change what reads would expose for that network's systems once the network comes back.

### Why does a system show under a chain number instead of a network name?

The system's chain has no entry in the platform's network catalogue, so the page shows a plain `Chain <id>` heading, such as `Chain 84532`. The indexer does not follow a chain outside the catalogue, so the system has no indexed data yet. You can still set its **Include in reads** switch, and the scope applies once the network is added to the catalogue.


# Platform networks

Source: https://docs.settlemint.com/docs/console/platform-admin/networks
Add a network to the platform catalogue, manage the RPC endpoints the platform reaches it through, and decide whether onboarding offers a choice of network.

**Platform networks** holds the platform's network catalogue: every network the DALP Instance can use, and the pool of remote procedure call (RPC) endpoints the platform reaches each one through. An RPC endpoint is the address of a node that answers chain reads and accepts transactions. Every organisation on the platform shares this catalogue, so a saved change reaches each organisation that uses the network, and the platform applies it without a restart.

Use this page to put a network in the catalogue before any organisation can add it, to change a network's endpoints or settings, or to check endpoint health. An organisation adds an enabled catalogue network to itself on its own [Networks](https://docs.settlemint.com/docs/console/organisation-settings/networks) page.

The page also carries the **Offer network choice at onboarding** switch. It decides what the next organisation onboarding offers. When it is off, a new organisation starts on the default network. When it is on, onboarding offers every enabled network. The switch takes effect at once and changes nothing for organisations that already exist. It does not turn on an organisation's own "Multi-network support" switch. [Two switches with similar names](https://docs.settlemint.com/docs/console/organisation-settings/networks#two-switches-with-similar-names) says who sets each one and in which order.

![Platform network catalogue with network cards and endpoint state](https://docs.settlemint.com/docs/screenshots/console-platform-admin-networks.light.en.webp)

[Screenshot] The platform network catalogue with the onboarding switch, a filter, an "Add network" button and one card per network.

The onboarding network choice switch carries its effect line. Each card shows the network name, the chain name and chain ID, "Enabled" or "Disabled", a "Default" marker on the default network, the indexing state, and the stored RPC endpoints with their health.

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

- The RPC endpoint pool you manage here serves the indexer and the Platform API. The transaction engine does not use it: it signs and broadcasts only through the endpoints in the deployment values, so an endpoint added here gives it no failover. A network you add only on this page is missing from the deployment values. It has no WebSocket endpoint, so the indexer does not index it, and the transaction engine, which reads only the deployment values, does not reach it. Declare the network in the deployment values, with its WebSocket endpoint, before an organisation deploys to it. [Node and endpoint requirements](https://docs.settlemint.com/docs/deployment/networks#node-and-endpoint-requirements) covers what each network needs.
- You need the **Administrator** platform role on your own account. Without it, the page shows "Not available", and the platform refuses every request to change the catalogue, the onboarding switch or an endpoint pool. Have the chain ID or the built-in chain alias of the network, and at least one RPC endpoint URL with its credential, if the provider needs one.

## Steps [#steps]

### Open Platform networks [#open-platform-networks]

In the sidebar, open "Platform admin", then **Platform networks**. The switch "Offer network choice at onboarding" sits at the top, with one line that states its current effect. Below it, the catalogue shows one card per network. Type in "Filter by name or chain ID" to narrow the cards.

### Add a network [#add-a-network]

Select **Add network** to open the "Add a network" sheet, then fill in the network definition:

- Enter a **Network name**. The name identifies the network everywhere and cannot change later.
- Under **Chain definition**, choose "Built-in chain" and enter a "Chain alias", such as `sepolia`, or choose "Custom chain" and enter a "Chain ID" and a "Chain name". The native currency, block explorer and Multicall3 fields describe the chain.
- Leave **Enabled** on if the network should be offered as soon as its endpoints are saved.

Under "RPC endpoints", select **Add endpoint** for each endpoint, then fill in its fields:

- Choose a **Provider**: a hosted RPC provider that takes an API key header, "Private node" for your own node behind basic authentication, or "Local node" for a node on the local network with no credentials.
- Enter the **URL** and the credential the provider needs.
- Once the pool has two or more endpoints, set each endpoint's **Priority**.

The platform stores credentials encrypted, and the browser does not keep them. At least one endpoint is needed.

When a pool has more than one endpoint, the indexer sends each call to one endpoint. Set a higher **Priority** on the endpoint you want used first. A higher "Priority" wins. Among endpoints with the same priority, health score, then the order you entered them, decides. An endpoint that trails the chain head too far, or whose health score is too low, is left out of routing while a usable endpoint remains, and a failed call moves to the next endpoint. Priority sets an order of preference. It does not split traffic by percentage.

Select **Add network**. The platform saves the network in three steps: it stores the definition as disabled, then saves the endpoints, then enables the network if you left "Enabled" on. A network is never enabled without endpoints. If a step after the first fails, the network stays in the catalogue as disabled, and the sheet says which part is left to save.

![Add a network sheet with the network definition and its RPC endpoints](https://docs.settlemint.com/docs/screenshots/console-platform-admin-networks-add-network.light.en.webp)

[Screenshot] The "Add a network" sheet, where you define the network and add at least one RPC endpoint.

The sheet shows the "Enabled" switch, "Network name", "Chain definition", the chain fields, "Advanced settings", and the "RPC endpoints" list with "Add endpoint".

**Advanced settings** holds the finality fields "Supports the finalized block tag" and "Finality confirmations", and the chain reorganisation depth field, "Reorg depth". Leave the depth empty: the indexer then keeps the larger of the finality distance and 64 blocks. [Finality](https://docs.settlemint.com/docs/deployment/networks#finality) gives the right values per network type, and [Chain reorganisation handling](https://docs.settlemint.com/docs/deployment/networks#chain-reorganisation-handling) explains the depth.

## Edit a network or its endpoints [#edit-a-network-or-its-endpoints]

On the network's card, select **Edit network**. The edit sheet holds the same definition fields and the endpoint list, and saving writes the whole definition. Some networks come from the deployment configuration, the network list the operator sets when installing the platform. When you change the definition of such a network, the sheet shows "This creates a registry override": your saved definition replaces the configured one until you remove it.

The chain of a network that already has stored RPC endpoints is locked, because those endpoints answer for the current chain. To move to another chain, remove the network and add it again on the chain you want.

If someone else saved the same network after you opened the sheet, the platform refuses your definition change and overwrites none of it. Endpoint changes in the same save are kept. Reload the stored definition and make the change again.

## Tune gas, funding and RPC behaviour [#tune-gas-funding-and-rpc-behaviour]

Open **Advanced settings**. Every field there is optional. Leave a field unset to keep the platform default.

**Chain charges no gas** is on both the add sheet and the edit sheet. Left unset, the platform probes the chain once, caches the answer, and shows what it found. Set it only to overrule a wrong probe. If you set it to "Yes" on a chain that does charge gas, funding protection turns off and an unfunded transaction fails at the node.

The edit sheet adds the tuning groups, including "Gas and funding", "Endpoint health scoring" and "RPC call limits". In **Gas and funding**, an empty field inherits its value, and the placeholder shows the inherited figure with its source underneath: "Set on this network", "Inherited from the deployment values", "Inherited from the chain default", "Inherited from the platform default" or "Detected on the chain". A value you type is fixed on this network until you clear the field. [Gas settings](https://docs.settlemint.com/docs/deployment/gas-settings) lists every key, its unit, its accepted range and its default.

## Remove a network [#remove-a-network]

A network that you added in the Console shows **Remove network**. Removing it takes it out of the catalogue and clears its saved RPC endpoints. A network from the deployment configuration shows "Remove override" only after it has been edited here. Removing the override restores the configured network and keeps its RPC endpoints. A configured network that was never edited has no remove control.

Note (A pool change reaches operations already in progress): Indexer and Platform API reads use the saved pool as soon as the platform reloads it, including the reads for a transaction that a user began preparing before you saved. The previous pool is not kept. The transaction engine still broadcasts through the endpoints in the deployment values. Check the endpoint addresses and the chain before you save.

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

- The card shows the expected "Enabled" or "Disabled" state, the chain name and chain ID, and the stored RPC endpoints. Each endpoint shows a health badge: **Healthy**, "Unhealthy", "Excluded" or "Not measured", and "Serving now" marks the endpoint that takes calls.
- For an enabled network that the deployment values also declare with its WebSocket endpoint, the indexing state moves to **Catching up** or "Live", and the committed block height advances. A network added only on this page stays unindexed.
- Each saved change writes an [Audit trail](https://docs.settlemint.com/docs/console/reporting/audit-trail) entry with your name. The entry belongs to no organisation, because the change reaches every organisation, so no organisation's Audit trail lists it. A platform administrator reads it through the platform-wide query of the [audit trail](https://docs.settlemint.com/docs/concepts/records-and-evidence/audit-trail).

## Troubleshooting [#troubleshooting]

**Add network is unavailable**

The catalogue must be read in full before a new name can be checked for duplicates. The button stays unavailable while
the catalogue loads, when stored override status cannot be read, and when the catalogue has more than 200 networks.
The page then shows the notice "Showing the first 200 networks", with the count of networks it does not list, and the
filter does not cover those. Adding a network stays unavailable until the catalogue fits one page.

**A network cannot be enabled**

A network with no RPC endpoints cannot be enabled, because the platform could not reach it. Add an endpoint in the
edit sheet, then turn on **Enabled**. Enabling is also refused when another enabled network already serves the same
chain ID. The message names that network. Disable or remove that network first.

**Token writes answer that the requested network is disabled**

When every network on a chain ID is disabled, token writes on that chain are refused with `409`
`core.network.NETWORK_DISABLED`, error [DALP-12297](https://docs.settlemint.com/docs/api-reference/errors). The API response names the network in
`data.networkName`. Enable that network, or enable another network on the same chain ID, then send the write again.

**Saving refuses an endpoint address**

The platform refuses an endpoint it would never call: a URL that embeds credentials or carries a query string or
fragment, or a host name that resolves to a loopback, private, carrier-grade NAT, link-local, reserved or multicast
address. Link-local covers cloud metadata services. It also refuses an endpoint that answers with a different chain ID
than the network's. The network definition stays saved, the pool is not written, and the error names the refused
endpoint. Enter credentials in the credential fields, and use an endpoint that resolves to a public address. Only a
network whose deployment values set `rpc.allowPrivateUpstreams` accepts private addresses, and the Console cannot
change that setting. See [Networks](https://docs.settlemint.com/docs/deployment/networks). An endpoint that does not answer at save time is still
saved.

**Disabling or removing a network is refused**

The platform refuses a change that would leave a chain without an enabled network while an organisation has a system
pending, deploying or active on that chain. The message names the chains. A second network cannot be enabled on a
chain that an enabled network already serves, so keep the network enabled and change its RPC endpoints instead.

**Saving refuses a pool with no endpoints**

The Platform API refuses a pool replacement that lists no endpoints with `422` (`PLATFORM_RPC_POOL_EMPTY`) and leaves
the stored pool as it was. List at least one endpoint. To remove a pool, delete it instead of saving it empty.

**Reads or transactions on a network fail right after a change**

Confirm the saved endpoints are reachable from the platform, not only from your browser. Indexer and Platform API
reads on that network go through the pool you saved, and the previous pool is not kept. Check the health badges on the
card: **Excluded** explains why routing leaves an endpoint out, for example how many blocks it trails the chain head.

**One endpoint is unreliable but the network still works**

The platform routes around an unhealthy endpoint while another usable one remains. [Selection and
hysteresis](https://docs.settlemint.com/docs/deployment/networks#selection-and-hysteresis) gives the thresholds that leave an endpoint out of
routing. Lower the unreliable endpoint's **Priority**, or remove it once another usable endpoint is in the pool.
Priority must stay a whole number of 1 or more.

**A card shows Rejected**

A stored network definition that the platform cannot serve stays in the list with the reason, instead of disappearing.
Examples: the stored definition contains credentials, its chain ID is already used by another network, or it would
create a second default network. Edit or remove the stored definition. Add credentials through the RPC endpoint
fields, never in the definition.

**A gas figure I saved is not the one the platform uses**

Check that you saved it on the network you meant. A typed figure applies to that one network only, so a figure saved
on a disabled catalogue entry for the same chain has no effect. Reopen the edit sheet: a field you set shows your
value, and an empty field shows the inherited figure with its source underneath.

**A funding request expires before anyone can act on it**

Raise **Funding pause window (seconds)** on that network. The platform default of 30 minutes, which the deployment
configuration can change per network, suits a deployment where someone can top up a wallet within that time. A chain
funded by hand from a treasury needs a longer window, because work that waits for funds fails when the window runs
out.

**A network card says new-token detection is off**

The network's RPC provider refuses the log query the platform uses to find tokens it has not seen before, so the
platform tracks only the tokens it already knows on that network. The card shows when the platform last checked the
provider, and the platform checks again at an interval the deployment sets, 10 minutes by default. When the provider
answers again, the card clears and the platform scans the period when detection was off, so deposits of new tokens
made in that period are detected. The [Why does a network show that new-token detection is
off?](https://docs.settlemint.com/docs/deployment/runbooks/ledger-indexing-stalled#why-does-a-network-show-that-new-token-detection-is-off) entry
in the Ledger indexing stalled runbook explains the cause and the fix.

**A card shows Stalled or Head unknown**

"Head unknown" means no RPC endpoint of the enabled network answered with the chain head. Check the endpoints and
their health. "Stalled" means indexing has committed no new block for a while although the chain has moved on. The
card's **Pause indexing** switch, shown when the network has RPC endpoints, stops and resumes indexing for the
network. Pausing stops new chain data for every organisation on that network until you resume it. The [Ledger indexing
stalled](https://docs.settlemint.com/docs/deployment/runbooks/ledger-indexing-stalled) runbook covers the causes.



# Operator wallets

Source: https://docs.settlemint.com/docs/console/platform-admin/operator-wallets
Read the native balance of every operator wallet the platform tracks, see which ones run low, and know which wallet to fund on which network.

**Operator wallets** lists the operator wallets the platform pays network fees from, with the native balance last observed for each on its network. A wallet appears here once the deployment configuration names it. The view is read-only: it has no control to fund, register or remove a wallet.

Read it to find the wallet that runs low before a transaction waits for funds. [Operator wallet](https://docs.settlemint.com/docs/concepts/custody-and-signing/operator-wallet) explains why the platform keeps these wallets and what happens when one empties.

![Operator wallets page with the Platform wallets table showing each wallet's address, status, purpose, network and native balance](https://docs.settlemint.com/docs/screenshots/console-platform-admin-operator-wallets.light.en.webp)

[Screenshot] The "Operator wallets" page with the "Platform wallets" table of each wallet's address, status, purpose, network and native balance.

A funding hint sits under the "Platform wallets" heading. The table columns are "Address", "Status", "Purpose", "Network" and "Native balance". Each row shows the wallet's address with its purpose under it. The rows start with the lowest balance.

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

- You need the platform administrator role. It is set on your account, not in one organisation, and an organisation **Owner** does not have it.
- The wallets are registered when the platform is deployed. If the table is empty, the deployment configuration registers no operator wallet, and the page reads "No operator wallets yet" and "Ask your platform engineer to register operator wallets in the deployment configuration so the platform can track them."

## Steps [#steps]

### Open Operator wallets [#open-operator-wallets]

Open "Platform admin", then **Operator wallets**. The page shows the "Platform wallets" table. Under the heading, a line says "Low balance uses the network's native currency mark. Ask platform operations to fund the wallet address on its network."

### Find the wallet that runs low [#find-the-wallet-that-runs-low]

The table starts with the lowest "Native balance", so a wallet that needs funding is at the top. Read the **Status** of each row:

| Status | What it means |
| --- | --- |
| **Low balance** | The native balance is below the network's low-balance mark, which is a tenth of one native unit. |
| **Balance above threshold** | The native balance is at or above that mark. |
| **Not needed (zero gas)** | The network charges no gas, so the wallet needs no balance. |
| **Not observed yet** | The platform has not read this wallet's balance on its network yet. |

The mark is the same fraction on every network. It does not estimate how many transactions the balance covers.

The **Network** column names the network and its chain ID. The "Native balance" column shows the balance in the network's native currency, or "Not observed yet".

### Open a wallet's details [#open-a-wallets-details]

Select a row to expand it. The detail shows the wallet's "Purpose", "Observed at" with the block of the reading when the platform has one, and the full **Address** with a copy control. Use the address to send the funds on the network the row names.

### Export or adjust the table [#export-or-adjust-the-table]

Use the table toolbar to export the rows or to choose which columns show. The table has no search or filter. On a narrow window the **Address** cell also carries the network, balance, status and observation time of the wallet.

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

- After the funding transfer lands and the platform reads the new balance, the row shows the higher "Native balance", a newer "Observed at" in its detail, and **Balance above threshold** as its "Status".
- The row shows the old balance until the platform reads the new one.

## Troubleshooting [#troubleshooting]

**Operator wallets is missing from the sidebar**

The entry appears only for a platform administrator. Ask a platform administrator to change your platform role on
[Platform users](https://docs.settlemint.com/docs/console/platform-admin/users).

**The table says No operator wallets yet**

The deployment configuration registers no operator wallet. Ask the platform engineer to register the wallets there.
This page cannot add one.

**A wallet shows Not observed yet**

The platform has not read a balance for that wallet on its network. The **Native balance** and "Observed at" show "Not
observed yet" until it does.

**A wallet shows Low balance**

Fund the wallet's address on the network the row names. The funding transfer is made outside the Console, and
[Operator
wallet](https://docs.settlemint.com/docs/concepts/custody-and-signing/operator-wallet#watching-the-balance-and-what-a-low-reading-means) explains
what a low reading means and when an alert fires.

## API routes [#api-routes]

The table reads `GET /api/v2/admin/operator-wallets`, which only a platform administrator can call. The [Platform API reference](https://docs.settlemint.com/docs/api-reference/v2) has the request and response shapes.


# Organisations

Source: https://docs.settlemint.com/docs/console/platform-admin/organisations
Review every organisation on the platform from one list, and archive or restore one from its page.

**Organisations** lists every organisation on the DALP Instance, whichever network is selected at the top of the page, and is where a platform administrator archives or restores one. An organisation groups membership, settings and issued assets. Each row's "Assets" column counts the tokens of that organisation's default system only: the tokens it issued and the external tokens registered into it, less the external tokens it dismissed. That is the same set the Console's asset classes count for the organisation.

The name in each row opens the organisation's own page. That page shows its owners and its archive history, and it holds the controls to archive or restore the organisation. The platform has no delete action for an organisation.

To manage settings inside an organisation you run, use "Organisation settings". A platform administrator can also act inside any organisation by impersonating one of its members from [Platform users](https://docs.settlemint.com/docs/console/platform-admin/users). This page has no create action. To create an organisation, open the "Organisation" submenu of the account menu at the top right and select **Create organisation**: that opens the setup wizard, the one way to create an organisation in the Console. The submenu offers it only on a multi-tenant deployment.

![Organisations table listing three organisations with their status, members, assets and creation date](https://docs.settlemint.com/docs/screenshots/console-platform-admin-organisations.light.en.webp)

[Screenshot] A table with columns "Name", "Status", "Members", "Assets", "Created" and "Archived on", with each organisation's slug under its name.

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

- You need the platform administrator role. It is set on your account, not in one organisation: a user's "Platform role" reads "Administrator" or "Member".
- Being the "Owner" of an organisation does not count.
- The sidebar shows "Platform admin", **Organisations** only to a platform administrator, and the platform refuses the organisation list and each organisation's page to every other account.

## Steps [#steps]

### Find an organisation [#find-an-organisation]

Open "Platform admin", then **Organisations**. Every organisation on the platform appears in the table, "Active" and "Archived". The "Owners" column is hidden by default. Turn it on from the column picker. The name cell also shows the slug.

The **Search organisations…** field matches both the name and the slug derived from it, so the name an organisation had at creation still finds it after a rename. Only the "Name", "Created" and "Archived on" columns sort. The "Status" filter limits the table to "Active" or "Archived" organisations.

### Open an organisation [#open-an-organisation]

Select the name of a row. The page shows the organisation's "Slug", "Owners", "Members", "Assets" and "Created" date, with an "Active" or "Archived" badge beside its name. An owners panel lists each owner's name and email. The **Archive history** table lists every archive and restore, newest first, with the "Event", "When", "By" and "Reason" when one was given. An organisation that was never archived shows "No archives or restores yet".

An archived organisation also shows a notice at the top of the page: "Archived on" the date and time, "by" the person, and the reason. The notice has its own **Restore organisation** button.

## Archive an organisation [#archive-an-organisation]

Open "Actions", then select **Archive organisation**. A confirmation opens. It states how many members lose access, and that the organisation's custody contexts and the participants only it drives are archived with it. It also says what happens to members who belong to no other organisation:

- On a platform where members may create an organisation, those members are asked to create one at their next sign-in.
- Otherwise, those members cannot use the Console until you restore the organisation.

Enter a "Reason (optional)" of up to 500 characters. The platform stores it with the time and your name. Select **Archive organisation** to confirm, or "Keep active" to close the confirmation.

The archive takes effect as soon as you confirm, with no second approver. It changes only the platform's records: no transaction is sent, so the organisation's contracts and every holder's tokens stay on-chain as they were. The change also writes an [Audit trail](https://docs.settlemint.com/docs/console/reporting/audit-trail) entry. The entry belongs to no organisation, so no organisation's Audit trail lists it, and a platform administrator reads it through the platform-wide query of the [audit trail](https://docs.settlemint.com/docs/concepts/records-and-evidence/audit-trail). A restore works the same way.

When the organisation is the one you are working in, the confirmation says that you lose access to it as well. After the archive succeeds, the Console moves you on as it does for any account without an active organisation.

## Restore an organisation [#restore-an-organisation]

Open "Actions", then select **Restore organisation**, or select "Restore organisation" in the notice on the organisation's page. The confirmation states how many members can switch to the organisation again, and that the participants whose custody context sits in it come back with it. The archive record stays in the history.

If another active organisation uses the same name, the confirmation also shows a warning. It gives the name the restore sets, which is the old name followed by a counter, such as "Acme (2)". The restored organisation keeps that name until its owner changes it. Owners change it in the Console under "Organisation settings", on "General", in the **Profile** section.

Enter a "Reason (optional)". It follows the same rules as an archive reason. Select **Restore organisation** to confirm, or "Keep archived" to close the confirmation.

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

- After an archive or a restore, the Console shows the message "Organisation archived" or "Organisation restored".
- On the organisation's page, the badge reads "Archived" or "Active", and the **Archive history** lists the change with your name and the reason.
- After a restore that renamed the organisation, the header shows the new name and the restored row in the history reads "Renamed from" and the old name.

## Troubleshooting [#troubleshooting]

**Organisations is missing from the sidebar**

Your account's platform role is not "Administrator". Owning an organisation does not give that role. A platform
administrator changes it under "Platform admin", **Platform users**.

**There is no button to create an organisation**

This page has no create action. Open the account menu at the top right, point at "Organisation" and select **Create
organisation**. That opens the setup wizard, where you name the organisation and choose its network. A single-tenant
deployment does not offer "Create organisation" and refuses a second organisation.

**An organisation was created by mistake**

The platform does not delete organisations. Open the organisation from this table and archive it: see [Archive an
organisation](#archive-an-organisation). The records stay, and a restore brings the organisation back.

**The confirmation says someone else changed the organisation first**

Another platform administrator archived or restored the organisation before you confirmed. The platform did not apply
your change, and the page now shows the current state. Read the history, then act again if you still need to.

**The organisation's page says Not available or Not found**

Not available means your account is not a platform administrator. Not found means the platform has no organisation
with that identifier, for example because the link was copied wrongly.

**The setup wizard rejects the name**

Another active organisation already uses the name. The first step of the setup wizard shows "Another organisation
already uses this name. Choose a different name." on the name field. The check compares the names without case and
without spaces at either end, so "Acme Corp" and " acme corp " are the same name. Choose a name that differs in more
than case and outer spaces. An archived organisation does not hold its name, so its name is free to use.

## Frequently asked questions [#frequently-asked-questions]

### Who owns the organisation after I create it?

The account that completes the setup wizard becomes that organisation's owner automatically: organisation creation always assigns ownership to its creator, and the wizard has no field to name a different owner. If someone else needs to run the organisation day to day, add and manage them from **Organisation participants** once you're inside it, not from this page.

### Can I delete an organisation?

No. The platform has no delete action for an organisation. Archive it, and its records stay. An archived organisation stays in this table with an **Archived** status, and a restore returns it to use.

### What happens to the members when I archive an organisation?

Members cannot switch to the organisation, join it, or accept an invitation to it. Every session that had it as its active organisation loses it at once. The organisation's custody contexts and the participants only it drives are archived with it. Members keep access to any other organisation they belong to.

A member whose organisations are all archived, and who has no pending invitation, sees "Your organisation is archived" at their next sign-in. The screen says that a platform administrator archived the organisation and can restore it. On a platform where the member may create an organisation, it offers **Create an organisation**. Otherwise it offers "Sign out" only. After a restore, the member signs in again to return to the organisation.

### Can I see who archived an organisation, and why?

Yes. The organisation's page lists every archive and restore with the time, the person, and the reason. A restore does not remove the archive entry. If the person who made a change no longer has an account, the history shows "Deleted user".

### Does a restore need a reason?

No. A reason is optional for both an archive and a restore. When you enter one, the history stores it on that entry.

### Can a new organisation use the name of an archived one?

Yes. Only active organisations hold a name. You can create an organisation with the name of an archived one. The archived organisation keeps its name in the table and in its page.

### What happens to the name when I restore an organisation?

The name stays the same unless another active organisation uses it. In that case the restore renames the restored organisation to its name followed by a counter: "Acme (2)", then "Acme (3)" if that name is taken as well. A name that already ends in a counter loses it first, so the restore gives the first free counter, starting at 2. The platform shortens the name when it must, so the result stays within 32 characters. The restore confirmation shows the new name before you confirm, and the history keeps the old name on the restored row. The owners of the organisation can change the name afterwards under "Organisation settings", on "General", in the **Profile** section.

### Why did an organisation get a counter in its name after the upgrade to DALP 3.2?

Before DALP 3.2, two active organisations could end up with the same name. The upgrade gives each of them its own name. The oldest organisation keeps the name, and each later one gets the name followed by a counter, the same way a restore renames: "Acme (2)", then "Acme (3)". Names are compared without case and without spaces at either end. Archived organisations keep their names, and no slug changes. The history does not record these renames. The database migration log of the upgrade lists each one, with the organisation's ID, its old name and its new name. The owners of the organisation can choose another name under "Organisation settings", on "General", in the **Profile** section.

### How can I tell whether a listed organisation has finished its onboarding?

The table has no onboarding-status column. A zero asset count does not prove that setup is incomplete: the organisation may have no issued assets or may hold assets on a system other than its default one. Select the organisation and check its setup or **Dashboard** state directly.

### Can I rename an organisation after creating it?

Yes. An owner renames it under "Organisation settings", on **General**. A member who is not an owner does not see "General": opening it shows "Not available", so a member cannot fix a typo in the name. Renaming changes the display name only. The slug, the organisation's URL namespace, stays fixed.


# Platform users

Source: https://docs.settlemint.com/docs/console/platform-admin/users
List, inspect and maintain any account on the platform: role, ban, sessions, API keys, impersonation, password, deletion and account closure.

**Platform users** is the one list of every account on a DALP Instance, whichever organisation a person belongs to. Use it to find an account by name or email, to read what an account can do, and to act on one when a person cannot sign in or when access must stop. It is a platform administrator's screen: an organisation owner does not reach it, and nothing here changes an organisation's own membership or roles.

Each account has one page. That page carries the platform role, the account state, the organisations the person belongs to, the sessions that are open, the API keys the person holds, and the actions that change the account. An account closure request a person filed appears on the same page, and the administrator decides it there.

![Platform users with the account count beside the title, the search field and filters, and the accounts table](https://docs.settlemint.com/docs/screenshots/console-platform-admin-users.light.en.webp)

[Screenshot] The "Platform users" page under "Platform admin", with the account count beside the title.

The "Search by name or email" field and the filters "Platform role", "Sign-in", "Email" and "Onboarding" head the table,
with "Export". The columns are "Name" with the email address under it, "Platform role", "Sign-in", "Email",
"Onboarding" and "Created".

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

- You need the **Administrator** platform role on your own account. Anyone else who opens the screen reaches the not-available state. The role is a value on the account, separate from any organisation role and from any on-chain role, so being an organisation owner grants nothing here.
- Three actions ask you to type the person's email address to confirm: making someone an administrator, resetting their onboarding in an organisation, and deleting an account.

## Steps [#steps]

### Find the account [#find-the-account]

Open "Platform admin", then **Platform users**. The title shows how many accounts match. The table has the columns "Name", with the email address under the name, "Platform role", "Sign-in", "Email", which says whether the address is verified, "Onboarding" and "Created". Sort by name or creation date, and filter by platform role, sign-in state, email verification or onboarding status. The table also exports the rows that match as a file.

Search matches a name or an email address that contains what you type. Your own row is marked **You**.

The **Sign-in** column reads "Active", "Banned" or "Closed". A ban whose end date has passed reads "Active" again. The account page gives the detail: "Banned until" a date, "Banned until an administrator unbans them", or "Closed on" a date.

### Read the onboarding column [#read-the-onboarding-column]

The **Onboarding** column shows one state per person, the worst across the organisations they belong to: "Stuck", "In progress", "Done", or "No organisation" when they belong to none. For a person in several organisations whose state is "Stuck" or "In progress", the cell also counts how many share that state, such as "Stuck · 1 of 3".

An organisation is "Done" once its onboarding finished, and "Stuck" when its initial deployment failed three or more times. Anything else is "In progress". Archived organisations do not count.

To read each organisation separately, expand the person's row in the list. It shows each organisation with its onboarding state and the person's role there. The **Organisations** section on the person's page adds the number of failed deployment attempts when a deployment failed. For a closed account, that section keeps the person's role in each organisation, such as "Owner", and offers neither "Reset onboarding" nor "Archive organisation". The page header and the "Sign-in" row carry "Closed".

### Open the account [#open-the-account]

Select the name. The page shows the person's name, or the email address when no name is stored, with the account state beside it. The **Account** card holds the email address, whether it is verified, the creation date and the user ID, which you can copy.

## Change the platform role [#change-the-platform-role]

The "Access" section shows the platform role: "Administrator" or "Member". Select **Change**. A closed account shows its role with no "Change".

Making a member an administrator asks you to type their email address, and says that administrators run every organisation on the platform. Changing your own role to "Member" warns that you lose **Platform admin** as soon as you confirm, and the Console then leaves the "Platform admin" section.

For an account that signs in with single sign-on, the identity provider decides the role at every sign-in: the account is an administrator while the provider sends the administrator claim, and a member otherwise. A change made here lasts only until that person's next sign-in.

When you are the only platform administrator, **Change** on your own row is unavailable, with the reason "You are the only platform administrator, so your role cannot change. Make someone else an administrator first." The API still accepts that change. If it leaves the platform with no administrator, no later account becomes one by signing up: an operator with deploy access to the cluster restores the role through the migration Job, as [Security and compliance posture](https://docs.settlemint.com/docs/deployment/security-compliance-posture#restore-the-platform-administrator-role) shows. With single sign-on, the identity provider's administrator claim grants the role at the next sign-in.

## Ban or unban the account [#ban-or-unban-the-account]

Select **Ban user**. The confirmation asks for an optional reason and for when the ban ends: "When an administrator unbans them", or "On a date". A date must be tomorrow or later, and the ban ends at the end of that day.

The confirmation states what the ban does: the person's sessions end now, they cannot sign in while the ban applies, and their API keys stop working until the ban ends. A ban turns no key off: once you lift it, or a ban with an end date runs out, the same keys work again.

**Unban user** replaces the action while a ban applies. Unbanning lets the person sign in again. The sessions the ban ended do not come back.

You cannot ban your own account. A closed account cannot be banned or unbanned: both actions answer `409 Conflict` with `ACCOUNT_CLOSED`, and the **Sign-in** row reads "Closed on" a date with "A closed account stays closed." in place of the ban action.

## End a session [#end-a-session]

The **Sessions** section lists each open session with its device, its organisation, when it started and when it expires, and marks a session an administrator started as "Impersonated". On your own page, the session you are using reads "Current session". The device reads as on the person's Security page: the browser, or the start of the client's name for another client, such as `DALP SDK v3.1.11`.

**End session** signs one device out. "End all sessions" signs out every session at once. Neither touches the account's API keys, and neither can restore a session later.

On your own page the current session has no end control, and **End all sessions** is hidden.

## Revoke a person's API keys [#revoke-a-persons-api-keys]

The **API keys** section lists the keys the person holds, newest first, in every organisation: its name with the start of the key, its organisation, when it was created, when it was last used and when it expires. A key the person turned off reads "Disabled", and a key past its expiry reads "Expired". A key with no organisation, or with an unknown scope, shows a dash under Organisation. Only a key created before the platform checked a key's organisation and scope can be one, as [Authenticate with API keys](https://docs.settlemint.com/docs/api-reference/guides/authentication-api-keys#organisation-scope) explains. The list never shows a key's secret.

**Revoke all API keys** deletes every key the person holds after you confirm. A revoked key stops working within 30 seconds and cannot be turned back on, so any program that used it needs a new key. Use it when a person leaves, or with a ban, which only refuses the keys while it applies. Revoking does not stop the person: while they can sign in, they can create new keys. Ban the account first to stop that.

The section offers no way to revoke one key. The person revokes a single key on their own [API keys](https://docs.settlemint.com/docs/console/my-account/api-keys) page.

## Act as the member [#act-as-the-member]

**Impersonate** opens the Console as that person, for one hour. Everything you do is real and runs as them, and the session records that you started it. That includes transactions from the person's wallet, which the platform submits as theirs and marks with your name as the impersonator.

The action is offered for a member account only. It is hidden on your own page, unavailable with "The account is closed" for a closed account, and unavailable with "Unban them first" while a ban applies.

While the hour lasts, a banner on every signed-in screen reads "Viewing the Console as" the person and the time the session ends, with **Stop impersonating**. Stopping ends the impersonated session, restores your own session and opens the person's page. Once the hour has passed the banner offers "Sign in" instead.

Some actions refuse an impersonated session, such as approving or rejecting anything that waits for a second person, switching an approval family off, changing the person's language, approving a device sign-in, adding a passkey or connecting an MCP client. Sign in as yourself for those. On the trading venue screens, Approve and Reject are disabled and read `Sign in as yourself to decide`. [Maker-checker](https://docs.settlemint.com/docs/concepts/custody-and-signing/maker-checker#impersonated-sessions-cannot-decide) lists every decision the refusal covers. [What the platform records](#what-the-platform-records) lists the evidence an impersonation leaves.

## Set a password [#set-a-password]

In the "Access" section, select **Set password**. A closed account has no "Password" row, so the action is not offered. The sheet states the password policy in force: by default at least 12 characters and three character types. The password changes without the old password and without an email to the person, so this is the way to restore access for someone who cannot sign in.

The sheet also offers to end the person's sessions in the same step. Setting the password turns off every API key they hold, before the new password is stored, so a request that presents one of those keys stops authenticating within 30 seconds of the change. If the keys cannot be turned off, the password does not change and the sheet reports the failure. If the password changes and ending the sessions fails, the sheet says so and points you at the **Sessions** section.

## Decide a request to close an account [#decide-a-request-to-close-an-account]

A person asks to close their account from [Security](https://docs.settlemint.com/docs/console/my-account/security). While a request is open, the account page shows a banner, "asked to close the account", with the date and whether it came from the Console or the Investor portal, and the page header carries **Waiting for you**.

The banner keeps the steps the person sees inline: empty the wallets, hand over organisation ownership, and replace the checker. Each step names who acts: the person, or an organisation owner for the checker step. When an on-chain identity is bound to the account, the banner says to close the account rather than delete it.

Three decisions are on offer:

- **Delete user** opens the delete sheet and stays unavailable, with the reason in words, while a step is open or an on-chain identity is bound.
- **Close account** ends every session of the person, keeps the account record, stops their API keys, emails them, and settles the request as closed. Closing is permanent: the account then refuses sign-in with `403 Forbidden` and `ACCOUNT_CLOSED`, whatever the sign-in method, and the Console and Investor portal show that message on the sign-in screen.

  While the person is still the only owner of an organisation, **Close account** is disabled with that reason and "Decline" leads. A close sent anyway answers `409 Conflict` with `PLATFORM_ACCOUNT_CLOSURE_SOLE_OWNER`, naming the organisations, and nothing is closed.

- **Decline** asks for a reason of up to 500 characters, which the person receives by email. The account stays open and they can ask again.

Deciding a request that is no longer open answers `409 Conflict` with `PLATFORM_ACCOUNT_CLOSURE_REQUEST_NOT_OPEN`. When the person withdraws the request, the banner goes away. "Delete user" and "Close account" read the request again before they open. If the person withdrew or changed it since the page loaded, nothing opens. A notice then names the person and reads "withdrew or changed the request. Read it again before you decide." **Decline** shows the same notice when you send the reason, and its sheet closes.

On your own page the banner shows the request without decisions, because another administrator settles it. Read a request through `GET /api/v2/admin/users/{userId}/account-closure-request`, which answers `404 Not Found` when the person never filed one.

## Delete the account [#delete-the-account]

**Delete user** sits in the danger area at the bottom of the page. It is hidden on your own page, and while a closure request is open, because the banner carries the decision. The row shows what the delete removes: the account, its sign-in methods and its sessions. It reads the reasons the platform refuses a delete before you act, and keeps the button unavailable while one applies:

| Reason | Code | What to do |
| --- | --- | --- |
| The person is the only owner of an organisation | `DELETE_USER_SOLE_OWNER` | Invite another owner, or archive the organisation. |
| An on-chain identity is bound to their participant | `DELETE_USER_ONCHAIN_IDENTITY` | Ban the account to stop sign-in. |
| Their wallets hold tokens | `DELETE_USER_POSITIVE_HOLDINGS` | Move the tokens out, or ban the account. |
| They approve transactions for a wallet | `DELETE_USER_WALLET_CHECKER` | Replace them as the wallet's checker. |

Read the same reasons through `GET /api/v2/admin/users/{userId}/deletion-refusals`, which lists the organisations a sole-owner or checker reason names.

The sheet asks you to type the person's email address. It states that their KYC records, participant names and audit entries stay, and points at banning as the way to stop access and keep the record. Deleting is permanent for the account, and it also settles an open closure request as deleted and emails the person.

## Find the account from an organisation [#find-the-account-from-an-organisation]

When you start from an organisation, open "Organisation participants", then "Users", then the person. The "Overview" tab shows a **Platform account** card with the platform role, the sign-in state, and "Open in Platform users". Only a platform administrator sees the card. It has no action of its own, so every change happens on the person's Platform users page.

## Create or update an account through the API [#create-or-update-an-account-through-the-api]

Platform users has no create or edit form. Both operations belong to the authentication administration API and need a signed-in platform administrator session: an API key is refused with `403 Forbidden`.

`POST /api/auth/admin/create-user` creates a sign-in account from an email address and a name. The password is optional, and without one the account has no password to sign in with. The platform sets the role itself, whatever the request asks for: the account becomes a member. Only the first account on a new instance becomes an administrator. Creation adds no organisation membership, participant or wallet, so the person joins an organisation through an invitation.

`POST /api/auth/admin/update-user` changes stored account fields. It writes the name, the email address, the email-verified flag, the language, the platform role and the ban fields. Any other field, such as a phone number, is refused with `400 Bad Request` and `FIELD_NOT_ALLOWED`, naming the field, and nothing is written. A password goes through **Set password** instead. For a closed account, a change to the ban fields answers `409 Conflict` with `ACCOUNT_CLOSED`, while its other fields still change.

## What the platform records [#what-the-platform-records]

A platform administrator can lock a person out, by a ban, by ending their sessions, by revoking their API keys or by closing the account. An administrator can act as a member through impersonation, or take over the account by changing its email address and setting a password. A session started with that password is not marked **Impersonated**, so only the platform-wide entries for the update and the password set tie it to the administrator. The platform keeps this evidence:

- The impersonated session stores the administrator who started it, and the person's **Sessions** section marks it "Impersonated" while it exists. Stopping the impersonation ends that session. While you act as the person, their [Security](https://docs.settlemint.com/docs/console/my-account/security) page shows it as the current session. The person's own Security page lists it too, in the Console and the Investor portal, with the line "Opened by &lt;your name&gt;, a platform administrator". The person can revoke it, which ends your impersonation. The person gets no new-device email for it.
- Every change made in an impersonated session, and every sensitive read made in it, is an entry on the [Audit trail](https://docs.settlemint.com/docs/console/reporting/audit-trail) of the organisation it was made in. The **Operator** column names the administrator and reads "Acting as" the person.
- A decision on a closure request stores the administrator who made it, which `GET /api/v2/admin/users/{userId}/account-closure-request` returns.
- The account holds only its current ban: whether it is banned, the reason and the end date. An unban clears all three, and the Audit trail entries for the ban and the unban keep the earlier values.

Each administration action also writes one Audit trail entry: a ban, an unban, a role change, a password set, ending one or all sessions, revoking every API key, creating, updating or deleting an account, and starting or stopping an impersonation. The entry names the administrator, their platform role and the account, and holds the old and new values the action changed, such as the role or the ban reason. A revoke records how many API keys it deleted, never a key. A password set records only that the password was replaced, never the password, and no entry holds a session token.

An action the route refuses, such as one without the permission it needs, is recorded as failed with its refusal code and no values. A refusal made before the route runs records nothing: `ACCOUNT_CLOSED` on a closed account, `FIELD_NOT_ALLOWED` on an update, `INVALID_ROLE_TYPE` or `YOU_ARE_NOT_ALLOWED_TO_SET_NON_EXISTENT_VALUE` on a role, and a delete the deletion rules refuse, such as for an organisation's sole owner.

These entries belong to no organisation, so an organisation's Audit trail page does not list them. A platform administrator reads them through the platform-wide query of the [audit trail](https://docs.settlemint.com/docs/concepts/records-and-evidence/audit-trail).

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

- After a role change, the **Access** section reads the new role and the list's "Platform role" column agrees.
- After a ban, the list's **Sign-in** column reads "Banned", the account page's "Sign-in" row reads "Banned until" the date you chose or "Banned until an administrator unbans them", and the "Sessions" section is empty.
- After a revoke, the **API keys** section reads "No API keys".
- After a password change, the sheet confirms **Password set**.
- After a delete, opening the account shows the not-found page, and the list no longer contains it.
- After a close, the account state reads **Closed** and the sign-in screen refuses the person with "This account is closed."

## Troubleshooting [#troubleshooting]

**The screen says Not available**

Your account does not hold the Administrator platform role. Ask a platform administrator to grant it on your account
page. Organisation ownership does not grant it.

**My own page says I cannot ban my own account**

Your own **Sign-in** row reads "You cannot ban your own account." in place of the ban action, and the platform refuses
a self-ban with `400 Bad Request` and `YOU_CANNOT_BAN_YOURSELF`. Ask another administrator to act.

**Change is unavailable on my own page**

You are the only platform administrator. Make someone else an administrator first. Banned administrators count towards
the total, so **Change** becomes available as soon as another administrator account exists.

**Delete user stays unavailable**

Read the row that holds the button. It names the reason, and each reason has its own way out: another organisation
owner, moving tokens, replacing a wallet checker, or, when an on-chain identity is bound, banning the account or
closing it on the person's request.

**Impersonate is unavailable**

The button says which rule applies. **Unban them first** means a ban is in force. "The account is closed" means the
account was closed on a closure request. The action is also absent for an administrator account.

**The ban ended but the person is still signed out**

A ban ends access for new sessions and ends the sessions open when it started. Nothing restores them, so the person
signs in again.

**The person says they are still signed in after I ended their sessions**

Ending a session stops that session from working at its next request. An API key is not a session, and ending sessions
never revokes one. **Revoke all API keys** in the "API keys" section stops every key the person holds, as [Revoke a
person's API keys](#revoke-a-persons-api-keys) describes. Setting their password also turns their keys off.

## Frequently asked questions [#frequently-asked-questions]

### Does a ban turn off API keys?

No, but it stops them. A ban ends interactive sessions, refuses new ones and refuses the person's API keys while it applies. The keys stop within 30 seconds. The keys stay turned on, so they work again once the ban is lifted or runs out. **Revoke all API keys** or closing the account stops them for good. [API keys](https://docs.settlemint.com/docs/console/my-account/api-keys#when-your-keys-stop-or-keep-working) lists what stops a key.

### What does deleting an account remove?

The account, its sign-in methods and its sessions. It leaves the person's KYC records, participant names and audit entries, so the record of what they did survives. The sheet states this before you confirm, and points at banning when the goal is to stop access and keep everything else.

### Can an account be created on this screen?

No. Create and update accounts through the authentication administration API, as [Create or update an account through the API](#create-or-update-an-account-through-the-api) describes.

### Is an impersonation or a ban recorded?

Yes. A ban, a role change and the start and end of an impersonation each write an Audit trail entry that names the administrator, and an impersonation also leaves the administrator's name on every Audit trail entry made in that session. [What the platform records](#what-the-platform-records) lists every trace.

### Does a closed account come back?

No. Closing ends sign-in and every session, and a closed account refuses a new session whatever the sign-in method. Its API keys are not revoked, but they stop authenticating within 30 seconds and stay refused. Banning, unbanning and changing its ban fields all answer `409 Conflict` with `ACCOUNT_CLOSED`, and the person cannot file another closure request.

## API routes [#api-routes]

The screen reads and changes accounts through these routes of the Platform API:

- `GET /api/v2/admin/users` lists the accounts the table shows.
- `GET /api/v2/admin/users/{userId}` reads one account and answers `404 Not Found` when no account has that identifier.
- `GET /api/v2/admin/users/{userId}/deletion-refusals` lists the reasons a delete is refused.
- `GET /api/v2/admin/users/{userId}/account-closure-request` reads an open closure request.


# Anchor registry

Source: https://docs.settlemint.com/docs/console/reporting/anchor-registry
Read the entries your system's document anchor registry holds, check a document you hold against an issuer's entries, and anchor a document.

Anchor registry lists the entries of your system's registry in write order and lets an owner anchor a document. The registry is an append-only list on the chain. Each entry holds a digest, a fingerprint computed from a document's files, so a holder of a copy can check that it is the one an issuer committed to. Writing an entry is called anchoring. **Anchor registry** lists the entries of your system's registry in write order, oldest first, and has two actions: "Check a document" compares a document you hold with an issuer's entries, and "Anchor a document" writes a new entry. [How an anchor proves a filing was not altered](https://docs.settlemint.com/docs/concepts/records-and-evidence/reporting-obligation#how-an-anchor-proves-a-filing-was-not-altered) explains what an entry contains and what each answer means.

Filings that an obligation anchors reach the registry on their own. Use this screen to look up one filing's entry, check a document you were handed, or anchor a document no filing produced.

![Anchor registry page with Check a document in the header, the Indexed up to block and Registry strip, and the table of anchored documents](https://docs.settlemint.com/docs/screenshots/console-reporting-anchor-registry.light.en.webp)

[Screenshot] The "Anchor registry" page as a reporting officer sees it.

The header carries "Check a document", with "Organisation owners and platform administrators anchor documents." in place of the anchor button. A strip above the table shows "Indexed up to block" and the "Registry" address. The table shows "Document", "Anchored at", "Digest", "Subject" and "Transaction", "View" lists the columns hidden at this width, and "Previous page" and "Next page" sit under the table.

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

- **The registry add-on.** The system needs the document anchor registry add-on. Without it, the page reads "This system has no anchor registry yet". A system manager sees "Open system add-ons" and adds it there. Any other reader is told to ask a system manager.
- **Files in the order you received them.** To check or anchor a document, have every file of the document ready, in the order it was delivered. Each file's position is part of the digest, so the same files in another order give a different digest. For a filing, use every part that "Download" on [Filings](https://docs.settlemint.com/docs/console/reporting/filings) gave you, in the same order.
- **To anchor.** An organisation owner or a platform administrator, signed in as themselves, not in an impersonated session. A platform administrator anchors in an organisation they are a member of, in any organisation role. The organisation needs an active system on the selected network, an issuer identity on it that is active and trusted for document hashes, and the registry add-on. The page also needs a network selected.

## Steps [#steps]

The files stay on your machine. The browser hashes them and sends only the digests and lengths.

### Open the registry [#open-the-registry]

Open "Reporting", then **Anchor registry**. A strip above the table gives "Indexed up to block" and the "Registry" address. An entry written after that block appears once the indexer reads it, so an empty table is not proof that nothing was anchored. While the indexer has read no block, the page says "Nothing is indexed on this chain yet" and lists nothing.

### Select Check a document [#select-check-a-document]

In the page header, select **Check a document**. The dialog opens for any reader of this screen. "Check a document" also appears beside an asset's documents in the Console and the Investor portal, and needs no reporting access there.

### Enter the issuer and add the files [#enter-the-issuer-and-add-the-files]

1. In **Issuer identity**, enter the identity contract of the organisation you believe issued the document. It is required because two organisations can commit to byte-identical documents. The answer comes only from the registry the issuer's own system runs, so a document another issuer anchored never answers for this one.
2. Add the document's files, then move them up or down until they are in the order they were delivered. Choose the files themselves. The registry stores a manifest digest computed over the files, each of which is a part, so a pasted file hash finds nothing, even for a document that is anchored. A single-file document is one part.

### Select Check this document [#select-check-this-document]

Select **Check this document**. You have succeeded when the answer reads "Anchored by this issuer". [What each answer means](#what-each-answer-means) explains the other three.

## Read the registry [#read-the-registry]

The table shows "Document", "Anchored at", "Digest", "Subject", "Transaction", "Block" and "Entry id". **View** adds "Issuer" and "Type", and lists any column hidden because the window is narrow.

The page shows 25 entries at a time. "Previous page" and "Next page" walk the registry, and the caption under the table gives the range, for example "Showing 1 to 25, oldest first". The table's export downloads every entry that matches.

A filing that has an anchor shows an "Anchor registry entry" link. It opens this screen filtered to that filing's digest, and a **Digest** chip above the table says so. Select the chip, or "Show the whole registry" when no entry matches, to remove the filter. When the filter finds no entry, the page says "No entry for this filing" and that the registry holds no entry with this digest at or below the block the indexer has read.

## Anchor a document [#anchor-a-document]

An organisation owner, or a platform administrator of the deployment, can write any document into the registry from their own session. The platform writes the entry with the organisation's operations signer, under the organisation's issuer identity, so the entry names the organisation and not the person who wrote it. The [Audit trail](https://docs.settlemint.com/docs/console/reporting/audit-trail) records who asked for the write. For every other reader the **Anchor a document** button is unavailable, and its reason reads "Organisation owners and platform administrators anchor documents."

The registry has no function that changes or removes an entry, and the transaction that wrote an entry stays on the chain. A wrong digest or a mislabelled entry can only be superseded by writing another entry beside it. The registry is an add-on of the issuer's own system, so a system manager of that system can replace its implementation or archive it, and an archived registry takes no new entries.

1. Select **Anchor a document**.
2. Check **Subject identity**. It defaults to the organisation's own identity, which suits a corporate document. Enter a token's identity for an asset document. The field takes any identity, and the registry's trusted-issuer check decides whether the issuer may attest about it.
3. Choose the "Document type", "Regulatory filing" or "Investor report", and enter a **Document label**: a short word for the kind of document, never a client name, a deal reference, a filing identifier or a path to a file. A label that contains the organisation's identifier or a path or URL character is refused.
4. Add the files in the order the document is delivered. The browser sends only each file's digest and length, so the platform keeps no copy of the document.
5. Select "Review what will be written", check the subject, type, label, registry and each part's name, digest and size, and confirm "I understand this entry is permanent and public and cannot be corrected."
6. Select **Anchor this document**.

The result reads "Anchored", with the **Manifest digest** to keep, "Still being written" when the write outlived the request, or "Not written", with the reason. A custody approval policy that holds the transaction is one cause of "Still being written". Do not send the document again: the entry appears in the registry once the write completes. Writing the same document for the same subject again returns the existing entry.

## What each answer means [#what-each-answer-means]

| Answer | What it means | What to do |
| --- | --- | --- |
| **Anchored by this issuer** | The issuer committed to exactly these bytes, in the anchor registry their own system runs. | Nothing further. The document you hold is the one the issuer committed to. |
| **No entry of this issuer's, so far** | No entry of this issuer's stands at or below the block the indexer has read. The answer shows that block. It does not say the document was never anchored. | Check the order of the files and that you chose the delivered files. Try again once the indexer has read further. |
| **Nothing has been read yet** | The indexer has read no block on this chain, so there is no block to have looked up to. The answer says nothing about the document. | Try again once the indexer has caught up. |
| **This issuer's registry could not be named** | No system on this chain answers for the identity you named, more than one does, or the one that does runs no live registry. Nothing was read, so the answer says nothing about the document. | Check the issuer address and the network. |

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

- **A check confirmed the document.** The answer reads "Anchored by this issuer". Any other answer means the document is not confirmed, and the answer gives the block it was read up to.
- **An anchor landed.** The result reads "Anchored", and the table lists the entry with the "Manifest digest" you kept. Select the "Anchor registry entry" link of a filing, or search the registry by that digest, to find it again.

## Troubleshooting [#troubleshooting]

| What you see | What it means and what to do |
| --- | --- |
| "This system has no anchor registry yet" | The document anchor registry add-on is not on the system. A system manager adds it from **Open system add-ons**. |
| "The anchor registry could not be loaded", or "The system could not be read" | The page could not read the registry or the system. Use the control to try again, or refresh the page. |
| "Nothing anchored yet" | The registry lists no entry at the block the indexer has read. Documents appear here once the indexer has read them. |
| "One of the chosen files could not be read, so nothing was checked." | The browser could not read one of the files. Choose the file again. |
| "The document could not be anchored." or "The decision was refused" | Read the reason in the dialog. The platform refuses a write without the disclosure confirmation, in an impersonated session, for a subject that is not a usable identity, for a label that would carry an identifier, and when the organisation has no active system, no issuer identity or no registry on the network. |
| **Anchor a document** is unavailable and **Review what will be written** is not offered | Your account is not an organisation owner or platform administrator, or the page has no registry or no selected network. |

## API routes [#api-routes]

The screen uses three routes of the [Platform API](https://docs.settlemint.com/docs/api-reference/v2):

- `POST /api/v2/reporting/anchors` writes an entry.
- `POST /api/v2/reporting/anchors/verify` checks a document.
- `GET /api/v2/reporting/anchors` searches a network's registry entries by exactly one of a manifest digest, a subject identity or a registry address.


# Audit trail

Source: https://docs.settlemint.com/docs/console/reporting/audit-trail
Review who acted, under what role, on which operation, and with what outcome, and read the questions people asked the assistant.

Audit trail lists your organisation's operations, such as publishing an obligation, approving a submission, or opening a participant's KYC record, with who performed each one, their role at the time and its outcome. A publish or an approval changes something. Opening a KYC record changes nothing but is still recorded, because the platform records some reads on their own as sensitive reads. Use this screen to confirm that an operation happened, who performed it and whether it succeeded.

An entry also shows the old and new values a change recorded, such as a venue announcement's text before and after an edit. An amount, such as a supply cap, shows in the asset's units with its symbol and digit grouping, for example 1,500 ACP. An amount recorded without its asset's decimals shows in smallest units and says so, for example 150,000 (smallest units). For a maker-checker approval it shows who proposed it and who approved or rejected it. The Console does not show request bodies. Each entry is linked to the previous one by a hash chain, and its final outcome is linked when the request closes. The [audit trail concept page](https://docs.settlemint.com/docs/concepts/records-and-evidence/audit-trail#how-the-trail-proves-that-its-rows-were-not-changed) explains how to check that chain and what the check cannot detect.

The trail is read-only, opens on the last 30 days and lists operations. It holds no ledger activity, so open the affected asset's page for on-chain activity. Reading the trail is itself a sensitive read, so it adds an entry that names you as the actor.

![Audit trail entries in a table with the Operation, When, Operator, Checker and Outcome columns](https://docs.settlemint.com/docs/screenshots/console-audit-trail.light.en.webp)

[Screenshot] The audit trail table with the "Operation", "When", "Operator", "Checker" and "Outcome" columns.

Each entry names the action in words, such as "View KYC profile", and reads "Success" under "Outcome" when it succeeded. An opened entry shows the target and the reason where present.

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

- Select the organisation whose activity you need to review.
- A compliance officer with the "Auditor" role can read the trail without the right to approve anything.
- A platform administrator reads the trail of any organisation they are a member of, in any organisation role.
- The trail records the operations the platform logs, which is not every Console click.

## Steps [#steps]

### Open Audit trail [#open-audit-trail]

Open "Reporting", then **Audit trail**. The "Actions" tab lists recorded operations from the previous 30 days, newest first, 200 entries to a page. The columns are "Operation", "When", "Operator", "Checker", "Outcome", "Target" and "Reason". A caption under the table gives the range the page shows, for example "Showing 201 to 400, newest first". An entry names the action in words, in the language the Console is set to, and shows the time the operation started.

The window ends when you open the page, so entries recorded after that, including your own reads of the trail, do not shift the pages. The tooltip on the window button gives that time. To include newer entries, apply the window again or reopen the page.

### Narrow the list [#narrow-the-list]

Use the toolbar above the table:

- **Search resources** matches the entry's target.
- **Action** limits the list to one operation. It reads "All actions" until you choose one.
- **Channel** limits the list to "Admin" entries for an operator, "Participant" for an investor or trader, or "System" for a scheduled job or a request with no signed-in session. It reads "All channels" until you choose one. An action that an assistant agent ran has the Agent channel, which its entry sheet shows. The "Channel" select does not offer it, so filter those entries through the API with `actorChannel=agent`.
- **Entry type** reads "All entries", "Writes" or "Sensitive reads". "Writes" shows the operations that changed something. "Sensitive reads" shows the reads the platform records on their own.
- The window button, which reads like "27 Sep - 27 Oct 2026", opens "From" and "To" dates with **Apply**. "Last 30 days" restores the default. An empty "From" gives the 30 days that end on "To". An empty "To" ends the window at the time you open the page, apply the window or change a filter. "From" and "To" refuse a "From" after the "To" or a typed day that does not exist, such as `2026-02-30`, and show a message under that field. "Apply" stays unavailable until you correct or clear that date.

When an operator acted as another user, the **Operator** column names the operator and says "Acting as" the user. When an operator acted under delegated authority on your organisation's behalf, the entry names the operator and the role they held in that session. It does not name the party the operator worked for.

Select **Next page** to go back in time and "Previous page" to return. The last page holds the oldest entry of the window. When nothing matches, the screen reads "No recorded actions match", and "Clear all" removes the filters.

### Open an entry [#open-an-entry]

Select an entry's operation to open its sheet, **Audit entry**. From the sheet, "Show actions by this operator" adds an "Operator" chip to the toolbar, and "Show history for this resource" searches for the entry's target. Compare the entry's actor, "Role at the time" and outcome with the event you are investigating.

### Continue the investigation [#continue-the-investigation]

The sheet shows the operation's target. The **Technical** block, folded by default, holds:

- the operation identifier
- the **Target path**, with credentials such as passwords and tokens in its query string replaced by `REDACTED`
- the **Status**, the "Entry ID" and the "Request ID"
- the **Approval ID**, for an entry that proposed or decided a maker-checker approval.

For a decided approval the sheet names the **Maker**, the user who proposed it, and the "Checker", the user who decided it. The "Checker" column of the list names the same user for a trade bust, a desk limit or a filing.

For a consolidated transition, one request that moves a record to a new state, the reason is the requested destination state. A failed transition records the state it was asked to reach. A reason that reads "From an assistant question" marks a read the assistant made.

The target does not always name the affected resource. `GET /api/v2/reporting/trail/resource` returns every actor and route that touched one resource. For a change that recorded no values, the operation's owning page holds its history, such as [Obligations](https://docs.settlemint.com/docs/console/reporting/obligations) for an obligation publish.

## Read an entry's outcome [#read-an-entrys-outcome]

An entry's outcome is one of three values:

| Outcome | What it means | What to do |
| --- | --- | --- |
| **Success** | The operation completed and its response carried no error. | Nothing further. |
| **Failure** | The request returned an error. The entry alone does not prove that every side effect was rolled back. | Read the error and check the affected resource before retrying. Follow that operation's retry and idempotency rules. |
| **Pending** | The platform recorded that the operation started but never recorded that it finished. | Treat it as unresolved. Open the operation's own owning page, such as Obligations for an obligation publish, and check its current state there, since only that page knows whether the write finished. |

For a write to on-chain access, a smart wallet or an add-on that the platform accepted and queued, the badge shows the chain's result instead of "Success". The badge reads "Queued" while a transaction is still open, "Confirmed" when every transaction completed, and "Reverted" when any transaction did not take effect. The entry sheet shows the roles or settings "Before" and "After", and the **Technical** block lists each transaction with its hash and, for a reverted one, the revert reason. A request that failed keeps the "Failure" badge. An open sheet for a queued entry refreshes every five seconds until the chain settles it.

## Export the trail as CSV [#export-the-trail-as-csv]

Select **Export** in the table toolbar to download a CSV file of the window and filters the page shows. The file holds every entry that matches, oldest first, however many pages that is. Spreadsheet formulas in a cell are written as text, so the file is safe to open in a spreadsheet. Every export adds its own sensitive-read entry to the trail that names who exported and the filters. If the platform cannot write that entry, it refuses the export and sends no rows. [API routes](#api-routes) gives the export route.

## Read assistant questions [#read-assistant-questions]

When the assistant is on for your organisation, or the window holds at least one question, the screen shows two tabs under the title, "Actions" and "Assistant questions", each with a count. The **Assistant questions** tab lists every question people in your organisation asked the assistant, newest first. The columns are "Question", "When", "Asked by", "Outcome", "Asked about" and "Rating". The question is shown as the person typed it. The date range carries over when you switch tabs.

Each question ends with one outcome: "Answered", "Refused", "Timed out", "Failed", "Stopped", or "Started" while the answer is still running. Narrow the list with "Person", "Outcome" and **Rating**, which takes "Helpful" or "Not helpful" and shows how people rated the answers. The detail of a "Not helpful" answer shows the reason and the note the person wrote, when they sent one.

Select a question to open its detail, **Assistant question**. It shows the "Question", the "Answer", what it was asked about and the person's "Role at the time". Its "Technical" section shows the "Model", the "Time taken", the "Tokens", the "Refusal code" when there is one, and the "Reads made", the operations the assistant read. The reads name the operations, never their input or the data they returned. "Show questions from this person" adds the person filter.

**Sent to the model** shows only when it differs from the question. Before the question reaches the model, the platform replaces the names it recognises, email addresses and `0x` addresses with handles or placeholders. A name it does not recognise, such as one typed in lower case, is sent as typed, so check this field when the question named a person.

An entry on the "Actions" tab whose reason reads `turn=<id>` is the record of one of these questions. Its detail has an **Open this question** button that opens the same detail on the other tab.

Select **Export** to download every question in the window and filters shown, oldest first, as `assistant-questions-<from date>-<to date>.csv`. The file holds the id, start time, person, asset, question and outcome of each question, and follows the same rules as the trail export.

The same roles can read this tab as the **Actions** tab, and every list, detail and export read adds its own entry to the trail. Questions are kept under the assistant's retention rule. Removing a person's account removes their questions, while the "Actions" entries that recorded them stay on the trail without the question text.

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

- Confirm that the entry names the expected operation and actor, and read its outcome to see whether the operation completed or failed.

## Troubleshooting [#troubleshooting]

| What you see | What it means and what to do |
| --- | --- |
| No matching operation appears | Confirm the organisation. The screen opens a 30-day window, so older operations are outside it until you set **From** and **To** in the window button. Inside the window, the first page holds the newest 200 entries. Select **Next page** until you reach the time of the operation, or clear the **Action**, **Channel**, **Entry type** and search filters if one of them hides it. |
| The entry has no changed values | The entry sheet shows **Before** and **After** values only for an operation that records them, such as a configuration change, and it never shows request bodies. The target keeps ordinary query parameter values, with credentials redacted, but not the fields an operation changed. Use the owning operational record when you need field-level history. |
| An entry stays **Pending** long after it should have finished | Two failures produce **Pending**, and the entry does not say which: a request lost to a crash before it finished, or a request that ran to completion whose closing write failed. Open the operation's owning page and check its current state there. Do not assume **Pending** means the work is still running. |
| The **Assistant questions** tab is missing | The tab shows when the assistant is on for your organisation, or when the window holds at least one question. Widen the window to find older questions. |

## Frequently asked questions [#frequently-asked-questions]

### Can I change an obligation's requirements from here?

No. This screen only reads. An organisation owner or platform administrator prepares or edits a draft on [Obligations](https://docs.settlemint.com/docs/console/reporting/obligations), and can publish it there.

### Can I look further back than 30 days?

Yes. Thirty days is the default. Open the window button, set "From" and "To", and select **Apply**. "Last 30 days" in the same panel restores the default. The window reaches back only as far as the deployment's audit retention, which the [audit trail concept page](https://docs.settlemint.com/docs/concepts/records-and-evidence/audit-trail#what-the-trail-covers-and-what-it-leaves-out) describes. For a one-off file, use the [CSV export](#export-the-trail-as-csv) with the window you need.

### Does opening this screen put an entry on the trail itself?

Yes, whenever the platform can write the entry, and the same is true of a call to the reporting endpoints. When that write fails, the platform still serves the read and logs the failure. Only the CSV export refuses to run without its entry.

## API routes [#api-routes]

The screen uses these routes of the [Platform API](https://docs.settlemint.com/docs/api-reference/v2). Each takes a time window, and the API reference defines the request and response fields.

- `GET /api/v2/reporting/trail` reads the organisation's entries. Each entry carries `targetName`, the name of the resource it targets: the token, member, venue or add-on name, or the symbol of the token a sale sells. The platform resolves it for the caller and answers `null` when the target has no name or the caller may not read it.
- `GET /api/v2/reporting/trail/resource` returns every actor and route that touched one resource.
- `GET /api/v2/reporting/trail/integrity` checks the hash chain of a date range.
- `GET /api/v2/reporting/trail/operator` returns the entries of every organisation on the deployment to a platform administrator. That read is itself recorded. `GET /api/v2/reporting/trail/operator/integrity` verifies the platform chain, the entries that belong to no organisation, over a date range of up to 31 days.
- `GET /api/v2/reporting/trail/export` returns the CSV export.

The export returns the same fields as the trail read, one row per entry, with `transactions`, a JSON list, and `transactionOutcome` as the last two columns, as a UTF-8 file with a byte order mark so spreadsheets read it correctly. The filename is `audit-trail-<from date>-<to date>.csv`.

```bash
curl "https://your-instance.example.com/api/v2/reporting/trail/export?from=2026-09-01T00:00:00Z&to=2026-09-30T23:59:59Z" \
  -H "X-Api-Key: <your api key>" \
  -o audit-trail-2026-09-01-2026-09-30.csv
```

- `from` and `to` are required ISO 8601 timestamps. Both bounds are inclusive, so start the next window after the previous `to` to avoid repeating an entry. A `to` later than the moment of the export is treated as that moment.
- `target`, `actorUserId`, `actorChannel` (one of `admin`, `participant`, `system` or `agent`), `kind` (`mutation` or `sensitive-read`) and `route` are optional and filter the export the same way they filter the trail read. The export has no paging parameters.
- The access rules match the trail read. An export never includes another organisation's entries.
- The platform streams the file, so a large window starts downloading at once.
- A cell that starts with `=`, `+`, `-`, `@`, a tab, or a carriage return is written with a leading apostrophe. A cell in which a comma, semicolon, tab, or pipe comes before one of those characters is written in quotes. A spreadsheet then shows the cell as text and does not run it as a formula.
- The export's own trail entry has the reason `export rows=<n> from=<from> to=<to>`, plus `target=<target>`, `actor=<user id>`, `channel=<channel>`, `kind=<kind>` and `route=<operation>` for each filter you gave.
- The export reads the Audit trail as it stands and adds no retention rule of its own.


# Daily transactions

Source: https://docs.settlemint.com/docs/console/reporting/daily-transactions
Download a report of chain movements, corporate actions, and venue trades for one organisation business day or a range of up to 31 days.

Daily transactions exports the movements of an organisation business day on the selected network as one file: chain movements, corporate actions and venue trades. Select another network and generate the report again for its movements. You choose one day or an inclusive range of dates, the time zone that sets where each day starts and ends, and the file format. The platform builds the report on request from the indexed chain, up to the last block before the end of the range, or up to the latest indexed block while the range has not ended. The file downloads to your device.

The screen keeps no earlier reports, so generate the report again when you need the file.

![Daily transactions page with the What the report includes note and the Generate a transaction report form with Start date, End date, Business-day time zone, File format and the Download report button](https://docs.settlemint.com/docs/screenshots/console-reporting-daily-transactions.light.en.webp)

[Screenshot] The "Daily transactions" page as a reporting officer sees it.

Under the title, a note headed "What the report includes" lists the columns of the report. The "Generate a transaction report" form below it holds "Start date", "End date", "Business-day time zone" and "File format", and the "Download report" button.

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

- **An indexed chain.** The report reads the chain through the end of the range. When the chain is not indexed that far, the platform refuses the request and the Console shows an error. Try again once indexing has caught up.

## Steps [#steps]

### Choose the dates [#choose-the-dates]

Enter the **Start date** and the "End date". Both fields default to the current date in your browser's time zone. Both dates are part of the range, so a single day has the same date in both fields. The Console says "Choose a start date and an end date." when a date is empty, "The end date must not be before the start date." when the end is before the start, and "Enter an inclusive date range of up to 31 days." when the range is longer than 31 days.

### Choose the time zone [#choose-the-time-zone]

In **Business-day time zone**, pick the time zone. Each day runs from local midnight to the next local midnight, so a day with a daylight-saving change lasts 23 or 25 hours. The report always uses the time zone you pick, whatever display time zone your organisation sets on [General](https://docs.settlemint.com/docs/console/organisation-settings/general). A request sent without a time zone, for example from the API, uses that display time zone, and UTC when the organisation has none.

### Choose the file format [#choose-the-file-format]

In **File format**, choose "CSV" for a portable file or "XLSX" to keep spreadsheet formatting.

### Select Download report [#select-download-report]

Select **Download report**. The button reads "Preparing report…" while the platform builds the file. The file is saved as `daily-transactions-<start>-<end>.csv` or `.xlsx`, with your start and end dates in the name. If the platform cannot produce the report, the screen shows "Something went wrong here". When the range holds more rows than one report carries, the screen shows "The date range holds too many rows for one report" and no file is saved.

## What the report includes [#what-the-report-includes]

Each row is one movement, grouped under its business day. The columns are kind, network, status, participant, client, wallet, asset, symbol, quantity, transaction hash and reference, so the file carries client and wallet identifiers.

- `participantId` and `clientId` name the participant that holds the wallet and that participant's identity reference. For a venue trade, the wallet is the buyer's. Both stay empty when no participant of your organisation holds the wallet, for example an escrow or settlement contract.
- `asset` is the token address and `symbol` its symbol. On a corporate-action payment (`ca-payment`), they name the asset the holder was paid in, such as the cash token of a coupon, not the instrument.
- `quantity` is in token units, with the token's decimals applied: 40 EUROC reads `40`, not `40000000000000000000`. It keeps every decimal the token has, without rounding, and stays the on-chain integer when the platform has not indexed the token's decimals.

A report holds at most 1,000,000 rows. When the range holds more, the platform refuses the request with the `reporting.daily-transactions.ROW_LIMIT_EXCEEDED` error, so you never receive a file that stops partway through the range. Request a shorter range and download the report in several parts.

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

- Open the file and check that the days you asked for are present, that each row has a kind, a network and a status, and that the quantities and the transaction hashes match the activity you expect.
- Generating the report is a sensitive read, a read the platform records on its own, so [Audit trail](https://docs.settlemint.com/docs/console/reporting/audit-trail) holds an entry for it.
- The entry names the range, the time zone, the format and the number of rows.

## Troubleshooting [#troubleshooting]

| What you see | What it means and what to do |
| --- | --- |
| "Enter an inclusive date range of up to 31 days." | The range is longer than 31 days. Download the range in two parts. |
| "The end date must not be before the start date." | The end date is before the start date. Correct the dates. |
| "The date range holds too many rows for one report" | The range holds more than 1,000,000 rows, so the platform produced no file. Request a shorter range and download the report in several parts. |
| **Something went wrong here** under the form | The platform refused or could not build the report, for example because the chain index has not reached the end of the range. Try again later, or choose an earlier end date. |
| **Select an organisation to see reporting** | Daily transactions needs an active organisation. Select one before you open **Reporting**. |

## API routes [#api-routes]

The form uses one route of the [Platform API](https://docs.settlemint.com/docs/api-reference/v2): `POST /api/v2/reporting/daily-transactions` takes `start`, `end`, an optional `timeZone` and the `format`, and returns the file. It answers 422 `reporting.daily-transactions.ROW_LIMIT_EXCEEDED` when the range holds more rows than one report carries.


# Filing calendar

Source: https://docs.settlemint.com/docs/console/reporting/filing-calendar
Review the organisation's filing periods and each one's urgency.

Filing calendar ranks your organisation's filing periods by urgency, most time-sensitive first. A reporting obligation is a recurring duty to file a report, and a filing period is one cycle of it. A quarterly obligation produces a new period each quarter, so the same duty can show more than one row here at different urgencies. The screen orders what needs attention. What an obligation requires, which version it files under and whether it is disabled are set on [Obligations](https://docs.settlemint.com/docs/console/reporting/obligations).

The calendar takes no filing action and changes no filing or asset state. You generate, review, approve and complete a filing on [Filings](https://docs.settlemint.com/docs/console/reporting/filings) or through the [Platform API](https://docs.settlemint.com/docs/api-reference/v2). The calendar lists scheduled periods only. A filing made for a date range you chose in Obligations has no deadline, so it appears in Filings with an **Ad hoc** badge and never here.

![Filing calendar with the Overdue, Due soon, Open and Fulfilled counts above a table of daily filing periods, each Scheduled with EVM coverage Pending](https://docs.settlemint.com/docs/screenshots/console-filing-calendar.light.en.webp)

[Screenshot] The "Filing calendar" page as a reporting officer sees it.

Four counts sit above the table: "Overdue", "Due soon", "Open" and "Fulfilled". The table has the columns "Obligation", with the fiscal period under the name, "Due", "Regime", "Coverage", "Status" and "Filing". The rows in the capture read "Scheduled" and have no filing.

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

- Select the organisation whose duties you want to review.
- The screen needs an active organisation, and a period only appears once its obligation has a published version.

## Steps [#steps]

### Open Filing calendar [#open-filing-calendar]

Open "Reporting", then **Filing calendar**, or select the "Filing calendar" tab from Obligations or Filings.

A strip above the table counts the periods that are "Overdue", "Due soon", "Open" and "Fulfilled", and names the oldest overdue duty with how late it is. Select a figure to filter the table to that status.

The table columns are "Obligation", "Due", "Regime", "Coverage", "Status" and "Filing". **Search periods** searches the rows.

Each row is one filing period of an obligation. The fiscal period under the obligation name, for example 2026-Q2 or a date for a daily duty, tells the rows of one duty apart.

### Read the urgency badge [#read-the-urgency-badge]

Read the badge in the **Status** column, one of seven values from "Overdue" to "Waived". [Match the badge to what it means](#match-the-badge-to-what-it-means) says what each one asks of you. The Console computes the badge in your browser from the period's state and the time left to its deadline. A fulfilled period never reads as due soon, and an overdue period stays overdue. The list is sorted by badge, most at risk first, and within one badge the earliest deadline comes first.

### Check chain family coverage [#check-chain-family-coverage]

Read the badge in the **Coverage** column. It names the chain family, the kind of network the report covers, and its state, for example "EVM: Pending". A family the period never claimed shows no badge.

| Badge text | What it means |
| --- | --- |
| **Covered** | The generated submission recorded reporting data for that family. |
| **Pending** | The platform has generated no submission for the period, including while a submission waits for generation or after generation failed. |
| **Not recorded** | A generated submission recorded no coverage for that family. One reason is given underneath. |
| **Refused** | The submission could not produce valid data for that family. The listed reasons explain why. |

Select a badge that has reasons to read them. A submission that recorded no coverage, or that refused a family, cannot be approved. Approval is the only step that checks this verdict. A later submission for the same period can produce a different verdict.

### Continue to Obligations or Filings [#continue-to-obligations-or-filings]

Select the row's obligation name to open its page, which lists its published versions, or open the "Obligations" tab to see its status and whether it is disabled. The **Filing** column names the state of the period's latest filing, or shows that the period has no filing. Select it to open that filing on "Filings", which lists every attempt made for a period.

## Match the badge to what it means [#match-the-badge-to-what-it-means]

A row's urgency badge holds one of seven values, listed here in the order the list sorts them.

| Badge | What it means | What to do |
| --- | --- | --- |
| **Overdue** | The deadline has passed. This includes a period whose stored state still reads open or scheduled after its deadline. A late deadline never reads as Open or Waiting for finality. | Treat the duty as late. Open the period's filing on Filings, or generate one there, and file it. |
| **Due soon** | The deadline falls within the next five days and the period is not waiting on chain finality. | Act on this duty before the rows below it. |
| **Open** | The period has started and its deadline is more than five days away. | Prepare the filing on Filings. |
| **Waiting for finality** | The period needs the network to confirm its last block as final before it can open, and keeps this badge inside the five-day window until that confirmation lands. | Nothing to do here. The period opens when finality confirms, and acting sooner does not open it. |
| **Scheduled** | The period has not opened and its deadline is more than five days away. | Nothing to do until the period opens. |
| **Fulfilled** | The duty has been discharged for this period. | Nothing further. Its deadline no longer applies. |
| **Waived** | The obligation that produced this period was disabled before the period opened, or one person selected **Waive period** on Filings and recorded why. That person is an organisation owner or a platform administrator, and no second approver is asked. | Nothing further. This period carries no outstanding duty. |

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

- Confirm that the duty you expect has a row and that its **Status** badge fits its "Due" date.
- A period due next week does not read "Overdue".
- Confirm that the "Coverage" column has a badge for every family of networks the period claims.

## Troubleshooting [#troubleshooting]

| What you see | What it means and what to do |
| --- | --- |
| A duty you expect is missing | Filing calendar and Obligations read the same catalogue, but a period only appears here once its obligation has a published version. A draft obligation produces no periods. Confirm you selected the organisation that owns it, then check Obligations. |
| The page reads **Select an organisation to see reporting** | Filing calendar needs an active organisation. Select one before you open **Reporting**. |
| An error replaces the table | The list could not load. Use the control to try again, or refresh the page. |
| **No filing periods yet** | No obligation in this organisation has a published version. Publish one on Obligations and its periods appear here on schedule. When an obligation is already published, the page says instead that a scheduled period appears here once it ends. **Open obligations** opens the Obligations list. |

## Frequently asked questions [#frequently-asked-questions]

### Does Filing calendar show every filing period, or only current ones?

Every one your organisation has. The screen has no date filter and no archive, so a period keeps its row, including one fulfilled or waived long ago.


# Filings

Source: https://docs.settlemint.com/docs/console/reporting/filings
Move filing attempts to completion, follow up on anchoring, and watch transaction reports to the regulator.

Filings lists the attempts your organisation has made to discharge reporting duties. Each row is one submission against a filing period, not the duty itself. Use this screen after [Filing calendar](https://docs.settlemint.com/docs/console/reporting/filing-calendar) tells you a period is due: generate the filing, send it for review, approve it and record how it was completed.

Reading the list changes no filing or asset state. A filing artifact, the set of stored files, can contain holder-level personal data, so only an organisation owner or a platform administrator can download one. [Who can do what](#who-can-do-what) lists which role gets which control.

![Filings table with each attempt's filing state and anchor state](https://docs.settlemint.com/docs/screenshots/console-reporting-filings-list.light.en.webp)

[Screenshot] The "Filings" page with a figures strip, filter controls and a table that shows each filing attempt as a row, with its filing state and anchor state.

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

- You need a filing to work on. A filing appears once a filing period has been generated against an obligation. Without one, the page reads "No filings yet" and offers **Open obligations**.
- You need a second owner to approve. The person who selected **Submit for review** is the filing's maker and cannot approve it, so another organisation owner has to. The person who generated the filing is not checked, so an owner who generated it can approve it when someone else submitted it for review. A filing that waits says who can approve it: a viewer who cannot approve reads "Waiting for approval by an organisation owner" with the names of the owners other than the maker.
- You need your own session. An impersonated session cannot approve, publish or record an authority receipt.
- You need to know where the filing goes. The platform sends no filing file to an authority. You send it through your organisation's channel and record the receipt, or you publish it, depending on the obligation's published version. Trade reports are the exception: see [Watch transaction reports to the regulator](#watch-transaction-reports-to-the-regulator).

## Steps [#steps]

### Open a filing [#open-a-filing]

Open "Reporting", then **Filings**.

A strip above the table counts the "Pending approval" filings under **Awaiting approval**, the "Overdue" ones, and those that read "Anchor unconfirmed". Select a figure to filter the table.

The table lists every attempt in the columns "Obligation", "Regime", "Report", "Due", "Status" and "Anchor", followed by an unlabelled column of row actions. It filters by regime, report, filing state, anchor state, and whether the filing is overdue, and **Search filings** searches the rows.

Columns that do not fit the window are hidden, and "Due", "Status" and "Anchor" move under the obligation name. **View** lists the hidden columns and turns any of them back on. Its count includes "Overdue", which starts hidden, and leaves out the columns the window is too narrow for. Select a filing's name to open it in a sheet, which holds the lifecycle actions, the findings and the stored parts.

When the page opens, filings that need action come first, earliest due date first: "Ready for review", "Pending approval", and any attempt other than a superseded one whose period is overdue. Filings still in progress follow, earliest due date first, such as "Queued", "Generation failed", "Blocked", "Approved" and "Submitted". "Published", "Acknowledged", "Superseded", "Rejected" and "Discarded" filings come last, latest due date first, unless their period is overdue. Ad-hoc filings and filings whose period could not be loaded have no due date, so each sits after the dated filings in its group. Select a column header to sort by that column instead.

If the page could not load the matching period, the row still appears and reads **Filing period not loaded**, the due date reads "No deadline on record", and the regime and fiscal period stay empty.

A filing made with "Generate for date range" in [Obligations](https://docs.settlemint.com/docs/console/reporting/obligations) shows the badge **Ad hoc**. Its fiscal period reads as the first and last day of the range, or as the one day for a single-day range. It has no deadline, so it is never overdue, raises no deadline alert and is never recorded as fulfilled late. [Filing calendar](https://docs.settlemint.com/docs/console/reporting/filing-calendar) lists scheduled periods only. An ad-hoc filing appears on Filings once its period is final and its files are generated, and then follows the same steps as any other filing.

### Generate and request review [#generate-and-request-review]

Select **Generate** on a queued attempt or to retry a failed generation. A filing that is "Ready for review", "Pending approval" or "Approved" does not show "Generate".

An "Approved" filing offers only its ending, "Record submission to authority" or "Publish". To change it, replace it from the **More** menu, and the new attempt goes through review and approval again.

When the row reads "Ready for review", select **Submit for review**.

### Read the findings [#read-the-findings]

A filing that is ready for review or waits for approval shows a **Findings** panel when validation raised findings.

A "Blocking" finding stays until you correct the data and generate the filing again. Select **Replace** under "More", then "Generate" on the new attempt.

For a "Warning" finding, an organisation owner other than the maker selects **Accept warnings**, writes why the warnings are acceptable in "Why these warnings are acceptable", and confirms. "Approve" stays unavailable until no finding stands, and the Console says "Accept the warnings to approve this filing."

### Approve the manifest digest [#approve-the-manifest-digest]

An organisation owner other than the maker opens **Approve** on a filing that is "Pending approval". Check the "Manifest digest being approved" in the dialog, then confirm. The digest identifies the filing files being approved. If the filing changes while the dialog is open, the platform rejects the old approval. Close the dialog and review the updated filing before trying again.

### Complete the filing [#complete-the-filing]

The obligation's published version determines how its filing is completed. A filing takes one of these two endings:

| Fulfilment mode | Console actions |
| --- | --- |
| Authority acknowledgement | Send the filing through your organisation's channel, then select **Record submission to authority**. Someone other than the approver selects **Record acknowledgement** and enters the **Authority receipt reference** and the **Authority acknowledgement time** in local time. |
| Publication | An organisation owner selects **Publish**, checks the approved digest and enters the **Publication reference**. |

Recording the authority receipt or publishing fulfils the filing period. The platform does not check the receipt with the authority: it records the reference and time you enter, and the period reads **Fulfilled**.

A receipt reference belongs to one submission, so the platform refuses a reference another submission carries. The Console marks the field and keeps the dialog open. Enter the reference the authority issued for this filing.

## Return a filing to the maker [#return-a-filing-to-the-maker]

For a filing that is "Pending approval", an organisation owner other than the maker can select **Return to maker**. The dialog is "Return filing to maker". Explain what needs correcting in "Reason for returning the filing". The reason is required and is recorded in the action log with your action. The filing returns to review. The maker cannot perform this checker action, and you must use your own session.

## Replace, terminate, revive, waive or reject [#replace-terminate-revive-waive-or-reject]

**More** in the filing's sheet holds these acts. Each keeps the earlier attempt on record.

- **Replace** supersedes an attempt that has not been sent with a new one of the "Replacement type" you choose: "New", "Modification", "Correction" or "Cancellation for error".
- **Terminate** supersedes it with a termination of the duty. A termination attempt offers "Revive" instead.
- **Record rejection** records that the authority rejected a sent filing, with the "Reason the authority gave". The filing becomes "Rejected".
- **Waive period** lets one organisation owner or platform administrator waive a period that has not opened, with a written reason in "Why this period is waived". No second approver is asked, and the period reads "Waived" on Filing calendar.

## Download or follow up on anchoring [#download-or-follow-up-on-anchoring]

Select **Download** to get one link for each stored artifact part. Each link is a pre-signed address that anyone who holds it can open for 15 minutes without signing in, so do not forward a link. Issuing the links is a sensitive read: the platform records it in the [Audit trail](https://docs.settlemint.com/docs/console/reporting/audit-trail) when it can write the entry, and later use of a link is not recorded. The last part is `filing.csv`, which names the obligation version, filing period, organisation and reference window. The manifest digest covers it, so include it with the other parts when you verify an anchor in [Anchor registry](https://docs.settlemint.com/docs/console/reporting/anchor-registry). Do not combine the parts: the anchored digest is computed across them, so a joined file does not match what was anchored.

**Download** stays disabled when no artifact exists, and the sheet says "No file has been generated for this attempt." An erased filing shows a notice instead of links.

Select **Anchor again** to retry the anchor of a discharged filing whose anchor state is "Unconfirmed".

Select **Override exception** to record why your organisation accepts that the filing is not anchored. The button in the dialog stays disabled until you enter a reason. The anchor state then reads "Accepted without anchor", and the line under it reads "Accepted by" with your name and the date. When the person who accepted is not a member of the organisation, for example a platform administrator, the line reads "Accepted on" with the date only.

A filing with an anchor shows an **Anchor registry entry** link that opens that one entry in Anchor registry.

## Place a legal hold [#place-a-legal-hold]

A legal hold keeps a filing, and the files behind it, while a matter such as a regulator's inquiry is live. It changes no filing state and withholds no download: it is the reason the files are still there, whatever the retention says.

The filing's sheet shows each open hold under "Legal hold" with its reason, when it was placed and who placed it. A filing with no open hold offers **Place legal hold**.

1. Open the filing from the table and select **Place legal hold**.
2. Write why this filing is held, in **Why this filing is held**. The reason is recorded in the [Audit trail](https://docs.settlemint.com/docs/console/reporting/audit-trail) and shown to everyone who opens the filing.
3. Select **Place legal hold**. The filing's sheet shows the hold, and the retention sweep passes over the filing from then on.

## Release a legal hold [#release-a-legal-hold]

A filing can carry more than one hold, and each is released on its own. Releasing the last open hold puts the filing back under its retention period.

1. Open the filing and select **Release legal hold** on the hold you mean.
2. Write why the hold is released, in **Why the hold is released**.
3. Select **Release legal hold**. The filing follows its retention period again: a period that already ended is erased by the next sweep, and one that has not ended yet ends later as usual.

## Match the anchor state to the next step [#match-the-anchor-state-to-the-next-step]

| Anchor state | What it means | What to do |
| --- | --- | --- |
| **Not requested** | No anchor result is recorded for this filing. This is the default, and it stays after an anchor run is refused, for example because the filing is not discharged or anchoring is off. | If you expected an anchor, check the duty's anchoring setting in [Obligations](https://docs.settlemint.com/docs/console/reporting/obligations). |
| **Still running** | An anchoring attempt started and has not recorded a result. | Only a later anchoring attempt changes this state. The page offers no control while it lasts. |
| **Confirmed** | The filing's anchor landed, and no later attempt replaces it. | Use the row as evidence that the attempt has an anchor. |
| **Unconfirmed** | The anchor did not confirm after the last attempt, and the finding still stands. | On a discharged filing, an owner or platform administrator can select **Anchor again**. Either can select **Override exception** and record why, and the platform accepts one override for each filing. |
| **Accepted without anchor** | The anchor stayed unconfirmed and an owner or platform administrator overrode the exception with a recorded reason. | Nothing further. The filing stays unanchored, the override reason is on record, and the row says who accepted it and on which date. |

## Watch transaction reports to the regulator [#watch-transaction-reports-to-the-regulator]

Filings shows a **Transaction reports to the regulator** card below the filings table once the organisation has a published obligation that configures a regulator FIX session, a regulator session that has connected before, a queued trade report or an unmatched regulator answer. Anyone who can open Filings sees it. [Trade reports](https://docs.settlemint.com/docs/concepts/records-and-evidence/trade-reports) explains what each report contains and how the session sends it.

1. Read **Regulator connection**. "Connected" with "Logged on" and a UTC time means the regulator accepted the session's Logon. "Disconnected" with "Reports wait until the connection returns" means a session is configured but is not logged on, so reports stay queued. "Not set up" means no published obligation configures a session. The platform keeps one record for each pair of sender and target CompIDs the organisation has used, so an organisation whose CompIDs changed shows one cell for each pair, named by the target CompID.
2. Read **Waiting to be sent**. The count is the queued reports, and "Oldest waiting" gives the age of the oldest one in minutes. The platform queues new trades every 15 seconds, and a connected session sends up to 100 queued reports at a time.
3. Read **Unmatched regulator answers**. Each row is an answer that moved no report, with the time "Received", the "Report" it named, or "No report named", and the "Reason". The platform keeps every row. The panel shows the newest 50 by the time they were received.

The session works when the connection reads **Connected**, "Waiting to be sent" reads 0, and no new row appears under "Unmatched regulator answers".

| What you see | What to do |
| --- | --- |
| **Disconnected** and a growing **Waiting to be sent** count | The session did not start or is not logged on. Ask the platform operator whether the regulator endpoint is on the deployment's allow list, whether the session's schedule window is open, and whether the session is held after a fault, which keeps it down until its configuration changes. Check on [Obligations](https://docs.settlemint.com/docs/console/reporting/obligations) that only one published trade journal version configures a session and that its message layout names a FIX version the session supports. If the regulator cannot be reached, file the trade journal export through your own channel as [Trade reports](https://docs.settlemint.com/docs/concepts/records-and-evidence/trade-reports#fall-back-to-the-file) describes. |
| **Not set up** and a growing **Waiting to be sent** count | The trade journal is in a published obligation that configures no regulator session, so its reports are queued and never sent. File the trade journal as a file, or publish a version that configures a session. |
| **Not set up** on a duty that should send trade reports | Check on [Obligations](https://docs.settlemint.com/docs/console/reporting/obligations) that a version with a regulator session is published. |
| "The regulator sent a message that is not an answer to a transaction report" | Compare the message with the regulator's specification, and ask the regulator what the message was meant to answer. No report changed. |
| "The answer lacks a field needed to read it" | Check that the message layout's answer settings match the regulator's acknowledgement format. Publish a corrected version if they differ. |
| "The answer names a report that was never queued" or "The answer does not fit the report's current state" | Compare the answer with the regulator's records. Find the report's `id` with `GET /api/v2/reporting/transaction-reports?filter[q]=` and the report ID the answer named. An organisation owner or a platform administrator sets the report's state with `POST /api/v2/reporting/transaction-reports/{transactionReportId}/transitions`. The platform takes that person's word for the regulator's answer, asks no second approver and records the change in the audit trail. |
| "The regulator rejected a session message that carried no report" | Ask the regulator why it rejected the message. No report changed. |

## Watch the regulator reporting evidence [#watch-the-regulator-reporting-evidence]

Below the transaction reports card, Filings shows a **Regulator reporting evidence** card for the last 24 hours. It appears when the period has session history, messages, reports, delay breaches or alerts, or when a reconciliation, legal hold or certification run exists. It is read-only. Placing a hold and recording a certification run use the Platform API, as [Trade reports](https://docs.settlemint.com/docs/concepts/records-and-evidence/trade-reports) describes.

1. Read the strip. **Session uptime** is the share of the period that the regulator had accepted a Logon, and shows the lowest figure when the organisation has more than one session. "Logons" and "Logouts" count the session's logon and logout events. "Session rejects" counts messages the regulator refused at session level. "Waiting to be sent" is the queue, with "Oldest waiting" in minutes. "Reports sent late" counts reports that waited longer than 15 minutes, until they were sent or the period ended.
2. Read **Daily reconciliation**. Each row is one version of one "Trading day", with "Trades and busts" executed, how many are "Acknowledged", and "Breaks". "Balanced" means every trade and bust was acknowledged. A number means that many have no acknowledged report, and the day has an open operations case that closes when a later version balances.
3. Read **Alert history** for the days that raised a break alert, "Logon and logout history" for each event with its "Reason", "Legal holds" with each hold's "Reason", when it was "Placed" and whether it is "Active" or "Released", and "Certification runs" with each run's "Environment", "Outcome" and "Cases passed".

A table with no rows is left out. The lines behind a reconciliation, the session's messages and the exports are available through the Platform API and as reports of kind `regulator-reconciliation`, `regulator-messages` and `regulator-monitoring`.

## How long a filing is kept [#how-long-a-filing-is-kept]

A filing keeps its stored files for the retention its obligation sets under **Keep for**. "Five years", "Seven years" and "Ten years" count from the day the filing is accepted, and "Indefinitely" never erases. When the retention ends, the platform erases the stored files and keeps a record of the erasure: the manifest digest, the retention it was kept under and the number of objects removed. Download any filing you must keep longer before its retention ends.

The filing's sheet shows **The stored file has been erased**, "Retained under" with the retention, and how many objects are confirmed gone. "Download" offers no links. While the platform is still writing the erasure record, the sheet reads "The erasure is still being recorded, so no tombstone is available yet."

Where the deployment stores reports on write-once storage, nobody can replace or delete a filing's files until the lock ends. See [Values and secrets](https://docs.settlemint.com/docs/deployment/install/values-secrets#write-once-report-storage).

A legal hold on a filing stops the erasure whatever its retention says. [Place a legal hold](#place-a-legal-hold) and [Release a legal hold](#release-a-legal-hold) say how to hold one filing and how to release it again. Once the last open hold is released, the platform erases the files if the retention has already ended.

## Who can do what [#who-can-do-what]

Opening the screen and acting on it need different roles. Any role listed for this page opens the screen. The controls follow the person's organisation role. A platform administrator holds the deployment's platform role and gets these controls in every organisation they are a member of, whatever their organisation role:

| Control | Who is offered it |
| --- | --- |
| **Generate**, **Submit for review**, **Record submission to authority**, **Replace**, **Terminate**, **Revive**, **Record rejection** | An organisation owner, an organisation member or a platform administrator. |
| **Record acknowledgement** | The same people, other than the person who approved the filing, and not from an impersonated session. |
| **Approve**, **Accept warnings**, **Return to maker** | An organisation owner other than the maker, not from an impersonated session. |
| **Publish** | An organisation owner, not from an impersonated session. |
| **Waive period** | An organisation owner or platform administrator, not from an impersonated session. |
| **Download**, **Anchor again** | An organisation owner or a platform administrator. |
| **Place legal hold**, **Release legal hold** | An organisation owner or a platform administrator, not from an impersonated session. |
| **Override exception** | An organisation owner or a platform administrator, not from an impersonated session. |

A reader who is neither an organisation owner nor a platform administrator sees the note "Organisation owners approve and publish filings. Organisation owners and platform administrators download them."

## Get email about a filing [#get-email-about-a-filing]

The platform emails the organisation's owners who have an email address on file. Each email names the filing and has one button that opens it. No email carries the filing's files or rows.

| Email | When it is sent | Who is left out |
| --- | --- | --- |
| Filing ready for review | The filing is generated and waits for review. | The person who started the generation. |
| Filing could not be generated | Generation failed. Open the filing in the Console to see why, then start it again. | Nobody. |
| Filing not acknowledged in time | The authority has not acknowledged the filing within its acknowledgement window. | Nobody. |
| Filing deadline approaching | The filing has not been submitted and its deadline is close. The email shows the deadline in the organisation's time zone. | Nobody. |
| Filing deadline passed | The deadline passed without a submission. | Nobody. |

The platform sends each acknowledgement and deadline email once per alert. Without a configured mail transport it sends no email, so check the Console.

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

- The filing you need appears, and its **Status** matches the attempt you expected.
- After "Record acknowledgement" or "Publish", the row reads "Acknowledged" or "Published", and the period reads "Fulfilled" on [Filing calendar](https://docs.settlemint.com/docs/console/reporting/filing-calendar).
- The **Anchor** column tells you whether follow-up is required.

## Troubleshooting [#troubleshooting]

| What you see | What it means and what to do |
| --- | --- |
| **No filings yet** | No filing period in this organisation has produced an attempt. Check Filing calendar for generated periods and Obligations for whether the duty has a published version. |
| **Deadlines unavailable**, or a duty name or deadline is missing | The filing periods could not be loaded. The page still lists the filing attempt and shows the notice. Refresh the page to try again. |
| **Download** is unavailable | A stored artifact must exist, and your account must be an organisation owner or platform administrator. Ask one of those users to download it, or read the filing state and anchor state. |
| An anchoring action was refused | Only an organisation owner or a platform administrator sees these controls, and the platform refuses the request from anyone else. An impersonated session cannot override an anchor exception. |
| **Anchor again** is unavailable | The Console offers **Anchor again** only on a discharged filing, one that is **Acknowledged** or **Published**, whose anchor state is **Unconfirmed**. Before discharge, an **Approved** filing can still be replaced, which starts a fresh attempt. |
| **That action was refused** | The Console shows the platform's reason. When the filing has moved on, the dialog says "This filing has moved on, so this action no longer applies." Close the dialog and read where the filing stands. |

## API routes [#api-routes]

The screen uses these reporting routes of the [Platform API](https://docs.settlemint.com/docs/api-reference/v2):

- `GET /api/v2/reporting/submissions` lists filing attempts, and `POST /api/v2/reporting/submissions/{submissionId}/generations` starts a generation.
- `POST /api/v2/reporting/submissions/{submissionId}/acts` carries the lifecycle acts: submit for review, approve, record submission, acknowledge, publish, replace, terminate, revive, waive and reject.
- `GET /api/v2/reporting/submissions/{submissionId}/artifact` returns the download links.
- `POST /api/v2/reporting/submissions/{submissionId}/anchoring/transitions` retries an anchor and answers `confirmed` without starting a run when the filing is already anchored, and `POST /api/v2/reporting/submissions/{submissionId}/anchor-overrides` records an override.
- `GET /api/v2/reporting/transaction-reports` and `POST /api/v2/reporting/transaction-reports/{transactionReportId}/transitions` read and correct transaction reports.


# Reporting

Source: https://docs.settlemint.com/docs/console/reporting
The Reporting group of the Console sidebar: the organisation's filing duties and the record of who did what.

The **Reporting** group holds the organisation's filing duties and the evidence behind them. An obligation is a recurring duty to file a report, Filing calendar lists the periods it creates, and a filing completes one period. Anchor registry, Statements, Daily transactions and Audit trail hold the evidence. Organisation owners draft, publish and approve on these screens, and so do platform administrators, who hold the deployment's platform role and act in every organisation they are a member of, even with the Member role. Holders of some on-chain roles can open the screens too, as each page lists. Statements opens for owners and platform administrators only.


  - [Anchor registry](https://docs.settlemint.com/docs/console/reporting/anchor-registry): Read the document anchor registry, check a document against it and anchor a new one.
  - [Filing calendar](https://docs.settlemint.com/docs/console/reporting/filing-calendar): Review the organisation's filing periods and each one's urgency.
  - [Filings](https://docs.settlemint.com/docs/console/reporting/filings): Move filings to completion, watch regulator reports, and place legal holds.
  - [Obligations](https://docs.settlemint.com/docs/console/reporting/obligations): Draft, publish and disable reporting duties, and switch chain anchoring on or off.
  - [Statements](https://docs.settlemint.com/docs/console/reporting/statements): Generate a wallet statement for a date range and set the statement policy.
  - [Daily transactions](https://docs.settlemint.com/docs/console/reporting/daily-transactions): Download chain movements, corporate actions, venue trades and custody for up to 31 days.
  - [Audit trail](https://docs.settlemint.com/docs/console/reporting/audit-trail): Review who acted, in what role, with what outcome, and what people asked the assistant.



# Obligations

Source: https://docs.settlemint.com/docs/console/reporting/obligations
Draft, edit, publish and disable reporting duties, review their versions, and turn chain anchoring of fulfilled filings on or off.

Obligations lists your organisation's [reporting duties](https://docs.settlemint.com/docs/concepts/records-and-evidence/reporting-obligation) and the published version used to generate each duty's filings. Use this screen to draft a custom duty, edit a draft, publish it, disable a duty, review its versions, or manage optional chain anchoring. To see which filing period needs attention, open [Filing calendar](https://docs.settlemint.com/docs/console/reporting/filing-calendar). To see attempts already made against those periods, open [Filings](https://docs.settlemint.com/docs/console/reporting/filings).

Publishing freezes the draft as a numbered version. A period generated under version 2 keeps being filed under version 2 after version 3 is published. The tabs "Obligations", "Filing calendar" and "Filings" at the top of each list move you between the three.

![Obligations list with each duty's name, report, cadence, version, anchoring and status](https://docs.settlemint.com/docs/screenshots/console-obligations-list.light.en.webp)

[Screenshot] Each row names a reporting duty with its "Report", "Cadence" and published "Version", or "Not published" for a draft.

The "Anchoring" column reads "Anchoring enabled" or "Off", and the "Status" column reads "Draft" or "Active".

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

- **Who manages duties.** The Console offers drafting, editing, publishing, disabling and generating for a date range to organisation owners and platform administrators. Other readers see "Organisation owners and platform administrators manage obligations." A platform administrator holds the deployment's platform role and can manage the duties of every organisation they are a member of, even with the Member role.
- **Reporting and finance operations.** The deployment's "Reporting and finance operations" module has to allow changes. When it does not, the screen offers no "New obligation" and no actions on any obligation.
- **Two owners.** The organisation's "Reporting" approval on [General](https://docs.settlemint.com/docs/console/organisation-settings/general#approvals) reads "On" or "Off". While it reads "On", the platform refuses to publish an obligation unless the organisation has at least two owners. This is a head count, not a second approval: publishing opens no approval request and takes effect at once, so one owner publishes alone once a second owner exists. With the row "Off", the check does not apply. An organisation owner or a platform administrator can switch the row, or switch the check off for one obligation, as [Allow one obligation to publish with fewer than two owners](#allow-one-obligation-to-publish-with-fewer-than-two-owners) explains.
- **For chain anchoring.** Confirm the intended EVM network. Anchoring makes the permanent public disclosure that the confirmation dialog describes, so agree it inside your organisation before you turn it on.

## Steps [#steps]

### Review the obligations [#review-the-obligations]

Open "Reporting", then **Obligations**. The table columns are "Name", "Regime", "Report", "Cadence", "Version", "Anchoring" and "Status", followed by an unlabelled column of row actions, and "Search obligations" searches the rows. When the table is too narrow for every column, "Regime" is the first to drop out, and "View" lists it. "Version" reads "Not published" until a version exists, then the version number. "Anchoring" reads "Anchoring enabled" or "Off". "Status" reads "Draft", "Active" or "Disabled", and "Disabled" marks an obligation that no longer produces new filing periods. A platform catalogue entry, a ready-made duty the platform supplies, reads "Managed by the platform." in place of its controls. Select the duty's name to open its page, as [Read an obligation's page](#read-an-obligations-page) describes.

### Draft a custom duty [#draft-a-custom-duty]

Select **New obligation**, then fill in the sheet:

- Enter a **Name**, an "Identifier", a "Regime", a "Description" and, if you want one, the "Reporting entity LEI (optional)". The identifier is filled from the name until you change it, and it cannot change after you create the draft.
- Choose the **Report** and the "Cadence".
- Set the deadline with **Due after**, "Counted in", which takes "Calendar days", "Business days" or "Hours", and "From", which takes "The period end" or "The period start".
- Choose the **Holiday calendar** and the "Time zone" in which periods start and deadlines fall due.
- Set **The duty ends with** to "Publication by us" or "Acknowledgement from the authority".
- Choose the **File format**: CSV, XLSX, ZIP, JSON, XML or PDF. A new draft starts on CSV.
- Choose **Keep for**, the retention: "Five years", "Seven years", "Ten years" or "Indefinitely". A new draft starts on "Seven years". [How long a filing is kept](https://docs.settlemint.com/docs/console/reporting/filings#how-long-a-filing-is-kept) says what the retention does.

![New obligation sheet for drafting a custom reporting duty](https://docs.settlemint.com/docs/screenshots/console-obligations-new-draft.light.en.webp)

[Screenshot] The "New obligation" sheet, where you draft a custom reporting duty that becomes active when you publish it.

For a duty about client assets, choose one of two reports. **Client asset summary** lists each client position with its account type and market value. "Safeguarding extract" allocates each client's outstanding custody receipts to the addresses that hold the backing coins. Outstanding receipts include receipts in the client's wallets and receipts locked in unfinished withdrawals. A position is segregated when its gateway keeps the coins for one client, or omnibus when its destination pools them. The classification and destination use the gateway's current coins-go-to terms. The balances and records use the report's as-of block.

A gateway that keeps funds allocates its receipts to escrow. For a gateway that forwards coins, confirmed funding, reserved withdrawal coins and receipt-backed custody returns are allocated to escrow first, up to the outstanding receipts. The rest is allocated to the destination, so each receipt counts once. Quarantined coins and withheld fees carry no receipt allocation. The extract shows actual coin balances at each holding address and the difference between that balance and the client allocations. Extra nonzero escrow and gateway balances also appear. Its **Asset totals** sheet counts a shared address balance once for each network and asset, and keeps the segregated or omnibus classification while coins wait in escrow.

The reconciliation reference names the latest gateway reserve observation at or before the report's as-of time. A custodian balance stays empty without evidence for that account. An aggregate balance across watched addresses cannot fill it. An asset's balance and difference in **Asset totals** stay empty when any holding address lacks that evidence.

For regulator evidence, choose **Regulator reporting reconciliation**, "Regulator session messages" or "Regulator session monitoring evidence". These reports export the daily reported-versus-executed results, the retained FIX messages or the monitoring history for the filing period. The regulator session and its separate certification test profile are configured through the Platform API. The draft preserves those settings when you edit other fields here.

A duty about the bank rail uses the `bank-rail-reconciliation` report kind, which the sheet does not list: author it through the Platform API, and the Console shows it as **Bank rail reconciliation** on the duty's page and on its filings. Each filing is the bank rail's daily reconciliation for the period: one row for each bank connection and closed day, with the same columns as the export on a connection's reconciliation page. A day whose reconciliation could not be completed keeps its row, marked unavailable with its reasons and with empty amounts. An organisation without a bank connection files an empty report.

Select **Create draft**. Nothing is scheduled until you publish the draft.

### Edit the draft [#edit-the-draft]

Select "Edit" from the obligation's row menu or on its page, change the fields, and select **Save draft**. Platform catalogue entries and disabled obligations cannot be edited.

The sheet also sets what the filing contains and the layout of its authority file:

- **Deadline.** Choose what happens when the deadline is not a business day with "If the deadline is not a business day", and the local "Cut-off time" for the filing.
- **Tokens.** Keep "All tokens", or list the EVM token addresses the filing covers, one per line. A list holds at most 200 addresses. A report without a token column cannot take a list.
- **Derived values.** Add a value that the filing calculates from a report field, such as the sum of the balances or the number of rows. Validation rules and the authority file can use it.
- **Validation rules.** Add a rule with its severity, its expression and the message a filing shows when the rule fails. A changed rule gets a new version, so earlier filings keep the rule they were checked against.
- **Authority file.** Turn on "Custom file layout" to write one extra file in the authority's layout: its name, CSV or XLSX, the CSV delimiter, and the columns in order. Remove, add back, move, rename and format each column. The report file in the same filing still holds every column.
- **Group rows by.** For an XLSX file, choose a column to write one sheet for each value in it. Each sheet repeats the header, and empty values go to a sheet named "Blank". The platform reads each cell as it is written to the file, so a formatted amount groups as its text. A file with no rows stays one sheet with only the header. The platform adds no subtotal rows. Publishing is refused for a CSV file, for a file whose rows are the data points, or for a header that no column carries.

If the platform refuses a value when you save, the message shows on that field. The sheet keeps settings it does not show, such as a layout of several files set through the Platform API. When the authority file layout was set outside the Console, the **Report** field is locked and the draft keeps its report.

If the Platform API set a report the **Report** list does not offer, such as "Wallet register" on a deployment without custody operations reports, the field shows that report. It stays in the list until you save a different report.

Choosing another report and selecting **Save draft** replaces every report the draft held with the one you chose. When the draft held the trade journal and configures the organisation's [regulator session](https://docs.settlemint.com/docs/concepts/records-and-evidence/trade-reports), publication refuses it until you choose "Trade journal" again. Without a session, a version published from that draft queues no trade reports. A later version that adds the trade journal back resumes after the last trade change the obligation queued. It queues a report for every trade and every bust, the cancellation of a trade, since then. A report queued earlier keeps its body.

### Publish a reviewed draft [#publish-a-reviewed-draft]

Select **Publish** from the obligation's row menu or on its page. It appears on every enabled obligation your organisation owns, and each publish creates the next version. A platform catalogue entry offers no "Publish": the entry is the same in every deployment, so no organisation may publish it. The "Publish obligation?" dialog explains that publication freezes the draft as the next version and starts filing periods. Confirm "Publish" only after reviewing that draft. A refusal stays in the dialog with its reason, and the list refreshes after the attempt.

Publication is unavailable on a disabled obligation. If the platform refuses your role, ask an organisation owner or a platform administrator to publish the draft. A publish sent against a platform catalogue entry comes back as a conflict that names the catalogue and points you at your own copy of the duty.

## Generate a filing for a date range [#generate-a-filing-for-a-date-range]

Open the actions menu of a published, enabled obligation and select **Generate for date range**. The item is not offered on a platform catalogue entry, a disabled obligation or a draft with no published version. Enter the first day in "From" and the last day in "To". Both days are part of the range. The dialog names the time zone of the obligation's deadline rule, and the platform reads the dates in that zone. A range of 1 to 15 October covers 1 October at 00:00 up to 16 October at 00:00 in that zone.

Select **Generate filing**. The platform adds one filing period to the obligation. The schedule does not change. The dialog says the filing appears in [Filings](https://docs.settlemint.com/docs/console/reporting/filings) once its period is final and its files are generated, and offers "Open Filings". Entering the same range again returns the period that exists.

A refusal shows on the field that caused it:

| Refusal | What to do |
| --- | --- |
| The end date is before the start date | Choose an end date on or after the start date. |
| The range has not ended in the time zone | Choose an end date on or before the latest day the dialog names. |
| The range is already a scheduled period | Find the filing in [Filing calendar](https://docs.settlemint.com/docs/console/reporting/filing-calendar), or choose a different range. |
| The range ends before recorded history | Choose a later end date. |
| The obligation is disabled or unpublished | Close the dialog. Publish the obligation, or choose an active one. |
| The deadline rule or holiday calendar cannot be evaluated | Fix the obligation's deadline settings or holiday calendar, then try again. |

## Disable a duty [#disable-a-duty]

Disabling cannot be reversed, in the Console or through the Platform API. One organisation owner or platform administrator can disable a duty. No second approver is asked, and the [Audit trail](https://docs.settlemint.com/docs/console/reporting/audit-trail) records who did it. The platform records no reason, so the Console asks for none.

Select "Disable", read the confirmation, and confirm **Disable obligation**. A disabled obligation takes no new filing periods. Published versions and past filings stay on record.

## Turn chain anchoring on or off [#turn-chain-anchoring-on-or-off]

Chain anchoring records a fulfilled filing's manifest digest in the document anchor registry on the selected network. It lets a holder compare a supplied document with its on-chain record, as [How an anchor proves a filing was not altered](https://docs.settlemint.com/docs/concepts/records-and-evidence/reporting-obligation#how-an-anchor-proves-a-filing-was-not-altered) explains. Turning anchoring off stops new anchors and does not remove existing records or reverse their disclosure.

Turning anchoring on needs an organisation owner or a platform administrator signed in as themselves, not in an impersonated session, and the obligation needs a published version. Turning it off needs the same, or a platform administrator in an impersonated session. The platform records each change as a new setting, with its author and reason.

To turn it on, select **Anchor filings** and fill in the dialog:

- Check **Chain**.
- Choose the available severity under **How loudly to report a missing anchor**.
- Choose a **Document type**: "Regulatory filing" or "Investor report".
- Enter a short **Document label** that contains no organisation name, period or identifier. A label that contains one shows "This label may say more than you mean to publish. It will be public and permanent." and is published as written, with every fulfilled filing, only after you tick "Publish anyway. I know this is public and permanent."
- Record why you are turning it on under **Why you are turning this on**.
- Read the disclosure warning, and confirm "I understand this disclosure is permanent and cannot be withdrawn." before submitting.

The available severities depend on the obligation. When publication fulfils the duty, only "Warning" is offered so a missing anchor cannot block that publication. To stop anchoring, select **Stop anchoring**, enter the reason, and confirm. A disabled obligation can still have open filing periods, so "Stop anchoring" stays available.

Note (Anchoring makes a permanent disclosure): From the next fulfilled filing onward, a chain reader can see that the organisation filed a document of the selected kind at that time. Stopping anchoring ends new records and leaves earlier records on the chain.

## Read an obligation's page [#read-an-obligations-page]

Select a duty's name to open its page. The **Details** card shows the "Description", the "Published version", the "Regime", the "Report", the "Cadence", the "Reporting entity LEI", "Anchoring", and a "View in filing calendar" link, which opens the [filing calendar](https://docs.settlemint.com/docs/console/reporting/filing-calendar) searched for this duty's name. The "Versions" table lists every published version with its "Published" date, its "Cadence" and what the duty ends with under "Ends with". A draft with no version reads "No version published yet".

## Allow one obligation to publish with fewer than two owners [#allow-one-obligation-to-publish-with-fewer-than-two-owners]

The "Reporting" row under "Approvals" on [General](https://docs.settlemint.com/docs/console/organisation-settings/general#approvals) holds an exception list. An organisation owner or a platform administrator picks an obligation under "Choose an obligation" and selects **Turn off the check for this one**. The dialog asks "Allow publishing" followed by the obligation's name and "with fewer than two owners?". "Allow publishing" confirms it with your wallet verification and "Keep the check" cancels. With the exception in place, that obligation publishes while the organisation has fewer than two owners. "Remove" returns it to the row's setting, which the other obligations keep.

## Send trade reports to a regulator [#send-trade-reports-to-a-regulator]

The message layout and the FIX session that carry trade journal reports to a regulator are part of the obligation version, and the Console's editor does not show them. The editor opens an obligation that carries the trade journal with **Trade journal** selected and keeps the layout and the session when you save. Edit the layout or the session through the Platform API with `POST /api/v2/reporting/obligations` or `PUT /api/v2/reporting/obligations/{obligationId}`, then publish. Publication refuses a session on a version whose report set leaves out the trade journal. A new version resumes queueing where the obligation's earlier versions stopped, and an obligation's first version with the trade journal queues the organisation's full trade history, as [When a report is queued](https://docs.settlemint.com/docs/concepts/records-and-evidence/trade-reports#when-a-report-is-queued) describes. [Trade reports](https://docs.settlemint.com/docs/concepts/records-and-evidence/trade-reports) describes the layout, the session settings and the deployment's allow list of regulator endpoints, and [Filings](https://docs.settlemint.com/docs/console/reporting/filings#watch-transaction-reports-to-the-regulator) shows whether the reports reach the regulator.

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

- After publication, confirm that the row shows the expected version number and the status "Active".
- After an anchoring change, confirm that the **Anchoring** column reads "Anchoring enabled" or "Off" as intended.
- Open [Filing calendar](https://docs.settlemint.com/docs/console/reporting/filing-calendar), find the duty's name and regime, and check for periods generated under the published version on its configured schedule.

## Troubleshooting [#troubleshooting]

| What you see | What it means and what to do |
| --- | --- |
| **Publish** is refused | Read the error in the confirmation dialog. The draft must belong to your organisation: a platform catalogue entry cannot be published, so draft your own copy instead. The draft must also be internally consistent, and its holiday calendar must be visible to the organisation. While the **Reporting** approval reads **On**, the organisation needs at least two owners. Correct the stated cause before retrying. |
| **Generate for date range** is missing | Confirm that the obligation has a published version, is enabled, and belongs to your organisation. A platform catalogue entry is not offered because its filings follow its schedule. In the Console, your account also needs the Owner role or a platform administrator account, and the **Reporting and finance operations** module has to allow changes. |
| A published version contains a mistake | Prepare and publish a corrected version. The earlier version remains unchanged, so filings generated under it keep the rules they were generated with. |
| An obligation was disabled by mistake | Disabling cannot be reversed in the Console or through the Platform API. Draft and publish a replacement obligation. |
| **Anchor filings** is missing | Confirm that the obligation is enabled, has a published version, an EVM network is selected, your account is an organisation owner or platform administrator, and the **Reporting and finance operations** module allows changes. An impersonated session cannot start a new disclosure. The emergency stop for existing anchoring has separate authorisation checks. |
| An anchoring change is refused | Read the reason in the dialog. Check the selected chain, the document label and the permitted severity, then try again. A label that names the organisation, a period or an identifier needs "Publish anyway. I know this is public and permanent.", so change the label rather than tick the box. |

## API routes [#api-routes]

The screen uses these obligation routes of the [Platform API](https://docs.settlemint.com/docs/api-reference/v2):

- `POST /api/v2/reporting/obligations` creates a draft, and `PUT /api/v2/reporting/obligations/{obligationId}` updates it.
- `POST /api/v2/reporting/obligations/{obligationId}/publish` publishes the draft, and `DELETE /api/v2/reporting/obligations/{obligationId}` disables the obligation.
- `POST /api/v2/reporting/filing-periods` creates the filing period for a date range. The response is the filing period with `origin` set to `ad_hoc`. The platform refuses a catalogue obligation with 409, and the other refusals with 422 `OBLIGATION_INVALID`, whose `data.ruleIdentity` names the reason.
- `GET /api/v2/reporting/obligations/{obligationId}/anchor-settings` and `PUT` on the same path read and change the anchoring setting.


# Statements

Source: https://docs.settlemint.com/docs/console/reporting/statements
Generate a statement for one wallet over a date range, and set the cadence, sections and formats that apply to every statement the organisation produces.

Statements gives an organisation owner or a platform administrator two cards. **Generate statement** produces a statement for one holder wallet, the investor wallet that holds the assets, on the selected network over a date range. "Statement policy" sets the cadence, the sections and the file formats that apply to every statement the organisation produces. A statement holds the sections the policy lists, for the wallet and the period. The platform marks it reconciled only when the opening balances plus the movements equal the closing balances, a check of the statement's own figures and not a comparison with a bank or custody record.

Asking again for the same range returns the same statement. A policy change applies to statements produced afterwards, not to earlier ones.

![Statements page with the Generate statement card, its Holder wallet address, First day and Last day fields, and the Statement policy card with Cadence, Sections and Formats](https://docs.settlemint.com/docs/screenshots/console-reporting-statements.light.en.webp)

[Screenshot] The "Statements" page as an organisation owner sees it.

The **Generate statement** card holds the fields "Holder wallet address", "First day" and "Last day" and the "Generate statement" button. The "Statement policy" card holds the "Cadence" list, the checkboxes under "Sections" and "Formats", an optional reason, and the "Save policy" button.

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

- **The holder's wallet address.** A statement covers one wallet. Have its address ready, starting with 0x.
- **Reporting and finance operations.** The deployment's "Reporting and finance operations" module has to allow changes. When it does not, the screen shows its title alone, without the two cards.
- **An organisation owner or platform administrator.** A platform administrator needs a membership in the organisation, in any organisation role. Any other person who opens the screen reads "Statements are managed by organisation owners and platform administrators" with the line "Ask an organisation owner or a platform administrator to change the statement policy or generate a statement."

## Steps [#steps]

### Enter the holder wallet [#enter-the-holder-wallet]

On "Generate statement", enter the wallet in **Holder wallet address**. The picker lists holder wallets only, never token contracts. You can still paste any wallet address. The Console refuses an address that is not a valid wallet address and says "Enter a valid wallet address, starting with 0x."

### Choose the days [#choose-the-days]

Enter the **First day** and the "Last day". Both days are part of the statement. The last day must not be before the first day, and a statement covers at most 366 days. The Console says "Choose a first and a last day.", "The last day must not be before the first day." or "A statement covers at most 366 days." beside the dates.

### Select Generate statement [#select-generate-statement]

Select **Generate statement**. The "Generated statement" card appears below the two cards. Changing the wallet or a date clears the card.

A statement covers only blocks that are final on the chain. When the last day is not final on the chain yet, the card reads "No statement can be produced for this range yet" and asks you to choose an earlier last day or to try again later.

### Read and download the result [#read-and-download-the-result]

The card shows the "Holder", the "Period" as "first day to last day", the "Formats" the statement is available in, and "Generated at" in UTC. A **Reconciled** badge means the opening balances plus the movements equal the closing balances for every security.

When they do not, the card reads **This statement is incomplete**, with "Opening balances plus the movements listed do not equal the closing balances for every security. Do not rely on it." Do not hand such a statement to a holder. Check the wallet and the period.

Select "Download CSV", "Download XLSX" or "Download PDF", one button for each format the statement is available in. The file name carries the wallet and the period.

## Set the statement policy [#set-the-statement-policy]

On **Statement policy**, which applies to every statement the organisation produces:

1. Choose the **Cadence**: "Daily", "Weekly", "Monthly" or "Quarterly". After each period of that length closes, the platform produces a scheduled statement for every holder of the organisation's assets.
2. Under **Sections**, tick what a statement holds: "Positions", "Portfolio", "Movements", "Profit and loss", "Fees", "Deposits and withdrawals" and "Corporate actions". Choose at least one section.
3. Under **Formats**, tick "CSV", "Excel workbook" and "PDF" as needed. Choose at least one format. "Excel workbook" downloads with "Download XLSX".
4. Enter a **Reason (optional)** if you want one recorded. It is recorded in the audit trail with the change, and takes up to 1,000 characters.
5. Select **Save policy**. The button is unavailable until a section and a format are ticked and something changed. The Console confirms with "Statement policy saved".

A change to the policy is recorded in [Audit trail](https://docs.settlemint.com/docs/console/reporting/audit-trail) as a change to the **Statement policy**, with the earlier and the new values.

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

- A statement was produced: the **Generated statement** card shows the wallet, the period and the formats you expect, and the "Reconciled" badge.
- The policy was saved: "Statement policy saved" appears beside **Save policy**, and after you reload the screen the "Cadence", "Sections" and "Formats" show your choices.

## Troubleshooting [#troubleshooting]

| What you see | What it means and what to do |
| --- | --- |
| "Statements are managed by organisation owners and platform administrators" | You are neither an organisation owner nor a platform administrator. Ask one to change the policy or generate a statement. |
| The screen shows only its title | The deployment's **Reporting and finance operations** module does not allow changes, so neither card is offered. Ask the platform operator. |
| **This statement is incomplete** | The balances do not reconcile for at least one security. See [Read and download the result](#read-and-download-the-result). |
| **The statement policy could not be loaded** | The policy card could not read the current policy. Statements already produced are unaffected. Use the control to try again, or refresh the screen. |
| **Save policy** is unavailable | Either no section or no format is ticked, or nothing changed since the last save. |
| **The statement is too large to produce** | The range holds more than 120,000 rows. Choose a shorter range and generate again. Nothing was stored. |
| A generate or download request fails with a message | The Console shows the platform's reason. Read it, correct the wallet or the dates, and try again. |

## API routes [#api-routes]

The two cards use these routes of the Platform API, which the [investor statements guide](https://docs.settlemint.com/docs/api-reference/guides/investor-statements) describes. A caller can also generate a statement for a wallet they hold without the owner or platform administrator role:

- `GET /api/v2/reporting/statements/policy` and `PUT /api/v2/reporting/statements/policy` read and change the policy.
- `POST /api/v2/reporting/statements` generates a statement, and `GET /api/v2/reporting/statements` lists them.
- `GET /api/v2/reporting/statements/{statementId}/download` returns a statement in one format.


# Backup and disaster recovery

Source: https://docs.settlemint.com/docs/deployment/backup-recovery
Who owns each part of DALP recovery: what is stateful, what the charts back up, point-in-time recovery, restore order, failover, and what sets RTO and RPO.

DALP's Helm charts can schedule backups of Kubernetes resources and volumes through Velero, a Kubernetes backup tool. Managed databases and object stores need their own backup and recovery plans, and so do the secrets that decrypt the data. DALP publishes no recovery time objective (RTO, how long until service returns) and no recovery point objective (RPO, how much recent data a recovery may lose). Those figures come from the services you choose, the schedules you set and the restores you rehearse. Configure the backup paths before production and test a restore in an isolated environment.

In an incident, go to [Restoring a whole instance](#restoring-a-whole-instance). To check that your backups are usable, go to [Verify a backup is usable](#verify-a-backup-is-usable).

## Who owns what [#who-owns-what]

The charts run the platform and give you the switches for backup. Your team and your service providers own the recovery plan around them.

This split applies when your team operates the instance. When SettleMint hosts or operates it ([Hosting and access](https://docs.settlemint.com/docs/deployment/hosting-and-access)), your service agreement sets who carries each item in the last column. What the charts provide does not change.

| Area | The DALP charts and platform provide | You own |
| --- | --- | --- |
| Platform pods | Separate Deployments per role, with autoscaled api, runner and Console pods, fixed pairs of serving and rebuild indexer pods, disruption budgets and spread rules ([Topologies](https://docs.settlemint.com/docs/deployment/topologies#high-availability-by-component)) | Node capacity across failure domains, cluster upgrades, registry access |
| PostgreSQL | A connection pooler in front of the database you supply | Replication, failover, backups, point-in-time recovery, retention and encryption of the managed service |
| Redis | Pods that keep serving from an in-process cache while Redis is away | Availability of the Redis service you supply |
| Object storage | Reads and writes through the configured provider | Versioning, replication and backup of the bucket |
| Cluster resources and volumes | A Velero schedule and storage location, rendered when you turn on the `dalp` chart's `backup` block | A running Velero server, a backup bucket outside the failure domain, the retention window, a tested restore |
| Ledger networks | Endpoint pools with health-scored failover | The nodes or the provider contracts behind each endpoint, at least two endpoints per network, an archive-capable endpoint for rebuilds |
| Secrets and keys | A refusal to start without the encryption master password | Storing the master password and the session secret in a secret manager, keeping the governance domain scope in your values file, holding signer credentials where the signer reads them, keeping the custodian credential identity key and its key ID with your other secrets, and backup and replication of the secret manager that holds signer keys when `secretManager.provider` is not `local` |
| Objectives and drills | [Alerts in the observability chart](https://docs.settlemint.com/docs/deployment/observability#alerts-that-show-a-recovery-risk) for backup failure, database health, indexer ownership and ledger endpoint selection, and a per-chain indexing lag gauge | Setting the RTO and RPO per data class, and running the recovery drill |

## What is stateful [#what-is-stateful]

Platform pods keep no durable state of their own: caches and in-flight work in a pod are lost when it stops. Everything that must survive a failure sits in one of these stores.

| Store | What it holds | If you lose it | Recovered from |
| --- | --- | --- | --- |
| PostgreSQL | Platform state, workflow journals and the indexed read models. Off-chain records such as approvals, off-chain identity records and workflow state exist only here. With `secretManager.provider` at its default of `local`, the encrypted application secrets, including `local` signer keys, are here too | Off-chain records are gone, and so are the signer keys when the secret manager is `local` | Your database provider's backup, point-in-time recovery or replica promotion |
| Indexed read models (inside PostgreSQL) | Typed business data that the indexer decodes from chain events | The indexer rebuilds them from the ledger when a rebuild is declared or requested, and the rebuild needs an archive-capable endpoint | The database restore plus catch-up. The indexer can also index again from the chain's start block, which a release declares or an operator requests |
| Redis | Cache and change notifications, not a system of record | Service degrades but continues. Pods serve from their in-process tier, and shared cache updates and change notifications stop until Redis returns | Nothing to restore |
| Object storage | Documents and assets that the Platform API serves, and KYC documents uploaded through the current API, which are sealed under the master password | The files are gone unless your provider kept versions | Your storage provider's versioning or replication |
| Ledger networks | On-chain state | Not DALP's to lose. The network operators or your node provider keep it, unless you run an in-cluster test network. Its node volumes are backed up only when they sit in a scheduled namespace and carry the schedule's label | The network itself |
| Secrets and keys | The encryption master password, the session secret, the custodian credential identity key and its key ID, and the governance domain scope, the name that scopes the signing of governance ballots. Signing keys sit in the application secrets, in the secret manager that `secretManager.provider` names, or with your custody provider when `signer.provider` is `dfns`, `fireblocks`, `luna`, `ripple` or `utila` | Without the master password, encrypted rows stay unreadable, because a new password cannot decrypt data sealed under a lost one. KYC documents uploaded through the current API are sealed the same way, so a restored bucket without the password cannot be read. Documents that arrived through the frozen `/api/v1` upload are stored as uploaded. Changing the session secret (`BETTER_AUTH_SECRET`) without its rotation procedure can break access, a changed governance domain scope invalidates the ballots signed under the old name, and a changed custodian credential identity key leaves stored credential identities incomparable until the backfill re-hashes them | Your secret manager for the master password and session secret, and your values file for the scope. Signing keys come from the PostgreSQL restore when `secretManager.provider` is `local`, from your secret manager when it is `aws`, `gcp`, `azure` or `vault`, or from your custody provider |
| Observability data | Logs, traces and metrics | Investigation history is gone | Not needed to restore service. The [observability stack](https://docs.settlemint.com/docs/deployment/install/observability-stack) sets its retention |

## What gets backed up, and what does not [#what-gets-backed-up-and-what-does-not]

When you turn on the `dalp` chart's `backup` block, the charts back up what runs inside your Kubernetes cluster through Velero, the Kubernetes-native backup tool they drive. A service outside the cluster, such as your PostgreSQL, Redis or object storage, backs up through its own mechanism, not through DALP. [Prerequisites](https://docs.settlemint.com/docs/deployment/prerequisites) lists a tested backup and restore for PostgreSQL and object storage as a go-live item.

| What | Backed up by | How |
| --- | --- | --- |
| Kubernetes resources and volumes in the release namespace, by default | The `dalp` chart's Velero schedule | Every labelled resource, with its volumes copied by Velero's file-level backup engine (Kopia unless your Velero server selects another uploader), once a day by default. `backup.namespaces.additional` widens the schedule to more namespaces |
| PostgreSQL (a managed service is the recommended production path) | Your database provider | Not orchestrated by these charts |
| Redis | Your provider, if it offers one | Not orchestrated by these charts. Redis here holds cache and change-notification state, not a system of record |
| Object storage | Your storage provider's versioning or replication | Not orchestrated by these charts |

The schedule runs no Velero backup hook, so a Velero copy of a database volume is a crash-consistent file-system copy, not a `pg_dump` or an application-quiesced snapshot. If you run PostgreSQL inside the cluster, use a database-native backup and verify recovery for production data.

[Figure] Cluster resources back up through Velero. Services outside the cluster back up through their own mechanism. Two backup paths split by who owns the data. Inside the cluster, the DALP chart's own Velero schedule backs up Kubernetes resources and persistent volumes in the release namespace by default, widened by backup.namespaces.additional, as a file-system copy. No database-aware hook is configured, so a volume backup of a database you run in the cluster is crash-consistent rather than application-consistent. Outside the cluster, a PostgreSQL, Redis or object storage service that you supply backs up through its own provider mechanism entirely, and none of it is orchestrated by these charts. Every cluster backup lands in the bucket that backup.storage names. The shipped default endpoint is an in-cluster address, so set backup.storage to a bucket you supply before production. On the DALP chart's own schedule, only resources still carrying the default kots.io/app-slug label fall inside that backup's scope, and a resource that loses the label drops out silently, with no failure or alert. Labels: Two backup paths, split by who owns the data; What gets backed up, by whom; Inside the cluster; The DALP chart's Velero schedule backs this up; Kubernetes resources; In the release namespace, by default; Persistent volumes; File-system backup, not DB-aware; Datastore volumes you run here; Only if labelled and in scope; Crash-consistent, not app-aware; No pg_dump-style hook runs; Outside the cluster; The service's own mechanism; PostgreSQL you supply; Provider's own snapshots; Redis you supply; Provider's mechanism, if any; Object storage you supply; Provider versioning/replication; Not orchestrated by these charts; See Prerequisites for the checklist; An S3-compatible bucket you point the chart at; Where a cluster backup lands; The shipped default endpoint is an in-cluster address; Set backup.storage to your own bucket before production; Only the chart's own app-slug label, by default; The DALP chart's label selector; A relabelled or unlabelled resource drops out silently; No alert fires when scope shrinks this way.

The `dalp` chart's Velero schedule backs up the release namespace, while PostgreSQL, Redis and object storage that you
supply back up through their own providers.

## How the backup block works [#how-the-backup-block-works]

The `dalp` chart never deploys a Velero server, and it is the one chart that decides what gets backed up and where. Its `backup` block, off by default, creates the `BackupStorageLocation` and `Schedule`. These custom resources need a Velero server that you run, for example an installation of OpenShift API for Data Protection (OADP) or Velero itself. Enabling the block backs up nothing until that server runs. Velero reconciles only its own namespace. The chart renders these resources in the release namespace unless you set `backup.veleroNamespace` to the Velero server's namespace, for example `openshift-adp` for OADP. An `existingSecret` you name must live in that same namespace. A workload identity (IRSA, Azure managed identity, GCP workload identity) takes effect once you bind it to the Velero server's service account, plus whatever pod settings your provider's Velero plugin documents. The shipped storage defaults are for development: the endpoint is an in-cluster address and `backup.storage.s3.insecureSkipTLSVerify` is `true`. Set both before you enable the block, as [Decisions to make before you need a restore](#decisions-to-make-before-you-need-a-restore) describes. What the block does with the credentials `Secret` depends on what you set.

| You set | The chart creates |
| --- | --- |
| `backup.storage.aws.useIRSA`, `azure.useManagedIdentity`, or `gcp.useWorkloadIdentity` | No `Secret`, and no credential reference on the `BackupStorageLocation` |
| `backup.storage.s3.existingSecret` (or the equivalent field for your provider) | No `Secret`. The `BackupStorageLocation` references the one you already manage |
| `accessKeyId` and `secretAccessKey` inline (`storageAccountKey` for Azure, not offered for GCP) | The `Secret`, populated from those values |
| None of these, the shipped default | Nothing: the render fails and names the missing field, so no location ever points at a `Secret` that does not exist |

## What the default schedule captures [#what-the-default-schedule-captures]

These are the `dalp` chart's own `backup.*` defaults.

| Setting | Default | What it means |
| --- | --- | --- |
| `backup.schedule.cron` | `0 2 * * *` | Daily, at 02:00 |
| `backup.retention.days` | `30` | Sets the backup's TTL to 720 hours. Velero deletes the recovery point, and the objects it wrote, once the TTL expires |
| `backup.includeAllPVCs` | `true` | Turns on `defaultVolumesToFsBackup`, the file-system backup mode, for every included volume |
| `backup.labelSelector.matchLabels` | `kots.io/app-slug: settlemint-dalp` | A packaging label that the `dapp`, `dapi`, `blockscout`, `docs` and `investor-portal` charts set on their resources, so the default selector matches them without extra configuration |
| Cluster-level resources | Excluded | `includeClusterResources` is hardcoded false, so the schedule only ever backs up namespaced resources |
| Excluded resource types | `events`, `events.events.k8s.io` | Hardcoded, not configurable |
| Storage location name | `<fullname>` plus a fixed suffix | The suffix does not change with the provider, so an Azure- or GCP-backed location keeps the same resource name pattern. Find it with `kubectl get backupstoragelocations.velero.io` |
| Schedule name | `<fullname>-daily` | The name to look for with `kubectl get schedules.velero.io` |

## Point-in-time recovery [#point-in-time-recovery]

Point-in-time recovery returns a database to a chosen moment between two backups by replaying its write-ahead log. The DALP charts do not configure it. The Velero schedule copies each volume's files once a day by default, so its recovery points are the schedule's run times and not arbitrary moments.

For production, point-in-time recovery is a feature of your managed PostgreSQL service. Ask the provider for three answers and record them in the database's recovery plan:

- The retention window, meaning how far back you can restore.
- The finest restore granularity.
- Whether a restore creates a new instance, which decides how you repoint the platform to it.

A restore to an earlier moment removes the off-chain records written after it. Whatever reached the ledger after that moment stays on the ledger. With the default `local` secret manager, a signer key or secret created after the restore point is lost with it, and the platform can no longer sign for the on-chain assets or roles that key controls. The indexer resumes from the position stored in the restored database and reads forward from there. Compare restored records with the ledger before you reopen traffic.

## Decisions to make before you need a restore [#decisions-to-make-before-you-need-a-restore]

Decide your storage target and who owns its credentials. `backup.storage.provider` accepts `s3`, `aws`, `azure`, or `gcp`. The shipped default endpoint is an in-cluster address, and the default `s3` location ships with `backup.storage.s3.insecureSkipTLSVerify` set to `true`, so point it at a bucket you supply and set that value to `false`. Store production recovery points outside the failure domain they must recover from. The chart creates no inline credentials secret for GCP. Either supply `backup.storage.gcp.existingSecret` or set `backup.storage.gcp.useWorkloadIdentity` and skip the secret entirely.

Decide your retention window from your compliance or evidentiary needs. The 30-day default TTL is the only retention control. Velero keeps no minimum count of backups once older ones expire. If a regulator or an internal policy expects a longer recovery window, raise `retention.days`. Do not assume a floor exists underneath it.

Decide whether the default label scope covers what you need backed up. A resource that never carried `kots.io/app-slug: settlemint-dalp`, or that loses it later, silently falls outside the schedule. The schedule keeps completing successfully and backs up less than you expect. The `pgbouncer` and `postgres-exporter` subcharts are on by default and do not carry the label. The umbrella chart's own resources, including the shared application environment Secret that holds the encryption master password and the session secret, carry it only when you add `kots.io/app-slug: settlemint-dalp` to `global.labels` on the release. Adding that label puts the Secret, and with it the master password, in the backup bucket. Without it, a Velero-only restore needs a Helm upgrade to recreate that Secret from your secret manager. Confirm the scope with `kubectl get all,pvc,configmap,secret -l kots.io/app-slug=settlemint-dalp -n <namespace>`, run the same command without the label, and compare the two lists against what you expect to matter in a restore.

Decide how each datastore fails over and recovers. You supply PostgreSQL, Redis and object storage, so a restore and a failover promise only what your providers promise. See [Failing over](#failing-over).

Confirm the backup alerts reach someone. Three Velero alert rules ship in the observability stack, and all three default to `warning` severity, not `critical`. They fire only after you switch on alerting in the [observability stack](https://docs.settlemint.com/docs/deployment/install/observability-stack#alert-rules-are-a-deliberate-second-step) and only when the Velero server's metrics are scraped. Until then, nothing alerts on a failed backup.

| Alert | Condition | For |
| --- | --- | --- |
| `VeleroBackupFailure` | A backup failed in the last hour | 5 minutes |
| `VeleroBackupPartialFailure` | A backup partially failed in the last hour | 5 minutes |
| `VeleroBackupStale` | No successful backup for a schedule in over 24 hours | 15 minutes |

A stale schedule can run silently broken for more than a day before `VeleroBackupStale` fires, because the rule waits for 24 hours without a success and then holds for 15 minutes. If your operating process needs faster notice than that, do not assume the default severity routes to an on-call page. Confirm it does, or raise it.

## Verify a backup is usable [#verify-a-backup-is-usable]

The Grafana dashboard **Cluster · Backups & Policy** (uid `backups-policy`) gives you the automated signal: its "Backup failures" panel and "Last successful backup" panel tell you a schedule ran and did not error, and the three Velero alerts tell you when a running schedule fails. The alerts read metrics from the Velero server. They stay silent when no Velero server runs, when its metrics are not scraped, or when a schedule has never completed a backup. Neither the dashboard nor the alerts tell you the data that came back is usable. Only a test restore does that.

Run a test restore on a fixed schedule that your recovery plan names, and at least before your first production go-live and after any change to `backup.storage`, `backup.labelSelector`, or `backup.schedule`. Restore into a namespace other than the one the backup came from, so you can inspect the result without touching a live workload. Confirm the resource and volume counts match what you expected. For anything that held database data, confirm the application starts cleanly against it, rather than only checking that files arrived. A restored environment Secret points at your production database, cache and ledger endpoints, and with the default labels the restore lacks that Secret and the pooler until a Helm upgrade recreates them. Before any restored pod starts, apply the isolation in [Rehearse a recovery](#rehearse-a-recovery), step 1. Delete the test restore's namespace once you have confirmed it, so a stale test copy does not linger as a second, unmanaged instance.

## Restoring from a backup [#restoring-from-a-backup]

1. Confirm which backup you are restoring from. A backup's phase must read `Completed`, not `PartiallyFailed`, before you trust it as your restore source. A partial failure means some resources or volumes did not make it in.

   ```bash
   kubectl get backups.velero.io -n <velero-namespace>
   ```

   This lists every backup in the namespace, including those the `<fullname>-daily` schedule created. `<velero-namespace>` is the release namespace unless you set `backup.veleroNamespace`.

2. Decide your target before you create the restore. Restoring into the same namespace where the original resources still exist behaves differently from restoring into an empty namespace or a new cluster. Existing-resource handling depends on Velero's configured restore policy. Do not assume a restore overwrites live resources. For a test restore, set `spec.namespaceMapping` on the `Restore` (step 3) to restore into an empty namespace instead of overwriting anything live.
3. Create the restore from the chosen backup by applying a `Restore` resource, then watch its phase rather than assuming it finished because the command returned.

   ```yaml
   apiVersion: velero.io/v1
   kind: Restore
   metadata:
     name: <restore-name>
     namespace: <velero-namespace>
   spec:
     backupName: <backup-name>
     namespaceMapping:
       <original-namespace>: <target-namespace>
   ```

   ```bash
   kubectl get restores.velero.io <restore-name> -n <velero-namespace> -w
   ```

4. Wait for volume restores to finish separately from the resources that reference them. The default schedule backs up volumes at the file-system level, so a restored pod can stay pending after its other resources already exist, while its volume's own restore is still copying data in the background. Watch the `PodVolumeRestore` resources Velero creates for this restore, not only the pod's own status:

   ```bash
   kubectl get podvolumerestores.velero.io -n <velero-namespace>
   ```

5. Confirm what came back before you call the restore done. A `Completed` restore proves Velero moved the bytes it had. It does not prove the data is transactionally consistent, since no backup hook runs against a database volume before the copy is taken. Start the application against the restored data and confirm it comes up cleanly, as [Verify a backup is usable](#verify-a-backup-is-usable) describes.

## Restoring a whole instance [#restoring-a-whole-instance]

A Velero restore brings back cluster resources and volumes. A full recovery after losing a cluster or a region also needs the datastores, the secrets and the ledger connection. Before step 1, confirm that the lost instance is stopped, so that two instances never act on the same ledger at once. Restore in this order. Steps 1 and 2 gate the platform, and steps 3 and 4 can run beside step 2. Keep traffic closed until step 8.

1. Recreate the secrets. Take `ENCRYPTION_MASTER_PASSWORD` and `BETTER_AUTH_SECRET` from your secret manager, and set `DALP_GOVERNANCE_DOMAIN_SCOPE` from your recorded values file, all to the values the lost instance used, together with `CUSTODY_CREDENTIAL_IDENTITY_KEY` and `CUSTODY_CREDENTIAL_IDENTITY_KEY_ID` ([Custody credential identity key](https://docs.settlemint.com/docs/deployment/install/values-secrets#custody-credential-identity-key)). The platform refuses to start without the master password, a different password cannot decrypt the restored rows, a changed governance domain scope invalidates every ballot signed under the old name, and a changed custodian credential identity key leaves stored credential identities incomparable until the backfill re-hashes them. Restore the credentials of a custody provider from the same source. When `secretManager.provider` is not `local`, restore that store to the same point as PostgreSQL. [Values and secrets](https://docs.settlemint.com/docs/deployment/install/values-secrets#encryption-at-rest) describes each value.
2. Restore PostgreSQL through your provider, either from a backup or to a chosen moment ([Point-in-time recovery](#point-in-time-recovery)). Point `global.datastores` at the restored instance. The network catalogue and the RPC endpoint pools are in this database, so they return with it. Their credentials decrypt with the master password from step 1.
3. Restore object storage through your provider, from its versions or its replica.
4. Provide a Redis service. There is nothing to restore, because the platform treats Redis as a cache and notification transport.
5. Install or upgrade the `dalp` chart. With the default hook type, the migration Job runs first, and the application Deployments update only after it succeeds. See [Upgrades and migrations](https://docs.settlemint.com/docs/deployment/upgrades-migrations).
6. Confirm that every network's endpoint pool is reachable from the new site, and that each network still has at least two endpoints.
7. Watch the indexer catch up, as [Catch-up and re-index time](#catch-up-and-re-index-time) describes. Confirm that the application starts cleanly against the restored data, that the Platform status screen shows no stalled workflows, and that the newest restored records agree with the ledger.
8. Switch DNS, ingress and routing to the recovered site, and reopen traffic.

## Catch-up and re-index time [#catch-up-and-re-index-time]

The platform publishes no figure for how long indexing takes after a restore, because the time depends on your chain and your endpoints. Two cases differ.

After a database restore, the indexer reads only the blocks between the stored position and the chain head. Divide that gap in blocks by the rate at which the lag shrinks to size the catch-up. The Console's **Platform status** screen shows how many chains are in sync and the delay of the furthest-behind chain, its Indexing detail view shows the state per network, and the indexer exports the `dalp_didx_watermark_lag_blocks` and `dalp_indexer_serving_lag_blocks` gauges. [Ledger indexing stalled](https://docs.settlemint.com/docs/deployment/runbooks/ledger-indexing-stalled) explains how to tell catch-up from a stall.

A rebuild is longer. A release that changes how earlier data is recorded declares one, and an operator can request one, as [Ledger indexing stalled](https://docs.settlemint.com/docs/deployment/runbooks/ledger-indexing-stalled) describes for a chain generation mismatch. The platform then indexes each network again from its start block into a new dataset while the current one keeps serving. Rebuild time grows with the length of the chain history, the volume of events and your provider's rate limits. The rebuild needs an archive-capable endpoint, because it asks for state at old blocks. Reads keep using the current dataset, and a read that needs data that is not available yet can receive a retryable rebuilding response. Measure a rebuild on your own data before you rely on it in a recovery plan.

## Failing over [#failing-over]

Failover splits into three jobs, because they answer to three different owners: compute, the stateful layer and the ledger connection.

Compute failover is a reschedule, because every Platform API pod and the Console are stateless. Recovering compute also requires reachable datastores, secrets, registry access, network endpoints, and routing in the target environment. Validate those dependencies before sending traffic there.

The stateful layer is where failover is decided, and it depends entirely on the services you supply. Failover for PostgreSQL, Redis and object storage is your provider's own replication and promotion mechanism, not something these charts orchestrate. A provider running a live standby promotes it, and your recovery point tracks that standby's replication lag, not the age of your last Velero backup.

A datastore with no live standby has nothing to fail over to. A cluster or regional loss then means restoring your most recent backup into new infrastructure, not promoting a replica. Recovery reaches the latest usable backup. Successful daily backups can leave a 24-hour gap, and missed or unusable backups make the gap longer. Choose services with a replica or standby for production.

Failover to the ledger is a third job, and the platform does it for you when a network has more than one endpoint. The platform scores each endpoint in a network's pool on its error rate, its latency, how far it lags behind the chain head and how far it lags behind finality. Each endpoint also carries a weight that a platform administrator sets in the pool. The platform then routes as follows:

- It leaves out an endpoint whose head lag passes 50 blocks or whose score falls below 0.25.
- It sends calls to the healthy endpoint with the highest weight, and prefers the better score among endpoints of equal weight.
- It retries a transient error with backoff and moves away from a dead endpoint.
- If every reachable endpoint is excluded, it keeps calling the excluded ones rather than failing.
- It keeps the serving endpoint when the best rival has the same weight, the last switch was under 60 seconds ago and the rival scores less than 0.1 higher. This stops two healthy endpoints from trading places. An endpoint that falls out of the healthy set is replaced without waiting for that interval.
- If no endpoint can serve a call, the caller receives an error.

The limits and the switching values are defaults. A platform administrator edits the pool in the Console under [Networks](https://docs.settlemint.com/docs/console/platform-admin/networks), and the change applies without a restart. Health-based selection needs fresh scores. When the platform holds no usable score for any endpoint of a network, selection is not active for that network and the platform logs it as degraded. It then chooses endpoints in their configured order and stops excluding unhealthy ones, and after 15 minutes the `RpcHealthSelectionDisabled` alert fires. Treat that alert as degraded failover until scores return. A network with a single endpoint has nothing to fail over to.

## What sets your RTO and RPO [#what-sets-your-rto-and-rpo]

Your RPO is the longest span of recent data you accept losing, stated as a time. Your RTO is the longest outage you accept before the platform serves traffic again. DALP states neither as a number, and no figure on this page is a commitment. Each one depends on choices that sit with different owners, and the weakest store sets the objective for the platform as a whole.

| Part of the objective | What moves it | Who sets it |
| --- | --- | --- |
| RPO for PostgreSQL | The provider's backup interval, its point-in-time retention, and the lag of a live standby. With a standby, the recovery point tracks the standby's replication lag | You, through your database provider's plan |
| RPO for cluster volumes | `backup.schedule.cron` (daily at 02:00 by default). A failed run lengthens the gap | You, in the `dalp` chart's values |
| RPO for object storage | The provider's versioning and replication settings | You, through your storage provider |
| RTO for the data stores | How long the provider takes to restore a database or promote a standby, and how long a volume restore takes to copy data back | Your providers, and your own measurement |
| RTO for the platform | The migration Job's run time, which the chart caps at 10 minutes by default (`dapp.migrator.timeout`), pod start-up, and node capacity in the recovery site | You, in the chart's values and the cluster |
| RTO for ledger data | The indexer's catch-up, or a rebuild, and the speed and rate limits of your endpoints | You, through your endpoints and chain history |
| RTO for traffic | DNS, ingress and routing in the recovery site | You |

Set the objectives per data class with your risk owner. Off-chain records and documents have no other copy, and usually need the tightest RPO. Indexed read models can be rebuilt from the ledger, so a looser RPO costs time and not data. Retention (`backup.retention.days`, 30 by default) sets how far back you can restore, and does not set the RPO. A provider's published service levels apply to that provider's service alone and do not add up to an objective for the platform as a whole.

## Rehearse a recovery [#rehearse-a-recovery]

DALP ships no disaster recovery test tool, so you schedule and record the drill. Run it on the occasions that [Verify a backup is usable](#verify-a-backup-is-usable) lists, and after a change of database or object storage provider.

1. Build an isolated target. The target holds production's master password, workflow journals and, with the default secret manager, signer keys, and its restored endpoint pools point at production endpoints.
   - Use a separate namespace or cluster, and never the namespace that serves production.
   - Before the pods start, block all egress except to ledger endpoints that serve reads only. That includes your custody provider and webhook receivers. A `local` signer signs inside the platform, so blocking the custody provider alone does not stop it.
   - Give the target its own `DALP_GOVERNANCE_DOMAIN_SCOPE`, because the chart's values say never to copy the scope between installs. Ballots signed under the production scope then stop verifying in the target, which a drill does not need.
   - Copy `CUSTODY_CREDENTIAL_IDENTITY_KEY`, although the values give the same rule for it, so the restored custody credentials stay readable. That is one more reason to keep the target isolated and delete it in step 6.
   - After the pods start, replace each pool in the Console under [Networks](https://docs.settlemint.com/docs/console/platform-admin/networks) with endpoints that serve reads only and refuse transaction submission, before you time the indexer catch-up. The network catalogue in the database overrides the deployment values.
2. Note the moment at which you simulate the failure. Restore PostgreSQL, object storage and the secrets from the sources your plan names, following steps 1 to 7 of [Restoring a whole instance](#restoring-a-whole-instance), apart from the governance domain scope in step 1. Run the checks in step 5 below before any routing change, and simulate step 8 without moving production traffic.
3. Time the drill from the moment you noted to the point where the target could serve traffic. Record each stage as well: the secrets, the database restore, the object storage restore, the migration Job, the pods becoming ready and the indexer's lag reaching zero. Stages that run beside each other count once. The result is your measured RTO. If your drill skips a stage, say which one.
4. Compare the newest record in the restored instance with production at the moment you noted in step 2. The difference is your measured RPO.
5. Run the checks in [Verify a backup is usable](#verify-a-backup-is-usable) and confirm that the application starts against the restored data.
6. Record the timings and the gaps against the objectives, delete the target, and fix what the drill exposed before the next one.

## What deletion removes [#what-deletion-removes]

Once `retention.days` elapses, 30 days by default, Velero deletes that recovery point and the objects it wrote from your bucket, with no undo. Deleting the bucket a `BackupStorageLocation` points at destroys every recovery point that location owns, not only the newest one.

Measure recovery time with your own volumes. The chart does not guarantee a restore duration.

For restores into a namespace with existing resources, check the behaviour of your installed Velero version and its resource policy first. An isolated test target avoids relying on overwrite behaviour.

## Frequently asked questions [#frequently-asked-questions]

### Does a restore bring back cluster-scoped resources like ClusterRoles?

No. `includeClusterResources` is hardcoded false in the default schedule, so nothing cluster-scoped ever enters the backup, and a restore has nothing to bring back for it. If your workload depends on a ClusterRole, a ClusterRoleBinding, or another cluster-scoped object, reapply it separately, from your chart's rendered manifests or your own record of it, before or after the restore runs.

### Does raising `backup.retention.days` extend the life of backups that already exist?

No. Velero sets a backup's time-to-live from `retention.days` at the moment that backup is created, not on an ongoing basis, so a change to the value only lengthens the life of backups taken afterwards. A recovery point already deleted stays deleted, and one still alive under a shorter TTL from before your change keeps that original TTL rather than adopting the new one.

### If I change `backup.storage.provider`, do my existing backups move with it?

No. The `dalp` chart's `BackupStorageLocation` keeps one fixed name regardless of provider, and changing `backup.storage.provider` repoints that same location at a different bucket or account rather than copying objects between them. Your existing recovery points stay in the old bucket and become unreachable through this location once you repoint it, so migrate or archive anything you still need before you switch.


# Deposit funding instructions

Source: https://docs.settlemint.com/docs/deployment/deposit-funding-instructions
How an operator makes deposits possible: turn the module on, enable coins on the custody gateway add-on and give clients the gateway address to send to.

A DALP Instance tells a client where to send a deposit through the client's own custody gateway. The gateway belongs to one client identity and has an address. The client sends coins to that address, and the gateway records the deposit, screens it and mints receipts. No deployment setting lists accepted coins, and no route watches a wallet for deposits. The operator decides what is accepted in the Console.

## What must be in place [#what-must-be-in-place]

| Requirement | Where it comes from |
| --- | --- |
| The "Self-custody" module is on | The `features.custodyOps` setting, as [Switch application layers on or off](https://docs.settlemint.com/docs/deployment/install/values-secrets#switch-application-layers-on-or-off) describes. With it off, the gateway routes answer `DALP-20531`. |
| The custody gateway add-on exists | An owner or platform admin sets it up. See [Set up the custody gateway](https://docs.settlemint.com/docs/console/asset-lifecycle/custody-gateway-setup). |
| A keeper service wallet | It records deposits and pays withdrawals. |
| A screener service wallet | It clears or refuses quarantined deposits. |
| At least one enabled coin and one profile | They define what a gateway accepts and the claim a client needs. |
| A gateway for the client | [Create a client gateway](https://docs.settlemint.com/docs/console/asset-lifecycle/custody-gateway-create). |

## Which coins are accepted [#which-coins-are-accepted]

A coin is accepted when it is enabled on the add-on. A deposit of any other coin lands on the gateway's "Unsupported" list and is returned, recovered or ignored by an operator. See [Review deposits and withdrawals](https://docs.settlemint.com/docs/console/asset-lifecycle/custody-gateway-review#handle-coins-the-gateway-does-not-accept).

A coin can be set to wait for custody. The gateway then mints the receipts to the client and holds them until the custodian accepts the coins the gateway forwarded. A deposit in that state rests at `Awaiting custody`.

## Where a client sends a deposit [#where-a-client-sends-a-deposit]

A client sees the gateway address in the Deposit dialog of the Investor portal, and reads it through `GET /api/v2/addons/custody-gateways/gateways/mine`. A gateway has no client wallet when it is created. A gateway manager binds one before the client's own routes work, as the [custody gateway API](https://docs.settlemint.com/docs/api-reference/guides/custody-gateway-api#bind-the-client-wallet) describes.

## What happens to a deposit [#what-happens-to-a-deposit]

Every deposit enters a screening stage first. The screener clears it, the gateway mints the receipts and the coins move on. [Deposit and withdrawal stages](https://docs.settlemint.com/docs/api-reference/guides/custody-gateway-stages) lists each stage, who moves it and the time limits.

## Related pages [#related-pages]

- [Custody gateway](https://docs.settlemint.com/docs/concepts/custody-and-signing/custody-gateway)
- [Wallet deposits and withdrawals in the Investor portal](https://docs.settlemint.com/docs/concepts/operating/investor-portal-wallet-transfers)
- [Custody settings in the Console](https://docs.settlemint.com/docs/console/organisation-settings/custody)


# Exit and data portability

Source: https://docs.settlemint.com/docs/deployment/exit-and-data-portability
Where a DALP instance keeps each kind of data, which exports it provides, what stays on your network, and how source access is agreed.

A DALP Instance keeps asset state on your ledger networks, operating records in the PostgreSQL database and object storage of its cluster, and signing keys with a custody provider or in the deployment's secret manager. Each location has its own export path, and the asset contracts keep running on your EVM network after DALP stops. SettleMint distributes the images and charts without source under a commercial licence, and source access or escrow can be agreed in a contract, as [Licence and source access](#licence-and-source-access) states.

## Where each kind of data lives [#where-each-kind-of-data-lives]

| Data | Where it lives | How you access it |
| --- | --- | --- |
| Asset contracts, balances, roles and events | The ledger networks in the instance's [networks](https://docs.settlemint.com/docs/deployment/networks) configuration. The contracts enforce the asset rules when a transaction executes. | Any node of the network, or the Platform API through the index. |
| The index, a PostgreSQL copy of those events that the Platform API reads | PostgreSQL. The index is derived from the network: it is rebuilt from blocks and events, and a chain reorganisation corrects it. See [Ledger Data](https://docs.settlemint.com/docs/concepts/records-and-evidence/ledger-data). | The Platform API and the [exports](#exports-the-platform-provides). |
| Operating records, such as filings and the audit trail | PostgreSQL. | The [exports in this page](#exports-the-platform-provides). For the database itself, your database provider's own export and backup tools. A database dump holds the platform's internal schema, which this documentation does not describe as an interchange format. |
| Files: asset documents, KYC documents, filing files, shareholder lists and investor statements | The object storage provider you configure. | The asset document, filing, KYC document and investor statement [downloads](#exports-the-platform-provides). For the storage itself, your storage provider's tools. |
| Console assistant conversations | PostgreSQL, deleted after `ASSISTANT_TURN_RETENTION_DAYS`, 365 days by default. When the assistant is on, questions and their context also go to OpenRouter. | Not exported. |
| Cache and wake-up messages, which tell a process to re-read state | Redis. It is not a system of record. | Not exported. |
| Signing keys | With the default `local` signer, in the deployment's secret manager. The default `local` secret manager keeps them as encrypted rows in PostgreSQL. The `aws`, `gcp`, `azure` and `vault` managers hold them in that service. With a custody provider, at that provider. | A custody provider's own tools. With the `local` signer and `local` secret manager, your PostgreSQL backups and the master password that decrypts them. With another secret manager, that service's own tools. |

In production, PostgreSQL, Redis and object storage are services you supply and back up. You set PostgreSQL and Redis in `global.datastores` and object storage in `global.dalpApp.config.objectStorage`. [Prerequisites](https://docs.settlemint.com/docs/deployment/prerequisites) lists each dependency and [Backup and disaster recovery](https://docs.settlemint.com/docs/deployment/backup-recovery) covers what DALP backs up and what your providers must back up. If SettleMint operates the cluster for you, the same stores sit in that cluster, and [Hosting and access](https://docs.settlemint.com/docs/deployment/hosting-and-access) explains why cluster access always means data access.

## What you depend on [#what-you-depend-on]

DALP runs from container images and Helm charts under the terms in [Licence and source access](#licence-and-source-access).

| Dependency | What it is |
| --- | --- |
| The DALP platform | The Console, the Platform API and the index, which you run from the images and charts. |
| SettleMint | The images at `ghcr.io`, the chart at `pkg.distribution.settlemint.com`, patch releases and security fixes. Mirror the version you run, because new versions and fixes need continued access. |
| Ledger network | EVM networks that you configure and connect to with your own endpoints. |
| Database | PostgreSQL. |
| Object storage | AWS S3, Google Cloud Storage, Azure Blob Storage, another S3-compatible service or a filesystem path. |
| Cache | Redis. |
| Signing | The `local` signer, or a custody provider you select. |
| Integration surface | The OpenAPI contract at `/api/v2/spec.json`, from which you can generate a client. |

## Exports the platform provides [#exports-the-platform-provides]

Each export is a separate download from the Console or the Platform API, as CSV, XLSX, PDF, JSON, ZIP, XML or the file as uploaded. No single export covers everything: the ledger holds balances and events, the holder register export gives positions at a block, and the audit trail export gives operating history. Asset and KYC documents download one at a time.

| What you export | Format | Where |
| --- | --- | --- |
| Resources the Platform API serves | JSON, except the file downloads in this table | `/api/v2`, with its OpenAPI contract at `/api/v2/spec.json`, and the legacy `/api/v1` that existing clients keep using. |
| The rows of a Console table | CSV or JSON | The table's "Export as CSV" and "Export as JSON" menu items. A table paged by the server fetches every matching row. Some Console pages replace this menu with their own export action, and some remove it. |
| A token's activity | CSV | "Export CSV" on the token's activity table, which exports every event that matches the filters, with times in UTC. The API route is `GET /api/v2/tokens/{assetId}/events/export`. |
| The holder register as at a chosen record block | CSV, XLSX or PDF | "Holder register…" in the holders table's Export menu. The API route is `GET /api/v2/reporting/shareholder-lists/{tokenAddress}/download`. |
| The holder register in the registrar layout | CSV | "Registrar file…" in the same menu, with columns `holderWallet`, `identityReference`, `jurisdiction` and `quantity`. The API route is `GET /api/v2/reporting/shareholder-lists/{tokenAddress}/registrar-file`. |
| Stored shareholder list deliveries | CSV, XLSX and PDF editions | "Issuer deliveries…" in the same menu. A download returns the stored file only after its length and digest match what was recorded. |
| An investor statement | CSV, XLSX or PDF, set by the statement policy | The download button for each format on the Console Statements page, or the statements routes under `/api/v2/reporting/statements`. The default policy produces CSV and PDF. A download link is valid for 15 minutes. |
| A transaction confirmation | CSV or XLSX | The confirmations routes under `/api/v2/reporting/confirmations`. |
| The audit trail for a time range | CSV | "Export" on the Reporting audit trail page, or `GET /api/v2/reporting/trail/export`. |
| The daily transaction report | CSV or XLSX | "Download report" on the Console Daily transactions page, or `POST /api/v2/reporting/daily-transactions`, which returns the file for a range of at most 31 days. |
| The stored files of a filing | CSV, XLSX, ZIP, JSON, XML or PDF, set by the obligation | The [Filings](https://docs.settlemint.com/docs/console/reporting/filings) page. Each part has its own link, valid for 15 minutes. |
| An asset document | The file as uploaded | The document's download action, or `POST /api/v2/tokens/{assetId}/documents/{documentId}/downloads`, which returns a signed link. |
| A KYC document | The file as uploaded | `POST /api/v2/kyc-profile-versions/{versionId}/documents/{documentId}/downloads`, which returns a signed link. |

Filing files expire. A filing keeps its files for the retention class its obligation sets, which is five, seven or ten years from acceptance, or indefinite. The platform erases the files when the period ends, but not while any legal hold on the filing is unreleased, so download any filing you must keep beyond that.

The holder register, registrar file, deliveries, audit trail and daily transaction exports are open to the reporting readers: the system roles `admin`, `auditor`, `complianceManager` and `systemManager`, the organisation owner, and a platform administrator. Downloading the files of a filing needs the organisation owner or a platform administrator. Statements and confirmations cover only the caller's own wallets, whatever the caller's role.

To keep a downstream copy of changes as they happen, register a webhook endpoint. The platform delivers the events that match the endpoint's subscriptions, with retries. See [Webhooks](https://docs.settlemint.com/docs/api-reference/webhooks). To read large result sets through the API, see [Pagination](https://docs.settlemint.com/docs/api-reference/guides/pagination).

## What stays on the ledger network [#what-stays-on-the-ledger-network]

Stopping the platform does not stop the contracts. The asset contracts, their balances and their role assignments remain on the network. The contracts keep enforcing their role checks, and apply the compliance modules to mints and transfers, on every call from any tooling. Forced updates, such as recovery transfers, skip the compliance modules but still require a registered recipient, and a verified one on V2 tokens with a V2 identity registry. The platform's authorisation, wallet verification and signing policy govern only the requests made through the platform.

An exit depends on who controls the keys of the role-holding wallets. A self-custody holder signs with their own wallet. For a managed wallet, the key sits at the custody provider the organisation chose. With the default `local` signer, the keys sit in the deployment's secret manager. The default `local` secret manager stores them as encrypted rows in PostgreSQL, under the master password you generated, so the signing keys in a PostgreSQL backup are readable only with that password.

Store that password with your other secrets for as long as you keep the backups. Data encrypted under a lost password is unreadable. To replace the password, follow the rotation steps in [Values and secrets](https://docs.settlemint.com/docs/deployment/install/values-secrets#encryption-at-rest). See [Security and compliance posture](https://docs.settlemint.com/docs/deployment/security-compliance-posture) for the custody layers.

The network endpoints are yours as well. You supply the RPC or ledger endpoints for each enabled network, so reading the chain needs nothing from SettleMint.

## Steps to leave [#steps-to-leave]

These steps assume you operate the cluster. If SettleMint operates it, SettleMint holds the database, the object storage and the master password, and with the default `local` signer those three hold the signing keys of every platform-managed wallet. Steps 3 and 5 then need SettleMint to deliver a database export, the stored files and the master password, and step 4 removes the platform's ability to sign for your roles. [Cluster access means data access](https://docs.settlemint.com/docs/deployment/hosting-and-access#cluster-access-means-data-access) explains why.

1. Mirror the images and the chart of the version you run into your own registry, so a pod can still reschedule if your access to the published registries ends.
2. Run the [exports](#exports-the-platform-provides) for every record you must keep, starting with filings whose retention period is about to end.
3. Back up PostgreSQL and the object storage, or the filesystem volume if you use one, with your providers' own tools.
4. Confirm who controls each role-holding wallet. For a role you still need on a wallet whose key the platform or a custody provider holds, grant that role to a wallet whose key you hold.
5. Store the master password with your secrets for as long as you keep the PostgreSQL backup from step 3.
6. Point your own tooling at the RPC endpoints of each network.
7. Stop the platform.

## Licence and source access [#licence-and-source-access]

SettleMint distributes DALP as container images and Helm charts under its commercial licence, without the source code. Access to the DALP source code, or escrow of it, can be agreed in a contract with SettleMint.

## Next steps [#next-steps]

- [Backup and disaster recovery](https://docs.settlemint.com/docs/deployment/backup-recovery) for the stores that hold the operating records.
- [Prerequisites](https://docs.settlemint.com/docs/deployment/prerequisites) for the master password, the signer and the object storage choices.
- [Issuer shareholder list](https://docs.settlemint.com/docs/api-reference/guides/issuer-shareholder-list) and [Investor statements](https://docs.settlemint.com/docs/api-reference/guides/investor-statements) for the two export families with their own API guides.


# Fireblocks policy

Source: https://docs.settlemint.com/docs/deployment/fireblocks-policy
The Fireblocks policy rules each DALP vault needs with account abstraction off and on, and what a Fireblocks rule cannot see once account abstraction is on.

A Fireblocks workspace decides whether each DALP signing request runs, waits for approvers, or stops. It decides with its policy, the ordered list of rules Fireblocks calls the Transaction Authorisation Policy. This page lists the rules each DALP vault needs and what a Fireblocks rule cannot see once account abstraction is on.

A wrong policy stops DALP in one of two ways. A missing allow rule blocks every request from a vault. An approval rule on a vault that must sign without a person fails every sponsored operation, for every user, until someone changes the rule. Both appear on the first transaction after the policy changes, so set the policy before you onboard investors and test it with one transfer per mode.

DALP signs in one of two modes. With account abstraction off, each wallet is a Fireblocks vault, and the vault sends its own transactions. With account abstraction on, each wallet is a Smart Wallet, a contract account under ERC-4337. The Fireblocks vault then holds only the wallet's owner key and signs user operations, the signed instructions that the Smart Wallet executes. Two shared vaults sign for every user: the paymaster vault signs the ticket that lets DALP pay gas for an operation, and the bundler vault submits user operations to the chain.

DALP signs as one Fireblocks API user, whose API key and private key it holds, as [Prerequisites](https://docs.settlemint.com/docs/deployment/prerequisites#a-custody-provider-when-signing-leaves-the-platform) lists. Whatever your approval rules do not catch, the allow rule for that API user passes without a person, so your approval rules are the only check between DALP and a signature.

[Figure] With account abstraction off, Fireblocks sees the token call. With it on, Fireblocks sees only signatures over typed data. Two panels compare what a Fireblocks policy can read in each DALP signing mode. With account abstraction off, the investor vault holds the wallet key and sends a contract call to the token contract, filed to a one-time address. Fireblocks reads that call itself, so asset, amount, and destination rules apply to it. With account abstraction on, three vaults take part. The owner vault signs the user operation as a typed message. The paymaster vault signs the sponsorship ticket as a typed message and must allow it without approval. The bundler vault sends the bundle to the entry-point contract as a contract call and must also allow it without approval. The Smart Wallet, a contract and not a Fireblocks vault, then runs the call against the token contract. Fireblocks reads only signatures over typed data, so it cannot apply amount or destination rules, and only the token's compliance rules check the transfer. Labels: Account abstraction off; Investor vault; Holds the key, sends the call; CONTRACT_CALL to a; one-time address; Token contract; Fireblocks reads the call itself:; asset, amount, and destination rules apply; Account abstraction on; Owner vault; TYPED_MESSAGE: user operation; Paymaster vault, no approval; TYPED_MESSAGE: sponsorship ticket; Bundler vault, no approval; CONTRACT_CALL to the entry point; Smart Wallet; A contract, not a Fireblocks vault; Token contract; Fireblocks reads only signatures; and only the token's compliance rules check it.

What a Fireblocks policy can read in each DALP signing mode.

## Rules per vault [#rules-per-vault]

| Mode | Vault | Fireblocks rule type | Settings |
| --- | --- | --- | --- |
| Account abstraction off | Each vault that holds investor tokens | Contract Call | Source: the vault. Asset: the DALP token. Amount: the range that needs approval. Destination type: one-time address. Action: require approval from an approver group with a threshold. |
| Account abstraction off | The same vaults | Transfer | Covers native coin transfers, which have no call data. Use the same source and approval settings. |
| Account abstraction on | Owner vault of each Smart Wallet | Typed Message | Source: the vault. Asset: the chain's base asset. Set the designated signers, the approver group, and its threshold. |
| Account abstraction on | Bundler vault | Contract Call | Source: the vault. Destination type: one-time address. Action: allow without approval. |
| Account abstraction on | Paymaster vault | Typed Message | Source: the vault. Action: allow without approval. |
| Both | Every vault DALP signs from | Rule order | Allow rules for Typed Message and Contract Call for the API user DALP signs as, matched by the [DALP vault tag](#tag-the-dalp-vaults), above the catch-all block rule. |

Each request DALP files reaches the approver with a note that names the operation: the action, the asset or contract, the amount, and the counterparty. Approvers read that note on the request in Fireblocks before they decide. The note starts with the name and symbol of the contract the call reaches, such as `Acme Bond (ACME): mint(...)`, which DALP reads from the contract. DALP writes the note and Fireblocks does not check it, and the contract name is whatever the contract reports, so an approver who must verify a request checks the contract address and the typed data. A request that calls more than one contract, or a contract that has no name, starts with the call. The note ends with the DALP request the signature belongs to, its kind and its id, so an approver can match a sponsorship ticket, a user operation and its bundle to one request.

A call that also sends the chain's coin ends with that amount, such as `depositTo(account=0x…) with 0.04 native`. A list of addresses, numbers or true/false values shows its first three entries and how many more follow. A list of roles shows the role names, and any other list shows its count, such as `[2 items]`. A list that holds a number of more than 32 digits, such as a list of claim topic ids, shows its count. A country code passed as a number in its own argument shows as its two letters and its number, such as `SA (682)`. A country code inside a structure does not read this way: a token created from an instrument template passes its settings as one structure, so its note shows the name, symbol, type and decimals of the token and not its country. DALP cuts the note at 255 characters from the end of the call, so a call that lists addresses can lose its last arguments, such as the country list of a batch registration.

## Rule order decides the outcome [#rule-order-decides-the-outcome]

Fireblocks checks a request against the rules from the top of the policy down, and the first rule that matches decides. A request that matches no rule meets the catch-all block rule at the bottom of every policy, and Fireblocks blocks it.

The API user that DALP signs as needs an allow rule for typed messages and one for contract calls on every vault it signs from. Without the typed message rule, every typed signature from that vault ends blocked by policy, while contract calls from the same vault still pass. A broad allow rule also hides any approval rule below it, because the allow rule matches first. Put the narrow rules at the top: the approval rule for a token first, then the general allow rules. The allow rules for the paymaster and bundler vaults can sit above the approval rules, because each one names its infrastructure vault as the source and so never hides the approval rule of an investor vault.

## With account abstraction on, Fireblocks cannot see amounts [#with-account-abstraction-on-fireblocks-cannot-see-amounts]

The tokens move from the Smart Wallet, a contract. Fireblocks sees only the owner vault's signature over an EIP-712 user operation, the typed data format that wallets use to show a structured message before signing. A Typed Message rule has no amount field and takes no destination limit, so it cannot tell a transfer of 10 tokens from a transfer of 10 million.

DALP does not replace an amount threshold or a destination rule. The token's compliance policy checks each transfer on chain against the compliance modules installed on that token, such as eligibility, jurisdiction, holding and per-transfer approval, whichever wallet sends it. DALP has no per-transfer amount cap. If your risk policy needs approval above an amount, install the transfer approval module on the token, or keep account abstraction off for those wallets. Fireblocks still decides who must approve: a Typed Message rule on the owner vault can name designated signers, an approver group, and a threshold.

One Typed Message rule covers every typed signature from its vault. The same rule gates user operations, token permits, trading venue orders, and governance ballots signed by that owner key, because Fireblocks sees each of them as a typed message. Scope the rule by source vault, and expect its approvers to see all four kinds of request.

## Keep the paymaster and bundler vaults free of approval rules [#keep-the-paymaster-and-bundler-vaults-free-of-approval-rules]

Two vaults sign for every user, not for one investor. The paymaster vault signs a sponsorship ticket for each operation that DALP pays gas for. The vault behind the bundler wallet submits each batch of user operations to the entry-point contract, the shared ERC-4337 contract that validates and runs them. A person cannot approve at that rate, and a hold on either vault stops operations for every user at once. Give each vault an allow rule without approval, above any approval rule that would match it.

DALP stops a sponsored operation within seconds when the paymaster vault's policy holds its ticket. The operation fails with this message, which names the held Fireblocks transaction:

```text
The paymaster vault's Fireblocks policy holds sponsorship ticket signing (Fireblocks transaction <id>). Infrastructure vaults must stay approval-free.
```

DALP does not retry that operation, because each attempt would put one more request in front of the approvers. It also logs one warning and adds one to the `dalp_execution_infrastructure_vault_holds_total` counter for each hold, with the vault role and the provider as labels. Alert on that counter to learn of a hold within seconds, before users report it.

## Rules for vaults that send their own transactions [#rules-for-vaults-that-send-their-own-transactions]

With account abstraction off, DALP files each token write as a Fireblocks contract call from the wallet's vault to a one-time address, the Fireblocks destination type for an address that is not on the workspace whitelist. A native coin transfer has no call data, so DALP files it as a Fireblocks transfer.

Here Fireblocks reads the call itself, so a Contract Call rule can hold large transfers for approval:

- **Source:** each vault that holds investor tokens.
- **Asset:** the DALP token. DALP adds each token it creates to the Fireblocks workspace as an asset, so the token appears in the rule editor.
- **Amount:** the range that needs approval, for example every transfer above a threshold your risk team sets.
- **Destination type:** one-time address. A rule that matches only whitelisted destinations does not match the calls DALP files.
- **Contract methods:** leave the field open. Fireblocks matches contract methods only on a whitelisted contract with a verified ABI, and DALP's token roles decide which token functions each wallet can call.
- **Action:** require approval from an approver group with a threshold.

## Name contract destinations [#name-contract-destinations]

`FIREBLOCKS_NAMED_CONTRACT_DESTINATIONS`, set through the chart value `global.dalpApp.env.FIREBLOCKS_NAMED_CONTRACT_DESTINATIONS`, is off by default. While it is off, every Fireblocks broadcast goes to a `ONE_TIME_ADDRESS` destination and DALP makes no contract wallet call to Fireblocks. The note on each request still names the contract. With it on, DALP adds the organisation's system contracts and each token it creates to the Fireblocks workspace as contract wallets. A broadcast then names the contract wallet as its `CONTRACT` destination only when Fireblocks has approved that contract's asset entry for the chain. A plain native transfer, an entry that Fireblocks has not approved, and any other address keep the `ONE_TIME_ADDRESS` destination, and so does every broadcast when DALP cannot read the contract wallets. A rule written for one-time addresses does not match a named contract. Before you turn the setting on, add Contract Call, Approve and Transfer rules that accept whitelisted contract destinations.

## Order the rules in three bands [#order-the-rules-in-three-bands]

Order the rules for each type in three bands:

1. At the top, allow rules without approval: a Typed Message rule for the paymaster vault and a Contract Call rule for the bundler vault. Each names its vault as the source and the API user DALP signs as the initiator, so a customer approval rule below it cannot hold an infrastructure vault. To keep other users off these vaults, add a block rule for every other initiator on them.
2. Your approval rules, in your own order. The approver groups are your policy.
3. At the bottom, above the catch-all block rule, an allow rule for the API user on the DALP vaults for each type DALP uses. It sits below your approval rules, so it never hides one. Match the vaults by the DALP vault tag, so a wallet DALP creates later is covered without a rewrite.

A rule holds requests for approval when its verdict names at least one approver group or uses the 2-TIER action. An allow rule with approvers is an approval rule. A screening verdict such as SCREEN never counts as approval. After a hand edit in the Fireblocks Console, compare the policy with the rules on this page, because a broken policy shows no sign until the next request fails.

## Tag the DALP vaults [#tag-the-dalp-vaults]

DALP attaches one Fireblocks tag to every vault account it creates, and the bottom-band rule matches that tag. Create the tag in the Fireblocks Console and set its id in `FIREBLOCKS_DALP_VAULT_TAG_ID` (chart value `global.dalpApp.env.FIREBLOCKS_DALP_VAULT_TAG_ID`). Use an unprotected tag, or give the DALP API user the Admin or Non-Signing Admin role. Fireblocks refuses to attach a protected tag with a Signer key, and then every wallet creation fails. With the value empty, DALP attaches no tag, new vaults fall outside the bottom-band rule, and their requests reach the catch-all block rule.

Vaults that DALP created before you set the tag carry no tag, so the bottom-band rule does not cover them. Tag each of them once: in the Fireblocks Console, or with one call to `POST /vault/accounts/attached_tags` with `tagIdsToAttach` and `vaultAccountIds`. DALP also attaches the tag when it adopts an existing vault with the same name. Until a vault is tagged, its requests of every type DALP uses reach the catch-all block rule.

## Troubleshooting [#troubleshooting]

| What you see | Cause | Fix |
| --- | --- | --- |
| A sponsored operation fails with "The paymaster vault's Fireblocks policy holds sponsorship ticket signing". | A rule that requires approval matches typed messages from the paymaster vault. | Add an allow rule without approval for typed messages from the paymaster vault above it. Reject the held request, then submit the operation again. |
| Typed signatures from a vault end blocked by policy, while contract calls from the same vault pass. | No allow rule matches typed messages from that vault, so the catch-all block rule does. | Add an allow rule for typed messages from that vault for the API user DALP signs as. |
| User operations stop reaching the chain while the bundler vault shows a request waiting for approval. | A rule that requires approval matches contract calls from the bundler vault. | Allow contract calls from the bundler vault without approval, then approve or reject the waiting request. |
| A large token transfer completes without the approval you configured. | A broader allow rule above the approval rule matches first. | Move the approval rule above the allow rule. |

## Fireblocks sources [#fireblocks-sources]

- [About Policies](https://support.fireblocks.io/hc/en-us/articles/29184395887772-About-Policies): first-match evaluation from the top down, and the catch-all block rule at the bottom of each policy.
- [Configure Policies](https://developers.fireblocks.com/reference/configure-transaction-authorization-policy): rule fields, transaction types, destination types, designated signers, and approval groups. Typed Message, RAW, and Burn rules take no destination limit.
- [Set Policies](https://developers.fireblocks.com/docs/set-transaction-authorization-policy): rules run in the order you define them, so put the most restrictive rules first.
- [Typed Message policy rules](https://support.fireblocks.io/hc/en-us/articles/27421604639900-Typed-Message-policy-rules): the rule type that typed signatures need.
- [Policies for EVM DeFi operations](https://support.fireblocks.io/hc/en-us/articles/29213873102108-Policies-for-EVM-DeFi-operations): amount limits on contract calls and one-time addresses.
- [Policy rules for specific contract call methods](https://support.fireblocks.io/hc/en-us/articles/29216898855964-Policy-rules-for-specific-contract-call-methods): method rules need a whitelisted contract with a verified ABI.
- [Transactions blocked by policy](https://support.fireblocks.io/hc/en-us/articles/19172792142876-Troubleshooting-transactions-rejected-due-to-Blocked-by-Policy): what the catch-all block rule looks like on a rejected transaction.


# Gas settings

Source: https://docs.settlemint.com/docs/deployment/gas-settings
The per-network gas keys a DALP instance reads before it asks for funds, the layer order behind each one, calibrated chains and zero-gas chains.

A DALP Instance prices a write before it sends it. When a wallet cannot pay for the transaction the platform is about to send, the platform pauses that work, names the wallet and requests a deposit, so the write does not fail at the node. Every figure in that decision comes from a per-network gas block: how much to request, how long the request stays open, how large a request the platform accepts as plausible, and whether the chain charges for gas. Most chains need no gas keys, and [Adding a chain](#adding-a-chain) says which to check first.

Each network carries its own block, because a native amount that suits one chain is wrong on another. Most settings are measured in gas, so one value keeps its meaning on a chain whose token trades in thousands and on one whose token trades in cents.

[Figure] Four layers decide each gas setting, field by field. A gas setting resolves through four layers in order. The network's own saved settings win first. The deployment's network entry comes next. Below that sit the per-chain-id defaults the platform ships for chains it has already measured. The built-in defaults answer last. Each field resolves on its own, so one saved figure leaves every other figure inherited. Labels: The first layer that names a field decides it; Four layers, resolved field by field; 1. The network's own saved settings; Saved in the Console, no release needed; 2. The deployment's network entry; Shipped with the release, reviewed like any config; 3. The per-chain-id defaults; Calibrated figures the platform ships for chains it measured; 4. The built-in defaults; Answer when no layer above names the field; The effective value, one field at a time; Save one figure and every other figure stays inherited.

Each gas field resolves through the layers on its own, so one value set on a network leaves every other field live
against the layer below.

## Where a value can be set [#where-a-value-can-be-set]

A gas setting can arrive from four places, and the first one that names the field decides it:

1. **The network's own saved settings.** A platform administrator writes these through the [platform-admin network catalogue](https://docs.settlemint.com/docs/console/platform-admin/networks). They take effect without a redeploy.
2. **The deployment's network entry.** The `gas` block on the network in the values you pass to the Helm chart. Changing it is a release event.
3. **The per-chain-id defaults.** The `chainGasDefaults` section, keyed by chain ID, carrying calibrated figures for chains the platform has already measured. See [Chains that ship calibrated](#chains-that-ship-calibrated).
4. **The built-in defaults.** The figures in the table below, used when nothing above names the field.

Each field resolves on its own. A figure saved on the network freezes at the value you saved, and no later calibration change moves it until you clear it. A field you leave unset keeps following the layer below, so a later calibration change still reaches that network.

The two sponsorship bounds fall through differently at the bottom. When no layer names them, they take the deployment's global `paymaster.maxGasCostCeiling` and `paymaster.autoSponsorshipMaxGasCost` rather than a gas-block default, so a chain that never mentions sponsorship uses the deployment's global bounds.

## How to read a key name [#how-to-read-a-key-name]

The suffix of a key gives its unit:

| Suffix | Unit | Example |
| --- | --- | --- |
| `Gas` | An amount of gas | `deployFallbackGas` |
| `Seconds` | A duration in seconds | `pauseWindowSeconds` |
| No suffix | The chain's smallest native unit | `sponsorshipMaxGasCostCeiling` |

No key names a chain-specific unit. A gas amount is priced at the fee of the transaction being sized, at the moment of the ask, so one figure holds its meaning as the fee market moves and across chains whose tokens are worth very different amounts. A native amount is a raw integer in the chain's smallest unit and travels as a string of digits, because the values involved are larger than a JavaScript number represents exactly.

## The settings [#the-settings]

| Key | What it decides | Accepted range | Built-in default |
| --- | --- | --- | --- |
| `zeroGas` | Whether the chain charges for gas at all. | `true` or `false` | Unset, and the platform measures |
| `opsAllowanceGas.deployer` | Gas held in reserve for a deployer wallet after a deployment, so the next operations do not pause again. | 1 to 2,000,000,000 | 10,000,000 |
| `opsAllowanceGas.organisation` | The same reserve for an organisation wallet. | 1 to 2,000,000,000 | 7,000,000 |
| `deployFallbackGas` | The size a deployment is funded for when the node refuses to estimate it, so a failed estimate still asks for a worst case rather than a placeholder. | 1 to 2,000,000,000 | 25,000,000 |
| `maxReasonableGas` | The ceiling above which a funding request is refused as implausible. `0` turns the ceiling off. | 0 or more | 200,000,000 |
| `feeCapBaseFeeMultiplier` | How far above the pending base fee a transaction's fee cap is set. Decimals such as 1.5 are accepted. | 1 to 50 | 2 |
| `feeCapBaseFeeFloor` | The smallest base-fee allowance a fee cap is given, however low the pending base fee is. Read from the deployment's values only. | Digits only | 1,000,000,000 (1 gwei), and `0` on chain IDs 1, 17000, 560048 and 11155111 |
| `feePolicy` | The tip bounds, the most one transaction may cost when a stuck write or bundle is resent at a higher fee, and whether such resends happen. See [Where the gas price comes from](#where-the-gas-price-comes-from). Read from the deployment's values only. | Five fields, all required | Set on chain IDs 1, 17000, 560048 and 11155111, and unset elsewhere |
| `pauseWindowSeconds` | How long a funding request stays open before it expires. | 60 to 604,800 | 1,800 |
| `pauseSettleDelaySeconds` | How long the platform waits after the deposit appears on chain before it retries the paused work. | 0 to 3,600 | 120 |
| `sponsorshipMaxGasCostCeiling` | The largest gas cost a sponsorship ticket may authorise on this chain. | Digits only | The deployment's `paymaster` ceiling |
| `sponsorshipAutoMaxGasCost` | What a ticket authorises when the caller names no amount. Never above the resolved ceiling. | Digits only | The deployment's `paymaster` automatic amount |
| `fallbackGasPrice.baseFee` | The base fee to price a transaction with when the chain cannot be read and no price was ever seen for it. See [Where the gas price comes from](#where-the-gas-price-comes-from). | Digits only | Unset |
| `fallbackGasPrice.tip` | The tip that goes with that fallback base fee. | Digits only | `0` |

A network whose resolved `sponsorshipAutoMaxGasCost` sits above its resolved `sponsorshipMaxGasCostCeiling` is refused rather than silently clamped, because every sponsored operation on it would fail validation anyway.

### Choosing the values that matter [#choosing-the-values-that-matter]

Four of these decide most of the behaviour an operator notices.

`pauseWindowSeconds` depends on how fast someone tops up a wallet, and the chain does not change it. The default of half an hour suits a deployment where someone is watching and can top a wallet up. A chain funded by hand from a treasury, or a public testnet whose token comes from a faucet an operator has to go and visit, needs a day. Set it too short and work that was only waiting for money fails instead.

`maxReasonableGas` protects the operator from a bad estimate. An estimator fault or a base-fee spike can produce a request many times the real cost, and an operator who pays it has lost the difference. With the default, a request worth more than 200,000,000 gas at the fee cap is refused. Set it only after measuring the chain, and set it to `0` only on a chain whose fee behaviour is deliberately extreme.

`feeCapBaseFeeMultiplier` sets the headroom for base-fee growth, because the cap is fixed when the transaction is signed and the base fee keeps moving. On a chain with Ethereum's fee rules, where the base fee rises by at most 12.5 percent a block, the default of 2 absorbs five consecutive maximally full blocks.

A chain whose fee market climbs faster than that needs a larger number: a signed transaction whose cap the market outruns can never be mined, and it holds the head of its sender's queue while every later transaction from that sender waits behind it. Raising it also raises what an operator is asked to deposit, because the request is sized from the same cap.

The headroom itself is never charged, since the sender pays the base fee plus the tip and the cap is only a ceiling.

`feeCapBaseFeeFloor` keeps a near-zero base fee from producing a cap with no room to move. The default of 1 gwei suits a chain that charges a few gwei or more. On a chain whose base fee is far below 1 gwei, the floor alone sets the cap, and every funding request is sized against a price the chain never charges. Set it on such a chain to a value close to what the chain charges in a busy hour. The field is read from the deployment's values only. The network catalogue does not write it.

## Where the gas price comes from [#where-the-gas-price-comes-from]

Every signature, cancellation, wallet reserve, and funding request on a chain reads one price source, and that source tries these in order:

1. **A chain that charges nothing** prices every transaction at zero.
2. **The price read from the chain now**: the pending base fee and the tip the node suggests. A read is reused for twelve seconds while the chain head does not move, so a funding request and the signature that follows it see the same price. A read that takes twelve seconds or longer is refused with a `gas-price-unknown` error.
3. **The newest price seen before**, when the chain cannot be read right now and that price is less than 60 seconds old.
4. **`fallbackGasPrice`** from the deployment's network entry, when the chain cannot be read, no price was ever seen for it, and the chain has been unreadable for less than 60 seconds.

When none of these exists, the platform signs nothing and the work waits with a `gas-price-unknown` error until the chain answers. A price seen more than 60 seconds ago is never used, and neither is `fallbackGasPrice` once a price has been seen for the chain. The fee cap is the base fee times `feeCapBaseFeeMultiplier`, never less than `feeCapBaseFeeFloor`, plus the tip. A chain without a base fee is signed with a legacy `gasPrice` equal to the price read from the chain, with no headroom, because a legacy price is paid in full rather than capped.

On a chain with a `feePolicy`, the tip comes from the chain's recent fee history instead of the node's suggestion, and is held between `tipFloorWei` and `tipCeilingWei`.

The tip ceiling also sizes what Ripple Custody may charge. Ripple prices each transaction at its own Priority High rate, and the platform sets the order's maximum fee at four times the gas limit times the fee cap with the tip at `tipCeilingWei`. On a chain without a fee policy the maximum fee uses the fee cap as quoted.

The policy's other fields govern resending a stuck write or bundle at a higher fee: `publicMempool` turns those resends on, `transactionBudgetWei` caps the native amount one transaction may cost, and `blockTimeSeconds` tells the platform how old a chain head may be before a resend is unsafe.

The platform ships a policy for Ethereum mainnet and Sepolia (chain IDs 1 and 11155111) and for chain IDs 17000 and 560048: a tip from 0.01 to 2 gwei, a budget of 0.01 of the native currency, resends on, and a 12-second block time. On those chains `feeCapBaseFeeFloor` defaults to `0`.

The multiplier is always the configured value or the default of 2. The platform does not measure it from the chain. The fee cap uses the multiplier to three decimal places, so 1.2345 prices as 1.235. Each network card on the Networks page shows the newest base fee the platform recorded on that network and when it last changed. That figure is for information only and does not change the fee cap.

Set `fallbackGasPrice` only for a chain whose endpoint may be unreachable when the platform first starts. A value set too low produces transactions that the chain refuses until a real price is read, so pick a base fee at or above what the chain has charged recently. The field is read from the deployment's values only. The network catalogue does not write it.

## Whether the chain charges gas [#whether-the-chain-charges-gas]

The platform measures `zeroGas` itself. Left unset, the platform probes the chain once and caches the answer, and the effective value is reported as measured rather than configured. Set it only to overrule a probe you know to be wrong.

When the probe cannot get an answer, because the endpoint is unreachable or the node offers neither fee history nor a gas price, the platform treats the chain as one that charges gas, because a chain wrongly marked as charging nothing puts every write back on the silent path, where a drained wallet's transaction dies at the node with no request raised, no wallet named, and no resumption once the wallet is funded. A chain wrongly treated as charging gas costs a funding request that an operator can decline.

Note (A wrong zero-gas setting is not visible until a payment fails): Setting `zeroGas` to `true` on a chain that does charge turns funding protection off for that chain. Nothing reports it until an operation fails at the node for want of funds.

## Chains that ship calibrated [#chains-that-ship-calibrated]

The `chainGasDefaults` section carries measured figures for chains the platform already knows, keyed by chain ID. A deployment that adds one of these chains, with only an ID, a name, and an RPC endpoint, gets those figures with no entry of its own and no code change.

| Chain ID | Network | What the shipped entry sets |
| --- | --- | --- |
| `1` | Ethereum mainnet | The `feePolicy` only |
| `36900` | ADI Chain mainnet | Both allowances, the deployment floor, a lower request ceiling, and a one-day request window |
| `99999` | ADI Chain testnet | The same calibration as mainnet, since the fee schedule is the same |
| `11155111` | Sepolia | A one-day request window, the `feePolicy`, and a deployment floor sized for the Amsterdam fork |
| `11155420` | Optimism Sepolia | A one-day request window only, since the other figures already suit this chain |
| `31339` | A DALP test chain with a volatile fee market, not for production | Both allowances, the deployment floor, a higher request ceiling, a two-second settle delay, and fee cap headroom of 10 |
| `31337` | A local development chain | A two-second settle delay only |
| `31338` | A second local development chain | A two-second settle delay only |

Sepolia runs the Amsterdam fork, which prices a code deposit at 1,530 gas per byte of deployed code. Its deployment floor, `deployFallbackGas`, is 40,000,000 gas for that reason: the largest contract DALP deploys is 24,494 bytes of runtime code, and with 120 bytes of overhead its code deposit costs 24,614 × 1,530 = 37,659,420 gas before the constructor runs, so the built-in `deployFallbackGas` of 25,000,000 underfunds it. A chain absent from this section resolves to the built-in defaults, so a chain that adopts the fork needs the same figure.

Adding an entry here is a values change, so a recalibration ships without a code release, and the platform records which layer supplied every figure it used.

## Adding a chain [#adding-a-chain]

Follow these steps in order, and stop at the first one that gives the behaviour you need.

1. **Check whether the chain is already calibrated.** If its chain ID appears in the table above, add the network with its ID, name, and RPC endpoint, and set nothing else. The shipped figures apply.
2. **Otherwise start on the built-in defaults.** Add the network, leave the whole gas block empty, and let the platform probe whether the chain charges gas.
3. **Adjust the figures that depend on how your deployment operates.** `pauseWindowSeconds` is the usual one, because it describes who funds the wallets and how fast they respond.
4. **Measure before you set a gas amount.** Run a deployment on the chain, read the effective figures and the layer each came from on the network's edit sheet, and set only the ones the measurement contradicts.
5. **Set the sponsorship bounds only if the chain's fee level differs from the rest of the deployment.** They default to the deployment's global paymaster bounds, which already cover a typical operation at a moderate fee.

## Questions about gas settings [#questions-about-gas-settings]

### Which layer supplied the value my network runs on? [#which-layer-supplied-the-value-my-network-runs-on]

Open the network in the platform-admin catalogue and edit it. Every gas field shows the figure it resolves to as its placeholder, with a line underneath naming the layer that supplied it: this network, the deployment values, the chain default, the platform default, or a measurement of the chain. An empty field with a placeholder is inheriting. A filled field is set on this network.

### How do I stop inheriting and pin a value? [#how-do-i-stop-inheriting-and-pin-a-value]

Type the value into the field on the network's edit sheet and save. From then on that one field is fixed on this network and no change to the layers beneath it moves the value. Clearing the field again restores inheritance for that field alone.

### Do these settings apply to a chain that charges nothing? [#do-these-settings-apply-to-a-chain-that-charges-nothing]

Almost none apply. On a chain resolved as charging no gas, the platform sizes no funding requirement at all: the requirement comes back as zero, so the allowances, the deployment fallback, and the reasonable-size ceiling never produce a figure, and no request is raised for the window or the settle delay to govern. `zeroGas` is the setting doing the work on such a chain, which is why leaving it for the platform to measure matters more there than anywhere else.

### Why is the request I am asked to approve larger than the transaction costs? [#why-is-the-request-i-am-asked-to-approve-larger-than-the-transaction-costs]

A request covers the work being done plus an ongoing-operations allowance, so the same wallet does not pause again on its next operation, and it is sized at the fee cap rather than at the fee the transaction pays. The cap is a ceiling: on a chain with a base fee and a tip, the sender pays the base fee plus the tip, and the headroom between that and the cap is never charged.

A request many times larger than that is what `maxReasonableGas` refuses outright. A wallet whose transactions Fireblocks broadcasts (provider-native mode) is asked for three times the gas cost at the cap, because Fireblocks holds back its own fee reserve before it broadcasts and refuses a transaction the wallet cannot cover with that reserve included.

Like every request sized from a refusal, that amount then gets a 25 percent margin, so the request is at least 3.75 times the gas cost before the ongoing-operations allowance is added.

That applies to the first request a deployment or a write raises, before anything is sent to Fireblocks, and to the request the funding pause raises when Fireblocks refuses a transaction for its fee: the pause then asks for the reserve Fireblocks reported, or for more than the wallet holds when Fireblocks reported none.

A wallet whose transactions Ripple broadcasts is sized the same way at four times the gas cost at the cap. Ripple holds the whole maximum fee of each open order, four times the gas cost at the fee cap with the tip at the fee policy's ceiling. When the wallet cannot cover that, Ripple holds the order and the funding pause asks for the reserve Ripple reports. Wallets signed through any other custody provider, and Fireblocks or Ripple wallets whose signed transactions DALP broadcasts itself, are asked for the gas cost alone.

Two requests hold their minimum to a ceiling: the one for the wallet that creates the organisation's contracts, and the one for the wallet that sends queued writes. The minimum the work waits for is at most twice the gas cost at the cap, times the provider's multiple, plus any currency the transaction itself sends, so the 25 percent margin never lifts it past that.

When the node or the provider reports a larger reserve than the estimate, the ceiling grows by twice the difference, and the minimum never drops below what they report. The recommended amount keeps the ongoing-operations allowance, so it can be larger than the ceiling. Its size comes from the network's `opsAllowanceGas` settings, which an administrator can lower for each network.

### Can a gas setting be changed without a redeploy? [#can-a-gas-setting-be-changed-without-a-redeploy]

Yes. The network's own saved settings are written through the platform-admin catalogue. A save notifies the running services, which reload that network without a restart. Only the deployment's network entry and the shipped chain defaults need a release.


# Hosting and access

Source: https://docs.settlemint.com/docs/deployment/hosting-and-access
Where a DALP Instance runs and how involved the vendor stays once it is running are separate decisions, chosen at install and revisited independently after.

A DALP Instance runs in a Kubernetes environment you select, and how far the vendor can reach into it is a separate choice from who owns the hardware or cloud account. On this page the vendor is SettleMint, the publisher of DALP. The vendor can hold cluster access, receive outbound telemetry only, hand over the chart and never connect, or be removed from image supply by a mirrored registry. Cluster access is data access: whoever reaches the cluster can read the credentials to the database.

[Figure] Four rungs of vendor access, from full cluster access down to none at all. Vendor access to a DALP deployment sits on a ladder independent of where the platform runs. At the top, operator access to the cluster gives the vendor direct debugging and direct upgrades, and everything the cluster holds. Next, telemetry forwarding only lets the vendor monitor platform health from metrics, logs, and traces pushed outward, with zero cluster access. Below that, no agent at all: the chart is handed over and you install and upgrade it yourself, so the vendor never touches the cluster. At the bottom, a mirrored registry lets you sync every required image into your own registry first and install entirely from it, so the install pulls no image from the vendor once that sync is done. Each step down trades vendor involvement for work your own team now carries, and the bottom rung needs its images synced before every install, not only the first one. Labels: 1. Operator access to the cluster; Direct debugging, direct upgrades; 2. Telemetry forwarding only; Health visible, zero cluster access; 3. No agent, chart handed over; You install it, you upgrade it; 4. A mirrored registry; Zero vendor access; Sync images first, then install from your own copy; The ladder is independent of where you host.

Four rungs of vendor access, from most to least: operator access, telemetry forwarding only, a handed-over chart and a mirrored registry.

## Two independent choices [#two-independent-choices]

"Whose infrastructure" decides where the cluster physically runs and who holds administrative control over the hardware or cloud account underneath it. How involved the vendor stays once the instance is running is a separate question. The access ladder runs from direct cluster access down to none, and the rung you pick decides who carries the day-to-day operating load.

On infrastructure you hold, your team usually operates the instance and the vendor supports the install. On infrastructure the vendor holds, the vendor usually operates it. The infrastructure choice does not enforce either pairing. The access ladder sets the operating split for each environment.

A DALP release installs the platform workloads and nothing beneath them. Dedicated hardware, cloud accounts, cluster control planes, and namespace isolation depend on the hosting arrangement, and the chart alone does not guarantee them.

A self-hosted instance can install from images you mirror into your own registry, with no route to the vendor. It still needs every endpoint you configure: ledger RPC, SMTP, the datastores, and any custody or identity provider. The chart ships no egress policy, so restrict outbound traffic to those endpoints in your network. A vendor-hosted instance installs the same charts.

## Cluster access means data access [#cluster-access-means-data-access]

The platform holds read and write access to its own database, because it could not serve a request otherwise, so anyone who can reach the cluster can read the credentials that reach that database. No configuration grants cluster access while keeping the data private.

If vendor access to your data is unacceptable, choose rung 2, 3 or 4. None of them grants cluster access.

## The access ladder [#the-access-ladder]

The ladder has four rungs, from most vendor involvement to least. Each rung trades vendor involvement for work your own team takes on.

### 1. Operator access to the cluster [#1-operator-access-to-the-cluster]

At the top, you grant the vendor direct access to the cluster: someone who can already see the running system does not need you to reproduce a problem before they can act on it. It is also the most access a vendor can hold. Cluster administration reaches the database credentials and the encryption master password, and with the default `local` signer and secret manager those two open every signing key the platform holds, so whoever holds this rung can sign as the wallets the platform manages. A custody provider or an external secret manager moves the keys out of that reach. Your own team carries the least operating load at this rung, since the vendor can debug and upgrade directly. Choose it when getting a problem fixed fast matters more than keeping every credential inside your own team.

### 2. Telemetry forwarding only [#2-telemetry-forwarding-only]

One rung down, you grant nothing but an outbound connection. The platform's monitoring stack can run in a forwarding mode that pushes metrics, logs, and traces to an endpoint you configure, so the vendor can watch platform health without ever reaching your cluster directly. Your own team still runs every install and upgrade at this rung, and the vendor's reach stops at the telemetry it receives. Forwarding adds only an outbound OTLP connection from the cluster to the endpoint you configure, and the chart opens no inbound port or route for it. Choose this rung when you want the vendor watching for trouble without touching the cluster. Your team runs the `observability` release that forwards, and keeps its credential current.

Operating it:

- Redaction. Logs pass through an attribute allow list and text redaction before they leave. The allow list keeps only the attribute keys the chart names and drops everything else on a log record. Then the body text is rewritten: credential-shaped text such as a password or token becomes a marker, and so does any email address. A hex string of 40 to 64 characters is masked too, which covers wallet and contract addresses, transaction hashes and storage keys. Redaction does not remove names, phone numbers, bank account numbers or other personal data in free text. Metrics and traces carry no redaction: a span or metric label your own code set leaves as written. Treat forwarded telemetry as data that can contain personal data.
- Authentication. Off by default. Set a username and the matching `observability-forwarding-basic-auth` Secret, and the connection carries it. Leave the username unset and it forwards unauthenticated. The chart does not create that optional Secret. A missing Secret can leave the telemetry forwarder, Grafana Alloy, running with a blank password, while the receiver rejects its pushes. Check delivery errors as well as pod health.
- Profiles. A separate switch on the same mode. The platform pushes no profiles itself, so profile forwarding relays only profiles that another agent you run pushes to the collector.

### 3. No agent, chart handed over [#3-no-agent-chart-handed-over]

Below that, you can skip an agent entirely. The vendor hands you the chart, and your team runs the install and every upgrade after it, straight from the published registries: `pkg.distribution.settlemint.com` for the charts and `ghcr.io` for the DALP images. A pod that reschedules onto a node without its image cached pulls again, so a lost route to those registries, or an expired pull credential, surfaces as image-pull errors on the next drain or scale-out. This rung costs you the vendor's outside view. Review enabled telemetry and external integrations to determine what leaves the deployment. Diagnosing a problem starts from what your own team can see. Choose it once you are ready to operate independently, but before you need to control your own image supply too.

### 4. A mirrored registry [#4-a-mirrored-registry]

At the bottom, the vendor is out of image supply as well. Copy the charts and every image into your own registry, set `global.imageRegistry` to it, and install entirely from your copy. Choose it when even an outbound telemetry connection is unacceptable, or your network has none to offer. Take it only if you can sync the registry before every install and upgrade.

**Images to mirror.** A default install pulls from four registries: `ghcr.io` for the DALP images and the TCP-check init container that most components use, `docker.io` for PgBouncer, its metrics exporter and the `kubectl` helper, `quay.io` for the PostgreSQL exporter, and `registry.k8s.io` for the `pause` placeholder. Mirror all of them. The Conjur authenticator image appears only when `global.conjur.enabled` is `true`. A mirror built only from the components you recognise strands the install.

**Console origins.** By default the Console, the web application operators sign in to, makes no runtime call to a content delivery network, hosted analytics or a third-party embed. It serves its fonts and avatars from its own origin, so it renders with no route to the internet. Two settings make the Console load from another origin. Setting `DALP_ANALYTICS_ENABLED=true` in the Console's environment loads Google Analytics and HubSpot, and a theme font with a custom stylesheet address loads that stylesheet. Separately, a configured Ethereum Name Service network and gateway let the platform server fetch the avatar images that wallet names point at. Without them, each address shows a generated mark.

**Server calls.** Two server-side features call out of the cluster. The exchange-rate refresh fetches rates from a public currency API, `cdn.jsdelivr.net` with `currency-api.pages.dev` as fallback, unless `EXCHANGE_RATE_API_PRIMARY_URL` and `EXCHANGE_RATE_API_FALLBACK_URL` point at a source you control. The Console assistant and the docs site's Ask AI send each question, with the context they gather, to OpenRouter when `ASSISTANT_OPENROUTER_API_KEY` or an organisation's own assistant key is set. Review these, and the telemetry, RPC, custody and identity endpoints you configure, before you treat an environment as air-gapped.

**Operating it.** A missing image only fails the one Job or init container that needed it, not the whole release, so a partial rollout can look mostly healthy while it is stuck. Check the failing pod's image reference against what your registry holds. That comparison finds a sync that did not run to completion. See [OpenShift](https://docs.settlemint.com/docs/deployment/install/openshift) for confirming every image reference resolves under an air-gapped install.

## Infrastructure as code [#infrastructure-as-code]

The Helm charts that stand up a DALP Instance are what you receive. There is no separate infrastructure-as-code layer: DALP ships no Terraform module, Pulumi program or CloudFormation template. Whichever rung of the access ladder you choose, you can read every value the install sets before you run it, and run the same charts yourself if you decide to operate the platform on your own infrastructure.

## Environments [#environments]

Run at least one lower environment beside production, so an upgrade reaches it first. Promote the same chart version and images from test to production unchanged. Every environment installs the same `dalp` chart with its own values overlay, as [Deployment topologies](https://docs.settlemint.com/docs/deployment/topologies#one-chart-for-every-environment) describes. Its [deployment identity](https://docs.settlemint.com/docs/deployment/topologies#deployment-identity) section covers how `global.dalpInstance` and `global.deploymentEnvironment` keep environments apart in shared observability views.

Keep test data and credentials separate from production. A test deployment follows the networks and datastores you configure. Neither its environment label nor its chart prevents an operator from connecting production services or importing production data.

The access ladder applies per environment, not once for the whole deployment. Granting a vendor cluster access to staging says nothing about production. Each environment carries its own rung, chosen against the data that environment holds.

## Consequences and reversibility [#consequences-and-reversibility]

Two of the four rungs are values settings, though not on the same chart. Turning telemetry forwarding on or off is `alloy.forwardingMode.*`, but that key lives in the `observability` chart, not `dalp`. The `dalp` chart does not pull `observability` in as a dependency. Rung 2 needs the `observability` chart deployed as its own release. Pointing at a mirrored registry is `global.imageRegistry` on `dalp` itself. Either way, moving between rungs again is a redeploy. The other two are not chart settings at all. Operator access to the cluster is a kubeconfig and an RBAC grant you make outside the chart, and handing the chart over instead of running an agent is an operating arrangement between your team and the vendor. Revoking either one means withdrawing the grant or changing who runs the install, not touching a value.

Turning telemetry forwarding off takes effect the next time the chart is applied. Withdrawing cluster access, or handing operational control back to your own team, takes effect as soon as the grant or the handoff itself changes, independent of any redeploy.

Revoking cluster access stops future access through that grant. It does not remove data already read or copied while access was open. Turning off telemetry forwarding also leaves previously forwarded data with its recipient.

Every upgrade ships new image references, so sync a mirrored registry again before each upgrade. A skipped sync fails the same way as a missed image on the first install.

## Frequently asked questions [#frequently-asked-questions]

### Can you move from a vendor-held cluster to your own hardware later?

Yes. [Infrastructure as code](#infrastructure-as-code) covers why the same charts move with you unchanged. Moving means installing that chart set on your own infrastructure and carrying your data across, which [Backup and disaster recovery](https://docs.settlemint.com/docs/deployment/backup-recovery) covers.

## See also [#see-also]

- [Deployment topologies](https://docs.settlemint.com/docs/deployment/topologies) for what deploys and how each backend service is sized.
- [Prerequisites](https://docs.settlemint.com/docs/deployment/prerequisites) for the external endpoints and credentials an install needs ready.
- [Install the Helm charts](https://docs.settlemint.com/docs/deployment/install/helm-charts) for the install command itself.


# Deployment overview

Source: https://docs.settlemint.com/docs/deployment
Plan a topology and posture, prepare prerequisites, install the charts, integrate SSO and observability, and run the instance with upgrades and runbooks.

A DALP Instance deploys the Platform API, the Console and supporting services into your Kubernetes cluster. You supply the datastores, the ingress and the ledger endpoints. For a new deployment, plan the topology and hosting, prepare what the instance connects to, install, then connect sign-in, custody and observability. Go to [runbooks](https://docs.settlemint.com/docs/deployment/runbooks) for an incident, or [Upgrades and migrations](https://docs.settlemint.com/docs/deployment/upgrades-migrations) for a release window.

## Plan the shape first [#plan-the-shape-first]

Two decisions come before any chart runs, because the install commits you to them: how the platform is sized, and whose infrastructure it runs on.


  - [Topologies](https://docs.settlemint.com/docs/deployment/topologies): The four separately sized Platform API roles, their replica ranges and PgBouncer cost.
  - [Hosting and access](https://docs.settlemint.com/docs/deployment/hosting-and-access): Whose infrastructure runs the instance and how much of it the vendor can reach.


## Evidence for a security, procurement or audit review [#evidence-for-a-security-procurement-or-audit-review]

A reviewer who accepts or audits an instance reads these four pages. The [SettleMint Trust Centre](https://trust.settlemint.com/) holds the security and compliance documentation a security review or audit asks for.


  - [Security and compliance posture](https://docs.settlemint.com/docs/deployment/security-compliance-posture): The control layers a reviewer checks before accepting an instance.
  - [Supply chain and support policy](https://docs.settlemint.com/docs/deployment/supply-chain-and-support): Image provenance, version-to-build mapping, patched release lines and fix reporting.
  - [Third-party components and licences](https://docs.settlemint.com/docs/deployment/third-party-components): The GPL-3.0 and AGPL-3.0 services the charts deploy, and how to switch them off.
  - [Exit and data portability](https://docs.settlemint.com/docs/deployment/exit-and-data-portability): Where each kind of data lives, which exports exist and what stays if you leave DALP.


## Prepare what it connects to [#prepare-what-it-connects-to]

Confirm every endpoint, credential and unit of capacity the instance needs, including the datastores and ingress you supply yourself, before you install.


  - [Networks](https://docs.settlemint.com/docs/deployment/networks): Declare the ledger networks the instance settles on, validated before it serves traffic.
  - [Gas settings](https://docs.settlemint.com/docs/deployment/gas-settings): The per-network gas keys the instance reads, their layer order and calibrated chains.
  - [Prerequisites](https://docs.settlemint.com/docs/deployment/prerequisites): The endpoints, credentials and cluster capacity to have ready before you run the charts.
  - [Price source prerequisites](https://docs.settlemint.com/docs/deployment/price-source-prerequisites): The network paths, size caps, secret store and alerts to set before a price source runs.


## Install, connect, and keep it current [#install-connect-and-keep-it-current]

Install runs the charts in the order that avoids a failed first install. Once the instance runs, connect an external identity provider and point telemetry at your own collector or the bundled stack, both through a values change that needs no reinstall. Every later version moves through one `helm upgrade` that treats the whole release as one unit. [Upgrade to DALP 3.2](https://docs.settlemint.com/docs/deployment/upgrade-to-3-2) is the runbook for the move from 3.1 or 3.0.


  - [Install](https://docs.settlemint.com/docs/deployment/install): The charts, the CRD bundle and the Gateway API CRDs to apply before an HTTPRoute.
  - [SSO](https://docs.settlemint.com/docs/deployment/sso): Connect an OpenID Connect provider that replaces local sign-in on the Console.
  - [Observability](https://docs.settlemint.com/docs/deployment/observability): Export metrics, logs and sampled traces over OTLP to your collector or the bundled stack.
  - [Upgrades and migrations](https://docs.settlemint.com/docs/deployment/upgrades-migrations): One `helm upgrade` moves every component, and its migration Job gates it by default.


## Connect custody and funding [#connect-custody-and-funding]

Set up the custody provider each organisation signs with, and the tokens investors can deposit.


  - [Fireblocks policy](https://docs.settlemint.com/docs/deployment/fireblocks-policy): The Fireblocks policy rules each DALP vault needs with account abstraction off and on.
  - [Ripple policy](https://docs.settlemint.com/docs/deployment/ripple-policy): The properties DALP sets on every Ripple intent and how to write matching policies.
  - [Utila setup](https://docs.settlemint.com/docs/deployment/utila-setup): What the operator and the Utila vault administrator prepare before adding Utila.
  - [Utila signing agent](https://docs.settlemint.com/docs/deployment/utila-signing-agent): Deploy the customer-run Utila signing agent beside DALP: values, keys and network path.
  - [Deposit funding instructions](https://docs.settlemint.com/docs/deployment/deposit-funding-instructions): Switch on the custody gateway and choose the coins clients can deposit.


## Back up and recover [#back-up-and-recover]


  - [Backup and disaster recovery](https://docs.settlemint.com/docs/deployment/backup-recovery): In-cluster Velero backup, what your datastores must back up and how to prove a restore.
  - [Runbooks](https://docs.settlemint.com/docs/deployment/runbooks): Start from the symptom: a pod not Ready, stalled indexing or failing webhooks.


When the vendor runs the infrastructure for you, the install and upgrade pages describe work that happens on your behalf, while the plan and integrate pages describe the instance you sign in to. [SettleMint status](https://status.settlemint.com/) reports current availability and incidents for SettleMint-hosted environments.


# Browser apps with user sessions

Source: https://docs.settlemint.com/docs/deployment/install/browser-apps
Configure the Console and Investor portal when they run on separate hosts and keep session cookies on each app origin.

The Console and the Investor portal can use separate public hosts. A browser app with a host-only session cookie serves the Platform API paths on its own origin and forwards them to the private Platform API service, so the cookie reaches the server-rendered pages that check it.

The Investor portal in the chart forwards these paths with the SDK's `createDalpProxy`, to the address in `DAPI_INTERNAL_URL`, which the chart sets to `http://dalp-api:3001`. A browser app you build on the SDK mounts the same `createDalpProxy` at its `/api` and `/dalp` routes, as [browser apps with user sessions](https://docs.settlemint.com/docs/api-reference/sdk/browser-apps) shows. Set each app's public URL separately: `global.dalpApp.config.app.http.url` for the Console and `global.dalpApp.env.INVESTOR_PORTAL_URL` for the Investor portal. Do not set a public `DAPI_URL` for the browser: the browser calls the app origin, and the server forwards the request internally.

## Helm [#helm]

The chart passes the Investor portal its `DAPI_INTERNAL_URL` and the trusted edge profile, `TRUSTED_PROXY_PROFILE`, read from `global.dalpApp.config.trustedProxy.profile`. The Console applies the same profile. The profile is one of `envoy`, `nginx`, `openshift` or `none`. Set it to match the ingress or gateway in front of the apps, because the apps read the client address from that proxy's forwarding header, and `none` discards every forwarding header. Set the portal's public URL once, in `global.dalpApp.env.INVESTOR_PORTAL_URL`: the chart passes it to the portal container and lists it as a Portal origin in the Platform API.

```yaml
global:
  dalpApp:
    env:
      INVESTOR_PORTAL_URL: "https://portal.example"
investorPortal:
  enabled: true
```

`investorPortal.env` already sets `PORT` to `3000` and `DAPI_INTERNAL_URL` to `http://dalp-api:3001`. An `env` list you supply replaces the chart's list, so repeat both entries in it when you change one.

[Investor portal](https://docs.settlemint.com/docs/concepts/operating/investor-portal) explains what investors see once the portal runs and how the portal applies your organisation's theme.

`INVESTOR_PORTAL_URL` replaces `CLIENT_PORTAL_URL`. When `INVESTOR_PORTAL_URL` is empty, the portal still reads `CLIENT_PORTAL_URL` and logs `CLIENT_PORTAL_URL is renamed INVESTOR_PORTAL_URL; the next release no longer reads the old name`. Rename the value before your next upgrade.

Give the Console and the Investor portal separate routes when they use separate hosts. The forwarding preserves `Set-Cookie`, event streams and the auth-surface headers, and stamps the app origin when a server-side request has no `Origin`. Each app forwards `GET`, `HEAD`, `POST`, `PUT`, `PATCH`, `DELETE` and `OPTIONS`. Any other method on an `/api` path gets HTTP 405 with the code `METHOD_NOT_ALLOWED` and an `Allow` header from the app itself, with the same security headers as every other `/api` response.

## OpenShift [#openshift]

Apply the OpenShift overlay and set the public Route host for each app. The Investor portal uses its in-cluster `DAPI_INTERNAL_URL` and needs no Platform API Route. Keep `DAPI_INTERNAL_URL` private and set `global.dalpApp.env.INVESTOR_PORTAL_URL` to the public Portal host. [Deploy DALP to OpenShift](https://docs.settlemint.com/docs/deployment/install/openshift) lists the Route and network-policy checks.

## Sign-in returns to login [#sign-in-returns-to-login]

A successful sign-in followed by a login page means the cookie was issued by a different host. In the browser's network panel, check that the sign-in request is `/api/auth/sign-in/email` on the app host, and that the response's `Set-Cookie` names no public Platform API host. Remove `DAPI_URL`, check that the app serves `/api` on its own host, clear the old cookie and sign in again.

[Browser apps with user sessions](https://docs.settlemint.com/docs/api-reference/sdk/browser-apps) has the handler example and the forwarding rules.


# Helm charts

Source: https://docs.settlemint.com/docs/deployment/install/helm-charts
The DALP umbrella chart: what its subcharts default to, what a release gates on, and where the Gateway API CRDs come from.

The `dalp` Helm chart is an umbrella chart: one release that composes its subcharts into a DALP Instance, each subchart pinned to the same chart version. You install it with one `helm install` after you apply the Gateway API CRD bundle once per cluster, and the release waits on its database migration, not on index rebuilds. The chart needs Kubernetes 1.23 or later, because it renders `autoscaling/v2` HorizontalPodAutoscalers. The [Subcharts](#subcharts) table lists the components, [Topologies](https://docs.settlemint.com/docs/deployment/topologies) explains which to enable, and [Values and secrets](https://docs.settlemint.com/docs/deployment/install/values-secrets) prepares the deployment settings.

## Install [#install]

Apply the Gateway API CRD bundle once per cluster, before the first install. The `docs` subchart renders an `HTTPRoute` by default, and `dapp` (the Console), `dapi` (the Platform API), `blockscout` and `investorPortal` render one when you set their `httpRoute.enabled`. A release that renders any of them without the CRDs fails to create it:

```bash
helm template envoy-gateway-crds oci://docker.io/envoyproxy/gateway-crds-helm \
  --version 1.10.0 \
  --set crds.gatewayAPI.enabled=true \
  --set crds.gatewayAPI.channel=standard \
  --set crds.envoyGateway.enabled=true \
  | kubectl apply --server-side --force-conflicts -f -
```

`--server-side` is required for this apply. The command pulls the bundle from Docker Hub, and the bundle is not part of DALP. `--force-conflicts` takes over any field another tool set on these CRDs, so run it only on a cluster where nothing else manages Gateway API, or mirror the bundle and apply your own copy. [Gateway API CRDs ship separately](#gateway-api-crds-ship-separately) explains why the bundle is a separate step and how often to repeat it.

Install the chart from the SettleMint OCI registry, pinning the chart version you deploy:

```bash
helm install dalp oci://pkg.distribution.settlemint.com/settlemint/dalp \
  --version <chart version> \
  --namespace dalp --create-namespace \
  --values my-values.yaml
```

Supply your own `my-values.yaml`, or repeated `--set key=value` flags, on top of the chart's defaults. A first install fails until it sets `global.datastores` for PostgreSQL and Redis, the object storage settings, `ENCRYPTION_MASTER_PASSWORD`, `BETTER_AUTH_SECRET`, `CUSTODY_CREDENTIAL_IDENTITY_KEY` and `global.dalpApp.env.DALP_GOVERNANCE_DOMAIN_SCOPE`, as [Values and secrets](https://docs.settlemint.com/docs/deployment/install/values-secrets) describes. The chart and its images come from SettleMint's registries, and [Prerequisites](https://docs.settlemint.com/docs/deployment/prerequisites) lists the pull access the cluster needs. Deploying to OpenShift needs the additional overlay in [OpenShift](https://docs.settlemint.com/docs/deployment/install/openshift).

Once `helm install` returns, `helm status dalp --namespace dalp` reports `deployed` and `kubectl get pods --namespace dalp` shows every pod `Running` or `Completed`. With local sign-in, the first account created on the fresh instance becomes a Platform admin and every later sign-up is a member, so create the first account before the Console is reachable from outside your network. [Security and compliance posture](https://docs.settlemint.com/docs/deployment/security-compliance-posture#restore-the-platform-administrator-role) says how to restore the role when no Platform admin is left.

[Figure] The path a DALP release moves through, from the Gateway API CRD prerequisite to a pod serving traffic. Five states in sequence, with three off-ramps. First, the Gateway API CRD bundle must already be applied to the cluster, once per cluster and before install. Skipping it fails HTTPRoute creation at helm install or upgrade time. Second, the migration hook runs as a pre-install or pre-upgrade Helm hook, before any workload rolls out. If it fails, the release fails immediately and the job survives only until the next helm upgrade retry reclaims it, so its logs need reading before then. Third, the workload rollout begins, with each subchart rolling on its own update strategy. Fourth, the startupProbe clears, on a boot budget sized per workload: 180 seconds for dapi, 300 seconds for dapp. Fifth, the readinessProbe clears and the pod starts serving traffic, on a budget that also differs per workload: 10 seconds for dapi's Postgres-bound check, 3 seconds for dapp's process-only check. An index rebuild or shard relocation on the indexer or runner workload runs behind an already-healthy deployment and is not part of this gate. Labels: 1. Gateway API CRDs applied; Once per cluster, before install; If skipped; HTTPRoute creation fails at; install or upgrade time; 2. Migration hook runs; Runs before any workload rolls out; If it fails; Release fails before any workload; rolls out. Job stays until retry; 3. Workload rollout begins; Each subchart rolls its own strategy; 4. startupProbe clears; dapi 180s boot budget (36 checks); dapp 300s boot budget (60 checks); 5. readinessProbe clears; Pod serves traffic. dapi 10s timeout,; Postgres-bound, and dapp 3s timeout, process only; Indexer and runner only; Index rebuild or shard; relocation runs behind an; already-healthy pod.

A release moves through five states, with off-ramps for a missing CRD bundle, a failed migration hook and [a `helm upgrade` that runs out its wait](#what-goes-wrong).

## Migrations gate a release, index rebuilds do not [#migrations-gate-a-release-index-rebuilds-do-not]

A schema migration runs as a Helm hook on the `dapp` subchart, and whether it gates the release depends on `dapp.migrator.hookType`. The default, `pre`, runs it as a `pre-install` and `pre-upgrade` hook before any workload rolls out, so a failed migration fails the release before a pod ever serves traffic. Set it to `post` when the same Helm release creates the database, so it exists before the migration runs against it. Set it to `none` to run the job as a plain, unhooked `Job` with no release gate.

By default, a failed job survives the upgrade that ran it, and the next `helm upgrade` removes it, so read its logs before you retry. With the `pre` default, a catch-up run of the same migration also follows the rollout and can still fail the release. [Upgrades and migrations](https://docs.settlemint.com/docs/deployment/upgrades-migrations#what-runs-and-when) states the retry limit, timeout and clean-up defaults.

An indexer index rebuild is a different kind of operation and does not block a release. It runs behind an already-healthy deployment, re-derives projections from already-ingested chain data, and a rebuild in progress does not fail or delay `helm upgrade`. Do not wire an index rebuild into a release gate the way you would a migration. A failed pre-upgrade migration blocks the new rollout. A projection rebuild has a separate completion signal. Affected reads can remain stale or unavailable until it completes.

## Subcharts [#subcharts]

| Subchart | Condition |
| --- | --- |
| `common` | always installed |
| `dapp` (the Console) | `dapp.enabled`, on by default |
| `dapi` (the Platform API) | `dapi.enabled`, on by default |
| `docs` (this documentation site) | `docs.enabled`, on by default |
| `pgbouncer` | `global.pgbouncer.enabled`, on by default |
| `postgres-exporter` | `postgres-exporter.enabled`, on by default |
| `blockscout` | `blockscout.enabled`, off by default |
| `investorPortal` (Investor portal) | `investorPortal.enabled`, off by default |

`pgbouncer` gates both the connection-pooling workload and the application URL routing, so it also decides how `dapp` and `dapi` reach PostgreSQL. `investorPortal` deploys the Investor portal, the standalone investor-facing web app for sign-in, funding, primary-issuance offers and secondary-market trading. The chart also carries `canton`, `investorDocs`, `utilaSigningAgent` and `simulator` blocks, all off by default.

| Your deployment | Enable this |
| --- | --- |
| Standard EVM asset issuance, no explorer, no investor-facing portal | Keep the defaults (`dapp`, `dapi`, `docs`, `pgbouncer`, `postgres-exporter`). Enable Blockscout or the Investor portal only when the deployment needs it. |
| Needs an on-chain block explorer | `blockscout.enabled: true`. Blockscout ships as its own subchart with its own dedicated PostgreSQL database. |
| Serves investor-facing primary or secondary market access | `investorPortal.enabled: true`. The Investor portal is a standalone web app on the published SDK, deployed as its own workload. |

Every subchart pins the same chart version as the umbrella chart, so a `dalp` release at one version installs `dapp`, `dapi`, `docs` and the rest at that same version. Mixing subchart versions inside one release is not supported.

## Gateway API CRDs ship separately [#gateway-api-crds-ship-separately]

The `docs` subchart creates an `HTTPRoute` by default, and `dapp`, `dapi`, `blockscout` and `investorPortal` do when their `httpRoute` is enabled, but the `dalp` chart does not bundle the Gateway API custom resource definitions. The bundle exceeds the size Helm allows inside a release's stored secret, and Helm cannot upgrade CRDs that ship inside a subchart's own `crds/` directory anyway, so a chart that bundled them could install once and never refresh them again.

Apply the bundle as a separate step, with the command in [Install](#install): `gateway-crds-helm`, applied server-side once per cluster. The controller that serves the routes is yours to supply and is not part of the `dalp` chart.

The CRD bundle's version is the one in that install command, not the `dalp` chart version, so a `dalp` upgrade alone never tells you the CRDs also need a refresh.

Kubernetes validates a resource's kind against installed CRDs before it stores it. A release started without the bundle applied fails to create its `HTTPRoute` resources, and that surfaces as a `helm install` or `helm upgrade` error.

## Values to set [#values-to-set]

- `global.pgbouncer.enabled`, default `true`. It also decides how `dapp` and `dapi` reach PostgreSQL. See [Subcharts](#subcharts).
- `dapp.migrator.hookType`, default `pre`. Sets whether a failed migration gates the release at all. See [Migrations gate a release, index rebuilds do not](#migrations-gate-a-release-index-rebuilds-do-not).
- `dapp.migrator.timeout`, default `600` seconds. It bounds all attempts together.
- `overprovisioning.enabled`, default `false`. Reserves standing rollout headroom so an upgrade does not stall on a tight scheduler pool.
- Chart version. Pin it on every install and upgrade so that each release is a reviewed change.
- Gateway CRD bundle version, set by the `--version` of the CRD command. It changes independently of the `dalp` chart version, so check both. See [Gateway API CRDs ship separately](#gateway-api-crds-ship-separately).

## What goes wrong [#what-goes-wrong]

**A helm upgrade times out before the last workload reports ready**

Run `helm upgrade` with a `--timeout` sized to your deployment's worst case, such as 30 to 40 minutes, and adjust for
your cluster. Helm's own default wait is 5 minutes. A timeout abort does not roll back completed steps by itself, so
check `helm history` and the workload status before you retry. `progressDeadlineSeconds` is 1500 seconds (25 minutes)
on both `dapi` and `dapp`, above the Kubernetes default of 600. A single surge pod can spend up to its boot budget
plus relaunch headroom before `/readyz` reports ready, so a tighter number needs its own margin. On the Kubernetes
default of 600 seconds, `dapp` would trip before the PgBouncer pooler it waits on, which needs up to 900, and that
reads as a Console failure when the fault is the pooler. `dapp`'s 1500 seconds outlasts it. The API fleets roll with
`maxSurge: 1` and `maxUnavailable: 0`, one pod at a time, so a tight timeout can fire before the last workload reports
ready. A tight scheduler pool adds its own stall: see [`overprovisioning.enabled`](#values-to-set).

**The readiness check keeps failing and the database looks fine**

Kubernetes' readiness and startup probes differ by workload in what they check and
how long they wait, so confirm which one is failing with `kubectl describe pod` before assuming Postgres is the
problem. `dapi`'s `/readyz` probes Postgres through a dedicated health session every 15 seconds. The probe has a
10-second timeout and allows three failures. An unavailable database removes the pod from service after roughly 45
seconds, or up to about 55 seconds including reporting lag. `dapi`'s startup probe answers on `/healthz` instead, with
its own 180-second boot budget. `dapp`'s startup and readiness probes both answer on `/readyz`. Its liveness probe
answers on `/healthz`. The startup probe budgets 300 seconds (5 minutes) for slow first-boot SSR and SDK warmup, and
only once that clears does the readiness probe start applying its own 3-second, process-only budget. A pod stuck in
that 300-second startup window looks identical to a hung readiness probe in `kubectl get pods` output, so check which
probe is failing before assuming either.

**An indexer or runner rollout looks stuck when the api workload rolled fine**

`dapi` renders each role as its own Deployment: the `/api/v1` and `/api/v2` fleets, a runner, a scheduler, and an
indexer with a separate rebuild Deployment. The API fleets and the runner have their own HorizontalPodAutoscaler. The
indexer, its rebuild pods and the scheduler run a fixed replica count. The API fleets roll `maxSurge: 1` and
`maxUnavailable: 0`, the same one-at-a-time pattern as `dapp`. The indexer rolls the other way, `maxUnavailable: 1`
and `maxSurge: 0`, and holds a replacement back for a 90-second `minReadySeconds` before it counts as ready. The
runner and the scheduler use the `Recreate` strategy, so their old pods stop before the new ones start. The indexer
and the runner each have a PodDisruptionBudget that keeps at least one pod up. Expect the indexer, runner and
scheduler to take an old pod down before a new one is ready. This protects capacity in those roles and is not a stuck
rollout.

**Redis restarts and pods keep serving**

Redis does not gate startup. Cache and notification connections are supervised per pod, so bringing the platform up
before Redis is ready is supported: pods serve from their in-process cache and reconnect on a jittered exponential
backoff capped at 30 seconds, with no attempt limit. Reconnection checks that Redis is serving requests rather than
only accepting connections, so an endpoint still loading a snapshot is retried instead of treated as healthy. While
disconnected, cached reads stay correct but remain private to each pod, and change notifications use each listener's
own reconcile interval. Watch `dalp_redis_client_unavailable_seconds`, labelled per `redis_role`, so you can tell
which of the two clients, cache or notifications, is the one that dropped. The `RedisClientLatchedOffline` alert
(severity `warning`) confirms roughly six minutes into a sustained outage, identifying a pod that has not recovered
from more than a brief restart.

**An indexer's head socket drops and live indexing waits for the reconnect**

The Ledger Data indexer learns about new blocks from a standard `newHeads`
subscription on the chain node's WebSocket. It sends `eth_blockNumber` on the same socket every 10 seconds. It
reconnects when no reply arrives, or when the reply is more than three blocks past the last head the subscription
delivered. It reads the head over HTTP on every new subscription, so blocks mined during an outage are indexed after
the reconnect. A connection-state gauge reports three values (connected, disconnected, or circuit broken), and a
separate `dalp_didx_ws_unavailable_seconds` series tracks how long the socket has been down, because the state gauge
alone cannot distinguish a two-second blip from a standing outage. The `IndexerWebSocketHeadLatchedOffline` alert
(severity `warning`) confirms roughly six minutes into a sustained outage, keyed per network, long enough that an
ordinary reconnect never pages. Live indexing does not advance while the socket is down, because no poll runs beside
the subscription. Once the socket reconnects, the indexer reads the current head and indexes every block it missed.

## Frequently asked questions [#frequently-asked-questions]

### Does turning off a subchart delete its data?

Disabling a subchart removes its rendered resources from the release on the next upgrade. External databases are separate, but PVC retention and underlying volume deletion depend on the workload and storage policies. Inspect the rendered change and confirm a recoverable backup before disabling a stateful component.

### How often do the Gateway API CRDs need reapplying?

Only when you move to a newer bundle version. A `dalp` upgrade alone does not need it. [Gateway API CRDs ship separately](#gateway-api-crds-ship-separately) explains why.

### Does each Platform API role scale on its own?

Yes. By default the `/api/v2` fleet ranges 2 to 24 replicas and the `/api/v1` fleet 1 to 4, both at 50% CPU utilisation, and the runner ranges 2 to 12 replicas at 75%. The indexer does not autoscale: it runs `dapi.indexerDeployment.replicaCount` pods, 2 by default, next to its rebuild pods. The scheduler runs one pod. A replica-count change on one role leaves the other roles, and each role's own rollout strategy, untouched.

### Does the migration job still run if I disable dapp?

No. The migration job is a `dapp` subchart template, so `dapp.enabled: false` skips the whole subchart, migration hook included, the same way it skips every other `dapp` object. A deployment without `dapp` must arrange the required database migration separately before starting services against the new schema.


# Install overview

Source: https://docs.settlemint.com/docs/deployment/install
The DALP Helm chart, the optional observability chart, the Gateway API CRD bundle that precedes them, and the order to install them in.

A DALP Instance is one running copy of the platform: the Platform API that handles transactions and workflow orchestration, the Console that operators and issuers sign in to, and the telemetry behind them, all running against datastores you supply. You install it as the `dalp` Helm release, an optional `observability` release, and one cluster-level prerequisite, the Gateway API CRD bundle. Apply the CRD bundle first, then install `observability` if your cluster has no telemetry stack of its own, then `dalp`.

Installing needs rights to create cluster-scoped resources, because the CRD bundle and the `observability` chart's collector create them, and network access from the cluster to your PostgreSQL. Both charts come from the SettleMint OCI registry, `pkg.distribution.settlemint.com`, and [Prerequisites](https://docs.settlemint.com/docs/deployment/prerequisites) lists the registry access the cluster needs.

## Two releases and one prerequisite [#two-releases-and-one-prerequisite]

The `dalp` chart is the platform itself: an umbrella release whose subcharts all pin one shared chart version, so one version number describes every subchart of the release. The CRD bundle, the `observability` release and your datastores have versions of their own. The Platform API, the Console, the docs site that publishes this documentation, PgBouncer connection pooling, and a PostgreSQL metrics exporter install by default. A block explorer and an Investor portal each have an enable flag. [Helm charts](https://docs.settlemint.com/docs/deployment/install/helm-charts) covers installing it and what a release waits on. It deploys no datastore and no ingress controller, so PostgreSQL, Redis, object storage, and the ingress controller or Gateway API implementation are services you supply, per [Prerequisites](https://docs.settlemint.com/docs/deployment/prerequisites) and [Values and secrets](https://docs.settlemint.com/docs/deployment/install/values-secrets).

The `observability` chart is a second, optional release: an Alloy collector, VictoriaLogs, Tempo and VictoriaMetrics stores, and Grafana with DALP dashboards provisioned and the DALP alert rules ready to switch on. The platform's default telemetry export endpoints name this chart's services in the `monitoring` namespace, so the two halves connect without per-URL wiring when the chart lands where the defaults expect it. [Observability stack](https://docs.settlemint.com/docs/deployment/install/observability-stack) covers it.

The Gateway API CRD bundle is the prerequisite for any release that renders an `HTTPRoute`: custom resource definitions applied once per cluster, before any of the charts. No DALP chart carries them, because Helm cannot upgrade CRDs that ship in a subchart's own `crds/` directory, so a chart that carried them would install them once and never refresh them. The `dalp` chart's docs site renders an `HTTPRoute` by default, so most installs need the bundle. A cluster that routes everything through ingress can set `docs.httpRoute.enabled: false` and skip the bundle. The bundle's version is the one in your CRD command, not the `dalp` chart version, so a `dalp` upgrade alone never tells you the CRDs also need one. [OpenShift](https://docs.settlemint.com/docs/deployment/install/openshift) runs a different overlay that renders Routes instead of `HTTPRoute` resources and does not need this bundle at all. [Helm charts](https://docs.settlemint.com/docs/deployment/install/helm-charts#gateway-api-crds-ship-separately) covers which subcharts render a route and what the failure looks like.

[Figure] The install order, and what each position protects. Three steps in sequence. First, the Gateway API CRD bundle, applied once per cluster and outside any release. Skipping it means a release that renders an HTTPRoute fails at install time on the unknown resource kind. Second, the observability chart: Alloy, VictoriaLogs, Tempo, VictoriaMetrics, and Grafana. Installing it before the DALP chart means telemetry export resolves from the first pod instead of failing until the receiver exists. Third, the DALP chart itself: the Platform API, the Console, the docs site, connection pooling, and the metrics exporter. Its database migration needs your PostgreSQL reachable and runs before any workload rolls out. Labels: 1. Gateway API CRD bundle; Applied once per cluster, outside any release; If skipped; A release that renders an; HTTPRoute fails at install; time on the unknown kind; 2. observability chart; Alloy, VictoriaLogs, Tempo, VictoriaMetrics, Grafana; Why before DALP; Telemetry export resolves from; the first pod instead of failing; until the receiver exists; 3. DALP chart; Platform API, Console, docs, pooling, metrics exporter; The platform release; Its migration needs your; PostgreSQL reachable and runs; before any workload rolls out.

Install order: the CRD bundle first, then the optional `observability` chart, then the `dalp` chart.

## What each position in the order protects [#what-each-position-in-the-order-protects]

The CRD bundle guards the resource kind. Kubernetes validates a resource's kind before storing it, so a release that renders an `HTTPRoute` on a cluster without the Gateway API CRDs fails at install time. The docs site's `HTTPRoute` renders by default inside the `dalp` chart, so a first install on a bare cluster hits this gate unless the CRDs went in first.

The Gateway it attaches to is a separate gate, and it fails without an error. The docs site's `HTTPRoute` points by default at a Gateway named `dalp-gateway` in a placeholder namespace, and no chart in this set creates that Gateway. Unless a Gateway with that name exists in that namespace of your cluster, the docs release still installs cleanly: no error, no route, nothing in `helm status` to flag it. Set `docs.httpRoute.gatewayRef.name` and `docs.httpRoute.gatewayRef.namespace` to your own Gateway.

Your PostgreSQL must be reachable when the `dalp` release's migration job starts. An init container in each attempt of that job waits up to 2 minutes for the database (`dapp.initContainer.tcpCheck.timeout`, 120 seconds by default), and the job retries up to 3 times inside its 600-second `dapp.migrator.timeout` window. [Helm charts](https://docs.settlemint.com/docs/deployment/install/helm-charts#migrations-gate-a-release-index-rebuilds-do-not) covers the migration job's own retry and timeout budget, and what happens to the release when the job never finishes.

Install the `observability` chart before `dalp` so the platform's export endpoints resolve from the first pod, instead of failing until the receiver appears. The first hours of a new instance are the hours you later want telemetry from.

## Which releases you install [#which-releases-you-install]

The `dalp` chart is on every path. You need the CRD bundle when any release renders an `HTTPRoute`, and the docs site does by default. You need the `observability` chart when your cluster has no telemetry stack. You supply the datastores and the ingress or Gateway on every path. OpenShift uses Routes instead of the CRD bundle and Gateway routing, as [OpenShift](https://docs.settlemint.com/docs/deployment/install/openshift) describes.

| Your cluster | Install | Why |
| --- | --- | --- |
| An existing metrics and logging stack. | CRDs, then `dalp`. With `docs.httpRoute.enabled` set to `false`, `dalp` alone, with no CRDs and no Gateway. | The platform reads its datastores from `global.datastores` and its object storage settings, and its telemetry export endpoints repoint to your own collector. The CRD bundle exists only because the docs site's `HTTPRoute` renders by default. An ingress-only cluster can turn that off and skip the bundle for good. |
| No telemetry stack. | CRDs, `observability`, then `dalp`. Skip the CRD bundle the same way if ingress covers every route. | The observability stack arrives with DALP dashboards and alert rules provisioned, which you would otherwise rebuild in your own Grafana. |
| A bare cluster, or a first environment. | Your PostgreSQL, Redis, and object storage first. Then the CRDs, your ingress controller or Gateway implementation and its Gateway, `observability`, and `dalp`, in the pictured order. | No chart provides the datastores or the routing layer, so a first environment needs them running before the first install, and each migration attempt waits only 2 minutes for PostgreSQL. Gateway API routing also needs a Gateway you create and name in `docs.httpRoute.gatewayRef`. |

The commands for each step are on [Helm charts](https://docs.settlemint.com/docs/deployment/install/helm-charts#install), for the CRD bundle and `dalp`, and on [Observability stack](https://docs.settlemint.com/docs/deployment/install/observability-stack), for `observability`.


  - [Helm charts](https://docs.settlemint.com/docs/deployment/install/helm-charts): Install the `dalp` umbrella chart, its subcharts and what a release gates on.
  - [Values and secrets](https://docs.settlemint.com/docs/deployment/install/values-secrets): Point `global.datastores` at your databases, set TLS and choose how secrets reach pods.
  - [Observability stack](https://docs.settlemint.com/docs/deployment/install/observability-stack): Install the bundled Alloy, VictoriaLogs, Tempo, VictoriaMetrics and Grafana stack.
  - [Browser apps](https://docs.settlemint.com/docs/deployment/install/browser-apps): Serve the Console and Investor portal on separate hosts with separate session cookies.
  - [OpenShift](https://docs.settlemint.com/docs/deployment/install/openshift): Apply the OpenShift overlay: a restricted security context and native Routes.



# Observability stack

Source: https://docs.settlemint.com/docs/deployment/install/observability-stack
Install the observability Helm chart a DALP instance exports to: an Alloy collector, VictoriaLogs, Tempo, VictoriaMetrics, and Grafana, then verify telemetry.

The `observability` chart is the receiving side of the platform's telemetry. A DALP instance exports traces, metrics, and logs over OTLP (the OpenTelemetry Protocol) whether or not anything is listening, as [Observability](https://docs.settlemint.com/docs/deployment/observability) describes.

This chart is one Helm release that receives that export, routes each signal to its own store and shows all three in Grafana, with the DALP dashboards provisioned. Install it when you want the deployment observable without assembling a stack yourself. Skip it when a fleet-wide backend already exists: in that case point each signal's export endpoint at your collector instead, and nothing on this page applies.

Installing it changes two things beyond the new pods. First, the platform's zero-configuration path starts working: the `dalp` chart's export defaults already target this stack's collector in the `monitoring` namespace, so a platform installed after this chart ships telemetry from its first pod onward with no export values set. Second, you commit to a telemetry identity. The chart refuses to render until you name the deployment, and that name is stamped on every signal the stack handles, so choosing it is the decision here that is hardest to change later.

You can keep part of the stack. Every component sits behind its own enable flag, so a deployment that already runs a fleet-wide log store can disable the bundled one and keep the rest. Disabling a component is not enough on its own: Alloy and Grafana still point at the bundled service names, so keeping your own store also means repointing the matching `alloy.endpoints.internal.<signal>` endpoint and the corresponding Grafana datasource at it.

[Figure] One release receives, stores, and graphs what the platform already exports. The platform's OTLP-exporting components, the Platform API, the Console, and this documentation site, export traces, metrics, and logs to obs-alloy, the collector this chart deploys, each signal targeting its own endpoint on OTLP ports 4317 for gRPC and 4318 for HTTP. Alloy also scrapes the cluster and node directly, kubelet and cAdvisor metrics plus the stdout of workloads that do not export OTLP, the ledger node, proxies, and policy controllers among them. Alloy routes each signal to its own store: logs to obs-logs running VictoriaLogs with 168 hour retention, traces to obs-tempo running Tempo with 168 hour retention, and metrics to obs-metrics running VictoriaMetrics with one month retention. All three stores feed obs-grafana, where DALP dashboards are provisioned by default and alert rules are opt in. Labels: DALP services; Platform API, Console, docs; Cluster &amp; other workloads; kubelet, cAdvisor, non-OTLP stdout; OTLP export; obs-alloy; collector, OTLP 4317 gRPC and 4318 HTTP; obs-logs; VictoriaLogs; logs, kept 168 hours; obs-tempo; Tempo; traces, kept 168 hours; obs-metrics; VictoriaMetrics; metrics, kept 1 month; obs-grafana; dashboards provisioned, alert rules opt in.

Services export OTLP to Alloy, which routes logs, traces and metrics to VictoriaLogs, Tempo and VictoriaMetrics, and Grafana reads all three.

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

- A Kubernetes cluster at version 1.23 or later.
- A Helm client that can pull charts from an OCI registry.
- Network access to `pkg.distribution.settlemint.com`.
- A default storage class with room for 31Gi total: VictoriaLogs, Tempo and VictoriaMetrics each claim a 10Gi persistent volume out of the box, and Grafana 1Gi, before you touch retention.
- A namespace decision: the `dalp` chart's export defaults assume `monitoring`, and any other choice costs overrides on both releases.
- A stable slug for this deployment and the environment it runs in, decided before you write any YAML. The render refuses to proceed without them.
- The right to create cluster-scoped RBAC, because Alloy defaults to a ClusterRole and ClusterRoleBinding that can discover pods in every namespace on the cluster.

## Steps [#steps]

**Step 1 of 4**

### Name the deployment's telemetry identity [#name-the-deployments-telemetry-identity]

Set `global.dalpInstance` to a stable slug for this deployment: 1 to 63 characters, lowercase letters, digits, and hyphens, starting and ending with a letter or digit. Set `global.deploymentEnvironment` to one of `local`, `development`, `test`, `staging`, `demo`, or `production`. Both are required and validated at render time, and neither has a default.

The pair is stamped on every metric, log, trace, and profile the stack handles, and two deployments sharing one slug merge silently into a single identity in every fleet-level dashboard and alert group, while every signal still flows. Pick a slug you can keep, because changing it later splits the deployment's history into two identities.

The render also refuses the slug `local` in any environment other than `local`, which catches the common copy-paste of a local values file into a staging install.

**Step 2 of 4**

### Write the values file [#write-the-values-file]

Start the values file with the identity pair, then configure credentials, routing, storage, and retention for your deployment:

```yaml
global:
  dalpInstance: "example-primary"
  deploymentEnvironment: "production"
```

On a restricted or multi-tenant cluster, scope Alloy before you install rather than after. Set `alloy.rbac.namespaces` to the namespaces you want the ClusterRole to cover. That list limits pod discovery for stdout scraping. It does not restrict OTLP logs, which can arrive from any pod that can reach the receiver Service. The platform's `dapi`, `dapp`, and `docs` containers export OTLP, so the stdout scrape excludes them. Set `alloy.podDiscovery.namespaces` instead when the scrape needs a different scope than the RBAC namespaces.

Set storage, retention and credentials now, not during an incident. To keep a store you already run elsewhere, disable the bundled component and repoint Alloy and Grafana at your own. Each component has its own enable flag: `victoria-logs-single.enabled`, `tempo.enabled`, `victoria-metrics-single.enabled`, `grafana.enabled`, `alloy.enabled`. Disabling one alone leaves Alloy writing to a Service that no longer exists.

Set `alloy.endpoints.internal.prometheus.url`, `alloy.endpoints.internal.otel.url` or `alloy.endpoints.internal.logs.victoriaLogsUrl` to your store's address, and point the corresponding Grafana datasource at the same place.

To hold telemetry longer than the defaults, raise the retention values now: `victoria-logs-single.server.retentionPeriod` and `tempo.tempo.retention` both default to seven days, and `victoria-metrics-single.server.retentionPeriod` to 1 month. A seven-day window cannot answer an investigation into older data, so size retention for the questions you must answer. This stack holds operational telemetry.

The platform's audit trail lives in its database, which [Backup and recovery](https://docs.settlemint.com/docs/deployment/backup-recovery) covers.

Replace the Grafana administrator login before the release is reachable. The chart ships `grafana.adminUser: settlemint` and `grafana.adminPassword: dalp`, which are public, and Grafana can read every log line. Supply unique values through your deployment's secret mechanism.

Set `alloy.clustername` as well. Alloy stamps it as `cluster_name` on every signal that lacks one, and falls back to `settlemint` when it is empty.

**Step 3 of 4**

### Install the release [#install-the-release]

```bash
helm install observability oci://pkg.distribution.settlemint.com/settlemint/observability \
  --version <chart version> \
  --namespace monitoring --create-namespace \
  --values my-values.yaml
```

The chart fixes its service names whatever the release name: `obs-alloy`, `obs-logs`, `obs-tempo`, `obs-metrics` and `obs-grafana`. The namespace is the placement choice that matters. The `dalp` chart's traces, metrics, and logs exporters all default to the Alloy receiver in `monitoring`, so installing there means the platform needs no export configuration at all. Installing anywhere else works, and costs two sets of overrides: each signal's `otlp.endpoint` key on the platform release, and `global.observability.namespace` on the same release if you enable the debug bundle wiring in the next step.

Install the receiving stack before the platform on a new deployment to avoid losing early telemetry. When upgrading both releases, check compatibility between the collector configuration and application exporters before deciding the order.

**Step 4 of 4**

### Connect the platform release [#connect-the-platform-release]

If the platform runs with default export settings and this stack sits in `monitoring`, telemetry flows with no further change. One connection is opt-in: set `global.observability.enabled: true` on the `dalp` release and the admin debug bundle derives its VictoriaLogs and Tempo query endpoints from this stack's service DNS.

A platform administrator's "Export debug information" action in the Console then pulls raw logs and traces without cluster access. An organisation owner's export leaves them out, because they carry every organisation's activity. The connection defaults to off because the platform cannot assume this chart exists. Explicit `dapi.observabilityLogsUrl` and `dapi.observabilityTempoUrl` values override the derivation for a renamed or out-of-cluster stack.

For export-side choices, the sample ratio, a different collector per signal, or an external backend, follow [Observability](https://docs.settlemint.com/docs/deployment/observability).

The chart's default ingress host is a placeholder, and OpenShift Route and Gateway API HTTPRoute variants sit behind their own flags. The provisioned dashboards are grouped into folders named `00-start-here`, `services`, `cluster`, `telemetry`, `fleet`, and `local`. The `local` folder ships in every environment and stays sparse outside one.

## What the chart deploys [#what-the-chart-deploys]

| Component | Role | Enable flag (default) |
| --- | --- | --- |
| Alloy | OTLP collector and router that scrapes cluster and pods | `alloy.enabled` (on) |
| VictoriaLogs | Log store | `victoria-logs-single.enabled` (on) |
| Tempo | Trace store | `tempo.enabled` (on) |
| VictoriaMetrics | Metrics store | `victoria-metrics-single.enabled` (on) |
| Grafana | Dashboards, datasources, alerting | `grafana.enabled` (on) |
| kube-state-metrics | Cluster metric source | `kube-state-metrics.enabled` (on) |
| node exporter | Node metric source | `prometheus-node-exporter.enabled` (on) |
| metrics-server | Cluster resource metrics API | `metrics-server.enabled` (off) |

Grafana's three datasources come provisioned and cross-linked: a log line carries a link to its trace, and a trace links back to the logs in its time window, so an investigation moves between signals without hand-building queries.

## Alert rules are a deliberate second step [#alert-rules-are-a-deliberate-second-step]

Dashboards work as soon as the release installs. The alert rules ship in the chart but stay dormant until you set `grafana.sidecar.alerts.enabled: true`, and enabling them forces a second choice: `grafana.sidecar.alerts.notificationOwner` must be `active` or `shadow`. Exactly one Grafana in an estate should be `active` and deliver notifications. A `shadow` install evaluates every rule and shows its state, but an always-on mute route stops it paging anyone, which is how a second stack observes the same fleet without doubling every page.

Once enabled, the rule groups cover these areas:

| Area | Rule groups | What they watch |
| --- | --- | --- |
| Application and ledger | `Application`, `Blockchain`, `BlockchainHealth` | Log volume and absence, route errors and latency, ledger heap, block lag, sync, and peers |
| Data layer | `PgBouncer`, `PostgresAvailability`, `RedisConnectivity` | Pool exhaustion, PgBouncer and Postgres availability, replica lag, Redis connectivity |
| Indexer | `Didx`, `DidxCanton`, `DidxDirectoryLineage`, `DidxLive`, `DidxNativeBalance` | Runner socket failures, a dropped head WebSocket, a chain no pod owns, Canton ingestion that failed, halted or stalled, directory conflicts, indexing lag, wallet balance |
| Transactions and wallets | `AccountAbstraction`, `FundingPause`, `TransactionRecovery` | Missing or unfunded bundler wallets and dropped bundles, funding requests that stay open or expire unfunded, and requests stuck on a used, held or unknown nonce slot, wedged nonce lanes and stale dead letters |
| Delivery and identity | `Webhooks`, `OnboardingDeploy`, `EstateIdentity`, `RpcPool` | Webhook backlog, stuck deploys, slug conflicts, RPC health |
| Settlement and trading | `Settlement`, `TradingVenue` | Failed XvP and token-sale workflows, and scheduled market transitions and dated market changes that failed or applied late |
| Market data | `MarketData` | Stale exchange rates, price feeds past their staleness bound, a failing stale-feed sweep |
| Platform guardrails | `Security`, `Migrations` | Kyverno quorum, latency, denials and admission heartbeat, and migration failures |
| Infrastructure | `Infrastructure`, `Velero`, `Heartbeat` | Crash loops, replica mismatches, resource pressure, cert expiry, backups, heartbeat |

Two families of absence rules fire on silence instead of a threshold: per-service log-ingest rules for streams that stop arriving, and a per-cluster heartbeat for a whole cluster that stops reporting. They exist because a broken telemetry path silences every log-based alert without any signal of its own.

Delivery goes to Slack in one of two modes. Webhook mode posts everything to one channel through `grafana.sidecar.alerts.slackUrl`. Bot mode routes critical and warning alerts to separate channels with runbook and dashboard links. It reads its token from the `grafana-alerting-slack-token` Secret, which the chart only renders from a chart value as a development convenience. Supply the token through your own secret machinery in a real environment, and never through a values file in version control.

Tune before trusting: the thresholds under `dalp.observability` are starting points. `LowOperatorWalletBalance` has no threshold value: it compares each operator wallet with the low-balance mark the platform publishes for each network, 0.1 whole units of the network's native currency whatever its decimal precision, the same mark the Console payer status uses. The chart refuses to render while `nativeBalance.lowThreshold` is still set.

`webhooks.queueDepthThreshold` defaults to 500, and `webhooks.overdueMsThreshold` defaults to 300000 milliseconds (5 minutes). These control the backlog and stalled-delivery alerts. `transactionReports.queuedWindowSeconds` defaults to 900 seconds (15 minutes), the reporting window a regulator transaction report may stay queued before `TransactionReportsQueuedTooLong` fires. Set it to your regulator's deadline. `kyverno.admissionLatencyHighSeconds` defaults to 7 seconds, below the admission webhook's 10-second timeout.

`webhooks.queueDepthThreshold` also carries a ceiling the others do not: the gauge it compares against saturates at 50000, so a threshold at or above that value could never fire, and the chart refuses to render one that high.

Two lists must also match your deployment. The log-ingest rules generate one rule per entry of `dalp.observability.logIngest.services`, whose default names the platform's own service containers: `dapi` (the Platform API), `dapp` (the Console), and `docs` (this documentation site). An install that does not deploy one of them must trim the entry, or that rule fires forever. The heartbeat rules generate one per entry of `dalp.observability.heartbeat.clusters` and default to none, because the chart cannot infer which clusters are supposed to report into it.

## One stack for several clusters [#one-stack-for-several-clusters]

The bundled stack is sized for one instance's telemetry in one cluster. To aggregate a fleet, run one central stack and put edge installs into forwarding mode. Set `alloy.forwardingMode.enabled: true` and `alloy.forwardingMode.otel.url` to the central Alloy's endpoint, and every signal copies there while the local stores keep working, so an edge cluster stays diagnosable on its own even when the link is down. Signals a cluster does not need locally can be switched off individually under `alloy.endpoints.internal`.

The central side does not authenticate its inbound traffic by default: the standard OTLP receiver on 4317 (gRPC) and 4318 (HTTP) takes unauthenticated traffic from anywhere that can reach it, in-cluster or not. Setting `alloy.receiver.auth.enabled: true` and `alloy.receiver.auth.username` adds a second, authenticated OTLP receiver on ports 4320 (gRPC) and 4321 (HTTP) with basic auth.

The standard 4317 and 4318 stay open and unauthenticated alongside it, because enabling the auth receiver does not close them. Restrict ports 4317 and 4318 to the platform namespaces with a NetworkPolicy when the cluster is reachable from outside.

Both ends read their passwords from Secrets the chart deliberately does not create, `observability-receiver-basic-auth` on the receiving side and `observability-forwarding-basic-auth` on the sending side. Create each Secret, holding a single `password` key, before the install that enables it.

Rotating either password needs an Alloy pod restart, because the container reads it from its environment, and the config reloader only watches configuration.

## Troubleshooting [#troubleshooting]

**helm install fails at render time asking for identity values**

Four distinct messages come from the same guard, and each names its own fix. A `required` error naming
`global.dalpInstance` or `global.deploymentEnvironment` means the value is missing. Set it. `global.dalpInstance must
be a 1-63 character lowercase slug` means the slug is set but shaped wrong. It must be lowercase letters, digits, and
hyphens, starting and ending with a letter or digit. `global.deploymentEnvironment must be local, development, test,
staging, demo, or production` means the environment value is set but does not match one of those six; typing `prod`
instead of `production` is the common miss. A message naming the slug and the environment together, ending "reserved
for local installs", means the slug `local` reached a non-local environment. Give the deployment its own stable slug
instead. Fix the value the message names rather than working around it: every one of these failures is a signal that
would otherwise surface as corrupted fleet dashboards weeks later.

**helm install fails at render time complaining about webhooks.queueDepthThreshold**

`dalp.observability.webhooks.queueDepthThreshold` must be a whole number from 0 up to, but not including, 50000. The
gauge it compares against saturates at 50000, so a threshold at or above that cap could never fire. A non-numeric
value would otherwise coerce to 0 and page on the first pending row that lingers 15 minutes, so the chart fails the
render instead. Set the threshold to a whole number below 50000.

**The render fails after I supplied my own Alloy extraEnv list**

Helm replaces list values wholesale, so your `alloy.alloy.extraEnv` list dropped the chart's Secret-backed password
entries, `RECEIVER_PASSWORD` and `FORWARDING_PASSWORD`. The chart fails the render when receiver auth or forwarding
auth is enabled and its entry is missing, because catching the values mistake at deploy time beats discovering it as
authentication failures on a live receiver. Repeat the chart's entries inside your own list alongside your additions.

**Grafana is up but the service dashboards are empty**

The stack shows what reaches it. Before the `dalp` release lands, empty is correct. Once it is installed, check
placement and endpoints: the platform's export defaults target `obs-alloy` in `monitoring`, so a stack in a different
namespace receives nothing until each signal's export endpoint on the platform release is overridden to match. Cluster
dashboards are the control here. They draw on Alloy's own scrapes and fill in regardless of the platform. Cluster data
with no service data points at the export path, while no data at all points at the stack itself.

**A log-ingest absence alert fires and never resolves**

Two different causes generate this alert, and each needs a different fix. `dalp.observability.logIngest.services`
lists the services the rule expects to hear from. A service the deployment never runs produces a stream that never
arrives, so trim the list to the services deployed. Separately, `dalp.observability.logIngest.namespaces` (falling
back to `alloy.podDiscovery.namespaces`, then `alloy.rbac.namespaces`) names the namespaces each service must report
from, and the rule emits one series per namespace, so it fires when a single namespace goes dark rather than only when
every namespace does. A namespace in that list that never runs the service fires forever regardless of the services
list. Do not confuse either key with `alloy.dalp.logIngest.services`, which drops the stdout scrape for the same
container names and must never list a workload that does not export OTLP, the ledger node, proxies, and policy
controllers included. The fix in every case is a values change and an upgrade. Do not silence the alert.

**Alerts are enabled but nothing reaches Slack**

Check ownership first: a `notificationOwner` of `shadow` mutes all delivery by design, and only an `active` owner
pages. Then check the delivery mode: webhook mode needs `grafana.sidecar.alerts.slackUrl` set, and bot mode needs the
token present in the `grafana-alerting-slack-token` Secret. A rule that fires in Grafana with nothing delivered points
to one of these two configurations.

## Frequently asked questions [#frequently-asked-questions]

### Can several DALP deployments share one stack?

Yes. Every signal carries its `global.dalpInstance` slug, so two deployments in the same Grafana stay on separate dashboards and alert groups as long as neither reuses the other's value. A deployment in the same cluster can point straight at this stack's receiver. A deployment in another cluster reaches it through forwarding mode instead: it keeps running its own local stack and relays a copy here, with the authenticated receiver turned on this side.

### What does changing the slug cost once the deployment has history?

The stamped `global.dalpInstance` value is how every earlier signal ties back to this deployment. Changing the slug starts a second identity. Existing history retains the old slug. New signals use the replacement. Treat the slug as fixed for the life of the deployment.

### Can I install this chart after the platform chart instead of before?

Yes. The platform chart is `dalp`. A DALP instance exports whether or not anything is listening, so the platform drops telemetry until this chart's receiver exists and resumes once `obs-alloy` answers in the `monitoring` namespace. The platform release needs no restart. Installing this chart first avoids that gap, so on a new deployment install it first.

### Do I need to enable alerting to get value from this chart?

No. Dashboards and their cross-linked datasources come up as soon as the release installs: cluster panels show data immediately, and service panels fill in once the `dalp` release starts exporting to it. Alerting is a separate step. It stays dormant until `grafana.sidecar.alerts.enabled` is set, and turning it on forces a second choice, `active` or `shadow`, so a working install and a paging install are separate decisions.

### What happens to the 30Gi of stored telemetry when I uninstall?

It stays. VictoriaLogs, Tempo, and VictoriaMetrics each use a stateful workload with its own persistent volume claim. `helm uninstall` removes the release's pods and services but leaves those claims. Kubernetes retains their storage after the workload is removed. The three 10Gi claims stay bound and billable until you delete them with `kubectl delete pvc`. A reinstall with matching claim names can reuse the retained data. A complete teardown also requires a deliberate decision about those claims and their underlying volumes.

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

- `kubectl get pods --namespace monitoring` shows the components you enabled, all named with the `obs-` prefix, reaching `Running`.
- Grafana opens on the host you configured, and you can sign in with the admin values you set.
- The home page is the provisioned "Start Here · Fleet & Instance Overview" dashboard.
- Cluster dashboards show data immediately, because Alloy scrapes node and pod metrics itself.
- Service dashboards fill in once the `dalp` release is installed and exporting. Metrics arrive within about a minute of the first pod starting, on the platform's default 60 second export interval.
- A healthy stack shows no service data before you install the platform, and that is expected.


# OpenShift

Source: https://docs.settlemint.com/docs/deployment/install/openshift
Apply the OpenShift values overlay to run the DALP chart under a restricted security context and Routes instead of ingress.

To run DALP on OpenShift, install the same `dalp` chart with its `values-openshift.yaml` overlay layered over your values. The overlay runs every pod under the `restricted-v2` Security Context Constraint (SCC), the OpenShift admission policy that governs a pod's identity and capabilities, and serves traffic through OpenShift Routes instead of ingress or Gateway API, so the Gateway API CRD bundle is not needed.

## Apply the values overlay [#apply-the-values-overlay]

The overlay ships inside the chart package. Pull and unpack the chart, then apply the overlay as a second values file over your own, in this order:

```bash
helm pull oci://pkg.distribution.settlemint.com/settlemint/dalp --version <chart version> --untar
helm install dalp ./dalp \
  -f values.yaml \
  -f ./dalp/values-openshift.yaml
```

The overlay ships local test hostnames under `apps-crc.testing`. Before you install anywhere but a local CodeReady Containers cluster, set every `openShiftRoute.host`, `global.dalpApp.config.app.http.url` and the `https://dapi.apps-crc.testing` entry in `global.dalpApp.config.auth.consoleUrls`, as [Preconditions beyond the security context](#preconditions-beyond-the-security-context) describes with the other prerequisites.

The `observability` chart installs as its own release, so it ships its own `values-openshift.yaml` beside its `values.yaml`, layered the same way:

```bash
helm install observability ./observability -f values.yaml -f ./observability/values-openshift.yaml
```

A `dalp` release never reads another chart's values, so these overrides take effect only in the release of the chart that owns them. Preview the output first: run `helm template` with the same flags in place of `install`.

The overlay declares empty `runAsUser`, `runAsGroup` and `fsGroup` fields globally, so no chart introduces a fixed identity. It sets `runAsNonRoot: true` and `seccompProfile: RuntimeDefault` at both pod and container level, and `allowPrivilegeEscalation: false` with all capabilities dropped at container level. Four subcharts ship a fixed identity of their own: the block explorer's frontend (1001), PgBouncer (70), the PostgreSQL exporter (65534) and the simulator (65532). The overlay clears those fields in each chart's own block.

That global block sits under `global.securityContexts` and reaches most charts in the release through one shared merge helper: the Console and the block explorer inherit the cleared identity fields, the non-root requirement and the dropped Linux capabilities from it. Other workloads have separate security-context blocks in the overlay because their subcharts, sidecars or Jobs cannot use the shared helper. These include the block explorer's frontend, PgBouncer, its metrics sidecar, the Investor portal, the Platform API and the PostgreSQL exporter. Grafana, kube-state-metrics, VictoriaLogs and Tempo have theirs in the `observability` overlay. The Platform API's deployment templates read only `dapi.podSecurityContext` and `dapi.containerSecurityContext`, so the block the overlay sets under `dapi:` is its only source of security context. The overlay mounts no application container's root filesystem read-only. It sets `readOnlyRootFilesystem: true` only on the PgBouncer metrics sidecar and the PostgreSQL exporter.

## Routing [#routing]

The overlay disables ingress and serves through native Routes. Every workload that serves HTTP has its own `openShiftRoute` block that sets the host, labels and TLS, and not every one ships turned on. The Console, the block explorer's frontend and the docs site enable `openShiftRoute` by default. The block explorer's API and the Platform API disable it by default. The Console reaches the Platform API inside the cluster, and most integrators use the Console's API path. Set `dapi.openShiftRoute.enabled` to `true` only when integrators must call the Platform API directly. Gateway API `httpRoute` is disabled for the Platform API on OpenShift, and Routes replace it. The Console Route sets an HAProxy router timeout of 5 minutes, above the worst-case create and write latency, so a slow request completes instead of returning a 504.

[Figure] The request path from a browser to a Console pod under the OpenShift overlay. A browser sends an HTTPS request to the Route host. The Route terminates TLS at the router and redirects any plain HTTP request to HTTPS instead of serving it. It then forwards the request into the cluster as plain HTTP, first to the Service, a ClusterIP with no external exposure of its own, then to a pod. That pod runs under the restricted-v2 security context: non-root, no added Linux capabilities, and a user and group ID that OpenShift assigns rather than the chart. Labels: Browser; Sends a request; HTTPS; TLS terminates here; The route; Plain HTTP redirected; to HTTPS, not served; HTTP; Service; ClusterIP only; Pod; restricted-v2 SCC; Non-root, no added; capabilities.

A browser's HTTPS request ends at the Route, continues as plain HTTP through the Service, and reaches a pod running under restricted-v2.

Every Route in the overlay terminates TLS at the router with `termination: edge` and `insecureEdgeTerminationPolicy: Redirect`: HTTPS ends at the OpenShift router, traffic continues unencrypted inside the cluster over the Service network, and a plain HTTP request is redirected to HTTPS. The chart does not restrict this value. The Route template passes your `tls` block through unchanged, so `passthrough`, where the original TLS session reaches the pod, or `reencrypt`, where the router terminates TLS and encrypts again to the pod, needs no template edit. Passthrough requires TLS at the pod. The Console service port uses plain HTTP, so changing the Route value alone cannot enable passthrough. Reencrypt also needs a `destinationCACertificate` and a pod that serves TLS on the port the Route re-encrypts to.

## LimitRange floor [#limitrange-floor]

A namespace `LimitRange`, a separate admission check from the `restricted-v2` SCC, sets the lowest CPU and memory each container may request and rejects any request below it. The chart's own defaults fall under a common floor of 100m CPU and 128Mi memory in several places: the Conjur authenticator init container ships 10m CPU and 32Mi memory. The overlay raises the containers in the table to at least that floor. The Conjur and Console blocks in the example show the shape of the overlay's `resources` keys, and the other containers follow the same pattern. These are the overlay's values, and they replace the base chart's sizing in [Resource sizing](https://docs.settlemint.com/docs/deployment/prerequisites#resource-sizing-starts-from-the-chart-defaults).

```yaml
global:
  conjur:
    resources:
      requests:
        cpu: "100m"
        memory: "128Mi"
      limits:
        cpu: "200m"
        memory: "256Mi"

dapp:
  resources:
    requests:
      cpu: 100m
      memory: 256Mi
    limits:
      cpu: "1"
      memory: 512Mi
```

| Container | CPU / memory request | CPU / memory limit |
| --- | --- | --- |
| Conjur authenticator init container | 100m / 128Mi | 200m / 256Mi |
| Console | 100m / 256Mi | 1 CPU / 512Mi |
| Console migrator Job | 100m / 256Mi | 500m / 512Mi |
| Console `tcpCheck` init container | 100m / 128Mi | 300m / 128Mi |
| PgBouncer metrics sidecar | 100m / 128Mi | 200m / 128Mi |
| Platform API `/api/v2` fleet | 600m / 1536Mi | 1500m / 3Gi |
| Platform API `/api/v1` fleet | 300m / 768Mi | 1000m / 1536Mi |
| Runner | 250m / 1536Mi | 1500m / 3Gi |
| Indexer | 1250m / 1536Mi | 2000m / 3Gi |
| contracts-deploy Job | 250m / 1Gi | 2 CPU / 4Gi |
| PostgreSQL exporter (disabled unless you turn it on) | 100m / 128Mi | 200m / 128Mi |

Compare your namespace's `LimitRange` floor with every container in the table before you deploy. A floor set higher than the overlay's requests rejects the pod at admission, and the workload controller reports a failed pod creation with an admission event naming the container and invalid request. A floor set lower still admits the pod but wastes the headroom the overlay already budgeted. For how the Conjur authenticator init container receives its credentials, see [Values and secrets](https://docs.settlemint.com/docs/deployment/install/values-secrets).

## Preconditions beyond the security context [#preconditions-beyond-the-security-context]

For an air-gapped OpenShift deployment, serve the chart and every image from a registry inside your network, in addition to the SCC and LimitRange settings. List the images a release uses with `helm template dalp ./dalp -f values.yaml -f ./dalp/values-openshift.yaml | grep 'image:' | sort -u`, and mirror each one by digest. Confirm every image reference, init and utility images included, carries an explicit registry and repository plus a tag or digest, because an air-gapped cluster cannot resolve an implicit public registry. The overlay supplies mirrored-registry overrides for the `kubectl` helper and the Conjur authenticator. A correct registry override cannot load an image whose digest is missing from the mirror.

The Platform API, the Workflow Engine, Ledger Data and the scheduler run as separate images, each with its own repository value and each distroless with no shell, so a mirrored registry needs all four. Any entrypoint wrapping these images, including the Conjur `summon` injection described in [Values and secrets](https://docs.settlemint.com/docs/deployment/install/values-secrets#secret-injection-conjur), must run in exec form, not through `/bin/sh -c`.

Every Route host, the Console public URL and the direct Platform API Route origin ship as placeholder `apps-crc.testing` hostnames, the domain a local CodeReady Containers cluster serves. Applying the overlay unchanged renders Routes on hostnames no production cluster serves. Override every `openShiftRoute.host`, `global.dalpApp.config.app.http.url` and the `https://dapi.apps-crc.testing` entry in `global.dalpApp.config.auth.consoleUrls`. When you enable the Investor portal, also set `global.dalpApp.env.INVESTOR_PORTAL_URL` to its public Route host: the overlay ships no value for it, and the render fails without one.

Set the Console public URL only in `global.dalpApp.config.app.http.url`. The Console and the Platform API both read that one value: the Console sends it as the origin of its server-side calls, and the Platform API accepts a Console session only from the origins it lists. Give it as a plain `https://` URL. The chart refuses to render `dapp.config.app` or `dapi.config.app`, a `${...}` variable in the URL, or a Helm template expression anywhere in `global.dalpApp.config`, because a second copy of the URL, or one that resolves differently per component, lets the two disagree and signs every user out on a full page load.

The `observability` overlay pins the storage classes of VictoriaMetrics and VictoriaLogs to one name, `standard-csi`. Without a StorageClass named `standard-csi`, those PersistentVolumeClaims stay `Pending`, and their provisioning events name the missing class. Set `server.persistentVolume.storageClassName` for VictoriaMetrics and VictoriaLogs to a class your cluster provides.

The overlay also turns on deny-by-default egress for two workloads: `dapp.networkPolicy.enabled` and `investorPortal.networkPolicy.enabled` both become `true`. The Console policy declares both `Ingress` and `Egress` policy types, and its egress allow list selects pods only, which covers same-namespace, chart-deployed dependencies. It does not reach an object store, an SMTP relay or a database outside the cluster. Before you apply the overlay, add `ipBlock` peers for those external dependencies to `dapp.networkPolicy.egress`, and to `investorPortal.networkPolicy.egress` when the portal is enabled. An endpoint missing from the allow list cannot be reached, and the blocked connection produces no admission error.

## Browser apps with user sessions [#browser-apps-with-user-sessions]

When the Console and the Investor portal use separate Routes, each app serves `/api` and `/dalp` on its own host and forwards to the private `DAPI_INTERNAL_URL`. The Investor portal needs no platform URL of its own: its server forwards the browser's `/api` and `/dalp` calls to `DAPI_INTERNAL_URL` in `investorPortal.env`, which defaults to the in-cluster `http://dalp-api:3001`. Do not configure a public `DAPI_URL` for the Portal. [Deploy browser apps with user sessions](https://docs.settlemint.com/docs/deployment/install/browser-apps) lists the values, and [the SDK browser guide](https://docs.settlemint.com/docs/api-reference/sdk/browser-apps) shows the proxy handler.

## Troubleshooting [#troubleshooting]

[Figure] Where in the pod lifecycle an OpenShift deployment failure lands. If the deploy fails or a pod stays unhealthy, start with when the failure happens rather than how it looks. A rejection before the pod object exists is an SCC error, the only case with no pod yet to inspect. A pod that exists but never starts is stuck on a LimitRange floor, a missing StorageClass, or a failed image pull, and the event attached to the pod names which. A pod that is already running and then fails points to the Route, the NetworkPolicy egress allow list, or the router timeout, none of which leave any event on the pod at all. Each case is covered in the accordions below. Labels: Rejected before it exists; Admission; The SCC denial names; the failed constraint; Created, but stuck; Never starts; LimitRange, PVC, or pull:; the event names which; Serving, then it breaks; Once running; No pod event fires: check; Route, policy, timeout.

A deployment failure lands in one of three phases: rejected before the pod exists, stuck before it starts, or failing once it is running.

**Pod rejected with an SCC or security-context error**

Check for a non-zero `runAsGroup`, `runAsUser`, or `fsGroup` still set somewhere in your values: the overlay clears
all three so OpenShift can assign compliant values itself, and a leftover fixed value anywhere in the chain overrides
that clearing. Confirm with `oc get events`: an SCC denial names the constraint it failed against, whether that is
`runAsGroup`, an added capability, or a missing `seccompProfile`.

**Pod stuck pending on resource requests**

Confirm your namespace's LimitRange floor accepts the chart's requested CPU and memory. The overlay sets minimum
requests of 100m CPU / 256Mi memory for Console and 100m CPU / 128Mi memory for Conjur. It also supplies minimum
requests for the migrator Job, `tcpCheck` init container, PgBouncer metrics sidecar, Platform API roles,
contracts-deploy Job and PostgreSQL exporter. A request below the floor is rejected at admission and not retried, so
inspect the workload controller's events for rejected pod creation as well as any existing pod's scheduling events.

**PersistentVolumeClaim stuck pending**

Confirm your cluster provides a StorageClass named `standard-csi`, the name the `observability` overlay pins for
VictoriaMetrics and VictoriaLogs. A cluster without that class leaves the PVC `Pending` with a provisioning event
naming the missing class. Point `server.persistentVolume.storageClassName` at a class your cluster has.

**Route not reachable**

Confirm the service's `openShiftRoute.enabled` matches what you expect: the block explorer's own API and the Platform
API ship it `false` by default, so a missing Route for them is the shipped state. For a service you do expect a Route
on, confirm `openShiftRoute.enabled` is true and that `httpRoute`/`ingress` are not also enabled for the same service,
since only one exposure mechanism should be active at a time. Inspect every rendered Ingress, HTTPRoute, and Route
when several exposure mechanisms are enabled. Confirm which controller owns each hostname and its TLS settings.

**Console lost an external dependency after applying the overlay**

Confirm `dapp.networkPolicy.egress` (and `investorPortal.networkPolicy.egress` if the portal is on) names every
external endpoint the deployment depends on: object storage, an SMTP relay, an external database. Enabling the Console
NetworkPolicy makes egress deny-by-default, and the chart's own allow list covers only same-namespace, chart-deployed
dependencies. Anything else needs an explicit `ipBlock` peer, or its connections fail with no admission error, which
looks like a network outage.

**Console times out on a slow request instead of completing**

The Console Route's HAProxy timeout is 5 minutes by default. A request that legitimately needs longer, such as a large
asset-creation write under load, returns a 504 from the router before the application finishes. Raise
`openShiftRoute.timeout` for the affected service.

**Image pull fails on an air-gapped cluster**

An air-gapped cluster cannot resolve an implicit public registry, so any image reference without an explicit registry,
repository, and tag or digest fails to pull. Check init and utility images specifically, not only the main application
images: the `kubectl` utility image and the Conjur authenticator image both need their registry overridden to your
cluster's mirrored path. A missed override on either fails only the Job or init container that uses it, not the whole
release, which makes it easy to miss in a partial rollout.

## Frequently asked questions [#frequently-asked-questions]

### Do I need to pass both values files, or does the overlay stand on its own?

Both, in that order: `-f values.yaml -f ./dalp/values-openshift.yaml`. The overlay carries only the fields that differ under `restricted-v2` and Routes. Every field it does not mention, such as image tags, replica counts, and feature flags, still comes from the base file. Helm always loads the chart's built-in defaults. Pass your deployment-specific base values before the overlay so those settings are retained and the OpenShift overrides take precedence.

### Is restricted-v2 mandatory, or does this overlay also work under a less restrictive SCC?

The overlay is written for `restricted-v2`, and the chart does not enforce it. The overlay clears fixed identities, drops capabilities and runs as non-root, which a less restrictive SCC also admits. Verify admission against the SCC assigned in your cluster, including any local policy additions.

### Can I raise the Conjur authenticator's resources further if my namespace needs more than the overlay sets?

Yes. `global.conjur.resources` sets one shared floor for every Conjur-enabled pod. Add your own values file on top of the overlay, the same way the overlay itself raises the chart's base default, and your values take precedence. Raising it further needs nothing overlay-specific.

### Does disabling ingress also disable the Kubernetes Service, cutting off traffic inside the cluster?

No. Ingress and Routes control external exposure only. Disabling `ingress.enabled` leaves the Service each chart creates in place, so traffic inside the cluster keeps working as it does off OpenShift.

### Does upgrading an existing OpenShift install need anything beyond the normal upgrade path?

No overlay-specific step: run `helm upgrade` with the same two values files, the way you would for any other release. See [Upgrades and migrations](https://docs.settlemint.com/docs/deployment/upgrades-migrations) for the rollout and migration-Job mechanics that apply regardless of platform.


# Values and secrets

Source: https://docs.settlemint.com/docs/deployment/install/values-secrets
Set the DALP Helm chart's datastore, TLS, and secret-manager values, and choose how secrets reach each pod.

This page sets the datastore, TLS and secret values of the `dalp` chart, and says how each secret reaches its pod. Read it before your first `helm install` with [Install the DALP Helm chart](https://docs.settlemint.com/docs/deployment/install/helm-charts), because a release does not render or does not start until some of these values are set.

Four values block a release until you set them:

| Value | Ships as | Without your own value |
| --- | --- | --- |
| `ENCRYPTION_MASTER_PASSWORD` | Empty | Every pod refuses to start |
| `BETTER_AUTH_SECRET` | A published placeholder | A production pod refuses to start on the placeholder |
| `CUSTODY_CREDENTIAL_IDENTITY_KEY` | A development placeholder | A production pod refuses to start on the placeholder |
| `global.dalpApp.env.DALP_GOVERNANCE_DOMAIN_SCOPE` | Empty | `helm install` and `helm upgrade` fail the render |

[Encryption at rest](#encryption-at-rest), [Custody credential identity key](#custody-credential-identity-key) and [Governance ballot domain](#governance-ballot-domain) describe each check. The secret-manager provider ships as `local`, which does not block the install and keeps application secrets in the platform's own database on a production deployment. Review datastore TLS, credentials, connection capacity and the secret delivery path against the target environment before installation.

`dapi` (the Platform API) and `dapp` (the Console) are the two application subcharts this page configures most. The migrator is the `dapp` subchart's schema-migration Helm hook, a Job that runs on every install and upgrade. It appears throughout this page because two of its steps, direct database access and encryption rotation, shape the values below.

## Values structure [#values-structure]

`values.yaml` groups into a shared `global` block: observability, image-pull credentials, datastores, the embedded application config, Conjur and HTTP routing.

Each service has its own block, among them `dapi` (the Platform API), `dapp` (the Console), `blockscout` (an optional block explorer), `investorPortal` (the optional Investor portal), `investorDocs`, `canton`, `utilaSigningAgent`, `contractsDeploy`, `docs`, `backup`, `overprovisioning` and `postgres-exporter`. The PgBouncer connection pooler is a separate chart dependency that `global.pgbouncer.enabled` switches on.

`dapi` and `dapp` each carry autoscaling, image, resource and exposure settings, through ingress, a Gateway `httpRoute` on Kubernetes or an `openShiftRoute` on OpenShift.

## Services you supply [#services-you-supply]

No chart deploys a datastore, so PostgreSQL, Redis, and object storage are services you supply. The chart's default values name placeholder in-cluster hosts and passwords for them, and the platform cannot connect until services answer under those names or you replace them. Point all three at services for a production deployment: a managed service can provide replication, patching, and backups, depending on the plan and configuration you choose. Verify those capabilities and test recovery. [Topologies](https://docs.settlemint.com/docs/deployment/topologies) covers the deployment shapes.

## Datastores [#datastores]

`global.datastores` sets connections per service for PostgreSQL and Redis, either inline or through `existingSecret`. Object storage is set under `global.dalpApp.config.objectStorage`, with its keys in `OBJECT_STORAGE_ACCESS_KEY` and `OBJECT_STORAGE_SECRET_KEY`. Default passwords in the chart, such as `"dalp"` for PostgreSQL, are placeholders. Change every one before you deploy to production.

PostgreSQL TLS reads `sslMode`, and the leg it secures depends on whether pooling is on. `global.pgbouncer.enabled` defaults to `true`, and a pooled deployment removes `sslMode` from the application's own connection URL. The pooler's client listener is plaintext inside the cluster, so with pooling on the leg from the application pods to the pooler is unencrypted.

An application that tries to negotiate TLS against it fails to connect and never falls back to plaintext. Encryption on that leg needs pooling off, with `DATABASE_TLS` on the direct connections. `sslMode` sets the pooler's own upstream leg to Postgres, and the chart ships it as `disable`, so the upstream leg is plaintext by default.

The pooler accepts four values there: `disable`, `require`, `verify-ca` and `verify-full`. Any other value fails the render.

For a managed PostgreSQL on a public certificate authority, set `sslMode` to `require`. The chart maps it to `verify-full` over the image's system CA bundle, which verifies both certificate and hostname with no CA to mount. For a server behind a private certificate authority, set `sslMode` to an empty string instead, and supply the CA under `pgbouncer.upstreamTls`, the pooler subchart's own values:

```yaml
global:
  pgbouncer:
    enabled: true # umbrella gate: whether pooling exists at all
pgbouncer:
  upstreamTls:
    ca: | # the private CA's certificate, PEM-encoded
      -----BEGIN CERTIFICATE-----
      ...
      -----END CERTIFICATE-----
    # existingSecret: my-ca-secret   # or point at a Secret instead
```

An empty `sslMode` with that CA configured resolves to a verified `verify-full` connection. The shipped `disable` with a mounted CA leaves the CA unused, because `disable` passes through as it is. The application's own `DATABASE_TLS` value takes effect only on direct connections: the migrator's, or every connection when pooling is off.

## How application pods reach Postgres [#how-application-pods-reach-postgres]

Set `global.datastores.default.postgresql.maxConnections` to your PostgreSQL server's real `max_connections`. The chart sizes the pooler's server connections against that number and fails the render when they do not fit.

A central transaction-mode connection pooler, PgBouncer, sits between every application pod and Postgres.

Each process role has its own pooler alias with its own fixed pool: `dalp_api` for the API role, `dalp_indexer` and `dalp_indexer_rebuild` for chain ingestion, `dalp_runner` and `dalp_scheduler` for background work, `dalp_app` for the Console, `dalp_cluster` for the storage traffic of the platform's durable-execution engine for background jobs, and `dalp_probe` for the health-probe connection.

A pod holds pooler client connections against that fixed pool, with a ceiling of 3,000 clients per pooler process (`pgbouncer.pool.maxClientConn`), and no steady direct Postgres backend of its own. Raising `dapi`'s replica count changes that client load and leaves Postgres's own `max_connections` untouched.

The chart pins the pool, reserve and hard-cap values for each alias, and checks two bounds when it renders. A render fails if either one is broken:

- **Server side.** Every alias's `max_db_connections` across the peers, plus `pgbouncer.pool.directConnections` (26), plus 3 reserved superuser slots, must fit `global.datastores.default.postgresql.maxConnections`. The defaults use 371 of 400: at the pinned `replicaCount` of 2 times `processCount` of 1, that is 342 alias connections, 26 direct and 3 reserved.
- **Client side.** A role's pods at their replica ceiling, times the per-pod pool, may hold at most `pgbouncer.pool.clientOversubscription` (8) clients per server connection of its alias. For the API role that is 28 pods times 40, so 1,120 clients onto 140 server connections.

The server-side check knows only the `maxConnections` you declare. The chart declares 400, which is a placeholder and not a reading of your server. A server configured lower than the declared value still accepts the deployment, and starts failing individual connections once traffic passes its ceiling. `PostgresAggregateBackendsHigh` in the observability chart watches the real server. Watch your server's connection count through `postgres-exporter` or `pg_stat_activity` before and after the change.

The migrator connects to Postgres directly, without the pooler, because its schema-migration locks are session-scoped and cannot survive a transaction-mode pooler. `postgres-exporter` holds one direct session by default too, to report the server's aggregate backend count.

Blockscout, an optional block explorer that ships disabled (`blockscout.enabled: false`), holds the largest direct share once you turn it on: 20 sessions. The indexer also opens up to 4 direct sessions for concurrent index builds. Blockscout's 20, the exporter's 1, the migrator's 1 and the index builds' 4 sum to the 26 direct connections in `pgbouncer.pool.directConnections`.

Enabling Blockscout adds its configured pool to the database connection budget.

A saturated pooler queues clients before it rejects them, so the signal to watch is a growing client queue. The `observability` chart's alert rules catch that. `PgBouncerClientsWaiting` pages after one minute of continuous queueing. `PgBouncerClientMaxWait` pages when the oldest queued client has waited more than one second for 10 seconds, so it is the earlier signal.

PgBouncer rejects a queued client at its 10-second `queryWaitTimeout`, ahead of the application role's 30-second statement timeout and the 60-second HTTP deadline. `PgBouncerDeploymentAbsent` and `PgBouncerDown` page separately when the pooler itself goes missing or becomes fully unavailable, since every application `DATABASE_URL` depends on it existing.

`PgBouncerReplicaUnavailable` catches the state between those two: it fires when redundancy stays below target for 3 minutes while at least one replica still serves, which halves pool capacity without tripping either alert. Watch the exporter's own health too.

`PgBouncerMetricsAbsent` and `PgBouncerMetricsUnreadable` both mean the saturation alerts have gone silent, because they read the same telemetry the exporter reports. Treat silence from them as unproven until the exporter is confirmed up.

These alerts ship in the `observability` chart, not in `dalp`, and fire only once you install it and switch its alert rules on, as [Install the observability stack](https://docs.settlemint.com/docs/deployment/install/observability-stack) describes.

With pooling off, `global.pgbouncer.enabled: false`, application traffic uses direct Postgres connections, sized by each role's own pool-size setting, and the pooler alerts stop applying. `PostgresAggregateBackendsHigh` watches the server in both cases and pages at 80% of `max_connections`. Size the change against `max_connections` by hand before you apply it.

### Pooler requirements for prepared statements [#pooler-requirements-for-prepared-statements]

Application connections through the pooler use named prepared statements. A connection prepares a statement once and reuses its name, so PostgreSQL plans each statement once per server connection instead of on every call. The pooler must track those names across the server connections it hands out.

The chart's pooler does. It runs PgBouncer 1.26 with `max_prepared_statements` at 512 (`pgbouncer.pool.maxPreparedStatements`). Each application connection keeps at most 100 statements prepared (`global.dalpApp.config.database.preparedStatementCacheSize`). Keep the pooler limit at or above that cache size.

A pooler you supply must track named prepared statements in transaction mode. PgBouncer 1.21 and later does when `max_prepared_statements` is above 0. These setups do not:

- PgBouncer before 1.21, or with `max_prepared_statements` at 0.
- Any pooler in statement mode.
- A pooler that pins the session to one server connection on its first prepared statement, such as RDS Proxy. Pinning removes the connection reuse the pooler exists for.

With one of those, set `global.dalpApp.config.database.preparedStatementCacheSize` to `0`. Pooled application connections then send every statement unprepared. Direct connections, such as the migrator's, never pass through the pooler, ignore this value and keep preparing.

A migration that changes a column's type invalidates the statements the pooler prepared before it. The first run of each such statement inside a transaction fails with `cached plan must not change result type`, once for each application process. That process then sends the statement unprepared, and a retry of the failed request succeeds. Restarting the application pods does not avoid the first failure, because the pooler keeps the old statement on its server connections.

PostgreSQL can switch a prepared statement to a generic plan after five executions. On a large, uneven database a few statements can run slower on that plan. If one does, set `plan_cache_mode` to `force_custom_plan` on the application role with `ALTER ROLE ... SET`. Role settings reach pooled connections. Connection startup options do not. This gives back the planning time that prepared statements save.

## Secret injection: Conjur [#secret-injection-conjur]

[Figure] Two secret systems, each with its own value and its own consumer. Two columns. On the left, Conjur and summon deliver deployment secrets when Conjur is switched on. A Conjur authenticator init container fetches an access token, then summon injects the resulting secrets as environment variables at process start, gated on that init container plus a conjur-certificate ConfigMap present in the namespace before the pod starts. Miss either one and the pod crash-loops at startup, naming the environment variable summon never injected, a faster signal than the underlying Conjur connectivity failure. On the right, the application's own secret-manager setting is a separate decision: pick one of local, aws, gcp, azure, or vault, and that choice decides where application-level secrets live at rest, independent of Conjur entirely. The highest-stakes value in this second system is the encryption master password, boxed below the provider choice. Rotate it in two steps: set the outgoing password as ENCRYPTION_PREVIOUS_MASTER_PASSWORD for the migration Job only, keep the new one as ENCRYPTION_MASTER_PASSWORD, then deploy. The migration Job decrypts with either key and re-seals every row under the new one before runtime pods start with only the new key. The migrator's rotation boot step runs automatically on that same deploy. Only remove the old password once that job succeeds, not just once its summary lines look clean. Removing it too early fails the next deploy loudly rather than silently losing data. Only the master password itself being lost makes a row permanently unreadable. A closing bar beneath both columns states the risk of getting the secret-manager provider wrong: mismatch it against your existing practice and you run two separate secret stores with two separate audit trails. Labels: Deployment secrets and application secrets differ; Two secret systems; Conjur / summon; Injected at pod start; Deployment secrets only; as env vars at process start; Init container fetches a token; summon injects the result; Missing cert: pod crash-loops; Named env var is the fast signal; Secret-manager provider; Application secrets at rest; One of five providers; local, aws, gcp, azure, vault; Master password; Two-step rotation: old key, then new; Drop the old key only after; the job succeeds; Two separate secret stores, two separate audit trails; Mismatching the provider against your practice runs both at once.

Conjur and summon deliver deployment secrets at pod start, while the application's secret-manager provider places
application-level secrets at rest.

By default the chart renders the application secrets in `global.dalpApp.env` into one shared Kubernetes `Secret` that the Console and Platform API pods read, and each datastore block can read its password from a Secret you name in `existingSecret`. CyberArk Conjur is an opt-in path: `global.conjur.enabled`, or a service's own `conjur.enabled`, switches a service to Conjur and `summon`, and both ship `false`.

`summon` is Conjur's command-line tool. It reads a `secrets.yml` mapping of environment variable names to Conjur paths, resolves each path against Conjur, and starts the service process with the resolved values in its environment. With Conjur on, each pod runs a Conjur authenticator init container that fetches an access token, and `summon` injects the secrets as environment variables at process start.

Declare each service's secrets under `<service>.conjur.secrets`, a map of environment variable names to Conjur paths. The chart renders that map as a `<release>-<service>-conjur-secrets` ConfigMap, mounts it as `/etc/summon/secrets.yml` and wraps the container's entrypoint with `summon`. Changing a mapping is a values change and a pod restart. A service with no `conjur.secrets` entries runs without `summon`.

The published DALP images do not include `summon` or `summon-conjur`. The Conjur path needs images built on top of them with `summon` at `/usr/local/bin/summon` and the `summon-conjur` provider at `/usr/local/lib/summon/summon-conjur`. It also needs the authenticator init container and a `conjur-certificate` ConfigMap in your release namespace before you deploy.

A pod that starts before its Conjur authenticator init container can reach the Conjur server, or before the `conjur-certificate` ConfigMap exists, fails at process start and never starts with empty secrets. Its crash loop names the environment variable `summon` did not inject, which shows sooner than the Conjur connectivity failure behind it. Check the init container's logs first, because the main container's log shows only the symptom.

## Application secret-manager providers [#application-secret-manager-providers]

The application's own secret-manager setting is a separate choice from the delivery path in [Conjur secret injection](#secret-injection-conjur). It selects one provider: `local`, `aws`, `gcp`, `azure` or `vault`. Selecting a provider makes its configuration block required. For example, selecting `vault` requires a token, and selecting `aws` accepts an access key ID, region and secret access key.

`local` keeps application secrets encrypted under the master password in the platform's PostgreSQL database. Choose it only for development. For production, choose the one of `aws`, `gcp`, `azure` or `vault` that matches infrastructure you already operate, with rotation and audit practices in place for it. This setting decides where application-level secrets live at rest, as opposed to the deployment secrets that reach the pods at start. A provider that differs from your existing practice leaves you with two secret stores and two audit trails.

## Encryption at rest [#encryption-at-rest]

The application requires a master password for encryption at rest. Config decode enforces a 16-character floor, but the encryption service applies a stricter check on top of it at pod startup: a minimum of 128 bits of estimated entropy. A 16-character password can still fail there if it is guessable, so generate one from a cryptographic random source, for example `openssl rand -base64 32`, and store it in your secret manager. The platform rejects the password it uses for local development on any pod whose `NODE_ENV` is not `development`.

`BETTER_AUTH_SECRET` ships with the published placeholder `"strong-secret-of-at-least-32-characters"`. A production pod checks the resolved value against that exact string and fails with "`BETTER_AUTH_SECRET` must be set to a unique value in production". Set your own value of at least 32 characters before production. Never change `ENCRYPTION_MASTER_PASSWORD` or `BETTER_AUTH_SECRET` on an existing environment outside the supported rotation procedure. The master password protects encrypted application data and the auth secret protects authentication material, so changing either another way can break access. A new key alone cannot decrypt data encrypted under a lost key.

Rotate the master password in two steps. Set the outgoing password as `ENCRYPTION_PREVIOUS_MASTER_PASSWORD` for the migration Job only, through `dapp.migrator.env` or, with Conjur, `dapp.migrator.conjur.secrets`, which the chart merges over the runtime `dapp.conjur.secrets` map so the Job keeps the current key.

Keep the new password as `ENCRYPTION_MASTER_PASSWORD`, then deploy: the migration Job can now decrypt with either key, so it reads every row sealed under the outgoing one. Runtime pods never receive the previous password. The migrator runs as a Helm hook on every install and upgrade.

One of its required boot steps, `rotate-encryption`, scans every encrypted row and rewrites it under the new key whenever `ENCRYPTION_PREVIOUS_MASTER_PASSWORD` is set. No separate command is needed. The same deploy's migration Job re-seals the data.

It logs an `Encrypted secret rotation summary` line, and a matching `KYC encryption rotation summary` line, each with `scanned`, `rotated`, `skipped`, and `failed` counts, and fails the job if any row fails. Use the migrator's successful exit as the completion signal. The Job also verifies KYC documents after rotation and can fail even when both rotation summaries show zero failures.

Wait for the Job to succeed, not just for those two lines to look clean, before you remove `ENCRYPTION_PREVIOUS_MASTER_PASSWORD`. Removing it too early does not silently destroy data: the next deploy's rotation step checks for leftover pre-rotation rows and fails loudly, naming exactly how many secret rows and KYC objects it found, rather than skipping past them.

Only the master password itself being lost makes an encrypted row permanently unreadable.

## Write-once report storage [#write-once-report-storage]

`global.dalpApp.config.objectStorage.objectLock.enabled` turns on write-once storage for archived reports. It defaults to `false`. Set `OBJECT_STORAGE_OBJECT_LOCK_ENABLED` to the same effect outside the chart.

With it on, every file a filing generates is written with a lock that lasts for the retention class of its obligation: five, seven or ten years, or 100 years for **Indefinitely**. DALP then refuses to replace or delete that file until the lock ends, and each pod refuses to start if the bucket cannot enforce the lock. The error names the bucket and what it is missing.

The lock runs from the moment the filing is generated. The retention period the platform erases by runs from the day the filing is accepted, so the lock ends slightly before that period does.

| Provider | Prerequisite on the bucket | What enforces the lock |
| --- | --- | --- |
| `aws`, `s3-compatible` | Created with Object Lock enabled | Object Lock in compliance mode |
| `azure` | Blob versioning and version-level immutability on the container | A locked immutability policy on each blob |
| `gcp` | Created with object retention enabled and object versioning off | Object retention in locked mode |
| `filesystem` | Not supported | Pods refuse to start |

Compliance mode cannot be shortened or removed by anyone, including the cloud account's root user, until the date passes. Check the setting on a test bucket first.

Before you turn it on:

- Create the bucket with the prerequisite above. Most providers can enable it only when the bucket is created.
- Leave the bucket's default retention unset. The bucket is shared with every other DALP object, and a default would lock those too. DALP sets retention on each report file itself.
- On S3, give the storage credentials `s3:PutObjectRetention`, `s3:GetObjectRetention`, `s3:GetBucketObjectLockConfiguration`, `s3:DeleteObjectVersion` and `s3:ListBucketVersions`.
- Deny `s3:PutObject` and `s3:DeleteObject` on the `reporting/` prefix to every other principal. Object Lock protects a stored version, so a client with direct bucket access could still add a newer version or a delete marker over it. The locked version stays intact and report digests expose the change, but a bucket policy stops it happening.

Keep the value on once locked files exist. With it off, DALP deletes an object with a plain delete, which on a versioned bucket hides the object and leaves its data behind.

## Switch application layers on or off [#switch-application-layers-on-or-off]

DALP sells seven application layers as licensed modules. The deployment decides which modules it offers, and that is the licence. Each switch sits under `global.dalpApp.config.features`. Each switch also reads an environment variable when you set the application config from the environment.

| Pricing layer | Value | Environment variable | Default |
| --- | --- | --- | --- |
| Primary market | `tokenSale` | `FEATURE_TOKEN_SALE` | `true` |
| Secondary market | `tradingVenue` | `FEATURE_TRADING_VENUE` | `false` |
| Market operations and compliance | `marketOperations` | `FEATURE_MARKET_OPERATIONS` | `true` |
| Reporting and finance operations | `regulatoryReporting` | `FEATURE_REGULATORY_REPORTING` | `false` |
| Market surveillance | `surveillance` | `FEATURE_SURVEILLANCE` | `false` |
| Self-custody | `custodyOps` | `FEATURE_CUSTODY_OPS` | `true` |
| Client portal | `clientPortal` | `FEATURE_CLIENT_PORTAL` | `true` |

Primary market covers offerings and fund dealing: the subscription and redemption requests of a fund and the settlement of its dealing days. Secondary market covers the trading venue. Market operations and compliance covers the audit trail views and export. Self-custody covers the custody gateway, embedded wallets and multisig wallets. Client portal covers investor sign-in to the Investor portal. Surveillance sends the live FIX copy of every order and trade to a surveillance provider, and needs the secondary market.

Everything else DALP ships is base platform: always on, with no switch. That includes issuance, corporate actions and holder votes, second-person approval of sensitive changes, and delivery-versus-payment (XvP) and escrow settlement. Bank rail and the AI assistant are not modules. Canton is neither a module nor base platform: it has its own switch, and it is off by default (see [Canton](#canton)).

A module that is off for the deployment has no screens and no API routes for any organisation. Its routes answer `404`, the same answer as a route that does not exist. A module that is on is available to every organisation until an organisation owner switches it off in Organisation settings. An organisation that switched a module off can still read its records, and the API refuses its writes with `platform.module.DISABLED`. See [Read and handle DALP errors](https://docs.settlemint.com/docs/api-reference/guides/errors#licensed-module-refusals).

A new organisation starts with every module the deployment offers ticked. Organisations that existed before you switched a module on get it too, unless they opted out of it. Switching a module off on the deployment does not stop work already in motion: scheduled payouts, trading sessions and provider syncs keep running, and only new writes through the API and the Console are refused.

```yaml
global:
  dalpApp:
    config:
      features:
        tradingVenue: true
        surveillance: true
```

## Canton [#canton]

Canton is off by default, and release 3.2 ships with it off. Set `global.dalpApp.config.features.canton` to `true`, or the environment variable `CANTON_ENABLED` to `true` when you set the application config from the environment, to turn it on. The switch is separate from the licensed modules above: no organisation can opt out of it, and Organisation settings has no row for it.

While the switch is off:

- The Console and the Investor portal show no Canton network, asset type, screen or menu.
- The Canton wallet routes (`/api/v2/wallets` and everything under it) answer `404`, the same answer as a route that does not exist. The OpenAPI document, the SDK and the CLI still list them, because they ship once for every deployment, and each of the six operations says in its description that it needs `features.canton`. A Canton command of the CLI answers `FEATURE_NOT_ENABLED` with the text "Canton is not enabled on this deployment."
- `GET /api/v2/tokens` answers `400 COLLECTION_FILTER_VALUE_INVALID` when the request selects the Canton family with `filter[family]=canton`, with a `filter[network]` that names a Canton network, or with the `X-Network-Id` header. `data.errors` says that Canton is not enabled on this deployment. The list without those selections answers from the EVM tokens only.
- Any other route that selects a Canton network is refused with `CANTON_NETWORK_NOT_CONFIGURED`.

Turning the switch on is not enough to use Canton: the deployment also needs an enabled Canton network in its network configuration and a reachable participant. See [Helm charts](https://docs.settlemint.com/docs/deployment/install/helm-charts) for the `canton` chart block.

```yaml
global:
  dalpApp:
    config:
      features:
        canton: true
```

## External-token auto-registration [#external-token-auto-registration]

`global.dalpApp.config.features.externalTokenAutoRegistration`, or the environment variable `FEATURE_EXTERNAL_TOKEN_AUTO_REGISTRATION`, decides whether the platform registers an unknown ERC-20 or ERC-3643 token on its own when it lands in a wallet an organisation manages. It is `false` by default. While it is off, a token sent to a managed wallet stays unregistered until an asset manager registers it by hand.

With it on, anyone can make the platform write a registry entry by sending a token to a managed wallet, up to 20 tokens per organisation per day, and no person confirms the entry. Turn it on only when every organisation on the deployment accepts that. See [External tokens](https://docs.settlemint.com/docs/console/asset-management/external-tokens#review-auto-detected-tokens-and-lookalikes).

## Governance ballot domain [#governance-ballot-domain]

Set `global.dalpApp.env.DALP_GOVERNANCE_DOMAIN_SCOPE` to a name that belongs to this deployment alone. The platform hashes the name into the signing domain of governance poll ballots. A ballot signed in one deployment must not verify in another, so never copy the name between installs. Changing it invalidates every ballot signed under the old name.

The chart has no default for this value. `helm install` and `helm upgrade` fail while it is empty or set to `local`. A production process also refuses to start on either value, and the error names `DALP_GOVERNANCE_DOMAIN_SCOPE`. Set it in the values file, not through a Conjur secret, because the chart checks the value when it renders.

## Custody gateway keeper gas price [#custody-gateway-keeper-gas-price]

The custody gateway keeper can ask a withdrawing client to repay the gas it spends on the payout, in the withdrawn coin. To turn gas into that coin it needs the price of the chain's native coin, and the platform reads no market feed for it. Without a price, a request carries no gas recharge and the organisation pays the keeper's gas.

Set `global.dalpApp.config.custodyOps.gateway.nativePrices` to a list of prices, one for each network and gateway coin:

```yaml
global:
  dalpApp:
    config:
      custodyOps:
        gateway:
          nativePrices:
            - chainId: 1
              token: "0x00000000000000000000000000000000000000c1"
              coinPerNativeCoin: "3000.25"
              observedAt: "2026-11-11T08:00:00Z"
```

| Field | Meaning |
| --- | --- |
| `chainId` | The chain whose native coin the price is for. |
| `token` | The gateway coin the gas is repaid in. Add one entry per coin. |
| `coinPerNativeCoin` | Whole units of the coin that one whole unit of the native coin buys, as a quoted decimal above zero. |
| `observedAt` | When you read the price. |
| `nativeDecimals` | Decimals of the native coin. Defaults to 18. Set it for a network whose native coin differs. |

An entry stops quoting once `observedAt` is older than `nativePriceMaxAgeSeconds`, which defaults to 3600 and accepts 60 to 604800. Set it through `CUSTODY_OPS_GATEWAY_NATIVE_PRICE_MAX_AGE_SECONDS`. A price that is missing, older than that bound, or paired with a coin whose decimals cannot be read quotes no gas recharge, so a stale price never overcharges a client. The keeper logs a warning with the reason for a stale or unreadable entry. Refresh `observedAt` and the price together whenever you update an entry. The platform caps every quote at the gas ceiling stored on the gateway.

## Custody credential identity key [#custody-credential-identity-key]

Set `global.dalpApp.env.CUSTODY_CREDENTIAL_IDENTITY_KEY` to a value of at least 32 characters that belongs to this deployment alone. The platform hashes each custodian credential identity under this key, so that it can tell when two organisations hold the same custodian credential. The key grants no access. Never copy it between installs, because the stored hashes derive from credential material.

The chart ships the development placeholder `local-custody-credential-identity-key`, and a production pod refuses to start on it. `CUSTODY_CREDENTIAL_IDENTITY_KEY_ID`, default `v1`, names the key the stored hashes were written under. Rotating the key leaves every stored identity incomparable until they are hashed again under the new key, so raise the key id when you rotate.

## Ask AI provider key [#ask-ai-provider-key]

Ask AI is the question-and-answer chat on the documentation site that the `docs` subchart serves under `/docs` on the Console hostname. It turns on when the documentation pod holds an OpenRouter API key. OpenRouter is a hosted service that routes requests to language models. The browser sends the question to the documentation server, and only the server calls OpenRouter, so the key never reaches the browser. Each call sends the reader's conversation and the documentation passages the server found for it to OpenRouter, which runs it on a DeepSeek model that the platform sets. The key does not choose the model. The investor documentation site has no Ask AI and receives no key.

The chart gives the pod the key as the `OPENROUTER_API_KEY` environment variable, read from one entry of a Kubernetes Secret. `docs.openRouter.existingSecret` names the Secret, and `docs.openRouter.existingSecretKeys.apiKey` names the entry. They default to the release's shared environment Secret and its `ASSISTANT_OPENROUTER_API_KEY` entry, which the chart renders from `global.dalpApp.env`. Supply `global.dalpApp.env.ASSISTANT_OPENROUTER_API_KEY` at deploy time from your secret store, as you do for the other secrets in that block, and keep it out of version control. That one value turns on Ask AI and also lets the Console assistant answer for organisations that have no key of their own.

Anyone who can reach the documentation can ask questions, and each answer spends the key's credit. The platform admits at most 10 questions a minute per client and 300 an hour in total. It tells clients apart by the address that your routing layer passes on.

The chart sets `DOCS_CHAT_TRUSTED_PROXY` to `envoy`, `nginx` or `openshift` only when the documentation Service is `ClusterIP` and exactly one of `docs.ingress.enabled`, `docs.httpRoute.enabled` and `docs.openShiftRoute.enabled` is true. Otherwise it sets `none`, and all readers share one allowance of 10 questions a minute. The default install turns on both ingress and HTTP route, so it uses `none`.

To override the value, set `DOCS_CHAT_TRUSTED_PROXY` in `docs.env`, and choose `envoy`, `nginx` or `openshift` only when every public path to the documentation goes through that routing layer. Any other value makes every Ask AI, search and Model Context Protocol request to the documentation fail.

The chart gives every documentation pod the release's Redis store when `global.dalpApp.env` holds `REDIS_URL`, so every count then covers all pods. A pod without a Redis store keeps its own counts, so each pod admits 10 questions a minute per client and 300 an hour.

Use a separate key when a different team pays for documentation questions or should cap them in its own OpenRouter account. You can supply it in one of two ways:

- Create a Secret in the release namespace, point `docs.openRouter.existingSecret` at it, and set `docs.openRouter.existingSecretKeys.apiKey` to the entry that holds the key.
- Set `docs.openRouter.existingSecret` to an empty string and supply `docs.openRouter.apiKey` at deploy time from your secret store, as you do for `global.dalpApp.env.ASSISTANT_OPENROUTER_API_KEY`. The chart then renders a Secret that holds the key under the entry named by `docs.openRouter.existingSecretKeys.apiKey`, and the pod reads it from there. With the default `docs.fullnameOverride`, the Secret is named `docs-openrouter-key`.

Only one of `docs.openRouter.existingSecret` and `docs.openRouter.apiKey` can hold a value, and `helm install` and `helm upgrade` fail when both do. `docs.openRouter.existingSecret` holds the name of the shared environment Secret by default, so set it to an empty string whenever you set `docs.openRouter.apiKey`.

`helm install` and `helm upgrade` also fail when `docs.openRouter.apiKey` is set and `docs.openRouter.existingSecretKeys.apiKey` is empty, because the key then has no entry to hold it. The pod specification holds a reference to the Secret and never the key. With the second way, the chart-created Secret and the Helm release record hold the key.

The release record holds every other secret in your values file the same way.

The documentation pod does not run `summon`, so a Conjur `secrets.yml` mapping does not reach it, and a key that exists only in Conjur leaves Ask AI off. The pod reads the key from a Kubernetes Secret: one of the two Secrets in the list, or the shared environment Secret that `global.dalpApp.env.ASSISTANT_OPENROUTER_API_KEY` fills.

To keep Ask AI off while the Console assistant keeps its key, set `docs.openRouter.existingSecret` to an empty string and leave `docs.openRouter.apiKey` empty:

```yaml
docs:
  openRouter:
    existingSecret: ""
```

If your values set an `OPENROUTER_API_KEY` entry in `docs.env`, `helm install` and `helm upgrade` fail. Remove the entry. With the default values, the pod then reads the shared key, or you can supply a separate key in one of the two ways in the list.

With no key, an empty key, a missing Secret, or a Secret without the named entry, Ask AI stays off and the pod still starts. The chat route at `/docs/api/chat` then answers 404, the documentation pages hide every Ask AI entry point, and search keeps working because the documentation pod serves it. The pod makes no call to OpenRouter.

To check the state, open `/docs/api/chat-config` on the Console hostname. The response is `{"enabled":true}` when the pod holds a key and `{"enabled":false}` when it does not. The check proves only that the pod holds a key. A key that OpenRouter rejects still reports enabled, and each answer then ends with "The answer could not be completed. Try again." A pod reads the variable when it starts. Restart the documentation pods after you set or change the key, unless your cluster already restarts pods when a Secret changes.

When an answer fails, the documentation pod logs `Ask AI provider call failed`. Its `stage` field says where the call stopped, and `error_code` carries the network error code when there is one. `no-response` means the pod got no HTTP response from OpenRouter, so check the pod's outbound network and DNS. `first-chunk` and `between-chunks` mean OpenRouter answered but sent no answer text in time, and `total` means the answer ran past 30 seconds. `response` means OpenRouter answered and the call then failed. `provider_status` carries the HTTP status when OpenRouter refused the call, for example 401 for a rejected key or 429 for a rate limit.

After a `no-response` failure, the pod tests whether it can reach OpenRouter and logs each step as an `Ask AI provider host probe` line, up to 20 seconds after the failure line. A step that worked logs at info level and a failed step at error level. The line with `stage` `provider-host-lookup` records whether `openrouter.ai` resolved to an address.

When it did, the pod opens a TCP connection on port 443 to the first IPv4 address and the first IPv6 address that the lookup returned and closes it at once. It logs a `provider-host-connect` line for each, with `address_family` set to `ipv4` or `ipv6`. Every line carries `elapsed_ms` and `timed_out`, which is `true` when the step ran past 10 seconds.

A step that failed for another reason carries `error_code`, which is `no_address` when `openrouter.ai` has no address of that family.

The probe connects directly and does not use a proxy set in the pod's environment, so when the pod reaches the internet through a proxy, failed `provider-host-connect` lines are expected and say nothing about the proxy. Without a proxy, when both `provider-host-connect` lines fail, the pod could not open a connection to OpenRouter on port 443, so check the egress rules that apply to the documentation pods.

When the `ipv4` line succeeds, the pod can open a TCP connection to OpenRouter on port 443. The probe does not test TLS or HTTP, so a rule that filters those can still block the call. A failed `ipv6` line next to it does not explain the failure, because the pod's HTTP client falls back to IPv4 when IPv6 does not connect.

### Count readers separately behind Cloudflare [#count-readers-separately-behind-cloudflare]

Behind Cloudflare, Envoy Gateway sees a Cloudflare address instead of the reader's address, so readers who arrive through the same Cloudflare address share one budget. To count each reader separately, have the Gateway trust the entry Cloudflare adds to `X-Forwarded-For`, keep that entry last, remove any `x-envoy-external-address` a request carries, and let only Cloudflare connect to the load balancer.

When `DOCS_CHAT_TRUSTED_PROXY` is `envoy`, the documentation server counts each reader by the `x-envoy-external-address` header. When that header is missing or does not hold a valid IP address, the server uses the last entry of `X-Forwarded-For`. It never reads an earlier entry, because a client can write every entry before the one Cloudflare adds.

Ask AI, answer ratings, search, the docs unlock form and the Model Context Protocol endpoint all count requests by that address. The chart sets `envoy` when `docs.service.type` is `ClusterIP`, `docs.httpRoute.enabled` is true, and `docs.ingress.enabled` and `docs.openShiftRoute.enabled` are false. The DALP chart turns `docs.ingress.enabled` on by default, so set it to false.

Otherwise set `DOCS_CHAT_TRUSTED_PROXY` to `envoy` in `docs.env`, which is safe only when every public path to the documentation goes through Envoy Gateway. With `global.dalpApp.config.trustedProxy.profile` set to `envoy`, the Console, the Investor portal and the Platform API read the reader's address by the same rule, and the Platform API records the address in its request audit trail.

Cloudflare adds the reader's address as the last entry of the `X-Forwarded-For` header before it connects to your load balancer. Configure the Gateway to trust exactly that one entry, and allow only Cloudflare to connect to the load balancer. Apply both settings together. If the load balancer accepts connections from any address, a caller that connects directly can put any address in `X-Forwarded-For` and get a new budget with each request.

With `xForwardedFor` set, Envoy Gateway no longer sets `x-envoy-external-address`, so a value that a caller sent reaches the pods unchanged. It also adds Cloudflare's address to the end of `X-Forwarded-For` unless `disableXForwardedForAppend` is true.

The policy in the example sets `disableXForwardedForAppend` to keep the reader's address last, and removes any incoming `x-envoy-external-address` so that a caller cannot pick its own address. `disableXForwardedForAppend` needs Envoy Gateway 1.9 or later. The documentation server, the Console, the Investor portal and the Platform API then read the reader's address from the last entry.

They read only that entry, so they see each reader's own address only when Cloudflare connects straight to the load balancer. If another proxy that adds to `X-Forwarded-For` sits between them, readers behind one Cloudflare address share a budget again.

Set `clientIPDetection` and `headers` in the `ClientTrafficPolicy` that targets your Gateway. Envoy Gateway applies the oldest policy when two policies target the same Gateway, so add `clientIPDetection` and the `headers.earlyRequestHeaders.remove` entry to the existing policy instead of creating a second one. A policy that targets one listener through `sectionName` replaces the Gateway-wide policy for that listener, so add them there too. If no policy targets the Gateway, create one like this:

```yaml
apiVersion: gateway.envoyproxy.io/v1alpha1
kind: ClientTrafficPolicy
metadata:
  name: client-ip
  namespace: <gateway-namespace>
spec:
  targetRefs:
    - group: gateway.networking.k8s.io
      kind: Gateway
      name: <gateway-name>
  clientIPDetection:
    xForwardedFor:
      numTrustedHops: 1
      disableXForwardedForAppend: true
  headers:
    earlyRequestHeaders:
      remove:
        - x-envoy-external-address
```

Restrict the load balancer `Service` in the `EnvoyProxy` resource that your Gateway or GatewayClass references through `parametersRef`. If neither references one, create it and point `spec.infrastructure.parametersRef` on the Gateway at it. A GatewayClass-level `EnvoyProxy` applies to every Gateway of that class. If other Gateways must stay reachable without Cloudflare, give this Gateway its own `EnvoyProxy`.

In an existing `EnvoyProxy`, add only the `envoyService` fields in the example. The list holds Cloudflare's IPv4 and IPv6 ranges as published in November 2026 at `https://www.cloudflare.com/ips-v4` and `https://www.cloudflare.com/ips-v6`. Compare it with those lists before you apply it, and update it when Cloudflare changes them.

```yaml
apiVersion: gateway.envoyproxy.io/v1alpha1
kind: EnvoyProxy
metadata:
  name: <proxy-name>
  namespace: <gateway-namespace>
spec:
  provider:
    type: Kubernetes
    kubernetes:
      envoyService:
        type: LoadBalancer
        externalTrafficPolicy: Local
        loadBalancerSourceRanges:
          - 173.245.48.0/20
          - 103.21.244.0/22
          - 103.22.200.0/22
          - 103.31.4.0/22
          - 141.101.64.0/18
          - 108.162.192.0/18
          - 190.93.240.0/20
          - 188.114.96.0/20
          - 197.234.240.0/22
          - 198.41.128.0/17
          - 162.158.0.0/15
          - 104.16.0.0/13
          - 104.24.0.0/14
          - 172.64.0.0/13
          - 131.0.72.0/22
          - 2400:cb00::/32
          - 2606:4700::/32
          - 2803:f800::/32
          - 2405:b500::/32
          - 2405:8100::/32
          - 2a06:98c0::/29
          - 2c0f:f248::/32
```

Source ranges apply only to the load balancer address. Check that your cloud provider enforces `loadBalancerSourceRanges`, and block the Service's node ports from outside the cluster.

When `DOCS_CHAT_TRUSTED_PROXY` is `envoy`, `nginx` or `openshift` and a request carries no address the server can use, the request counts against one budget that all such requests share. The documentation pod then logs `Docs client address unavailable`.

Its `envoy_external_address_present` field says whether the request carried `x-envoy-external-address`, and `forwarded_for_present` whether it carried `X-Forwarded-For`. Each is `true` or `false`, and the line holds no header value. If these lines appear, check that every public path to the documentation goes through the proxy that `DOCS_CHAT_TRUSTED_PROXY` names.

That is Envoy Gateway for `envoy`, the NGINX ingress for `nginx` and the OpenShift router for `openshift`.

## Documentation host [#documentation-host]

The documentation pod writes one host into the absolute links of its `llms.txt` and `llms-full.txt` indexes, the markdown export of each page, the canonical and Open Graph tags of each page, and the URLs that its Model Context Protocol server returns. AI agents follow those links, so they must point at the host that serves your copy of the documentation. The chart passes the host to the pod as the `PUBLIC_URL` environment variable.

With the default values the documentation runs under `/docs` on the Console hostname, and the chart takes that host from the first `docs.ingress.hosts` entry. That entry ships as `dapp.k8s.orb.local` with the ingress class `dalp-nginx`, both development values, so set `docs.ingress.hosts` to your Console hostname and `docs.ingress.ingressClassName` to your class. The OpenShift profile serves the documentation on its own Route host and takes the host from `docs.openShiftRoute.host`. Set `docs.publicUrl` only to override the host the chart picks.

Give `docs.publicUrl` as a scheme and a host with no path, such as `https://console.example.com`. The site adds the `/docs` path itself. The chart's values schema rejects a value with a path, so `helm install`, `helm upgrade` and `helm template` fail on one.

When `docs.publicUrl` is empty, which is the default, the chart uses `https://` and the first host it finds:

1. The first host in `docs.ingress.hosts`, when `docs.ingress.enabled` is true.
2. The first entry in `docs.httpRoute.hostnames`, when `docs.httpRoute.enabled` is true.
3. `docs.openShiftRoute.host`, when `docs.openShiftRoute.enabled` is true.

The documentation chart enables its HTTP route by default with the hostname `docs.settlemint.com`. An install that turns off `docs.ingress` and keeps this HTTP route must set `docs.httpRoute.hostnames` or `docs.publicUrl`, or the links point at the public documentation host, `docs.settlemint.com`. With no enabled route and no `docs.publicUrl`, the chart sets no `PUBLIC_URL`, and the links also point at `docs.settlemint.com`.

A `PUBLIC_URL` entry in `docs.env` replaces the value the chart works out. The schema does not check this entry, so give it a scheme and a host with no path.

## Documentation served from the Console [#documentation-served-from-the-console]

The Console also answers `/docs` on its own hostname. When a `/docs` request reaches the Console instead of a documentation route, the Console forwards it to the documentation service and returns the response, so the reader stays on the Console hostname. A request for `/docs` itself is redirected to `/docs/operators/introduction`. The chart builds the Console configuration from `global.dalpApp.config`, and the Console reads two keys under `global.dalpApp.config.docs` to decide where to forward. The chart sets neither key.

| Key | What it does |
| --- | --- |
| `global.dalpApp.config.docs.internalUrl` | The address the Console forwards to. When it is empty the Console uses `global.dalpApp.config.docs.url`, and when both are empty it uses `http://docs:3030`. |
| `global.dalpApp.config.docs.proxyAllowedHosts` | A comma-separated list of host names. The Console forwards only to the host `docs`, a host on this list or a host name that ends in `.localhost`. The default is an empty list. |

The address must use `http` or `https`, and the Console keeps only its scheme, host and port. An address with another scheme, or with a host the list does not admit, is ignored and the Console forwards to `http://docs:3030`. To forward to a documentation service under another name, set `internalUrl` to its address and add its host name to `proxyAllowedHosts`.

The Console removes the `authorization`, `cookie` and `x-api-key` headers from each request before it forwards it, so a Console session credential never reaches the documentation service. It also removes `set-cookie` from the response, so the documentation service cannot set a cookie on the Console hostname.

## Frequently asked questions [#frequently-asked-questions]

### Can I supply a datastore password through a plain Kubernetes Secret instead of Conjur?

Yes. Each `postgresql` and `redis` block under `global.datastores` accepts its own `existingSecret`, which the chart reads as an ordinary Kubernetes `Secret`, with or without Conjur. The application's other secrets, such as the encryption master password, reach the pods through the shared Secret the chart renders from `global.dalpApp.env`, or through Conjur and `summon` when you switch Conjur on.

### If I set the application's `DATABASE_TLS` value while pooling is enabled, does it do anything?

No. The platform ignores it and raises no error. When `global.pgbouncer.enabled` is true, the application connects to the pooler's plaintext in-cluster listener with its own TLS setting turned off. `DATABASE_TLS` takes effect only on direct connections, such as the migrator's, or on every connection when pooling is off.

### Which model provider keys does Ask AI accept?

Ask AI accepts only an OpenRouter key. A key from another provider still makes `/docs/api/chat-config` report enabled, and every answer then ends with "The answer could not be completed. Try again." The platform chooses the model, and the key does not change it. [Ask AI provider key](#ask-ai-provider-key) shows where to set the key.

### Can the documentation run without internet access?

Yes, apart from Ask AI and the YouTube video on the DALP 3.0 changelog page. The documentation pod serves pages and search itself, so neither needs internet access. Without internet access, set `docs.openRouter.existingSecret` to an empty string and leave `docs.openRouter.apiKey` empty, because with a key present Ask AI stays visible and every answer fails. The bundled documentation loads no third-party analytics script, because the site loads those scripts only when `docs.leadCapture.enabled` is `true`. The setting is `false` by default and the platform chart does not set it. `/docs/api/site-config` reports it as `leadCapture`.

### Does `postgres-exporter` route through PgBouncer like the application does?

No, it connects directly to Postgres. With it off you lose the aggregate backend-count view and `PostgresAggregateBackendsHigh`, while the pods' own pool-pressure gauges keep working.


# Networks

Source: https://docs.settlemint.com/docs/deployment/networks
The EVM networks a DALP instance runs on, what it needs from your nodes, how it decides a block is final, and how it handles chain reorganisations and failover.

A DALP Instance runs on any EVM network that supports the Cancun version of the EVM, and it reaches each network only through RPC endpoints that you supply.

Configure the baseline network list during deployment, in the `networks` section of the Helm values. A platform administrator can edit those networks at runtime in the platform network catalogue, without a redeployment. A network that exists only in the catalogue is not indexed and the transaction engine cannot reach it, so declare every network you use in the Helm values first. The base chart values ship one placeholder network, `mintnet`, whose endpoints name nodes no DALP chart installs: replace it before the first install, as [What the base chart values declare](#what-the-base-chart-values-declare) describes. The baseline seeds that catalogue once per network name, and after that the stored catalogue wins.

[Figure] Two ways to configure the network list. Deployment values set the default EVM network and require a Helm upgrade. The runtime catalogue adds or edits a network without redeployment, but cannot change the default. Runtime writes check concurrency, the entry schema, the merged catalogue, active systems, and existing RPC pools. Both paths require a non-empty network list with exactly one enabled EVM default. Labels: Deploy-time values and the runtime catalogue differ in power; Two write paths, one network list; Deploy-time; helm upgrade, then a restart; Change-controlled release; Reviewed like any deploy; Sets the EVM default; Exactly one network; Controls private RPC access; Review access before deployment; Runtime; platform catalogue, no redeploy; 5 runtime checks; concurrency and entry schema,; catalogue and active systems,; then existing RPC pools; Default never moves here; A submitted default is refused; Add or edit an EVM network; RPC credentials use; the upstream pool; Either path, the result still passes the same boot-time rules; Exactly one EVM default, and the network list never empty.

Deployment values set the default network, and runtime catalogue writes keep it and reject changes that disconnect
active systems or invalidate an RPC pool.

## Supported EVM networks [#supported-evm-networks]

The platform supports any EVM network whose nodes run the Cancun version of the EVM. The smart contracts compile for Cancun, and some of them use transient storage, the EIP-1153 feature that Cancun introduced. Confirm Cancun support with whoever runs the network before you add it. The platform also runs on networks that charge no gas, such as the QBFT network in the base chart values.

Each entry in `networks` takes one of two shapes:

| Shape | Discriminator | Use |
| --- | --- | --- |
| Built-in EVM | `chain`, a viem chain alias such as `sepolia` | A public or well-known EVM chain. It inherits its chain ID, name, native currency and block explorer. |
| Custom EVM | `chainId` + `name` | A private or unlisted EVM chain. You supply the native currency and block explorers yourself. |

A built-in alias must be a chain that the viem chain list in the release defines. Any other alias fails validation with `Invalid built-in viem chain name`. A custom entry needs a chain ID of 1 or more. Its native currency defaults to Ether with the symbol `ETH` and 18 decimals.

Every EVM entry also carries RPC connection settings, finality settings, indexing settings and, for the indexer, the address of the Directory contract. One instance can serve any number of networks, but exactly one EVM network is the default.

## Validation at boot [#validation-at-boot]

The instance rejects the `networks` section at startup, before it serves traffic, when any of these hold:

- The section is empty. It needs at least one network.
- No EVM network sets `default: true`. The boot failure is `Exactly one EVM network must have 'default: true'`.
- More than one EVM network sets `default: true`. This boot failure names every offending network: `Multiple EVM networks marked as default: <names>`.
- The network that sets `default: true` does not also set `enabled: true`. The boot failure is `Default network '<name>' must be enabled`.

A chain ID can repeat across two entries on purpose. That lets you rotate an RPC provider, or promote a secondary alias to primary, by keeping the old entry turned off beside its enabled replacement. The indexer reads a chain ID only once, through the first enabled entry for it.

## Adding or changing a network [#adding-or-changing-a-network]

A network reaches the catalogue through one of two write paths, and they carry different consequences.

**Deployment values.** The `networks` section of the Helm values declares the baseline. Changing it takes a `helm upgrade` and a restart of the affected components, so it goes through the same change control as the rest of the release. At startup the platform adds each baseline network that its stored catalogue does not hold yet. It does not rewrite a network the catalogue already holds, so runtime changes survive a release. To apply a changed baseline entry to a network the catalogue already holds, remove the override on that network in the platform network catalogue. That puts back the entry from the current baseline.

**Platform network catalogue.** A platform administrator adds or edits a network at runtime, with no redeployment, on the [platform networks page](https://docs.settlemint.com/docs/console/platform-admin/networks). A save writes the network's definition: its chain alias or chain ID, name, finality and indexing settings, RPC policy and `gas` block. The RPC endpoints and their credentials are a separate write to the network's RPC endpoint pool. A runtime write passes these checks before the platform accepts it:

1. The new entry must decode as a valid network definition.
2. The write names the catalogue version it expects to change. A concurrent change elsewhere fails the write instead of being overwritten.
3. The catalogue as it would stand after the write must still pass the boot validation rules, such as exactly one EVM default.
4. A write that would leave a chain ID with no enabled network, while an organisation has systems deployed on that chain ID, is refused and names the stranded chain IDs.
5. A write that moves a network to another chain ID while RPC endpoints are stored for that network is refused.

A runtime network definition has no WebSocket endpoint, and runtime pool endpoints must use HTTP or HTTPS. A network that exists only in the platform network catalogue therefore has no `rpc.wsUrl`, and the indexer does not index it. The transaction engine's RPC client also takes its networks and endpoints from the deployment values only, so it does not find a network that is declared nowhere else. Declare a network in the deployment values, with `rpc.wsUrl`, before an organisation deploys to it.

For a network declared in the deployment values, the indexer follows the runtime catalogue. It starts indexing the network when you enable it and stops when you disable it, with no restart. A disabled network releases its chain, and its card stops showing indexing state.

The runtime catalogue cannot change the default network or `rpc.allowPrivateUpstreams`. Change the default with a Helm upgrade, then remove the overrides on the old and the new default network in the platform network catalogue, so that the stored catalogue takes the new default.

A removal depends on where the network came from. A network that also has a baseline entry goes back to that baseline and keeps its RPC endpoints. A network that exists only at runtime leaves the catalogue, and its RPC endpoints are cleared with it. Check 4 applies first in both cases.

The boot validation does not check whether an organisation has systems on a network. A Helm upgrade that disables or removes a network therefore has no stranding check. Confirm that nothing live depends on the network before you take it out in a release.

## Node and endpoint requirements [#node-and-endpoint-requirements]

SettleMint does not run nodes for you. You run the nodes, or contract a node provider, that serve the standard EVM JSON-RPC interface, and you list their endpoints on each network.

| Setting | Protocol | What reads it |
| --- | --- | --- |
| `rpc.url` or `rpc.urls` | HTTP or HTTPS | Every HTTP call, including transaction broadcasts. `rpc.urls` lists several endpoints, each with optional authentication and a `weight`. |
| `rpc.wsUrl` | WS or WSS | The indexer. It follows the chain head through an `eth_subscribe` `newHeads` subscription and reconnects when delivery stops. |

The indexer needs the WebSocket endpoint and has no HTTP polling fallback. A network with no `rpc.wsUrl` is not indexed, and the indexer logs `EVM indexing needs a WebSocket endpoint that supports eth_subscribe newHeads`. The indexer also reads historical state. When the endpoint keeps none, the indexer logs `EVM chain RPC keeps no historical state; the chain waits for an archive RPC` and that network waits until an endpoint that keeps history answers.

Endpoints added at runtime to a network's RPC endpoint pool must use HTTP or HTTPS. A runtime pool write rejects a URL that embeds credentials or carries a query string or fragment, and an endpoint that the private upstream guard refuses. When the network has a chain ID stored, the write also asks each endpoint for its chain ID and refuses one that reports a different chain ID. The probes in one write share a 15-second deadline, and an endpoint that does not answer in time is still saved. Credentials go in the endpoint's own API key or basic authentication fields and are stored encrypted.

### What the platform trusts [#what-the-platform-trusts]

The platform trusts the endpoint that answers. Each call goes to one endpoint, and the first successful answer is the answer the platform uses. It does not compare answers across endpoints and does not run a light client. It does check two things: the indexer's health-ranked pool refuses an answer that reports a lower block than one it has already seen from any endpoint, and a runtime pool write refuses an endpoint whose chain ID differs from the network's. List only nodes that you, or a provider you have a contract with, operate and secure.

### Private upstream guard [#private-upstream-guard]

The platform refuses to send a request to an endpoint whose hostname resolves to an internal address. It checks the addresses that the hostname resolves to, not only the hostname, and checks again when the cached resolution expires.

- Link-local addresses, cloud metadata services and other blocked ranges are always refused.
- Loopback, RFC 1918 private, IPv6 unique local and carrier-grade NAT addresses are refused unless the network sets `rpc.allowPrivateUpstreams: true`.

`rpc.allowPrivateUpstreams` is a deployment-time value. The platform network catalogue cannot change it, and a runtime pool on a network takes the value that the network's deployment values set. Set it to `true` only on a network whose nodes run on your private network.

## Finality [#finality]

Every EVM network decides finality by distance from the chain head. A block is final once it is the network's finality distance below the newest block the indexer has seen. The platform does not read the `finalized` block tag. `supportsFinalizedTag`, `finalityConfirmations` and the chain alias choose the distance:

| Network type | Settings | Finality distance |
| --- | --- | --- |
| Built-in chain with a recommended distance | `supportsFinalizedTag: true`, the default | The chain's recommended distance |
| Any other network whose nodes expose the `finalized` block tag | `supportsFinalizedTag: true` | 64 blocks |
| Network whose nodes have no `finalized` tag, such as QBFT, IBFT or Clique | `supportsFinalizedTag: false`, `finalityConfirmations` of 1 or more | `finalityConfirmations` blocks |
| Local test node, `test` set to `anvil`, `hardhat` or `ganache` | `supportsFinalizedTag: false`, `finalityConfirmations: 0` | 0 blocks |

| Built-in chain alias | Recommended distance in blocks |
| --- | --- |
| `arbitrum` | 240 |
| `polygon` | 200 |
| `mainnet` | 65 |
| `base`, `optimism` | 24 |
| `baseSepolia`, `optimismSepolia`, `arbitrumSepolia` | 24 |
| Any other network with `supportsFinalizedTag: true` | 64 |

A network with `supportsFinalizedTag: false` and no confirmations fails validation outside test mode. The error ends `Production chains must set finalityConfirmations>=1 to preserve a pruning safety margin.`

**Example: a QBFT network.** QBFT finalises each block when the validators produce it and has no `finalized` tag. Set `supportsFinalizedTag: false` and `finalityConfirmations: 1`. A block is then final one block below the head. Webhook events that wait for finality still wait for the 64-block chain reorganisation window, unless `reorgDepth` sets a smaller one.

### How the platform waits for finality [#how-the-platform-waits-for-finality]

The indexer records a final block for each network, the head minus the finality distance, every time it commits new blocks. Normal indexing never moves that watermark back: a lower value, for example from an endpoint that lags, leaves the stored value in place. Only a rewind after a chain reorganisation, or a rebuild of the network's indexed data, lowers it. Among the parts of the platform that wait for finality:

- **Webhook events.** An event that waits for finality is released for delivery once its block is at or below the bottom of the chain reorganisation window. That is the indexed block minus `reorgDepth`, or minus the larger of the finality distance and 64 blocks when `reorgDepth` is unset. On a QBFT network with `finalityConfirmations: 1` and no `reorgDepth`, an event waits until it is 64 blocks behind the indexed block.
- **New-token detection.** Tokens that the platform detects on its own are read at the lower of the indexed block and the indexer's final block.
- **Custody deposit reports.** Inbound transfers to a custody gateway are reported only up to the RPC head minus the finality distance.

The transaction queue does not wait for finality. It completes a write once the node returns the receipt and the indexer has processed that block. Data from blocks newer than the final block can still change after a chain reorganisation.

`supportsFinalizedTag`, `finalityConfirmations` and `reorgDepth`, which the Console labels "Reorg depth", are editable on a network in the platform network catalogue.

## Chain reorganisation handling [#chain-reorganisation-handling]

A chain reorganisation replaces recent blocks with different ones. The indexer follows each block by its hash, so it detects a replaced block at the same height. It then rolls its records back to the last block that both versions share and indexes the new blocks again.

The indexer keeps undo data for each block in a window of recent blocks. `reorgDepth`, 1 or more, sets how many recent blocks that window keeps. With no `reorgDepth`, the window is the larger of the finality distance and 64 blocks. A repair never reaches at or below the stored final block, so a window deeper than the finality distance adds no repair reach. It does delay webhook events that wait for finality, because they are released at the bottom of the window. At startup the platform logs a warning when `reorgDepth` exceeds the expected finality distance of a built-in chain with a recommended distance, or of a network with no `finalized` tag.

| Setting | Recommended value |
| --- | --- |
| `reorgDepth` on any network | Leave it unset. The window is then the larger of the finality distance and 64 blocks. |
| `finalityConfirmations` on a network with no `finalized` tag | At least the deepest chain reorganisation the network's consensus allows. 1 on QBFT or IBFT, which finalise each block. |

The indexer measures its reach from the stored final block and window, not from the current head, so it still repairs a chain reorganisation that it finds after a long downtime.

### Beyond the window [#beyond-the-window]

The indexer does not repair a fork that starts at or below the stored final block, or below the bottom of the retained window. It parks that network instead: the network stops advancing, its Ledger Data freezes at the last indexed block, and the other networks keep running. The log line is `EVM span chain parked; its siblings continue`, with the failure `Repair stopped <reason> at retained floor <block>.`, where the reason is `at-or-below-finality`, `below-retained-floor` or `beyond-repair-depth`. The platform does not rewind on its own. Follow [Indexer chain parked](https://docs.settlemint.com/docs/deployment/runbooks/indexer-chain-parked): a restart heals a park whose fork block is still inside the window, and a fork below it needs a rebuild of the network's indexed data.

The counter `dalp_didx_reorg_detected` counts the chain reorganisations the indexer meets, whether it repairs them or not. The gauge `dalp_didx_reorg_depth` holds how many blocks the last repair rewound. Both carry a `chain` label.

## Endpoint failover and retries [#endpoint-failover-and-retries]

Three RPC clients make most calls to a network, and they choose endpoints in different ways:

- **The indexer** reads blocks and logs, and runs its event handlers, through the network's RPC endpoint pool with health ranking. The endpoints in the deployment values form the baseline pool, and a platform administrator adds, removes and weights endpoints at runtime on the [platform networks page](https://docs.settlemint.com/docs/console/platform-admin/networks). Health scoring, weights, hysteresis and the retry settings in this section apply to this client.
- **The Platform API** uses the same pool, and ranks the endpoints by a score that blends each endpoint's recent successes and failures, with the listed order breaking ties. An endpoint that the persisted health data shows more than 50 blocks behind the chain head, unhealthy or below the minimum score is left out while another endpoint qualifies. A call tries the endpoints in that ranked order. Each endpoint gets `timeout` per attempt and retries a failure `retryCount` times, `retryDelay` apart. When every endpoint fails, the client runs through the whole list again, up to `retryCount` more times. A revert or another deterministic answer returns at once. `weight`, hysteresis and the `rpc.health` thresholds do not apply to it. `requestRpcDeadlineMs` bounds the whole call while a Platform API request waits on it.
- **The transaction engine** signs, broadcasts and confirms transactions, and reads the chain head and the final block, through its own client. That client uses only the endpoints in the deployment values. To give the transaction engine a second endpoint, list several entries in `rpc.urls` in the deployment values. Endpoints added on the platform networks page do not reach it. Endpoints added at runtime, `weight`, hysteresis and the `rpc.health` thresholds do not apply to it. [How the transaction engine picks an endpoint](#how-the-transaction-engine-picks-an-endpoint) describes it.

The Platform API and the indexer's event handlers reload a changed pool when they are notified, and a catch-up pass every 60 seconds applies a change they missed.

With a single endpoint, none of the ranking and failover in this section applies: the call retries that endpoint `retryCount` times and then fails.

### Health scoring [#health-scoring]

One collector measures every endpoint and stores the scores. The indexer ranks the pool on them, and the transaction engine's client reads them too. The collector runs every 60 seconds by default, and `monitoring.blockchainHealthCollector.intervalSeconds` changes that. A score runs from 0 to 1:

| Component | Weight | Scale |
| --- | --- | --- |
| Reliability | 45% | 1 minus the error rate |
| Head lag | 25% | Falls to 0 at 50 blocks behind the chain head |
| Latency | 20% | Falls to 0 at 5,000 milliseconds |
| Finalisation lag | 10% | Falls to 0 at 50 blocks of lag |

A score older than `staleScoreMs` is stale. That setting defaults to three collector intervals, 180 seconds, and a lower value is raised to three intervals. While another endpoint has a fresh score, the pool leaves an endpoint with a stale score out of routing. When every score is stale or missing, the indexer asks every endpoint for its block number and ranks the endpoints on head lag and latency until fresh scores arrive.

### Selection and hysteresis [#selection-and-hysteresis]

With health ranking, the pool sends each call to one endpoint. The highest `weight` wins among usable endpoints, and health score, then configuration order, decides between endpoints with the same weight. Weight sets priority and does not split traffic. The pool leaves an endpoint out of routing when it trails the chain head by more than `maxBlockHeadLag` blocks, scores below `minScore`, or the collector reports it unhealthy. When every endpoint is left out, the pool still serves from them as a degraded fallback rather than refusing all traffic.

Hysteresis stops two endpoints of similar quality from trading places. Within `minSwitchIntervalMs` of the last switch, an endpoint with the same weight takes over from the current one only when its score is at least `hysteresis` higher. After that interval, a better score switches at once. A failed call moves to the next endpoint without waiting for either rule.

| `rpc.health` setting | Default | Console label |
| --- | --- | --- |
| `enabled` | `true` | "Score endpoint health" |
| `maxBlockHeadLag` | 50 blocks | "Max block-head lag" |
| `minScore` | 0.25 | "Minimum score (0 to 1)" |
| `staleScoreMs` | 180,000 ms | "Score staleness (ms)" |
| `hysteresis` | 0.1 | "Switch hysteresis (0 to 1)" |
| `minSwitchIntervalMs` | 60,000 ms | "Min switch interval (ms)" |
| `penaltyHalfLifeMs` | 60,000 ms | "Penalty half-life (ms)" |

A failed call lowers that endpoint's score by 0.2 in the calling process, up to 1 in total, and the penalty halves every `penaltyHalfLifeMs`. The same failure takes the endpoint out of rotation in that process for `retryDelay` or one second, whichever is longer. A revert, an invalid request or an empty answer carries no penalty.

### Retries, timeouts and deadlines [#retries-timeouts-and-deadlines]

These `rpc` settings bound each call through the pool with health ranking. The Platform API's client uses only `timeout`, `retryCount` and `retryDelay` from this table, and `requestRpcDeadlineMs`.

| `rpc` setting | Default | What it bounds |
| --- | --- | --- |
| `timeout` | 10,000 ms | One attempt on one endpoint. `methodTimeouts` overrides it per JSON-RPC method. |
| `retryCount` | 3 | Retries of a transient failure on the same endpoint |
| `retryDelay` | 150 ms | The first retry wait. `retryBackoffFactor` 2 doubles it each retry, `retryJitter` 0.2 varies it by 20%, and `retryMaxDelay` caps it at 30,000 ms. |
| `maxUpstreamAttempts` | 32 | Attempts one call may spend across retries and failovers |
| `requestDeadlineMs` | 120,000 ms | The whole call, across every retry and failover |
| `requestRpcDeadlineMs` | 25,000 ms | The whole call when a Platform API request is waiting on it |
| `retryOverrides` | `eth_sendRawTransaction` retries 0 times | Retries per JSON-RPC method |

In the health-ranked pool, two timeouts in a row on one endpoint move the call to the next endpoint. A deterministic answer, such as a revert or an invalid request, returns at once with no retry and no failover. An empty answer to a receipt lookup, a transaction lookup or a log query up to the head counts as a lagging node, and the call tries the next endpoint once before it returns the empty answer.

With health ranking, when every usable endpoint has failed, the call fails with the retryable error `RpcUpstreamsExhaustedError`, whose message reads `All healthy RPC upstreams exhausted for network <name>`. Restore an endpoint, correct its configuration, or retry once the transient failures recover. The metrics `dalp_rpc_failovers_total` and `dalp_rpc_upstreams_exhausted_total` count failovers and exhausted calls per network.

### How the transaction engine picks an endpoint [#how-the-transaction-engine-picks-an-endpoint]

The transaction engine's client keeps its own success score for each endpoint in the deployment values. Every endpoint starts at 0.5, and each call moves the score 30% of the way towards 1 on success or towards 0 on failure. The client ranks endpoints by that score, then by configuration order. It tries first the endpoints that score more than 0.25 and that the collector reports as healthy, with a fresh score of at least 0.25 and no more than 50 blocks behind the chain head. Endpoints with no fresh collector score come next. When no endpoint qualifies, the client tries every endpoint. These limits are fixed and do not follow `rpc.health`. A collector score counts as fresh for three collector intervals, 180 seconds by default.

A call moves through the endpoints in that order and tries each one once. A transient failure, a lost connection, a timeout, an endpoint configuration error, a method the endpoint does not support, or a refusal by the endpoint moves the call to the next endpoint. A revert or any other answer returns at once. An endpoint that answers with a rate limit cools down, and when every endpoint is rate limited the client can wait for the shortest cooldown and try again. When the last endpoint fails, the call fails with that endpoint's error. The metrics `dalp_chain_evm_rpc_failovers_total` and `dalp_chain_evm_rpc_upstreams_exhausted_total` count this client's failovers and exhausted calls.

When a transaction broadcast fails over to another endpoint, the client marks the outcome as uncertain, because the first endpoint may have taken the transaction. The transaction engine then decides what happened from the chain, as [Nonce management](https://docs.settlemint.com/docs/concepts/settlement/transaction-queue#nonce-management) describes.

## Per-network indexing [#per-network-indexing]

An EVM entry's `indexing` block tunes how the indexer reads that chain. Its runtime settings carry schema defaults and are editable on a network that the platform network catalogue holds. `chunkSize`, `minChunkSize` and `maxChunkSize` bound the adaptive read range, and `verifyBlockReceipts` re-checks a block that a log fetch flagged as possibly incomplete. While the indexer is behind the head it reads the next range at once.

`indexing.startBlock` is the exception in that block. It is a deployment-time value the platform network catalogue refuses, and it names the lowest block the indexer may start scanning at on a chain it has not read yet, for a chain whose Directory deploy height is already known. With the key absent, the DALP Instance resolves that height exactly: the earliest registered contract, else the Directory row, else block 0. On a long public chain, block 0 means walking millions of blocks before the first event the deployment cares about.

Two rules bound what it can do:

- **A registered contract always wins.** The floor fills the case with no rows to anchor on, and never raises the scan above a contract the indexer already knows about, because a contract that registers while the chain is catching up has to be inside the next range read.
- **It only decides where a first pass starts.** While a chain catches up, the indexer widens its reads and jumps over regions it has proven empty. Setting this key does not make an existing catch-up faster.

### When the floor is safe, and when it is not [#when-the-floor-is-safe-and-when-it-is-not]

Set it only where the deployment block is known from the chain's own deploy record: a non-production chain, or a public testnet whose Directory you deployed and whose deployment block you can read back.

Leave it unset, or set it to a block at or below the Directory's deployment, on any network where the indexer has to find the deployment itself. That discovery reads the Directory's own deployment and registration events to find the contracts seeded there and everything they deploy afterwards, and the same history is what bounds which implementations the indexer may still trust. The indexer never revisits a range it has passed, so a floor above those events is a floor above the discovery.

Note (A floor above the Directory deployment block loses history for good): The indexer does not warn you about a floor above the Directory deployment block: that deployment's events stay unfetched. Lower the floor to the Directory's deployment block, or remove it and let the deployment height resolve on its own.

### History scan floor for imported custody wallets [#history-scan-floor-for-imported-custody-wallets]

`indexing.custodyHistoryScanFloor` is a second deployment-time value the platform network catalogue refuses. The first time the platform watches a custody wallet it was not asked to create, it scans that wallet's token deposits from block 0. This key sets the lowest block that first scan may start at. It is off by default, and an empty value leaves it unset.

Wallets the platform created start about an hour before their earliest record whatever this key says, and never below it. A floor above the chain's head is ignored for that pass and logged as an error.

Deposits to an imported wallet below the floor are not detected, and changing the floor later has no effect on watches already opened.

## Gas-charging networks [#gas-charging-networks]

On a network that charges gas, the platform submits smart-account operations through a bundler, the service that wraps and pays for them. Two bundler values behave differently there than on the QBFT chain the base chart ships, which charges no gas. Neither failure shows on a dashboard.

- `bundler.priorityFeeBaseFeeMultiplier` bounds the tip a smart-account operation may carry, relative to the network's base fee, with `bundler.minPriorityFee` as the absolute floor. Without a bound, a network on which the platform is the dominant sender can drive its own fee suggestion far over the base fee until the sponsorship ceiling rejects the operation. The multiplier defaults to 3 and the floor defaults to 0. A negligible base fee makes the relative bound negligible too. Raise `minPriorityFee` on those chains to keep the bound effective.
- `bundler.callGasBufferNonDeploy` gives ordinary operations that do not deploy a contract headroom on top of the protocol's own gas-forwarding correction. The default is 1.3125, which gives a 1.333x total margin. Set too low, the transaction is included while the work inside it runs out of gas: the operation looks mined and did nothing.

Confirm both against the target network before it carries production traffic. The symptom in each case is an operation that never completes, with no error at the point of submission.

The platform treats a chain's own fee suggestion as an input. The backend caps the tip a UserOperation may carry at `max(minPriorityFee, baseFee * priorityFeeBaseFeeMultiplier)` before the operation is hashed and signed, because the fee fields are inputs to that hash and cannot be corrected afterwards. The bound applies only to operations the platform signs: an externally signed operation whose tip is under the configured floor is rejected, since raising it would invalidate the signature that covers it.

Both limits have a cost. A tip ceiling that is too tight leaves operations uncompetitive during congestion, and one that is too loose lets the tip run away again. Both show as operations that never reach inclusion, so pair any change with broadcast-latency and inclusion monitoring.

### Per-network gas settings [#per-network-gas-settings]

The two bundler settings in this section bound what a smart-account operation may pay. A separate per-network `gas` block decides what the platform asks an operator to deposit when a wallet cannot pay at all, how long that request stays open, and whether the chain charges for gas in the first place. [Gas settings](https://docs.settlemint.com/docs/deployment/gas-settings) is the reference for every key, its unit, its accepted range, and its default.

Each key resolves through four layers, and the first layer that names a field decides it:

1. The network's own settings, saved through the platform network catalogue.
2. The `gas` block on the network entry in the deployment values.
3. The `chainGasDefaults` section, keyed by chain ID, carrying calibrated figures for chains the platform has already measured. Eight chain IDs ship there, so a deployment that adds one of them needs no entry of its own. [Chains that ship calibrated](https://docs.settlemint.com/docs/deployment/gas-settings#chains-that-ship-calibrated) lists them.
4. The built-in defaults.

Resolution is per field. A network that sets one value keeps every other value live against the layer beneath it, so a later calibration change still reaches that network.

`zeroGas` is the exception to that ladder. Left unset by every layer, it is not defaulted at all: the platform probes the chain once and caches the answer. When the probe cannot reach an answer, the chain is treated as one that charges gas, because a chain wrongly treated as free puts every write back on the path where an unfunded transaction fails at the node with no request raised and no wallet named. The cost of the opposite error is one funding request an operator declines.

## What the base chart values declare [#what-the-base-chart-values-declare]

The base chart values declare one network, keyed `mintnet`, and nothing else. It is a custom EVM network with chain ID `53771311147` and the name `DALP`, set `enabled: true` and `default: true`. It describes a QBFT network, so it sets `supportsFinalizedTag: false` and `finalityConfirmations: 1`.

Its RPC settings point at in-cluster node service names: two HTTP endpoints, `http://besu-rpc-0.besu-rpc-headless:8545` and `http://besu-rpc-1.besu-rpc-headless:8545`, and the WebSocket endpoint `ws://besu-rpc-0.besu-rpc-headless:8546`. The chart does not install those nodes. The entry also turns on JSON-RPC batching of up to 20 calls per request. For the indexer, it turns on a cache of historical responses from blocks at least 128 below the head, each kept for 24 hours.

Override these values before a deployment goes live on its own network:

| Override | Why the shipped value is wrong for a real deployment | What goes wrong if you do not override it |
| --- | --- | --- |
| Chain ID, name, `rpc.urls` and `rpc.wsUrl` | They name in-cluster node services that no DALP chart installs. | The deployment keeps dialling those service names instead of the network you operate. |
| `rpc.allowPrivateUpstreams` | It ships `true` because the shipped endpoints resolve to cluster-private addresses. It is a deployment-time value that the Console cannot change. | Left `true` on a network whose nodes are public, the private upstream guard also allows private addresses that the network never needs. Set it to `false` once every endpoint resolves to a public address. While an endpoint is still private, `false` makes the guard refuse it. |
| `contracts.directory` | It ships empty. | The indexer has no Directory address to start from on that network. |
| `default`, the moment you add a second EVM network | The base values already set `default: true` on `mintnet`. | Add another EVM entry without moving the flag, and the boot check rejects the release with `Multiple EVM networks marked as default`. |

An environment overlay can add more EVM networks. The merged configuration must still pass the boot validation rules.

## Failure modes [#failure-modes]

| Symptom | Cause | Fix |
| --- | --- | --- |
| Instance fails to start, and the error names "Multiple EVM networks marked as default" | Two or more EVM entries set `default: true`. | Set `default: true` on exactly one EVM network, and `default: false` or nothing on the rest. |
| Instance fails to start, and the error mentions a pruning safety margin | An EVM network sets `supportsFinalizedTag: false` with no `finalityConfirmations`, outside `test` mode. | Set `finalityConfirmations` to at least 1. |
| Instance fails to start, and the `networks` section is rejected as empty | No networks are declared at all. | Declare at least one network. The base chart values ship one you can start from. |
| Instance fails to start, and the error says the default network must be enabled | The entry with `default: true` sets `enabled: false`. | Set `enabled: true` on the default network, or move `default: true` to a network that is enabled. |
| A network is never indexed | The network has no `rpc.wsUrl`, or it exists only in the platform network catalogue. | Declare the network in the deployment values with a WS or WSS `rpc.wsUrl` that supports `eth_subscribe` `newHeads`. |
| Indexing waits on one network and logs that the RPC keeps no historical state | The endpoint prunes historical state. | Point the network at an endpoint that keeps historical state. |
| Calls on a network fail with `RpcUpstreamsExhaustedError` | Every usable endpoint in the indexer's health-ranked pool failed the call. | Check each endpoint's health on the platform networks page, then restore or replace the failing endpoints. |
| An indexed network stops advancing and logs `EVM span chain parked` | A chain reorganisation reached beyond the repair window, or another failure a retry cannot fix. | Follow [Indexer chain parked](https://docs.settlemint.com/docs/deployment/runbooks/indexer-chain-parked). |

## Frequently asked questions [#frequently-asked-questions]

### How many networks can one instance run?

Yes. The network list has no fixed size, but it must contain exactly one enabled EVM default. Entries can describe different chains, or different endpoint sets for the same chain. Each entry needs connection, finality and indexing settings.

### Can the base chart's default network be removed?

Only by replacing it. The boot check requires exactly one EVM network with `default: true`, so a values file with no EVM entry, or with no entry marked default, fails validation before the instance serves traffic. To move off the shipped network, add your own EVM entry with `default: true` and set `default: false` on `mintnet` in the same Helm upgrade.

### Can a network added in the platform network catalogue move to another chain ID later?

Not while RPC endpoints are stored for it. The platform checked those endpoints against the current chain ID, and moving the network would send traffic meant for one chain to another. Remove the network and add it again under the new chain ID. The stranding check still applies if an organisation has systems on the old chain ID.

### Does the platform protect against a node that returns wrong data?

Only partly. When you save an endpoint to a runtime pool, the platform refuses it if it reports a different chain ID than the network. The indexer's health-ranked pool also refuses an answer that reports a lower block than one it has already seen, and briefly skips that endpoint. The Platform API and the transaction engine do not run this check. It does not compare answers from two endpoints, so a node that returns false data for a valid block is believed.


# Observability

Source: https://docs.settlemint.com/docs/deployment/observability
The OpenTelemetry pipeline a DALP instance exports by default: traces, metrics, and logs, and how the admin debug bundle auto-wires to an in-cluster stack.

DALP exports metrics, logs, and sampled traces over the OpenTelemetry Protocol (OTLP). Configure each signal's endpoint to use your collector or the [bundled observability stack](https://docs.settlemint.com/docs/deployment/install/observability-stack). The admin debug bundle reads stored logs and traces through a separate query path. [Alerts that show a recovery risk](#alerts-that-show-a-recovery-risk) lists the alerts that warn when a part of recovery stops working.

Every deployment declares a stable `dalpInstance` slug and `deploymentEnvironment` value, stamped on every signal it exports, so a central view can group a whole fleet by instance identity. Each Platform API role process owns one observability instance, with a separate exporter for each signal, so replica identity remains a reliable grouping key.

## What exports by default [#what-exports-by-default]

| Signal | Enabled by default | Config key | Notes |
| --- | --- | --- | --- |
| Traces | Yes | `telemetry.traces.otlp.endpoint` | Batches export every 5 seconds (`telemetry.traces.exportIntervalMs`) by default. `telemetry.traces.sampleRatio` defaults to 0.1 (10%), a source-side safety guard against overloading your backend with unsampled volume. Raise it towards 1 (100%) only behind a measured tail sampler in your collector, such as Grafana Alloy, the collector the bundled stack runs. |
| Metrics | Yes | `telemetry.metrics.otlp.endpoint` | Pushed every 60 seconds (`telemetry.metrics.exportIntervalMs`) by default. |
| Logs | Yes | `telemetry.logs.otlp.endpoint` | `info` level by default. The console sink renders one logfmt line per record in `kubectl logs` whenever `telemetry.logs.enabled` stays `true`. Set `telemetry.logs.exporter` to `"none"` to stop OTLP export alone and keep `kubectl logs` output. Set `telemetry.logs.enabled` to `false` to stop both. |

All three default to the same in-cluster Alloy OTLP receiver at `obs-alloy.monitoring.svc.cluster.local:4318`, which only the separate `observability` chart provides. Without that release or your own endpoint, nothing receives the data. Point these at a different collector by overriding each signal's `otlp.endpoint` key individually. There is no single global override for all three. This exporter configuration is a separate concern from the admin debug bundle below: the bundle reads telemetry back out of a VictoriaLogs and Tempo query API, while the keys above control what the Platform API pushes in.

[Figure] OTLP telemetry pushes out on a timer, and the admin debug bundle reads back on request, along two separate paths. Each Platform API role process exports traces, metrics, and logs as three independent OTLP streams, each with its own endpoint key, all targeting the in-cluster Alloy collector at obs-alloy port 4318 by default. Any signal's endpoint overrides independently to point at an external collector instead. Separately, Console's Export debug information menu item, for organisation owners and platform administrators, calls a Platform API route that downloads a zip. For a platform administrator's export, that route also pulls logs and traces back out of a VictoriaLogs and Tempo query API instead of reading the exporters above. An organisation owner's export leaves them out. When global.observability.enabled is true, those endpoints derive automatically from the observability stack's service DNS, and dapi.observabilityLogsUrl and dapi.observabilityTempoUrl override them explicitly for an out-of-cluster stack or renamed services. Labels: Each Platform API role process; one exporter per signal, pushed on a timer; Traces; own endpoint; 10% sampled by default; Metrics; own endpoint; pushed every 60 seconds; Logs; own endpoint; info level by default; obs-alloy:4318, in-cluster default; or your own collector, per signal; Export debug information; Reads back on request; Console account menu, owner or platform administrator; VictoriaLogs + Tempo query APIs; platform administrator's export only.

Role processes push OTLP traces, metrics and logs to the in-cluster Alloy receiver, while the admin debug bundle reads back on request, for a platform administrator's export only.

Point the exporters at the bundled in-cluster collector when you want zero-configuration observability and are comfortable keeping telemetry inside the cluster. Point them at an external OTLP endpoint instead when a compliance requirement keeps observability data outside the deployment's own cluster, or when you already run a fleet-wide observability backend and want this instance folded into it rather than siloed. Overriding the three endpoints independently is supported. A deployment can send traces to one backend and logs to another.

In the bundled stack's telemetry-forwarding mode, logs pass through an attribute allow list and text redaction before they leave, and metrics and traces are not redacted, as [Hosting and access](https://docs.settlemint.com/docs/deployment/hosting-and-access#2-telemetry-forwarding-only) describes. Treat every signal as data that can contain personal data. Telemetry is for operations: the platform's audit record is the audit trail in [Security and compliance posture](https://docs.settlemint.com/docs/deployment/security-compliance-posture#logging-and-audit-trail).

During shutdown, the process stops accepting new work and makes bounded attempts to release role-owned resources and flush its telemetry exporters before forced exit. The flush runs last so it can report the shutdown itself. The flush is one bounded delivery attempt and gives no delivery guarantee, so the terminal log record also carries any final condition.

## Which signal answers which operational question [#which-signal-answers-which-operational-question]

The three signals answer different questions.

| What you are asking | Reach for | Why |
| --- | --- | --- |
| Which downstream call is responsible when one operation is slow or failing | A trace | Shows the causal path of one request, call by call |
| Whether a rate, count, or duration is trending worse, staying in range, or shifted since a deploy | A metric | Aggregates over time on a 60-second export interval, with up to one export interval of delay before ingestion |
| Exactly what one component reported, once a trace or metric has narrowed the search to a service and a time window | A log | A structured, point-in-time record carrying the identifiers that pivot back to the trace or metric around it |

A webhook delivery attempt that times out, or a Console request that hangs waiting on a database query, are both trace questions.

Because metrics export every 60 seconds (`telemetry.metrics.exportIntervalMs`) by default, a metrics dashboard shows data with up to one export interval of delay before ingestion. Treat a metric reading during an active incident as slightly stale, and confirm a fast-moving condition against a trace or a direct check instead.

A log carries identifiers, such as a request id or a trace id, that let you pivot from a log line back to the trace or metric around it.

Kubernetes health probes (`/healthz` and `/readyz`) are separate from this OTLP pipeline: fast checks the cluster itself polls to decide whether to route traffic to a pod or restart it. They are not exported anywhere and do not appear in VictoriaLogs or Tempo. See [Platform API not ready](https://docs.settlemint.com/docs/deployment/runbooks/platform-api-not-ready) for what each probe checks and what a failure means. In `external` mode the scheduler's `/readyz` also reports the bank FIX sessions it dials, and a session that is not logged on does not take the pod out of Ready, as the [bank rail guide](https://docs.settlemint.com/docs/api-reference/guides/bank-rail#set-up-a-connection) describes.

## The sampling trade-off [#the-sampling-trade-off]

The default 10% trace sample ratio is a head sampler: the platform decides whether to keep a given trace before that request finishes, with no knowledge yet of whether it fails or runs slow. Raising the ratio towards 100% keeps every trace, including the large majority that succeed quickly and tell you nothing new, and ingestion and storage cost rises in direct proportion to the ratio you set.

A downstream tail sampler can keep traces according to their outcome or latency. It can only inspect traces that pass the source sampler. To evaluate every trace, raise source sampling to 100% and size the collector for that incoming load before applying selective retention. Measure exporter, collector, network, and storage costs when changing the ratio.

## Retention is not controlled from this page [#retention-is-not-controlled-from-this-page]

How long a trace, metric, or log line survives in your backend is a property of that backend's own configuration, not of anything in the table above. If your deployment uses the bundled in-cluster stack, its defaults keep logs and traces for 168 hours and metrics for one month. [Observability stack](https://docs.settlemint.com/docs/deployment/install/observability-stack) covers the values that raise them. An investigation that starts days after an incident can fail because retention has expired. Raise retention if you need a longer window.

## Alerts that show a recovery risk [#alerts-that-show-a-recovery-risk]

Alerting is off by default. Set `grafana.sidecar.alerts.enabled` in the `observability` chart to turn these alerts on.

`PostgresDown` and `ChainUnowned` carry `critical` severity and the other recovery alerts carry `warning`, so confirm that your routing reaches someone who can act on each. [Backup and disaster recovery](https://docs.settlemint.com/docs/deployment/backup-recovery) explains the objectives they protect.

| Alert | It fires when | What it protects |
| --- | --- | --- |
| `VeleroBackupFailure`, `VeleroBackupPartialFailure`, `VeleroBackupStale` | A cluster backup failed, partly failed, or no backup succeeded in over 24 hours | The recovery point for cluster volumes |
| `PostgresDown` | The PostgreSQL exporter reports the database as down | The system of record |
| `PostgresReplicationLagHigh` | Replication lag passes 300 seconds | The recovery point after a database failover |
| `ChainUnowned` | A chain has no live indexer owner | Ledger data freshness and catch-up time |
| `IndexerBuildFailed` | A reindex build failed within the last 15 minutes | Rebuild time after a release or a recovery |
| `IndexerSpanRetryLoop` | A lane retried the same failed database statement more than 9 times in 15 minutes, for 30 minutes | Ledger data freshness and rebuild time |
| `IndexerWritingLaneRefused` | The rebuild pods refused to write a build whose data layout this release cannot extend in place | Rebuild time after a release |
| `RpcHealthSelectionDisabled` | Health-based endpoint selection is not active for a network | Failover between ledger endpoints |
| `RedisClientLatchedOffline` | A pod's Redis connection stays unavailable for over five minutes | Cache and notification delivery |

The three Velero alerts read metrics from the Velero server, so they stay silent when no Velero server runs or its metrics are not scraped. `PostgresDown` reads the PostgreSQL exporter, so it stays silent if you set `postgres-exporter.enabled` to `false`. `PostgresReplicationLagHigh` reads replication lag metrics that an exporter reports, either from the primary's replication statistics or from a standby that has its own exporter. It stays silent for a single unreplicated instance and for a managed service whose lag the exporter cannot see.

## The admin debug bundle [#the-admin-debug-bundle]

Console's account menu carries an "Export debug information" item, visible only to a platform administrator or an organisation owner, the same gate the Platform Status page enforces. Selecting it calls a Platform API route that collects the bundle for the window into a zip and downloads it, without giving the requester direct access to the observability cluster. The bundle's recent errors and API requests categories hold only requests made in the requester's active organisation.

Only a platform administrator's export includes the log lines and traces the stack holds for the window, because those carry every organisation's activity on the instance. An organisation owner's export does not query VictoriaLogs or Tempo. Its manifest marks the observability logs and observability traces categories as unavailable, with a note that only a platform administrator's export includes them. The bundle the Console downloads when one of these users stops a recording started from Report an issue follows the same rules.

Set `global.observability.enabled: true` when your deployment includes the bundled [observability stack](https://docs.settlemint.com/docs/deployment/install/observability-stack), and the debug bundle's in-cluster VictoriaLogs and Tempo query endpoints are derived from that stack's release service DNS, so you set no URL. `global.observability.namespace` (default `monitoring`) controls the namespace those derived endpoints target, and has no effect on where the traces, metrics, and logs exporters above send signals: those always target the fixed `obs-alloy.monitoring.svc.cluster.local` host unless you override each `otlp.endpoint` key yourself.

Two settings stay explicit regardless of auto-wiring:

- `dapi.observabilityLogsUrl` / `dapi.observabilityTempoUrl` override the derived endpoints, for an out-of-cluster stack or renamed services.
- `dapi.observabilityBaseUrl` sets the Grafana deep-link base, an external route host never auto-derived from in-cluster service DNS.

## Alert on how long a dependency is unavailable [#alert-on-how-long-a-dependency-is-unavailable]

A gauge that reports whether an input is connected reads the same for a two-second blip and a two-hour outage. Both show the disconnected value, and only the second is an operator's problem. Alert on how long the input has been unavailable.

The platform's own signals follow this pattern. `dalp.didx.ws.unavailable_seconds` tracks how long the chain's `newHeads` WebSocket has been continuously down. `dalp_redis_client_unavailable_seconds` tracks the same for a Redis client. Both sit at `0` while connected. Both escalate their log line from WARN to ERROR once the outage passes 30 seconds. The log threshold is separate from an alert's evaluation and hold periods. The bundled sustained-outage alerts take about six minutes to fire. Tune them for your operating requirements. Reconnection can still recover without operator action after either threshold.

If you build your own alert on such a gauge, measure from when the outage started, not from the latest reconnect attempt: a duration that resets on every attempt stays near zero for the outage that does not resolve itself.

The dashboards and alert rules the bundled stack ships with, and its default retention windows, live with the stack itself: see [Observability stack](https://docs.settlemint.com/docs/deployment/install/observability-stack). The receiving stack's content and storage policy are not covered here.

## The database metrics exporter [#the-database-metrics-exporter]

The PostgreSQL exporter ships enabled by default: it opens one direct session to your PostgreSQL server and reports the aggregate server backend count, on top of the metrics its own upstream collectors define. The platform adds no custom queries of its own. Set `postgres-exporter.enabled` to `false` to remove that session.

If you extend it, do not give a custom query a metric name a built-in collector already publishes. A duplicated name makes the exporter reject the whole scrape and serve nothing. The pod stays ready while that happens, because readiness does not read `/metrics`, so watch `up` and `pg_up` for the gap rather than the pod status.

Treat the exporter's own metric names as a fixed contract, and prefer widening what it already collects over declaring a metric again.

Neither probe queries the database. Both hit `/`, the exporter's static landing page, with a 5-second timeout: readiness every 15 seconds, liveness every 30 seconds. Only the Prometheus scrape of `/metrics` runs the collection, so the database pays for one collection per scrape interval and for nothing else. A readiness probe on `/metrics` would double that cost and would also mark the pod unready when the database is slow, which drops the scrape that carries `pg_up` and the wait metrics exactly when they answer the question.

The per-table collectors, `stat_user_tables` and `statio_user_tables`, ship off. `stat_user_tables` calls `pg_indexes_size` and `pg_table_size` once per user table, so one scrape stats every fork and segment of every relation and index in the database. On a schema with about a thousand tables that is seconds of server time per scrape and tens of thousands of series. Set `postgres-exporter.perTableCollectors` to `true` on a small schema where per-table vacuum, bloat and scan counts are worth that price.

## Frequently asked questions [#frequently-asked-questions]

### What happens if I set `global.observability.enabled` to `true` but never install the observability stack?

The debug bundle still derives the in-cluster VictoriaLogs and Tempo URLs from that flag, whether or not the stack is running. Each query carries its own five-second timeout, and an unreachable or erroring endpoint is reported as an unavailable artifact rather than failing the whole export, so the rest of the bundle still lands. The exporters above are unaffected either way, since they send OTLP to `obs-alloy` independently of this flag.

### Can I disable trace export while keeping metrics and logs exporting?

Yes. Traces, metrics, and logs each carry their own `enabled` key under `telemetry`, defaulting to true, so turning one off leaves the other two untouched. No single switch disables all three at once: disabling logs, for instance, does nothing to the trace or metric exporters, which keep running on their own schedules and their own endpoints.

### Do the three signals authenticate to their collector the same way?

Not necessarily. Each signal's OTLP block carries its own headers key alongside its endpoint, so traces, metrics, and logs can each present a different bearer token or API key, or none at all, to whatever collector they target. That matters most once you split signals across backends: a managed metrics vendor and an in-cluster log store rarely share one credential.

### If I set `dapi.observabilityLogsUrl` explicitly, do I still need `global.observability.enabled: true`?

No. The debug bundle reads that value directly and uses it whenever it is a non-empty, valid HTTP or HTTPS URL, independent of the flag. `global.observability.enabled` only controls whether the chart derives a default for you. An explicit URL is used as given, whether the flag is on, off, or the bundled stack was never installed at all.

### Can the debug bundle's incident window run past my backend's retention?

Yes, if your backend retains less history than the requested window. The bundle's window defaults to the six hours before the request and is capped at 24 hours of lookback regardless of what a caller asks for, well inside the bundled stack's 168-hour default for logs and traces. Retention only becomes a real risk for a direct backend query days or weeks later, which is a different question from this bundle's own short window.


# Prerequisites

Source: https://docs.settlemint.com/docs/deployment/prerequisites
The external endpoints, credentials, and cluster capacity a DALP installation needs ready before you run the Helm charts.

A DALP Instance needs a Kubernetes cluster, network endpoints, datastores, registry access, and generated secrets. No chart deploys the datastores: you supply PostgreSQL, Redis, and object storage, and you verify availability, security, and recovery for each dependency. Complete this checklist before [installing the charts](https://docs.settlemint.com/docs/deployment/install) or changing networks, custody, or hosting.

A gap fails in one of two ways. Values the platform validates at boot, such as a secret below its minimum length or a network entry with no endpoint, prevent the affected application pods from starting right after the install. Gaps the platform cannot validate surface in use: an unreachable SMTP relay fails at the first email, and a bad custody credential fails at the first signature. Confirm both kinds before you start.

[Figure] What the DALP chart runs in your cluster, and what you supply from outside. Two columns. Inside your cluster, the DALP chart runs the Console, the Platform API with its api, runner, indexer, and scheduler roles, and an optional block explorer that ships off by default, plus the docs site, PgBouncer connection pooling, and a PostgreSQL metrics exporter, all on by default. You supply everything else. That is the datastores, namely PostgreSQL, Redis, and object storage, and an ingress controller or Gateway API implementation that serves the class or Gateway the chart names. You also supply an RPC or ledger endpoint per enabled network, an SMTP relay, four generated values for encryption, session signing, governance ballots and custody credential identities, and registry pull access. Two conditional items sit below them: custody provider credentials for managed signing, and an optional SSO provider that replaces local sign-in. A closing rule states that no chart deploys a datastore or an ingress controller: PostgreSQL, Redis, object storage, and routing are services you run and point the charts at. Labels: Runs in your cluster; what the DALP chart deploys; Console; operator web app; Platform API; api, runner, indexer, scheduler; Block explorer; off by default; Also on by default; docs, PgBouncer, exporter; You supply; services, endpoints, credentials; Datastores; PostgreSQL, Redis, object storage; Ingress or Gateway; serves the class or Gateway named; RPC or ledger endpoint; one per enabled network; SMTP relay; every instance sends email; Four generated values; encryption and session signing; Registry pull access; credentials or pull secrets; Custody provider credentials; managed signing only; SSO provider; optional, replaces local sign-in; No chart deploys a datastore or an ingress controller; PostgreSQL, Redis, object storage, and routing are services you run and point the charts at.

The `dalp` chart runs the platform and nothing it depends on, so datastores, ingress, network endpoints, SMTP, secrets
and registry access stay yours.

## Decide first: where the datastores run [#decide-first-where-the-datastores-run]

One fact shapes the rest of this checklist: no chart deploys PostgreSQL, Redis, object storage, or an ingress controller, so each is yours in every environment. The `dalp` chart's default values name placeholder in-cluster endpoints for the three datastores and placeholder passwords for PostgreSQL and Redis. Nothing resolves those names until you run services under them, so set every one before the first install.

For production, point each datastore at a service that provides replication, patching, and backups, whether a managed offering or one you operate. Confirm the selected service plan and settings, then include its endpoint and credentials in this checklist. [Values and secrets](https://docs.settlemint.com/docs/deployment/install/values-secrets#datastores) shows how the connections are configured, and [Topologies](https://docs.settlemint.com/docs/deployment/topologies) covers the deployment shapes.

Each item is marked always yours, conditional or optional.

## What you must supply [#what-you-must-supply]

### An RPC endpoint for every network you enable [#an-rpc-endpoint-for-every-network-you-enable]

Always yours. Every network in the `networks` configuration needs connection details, and the instance refuses to start an EVM entry that has neither a single RPC URL nor a list of upstreams. With more than one upstream, the platform scores upstream health and shifts traffic away from a lagging endpoint.

- The RPC URL, or the list of upstreams, for each EVM network you plan to enable.
- An API-key or basic-auth credential for any upstream that requires one.
- Which network is your default. Exactly one enabled EVM network carries the default flag.

### A custody provider, when signing leaves the platform [#a-custody-provider-when-signing-leaves-the-platform]

Conditional. The `signer.provider` setting decides who holds signing keys. The default, `local`, is the platform's own key store: keys live encrypted inside the platform, protected by the encryption master password below, and nothing external is needed. The keys and their encryption password sit in the same deployment, so a compromised deployment can sign a transaction and nothing external approves it.

A custody provider adds a separately governed signing path with its own controls. Choosing `dfns`, `fireblocks`, `luna`, `ripple` or `utila` moves signing to that provider, and the chart then requires that provider's configuration block, filled with its credentials:

- DFNS: an auth token, or a credential ID and private key. An organisation ID when your DFNS account is scoped to one.
- Fireblocks: an API key and private key. A webhook URL when Fireblocks should call back into the platform.
- Luna HSM: the PKCS11 library path, a token label, and a PIN reference. Client certificate and key references when your HSM requires mutual TLS.
- Ripple Custody: the user ID, client ID, and private key the integration signs with, plus the vault ID and key strategy for the wallets it manages.
- Utila: the service account email and its RSA private key, plus a standby key when you rotate keys. [Set up Utila custody](https://docs.settlemint.com/docs/deployment/utila-setup) covers the vault and network names each organisation enters in the Console.

Ripple and Utila are the two providers this platform ships switched off. Set `global.dalpApp.config.custody.providers.ripple.enabled: true` or `global.dalpApp.config.custody.providers.utila.enabled: true` in your Helm values, or `CUSTODY_PROVIDER_RIPPLE_ENABLED=true` or `CUSTODY_PROVIDER_UTILA_ENABLED=true` outside the chart.

Each custody provider has its own switch, `global.dalpApp.config.custody.providers.<kind>.enabled`. A provider that is off leaves the Console catalogue and the published capability templates, and the platform refuses a new provider configuration that names it. Configurations stored while that provider was on keep signing, and their credentials can still be rotated, because the switch closes intake and does not revoke live accounts. To stop one existing account from signing, quarantine its provider configuration.

Have ready whichever combination your provider's own authentication flow needs. The provider, not the platform, decides which is sufficient. For inbound custody webhooks, DFNS and Ripple each need a webhook secret you supply. Fireblocks webhook verification works against Fireblocks' published key endpoint out of the box. Override it only when your Fireblocks environment publishes keys elsewhere on an https endpoint under `fireblocks.io`, the only host the platform accepts.

### An SMTP relay, because every instance sends email [#an-smtp-relay-because-every-instance-sends-email]

Always yours. Invitations and notifications go out over SMTP, and the platform has no relay of its own. Nothing checks the relay at boot, so a missing or wrong relay surfaces as the first invitation that never arrives. Confirm delivery before your first user is waiting on one.

- An SMTP host and port.
- A username and password for that relay. For a relay that accepts mail from your cluster without authentication, leave both empty. If you set only one of them, the platform sends no email.
- The sender address the platform sends as, which is required, and optionally a sender name, which defaults to `DALP`. With no sender address, the platform sends no email.

Every message carries a `Message-ID` built from the event it announces and the domain of the sender address, in the form `<hash@your-sender-domain>`. The platform records each message in a send-once ledger in PostgreSQL before it hands the message to the relay, and marks it sent afterwards. A message the ledger shows as sent is never sent again. If the platform stops or the relay times out before it can mark a message, it sends that message again with the same `Message-ID`. A relay or mailbox that drops repeated `Message-ID` values then never shows a second copy, and an operator who reads relay logs sees the repeat under one id.

### A PostgreSQL database [#a-postgresql-database]

Always yours. The Platform API stores its state in PostgreSQL and does not start without a reachable database. Provision an instance reachable from your cluster and sized for your load, then set its connection in `global.datastores`.

- A PostgreSQL instance, reachable from the cluster.
- Its connection details: a URL, or hostname, database name, and credentials.
- A pass over the connection budget when you change replica ceilings. See [Values and secrets](https://docs.settlemint.com/docs/deployment/install/values-secrets#how-application-pods-reach-postgres).

### Redis [#redis]

Always yours. The `dalp` chart enables the Redis-backed cache by default. The cache is required because the Console and several Platform API roles run more than one pod out of the box, and the cache's in-memory fallback lives per pod. Without a shared Redis, which pod answers a request would decide what a reader sees. Keep the cache on, and point it at your own endpoint.

- A Redis-compatible endpoint with host, port, and credentials, plus TLS settings when it requires them. DALP's own development and test stacks run Valkey, the BSD-3-Clause fork of Redis, so a managed Valkey service meets this item as well as a managed Redis one.

### An object storage bucket [#an-object-storage-bucket]

Always yours. Every operation that stores or retrieves a file needs a bucket. The default profile selects the S3-compatible provider against a placeholder endpoint. Set the provider, bucket, and endpoint under `global.dalpApp.config.objectStorage`. Pick one provider and have its access ready:

- AWS S3: the bucket's region, plus an access key pair unless you rely on IAM Roles for Service Accounts, the usual workload-identity alternative to a static key.
- Google Cloud Storage: the project ID and a service account key, or inline credentials, unless you rely on Workload Identity, the usual alternative to a static service account key.
- Azure Blob Storage: the storage account name plus an account key, a connection string, a SAS token, or Azure AD Workload Identity as the alternative to a static key.
- Another S3-compatible service: its endpoint, region, access key, and secret key.

A filesystem provider exists for development only. Its default signing key is marked unsuitable for production.

### An encryption master password you generate [#an-encryption-master-password-you-generate]

Always yours. The platform encrypts sensitive data at rest with a master password you generate: at least 16 characters and at least 128 bits of estimated entropy, which in practice means a random string of 40 characters or more. The chart ships the value empty, so leaving it unset prevents the affected application pods from starting at boot. Never re-mint it for an existing environment: data encrypted under the old password becomes unreadable. See [Values and secrets](https://docs.settlemint.com/docs/deployment/install/values-secrets#encryption-at-rest) for the two-step rotation.

- A generated master password of at least 16 characters and 128 bits of estimated entropy, such as a random 40-character string, stored with the rest of your secrets.

### An auth secret you generate [#an-auth-secret-you-generate]

Always yours. `auth.secret` signs and verifies sessions and must be at least 32 characters, with or without SSO. Unlike the master password, the chart does not ship it empty: the values file commits a placeholder that passes the length check. Every pod the chart deploys runs as a production process, whatever `global.deploymentEnvironment` says, and refuses to start on that placeholder.

- A generated secret of at least 32 characters for `auth.secret`, replacing the chart's committed placeholder.
- Replace the placeholder before the first install, because the pods refuse to start on it.

### Two deployment identity values you set [#two-deployment-identity-values-you-set]

Always yours. Keep both unique per deployment and never copy them between installs.

- `global.dalpApp.env.DALP_GOVERNANCE_DOMAIN_SCOPE` names the domain this deployment signs governance ballots under. The chart refuses to render while it is empty or `local`.
- `CUSTODY_CREDENTIAL_IDENTITY_KEY`, at least 32 characters, keys the hashes of custodian credential identities. The platform refuses to start on the chart's local default. [Custody credential identity key](https://docs.settlemint.com/docs/deployment/install/values-secrets#custody-credential-identity-key) covers it.

### Pull access to every image registry the charts reference [#pull-access-to-every-image-registry-the-charts-reference]

Always yours. The charts pull the DALP images from `ghcr.io` and the third-party images from `docker.io`, `quay.io` and `registry.k8s.io`, and the chart itself comes from `pkg.distribution.settlemint.com`. Allow those hosts, or [mirror the images](https://docs.settlemint.com/docs/deployment/hosting-and-access#4-a-mirrored-registry). Either hand the chart registry credentials so it renders the pull secrets for you, or pre-create matching secrets in the target namespace. Without them, pods sit in image-pull errors instead of starting.

- Registry credentials under `global.imagePullCredentials` for the chart to render, or pull secrets already present in the namespace.

### Optional: a single sign-on identity provider [#optional-a-single-sign-on-identity-provider]

The Console signs users in locally with email, password, and passkeys by default, and that path needs nothing from you. If you want an external OIDC provider instead, have its issuer URL, client ID, and client secret ready, and read [Single sign-on](https://docs.settlemint.com/docs/deployment/sso) first: a complete provider entry makes the external provider the sole login method the moment it rolls out.

- The OIDC issuer URL, client ID, and client secret, when you configure SSO.
- A plan for who at your identity provider can grant the platform administrator role, when you set an admin claim.

### Optional: an application secret-manager provider [#optional-an-application-secret-manager-provider]

By default, secrets reach the platform as environment values you inject. If you would rather the platform fetch them at runtime from AWS, Google Cloud, Azure, or Vault, that is a separate configuration layer. See [Values and secrets](https://docs.settlemint.com/docs/deployment/install/values-secrets#application-secret-manager-providers) for what each provider needs.

The platform refreshes exchange rates from a free public currency API over the internet, `cdn.jsdelivr.net` with `currency-api.pages.dev` as fallback, and publishes them to the on-chain feeds. That source carries no service commitment and needs outbound internet access. To use a rate source your organisation approves, set `EXCHANGE_RATE_API_PRIMARY_URL` and `EXCHANGE_RATE_API_FALLBACK_URL`. See the{" "} Market Data concept to verify or replace a feed.

## What your hosting must provide [#what-your-hosting-must-provide]

See [Hosting and access](https://docs.settlemint.com/docs/deployment/hosting-and-access) for how these choices shape topology and access. This section is the checklist to have ready before you install.

### Kubernetes 1.23 or later, or OpenShift with the overlay [#kubernetes-123-or-later-or-openshift-with-the-overlay]

The `dalp` chart and the optional `observability` chart both declare Kubernetes 1.21 or later, but every autoscaler the `dalp` chart renders uses the `autoscaling/v2` API, which Kubernetes serves from 1.23. Plan for Kubernetes 1.23 or later. OpenShift runs the same chart templates through a separate values overlay rather than a different chart. See [Deploy DALP to OpenShift](https://docs.settlemint.com/docs/deployment/install/openshift) for what the overlay changes.

Before any chart, apply the Gateway API CRD bundle once per cluster. No Helm release can carry it, because Helm cannot upgrade CRDs shipped inside a release and the bundle exceeds what a release's stored secret allows.

Skip it and a release that renders an `HTTPRoute` fails at install time on the unknown resource kind, which a first install on a bare cluster hits by default because the docs site's route renders out of the box. OpenShift is the exception: its overlay renders Routes instead of `HTTPRoute` resources for every service, so an OpenShift install has no `HTTPRoute` to fail on and does not need the bundle at all.

[Install](https://docs.settlemint.com/docs/deployment/install) covers the bundle's version and where it sits in the order.

- The Gateway API CRD bundle applied to the cluster, before any chart, unless you install on OpenShift, whose overlay renders Routes instead and needs no CRD bundle.
- A Kubernetes cluster at 1.23 or later, or an OpenShift cluster with the overlay applied.
- Nodes with x86-64 CPUs. Every DALP image is built for Linux on x86-64.
- A resource metrics API, such as metrics-server, so the autoscalers can read pod CPU. Without one, every autoscaled component stays at its floor.
- At least two schedulable nodes. PgBouncer's two replicas must run on different nodes.
- A default `StorageClass` that can bind the volumes the charts request, such as the persistent volumes of the observability stores.
- When you enable the chart's contract-deployment job: a Retain-policy `StorageClass` for its journal volume, or the cluster's CSI provisioner plus permission to create `StorageClass` resources so the chart can create the Retain class for you. The job resumes from that journal after a pod restart, and losing the volume forces a fresh deployment at new addresses your running network cannot reconcile.

### One exposure mechanism per service, and TLS you bring [#one-exposure-mechanism-per-service-and-tls-you-bring]

The Console ships with ingress enabled. With local sign-in, the first account created on a fresh instance becomes a platform administrator, so create it before the Console's hostname is reachable from outside your network. Every later sign-up is a member, even after the last platform administrator loses the role. A platform administrator grants the role to another account on that account's Platform users page. When no platform administrator is left, [Security and compliance posture](https://docs.settlemint.com/docs/deployment/security-compliance-posture#restore-the-platform-administrator-role) shows how to restore the role.

The docs site ships with its own ingress enabled too, routing `/docs` on the Console's hostname. The Platform API stays internal, reached through the Console's own proxy. The block explorer is off by default and brings its own ingress when you enable it. Choose one intended exposure path per service from Ingress, Gateway API `HTTPRoute`, and OpenShift `Route`. If multiple objects render, inspect their hostnames and controller ownership for conflicting routes. The [OpenShift troubleshooting section](https://docs.settlemint.com/docs/deployment/install/openshift#troubleshooting) shows what that looks like.

Outside OpenShift, bring your own ingress controller. The `dalp` chart's ingresses name the class `dalp-nginx` by default, so either your controller registers a class with that name or you set `ingressClassName` on each ingress to match it. Reach for Gateway API `HTTPRoute` instead when your cluster standardises on a Gateway API implementation such as Envoy Gateway: each route names the Gateway it attaches to, so create that Gateway or point the route at yours. On OpenShift, skip the ingress controller, since Routes replace ingress there and the controller has nothing to do.

TLS differs by platform. Outside OpenShift, the chart requests no certificates: add cert-manager annotations or pre-created TLS secrets to the ingress, or HTTPS to your hostnames fails while plain HTTP answers. On OpenShift, Routes terminate TLS at the edge with the router's certificate and redirect plain HTTP. HTTPS therefore works without cert-manager. The optional per-Route cert-manager Certificate is off by default. Replace its placeholder issuer with your cluster's issuer before enabling it.

- An ingress controller, a Gateway API implementation, or OpenShift Routes: exactly one per exposed service.
- A load balancer the controller can obtain an external address from.
- A certificate source outside OpenShift: cert-manager wiring or pre-created TLS secrets.
- DNS entries for every hostname you plan to expose.

### Backups decided and tested before production [#backups-decided-and-tested-before-production]

The platform starts without a backup plan, and production without one leaves a failure with no recovery path. The `dalp` chart's Velero backup block ships turned off, and the chart never deploys a Velero server. Your database and object store need their own backup story, whether a managed service provides it or you operate it.

- A backup and restore approach for PostgreSQL and object storage, tested before go-live. See [Backup and disaster recovery](https://docs.settlemint.com/docs/deployment/backup-recovery) for what a tested approach covers.

### Resource sizing starts from the chart defaults [#resource-sizing-starts-from-the-chart-defaults]

The chart sets CPU and memory requests and limits for every long-running container, except that the PgBouncer metrics sidecar has a memory limit but no CPU limit. Treat them as a starting footprint that you size for your own load, not a guarantee of capacity. 1000m is one CPU core. Production needs depend on the networks you index and their block volume, the number of participants, and the request rate, and the chart cannot see any of these in advance.

| Component | Requests to limits, per pod | Replicas |
| --- | --- | --- |
| Platform API `api` role | 600m to 1500m CPU, 1536Mi to 3Gi memory | 2 to 24, target 50% CPU |
| Platform API `api` role, frozen v1 fleet that serves the older `/api/v1` contract | 300m to 1000m CPU, 768Mi to 1536Mi memory | 1 to 4, target 50% CPU |
| Platform API `runner` role | 250m to 1500m CPU, 1536Mi to 3Gi memory | 2 to 12, target 75% CPU |
| Platform API `indexer` role, serving pods | 1250m to 2000m CPU, 1536Mi to 3Gi memory | 2, fixed. One network's live indexing stays on one pod |
| Platform API `indexer` role, rebuild pods | The same as the serving pods | 2, fixed |
| Platform API `scheduler` role | 250m to 1500m CPU, 1Gi to 2Gi memory | 1, fixed |
| Console | 50m to 200m CPU, 512Mi to 756Mi memory | 2 to 30, target 80% CPU |
| Docs site | 100m to 500m CPU, 756Mi to 1024Mi memory | 2 to 5, target 80% CPU |
| PgBouncer | 100m to 500m CPU, 128Mi to 256Mi memory, plus a metrics sidecar at 10m CPU with no CPU limit and 32Mi to 64Mi memory | 2, fixed |
| PostgreSQL metrics exporter | 100m to 200m CPU, 32Mi to 128Mi memory | 1, fixed |
| Investor portal, off by default | 100m to 500m CPU, 256Mi to 512Mi memory | 2 to 5, target 80% CPU |
| Block explorer backend, off by default | 100m to 600m CPU, 640Mi to 1280Mi memory | 1, fixed |
| Block explorer frontend, off by default | 100m to 360m CPU, 320Mi to 640Mi memory | 1 to 5, target 80% CPU |

At their floor replica counts, the pods that run by default request about 7.9 CPU cores and 16.6 GiB of memory in total. The four indexer pods, serving and rebuild, account for 5 of those cores. Each autoscaler adds pods beyond its floor when average CPU passes its target, so plan node capacity for the ceilings you allow, not only the floors. With every default autoscaler at its ceiling, the same pods request about 26.2 CPU cores and 83 GiB of memory.

These totals count the long-running pods and leave out one-off Jobs. To change a row, set `dapi.v2.autoscaling`, `dapi.v1.autoscaling`, `dapi.runnerDeployment.autoscaling`, `dapi.indexerDeployment.replicaCount`, `dapi.indexerDeployment.rebuild.replicas`, `dapi.schedulerDeployment.replicaCount` or the matching block of another component. The rebuild pods idle while no reindex build exists. `dapi.indexerDeployment.rebuild.enabled: false` removes them, and every serving pod then also writes reindex builds. [Topologies](https://docs.settlemint.com/docs/deployment/topologies#high-availability-by-component) covers what each role does and what a failure of each costs.

Your datastores add their own footprint, which the table does not count. Supply a `StorageClass` that can bind the volumes the charts request and a load balancer that can assign an address to your controller. On managed clouds, workload identity can replace the static keys in the checklists. A self-managed or bare-metal cluster brings its own load balancer and injects every credential as a secret.

## How a missing item shows up [#how-a-missing-item-shows-up]

You are ready to install when you have confirmed every item in both checklists and can name where each credential lives. If something slips through anyway, this is the signal each gap gives:

| Missing or wrong | Signal | When |
| --- | --- | --- |
| Gateway API CRDs not applied before the charts | The release fails at install time on the unknown `HTTPRoute` kind | At install |
| Master password unset, too short or too weak | Pods crash-loop, and the log names the failed length or entropy check | At boot, right after install |
| Auth secret left at the chart's committed placeholder | Pods crash-loop, and the log names the rejected default | At boot, right after install |
| `DALP_GOVERNANCE_DOMAIN_SCOPE` empty or `local` | The render fails and names the value | At install |
| Custody credential identity key left at the local default | Pods crash-loop, and the log names the rejected default | At boot, right after install |
| An EVM network with no RPC URL or upstream list | Pods crash-loop, and the error asks for a URL or upstreams | At boot |
| No default network, or two of them | Pods crash-loop, and the error names the offending entries. See [Networks](https://docs.settlemint.com/docs/deployment/networks) | At boot |
| A managed custody provider selected without its config block | Pods crash-loop, and the error names the missing section | At boot |
| `signer.provider` naming a provider this deployment switched off | Pods crash-loop, and the error names `CUSTODY_PROVIDER_<KIND>_ENABLED` | At boot |
| Pull secrets absent | Pods never start and report image-pull errors | At rollout |
| SMTP relay unreachable or wrong | The first invitation email never arrives, with no boot error | In use |
| Custody credentials present but invalid | The first signing request against that provider fails | In use |
| No certificate source outside OpenShift | HTTPS to exposed hostnames fails while HTTP answers | At first access |

## Frequently asked questions [#frequently-asked-questions]

### Can I run each datastore on a different service, such as a managed Redis with a self-operated PostgreSQL?

Yes. The `dalp` chart points each dependency at its own connection details independently, so each datastore can run on a different service. Each one carries the limits of whoever operates it, so a production setup needs a tested backup plan for every datastore your own team runs.

### Can a deployment sign through two custody providers at once, such as DFNS for one network and the local key store for another?

The deployment has a default `signer.provider`, while an organisation can select a configured provider during onboarding. That organisation choice becomes fixed once its first wallet is created. Review [Custody providers](https://docs.settlemint.com/docs/concepts/custody-and-signing/custody-provider) and configure the required provider credentials before onboarding.

### What changes when I add a network or move custody after go-live?

Adding a network touches only the network checklist: give the new entry its RPC URL or upstream list, and decide whether it becomes the default, since exactly one enabled EVM network carries that flag. The SMTP relay, the generated values and registry access stay as configured.

Moving custody touches only the custody checklist: set `signer.provider`, supply its configuration block, and add a webhook secret for DFNS or Ripple Custody's inbound webhooks. Moving to Ripple Custody adds one step: switch Ripple on with `global.dalpApp.config.custody.providers.ripple.enabled: true`, because the platform ships Ripple off. The master password and auth secret stay untouched.

They protect data at rest and sessions, not who holds the signing keys.

### I do not plan to use Gateway API. Why does the Gateway API CRD bundle still block my first install?

Because the docs site renders both a classic Ingress and a Gateway API `HTTPRoute` by default, so its manifest names a resource kind the cluster must already recognise even though no Gateway controller is running to serve it. No Gateway controller ships with the charts, so the route does nothing until you supply a Gateway. Skipping the bundle only moves the failure earlier, to the unrecognised kind. Apply the CRDs or turn off every rendered `HTTPRoute`, including `docs.httpRoute.enabled`. On OpenShift, its overlay renders Routes instead of `HTTPRoute` for every service, so the bundle has nothing to guard there and you can skip it entirely.

## See also [#see-also]

- [Install](https://docs.settlemint.com/docs/deployment/install) for the chart set, the Gateway API CRD prerequisite, and the install order.
- [Values and secrets](https://docs.settlemint.com/docs/deployment/install/values-secrets) for how each credential reaches the chart.
- [Deploy DALP to OpenShift](https://docs.settlemint.com/docs/deployment/install/openshift) for the OpenShift overlay and its own preconditions.
- [Networks](https://docs.settlemint.com/docs/deployment/networks) and [Single sign-on](https://docs.settlemint.com/docs/deployment/sso) for the configuration these prerequisites feed into.


# Price source prerequisites

Source: https://docs.settlemint.com/docs/deployment/price-source-prerequisites
The network paths, address rules, size caps, secret store, and alerts an operator sets before a price source can fetch from SFTP, FIX, Bloomberg, or LSEG.

A price source is a configured connection to an SFTP server, a FIX session, Bloomberg or LSEG that fetches prices on your behalf, so the deployment must allow that traffic. The scheduler workload, the part of the platform that runs background jobs, opens every connection to a provider. Before the first source goes live, check five things: the address rules, a fixed outbound address for Bloomberg, the paths to each provider, a production secret store, and the stale-feed alert. The size and time caps work at their defaults, and you tune them only for larger deliveries. A source for a public SFTP, FIX, or vendor host needs no address-rule change. A provider on a private network does.

The Bloomberg and LSEG requests are built from each vendor's public documentation and have not run against the live services, so test them with your own vendor account in a non-production deployment before you rely on them.

This page is for the operator who owns the Helm release. For the feeds manager who creates sources through the Platform API, use [Read and submit price feeds](https://docs.settlemint.com/docs/api-reference/guides/feeds). For what a price source is and how its checks work, use the [external price sources release note](https://docs.settlemint.com/docs/changelog/dalp-3-2/market-data).

## Settings you may change [#settings-you-may-change]

Every setting sits in the `priceSources` section of the platform configuration. In the `dalp` chart the section is `global.dalpApp.config.priceSources`. Each value is a placeholder of the form `${VAR:-default}`, so the matching `PRICE_SOURCES_` variable on the pod moves it. A literal value in the chart pins the field, and the variable then has no effect. No tenant API reads or widens these settings.

The API pods and the scheduler pod read the same section. The API pods check the host of a source when you create or edit it. The scheduler pod checks again at every connection and enforces the caps.

```yaml
# Illustrative values: allow a private proxy range and send vendor traffic through it.
global:
  dalpApp:
    config:
      priceSources:
        allowedEndpointCidrs: "10.20.0.0/16"
        forwardProxyUrl: "http://10.20.4.10:3128"
```

## The endpoint allow list [#the-endpoint-allow-list]

By default a price source can reach public hosts only. The setting `priceSources.allowedEndpointCidrs`, set by `PRICE_SOURCES_ALLOWED_ENDPOINT_CIDRS`, lists the address ranges that private providers sit in. It is empty by default. Write ranges in CIDR form, such as `10.20.0.0/16`, separated by commas or spaces. The platform refuses a value that holds anything else.

Without an entry, the platform refuses a host that is, or resolves to, any of these:

| Refused class | Examples | Can the allow list lift it |
| --- | --- | --- |
| Loopback | `127.0.0.0/8`, `::1`, `localhost` and names ending in `.localhost` | Yes for an address. The `localhost` names stay refused |
| Link-local | `169.254.0.0/16`, `fe80::/10` | Yes |
| Private | `10.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16`, `100.64.0.0/10`, `fc00::/7`, and other reserved ranges | Yes |
| Unspecified | `0.0.0.0/8`, `::` | Yes |
| Metadata | `169.254.169.254`, `169.254.170.2`, `168.63.129.16`, `100.100.100.200`, and the names `metadata`, `metadata.google.internal`, `metadata.tencentyun.com`, `instance-data` | No. No range lifts it |
| Numeric alias | A host written as a bare number or in a short or hexadecimal form, such as `2130706433` or `0x7f.1` | No |

A range that covers a metadata address does not lift the refusal for that address. If your provider sits in `169.254.0.0/16`, the allow list admits it, and the metadata addresses inside that range stay refused.

The two places that check a host differ:

- The API checks the host as written when a feeds manager creates, edits, or activates a source. It does not resolve a name. A refusal answers 422 with [DALP-14704](https://docs.settlemint.com/docs/api-reference/errors).
- The scheduler resolves the name at every connection and checks every address the name returns. If any address is refused, the connection fails. The scheduler then connects to the address it checked, so a name that changes its answer between the check and the connection cannot reach an internal address. A host that resolves to a refused address is a configuration failure, and the delivery is recorded as `blocked_egress`.

A vendor call follows at most five redirects, and never to another origin than the vendor's own.

If your network uses DNS64, which maps an IPv4 host into `64:ff9b::/96`, add `64:ff9b::/96` to the list so a public IPv4 provider resolves. The IPv4 address embedded in such an address is still checked against the metadata ranges, the allow list, and internal ranges.

### Plaintext FIX [#plaintext-fix]

A FIX source uses TLS or plaintext. The platform accepts plaintext only for a host inside the allow list. A plaintext source that names a host outside it answers 422 with [DALP-14705](https://docs.settlemint.com/docs/api-reference/errors). Because the API checks the host as written, name the counterparty by an IP address that the allow list covers. The scheduler repeats the test on the address the host resolves to.

### Server name check for TLS [#server-name-check-for-tls]

A FIX source with TLS carries a server name. The scheduler connects to the checked address and verifies the counterparty certificate against that server name. A certificate that does not verify is a configuration failure, and the source stops after three refusals in a row. The source has a server name field and no field for a certificate authority.

## Size and time caps [#size-and-time-caps]

Every delivery is read under a cap, so the scheduler rejects an oversized file at the cap. The scheduler reads a delivery into memory, so size the scheduler pod's memory limit before you raise a cap.

| Setting | Environment variable | Default | Allowed range | What it caps |
| --- | --- | --- | --- | --- |
| `maxFileBytes` | `PRICE_SOURCES_MAX_FILE_BYTES` | 26,214,400 bytes | 1 to 1,073,741,824 | One SFTP file, and one Bloomberg or LSEG download |
| `maxRows` | `PRICE_SOURCES_MAX_ROWS` | 250,000 | 1 to 10,000,000 | Records in one delivery, and entries in one SFTP directory |
| `maxInflatedBytes` | `PRICE_SOURCES_MAX_INFLATED_BYTES` | 104,857,600 bytes | 1 to 4,294,967,295 | The size a compressed delivery may inflate to |
| `maxXmlEntities` | `PRICE_SOURCES_MAX_XML_ENTITIES` | 10,000 | 1 to 1,000,000 | Entity references in one ISO 20022 document |
| `maxXmlDepth` | `PRICE_SOURCES_MAX_XML_DEPTH` | 32 | 1 to 256 | Element nesting in one ISO 20022 document |
| `maxFixGroupEntries` | `PRICE_SOURCES_MAX_FIX_GROUP_ENTRIES` | 1,000 | 1 to 100,000 | Entries in one FIX repeating group |
| `maxFixBodyBytes` | `PRICE_SOURCES_MAX_FIX_BODY_BYTES` | 65,536 | 1 to 16,777,216 | The body of one FIX message |
| `evidenceRetentionDays` | `PRICE_SOURCES_EVIDENCE_RETENTION_DAYS` | 365 | 1 to 3,650 | Days the raw delivery is kept as evidence in object storage |
| `indexerLagBoundSeconds` | `PRICE_SOURCES_INDEXER_LAG_BOUND_SECONDS` | 300 | 1 to 86,400 | Seconds the indexer may trail the chain head before the stale-feed sweep stops judging |

The row cap, `maxRows`, counts records in one delivery. A Bloomberg or LSEG delivery counts rows times price fields against it.

What happens when a delivery passes a cap:

- A file over `maxFileBytes` settles as `failed_validation`. The read stops one byte past the cap, so the platform never holds the rest.
- A file or vendor result with more records than `maxRows` settles as `failed_validation`. An SFTP directory with more entries than `maxRows` fails the poll as a configuration failure.
- A Bloomberg or LSEG request whose mapped ISINs times requested price fields pass `maxRows` fails as a configuration failure before the scheduler sends anything.
- A compressed delivery that inflates past `maxInflatedBytes` fails validation.
- A FIX message with a repeating group over `maxFixGroupEntries` gets a session-level reject, and no part of it becomes an observation. A FIX message body over `maxFixBodyBytes` is not read as a message, and the session fails as a data failure that the platform retries.

The scheduler also enforces fixed deadlines that have no setting.

| Deadline | Value |
| --- | --- |
| Total read of a file or body | 30 seconds plus 1 second for each 64 KiB of the cap, rounded up. About 430 seconds at the default `maxFileBytes` |
| Total read of a vendor control call | 46 seconds. These calls are capped at 1 MiB |
| Vendor call, until it answers | 120 seconds |
| Vendor body with no bytes arriving | 120 seconds |
| Opening a socket | 15 seconds. An SFTP session then has 30 seconds to open and 60 seconds to list a directory |
| FIX logon | 30 seconds |
| Connection test | 30 seconds |

A file read, vendor call, or vendor body that passes its deadline fails as transient, and the platform retries with backoff.

## Bloomberg: a fixed egress address or a forward proxy [#bloomberg-a-fixed-egress-address-or-a-forward-proxy]

Bloomberg Data License accepts calls only from addresses you have registered with Bloomberg. The scheduler sends the calls to `api.bloomberg.com` over HTTPS. The address Bloomberg sees must therefore be one that does not change, and you register it in the Bloomberg Enterprise Console.

You have two ways to supply that address:

| Option | What you do | Cost |
| --- | --- | --- |
| Fixed address on the cluster | Route the scheduler pod's outbound traffic through an address that does not change, and register it with Bloomberg | You change the cluster's outbound path for the whole scheduler pod |
| Forward proxy | Set `priceSources.forwardProxyUrl` to a proxy with a fixed address, and register the proxy's address | You run a proxy. Only vendor traffic uses it |

`forwardProxyUrl`, set by `PRICE_SOURCES_FORWARD_PROXY_URL`, is empty by default, which connects directly. A value must be an `http` or `https` URL without credentials. It carries Bloomberg and LSEG traffic only. SFTP and FIX connections never use it. The proxy must forward HTTPS requests to the vendor host.

The proxy host passes the same guard as a provider host. A proxy on a private address, such as an in-cluster service, needs its range in `allowedEndpointCidrs`. The platform also resolves and checks the vendor host from the scheduler before it sends a request through the proxy, so the scheduler needs working name resolution for it.

If Bloomberg refuses the address, the platform shows it in three places:

- The delivery is recorded as `blocked_egress`. Its detail names the address Bloomberg saw, when Bloomberg's answer states it.
- The source reports a configuration failure and retries after one hour. After three refusals in a row the source stops until a feeds manager pauses and activates it.
- A connection test from the scheduler fails with the same reason and carries the address in its result.

Each Bloomberg call carries a signed token with a timestamp. If Bloomberg's clock differs from the scheduler's by more than 10 seconds, Bloomberg refuses the call. The platform then retries after five minutes and reports the skew. Keep the scheduler host clock synchronised.

## Network paths to each provider [#network-paths-to-each-provider]

Only the scheduler workload opens these connections. It is the scheduler role of the `dalp` chart, and it runs one replica by default. If you restrict outbound traffic with a network policy of your own, allow these paths for it.

| Protocol | Outbound path from the scheduler | Notes |
| --- | --- | --- |
| LSEG | HTTPS to `selectapi.datascope.lseg.com` | Direct, or through the forward proxy. The platform never follows a result location on another origin |
| Bloomberg | HTTPS to `api.bloomberg.com` | Direct, or through the forward proxy. See the Bloomberg section |
| FIX | TCP to the counterparty host and port you set on the source | The scheduler starts the session and keeps it open inside the daily hours of the source. TLS with a server name, or plaintext inside the allow list. Never through the proxy |
| SFTP | TCP to the host and port you set on the source | Read only. The platform lists directories and reads files and never writes. Never through the proxy |

Every host name must resolve from the scheduler pod. For SFTP, a feeds manager accepts the server's host key fingerprint through the API before the first poll.

## Secrets [#secrets]

A provider credential is stored through the platform's secret store, and no response, log, or error returns it. A feeds manager sets it with `PUT /api/v2/price-sources/{sourceId}/credential`. The API pods write the credential and the scheduler pod reads it, so both pods must use the same secret store.

You choose one secret store for the deployment. Set `secretManager.provider` to `local`, `aws`, `gcp`, `azure`, or `vault`, and fill the block for the provider you chose. In the `dalp` chart the setting is `global.dalpApp.config.secretManager`. The `local` provider keeps secrets in the platform's own database and fits development. For production, choose the manager your organisation already runs. [Secret-manager providers](https://docs.settlemint.com/docs/deployment/install/values-secrets#application-secret-manager-providers) describes each choice. The platform keeps each source credential in its own entry and deletes the entries when a feeds manager retires the source.

If the scheduler cannot read the store, the source fails the fetch. An unreachable store is a transient failure that retries. A store that refuses the read for a reason a retry cannot fix is a configuration failure.

## Observability [#observability]

Price source logs share the category `market-data.price-source`. Search your log store for that category, then narrow by field.

| Field | Meaning |
| --- | --- |
| `source_id` | The price source the line is about |
| `failure_class` | `transient`, `credential`, `config`, or `data`, on a warning that the adapter stopped delivering and on the error that a source stopped |
| `reason` | The failure text, or the reason a counterparty gave |
| `expires_in_days` and `warning_threshold_days` | A Bloomberg credential nearing expiry. Warnings come at 30, 7, and 1 days |
| `ref_seq_num` | The FIX message number a counterparty rejected |
| `isins` | The ISINs a FIX counterparty cannot serve |
| `chain_id` and `instrument_id` | The chain or mapping the stale-feed sweep could not judge |

The stale-feed signals are:

- The gauge `dalp_market_data_stale_price_feeds` counts mapped feeds past their staleness bound, for each `chain_id`. It has no source label. The operations case of kind `stale-feed` names the source and the cause.
- The gauge `dalp_market_data_price_feed_indexer_lag_seconds` shows how far the indexer trails the chain head. While it passes `indexerLagBoundSeconds`, the sweep makes no judgement on that chain and the first gauge keeps its last value.
- The counter `dalp_market_data_stale_sweep_pass_errors_total` counts sweep passes that could not judge every feed.

The observability chart ships two price source alert rules in its `MarketData` group. `StalePriceFeeds` fires at warning severity when the gauge stays over 0 for 15 minutes. `PriceSourceStaleSweepFailing` fires when 10 or more passes fail within 15 minutes. The rules stay dormant until you enable them, as [Alert rules are a deliberate second step](https://docs.settlemint.com/docs/deployment/install/observability-stack#alert-rules-are-a-deliberate-second-step) explains. [Observability](https://docs.settlemint.com/docs/deployment/observability) describes how the platform exports logs, metrics, and traces to that stack.

## Next steps [#next-steps]

- [Set up a source and read its error codes](https://docs.settlemint.com/docs/api-reference/guides/feeds)
- [Choose a secret-manager provider](https://docs.settlemint.com/docs/deployment/install/values-secrets)
- [Install the observability stack](https://docs.settlemint.com/docs/deployment/install/observability-stack)


# Ripple policy

Source: https://docs.settlemint.com/docs/deployment/ripple-policy
The properties DALP sets on every Ripple intent, how to write Ripple policies that match them, and the operation names that changed between DALP 3.1 and 3.2.

Ripple Custody is a custody provider. It decides who must approve each request that DALP files with it, in the custody approval step before it signs. Ripple calls that request an intent and decides with its policies. This page lists the properties DALP sets on every intent, so that a policy can match them. A deployment that upgrades from 3.1 also changes the policies that name an old operation, as [Operation names that changed from 3.1 to 3.2](#operation-names-that-changed-from-31-to-32) lists. A new 3.2 installation can skip that section.

A policy that matches nothing stops the intent. Ripple runs only the intents that a policy covers, so a policy that names an old value leaves the matching operations unable to run. Set your policies before you onboard investors, and test them with one write of each kind you use.

## How Ripple picks a policy [#how-ripple-picks-a-policy]

Ripple runs one policy for each intent. Among the policies that apply to the intent and whose condition matches, Ripple runs the one with the highest rank, or the older one at equal rank. An intent that no policy matches cannot run.

[Figure] Ripple runs the highest ranked policy that matches the properties of an intent. An intent from DALP carries a description and the properties dalpKind token.grant-role, dalpRoles admin and dalpChainId 11155111. Ripple checks three policies. The rank 40 policy on dalpRolesUndescribed does not match, because DALP did not set that property. The rank 30 policy on dalpRoles containing admin matches. The rank 10 policy on dalpKind token.grant-role also matches. Ripple runs the rank 30 policy, the highest rank that matches. An intent that matches no policy cannot run. Labels: Intent from DALP; A description for approvers; dalpKind: token.grant-role; dalpRoles: admin; dalpChainId: 11155111; dalpLane: order; Rank 40, no match; dalpRolesUndescribed is true; Rank 30, match; dalpRoles contains admin; Rank 10, match; dalpKind is token.grant-role; Rank 30 runs; The highest rank that; matches decides who; must approve; An intent that matches no policy cannot run.

How Ripple picks one policy for an intent from its properties and the rank of each matching policy.

DALP signs each intent that it files, so Ripple treats it as a user-signed proposal. A policy that omits the intent origin matches it. A policy for system-signed proposals only does not. Under Ripple's `CoerceDescendants` governing strategy, a policy in a parent domain overrides a policy in a child domain, whatever its rank.

Ripple matches a value exactly with `is`, or matches text inside it with `contains`, and combines conditions with `AND` and `OR`, as its [policy reference](https://docs.ripple.com/products/custody/governance/policies/reference) describes.

## What DALP sets on every intent [#what-dalp-sets-on-every-intent]

Each intent carries a description for the approver and the custom properties below. The description starts with the name and symbol of the contract the request calls, such as `Acme Bond (ACME): mint(...)`, when the request calls one contract that has a name. It names the action, the asset or contract, the amount, and the counterparty, and DALP keeps it to 250 characters. A call that also sends the chain's coin ends with that amount, such as `depositTo(account=0x…) with 0.04 native`. A list of addresses, numbers or true/false values shows its first three entries and how many more follow. A list of roles shows the role names, and any other list shows its count, such as `[2 items]`. A list that holds a number of more than 32 digits, such as a list of claim topic ids, shows its count. A country code passed as a number in its own argument shows as its two letters and its number, such as `SA (682)`. A country code inside a structure does not read this way: a token created from an instrument template passes its settings as one structure, so its description shows the name, symbol, type and decimals of the token and not its country. A description that runs past 250 characters is cut from the end of the call, so a call that lists addresses can lose its last arguments, such as the country list of a batch registration. DALP limits each property value to 100 characters. DALP writes the description and every property itself, and Ripple does not check them against the request, so a policy that matches them trusts DALP's account of the request.

| Property | What DALP sends |
| --- | --- |
| `dalpKind` | The DALP operation, for example `token.mint` or `paymaster.sponsorship`. The list under this table says which operation each kind of request sends. |
| `dalpRoles` | The roles that the request changes, separated by commas, for example `supplyManagement,custodian`. Each role is on the contract in `dalpContract`. |
| `dalpRolesUndescribed` | `true` when DALP cannot list every role the request changes. DALP leaves it out otherwise. |
| `dalpContract` | The address of the contract the request is for, in lowercase: the contract a transaction calls, or the contract that checks a signature. On a user operation, it appears only with `dalpRoles`, so a policy on `dalpContract` matches a user operation only when the operation changes roles. |
| `dalpChainId` | The network, as a decimal chain ID, for example `11155111`. |
| `dalpLane` | `order` when Ripple signs and sends a transaction, `manifest` when Ripple signs a payload and returns the signature, `account` when Ripple creates or updates an account, `display` when Ripple files a ticker or a named endpoint. |
| `dalpSignature` | On a `manifest`, what Ripple signs: `typed-data`, `message`, `userop` for a user operation, or `raw` for a transaction that DALP sends. |
| `dalpEip712Domain` | On typed data and user operations, the name of the signing domain and its version, for example `DALPIdentityFactory v3`. |
| `dalpEip712PrimaryType` | On typed data and user operations, the type of the message that Ripple signs, for example `CreateIdentityWithManagementKeys`. |
| `dalpEip712Verifier` | On typed data and user operations, the contract that checks the signature, in lowercase. |
| `dalpEip712Message<Field>` | On typed data and user operations, one property for each field of the message that has a value, for example `dalpEip712MessageWallet`. An address is in lowercase and a number is in decimal. A list is separated by commas and cut like `dalpRoles`. A field that holds another structure is left out. |
| `dalpOrganizationId` | The DALP organisation that filed the intent. |
| `dalpExternalId` | DALP's ID for the request, to trace an intent back to DALP. |

The operation in `dalpKind` depends on the request:

- A data feed, settlement, token sale or trading venue transaction sends its own operation, for example `feeds.submit`, `xvp.execute`, `token-sale.buy` or `tradingvenue.halt-market`.
- A custody withdrawal payout sends `custody-ops.withdrawal-payout`.
- When a settlement or token sale write first sends an ERC20 allowance, that transaction carries the same kind as the write, for example `token-sale.buy`, and `dalpContract` names the token.
- A transaction that names no operation sends `txqueue.enqueue`, the generic name of DALP's transaction queue.
- A smart account runs its operations as user operations. When Ripple holds the owner key of a smart account, the user operation that Ripple signs sends the operation that it runs, for example `token.mint`, so a policy on `dalpKind` `is` `token.mint` matches that mint too. DALP sends `userOp` only for a user operation that carries no operation name.
- On a multisig wallet, a smart account that needs signatures from more than one member, the signature of the member who starts the operation also sends the operation, and each approval sends `user-operation.approve`.
- When Ripple holds the key that submits user operations to the chain, that transaction sends `aa.bundle`.
- With named endpoints on, the request that files a ticker sends `custody.display.ticker`, and the request that files an endpoint sends `custody.display.endpoint`.

DALP 3.1 sent every property in this table except `dalpRolesUndescribed` and the `dalpEip712` properties. The `dalpKind` values changed, as the last section lists.

## Name contract destinations [#name-contract-destinations]

`RIPPLE_NAMED_ENDPOINTS`, the config key `signer.ripple.namedEndpoints`, is off by default. While it is off, DALP makes no ticker, endpoint or ledger call, every order goes to the bare address it calls, and the intent description names the contract. The chart has no value for it. Set it in the `signer.ripple` config override that a Ripple signer needs.

With it on, DALP files a Ripple ticker for each token it creates and a named endpoint for each organisation smart wallet, system contract and token. An order to a contract goes to its endpoint once Ripple approves the endpoint and leaves it unlocked. Any other order keeps the bare address. The setting also sends text messages as `EIP-191` content, so an approver reads the message instead of prefixed bytes.

A policy written for orders to an address can stop matching an order to an endpoint, and the same holds for a message of the `EIP-191` type. Check both before you turn the setting on. Only tokens and contracts deployed after that get an endpoint, unless an administrator adds older ones by hand.

## Policies for role changes [#policies-for-role-changes]

A role change is the request most worth a stricter workflow. DALP marks each role change so that a policy can find it.

When the role list is longer than 100 characters, DALP sends the leading role names that fit, adds `+N` for the N roles it left out, and sets `dalpRolesUndescribed` to `true`. A grant of twelve roles on the platform's access manager contract, for example, can send `admin,auditor,systemManager,tokenManager,complianceManager,claimPolicyManager,claimIssuer,+5`.

DALP also sets `dalpRolesUndescribed` to `true`, with no `dalpRoles`, when it cannot name every role, or when the roles are not all on one contract:

- A role ID that DALP does not know.
- A batch that changes roles and also calls another contract.
- A call that passes a role change on to another contract to run.
- A call that carries other calls inside it and that DALP cannot unpack, even when it changes no role.

DALP reads roles only from calls to functions that it knows. A call to a function that DALP does not know adds no name to `dalpRoles` and does not set `dalpRolesUndescribed`, even when it changes a role, so that intent gets the policy that its other properties match.

Add a `dalpRolesUndescribed` policy and rank it above your role policies, because Ripple runs only one policy for each intent.

1. Add one policy that matches `dalpRolesUndescribed` `is` `true`. Apply it to every intent type, intent origin and domain that your role policies apply to, and give it your strictest workflow for role changes.
2. Give it a higher rank than every policy that a role change can also match.
3. Keep it in the domain of your role policies or in a parent domain, because of the `CoerceDescendants` rule above.

A request with `dalpRolesUndescribed` set then gets that workflow, never a looser one that matched only the names that fit. A role change through a function DALP does not know sets neither property, so this policy does not catch it.

Role changes reach Ripple as transaction orders and as manifests, so apply each role policy to both intent types. To match a single role, use `contains`, because `is` on `dalpRoles` matches only the complete list. Before you use `contains`, check that no longer role name includes the same text.

One request can change more than one role, and Ripple still runs only one policy. Rank your role policies by how strict their workflows are, with the strictest highest, and above any other policy that a role change can also match, such as a policy on `dalpKind`. A grant of `auditor` and `admin` together then gets the stricter `admin` workflow. Never give two role policies with different workflows the same rank, because at equal rank Ripple runs the older policy.

## Keep the paymaster and bundler wallets approval-free [#keep-the-paymaster-and-bundler-wallets-approval-free]

Two DALP wallets sign for every user, not for one investor. The paymaster wallet signs a sponsorship ticket, with `dalpKind` `paymaster.sponsorship`, for each operation that DALP pays gas for. The wallet that submits user operations to the chain sends `aa.bundle`. A policy that holds either intent for approval stops every sponsored operation on that network, not one.

Give these two intents a policy whose workflow needs no approver, and rank it ahead of every approval policy that they also match. When a policy holds a sponsorship ticket, DALP refuses the operation with "The paymaster wallet's Ripple policy holds sponsorship ticket signing", and names the Ripple intent. For each hold on either wallet, DALP logs one warning and adds one to the `dalp_execution_infrastructure_vault_holds_total` counter.

## Operation names that changed from 3.1 to 3.2 [#operation-names-that-changed-from-31-to-32]

A policy whose condition names a 3.1 value stops matching after the upgrade. Its intents then go to the next policy that matches, or cannot run when no policy matches. Until every deployment you run is on 3.2, match both values with an OR condition, so that an intent from either version finds its policy.

DALP 3.1 sent `contract.` and the contract function name when a workflow wrote to a contract directly, for example during organisation setup, invitations, token creation and system migration. Writes that came through the API sent the operation name of their route, and many of those names changed too. 3.2 sends an operation name for both. The tables pair each 3.1 value with its 3.2 name. The values `token.mint`, `token.burn`, `token.pause`, `token.unpause` and `xvp.execute` kept their 3.1 names. For any other value that the tables do not list, run the operation on a 3.2 test deployment and match the value that Ripple shows.

### Direct contract writes [#direct-contract-writes]

| 3.1 value | 3.2 value |
| --- | --- |
| `contract.createSystem` | `system.create-system` |
| `contract.bootstrap` | `system.bootstrap` |
| `contract.grantRole`, `contract.batchGrantRole`, `contract.grantMultipleRoles` on the system access manager | `system.grant-role` |
| `contract.revokeRole`, `contract.batchRevokeRole`, `contract.revokeMultipleRoles` on the system access manager | `system.revoke-role` |
| The same three grant values on a token's access manager | `token.grant-role` |
| `contract.registerTopicScheme`, `contract.updateTopicScheme`, `contract.removeTopicScheme` | `system.topic-create`, `system.topic-update`, `system.topic-delete` |
| `contract.addTrustedIssuer`, `contract.updateIssuerClaimTopics`, `contract.removeTrustedIssuer` | `system.trusted-issuer-create`, `system.trusted-issuer-update`, `system.trusted-issuer-delete` |
| `contract.installScopedModule`, `contract.uninstallModule` on the system compliance module | `system.compliance-module-configure` |
| `contract.registerComplianceModule` | `system.compliance-module-create` |
| `contract.registerSystemAddon` | `system.addon-factory-create` |
| `contract.setAddonImplementation`, `contract.updateImplementation` on an add-on | `system.addon-set-implementation`, `system.addon-factory-update-implementation` |
| `contract.registerIdentity`, `contract.deleteIdentity` | `system.identity-register`, `system.identity-delete` |
| `contract.registerPendingIdentity` | `system.identity-register-pending` |
| `contract.registerClaimAuthorizationContract` | `system.identity-register-claim-authorization` |
| `contract.createIdentityWithManagementKeyAuthorization` | `system.identity-create.create` |
| `contract.addKey` when an identity is created | `system.identity-create.mgmt-key-` and the wallet address in lowercase |
| `contract.addKey` when an organisation key is added | `system.identity-add-key` |
| `contract.addKey` for a claim issuer key | `system.identity-add-management-key` or `system.identity-add-action-key` |
| `contract.upgradeToAndCall`, `contract.migrate` | `system.upgrade-proxy`, `system.migrate` |
| `contract.setImplementation` on the system or its compliance module registry | `system.set-implementation`, `system.compliance-module-set-implementation` |
| `contract.registerTokenFactory` | `system.factory-create` |
| `contract.setTokenFactoryImplementation`, `contract.updateTokenImplementation` | `system.factory-set-implementation`, `system.factory-update-token-implementation` |
| `contract.remapKey` on the token factory registry | `system.factory-remap-key` |
| `contract.registerFeed` | `feeds.register` |
| `contract.batchCreate` for exchange rate feeds | `feeds.exchange-rate.create` |

### Token operations [#token-operations]

| 3.1 value | 3.2 value |
| --- | --- |
| `token.grantRole`, `token.revokeRole` | `token.grant-role`, `token.revoke-role` |
| `token.installComplianceModule`, `token.uninstallComplianceModule` | `token.install-compliance-module`, `token.uninstall-compliance-module` |
| `token.installScopedComplianceModule` | `token.install-scoped-compliance-module` |
| `token.configureComplianceModule`, `token.configureScopedComplianceModule` | `token.configure-compliance-module`, `token.configure-scoped-compliance-module` |
| `token.setModuleScope` | `token.set-module-scope` |
| `token.setMetadata`, `token.removeMetadata` | `token.set-metadata`, `token.remove-metadata` |
| `token.setYieldSchedule` | `token.set-yield-schedule` |
| `token.freezePartialTokens`, `token.unfreezePartialTokens` | `token.freeze-partial`, `token.unfreeze-partial` |
| `token.recoverTokens`, `token.recoverERC20`, `token.forcedRecoverTokens` | `token.recover-tokens`, `token.recover-erc20`, `token.forced-recover` |
| `token.forcedTransfer` from the API | `token.forced-transfer`. A batch of forced transfers keeps `token.forcedTransfer`. |
| `token.transfer-approval.approve`, `token.transfer-approval.revoke` | `token.transfer-approval-approve`, `token.transfer-approval-revoke` |
| `token.convertYield` | `token.convert-yield:` and the batch |
| `token.feature` and the feature name, then `Create`, for example `token.featureAumFeeCreate` | `token.feature-create` |
| `token.feature` and the feature name, then `Attach`, for example `token.featureAumFeeAttach` | `token.feature-attach`. When the feature contract already exists, `token.feature.attach`. |
| `token.featureDetach`, `token.featurePermitDetach` | `token.feature-detach` |
| `token.featureRotateCreate`, `token.featureRotateAttach` | `token.feature-rotate-create`, `token.feature-rotate-attach` |
| `addon.fixedYieldSchedule.create`, `.topUp`, `.withdraw`, `.claim` | `features.fixed-yield.create`, `features.fixed-yield.top-up`, `features.fixed-yield.withdraw`, `features.fixed-yield.claim` |
| `token.create.role`, the role grant that token creation files | `token.grant-role` |
| `claim.issue` and `claim.revoke` from the API | `system.claim-issue` or `token.claim-issue`, and `system.claim-revoke` or `token.claim-revoke` |

The pairs above are the values the API sends when you attach, replace or detach a feature on an existing token. A token that you create with its features, and a feature that a creation flow replaces, are filed under `token.feature.` and the feature ID, then `.create` or `.attach`. A replacement in a creation flow keeps `token.featureRotateCreate` for the create step and sends `token.feature-rotate-attach` for the attach step.

### System, identity and wallet operations [#system-identity-and-wallet-operations]

| 3.1 value | 3.2 value |
| --- | --- |
| `system.factory.create` | `system.factory-create` |
| `system.grant-role-by-participant`, `system.revoke-role-by-participant` | `system.grant-role`, `system.revoke-role` |
| `compliance.provider-webhook-reactivate` | `system.trusted-issuer-add-claim-topic` |
| `compliance.provider-webhook-revoke` | `system.trusted-issuer-remove-claim-topic` |
| `system.identity-create.mgmt-key` | `system.identity-create.mgmt-key-` and the wallet address in lowercase |
| `system.identity-update-country:` and the wallet | `system.identity-update-country` |
| `identity-recovery.identity-create` | `system.identity-create.create` |
| `identity-recovery.recover-identity` | `identity.recover` |
| `invitation.identity-attach.register-pending` | `system.identity-register` |
| `invitation.identity-attach.smart-wallet-mgmt-key` | `system.identity-add-management-key` |
| `invitation.identity-attach.register-claim-auth` | `system.identity-register-claim-authorization` |
| `claim.issue.add-claim` | `identity.claim-add` |
| `smart-wallet.create`, `smart-wallet.create.multisig`, when they named the account creation order | `custody.smart-wallet-create`, `custody.smart-wallet-create.multisig` |
| `smart-wallet.identity.add-key` | `custody.smart-wallet-create.add-key` |
| `smart-wallet.authorise`, `identity-recovery.authorise` | `smart-wallet.create`. 3.1 used this string for the account creation order, so a policy on `smart-wallet.create` that you wrote for 3.1 now matches a different intent. |
| `system.identity-create.register-pending`, `system.identity-create.register-controller` | `system.identity-register-pending.wallet:` and the wallet address in lowercase |
| `system.identity-create.batch-register-pending` | `system.identity-register-pending.batch:` and the wallet addresses in lowercase, joined with hyphens |
| `system.identity-create.claim-auth` | `system.identity-create.claim-auth` when an identity is created, and `system.identity-register-pending.claim-auth` when a pending identity is registered. A policy on the 3.1 value no longer matches the second. |
| `identity-recovery.register-replacements` | `identity.register` for a wallet with no identity, and `identity.recover` for the others |
| No value, for a user operation that a smart account runs | The operation that it runs, for example `token.mint`. A policy on `token.mint` now also matches that operation when a smart account runs it. |
| `smart-wallet.install-module`, `smart-wallet.uninstall-module`, `smart-wallet.set-threshold` | `custody.wallet-mutation` |
| `sponsorship.ticket` | `paymaster.sponsorship` |
| `paymaster.set-signer.` and the paymaster address | `paymaster.set-signer` |
| `refundSplitter.recoverNative` | `system.refund-splitter-recover-native` |
| `xvp.approve.erc20.` or `xvp.approve.settlement.` and the addresses | `xvp.approve` |
| `feeds.feed-submit`, `feeds.issuer-signed-create` | `feeds.submit`, `feeds.issuer-signed.create` |

### Operations that 3.2 no longer sends [#operations-that-32-no-longer-sends]

These 3.1 values have no 3.2 successor. Remove a policy condition that names only one of them.

- `paymaster.set-signer-rollback.` and the paymaster address
- `refundSplitter.recoverErc20`, `refundSplitter.setSponsorship`
- `token.delegateBySig`
- `token-sale.add-payment-currency`, `token-sale.remove-payment-currency`, `token-sale.configure-vesting`, `token-sale.set-purchase-limits`, `token-sale.set-soft-cap`
- `system.identity-delete.paired.` and the wallet, replaced by `system.identity-delete`

## Check your policies before you upgrade [#check-your-policies-before-you-upgrade]

1. Run the operations that your policies cover on a 3.2 test deployment.
2. Compare the `dalpKind` that Ripple shows for each intent with the condition of the policy you expect to run.
3. Check each policy against the property table above, and add the `dalpRolesUndescribed` policy.

## Troubleshooting [#troubleshooting]

| What you see | Cause | Fix |
| --- | --- | --- |
| An intent cannot run. | No policy matches the intent, often because a condition still names a 3.1 `dalpKind`. | Match the 3.2 value, or both values with OR. Then submit the operation again. |
| A role grant gets a looser workflow than you set. | A policy on `dalpKind` or `dalpRoles` has a higher rank than the `dalpRolesUndescribed` policy. | Rank the `dalpRolesUndescribed` policy ahead of every policy that a role change can match. |
| A sponsored operation fails with "The paymaster wallet's Ripple policy holds sponsorship ticket signing". | A policy with an approval workflow matches `paymaster.sponsorship` intents. | Rank a policy without approvers for that intent ahead of it, then submit the operation again. |
| A request stays in signing, and its error message says that the account has an amount in quarantine. | Ripple quarantines funds that it receives from an outside address, a minted token included, and an order waits until its funds are released. The message names each quarantined token or gas amount. | Release the quarantine in the Ripple console. DALP never releases a quarantine. |
| An intent stays open in Ripple after DALP stops waiting, and the Console shows the request as "May still go through". | Ripple has no call that withdraws a held intent, so DALP does not cancel one. DALP stops waiting after its poll limit and reports the intent as open. | Let the intent run or stop it in Ripple. Do not submit the operation again while the intent is open. |
| A request stays in signing, and its error message says that Ripple has not prepared or broadcast an order. | Ripple holds the order. After ten minutes without a broadcast, DALP names the order on the request, says how long ago it filed the order, and keeps waiting. | Find the order by its id in Ripple, and let it run or stop it there. |

## Ripple sources [#ripple-sources]

- [Policy reference](https://docs.ripple.com/products/custody/governance/policies/reference): the conditions a policy can use, and how Ripple ranks and picks a policy.


# Index rebuild after an upgrade

Source: https://docs.settlemint.com/docs/deployment/runbooks/index-rebuild-after-upgrade
An upgrade that changes the indexer's data version rebuilds indexed chain data for hours: read its progress, check its provider and spot a stalled rebuild.

After an upgrade that changes the indexer's data version, the indexer rebuilds its data while the current data keeps serving reads. Act only when the build stops advancing, the provider throttles it, or `IndexerBuildFailed` fires.

The data version is the format the indexer records chain data in. The first time such a release starts, the indexer builds a new dataset for Ledger Data. It indexes each EVM network again from the network's configured start block, or else from the block where DALP's Directory was deployed. With a legacy Directory, it starts at the earlier of the two. The current dataset keeps serving Console, API and report reads while the new one builds, and those reads stay current while the serving lane can take the release's writes, as Check 3 explains. When the new dataset has caught up, the platform switches reads to it in one step. Its duration grows with the number of blocks from the start block to the head and with the provider's `eth_getLogs` throughput. A rebuild over a long chain history can take hours, so measure one on a non-production copy before the change window.

Rolling back to an older release after the switch is not self-service, as [Actions](#actions) explains. [Upgrades and migrations](https://docs.settlemint.com/docs/deployment/upgrades-migrations) explains where the rebuild sits in a change window.

## Symptoms [#symptoms]

- The indexer logs, category `didx.db.deployment`, hold `Dataset created; it indexes from the chain's start` with `status` `building` and the new `version`.
- The network's card on "Platform admin", "Platform networks" reads `Rebuilding indexed data · <percent>% · block <current> of <target> · started <time>. Reads use the current data until the rebuild catches up.` A progress bar sits under the line. Before the build records its first block on that network, the line reads `Rebuilding indexed data · started <time>. Reads use the current data until the rebuild catches up.`
- The Console's [Submissions tray](https://docs.settlemint.com/docs/console/essentials/submissions) shows a confirmed write as "Recorded on-chain", with the line "Recorded on-chain. The platform rebuilds its data, and your lists catch up on their own. Nothing is needed from you."
- Creating or retrying an organisation deployment, creating an invitation, or accepting one, with `Prefer: dalp-fail-on-indexer-reindexing` is answered `503` with `DALP-12331` and the message "The indexer is still catching up on this chain". The response carries `Retry-After` and `data.retryAfterSeconds`. Without that preference, these requests are not refused for the rebuild. The refusal also needs the `indexerReadinessGate` feature, which is on by default.

## How the rebuild runs [#how-the-rebuild-runs]

Each lane is a set of indexer processes that writes one dataset:

- **The build lane** indexes each EVM network into the new dataset. With the default chart values, a separate rebuild Deployment of two pods runs it: `dapi.indexerDeployment.rebuild.enabled` is `true` and `dapi.indexerDeployment.rebuild.replicas` is `2`. With the rebuild Deployment turned off, every indexer pod runs both lanes.
- **The serving lane** keeps the current dataset following the chain head, so reads stay current during the build.

The platform switches reads to the new dataset when two conditions hold on every network that is not paused. The build has reached the finalised block it last recorded for the network, and it has caught up with the serving dataset. A network whose provider had no history at the start block counts as ready, so promotion does not wait for it. When the build still trails and every trailing network committed new blocks in the last 60 seconds, the platform holds the serving dataset still for at most 30 seconds so the build can catch up, and logs `Serving dataset frozen for the handover; the build catches up before promotion`. The switch logs `Dataset promoted; reads now serve from the rebuild`. The platform drops the old dataset at its first check after one hour has passed since the switch.

## Checks [#checks]

1. Read the progress. On "Platform networks", the card's `block <current> of <target>` compares the build's position with the serving dataset's position on that network. The percentage is `<current>` divided by `<target>`. The build starts at the network's start block, so the first reading is that block's share of `<target>`, not zero. `<target>` moves as the serving dataset follows the chain, unless the serving lane is refused, as in step 3. Read both numbers twice, five minutes apart. If the gap between them shrinks, the build is catching up, and the gap divided by how fast it shrinks gives the time left.

2. Confirm that reads are still current. Open "Organisation settings", "Infrastructure", "Platform status", then the "Indexing" detail. Its snapshot log describes the serving dataset that reads use, not the build. "Status" and "Lag" show by default. "Stall" is hidden by default, so turn that column on. A low "Lag" means the serving lane follows the chain while the build runs.

3. If "Lag" and "Stall" grow on that page during the build, search the indexer logs, category `host.didx.serving-lane`, for `Serving lane refused: the serving dataset cannot take this version's writes, so it stays where it is until it can or until promotion`. The release changed the data layout in a way the old dataset cannot take. Reads then stay where they were when the earlier release stopped, until the switch.

4. If the percentage stops rising, check that the build lane runs: `kubectl get pods -l app.kubernetes.io/component=indexer-rebuild`. With the rebuild Deployment on, only these pods write the build, so the build does not advance while they are down. `IndexerBuildFailed` does not fire while the build is still behind the finalised block, so a flat `<current>` with no alert can still be a stall. Then check the alerts and logs in [When to worry](#when-to-worry).

5. Check the provider of the slow network. The build reads the whole indexed range of the chain through the indexer's RPC endpoint pool, so the provider sets its pace. A rising `dalp_rpc_admission_throttles_total` for that network means the provider answers `429` and the pool retries on the same endpoint. [RPC upstreams failing over](https://docs.settlemint.com/docs/deployment/runbooks/rpc-upstream-failover) covers the pool's health.

## Actions [#actions]

- **The rebuild advances.** Let it drain. Adding indexer replicas does not make one network faster: one process at a time holds a network's lane, so extra replicas add failover and leave throughput unchanged.
- **The provider limits the pace.** The build does not use the network's "RPC call limits" from the Console. It reads spans of at most `global.dalpApp.config.indexer.batch.maxBlocks` blocks in the chart values, which the pod's `DIDX_BATCH_MAX_BLOCKS` variable can move, and 2,000 by default. It halves the span after repeated fetch failures and doubles it again, up to that maximum, after three clean commits. Raise the maximum only as far as the provider's `eth_getLogs` range limit allows, or raise the plan at the provider.
- **The build stops at an old block with a missing-state or pruned-history error.** The provider does not keep that history. Point the network's pool at an archive-capable endpoint, as [What RPC provider does a rebuild need?](https://docs.settlemint.com/docs/deployment/runbooks/ledger-indexing-stalled#what-rpc-provider-does-a-rebuild-need) describes. The build resumes from its last committed position. Fix the endpoint before the switch, because a network whose provider has no history at the start block does not hold back promotion.
- **Do not roll back or upgrade again during a rebuild unless you accept a fresh start.** A release with a different indexer data version discards a build that is not its own and logs "Retiring dataset" with reason `build for another version`. The next release with the new data version starts its build again from the beginning.
- **Rolling back after the switch.** An older release than the one serving does not bind the data. It logs a line that starts with "Runtime is behind the serving deployment", and its readiness waits for an operator. Escalate instead of forcing it. A database restore from the backup taken before the upgrade, as [Backup and disaster recovery](https://docs.settlemint.com/docs/deployment/backup-recovery) describes, is the way back to the older release's data.

## When to worry [#when-to-worry]

| Signal | What it means |
| --- | --- |
| `IndexerBuildFailed` fires, and `dalp_indexer_build_failures_total` rose with `phase` `validate` | The build reached the finalised block on every network but still trails the serving dataset on one. That network's build has not committed for 60 seconds, or its block at the serving position has a different hash. Serving data is unchanged. Compare the network cards to find the network whose `<current>` stays flat. |
| `IndexerBuildFailed` fires, and the counter rose with `phase` `promote` or `cleanup`, with `Dataset promotion check failed; the next check retries` or `Drained dataset cleanup failed; the next check retries` in the logs | The switch or the removal of the old dataset failed. The platform retries on the next check. Escalate if it keeps firing. |
| `Indexing stalled: no new block for <age>.` on the network card | The serving dataset has not advanced for 15 minutes while the chain has. This line replaces the rebuild line on the card. It is a stall, and rebuild progress does not explain it: use [Ledger indexing stalled](https://docs.settlemint.com/docs/deployment/runbooks/ledger-indexing-stalled). |
| `EVM span chain parked; its siblings continue` in the indexer logs | One network stopped on a failure. Use [Indexer chain parked](https://docs.settlemint.com/docs/deployment/runbooks/indexer-chain-parked). |
| `IndexerSpanRetryLoop` fires, or `EVM span attempt failed; retrying from the committed watermark` repeats with a `driver_sqlstate` for one network and `operation` | One lane fails the same database statement on every attempt, so its position does not move. On the rebuild pods that holds the build back with no `IndexerBuildFailed`. The log line's `error_detail` names the `SQLSTATE` and the server message. A release that adds a column without a new data version adds it to the build when the rebuild pods start, so a missing column or table here means the release did not finish rolling out to the rebuild pods: check that they run the new release. |
| `IndexerWritingLaneRefused` fires, or `Writing lane refused: the dataset cannot take this version's writes, so it stays where it is until it can or until a new build replaces it` in category `host.didx.serving-lane` | The build was created by a release whose data layout this release cannot extend in place, so the rebuild pods do not write it, and it never promotes. The pods plan it again only on the next deployment change or pod restart. Escalate: the build needs a new data version to start over. Only a build is refused: with no build running, the indexer keeps writing the serving dataset and logs `Writing lane kept on a serving dataset whose layout differs from this version's` once instead. A database restored from a backup of a dataset this release created is never refused. |

## Verify recovery [#verify-recovery]

The network card no longer reads "Rebuilding indexed data", the indexer logs `Dataset promoted; reads now serve from the rebuild`, and `IndexerBuildFailed` is quiet.

## Escalate [#escalate]

Escalate to your DALP support contact when `IndexerBuildFailed` keeps firing, when the gap on the card stays the same for longer than your change window allows with the build lane running and no provider errors, or after a rollback past the switch. Include:

- the release you upgraded from and to.
- the network and chain ID, and two readings of the card's `block <current> of <target>` with their times.
- the `phase` values of `dalp_indexer_build_failures_total`, and the log lines in categories `didx.db.deployment`, `didx.dataset` and `host.didx.serving-lane` from the start of the build.
- the RPC provider, and the value of `DIDX_BATCH_MAX_BLOCKS` if you changed it.


# Runbooks

Source: https://docs.settlemint.com/docs/deployment/runbooks
Diagnose and fix readiness, indexing, funding, RPC, signing and webhook delivery problems on a DALP instance, starting from the symptom you see.

Find what you are seeing in [Match the symptom to a runbook](#match-the-symptom-to-a-runbook) and open that runbook. Each runbook opens from a symptom you can observe directly: `kubectl` output, a Console screen, an alert or a log line. Its checks name the signal to read and, where the platform defines one, the value that means healthy, and it ends with the fix.

## Match the symptom to a runbook [#match-the-symptom-to-a-runbook]

| What you observe | Open | Why this one |
| --- | --- | --- |
| `kubectl get pods` shows a pod `Running` but not `1/1 Ready`, or Console and API calls fail with connection errors or 503s while every pod shows `Running`. | [Platform API not ready](https://docs.settlemint.com/docs/deployment/runbooks/platform-api-not-ready) | The pod is out of rotation. Check the readiness of the other replicas. |
| Console, the API, or reports stop reflecting new on-chain activity while the pods themselves report `Ready`. | [Ledger indexing stalled](https://docs.settlemint.com/docs/deployment/runbooks/ledger-indexing-stalled) | The pod is healthy. Only the chain data behind it has stopped advancing. |
| A registered webhook endpoint stops receiving events, alone or while sibling endpoints on the same instance keep working, or its status in Console flips to "Auto-disabled" on its own. | [Webhook deliveries failing](https://docs.settlemint.com/docs/deployment/runbooks/webhook-deliveries-failing) | Start with that endpoint's delivery history and breaker state. |
| Every registered webhook endpoint on the instance goes quiet at the same time. | [Ledger indexing stalled](https://docs.settlemint.com/docs/deployment/runbooks/ledger-indexing-stalled) | The indexer writes each webhook event in the same transaction that advances its indexed state, so a stalled indexer can stop new chain events across endpoints. Also inspect the shared delivery runner. |
| Work that DALP filed through a Utila configuration stays in `AWAITING_SIGNATURE` in the Utila console, or the co-signer does not show as running. | [Utila signing agent](https://docs.settlemint.com/docs/deployment/runbooks/utila-signing-agent) | The customer-run agent signs only after DALP answers. Read its answers first. |
| The Console's Submissions tray shows work as "Waiting for funds", or the API answers `TRANSACTION_QUEUE_FUNDING_REQUIRED`. | [Transactions waiting for funding](https://docs.settlemint.com/docs/deployment/runbooks/transactions-waiting-for-funding) | The paying wallet could not cover gas. Work is paused while the Submissions tray shows "Waiting for funds", and has failed when a `Prefer: wait` call answers the code. |
| Logs show `RPC upstream failed over` or `All RPC upstreams exhausted`, `dalp_chain_evm_rpc_upstreams_exhausted_total` rises, or `RpcHealthSelectionDisabled` fires. | [RPC upstreams failing over](https://docs.settlemint.com/docs/deployment/runbooks/rpc-upstream-failover) | One or more of the network's RPC endpoints fail. The log lines and the alert come from the indexer. For queued transactions, read the `dalp_chain_evm_rpc_*` counters. |
| The indexer logs `EVM span chain parked; its siblings continue` for one chain, and that chain stays frozen while the indexer pod is `Ready` and its other chains advance. | [Indexer chain parked](https://docs.settlemint.com/docs/deployment/runbooks/indexer-chain-parked) | The indexer stopped that chain on a failure a retry cannot fix. A restart clears the park, and the failure decides whether that is enough. |
| After an upgrade, the network card on "Platform networks" reads "Rebuilding indexed data" and the percentage rises slowly. | [Index rebuild after an upgrade](https://docs.settlemint.com/docs/deployment/runbooks/index-rebuild-after-upgrade) | The release rebuilds indexed data while the current data keeps serving. Read its pace before you intervene. |
| `IndexerSpanRetryLoop` or `IndexerWritingLaneRefused` fires, or the rebuild percentage on "Platform networks" stops rising after an upgrade. | [Index rebuild after an upgrade](https://docs.settlemint.com/docs/deployment/runbooks/index-rebuild-after-upgrade) | The build is not being written: a database statement fails on every attempt, or this release cannot write the build's data layout. The runbook names the log line for each. |

An indexer pod answers `/healthz` and `/readyz` with `200` while its process runs, so its pod status does not show a stalled chain. A chain the indexer cannot retry is parked: the indexer logs `EVM span chain parked; its siblings continue` in category `host.didx.evm-span`, with `chain_id`, `failure_tag` and `error_detail`, and keeps indexing its other chains. The pod stays `Ready` and does not restart. Read that log line, not pod restarts.

## When transactions stop going out [#when-transactions-stop-going-out]

Check these four causes in order. Fix the first one whose signal you find, because a later cause can be an effect of an earlier one.

1. **The paying wallet is short of gas.** The Submissions tray shows "Waiting for funds", the Transaction funding page shows a notice such as `<wallet> needs <amount>`, or a transaction request failed with `DALP-9087` on its status or `DALP-14062` from the API. Open [Transactions waiting for funding](https://docs.settlemint.com/docs/deployment/runbooks/transactions-waiting-for-funding).
2. **The network's RPC endpoints fail.** `dalp_chain_evm_rpc_attempts_total` with `outcome` `failure` rises for the chain, or `dalp_chain_evm_rpc_upstreams_exhausted_total` rises on a network with more than one endpoint. These come from the client that sends queued transactions, which uses only the endpoints in the deployment values. `All RPC upstreams exhausted` in the logs and an "Unhealthy" or "Excluded" badge on "Platform networks" describe the indexer's pool. Open [RPC upstreams failing over](https://docs.settlemint.com/docs/deployment/runbooks/rpc-upstream-failover).
3. **A transaction stays open.** A row on the "Transactions" detail of Platform status stays open without settling, and the first two causes are ruled out. Use "Set next nonce" when a nonce gap holds it, or "Force fail" it when it can no longer complete, as [Recover a stuck transaction](https://docs.settlemint.com/docs/console/organisation-settings/platform-status-transactions#recover-a-stuck-transaction) describes. Before you force fail a transaction that has a transaction hash, check on a block explorer that no transaction from that sender with that nonce was mined or is still pending. A force-failed transaction that lands later, followed by a resent write, runs the operation twice.
4. **The transactions settle but screens do not show them.** That is indexing, not sending. Open [Ledger indexing stalled](https://docs.settlemint.com/docs/deployment/runbooks/ledger-indexing-stalled), or [Index rebuild after an upgrade](https://docs.settlemint.com/docs/deployment/runbooks/index-rebuild-after-upgrade) when a release started a rebuild.

## How the roles depend on each other [#how-the-roles-depend-on-each-other]

A DALP instance runs four backend roles, and these runbooks cover three of them: one serves Console and API traffic, one indexes chains into Ledger Data, and the runner executes durable workflows, including webhook delivery. The fourth, the scheduler, runs background jobs. The indexer writes each webhook event as part of the same transaction that advances its indexed state, and the runner reads that queue on its own cadence to deliver it, so a stalled indexer starves webhook deliveries too. Each of the three answers `/readyz`, but only the Platform API reports boot phases and dependency verdicts there. The runner and the indexer report only whether the process is up or draining. All three write into one PostgreSQL database, so a symptom on one surface can trace back to another. The scheduler's `/readyz` answers `503` when the bank FIX simulator cannot listen and, in `external` mode, lists the bank FIX sessions it dials, as [Platform API not ready](https://docs.settlemint.com/docs/deployment/runbooks/platform-api-not-ready) describes.

[Figure] Three roles run one instance, and they share one database. Three cards inside one instance outline show the backend roles. The indexer reads chains into Ledger Data and publishes a servable schema once it is caught up. The Platform API serves Console and API traffic, and its readiness waits on that schema being bound. The runner, the Workflow Engine role, owns durable execution and sends webhook deliveries. An accent arrow carries the schema bind from the indexer into the Platform API's readiness, which is why a readiness symptom can turn out to be an indexing fault. A second accent arrow runs from the indexer to the runner, carrying the webhook queue the indexer writes as part of the same transaction that advances its indexed state, which is why a stalled indexer starves webhook deliveries too. Below the instance outline, a connector leads to one PostgreSQL database that holds durable execution state, chain positions, and webhook delivery history for every role, which is why a database problem can surface as more than one symptom at once. Labels: One DALP instance; Indexer; Indexing; Reads chains into; Ledger Data; schema bind; Platform API; Serving; Serves Console; and the API; Readiness waits on; the schema bind; Workflow Engine; Runner; Durable execution; Sends webhook; deliveries; One PostgreSQL database; Shared state; Durable execution state, chain positions, and delivery history for every role.

The indexer feeds the Platform API's readiness and the runner's webhook queue, and all three roles write to one PostgreSQL database.

## Open a runbook [#open-a-runbook]


  - [Platform API not ready](https://docs.settlemint.com/docs/deployment/runbooks/platform-api-not-ready): A pod stays out of Ready: tell a slow boot from a hang and read its status and logs.
  - [Ledger indexing stalled](https://docs.settlemint.com/docs/deployment/runbooks/ledger-indexing-stalled): Indexed data stops advancing while pods are Ready: read the indexer's progress and logs.
  - [Webhook deliveries failing](https://docs.settlemint.com/docs/deployment/runbooks/webhook-deliveries-failing): A webhook endpoint goes quiet: read the retry schedule, circuit breaker and recovery.
  - [Utila signing agent](https://docs.settlemint.com/docs/deployment/runbooks/utila-signing-agent): Utila work stops being signed: read the agent's answers, then enrol, rotate or recover it.
  - [Transactions waiting for funding](https://docs.settlemint.com/docs/deployment/runbooks/transactions-waiting-for-funding): Work pauses because the paying wallet cannot cover gas: fund it inside the window.
  - [RPC upstreams failing over](https://docs.settlemint.com/docs/deployment/runbooks/rpc-upstream-failover): RPC endpoints fail over or run out: find the failing one and fix it where it is read.
  - [Indexer chain parked](https://docs.settlemint.com/docs/deployment/runbooks/indexer-chain-parked): One chain stops on a failure a retry cannot fix: tell a restart from a rebuild.
  - [Index rebuild after an upgrade](https://docs.settlemint.com/docs/deployment/runbooks/index-rebuild-after-upgrade): A release rebuilds indexed data for hours: read its progress and know when it is a fault.


## When nothing here matches [#when-nothing-here-matches]

If the pod is `Ready`, Ledger Data is current, and webhook deliveries are flowing, but you are still looking at a failure none of these runbooks name, capture the evidence before you touch anything. Take the pod's logs and `kubectl describe pod` output, the delivery history, or whatever error your own integration returned. A restart or a resend can destroy the failure reason you need. Escalate to your DALP support contact with what you captured.


# Indexer chain parked

Source: https://docs.settlemint.com/docs/deployment/runbooks/indexer-chain-parked
The indexer stops one chain after a failed chain reorganisation repair: recognise a parked chain, heal it with a restart, and know when it needs a rebuild.

One chain has stopped advancing while the indexer pod stays `Ready`, because the indexer parked it after a chain reorganisation repair it refused. Read the fork block from the log and compare it with the chain's `rollup_block` and `finality_block`: a restart heals the park when the fork is higher than both, and a rebuild is the only fix when it is not. For a chain that is only behind, or for a pod that restarts, start with [Ledger indexing stalled](https://docs.settlemint.com/docs/deployment/runbooks/ledger-indexing-stalled) instead.

Each indexer loop advances one chain. When a loop hits a failure that a retry cannot fix, the indexer parks that chain and keeps the other chains running. A parked chain stops advancing, so Ledger Data for it freezes at the last indexed block while the network moves on.

A chain reorganisation is a change in the chain's recent blocks. The indexer keeps undo data for every block above the `rollup_block` of the chain's row in `idxr_chain_watermark`. It can rewind to any block above `rollup_block` and above `finality_block`. It cannot rewind below them.

The park lives in memory only. A restart of the indexer clears it.

## Symptoms [#symptoms]

- A chain stops advancing and the pod stays `Ready`. The probes answer for the process, not for chain state.
- The indexer log holds the line `EVM span chain parked; its siblings continue`.
- The failure the line names has the tag `repair`. The failure text reads `Repair stopped <reason> at retained floor <block>.`

## Checks [#checks]

1. Search the indexer logs for `EVM span chain parked; its siblings continue`. The line carries the chain and the failure that parked it. A park for another failure tag is not this runbook: use [Ledger indexing stalled](https://docs.settlemint.com/docs/deployment/runbooks/ledger-indexing-stalled).

2. Read the failure text. The fork block is the `position` of the `repair` failure. The retained floor is the number after `at retained floor`. The reason is one of `below-retained-floor`, `at-or-below-finality`, or `beyond-repair-depth`.

3. Read the stored reach for the chain from the database:

   ```sql
   SELECT chain_id, committed_block, rollup_block, finality_block
   FROM idxr_chain_watermark
   WHERE chain_id = <chain id>;
   ```

   Run it in the indexer schema of the instance.

4. Compare the fork block with `rollup_block` and `finality_block`:
   - The fork block is above both. Undo data exists for it, so the indexer can repair it.
   - The fork block is below `rollup_block`, or at or below `finality_block`. The indexer has no undo data to rewind to.

## Actions [#actions]

- If the fork block is above `rollup_block` and above `finality_block`, restart the indexer deployment. The first attempt after the restart verifies the chain before it writes to `idxr_chain_watermark`, finds the common ancestor above the rollup floor, rewinds to it, and continues. Reach comes from the stored `rollup_block` and `finality_block`, so a chain that was down for more than 64 blocks still repairs.
- If the fork block is below `rollup_block`, or at or below `finality_block`, a restart parks the chain again. The data needed to rewind is gone. Rebuild through a reindex. A platform administrator starts one with `POST /api/v2/admin/operator/blockchain-monitoring/reindexes`, naming the chain's `chainId`. A reindex rebuilds the indexed data of every network at once, and only one runs at a time. It indexes again from each network's start block into a new dataset while the current one keeps serving, so reads for the parked chain stay frozen at its last indexed block until the new dataset takes over. [Upgrades and migrations](https://docs.settlemint.com/docs/deployment/upgrades-migrations) explains how a rebuild runs, and the Indexing detail page on the Console's Platform status screen shows the chain as Reindexing until it drains.

## Verify recovery [#verify-recovery]

After a restart, `committed_block` for the chain advances and the indexer logs no new park line for it. After a rebuild, the chain leaves "Reindexing" on the Indexing detail page.

## Escalate [#escalate]

If the chain parks again after a restart with a fork block higher than both values, escalate to your DALP support contact as a platform defect. Include the chain id, the park line, the failure text, and the row from `idxr_chain_watermark`.


# Ledger indexing stalled

Source: https://docs.settlemint.com/docs/deployment/runbooks/ledger-indexing-stalled
The Ledger Data stops advancing on a chain: how to tell catch-up from a stalled chain, and which of three signatures decides the fix.

Console, the API or reports have stopped reflecting new on-chain activity on one or more chains. Read the chain's indexed position: a position that still advances is a backlog, a position that stopped moving means an indexer pod failed on that chain's ingest, and an absent position means the chain never started. This page assumes the indexer pod is running and passing its probes. For a pod that Kubernetes holds out of `Ready`, start with [Platform API not ready](https://docs.settlemint.com/docs/deployment/runbooks/platform-api-not-ready) instead. It covers the readiness legs, and its indexer leg hands back here.

Ledger Data is the platform's own record of the chains a
DALP instance follows. It reads each block once, decodes the events into business
records, and Console, the API and reports answer from that record rather than from the live network. When indexing stops
advancing on a chain, those surfaces freeze at the last indexed block while the network moves on. The checks separate
the three signatures, cheapest first.

## Symptoms [#symptoms]

- Console screens, API responses, or reports stop reflecting new on-chain activity while the underlying network keeps producing blocks.
- The Console's **Platform status** screen shows a chain out of sync in its Indexing section, a growing worst sync-lag, or a degraded data-freshness panel.
- The gap between the chain's head and the indexed position grows instead of shrinking.
- The indexer pod may still report `Ready`, and that is expected: its probes answer for the process, not for chain state. A chain that lags, a chain that keeps retrying a failed read and a chain that has stopped all leave the pod green, and the indexer keeps running its other chains (Check 2). A green pod with a frozen position is the normal shape of a stall, so read the chain's log lines rather than the pod status.

## Checks [#checks]

1. Confirm the chain is frozen, not catching up. The signal is the indexed position over time: the Console's **Platform status** screen shows chains in sync and the worst sync-lag in blocks, and the indexer exports the same lag for each network as the `dalp_didx_watermark_lag_blocks` metric. Healthy catch-up means the indexed position advances and the lag shrinks. A constant lag can mean ingestion matches block production but is not catching up.

   The platform's own monitor marks a chain's indexing degraded once it is 10 or more blocks behind or has gone 5 minutes without progress, and critical past 100 blocks or 15 minutes.

   Two shapes are not stalls. A rebuild after a platform upgrade reports as reindexing rather than degraded. That is the indexer working, so let it drain. A chain that is fully caught up on a quiet network is idle, not stalled: the stall clock only runs while the chain is behind. Chains that mint blocks only when a transaction is submitted skip the no-progress rule entirely.

2. On a chain whose position stopped moving, read the logs of every indexer pod for that chain's `chain_id` in the `host.didx.evm-span` category. A failed attempt and a stop log different lines.

   `EVM span attempt failed; retrying from the committed watermark` is a warning. The attempt failed, for example on an RPC error, and the chain tries again from its last committed position after a short wait. A cause that clears lets the next attempt through, and a cause still present repeats the same warning.

   `EVM span chain parked; its siblings continue` is an error. The chain stopped on a failure it does not retry, and the indexer keeps indexing its other chains. A stop the platform records, such as a handler failure, a reorganisation deeper than the repair depth or a replaced chain, also logs `EVM span attempt stopped`. The lines carry `failure_tag` and `error_detail`, which name the failure. A parked chain stays stopped until the indexer restarts, and the restart resumes it from the last committed watermark. For a park whose failure tag is `repair`, use [Indexer chain parked](https://docs.settlemint.com/docs/deployment/runbooks/indexer-chain-parked).

3. For a chain with no indexed position at all from the moment the instance started, and no failed-attempt or parked line for it on any replica, check that the chain is in the instance's [`networks` entry](https://docs.settlemint.com/docs/deployment/networks) and that an indexer pod owns it, as the next check describes.

4. For positions that froze or flapped around a redeploy, a replica restart, or a replica-count change, look at the ownership handoff. Ownership of each network is a lease with an expiry and an epoch. A process can take the lease only after the current holder's lease has expired, and each takeover raises the epoch, so a write from an owner whose lease lapsed is rejected as a conflict rather than silently accepted. An owner that finds its lease lapsed or taken logs `Chain lease renewal found the lease lapsed or taken; the lane acquires it again on its next span attempt` in the same category. A healthy handoff therefore shows the departing owner's writes failing briefly while the new owner continues from the stored cursor. Owners keep no state of their own, so nothing is lost in the transfer.

   Each pod carries only the chains it owns, so a redeploy or a replica-count change moves chains between pods and a chain can legitimately have no owner on the pod you happened to read. Check every replica before treating a frozen chain as one nobody is working on.

   A process outside the deployment that uses the same database, for example an operator's ad hoc instance, competes for the same leases. Check for one, because a chain it holds is not indexed by the managed deployment.

## Actions [#actions]

- If the position is behind but advancing, it is a backlog: monitor it. Divide the lag in blocks (`dalp_didx_watermark_lag_blocks`) by the observed rate at which that lag decreases to size the window it should close in. Revisit your RPC provider limits or the chain's scope if it is not closing within that window. Do not add indexer replicas to speed one chain up: each network's live ingest is a fenced singleton owned by one process, so extra replicas spread chains across pods and buy failover, never per-chain throughput.
- If the chain's position stopped moving, read its failed-attempt or parked line: the failure it names decides the fix. A failure the database refused, such as a missing table or column, a constraint violation or a revoked permission, is fixed in the database. The refused transaction rolled back whole, so nothing already indexed is lost and the checkpoint did not move. A failure naming the chain's configuration is fixed in the instance's [`networks` entry](https://docs.settlemint.com/docs/deployment/networks) and needs a rollout. A chain that parked resumes when the indexer restarts after the fix.
- If an RPC provider is unavailable or rate-limiting, the chain's attempts fail on it and it retries from the last committed watermark until the provider recovers. Check the provider's status and your configured endpoint first: it is quicker to rule out than duplicate ownership. The chain needs nothing from you while you investigate.
- If a rebuild after an upgrade stops at an old block and the indexer logs show a missing-state or pruned-history error from the provider, the provider cannot serve that block. Point the chain's RPC pool at an archive-capable endpoint that also keeps logs and block headers from the chain's start block, as [What RPC provider does a rebuild need?](#what-rpc-provider-does-a-rebuild-need) describes. The chain picks the rebuild up again on its next try, which comes every 5 minutes.
- If the failure is a handler failure, escalate to your DALP support contact as a platform defect with the held block, the event name, and the parked line's text. Restarting the indexer before the fix only parks the chain again. Nothing already indexed is lost while the chain is stopped: once the release carrying the fix deploys, the restart resumes the chain from the held checkpoint. A release whose fix changes what earlier data should have looked like declares its own rebuild, which reports as reindexing while it drains.
- If the stop line names `failure_tag=chain-generation`, the database holds data from a chain that no longer exists, for example a development chain that restarted without its state. The indexer stops that chain and refuses its reads, so no screen shows the old data as current. Start a reindex: a platform administrator sends `POST /api/v2/admin/operator/blockchain-monitoring/reindexes` with the chain's `chainId`. The rebuild indexes the live chain and replaces the old data when it is complete. A reindex rebuilds every network at once, and on a long history it runs for hours.
- If a process outside the managed deployment holds chain leases, stop that process.

## Verify recovery [#verify-recovery]

The chain's indexed position advances, the Platform status screen shows the chain in sync, and `dalp_didx_watermark_lag_blocks` falls for the chain.

## Escalate [#escalate]

Escalate to your DALP support contact with the chain id, the failed-attempt or parked line, the last position that advanced, and which of the three signatures you observed.

## Frequently asked questions [#frequently-asked-questions]

### What happens to a chain removed from the networks configuration and added back?

Removing the entry stops that chain's ingest on the next rollout. It does not touch anything already indexed, because the [`networks` configuration](https://docs.settlemint.com/docs/deployment/networks) decides which networks run, not what data exists. Adding the entry back starts a new singleton on the next rollout. It takes the chain's lease and resumes from the stored watermark, as any ownership handoff does. The chain's span loop indexes forward from that watermark, so blocks produced while the chain had no owner are indexed once it resumes, provided your RPC provider still serves them.

### How fast does a chain recover once the cause is fixed?

It depends on the signature. A lagging chain recovers at the pace RPC availability and ingest throughput allow, and it needs no restart. DALP states no recovery time for it, so set your own alert and escalation bound from the thresholds in Check 1. A chain that keeps retrying recovers on the first attempt after the cause clears, so a transient RPC outage needs nothing from you. A parked chain recovers when the indexer restarts after the fix, and the restart resumes it from the last committed watermark. A cause still present parks it again.

Contract discoveries are written in bounded groups to reduce database round trips. Discoveries that depend on an earlier parent are written in order, within the same transaction as the indexed checkpoint. Grouping needs no operator setting. Use the advancing checkpoint and falling lag to judge recovery.

### Why does Platform status show degraded while the pod is still Ready?

The two surfaces answer different questions. Platform status reads the chain's lag against the thresholds in Check 1, so it is the earlier warning. The pod's own probes answer for the process, not for chain state: an indexer that is behind keeps answering them and stays `Ready`. Degraded on the screen with a still-Ready pod therefore means the chain has crossed Platform status's window while its ingest is still running. A chain that has stopped leaves the pod `Ready` too, so the chain's own log lines (Check 2) tell a stop from a lag.

### What RPC provider does a rebuild need?

An archive-capable one, for as long as the rebuild runs. A release that changes how earlier data is recorded declares a rebuild, and the platform then indexes each network again from its start block into a new dataset while the current one keeps serving. Live indexing reads each block while it is recent, so a full node that keeps only recent state is enough for it as long as the chain's lag stays inside the node's retained window. A chain that stalls long enough to fall outside that window makes the same old-block reads when it catches up, and needs an archive-capable provider to recover. A rebuild reads the same blocks months or years later.

Three kinds of read in a rebuild ask for state at an old block:

- **External-token balances.** The platform reads an external token's total supply and each tracked wallet's balance at the block the token or the wallet's tracking starts.
- **Finding the deployment block.** When the network entry sets no `indexing.startBlock`, the platform searches for the block where the Directory contract was deployed. It checks for contract code at blocks between block 0 and the head.
- **Event handling.** Every contract read made while handling an event asks for the state at that event's block.

A node without that state answers with a missing-state error, and the chain stops at that block until the provider can serve it. The provider must also return logs and block headers from the start block. Some public endpoints drop old history and answer log queries for old blocks with a pruned-history error, code 4444. Setting `indexing.startBlock` in the [`networks` entry](https://docs.settlemint.com/docs/deployment/networks) removes the deployment-block search but not the other two kinds of read.

### Why does a network show that new-token detection is off?

The network's RPC provider refuses the log query that finds unknown tokens. This can happen at chain start, or later when a provider that answered the query stops answering it. To detect a token it has not seen before, the platform asks the provider for every token transfer into the wallets it manages, without naming a token. Some providers refuse a log query that names no contract address. The platform then fetches logs only for the tokens it already knows, so those tokens keep their balances, but a deposit of a new token into a managed wallet does not become a detected token.

The platform checks the provider again every 10 minutes (`indexer.evmFetchMode.recheckIntervalMs`) and turns detection back on when the provider answers the query. To fix it, point the network's RPC pool at a provider that supports log queries with no contract address. When detection is back on, the platform scans the period it was off again. It does this for every managed wallet whose watch overlaps that period, starting no earlier than the block where the wallet's watch started, so deposits of new tokens made in that period become detected tokens. This also covers a period that was already running when the platform was updated.


# Platform API not ready

Source: https://docs.settlemint.com/docs/deployment/runbooks/platform-api-not-ready
A Platform API, indexer, or Workflow Engine pod runs but is not Ready: how to read the pod's own diagnosis, which waits are normal, and when a restart helps.

Kubernetes routes traffic only to pods that report Ready. A pod that is Running but not Ready is alive and deliberately out of rotation: its Service sends it nothing, so Console screens and API calls fail while `kubectl get pods` looks healthy. This runbook covers that state on the three backend roles of a [DALP instance](https://docs.settlemint.com/docs/platform/dalp-instance): the Platform API, the Ledger Data indexer, and the [Workflow Engine](https://docs.settlemint.com/docs/concepts/settlement/workflow-engine). The Workflow Engine carries multi-step operations across crashes and restarts instead of running them as one call that has to finish in one pass. It also covers the readiness answer of the scheduler, the role that runs background jobs.

Read `RESTARTS` first, then the `/readyz` body of a Platform API pod. A climbing restart count is a boot failure, `draining` is routine, `starting` means the pod is still building, and `degraded` names the verdict holding the pod out. Do not restart a pod for a `postgres` verdict.

`kubectl get pods` does not print those role names. The chart labels each role's Deployment with `app.kubernetes.io/component`, so find the pod a check names by that label:

- Platform API: `kubectl get pods -l 'app.kubernetes.io/component in (api-v1,api-v2)'`
- Indexer: `kubectl get pods -l 'app.kubernetes.io/component in (indexer,indexer-rebuild)'`
- Workflow Engine: `kubectl get pods -l app.kubernetes.io/component=runner`
- Scheduler: `kubectl get pods -l app.kubernetes.io/component=scheduler`

The pod publishes its own diagnosis, but the contract depends on its role. Platform API pods report a boot phase or dependency verdicts on `/readyz`. A Workflow Engine pod reports only `ok`, or `draining` while it shuts down, so for it the restart count and the logs are the signals. An indexer pod answers `/healthz` and `/readyz` with `200` while its process runs, and its chain state is not a readiness verdict. A chain it cannot retry is parked: it logs `EVM span chain parked; its siblings continue` and stops while the pod stays `Ready`. [Ledger indexing stalled](https://docs.settlemint.com/docs/deployment/runbooks/ledger-indexing-stalled) owns that diagnosis.

The scheduler, the fourth backend role, runs background jobs and has no runbook of its own. Its `/readyz` answers like the Workflow Engine's, plus two bank rail cases. A scheduler pod answers `ok`, or `draining` while it shuts down. With the bank rail in `simulator` mode, it answers `503` with `bank-fix-simulator-unavailable` when the bank FIX simulator could not listen on `bankFix.simulator.listenHost` and `listenPort`. The `reason` names the cause. Free the port or correct the setting, then restart the pod, because the platform does not retry the listen. With the bank rail in `external` mode, one scheduler pod dials the bank at a time, and it adds a `bankFix` object: `sessions` counts the active connections it dials, `loggedOn` counts those whose Logon the bank has answered, and `status` is `logged-on` when the two match and `not-logged-on` otherwise. A session that is not logged on keeps the pod Ready, because the scheduler keeps dialling on its own, and a restart fixes neither a bank outage nor a refused logon. Read the scheduler log for `The bank FIX session to the bank ended; reconnecting.` and its reason, as the [bank rail guide](https://docs.settlemint.com/docs/api-reference/guides/bank-rail#set-up-a-connection) describes.

## Symptoms [#symptoms]

- `kubectl get pods` shows a Platform API, indexer, Workflow Engine or scheduler pod Running but not `1/1 Ready`.
- A Helm install or upgrade hangs waiting for the rollout, then fails with a progress deadline error.
- Console or API requests return connection errors or 503 responses while every pod shows Running.

[Figure] Four checks route a not-Ready pod to its one real cause. A decision tree with four questions. First, is the restart count climbing? Yes means a boot failure: read the previous logs, because this is not a readiness problem. No leads to the second question: does /readyz report draining? Yes means an old pod leaving during a rollout, which is routine and needs no action. No leads to the third question: does /readyz report starting? Yes means the pod is still booting, and the reason field names the phase: building the graph gets up to 10 minutes, and a build past that limit exits the pod, so its restart count climbs. No leads to the final question: which verdict is unhealthy? Postgres means fix the database or the pooler in front of it. Durable means the work-scheduling cluster is down or shutting down. If postgres and indexer both read healthy, capture logs and restart the pod. Indexer means follow the indexing runbook, or on a Platform API pod, check the indexer pod it is waiting for. Labels: Is the restart count climbing?; Restart count; Read the previous logs, not readiness; Boot failure; Does /readyz report draining?; Draining; Routine in every rollout, no action; Old pod leaving; Does /readyz report starting?; Boot phase; The reason field names the boot phase; Still booting; Building the graph: up to 10 minutes; Past the limit, the pod exits; and its restart count climbs; so go back to the first check; Which verdict is unhealthy?; Verdict; Fix the database or pooler; Postgres; Isolated probe pool, so app; traffic cannot fake this; Cluster down or stopping; Durable; If postgres and indexer are; healthy, capture logs, restart; Indexing runbook; Indexer; On a Platform API pod:; check the indexer pod; No; No; No; Yes; Yes; Yes.

Four checks sort a Platform API pod into a boot failure, a drain, a start in progress or a degraded verdict, and only one path ends in a manual restart.

## Checks [#checks]

1. Rule out a crash loop first. Signal: the `RESTARTS` column of `kubectl get pods`. Healthy value: a count that stays put. A lightweight boot shell binds the HTTP port at start and answers the startup probe within milliseconds, so the startup probe does not end a slow boot. Instead the Platform API process allows up to 10 minutes to build its application graph, and a build past that limit exits so the failure becomes a visible restart. A climbing count therefore means a boot failure: read `kubectl logs --previous <pod>` for the exit, and stop investigating readiness until the pod stops crash looping.

2. Read the pod's own answer. Signal: the JSON body of `/readyz` on the pod's HTTP port, reached with `kubectl port-forward` or a `curl` from inside the cluster. For a Platform API pod, the body routes you to the remaining checks: `draining` is check 3, `starting` with a `reason` field is check 4, and `degraded` with per-dependency fields is check 5. A Workflow Engine pod returns only `ok` or `draining`. An indexer pod returns `200` while the process runs, so read its logs for a parked chain. A scheduler pod returns `ok`, `draining` or `bank-fix-simulator-unavailable`. In `external` bank rail mode the pod that dials the bank adds a `bankFix` object to its `ok`. Only `bank-fix-simulator-unavailable` needs action on the pod. A `not-logged-on` status sends you to the reconnect warning in the scheduler log.

3. Decide whether the pod is arriving or leaving. Signal: the pod's age next to a `draining` status. A pod that is shutting down flips not-Ready on purpose and skips its dependency checks rather than racing a closing connection pool. Every rolling restart produces this state briefly. Platform API rollouts start one new pod before taking any old one away by default, so the old replicas keep serving while the new one boots. Indexer rollouts replace one pod at a time instead, holding each replacement 90 seconds past Ready before moving to the next. Workflow Engine rollouts stop every old pod before the new ones start, so durable work pauses for the length of the boot. Healthy value: at most one Platform API or indexer replica in transition at a time. Investigate when rollout progress stops or capacity falls below the deployment's needs. Losing every Ready Platform API replica is a complete serving outage, so treat it as an incident and work checks 1, 2 and 4 on the newest pod.

4. Place a starting pod in its boot phase. Signal: the `reason` field beside `status: "starting"`. One phase appears: `application-building`, the graph build, bounded at 10 minutes. If it wedges, the pod exits, which sends you back to check 1.

5. Name the verdict holding a running Platform API pod out. Signal: the `postgres`, `durable` and `indexer` fields in a `degraded` body, with their reasons under `reasons`.

   - `postgres`. The probe dials a dedicated client against a PgBouncer alias reserved for it, an isolated one-connection pool that application traffic never shares, so a saturated app pool cannot make a healthy database look down. A failing verdict names a real problem in Postgres or in the pooler in front of it. The pooler has a shorter rollout deadline than this pod, so a stuck pooler fails first and shows up here instead of looking like a Platform API fault. Check the pooler alongside the database.
   - `durable`. This is the work-scheduling cluster the Workflow Engine runs on. It lives inside the same pod and stores its state in the same Postgres, so there is no separate service to check. An unhealthy verdict, with the reason `runner_shutting_down`, means the cluster is shutting down or has not come up.
   - `indexer`. The pod needs a servable schema, the current version of the indexed database tables, which the indexer publishes. `serving_schema_unbound` means the pod waits, with no deadline, for the indexer to publish one, including on a fresh install. `bump_window_blocked` means a release's data rebuild holds the bind. Read the indexer pod's logs before you treat this pod as stuck.

## Actions [#actions]

- If the restart count is climbing, fix the boot failure from `kubectl logs --previous` first. Readiness is downstream of a boot that completes.
- If the `postgres` verdict is failing, check both the database and the pooler in front of it, and do not restart the pod. A restart only forces the reconnect the pod makes on its own, and the pod rejoins the Service once the database and pooler both answer. The default probe settings pull a pod from rotation after about 45 seconds of sustained readiness failure, which is three failed probes 15 seconds apart, and return it after one successful probe, up to 15 seconds later.
- If indexing has stopped on a chain, search the indexer logs for `EVM span chain parked; its siblings continue` and follow [Ledger indexing stalled](https://docs.settlemint.com/docs/deployment/runbooks/ledger-indexing-stalled). Restarting or resizing the Platform API deployment changes nothing about indexing.
- If a pod reports `serving_schema_unbound` under `reasons.indexer` (check 5) with no schema ever appearing, the wait itself is not the problem: diagnose the indexer pod, whose background schema work every Platform API pod waits on. Producing that schema, on a fresh install too, is work the indexer does inside its own process, not a separate Kubernetes Job, so `kubectl get jobs` finds nothing for it. Read the indexer pods' restart counts and logs. Restarting the waiting pod changes nothing, because the wait resumes on the next boot.
- If the `durable` verdict is failing while `postgres` is healthy, and the pod still sits not-Ready, capture `kubectl describe pod` and its logs first, then delete the pod. A `durable` failure outside a drain you already expect (check 3) means the wedge case applies, and the wedged state does not survive the restart, so the evidence has to come first.

## Verify recovery [#verify-recovery]

`kubectl get pods` shows the pod `1/1 Ready`, its `/readyz` returns `status` `ok`, and Console and API calls succeed.

## Escalate [#escalate]

If the same pod wedges again after a restart, escalate to your DALP support contact with the logs, the describe output and the failing verdict. A wedge that repeats points to a platform defect.

## Frequently asked questions [#frequently-asked-questions]

### Why does Kubernetes leave a not-Ready pod running instead of restarting it?

Readiness and liveness ask different questions. Readiness asks whether traffic should route here now, and its failures are recoverable states that clear on their own, so the right response is to wait out of rotation. Liveness asks whether the process is wedged beyond recovery, where a restart is the only remedy. Combining them would restart every pod whose only problem is a slow dependency, so a short database outage would cold-start the fleet. A Platform API pod's liveness fails only when its heartbeat goes stale for 30 seconds. The indexer uses the same heartbeat on its own liveness port, and the Workflow Engine pod answers liveness from its main loop. On both workers, four failed probes ten seconds apart call the pod wedged. No liveness probe reads a dependency, so a database or pooler outage does not by itself trip one.

### Can I point the startup probe at the readiness endpoint to enforce the boot budget?

No. The indexer pod's `/readyz` is static, so it cannot enforce a boot budget. A Platform API pod already enforces its own 10-minute graph build, which is why the shipped startup probe confirms the port is up instead of using dependency readiness.

### Why did my Helm upgrade fail on a deadline while every pod showed Running?

The rollout counts Ready pods. The chart marks a rollout failed after 25 minutes without progress by default, so a pod that never reports Ready fails the upgrade. What that costs you while you diagnose depends on the role. A Platform API rollout starts the new pod before removing any old one, so the old replicas keep serving unaffected and you can read the new pod's `/readyz` without time pressure. An indexer rollout replaces pods one at a time, so a pod that never becomes Ready has already taken the instance down a replica, and a Workflow Engine rollout stops every old pod first. Diagnose it promptly. Either way, a `starting` phase or a failing verdict in the new pod's `/readyz` names the cause directly before you decide whether to roll back.

### Is it safe to poll the readiness endpoint myself?

Yes. The kubelet polls the same endpoint. It answers read-only, from in-memory state plus a dedicated Postgres session on an isolated PgBouncer pool, held open across probes rather than opened per call. That session gets 8 seconds to connect and query, covering a fresh reconnect after a dropped connection as well as an ordinary check. The chart pairs it with a 10-second probe timeout and a 15-second period, so a normal kubelet probe has time to finish before its next scheduled check. Avoid rapid additional polling during an incident. The body names each verdict and its reason, which makes it the fastest way to watch a recovery complete. It reports one pod's view only. For the rolled-up operator verdict across the whole instance, use [Platform Health](https://docs.settlemint.com/docs/concepts/operating/platform-health) in the Console.


# RPC upstreams failing over

Source: https://docs.settlemint.com/docs/deployment/runbooks/rpc-upstream-failover
A network's RPC endpoints fail over or run out: read which endpoint fails and why, fix it where the failing client reads it, and know when to escalate.

A single failover is routine and needs no action. Act when calls run out of endpoints, when failover never stops, or when a network has only one endpoint. Two clients read a network's endpoints from different sources, so find the client that fails first.

The platform reaches each network through its RPC endpoints, also called upstreams. When one endpoint fails a call, the platform sends the same call to the next candidate, which is a failover. When every candidate fails one call, the endpoints are exhausted and that call fails.

Two clients read a network's endpoints, from different sources, and each reports its own signals. [Endpoint failover and retries](https://docs.settlemint.com/docs/deployment/networks#endpoint-failover-and-retries) describes both.

- **The transaction engine's client** signs, sends and confirms queued transactions, and serves chain reads in the Platform API and the runner. It uses only the endpoints in the deployment values, so a change on "Platform networks" does not reach it. It ranks endpoints by its own success record and ignores "Priority". Its signals are the `dalp_chain_evm_rpc_*` metrics, labelled with `chain_id` and `rpc_method`. When transactions stop going out, start with this client.
- **The RPC endpoint pool** serves the Platform API and the indexer, including the block and log reads of an index rebuild. A platform administrator changes it on "Platform networks". Only the indexer ranks it on health scores, and only there does it write the `network.rpc-pool` log lines and the `dalp_rpc_*` metrics on this page. The Platform API tries the pool's endpoints in their listed order.

Access: "Platform networks" opens for platform administrators only. Without that role, ask a platform administrator to read the card, or use the metrics and logs.

## Symptoms [#symptoms]

- Transaction engine client metrics, labelled with `chain_id` and `rpc_method`:
  - `dalp_chain_evm_rpc_attempts_total` adds `rpc_upstream_id` and `outcome`, `success` or `failure`, so it shows which endpoint fails. `rpc_upstream_id` is the SHA-256 of the endpoint URL in the deployment values.
  - `dalp_chain_evm_rpc_failovers_total` counts each move of a call to the next endpoint.
  - `dalp_chain_evm_rpc_upstreams_exhausted_total` counts calls that failed on their last endpoint after at least one failover, so it stays flat on a network with one endpoint.
- The transaction engine client logs `persisted RPC upstream health unavailable; ranking on local outcomes only` in category `chain-evm.upstream-selection` when it cannot read the stored health scores.
- The indexer logs, category `network.rpc-pool`, show these lines. Each also carries `network`.

| Log line | Level | Fields |
| --- | --- | --- |
| `RPC upstream failed over` | Warning | `upstream_id`, `method`, `attempt`, `reason` |
| `RPC failover occurred` | Warning | `from_upstream_id`, `to_upstream_id` |
| `RPC upstream excluded for lag` | Warning | `upstream_id`, `block_head_lag`, `max_block_head_lag` |
| `All RPC upstreams exhausted` | Error | `method`, `failure_count`, `upstream_count`, `survivor_count`, `excluded_by_health`, `excluded_by_tip_lag`, `excluded_by_local_liveness` |
| `RPC health-based upstream selection disabled; ranking falls back to configured order` | Warning | `reason_class` |

- A call that exhausted the indexer's pool fails with `All healthy RPC upstreams exhausted for network <name>`, code `core.network.RPC_UPSTREAMS_EXHAUSTED`. The platform treats it as a retryable dependency failure: `Every eligible RPC upstream failed or was excluded.`
- Indexer pool metrics: `dalp_rpc_failovers_total`, labelled with `network`, counts calls that succeeded on a later endpoint. `dalp_rpc_upstreams_exhausted_total`, labelled with `network` and `method`, counts calls that ran out of endpoints. `dalp_rpc_admission_throttles_total`, labelled with `network`, `method` and `reason`, counts `429` answers the pool retried on the same endpoint. The bundled dashboard `Service · RPC & Network Dependencies` charts them.
- The bundled alert `RpcHealthSelectionDisabled` fires when ranking on health scores has been off for 15 minutes on a network. `IndexerWebSocketHeadLatchedOffline` fires when the indexer's `newHeads` WebSocket for a chain has been unavailable for more than five minutes, and stays so for one more minute.
- Two symptoms belong to other runbooks: indexing stops on the chain, which [Ledger indexing stalled](https://docs.settlemint.com/docs/deployment/runbooks/ledger-indexing-stalled) covers, and `NativeBalanceFetchErrors` fires because wallet balances cannot be read, which [Transactions waiting for funding](https://docs.settlemint.com/docs/deployment/runbooks/transactions-waiting-for-funding) covers.

## Checks [#checks]

1. For queued transactions, read `dalp_chain_evm_rpc_attempts_total` for the chain's `chain_id` by `rpc_upstream_id` and `outcome`. A rising `failure` count on one id names the failing endpoint. Compute the SHA-256 of each endpoint URL in the deployment values to match the id. Endpoint URLs often carry a provider API key, so keep them out of shared channels and redact the key from logs and screenshots you share. A rising `dalp_chain_evm_rpc_upstreams_exhausted_total` means calls ran out of endpoints.

2. For the indexer's pool, tell failover from exhaustion, using the ranking rules in [How the indexer's pool picks an endpoint](#how-the-indexers-pool-picks-an-endpoint). A rising failover counter with a flat exhaustion counter means the endpoints absorb the failures. Calls can still fail for other reasons, such as a deadline or an error the endpoint returns for the call itself. Any `All RPC upstreams exhausted` line means calls ran out of endpoints.

3. Read the pool's card. Open "Platform admin", "Platform networks" and read the network's card. When the health readings load, each endpoint shows a badge, "Healthy", "Unhealthy", "Excluded" or "Not measured", with its latency as `<value>ms` and its error rate as `<value>% errors`. An excluded endpoint shows why, for example `Left out of routing: 120 blocks behind the chain head, health score 0.18.` "Serving now" marks the highest-priority endpoint whose latest reading is healthy. A reading older than three minutes counts as "Not measured". The card lists the pool, which can differ from the endpoints in the deployment values.

4. Read the card's notices. "Endpoint health cannot be read right now, so nothing below states whether an endpoint is reachable." means the health readings themselves are unavailable. "The platform has not measured these endpoints yet." means no endpoint has a reading. "Chain head unknown: no endpoint answered." means no endpoint returned the chain head.

5. Read the exhaustion line's fields. `excluded_by_health` and `excluded_by_tip_lag` count endpoints the scores left out. `excluded_by_local_liveness` counts endpoints skipped after a recent failure. `failure_count` against `upstream_count` shows how many endpoints the call tried and lost.

6. Look for rate limiting. A rising `dalp_rpc_admission_throttles_total` means the provider answers `429` and the indexer's pool retries on the same endpoint.

7. If `RpcHealthSelectionDisabled` fires, read the `Health scores unavailable by cause` panel on the dashboard, or `dalp_rpc_health_scores_unavailable_total` by `reason`: `timeout`, `query_failed`, `read_unavailable` or `scoreless`. Until scores return, the indexer ranks its pool by "Priority", then configured order, so a lagging endpoint is no longer left out. The log line `RPC health-based upstream selection restored` marks the recovery.

## Actions [#actions]

- **Queued transactions fail on an endpoint.** Fix the endpoint at the provider, or replace it in the network's `rpc` entry in the deployment values. A change there takes a `helm upgrade` and a restart of the affected components, as [Adding or changing a network](https://docs.settlemint.com/docs/deployment/networks#adding-or-changing-a-network) describes. An edit on "Platform networks" does not change the endpoints transactions are sent through.
- **The network has one endpoint.** With one endpoint, a provider outage fails every call to that network until the provider returns. Add a second endpoint from an independent provider in the deployment values, so calls can fail over when one provider is down.
- **One endpoint in the pool fails or lags.** On "Platform networks", select "Edit network", then work under "RPC endpoints". Lower the endpoint's "Priority", or select its remove icon, labelled "Remove endpoint", once another usable endpoint remains. Save with "Save network". Saving stores the new pool and signals the running processes to reload the network. The previous pool is not kept as a version you can restore, so record the current endpoints before you save. An endpoint added only on this page is not probed, so its card reads "Not measured" and the indexer never excludes it on health.
- **The provider rate-limits.** Raise the plan at the provider, or add an endpoint from another provider.
- **Every endpoint is excluded for lag on a healthy chain.** Raise "Max block-head lag" under "Endpoint health scoring" only when the chain's normal lag is larger than the default. The indexer's pool then uses the new value. The card's "Excluded" badge and reason, and the transaction engine's client, keep the defaults of 50 blocks and 0.25.
- **Answers report missing state or pruned history for old blocks.** The endpoint does not keep the history the platform reads. Use an archive-capable endpoint, as [What RPC provider does a rebuild need?](https://docs.settlemint.com/docs/deployment/runbooks/ledger-indexing-stalled#what-rpc-provider-does-a-rebuild-need) describes.
- **Health scores are unavailable.** Restore the health readings named by the reason. Meanwhile, give the most reliable endpoint the highest "Priority", because priority and then configured order decide.

## Verify recovery [#verify-recovery]

`dalp_chain_evm_rpc_upstreams_exhausted_total` and `dalp_rpc_upstreams_exhausted_total` stop rising, the logs show no new `All RPC upstreams exhausted` line, and the network card shows every endpoint you kept as "Healthy".

## Escalate [#escalate]

Escalate to your DALP support contact when `dalp_chain_evm_rpc_upstreams_exhausted_total` or `All RPC upstreams exhausted` keeps rising after the provider confirms its endpoints are up, when `RpcHealthSelectionDisabled` keeps firing and its reason does not clear, or when an endpoint the card shows as "Healthy" keeps failing calls. Include:

- the network name and chain ID.
- `dalp_chain_evm_rpc_attempts_total` by `rpc_upstream_id` and `outcome`, and the other `dalp_chain_evm_rpc_*` and `dalp_rpc_*` counters for that network, over the time window.
- the `All RPC upstreams exhausted` lines with their `network` and all their fields.
- each endpoint's badge, latency, error rate and exclusion reason from the card.
- the provider's own status for the same window.

## How the indexer's pool picks an endpoint [#how-the-indexers-pool-picks-an-endpoint]

The indexer ranks its pool on health scores when the network has more than one endpoint, at least one of them HTTP, and "Score endpoint health" is on, which is the default. Otherwise it tries the endpoints in configured order, and none of the `network.rpc-pool` lines, the `dalp_rpc_failovers_total` and `dalp_rpc_upstreams_exhausted_total` counters or the exhaustion error appear.

- **Exclusion first.** Routing leaves out an endpoint that is unhealthy, that scores below "Minimum score (0 to 1)", or that trails the chain head by more than "Max block-head lag". The defaults are 0.25 and 50 blocks. While any endpoint is not excluded, the pool sends calls only to endpoints that are not excluded, whatever their priority. When every endpoint is left out, the pool still serves from them in ranked order rather than refusing every call.
- **Then priority.** Among the remaining endpoints, a higher "Priority" wins. Among endpoints with the same priority, the higher health score wins, then configuration order.
- **Health score.** The platform probes each endpoint in the deployment values and scores it from 0 to 1. Whether the last probe failed to return the chain head counts for 45%, latency for 20%, the lag behind the chain head for 25% and the finalisation lag for 10%. An answer that takes 5 seconds or more scores zero on latency.
- **Penalty.** An endpoint that fails a call is skipped for at least one second and loses score for a while. The penalty halves every "Penalty half-life (ms)", 60,000 by default.
- **Stickiness.** Within "Min switch interval (ms)", 60,000 by default, a contender with the same priority takes over only when its score beats the current endpoint by "Switch hysteresis (0 to 1)", 0.1 by default.
- **Budget.** One call may spend "Maximum endpoint attempts", 32 by default, across retries and failovers, within "Request deadline (ms)", 120,000 by default. "RPC retries", 3 by default, applies per endpoint. A transaction broadcast, `eth_sendRawTransaction`, is not retried on the same endpoint by default, but it still fails over to the next one. A network that sets its own per-method retry overrides replaces that default.


# Transactions waiting for funding

Source: https://docs.settlemint.com/docs/deployment/runbooks/transactions-waiting-for-funding
Transactions stop going out because the wallet that pays gas is short: find the wallet, fund it inside the funding window, and recover failed requests.

Work shows "Waiting for funds" because the wallet that pays its gas is short. Fund the wallet the funding notice names before the funding window closes, 1,800 seconds unless the network sets another value, and the request continues.

Every EVM write you submit through the Console or the API becomes a transaction request, which the platform signs and sends to the chain. When the wallet that pays gas for it is short, the platform pauses the transaction request instead of failing it. It opens a funding notice that names the wallet and the amount, and waits for the wallet to be funded. Nothing from that request is mined while it waits.

The wait has a limit, the funding window, set per network. When the wallet is funded inside the window, the request continues on its own once the custody provider's balance view and the wallet's other open writes allow it, as Check 4 explains. When the window closes first, the platform requeues the request, and it pauses again with a new window, up to its retry budget of 3 retries by default. The request fails when the window closes on its last retry. By default the API answers a write before the request runs, so the failure shows on the request's status and in Activity, not on the original API call.

A caller can decline the pause with `Prefer: dalp-no-funding-pause`, and the platform also declines it on a network it treats as charging no gas. [Whether the chain charges gas](https://docs.settlemint.com/docs/deployment/gas-settings#whether-the-chain-charges-gas) explains that setting. A declined pause fails the request at once. When the platform can size the shortfall, that failure carries the funding error described below.

## Symptoms [#symptoms]

- The Console's [Submissions tray](https://docs.settlemint.com/docs/console/essentials/submissions) shows the request as "Waiting for funds", with the line "Held until the wallet it pays from has enough funds. It continues on its own once the funds arrive."
- The [Transaction funding](https://docs.settlemint.com/docs/console/organisation-settings/transaction-funding#fund-an-open-request) page shows a notice such as `Relayer wallet needs 0.25 ETH`, followed by `Operations wait until it is funded. Raised <when>.`, after `It holds <held>.` when the balance is known. When the Console cannot show the amount, the notice reads `<wallet> needs gas`.
- The runner logs, category `ddwf.workflow.with-funding-pause`, hold `Funding pause entered, waiting on the funded subject`. The line carries the wallet as `subject_address`, the balance to fund the wallet up to as `recommended_total_wei`, and the time the window closes as `deadline_ms`.
- After the window closes, the same category logs `Funding pause window elapsed, failing terminal`. The request is requeued unless that was its last retry.
- `GET /api/v2/transaction-requests/<transactionId>` returns `activeRequirement` while the request waits, with the wallet `address`, the `shortfall` and the `recommendedTotal`. Once the request has failed for funding, it returns `contractError` with `id` `DALP-9087`, and `args` carries the wallet `address`, its `shortfall` and the `recommendedTotal`.
- Token, add-on, restriction and portfolio write routes answer `400` with code `TRANSACTION_QUEUE_FUNDING_REQUIRED`, error `DALP-14062`, when the request failed for funding. A caller sees this when it waits for the outcome with `Prefer: wait=<seconds>` and the request fails for funding inside that wait, for example because the pause was declined. `data.refusal` is `FundingRequired`, and `data.transactionId` names the transaction request when the platform recorded one.
- One of these alerts fires from the bundled observability stack:

| Alert | It fires when |
| --- | --- |
| `LowOperatorWalletBalance` | An operator wallet stays below the low-balance mark for 15 minutes. The mark is 0.1 of the native currency, the same one the Console payer status uses. It does not fire on networks reported as charging no gas. |
| `FundingPauseExpirySustained` | Three or more funding notices for the same network and kind of wallet expire unfunded within 30 minutes, and that lasts 15 minutes. |
| `FundingPauseNeverResumed` | A funding notice is still open past its own deadline while a paused request still waits on it, for 15 minutes. |

## Checks [#checks]

Access: "Transaction funding" opens for the system administrator, System Manager and Gas Manager roles. "Platform networks" opens for platform administrators.

1. Tell a paused request from a failed one. "Waiting for funds" in the Submissions tray, an open notice on Transaction funding, or `activeRequirement` on the request's status means the request is still inside its window and needs only the funds. A `DALP-9087` `contractError` on the status, or a `DALP-14062` answer to a `Prefer: wait` call, means the request has failed and must be sent again after funding. Between retries the request can pause again with a new notice.

2. Find the wallet and the amount. When your account has more than one network, the account menu at the top right shows a Network submenu. Select the network the notice is for. Then open "Organisation settings", "Infrastructure", "Transaction funding". Each open notice names the wallet and the amount. From the API, read `activeRequirement` or `contractError` on `GET /api/v2/transaction-requests/<transactionId>`.

3. Read the window. Open "Platform admin", "Platform networks", then "Edit network" on the network, and open "Advanced settings". The "Gas and funding" group shows "Funding pause window (seconds)" with the value in force. The built-in default is 1,800 seconds. ADI Chain mainnet and testnet, Sepolia and Optimism Sepolia ship with 86,400 seconds. [Gas settings](https://docs.settlemint.com/docs/deployment/gas-settings#the-settings) lists every key and its range.

4. If you funded the wallet and the request still waits, search the runner logs in the same category for these lines:
   - `Custody provider balance view has not caught up with the funding, not filing`. The custody provider's own balance view does not show the deposit. The platform checks again after the network's funding settle delay, 120 seconds by default and never less than 5 seconds, until the provider sees it or the window closes.
   - `Sender funds are held by its other open writes, waiting for them to settle`. The wallet holds enough, but earlier requests from the same wallet have not settled. The platform checks again with a growing delay, from 5 seconds up to 60 seconds, inside the same window.
   - `Funding ask cannot be sized, declining to pause`. The platform could not work out the amount, so it did not pause, or it closed a pause already open, and the request failed with its original error.

5. If `NativeBalanceFetchErrors` fires for the same network, the platform failed to read wallet balances on that chain. The runner logs `Native balance fetch failed` in category `didx.native-balance-collector` with the reason. When the reason is an RPC failure, see [RPC upstreams failing over](https://docs.settlemint.com/docs/deployment/runbooks/rpc-upstream-failover).

## Actions [#actions]

- **The request is paused.** Fund the wallet the notice names before the window closes. Select the button on the notice, for example `Fund 0.25 ETH`, and send the network's native currency to the address the sheet shows. Before you send, compare that address with the wallet `address` in `activeRequirement` on the request's status, and with your own record of the platform's wallets. The sheet changes from "Watching for the deposit…" to "Deposit received." when the wallet's balance rises, or, for a wallet the page does not list, when the notice closes. Do not send the write again. The platform resumes the request when the funds land, and logs a line in the same category that ends `slot cleared`, for example `Funding pause re-invoke succeeded after funding, slot cleared`.
- **The request failed for funding.** First confirm that it has failed: its status carries the `DALP-9087` `contractError` and no `activeRequirement`, and Transaction funding has no open notice for it. Then fund the wallet and send the write again under a new `Idempotency-Key`. A new key makes a new write, so sending it while the original can still continue runs the operation twice. Reusing the failed request's key answers `400` `TRANSACTION_QUEUE_DUPLICATE_SETTLED`, error `DALP-14066`.
- **The request failed because other requests held the funds.** The failure reads `kept the funds this write needs. Submit it again once those writes settle.` Wait for those requests to settle, then send the write again.
- **Notices expire unfunded repeatedly.** When `FundingPauseExpirySustained` fires, first check that the notice reaches someone who can fund the wallet. Then raise "Funding pause window (seconds)" on the network if your funding process needs longer. The accepted range is 60 to 604,800 seconds.
- **Wallets run low before any notice opens.** When `LowOperatorWalletBalance` fires, top up the wallet the alert names. The alert has no threshold setting of its own: it reads the same 0.1 mark as the Console.
- **The node kept rejecting a funded wallet.** The failure reads `the node kept rejecting it for gas while wallet <address> already covered <amount>`. The platform retries the request on its own up to its retry budget. If it still fails, send the write again.

## Verify recovery [#verify-recovery]

The request leaves "Waiting for funds" in the Submissions tray, its notice on Transaction funding closes, and `LowOperatorWalletBalance` clears for the wallet.

## Escalate [#escalate]

Escalate to your DALP support contact as a platform defect when `FundingPauseNeverResumed` fires, when a funded wallet's request still shows "Waiting for funds" and none of the lines in Check 4 explain it, or when the request fails again with the node-kept-rejecting message. Include:

- the network and chain ID, and the wallet address.
- the transaction request ID, from `data.transactionId` or the Activity entry.
- the amount the notice asked for and the hash of the funding transfer.
- the `ddwf.workflow.with-funding-pause` log lines for the request, matched on `op_name`, with the `deadline_ms` from the entered and elapsed lines.


# Utila signing agent not signing

Source: https://docs.settlemint.com/docs/deployment/runbooks/utila-signing-agent
Enrol, enable, rotate and recover the customer-run Utila signing agent, and diagnose transactions that wait for its signature.

A Utila transaction that DALP filed waits for the signing agent. If the agent is down, enrolled wrongly, or refused by DALP, the transaction stays in `AWAITING_SIGNATURE` and nothing reaches the chain. Read the status the agent last got from DALP in the status table under Checks: `200` with `signTransaction` true means it signs, `200` with `signTransaction` false cancels the transaction, and every other status leaves it pending. To enrol, rotate or roll back the agent, use the procedure sections after Escalate.

Utila is a third-party custody provider that holds the keys of wallets DALP uses. The agent is the Utila co-signer, run in your cluster. Deploy it with the [Utila signing agent deployment page](https://docs.settlemint.com/docs/deployment/utila-signing-agent). The agent polls Utila for transactions designated to its service account. For each one it asks DALP whether to sign. Use a service account dedicated to DALP, because a refusal cancels the transaction at Utila.

[Figure] What each answer from DALP does to the transaction at Utila. The agent asks DALP about a held transaction. Three outcomes branch from the question. An accent arrow for a 200 answer with sign true leads to a box that says the agent signs. A second 200 answer with sign false leads to a box that says Utila cancels the transaction. A dashed arrow for any other status, 401, 409, 413, 400 or 503, leads to a box that says the transaction stays pending and the agent asks again. Labels: Held transaction; Sign it?; Agent asks; 200, sign true; The agent signs. The transaction goes on.; 200, sign false; Utila cancels the transaction. It is final.; 401, 409, 413,; 400, 503; Stays pending. The agent asks again.

A 200 answer with `signTransaction` true leads to a signature, false cancels the transaction at Utila, and every other status leaves it pending.

## Symptoms [#symptoms]

- Work that DALP designated to the Utila service account stays in `AWAITING_SIGNATURE` in the Utila console past the bound you accept.
- A DALP approval or write through a Utila configuration does not finish, and its approval deadline passes.
- The co-signer does not show as running under Vault Settings, API, Co-signers in the Utila console.
- The agent log shows an error from the decision address on every poll.

## Checks [#checks]

1. Read the pod. `kubectl get pods` for the label `app.kubernetes.io/component=utila-signing-agent` must show one pod `1/1 Running`. Kubernetes has no health signal for the agent beyond that, because Utila documents no liveness endpoint. A running pod can still be stuck.
2. Read the agent log for the status of its last decision request, and match it to the status table. The decision address is the URL the agent calls to ask DALP whether to sign, built from `dapiInternalUrl` and ending in the agent secret, so never paste it into a ticket.
3. In the Utila console, open Vault Settings, API, Co-signers. The co-signer must show as running. If it does not, the agent is not connected: check the service account key, the network egress to Utila, and the state store.
4. Check the transaction. It must list the service account in its designated signers. Utila sends only designated transactions to the co-signer, and transfers created in the Utila console are never sent.
5. In DALP, open Settings, Custody, and read the Utila configuration. It must not be quarantined, and its "Signing agent secret" must be set.

| Status the agent sees | Meaning | Action |
| --- | --- | --- |
| 200 with `signTransaction` true | DALP filed this request and it matches. The agent signs. | None. |
| 200 with `signTransaction` false | The held request differs from the one DALP filed, in the field the body names. Utila cancels the transaction. | Do not retry. Compare the field, then file a new request. |
| 401 | The secret is wrong, the configuration is unknown, or the configuration is quarantined. | Compare the agent secret with the Console field. Check quarantine. |
| 404 | The `dapiInternalUrl`, the path, or the secret is wrong. A secret with URL-reserved characters (`/`, `?`, `#`, `%`) or a trailing newline also gives 404. | Check `dapiInternalUrl`. Recreate the secret with `openssl rand -hex 32`. |
| 409 | DALP never filed this request through this configuration. | Find who created it. The service account must be dedicated to DALP. |
| 413 or 400 | The body is over 64 KiB, or it is not a transaction. | Check the CLI version and any proxy between the agent and DALP. |
| 503 | DALP cannot read its records or its secrets. | Check the DALP API health. The agent asks again. |

## Actions [#actions]

- If the pod is not running, read `kubectl describe pod` and the log. A pod stuck on its volume needs the state store. A pod that cannot reach Utila or the KMS needs an egress rule in `utilaSigningAgent.networkPolicy.egress`.
- If the status is 401, fix the secret first. Generate a new secret with `openssl rand -hex 32`, store it in the cluster Secret, enter the same value in the "Signing agent secret" field of the Utila configuration, and restart the agent. If the configuration is quarantined, find out who quarantined it and why: DALP records the actor and the reason. Lift it only when that cause is fixed and its owner agrees, then select "Test connection" and "Recover execution" with a reason.
- If the status is 503, fix DALP first. The agent needs no change.
- If the pod is running and answers 200 but nothing is signed, check that the key shares cover the chain. Utila needs a key downloaded for every network you sign on, so run `utila keys download` again for the device against the agent's state location.
- To stop new work while you investigate, turn off "New accounts" for the configuration. To stop all signing through it, select "Quarantine execution" with a reason. Quarantine stops DALP from filing and from answering for the configuration. It does not touch transactions already in Utila.
- If designated work stays unsigned, DALP parks the approval until its deadline. After the deadline the request ends as expired and you file it again. You can cancel a transaction in the Utila console when you decide it must not sign. A cancelled transaction cannot be restored, so file the request again.

## Verify recovery [#verify-recovery]

The co-signer shows as running under Vault Settings, API, Co-signers, and a small test transaction that designates the service account gets a `200` with `signTransaction` true and signs.

## Escalate [#escalate]

Escalate to your DALP support contact when the status is `200` and the pod is running but nothing signs after `utila keys download`, or when the agent log shows a status the table does not list. Include the configuration id, the transaction's Utila status, the matching status table row and the time window, with the agent log redacted as [Redact before you share](#redact-before-you-share) describes.

## Enrol the agent [#enrol-the-agent]

Do this once per environment, before you enable the provider.

1. In Utila, create a service account with the Signer role and wait for an admin to approve the role. Use one account only for DALP.
2. Choose the state location and encryption before you register the device. Utila saves the device key and signing keys there, and changing it later can break the agent's commands.
3. Register the device with the Utila CLI. It prints a device id and a fingerprint. Record both.
4. A vault admin approves the device in Vault Settings, Devices, and signs it in the Utila mobile app, and the admin quorum approves it. Record who approved and when.
5. Download the key shares for every network you need to sign on.
6. Keep the device id. The chart needs it as `deviceId`.

## Set the agent secret [#set-the-agent-secret]

The secret binds one DALP provider configuration to one agent.

1. Generate a secret with `openssl rand -hex 32`. DALP enforces a minimum of 32 characters when it saves the credential. The secret is a URL path segment, so use only letters, digits, `.`, `_`, `~` and `-`. Do not use `openssl rand -base64`, which can produce `/`.
2. Store it in a cluster Secret with `kubectl create secret generic <name> --from-literal=secret=<value>`, not `--from-file`, which keeps a trailing newline. Name that Secret in `utilaSigningAgent.signingAgentSecret.existingSecret`.
3. Enter the same value in the "Signing agent secret" field of the Utila configuration in Settings, Custody. The credential key is `auth.signingAgentSecret`.
4. The decision address carries the secret, so never log it. The expanded argument is visible to anyone who can read the pod's process arguments, so restrict who can exec into the agent pod or read its spec. The address uses `utilaSigningAgent.dapiInternalUrl`, plain HTTP inside the cluster by default, so keep the chart's NetworkPolicy on, and use a service mesh with mutual TLS if your policy forbids secrets in cleartext on the pod network.

Each provider configuration has its own secret. A second configuration needs its own agent.

## Enable the agent [#enable-the-agent]

Before you enable, record these values: how many Utila configurations exist, the key source, the state location, and who approved the device.

1. Confirm that the organisation has a Utila provider configuration in Settings, Custody, with its "Signing agent secret" set, as [Utila setup](https://docs.settlemint.com/docs/deployment/utila-setup) describes. Without that configuration the agent has nothing to answer for.
2. Deploy the chart with `utilaSigningAgent.enabled` set to `true`. Confirm the pod is `Running` and shows under Co-signers in the Utila console.
3. Select **Test connection** on the configuration. It must be healthy with a fresh probe time.
4. Send one small test transaction. Confirm that Utila lists the service account as the designated signer, and that the agent log shows one decision request answered with 200.

For the first day, check that the configuration stays healthy, and that no designated work stays in `AWAITING_SIGNATURE` past your bound.

## Roll back [#roll-back]

Use the smallest action that stops the harm.

1. Turn off "New accounts" for the configuration to stop new accounts. Existing accounts keep signing.
2. Select **Quarantine execution** with a reason to stop all signing through the configuration. DALP records the action, the actor and the reason.
3. Scale the agent to zero only after you quarantine. If you scale it down first, new writes wait until their deadline and then end as expired.
4. Roll the image back by digest. The older pod resumes against the existing state.
5. De-enrol the device in Utila as a separate step. Deleting the workload does not revoke the key share, so a live signing credential would stay behind.

To recover, fix the cause, select "Test connection" on the configuration, and select "Recover execution" with a reason.

## Rotate the service account key [#rotate-the-service-account-key]

DALP and the agent use the same Utila service account, so rotation changes both sides in order. Keep the old key working until the last step.

1. Add the new key to the service account in Utila as a standby.
2. In DALP, put the new key in the "Standby private key (PEM)" field of the configuration.
3. Switch DALP to the new key by replacing the "Service account private key (PEM)".
4. Switch the agent. Update the KMS key or the Secret behind `UTILA_SA_PRIVATE_KEY`, then restart the pod.
5. Select **Test connection** and confirm it is healthy, and confirm that a test transaction signs with the new key on both sides.
6. Only then remove the old key from the service account in Utila. Removing it earlier leaves you no working key if the new one fails, and adding another needs the vault admin quorum.

## Recover from lost access [#recover-from-lost-access]

If Utila answers code 1002 after DALP mints a fresh token, Utila no longer accepts the key. Someone revoked it, or it expired. Switch to the standby key: move the standby into the active field in DALP and in the agent. Adding a new key to the service account needs the vault administrator quorum, so allow time for it.

## State loss [#state-loss]

The agent state holds the device key and the key shares. If you lose it, the agent cannot sign. Recovery is a new enrolment: register a new device, have the admin quorum approve it in the Utila mobile app, and download a new key share. Back up the state store. On a PVC, use volume snapshots. In object storage, turn on versioning.

## Redact before you share [#redact-before-you-share]

Remove these from tickets, logs and screenshots: vault ids, service account emails, wallet resource names, addresses, signature bytes, the agent secret and the decision address. A transaction hash is public and is safe to share.

## Run it locally [#run-it-locally]

Use a stub to check the invocation without a Utila vault.

1. Build the image from Utila's distroless Dockerfile with the CLI binary from the Utila Resource Centre.
2. Start a stub HTTP server that answers every POST with 200 and `{"signTransaction":false}`.
3. Run the image with `cosigner run`, the vault id, the device id and the stub address as `--webhook-url`. Use a vault with no value, and never `--sign-all-txs` against a vault that holds funds.
4. Create one transaction that designates the service account. Confirm the stub receives the transaction body and that Utila cancels it. Change the stub to answer 503 and confirm the transaction stays pending.

## Alert bound for unsigned work [#alert-bound-for-unsigned-work]

Utila documents that an unreachable endpoint leaves a transaction pending and that the co-signer asks again on the next poll. DALP publishes no measurement of how the agent behaves in a live vault when the decision route is unreachable, or of how many seconds it takes to notice unsigned work. Set your `AWAITING_SIGNATURE` alert bound from what you observe in your own vault during [Enable the agent](#enable-the-agent), step 4.


# Webhook deliveries failing

Source: https://docs.settlemint.com/docs/deployment/runbooks/webhook-deliveries-failing
A webhook endpoint stops receiving events: the retry schedule, the automatic circuit breaker that pauses a failing consumer, and how deliveries recover.

A registered webhook endpoint has stopped receiving some or all of its events. Open its delivery history: its shape tells you whether attempts keep failing, have stopped, or succeeded while your consumer disagrees. A webhook endpoint is a URL you register with a DALP instance so the platform pushes a signed HTTP request to it whenever a relevant event happens. It covers outbound webhook delivery from the platform to your consumer. Webhooks your instance receives from compliance providers are a different surface with their own management screens.

Every check reads from the endpoint's delivery history: one row per event with its attempts nested under it, each attempt with its status, its failure class, and the response your consumer returned. In Console, open Organisation settings, then Webhooks, then the endpoint. The Event deliveries tab lists every event with its attempts, and clicking a row opens the Webhook event sheet with the failure class, the signed request headers, the response, and a ready-made repro command. The same history is available from the `dalp` command-line tool as `dalp get webhooks deliveries <webhookId>`, and over the [webhook management endpoints](https://docs.settlemint.com/docs/api-reference/guides/webhooks).

Whatever the cause, the history shows one of three shapes: attempts that keep failing, attempts that have stopped entirely, or attempts that succeeded while your consumer disagrees. Breaker, Reactivate, replay and the address policy are on the platform side. DNS, TLS, response codes, the signing secret and receipts are on the consumer side, so send the failure class to the consumer's owner.

## Symptoms [#symptoms]

- A registered webhook endpoint stops receiving events it previously received.
- Deliveries to one endpoint fail while other endpoints on the same instance keep receiving events normally.
- The endpoint's status in Console changed to Auto-disabled without anyone switching it off.
- Your consumer reports missing events for a time window, then receiving them all at once, or not at all.

## Checks [#checks]

Read the delivery history first. Its shape tells you which check to start with.

[Figure] The delivery history's shape picks the check to run. Start with the Event deliveries tab, which lists one row per event with its attempts, each with its failure class and the consumer's response. Three shapes follow. Failing rows that keep appearing split on the failure class: a retryable class such as DNS, TLS, a timeout, or a 5xx keeps retrying for three days, so fix reachability under check 3. A terminal 4xx is permanent for that one event, handled under check 4. No new rows at all means the circuit breaker is open: go to check 2. Rows that show delivered while your consumer disagrees point at receipt deadlines and duplicate handling under check 5. Labels: Start with the delivery history; What does Event deliveries show?; One row per event, with its failure class and the consumer's response; Attempts continue; Failing rows appear; Read the failure class; in Last response; Attempts stopped; No new rows at all; The breaker is open:; go to check 2; Consumer disagrees; Delivered, disputed; Receipt deadline or; duplicates: check 5; DNS, TLS, a timeout, or a 5xx; Retryable failure; The platform keeps retrying for 3 days; Fix reachability: check 3; Permanent for that one event; Terminal 4xx; Consumer rejected the request outright; If signing is verified, check 4.

The delivery history sorts a failing endpoint into three shapes: attempts that keep failing, attempts that stopped, and deliveries the consumer disputes.

1. Confirm whether the endpoint's failures are transient or sustained. The signal is the Event deliveries tab: a healthy endpoint shows mostly delivered rows, with occasional failed attempts followed by a delivered one for the same event. A single failed attempt retries automatically on an exponential schedule that starts near 30 seconds and roughly doubles after each attempt, with random jitter so many endpoints failing at once do not retry in lockstep. Retries stop 3 days after the platform recorded the event. The next attempt after that records the abandonment, and an open breaker delays that attempt, so the entry can appear after the event has aged out, as check 2 explains. A handful of retries in the history is normal. Some failures never retry: a delivery your consumer rejects with an ordinary 4xx response, other than a request timeout or a rate-limit signal, is permanent for that event. A fix made afterward recovers future events but never that one. Each attempt itself times out after 20 seconds if the consumer never responds.
2. Check whether the platform has stopped attempting deliveries. The signal is the Breaker field under Endpoint details on the endpoint's Overview tab. "Closed, deliveries flowing" means deliveries flow. "Open, deliveries paused", with the endpoint shown as Auto-disabled, means the breaker tripped and the platform is skipping deliveries to this endpoint rather than attempting them.

   - Tripping. An endpoint trips the breaker after 30 consecutive failed deliveries. Missed receipt deadlines count toward that streak, manually sent test events never do. Events that happen while the breaker is open are not queued for the endpoint, so neither recovery nor a replay delivers them later.
   - Recovery. Recovery is automatic: the platform probes an open endpoint by re-sending its most recent live event, each probe at least a minute apart with 10 seconds to answer. A failed probe resets the success count, so a consumer that flaps between working and failing stays paused until it answers twice in a row. Two consecutive probe successes move the endpoint to Recovering, and live deliveries resume immediately. The next delivered event returns it to Enabled.
   - The Recovering trap. Entering Recovering does not reset the failure streak that tripped the breaker in the first place. One failed live delivery there reopens the breaker immediately, before a second probe or a delivered event ever gets the chance. A consumer that is only half fixed can loop through probe, Recovering, and Auto-disabled without a single live delivery landing.

3. Verify the consumer's endpoint is reachable and answering correctly. The signal is the failure class in the Last response column on each row.

   - Reading the taxonomy. It separates the ways a request can die: the name never resolved, the TLS handshake failed, the connection never opened, the response never finished, or the consumer answered with an error status. The sixth value is an unparseable response. A request the platform refuses under the two address rules that follow never reaches the consumer and records `TARGET_REFUSED`. The healthy value is a delivered row, which the platform records only for a 2xx response.
   - Network failures. All of them retry on the normal schedule, so fixing the consumer is enough and no platform-side change is needed.
   - Platform policy. The platform checks endpoint address and HTTPS policy at registration and before each dispatch. A URL that fails those checks cannot be registered. The endpoint URL must resolve to a publicly routable address. A receiver on private address space fails that check until the operator adds its range to `global.dalpApp.config.webhooks.allowedTargetCidrs` in the deployment's Helm values. The URL must also use https. Both rules share one exception: an origin the operator lists in `DALP_WEBHOOKS_TRUSTED_DESTINATIONS`, for a private-network install, is exempt from the https requirement and the public-address check alike, so an endpoint on that list can use http:// or a private address. Both settings widen the delivery policy for every organisation on the instance, not only the endpoint you are fixing, and a trusted origin receives deliveries over plain HTTP. List only private receivers your own team runs. Never list a DALP origin or another internal service whose responses must stay private, because the delivery history records the response, so a webhook manager in any organisation could read it through a delivery. Tenant-facing APIs cannot add an origin to that list. Only an operator changing the deployment's configuration can. An attempt that fails either rule before dispatch sends nothing, records `TARGET_REFUSED`, and does not retry: correct the endpoint URL or the deployment's configuration, then use Resend for each affected event.

4. If the integration verifies signed payloads, confirm the consumer holds the current signing secret. The signal is a run of terminal 4xx rows that started when a secret changed on either side. A consumer that rejects a signature usually does so with an ordinary 4xx, which the platform treats as permanent for that event. Fixing the secret recovers deliveries from that point forward but does not restore the events rejected while it was wrong. Replay them, as Actions describes. Two behaviours keep rotation itself from causing this. After a rotation the previous secret stays valid for 24 hours, and the platform signs with both secrets during the overlap. An event that waited in retry backoff is re-signed with a fresh timestamp before the next attempt, inside the Standard Webhooks tolerance window. A long network delay or clock mismatch can still exceed the receiver's timestamp tolerance. Check receiver time and the verified delivery headers.
5. If the endpoint requires counter-signed receipts, confirm the consumer responds inside its receipt window. That window is 30 seconds by default. Receipt timeout in the endpoint's Edit sheet, or `receiptTimeoutSeconds` through the API, sets it to a whole number of seconds from 1 to 60. The signal is rows that reached the consumer but still count as failures because the receipt never arrived in time. A late receipt is treated like any other failed delivery and retried on the normal schedule. A receipt whose signature does not verify is refused without changing the delivery, so the consumer can sign it again inside the window. A correctly signed receipt whose body hash does not match is different: it ends delivery of the event, on the same footing as a terminal 4xx. A corrected receipt for the same delivery still restores the attempt as delivered.

[Figure] The circuit breaker recovers automatically, and one failed delivery during recovery reopens it at once. A healthy endpoint delivers normally while individual failures retry on the backoff curve. Thirty consecutive failed deliveries trip the breaker, and test events never count. While the breaker is open the platform skips deliveries to the endpoint rather than attempting them, and Console shows the endpoint as Auto-disabled. Test events still deliver and change nothing. The platform probes the open endpoint automatically by re-sending its most recent live event, each probe at least a minute apart with ten seconds to answer, and a failed probe resets the success count. Two consecutive probe successes move the endpoint to Recovering, where live deliveries resume immediately, and from there two things can happen. The failure count that tripped the breaker carries over unchanged: one failed live delivery while Recovering reopens the breaker at once, looping back to Open before a second probe or a delivered event ever gets the chance. Only if a live delivery succeeds first does the endpoint return to Enabled, with the failure streak reset to zero. A manual shortcut exists: the Reactivate action on the endpoint's Overview tab re-enables the endpoint and closes the breaker at once. Labels: The breaker recovers on its own; Enabled, closed; Deliveries flow. Individual failures retry on the backoff curve; 30 consecutive failed deliveries trip it.; Test events never count; Open; Deliveries are skipped, not attempted. Console shows Auto-disabled; Test events still deliver and change nothing; Automatic probe: the latest live event,; at least a minute apart, 10 seconds to answer.; A failed probe resets the success count; Recovering (half open); After two consecutive probe successes, live deliveries resume immediately; The next delivered event; A live delivery succeeds; closes the breaker fully; The failure streak resets to zero; One failed live delivery here; One failure reopens it; reopens Open immediately; The failure count carries over; Reopens; Open at once; Enabled, closed again; The failure streak starts from zero; Manual shortcut; Reactivate on the endpoint's Overview tab re-enables it and closes the breaker at once.

The breaker trips after 30 consecutive failed deliveries, recovers through probes, and reopens at once if one live delivery fails while Recovering.

## Actions [#actions]

- If the breaker tripped, fix the underlying reachability or response problem first. The platform resumes on its own once its probes confirm recovery: two consecutive successes, each at least a minute apart, so recovery takes at least two minutes after your fix, and longer when a probe fails. Events raised during that wait are not delivered to this endpoint later, so once the fix is in place, prefer to recover at once: on the endpoint's Overview tab, Reactivate, or Reactivate and replay failed events when failed events are loaded, re-enables the endpoint and closes the breaker at once. Enable in the endpoint's actions menu does the same. Use Send test event to confirm your fix either way. A test event delivers even while the breaker is open and never counts toward tripping or clearing it, so it confirms your fix without changing the breaker.
- If events aged past the 3-day retry window, or failed terminally, replay them. Replay covers only events the platform recorded for this endpoint. Events raised while the breaker was open were never recorded for it, so no replay returns them: reconcile that window from the API, from the time the breaker opened until it closed. The [webhook replay call](https://docs.settlemint.com/docs/api-reference/webhooks/consuming#resend-and-replay) re-queues either one event by its id or every matching event in a block range. Each replayed delivery is flagged as a replay in its envelope, so your consumer can tell it from a first delivery. Replay is refused while the endpoint is disabled or the breaker is open, so recover the endpoint first, then replay. Check the delivery history for events approaching the 3-day window rather than waiting for an alert.
- If signature verification was the failure, correct the consumer's secret, then replay. A rejected signature is permanent per event, so the events that failed while the secret was wrong stay failed. The same [replay and retry calls](https://docs.settlemint.com/docs/api-reference/webhooks/consuming#resend-and-replay) cover both a window of them and a single delivery you want to re-queue on its own. Deliveries themselves are otherwise working, so no platform-side change is needed.
- If your consumer sees a duplicate event, it is normal at-least-once delivery within the 3-day retry window. The platform journals delivery attempts, and a retry reuses the same event id as its original delivery throughout. Deduplicate retries on the `webhook-id` header, which carries that id on every attempt. A replay is different: it mints a fresh event id for each event it re-queues, so the `webhook-id` header on a replayed delivery does not match the original and deduplicating on it does not work. Use `is_replay` to recognise the replay, then use stable domain identifiers from the event payload to avoid applying the same outcome twice.

## Verify recovery [#verify-recovery]

New events show as delivered in Event deliveries, the endpoint's Breaker field reads "Closed, deliveries flowing", and replayed events reach your consumer flagged as replays.

## Escalate [#escalate]

Escalate to your DALP support contact with the endpoint id, the failure window, whether the breaker had tripped, and the failure class shown in the delivery history. That field distinguishes a consumer-side outage from a platform delivery defect. A name that never resolved points at DNS or egress, a terminal 4xx points at the consumer's validation, and a run of timeouts points at the consumer's capacity.

## Frequently asked questions [#frequently-asked-questions]

### Does the 3-day retry window keep counting while the breaker is open?

Yes. The window is measured from when the platform recorded the event, and it does not pause while the breaker skips deliveries. A consumer that stays broken for days can therefore age events out without a single further attempt appearing in the history. After a long outage, replay the events that aged out before the breaker tripped, and reconcile from the API the window the breaker was open, which no replay covers.

### What happens to a delivery when the platform's own database fails part-way through it?

The attempt pauses and the platform runs it again later. The first rerun comes about a minute after the failure, and each further wait is twice as long as the one before, up to six hours. The endpoint's later events wait behind the paused one, so they still arrive in order once it goes through. Each rerun signs the event again before it posts, so a delivery sent after a long pause still carries a fresh signature. Your consumer can receive the same delivery twice when the first post went out before the failure. Deduplicate on the `webhook-id` header as for any retry.

If the attempt still fails after ten reruns, about eight and a half hours after the first, or cannot be completed at all, the platform marks that event as failed with the reason `attempt_workflow_died` and logs the error. The endpoint's later events then keep flowing. Replay the failed event with the [webhook replay call](https://docs.settlemint.com/docs/api-reference/webhooks/consuming#resend-and-replay).

### Does rotating the signing secret break deliveries already in flight?

No, provided the consumer finishes its switch inside the 24-hour overlap described in check 4. After the overlap ends, the old secret stops signing, and a consumer still pinned to it starts rejecting deliveries as terminal 4xx failures, the same signature scenario check 4 covers.


# Security and compliance posture

Source: https://docs.settlemint.com/docs/deployment/security-compliance-posture
Answers to bank security review questions about a DALP instance: SSO, two-factor, maker-checker, privileged access, keys, encryption, audit and supply chain.

A DALP Instance has fixed controls and controls your deployment sets, and a security review records both. A login authorises nothing on its own: an asset operation passes five separate controls, shown under [Login is not enough to move assets](#login-is-not-enough-to-move-assets). The gaps a reviewer asks about are stated here: sign-in is OpenID Connect only, with no SAML or LDAP connector, there is no break-glass account, the release images and their records are not signed, there is no post-quantum signature option, and this page claims no certification.

## Short answers for a security questionnaire [#short-answers-for-a-security-questionnaire]

| Topic in the questionnaire | Short answer | Section |
| --- | --- | --- |
| SSO, OAuth 2.0, OpenID Connect | OpenID Connect to any standards-compliant identity provider, for the Console. | [Identity and single sign-on](#identity-and-single-sign-on) |
| SAML | No SAML connector. Put an identity provider that issues OpenID Connect tokens in front of a SAML source. | [Identity and single sign-on](#identity-and-single-sign-on) |
| LDAP, Active Directory | No LDAP connector. Connect the directory to an identity provider that issues OpenID Connect tokens. | [Identity and single sign-on](#identity-and-single-sign-on) |
| MFA, two-factor | The deployment can require login two-factor for local accounts. Under SSO, your identity provider enforces MFA. Wallet verification asks the person to confirm each write they request in the Console. | [Two-factor authentication](#two-factor-authentication) |
| Segregation of duties, maker-checker | Role-pair rules on role grants, five built-in second-person checks, and ten approval families an owner or platform administrator switches on. | [Segregation of duties and maker-checker](#segregation-of-duties-and-maker-checker) |
| PAM, privileged access, break-glass | One platform administrator role, granted in three ways. Impersonation lasts one hour and is recorded. No break-glass account exists. | [Privileged access](#privileged-access) |
| Key management, HSM, secrets | Keys sit in the platform key store by default, inside the same deployment and so with no independent custody, or with a custody provider such as a Thales Luna HSM. Secrets come from Conjur, Kubernetes Secrets or a secret manager. | [Secrets and key handling](#secrets-and-key-handling) |
| Encryption in transit | TLS terminates at the Ingress, Gateway or OpenShift Route you configure. Traffic inside the cluster is plain HTTP. Datastore TLS is a value you set. | [Encryption in transit](#encryption-in-transit) |
| Encryption at rest | The platform encrypts KYC data, login authenticator secrets, and secrets held in its local store itself. Disk and database encryption belong to the stores you operate. | [Encryption at rest](#encryption-at-rest) |
| Logging, audit, SIEM | A hash-chained audit trail with CSV export, plus OpenTelemetry traces, metrics and logs to your collector. | [Logging and audit trail](#logging-and-audit-trail) |
| SDLC, SBOM, provenance | Every DALP image carries an SPDX bill of materials and a SLSA provenance record. Neither the records nor the images are signed. | [Secure development and supply chain](#secure-development-and-supply-chain) |
| Post-quantum readiness, cryptographic agility | On-chain signatures use the network's curve: secp256k1 on EVM networks and Ed25519 on Canton. Only the transaction code parameters and your TLS edge are configurable. No post-quantum option. | [Cryptographic agility](#cryptographic-agility) |
| Vendor access to production | Set by the access rung you choose, from full cluster access down to none. Cluster access is data access. | [Hosting and access](https://docs.settlemint.com/docs/deployment/hosting-and-access#cluster-access-means-data-access) |
| Third-party data processors | The Console assistant and Ask AI send questions to OpenRouter when a key is set. The exchange-rate refresh calls a public currency API by default. | [Logging and audit trail](#logging-and-audit-trail) |
| Data visibility on a public chain | Treat addresses, calldata, events and timing as public. Identity evidence stays off chain. | [A public EVM network makes activity discoverable](#a-public-evm-network-makes-activity-discoverable) |
| Custody versus compliance | Separate checks, each passing or failing on its own. | [Custody and compliance are separate decisions](#custody-and-compliance-are-separate-decisions) |
| SOC 2, ISO 27001, other certifications | This page claims no certification. For a SettleMint-hosted or managed deployment, see the SettleMint Trust Centre. | [What supports a technical review](#what-supports-a-technical-review) |

## Identity and single sign-on [#identity-and-single-sign-on]

The Console signs users in with email and password or a passkey by default, and with OpenID Connect (OIDC) when you configure an identity provider. OIDC is the only external sign-in protocol the platform supports. It has no SAML and no LDAP connector.

To use a SAML federation, an LDAP directory or Active Directory, connect it to an identity provider that issues OIDC tokens, and point DALP at that provider. The OIDC setting is provider-neutral, so any standards-compliant issuer works. The issuer must use `https://`.

One complete provider entry under `auth.oidcProviders` replaces local Console sign-in for the whole deployment. The Investor portal keeps email and password for investors. [Single sign-on](https://docs.settlemint.com/docs/deployment/sso) covers the entry, the administrator claim, the lockout risk and its recovery.

Local passwords follow a server-side policy under `auth.passwordPolicy`. By default a password has at least 12 characters and three character classes, cannot repeat one of the last five, and never expires. By default, five wrong passwords within 15 minutes lock the account for 30 minutes. A session expires seven days after its last renewal, and the platform renews a session in use once a day, so an active session has no fixed end.

## Two-factor authentication [#two-factor-authentication]

Login two-factor guards sign-in. Wallet verification confirms a signing request after sign-in. They are separate challenges, and enrolling one does not enrol the other.

### Login two-factor [#login-two-factor]

`auth.enforce2fa` is off by default. When you turn it on, the API refuses every authenticated call from a browser session whose account has no login two-factor, with `LOGIN_2FA_REQUIRED`. On a deployment without an OIDC provider, the Console sends the user to two-factor setup. A request with an API key is not subject to this check. An account whose only sign-in is your OIDC identity provider is not subject to it either, because the identity provider owns the login challenge. An account that also has a password or a passkey still needs login two-factor. Before you roll SSO out, set an MFA policy at the identity provider.

Each organisation chooses which second factors its members may use at sign-in: an authenticator app, an email code or a text message code. A new organisation allows the authenticator app only. [Sign-in codes](https://docs.settlemint.com/docs/getting-started/sign-in-codes) covers the email and text message options. At the two-factor step a user can tick "Trust this device". That device then skips the second factor until 30 days pass without a sign-in from it.

### Wallet verification [#wallet-verification]

Wallet verification accepts a transaction PIN, a transaction code from an authenticator app, a single-use recovery code, or a code from a FusionAuth identity provider. Each account enrols its own methods, and the platform refuses a request that names a method the account never enrolled. The identity-provider method exists only when you configure the wallet verification fields of an OIDC provider entry, and the platform checks the code through FusionAuth's user and two-factor API, so other identity providers cannot act as a wallet factor.

Repeated failed attempts lock wallet verification for the whole account, across every method. A wrong code reports how many attempts remain. Once the account locks, the platform refuses further attempts, correct codes included, until the reported wait passes. The refusals are catalogued in the [Platform API error reference](https://docs.settlemint.com/docs/api-reference/errors/platform-api-error-reference), so an integration can tell an unenrolled method from a wrong code and from a locked account.

A request authenticated with an API key skips the wallet challenge, because the scoped key is the machine credential for that request. Authorisation, the asset's compliance rules and the signing policy still review it. Scope each key to the operations it needs, and revoke it when the integration or its owner changes.

## Login is not enough to move assets [#login-is-not-enough-to-move-assets]

A session or an API key authenticates the caller and authorises nothing on its own. An asset operation also has to pass authorisation, any required wallet verification, the signing policy of the key, and the asset's on-chain rules.

Authorisation checks whether the caller may request the operation. Wallet verification challenges an eligible browser-session request. Prechecks can predict a compliance rejection before signing, but the contract makes the authoritative decision when the signed transaction executes. Custody policy decides whether the provider releases a signature. A self-custody holder signs with their own wallet, so no platform request can release or withhold that signature, and the contract still enforces its rules. Each layer can refuse on its own.

These layers govern requests made through the platform. A contract checks role membership, not the platform session, so a key that holds an on-chain role can call the contract from any tooling on a public EVM network. Keep role-holding keys behind a signing path you trust, and record who controls them.

[Figure] Five controls govern access, signing, and transaction execution. Authentication and authorisation identify an eligible caller. Browser-session requests can require wallet verification. The configured signer releases a signature, then the contract enforces the asset rules during execution. Prechecks can detect likely failures before signing but do not replace contract enforcement. Self-custody holders sign directly, and the contract still checks their transactions. Record the authentication, wallet-verification, and custody settings in the deployment review. Labels: The path a signing request takes; 1. Authentication; A recognised session, API key, or SSO identity?; 2. Authorisation; May this caller request this operation at all?; 3. Wallet verification; Did the holder confirm this exact write?; 4. Custody or signer policy; Does the provider release a signature?; Contract executes or reverts; 5. On-chain compliance; Authoritative check of the asset rules; Each layer refuses alone; Passing one layer proves; nothing about the next.; Your choices; Three layers depend on your; settings and enrolment:; 1. login two-factor enforcement; 3. wallet verification methods; 4. custody or signer policy; Record each choice in the; instance's evidence pack.; Managed signing only; A self-custody holder signs; directly, and contract checks; still apply at execution.

Authentication, authorisation, wallet verification, custody policy and on-chain rules each protect a different stage of a signed transaction.

## Segregation of duties and maker-checker [#segregation-of-duties-and-maker-checker]

The platform separates duties in three ways: role-pair rules on role grants, five built-in second-person checks and ten maker-checker approval families. The first two always apply, and the approval families apply once the organisation switches them on.

Role-pair rules act when a role is granted. The platform always refuses to give one address the Auditor system role together with any of the other 14 system roles the platform grants, whichever is granted second. Each organisation can also keep its own rules, which block or warn on a grant that gives one address two conflicting on-chain roles, such as Governance and the custodian role. Those rules apply once the organisation enables them, and a report lists every address that already holds a conflicting pair.

Five built-in controls refuse a decision by the person who proposed it: a trade bust, a desk trading limit, a wallet checker approval, a reporting sign-off with its acknowledgement, and a partial redemption or payout in new tokens. A bust of a delivered trade always waits for a second person. Other trade busts and desk limits wait for one only while the Trading venues approval family is on, and an organisation can switch the partial redemption control off. [Maker-checker](https://docs.settlemint.com/docs/concepts/custody-and-signing/maker-checker) states when each control applies.

Maker-checker approvals cover ten families of change, which an owner or a platform
administrator switches on in the organisation's `Approvals` settings. The Administration family sends privileged
changes, such as role management, compliance configuration, freezes, pauses, forced transfers and recovery, to a second
person for approval. Every family is off by default, so a new organisation asks nobody for a second approval until
someone turns a family on.

[Roles and segregation of duties](https://docs.settlemint.com/docs/concepts/compliance-and-identity/roles-and-segregation-of-duties) lists every role, rule and enforced pair. [Approvals](https://docs.settlemint.com/docs/console/organisation-settings/general#approvals) describes the families and who decides each request.

## Privileged access [#privileged-access]

The platform administrator is the one role with authority across every organisation and user account on the instance. The organisation Owner and Member roles act inside one organisation, and on-chain roles act on contracts.

The platform administrator role is granted in three ways:

- The first account created locally on a new instance, before any other account exists, becomes one. Without an OIDC provider, anyone who can reach the Console or the Investor portal can create an account, so create the first administrator before you expose the instance. Keep at least one administrator at all times: once accounts exist, a new account is always a member, and [the steps below](#restore-the-platform-administrator-role) restore the role when none is left.
- A platform administrator gives the role to a local account on that account's page under Platform admin › Platform users.
- With SSO, the identity provider decides at every sign-in. `adminClaim` is either a value that must appear in the user's `roles` or `groups` claim, or the name of a claim that must be `true`. A grant made in DALP is overwritten at the user's next sign-in, and with no `adminClaim` every SSO user signs in as a member. Whoever can set that claim at your identity provider controls who is a platform administrator.

A platform administrator can impersonate a member to investigate a problem. The impersonated session lasts one hour, cannot target another platform administrator, and records the administrator who started it in the audit trail. An impersonated session cannot approve or reject anything that waits for a second person, and cannot loosen the approval policy. The Platform API refuses such a decision with `DALP-200386`. An impersonated session also cannot approve a device sign-in, add a passkey or connect an MCP client, so the administrator cannot sign in later as the member without the impersonation mark. [Maker-checker](https://docs.settlemint.com/docs/concepts/custody-and-signing/maker-checker#impersonated-sessions-cannot-decide) lists the decisions it covers.

The Helm value `global.dalpApp.config.auth.allowImpersonatedDecisions` lets an impersonated session decide. It exists for demo deployments only. It is `false` by default and in every shipped values file. Leave it `false` on any deployment that holds real assets or real people: with it on, one administrator can approve their own proposal by impersonating a second operator.

A platform administrator signed in as themselves can change the organisation's approval policy and decide held requests in the Administration family, the same as an owner. Review who holds the role as part of your privileged access review.

On chain, version 2 of the system access manager refuses a revoke or a renounce that would leave its Admin role with no holder. A system access manager upgraded from version 1 refuses Admin grants and revokes until its administrator count is initialised, and the guard does not cover a contract upgrade by an Admin or system manager. Version 2 of the token access manager protects the last Admin of each token created on it, and of a token created on version 1 once one of its administrators migrates it.

The platform has no break-glass account. If an SSO configuration locks every operator out, the recovery is a redeploy with an empty provider list, which [Single sign-on](https://docs.settlemint.com/docs/deployment/sso#recovering-from-a-lockout) describes. Keep deploy access to the cluster under your own privileged access controls, because it reaches every secret the platform holds.

### Restore the platform administrator role [#restore-the-platform-administrator-role]

Once accounts exist, no new account becomes a platform administrator. When the last one has lost the role, or no administrator can sign in, the migration Job restores the role to an existing account. With its default hook settings, the chart runs that Job on every install and upgrade, and its `recover-platform-admin` step acts only on an upgrade that names the account. The recovery needs deploy access to the cluster, not a Console session or an API key.

The recovery is for a deployment where the Console accepts password sign-in. Pick an account that has a password and is not banned. The step refuses an account with no password, such as one created through single sign-on or an invited account that has not finished signing up. With single sign-on configured, the Console refuses password sign-in, and the identity provider sets each account's role at every sign-in. Set the administrator claim at your identity provider instead, as [Single sign-on](https://docs.settlemint.com/docs/deployment/sso) describes.

1. Find the chart version the release runs: the `CHART` column of `helm list --namespace dalp` shows it as `dalp-<version>`. Upgrade the release with that version and your usual values file, and add the account's email address. Replace the release name and namespace `dalp` with your own.

   ```bash
   helm upgrade dalp oci://pkg.distribution.settlemint.com/settlemint/dalp \
     --version <current chart version> \
     --namespace dalp \
     --values my-values.yaml \
     --set dapp.migrator.env.PLATFORM_ADMIN_RECOVERY_EMAIL=ops@example.com
   ```

   Upper and lower case in the address do not matter. Keep the chart version and values as they are, so the upgrade changes nothing else.

2. Wait for `helm upgrade` to succeed. The migration Job has then granted the role, or found that the account already held it and changed nothing.

   When the account does not qualify, the step fails the Job with the error `dalp.migrator.PLATFORM_ADMIN_RECOVERY_REFUSED` and the role does not change. The message says why: no account has the address, the account has no password sign-in, or the account is banned or closed. A retry with the same address fails the same way. With the default `pre` hook type, Helm stops before it changes any running pod and keeps the failed Job, so you can read the message with `kubectl logs job/dalp-migrations --namespace dalp`. Correct the address or pick another account, then run step 1 again.

3. Sign in to the Console with that account's password. The account holds the role from its next request.

4. Run the upgrade again without the `--set` line. While `PLATFORM_ADMIN_RECOVERY_EMAIL` stays set, every upgrade gives that account the role back if someone removes it. Once that account is banned or deleted, every upgrade fails at the migration Job until you remove the value.

Each grant writes one entry to the audit trail: the route `auth.admin.setRole`, the system actor `platform-admin-recovery`, the account as its target, and the role before and after. The entry belongs to no organisation, so a platform administrator reads it through the platform-wide query of the [audit trail](https://docs.settlemint.com/docs/concepts/records-and-evidence/audit-trail). When the account already held the role, the step records nothing.

## Secrets and key handling [#secrets-and-key-handling]

Deployment secrets reach the pods in one of three ways, and you can mix them:

- Values you set in the chart's shared environment block, which the chart renders into a Kubernetes Secret. Helm stores every chart value in its release history, so pass production secrets through an `existingSecret` or Conjur instead.
- An `existingSecret` you create for the Blockscout and DApp PostgreSQL connections and the DApp Redis connection under `global.datastores`.
- Conjur, through `global.conjur`. A Conjur authenticator init container signs the pod in, and `summon` injects each mapped secret as an environment variable when the process starts.

The platform's own secrets, such as signing keys, custody provider credentials, and the Xero app secret and refresh token that connect an organisation's ledger, go to the secret manager selected by `secretManager.provider`: `local`, `aws`, `gcp`, `azure` or `vault`. With `local`, the platform encrypts each secret and stores it in its own database. With the other four, the secret lives in your AWS Secrets Manager, Google Secret Manager, Azure Key Vault or HashiCorp Vault, under its controls and audit. [Values and secrets](https://docs.settlemint.com/docs/deployment/install/values-secrets) covers each option.

Four values are always yours to generate: the encryption master password, at least 16 characters and 128 bits of estimated entropy, the session signing secret, at least 32 characters, the custody credential identity key, and the governance ballot domain scope. A production pod refuses to start on the chart's placeholder session secret and on the development master password.

Signing keys sit in one of two places:

- The platform key store, the `local` signer. The platform generates the key and stores it through the selected secret manager. With the `local` secret manager, the key and the password that protects it are inside the same deployment, so this gives no independent custody control.
- A custody provider: DFNS, Fireblocks, Ripple Custody, Utila or a Thales Luna HSM. With Luna, the platform generates each secp256k1 key pair inside the HSM partition over PKCS#11, marked sensitive and non-extractable, and the HSM signs. The provider's own policy, such as an MPC policy or an HSM quorum, can hold a request before it signs.

[Prerequisites](https://docs.settlemint.com/docs/deployment/prerequisites#a-custody-provider-when-signing-leaves-the-platform) lists the credentials each custody provider needs.

## Encryption in transit [#encryption-in-transit]

TLS for browser and API traffic terminates at the edge you configure. The Console Ingress takes a `tls` list with your certificate Secret, a Gateway API `httpRoute` attaches to a Gateway you supply, and an OpenShift Route takes a `tls` block and can request its certificate from cert-manager. The chart sets no certificate and no cipher policy of its own, so TLS versions and ciphers are those of your ingress controller, Gateway or router. [OpenShift](https://docs.settlemint.com/docs/deployment/install/openshift#routing) describes the edge, passthrough and reencrypt options.

Inside the cluster, the services talk over plain HTTP on the Service network, so a service mesh or CNI encryption is your control where you need encryption there. A network policy, on by default, admits to the Platform API only the Console, the Investor portal and the Utila signing agent of the same release, plus any edge namespace you trust.

Datastore TLS is a value you set, and the chart default is off. With the default PgBouncer pooler, the application connects to PgBouncer in plaintext inside the cluster, and the datastore `sslMode` sets the TLS mode from PgBouncer to PostgreSQL. For a private CA, leave `sslMode` empty and give the CA through `pgbouncer.upstreamTls`. Without the pooler, `sslMode` applies to each direct connection, or use the typed `database.tls` with a CA file. Set `tls` for Redis. An object store with a self-signed certificate gets its CA through `s3SslCertSecret`. A custody provider is reached over its own HTTPS API, and a Luna HSM over its client, with mutual TLS when your HSM requires it.

## Encryption at rest [#encryption-at-rest]

The platform encrypts these items with AES-256-GCM before it stores them:

- Secrets in the `local` secret manager, which include platform key store signing keys and custody provider credentials.
- KYC documents in object storage, and the values of KYC templates in the database.
- Credentials of RPC endpoints that an administrator adds at runtime, and the input of a participant import.

The key comes from the encryption master password through PBKDF2 with SHA-256 over 600,000 iterations. The platform refuses a master password shorter than 16 characters or weaker than 128 bits of estimated entropy. A master password rotates in one deploy through the migration Job, as [Values and secrets](https://docs.settlemint.com/docs/deployment/install/values-secrets#encryption-at-rest) describes.

Login authenticator secrets, login backup codes and the private ES256 keys that sign the platform's short-lived JSON Web Tokens are encrypted with XChaCha20-Poly1305 under a key derived from the session signing secret. Those signing keys rotate every 30 days. Sessions themselves are database records behind a cookie signed with HMAC-SHA256.

Login passwords are stored as scrypt hashes and wallet PINs as Argon2id hashes. Login codes sent by email or text message are stored hashed.

Everything else at rest belongs to the stores you operate: disk and volume encryption of PostgreSQL, Redis and object storage, their backups, and the encryption of the external secret manager. Record those controls with the store, because the chart neither sets nor checks them.

## Logging and audit trail [#logging-and-audit-trail]

The audit trail records every state-changing request and selected reads, with the person, the role they held, their organisation, and the outcome. [Audit trail](https://docs.settlemint.com/docs/concepts/records-and-evidence/audit-trail) lists what it covers.

Each organisation's rows form a SHA-256 hash chain. Database triggers refuse to update a row, except that a pending request's outcome is written as a new appended row. They refuse to truncate the table, and refuse to delete a row before its day is anchored. A role that owns the table can still remove the triggers, so the hash chain and its daily on-chain anchor are what reveal a change. A daily job anchors each closed day's chain head on the organisation's default network once it has a deployed system and an active anchor signer, and records each anchor in a table that only accepts new rows. Until then the job retries each day, and that day's rows cannot be deleted. Rows of platform-wide operations, recorded without an organisation, form one more chain. It has no anchor, so the triggers refuse every delete of its rows. The Helm value `global.dalpApp.config.monitoring.auditRetentionYears` takes 5, 7 or 10 years, or `indefinite`, which is the default.

You read the trail in the Console, export it as CSV in the Console or through `GET /api/v2/reporting/trail/export`, and check a date range for tampering through `GET /api/v2/reporting/trail/integrity`. A platform administrator checks the platform chain through `GET /api/v2/reporting/trail/operator/integrity`.

Each service exports traces, metrics and logs over OpenTelemetry (OTLP) to the collector endpoints you set under `telemetry`. Forward them from that collector to your SIEM. [Observability](https://docs.settlemint.com/docs/deployment/observability) lists the keys and defaults.

Two features send data to third parties. The Console assistant and the docs site's Ask AI send questions, with the context they gather, to OpenRouter when an assistant key is set. The exchange-rate refresh calls a public currency API unless you point it at your own source. [Hosting and access](https://docs.settlemint.com/docs/deployment/hosting-and-access#4-a-mirrored-registry) names both.

## Secure development and supply chain [#secure-development-and-supply-chain]

SettleMint builds every release image from source in an automated release build. Each DALP image is published with a provenance attestation in the SLSA format and a software bill of materials in the SPDX format, attached to its registry entry. Neither the records nor the images are signed, so a reviewer compares image digests and reads the records. The Platform API images run compiled binaries, so their bill of materials lists the image's OS packages but not the JavaScript dependencies inside the binary. PgBouncer and the two metrics exporters are third-party images and carry only what their publishers attach.

Source changes are scanned for committed secrets before they merge. Dependencies are pinned to exact versions and image digests, and most updates wait two days after their upstream release. Report a suspected vulnerability to support@settlemint.com. SettleMint publishes no response time, fix time or advisory channel for a report.

[Supply chain and support policy](https://docs.settlemint.com/docs/deployment/supply-chain-and-support) shows how to read the records, how a version maps to one build, which release lines take patches, and how a report becomes a fix.

## Cryptographic agility [#cryptographic-agility]

| Area | Algorithm | Configurable |
| --- | --- | --- |
| On-chain signatures on EVM networks | ECDSA on secp256k1, which an EVM network requires | No. A custody provider changes where the key lives and who approves its use, not the curve. |
| On-chain signatures on Canton | Ed25519, generated by the platform key store | No. |
| Transaction codes | TOTP to RFC 6238, SHA-512, 6 digits, 30 seconds by default | Yes. `auth.walletTwoFactor` sets the hash, from SHA-1 to SHA-3, and the digits, period and secret length. |
| Login authenticator codes | TOTP, SHA-1, 6 digits, 30 seconds | No. |
| Secrets, KYC data and credentials the platform encrypts | AES-256-GCM, key from PBKDF2 with SHA-256 | No. You choose and rotate the master password. |
| Login authenticator secrets, backup codes, token signing keys | XChaCha20-Poly1305 storage, ES256 signatures on JSON Web Tokens | No. You choose the session signing secret. |
| Audit trail chain | SHA-256 | No. |
| TLS to browsers and API clients | Set by your ingress controller, Gateway or router | Yes, at your edge, not in the chart. |

No setting selects a post-quantum algorithm. The signing curve is the network's rule, so a post-quantum signature on chain depends on the network.

## Custody and compliance are separate decisions [#custody-and-compliance-are-separate-decisions]

Compliance decides whether an address, claim or transfer is allowed under the asset's rules. Custody decides whether the signing path releases a signature for an authorised request. Each check passes or fails on its own, so a reviewer traces both.

An organisation picks its custody provider during onboarding, and the choice locks when its first wallet is created. A later switch is refused, because it would orphan the keys already issued. The deployment sets the platform's default signer and which providers are switched on.

Two on-chain roles carry most custody authority. The custodian role covers exceptions for one holder, such as freezing an address or part of a balance, forcing a transfer, or recovering a wallet. The emergency role covers stops that affect every holder, such as pausing the asset. Through the platform, a wallet holding either role still clears authorisation, wallet verification and the signing policy.

Whether one person may hold both compliance configuration authority and custody execution authority is your decision. The platform gives you separate roles, role-pair rules and approval families to enforce the split, as [Segregation of duties and maker-checker](#segregation-of-duties-and-maker-checker) describes. Confirm the split during review.

## A public EVM network makes activity discoverable [#a-public-evm-network-makes-activity-discoverable]

On a public EVM network, treat wallet addresses, calldata, event logs, registry links, claim relationships, settlement timing and contract state as public. The contracts write only the state they need to enforce rules. Identity evidence, screening reports and internal review notes stay in your off-chain systems.

- Token contracts expose their addresses, operations, role changes, mints, transfers, burns, pauses and configuration values. Keep personal data and confidential terms out of names, symbols, metadata and configuration values.
- The identity registry exposes wallet-to-identity links and which claim checks apply.
- Claims and trusted issuers publish claim topics, issuers, signatures, claim lifecycle events, and which issuers are trusted for which topics. Keep raw verification evidence off chain.
- Compliance modules reveal their addresses, parameters and pass-or-fail outcomes through transaction behaviour.
- Transaction history stays on chain as hashes, event logs and block timestamps, so regulated activity can be correlated over time.

## What supports a technical review [#what-supports-a-technical-review]

Four kinds of evidence let you verify a deployed instance yourself. A deployment record lists the contract addresses and parameters you expect. Reading bytecode at those addresses confirms what is deployed. Checking contract wiring and versions after a migration confirms both are correct. Indexed events connect submitted transactions to accepted state changes. Put these into an evidence pack with your change-control and signing records and the deployment choices this page names. The pack feeds a formal smart contract audit and your own approval process.

For a SettleMint-hosted or managed deployment, add two SettleMint sources to the pack: the [SettleMint Trust Centre](https://trust.settlemint.com/), and the [SettleMint status page](https://status.settlemint.com/), which reports platform availability and incident history. This page claims no certification. [Exit and data portability](https://docs.settlemint.com/docs/deployment/exit-and-data-portability) covers where each kind of data lives and what you can export.

## Frequently asked questions [#frequently-asked-questions]

### Can users sign in with SAML or LDAP?

Not directly, because the Console supports OpenID Connect only. Connect a SAML federation, an LDAP directory or Active Directory to an identity provider that issues OIDC tokens, and configure that provider in `auth.oidcProviders`.

### Who can make someone a platform administrator?

For a local account, an existing platform administrator does it on the user's page. For an SSO account, the identity provider claim decides at every sign-in and overwrites a grant made in DALP. Only the first account created locally on a new instance becomes one without such a grant.

### Can a wallet holding an on-chain role act outside the platform?

Yes, on a public EVM network. The contract checks role membership, not the platform session, so a wallet holding a custodian or emergency role can call the contract from any tooling. The platform's authorisation, wallet verification and signing policy cannot limit what that key signs outside the platform.

### Can data written to a public EVM network be removed later?

No. A public chain is append-only, so anything written into names, symbols, metadata, calldata or event logs stays discoverable. A correction writes new state, and the old state remains.


# Single sign-on

Source: https://docs.settlemint.com/docs/deployment/sso
Configure an external OIDC identity provider for the DALP Console, and understand that a complete entry replaces local Console sign-in deployment-wide.

OpenID Connect (OIDC) connects Console sign-in to an external identity provider. One complete provider entry replaces local Console sign-in for the whole deployment, while the Investor portal keeps password sign-in for investors. Verify the provider, administrator claim, and recovery path before rollout. Wallet verification has separate settings and remains a distinct control.

OIDC is the only external sign-in protocol the platform supports. It has no SAML or LDAP connector, so a SAML federation, an LDAP directory or Active Directory connects through an identity provider that issues OIDC tokens.

The Console authenticates through the identity provider or providers you configure under `auth.oidcProviders`. That value lives on the parent chart under `global.dalpApp.config`, not on the `dapp` subchart alone, and both the Console and the Platform API read it. Sign-in works with any OIDC issuer that serves standard discovery and returns the `email` and `name` claims, such as FusionAuth, Okta or Auth0. The identity-provider wallet factor works only with FusionAuth.

## Default: no external provider [#default-no-external-provider]

`auth.oidcProviders` is an empty list by default. With no provider configured, the Console authenticates locally with email and password plus passkeys.

## Adding a provider [#adding-a-provider]

Rolling out one complete entry replaces local Console sign-in for every user on the deployment. Read [A complete entry disables local Console sign-in](#a-complete-entry-disables-local-console-sign-in-for-the-whole-deployment) and the [production rollout checklist](#production-rollout-checklist) first.

Each entry in `auth.oidcProviders` needs an id, a display name, the issuer URL, and a client ID. It also needs a client secret, injected as an environment variable rather than set as a plain value:

```yaml
global:
  dalpApp:
    config:
      auth:
        oidcProviders:
          - id: "fusionauth"
            displayName: "FusionAuth"
            issuer: "https://auth.example.com"
            clientId: "dalp"
            clientSecret: "${OIDC_PROVIDER_CLIENT_SECRET:-}"
            adminClaim: "dalp-admin"
```

Everything except `clientSecret` is plain configuration that you set directly in your values file. `issuer` must be an `https://` URL, except for a loopback host reserved for local testing. Any other `http://` issuer fails config decode when the pod boots, not when the chart installs. A render can succeed while the pod later fails config validation. An upgrade that waits for readiness can then time out. `clientSecret` is the one field you inject from a secret rather than set directly, through the `OIDC_PROVIDER_CLIENT_SECRET` environment variable or your configured secret-manager equivalent. [Values and secrets](https://docs.settlemint.com/docs/deployment/install/values-secrets) shows how that injection reaches the running pod. Set it from a Kubernetes Secret, never as a literal in your values file or in a plain ConfigMap. An unencrypted values file lands the secret in Helm release history and in etcd, readable by anything with read access to Secrets or ConfigMaps in the namespace. Add more entries to the list to offer more than one provider at sign-in.

An entry only counts as a configured provider once `id`, `issuer`, `clientId`, and `clientSecret` all have real values. A partially filled entry parses without an error and changes nothing: local sign-in stays active, and no external sign-in option appears. This is deliberate. It stops a values file mid-edit, or a Secret that has not synced yet, from silently taking down local login.

Set two more fields on purpose rather than leaving their defaults:

- `scopes` requests the token claims the provider returns. When you omit it, the Console requests `openid`, `email`, and `profile`. Setting `scopes` replaces that default list and does not add to it. If you need a role or group claim for `adminClaim`, list `openid`, `email`, and `profile` alongside it, or sign-in fails on the missing email claim the platform relies on as the identity anchor.
- `adminClaim` names the claim, or the array a claim value must appear in, that grants the platform administrator role on sign-in. Leave it unset and no OIDC user ever becomes a platform administrator through this provider, which is the deny-by-default posture you want until you have scoped who at your identity provider can assign it. Anyone who can set that claim's value for a user at the identity-provider side can make that user a platform administrator the next time they sign in, because the role is recomputed on every login. Scope who can assign the claim before you set it, the same way you would scope a platform administrator grant inside DALP itself.

## A complete entry disables local Console sign-in for the whole deployment [#a-complete-entry-disables-local-console-sign-in-for-the-whole-deployment]

[Figure] One complete OIDC entry flips a deployment-wide switch, with no per-user exception. Before any OIDC entry is complete, the Console authenticates locally with email, password, and passkey, and a partially filled entry, missing a field or waiting on a secret that has not synced, parses without error and changes nothing. The moment a release rolls out with one entry holding all four required fields, id, issuer, clientId, and clientSecret, the authentication service treats Console sign-in as OIDC-only across the deployment. It disables the local email and password credential flow at the API layer, rejects passkey sign-in and passkey registration at that same layer, and rejects password change, password reset, email change, and enabling a new login two-factor method as a second, independent check. Two-factor already enrolled can still be turned off, and wallet-signing two-factor is untouched, because neither is part of that second check. The platform refuses a first OIDC sign-in whose email matches a pre-existing local account, rather than adopting that account. Returning users resolve by provider and subject. This applies to every Console user on the deployment the moment the release rolls out: there is no per-user or per-organisation exception, and no in-band fallback for an operator who gets locked out. A partial entry never triggers any of this. The only way back is to redeploy with oidcProviders set back to an empty list, which restores local sign-in immediately. No partial fix exists, because enablement is all-or-nothing. Labels: One value, one deployment-wide switch; Local sign-in active: email, password, passkey; Before: no complete entry; A partial entry parses safely and changes nothing; All four fields set, release rolls out; Local credential sign-in disabled at the API layer; After: OIDC-only, deployment-wide; Passkey sign-in and passkey registration rejected too; Password change, password reset, email change, and enabling; login two-factor rejected as a second, independent check; Already-enrolled two-factor and wallet-signing two-factor stay usable; A provider sign-in that matches a local account's email is refused; No per-user exception. Effective the moment this release rolls out.; Only way back; Redeploy oidcProviders to an empty list; Restores local sign-in immediately, deployment-wide.

What one complete OIDC entry flips for Console sign-in at rollout, and the one way back.

One complete OIDC entry replaces local Console sign-in for every Console user on the deployment, from the moment the release that carries it rolls out. No per-user or per-organisation exception exists, and no in-band fallback exists: an operator who is locked out cannot sign in locally to fix the configuration.

The API enforces these restrictions as well as the Console. Calling a blocked credential flow directly does not bypass the restriction.

A first sign-in through OIDC does not adopt a pre-existing local account that shares the same email address. The platform refuses that sign-in, and the browser returns to the Console sign-in page. Returning users resolve by provider and subject, so only an account whose first sign-in came through the provider can sign in through it. Plan for this before rollout: a Console user who already holds a local account with the same email cannot sign in to the Console at all, because local sign-in is off and the provider sign-in is refused.

A platform administrator can delete that local account under "Platform admin", "Platform users" only when nothing refuses the deletion: the account must not be an organisation's only owner or a wallet checker, must hold no tokens and must have no on-chain identity bound to it. After the deletion, the next provider sign-in creates a new account without the old account's memberships.

SSO centralises authentication at your identity provider, which gives you one place to enforce password policy and MFA and to stop new sign-ins. A Console session already open stays valid until it expires. The identity provider also becomes a single point of failure for reaching the Console.

### Recovering from a lockout [#recovering-from-a-lockout]

If a bad OIDC configuration locks every user out, redeploy with `oidcProviders` set to an empty list. Local email and password sign-in returns when the redeploy completes. Accounts first created through the provider have no local password, and because the instance already has accounts, a new local sign-up does not become a platform administrator. When no account with a password holds that role, [Restore the platform administrator role](https://docs.settlemint.com/docs/deployment/security-compliance-posture#restore-the-platform-administrator-role) gives it to one. To restore external sign-in instead, fix the provider configuration in a non-production environment, verify a full sign-in round trip there, then redeploy it to production.

### What stays independent [#what-stays-independent]

Three things do not follow the all-or-nothing rule:

- OIDC-based wallet verification is a separate capability from OIDC sign-in. It uses its own fields, `apiKey` and `applicationId`, on the same provider entry, and it does not gate whether local sign-in stays active.
  - It works only for an account that has signed in through that provider, because the platform finds the account at the provider by the identity linked at sign-in, never by email.
  - Without `issuer`, `apiKey` and `applicationId`, the provider's authenticator is not offered as a wallet factor.
  - The platform checks the code through the provider's user and two-factor APIs at the issuer URL (`/api/user/{id}`, `/api/two-factor/start` and `/api/two-factor/login`, the FusionAuth API), with `apiKey` as the credential. A provider that does not serve these routes cannot act as a wallet factor, even when its OIDC sign-in works.
  - The PIN, recovery codes and wallet authenticator keep working under single sign-on. [Wallet verification](https://docs.settlemint.com/docs/console/my-account/security#wallet-verification) describes the methods.
- A user's existing two-factor can still be turned off on the Console. Only enrolling a new login two-factor method is blocked there, alongside password and email changes. Wallet-signing two-factor is untouched regardless.
- Investor portal sign-in keeps its local methods, as the next section describes.

### Investor portal sign-in under single sign-on [#investor-portal-sign-in-under-single-sign-on]

The identity provider replaces sign-in on the Console only. The Investor portal keeps email and password sign-in, passkeys, password reset and two-factor enrolment for investors, including the email and text message [sign-in codes](https://docs.settlemint.com/docs/getting-started/sign-in-codes) their organisations allow. SSO also closes self sign-up on the Investor portal, so nobody can create a new account there. An account that holds the admin or owner role on the platform, or in an organisation that is not archived, cannot start an Investor portal session. The portal refuses it with `403 Forbidden` and `ADMINISTRATION_NEEDS_CONSOLE_SIGN_IN`, and the message `This account administers the platform or an organization, so it signs in to the Console through the identity provider.`

### Role writes that need a Console session [#role-writes-that-need-a-console-session]

The Platform API checks the app that issued a session before it accepts these writes, even when the caller's wallet holds the on-chain role:

- system, asset, offering, venue and custody gateway role grants and revokes
- changes to an asset's supply delegate, hold reserver, authorised converter and burner capability
- fixed-yield and offering fund withdrawals
- undeliverable-purchase refunds

These writes require a Console-issued session. A Portal-issued session, an anonymous session or one with no recorded issuing app answers `403 Forbidden` with `WALLET_ROLE_ADMINISTRATION_NEEDS_CONSOLE_SIGN_IN` ([DALP-200384](https://docs.settlemint.com/docs/api-reference/errors)), and starts no write. On the v1 API the same refusal answers `403 Forbidden` with DALP-9485, whose message and fix also say to sign in to the Console. Sign in to the Console and retry. The check applies without an identity provider too, and sessions issued before the issuing app was recorded are refused until the user signs in to the Console again. This check does not end a Console session when access at the identity provider changes, revoke an on-chain role or disable an existing API key. API keys keep each route's existing access policy, and investors can still buy, claim and transfer their own holdings through the portal.

## Production rollout checklist [#production-rollout-checklist]

Before you roll a complete OIDC entry into a production instance:

- Stage and verify the full sign-in round trip in a non-production environment first. Include a user who should land as a platform administrator and one who should land as an ordinary member.
- Confirm your identity provider enforces multi-factor authentication for Console users. `auth.enforce2fa` stops applying to an account whose only sign-in is the identity provider.
- Confirm `clientSecret`, and `apiKey` if you also configure OIDC wallet verification, come from a Kubernetes Secret, never a values literal.
- Confirm `adminClaim` is set only if you intend OIDC users to reach the platform administrator role, and confirm who at your identity provider can assign that claim's value.
- Register the Console's callback URL with your identity provider before rollout: `/api/auth/callback/<provider-id>`, using the provider's `id` field and matching the exact host the Console serves from. A multi-host deployment needs the callback registered for each host.
- Confirm that whoever holds deploy access understands [Recovering from a lockout](#recovering-from-a-lockout) before you roll the entry out.

## Failure modes [#failure-modes]

| Symptom | Likely cause | Fix |
| --- | --- | --- |
| Everyone is locked out after enabling a provider | Any complete entry disables local Console sign-in deployment-wide, by design. | Redeploy with `oidcProviders: []`, fix the configuration, verify in staging, re-enable. |
| `helm upgrade` reports success, but the Platform API pods never become ready | `issuer` is not an `https://` URL (and is not the loopback exception reserved for local testing). Config decode runs at pod boot, not during the Helm install. | Set `issuer` to the identity provider's `https://` URL and redeploy. |
| Sign-in redirects fail with a callback or redirect-URI error | The callback URL from the [production rollout checklist](#production-rollout-checklist) is not registered with the identity provider, or does not exactly match the host the Console served the request from. | Register that callback URL for every host the Console is reachable on. |
| Sign-in fails or lands with no name | The token lacks `name`, or `email`, or returns `email_verified: false`. An explicit `false` is rejected, and an absent claim is accepted. | Confirm the scopes return a populated `name` claim and a verified email. Some providers need `profile` added. |
| A user returns to the Console sign-in page after signing in at the identity provider | The email the provider returns already belongs to a local account that never signed in through this provider. The platform refuses to link the two. | A platform administrator deletes the local account under "Platform admin", "Platform users", when the platform allows it (no sole ownership, tokens or bound on-chain identity), then the user signs in through the provider again. The new account starts without the old account's memberships. |
| A user signs in through OIDC as an ordinary member when they should be a platform administrator | The claim named by `adminClaim` is missing from that user's identity token, or its shape does not match: a direct boolean, or the claim's value inside a `roles` or `groups` array. | Confirm the provider populates that claim in the token it returns, not only in an internal profile. The fix takes effect on the user's next sign-in. |

## Related authentication settings [#related-authentication-settings]

These sit alongside `oidcProviders` in the same `auth` block. `restrictOrgCreationToAdmin`, `membershipLimit`, and `walletTwoFactor` apply the same way whether or not you configure OIDC. `enforce2fa` does not: it stops applying to an account whose only sign-in is the identity provider, because the provider then owns login authentication. An account that holds a password or a passkey, such as an investor on the Investor portal, still needs two-factor.

| Setting | Purpose |
| --- | --- |
| `enforce2fa` | Requires two-factor authentication for accounts that sign in with a password or a passkey. Stops applying to accounts whose only sign-in is the identity provider: an operator who kept `enforce2fa: true` for Console users needs an equivalent MFA policy at the identity provider before rollout, because DALP no longer enforces one for them. |
| `restrictOrgCreationToAdmin` | Restricts who can create a new organisation on the instance. |
| `membershipLimit` | Caps members per organisation (default 10,000). |
| `walletTwoFactor` | Configures wallet TOTP (RFC 6238): algorithm, digits, period, secret length, issuer string, and used-token expiration. |

## See also [#see-also]

- [Values and secrets](https://docs.settlemint.com/docs/deployment/install/values-secrets) for how a Kubernetes Secret reaches `clientSecret` and `apiKey` without touching the values file.
- [Security](https://docs.settlemint.com/docs/console/my-account/security) for the sign-in code, transaction PIN and transaction code from a signed-in user's own account settings.
- [Install the Helm charts](https://docs.settlemint.com/docs/deployment/install/helm-charts) for the redeploy command itself.

## Frequently asked questions [#frequently-asked-questions]

### If I grant a user the platform administrator role inside DALP, does that survive after they start signing in through OIDC?

No. `adminClaim` is re-evaluated on every OIDC login, and an absent or false claim resolves to an ordinary member regardless of any role granted inside DALP beforehand. In an OIDC-only deployment, the identity provider's claim is the source of truth for the platform administrator role, and an out-of-band grant is overwritten the next time that user signs in.


# Supply chain and support policy

Source: https://docs.settlemint.com/docs/deployment/supply-chain-and-support
How a release image is built and verified, how a version maps to one build, which release lines take patches, and how a report becomes a fix.

Every DALP release publishes container images and a Helm chart, built by SettleMint's automated release build. A DALP Instance runs from those images, and each image carries a SLSA provenance record and an SPDX bill of materials in the registry you pull it from. Neither record is signed. At most two release lines take patches at a time, and a suspected vulnerability is reported to support@settlemint.com.

## What every image carries [#what-every-image-carries]

The DALP images come from `ghcr.io`, in a repository per component, and the chart comes from `pkg.distribution.settlemint.com`. A default install also pulls third-party images. PgBouncer, its metrics exporter and the `kubectl` helper come from `docker.io`, the PostgreSQL exporter from `quay.io`, and the `pause` placeholder from `registry.k8s.io`. Allow all five hosts where egress is restricted, or mirror every image and set `global.imageRegistry`. The records on this page are attached to the DALP images only.

Each DALP image is published with two records attached to it.

The first is a provenance attestation in the SLSA format: a record of the build that names the commit it was built from, its build definition, and the base images it resolved. The second is a software bill of materials in the SPDX format, listing the packages the image's final stage installs and their licences. A component that ships as a compiled binary keeps its JavaScript dependencies inside that binary, so no package listing enumerates them. Neither record is signed, so a reviewer reads what the build did and cannot check a signature against it. [Third-party components and licences](https://docs.settlemint.com/docs/deployment/third-party-components) lists the GPL-3.0 and AGPL-3.0 services and contract code that a deployment includes beside DALP's own images.

Read either record from any machine that holds credentials for the image registry. Those are the same credentials you gave the chart for its pull secrets, which [Prerequisites](https://docs.settlemint.com/docs/deployment/prerequisites) covers:

```sh
docker buildx imagetools inspect ghcr.io/settlemint/dalp-dapi:<version> --format '{{json .Provenance}}'
docker buildx imagetools inspect ghcr.io/settlemint/dalp-dapi:<version> --format '{{json .SBOM}}'
```

Substitute the reference the chart renders for the container you are checking. The first command prints the provenance document, the second the bill of materials. Check that the subject digest in the provenance document is the digest of the platform image it describes. Both records are part of the image's registry entry, not its contents, so a mirror that copies the whole reference keeps them and a copy taken from the platform image alone carries neither.

## How a version maps to one build [#how-a-version-maps-to-one-build]

A release builds each image once per set of inputs and names that build after its inputs. The release hashes the image build definition, the files the build reads, the digests of the base images, the dependency lockfile, the build configuration, and the hashes of the steps that produce the image. Those inputs produce a source tag of the form `source-<hash>`, the same tag on every run when nothing changed, and a new tag when anything did. Every image in a release is built for Linux on x86-64.

[Figure] A version tag is created from the same digest. The build inputs are hashed into a source tag. The image is built once with its provenance and bill of materials attached, and that build sits under the source tag. The version tags are then created from the same manifest digest, so no rebuild stands between the two. The Helm chart ships at the same version and selects those image tags through its app version. A later release run finds the existing source tag and creates only the new version tags from it. Labels: The version tag comes from the same digest; One commit, one build, one digest; 1. The build inputs are hashed into a source tag; Same inputs, same tag, on every run; 2. The image is built once; Provenance and a bill of materials attach to it; 3. The source tag holds that build; A digest that changes only when an input changes; 4. The version tags point at the same digest; No rebuild stands between the two tags; 5. The chart ships at that version; Its app version selects the image tags it renders.

A release hashes its inputs into a source tag, builds once under it, and creates the version tags from the same
digest.

The version tag is created from the digest the source tag holds. A later release run finds the source tag already present, creates the new version tags from that build, and starts no second build, so a version tag and the source tag it came from always name the same image.

The chart carries the number too. A release sets the chart version and the chart's app version to the same version, and the image tags it renders follow that app version, so the images and the chart come from one commit. Pin the chart version and leave a component's image tag empty, and that chart version selects the image builds released with it. A tag pinned to an older build than the chart is the combination that breaks, because the chart's probes and settings belong to the build it ships with.

The chart carries no attestation of its own, so its version is what you check, together with the packaged chart and the values it renders, which `helm show chart` and `helm show values` print before an upgrade. The release does not overwrite a published chart version: it refuses to push a chart version that already exists. The chart version you pin therefore names one chart, and the version tags created for it name one image per component.

## How a version is numbered [#how-a-version-is-numbered]

Versions follow major.minor.patch. The first release of a minor version, `X.Y.0`, opens a release line, and each patch release of `X.Y` ships on that line. A patch release keeps the minor version you run and carries the fix, so the version number you pin tells you which line a release belongs to.

The [changelog](https://docs.settlemint.com/docs/changelog) records what each version carries. Patch releases do not get entries of their own. The changes a patch carries are listed in the entry of the next minor release.

## Which release lines take patches [#which-release-lines-take-patches]

At most two release lines are live at a time: the current generally available line and the one before it. The first release of a new minor version opens its line, keeps the line before it, and retires the line before that. A retired line takes no further patches.

A line takes patches from its `X.Y.0` release until the second newer minor version ships, so the support window is counted in release lines, not in dates. No minimum calendar period is stated. A fix that affects a live line ships as a patch release on that line and reaches later releases too. When the line you run retires, [Upgrades and migrations](https://docs.settlemint.com/docs/deployment/upgrades-migrations) covers the move to a live one.

## What stays compatible across an upgrade [#what-stays-compatible-across-an-upgrade]

The API contract you integrate against keeps working on the terms its version carries. A stable version never loses an operation and never changes one incompatibly inside itself. A breaking change ships only as a new version beside the one you call, and an operation or a whole version is removed only after a deprecation announcement that gives at least 90 days' notice. [API versioning and deprecation](https://docs.settlemint.com/docs/api-reference/guides/versioning-and-deprecation) names which versions are stable and holds the headers, the contract fields, and the notice window.

On the deployment side, one Helm upgrade moves every component to the new version together, and on the default migration hook the database migration runs before the new pods start. The API promise does not cover the database schema or the chart's values. [Upgrades and migrations](https://docs.settlemint.com/docs/deployment/upgrades-migrations) covers the hook choice, the migration gate, what a failed migration leaves behind for you to inspect, and the checks to run before an upgrade.

## How a vulnerability report reaches a fix [#how-a-vulnerability-report-reaches-a-fix]

Report a suspected vulnerability in the platform to support@settlemint.com. It is the only published reporting route, and SettleMint publishes no response time, fix time or advisory channel.

A fix for a reported vulnerability follows the route any production fix takes. It ships as a patch release on the affected release line and reaches later releases too. A patch release that carries a fix changes the image digest, so a digest comparison confirms whether the build you run is the published build of the version that carries the fix.

## Frequently asked questions [#frequently-asked-questions]

### How do you confirm the image on your cluster is the published one?

Read the digest the cluster resolved and compare it with the digest the registry publishes for that version. Each running container reports the image it pulled:

```sh
kubectl get pods -o jsonpath='{range .items[*]}{.metadata.name}{"\t"}{.status.containerStatuses[*].imageID}{"\n"}{end}'
docker buildx imagetools inspect <image-reference>
```

The second command prints the reference, the digest of the index the tag names, and one manifest per platform the index carries. Take the `linux/amd64` entry, which is the manifest a node runs, and compare it with the digest in the container's image ID. Equal digests mean the node runs the published build of that version. A difference means the copy came from another build, which happens when a build ran again from changed inputs, when a mirror republished the image under its own digest, or when the reference names an older version.

### Which value pins the image a chart renders?

Each component carries its own image block, so the value is component-scoped, such as `dapi.image.tag` or `dapp.image.tag` in the values you pass the DALP chart. There is no single top-level image tag over every component. A release sets the chart version and the chart's app version to the same number, and each component's tag defaults to that app version, so pinning the chart version and leaving the image tags empty follows the release.


# Third-party components

Source: https://docs.settlemint.com/docs/deployment/third-party-components
The GPL-3.0 and AGPL-3.0 services the Helm charts deploy and the GPL-3.0 contract code in DALP: what each does, how to turn it off and where its source is.

A DALP deployment runs SettleMint's own software next to services and contract code that other projects publish under copyleft licences. This page lists the ones under GPL-3.0 or AGPL-3.0, which are Grafana, Loki, Tempo and Blockscout in the Helm charts, and OnChainID and the ERC-4337 EntryPoint in the smart contracts. For each it states what the component does in a DALP Instance, how it is deployed, whether you can turn it off, and where its source is published. The page records facts and draws no legal conclusion. [Supply chain and support policy](https://docs.settlemint.com/docs/deployment/supply-chain-and-support) covers how DALP's own images are built.

## Services the Helm charts deploy [#services-the-helm-charts-deploy]

Four open source projects run as separate services in the cluster. The `observability` chart deploys Grafana, Loki and Tempo, and the `dalp` chart deploys Blockscout. The table gives the version each chart deploys on the 3.1 release line, its licence, and the flag that controls it. The frontend flag takes effect only while `blockscout.enabled` is true.

| Service | Licence | Version deployed | Chart | Flag | Default |
| --- | --- | --- | --- | --- | --- |
| Grafana | AGPL-3.0 | 13.3.0, from Helm chart 14.4.0 | `observability` | `grafana.enabled` | On |
| Loki | AGPL-3.0 | 3.7.9, from Helm chart 21.0.0 | `observability` | `loki.enabled` | Off |
| Tempo | AGPL-3.0 | 3.1.1, from Helm chart 3.2.1 | `observability` | `tempo.enabled` | On |
| Blockscout backend | GPL-3.0 | 9.0.2 | `dalp` | `blockscout.enabled` | Off |
| Blockscout frontend | GPL-3.0 | v2.3.5 | `dalp` | `blockscout.frontend.enabled` | On |

Grafana Labs publishes Grafana, Loki and Tempo, and the `observability` chart pulls their Helm charts from the grafana-community chart repository. The `observability` chart sets no image tag for them, so each service runs the version its Helm chart names as its application version. Blockscout is published by the Blockscout project, and the `dalp` chart sets the image tags itself.

The same facts hold for all five services:

- **Unmodified upstream image.** The charts pull the image the upstream project publishes: `grafana/grafana`, `grafana/loki`, `grafana/tempo` and `grafana/tempo-query` from the Grafana Labs image repositories, and `blockscout/blockscout` and `blockscout/frontend` from `ghcr.io`. The DALP source tree holds no fork, patch, rebuild or custom Dockerfile for any of them. DALP supplies configuration only, through chart values, environment variables and mounted configuration files.
- **Separate service.** Each one runs in its own pods and is reached over the network by HTTP or OTLP, the OpenTelemetry Protocol. Grafana and Blockscout also serve their own web interfaces.
- **No linking or embedding.** No DALP package imports, bundles or links code from these projects. The Platform API, the Console and the Investor portal reach them only through the network addresses the charts configure.
- **Optional.** None of them is needed to issue or operate assets. The platform exports telemetry over OTLP whether or not a receiver exists, and it does not call Blockscout.

### Grafana [#grafana]

Grafana shows the platform's metrics, logs and traces. The `observability` chart provisions its datasources for the three stores and the DALP dashboards, and it can provision alert rules, which are opt-in. Set `grafana.enabled: false` to leave it out. The dashboards and datasources ship inside the chart, so a Grafana you already run needs its own provisioning of them. The [observability stack](https://docs.settlemint.com/docs/deployment/install/observability-stack) page covers the full install.

Source: [github.com/grafana/grafana](https://github.com/grafana/grafana).

### Loki [#loki]

Loki is an optional log store. The `observability` chart sends logs to VictoriaLogs by default, so Loki is off. To use Loki instead, set `loki.enabled: true` and `global.observability.logsSink: loki`. The collector then writes logs to Loki's HTTP endpoints. Leave both unset and no Loki pod exists.

Source: [github.com/grafana/loki](https://github.com/grafana/loki).

### Tempo [#tempo]

Tempo stores distributed traces. The collector receives traces from the platform over OTLP and forwards them to Tempo, which keeps them for 168 hours, and Grafana reads them back through its Tempo datasource. The chart also references the `grafana/tempo-query` image from the same project. Set `tempo.enabled: false` to leave Tempo out. To keep a trace store you already run, repoint the collector's trace endpoint and the Grafana datasource at it, as the [observability stack](https://docs.settlemint.com/docs/deployment/install/observability-stack) page describes.

Source: [github.com/grafana/tempo](https://github.com/grafana/tempo).

### Blockscout [#blockscout]

Blockscout is a block explorer for the ledger network the deployment runs on. The backend indexes the chain through the ledger node's JSON-RPC endpoint into its own `blockscout` database on the PostgreSQL server you supply, and the frontend serves the explorer pages. The Console builds its links to the explorer from the `explorer.url` application setting. A network definition can name any other explorer, so Blockscout is one choice among several.

The chart leaves Blockscout off. Set `blockscout.enabled: true` to deploy it, and `blockscout.frontend.enabled: false` to run the backend without the frontend. The chart configures the backend and frontend containers through environment variables. Its init containers wait for the database with a small SettleMint-built utility image and do not alter the Blockscout image.

Both pinned versions were published under GPL-3.0: the `LICENSE` file at backend tag 9.0.2, published on 14 August 2025, and at frontend tag v2.3.5, published on 14 October 2025, holds the GPL-3.0 text. The default branch of both repositories now holds a different licence file, the Blockscout Software Licence, effective 22 April 2026, which states that it does not apply to earlier versions of the software. Read the `LICENSE` file at the tag you move to before you change `blockscout.blockscout.image.tag` or `blockscout.frontend.image.tag`.

Source: [github.com/blockscout/blockscout](https://github.com/blockscout/blockscout) and [github.com/blockscout/frontend](https://github.com/blockscout/frontend).

### Check what runs in your cluster [#check-what-runs-in-your-cluster]

List the distinct images running in the cluster and pick out these projects:

```sh
kubectl get pods --all-namespaces -o jsonpath='{range .items[*]}{.spec.containers[*].image}{"\n"}{end}' \
  | tr ' ' '\n' | sort -u | grep -E 'grafana/|blockscout/'
```

A cluster with the default values lists Grafana and Tempo images and no Blockscout or Loki image.

## Contracts [#contracts]

Every Solidity file in the DALP contract set names its licence in an `SPDX-License-Identifier` line at the top of the file. SettleMint's contracts are under the SettleMint commercial licence, identified as `LicenseRef-SettleMint-Commercial`. The exceptions are the GPL-3.0 components below, which come from or build on OnChainID and the eth-infinitism ERC-4337 EntryPoint, and a few files that carry the licence of the work they adapt or implement. DALP deploys every contract through Hardhat Ignition modules. [EVM contract set](https://docs.settlemint.com/docs/platform/evm-contract-set) describes the contract layers.

### GPL-3.0 components [#gpl-30-components]

Three components carry GPL-3.0:

- **Key and claim management.** The ERC-734 key management and ERC-735 claim management base contracts are derived from the `Identity` contract of OnChainID, and each file carries an attribution line to the upstream project.
- **Identity implementations.** The wallet identity implementation, in three versions, and the contract identity implementation, in two versions, inherit those base contracts.
- **Local ERC-4337 EntryPoint.** Two wrapper contracts around the eth-infinitism EntryPoint, described below.

### OnChainID [#onchainid]

OnChainID is the open standard for on-chain identities that hold keys and claims. DALP's contracts depend on the package `@onchain-id/solidity` 2.2.1, published under GPL-3.0 by the OnChainID project at [github.com/onchain-id/solidity](https://github.com/onchain-id/solidity). DALP uses four interfaces from it: `IIdentity`, `IERC734`, `IERC735` and `IClaimIssuer`. They define an on-chain identity, its key management, its claim management and the check that a claim issuer runs on a claim. DALP uses nothing else from the package.

The package declares a narrower Solidity pragma than the compiler DALP builds with, so DALP applies a patch to it. The patch makes 18 pragma widenings and changes nothing else. The key and claim management base contracts and the identity implementations are the DALP files derived from or built on that package, and they keep the GPL-3.0 licence. The rest of the identity contracts, among them the identity factories and proxies, are SettleMint code under the commercial licence.

### ERC-4337 EntryPoint [#erc-4337-entrypoint]

ERC-4337 is the account abstraction standard. Its EntryPoint contract validates and executes user operations for smart accounts. DALP uses the eth-infinitism implementation from the package `@account-abstraction/contracts` 0.9.0-rc.1, published at [github.com/eth-infinitism/account-abstraction](https://github.com/eth-infinitism/account-abstraction). The `EntryPoint` and `EntryPointSimulations` source files in that package carry GPL-3.0, and other files in the package carry MIT.

Two DALP contracts wrap these files without changing them. Each is an empty subclass of the upstream contract, and each carries a GPL-3.0 identifier:

- **The EntryPoint wrapper** exists so that Hardhat produces a deployable artifact for the upstream EntryPoint. Ignition deploys it when the canonical ERC-4337 EntryPoint is absent from the target chain, which Ignition detects by reading the code at the canonical address. That is the usual case on local and private chains.
- **The EntryPoint simulations wrapper** exists to produce the simulations bytecode. DALP never deploys it. The execution service reads its ABI and calls it through `eth_call` with a state override that places the simulations code at the EntryPoint address, which is how it estimates gas and validates user operations before submission.

On a chain where the canonical EntryPoint at `0x433709009B8330FDa32311DF1C2AFA402eD8D009` already has code, as on the public networks that carry it, Ignition deploys no EntryPoint. It deploys `EntryPointReference` instead, a thin forwarder that points DALP at the canonical contract. `EntryPointReference` is SettleMint code under the commercial licence, and it blocks `withdrawTo` and the stake management calls `addStake`, `unlockStake` and `withdrawStake`, because the canonical EntryPoint keys deposits and stake by the calling address.

### Files under other licences [#files-under-other-licences]

A few files carry the licence of the work they adapt or implement:

- **MIT.** The ERC-7579 validator, executor and multisig modules and the paymaster base contract are adapted from OpenZeppelin Community Contracts. `Multicall3` is vendored from the Multicall3 project. A small interface for resolving a paymaster's deposit EntryPoint is SettleMint's own and also carries MIT.
- **CC0-1.0.** The six ERC-3643 interface files.

The identifier in the first line of each file is the record for that file.


# Topologies

Source: https://docs.settlemint.com/docs/deployment/topologies
See what the DALP Helm chart deploys, the replicas each component starts with, how each Platform API role scales, and how PgBouncer sits in front of PostgreSQL.

A `dalp` Helm release runs the Platform API as four roles in six Kubernetes Deployments that you size separately. The `api` role runs a current v2 fleet and a frozen v1 fleet, the `indexer` role runs serving and rebuild pods, and the `runner` and `scheduler` roles run one Deployment each. Every role reaches a PostgreSQL database through a connection pooler. Use this page to size a deployment or check its high availability: how many replicas each component starts with, how far each scales, what a failure of each costs, and what extra replicas cost at the pooler and the database. For a first install, see [Prerequisites](https://docs.settlemint.com/docs/deployment/prerequisites) and [Helm charts](https://docs.settlemint.com/docs/deployment/install/helm-charts). For backup and restore, and for who owns recovery, see [Backup and disaster recovery](https://docs.settlemint.com/docs/deployment/backup-recovery).

[Figure] One Platform API release, three of its four roles, each sized on its own. Every DALP Helm release deploys the Platform API as role Deployments that are sized independently of each other, side by side, not as a pipeline. The api role serves HTTP traffic and scales from 2 to 24 replicas at 50 per cent average CPU. The runner role executes durable workflow shards and scales from 2 to 12 replicas at 75 per cent average CPU. The indexer role indexes the configured networks and runs a fixed two replicas. Exactly one live owner pod holds a network's ingestion, so the second replica buys failover rather than faster indexing for one network. A scheduler role, a frozen v1 api fleet and a rebuild pool of indexer pods run beside them and are listed in the table below the figure. Arrows lead down from all three roles to PgBouncer, which runs two replicas in transaction pooling mode with per-process pool limits, so adding a platform pod adds cheap client sockets rather than PostgreSQL server connections. A final arrow leads from PgBouncer down to PostgreSQL, where the pgbouncer chart's values price the aggregate pool peak against the server's max_connections ceiling. Labels: The api, runner and indexer roles are sized separately; One release, separate roles; api; Serves HTTP traffic; 2 to 24 replicas; at 50% average CPU; runner; Runs workflow shards; 2 to 12 replicas; at 75% average CPU; indexer; Indexes the networks; 2 replicas, fixed; One live owner per network; The spare buys failover; PgBouncer, transaction pooling; Two replicas, per-process pool limits; An extra api pod adds client sockets, not server connections; PostgreSQL; The pgbouncer chart prices the aggregate pool peak against max_connections.

One `dalp` release runs four Platform API roles, three of them drawn, and every role reaches PostgreSQL through PgBouncer.

## What deploys [#what-deploys]

The `dalp` Helm chart is the umbrella you deploy for one DALP Instance, one copy of the platform's own workloads, running in the cluster you choose and connected to the ledger networks you approve. The datastores, ingress, ledger RPC endpoints and SMTP relay are yours. It composes conditionally enabled subcharts. Five are on by default: `dapi` runs the Platform API, `dapp` the Console, `docs` this documentation site, `pgbouncer` the PostgreSQL connection pooler, and `postgres-exporter` the database metrics exporter. Optional components are off by default, including `blockscout`, a block explorer for EVM networks, and `investor-portal`, the Investor portal, which `investorPortal.enabled` switches on. Set `docs.enabled: false` to leave the documentation site out.

The `dalp` chart deploys no PostgreSQL, Redis or object storage for the platform. You supply those services and point `global.datastores` at them, and your providers carry their backup and failover. Ingress is yours as well.

The `dalp` chart owns what Velero backs up: its `backup` block renders the storage location and schedule. The chart never deploys a Velero server.

| Subchart | On by default |
| --- | --- |
| `dapi`, the Platform API | Yes |
| `dapp`, the Console | Yes |
| `docs`, this documentation site | Yes |
| `pgbouncer` | Yes |
| `postgres-exporter` | Yes |
| `blockscout` | No |
| `investor-portal` | No |

Every `dalp` service reads its configuration from the chart values, with your own values overlay on top. Confirm the rendered ConfigMaps and Secrets contain the values your deployment requires.

## High availability by component [#high-availability-by-component]

The chart's defaults start the current API, the runner, the serving indexer, the Console and the connection pooler at two replicas. Each has a disruption budget that keeps one available during a voluntary disruption such as a node drain. The frozen v1 API and the scheduler start at one replica with a budget of zero, so a node drain is never refused. These numbers are a starting footprint. Size them against your own load and your own availability objective. [Prerequisites](https://docs.settlemint.com/docs/deployment/prerequisites#resource-sizing-starts-from-the-chart-defaults) lists the CPU and memory each pod requests.

| Component | What it does | Default replicas | Availability defaults |
| --- | --- | --- | --- |
| `api`, v2 fleet | Serves Platform API requests for every path except `/api/v1` | 2 to 24 at 50% average CPU, scale-down waits 300 seconds | A PodDisruptionBudget keeps 1 available. Topology spread constraints prefer to place pods in different zones and on different nodes |
| `api`, frozen v1 fleet | Serves the frozen `/api/v1` contract for integrations that have not moved | 1 to 4 at 50% average CPU | A PodDisruptionBudget keeps 0 available, so a node drain is never refused and can briefly take the only v1 pod out of service |
| `runner` | Executes the durable workflow engine and owns the workflow shard groups | 2 to 12 at 75% average CPU, scale-in moves one pod at a time | A PodDisruptionBudget keeps 1 available. The HTTP Service never selects runner pods |
| `indexer`, serving | Indexes the configured networks | 2, fixed | A PodDisruptionBudget keeps 1 available. Rollouts replace one pod at a time with no surge, and a replacement must stay Ready 90 seconds before the wave moves on |
| `indexer`, rebuild | Writes a reindex build while one exists, and idles otherwise | 2, fixed | No PodDisruptionBudget: a drained rebuild pod costs build time, not serving |
| `scheduler` | Owns the scheduler shard group and runs the fleet-wide singleton polls | 1, fixed | A PodDisruptionBudget keeps 0 available. While the pod is away the singleton polls pause, and the replacement pod resumes them when it acquires the shard lease |
| `dapp`, the Console | Serves the Console web app | 2 to 30 at 80% average CPU | A PodDisruptionBudget keeps 1 available, with soft anti-affinity and zone spread |
| `pgbouncer` | Pools every platform connection to PostgreSQL | 2, fixed | A PodDisruptionBudget keeps 1 available. Required anti-affinity places the replicas on different nodes, so a cluster with one node cannot schedule the second |

Topology spread constraints apply to every Platform API role, not only the v2 fleet. The documentation site and the optional Investor portal each autoscale from 2 to 5 replicas, and the optional block explorer frontend from 1 to 5.

The indexer floor of two is deliberate. A single indexer stops all indexing for its whole boot window on every restart, and a disruption budget of one against one replica allows zero voluntary disruptions, so a node drain is refused outright. More serving replicas never add throughput for a single network: live indexing keeps exactly one owner pod per network, held by a database lease. Each replica holds the networks it claimed, and the replica count buys failover and a spread of networks across pods. If an owner fails, a surviving replica claims its networks and resumes from the last committed position.

Alerting in the observability chart is off by default and turns on with `grafana.sidecar.alerts.enabled`. Once it is on, its `ChainUnowned` alert fires when a network has had no live owner for five minutes.

Every Platform API pod is stateless. Persistence lives in PostgreSQL and object storage, with Redis as a cache and change-notification tier, not in the pod. The Console (`dapp`) is stateless too. A failed pod loses no data, so recovering these components is a reschedule. While the single scheduler pod is away, its singleton polls pause.

The chart provides no high availability for the stateful layer. PostgreSQL, Redis and object storage are services you supply (see [Stateful dependencies](#stateful-dependencies)), so you take their replication and failover from your provider. The platform does not orchestrate failover of a database, and its recovery point after a database failover tracks the provider's replication lag. [Backup and disaster recovery](https://docs.settlemint.com/docs/deployment/backup-recovery#what-sets-your-rto-and-rpo) lists who sets which objective.

Durable workflow execution shards work across every `runner` replica. The shard count (`durable.sharding.shardsPerGroup`, default 64) is a modulus every runner and client hashes entities through, which makes it cluster-wide configuration: two participants that disagree about it address the same work to different shards. Change it everywhere at once, as one coordinated configuration change, never per pod.

### Ledger endpoints [#ledger-endpoints]

Each network's endpoint pool is a failover group of its own. With two or more endpoints in a pool, the indexer and the Platform API stop sending calls to an endpoint that lags behind the chain or fails, and keep serving from another one. A platform administrator extends that pool in the Console under [Networks](https://docs.settlemint.com/docs/console/platform-admin/networks), and a change applies without a restart. The transaction engine, which signs and broadcasts, uses only the endpoints listed in `rpc.urls` in the deployment values, as [Networks](https://docs.settlemint.com/docs/deployment/networks) describes. [Backup and disaster recovery](https://docs.settlemint.com/docs/deployment/backup-recovery#failing-over) describes how the platform scores and switches endpoints. A network with one endpoint has no failover, so give each production network at least two in `rpc.urls`, from providers that fail independently.

## How queries reach PostgreSQL [#how-queries-reach-postgresql]

Application queries reach PostgreSQL through PgBouncer, not directly. The umbrella chart enables the `pgbouncer` subchart by default and renders every service's database URL at the PgBouncer Service, so routing is the chart's decision end to end. No service opts in or out on its own. The database migration Job keeps a direct connection, so its schema changes run outside the pooler's transaction-mode constraints. The PostgreSQL exporter and the optional Blockscout workload also connect directly.

PgBouncer runs in transaction pooling mode, and the chart rejects every other mode. Two PgBouncer replicas each run one process, and every limit is per process: a process accepts up to 3000 client sockets by default while holding a small bounded pool of real server connections per user and database pair. The pooler is what lets replica counts scale without multiplying server connections: an extra `api` pod adds cheap client sockets, not PostgreSQL backends.

The budget that matters therefore lives in the `pgbouncer` chart's values. They price the aggregate peak, meaning every pooled alias across both peers, the reserve pools, and the direct consumers (the block explorer, the `postgres-exporter`, and the migration Job), against the PostgreSQL server's `max_connections`. If you raise a pool size, a reserve or the PgBouncer replica count without repricing, every per-process limit multiplies by the peer count and the sum spends headroom that the whole estate shares. Under saturation, clients queue instead of opening new server connections, and a client that queues past the configured wait timeout (10 seconds by default) is rejected.

The chart checks this at render time: a render fails when the aggregate exceeds the declared `max_connections`, or when a role's pods at their replica ceiling would hold more than 8 clients per server connection of their alias. Keep the declared `max_connections` equal to the server's real one, because the check can only see the declared value.

## Stateful dependencies [#stateful-dependencies]

You supply PostgreSQL, Redis and object storage and point `global.datastores` at them. The `dalp` chart deploys none of them for the platform, so the availability of each is the availability of the service you chose.

| Dependency | What the platform needs | Who carries availability and backup |
| --- | --- | --- |
| PostgreSQL | One database server, reached through PgBouncer | Your database provider |
| Redis | A cache and notification service, and the platform keeps serving while it is away | Your Redis provider |
| Object storage | AWS, GCP, Azure, an S3-compatible endpoint or a filesystem path, one active | Your storage provider |

One PostgreSQL server backs several logical databases (the default database, `blockscout` and `dapp`), not one database per service. Only the active object storage provider's configuration is used. [Backup and disaster recovery](https://docs.settlemint.com/docs/deployment/backup-recovery) lists who owns the backup and failover of each.

### When the cache and notification transport fail [#when-the-cache-and-notification-transport-fail]

The platform keeps serving while Redis is away, but the default multi-replica deployment needs a shared Redis, as [Prerequisites](https://docs.settlemint.com/docs/deployment/prerequisites) says, and the `dalp` chart enables the Redis cache backend by default. A pod does not wait for Redis before it starts serving, because gating startup on it turns a brief interruption into a restart loop across every role. A pod that starts before Redis is reachable serves from its in-process tier and reconnects on its own.

Each pod supervises its cache and notification connections and retries on a bounded backoff with no limit on the number of attempts. Reconnection also checks that Redis is serving requests, not only accepting connections, so an endpoint that is loading a snapshot or failing over is retried rather than treated as healthy.

While a pod is disconnected, it cannot receive shared cache updates or invalidation notifications. Change notifications also stop, and each listener falls back to its own fixed reconcile bound instead: a lost cache-invalidation hint heals within `cache.versioned.windowMaxLifetimeMs`, 600,000 milliseconds (ten minutes) by default, and chain-health and network-configuration reloads heal within a fixed sixty seconds. These intervals bound scheduled reconciliation, not event delivery. Dependency outages and processing delays can extend the time until fresh state is visible. Operations that promise deployment-wide reach, such as clearing a cache namespace, fail while Redis is unreachable instead of reporting a success they cannot deliver.

`dalp_redis_client_unavailable_seconds` is zero while a pod's Redis connection is usable. During an outage, it reports how long the connection has been unavailable. Once alerting is turned on in the observability chart, its `RedisClientLatchedOffline` alert fires for a sustained outage, which separates a brief Redis restart from a pod that is not recovering.

## One chart for every environment [#one-chart-for-every-environment]

Every environment, from a first test install to production, installs the same `dalp` chart with its own values overlay. Point that overlay at your own PostgreSQL, Redis and object storage, and at your own ingress controller. See [Stateful dependencies](#stateful-dependencies).

`global.deploymentEnvironment` names the environment and takes one value from a closed set: `local`, `development`, `test`, `staging`, `demo` or `production`. The `dapi` subchart's ConfigMap derives the `platform.environment` setting from that value at render time, so `platform.environment` is not a key you set.

The `observability` chart, which collects metrics, logs and traces, installs as its own release beside `dalp`. The `dalp` chart does not pull it in as a dependency.

On OpenShift, layer **`values-openshift.yaml`**, a security-context overlay for the same `dalp` chart templates, and the `observability` chart's own `values-openshift.yaml` over its release. See [OpenShift](https://docs.settlemint.com/docs/deployment/install/openshift).

## Deployment identity [#deployment-identity]

Every deployment carries two identity values: `global.dalpInstance` names the instance, and `global.deploymentEnvironment` names its environment from that closed set. Both default to `local`, and every non-local deployment must override them: they flow into telemetry labels and dashboards, so an instance that keeps the defaults cannot be told apart from any other in shared observability views. The `dapi` subchart, on by default in every `dalp` install, validates both: it requires each value present, checks `global.dalpInstance` against the 1 to 63 character lowercase slug rule, and checks `global.deploymentEnvironment` against the same closed set, failing the render before any pod starts. The observability chart, where you install it, adds one more guard: a non-local environment that still carries the reserved `local` instance slug also fails the render.

## Consequences and reversibility [#consequences-and-reversibility]

Scaling a role is a rollout. Replica changes move no data because every Platform API pod is stateless. Scaling back requires another ownership and readiness transition. Raising pool ceilings without checking the connection budget can overload PostgreSQL, not only the role you scaled, so the [pricing check](#how-queries-reach-postgresql) has to happen alongside the replica change, not after it.

Keep at least [two indexer replicas](#high-availability-by-component) for restart headroom and voluntary node drains. Scaling changes network ownership and readiness, so verify indexing after the transition.

The shard count is the one value with no gradual path: every runner and client must agree on it, so it changes everywhere at once or not at all.

Each role's shutdown window is bounded by the chart's own numbers: a 50-second termination grace period, a 5-second preStop pause, and a 44-second `DAPI_SHUTDOWN_BUDGET_MS` that fits inside what remains. The budget covers the 20-second HTTP drain that `DAPI_HTTP_DRAIN_TIMEOUT_MS` bounds, the 15-second durable entity termination wait, and the 5-second telemetry flush. An `api` pod drains in-flight HTTP work within its drain timeout. A `runner` lets the cluster relocate its shards during the window. An `indexer` releases its network ownership so a surviving replica can claim the networks it owned.

## Frequently asked questions [#frequently-asked-questions]

### Can the runner role pick up HTTP traffic if the api role is overloaded?

No. The runner's HTTP port is health-only: kubelet probes it, but the Service that routes application traffic never selects runner pods. Scaling the `api` role, not the `runner` role, is what adds HTTP capacity, and the two autoscalers stay independent so a workflow backlog on `runner` cannot starve the pool serving requests.

### How much warning do I get before PgBouncer starts rejecting queued clients?

There is no guaranteed warning interval. Once alerting is turned on in the observability chart, its `PgBouncerClientMaxWait` alert uses a one-second queue-wait threshold, a ten-second hold, and a ten-second evaluation interval. The hold equals the 10-second query-wait timeout, so the alert fires as clients begin to be rejected, and notification delays come on top. Use the alert to investigate sustained pressure, not as a promise of time to prevent an individual rejection.

### Why does PgBouncer scale by adding replicas instead of raising the number of processes in each pod?

Each PgBouncer pod runs one process by chart default, and that pin is deliberate. The pod's metrics exporter holds a single admin-console connection. A multi-process pod would route that connection to only one process at random, leaving the other processes' queue depth invisible to the saturation alert: clients could then hit the query wait timeout while monitoring reports no queue at all. Adding replicas instead keeps every process visible, because each replica carries its own exporter sidecar.

### What happens if `global.dalpInstance` or `global.deploymentEnvironment` is left unset entirely, rather than kept at its default?

An unset value fails differently from the default. The `dapi` subchart's ConfigMap declares both values with Helm's `required` function, so an unset value fails that render immediately with a message naming the missing key. The observability chart, where you install it, repeats the same `required` guards, though there the environment check sits behind several unrelated Alloy credential checks, so a misconfigured Alloy receiver can fail that render first. Keeping `global.dalpInstance` at its default `local` while setting a non-local environment, by contrast, satisfies every presence check. Only the observability chart, where you install it, rejects that combination. The `dalp` chart alone renders it.

### Which PostgreSQL, Redis and object storage does a deployment use?

The ones you supply. The umbrella chart's services read their connection details from `values.yaml` (`global.datastores`) regardless of who runs the backing service. When you change the PostgreSQL server, reprice the PgBouncer aggregate against the new server's own `max_connections`.


# Upgrade to 3.2

Source: https://docs.settlemint.com/docs/deployment/upgrade-to-3-2
The operator runbook to move a self-hosted DALP 3.1 or 3.0 deployment to 3.2: backup, values to move, renamed workloads, the index rebuild and System updates.

This runbook moves a self-hosted DALP deployment from 3.1, or directly from 3.0, to 3.2 with Helm. Plan it as a maintenance window: the upgrade replaces the Platform API workloads and the workflow engine, does not carry running workflows across, and can be reversed only by restoring the database backup you take before it, as [Rolling back](#rolling-back) explains.

Changes that affect API clients, the SDK and the CLI are on [Upgrade an integration to DALP 3.2](https://docs.settlemint.com/docs/api-reference/guides/upgrade-to-3-2). [Upgrades and migrations](https://docs.settlemint.com/docs/deployment/upgrades-migrations) explains the database migration Job that every upgrade runs.

## Which steps apply to you [#which-steps-apply-to-you]

`helm list --namespace dalp` shows the version you run in its CHART column. A deployment on 3.1.19 or later follows the steps in the table that apply to it. A deployment on 3.0 also follows [Upgrading from 3.0](#upgrading-from-30), which holds the steps from the 3.1 releases that a direct upgrade skips. A deployment on an earlier 3.1 patch release needs two of those: the legacy asset creation decision before 3.1.19, and the Gas Station setting before 3.1.12. You can upgrade from 3.0 directly to 3.2 without installing 3.1 first.

| Step | Who it applies to |
| --- | --- |
| [Finish in-flight work](#finish-in-flight-work) | Every deployment |
| [Update Ripple policies](#update-ripple-policies) | Deployments where an organisation uses Ripple custody |
| [Update Fireblocks settings](#update-fireblocks-settings) | Deployments that use Fireblocks custody |
| [Move your values to the 3.2 chart](#move-your-values-to-the-32-chart) | Every deployment with its own values file |
| [Set the values that 3.2 adds](#set-the-values-that-32-adds) | Every deployment |
| [Decide on Ask AI](#decide-on-ask-ai) | Every deployment |
| [Decide on legacy asset creation](#decide-on-legacy-asset-creation) | Deployments on 3.0, or on a 3.1 release before 3.1.19, whose users issue the original asset families |
| [Decide on the offerings surfaces](#decide-on-the-offerings-surfaces) | Every deployment |
| [Decide which application layers to switch on](#decide-which-application-layers-to-switch-on) | Every deployment |
| [Check that the custody provider signs user operations](#check-that-the-custody-provider-signs-user-operations) | Deployments with account abstraction on |
| [Prepare the custody census](#prepare-the-custody-census) | Every deployment |
| [Upgrading from 3.0](#upgrading-from-30) | Deployments on 3.0, and the two early 3.1 cases in this table |
| [Take a recovery point](#take-a-recovery-point) | Every deployment |
| [Run the Helm upgrade](#run-the-helm-upgrade) | Every deployment |
| [Watch the index rebuild](#watch-the-index-rebuild) | Every deployment |
| [Run System updates](#run-system-updates) | Each organisation, on each network, when it wants the 3.2 contracts |

Make the values changes ahead of the day. On the day, start the quiet window, let in-flight operations finish, take the database backup, then run `helm upgrade`. A backup taken before the drain misses the records the drain writes.

## Before you upgrade [#before-you-upgrade]

### Finish in-flight work [#finish-in-flight-work]

3.2 runs workflows on a new workflow engine, and the chart no longer deploys the workflow engine that 3.1 and 3.0 ran. A workflow that the earlier workflow engine is still running at the upgrade does not continue on 3.2, because no 3.2 component reads the earlier engine's state. Plan a window in which nobody starts new operations. The platform has no setting that blocks new operations, so agree the window with the people and systems that start them. Before the upgrade, let every operation in progress reach a final state: transaction requests, issuance runs, corporate action runs, invitations and identity recoveries. `GET /api/v2/transaction-requests` lists transaction requests with their status, `GET /api/v2/token-issuance-runs/{runId}` reads one issuance run, and `GET /api/v2/tokens/{assetId}/corporate-actions` lists an asset's corporate action runs.

### Update Ripple policies [#update-ripple-policies]

3.2 offers Ripple custody only when `global.dalpApp.config.custody.providers.ripple.enabled`, the `CUSTODY_PROVIDER_RIPPLE_ENABLED` variable, is `true`, and it ships `false`. With it off, existing Ripple custody configurations keep signing, a new one is refused, and pods whose `SIGNER_PROVIDER` is `ripple` refuse to start. A deployment that uses Ripple sets it to `true` in the values for the upgrade.

An organisation that uses Ripple custody files an intent with Ripple for each operation, and DALP names the operation in the intent's `dalpKind` property. 3.1 named most direct contract writes after the contract function, such as `contract.grantRole`, and 3.2 names them after the operation, such as `system.grant-role` or `token.grant-role`. 3.2 also marks a role change with `dalpRolesUndescribed=true` when it cannot list every role that the change grants or revokes. A Ripple policy that matches the 3.1 names stops matching after the upgrade, so a fallback policy that was not written for the operation can approve or refuse it.

Update the policies before the upgrade. [Ripple policy reference](https://docs.settlemint.com/docs/deployment/ripple-policy#operation-names-that-changed-from-31-to-32) lists the changed names, and [Policies for role changes](https://docs.settlemint.com/docs/deployment/ripple-policy#policies-for-role-changes) describes the policy that the role mark needs.

### Update Fireblocks settings [#update-fireblocks-settings]

3.2 refuses a Fireblocks Raw signing request by default, before it reaches Fireblocks: an EVM operation signs as a Typed Message or sends a Contract Call. `FIREBLOCKS_ALLOW_RAW_SIGNING` set to `"true"` turns Raw signing back on, for a workspace whose policy allows it. 3.2 also attaches a Fireblocks tag to every vault account it creates, named by `FIREBLOCKS_DALP_VAULT_TAG_ID`, and the policy rule that allows the DALP API user to sign from those vaults matches that tag. With the value empty, new vaults carry no tag and their requests reach the catch-all block rule. Before the upgrade, create the tag, set its id, tag the vaults DALP created earlier, and check your rules against [Fireblocks policy](https://docs.settlemint.com/docs/deployment/fireblocks-policy#tag-the-dalp-vaults).

### Move your values to the 3.2 chart [#move-your-values-to-the-32-chart]

The 3.2 chart splits the Platform API into four roles inside one subchart and drops the subcharts that 3.1 ran beside it. A values file written for 3.1 keeps keys that the 3.2 chart no longer reads. Move each of them:

| 3.1 values key | 3.2 values key |
| --- | --- |
| `dapi.resources`, `dapi.routesReplicaCount` | `dapi.v1.resources` and `dapi.v2.resources`, and replicas under `dapi.v1` and `dapi.v2` |
| `didx.*` (the indexer subchart) | `dapi.indexerDeployment.*`, with `rebuild.enabled` and `rebuild.replicas` for the rebuild pods |
| `ddwf.*` (the workflow subchart) | `dapi.runnerDeployment.*` for durable work and `dapi.schedulerDeployment.*` for scheduled work |
| `docs.searchIndexing.*` | `global.searchIndexing.*` |
| `dapp.config.app.http.url` | `global.dalpApp.config.app.http.url`, a literal `https://` URL |
| `global.dalpApp.config.networks.default.*` | `global.dalpApp.config.networks.mintnet.*`. The `default: true` flag, not the key, marks the default network |
| `global.dalpApp.config.platform.instance` | `global.dalpInstance`, with `global.deploymentEnvironment` set to the environment |
| `global.dalpApp.config.app.logOrpcRequests` | `global.dalpApp.config.app.logApiRequests` |
| `erpc`, `nodecore`, `global.rpcGateway` | None. Remove them and set `rpc.urls` on each network, as **Network endpoints** below describes. |
| `global.dalpApp.config.bundler.providerNativeSubmission` | None. Remove it. |
| `global.dalpApp.config.signer.dfns.executionMode`, `global.dalpApp.config.signer.ripple.executionMode` | None. Remove them. |

The chart fails the render on a `config.app` block under `dapp` or `dapi`, because the Console and the Platform API must read one public URL from `global.dalpApp.config.app`. It ignores the other 3.1 keys you leave in the values file, so remove each one yourself. A 3.1 `dapi.resources` block no longer sizes the API pods, because `dapi.v1.resources` and `dapi.v2.resources` have their own defaults and take precedence. Move your sizing to those keys and to the `resources` of `dapi.indexerDeployment`, `dapi.runnerDeployment` and `dapi.schedulerDeployment`. `dapi.routesReplicaCount` is ignored: set replicas under `dapi.v1` and `dapi.v2`. `dapi.ingress`, `dapi.httpRoute` and `dapi.openShiftRoute` keep their 3.1 meaning, and `dapi.config` is merged over `global.dalpApp.config` for every Platform API role.

A 3.1 override under `networks.default` no longer reaches the shipped network, so an RPC endpoint you set there must move to `networks.mintnet`. 3.2 ignores `platform.instance` and stamps every log, metric and trace with `global.dalpInstance` and `global.deploymentEnvironment`, which both default to `local`. Set them to this deployment's name and its environment: `development`, `test`, `staging`, `demo` or `production`.

**Client addresses behind a proxy.** The 3.1 chart read the client address from the forwarding header that an NGINX ingress controller writes, and 3.2 ships `global.dalpApp.config.trustedProxy.profile` as `none`, which discards every forwarding header. Behind a proxy, `none` keys sign-in rate limits and the request addresses in audit records on the proxy's address. Set `nginx`, `envoy` or `openshift` to match the controller in front of the Console and the Platform API.

**Network endpoints.** 3.1 sent every network call through an RPC gateway that the chart deployed, and each network's `rpc.url` pointed at that gateway. 3.2 deploys no gateway. Each network under `global.dalpApp.config.networks` takes its node endpoints directly in `rpc.urls`, a list. Copy the node endpoints that you configured as gateway upstreams into `rpc.urls`. 3.2 refuses a node endpoint that resolves to a private or loopback address unless the network sets `rpc.allowPrivateUpstreams` to `true`, so set it on a network whose nodes run inside your own network. [Networks](https://docs.settlemint.com/docs/deployment/networks) describes the setting. Set `rpc.wsUrl` on every network as well: the 3.2 indexer follows each network through that subscription endpoint and does not fall back to polling an HTTP endpoint.

**Custody execution mode.** 3.1 let you choose whether DFNS and Ripple sign as the provider's own transactions or as approvals that DALP submits, and a later 3.1 patch release added a bundler setting that did the same for Fireblocks. 3.2 has no such settings: each custody provider declares how it signs on each network, and the platform uses that. Remove the settings and their environment variables, `DFNS_EXECUTION_MODE`, `RIPPLE_EXECUTION_MODE` and `BUNDLER_PROVIDER_NATIVE_SUBMISSION`.

**Environment variables.** The 3.2 configuration no longer reads these variables. Remove them from any environment file or Secret you maintain:

- `DIDX_URL`, `DIDX_PORT`, `DIDX_HOSTNAME`, `DIDX_INTERNAL_HOSTNAME`, `DDWF_URL`, `DDWF_PORT`, `DDWF_HOSTNAME` and `DDWF_INTERNAL_HOSTNAME`. The chart sets the internal addresses of the four roles itself.
- `DATABASE_POOL_MIN` and `DATABASE_POOL_MAX`. 3.2 sizes one pool for each role, with these defaults: `DATABASE_POOL_MAX_API` 40, `DATABASE_POOL_MAX_INDEXER` 24, `DATABASE_POOL_MAX_RUNNER` 16 and `DATABASE_POOL_MAX_SCHEDULER` 32. Check the sum of the pools across all pods against your database's connection limit.

### Set the values that 3.2 adds [#set-the-values-that-32-adds]

3.1 had neither of these values, so a 3.1 values file sets neither, and the upgrade fails until both are set:

- `global.dalpApp.env.DALP_GOVERNANCE_DOMAIN_SCOPE` names the domain under which the deployment signs governance poll ballots. `helm upgrade` fails the render while it is empty or `local`. Set a name unique to this deployment, as [Governance ballot domain](https://docs.settlemint.com/docs/deployment/install/values-secrets#governance-ballot-domain) describes.
- `global.dalpApp.env.CUSTODY_CREDENTIAL_IDENTITY_KEY` is the key under which the platform hashes custodian credential identities, at least 32 characters long. The chart ships a development placeholder, and the Platform API pods, which run in production mode, refuse to start on it. Set a value unique to this deployment and keep `CUSTODY_CREDENTIAL_IDENTITY_KEY_ID` at `v1`.

### Decide on Ask AI [#decide-on-ask-ai]

3.2 adds Ask AI, a question-and-answer chat on the documentation site that the chart deploys. The documentation chart reads its model provider key from the same Secret entry that the Console assistant uses, `global.dalpApp.env.ASSISTANT_OPENROUTER_API_KEY`. The chart points the documentation at that entry by default, through `docs.openRouter.existingSecret` and `docs.openRouter.existingSecretKeys.apiKey`. The entry is empty by default, and Ask AI stays off while it is empty. As soon as you set the key for the Console assistant, Ask AI turns on too, for anyone who can reach the documentation site, and each answer is billed to that key. Ask AI allows each client 10 questions a minute and all clients together 300 an hour. The chart passes `global.dalpApp.env.REDIS_URL` to the documentation pods, so they keep these counts in Redis and share them. While Redis does not answer, Ask AI refuses questions.

Choose one of three settings in the same values change that sets the key:

- To share the key, set `ASSISTANT_OPENROUTER_API_KEY` and leave the `docs.openRouter` values as they ship.
- To keep Ask AI off, set `docs.openRouter.existingSecret` to `""` and leave `docs.openRouter.apiKey` empty.
- To bill Ask AI to a separate key, set `docs.openRouter.existingSecret` to the name of a Secret you manage and `docs.openRouter.existingSecretKeys.apiKey` to the entry that holds the key.

[Ask AI provider key](https://docs.settlemint.com/docs/deployment/install/values-secrets#ask-ai-provider-key) describes each value and the combinations that fail the render.

### Decide on legacy asset creation [#decide-on-legacy-asset-creation]

The seven asset families of the original catalogue, `bond`, `equity`, `fund`, `stablecoin`, `deposit`, `real-estate` and `precious-metal`, cannot be created unless the deployment turns legacy asset creation on. A request to create a token of one of these types, or to install its factory, is refused, and organisations and networks deployed while the setting is off get no factories for them. Tokens and factories that already exist stay on chain: the platform removes nothing.

The setting arrived in the 3.1.19 patch release, so a deployment on 3.1.19 or later keeps the value it already runs with. 3.0 and the 3.1 releases before 3.1.19 had no such setting, so a deployment on one of them whose users still issue these families loses that ability at the upgrade unless you turn the setting on. To keep issuing them, set `global.dalpApp.config.features.legacyAssetCreation` to `"true"`, or the environment variable `FEATURE_LEGACY_ASSET_CREATION` to `true`, in the values for the upgrade. The setting is `false` by default.

### Decide on the offerings surfaces [#decide-on-the-offerings-surfaces]

The Console shows the Offerings sidebar item and the issuer offering pages only when `global.dalpApp.config.features.tokenSale` is `true` and the organisation has deployed the token sale add-on. The 3.0 and 3.1 charts shipped `tokenSale: false`, and the 3.2 chart ships `tokenSale: true`. A deployment whose values file does not set the key therefore has the setting on after the upgrade, and an organisation that deploys the add-on gets the Offerings surfaces. Helm keeps a value that your values file sets, so a deployment whose overlay sets `tokenSale` to `false` stays without the Offerings surfaces. The same setting switches on fund dealing, the subscription and redemption requests of a fund and the settlement of its dealing days, so with it `false` the Dealing tab, the Dealing requests card and the Funds section of Invest are absent too. Corporate actions do not depend on it. Check your overlay for the key. Remove it or set it to `true` if issuers on this deployment run offerings or fund dealing, and set it to `false` to keep the surfaces off.

### Decide which application layers to switch on [#decide-which-application-layers-to-switch-on]

3.2 sells its application layers as licensed modules, and each one has a switch under `global.dalpApp.config.features`. [Switch application layers on or off](https://docs.settlemint.com/docs/deployment/install/values-secrets#switch-application-layers-on-or-off) lists every switch with its default. The Secondary market (`tradingVenue`), Reporting and finance operations (`regulatoryReporting`) and Market surveillance (`surveillance`) are off by default. A module that is off has no screens and its routes answer `404`, so for each module your licence includes, set its switch to `true` in the values for the upgrade.

Multi-signer wallets belong to the Self-custody module, `features.custodyOps`, which is on by default. A deployment that sets it to `false` accepts a signer set only when it has one signer and a threshold of one. It refuses any other signer set with HTTP 403 and the error `DALP-12261` `MULTISIG_NOT_ENABLED`, whose message is "Multi-signer wallets are switched off on this deployment". An organisation owner who switches Self-custody off for one organisation gets the same limit for that organisation, refused with `custody.multisig.OFF_FOR_ORGANIZATION`. [Multisig](https://docs.settlemint.com/docs/concepts/custody-and-signing/multisig) explains what a multi-signer wallet is.

### Check that the custody provider signs user operations [#check-that-the-custody-provider-signs-user-operations]

At start-up, the API, runner, indexer and scheduler pods check that the platform's custody provider, `SIGNER_PROVIDER`, can sign on each enabled network. With account abstraction on, they also check that the provider can sign user operations, the transactions that smart accounts send. A provider that cannot stops the pods from starting with an error that names the chain ID and ends with `Set SIGNER_PROVIDER to a provider that signs user operations. A deployment that runs without account abstraction can set FEATURE_ACCOUNT_ABSTRACTION=false instead.` Confirm before the upgrade that your provider supports every enabled network, or that you can turn account abstraction off.

### Prepare the custody census [#prepare-the-custody-census]

The custody census is the 3.2 migration step that records which custodian holds each existing wallet before it moves wallets to custody accounts. It archives wallets that hold no signing key. When it cannot prove the custodian of any other wallet, it stops with the message `The custody census still has <n> unresolved row(s)`, followed by the count of each kind of row it could not resolve, and the upgrade does not complete. If the deployment still has the legacy transaction signer database, which a deployment first installed before 3.1 can have, set `TXSIGNER_DATABASE_URL` under `dapp.migrator.env`. The Job reads that database as evidence of which wallets DFNS or Fireblocks hold. The runtime pods do not read this value.

### Upgrading from 3.0 [#upgrading-from-30]

A 3.0 deployment that upgrades directly to 3.2 needs every step above, and these steps from the 3.1 releases as well. Make them part of the same values change.

**Legacy asset creation.** 3.0, and 3.1 before 3.1.19, created the seven original asset families without a setting. Decide on the setting before the upgrade, as [Decide on legacy asset creation](#decide-on-legacy-asset-creation) describes.

**Custody records per organisation.** 3.0 configured one custody provider for the whole deployment. Since 3.1 each organisation has its own custody provider configuration. Keep `SIGNER_PROVIDER` and the provider credentials set to the custodian that holds the existing keys during the upgrade. A 3.0 deployment is the most likely to still have the legacy transaction signer database, so read [Prepare the custody census](#prepare-the-custody-census) before you upgrade.

**Data sealed under an earlier password.** If the migration Job stops with the message `ENCRYPTION_PREVIOUS_MASTER_PASSWORD is required`, some secrets or KYC files are still sealed in an older format or under another password, and the message names how many. Give the Job the password that sealed them through `dapp.migrator.env.ENCRYPTION_PREVIOUS_MASTER_PASSWORD`, and it seals them again under `ENCRYPTION_MASTER_PASSWORD`. Only the migration Job receives this value. [Encryption at rest](https://docs.settlemint.com/docs/deployment/install/values-secrets#encryption-at-rest) describes the procedure.

**Fireblocks Gas Station.** Since 3.1.12, new Fireblocks vault accounts are enrolled in Fireblocks Gas Station by default. A deployment on 3.0, or on a 3.1 release before 3.1.12, that uses a Fireblocks workspace where Fireblocks has not set up Gas Station sets `FIREBLOCKS_AUTO_FUEL` to `"false"`, because a vault account creation that Fireblocks rejects cannot be retried.

**Network defaults for DFNS and Fireblocks.** `DFNS_DEFAULT_NETWORK`, added in 3.1, names the DFNS network on which a new wallet is created when the request names no network and carries no chain ID that maps to a DFNS network, and in 3.2 it defaults to `Ethereum`. A DFNS custody configuration whose "Default network" field is set uses that field instead. A request that carries a mapped chain ID creates the wallet on that chain's DFNS network instead, as [Which network a DFNS wallet is created on](https://docs.settlemint.com/docs/concepts/custody-and-signing/custody-provider#which-network-a-dfns-wallet-is-created-on) describes. `FIREBLOCKS_DEFAULT_ASSET_ID`, also added in 3.1, names the Fireblocks asset used when a request names no network. A wallet is bound to its network when it is created. On a test network, set both to that network, such as `EthereumSepolia` for DFNS or `ETH_TEST5` for a Fireblocks Sepolia workspace.

**Integrations.** Clients built against 3.0 need the changes on [Upgrade an integration to DALP 3.2](https://docs.settlemint.com/docs/api-reference/guides/upgrade-to-3-2#upgrading-from-30) as well.

### Take a recovery point [#take-a-recovery-point]

A Helm rollback does not reverse the database migrations of the upgrade, as [Rolling back](#rolling-back) explains. Once in-flight work has finished, take a database backup and keep it until you have confirmed the 3.2 deployment. [Backup and recovery](https://docs.settlemint.com/docs/deployment/backup-recovery) covers what to back up.

## Run the Helm upgrade [#run-the-helm-upgrade]

Run `helm upgrade` with the 3.2 chart version and your updated values:

```bash
helm upgrade dalp oci://pkg.distribution.settlemint.com/settlemint/dalp \
  --version <3.2 chart version> \
  --namespace dalp \
  --values my-values.yaml \
  --wait
```

The migration Job runs first, as [Upgrades and migrations](https://docs.settlemint.com/docs/deployment/upgrades-migrations) describes, and Helm then replaces the earlier workloads with the 3.2 ones. Under the default `pre` hook, a catch-up run of the same migration follows the rollout and can still fail the release, so pass `--wait` to hold the catch-up until the new workloads are ready. When the command returns, check that each Deployment has finished rolling out:

```bash
for d in dalp-api-v1 dalp-api-v2 dalp-indexer dalp-indexer-rebuild dalp-runner dalp-scheduler dalp-dapp; do
  kubectl rollout status deployment/"$d" --namespace dalp
done
```

Leave `dalp-indexer-rebuild` out of the list when `dapi.indexerDeployment.rebuild.enabled` is `false`, as the OpenShift overlay sets it.

The Platform API's workloads change name, because the one API workload and the two subcharts of 3.1 become separate Deployments in 3.2. With the default `dapi.fullnameOverride` of `dalp-dapi`, the 3.2 Deployments are named as follows:

| 3.1 workload | 3.2 Deployments |
| --- | --- |
| `dalp-dapi` | `dalp-api-v1` for `/api/v1`, `dalp-api-v2` for `/api/v2` |
| `dalp-didx` | `dalp-indexer`, plus `dalp-indexer-rebuild` for index rebuilds |
| `dalp-ddwf-v<version>` | `dalp-runner` and `dalp-scheduler` |
| `dalp-dapp` | `dalp-dapp`, unchanged |

The API Services are `dalp-api`, which serves `/api/v2`, and `dalp-api-v1`. The chart's own Ingress, Route and NetworkPolicy objects follow the new names. Anything outside the chart that names a 3.1 object, such as an alert rule, a dashboard, a NetworkPolicy you added, an HPA or capacity rule, or a client inside the cluster that dials the `dalp-dapi` Service, needs the new name.

3.2 also runs no RPC gateway, so the upgrade removes the `dalp-erpc` Deployment and, where you turned it on, `dalp-nodecore`, together with their Services and any Ingress or Route you enabled for them. Search your alert rules, dashboards and NetworkPolicies for `dalp-erpc` and `dalp-nodecore`. Move an egress rule that allowed traffic to the gateway onto the API, indexer, runner and scheduler pods, which call the node endpoints in `rpc.urls` directly, and remove the rules and panels that watched the gateway. A client outside the platform that used the gateway's own hostname needs a node endpoint of its own. The upgrade also starts the PostgreSQL exporter, `postgres-exporter.enabled`, on by default, which holds one direct database session.

The chart has no step that sequences the cutover. Helm creates the 3.2 Deployments and Services and removes the 3.1 ones in the same release, except the 3.1 workflow Deployment, Service and ConfigMap, which Helm keeps until you delete them, as [Verify the upgrade](#verify-the-upgrade) describes. The API answers only once the new API pods are ready.

The upgrade does not delete the data that the earlier workflow engine stored in its persistent volumes and in object storage. It stays until you delete it. Delete it once you no longer need a way back to 3.1.

## After the upgrade [#after-the-upgrade]

### Watch the index rebuild [#watch-the-index-rebuild]

3.2 changes how the platform indexes chain data, so the first 3.2 start builds a new index next to the existing one. The existing index keeps answering reads while the new one replays the history of each enabled network, and the platform promotes the new index only when it has caught up. A Helm release that reports success does not mean the rebuild has finished.

How long the rebuild takes depends on the number of enabled networks, the blocks and events to replay, and how fast your RPC nodes and database answer. The platform gives no fixed duration. Follow it in three places:

- In the Console, open Platform status, open the details of the Data freshness panel, and wait for each network to move from Reindexing to Healthy.
- The metric `dalp_indexer_build_progress_ratio` runs from 0 to 1 for the index being built. `dalp_indexer_build_failures_total` counts failed build steps, and `dalp_indexer_promotion_age_seconds` reports the age of the last promotion.
- A client that sends `Prefer: dalp-fail-on-indexer-reindexing` on `POST /api/v2/organizations`, `POST /api/v2/organizations/bootstrap`, `POST /api/v2/invitations` or `POST /api/v2/invitation-acceptances` receives HTTP 503 with code `platform.http.REINDEXING` (`DALP-12331`) while the network's index is rebuilding, instead of the request going ahead. The response carries `data.retryAfterSeconds` and a `Retry-After` header. The refusal is retryable.

### Run System updates [#run-system-updates]

The Helm upgrade changes the platform, not the contracts of each organisation's system on chain, so 3.2 does not require a System updates run. An organisation's system keeps running on the contract versions it has, and each organisation decides when to run System updates on each network it uses. An organisation runs it when it needs a token feature, add-on or document anchoring that the 3.2 contracts add.

Until an organisation runs System updates on a network:

- Its installed contracts on that network stay on the versions they run.
- The token feature factories and add-ons that 3.2 adds are not on its system, among them the factories for holds, supply delegation, interest and dividend yield, distribution waterfalls and register lines, and the custody gateway add-on. Attaching a token feature whose factory the system lacks is refused with HTTP 409 `TOKEN_FEATURE_FACTORY_NOT_FOUND` (`DALP-9465`). Creating a token from a template that uses such a feature is refused before anything is signed, with HTTP 409 `TOKEN_CREATE_FEATURE_FACTORY_NOT_REGISTERED` (`DALP-207901`), and Issue asset marks the template as needing a feature factory. Every system template uses holds. Reading the custody gateway on a system without the add-on answers HTTP 404 `GATEWAY_ADDON_NOT_DEPLOYED` (`DALP-9813`). Anchoring a document is refused with HTTP 409 `ANCHOR_WRITE_REFUSED` (`DALP-0749`) until the system has the document anchor registry. A System manager can also install one factory or add-on at a time from [Factories](https://docs.settlemint.com/docs/console/organisation-settings/factories), without a full run. The custody gateway add-on is not offered there: install it with System updates or with `POST /api/v2/system/addon-factories`.
- The run's data steps stay outstanding: price feeds for assets that lack one, the organisation's trust for the claim topics it issues, topic scheme updates, investor eligibility topic signatures, escrow claims and the advanced accounts infrastructure.
- The organisation sees the shipped reporting obligations but has no editable copies of them, because the run is what makes those copies.

System updates compares the organisation's system with the newest release directory on the network. An Admin or a System manager of each organisation opens System updates in the Console, reviews the components marked Upgrade available or Not installed, and starts the run. [System updates](https://docs.settlemint.com/docs/console/organisation-settings/system-updates) describes the run, which cannot be undone once its steps are written to the network.

### Verify the upgrade [#verify-the-upgrade]

Check each of these after the upgrade:

1. `helm upgrade` returned without an error. Under the default `pre` hook, that means the migration Job succeeded before Helm touched the workloads, and the catch-up run succeeded after the rollout.
2. `helm history dalp --namespace dalp` lists the 3.2 chart version as the `deployed` revision.
3. Each Deployment in the rollout loop above has finished rolling out, and `kubectl get deployments --namespace dalp` no longer lists `dalp-dapi`, `dalp-didx` or `dalp-erpc`. The 3.1 workflow Deployment `dalp-ddwf-v<version>`, its Service of the same name and its `dalp-ddwf-v<version>-config` ConfigMap carry Helm's keep policy, so the upgrade leaves them running. Delete them once the 3.2 runner is ready: `kubectl delete deployment,service dalp-ddwf-v<version> --namespace dalp` and `kubectl delete configmap dalp-ddwf-v<version>-config --namespace dalp`.
4. A `/api/v1` request and a `/api/v2` request both answer through your Ingress, Route or HTTPRoute. The chart sends `/api/v2` to the v2 fleet and the rest of `/api` to the v1 fleet.
5. Platform status shows each enabled network as Healthy in the Data freshness panel, once the index rebuild has finished.

## Rolling back [#rolling-back]

`helm rollback` returns the Kubernetes objects to the manifests of the release you upgraded from. It does not reverse the database migrations, it does not restore the earlier workflow engine's state, and it does not undo a System updates run, which is written on chain. The 3.1 code then runs against a database that 3.2 has migrated. To return to 3.1, restore the database backup you took before the upgrade, then roll the release back. Any operation that ran on 3.2 after the backup is not in the restored database, while its on-chain results stay on the ledger, so compare the restored records with the ledger before you reopen traffic, as [Point-in-time recovery](https://docs.settlemint.com/docs/deployment/backup-recovery#point-in-time-recovery) describes. [Rolling back after a bad upgrade](https://docs.settlemint.com/docs/deployment/upgrades-migrations#rolling-back-after-a-bad-upgrade) explains why a rollback leaves the schema as it is.


# Upgrades and migrations

Source: https://docs.settlemint.com/docs/deployment/upgrades-migrations
How the database migration Job runs inside a Helm upgrade, which hook type to choose, and what a failed migration leaves behind for you to inspect.

A `dalp` Helm upgrade updates the platform release and runs its database migration Job. With the default pre-upgrade hook, the Job must succeed before Helm updates application Deployments. Database changes are separate from the application rollout and do not reverse with `helm rollback`. Check migration compatibility, recovery points, and any required index rebuild before the upgrade. To move a 3.1 or 3.0 deployment to 3.2, follow [Upgrade a deployment to DALP 3.2](https://docs.settlemint.com/docs/deployment/upgrade-to-3-2).

## What runs, and when [#what-runs-and-when]

The `dapp` subchart renders a Kubernetes `Job` named `<release>-migrations` whenever `dapp.migrator.enabled` is true, which is the shipped default. Set `dapp.migrator.enabled: false` and no migration runs, so your application pods start against whatever schema the database already has. That setting is for a pipeline that runs migrations through its own tooling before it calls `helm upgrade`. On every other path, disabling it removes the check between a schema change and a pod that expects it.

`dapp.migrator.hookType` decides when the Job runs. Only the `pre` hook is a hard gate.

| `dapp.migrator.hookType` | Runs | Use when | Consequence |
| --- | --- | --- | --- |
| `pre` (default) | `pre-install,pre-upgrade` hook at weight `-5` | Postgres is external or already running, as in production | The Job completes before Helm updates the application workloads. |
| `post` | `post-install,post-upgrade` hook at weight `0` | The same release also creates the database the migration targets | Helm applies and waits on the workloads before the Job runs, so new pods can start before the migration finishes. A readiness check that needs the new schema can stop the wait from ever reaching the post hook. |
| `none` | An ordinary resource in the release, with no hook annotations | Your own pipeline orders migrations outside Helm | Helm's `before-hook-creation` cleanup and the hook ordering no longer apply, so you own migration ordering. |

With `pre`, the chart also runs the migrator a second time after the rollout, as the `<release>-migrations-catchup` Job: a `post-install,post-upgrade` hook at weight `10`. It picks up rows an old pod wrote while the rollout ran, and it is a no-op when nothing is left to migrate. Pass `--wait` to `helm upgrade` so the catch-up runs only after the new pods replace the old ones. Without it, the catch-up can run while old pods still serve. A failure there fails the release after the new pods already serve. Both Jobs carry the label `app.kubernetes.io/component: migrations`, so `kubectl get jobs -l app.kubernetes.io/component=migrations` lists them together. Set `dapp.migrator.catchUp.enabled: false` where a second Job per upgrade is not acceptable.

Before running its migration command, the Job's init containers wait for the Postgres endpoint to accept connections and, when you enable Conjur, fetch a Conjur access token. That wait draws from the same clock the migration itself runs on: `activeDeadlineSeconds` bounds the Job from the moment it starts, init containers included. The Postgres wait's own timeout defaults to 120 seconds, so a slow database can use a fifth of the default budget before the migration command runs. The migration container runs with a default `backoffLimit` of 3 and an `activeDeadlineSeconds` of 600 seconds, 10 minutes in total.

Its database connection is not the one the application containers use: a dedicated migration Secret gives it a direct, non-pooled `DATABASE_URL`, bypassing the connection pooler even when pooling is enabled for the application. A transaction-mode pooler would break the session-scoped advisory lock the migration takes. Everything else about how it reads configuration matches the application containers: a mounted `config.yml`, an `envFrom` secret, and, when you configure Conjur secrets for the migrator or inherit them from the runtime `dapp` configuration, a `summon`-wrapped entrypoint. `dapp.migrator.env` can also carry `TXSIGNER_DATABASE_URL` for a deployment that still has the legacy transaction signer database, which [Prepare the custody census](https://docs.settlemint.com/docs/deployment/upgrade-to-3-2#prepare-the-custody-census) describes: the Job reads that database as evidence of which custodian holds each wallet's keys when it records each organisation's custody provider. It can carry the encryption-rotation keys too (`ENCRYPTION_MASTER_PASSWORD`, `ENCRYPTION_PREVIOUS_MASTER_PASSWORD`) for a local, non-Conjur rotation run. [Values and secrets](https://docs.settlemint.com/docs/deployment/install/values-secrets#encryption-at-rest) covers the two-step rotation and when the old key can be removed. It can carry `PLATFORM_ADMIN_RECOVERY_EMAIL` for one upgrade, to give an existing account the platform administrator role when no administrator is left or none can sign in, as [Restore the platform administrator role](https://docs.settlemint.com/docs/deployment/security-compliance-posture#restore-the-platform-administrator-role) describes.

With the default `pre` hook type, Helm does not change your running Deployments until the migration Job succeeds. The previous pods keep serving, but migration locks, data changes or incompatible schema changes can still slow or fail their requests, so plan the upgrade in a maintenance window. An index rebuild is not a gate. Some releases require one, so check the release notes for your target version. A rebuild runs behind a deployment that already serves, and the read models it populates are incomplete for earlier periods until it finishes draining. Treat affected historical figures as provisional during the rebuild. Open the Indexing detail screen from Platform status and wait for the affected chain to return from Reindexing to Healthy. Helm release completion does not prove that the rebuild finished.

[Figure] A migration Job gates the release. An index rebuild never does. A vertical timeline runs down the figure from when helm upgrade starts to well after the release finishes. The migration Job sits directly on that timeline: on its default pre-install and pre-upgrade hook it runs before pods roll to the new version, and a solid gate marker shows the timeline cannot pass this point until the Job succeeds, so a failure stops the release right there while your prior release's serving pods stay untouched. Two independent clocks remove the finished or failed Job afterward: the Helm hook-delete policy, which by default keeps a failed Job until the next upgrade attempt, and a Kubernetes-native ttlSecondsAfterFinished defaulting to 24 hours, whichever fires first. Past the gate, pods roll and the timeline keeps moving. The index rebuild attaches differently: it starts once pods are already rolling, and its own activity is drawn straddling the point where the release reports complete, because the release proceeds regardless of whether the rebuild has finished and the rebuild keeps draining on its own clock afterward. While it drains, the affected chain's status shows as Reindexing in the Indexing detail page, and moves to Healthy once the rebuild finishes. Labels: Migration Job blocks. Index rebuild runs alongside; One obligation gates the release, one never does; Helm upgrade starts; Migration job; Pre-hook default, before pods roll; Serving pods stay untouched; A failure blocks the release here; Two clocks remove the Job; Hook policy, or a 24h TTL; Whichever fires first wins; Gate; Pods roll to the new version; Index rebuild; Not a gate, runs after pods roll; Behind the healthy deployment; Release proceeds either way; Release reports complete; Figures stay provisional; Shown as Reindexing in the; Indexing detail page, then Healthy; Keeps draining independently of the release.

The pre-upgrade hook holds the application rollout while the migration runs, and an index rebuild continues alongside without gating the release.

## What a failed migration leaves behind [#what-a-failed-migration-leaves-behind]

The Job's hook delete policy defaults to `before-hook-creation,hook-succeeded`, without `hook-failed`. A `hook-failed` policy would make Helm delete the failed Job and its pod immediately, which removes the pod-local evidence before you inspect it. Centralised logs may still retain the error. With the default policy, Helm leaves a failed migration Job and its pod in the cluster for you to inspect (`kubectl logs job/<release>-migrations`, `kubectl describe job/<release>-migrations`) until the next upgrade attempt, at which point `before-hook-creation` deletes the previous Job to make room for the new one.

Helm's hook-delete policy is not the only thing that can remove that Job. The Job template also sets a Kubernetes-native `ttlSecondsAfterFinished`, defaulting to 86400 seconds, or 24 hours, which the cluster's own TTL controller uses to delete the Job, on success or on failure, independently of anything Helm decides. If you upgrade less than once a day, that clock is the shorter one: by default you have 24 hours after a migration Job finishes to read its logs. If your process needs longer to notice a failed upgrade and pull logs, raise `dapp.migrator.ttlSecondsAfterFinished`. Changing `dapp.migrator.hookDeletePolicy` alone does not extend that window.

## Before you upgrade [#before-you-upgrade]

- Drain the waiting workflows, as [Drain waiting workflows before you upgrade](#drain-waiting-workflows-before-you-upgrade) describes.
- Read the release notes for the version you are upgrading to. A migration Job runs on every `helm upgrade` unless `dapp.migrator.enabled` is `false`, whether or not that release changed the schema, so check for a required index rebuild, which needs its own place in the change window. [Upgrade to 3.2](https://docs.settlemint.com/docs/deployment/upgrade-to-3-2) lists the changes one version step asks an operator and an integrator to make. [Supply chain and support policy](https://docs.settlemint.com/docs/deployment/supply-chain-and-support) states which release lines take patches and how a version number maps to the images it selects.
- If the application reaches Postgres through a pooler that does not track named prepared statements (PgBouncer before 1.21, statement mode, or a session-pinning proxy), set `global.dalpApp.config.database.preparedStatementCacheSize` to `0` before you upgrade. [Pooler requirements for prepared statements](https://docs.settlemint.com/docs/deployment/install/values-secrets#pooler-requirements-for-prepared-statements) has the details.
- Confirm the Postgres endpoint the new release uses is reachable and has enough headroom for the migration to complete inside the 10 minute default deadline. Raise `dapp.migrator.timeout` for a migration you expect to run longer. The migration connects direct to Postgres, so that headroom comes from your server's own `max_connections`, not from the pooler's fixed pools. [Values and secrets](https://docs.settlemint.com/docs/deployment/install/values-secrets#how-application-pods-reach-postgres) covers how to compare those pools against your server's ceiling.
- If your cluster enforces `NetworkPolicy`, confirm the migration Job's egress rule permits the Postgres port and any external Postgres host you use. That policy ships at an earlier hook weight than the Job, so it is in place before the Job needs it. If the rule is wrong, the pre-upgrade Job cannot reach Postgres, the hook fails, and the manifests that carry the fix never apply.
- Confirm `dapp.migrator.ttlSecondsAfterFinished` gives your on-call process enough time to pull logs from a failed Job before the cluster deletes it. The default is 86400 seconds (24 hours).
- Size the `--timeout` you pass to `helm upgrade`. The migration Job's deadline and that release-wide wait are separate clocks, and [Helm charts](https://docs.settlemint.com/docs/deployment/install/helm-charts#what-goes-wrong) explains how to size the wait.

## Drain waiting workflows before you upgrade [#drain-waiting-workflows-before-you-upgrade]

The [Workflow Engine](https://docs.settlemint.com/docs/concepts/settlement/workflow-engine) stores each workflow it runs as a journal of steps and replays that journal after a restart. A workflow that is waiting survives an upgrade only if the new release still reads the step names and data in its journal. The release does not check this. A wait can be long: a funding request stays open for up to its network's `pauseWindowSeconds`, which can be 7 days. See [Gas settings](https://docs.settlemint.com/docs/deployment/gas-settings). Finish or cancel the waiting work first, then upgrade. When you move from 3.1 to 3.2, also finish the work in [Finish in-flight work](https://docs.settlemint.com/docs/deployment/upgrade-to-3-2#finish-in-flight-work), because the workflow engine changes in 3.2.

1. List the unfinished workflows. Call `GET /api/v2/platform-status/workflows-list?limit=500` as a platform administrator or as the organisation's owner, once for each organisation. The Workflows detail screen on [Platform status](https://docs.settlemint.com/docs/console/organisation-settings/platform-status) shows the same list.
2. Read the `status` of each item. Treat `waiting` and `running` alike: both mean the workflow has not finished, and a workflow sleeping on a timer or an external event can show either one. The list shows unfinished items first. If `truncated` is `true`, more items exist than `limit` returned.
3. Let each unfinished workflow finish, or cancel the operation it belongs to from the Console screen that started it.
4. List again. Run `helm upgrade` when no item has status `waiting` or `running`.

Find out why a `running` item with `stalled: true` stopped before you cancel it. [Platform status](https://docs.settlemint.com/docs/console/organisation-settings/platform-status#troubleshooting) explains what a stalled workflow means.

## After you upgrade [#after-you-upgrade]

All charts in a release share one version: [Helm charts](https://docs.settlemint.com/docs/deployment/install/helm-charts#subcharts) covers why mixing subchart versions inside one release is not supported. After the upgrade, confirm the deployed state:

- `helm list` reports the release's current chart version. Confirm it matches the version you upgraded to.
- `helm history <release>` shows which revision landed, so you can compare it against the one you expected.
- Confirm both migration Jobs succeeded: `kubectl get jobs -l app.kubernetes.io/component=migrations`.
- If the release requires an index rebuild, open Data freshness on the Console's Platform status screen, then open the Indexing detail screen. Confirm that the affected chain has moved from Reindexing to Healthy. Release completion does not prove rebuild completion. See [What runs, and when](#what-runs-and-when).

## Rolling back after a bad upgrade [#rolling-back-after-a-bad-upgrade]

A Helm rollback (`helm rollback <release> <revision>`) returns your Deployments, Services, and other templated resources to a prior release's rendered manifests. It does not run a migration Job to reverse a schema change, and it does not restore database rows a completed migration already altered. Rolling back the release moves your running pods back to code that expects the older schema. If the failed or completed migration already changed the schema in a way the older application code cannot read, a Helm rollback alone leaves the older code running against a schema it cannot read.

The same holds for an index rebuild. It runs as an indexer process behind the deployment, not as a Helm hook, so a rollback has no lever over it. Rolling back does not pause or reverse a rebuild already in progress, and it does not restore the projections a rebuild has already rewritten.

Retry safety depends on the failed migration and the state it left behind. Treat a failed migration, and any rollback decision that follows it, as a stop-and-inspect event: read the Job's logs, confirm what state the schema is in, and involve whoever owns your database change process before retrying or rolling back. Do not assume a `backoffLimit` retry is always safe to repeat.

To return to the previous version after a migration changed the schema, restore the recovery point you took before the upgrade, then run `helm rollback <release> <revision>`. Records written after that recovery point are not in the restored database. [Backup and disaster recovery](https://docs.settlemint.com/docs/deployment/backup-recovery) lists what to restore and in what order.

## Frequently asked questions [#frequently-asked-questions]

### Is a `helm upgrade --timeout` failure the same thing as a failed migration Job?

No, though both can abort the same upgrade. `--timeout` bounds how long Helm waits for the whole release, migration Job and every workload's rollout together, before it gives up and reports a timeout. `dapp.migrator.timeout` (rendered as the Job's `activeDeadlineSeconds`) bounds only the migration Job itself. A migration that finishes at second 590 of its own 600-second budget can still exceed a `--timeout` sized for the rollout alone.

### Is it safe to remove the previous encryption master password as soon as the migration Job finishes?

Yes, once that Job succeeded, for the live database. Keep the previous password until every backup you may restore has aged out, because a restore from an older backup brings back rows sealed under it. Rotation is one of the migration Job's required boot steps, not a separate job, so a row that fails to rotate fails the step, and a failed required step fails the Job. A migration Job that exited successfully has already reported a clean rotation.

The step logs an `Encrypted secret rotation summary` line and a matching `KYC encryption rotation summary` line, each with `scanned`, `rotated`, `skipped` and `failed` counts. A `skipped` row is already stored under the current key, so a `rotated` count below `scanned` is normal. The count that matters is zero `failed`.

The platform re-checks the decision after you clear the value. With `ENCRYPTION_PREVIOUS_MASTER_PASSWORD` empty, the step confirms no pre-v2 data remains and fails the Job with a count of the secret rows and KYC objects still under the old key. That guard catches a premature removal at the next upgrade. What it cannot undo is destroying the key material itself, because a row still encrypted under a master password nobody holds is unreadable. [Encryption at rest](https://docs.settlemint.com/docs/deployment/install/values-secrets#encryption-at-rest) covers the two-step sequence.


# Utila setup

Source: https://docs.settlemint.com/docs/deployment/utila-setup
What the platform operator and the Utila vault admin prepare before an organisation adds Utila in the Console, how each field maps to Utila, and the limits.

Before an organisation can add Utila in the Console, the platform operator switches Utila on, and the Utila vault admin creates a service account that accepts calls only from DALP's addresses. Without the switch, Utila is not in the Console provider list. Without the service account and its allowed addresses, the first probe fails. Read [Limits](#limits) first to decide whether Utila fits.

Utila is a custody provider that holds keys in a vault and signs when its own policy allows it. In DALP, the platform files each transaction request in your Utila vault. Utila's approvers vote under your Utila policy, and the signing agent, which holds the service account's key share, signs the request designated to it. DALP tracks the request while it waits for a signature. DALP never asks Utila to sign a raw digest, the bare hash of a transaction, which Utila does not sign.

The Utila signing agent is the process that signs the requests DALP filed. Utila's own name for it is the Co-Signer, and its guide is [Utila Co-Signer](https://docs.utila.io/reference/utila-cosigner.md).

[Figure] DALP files each request in the Utila vault, Utila signs it after its approvers decide, and DALP tracks it while it waits for a signature. Two panels show who does what. In the DALP panel, DALP files the request and records it before it submits, and later tracks the request while it waits for a signature, by asking Utila for its status. In the Utila panel, the request is held for the service account, the Utila approvers vote under your policy, the customer-run Utila signing agent decides, and Utila signs it. An accent arrow runs from DALP filing the request to Utila holding it, and a quiet arrow runs from Utila signing back to DALP tracking. DALP never asks Utila to sign a raw digest. Labels: Who does what when DALP uses Utila; DALP; Files the request; Records it first, then submits; Tracks it while it waits; Asks Utila for the signature; Utila; Holds the request; Designated to the service account; Approvers decide; Then the customer-run signing agent; Utila signs; Never a raw digest.

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

- A Utila vault admin, who creates the service account.
- The platform operator, who switches Utila on and supplies the addresses DALP calls Utila from.
- An organisation Owner or a platform administrator who adds the configuration in the Console.
- The vault ID, ready before the Console step.
- The Utila network name for every network the organisation will use.

## What the Utila vault admin prepares [#what-the-utila-vault-admin-prepares]

A Utila service account is a non-human user that DALP signs in as. The vault admin creates it, and Utila describes the screens in [Creating a Service Account](https://docs.utila.io/reference/set-up-a-service-account.md).

**Step 1 of 4**

### Create the service account [#create-the-service-account]

As an admin of the vault, open Vault Settings, then Service Accounts, and add a service account. Enter a name and an email. DALP asks for the email in the "Service account email" field, so note it.

**Step 2 of 4**

### Add a public key [#add-a-public-key]

Utila controls the service account with RSA key pairs and asks you to paste the public half. You must add at least one key when you create the account, and an account holds up to three active keys. Keep the private half. You enter it in DALP as the "Service account private key (PEM)", and DALP stores it with the configuration's credentials.

A second key lets you rotate without a gap. If you add one, give its private half to DALP as the "Standby private key (PEM)". When Utila rejects the main key as no longer active, DALP authenticates with the standby key instead. The key signs the API token DALP presents to Utila, not the transactions.

**Step 3 of 4**

### Restrict the service account to DALP's addresses [#restrict-the-service-account-to-dalps-addresses]

Utila requires you to choose how the account may be accessed. It recommends trusted IPs only. Each entry is a single IPv4 or IPv6 address, and Utila does not support CIDR ranges, so the vault admin lists every address DALP calls Utila from, one by one. The platform operator provides that list, because only the operator knows which egress addresses the deployment uses. Take them from the outbound addresses of the network the DALP cluster runs in. DALP calls Utila at `https://api.utila.io` unless the organisation sets its own "API base URL", and uses port 443. A request from an address that is not listed is rejected, so a missing address shows up as a failed probe. Changing the list later needs an admin approval in Utila.

**Step 4 of 4**

### Choose the role [#choose-the-role]

Utila asks for a role in the last step, or lets you skip it. Utila's page does not list the roles, so take the role from your Utila policy: the account must be able to file and sign transactions in the vault. Assigning the role can need approval from further vault admins, so allow for that wait before you probe.

## What the platform operator switches on [#what-the-platform-operator-switches-on]

Utila is off in every deployment until the operator switches it on. Set `global.dalpApp.config.custody.providers.utila.enabled: true` in your Helm values, or `CUSTODY_PROVIDER_UTILA_ENABLED=true` outside the chart, as [Prerequisites](https://docs.settlemint.com/docs/deployment/prerequisites) describes. Until you do, "Utila custody" is not in the Console provider list, and the platform refuses a new Utila configuration. The same switch leaves existing configurations signing if you switch it off later, so switching off closes intake and does not stop signing. Quarantine a configuration to stop it.

Give the vault admin the list of addresses DALP calls Utila from.

## How each Console field maps to Utila [#how-each-console-field-maps-to-utila]

The organisation Owner fills these fields when adding the configuration, as [Organisation custody](https://docs.settlemint.com/docs/console/organisation-settings/custody) describes. Every value comes from the vault admin's steps in Utila.

| Console field | Where the value comes from |
| --- | --- |
| "Vault ID" | The ID of the Utila vault that holds the wallets. |
| "API base URL" | Optional. Leave it empty unless Utila gave you a different API address. It must be https on a `utila.io` host, on port 443, with no path. The platform refuses any other value when it probes. |
| "Networks" | One line per network: the chain ID, a space, then the Utila network name, for example `11155111 networks/ethereum-testnet-sepolia`. Utila's [Supported Blockchains](https://docs.utila.io/reference/supported-blockchains.md) page lists no network names. It points to the ListNetworks call and a support article, so take the names from there. |
| "Service account email" | The email you entered when you created the service account. |
| "Service account private key (PEM)" | The private half of the RSA key whose public half you gave Utila. |
| "Standby private key (PEM)" | Optional. The private half of a second key on the same service account. |
| "Signing agent secret" | Optional. At least 32 characters, using only letters, digits, `.`, `_`, `~` and `-`, because the signing agent sends it inside a URL. `openssl rand -hex 32` gives a valid value. The Console refuses a shorter one. |

A chain ID can have only one Utila network. The form refuses two lines with the same chain ID. A chain with no line in "Networks" cannot sign, as [The signing lanes](#the-signing-lanes) explains.

## Add the configuration [#add-the-configuration]

### Add and probe [#add-and-probe]

In the Console, open "Organisation settings", then "Custody". Select "Utila custody" in "Add custody provider", fill in the fields in [How each Console field maps to Utila](#how-each-console-field-maps-to-utila), and select "Add and probe provider". The platform probes Utila before the configuration accepts new accounts.

### Rotate when a key changes [#rotate-when-a-key-changes]

Open the configuration, change the fields that changed, and select **Probe and rotate credentials**. The platform probes the replacement before it saves it, so a failed probe leaves the stored credentials in place. Credential fields you leave empty keep their stored values. The other fields open with the stored values and are saved as the form holds them. After a rotation DALP keeps the current and the previous credential stored, and a later rotation removes older ones after a one-hour grace period.

### Stop signing through a configuration [#stop-signing-through-a-configuration]

Use "Quarantine execution", which [Organisation custody](https://docs.settlemint.com/docs/console/organisation-settings/custody) describes. Quarantine stops new execution through the configuration, and "Recover execution" reverses it. It does not cancel a request already filed in Utila. In webhook mode the signing agent gets no decision from DALP for a quarantined configuration, so that request stays pending in Utila until it expires or you cancel it there.

## The signing agent [#the-signing-agent]

The Utila signing agent is a component of the Utila CLI. [Utila Co-Signer](https://docs.utila.io/reference/utila-cosigner.md) states how the agent works:

- It polls a vault and acts only on transactions that wait for a signature and are designated to its service account.
- Transfers created in the Utila console are not sent to it. Only transactions created through the API reach it, which is how DALP files them.
- It runs in one of two modes. In sign-all mode, it signs every transaction designated to the service account. In webhook mode, it forwards each transaction to a URL and signs or cancels as the reply says. Utila suggests sign-all mode for a first test.
- In webhook mode, if the endpoint is unreachable, times out or answers with anything other than 200, the agent neither signs nor cancels. The transaction stays pending.

The "Signing agent secret" field is optional, and you need it only when a signing agent asks DALP for a decision. When you set it, DALP stores it with the configuration's credentials. A signing agent that asks DALP for a decision must present that secret. DALP gives no decision to a wrong secret, to an unknown or quarantined configuration, or to a configuration of another organisation. DALP also answers only for a request it filed itself, and tells the agent not to sign when a field of the held request differs from what DALP filed. A request DALP never filed stays pending in Utila.

The signing agent does not judge the request. In webhook mode it asks DALP, and DALP says yes to every request it filed whose fields still match. That protects against a request changed after DALP filed it. It does not protect against DALP filing a request you would refuse, so put a Utila approval policy on the vault for any request that needs a person.

To run the agent and point it at DALP, see [Utila signing agent](https://docs.settlemint.com/docs/deployment/utila-signing-agent).

## The signing lanes [#the-signing-lanes]

A signing lane is how a provider signs one kind of request on one chain. Utila declares the same lanes on every network that has a line in "Networks".

| What is signed | Lane on a chain with a bound Utila network |
| --- | --- |
| A wallet's own transactions | Utila sends the transaction from the vault. |
| A smart-account operation | Utila files the operation. |
| A typed payload | Utila signs it as typed data. |
| A request that is still pending | DALP reads its status from Utila, and can withdraw it. |
| A raw digest | Not signed. Utila signs none. |
| Any request on a chain with no network | A missing lane. The refusal names the fix: bind the chain to a Utila network, then probe the configuration again. |

For a typed payload or a smart-account operation, DALP asks Utila for the signature once a second for up to 300 seconds, then reports that signing failed and that the request may still be pending in Utila. When the request may wait for an approver, DALP checks for 15 seconds, then holds it as waiting for approval. A wallet transaction is filed and returns at once. A request that Utila declines, blocks by policy or cancels reads as rejected, and one that expires reads as expired.

## Limits [#limits]

- A chain with no network in "Networks" is refused, at creation and at "Add network". The message names the fix.
- "Networks" needs at least one line, and the networks you list are the only ones Utila can serve. To add a chain to an existing configuration, rotate the credentials with the new line in "Networks", then use **Add network**.
- The service account's allowed addresses are single addresses. A deployment with a changing egress address needs the list updated, with an admin approval in Utila, each time it changes.
- DALP holds a Utila request that waits for an approver as waiting for approval. When Utila reports the decision, by signed webhook (`POST /api/webhooks/utila`) or on DALP's own re-read, DALP resumes the request. A request still undecided at DALP's approval deadline ends as expired.
- Switching Utila off closes new intake and leaves stored configurations signing. A quarantined configuration does not execute. A rotation saves the new credentials only after they pass the probe, so a failed rotation leaves the stored ones in use.

## Troubleshooting [#troubleshooting]

**The probe fails**

Read the reported error first. An authentication failure points to the service account email or the private key:
confirm that the key is still active on the service account in Utila. A message that the vault, wallet or transaction
is not found points to the vault ID, or to a service account whose role does not cover the vault. Then confirm that
every address DALP calls Utila from is on the service account's list, because Utila rejects any other address. Correct
the value and probe again. If the reported error does not explain the failure, send the error text to your DALP
support contact. Questions about the vault, the service account or its allowed addresses go to Utila support.

**The refusal says no Utila network is bound to a chain**

The chain has no line in "Networks". Rotate the credentials with a `chain ID network name` line for it, then add the
chain with "Add network". The refusal asks you to probe again after you bind the chain.

**A request stays pending in Utila**

Utila holds a request until its approvers vote and its designated signer signs. If you use the signing agent in
webhook mode, a webhook that is unreachable, times out or answers other than 200 leaves the request pending. A request
created in the Utila console is never sent to the signing agent.

**The Console refuses the signing agent secret**

The secret is shorter than 32 characters. Enter a longer value, or leave the field empty. Use only letters, digits,
`.`, `_`, `~` and `-`, because the signing agent sends the secret inside a URL.

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

- The configuration in the "Custody" list, with its health, its networks and the accounts it accepts.
- Health that reads "Healthy", which shows that the probe succeeded and that Utila accepted the service account's key from a listed address.

## Utila sources [#utila-sources]

- [Creating a Service Account](https://docs.utila.io/reference/set-up-a-service-account.md)
- [Utila Co-Signer](https://docs.utila.io/reference/utila-cosigner.md)
- [Supported Blockchains](https://docs.utila.io/reference/supported-blockchains.md)


# Utila signing agent Helm values

Source: https://docs.settlemint.com/docs/deployment/utila-signing-agent
Deploy the customer-run Utila signing agent beside DALP: chart values, image, state, keys, and the network path that keeps the decision route internal.

Utila signs a DALP transaction only after a co-signer you run approves it. The Helm chart can run that co-signer, called the signing agent here, beside DALP. In its default mode the agent asks DALP before it signs, and DALP answers yes only when the held request matches the request DALP filed. The agent adds no judgement of its own: it catches a request changed after DALP filed it, not a request DALP should not have filed, so approval by a person belongs in your Utila policy. The agent is off by default. Before you enable it, you need a Utila provider configuration, a device id from registration, an image you built and a state store.

Use this page to render the workload and to set its values. For enrolment, key rotation and incident work, use the [Utila signing agent runbook](https://docs.settlemint.com/docs/deployment/runbooks/utila-signing-agent).

Utila ships switched off. Switch it on with `global.dalpApp.config.custody.providers.utila.enabled: true`, then add the Utila configuration in the Console with its "Signing agent secret", as [Utila setup](https://docs.settlemint.com/docs/deployment/utila-setup) describes. The agent answers only for a Utila provider configuration that holds that secret, so the agent alone signs nothing for DALP.

[Figure] The agent reaches DALP from inside the cluster, and the public edge never routes the decision route. Inside one cluster, the signing agent pod has an accent arrow to the DALP API Service. The arrow is labelled decision request. The agent also has a dashed arrow leaving the cluster to the Utila API, which holds the transactions it polls. Outside the cluster, a public edge box shows the paths it publishes, the API path and the DALP path, with an arrow to the DALP API Service. A crossed note says the internal path is not published, so a request from outside the cluster for the decision route is never routed. Labels: Your cluster; Utila co-signer pod; Signing agent; One replica; Serves nothing; API Service; DALP; Decides, never signs; asks; Network policy: no ingress to the agent.; Egress only to DNS, the DALP API pods, and the rules you add.; Public edge; Publishes the API paths; Utila; Holds the transactions; The edge does not route; the decision route.

The agent calls DALP over the cluster network, and the public edge never routes the decision route, so outside requests cannot reach it.

## What the chart renders [#what-the-chart-renders]

The `utilaSigningAgent` block in `values.yaml` is off by default. When you enable it, the chart renders these objects in the release namespace:

| Object | What it does |
| --- | --- |
| Deployment | One replica with the `Recreate` strategy. Two agents on one key share are unsafe, so the old pod stops before the new one starts. |
| ServiceAccount | No API token is mounted into the pod. |
| PodDisruptionBudget | `maxUnavailable` from `utilaSigningAgent.podDisruptionBudget.maxUnavailable`. The default is `0`. |
| NetworkPolicy | No ingress. Egress to DNS, the DALP API pods and the rules you add. |
| PersistentVolumeClaim | The agent state, when `state.location` and `state.persistence.existingClaim` are both empty. Kept on upgrade and uninstall. |
| Secret | Only when `signingAgentSecret.create` is `true`. Use it outside production only. |

The chart renders no Service for the agent, and no Ingress, HTTPRoute or Route. The agent polls Utila and calls DALP, and nothing calls the agent.

## Build the image [#build-the-image]

The chart never builds or pulls a public image. Build the image yourself from Utila's distroless Dockerfile with the Utila CLI binary from the Utila Resource Centre, then push it to a registry your cluster trusts and record the digest.

Utila's Dockerfile copies the CLI binary into a distroless non-root image and sets it as the entrypoint. The chart passes `cosigner run` as arguments to that entrypoint. The Utila co-signer guide asks for CLI version 1.5.0 or later.

Set both `image.repository` and `image.digest`. The chart refuses to render without them. An upgrade changes the digest. The new pod starts against the existing state and does not enrol again.

## Set the values [#set-the-values]

These values are required when `utilaSigningAgent.enabled` is `true`:

| Value | Meaning |
| --- | --- |
| `image.repository`, `image.digest` | The image you built. |
| `organizationId` | The DALP organisation id of the Utila provider configuration. |
| `providerConfigurationId` | The id of that provider configuration. |
| `vaultId`, `deviceId` | The Utila vault and the device id printed at registration. |
| `account` | The Utila service account email, passed as `UTILA_ACCOUNT`. |
| `serviceAccountKey` | `kmsKeyUrl`, or `privateKeySecret.name`. |
| `signingAgentSecret.existingSecret` | The Secret that holds the agent secret. Required in webhook-decision mode, unless `signingAgentSecret.create` is `true`. |
| `state.encryptionProvider` | How Utila encrypts the state. |
| `networkPolicy.egress` | Egress rules for the Utila API and your KMS or object store. Required while `networkPolicy.enabled` is `true`. |

`dapiInternalUrl` defaults to `http://dalp-api:3001`, the Service of the API pods for a release named `dalp`. Change it when your release has another name or your API Service sits on another port. It must not be empty in webhook-decision mode.

### Default invocation [#default-invocation]

The default arguments run the co-signer in webhook-decision mode. The chart adds the vault id, the device id and the decision address to the arguments `cosigner run`, so the pod runs the equivalent of:

```shell
utila cosigner run --vault-id <vault-id> --device-id <device-id> \
  --webhook-url <dapiInternalUrl>/internal/custody/utila/signing-decision/<organization-id>/<provider-configuration-id>/$(SIGNING_AGENT_SECRET)
```

The agent secret is the last segment of the address. Kubernetes expands `$(SIGNING_AGENT_SECRET)` from a Secret reference, so the secret never sits in values or in a ConfigMap. Anyone who can read the pod's process arguments can read the expanded secret. Restrict `pods/exec` and pod read access in the namespace, and never log the address. The Platform API records no request span for any request on the decision address, however the request spells it, in upper case, with doubled slashes or with percent-encoding, so the address and the secret in it do not reach the trace store.

The command and flags follow the Utila co-signer setup guide, which shows `utila cosigner run --vault-id <vault-id> --device-id <device-id> --webhook-url <url>`. Utila's Dockerfile names its binary `utilacli` in the build context. Check the flags against the CLI version you build, and use `command`, `args` and `extraArgs` to adapt the invocation.

### Sign-all mode [#sign-all-mode]

`mode: sign-all` runs the co-signer with `--sign-all-txs`. It signs every transaction designated to the service account without asking DALP. That makes the agent a signing oracle for the whole service account. Use it for first-contact testing in a vault with no value, then set `mode` back to `webhook-decision`. The chart adds a pod annotation and a warning to the Helm notes while it is set.

## State and keys [#state-and-keys]

The agent keeps its device key and key shares in a state store, encrypted with the provider you name in `state.encryptionProvider`. Utila documents `awskms://...`, `gcpkms://...` and `passphrase`. A passphrase comes from the Secret in `state.passphraseSecret`.

| Choice | Value | Notes |
| --- | --- | --- |
| Chart volume | `state.location` empty | A PVC mounted at `/state`. Back it up. |
| Object storage | `s3://bucket` or `gs://bucket` | No PVC is rendered. Use it on OpenShift, as [OpenShift](#openshift) explains. |

If you lose the state, the agent cannot sign. Recovery is a new enrolment: register a new device, have the vault admins approve it in the Utila mobile app, and download a new key share. Plan a backup policy for the state store that matches how quickly you must recover. Your recovery time is the time to restore the state store, or to enrol a new device and have the vault admins approve it.

The service account key has two sources. Prefer `serviceAccountKey.kmsKeyUrl`, which sets `UTILA_SA_KMS_KEY_URL`. The fallback `privateKeySecret` sets `UTILA_SA_PRIVATE_KEY` from a Secret. With the fallback, the key sits in the pod environment, so anyone who can read pod specs with secret access or exec into the pod can read it.

Annotate the agent's ServiceAccount through `serviceAccount.annotations`: `eks.amazonaws.com/role-arn` for IAM roles for service accounts on EKS, `iam.gke.io/gcp-service-account` for GKE Workload Identity.

The Utila CLI talks to `api.utila.io` by default. For another Utila environment, set `UTILA_HOST` in `extraEnv`.

These `UTILA_*` names are Utila's own. They are separate from the credentials you enter for the Utila provider in the Console.

## Availability [#availability]

The agent runs one replica. While it is down, no Utila transaction that DALP filed gets signed, and DALP writes through Utila wait.

The PodDisruptionBudget defaults to `maxUnavailable: 0`. A node drain that would evict the agent is blocked until you act, so writes pause only when you choose to. Set `podDisruptionBudget.maxUnavailable` to `1` to let a drain proceed. The agent then stops, and designated work waits in `AWAITING_SIGNATURE` until the pod is back.

Kubernetes has no health signal for the agent. The Utila documentation lists no liveness endpoint or command for the co-signer, so the chart defines no probe. A hung agent looks healthy to Kubernetes. The health check is the work itself: alert when work DALP designated to the service account stays in `AWAITING_SIGNATURE` longer than the bound you accept. The [runbook](https://docs.settlemint.com/docs/deployment/runbooks/utila-signing-agent) says what to do when the alert fires.

This page gives no detection time for an unreachable DALP endpoint, because DALP has not measured it against a live Utila vault. The Utila documentation says an unreachable endpoint leaves transactions pending and the co-signer asks again on the next poll.

## Network policy [#network-policy]

The chart renders a NetworkPolicy for the agent pod, on by default. It allows no ingress. Egress goes to:

- DNS.
- The DALP API pods on the port set in `dapi.service.httpPort`.
- Any rule you add in `networkPolicy.egress`.

Add egress rules for the Utila API and for your KMS or object store. Without them the agent cannot poll Utila or open its state. The agent's pod carries the label `app.kubernetes.io/component: utila-signing-agent`. The DALP API NetworkPolicy admits pods of the same release with that label. The entry matches nothing unless the chart renders the agent pod.

The decision route lives under `/internal`, not under `/api`. No Ingress, HTTPRoute or OpenShift Route published by the chart carries an `/internal` path, and the Console does not proxy it. With the default `/api` and `/dalp` edge paths, a request from outside the cluster cannot reach the route. Do not publish `/` or an unset path at the edge, because either covers `/internal` too.

## OpenShift [#openshift]

`values-openshift.yaml` pins the agent resources and leaves the user and group ids unset, so the restricted security context constraint assigns them. The pod takes its security context from the same shared settings as the other chart workloads and runs with a read-only root filesystem. The overlay clears `fsGroup`, so a PVC root can be unwritable under the assigned user id. On OpenShift, point `state.location` at object storage.

## Verify the render [#verify-the-render]

1. Run `helm template` with the agent enabled and the values above. Confirm a Deployment, a PodDisruptionBudget and a NetworkPolicy, and no Service, Ingress, HTTPRoute or Route that names the agent.
2. Confirm the decision address in the rendered arguments ends in `$(SIGNING_AGENT_SECRET)` and the secret value appears in no rendered object except a chart-created Secret.
3. Render once without `image.repository`. The render must fail with the message that names it.


# Getting started

Source: https://docs.settlemint.com/docs/getting-started
Go from a first sign-in to a first issued asset in the Console, then find the next three pages for your role.

Sign in, set up your organisation and issue a first asset in the Console, then go to the pages for your role. You work in a DALP Instance, one deployment of the platform that your institution runs or that SettleMint operates for you. If an organisation owner invited you, accept the invitation instead of creating an organisation, then go to [Issue your first asset](https://docs.settlemint.com/docs/getting-started/your-first-asset) once your wallet holds the Asset manager role.

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

- You need the Console address of your instance, which your platform operator gives you, and a way in: an invitation from an organisation owner, or the right to create an organisation.
- Roles decide what you can do once you are in. To issue an asset, your wallet needs the Asset manager role. Your wallet is the account that signs for you on the network and holds your roles and balances.
- If you created the organisation, your wallet already holds Permission manager, System manager, Asset manager, Compliance manager, Verification policy manager, Identity manager and Verification issuer, so you can issue at once.
- If you joined by invitation, you hold the roles the invitation carried, and a Permission manager grants any that are missing on [Roles and permissions](https://docs.settlemint.com/docs/console/organisation-settings/admins-and-roles).
- The optional asset class step in the tutorial needs the Permission manager, System manager or Asset designer role.

## Three steps [#three-steps]


  - [1. Create your account and organisation](https://docs.settlemint.com/docs/getting-started/onboarding): Sign in, name your organisation, choose its network and custody and deploy.
  - [2. Issue your first asset](https://docs.settlemint.com/docs/getting-started/your-first-asset): Issue an instrument from a template, mint tokens and transfer part of the balance.
  - [3. Choose your path](https://docs.settlemint.com/docs/getting-started/where-next): Find your goal, the next three pages and the Console role for each kind of work.


## Two ways to act on the same asset [#two-ways-to-act-on-the-same-asset]

The Console is the web application your team signs in to and works in by hand. The [Platform API](https://docs.settlemint.com/docs/api-reference) lets your own software issue, mint and transfer without a person at each step. Both act on the same token contract, and the transfer rules run inside that contract. An ordinary transfer that fails a rule is refused on chain and no balance changes, whichever surface sends it, which is transfer-path compliance. A custodian's forced transfer and other recorded paths skip some checks, as [Transfer-path compliance](https://docs.settlemint.com/docs/concepts/compliance-and-identity/transfer-path-compliance) lists. Every instrument is issued from a template as the same composable token. It can move through design, issuance, servicing and redemption. Servicing covers mints, transfers and income payments, and an instrument is issued halted until it is launched. These stages are its asset lifecycle.

[Figure] The Console and the Platform API act on the same token contract. The Console and the Platform API act on the same token contract. The contract checks its transfer rules, so they apply whichever surface moves the tokens. An asset is designed from a template, issued halted until it is launched, serviced with mints, transfers and income payments, and redeemed. Labels: Console; Web application; Platform API; Connected software; One token contract per asset; On chain; Its rules check transfers; Issuance to redemption; Design; template,; facts, rules; Issue; deployment,; token, roles; Halted; until launched,; no supply; Service; mint, pay,; transfer; Retire; redeem,; burn units; Both surfaces reach every stage of an asset's life.; Use the Console when a person acts, and the Platform API when your own system acts.

The Console and the Platform API act on one token contract, which checks its transfer rules for either surface at every stage of the asset's life.

To see the eight systems and how a write moves through them, read [What DALP is](https://docs.settlemint.com/docs/platform) after your first asset. Start with [Create your account and organisation](https://docs.settlemint.com/docs/getting-started/onboarding).


# Account and organisation

Source: https://docs.settlemint.com/docs/getting-started/onboarding
Deploy a new organisation in four steps, knowing that its name, network and wallet choice are final, and recover a deployment that fails or stalls.

A new organisation cannot hold settings, members or assets until the platform deploys its on-chain system on a network: the registries, permissions, compliance rules and asset templates that every later action uses. The Console's organisation setup collects what that deployment needs in four steps, deploys it, and shows each phase until the organisation is ready. If an organisation owner invited you, open the invitation link instead: it takes you to that organisation's join screen, and you skip this setup.

[Progress] Step 1 of 2: Account and organisation (you are here). Step 2 of 2: Issue your first asset

An organisation is the unit that owns settings, members, roles and assets in the Console. A network is one blockchain the platform connects to, named by its chain ID.

[Figure] The four steps of organisation setup. Sign in, then work through the four setup steps in order. Organisation: name, currencies, languages, default currency, network and accounts and gas. Custody provider: the provider the platform signs with, skipped when the organisation already has one. Your account: the managed account that signs the deployment. Deploy: the platform deploys the organisation's system and pauses for custody approval or funding when needed. When the deployment completes, open the dashboard in the new organisation. Labels: 1. Organisation; Details, network, gas; 2. Custody provider; Who signs for you; 3. Your account; Managed signing; account; 4. Deploy; System on the network.

The setup runs in four steps: Organisation, Custody provider, Your account and Deploy, and the deploy step can pause for custody approval or funding.

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

- You are signed in to a Console account.
- Your account has no active organisation and no pending invitation, so the Console opens the setup.
- The person who deploys is an owner of the organisation or a platform administrator.
- You know which network, currencies and custody provider to use, and how much native currency the network needs for gas, because the deployment pauses until its wallets are funded. Your platform operator, the team that runs your DALP deployment, tells you.

The Console opens the setup when your account has no active organisation and no pending invitation. If you have a pending invitation, the Console opens that invitation instead. If your email address is unverified, it opens "Verify your email to see your invitation" with "Send a new link" and "Sign out".

The person who deploys must be an owner of the organisation or a platform administrator, the role that administers the whole DALP deployment. When your platform lets only platform administrators create organisations, everyone else sees "Ask a platform admin to create your organisation" instead of the deploy button, with the reason "Only a platform admin can create an organisation on this platform." On a deployment that runs a single organisation and already has one, the Console signs a new account out instead of opening the setup.

Ask your platform operator, the team that runs your DALP deployment, which network, currencies and custody provider to use, and how much native currency the network needs for gas, because the deployment pauses until its wallets are funded. The setup shows only networks that are enabled and ready for a first deployment. When the platform offers no choice of network at onboarding, it shows the platform default network only.

If someone invited you to an existing organisation, your invitation link opens that organisation's join screen instead, where you can accept or reject the invitation. If the invitation was cancelled or has expired, the Console opens this setup form with a notice that says so and names the organisation when it can. Ask the person who invited you to send a new one. A link that was already accepted, declined or cancelled, or that has expired, no longer offers sign-up: it says what happened and offers "Sign in" instead.

## What a new organisation sets up first [#what-a-new-organisation-sets-up-first]

The setup asks for these, in this order. The first step, "Organisation", covers items 1 to 3, and items 4 to 6 are the other three steps. Once you select "Continue" on the first step, the name, the network and the "Accounts and gas" choice cannot change, so settle them with your platform operator before you start.

1. **Organisation details**: the name, the currencies the organisation works with, its default currency, and the languages its members can choose.
2. **Network**: the network the organisation's first system deploys on. It becomes the organisation's default network and does not change later.
3. **Accounts and gas**: the kind of wallet the organisation's users hold, and who pays the network fee, called gas, on the first network.
4. **Custody provider**: the provider the platform signs with for this organisation. The step is skipped when the organisation already has one.
5. **Your account**: the managed account that signs the deployment.
6. **Deploy**: the platform deploys the system. When a wallet it needs is short of funds, the deployment pauses until you fund it.

After the deployment, set up your transaction PIN and recovery codes, submit your own KYC information, and invite your team. [What to do next](#what-to-do-next) lists each.

## Steps [#steps]

**Step 1 of 6**

### Open the organisation setup [#open-the-organisation-setup]

Sign in. The Console opens "Set up your organisation". The track at the side lists the four steps: "Organisation", "Custody provider", "Your account" and "Deploy". A summary panel repeats your choices as you make them.

If you leave the setup and come back, the Console opens the step you have not finished. Reloading the page during a deployment returns to its progress.

**Step 2 of 6**

### Enter the organisation details [#enter-the-organisation-details]

Before you select "Continue" on this step, check the name, currencies, network and "Accounts and gas" choice. "Continue" creates the organisation and makes it your active organisation. After that, the name, the network and the "Accounts and gas" choice cannot change in the setup, and an organisation on smart wallets cannot switch back to EOA wallets.

![Set up your organisation form with Organisation name, Currencies, Languages, Default currency, Network and Accounts and gas, beside a summary panel](https://docs.settlemint.com/docs/screenshots/getting-started-organisation.light.en.webp)

[Screenshot] The "Set up your organisation" form at the first of four steps.

In the screenshot, "Currencies" has five currencies chosen, all ten "Languages" are on, "Default currency" is set to "Euro (EUR)", "Network" to local, and "Accounts and gas" to "Smart wallets, Paymaster-paid". "Organisation name" is still empty, so "Continue" stays unavailable and shows the reason beside it. The side panel lists the values chosen so far.

Fill in the form:

- **Organisation name**: up to 32 characters. Members and invitees see this name. A name that another active organisation already uses is refused with "Another organisation already uses this name. Choose a different name."
- **Currencies**: the currencies your organisation works with. The platform creates an exchange-rate feed for each currency other than the default currency. You can add currencies later, but you cannot remove one once it is enabled.
- **Languages**: the languages members can choose in the Console. English is always on. You can change this later on [Languages](https://docs.settlemint.com/docs/console/organisation-settings/languages).
- **Default currency**: the organisation's base currency. Pick at least one other currency in "Currencies", because each exchange-rate feed pairs the default currency with another one.
- **Network**: the platform default network is preselected and marked "Default". With one network available, the form shows it without a choice. The note under it reads "This organisation's first system deploys on this network, and it becomes the organisation's default. It can't be changed later." To work on more networks later, an owner turns on multi-network support on [Organisation networks](https://docs.settlemint.com/docs/console/organisation-settings/networks).

"Accounts and gas" sets two things at once: the kind of wallet the organisation's users hold, and who pays gas on the network you chose. The options read as a wallet kind and a payer:

- **Smart wallets, Paymaster-paid**: users get smart wallets, contract wallets with approvals and recovery. On networks where the organisation's paymaster is set up, the paymaster pays the gas, so users need no gas balance. The first network ends on Paymaster-paid when its deployment leaves the paymaster with a ready signing key, and on Self-pay otherwise. On a network that charges gas, the deployment also asks for the paymaster's deposit, unless the network funds it on its own. The option appears only when the platform enables account abstraction, and it is then the default. Its note reads "You cannot switch back to EOA wallets later."
- **EOA wallets, Relayer-paid**: users keep EOA wallets, standard wallets controlled by one private key, and an organisation wallet called the relayer pays their gas. Fund the relayer before users transact. On a network that charges no gas, the option adds a note that users can already send from their own wallets, so Self-pay is simpler.
- **EOA wallets, Self-pay**: each user pays gas from the balance of their own wallet. It is the default when the platform does not enable account abstraction.

The platform refuses smart wallets on a network that cannot run them, which is when account abstraction is off or the network has no paymaster set up. **Continue** then fails and nothing is created. The API answer names the network and the reason. Pick an EOA option for that network, or ask your platform operator to set up account abstraction on it first.

The wallet kind applies to the whole organisation. Who pays gas is a setting for each network, and each network you add later starts on Self-pay. An organisation on EOA wallets can move to smart wallets later on [Transaction funding](https://docs.settlemint.com/docs/console/organisation-settings/transaction-funding#change-the-wallet-type), and an owner changes the gas payer for each network on the same page. Whatever you choose, the deploying wallet pays for the transactions that deploy the organisation.

When "Continue" is disabled, the reason shows beside it. The form shows one reason at a time, in this order:

1. "Enter an organisation name before you continue."
2. The name length rule.
3. "Fix the organisation name before you continue."
4. "Pick at least one currency before you continue."
5. "Pick a default currency before you continue."
6. "Add a currency other than the default currency."
7. "No deployment network is available yet. Reload the page and try again."

When the network list is empty, the form shows "No network available" and asks you to contact your platform operator.

Select "Continue".

**Step 3 of 6**

### Set up the custody provider [#set-up-the-custody-provider]

The Console shows "Organisation custody provider" with the line "This organisation needs a provider the platform can sign with. It deploys the organisation and runs its automation." A custody provider holds the signing keys for the organisation's accounts. A browser wallet signs only while its owner is present, so the setup offers managed providers only.

The Console skips this step when the organisation already has a managed custody provider enabled.

Under "Set up the custody provider":

- **Provider**: choose the provider your platform operator named.
- **Credentials**: "Held by the platform" means the organisation signs through the provider account whose credentials the platform operator configured, so you enter nothing. The keys stay with the provider, or with the platform when the provider is the local key store. "Supplied by this organisation" connects your organisation's own workspace at that provider, and the form asks for the credentials the provider issued.
- **Exclusive to this organisation**: shown for credentials your organisation supplies. When on, keys from this configuration are used only in this organisation, and accounts from other organisations cannot use it. You cannot change it after creation.

The line "Deploys on" names the network you chose and EVM. The note under the form reads "This configuration's provider and credential source can't change later. You can add other providers and accounts after deployment." [Custody](https://docs.settlemint.com/docs/console/organisation-settings/custody) covers the providers you add later.

Select "Continue". The button reads "Checking the connection…" while the platform checks the provider. When the check fails, the form shows the provider's error with "Try again". Correct the details, then select "Try again".

**Step 4 of 6**

### Create your account [#create-your-account]

The Console shows "Your account in" followed by the organisation name, with the line "You act in" the organisation "with this account." The account card is marked "Managed": the custody provider you chose in the previous step creates and holds the key, and the platform asks it to sign for you. With the local key store, the platform holds the key itself.

Select "Create account". The card reads "Creating your account…" and then "Yours. Held by" the provider name.

If you already hold accounts that can act in this organisation, the Console shows "Choose how you act in" the organisation name. Select "Use this account" on the one to act with, or "Create a new account". An account that signs with your own browser wallet cannot deploy, because the organisation needs an account the platform can sign with.

When your managed account belongs to another network, the step reads "Your managed account is linked to another network. Add a managed account for the selected deployment network."

**Step 5 of 6**

### Deploy the organisation [#deploy-the-organisation]

The Console shows "Deploy" followed by the organisation name, and "Deploys the organisation's system on" the network name. The "Signing account" card shows the provider, the "Managed" and "Yours" badges, the account's signing address, and its smart wallet address when it has one. The note reads "This account signs the deployment."

The "Modules" group lists each licensed module your deployment offers, such as "Primary market", "Secondary market" and "Client portal". Every module is ticked. Untick the ones your organisation will not use. A module you leave unticked is switched off for the organisation, and you can change this later in Organisation settings. [Switch application layers on or off](https://docs.settlemint.com/docs/deployment/install/values-secrets#switch-application-layers-on-or-off) lists which modules a deployment offers.

A completed deployment cannot be run again or undone, and the organisation keeps its default network. Select "Deploy organisation".

The Console shows "Deploying your organisation" with "This may take a few minutes. You can safely stay on this page." The progress tree lists each deployment phase with its status, and the reason when a phase fails. The deployment runs on the server, so closing the page does not stop it.

While the deployment runs, it can pause in three ways:

- **Custody approval**: when your custody provider holds a transaction for approval, the phase shows "Pending approval" with "An approver must accept this step in your custody admin before the deploy can continue." An approver accepts it in the provider's own admin console. Custody approval explains the approval model.
- **Funding**: every transaction pays gas in the network's native currency. When a wallet the deployment needs, such as the "Organisation creator wallet", cannot pay, the Console shows "An account for your new organisation needs funds". It names the recommended amount, the network and the current balance.
  - **Send the funds**: the organisation has no other members, so you send them yourself. Select the confirmation that you are sending the stated currency on that network to show the funding address, then send the funds. The setup resumes on its own once they arrive, and "Funds received, continuing" confirms it. The funds become the organisation's money.
  - **Funding window**: when the request has a deadline, the dialog shows when the window closes and how much time is left. If the funds do not arrive in time, it reads "Funding window expired" with what to do next, such as "Fund the address below, then try again." Arrange the funds before you deploy.
  - **Full batches**: the request can also name a larger balance that lets the deployment send its registrations in full batches. With less, it sends smaller batches, and the gas fees paid stay the same. [Transaction funding](https://docs.settlemint.com/docs/console/organisation-settings/transaction-funding) covers funding requests in full.
- **Background setup**: when the indexer, the service that reads the chain into the platform, is catching up, the Console shows "Almost ready" and checks again after a countdown that follows the retry interval the platform suggests, at most about 30 seconds. Select "Check now" to check at once. The deployment continues on its own when the indexer is ready.

**Step 6 of 6**

### Continue to the dashboard [#continue-to-the-dashboard]

When the deployment completes, the Console shows "Organisation deployed. Finish your setup" with your wallet and a list of next steps. Next to "Go to dashboard", the list shows the setup items you still have open, such as "Set your transaction PIN" and "Save your recovery codes", and "Invite team members" when there is room. Select "Go to dashboard". The new organisation becomes your active organisation.

## What to do next [#what-to-do-next]

- **Set your transaction PIN and recovery codes**: select "Set your transaction PIN" on the completion screen, or open "Security" from the account menu at the top right. The Console also asks for this before your first signing action. [Security](https://docs.settlemint.com/docs/console/my-account/security#wallet-verification) explains wallet verification.
- **Submit your KYC information**: open Profile from the account menu and fill in Information. [Profile](https://docs.settlemint.com/docs/console/my-account/profile) covers the review.
- **Invite your team**: select "Invite team members", or later open "Organisation participants", then "Users". [Roles and permissions](https://docs.settlemint.com/docs/console/organisation-settings/admins-and-roles) covers roles.
- **Add networks**: an owner adds more networks on [Organisation networks](https://docs.settlemint.com/docs/console/organisation-settings/networks).
- **Issue an asset**: continue with [Issue your first asset](https://docs.settlemint.com/docs/getting-started/your-first-asset).

## When the deployment fails [#when-the-deployment-fails]

A failed deployment shows "Deployment failed", the error, and a reference. Two choices follow: "Try again", described as "Reload and try the deployment again", and "Contact support". "Contact support" opens an email to SettleMint support at support@settlemint.com on every instance, whoever runs it. When your institution runs its own support desk, give the reference to your platform operator instead.

Select "Try again". The Console starts a new attempt straight away with the stored default currency, currencies, network and "Accounts and gas" choice, and shows the progress screen. The retry signs with the custody account you already hold on that network, or with a custody provider that covers it. When the earlier attempt already created the organisation's system on chain, the retry continues on that system instead of creating a second one.

When the Console no longer has the saved details, it says "We don't have your organisation's saved details to redeploy. Fill the form in and deploy again." The form then opens as "Finish setting up your organisation" with "Your previous attempt didn't complete. Pick a currency to try again." The name stays locked. When the earlier attempt recorded them, the account choice reads "Set during your earlier attempt. You cannot change it on retry." and the network reads "Chosen during your earlier attempt. It can't be changed on retry."

A retry is refused while another attempt for the organisation is running, and for an organisation that already finished its setup.

A smart-wallet deployment also checks the balance of the organisation's bundler, the wallet that sends its smart account bundles. When it is below target, the platform raises a funding request for the operator to fulfil. The platform sizes that funding request from the network's live fee quote. When the network has no fresh quote, the deployment fails at that step with a retryable error saying the network's fee pricing is unavailable, and does not continue with an unfunded bundler. Ask your platform operator to restore the network's RPC and fee policy, then select "Try again".

## When the deployment stalls [#when-the-deployment-stalls]

A deployment that stops reporting does not stay on the progress screen for ever. The platform checks for stalled deployments every minute. A deployment that has reported nothing for 90 seconds, with no running process behind it, is marked failed with the reason "The deployment stopped reporting and no execution is running it." The Console then shows the failed screen, and "Try again" starts a new attempt as described above.

When the connection to the progress stream drops, the Console reconnects and reads the deployment's state again, so a reload is not needed.

The failed screen appears only when the platform reports that the deployment failed. A progress stream that drops or fails before the deployment reports a result never shows it. The Console keeps the steps it showed, adds "Reconnecting to live updates", and reads the deployment's status every 10 seconds. While the platform still runs the deployment, the Console reconnects and shows the current step. When the platform reports it complete or failed, the Console shows that result. When the platform holds no deployment for the organisation, the Console returns to the deploy step so you can start one. Accepting an invitation follows the same rules.

## Create another organisation [#create-another-organisation]

On a platform that runs several organisations, a person who already runs one can set up another. Open the account menu at the top right, point at Organisation and choose "Create organisation". The menu offers it when creating organisations is not limited to platform administrators, or when you are a platform administrator.

The Console opens the same setup with an editable name and the same four steps. Opening it changes nothing until you submit the first step.

- Before you submit the first step, "Cancel" returns you to the dashboard.
- After the first step and until the new organisation is deployed, "Switch organisation" takes you back to your other organisations. It shows on the custody provider, account and deploy screens and on the failed screen.
- Starting the setup again resumes your unfinished organisation instead of creating a second one. Until it is deployed, it stays in the Organisation submenu of the account menu, and choosing it resumes its setup.

## When your organisation is archived [#when-your-organisation-is-archived]

A platform administrator can archive an organisation. When every organisation you belong to is archived, the Console shows "Your organisation is archived" with "A platform administrator archived your organisation and can restore it." and "Sign out". When you may create an organisation, it also offers "Create an organisation", and the setup form then shows "You are not a member of an active organisation. Create one, or ask a platform administrator to restore yours."

The screen does not refresh on its own. After a platform administrator restores the organisation, reload the page or sign in again.

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

- The completion screen confirms the deployment.
- The dashboard opens in the new organisation, which is your active organisation in one DALP Instance, the deployment of the platform that your institution runs or that SettleMint operates for you.


# Sign-in codes

Source: https://docs.settlemint.com/docs/getting-started/sign-in-codes
Email and text message codes are a second factor at Investor portal sign-in, offered when the account and its organisations allow them.

An investor who has turned on two-factor authentication can have more than one way to finish signing in. Beside an authenticator app, the platform accepts a six-digit code sent to the account's email address, or by text message to a verified phone number already stored on the account, when the investor's organisations allow it. Both are second factors: the password is still the first. They are off by default, and an organisation owner turns them on through the API, so this page serves the owner who sets the methods and the support team that helps investors sign in.

The codes belong to Investor portal sign-in. Console sign-in takes an authenticator code or a backup code only. The Console's [Security](https://docs.settlemint.com/docs/console/my-account/security) page and the Investor portal's own Security screen set up an authenticator app and passkeys, and neither offers a control for email and text message codes.

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

- The account has two-factor authentication enabled. An investor turns it on with an authenticator app, or with the codes themselves through the authentication API: `POST /api/auth/two-factor/enable` from their signed-in session, with their `password` and `method: "otp"`.
- Every organisation the investor belongs to allows the method. An organisation owner sets that through the API, as [Which methods an organisation allows](#which-methods-an-organisation-allows) shows, and a member sees a method only when all their organisations allow it. Both code methods are off by default.
- For a text message, the account has a verified phone number. No screen and no API route records or verifies a phone number, so an account offers the text message method only when a verified number is already stored on it.
- For a text message, the deployment's SMS provider is configured. Without a provider configured, the send answers `TWO_FACTOR_DELIVERY_FAILED` and no code arrives.

## Steps [#steps]

**Step 1 of 4**

### Sign in with the password [#sign-in-with-the-password]

Open the Investor portal sign-in screen and enter the email address and password. The platform accepts the password and, because two-factor is on, answers a challenge instead of a session. The Portal opens "Two-factor authentication" over the sign-in page.

When the account allows more than one method, the dialog shows a button for each: "Authenticator app", "Email code" or "Text message", with the first one selected. With one method available it shows that method with no choice to make. When no method is available, the sign-in screen reads `No enabled two-factor method is available for this account. Ask an organization administrator to enable one.` and opens no dialog.

**Step 2 of 4**

### Choose where the code goes [#choose-where-the-code-goes]

Select "Email code" to receive the code at the account's email address, or "Text message" to receive it at the verified phone number. The dialog reads `Choose where to receive your 6-digit sign-in code.`

Select **Send code**. "Verify" cannot be selected until a code has been sent.

**Step 3 of 4**

### Enter the code [#enter-the-code]

Type the six digits into `6-digit sign-in code` and select **Verify**. A correct code opens the portal. A wrong one shows "Invalid code" and counts towards the attempt budget. A code older than five minutes shows "OTP has expired".

The email carries the same code in its body and in an `OTP-Token` header bound to the address of the sign-in screen, so a mail client can offer to fill it in on that site. The header is written only for an https address or a loopback address. Any other address sends the mail without it.

**Step 4 of 4**

### Send another code [#send-another-code]

Select "Resend code" after the wait. The button reads "Resend code in" the remaining seconds while the wait runs, and the platform refuses an earlier request with `429 Too Many Requests` and `TWO_FACTOR_RESEND_THROTTLED`.

A new code replaces the previous one. The older code stops working the moment the new one is sent.

## What each code obeys [#what-each-code-obeys]

| Rule | Value |
| --- | --- |
| Length | Six digits |
| Lifetime | Five minutes from the send |
| Uses | One. A code that was accepted cannot be accepted again. |
| A second send | Replaces the earlier code and ends its life |
| Wait between sends | 30 seconds |
| Wrong codes before a lock | Five within 15 minutes. The sixth attempt is refused. |
| Lock length | 15 minutes |

Wrong email codes, text message codes, authenticator codes and backup codes share the same budget. The sixth wrong code in the window is refused before its code is checked, with `429 Too Many Requests` and code `LOGIN_TWO_FACTOR_LOCKED`, and the answer states how many seconds remain. A correct code does not clear a lock that is already in force. The lock ends when its time passes.

## Which methods an organisation allows [#which-methods-an-organisation-allows]

A method is available only when it is allowed by every organisation the investor belongs to. The platform intersects the policies: one organisation that leaves email codes out removes them for a member who belongs to it, however the other organisations are set. An archived organisation does not count.

New organisations start with the authenticator app alone. No Console screen changes the set. An organisation owner changes it with `POST /api/auth/organization/update` from a signed-in session, since an API key is refused on this route. The body sends `allowedTwoFactorMethods` as a JSON array of `totp`, `email-otp` and `sms-otp`, written as a string, and applies to the active organisation unless it names another with `organizationId`:

```json
{ "data": { "allowedTwoFactorMethods": "[\"totp\",\"email-otp\"]" } }
```

An empty array or an unknown method is refused with `400 Bad Request` and `INVALID_TWO_FACTOR_METHODS`. A saved change is an entry on the organisation's [Audit trail](https://docs.settlemint.com/docs/console/reporting/audit-trail) with the methods before and after.

Note (Keep totp in the list while members sign in to the Console): Console sign-in accepts only an authenticator code or a backup code, and both are refused with `TWO_FACTOR_METHOD_DISABLED` when an organisation the member belongs to leaves `totp` out. A member with two-factor on then cannot finish Console sign-in.

The platform decides which buttons the dialog shows. It returns a method only when the organisation policies allow it and the account can receive it, so a text message disappears from the dialog as soon as the phone number stops being verified.

## What each failure means [#what-each-failure-means]

| Answer | Code | What it means | What to do |
| --- | --- | --- | --- |
| `403 Forbidden` | `TWO_FACTOR_METHOD_DISABLED` | The organisation policy does not allow that method, or the account cannot receive it. | Ask an organisation owner to allow it, or choose another method. |
| `403 Forbidden` | `TWO_FACTOR_METHOD_UNAVAILABLE` | No allowed method is one the account can receive. The sign-in screen says so. | An organisation owner allows a method the account can receive. |
| `400 Bad Request` | `TWO_FACTOR_METHOD_REQUIRED` | The request named no method. | Choose a method before sending a code. |
| `429 Too Many Requests` | `TWO_FACTOR_RESEND_THROTTLED` | A code was requested less than 30 seconds ago. | Wait the seconds the answer names. |
| `429 Too Many Requests` | `LOGIN_TWO_FACTOR_LOCKED` | Five wrong codes were entered inside the window. | Wait for the lock to pass, then request a new code. |
| `503 Service Unavailable` | `TWO_FACTOR_DELIVERY_FAILED` | The email or the SMS provider did not accept the message. | Send again at once. |

When delivery fails, the platform discards the code it could not deliver and lifts the 30 second wait, so the investor can send again at once and loses no attempt.

## Troubleshooting [#troubleshooting]

**The dialog offers only the authenticator app**

At least one organisation the investor belongs to leaves both codes out, so check each membership, not only the
organisation the investor is working in. When the organisations allow text messages but not email codes, the account
also needs a verified phone number. An organisation owner changes the policy.

**Verify says Invalid code or OTP has expired**

"Invalid code" means a wrong code, including an older code that a newer send replaced, and it counts towards the
attempt budget. "OTP has expired" means the code passed its five minutes. Request a new code and enter the latest one.
If five codes were already wrong, the lock answers with the seconds left.

**No email arrives**

Check the address on the account, then send another code after the 30 second wait. A send that failed on the provider
side answers `TWO_FACTOR_DELIVERY_FAILED`, costs no attempt and can be repeated at once.

**No text message arrives**

SMS needs a verified phone number and a configured SMS provider on the deployment. A number that is present but
unverified is treated as absent, and the method is not offered. Confirm with the deployment operator how the number is
stored before you promise an investor this method.

**The investor wants codes instead of an authenticator app**

Turn two-factor on with `POST /api/auth/two-factor/enable`, the account password and `method: "otp"`, then have every
organisation the investor belongs to allow `email-otp`, `sms-otp`, or both. The Console's Security page sets up the
authenticator app and passkeys and does not manage these codes.

## Frequently asked questions [#frequently-asked-questions]

### Is this the same two-factor authentication as the Console's Security page?

Yes for the authenticator app. Both Security screens set up the same authenticator app and passkeys on the same account. Email and text message codes finish sign-in at the Investor portal only, and the authentication API turns them on for an account.

### Does a code replace the password?

No. The password is checked first, and the code answers the challenge that follows. A wrong password never reaches the code step.

### Can an investor turn a policy-enabled method off for their own account?

No. The platform offers every method that all the investor's organisations allow and that the account can receive. An investor who does not want codes asks an organisation owner to change the policy.

### Do sign-in codes work when the deployment uses single sign-on?

Yes. With an identity provider configured, the Console signs in only through the provider, but the Investor portal keeps password sign-in for investors, and the codes finish that sign-in as described here. [Single sign-on](https://docs.settlemint.com/docs/deployment/sso#investor-portal-sign-in-under-single-sign-on) covers what changes.

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

- The Portal opens on the page you asked for.
- No code from an earlier send is accepted afterwards.
- The account's session list shows the new session's device, organisation and expiry, like any other session.


# Where to go next

Source: https://docs.settlemint.com/docs/getting-started/where-next
Pick the path that matches your work in DALP: its goal, the next three pages to read, and the Console role you need.

Pick the path that matches your work. Each path names its goal, the three pages to read next, and the Console role it needs in your DALP Instance. Most roles are granted to your wallet, the account that signs for you on the network, and a Permission manager grants them on [Roles and permissions](https://docs.settlemint.com/docs/console/organisation-settings/admins-and-roles). Two are account roles: an Owner of the organisation manages its members and settings, and a Platform admin runs the whole deployment. Role names here match the labels the Console shows.

## Run assets day to day [#run-assets-day-to-day]

Goal: issue assets, manage their supply and service them through their asset lifecycle.

1. [Issue a new asset](https://docs.settlemint.com/docs/console/asset-management/issue-new-asset)
2. [All assets](https://docs.settlemint.com/docs/console/asset-management/all-assets)
3. [Asset lifecycle in the Console](https://docs.settlemint.com/docs/console/asset-lifecycle)

Console role: Asset manager to issue. The wallet that issues an asset receives Permission manager, Governance, Supply management and Emergency on that asset. Supply management mints and burns, and Emergency pauses the token.

## Onboard and verify investors [#onboard-and-verify-investors]

Goal: register participants, verify them and decide which rules an asset enforces on every transfer.

1. [Verify a participant](https://docs.settlemint.com/docs/console/participants/verify-a-participant)
2. [Policy templates](https://docs.settlemint.com/docs/console/compliance/policy-templates)
3. [Transfer-path compliance](https://docs.settlemint.com/docs/concepts/compliance-and-identity/transfer-path-compliance)

Console role: Identity manager to register identities, Verification issuer to attach verifications, and Compliance manager to configure compliance modules and global controls.

## Administer the organisation [#administer-the-organisation]

Goal: invite people, grant roles, connect custody and require maker-checker approval for sensitive changes.

1. [Roles and permissions](https://docs.settlemint.com/docs/console/organisation-settings/admins-and-roles)
2. [Roles and segregation of duties](https://docs.settlemint.com/docs/concepts/compliance-and-identity/roles-and-segregation-of-duties)
3. [Custody](https://docs.settlemint.com/docs/console/organisation-settings/custody)

Console role: Owner to invite members and change settings, and Permission manager to grant and revoke on-chain roles.

## Connect your own software [#connect-your-own-software]

Goal: call the Platform API from your own software, and receive events without polling.

1. [Authentication and API keys](https://docs.settlemint.com/docs/api-reference/guides/authentication-api-keys)
2. [Idempotency and async settlement](https://docs.settlemint.com/docs/api-reference/guides/idempotency-async-settlement)
3. [Webhooks](https://docs.settlemint.com/docs/api-reference/guides/webhooks)

Console role: none of its own. You create an API key on [API keys](https://docs.settlemint.com/docs/console/my-account/api-keys), and the key acts with the roles of the person who created it, within the read or read-write scope you set for the key. [Transaction lifecycle](https://docs.settlemint.com/docs/concepts/settlement/transaction-lifecycle) explains how the platform runs each request that changes state on the network.

## Deploy and run the instance [#deploy-and-run-the-instance]

Goal: install DALP in your cluster, connect its networks and keep it running through upgrades.

1. [Prerequisites](https://docs.settlemint.com/docs/deployment/prerequisites)
2. [Helm charts](https://docs.settlemint.com/docs/deployment/install/helm-charts)
3. [Upgrades and migrations](https://docs.settlemint.com/docs/deployment/upgrades-migrations)

Console role: Platform admin for the network catalogue and the [Platform admin](https://docs.settlemint.com/docs/console/platform-admin) screens. With local sign-in, the first account created on a fresh instance takes that role, and every later sign-up is a member. Create the first account before the Console is reachable from outside your network. With an identity provider, a claim from the provider decides who is a Platform admin.

## Review the platform [#review-the-platform]

Goal: assess how DALP is built, which controls a request passes, and who can reach the instance.

1. [What DALP is](https://docs.settlemint.com/docs/platform)
2. [Security and compliance posture](https://docs.settlemint.com/docs/deployment/security-compliance-posture)
3. [Hosting and access](https://docs.settlemint.com/docs/deployment/hosting-and-access)

No Console login is needed to read these pages. To review a running instance, ask for the Auditor role, which gives view-only access to permissions, identities, audit logs and system state. The [audit trail](https://docs.settlemint.com/docs/concepts/records-and-evidence/audit-trail) records state changes and sensitive reads.


# Issue your first asset

Source: https://docs.settlemint.com/docs/getting-started/your-first-asset
Issue an instrument from a template, mint its tokens, and transfer part of the balance to a recipient in the Console.

Follow one instrument from setup to its first transfer in the Console. You issue the asset from a template, mint tokens to a holder, and transfer part of that balance. An optional step adds your own asset class. This path covers the opening stages of the asset lifecycle, which continues through servicing and final redemption.

[Progress] Step 1 of 2: Account and organisation. Step 2 of 2: Issue your first asset (you are here)

Issuing, minting and transferring each depend on the state the step before leaves.

[Figure] The state after each step in this tutorial. Confirm the organisation, optionally add an asset class, and issue an asset from a published template. Launch at creation or through the Actions menu before minting. Mint to an eligible holder, then transfer to an eligible recipient. Labels: 1. Organisation; confirmed; scope for; the rest; 2. Asset class; optional,; for your own; templates; 3. Issued asset; one contract; from a template,; launched to mint; 4. Minted; a balance sits; in one wallet; 5. Transferred; second wallet; has part of it; Issue, mint and transfer run in that order. The asset class is optional.

Confirm the organisation, optionally add an asset class, issue and launch from a template, then mint to a holder and transfer part of the balance.

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

- You completed [Create your account and organisation](https://docs.settlemint.com/docs/getting-started/onboarding).
- Your wallet holds the Asset manager role.
- You set up your transaction PIN or transaction code.
- Your organisation has a published instrument template to select.
- The first holder you mint to and the transfer recipient each have a verified identity that meets the asset's rules.
- You have the transfer recipient's wallet address.

**Roles.** To issue an asset, your wallet needs the Asset manager role. Your wallet is the account that signs for you on the network and holds your roles and balances. If you created the organisation, your wallet already holds Permission manager, System manager, Asset manager, Compliance manager, Verification policy manager, Identity manager and Verification issuer, so you can issue at once. If you joined by invitation, you hold the roles the invitation carried, and a Permission manager grants any that are missing on [Roles and permissions](https://docs.settlemint.com/docs/console/organisation-settings/admins-and-roles). The optional asset class step needs the Permission manager, System manager or Asset designer role. The wallet that issues the asset receives Permission manager, Governance, Supply management and Emergency on it, so the same wallet can mint and launch it. The Console checks these roles for the signed-in account, and the forms have no role selector.

**PIN.** The Console asks you to confirm every action your wallet signs with your transaction PIN or transaction code. If you skipped that setup after onboarding, the Console opens it before your first signing action, or you can set it now on [Security](https://docs.settlemint.com/docs/console/my-account/security#wallet-verification).

**Template.** An instrument template defines the facts, on-chain behaviour and compliance rules for one product shape. Only a Permission manager, System manager or Asset designer can create or publish one, so this tutorial uses the templates already published in your organisation. The person who owns the product at your institution decides which template and which configuration to select. That decision is separate from the Console role that lets you act on it. Read [Instrument templates](https://docs.settlemint.com/docs/concepts/modeling-assets/instrument-templates) and [Compliance policy](https://docs.settlemint.com/docs/concepts/compliance-and-identity/compliance-policy) to understand the template and compliance choices this tutorial takes as given.

**Recipients.** The first holder you mint to and the recipient of the transfer each need a verified identity that meets the asset's rules, because the token checks both a mint and a transfer. Use [Verify a participant](https://docs.settlemint.com/docs/console/participants/verify-a-participant) to review a participant's status before you mint. Mint to your own signed-in wallet, so the transfer step has a balance to send from. Get the transfer recipient's wallet address before the transfer step.

## Steps [#steps]

**Step 1 of 6**

### Confirm the organisation [#confirm-the-organisation]

Open the account menu at the top right and confirm that it names the organisation you created. The asset classes, issued assets and roles you work with belong to the active organisation.

**Step 2 of 6**

### Optional: add an asset class [#optional-add-an-asset-class]

Skip this step to issue from a published template, because the Console sets the asset class from the template you choose. An asset class is the economic category an instrument belongs to, such as Equity, Fixed income or Funds. Adding one needs the Permission manager, System manager or Asset designer role. The instrument template you choose in a later step decides the token's facts, behaviour and compliance rules. Open "Asset design", then "Asset classes". Select "Add asset class", enter a name and description, and select "Create". The Console generates the URL-safe slug from the name.

![Asset classes page with the Add asset class action](https://docs.settlemint.com/docs/screenshots/console-asset-classes.light.en.webp)

[Screenshot] The "Asset classes" table lists each class with its slug and a "System" or "Custom" badge, with "Add asset class" above it.

**Step 3 of 6**

### Start a new issue [#start-a-new-issue]

Open "All assets" and select "Issue asset". Choose a published instrument template. The list shows the templates your organisation has published. Common Equity, Corporate Bond and Fiat-Backed Stablecoin start published. When the template you need is missing, a Permission manager, System manager or Asset designer publishes it on [Instrument templates](https://docs.settlemint.com/docs/console/asset-design/instrument-templates). The choice determines which details and features Issue asset asks you to configure.

![Issue asset on the Instrument step, with published templates in one table under Choose an instrument](https://docs.settlemint.com/docs/screenshots/console-issue-new-asset.light.en.webp)

[Screenshot] "Issue asset" opens on the "Instrument" step, where "Choose an instrument" lists the published templates in one table.

Before you pick a template, the step list shows "General info", "Holder rule", "Asset permissions", "Token logo" and "Review" after it. The table has a search field and the "Class" and "Features" filters. Common Equity, Corporate Bond and Fiat-Backed Stablecoin start published, and the demo organisation in this capture has published more.

**Step 4 of 6**

### Configure and issue the asset [#configure-and-issue-the-asset]

Complete each step shown for the selected instrument. Enter the asset basics. The Console sets the asset class from the template you chose. Fill in the instrument details the template leaves open, then the compliance values your product owner approved, the initial permissions and an optional logo. Check the template and the decimals on the review before you issue, because neither can change on a live instrument. On "Review", select "Open for transfers once issued" so the asset can accept mint and transfer operations immediately. Enter your PIN when the Console asks you to confirm your identity, then submit the issue. The Console shows the asset name followed by "is issued" and opens the new asset.

A successful issue deploys a composable token: one regulated token contract, configured at creation with the features and compliance rules your template and settings specify. Every product shape uses the same contract. The instrument starts with no minted supply. "Open for transfers once issued" makes it ready for the next step. If you did not select "Open for transfers once issued", the asset is halted. Open "Actions" on the asset's page and select "Resume token operations". The first resume launches the token. Confirm that transaction before minting.

**Step 5 of 6**

### Mint tokens [#mint-tokens]

Open "All assets", select the asset, open "Actions" and select "Mint tokens". Enter the first holder's wallet address and the amount, using your own signed-in wallet so you can transfer from it next. The form checks that wallet's eligibility against the asset's rules as you enter it, before you can submit. Review the mint, then select "Confirm mint". The Console reports "Tokens minted successfully" when the transaction completes. To undo a mint on a token that supports burning, use "Burn tokens" in the same "Actions" menu. The burn is a separate transaction.

![All assets table with issued assets available for management](https://docs.settlemint.com/docs/screenshots/console-all-assets.light.en.webp)

[Screenshot] "All assets" lists issued assets.

Open one row to reach its supply and transfer tools.

**Step 6 of 6**

### Transfer tokens [#transfer-tokens]

On the asset's page, open "Actions" and select "Transfer tokens". The signed-in wallet must hold a balance of the asset, which it does when you minted to it. Enter the recipient and amount, then submit the transfer. Transfer-path compliance enforces the configured rules inside the token's own on-chain transfer, so every ordinary transfer runs the same check, whichever surface submits it. If any rule fails, the transfer reverts on chain before any balance changes, and the Console reports the failure. A successful transfer shows "Tokens transferred successfully". To undo a completed transfer, the recipient sends a new transfer back.

Continue with [Where to go next](https://docs.settlemint.com/docs/getting-started/where-next).

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

- The asset is issued and has a minted supply.
- The asset has completed one transfer, and [Activity](https://docs.settlemint.com/docs/console/essentials/activity) shows the transfer's indexed event.
- If you can act as the recipient, [Portfolio](https://docs.settlemint.com/docs/console/my-assets/portfolio) shows its holding after you select that participant.


# DALP documentation

Source: https://docs.settlemint.com/docs
DALP runs regulated digital assets from design to redemption on the EVM network you choose, and these seven sections cover it.


  - [Getting started](https://docs.settlemint.com/docs/getting-started): Sign in and issue a first asset in the Console, then find the pages for your role.
  - [The platform](https://docs.settlemint.com/docs/platform): The eight systems DALP is built from, how a write moves through them and where it runs.
  - [Concepts](https://docs.settlemint.com/docs/concepts): The page that defines each part of the asset lifecycle, from settlement to operations.
  - [Console](https://docs.settlemint.com/docs/console): Find every Console screen, grouped the way the Console sidebar groups it.
  - [Deployment](https://docs.settlemint.com/docs/deployment): Plan a topology, install the charts, connect sign-in and run the instance.
  - [API reference](https://docs.settlemint.com/docs/api-reference): Authenticate, generate a client and call the Platform API.
  - [Changelog](https://docs.settlemint.com/docs/changelog): Every release from 3.0, with its version rules and breaking changes.


## Latest release [#latest-release]

Spotlight: DALP 3.2: run the instrument from issuance to trading

- Released: 11 November 2026
- Version: 3.2.0

Corporate actions on the live token, offerings only for eligible investors, a compliant venue you operate, and an assistant that drafts while your team decides. Start an upgrade from its [compatibility section](https://docs.settlemint.com/docs/changelog/dalp-3-2#compatibility).

For an instance that SettleMint hosts, the [SettleMint Trust Centre](https://trust.settlemint.com/) holds its security, compliance and governance documents, and the [SettleMint status page](https://status.settlemint.com/) shows availability and incident history.


# DALP Instance

Source: https://docs.settlemint.com/docs/platform/dalp-instance
A DALP Instance is one self-contained copy of the platform, deployed on infrastructure you choose and connected to ledger networks you approve.



[Figure] Infrastructure you choose, and what sits inside and outside it. A DALP Instance is one self-contained copy of the platform running on infrastructure you choose: your data centre, your cloud, or dedicated infrastructure the vendor runs. Inside it sit the Operations Console, the backend workloads of the Platform API, the Workflow Engine, Ledger Data and a scheduler, and the durable data stores that hold every record the platform keeps. Outside it, still under your governance, sit the EVM-compatible ledger networks you approve, the custody and signing path, your identity provider, and central telemetry grouped by instance identity. Each of those is an integration you configure. Labels: DALP instance; Operations Console; what your operators work in; Backend workloads; Platform API, Workflow Engine,; Ledger Data indexer, scheduler; Durable data stores; your records, on storage you control; Outside it, under your governance; Ledger networks; EVM networks you approve; Custody and signing; keys stay where you put them; Your identity provider; decides who may sign in; Central telemetry; grouped by instance identity.

One instance runs on infrastructure you choose, and everything outside it stays under your governance.

Each deployment path uses the same platform package. Enabled capabilities depend on the release, configuration, and connected services.

You choose where the platform stores its durable data. Review ledger, custody, identity-provider, and telemetry destinations against your residency and access policies.

Each instance connects to the approved EVM-compatible networks, public or private.

## Why the deployment unit matters [#why-the-deployment-unit-matters]

A DALP Instance is the unit you deploy and run: one full copy of the tokenisation platform, placed where your own rules demand. It does not split into a hosted core and satellite services. Each copy carries issuance, servicing, and reporting inside the same deployment, wherever that deployment runs.

A regulated institution reviews where a platform runs before it reviews features. The platform has to run inside your perimeter, sign staff in through your corporate identity provider and hand its audit evidence to your own monitoring. You pick one of three deployment paths and configure the durable stores the instance uses. Records sent to external integrations or ledger networks also follow those systems' storage policies. The systems you connect it to stay under your own governance and receive only the traffic your configuration sends them.

The three paths differ on two things a deployment review tests: who holds the infrastructure, and who has to be able to reach the running system.

| Path | Choose it when | What it costs you |
| --- | --- | --- |
| On premises | Policy or jurisdiction requires the hardware and the records to stay on premises under your own administrative control, and you have a platform team that already runs Kubernetes or OpenShift clusters. | Your team runs the cluster, applies every upgrade, and answers the alerts. Availability and recovery follow the setup you design, and your backups are what protect the off-chain records. |
| Your cloud account | A cloud account you approve is acceptable, and you would rather use managed database, storage, and multi-zone replication than run hardware for them. | The same operating duty as on premises, minus the hardware: your team still applies each upgrade and answers the alerts, and the provider's own availability model becomes part of yours. |
| Vendor-operated | You want upgrades and paging handled, or you have no platform team to run Kubernetes. | The vendor operates the cluster, and cluster access gives the vendor access to your data, so test this path against any policy that forbids the vendor reaching your records. Availability follows the service terms in your agreement with the vendor. |

Start from the constraint that is hardest to move. A residency or vendor-access rule decides the path on its own, because no configuration makes an operated cluster private from its operator. Where no such rule binds, the question is whether you have the team: self-hosting gives you control over availability and upgrade timing at the cost of operating work. The vendor-run path takes that work from your team and also takes that control. On all three paths an instance has its own platform state, database and control plane, and instances share no application data. Shared infrastructure, network providers, or other external services can still affect multiple instances.

Approve each ledger network for the instance. A public EVM-compatible network uses its existing node governance. A private network lets you control who operates the nodes. Choose the network whose access and governance meet your deployment requirements.

## Running an instance [#running-an-instance]

Day to day, a DALP Instance is a short list of workloads on a Kubernetes or OpenShift cluster. The backend runs as separate workloads from one release: the Platform API, the Workflow Engine runner, the Ledger Data indexer and a scheduler, each with its own replica count. The web Console, a PostgreSQL data plane and Redis sit beside them, with object storage for documents and backups.

The runtime shape is the same on all three paths. Only the party that runs each layer changes.

On self-hosted paths your platform team runs the cluster and applies each upgrade from the vendor's versioned releases. Promote the same release artifacts from test to production. Use release and instance attributes in telemetry to identify mixed versions during a rollout. Two parts of one copy that report different versions in the same telemetry view are a defect. Finish rolling the new release out to the part that is behind, or roll the part that is ahead back, until every part reports the same version.

Every copy declares a stable, globally unique identity, stamped on every signal it exports. In the telemetry store you designate, that identity groups a whole fleet into one view, while each copy's dashboards show only itself. The identity is the Helm value `global.dalpInstance`. It defaults to `local`, which suits a developer machine only, so set a unique identity on every other install. The chart refuses an empty or malformed value, but not the default. Two copies that declare the same name are not refused either: their signals merge into what the fleet view reads as one instance, and separating them again means renaming one copy's declared identity.

Recovery splits by data class: the platform can rebuild indexed chain state from the ledger, while off-chain records such as approvals, identities, documents and workflow state exist only in the copy's database, so your backups protect them.

## What sits inside the instance [#what-sits-inside-the-instance]

A DALP Instance holds three zones: public access, the backend runtime, and durable data. Systems that you govern separately stay outside and connect in, including ledger nodes or remote procedure call endpoints, custody and signing, identity, outside data providers, and central telemetry.

Inside, the backend runs as separate workloads, and each scales on its own. The Platform API authenticates callers, serves reads, and accepts writes. The Workflow Engine runner carries multi-step work across crashes and restarts. The Ledger Data indexer turns chain events into typed, queryable business data: holdings, transfers, balances. A scheduler runs the platform's scheduled jobs. All of them share one PostgreSQL data plane, the durable core: platform state, workflow journals, and indexed read models live there, and the workloads coordinate who owns which durable work through it.

Multi-tenancy lives inside the copy, and it has two layers. On chain, each organisation operates its own set of contracts holding its registries and roles under its own rulebook, so one issuer's assets never mix with another's. Each copy also keeps a catalogue of served networks, and different organisations on it can put their on-chain systems on different approved networks.

Off chain, tenant routes scope data to the authorised organisation. Platform administration also has privileged cross-organisation operations. Separate firms run separate copies, which share no state, no database, and no control plane. Isolation also depends on network rules, credentials, and external services. The ledger and separately governed systems keep their own state.

[Figure] Two tenancy layers inside one copy, next to a separate firm's own copy. One DALP Instance belongs to one firm. Inside it, Organisation A and Organisation B each operate their own contract set on chain under their own rulebook, while both share one backend, one database and one instance identity underneath, with every request scoped to its organisation by the platform. Another firm runs its own separate copy, with no shared state, no shared database, and no shared control plane between the two. Labels: One copy, one firm; Organisation A; its own contract set,; under its own rulebook; Organisation B; its own contract set,; under its own rulebook; Shared underneath; one backend, one instance identity; each request scoped to its organisation; Another firm; runs its own copy; no shared state,; no shared database,; no shared control plane.

Organisations share one firm's copy, each with its own contracts on chain, while a separate firm runs a separate copy that shares nothing.

The network list a copy serves has two writers: the values set when the platform is deployed, which seed a network the first time its name appears, and entries a platform administrator registers at runtime. After a network is stored, the stored entry wins. Adding a network therefore needs no redeploy, while the default network stays a change-controlled setting.

## Frequently asked questions [#frequently-asked-questions]

### Which of the three paths does a residency rule force?

It depends on the rule. A rule that requires the hardware and the records to stay on premises under your own administrative control forces the on-premises path. A rule that forbids the vendor's operations team from reaching your records rules out the vendor-operated path and leaves on premises or your cloud account. A rule that only requires an approved cloud account leaves both of those open.

### Can we start on one path and move later?

Yes. The package is the same everywhere: the API surface, the software, and the records it holds do not change with a move. What changes is the operating split, who runs the cluster, applies upgrades, and answers the alerts. A later move redeploys the same package onto the new path, and the database and storage come with it. Plan the move of signing keys and secrets separately, because they sit with your custody provider or secret manager. [Exit and data portability](https://docs.settlemint.com/docs/deployment/exit-and-data-portability) and [Backup and disaster recovery](https://docs.settlemint.com/docs/deployment/backup-recovery) set out what you can take with you and how to restore it. Your client code keeps targeting whichever copy's endpoint and credentials you configure, regardless of which of the three paths that copy runs on.

### What traffic leaves the instance?

The integrations you configure, plus defaults you can replace. Configured traffic goes to the ledger networks you approve, the custody and outside data providers you select, mail delivery, telemetry to the store you designate, and webhooks to your endpoints. Unless you set your own exchange-rate source, the platform fetches exchange rates from a public currency service on the internet. Unless you mirror the images, each pod pulls them from SettleMint's public image repositories. When the operator turns analytics on, the Console sends usage data to SettleMint's analytics accounts. No shared control plane sits behind the copy, so telemetry reaches SettleMint only when you send it there. Your own network controls govern any other egress.

### Does the environment label change how a copy behaves?

No. `global.deploymentEnvironment`, one of `local`, `development`, `test`, `staging`, `demo` or `production`, feeds one telemetry attribute, `deployment.environment.name`, and nothing else. Declaring a copy's environment tells your fleet view which one it is. The platform's behaviour comes from the release image and the rest of its configuration, not from this field.

### Where do the signing keys live?

They live where your policy puts them. The platform signs through a path you configure: your own hardware security module, an external custodian, or an encrypted store the copy hosts. Review who can access each signing service and its administration. When SettleMint operates an instance that uses the local key store, SettleMint staff with cluster access can reach the encrypted key material. Use an external HSM or custodian if that is not acceptable.

## Related concepts [#related-concepts]

- [What DALP is](https://docs.settlemint.com/docs/platform): How DALP divides one regulated-asset platform into eight named systems, all of which run inside one instance.
- [EVM Contract Set](https://docs.settlemint.com/docs/platform/evm-contract-set): The identity, compliance, custody, and settlement contracts DALP deploys on the EVM chains a copy serves.
- [Ledger Data](https://docs.settlemint.com/docs/concepts/records-and-evidence/ledger-data): The platform's queryable record of the ledger networks it follows, built by decoding blocks and events into business records.
- [Prerequisites](https://docs.settlemint.com/docs/deployment/prerequisites): What an install needs ready.
- [Hosting and access](https://docs.settlemint.com/docs/deployment/hosting-and-access): Who operates the instance and what the vendor can reach.


# EVM Contract Set

Source: https://docs.settlemint.com/docs/platform/evm-contract-set
The EVM Contract Set is the identity, compliance, custody, and settlement contracts DALP deploys around one composable security token, checked in one call.



[Figure] Every ordinary transfer passes one compliance gate before any balance changes. A transfer request carries a sender, a receiver, and an amount. Before any balance changes, the request passes a compliance gate inside the same transaction: the receiver's identity is verified, the instrument's own compliance rules are checked, then the platform-wide rules that apply to every instrument. If every check clears, the balance updates and the transfer is recorded on the ledger. If any check fails, the transaction reverts and no balance changes. A mint takes the same path. A burn has no receiver to check, but a frozen sender or a Token Feature rule can still block it. A registered fee feature can split a transfer, a mint, or a burn into a net leg and a fee leg, so the amount credited is not always the amount submitted. Custodian powers such as freeze, forced transfer, and recovery skip the ordinary compliance and freeze checks, but a forced transfer's receiver must still pass the identity check. Labels: Every transfer, one path; Transfer request; from &#8594; to; amount and asset; this instrument; A mint takes this; same path. A burn; has no receiver check,; but can still revert; (fee features may split it); Compliance gate; inside the same transaction; Identity verified; may hold this asset; Instrument&#8217;s own rules; checked per token; Platform-wide rules; checked for every asset; All three must clear; before value moves; Balance; updated; Passes; recorded on ledger; Reverted; Fails; no balance changes; Custodian powers (freeze, forced transfer, recovery) skip the rule checks.; A forced transfer&#8217;s receiver must still pass the identity check.

Identity, this instrument's own rules, and the platform's own rules all clear inside the same transaction that changes the balance, or none of it happens.

One generic, standards-based token contract carries every instrument issued on the network.

Every ordinary transfer checks identity and compliance inside the same transaction that moves value. A recipient on the platform's own bypass list skips the rules that judge the recipient. A failed check reverts before any balance changes.

A single custodian role can freeze an address, force a transfer, or recover a lost wallet's tokens without a second signer's on-chain consent.

## Custody calls use one role, and the signing account adds approval [#custody-calls-use-one-role-and-the-signing-account-adds-approval]

The EVM (Ethereum Virtual Machine) Contract Set is the on-chain half of the platform on EVM chains: one Composable Token configured per instrument, meaning one regulated contract deployed per issued asset rather than a different contract per product type. It does not ask a second party to co-sign a transfer, a freeze, or most recoveries. Use a custody approval policy or a weighted Smart Wallet when a privileged call needs more than one approver. It builds on published standards: ERC-3643 for identity-gated transfers and ERC-20 as the base fungible interface. Coverage depends on the instrument terms a configuration carries.

The contract checks compliance before the balance changes, and no off-chain system is trusted to apply it. An ordinary transfer that would violate compliance never settles, so nothing is unwound later. The bypass list and the custodian role are the recorded exceptions.

Custody power concentrates freezing and forced transfer in one custodian role, and the contract asks for nothing more than that role to exercise them. Recovering a lost wallet has two paths instead of one: the identity registry's named replacement wallet can claim the balance itself once the registry flags the original wallet lost, or the custodian role can force the same recovery directly. Institutions pair the custodian role, and who the registry may name as a replacement, with their own authorisation policy before granting either (see Custody Approval).

**Single signing key**

An address that holds the custodian role can authorise a privileged call. Separate role assignments do not require two signatures on that call.



**Weighted Smart Wallet**

A Smart Wallet can hold the custodian role and require a configured signature threshold. Check its installed validators: another validator can provide an additional authorisation path.

## A failed compliance check reverts the transfer [#a-failed-compliance-check-reverts-the-transfer]

A transfer that fails compliance reverts during execution, inside the same transaction that would have moved the balance. No separate remediation queue exists to run afterward: the sender sees the failed transaction, and no balance anywhere has moved. Resubmitting the same request fails again. Fix the eligibility, scope, limit, or approval condition the failing module flagged, or get the receiver registered and cleared in the identity registry if that check failed. Compliance Policy covers how to find which tier, this instrument's own rules or the platform-wide floor, rejected the movement.

The EVM Contract Set deploys one token per instrument. Issuing starts with an Instrument Template, and no new contract is requested: the template supplies the facts, features, and compliance choice, and deployment produces one configured token that already carries identity and compliance enforcement.

Servicing steps follow the same pattern. Freezing an address, freezing part of a balance, and forcing a transfer are each a single call from whoever holds the custodian role for that asset. Recovering a lost wallet's tokens can be that same call, or a direct call from the registry-named replacement wallet instead. None of them waits on a second signer at the contract level. Freeze the whole address when the wallet itself is the concern: a full freeze blocks both directions, so it can neither send nor receive, and a mint to it reverts too. Freeze part of the balance instead when only a specific amount needs to hold: a partial freeze locks that amount while the holder keeps receiving and keeps spending whatever sits above it.

Trades between counterparties settle through a dedicated escrow contract rather than the token contract itself. Local-only execution is atomic, and hashlock-committed settlements can defer blocked deliveries. See [XvP Settlement](https://docs.settlemint.com/docs/concepts/settlement/xvp-settlement) for local atomic execution, external coordination, and deferred deliveries.

## The compliance check runs inside the same step that moves the balance [#the-compliance-check-runs-inside-the-same-step-that-moves-the-balance]

The low-level operation that changes a balance is the same operation that runs the compliance check, so an ordinary transfer or mint cannot settle without that operation running. Two deliberate exceptions break that pattern: the platform's own bypass list, and the custodian role's privileged powers.

The EVM Contract Set combines identity, compliance, features, and custody around the token. First, an identity registry with trusted issuers decides who may hold the asset at all, as Onchain Identity describes. The Composable Token itself carries identity checks, roles, and metadata. Second, a compliance layer evaluates every ordinary transfer or mint twice. It checks this instrument's own compliance modules first, small rule contracts plugged into the token that each test one condition such as eligibility or a holding limit. Then it checks a platform-wide set of the same kind of module that applies across every instrument on the deployment. Third, [Token Features](https://docs.settlemint.com/docs/concepts/modeling-assets/composable-token#how-composition-works) can approve or refuse an operation before it runs, and when one rewrites an operation it can split it into several legs. A fee feature, for example, turns one transfer into a net leg plus a fee leg rather than moving the requested amount whole. Fourth, a custody layer sits alongside, with its own privileged bypass.

Put a rule at the instrument tier when it belongs to this issuance's own terms, such as an eligibility test or a holding limit unique to the offering. Put it at the platform tier when it has to hold for every instrument regardless of terms. Compliance Policy names which rules belong at which tier, and Transfer-Path Compliance describes the general mechanism this contract set implements.

Two conditions change how the ordinary compliance rules run. Compliance keeps its own bypass list, separate from the instrument's own modules and the platform-wide set. The platform manages it: the token and add-on factories add the contracts they deploy, and no Console screen or Platform API route edits the list directly. A recipient on that list skips only the rules that judge the recipient: country and identity lists, identity verification, claim expiry, holder counts and transfer approval. Sender-side, lock-up, minimum-holding and supply rules still run in both tiers. Compliance contracts still on the earlier version skip every rule for a bypassed recipient. A paused token works the other way: every ordinary transfer, mint, and burn fails outright before compliance runs at all. Wait for the emergency role that paused the token to lift the pause.

Minting passes through the identical gate as an ordinary transfer, with its own revert reason. Burning is different: it has no destination address for identity or the ordinary compliance modules to check, so those two checks do not run. A burn still runs through the custody layer, so a burn from a fully frozen address reverts, whether the holder redeems or the Supply management role burns. It still runs through Token Features too, so a feature such as a conversion lock can refuse a burn on the same terms it would refuse a transfer.

The custodian role's privileged powers skip the ordinary compliance checks and the sender's freeze, since a freeze or a forced transfer is itself the enforcement step. The receiving wallet's identity check still runs, so even a forced transfer cannot deliver tokens to a wallet the identity registry has not verified. A forced transfer also refuses a receiving address that is frozen. A current registry checks the required claims, and older registries can fall back to registration. The ledger records the write: a forced transfer records as a transfer, with the custodian's step recorded as its own on-chain event. Recovering a lost wallet is the one custodial power with a second path. The identity registry's named replacement wallet can claim the balance itself once the registry flags the original wallet lost, with no role check at all, or the custodian role can force the same recovery directly. Custody functions are gated by a single role check made by the platform's access manager, the per-token contract that records role assignments and answers whether a caller holds one.

[Figure] One role authorises every custodial lever. A single custodian role authorises four privileged powers on this ledger. Freezing an address blocks sending and receiving. Freezing part of a balance leaves the rest spendable. Forcing a transfer skips the compliance rules and the sender's freeze, while the receiver's identity check and freeze still apply. Recovering a lost wallet moves freeze state to the replacement wallet. The custodian role can force that recovery, or the registry-named replacement wallet can claim it directly with no role check at all. Freezing an address, freezing part of a balance, and forcing a transfer are each a single on-chain call from whoever holds that role. None requires a second party to co-sign at the contract level. Labels: Custodian role; One role; one on-chain check; Freeze an address; blocks send and receive; Freeze part of a balance; the rest stays spendable; Force a transfer; skips rules and sender freeze; receiver identity, freeze checked; Recover a lost wallet; freeze state moves with it; or wallet self-claims, no role.

Freezing, partial freezing and forced transfer share one role check, and recovery adds a second path through the registry-named replacement wallet.

## Read the outcome of a submitted transaction [#read-the-outcome-of-a-submitted-transaction]

A simulation or preflight can reject a blocked transfer before submission. A transaction can also revert during on-chain execution after the Platform API has accepted the request. Follow the accepted request's status until its outcome is recorded. The [contract error reference](https://docs.settlemint.com/docs/api-reference/errors/error-code-reference#compliance--token-operations) names every reason along with what it takes to clear each one. A burn skips recipient eligibility checks, but a feature or a stateful compliance hook can still revert it. Read the failure details and resolve the cause before starting another attempt.

A wallet can submit these transactions directly, or through ERC-4337 account-abstraction infrastructure when an integration wants sponsored or batched submission. That infrastructure is a separate layer from the contract set itself.

Custody operations are ordinary contract calls gated by a role check, with no additional signature payload from a second party required at the call level. Multi-party settlement integrates through the settlement contract's own interface, not through the token contract. See [XvP Settlement](https://docs.settlemint.com/docs/concepts/settlement/xvp-settlement).

## The control and the transaction are one object, so nothing settles then reverses [#the-control-and-the-transaction-are-one-object-so-nothing-settles-then-reverses]

Every ordinary transfer is checked twice inside one transaction: this instrument's own compliance modules, then a platform-wide set of rules evaluated the same way for every instrument on the deployment. A failing check reverts before any balance changes, so a non-compliant transfer is never settled and then reversed. The platform's own bypass list is the one address-level exception: it lifts the rules that judge a recipient, and the chain records every change to the list with the account that called the compliance contract, which is the factory for an address it adds or removes and the calling account for a direct call.

Custody enforcement on the network is single-role authorised: the contract itself asks for one role check, not a second party's on-chain consent, for freezing, forced transfer, and recovery. Controls that require multi-party sign-off for those steps live in the platform's own operating policy around who may hold that role, as [Custody Approval](https://docs.settlemint.com/docs/concepts/custody-and-signing/custody-approval) describes, not in the contract's own logic.

On-chain events and receipts record contract execution. Keep the platform audit trail and approval evidence as well: the chain alone does not identify every human decision behind a signing account.

## Frequently asked questions [#frequently-asked-questions]

**Can an address escape compliance checks entirely?**

Only partly on current contracts, and only through the platform's own bypass list. Once an address is on the list, a transfer or mint into it skips the rules that judge the recipient in both the instrument's own rules and the platform-wide floor. The other rules still run, and compliance contracts still on the earlier version skip every rule. Removing the address from the list restores every check. The platform manages the list: the token and add-on factories add the contracts they deploy, and no Console screen or Platform API route edits it directly. A System manager can change the list by registering a custom token factory or add-on, or by pointing a registered one at new code, because every registered factory and add-on can add and remove addresses. A Compliance manager can change it with a direct call to the system compliance contract.

**What happens to a transfer while the token is paused?**

It reverts, and so does every mint or burn submitted while the pause holds. Pausing is an emergency-role step that stops the whole asset at once, ahead of the compliance check rather than as one, so nothing settles and nothing is left half-applied.

**Can a forced transfer move tokens that are frozen?**

Yes. When the amount exceeds the sender's unfrozen balance, the contract unfreezes exactly the shortfall and moves the tokens, recording that unfreeze as its own on-chain event. A full address freeze on the sender does not stop the call either. Three limits hold. The receiving wallet must still pass the identity check, its address must not be frozen, and the destination cannot be the zero address, so a forced transfer can never destroy supply.

**What happens to a freeze when a lost wallet is recovered?**

The freeze moves with the tokens. Recovery transfers the lost wallet's whole balance to its replacement and migrates both the partially frozen amount and any full-address freeze, so reporting a wallet as lost does not clear a freeze. A freeze already sitting on the replacement wallet also stays until a custodian explicitly lifts it. Recovery itself only runs after the identity registry has flagged the wallet lost and named its replacement.

**Does the platform still support the older asset-specific contracts?**

New issuance uses the composable contract model. Older per-type contracts are deprecated for creation. Existing deployments still require servicing and a planned upgrade path. Instrument Templates supply terms for new configured tokens. See [Composable Token](https://docs.settlemint.com/docs/concepts/modeling-assets/composable-token) for the model that replaced them.

## Related concepts [#related-concepts]

- [Composable Token](https://docs.settlemint.com/docs/concepts/modeling-assets/composable-token): The one regulated contract model this contract set configures per instrument.
- [Compliance Policy](https://docs.settlemint.com/docs/concepts/compliance-and-identity/compliance-policy): The general mechanism by which compliance rules are configured and evaluated.
- [Transfer-Path Compliance](https://docs.settlemint.com/docs/concepts/compliance-and-identity/transfer-path-compliance): Why compliance runs inside the transfer rather than beside it.
- [Custody Approval](https://docs.settlemint.com/docs/concepts/custody-and-signing/custody-approval): The platform's own authorisation policy around who may hold the custodian role.
- [XvP Settlement](https://docs.settlemint.com/docs/concepts/settlement/xvp-settlement): The escrow contract that settles multi-party trades atomically on this ledger.
- [Onchain Identity](https://docs.settlemint.com/docs/concepts/compliance-and-identity/onchain-identity): How eligibility to hold this asset is established and checked.
- [Settlement Verdict](https://docs.settlemint.com/docs/concepts/settlement/settlement-verdict): The recorded end state of an on-chain operation, on an EVM-compatible network.


# What DALP is

Source: https://docs.settlemint.com/docs/platform
DALP is built from eight named systems around one registry of assets. Learn what each system owns, how a write moves through them, how an instance is deployed and which networks it runs on.



[Figure] The eight DALP systems around the Asset Registry. One DALP instance holds eight systems. Operators work in the Operations Console, and your own software calls the platform through its API, SDK and CLI. Both send every on-chain write to the Transaction Lifecycle Engine. It works with the Asset Registry at the centre, which holds every asset, its template and its servicing, with Compliance &amp; Identity, which decides who may hold and receive an asset, and with Custody &amp; Settlement, which gets approvals and signatures and settles trades. Each token checks the rules of Compliance &amp; Identity inside its own transfer. The Transaction Lifecycle Engine broadcasts the signed transaction to the EVM network, a public or permissioned blockchain outside DALP. Ledger Data indexes what the network records into holdings, history and events. Market Data supplies prices, feeds and exchange rates. Core Platform runs under every system with sign-in, API keys, organisations, networks and deployment. Each system owns its own records, and all of them read the same indexed record in Ledger Data. Labels: rules; Your software; API, SDK, CLI; One DALP instance; Operations Console; Operators; Where operators work; Transaction Lifecycle Engine; Every on-chain write; Queues it, broadcasts it, records each step; Compliance &amp;; Identity; Who may hold; and receive; Asset Registry; Templates, tokens; and servicing; Custody &amp;; Settlement; Keys, approvals; and settlement; EVM network; Outside DALP; Public or; permissioned; Market Data; Prices; Feeds and rates; Ledger Data; Read model; Indexed holdings, history and events; Core Platform; Under every system; Sign-in, API keys, organisations, networks, deployment.

The Console and your own software send every on-chain write through the Transaction Lifecycle Engine to the EVM network, and Ledger Data indexes the result.

Eight named systems divide the work. Each system owns its own records, and all of them read the same indexed record in Ledger Data.

The compliance rules run inside the token's own transfer, so every path to an ordinary transfer meets the same check. A custodian's forced transfer and three other recorded paths skip some of these checks, and [Transfer-path compliance](https://docs.settlemint.com/docs/concepts/compliance-and-identity/transfer-path-compliance) lists all four.

A write succeeds when its settlement verdict, the outcome the platform records, is completed. Acceptance and broadcast are steps on the way.

DALP, the Digital Asset Lifecycle Platform, runs a regulated digital asset from its design to its final redemption on an EVM network, a public or permissioned blockchain that runs Ethereum-compatible contracts. It is built from eight named systems around one registry of assets, the Asset Registry.

## The eight systems [#the-eight-systems]

Each capability in DALP has one owning system. People reach DALP through the Operations Console, and software reaches it through the Platform API, which belongs to Core Platform. Core Platform also runs sign-in, organisations and deployment under every other system. The other six systems do the work behind those surfaces.

### Asset Registry [#asset-registry]

The Asset Registry holds every asset the organisation issues and the instrument templates it issues them from. Every asset, whether a bond, a fund, an equity or a stablecoin, is issued from a template as the same composable token with its own features and rules. The registry also services the asset over its life: fixed-yield and interest-yield payments, dividends, corporate actions, governance votes, maturity redemption and the holder register. Read [Instrument templates](https://docs.settlemint.com/docs/concepts/modeling-assets/instrument-templates) and [Asset lifecycle](https://docs.settlemint.com/docs/concepts/issuing-and-markets/asset-lifecycle).

### Compliance & Identity [#compliance--identity]

Compliance & Identity decides who may hold and receive an asset. It keeps the on-chain identity behind each wallet and the transfer rules each token checks inside its own transfer. Trusted issuers are the parties your organisation accepts to vouch for an investor, and Compliance & Identity keeps the verifications they attach to each identity. It also holds the roles each participant has, the organisation-wide compliance controls, the audit trail and regulatory reporting. Read [Transfer-path compliance](https://docs.settlemint.com/docs/concepts/compliance-and-identity/transfer-path-compliance) and [Compliance policy](https://docs.settlemint.com/docs/concepts/compliance-and-identity/compliance-policy).

### Transaction Lifecycle Engine [#transaction-lifecycle-engine]

The Transaction Lifecycle Engine runs every on-chain write, which is any request that changes state on the network, such as a mint, a transfer or a role change. It queues the write, keeps a durable record of each step, resumes the write after a restart, broadcasts the signed transaction, and ends the write in one outcome. A retry with the same idempotency key within 24 hours attaches to the first write. The engine also pauses a write that is short of gas and decides who pays the gas. Read [Transaction lifecycle](https://docs.settlemint.com/docs/concepts/settlement/transaction-lifecycle) and [Settlement verdict](https://docs.settlemint.com/docs/concepts/settlement/settlement-verdict).

### Custody & Settlement [#custody--settlement]

Custody & Settlement connects the signer behind each wallet: an external custody provider or HSM, the local key store, or a member's own wallet. It asks a managed signer to sign, and a member signs in their own wallet. It holds a write while a custody provider approves it or while a wallet checker approves it. A wallet checker is the second person a wallet owner names for maker-checker approval of every transaction from that wallet. Custody & Settlement also owns how value changes hands: escrow, primary offerings, fund subscriptions, trading venues, custodial deposits, the bank rail and XvP settlement. The bank rail is the bank connection that credits a client's wallet when a bank transfer arrives and pays redemptions back to the client's bank account. XvP settlement is an exchange in which neither side delivers first. Read [Custody provider](https://docs.settlemint.com/docs/concepts/custody-and-signing/custody-provider) and [XvP settlement](https://docs.settlemint.com/docs/concepts/settlement/xvp-settlement).

### Ledger Data [#ledger-data]

Ledger Data is the indexed record of each network the instance follows. The indexer turns chain events into holdings, history and portfolios, and repairs its records after a chain reorganisation. Console and API reads of business records come from this record. The platform reads the chain directly only for named checks: before it sends a write, to detect drift, to reconcile custody and to validate historical timestamps. Ledger Data also sends signed webhooks to your endpoints. Read [Ledger data](https://docs.settlemint.com/docs/concepts/records-and-evidence/ledger-data).

### Market Data [#market-data]

Market Data supplies the prices the platform values assets with. It keeps a price feed per token, connects external price sources and refreshes exchange rates. A price that moved too far, or that corrects an earlier price, waits for maker-checker approval by a feeds manager or the token's governor. The on-chain price resolver and the current-price reads refuse a price older than its feed's staleness window, and indexed holdings mark a stale value as unreliable. Read [Market data](https://docs.settlemint.com/docs/concepts/records-and-evidence/market-data).

### Operations Console [#operations-console]

The Operations Console is the web application where operators do their work: the dashboard, the actions inbox, asset and participant screens, settings and platform status. Its sidebar lists only the areas the signed-in person can use. The investor portal is a separate application for investors. Read the [Console guides](https://docs.settlemint.com/docs/console).

### Core Platform [#core-platform]

Core Platform runs under every other system. It covers sign-in, organisations and their members, API keys, the Platform API, the SDK and the CLI, the network catalogue, observability, system updates and the self-hosted deployment. Read [DALP Instance](https://docs.settlemint.com/docs/platform/dalp-instance) and [System version](https://docs.settlemint.com/docs/platform/system-version).

## How one write moves through the systems [#how-one-write-moves-through-the-systems]

A write passes the same systems whether it starts in the Console or in the API. Each step maps to the states the platform records on the write. Indexing happens while the write still reads as confirming.

[Figure] One write, from request to settlement verdict. A write starts as a request from the Console or the Platform API, with an idempotency key, and the platform checks that the caller's wallet holds the role the action needs. The Transaction Lifecycle Engine queues the write and prepares the transaction. Custody &amp; Settlement gets an approval when the custody provider's policy or the wallet's checker requires one, then the wallet's signer signs. Up to broadcast the platform can still retry or stop the write. The Transaction Lifecycle Engine broadcasts the signed transaction to the EVM network, where the token contract checks its compliance rules and reverts the transfer when a rule fails. Ledger Data indexes the block and its events. The write ends in one settlement verdict: completed, failed, dead letter or cancelled. By default the platform answers 202 with a status handle at once. A caller that sends Prefer: wait=N holds the response for up to N seconds, at most 99, until Ledger Data has indexed the block, and gets the 202 handle if the wait runs out first. Labels: Before broadcast, the platform can still retry or stop the write; 1. Request; Console or Platform API,; role checked, with an; idempotency key; 2. Transaction; Lifecycle Engine; Queued, then; transaction prepared; 3. Custody &amp;; Settlement; Approved if required,; then signed; After broadcast, the network decides and ledger data records; 4. EVM network; The engine broadcasts it.; Token checks compliance,; reverts if a rule fails; 5. Ledger Data; Indexer records the; block and its events; 6. Settlement verdict; Completed, failed,; dead letter or cancelled.

A write passes from request through the engine, approval, signing and broadcast to indexing, and ends in one settlement verdict.

1. **Request.** An operator acts in the Console, or your system calls the [Platform API](https://docs.settlemint.com/docs/api-reference). Every caller acts through an on-chain wallet that holds roles, and the platform refuses a request when the wallet lacks the role the action needs. A write can carry an `Idempotency-Key` header. A repeat with the same key within 24 hours attaches to the first write.
2. **Queue and prepare.** The Transaction Lifecycle Engine records the write and queues it, then prepares the transaction.
3. **Approve and sign.** When a custody provider or a wallet checker holds the transaction for approval, the write waits in the pending approval state. The wallet's signer then signs it: the custody provider, the local key store or, for a self-custody wallet, the member.
4. **Broadcast and execute.** The engine broadcasts the transaction and waits for confirmation. The token contract runs its compliance rules inside the transfer. A transfer that breaks a rule reverts, and no balance changes.
5. **Index.** Ledger Data indexes the block. By default the platform answers a write at once with HTTP 202 and a status handle. A caller that sends `Prefer: wait=N` holds the response for up to N seconds, at most 99, until Ledger Data has indexed the effect, so the next read shows it. If the wait runs out first, the caller gets the 202 handle and the write continues.
6. **Verdict.** The write ends as completed, failed, dead letter or cancelled. Dead letter means the platform has stopped retrying and holds the write for an operator, who can requeue a failed or dead-lettered write.

Up to broadcast, the platform can still retry or stop the write. A write can also pause there while it waits for gas funding, as [Transaction funding](https://docs.settlemint.com/docs/console/organisation-settings/transaction-funding) describes. After broadcast, the network decides which transaction confirms, and a cancel sends a replacement transaction that can lose the race.

A completed verdict means the transaction's block was mined and indexed. It does not mean the block is final. If a chain reorganisation removes the block, Ledger Data rolls back the indexed record for the replaced blocks, replays the new ones and withdraws the webhook events of replaced blocks that had not reached finality. [Ledger data](https://docs.settlemint.com/docs/concepts/records-and-evidence/ledger-data) describes the repair.

The Console and the transfer pre-check can test a transfer against the rules before anyone signs, and they name what stands in the way. Those checks inform the operator. The token contract makes the decision, and its check applies to every ordinary transfer, including one sent straight to the contract. [Transfer-path compliance](https://docs.settlemint.com/docs/concepts/compliance-and-identity/transfer-path-compliance) explains both.

## How DALP is deployed [#how-dalp-is-deployed]

DALP ships as container images and one umbrella Helm chart, `dalp`. Production instances install that chart, and an optional `observability` chart collects metrics, logs and traces. Two choices decide how an instance runs.

- **Who operates the instance.** Your platform team installs the chart in your own Kubernetes cluster, in your cloud or on premises, and runs every upgrade. Or SettleMint operates the instance for you with the same chart, on your infrastructure or on infrastructure it holds. On OpenShift, a values overlay sets the restricted security context.
- **How much vendor access, when your team operates.** The vendor can keep cluster administration, receive telemetry only, hand over the chart and keep no agent, or hold no cluster access while the instance pulls nothing from the vendor registry, because you mirror every image into a registry inside your network and install from that copy. [Hosting and access](https://docs.settlemint.com/docs/deployment/hosting-and-access) sets out each option.

In both models the instance stores its state in PostgreSQL, Redis and object storage that the operator supplies. The operator also chooses a secret manager for the platform from AWS Secrets Manager, Azure Key Vault, Google Secret Manager or HashiCorp Vault. The chart defaults to the built-in store, `local`, which keeps secrets and local signing keys encrypted in the platform database. The platform does not refuse it in production, so choose an external secret manager before a production install.

The Console serves its own fonts and images. By default, the platform fetches exchange rates from a public currency service, first through the jsDelivr content network and, when that fails or still serves an earlier day, from `currency-api.pages.dev`. An operator can point it at its own source. When the operator turns analytics on, the Console sends each signed-in user's email address and user ID to SettleMint's HubSpot account, and the organisation's ID and name to SettleMint's Google Analytics property. Otherwise it calls no hosted analytics service. An instance still reaches the RPC nodes of its networks and any custody provider, identity provider, price source, mail server, telemetry endpoint and assistant model provider it uses. The Console assistant calls its model provider only when the platform or an organisation holds a model key. [Prerequisites](https://docs.settlemint.com/docs/deployment/prerequisites) lists the endpoints and credentials an install needs ready.

| Party | Responsible for |
| --- | --- |
| Whoever operates the instance: your team, or SettleMint when it operates | The cluster, PostgreSQL, Redis, object storage, ingress, backups and upgrades |
| SettleMint | Releases, images with build provenance and a software bill of materials, the chart, patch releases and support under your agreement in both models, and operation of the instance when it operates it |
| Your institution | Legal and economic terms, the choice of custody provider, trusted issuers and price sources, and reconciliation against your book of record |
| Your custody provider or HSM | Keys, approval policies and vault set-up, when you use one |
| The operator, when the instance uses the local key store | The key material, which the platform holds |
| You or a node provider | The RPC endpoints for each network |

[Topologies](https://docs.settlemint.com/docs/deployment/topologies) sizes each role of the chart, [Upgrades and migrations](https://docs.settlemint.com/docs/deployment/upgrades-migrations) covers an upgrade, and [Supply chain and support](https://docs.settlemint.com/docs/deployment/supply-chain-and-support) covers releases, image provenance and support. For the controls around an instance, read [Security and compliance posture](https://docs.settlemint.com/docs/deployment/security-compliance-posture), [Single sign-on](https://docs.settlemint.com/docs/deployment/sso), [Backup and disaster recovery](https://docs.settlemint.com/docs/deployment/backup-recovery) and [Exit and data portability](https://docs.settlemint.com/docs/deployment/exit-and-data-portability).

## Supported networks [#supported-networks]

DALP runs on EVM networks, public or permissioned. An instance lists its networks in its configuration, as built-in chains or custom chains with their own chain id, and a platform administrator can add networks later in the network catalogue without a redeployment. Each network needs an HTTP RPC endpoint and a WebSocket endpoint for live indexing. One instance hosts many organisations, the tenants that each have their own members, assets and contracts. An organisation deploys its on-chain system, the set of contracts that holds its identities, rules and assets, on one default network. With multi-network support turned on, it deploys its contracts on more networks, and a request names its network in the `X-Chain-Id` header or acts on the default network. [Networks](https://docs.settlemint.com/docs/deployment/networks) covers the configuration.

## Versions [#versions]

Each organisation's contracts move between versions through the System updates page in the Console. [System version](https://docs.settlemint.com/docs/platform/system-version) explains what a version is and what a migration changes. The platform's own releases, the API versions and the deprecation policy are on the [changelog](https://docs.settlemint.com/docs/changelog).

## Frequently asked questions [#frequently-asked-questions]

### Can a transfer skip the platform and go straight to the token contract?

Yes, and the compliance rules still apply. The rules live in the token contract, so a transaction sent straight to the network meets the same check at the same point, and an ordinary transfer that breaks a rule reverts. A custodian's forced transfer and three other recorded paths skip some of these checks, and [Transfer-path compliance](https://docs.settlemint.com/docs/concepts/compliance-and-identity/transfer-path-compliance) lists all four. A direct call skips what the platform adds before broadcast: the role check, custody approval, the durable record and the settlement verdict. Ledger Data still records the result, because it indexes the events of each block it follows, not only the platform's own writes.

### What happens to a write in progress when the platform restarts?

The Transaction Lifecycle Engine resumes the write from its recorded state. Keep the original idempotency key. A retry with that key within 24 hours attaches to the write that is still running and does not start a second one. Read the outcome from the write's settlement verdict.

### Does DALP replace your core banking or custody systems?

No. Your core systems stay the book of record. They call the Platform API and receive signed webhooks. With an external custody provider or HSM, the provider keeps the keys and its own approval policies, and DALP asks it to sign. With the local key store, the platform holds the key material. A member with a self-custody wallet signs in that wallet.

## Related concepts [#related-concepts]

- [DALP Instance](https://docs.settlemint.com/docs/platform/dalp-instance): One deployed copy of the platform, and what it contains.
- [EVM contract set](https://docs.settlemint.com/docs/platform/evm-contract-set): The identity, compliance and custody contracts the platform deploys on an EVM network.
- [System version](https://docs.settlemint.com/docs/platform/system-version): The version an organisation's contracts have reached, and what a migration changes.
- [Transaction lifecycle](https://docs.settlemint.com/docs/concepts/settlement/transaction-lifecycle): The full path of one write, from acceptance to its recorded outcome.
- [Settlement verdict](https://docs.settlemint.com/docs/concepts/settlement/settlement-verdict): The recorded outcome of a write, and the record to read instead of the acceptance.
- [Transfer-path compliance](https://docs.settlemint.com/docs/concepts/compliance-and-identity/transfer-path-compliance): How the token enforces its rules at the moment value would move.
- [Ledger Data](https://docs.settlemint.com/docs/concepts/records-and-evidence/ledger-data): The indexed record of the networks the platform follows, and the source of business reads.
- [Platform health](https://docs.settlemint.com/docs/concepts/operating/platform-health): The single health signal the platform reports about itself.


# System Version

Source: https://docs.settlemint.com/docs/platform/system-version
A System Version is how far an organisation's on-chain components have advanced against the current module set, and migrating repoints those that fell behind.



[Figure] Migrating repoints an organisation's own registry row, not the Directory's. A vessel labelled Organisation's addon registry holds one focal row for an addon, keyed by a fixed type id, xvp-settlement. The row's implementation pointer targets a quiet card labelled V1 implementation, superseded. An accent arrow labelled the migration call repoints this row shows the pointer moving to an emphasised card labelled V2 implementation, current, same id. A separate dashed note below states that installing this addon again with that same type id instead fails, because a version bump updates the existing row rather than creating a second one. Labels: Organisation's addon registry; Addon registry row; type id: xvp-settlement; fixed, never changes.; V1 implementation; superseded; V2 implementation; current, same id; the migration call; repoints this row; Installing this addon again fails instead of adding a row; a version bump updates the row. It does not create a second one.

A type id keys one Directory row and one organisation registry row, and migrating repoints only the organisation's row in place without adding a second.

A component keeps one fixed type id across every version. A new implementation repoints the existing registry row instead of registering a second, competing entry.

The platform compares each component against the current module set and reports one of three statuses. The Console's System updates page shows them as Up to date, Upgrade available and Not installed, with two more states for components it cannot upgrade or could not read.

Comparing and starting a migration both take the admin or system manager role, and a migration runs as a signed background workflow. Validate the upgrade against representative chain state before production.

## Staying current is a repoint, not a rebuild [#staying-current-is-a-repoint-not-a-rebuild]

A system version tells you whether the contracts an organisation deployed match the platform's current module set. When [System updates](https://docs.settlemint.com/docs/console/organisation-settings/system-updates) in the Console shows Upgrade available, an authorised operator starts a migration, which repoints the outdated component to its current implementation without changing its address. The expectation it compares against lives in the Directory, the platform's own on-chain catalogue, one per network. The module set is the bundle of implementation addresses the Directory holds as current across every component type. A chain's implementations are locked in at deployment. The Directory's addresses keep advancing with fixes, new capabilities, and, over time, compliance features that graduate from optional to standard. A chain that never migrates keeps the exact behaviour it deployed with, including any defect fixed since, and misses later capabilities without anyone deciding to skip them. Security fixes in contract logic reach the chain only when the organisation starts a migration.

A component's identity in the registry does not change across versions, so staying current repoints the same, already-integrated component at newer logic. The organisation does not redeploy its system, and counterparties keep trusting the same contract address.

## Starting a migration takes explicit authority, and a second request joins the run already underway [#starting-a-migration-takes-explicit-authority-and-a-second-request-joins-the-run-already-underway]

The Console's System updates page is where an operator reads and starts a migration. It lists every component in one table with the columns Component, State, Tokens affected and Area, where Area is the group the component belongs to, such as token factories, add-ons or compliance modules. A replacement of a global compliance module needs the compliance manager role on the signing wallet, and the run leaves it out without that role. [System updates](https://docs.settlemint.com/docs/console/organisation-settings/system-updates) describes the page.

The migration submits transactions from the organisation's own signing wallet, so starting one needs three things before anything on-chain is signed. The wallet holds the role a comparison needs on the system contract, it holds a management key on the organisation identity, and you pass a wallet verification step, such as a PIN code. Without the key, the start is refused. If a migration is already running for the organisation, meaning it is running, waiting on a step, or suspended, a second start request joins the run already in progress rather than starting a competing one. The Console shows the same live progress either way. The migration proceeds as a background workflow, so an operator can navigate away and come back to see it still running, waiting on a step, or finished.

## A version bump repoints one registry row and never creates a second [#a-version-bump-repoints-one-registry-row-and-never-creates-a-second]

Each organisation holds its own addon registry, a contract on its own chain that the migration repoints. The Directory is a separate, platform-owned catalogue on the same chain. The organisation's registry repoints itself to match what the Directory expects. It never changes the Directory. Every component the Directory tracks is addressed by a stable type id: for example, the settlement addon's id is the fixed hash of the string "xvp-settlement". Every implementation of that same addon declares that identical id, because the id names the slot in the registry, not a specific version of the logic behind it. Installing a component in an organisation's registry for the first time calls a function named registerSystemAddon, which reverts if the organisation already has that type id registered and active. Calling it for an archived type id unarchives the entry. Shipping a new version instead calls setAddonImplementation, which requires the organisation to already have that id registered and overwrites the implementation address stored at that row.

A new version of a component is the same registry entry pointed at a new implementation. Addon proxies resolve their logic through the row on every call, so they move when the row changes. For a factory-style addon, the instance implementation the factory deploys is a separate setting that the migration syncs in its own step, as the factory comparison describes. On chain, the registry accepts that change from any wallet that holds the System manager role, in one call with no second signer and no delay. Control who holds that role, and require custody approval on its wallet, if a repoint needs more than one person.

Comparing an organisation's registry against the Directory's module set compares addresses only. For each component, the platform reads the address the organisation's registry has and compares it to the address the Directory expects. A component's status follows directly from that comparison, as this table shows.

Factory-style addons carry a second, independent comparison. The factory contract's own registry row can be current while the instance implementation it deploys, the logic that already-created instances run, still lags behind, since the two can be updated separately. Only the type id ties them together as one addon.

| API status | Console state | What it means |
| --- | --- | --- |
| `up-to-date` | Up to date | The organisation's deployed address matches what the Directory expects, or the Directory has no expectation for this component yet. |
| `update-available` | Upgrade available | An address is deployed, but it differs from what the Directory expects. |
| `new` | Not installed | The Directory expects this component, but the organisation has nothing deployed for it yet. |

The Console shows two more states. Needs compliance manager marks a global compliance module replacement that the signing wallet lacks the role for. Not verified marks a component whose tokens' version the platform could not read.

## A status check reports what to repoint, never what changed [#a-status-check-reports-what-to-repoint-never-what-changed]

A migration comparison call returns components grouped the same way the Console displays them, each carrying a status of `up-to-date`, `update-available` or `new`. A component's status alone tells you whether a repoint is available. It does not tell you what changed in the new implementation, since the comparison is address-level, not a semantic diff of behaviour. Reading the implementation change is a source-level exercise against the module set's release notes or diff, not something the compare endpoint answers.

Starting the migration itself is not a single transaction. It runs as a durable background workflow keyed to the organisation, so a client that starts a migration and loses its connection can reconnect and resume watching the same run rather than losing state or accidentally starting a second one. Only the running, waiting and suspended states count as an existing run that a second start request can join.

| Run state | The migration API reports | A second start request |
| --- | --- | --- |
| Running | Running | Joins this run |
| Waiting | Running | Joins this run |
| Suspended | Running | Joins this run |
| Completed | Succeeded | Starts a new run |
| Failed | Failed | Starts a new run |

A run moves between running, waiting and suspended until it completes or fails. A retry after a failure starts a new run and never resumes the one that failed.

The workflow signs its on-chain calls with the organisation's own submission signer, resolved per network and system, according to the configured custody path. A signer that cannot be resolved degrades specific steps, such as feed backfill, instead of failing the whole run.

Three further details shape what a migration touches. First, an organisation can opt in to migrating components the Directory marks experimental. Left at its default, the migration skips them and they stay visible as pending rather than being repointed silently. Second, a small set of components sync without ever appearing as a row in the comparison or in the Console: they still repoint, but a reader watching only the visible list does not see them move. Third, when a factory-style addon does not support the interface a factory-instance update needs, the migration skips that one factory's instance update and the run continues. The workflow's own log records the skip, and the Console does not show it.

## Authorise and validate an upgrade before production [#authorise-and-validate-an-upgrade-before-production]

The selected signing path applies its verification and approval requirements. An authenticated API caller can also start the workflow when authorised.

Validate the selected module set against the deployment's current state before a production upgrade. A local chain fork can expose assumptions that a fresh test deployment would miss. The migration API checks authorisation and starts the workflow. It does not run or verify a deployment-specific fork test for you.

1. Review the release and the current deployment.
2. Validate the upgrade against representative state, for example on a local fork of the chain.
3. An authorised operator starts the migration.
4. The signing policy authorises each transaction.
5. Review the workflow outcome and the component changes.

Validation is an operational step before the authorised migration request. Retain its results with the change approval.

On-chain implementation-change events record which components changed. Combine them with the workflow outcome, initiating actor, and your change-approval evidence. The chain and workflow journal do not replace that approval record.

## Frequently asked questions [#frequently-asked-questions]

**Does migrating change a component's address that other systems integrate against?**

No. A migration overwrites the implementation address stored at the registry row. The row's own address, and the address of anything already deployed through it, stays exactly where it was. A counterparty or integration that already has that address saved keeps the same address. Review behaviour and interface compatibility before upgrading. A stable address does not guarantee unchanged behaviour.

**Can a chain skip a version and jump straight to the latest?**

Yes. The comparison and repoint mechanism does not require passing through every intermediate version: an organisation's registry compares its current address directly against what the Directory expects and repoints once. What a specific module set's implementation is allowed to assume about the prior version it replaces is a source-level concern for that implementation, not a limitation of the repoint mechanism itself.

**Do you have to start a migration to see whether a component has an update available?**

No. Comparing reads the organisation's current on-chain state and signs nothing, so it commits the organisation to nothing. It still needs the admin or system manager role on the selected wallet, the same role as starting a migration. A caller without it is refused with "System updates need the admin or system manager role."

## Related concepts [#related-concepts]

- [EVM Contract Set](https://docs.settlemint.com/docs/platform/evm-contract-set): The identity, compliance, custody, and settlement contracts a module set deploys, such as the settlement addon.
- [What DALP is](https://docs.settlemint.com/docs/platform): How the platform divides into named systems, one of which owns the Directory a chain's components are compared against.
- [Role Grant](https://docs.settlemint.com/docs/concepts/compliance-and-identity/role-grant): The on-chain permission, held as the admin or system manager role, that an operator needs to start a migration.