Skip to main content
POST
Prepare a wallet-ownership proof
Requires scope: manage:accounts — see Required scopes. Returns the message a self-custody customer must sign to prove they control the destination wallet of a virtual bank account. Nothing is persisted — there is no preparation id and no expiry, so two calls for the same account and wallet return an equivalent message.
The customer must sign message verbatim and blind. It embeds an opaque provider token, so do not reformat, re-encode, pretty-print, or reconstruct it — the signature is checked against the exact bytes, and a mismatch fails with signature-mismatch.
Submit the message and signature in the ownershipProof block of Create a virtual bank account. Not every account needs this step. Call it to find out: if a proof is required you get the message to sign, and if it isn’t you get 400 ownership-proof-not-applicable and can create the account directly. Only an externally-owned account can sign — the scheme is EIP-191, and ERC-1271 contract signatures are not supported. Self-custody wallets are single-key wallets only for now.

Errors

The codes this endpoint can return, in addition to the standard errors. Branch on code, never the message.

Authorizations

Headers

x-tenant-id
string<uuid>

Which tenant the request is scoped to, among those your token grants. Omit it when the token grants exactly one tenant; it is required when the token grants more than one. A supplied value must exactly match a tenant the token grants.

Absent when required, blank, malformed, or naming a tenant the token does not grant — each gets the same generic 403 forbidden, which reveals neither whether a tenant exists nor which ones you may use. Send the header once: a repeated header is rejected the same way.

Example:

"3fa85f64-5717-4562-b3fc-2c963f66afa6"

Path Parameters

accountId
string<uuid>
required

Unique account identifier

Body

application/json

Request to assemble the wallet-ownership-proof message for a virtual bank account.

walletAddress
string
required

The destination self-custody wallet address to prove ownership of

Maximum string length: 128
blockchain
string
required

The chain of the destination wallet (e.g. ETHEREUM)

Maximum string length: 32

Response

The assembled message to sign

success
boolean

Indicates whether the request was successful

result
object

The fully-assembled message to sign verbatim. No preparation id, no expiry and no provider identifier are returned — the embedded provider customer token stays opaque inside message.