Sign in

aaa1fb8782c8

latestOpenAPI 3.1.0Proprietary2026-08-141526321.5 MB
External Accounts

Start an ownership verification challenge

Start (or restart) ownership verification for a FIRST_PARTY self-custody crypto wallet external account in PENDING_OWNERSHIP_VERIFICATION or UNVERIFIED status. The response carries the method-specific challenge material:

  • WALLET_SIGNATURE — a messageToSign; have the wallet sign it exactly and submit the result to the verify endpoint to complete verification synchronously.
  • LIVENESS — a hosted verificationLink (and possibly an embed token); the user completes a biometric flow and verification completes asynchronously. The outcome is delivered via EXTERNAL_ACCOUNT.STATUS_UPDATED webhooks or by polling the account.

Calling this endpoint again abandons any in-flight challenge and issues a new one with the requested method — use it to retry after a failed attempt, to replace an expired challenge, or to switch methods. An UNVERIFIED account returns to PENDING_OWNERSHIP_VERIFICATION when a new challenge is issued.

Completing ownership verification moves the account to ACTIVE.

post/customers/external-accounts/{externalAccountId}/challenge

Path parameters

externalAccountIdstring required

External account ID

Request body

method'WALLET_SIGNATURE' | 'LIVENESS' required

The method used to verify ownership of a self-custody crypto wallet.

MethodDescription
WALLET_SIGNATUREProve control of the wallet by signing a message with the wallet's key
LIVENESSProve identity via a hosted biometric verification flow

Example request

{
  "method": "WALLET_SIGNATURE"
}

Response

Challenge created; the method-specific material is returned.

OR

Example response

{
  "method": "WALLET_SIGNATURE",
  "messageToSign": "I verify that I control this wallet. Nonce: 019542f5-b3e7-1d02",
  "expiresAt": "2025-08-15T15:32:00Z"
}