External Accounts

Start an ownership verification challenge

Changed on Sep 15, 2026

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

Request

Base URL: https://api.lightspark.com/grid/2025-10-13
URL: https://api.lightspark.com/grid/2025-10-13/customers/external-accounts/{externalAccountId}/challenge
Auth: HTTP basic

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.

Method	Description
WALLET_SIGNATURE	Prove control of the wallet by signing a message with the wallet's key
LIVENESS	Prove identity via a hosted biometric verification flow

Example request

{
  "method": "WALLET_SIGNATURE"
}

Response

Challenge created; the method-specific material is returned.

Example response

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

Changes

Sep 15, 20263966e5d38aad Revision changes
- breaking
  removed the required property from the response with the status
- breaking
  removed the required property from the response with the status
- breaking
  removed the required property from the response with the status
- breaking
  removed the required property from the response with the status
- breaking
  removed the required property from the response with the status
- breaking
  removed the required property from the response with the status
- breaking
  removed the required property from the response with the status
- breaking
  removed the required property from the response with the status
- breaking
  removed the required property from the response with the status
- breaking
  removed the required property from the response with the status
- warning
  added the new ACCOUNT_NOT_FOUND enum value to the response property for the response status
- warning
  added the new AUTH_METHOD_NOT_FOUND enum value to the response property for the response status
- warning
  added the new CUSTOMER_NOT_FOUND enum value to the response property for the response status
- warning
  added the new DOCUMENT_ALREADY_EXISTS enum value to the response property for the response status
- warning
  added the new DOCUMENT_HOLDER_NOT_FOUND enum value to the response property for the response status
- warning
  added the new DUPLICATE_EXTERNAL_ACCOUNT enum value to the response property for the response status
- warning
  added the new DUPLICATE_PAY_REQUEST enum value to the response property for the response status
- warning
  added the new INSUFFICIENT_FUNDS enum value to the response property for the response status
- warning
  added the new NOT_FOUND enum value to the response property for the response status
- warning
  added the new PAYMENT_URL_NOT_FOUND enum value to the response property for the response status
- warning
  added the new PLATFORM_NOT_FOUND enum value to the response property for the response status
- warning
  added the new QUOTE_EXPIRED enum value to the response property for the response status
- warning
  added the new QUOTE_RATE_UNAVAILABLE enum value to the response property for the response status
- warning
  added the new REQUEST_NOT_FOUND enum value to the response property for the response status
- warning
  added the new SESSION_NOT_FOUND enum value to the response property for the response status
- warning
  added the new SMS_OTP_CREDENTIAL_SET_CHANGED enum value to the response property for the response status
- warning
  added the new SMS_OTP_PHONE_NUMBER_ALREADY_EXISTS enum value to the response property for the response status
- warning
  added the new STABLECOIN_AMOUNT_NOT_REPRESENTABLE enum value to the response property for the response status
- warning
  added the new STABLECOIN_BURN_SOURCE_NOT_SUPPORTED enum value to the response property for the response status
- warning
  added the new STABLECOIN_EXTERNAL_ACCOUNT_LINK_FAILED enum value to the response property for the response status
- warning
  added the new STABLECOIN_EXTERNAL_ACCOUNT_LINK_METHOD_REQUIRED enum value to the response property for the response status
- warning
  added the new STABLECOIN_EXTERNAL_ACCOUNT_NOT_FOUND enum value to the response property for the response status
- warning
  added the new STABLECOIN_EXTERNAL_ACCOUNT_NOT_LINKED enum value to the response property for the response status
- warning
  added the new STABLECOIN_EXTERNAL_ACCOUNT_NOT_SUPPORTED enum value to the response property for the response status
- warning
  added the new STABLECOIN_EXTERNAL_ACCOUNT_PROVIDER_LINK_FAILED enum value to the response property for the response status
- warning
  added the new STABLECOIN_EXTERNAL_ACCOUNT_PROVIDER_LINK_REQUIRED enum value to the response property for the response status
- warning
  added the new STABLECOIN_GRID_OPERATIONS_NOT_ENABLED enum value to the response property for the response status
- warning
  added the new STABLECOIN_NOT_FOUND enum value to the response property for the response status
- warning
  added the new STABLECOIN_NOT_PROVISIONED enum value to the response property for the response status
- warning
  added the new STABLECOIN_OPERATION_NOT_FOUND enum value to the response property for the response status
- warning
  added the new STABLECOIN_OPERATION_NOT_SUPPORTED enum value to the response property for the response status
- warning
  added the new STABLECOIN_PROVIDER_ERROR enum value to the response property for the response status
- warning
  added the new STABLECOIN_PROVIDER_SOURCE_NOT_LINKED enum value to the response property for the response status
- warning
  added the new STABLECOIN_SYMBOL_ALREADY_EXISTS enum value to the response property for the response status
- warning
  added the new STABLECOIN_TOKEN_IDENTIFIER_ALREADY_EXISTS enum value to the response property for the response status
- warning
  added the new STABLECOIN_VERIFICATION_FAILED enum value to the response property for the response status
- warning
  added the new VERIFICATION_NOT_FOUND enum value to the response property for the response status
- warning
  added the new WALLET_NOT_PROVISIONED enum value to the response property for the response status
- info
  added the required property to the response with the status
- info
  added the required property to the response with the status
- info
  added the required property to the response with the status
- info
  added the required property to the response with the status
- info
  added the required property to the response with the status
Sep 13, 2026ccf658daca4b Revision changes
- warning
  added the new BANK_ACCOUNT_VALIDATION_PENDING enum value to the response property for the response status

Operation history (5 revisions)