---
title: "Start an ownership verification challenge"
method: POST
path: "/platform/external-accounts/{externalAccountId}/challenge"
tags: ["External Accounts"]
---

# Start an ownership verification challenge

`POST /platform/external-accounts/{externalAccountId}/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`.

## Path parameters

- `externalAccountId` string, required

## Request body

- OwnershipChallengeRequest — Starts (or restarts) an ownership verification challenge for a crypto wallet external account.
  - `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 |

## Response `201`

Challenge created; the method-specific material is returned.

- union — An ownership verification challenge for a crypto wallet external account. The shape is determined by the challenge `method`.
  - WalletSignatureChallenge — A challenge to prove ownership of the wallet by signing a message with the wallet's key.
    - `method` 'WALLET_SIGNATURE', required — The verification method. Always `WALLET_SIGNATURE` for this shape.
    - `messageToSign` string, required — The exact message the wallet must sign, character-for-character. Submit the resulting signature via the verify endpoint.
    - `expiresAt` string, date-time, required — When this challenge expires. Prompt the user promptly; after expiry, start a new challenge.
  - LivenessChallenge — A challenge to prove ownership through a hosted biometric verification flow. Completes asynchronously — the outcome is delivered via `EXTERNAL_ACCOUNT.STATUS_UPDATED` webhooks or by polling the external account.
    - `method` 'LIVENESS', required — The verification method. Always `LIVENESS` for this shape.
    - `verificationLink` string, uri, required — Hosted verification URL to present to the user.
    - `token` string — Provider-specific token that can be used in place of `verificationLink` — for example, to embed the provider's SDK directly in your application. Only returned for providers that support direct SDK integration. Whether to use the hosted URL or the embedded SDK is up to you; both flows result in the same verification outcome.
    - `expiresAt` string, date-time, required — When this challenge expires. Prompt the user promptly; after expiry, start a new challenge.

## Other responses

- `400` — Bad request - Invalid parameters
- `401` — Unauthorized
- `404` — External account not found
- `409` — Ownership verification is not applicable to this external account (not a self-custody crypto wallet, not `FIRST_PARTY`, or already verified).
- `500` — Internal service error

---

[API](https://skmtc.net/stainless-api/apis/grid-api.md) · [All operations](https://skmtc.net/stainless-api/apis/grid-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/stainless-api/grid-api/revisions/aaa1fb8782c8/schema)