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

# Whitelist External Wallet

> Whitelists an external wallet for the account at once, with no approval step. The signature must be the wallet itself signing the challenge issued for this account and wallet by `POST /v1/accounts/{account-id}/external-wallets/{address}/challenge`.

`account-id` is the caller's own account or one of its sub-accounts. Requires the `manage-wallets` capability on the account.

The wallet takes the fields and rules of one declared at sub-account creation:

- A wallet whose `capabilities` is `fx` alone needs `custody-type`, `custody-country` (ISO-3) and `owner-type`. It needs `custodian-name` with `exchange` custody and refuses it with `self`, and needs `owner-name` with a `third-party` owner and refuses it otherwise.
- Any other wallet accepts `owner-type` `account-holder` only, and no `owner-name`.

Any wallet that signs with its own key can be whitelisted here. A smart-contract wallet, or an address that cannot sign such as an exchange deposit address, cannot: contact Crown for those.

**Refusals**

- `400` `Invalid value for signature: Invalid signature` when the signature is not the wallet's own.
- `400` `Invalid value for signature: Must be a 65-byte signature as 0x-prefixed hex`.
- `400` `Invalid value for challenge: Is not the challenge issued for this account and wallet`.
- `400` `Invalid value for challenge: Has expired`.
- `400` when a field rule above is broken, for example `Missing required field: custody-type`.
- `403` when the account lacks the `manage-wallets` capability.
- `404` when the account is neither the caller's nor one of its sub-accounts.
- `422` when another account already uses the address. A wallet with `rewards` must not be in use by any account at all.
- `422` when the account already has the wallet.
- `422` when Crown rejected the wallet for this account.
- `422` `This account is being closed and can only withdraw funds`.



## OpenAPI

````yaml POST /api/v1/accounts/{account-id}/external-wallets
openapi: 3.1.0
info:
  title: Crown API & Webhooks
  version: 1.0.0
  description: >-
    Open API 3 docs for Crown API


    Webhook events that Crown will POST to your configured endpoint URL. All
    webhooks expect a 200 OK response. Payloads use kebab-case for all keys to
    match the Crown API conventions.
servers:
  - url: https://app.crown-brlv.com
    description: Production server
