Identity recovery API

Use the identity recovery API when an integration needs to help an Identity manager recover a user's wallet access. Recovery creates replacement wallet and identity records, moves the user's active identity to the new wallet path, and reports token recovery progress through a workflow status endpoint.

Identity recovery is an operator action for lost or compromised wallet access. It is not a general token transfer API, custody service, or claim migration tool.

Recovery creates a replacement identity. KYC and compliance claims on the old identity do not migrate, so the required trusted issuers must issue new claims for the recovered identity after the workflow completes.

Wallet binding and address-change controls

DALP binds an onboarded participant to wallets through the participant record, the OnchainID identity, and the system Identity Registry. A registered wallet address is not just a profile field that an investor can edit. Token eligibility depends on the registered wallet and its OnchainID claims.

For lost or compromised wallet access, use identity recovery instead of replacing the address in place. The recovery endpoints select the target user inside the caller's active organization and require the Identity manager recovery permission.

If the request supplies a wallet address, DALP checks participant ownership. A wallet outside the selected participant is rejected. When no wallet is supplied, DALP resolves the participant's effective wallet for the active organization rather than accepting an arbitrary replacement address from the request.

Recovery creates the replacement wallet path itself. DALP generates a new EOA, creates a new OnchainID, creates a replacement personal smart wallet when needed, links registered lost wallets to their replacements in the Identity Registry, revokes the user's active sessions and wallet security factors, and attempts token recovery for balances found on the affected wallets.

Endpoints

The identity recovery API exposes three endpoints:

Preview and execute require a caller with the Identity manager recovery permission. Status polling is available to callers with that permission and to the caller that initiated the recovery workflow in the same active organisation.

Preview recovery impact

Call the preview endpoint before submitting recovery. If you know the lost wallet address, pass it as the optional wallet query parameter.

When the request omits wallet, DALP selects the target user's effective wallet for the caller's active organization.

• If account abstraction is enabled and the user already has a personal smart wallet, DALP selects that smart wallet.
• Otherwise, DALP falls back to the user's signing EOA.

Use the returned lostWallet as the explicit wallet value when you execute recovery. That keeps the submitted workflow tied to the wallet the operator reviewed, including AA-enabled cases where execute can otherwise provision or select a different default smart-wallet path.

curl --globoff "$DALP_API_URL/api/v2/identity-recoveries/user_123/preview?wallet=0x1000000000000000000000000000000000000001" \
  --header "X-Api-Key: $DALP_API_TOKEN"

The response shows the user, the wallet being recovered, the current identity status, token balances that need recovery, and blocking reasons when recovery cannot proceed.

{
  "data": {
    "user": {
      "id": "user_123",
      "email": "[email protected]",
      "name": "Platform operator"
    },
    "lostWallet": "0x1000000000000000000000000000000000000001",
    "identity": {
      "id": "0x2000000000000000000000000000000000000002",
      "status": "registered",
      "isMarkedAsLost": false
    },
    "tokenBalances": [
      {
        "tokenAddress": "0x3000000000000000000000000000000000000003",
        "tokenName": "Example Bond",
        "tokenSymbol": "EXB",
        "balance": "10.5",
        "balanceExact": "10500000000000000000",
        "decimals": 18
      }
    ],
    "canRecover": true,
    "blockingReasons": []
  }
}

Do not execute recovery when canRecover is false. Resolve the listed blocking reasons first.

Submit recovery

Submit recovery with the userId and, when needed, the specific lost wallet address. The executing administrator may also need to provide wallet verification.

curl "$DALP_API_URL/api/v2/identity-recoveries" \
  --request POST \
  --header "X-Api-Key: $DALP_API_TOKEN" \
  --header "Content-Type: application/json" \
  --header "Prefer: respond-async" \
  --data '{
    "userId": "user_123",
    "wallet": "0x1000000000000000000000000000000000000001"
  }'

With Prefer: respond-async, a successful response means DALP accepted the workflow request. Use the returned statusUrl to track the transaction request. Continue to use the identity recovery status endpoint to track recovery phases.

{
  "transactionId": "txreq_123",
  "status": "QUEUED",
  "statusUrl": "/api/v2/transaction-requests/txreq_123"
}

Without Prefer: respond-async, the request starts in synchronous mode. If the recovery finishes within the wait window, DALP returns the standard mutation envelope.

{
  "data": {
    "success": true
  },
  "meta": {
    "txHashes": []
  },
  "links": {
    "self": "/v2/identity-recoveries"
  }
}

Long-running recoveries can still continue asynchronously. If the synchronous wait times out, DALP returns the same accepted workflow shape as an explicit async request. Treat both response shapes as valid and poll the returned statusUrl, then use the identity recovery status endpoint for recovery phases.

Poll recovery status

Poll the status endpoint until the workflow reaches completed, completed-with-token-failures, or failed.

curl "$DALP_API_URL/api/v2/identity-recoveries/user_123/status" \
  --header "X-Api-Key: $DALP_API_TOKEN"

The status response includes the current phase, token progress, the replacement wallet and identity when available, and a per-token failure manifest when recovery finished with token-level failures.

{
  "data": {
    "phase": "completed-with-token-failures",
    "tokensRecovered": 2,
    "totalTokens": 3,
    "error": null,
    "newWallet": "0x4000000000000000000000000000000000000004",
    "newIdentity": "0x5000000000000000000000000000000000000005",
    "tokenRecoveryFailures": [
      {
        "tokenAddress": "0x3000000000000000000000000000000000000003",
        "holderAddress": "0x1000000000000000000000000000000000000001",
        "reason": "TOKEN_PAUSED",
        "message": "Token recovery failed because the token is paused.",
        "rawError": "execution reverted"
      }
    ]
  }
}

Treat completed-with-token-failures as a partial success. The identity recovery link is in place, but the listed token balances still need operator follow-up. Typical token failure reasons are TOKEN_PAUSED, MISSING_CUSTODIAN_ROLE, NO_TOKENS, RPC_ERROR, and UNKNOWN.

Use the failure manifest to decide the next operator action:

The status phase field uses the recovery workflow phase names shown below.

CLI workflow

Use the CLI when an operator wants to run the same recovery flow from a terminal instead of calling the API directly. The CLI exposes the same preview, execute, and status sequence.

# Preview the recovery impact for DALP's default selected wallet.
dalp identity-recoveries preview user_123

# Preview or execute recovery for a specific lost wallet.
dalp identity-recoveries preview user_123 0x1000000000000000000000000000000000000001
dalp identity-recoveries execute user_123 0x1000000000000000000000000000000000000001

# Check recovery progress and token-level failures.
dalp identity-recoveries status user_123

When the wallet argument is omitted, the CLI asks DALP to select the target user's effective wallet for the caller's active organization. Preview first so the operator can confirm the selected user, wallet, balances, and blockers. Then pass the previewed wallet address to execute when the recovery must target that exact address.

Operational notes

• Use preview first so operators can see the affected wallet, identity status, balances, and blockers before submitting recovery.
• Poll status after submit; the execute endpoint returns after the workflow is accepted.
• Recheck identity and claim state after completion. KYC and compliance claims do not migrate automatically to the replacement identity; each required trusted issuer must re-issue its claims externally.
• A missing active workflow returns a not-found response to authorised callers. Unauthorised callers receive an authorisation error instead of a workflow existence signal.

Related

• CLI command reference
• API reference
• Error handling
• User management