Skip to content

Reusable Wallet Verification

Reuse previous wallet ownership evidence without storing raw owner-name PII

Reusable wallet verification lets CryptoSwift complete a new wallet verification by matching it with a previous eligible verified wallet verification. This reduces repeated user challenges when the same wallet has already been verified for the same owner.

Reuse matching is cross-tenant. A verification created by one tenant can be eligible as matching evidence for another tenant when the reusable matching criteria are met.

When To Use It

Use reusable verification when:

  • The customer is verifying a wallet that may have already been verified before.
  • You can produce a stable SHA-256 hash of the wallet owner's normalized full name.
  • Your policy allows reuse of recent wallet ownership evidence.
  • You want to reduce unnecessary repeat signing, screenshots, declarations, or Satoshi Tests.

If no reusable match is found, the verification remains PENDING and the customer continues through the normal widget or API proof flow.

How It Works

  1. Your backend creates a wallet verification and includes reuse.
  2. CryptoSwift looks for a previous eligible VERIFIED wallet verification with the same wallet address and blockchain.
  3. CryptoSwift compares reusable subject attributes and policy requirements.
  4. If the match satisfies your policy, the new verification is automatically marked VERIFIED.
  5. If the match does not satisfy your policy, CryptoSwift returns a normal pending verification for the customer to complete.

Reusable verification never copies sensitive proof artifacts from the source verification into the new reused verification. For example, source screenshots, signatures, signed messages, Satoshi Test amounts, and deposit addresses are not copied into the reused record.

Request Shape

Add reuse when creating the wallet verification.

curl --location 'https://api-dev.cryptoswift.eu/wallet-verification' \
--header 'x-api-key: $API_KEY' \
--header 'Content-Type: application/json' \
--data '{
  "asset": "ETH",
  "blockchain": "Ethereum",
  "address": "0x32Be343B94f860124dC4fEe278FDCBD38C102D88",
  "allowedFlows": ["SIGNATURE_PROOF"],
  "reuse": {
    "subject": {
      "type": "NATURAL",
      "nameHash": "6f1c9d3d5c2f7b1e8a4f7c9b0d3a1e5f6c8b9a0d2e4f6a8b0c1d3e5f7a9b1c3"
    },
    "policy": {
      "minimumMatchLevel": "MEDIUM",
      "maxReuseAgeDays": 180
    }
  }
}'

Subject Data

subject.type describes the wallet owner type:

  • NATURAL - an individual person
  • LEGAL - a legal entity

subject.nameHash is required for reusable verification. Hash the owner's full legal name after NFKC normalization, trimming, lowercasing, and collapsing repeated whitespace to one space. Send the lowercase 64-character SHA-256 hex digest, not the plain-text name.

Policies

Policies control how strong and how recent a previous verification must be before CryptoSwift can reuse it.

minimumMatchLevel

minimumMatchLevel sets the minimum accepted match strength:

LevelRequired match
LOWWallet address, blockchain, and subject type
MEDIUMWallet address, blockchain, and nameHash
HIGHWallet address, blockchain, subject type, and nameHash

Default: MEDIUM

maxReuseAgeDays

maxReuseAgeDays limits how old the source verification can be.

Default: 180

Use a shorter age for stricter compliance policies. Use a longer age only when your internal policy accepts older ownership evidence.

Response

When a reusable match is found, the verification is returned as VERIFIED and includes reuse details.

{
  "id": "9f3dc458-a2be-4a34-bcb7-f1f677a0864c",
  "asset": "ETH",
  "blockchain": "Ethereum",
  "address": "0x32Be343B94f860124dC4fEe278FDCBD38C102D88",
  "status": "VERIFIED",
  "statusReasoning": "Verification completed using reusable wallet verification",
  "reuse": {
    "matchLevel": "HIGH",
    "matchedAttributes": ["blockchain", "address", "nameHash", "type"],
    "policy": {
      "minimumMatchLevel": "MEDIUM",
      "maxReuseAgeDays": 180
    }
  }
}

When no reusable match is found, reuse is null, the verification remains PENDING, and you continue with the normal widget or API verification flow.

Data Storage And PII

For reusable matching, CryptoSwift does not store the wallet owner's plain-text name. Your integration sends only nameHash, the lowercase 64-character SHA-256 hex digest created from the normalized full legal name.

On CryptoSwift's side, reusable matching data is stored separately from raw owner-name PII. The reusable verification record can store:

  • Owner type, such as NATURAL or LEGAL
  • Server-protected owner name digest used for matching
  • Source verification reference
  • Match level and matched attributes
  • Policy values applied at the time of matching
  • Source verification timestamp

For reused verifications, CryptoSwift does not copy sensitive proof artifacts from the source verification into the new record. This keeps the reused record focused on the reuse decision and its audit evidence.

Operational Guidance

  • Normalize names with NFKC normalization, trimming, lowercasing, and collapsing repeated whitespace to one space before hashing. Inconsistent normalization reduces match rates.
  • Do not use customer IDs, emails, account numbers, or other direct identifiers as nameHash input.
  • Choose HIGH when both owner type and normalized name hash must match.
  • Choose shorter maxReuseAgeDays values for stricter review policies.
  • Always reconcile completion through webhook events or a server-side status check.

Next steps