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

# External Wallet Screening

Every external wallet must now pass compliance screening before it can receive funds. New wallets are screened from launch, and existing wallets must be re-submitted before **Wednesday, November 11, 2026**, or they will stop working.

<Warning>
  From Wednesday, November 11, 2026, any wallet that hasn't cleared screening is deactivated, and transfers sent to a raw `walletAddress` are rejected.
</Warning>

## Key Dates

| When | What Happens |
| :- | :- |
| From launch | New wallets are screened and stay inactive until `CLEARED`. Flagged wallets are blocked immediately. Existing wallets keep working. |
| Until Wednesday, November 11, 2026 | Re-submit every existing wallet you still use. |
| From Wednesday, November 11, 2026 | Any wallet that hasn't cleared is deactivated. Raw `walletAddress` destinations are rejected. |

## What This Means for You

### New Wallets

* A wallet created with `POST /v2/users/{userId}/wallets/external` starts inactive (`active: false`, `screeningStatus: UNDER_REVIEW`).
* It turns on only when it is `CLEARED`. Wait for `CLEARED` before using it as a transfer destination or as the `externalWalletId` of a virtual account.
* Any transfer to a wallet that isn't active is rejected.

### Existing Wallets

* They keep working as usual until Wednesday, November 11, 2026.
* Re-submit each one you still use before then (see below). It stays active while under review.
* From Wednesday, November 11, 2026, any wallet that isn't `CLEARED` is deactivated. To use it again, register it with a new `referenceId` and wait for it to clear.

### Flagged Wallets

* A `FLAGGED` wallet is deactivated immediately, at any time, including existing wallets before November 11.
* It is blocked from all transactions and can't be linked to a virtual account.

### Raw Addresses

* From Wednesday, November 11, 2026, every destination must be a registered external wallet.
* Crypto transfers and bridging that send to `destination.walletAddress` will be rejected. Register the address as an external wallet, wait for it to clear, and send to `destination.externalWalletId` instead.

## Re-submitting an Existing Wallet

Send the original registration request again, unchanged. The wallet keeps its `id` and keeps working while it is screened.

<Steps>
  <Step title="Call the external wallet endpoint">
    Call `POST /v2/users/{userId}/wallets/external` for the same user.
  </Step>

  <Step title="Send the original values">
    Send the **same** `referenceId`, `address`, `chain` and `name` as the original registration.
  </Step>

  <Step title="Confirm the wallet is under review">
    The response returns the **same wallet** `id` with `screeningStatus: UNDER_REVIEW` and `active: true`.
  </Step>

  <Step title="Wait for the webhook">
    Wait for the `WALLET.EXTERNAL_WALLET.UPDATE` webhook. `CLEARED` means you're done; `FLAGGED` means the wallet is now deactivated.
  </Step>
</Steps>

**Request:**

```bash theme={null}
curl -X POST "https://sandbox.hifibridge.com/v2/users/usr_abc123/wallets/external" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "referenceId": "<original referenceId>",
    "address": "<original address>",
    "chain": "<original chain>",
    "name": "<original name>"
  }'
```

<Info>
  Changing the address, chain or name returns a `400` `EXTERNAL_WALLET_ALREADY_EXISTS` error. Deleted wallets can't be re-submitted; register them again with a new `referenceId`.
</Info>

## Screening Status and Webhooks

The external wallet response now includes `screeningStatus` next to `active`. Use `active` to decide whether a wallet can be used.

| `screeningStatus` | Meaning | `active` |
| :- | :- | :- |
| `UNDER_REVIEW` | Screening in progress, or held for manual review by our compliance team | `false` for new wallets; `true` for re-submitted existing wallets until November 11 |
| `CLEARED` | Passed screening | `true` |
| `FLAGGED` | Failed screening; blocked from all transactions | `false` |
| `NOT_SCREENED` | The chain isn't supported for screening yet | `true` |
| `null` | Registered before this change and not yet re-submitted | `true` until Wednesday, November 11, 2026 |

When a wallet's status changes, we send a `WALLET.EXTERNAL_WALLET.UPDATE` webhook with the updated wallet (`id`, `userId`, `chain`, `name`, `address`, `referenceId`, `active`, `screeningStatus`, `createdAt`, `updatedAt`).

<Note>
  No webhook is sent when wallets are deactivated on November 11. Check `active` on your wallets after that date.
</Note>

## Virtual Accounts

A virtual account created with an `externalWalletId` follows that wallet's status. If the wallet is blocked, deposits are not delivered.

* You can only set `externalWalletId` to an **active** wallet. For a new wallet, wait for `CLEARED`.
* If the linked wallet is later flagged, deactivated on November 11, or deleted, new deposits **fail** instead of being delivered.
* A failed deposit's onramp ends as `FIAT_FAILED` with error `EXTERNAL_WALLET_INACTIVE` ("External wallet is not active"), and you'll get the usual onramp status webhook. No crypto is sent.
* To keep receiving deposits, update the virtual account to point to a wallet that has cleared.
* Virtual accounts that deliver to the user's HIFI wallet (`destinationChain` with no `externalWalletId`) are not affected.

## Testing and Common Errors

You can test the full flow in sandbox now. The wallet `name` picks the result:

| `name` | Result |
| :- | :- |
| `FLAGGED` | `FLAGGED`, wallet stays inactive |
| Anything else | `CLEARED`, wallet turns on |

| Response | What It Means | What to Do |
| :- | :- | :- |
| `503` `SERVICE_UNAVAILABLE` "Unable to register the external wallet right now. Please try again later." | Screening couldn't be started; no wallet was created | Retry the same request |
| `400` `EXTERNAL_WALLET_ALREADY_EXISTS` | That `referenceId` is already used with a different address, chain or name | Use a new `referenceId`, or re-send the original values |
| Transfer rejected: wallet not active | The wallet is under review, flagged, or deactivated | Check `screeningStatus`; wait for `CLEARED` or register a new wallet |

## Getting Help

* 📧 **Email:** [support@hifi.com](mailto:support@hifi.com)
* 💬 **Slack:** Message us in our shared Slack channel

## Related Resources

* [Wallets](/wallets) - Wallet provisioning, balances, and transfers
* [Wallet Events](/webhooks/wallet-events) - Wallet webhook notifications
* [Virtual Accounts](/accounts/virtual-accounts) - Set up fiat onramps to wallets
* [Transfers](/transactions/transfers) - Send stablecoins between wallets


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