Add External Wallets

Overview

Add customer or counterparty self-custody or hosted crypto external wallets to the Cybrid platform using the POST /api/external_wallets endpoint. Once registered, you can withdraw crypto assets to these wallets after the wallet's usable_at time; newly created wallets are subject to a new withdrawal destination hold.

Types of external wallets

Create external wallets

POST /api/external_wallets

• Customer wallet — provide customer_guid to associate the wallet with a specific customer.
• Counterparty wallet — provide counterparty_guid (the counterparty can belong to a bank or customer).
• Partner wallet — omit both customer_guid and counterparty_guid. Useful for omnibus wallets receiving all withdrawals.

{
  "name": "<wallet name>",
  "customer_guid": "<customer guid>",
  "asset": "<asset>",
  "address": "<blockchain wallet address>",
  "tag": "<string>"
}

{
  "name": "<wallet name>",
  "counterparty_guid": "<counterparty guid>",
  "asset": "<asset>",
  "address": "<blockchain wallet address>",
  "tag": "<string>"
}

{
  "name": "<wallet name>",
  "asset": "<asset>",
  "address": "<blockchain wallet address>",
  "tag": "<string>"
}

Wallet screening

All wallets undergo screening to determine their risk level:

• High risk — automatically rejected. The wallet state is failed with failure_code: "prohibited_address".
• Medium risk — sent for manual review by the Compliance team. See review targets for timelines. After review, the wallet is accepted or rejected.
• Low risk — automatically accepted.

Withdrawal review holds

Some crypto withdrawals to external wallets may be held for manual review by Cybrid before funds are released.

If you regularly send withdrawals to the same wallet, open a Zendesk ticket asking Cybrid to allowlist the wallet address. After the address is allowlisted, withdrawals to it are released automatically without manual review.

Monitor wallet status via GET /api/external_wallets/{external_wallet_guid}:

{
  "guid": "<wallet guid>",
  "name": "<wallet name>",
  "asset": "<asset>",
  "environment": "<production/sandbox>",
  "bank_guid": "<bank guid>",
  "customer_guid": "<customer guid>",
  "counterparty_guid": null,
  "address": "<blockchain wallet address>",
  "tag": null,
  "created_at": "<datetime>",
  "updated_at": "<datetime>",
  "state": "failed",
  "failure_code": "prohibited_address"
}