security: []
paths:
  /api/v1/accounts/{account-id}/external-wallets:
    post:
      summary: Whitelist an external wallet
      description: >-
        Whitelists an external wallet for the account at once, with no approval
        step. The signature must be the wallet itself signing the challenge
        issued for this account and wallet by `POST
        /v1/accounts/{account-id}/external-wallets/{address}/challenge`.


        `account-id` is the caller's own account or one of its sub-accounts.
        Requires the `manage-wallets` capability on the account.


        The wallet takes the fields and rules of one declared at sub-account
        creation:


        - A wallet whose `capabilities` is `fx` alone needs `custody-type`,
        `custody-country` (ISO-3) and `owner-type`. It needs `custodian-name`
        with `exchange` custody and refuses it with `self`, and needs
        `owner-name` with a `third-party` owner and refuses it otherwise.

        - Any other wallet accepts `owner-type` `account-holder` only, and no
        `owner-name`.


        Any wallet that signs with its own key can be whitelisted here. A
        smart-contract wallet, or an address that cannot sign such as an
        exchange deposit address, cannot: contact Crown for those.


        **Refusals**


        - `400` `Invalid value for signature: Invalid signature` when the
        signature is not the wallet's own.

        - `400` `Invalid value for signature: Must be a 65-byte signature as
        0x-prefixed hex`.

        - `400` `Invalid value for challenge: Is not the challenge issued for
        this account and wallet`.

        - `400` `Invalid value for challenge: Has expired`.

        - `400` when a field rule above is broken, for example `Missing required
        field: custody-type`.

        - `403` when the account lacks the `manage-wallets` capability.

        - `404` when the account is neither the caller's nor one of its
        sub-accounts.

        - `422` when another account already uses the address. A wallet with
        `rewards` must not be in use by any account at all.

        - `422` when the account already has the wallet.

        - `422` when Crown rejected the wallet for this account.

        - `422` `This account is being closed and can only withdraw funds`.
      parameters:
        - in: path
          name: account-id
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                address:
                  type: string
                  description: The wallet's EVM address, in any letter case
                  example: '0xdDa4775Ed1d0c831B006FD4061Edb1b30693a44c'
                challenge:
                  type: string
                  description: The challenge issued for this account and wallet, unchanged
                  example: >-
                    Crown: whitelist wallet
                    0xdda4775ed1d0c831b006fd4061edb1b30693a44c for account
                    019712cf-c86d-703f-85b8-bdaa4fc8d254. Expires at
                    2024-01-15T10:45:00Z.
                signature:
                  type: string
                  pattern: ^0x[0-9a-fA-F]{130}$
                  description: >-
                    The wallet's `personal_sign` (EIP-191) signature of the
                    challenge, 65 bytes as `0x`-prefixed hex. A last byte of 0
                    or 1, or 27 or 28, is accepted
                  example: >-
                    0x055b70e307b8ebbba01105a026164f5a8526af8ddf7149e3184d1d7e0bee4279377d982f2592028cdcea412105aece8b41529aac93e1c29545b9286d6c0071f41b
                capabilities:
                  type: array
                  items:
                    type: string
                    enum:
                      - fx
                      - rewards
                  minItems: 1
                  uniqueItems: true
                  description: >-
                    What the wallet is for. A wallet with `rewards` earns the
                    account's rewards, receives FX payouts too, and belongs to
                    that account alone. A wallet with `fx` alone only receives
                    FX payouts, and several accounts can have the same one.
                    Omitted, the wallet does both
                  example:
                    - fx
                custody-type:
                  oneOf:
                    - type: string
                      enum:
                        - self
                        - exchange
                    - type: 'null'
                  description: >-
                    Self-custody or exchange custody. Required when
                    `capabilities` is `fx` alone
                custody-country:
                  oneOf:
                    - type: string
                    - type: 'null'
                  description: >-
                    Custodian country, ISO-3. Required when `capabilities` is
                    `fx` alone
                  example: BRA
                custodian-name:
                  oneOf:
                    - type: string
                    - type: 'null'
                  description: >-
                    Custodian/exchange name. Required with `exchange` custody
                    when `capabilities` is `fx` alone, and not accepted with
                    `self` custody there
                owner-type:
                  oneOf:
                    - type: string
                      enum:
                        - account-holder
                        - third-party
                    - type: 'null'
                  description: >-
                    Whether the account holder owns the wallet or someone else
                    does. Required when `capabilities` is `fx` alone. A wallet
                    with `rewards` belongs to the holder, so it accepts
                    `account-holder` only
                  example: third-party
                owner-name:
                  oneOf:
                    - type: string
                      minLength: 1
                    - type: 'null'
                  description: >-
                    Legal name of the wallet's owner. Required with `owner-type`
                    `third-party`, and not accepted otherwise
                  example: Acme Ltd
              additionalProperties: false
              required:
                - address
                - challenge
                - signature
            example:
              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
      responses:
        '201':
          description: Wallet whitelisted
          content:
            application/json:
              schema:
                type: object
                properties:
                  external-wallet:
                    type: object
                    properties:
                      address:
                        type: string
                        description: The wallet's address, in EIP-55 checksum form
                        example: '0xdDa4775Ed1d0c831B006FD4061Edb1b30693a44c'
                      capabilities:
                        type: array
                        items:
                          type: string
                          enum:
                            - fx
                            - rewards
                        description: >-
                          `fx` alone for a wallet that only receives FX payouts.
                          `fx` and `rewards` for the account's own wallet, which
                          also earns its rewards
                        example:
                          - fx
                      created-at:
                        type: string
                        example: '2024-01-15T10:31:12Z'
                        format: date-time
                        description: ISO 8601 timestamp when the wallet was whitelisted
                    additionalProperties: false
                    required:
                      - address
                      - capabilities
                      - created-at
                additionalProperties: false
                required:
                  - external-wallet
        '400':
          description: Bad request - Invalid input parameters
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      type:
                        type: string
                      message:
                        type: string
                      code:
                        type: string
                    additionalProperties: false
                    required:
                      - type
                      - message
                      - code
                    description: Bad request error details
                additionalProperties: false
                required:
                  - error
        '403':
          description: Forbidden - Access denied
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      type:
                        type: string
                      message:
                        type: string
                      code:
                        type: string
                    additionalProperties: false
                    required:
                      - type
                      - message
                      - code
                    description: Forbidden access error details
                additionalProperties: false
                required:
                  - error
        '404':
          description: Not found - Resource does not exist
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      type:
                        type: string
                      message:
                        type: string
                      code:
                        type: string
                    additionalProperties: false
                    required:
                      - type
                      - message
                      - code
                    description: Resource not found error details
                additionalProperties: false
                required:
                  - error
        '422':
          description: Unprocessable entity - Validation failed
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      type:
                        type: string
                      message:
                        type: string
                      code:
                        type: string
                    additionalProperties: false
                    required:
                      - type
                      - message
                      - code
                    description: Validation error details
                additionalProperties: false
                required:
                  - error

````

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