Crypto v3 (beta)
The v3 crypto endpoints: an account's deposit wallets, the counterparties it withdraws to (v2 calls them beneficiaries), and its crypto withdrawals. They read and write the same wallets, counterparties and balances as the v2 crypto endpoints, with v3's conventions: TypeIDs, snake_case fields and the v3 error body (see the API v3 overview).
Crypto v3 is in beta. BlockWyre enables it per workspace, on request: ask your BlockWyre contact to turn it on for yours. Until it is on, the endpoints that create, change or move something answer 404 feature_not_enabled (see Turning it on). The v2 crypto endpoints keep working as before.
What is in it
| Section | Endpoints | v2 equivalent |
|---|---|---|
| Wallets | Create, List, Get, Rename, Totals | Wallet: create, list, get |
| Counterparties | Save, List, Get, Rename, Delete | Crypto Beneficiary |
| Withdrawals | Preview, Create, Get, Cancel | Crypto Transaction: preview, execute, cancel |
Deposits have no endpoint of their own. Coins sent to a wallet's address are credited to the account's balance in that coin (List Balances) and announced by the crypto_transaction_created webhook with details.type "deposit".
Turning it on
BlockWyre turns crypto v3 on in three parts — wallets, counterparties, withdrawals — for a whole workspace, or for chosen accounts of it. While a part is off, its switched endpoints answer:
{ "code": 404, "message": "feature_not_enabled" }
| Part | Switched (answer 404 feature_not_enabled while off) | Always open |
|---|---|---|
| Wallets | POST /v3/crypto/wallets | GET /v3/crypto/wallets, GET /v3/crypto/wallets/{wallet_id}, GET /v3/crypto/wallets/stats, PATCH /v3/crypto/wallets/{wallet_id} |
| Counterparties | POST /v3/crypto/counterparties, PATCH and DELETE /v3/crypto/counterparties/{counterparty_id} | GET /v3/crypto/counterparties, GET /v3/crypto/counterparties/{counterparty_id} |
| Withdrawals | POST /v3/crypto/withdrawals/preview, POST /v3/crypto/withdrawals | GET /v3/crypto/withdrawals/{withdrawal_id}, POST /v3/crypto/withdrawals/{withdrawal_id}/cancel |
The reads, and renaming a wallet, stay open because they work on records that v2 and v3 share. A withdrawal accepted while withdrawals were on can still be read and cancelled after they are turned off.
Which switch counts:
- An account-scoped key: its own account's. It is on when it is on for the workspace or for that account.
- A workspace-scoped key: the account it names with the
account_idquery parameter, or the workspace alone when it names none. The wallet and counterparty creates name their account in the body (customer_id), which this check does not read: when crypto v3 is on for some accounts only, a workspace-scoped key also sends?account_id=with the same account on every switched call. Anaccount_idthat is not acst_…id answers400 invalid_account_id.
Which account a request acts for
Both kinds of key work on every endpoint here (see Key types and permissions).
- An account-scoped key acts for its own account and need not name it. Naming a different account is refused with
403 forbidden; another account's wallets, counterparties and withdrawals read as404. - A workspace-scoped key acts for the whole workspace. The wallet and counterparty endpoints name the account as
customer_id(a filter on the lists, required on the two creates). The withdrawal endpoints name it as theaccount_idquery parameter, required on preview and create (400 account_id_required).
IDs
| Prefix | Is | From v2 |
|---|---|---|
wlt_ | a deposit wallet, and a counterparty: both are kept in the same table, so a counterparty's id is a wlt_ id too | the wallet's or the beneficiary's id |
wtx_ | a crypto withdrawal | the withdrawal's transactionId |
cst_ | an account | accountId |
A v2 UUID and the v3 TypeID name the same record: wlt_ plus the UUID in base32 (see IDs are TypeIDs). v3 lists and reads the wallets and beneficiaries created through v2, under those ids.
Withdrawals are the exception. v3 reads only the withdrawals created through v3: a v2 withdrawal's id answers 404 withdrawal_not_found, so follow it through v2, for example with Get Transaction Details. A withdrawal created through v3 is cancelled through v3: v2's Cancel Crypto Withdraw refuses it with 409.
Amounts
The withdrawal endpoints answer amount, fee and total as decimal strings in the coin, next to coin — "amount": "250" — not as the { "amount", "currency" } money object other v3 resources use. Trailing zeros are dropped ("2.5", not "2.50"). Send amount as a decimal string too.
Safe retries
POST /v3/crypto/wallets and POST /v3/crypto/withdrawals require an Idempotency-Key header: one key per wallet or withdrawal you mean to create, sent again unchanged on every retry. A retry with the same key within 24 hours answers the first response instead of creating a second wallet or withdrawal (see Safe retries). Dashboard sessions are held to it already. API keys have a grace period until 2027-01-18: until then a request without the header still runs, without that protection, and its response carries
Warning: 299 - "Idempotency-Key will be required on this endpoint from 2027-01-18"
Send the header now. The other endpoints here do not take it.
Webhooks
The v3 endpoints send the same webhooks as v2, with ids in their UUID form:
| Webhook | When |
|---|---|
crypto_wallet_created | Once per wallet a create answers. |
crypto_beneficiary_created | A counterparty is saved, or a deleted one is saved again. |
crypto_beneficiary_updated | A counterparty's label changes. |
crypto_beneficiary_deleted | A counterparty is deleted. |
crypto_transaction_created | A v3 withdrawal is created (status pending). |
crypto_transaction_status_updated | A v3 withdrawal is submitted (processing), completes (success), fails (failed) or is cancelled (cancelled). Its confirmed step sends none. |
See Crypto Webhooks for the payloads.
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!