> ## Documentation Index
> Fetch the complete documentation index at: https://docs.crown-brlv.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Whitelisting External Wallets

> Learn how to whitelist an external wallet by having it sign a challenge

## 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.

> [!NOTE]
>
> 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](https://docs.crown-brlv.com/api-reference/endpoint/v1/wallets/issue-external-wallet-challenge.md):

```bash theme={null}
curl -X POST https://app.crown-brlv.com/api/v1/accounts/{account-id}/external-wallets/{address}/challenge \
  -H "X-API-Key: your_api_key" \
  -H "Authorization: Bearer your_jwt_token"
```

`{account-id}` is your own account or one of your sub-accounts.
The response carries the text the wallet signs:

```json theme={null}
{
  "challenge": "Crown: whitelist wallet 0xdda4775ed1d0c831b006fd4061edb1b30693a44c for account 019712cf-c86d-703f-85b8-bdaa4fc8d254. Expires at 2024-01-15T10:45:00Z.",
  "expires-at": "2024-01-15T10:45:00Z"
}
```

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](https://docs.ethers.org/v6/):

```javascript JavaScript theme={null}
import { Wallet } from 'ethers';

const wallet = new Wallet(walletPrivateKey);
const signature = await wallet.signMessage(challenge);
```

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](https://docs.crown-brlv.com/api-reference/endpoint/v1/wallets/whitelist-external-wallet.md):

```bash theme={null}
curl -X POST https://app.crown-brlv.com/api/v1/accounts/{account-id}/external-wallets \
  -H "X-API-Key: your_api_key" \
  -H "Authorization: Bearer your_jwt_token" \
  -H "Content-Type: application/json" \
  -d '{
    "address": "0xdDa4775Ed1d0c831B006FD4061Edb1b30693a44c",
    "challenge": "Crown: whitelist wallet 0xdda4775ed1d0c831b006fd4061edb1b30693a44c for account 019712cf-c86d-703f-85b8-bdaa4fc8d254. Expires at 2024-01-15T10:45:00Z.",
    "signature": "0x055b70e307b8ebbba01105a026164f5a8526af8ddf7149e3184d1d7e0bee4279377d982f2592028cdcea412105aece8b41529aac93e1c29545b9286d6c0071f41b",
    "capabilities": ["fx"],
    "custody-type": "self",
    "custody-country": "BRA",
    "owner-type": "account-holder"
  }'
```

`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](https://docs.crown-brlv.com/api-reference/endpoint/v1/wallets/whitelist-external-wallet.md).

The response returns the address in EIP-55 checksum form:

```json theme={null}
{
  "external-wallet": {
    "address": "0xdDa4775Ed1d0c831B006FD4061Edb1b30693a44c",
    "capabilities": ["fx"],
    "created-at": "2024-01-15T10:31:12Z"
  }
}
```

## 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.

> [!WARNING]
>
> 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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.