# Wallet Verification

Source: https://docs.settlemint.com/docs/compliance-security/security/wallet-verification
Wallet verification gates blockchain write operations as a second security
layer beyond session authentication, using PIN, TOTP, or backup-code checks.




## Overview [#overview]

Wallet verification is the per-request check that protects blockchain write operations from browser sessions. Even with a valid authenticated session, you must include PIN, TOTP, or backup-code evidence before the platform passes the operation to the signing flow.

## System context [#system-context]

<Mermaid
  chart="`sequenceDiagram
  participant Operator as Authenticated operator
  participant Session as Platform session
  participant Challenge as Wallet verification
  participant API as Platform API transaction gate
  participant Signer as Signer or custody service
  participant Chain as Configured EVM network

  Operator->>Session: Submit blockchain write request
  Session->>Challenge: Require PIN, TOTP, or backup code
  alt verification accepted
    Challenge->>API: Release request to signing gate
    API->>Signer: Request signature or custody approval
    Signer->>Chain: Submit EVM transaction
  else missing or failed check
    Challenge-->>Operator: Reject before signing
  end

`"
/>

## Why wallet verification exists [#why-wallet-verification-exists]

Session authentication proves identity. Wallet verification proves intent for the specific request that will consume a wallet secret. Separating these checks means your browser session alone cannot trigger asset transfers, minting, burning, or other signing operations protected by the wallet-verification middleware.

The check runs prior to signing. The platform rejects the request at the gate when verification evidence is missing, the selected method is not configured for your account, or the credential is wrong.

See the [security overview](/docs/compliance-security/security) for how this check combines with authentication, authorization, custody policy, and on-chain transfer controls.

## Verification methods [#verification-methods]

Transaction-signing APIs accept these wallet verification methods. Organizations can enable one or more based on their security posture.

### PINCODE [#pincode]

A 6-digit PIN set at initial wallet creation. This method provides quick confirmation for routine transactions where you are already authenticated and working within the platform.

* Setup: define the PIN when creating the wallet.
* Usage: enter the 6-digit code alongside the transaction request.
* Trade-off: fastest confirmation, lower resistance to shoulder-surfing than TOTP.

### Two-factor authentication (TOTP) [#two-factor-authentication-totp]

Time-based one-time passwords generated by an authenticator app. Codes rotate every 30 seconds following RFC 6238.

* Setup: scan a QR code into your authenticator app at wallet creation.
* Usage: enter the current 6-digit code from the app.
* Trade-off: stronger than PIN (each code expires), but requires the authenticator device.

### Backup codes [#backup-codes]

Backup codes are one-time recovery codes generated at wallet creation. DALP generates 16 codes in `xxxxx-xxxxx` format. Each code passes verification once; reuse fails because DALP records every used code.

* Setup: the platform generates and stores the active code set at configuration time; store the codes securely offline.
* Usage: enter any unused code when PIN or TOTP is unavailable.
* Trade-off: last-resort recovery only; limited supply, one use per code.

## Passkeys and wallet verification [#passkeys-and-wallet-verification]

When enabled for the deployment, operators can use passkeys for account authentication. DALP documents passkey sign-in on the [Authentication](/docs/compliance-security/security/authentication) page.

For blockchain write requests, the wallet verification middleware accepts PINCODE, OTP, or SECRET\_CODES. Passkeys are not a wallet verification type. They authenticate account sign-in only.

## How verification works in requests [#how-verification-works-in-requests]

API procedures that trigger blockchain write operations accept a `walletVerification` object in the request body:

| Field                                       | Value                                     | Description                                         |
| ------------------------------------------- | ----------------------------------------- | --------------------------------------------------- |
| `walletVerification.verificationType`       | `PINCODE`, `OTP`, or `SECRET_CODES`       | Which wallet verification method the user presents  |
| `walletVerification.secretVerificationCode` | 6-digit string, TOTP code, or backup code | The credential for the selected verification method |

The Platform API validates the credential before forwarding the operation to the Workflow Engine. If verification fails, the platform rejects the request immediately. No gas flows, no custody provider interaction occurs, and no on-chain state changes.

### API key sessions bypass verification [#api-key-sessions-bypass-verification]

When an API key authenticates a request, wallet verification is not required. You can omit the `walletVerification` field from the request body. API keys carry scoped credentials for machine-to-machine use. The API key is the authorization factor, so a second interactive challenge is not part of that path.

## Failure cases [#failure-cases]

Wallet verification fails before the signing flow starts. The platform rejects the request when:

| Condition                                                               | Result                                               |
| ----------------------------------------------------------------------- | ---------------------------------------------------- |
| No authenticated user is available                                      | `UNAUTHORIZED` with `Authentication required`        |
| The user has no PIN, backup-code, or TOTP method configured             | `USER_MISSING_2FA` with setup guidance               |
| The request omits `walletVerification` for a browser-session write      | `BAD_REQUEST` with `Wallet verification is required` |
| The selected method is not configured for the user                      | `FORBIDDEN`                                          |
| The submitted PIN, backup code, or TOTP code is invalid or already used | `FORBIDDEN`                                          |
| Too many failed PIN, backup-code, or TOTP attempts in a short window    | `FORBIDDEN` with a retry message and seconds to wait |

When repeated attempts fail, DALP temporarily locks the affected verification method for that user. The platform rejects further attempts with a `FORBIDDEN` response whose message states how many seconds to wait. While the lockout is active, the platform rejects the call without checking the credential, so even a correct value must wait for the window to expire. A successful check within the threshold clears the recorded failures. The lockout covers the PIN, backup-code, and TOTP paths; the remote identity provider handles its own challenge.

Passkeys authenticate account sign-in. PINCODE, OTP, and SECRET\_CODES are the accepted wallet verification values for transaction-signing requests.

## Security considerations [#security-considerations]

Wallet verification uses wallet-specific PIN, backup-code, or TOTP records rather than the browser session token, keeping the credential path separate from session state.

A user must have the selected method enabled before it can satisfy a signing request. The platform records each backup code on use and tracks TOTP tokens so no token passes twice. Repeated failed PIN, backup-code, or TOTP attempts temporarily lock the affected method for that user, blunting online guessing of a low-entropy secret from a compromised session. A successful attempt resets the count. Machine-to-machine API-key requests skip the interactive wallet-verification challenge.

## See also [#see-also]

* [Security overview](/docs/compliance-security/security): the full defense-in-depth model
* [Signing Flow](/docs/architects/flows/signing-flow): how wallet verification fits the transaction lifecycle
* [Authentication](/docs/compliance-security/security/authentication): API-level rate limiting and RBAC
* [Authorization](/docs/compliance-security/security/authorization): role-based access controls
* [Key Management](/docs/architects/components/infrastructure/key-management): how the platform stores and uses signing keys