Skip to main content

Overview

You can whitelist an external wallet for your own account or one of your sub-accounts at any time, by having the wallet sign a challenge. The wallet is whitelisted at once, with no approval step. Any wallet that signs with its own key works, wherever it is held.
The account needs the manage-wallets capability.

Step 1: Ask for a challenge

Request a challenge for the account and the wallet’s address from the Issue External Wallet Challenge endpoint:
{account-id} is your own account or one of your sub-accounts. The response carries the text the wallet signs:
The challenge is valid for 15 minutes. Once it expires, ask for a new one.

Step 2: Sign the challenge with the wallet

The wallet signs the challenge exactly as returned, as a UTF-8 message with personal_sign (EIP-191). With ethers:
A wallet held at a wallet provider signs through that provider’s personal_sign API. A signature whose last byte is 0 or 1, or 27 or 28, is accepted, so the output of common wallet libraries works as is.

Step 3: Whitelist the wallet

Send the wallet, the challenge and the signature to the Whitelist External Wallet endpoint:
capabilities decides what the wallet is for:
  • ["fx"]: the wallet only receives FX payouts, and several accounts can have the same one.
  • Anything else, or no capabilities: the wallet also earns the account’s rewards, and belongs to that account alone.
The other fields follow the rules of a wallet declared when creating a sub-account, listed in the endpoint reference. The response returns the address in EIP-55 checksum form:

Limits

An address another account already uses is refused. A wallet that also earns rewards must not be in use by any account at all.
A smart-contract wallet, or an address that cannot sign such as an exchange deposit address, cannot be whitelisted this way. Contact Crown’s support team for those.