Manage mutable token metadata for DALP asset tokens

Set and remove mutable token metadata entries for DALP asset tokens using the token metadata API.

Token metadata stores issuer-defined asset facts such as issuer name, coupon rate, maturity type, reporting category, or other fields collected during asset creation. Use the token metadata API when an integration needs to keep mutable asset facts current after deployment without redeploying the token.

DALP changes metadata on the token contract through the transaction queue. Use the endpoint only for fields that remain editable on the issued asset. Immutable metadata stays locked after deployment.

Prerequisites

A deployed token address.
A caller with the token governance permission for metadata changes.
A metadata key that is mutable on the issued asset.
Wallet verification for the transaction-submitting wallet when the active authentication flow requires it.

Choose the right operation

Task	API operation	Use when
Set one or more metadata values	`PATCH /api/v2/tokens/{tokenAddress}/metadata`	You need to add or update mutable metadata fields in one request.
Remove one metadata value	`DELETE /api/v2/tokens/{tokenAddress}/metadata`	You need to clear a single metadata key from the token.

Set metadata entries

Call PATCH /api/v2/tokens/{tokenAddress}/metadata with a metadataValues object. Metadata keys are issuer-defined strings. Values can be strings or finite numbers.

curl -X PATCH "$DAPI_URL/api/v2/tokens/0x1111111111111111111111111111111111111111/metadata" \
  -H "X-Api-Key: $DALP_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "metadataValues": {
      "issuerName": "Northwind Treasury",
      "couponRate": 5.5
    }
  }'

DALP encodes metadata values as strings before submitting the transaction. Numeric values are accepted and written as their string form. Numeric zero is preserved. Empty string values are ignored rather than written.

DALP submits the metadata change through the transaction queue. When the transaction completes synchronously, the response contains the token read-back. When the transaction is accepted asynchronously, use the returned transaction tracking data to monitor completion.

Remove one metadata entry

Call DELETE /api/v2/tokens/{tokenAddress}/metadata with the metadata key to remove.

curl -X DELETE "$DAPI_URL/api/v2/tokens/0x1111111111111111111111111111111111111111/metadata" \
  -H "X-Api-Key: $DALP_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "metadataKey": "issuerName"
  }'

metadataKey must be a non-empty string of at most 200 characters. The remove operation clears one key per request.

Permission and mutability rules

Metadata changes require governance permission. DALP checks the caller before queuing the transaction. A caller without the required permission receives an error before transaction submission.

The metadata schema controls which fields can change after deployment. Immutable fields cannot be updated later. Restricted-mutable fields are not locked on-chain during asset creation. DALP can edit restricted-mutable fields through the metadata endpoint when the caller passes token permission checks.

CLI equivalent

The DALP CLI exposes the same operations for one key at a time. Use the API when an integration needs to set several values in one request. Use the CLI for operator-driven single-key changes:

dalp tokens set-metadata --address 0x1111111111111111111111111111111111111111 --key issuerName --value "Northwind Treasury"
dalp tokens remove-metadata --address 0x1111111111111111111111111111111111111111 --key issuerName

Token metadata