Wallet and identity recovery API reference

Use the identity recovery API when you need 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 operation for lost or compromised wallet access. The endpoint 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. Do not replace 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 and rejects any wallet outside the selected participant. When no wallet is supplied, DALP resolves the participant's effective wallet for the active organization.

Recovery creates the replacement wallet path itself. DALP generates a new EOA, deploys a new OnchainID, and creates a replacement personal smart wallet when needed. The platform then 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 your request omits wallet, DALP selects the target user's effective wallet for the caller's active organization.

• If advanced accounts 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. Your 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: poll the returned statusUrl, then use the identity recovery status endpoint to track recovery phases.

Poll recovery status

Poll the status endpoint until the workflow reaches completed, completed-with-token-failures, or failed. Use the phase and failure fields to decide your next step.

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 your operator's follow-up. Typical token failure reasons are TOKEN_PAUSED, MISSING_CUSTODIAN_ROLE, NO_TOKENS, RPC_ERROR, and UNKNOWN.

Use the failure manifest to determine the next operator step:

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-then-execute flow with a status command to check progress.

# 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, the wallet, any token balances, and any blocking reasons. 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, token balances, and any blocking reasons before submitting recovery.
• Poll status after submit; the execute endpoint returns after the workflow is accepted.
• Recheck identity and claim state once the workflow completes. KYC and compliance claims do not migrate automatically to the replacement identity; each required trusted issuer must re-issue its claims before your integration can treat the recovered identity as fully verified.
• 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