# Manage on-chain token metadata

Source: https://docs.settlemint.com/docs/operators/asset-servicing/manage-token-metadata
Add, update, or remove on-chain metadata entries on a deployed asset from the Console after issuance.



On-chain metadata stores structured key-value entries on the token contract, such as an issuer reference, an external identifier, or a reporting category. Each entry sits alongside the asset and can be read by any integration. Use this page when you need to keep those entries current from the Console after the asset is deployed.

Some entries are locked at deployment and cannot change. The token metadata page handles both: it lets you add or update editable entries and remove the ones that are not locked, while leaving locked entries untouched.

Use this page for the web console workflow. Integrations can use the [token metadata API](/docs/api-reference/tokens/token-metadata), which exposes the same add, update, and remove operations.

## Prerequisites [#prerequisites]

* A deployed asset and its token metadata page.
* The token-level governance permission for metadata changes on that asset. Without it, the page is read-only.
* Wallet verification for the transaction-submitting wallet when the active authentication flow requires it.
* The metadata key you want to change is editable. Locked (immutable) entries cannot be updated or removed after deployment.

## Open the token metadata page [#open-the-token-metadata-page]

The metadata capability tile on the asset overview is the entry point. The tile shows the entry count and a short preview of existing entries, with a footer action that opens the full metadata page.

The metadata page opens as a full detail view at `/token/{assetClassSlug}/{templateSlug}/{tokenAddress}/metadata`, with its own breadcrumb instead of the workspace tab row. The page lists every entry with its key, value, and whether the entry is locked. For background on where the tile sits in the workspace, see the [asset detail workspace](/docs/operators/asset-servicing/asset-detail-workspace).

## Choose the right action [#choose-the-right-action]

| Goal                              | Action on the metadata page | Use when                                                                           |
| --------------------------------- | --------------------------- | ---------------------------------------------------------------------------------- |
| Record a new metadata fact        | **Add metadata entry**      | The key does not exist yet on the token.                                           |
| Change an existing editable value | **Add metadata entry**      | The key already exists and is editable. Reusing the same key overwrites its value. |
| Clear an editable entry           | **Remove entry**            | You no longer need an editable key on the token.                                   |

<Mermaid
  chart="graph TD
  Page[Metadata page] --> AddCheck{Editable key?}
  AddCheck -->|New or editable key| Add[Add metadata entry]
  AddCheck -->|Locked key| Blocked[Cannot change after deployment]
  Page --> RemoveCheck{Entry editable?}
  RemoveCheck -->|Editable| Remove[Remove entry shown per row]
  RemoveCheck -->|Locked| NoRemove[No remove control shown]"
/>

## Add or update an entry [#add-or-update-an-entry]

1. On the metadata page, choose **Add metadata entry**.
2. Enter the **Key** and the **Value**. Keys are issuer-defined strings; keep keys to 200 characters or fewer so the entry stays removable later. Values are stored as text.
3. Continue to the confirmation step, complete wallet verification when prompted, and submit.

Submitting an existing key overwrites its current value, so the same action covers both adding a new entry and editing an existing one. The change is submitted to the token contract through the transaction queue. When the transaction completes, the updated entry appears in the table.

<Callout type="info" title="Locked keys are blocked at input">
  If you enter a key that is locked on the token, the form rejects it before submission. Locked entries are fixed at
  deployment and cannot be overwritten from this page.
</Callout>

## Remove an entry [#remove-an-entry]

A per-row remove control appears only for editable entries. Locked entries have no remove control, because they cannot be cleared on-chain.

1. Find the entry in the table and choose its **Remove entry** control.
2. Confirm the removal, complete wallet verification when prompted, and submit.

Removal clears one key per action and cannot be undone. The transaction is submitted through the queue, and the entry disappears from the table once it completes.

For example, an asset team that tracks a `reportingCategory` entry can update it from `pilot` to `production` by reusing the same key on **Add metadata entry**, then confirm the new value in the table. There is no redeployment, and the change is visible to every integration that reads the token's metadata.

## Verify the result [#verify-the-result]

After a successful add, update, or remove, the metadata page reloads the entry list so the table reflects the current on-chain state. Confirm that the key shows the expected value, or that a removed key no longer appears, before treating the change as complete.

## Permissions and editability [#permissions-and-editability]

Metadata changes require the token governance permission. Operators without it see the metadata page in read-only form, with no add button and no per-row remove controls.

Editability is set when the asset is created. Entries marked immutable in the instrument template are locked on the deployed token and cannot change afterwards. Entries that are not locked remain editable through this page, subject to the governance permission. For how editability is defined during template design, see [instrument templates](/docs/operators/asset-creation/instrument-templates#define-metadata-fields).

## Related [#related]

* [Token metadata API](/docs/api-reference/tokens/token-metadata)
* [Asset detail workspace](/docs/operators/asset-servicing/asset-detail-workspace)
* [Instrument templates](/docs/operators/asset-creation/instrument-templates)
* [Create an asset](/docs/operators/asset-creation/create-asset)