Crypto and Wallet Concepts for Integrators

This page gives integrators a practical mental model for how Bead uses crypto assets and wallets. It explains:

• How the hosted payment page works for crypto

• What customers need in their wallet

• How network fees work

• High level ways customers get funds into a wallet

For step by step wallet instructions, customers should use the help center for their wallet provider. This page is focused on system behavior, not consumer support.

How crypto payments work with Bead

At a high level a crypto payment looks like this:

1. Your system creates a payment with Bead for a specific asset and network.

2. Bead generates a unique address and amount for that payment on that network.

3. The hosted payment page shows the customer the asset, the network, the exact amount to send, and a QR code that encodes the address, network, and amount.

4. The customer opens a compatible wallet, scans the code or copies the details, and confirms the send.

5. Bead monitors the network and updates the payment status as confirmations occur.

Key point: Bead is giving the wallet a precise set of instructions. The main failure cases occur when the customer selects the wrong asset, the wrong network, or does not have enough balance to cover network fees.

Asset types (USDC, Bitcoin, and Lightning)

Bead supports multiple asset types that behave differently at the network level.

For USDC on smart contract networks:

• USDC on Base

  • Payment token: USDC on Base

  • Fee token: ETH on Base

• USDC on Solana

  • Payment token: USDC on Solana

  • Fee token: SOL on Solana

For Bitcoin based payments:

• Bitcoin on-chain

  • Payment asset and fee asset are both BTC.

  • There is no separate fee token. Network fees are deducted in BTC as part of the transaction.

• Bitcoin Lightning

  • Uses payment channels managed by Lightning capable wallets.

  • Routing and fees are handled within the Lightning network and the user’s Lightning wallet.

The Compatible Crypto Wallets page describes which wallets and networks are supported for USDC, Bitcoin on-chain, and Bitcoin Lightning, and how payment and fee behavior works for each combination.

Networks and compatible assets

The hosted payment page always specifies a network for the payment, such as Base, Solana, Bitcoin mainnet, or Bitcoin Lightning.

Wallets often allow the same symbol or brand to exist on multiple networks. For example, a customer might hold:

• USDC on Base

• USDC on Solana

The wallet user must choose the version that matches the network shown on the Bead hosted page. If they pick the wrong one, the send will usually fail or will not settle to the address Bead is monitoring.

For integrators and merchant teams, the key checks are:

• Does the customer have a compatible wallet for the network shown

• Does that wallet show the correct asset on that same network

• Does the customer have enough balance to pay both the invoice amount and network fees

Wallet types and what Bead expects

From Bead’s perspective, there are two high level wallet categories.

1. Self custody wallets

   • Examples include Phantom, the Base app (Coinbase’s self custody wallet), and similar applications.

   • The customer controls the private keys.

   • These wallets can usually scan a QR code, choose the correct network, and send directly to the address provided by Bead.

2. Exchange accounts

   • Examples include centralized exchanges where balances are held on the customer’s behalf.

   • These often cannot scan an external QR and pay directly in a point of sale or ecommerce style flow in the same way a self custody wallet can.

   • Transfers usually require moving funds from the exchange into a self custody wallet first.

Bead’s crypto payment flows are designed for self custody wallets.

Some exchanges and wallets provide features that make moving funds into self custody easier. For example:

• A self custody wallet can be linked to an exchange account to make it easier to move assets between the two.

• Wallets may offer a deposit from exchange flow that connects to major exchanges and guides the withdrawal into the wallet.

From an integrator’s point of view, these features are convenience layers around the same core concept: the user is ultimately performing an exchange withdrawal into a self custody wallet, which is then used to pay the Bead hosted payment address.

If a merchant’s customers primarily keep assets on an exchange, they may need to:

• Move funds from the exchange into a self custody wallet, using either a direct withdrawal or an exchange linking feature

• Then pay from that wallet using the hosted page

When you see issues such as “customer is using Coinbase but cannot pay,” it is often because they are trying to use an exchange balance instead of a self custody wallet app such as Base or Phantom.

How customers typically fund a wallet

Bead does not provide funding or exchange services. In practice, customers usually get funds into a wallet in one of these ways.

1. On ramp inside the wallet app

   • Many wallets let customers buy crypto using cards or bank transfers inside the app.

   • The details vary by region and provider.

2. Transfers or links from an exchange to a wallet

   • The customer buys USDC, BTC, and any fee tokens on an exchange.

   • The customer then moves those assets into a self custody wallet. This can be done by:

     • Manually withdrawing to a wallet address, or

     • Using features that link an exchange account to the wallet and guide the withdrawal flow directly, where supported.

3. Transfers from another wallet

   • The customer already has assets and fee tokens in another wallet and sends to the wallet they want to use for payment.

For integrators, the main points to understand are:

• Bead only sees the funds when they are sent to the address generated for the payment.

• The path the customer used to fund their wallet is out of scope for Bead, but often drives the types of questions support teams will see.

Swaps inside wallets

Many wallets support swaps, where the customer trades one asset for another inside the wallet.

Relevant examples include:

• Swapping from a different asset into USDC

• Swapping into fee tokens, for example into SOL on Solana or ETH on Base for fees

• Using swap or bridge flows to move value between networks, where supported

Important things for integrators to know:

• Swaps are wallet features. Fees and capabilities are controlled by the wallet provider or its partners.

• Swaps often require fee tokens as well, so a customer with zero fee token may need to deposit some before they can perform a swap.

• From Bead’s perspective, a swap is just a way for the customer to prepare their balances. The actual payment is still a send to the Bead generated address for the requested asset and network.

In your own help materials you can encourage merchants to:

• Make sure their teams understand that swaps are possible but not required

• Encourage customers to complete any swap before initiating the payment, to avoid the payment window expiring during a swap

Common situations integrators should be aware of

These are patterns that will show up in support conversations.

• Wrong network selected in the wallet

  • The wallet has the asset on a different network than the one requested.

  • The payment fails or never arrives.

• Insufficient fee balance

  • The wallet shows an error about network fees even when the main asset balance looks sufficient.

  • The customer may need to acquire a small amount of ETH on Base, SOL on Solana, or additional BTC for on-chain Bitcoin fees.

• Trying to pay directly from an exchange

  • The customer cannot scan the QR or confirm quickly enough using an exchange account.

  • Withdrawals may be delayed or batched, which does not match a real time payment flow, even when the exchange is linked to a self custody wallet.

• Expired payments

  • The customer starts the flow, leaves the screen open, and pays later.

  • By the time they send, the payment window has expired and the address is no longer considered valid for the original invoice.

Each of these cases can be handled in more detail in your FAQs and Troubleshooting section. This page provides the shared vocabulary and concepts.

How this page relates to other documentation

• For a list of currently supported wallets and assets, see Compatible Crypto Wallets.

• For running a full test transaction end to end, see Test Crypto Transactions.

• For common issues and questions, see FAQs and Troubleshooting under Payments and Environment and Testing.