Recover assets

When a holder loses access to a wallet, or an unrelated token lands in an asset contract by mistake, an institution needs a governed way to move the affected balance without asking the original wallet to sign. DALP exposes three recovery operations on the asset for exactly these cases. Each one is a first-class, role-gated API call that a regulated operator can run under an approved recovery process and reconcile afterward.

These three operations act on the balances of one asset. To provision a replacement wallet and identity for a user across all their holdings, use identity recovery instead.

The diagram shows how the platform routes a recovery instruction. It validates the caller's role and wallet verification, then submits the on-chain call through the durable transaction queue. The recovery takes effect after the transaction confirms, and the indexed balances update after the indexer processes that block.

Choose the recovery operation

Pick the operation that matches the approved recovery decision.

Standard recovery and forced recovery both move the asset's own holder balance out of a lost wallet. They differ in who names the destination. Standard recovery sends the balance to the caller's own wallet, so it fits a holder who recovers their own position. Forced recovery sends the balance to a replacement wallet named in the request, so it fits a custodian who recovers on a holder's behalf.

ERC-20 recovery is a different operation. It moves a foreign token that is sitting in the asset contract address by mistake, not any holder balance of the asset itself.

Prerequisites

Confirm the following before you submit a recovery instruction.

• Platform URL, for example https://your-platform.example.com
• API key for a user with the required role: Emergency for standard and ERC-20 recovery, Custodian for forced recovery
• For forced recovery, the asset must include the CUSTODIAN token extension
• Wallet verification for the signing account, when the platform requires a PIN, OTP, or secret code
• Token contract address for the asset you administer
• The lost wallet address, and for forced recovery the replacement wallet address
• Approval evidence for the recovery decision

Recover a holder's own balance

Send a POST to the recoveries endpoint with the lost wallet address. The platform moves the asset balance from the lost wallet to the caller's wallet.

curl -X POST https://your-platform.example.com/api/v2/tokens/0xTOKEN/recoveries \
  -H "X-Api-Key: sm_dalp_xxxxxxxxxxxxxxxx" \
  -H "Idempotency-Key: recover-case-2026-01-15-001" \
  -H "Content-Type: application/json" \
  -d '{
    "lostWallet": "0x71C7656EC7ab88b098defB751B7401B5f6d8976F"
  }'

The platform validates the caller's Emergency role, wallet verification, and request shape, then queues the transaction and returns an asynchronous response with a transaction identifier and a status URL.

Recover a holder's balance to a replacement wallet

Send a POST to the forced-recoveries endpoint with the lost wallet and the replacement wallet. Forced recovery requires the Custodian role because the caller names both the source and the destination.

curl -X POST https://your-platform.example.com/api/v2/tokens/0xTOKEN/forced-recoveries \
  -H "X-Api-Key: sm_dalp_xxxxxxxxxxxxxxxx" \
  -H "Idempotency-Key: forced-recover-case-2026-01-15-001" \
  -H "Content-Type: application/json" \
  -d '{
    "lostWallet": "0x71C7656EC7ab88b098defB751B7401B5f6d8976F",
    "newWallet": "0x8ba1f109551bD432803012645Ac136ddd64DBA72"
  }'

The replacement wallet still needs the identity registration or verification that the asset requires of any recipient. Confirm the new wallet is eligible to hold the asset before you submit the request.

Return a stray ERC-20 from the contract

Send a POST to the erc20-recoveries endpoint when an unrelated ERC-20 token was sent to the asset contract address and needs to be returned. Name the foreign token, the recipient, and the amount in that token's base units.

curl -X POST https://your-platform.example.com/api/v2/tokens/0xTOKEN/erc20-recoveries \
  -H "X-Api-Key: sm_dalp_xxxxxxxxxxxxxxxx" \
  -H "Idempotency-Key: erc20-recover-case-2026-01-15-001" \
  -H "Content-Type: application/json" \
  -d '{
    "erc20Address": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
    "recipient": "0x71C7656EC7ab88b098defB751B7401B5f6d8976F",
    "amount": "1000000000000000000"
  }'

This operation moves the foreign token held by the asset contract. It does not touch any holder balance of the asset itself.

Request bodies

Standard recovery (/recoveries):

Forced recovery (/forced-recoveries):

ERC-20 recovery (/erc20-recoveries):

Every recovery request also accepts an optional walletVerification object when your platform requires a PIN, OTP, or secret code for the signing account.

What to verify after submission

Treat a recovery the same way you treat any other governed servicing operation on the asset.

1. Confirm the affected holder balances or token events through your operating view or API integration after the transaction confirms.
2. Record the token address, source address, destination address, amount where it applies, approving operator, request identifier, and transaction hash.
3. Keep the recovery approval and identity evidence outside the API request.
4. For a forced recovery, confirm the replacement wallet holds the recovered balance and can transact under the asset's compliance rules.

Use idempotency keys

Send an Idempotency-Key header on any recovery your integration may retry after a timeout. Reuse the same key only when the method, path, and request body match the original instruction. A retry without a key can queue a duplicate recovery.

Troubleshooting

Related guides

• Recover a user's identity for the identity-level workflow that provisions a replacement wallet across a user's holdings
• Forced transfer for governed exception moves between holders
• Freeze controls for regulatory and dispute holds
• Token holders and transfers for the recovery, transfer, and freeze API reference
• Track asynchronous transactions for polling queued transaction status
• Per-asset RBAC for Emergency and Custodian role context