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 /platform/external-accounts/{externalAccountId}/challenge

Start an ownership verification challenge

cURL

curl --request POST \
  --url https://api.lightspark.com/grid/2025-10-13/platform/external-accounts/{externalAccountId}/challenge \
  --header 'Authorization: Basic <encoded-value>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "method": "WALLET_SIGNATURE"
}
'

201

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

Authorizations

Authorization · string · header · required

API token authentication using format <api token id>:<api client secret>

Path Parameters

externalAccountId · string · required

External account ID

Body

application/json

Starts (or restarts) an ownership verification challenge for a crypto wallet external account.

method · enum<string> · required

The verification method to use for this challenge.

Available options: WALLET_SIGNATURE, LIVENESS

Example:

"WALLET_SIGNATURE"

Response

201

application/json

Challenge created; the method-specific material is returned.

Wallet Signature Challenge

Liveness Challenge

An ownership verification challenge for a crypto wallet external account. The shape is determined by the challenge method.

method · enum<string> · required

The verification method. Always WALLET_SIGNATURE for this shape.

Available options: WALLET_SIGNATURE

Example:

"WALLET_SIGNATURE"

messageToSign · string · required

The exact message the wallet must sign, character-for-character. Submit the resulting signature via the verify endpoint.

Example:

"I verify that I control this wallet. Nonce: 019542f5-b3e7-1d02"

expiresAt · string<date-time> · required

When this challenge expires. Prompt the user promptly; after expiry, start a new challenge.

Example:

"2025-08-15T15:32:00Z"