Create a Deposit Wallet

Opens a deposit wallet for an account in one coin, at the custodian BlockWyre uses for that coin, and answers its address. Coins sent to the address are credited to the account's balance in that coin.

One address can receive more than one coin. An Ethereum address receives ETH, USDC and USDT alike, so asking for any of the three answers a wallet for each of them that BlockWyre supports in the environment, all with the same address. The coin asked for comes first.

Beta

Part of crypto v3, in beta. While crypto v3 wallets are off for the account, this answers 404 feature_not_enabled.

A workspace-scoped key names the account with customer_id in the body; an account-scoped key creates the wallet for its own account and may omit it.

Replaces POST /api/v2/crypto/wallets.

Authorization:

Every request is signed with your API key: a short-lived JWT, signed with your private key, sent in one header on /v3/* and /api/v2/* alike.

Headers:
  Authorization: APIKey {SIGNED_JWT}

How to build and sign the JWT: Authentication.

Endpoint

POST

/v3/crypto/wallets

Headers

Header

Description

Idempotency-Key

Required. One key per wallet you mean to open: any printable-ASCII string of 1 to 255 characters (a UUID is recommended), sent again unchanged on every retry of it. A retry answers the first response, with Idempotency-Replayed: true, instead of opening a second wallet. Dashboard sessions are held to it already; API keys have a grace period until 2027-01-18, during which a request without it still runs and its response carries a Warning header. See Safe retries.

Request Body Sample

{
  "customer_id": "cst_01h455vb4pex5vsknk084sn02q",
  "coin": "USDC",
  "label": "Main"
}

Request Body Schema

Field	Type	Description
customer_id	string (cst_…)	The account the wallet belongs to. Required for a workspace-scoped key; an account-scoped key may omit it.
coin	string	Required. The coin's ticker: BTC, ETH, LTC, USDC, USDT or XRP. Any casing is accepted; the answer is upper case.
label	string	Optional. Your name for the wallet, up to 255 characters; leading and trailing spaces are dropped. It is given to every wallet the request opens, and can be changed later.

Response Sample

201 Created

{
  "wallets": [
    {
      "id": "wlt_01k8y3a4b6c8d0e2f4g6h8j0k3",
      "customer_id": "cst_01h455vb4pex5vsknk084sn02q",
      "coin": "USDC",
      "address": "0x4e2a6c1f0b9d3a7e5c8f2b1d6e9a3c7b5d1f8e20",
      "label": "Main",
      "status": "active",
      "created_at": "2026-10-20T14:03:11Z",
      "updated_at": "2026-10-20T14:03:11Z"
    },
    {
      "id": "wlt_01k8y3a4b6c8d0e2f4g6h8j0k2",
      "customer_id": "cst_01h455vb4pex5vsknk084sn02q",
      "coin": "ETH",
      "address": "0x4e2a6c1f0b9d3a7e5c8f2b1d6e9a3c7b5d1f8e20",
      "label": "Main",
      "status": "active",
      "created_at": "2026-10-20T14:03:11Z",
      "updated_at": "2026-10-20T14:03:11Z"
    },
    {
      "id": "wlt_01k8y3a4b6c8d0e2f4g6h8j0k4",
      "customer_id": "cst_01h455vb4pex5vsknk084sn02q",
      "coin": "USDT",
      "address": "0x4e2a6c1f0b9d3a7e5c8f2b1d6e9a3c7b5d1f8e20",
      "label": "Main",
      "status": "active",
      "created_at": "2026-10-20T14:03:11Z",
      "updated_at": "2026-10-20T14:03:11Z"
    }
  ]
}

Response Schema

Field	Type	Description
wallets	array	Every wallet the request opened, the coin asked for first. Each has the fields of a List Deposit Wallets row, without customer.

Each wallet also sends a crypto_wallet_created webhook.

Errors

Status	message	When
400	failed to parse request	The body is not valid JSON, customer_id is not a cst_… id, or coin is not a ticker.
400	invalid_customer_id	A workspace-scoped key named no customer_id.
400	invalid_account_id	A workspace-scoped key sent an account_id query parameter (see Turning it on) that is not a cst_… id.
400	invalid_coin	BlockWyre does not hold this coin in custody here.
400	invalid_label	label is longer than 255 characters.
400	idempotency_key_required	No Idempotency-Key header (dashboard sessions now; API keys once the grace period ends).
400	idempotency_key_invalid	The Idempotency-Key is longer than 255 characters or not printable ASCII.
401	unauthorized	Missing or invalid signature.
403	forbidden	An account-scoped key named another account in customer_id.
404	feature_not_enabled	Crypto v3 wallets are not enabled for the account. See Turning it on.
409	wallet_already_exists	The account already has an active wallet for this coin.
409	wallet_provider_not_configured	No custodian is set up for this coin. Retrying does not help until BlockWyre sets one up.
409	idempotency_in_progress	The same Idempotency-Key is still running. Retry after Retry-After seconds with the same key.
413	body_too_large	The body is over 1 MiB.
422	Validation failed	coin is missing; details names it.
422	idempotency_key_conflict	The same Idempotency-Key was used for a different request.
502	invalid_deposit_address	The custodian answered without a usable address. Nothing was saved.
503	idempotency_unavailable	The retry store could not be reached. Nothing was created: retry later with the same key.

Coming from v2

v2 (POST /api/v2/crypto/wallets)	v3
no idempotency header	Idempotency-Key required (API keys: grace period until 2027-01-18)
accountId (uuid)	customer_id (cst_…), optional for an account-scoped key
one wallet in the response	wallets: every wallet the address covers
id (uuid), accountId	id (wlt_…), customer_id
createdAt, updatedAt	created_at, updated_at

Support and Resources

If you need assistance or have any questions, our support team is here to help. You can contact our support team at support@blockwyre.com.

Stay Updated

Stay up-to-date with the latest news, updates, and features from BlockWyre by following us on social media:

• Instagram: BlockWyre Instagram
• Twitter: BlockWyre Twitter
• Facebook: BlockWyre Facebook
• LinkedIn: BlockWyre LinkedIn

We are excited to have you on board and look forward to seeing how you leverage BlockWyre's powerful tools to enhance your financial operations. Happy integrating!