Skip to main content

Wallets Guide

Overview​

On the BlockWyre platform, a wallet is a deposit address for one coin, held for one account. Coins sent to the address are credited to the account's balance in that coin. An account holds at most one active wallet per coin.

Sending crypto out is the other direction: the account saves a destination (a counterparty) and withdraws to it. Both directions are on the v3 crypto endpoints; see Crypto v3 for the whole surface, the fees and minimums, and the webhooks each step sends.

StepEndpoint
Create a walletPOST /v3/crypto/wallets
List an account's walletsGET /v3/crypto/wallets
Read one walletGET /v3/crypto/wallets/{wallet_id}
Rename a walletPATCH /v3/crypto/wallets/{wallet_id}
Count the workspace's walletsGET /v3/crypto/wallets/stats
Follow the depositsGET /v3/crypto/deposits
Check the balanceGET /v3/balances

The v2 wallet endpoints (/api/v2/crypto/wallets) are deprecated. They work on the same wallets, under the same ids — a UUID in v2, that UUID as a wlt_… TypeID in v3 — so you can move one call at a time; see Moving from v2.

Wallet Flow​

1. Creating the Wallet​

  • Action: Create a wallet for the account and the coin it will receive.
  • Endpoint: POST /v3/crypto/wallets with coin, and customer_id from a workspace-scoped key (an account-scoped key may omit it). Send an Idempotency-Key, so a retry answers the same wallet instead of a second one.
  • Webhook: crypto_wallet_created, once per wallet created.
  • Resulting State: The wallet exists, with its address. One address can receive several coins — on Ethereum, one address receives ETH, USDC and USDT — so a request for any of them answers a wallet for each, all with the same address.

2. Finding the Address​

  • Action: Read the wallet back when you need its address again.
  • Endpoint: GET /v3/crypto/wallets?customer_id=…, or one wallet with GET /v3/crypto/wallets/{wallet_id}.
  • Response: The account's wallets, each with its coin and address.

3. Sharing the Wallet Address​

  • Action: Give the address to whoever sends the transfer. On XRP, which routes by memo, the address carries the memo as <address>?dt=<tag>: give the sender both the address and the memo.
  • Resulting State: The sender has the address for that coin.

4. Transfer Detection​

  • Action: When a transfer to the address is seen, a deposit is recorded for the account, pending, and its amount shows on the balance as pending_credits.
  • Webhooks: crypto_transaction_created with details.type deposit and status pending, then crypto_transaction_status_updated with the status it was first seen in.
  • Resulting State: The deposit is listed in GET /v3/crypto/deposits.

5. Completion​

  • Action: When the transfer completes, the deposit becomes success and its total — amount minus the deposit's fee — moves to the balance's available. A transfer that fails is failed and credits nothing.
  • Webhook: crypto_transaction_status_updated
  • Resulting State: Check the account's balance with List Balances.

See Crypto Webhooks for the payloads.

Sequence Diagram​

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:

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!