Product tours for crypto and web3 apps: wallet and DApp onboarding

Web3 apps lose 55% of users during wallet setup alone. As of April 2026, that number comes from ConsenSys's own user research, and it hasn't improved much despite two years of embedded wallet tooling from Privy, Magic.link, and Sequence. The wallet infrastructure is getting better. The post-connection guidance is still absent.

Most dApp teams invest heavily in wallet connection flows and account abstraction but drop users into complex dashboards with zero contextual help afterward. Product tours fill that gap, but standard tour libraries assume synchronous, predictable UI flows. Web3 breaks that assumption with pending transactions, network switches, wallet popups, and state that lives on a blockchain instead of a database.

This guide covers the onboarding patterns that work for crypto and web3 apps, the compliance considerations that constrain your copy, and how to build wallet-aware tours that handle the async reality of blockchain interactions.

npm install @tourkit/core @tourkit/react @tourkit/hints

Why web3 onboarding is different from SaaS onboarding

Web3 app onboarding introduces failure modes that don't exist in traditional SaaS products. Users must install browser extensions, manage private keys, approve token allowances, pay gas fees, and wait for blockchain confirmations before they can do anything useful. As of April 2026, ConsenSys reports that 65% of users abandon dApps during wallet setup or their first transaction, 60% report confusion with concepts like liquidity pools, and 36% cite frustration with technical jargon specifically (dev.to/toboreeee).

That's not a typical drop-off funnel. SaaS apps lose users to boring onboarding. Web3 apps lose users to incomprehensible onboarding.

Three factors make web3 onboarding structurally harder:

Async state changes. A blockchain transaction takes 15 seconds to several minutes to confirm. Your tour can't just advance to the next step on click. It needs to pause, show a pending state, handle rejection, and resume on confirmation. Standard tour libraries don't account for this.

External UI surfaces. When a user approves a transaction, MetaMask opens a popup. WalletConnect shows a QR code. The tour's target element is no longer in your DOM. You need tours that gracefully handle elements appearing and disappearing outside your control.

Irreversibility. Wrong-network transactions, approved token allowances, and sent tokens can't be undone. Your onboarding copy carries legal and financial weight that "click next to continue" tutorials in a project management app never will.

Laurina Ayarah put it bluntly in her analysis of web3 UX: "This isn't a learning curve. It's a cliff." (dev.to)

The five onboarding patterns that work for DApps

Wallet-aware product tours share common patterns across DeFi dashboards, NFT marketplaces, and DAO tooling. These patterns emerged from how successful projects reduced their 30% wallet-connection drop-off rate (Formo.so) and sub-1% 30-day retention numbers.

Pattern 1: delayed wallet connection

Don't ask users to connect a wallet on first load. Let them explore with a read-only or guest mode. Trigger the wallet connection step only when they try to do something that requires it: saving progress, making a trade, or claiming a reward.

In tour terms, this means your first 3-4 steps should educate about the interface without touching the wallet at all. The wallet connection becomes a mid-tour event, not a gate.

// src/components/DAppTour.tsx
import { useTour } from '@tourkit/react';
import { useAccount } from 'wagmi';

function DAppTour() {
  const { isConnected } = useAccount();
  const tour = useTour({
    tourId: 'dapp-onboarding',
    steps: [
      {
        id: 'explore-dashboard',
        target: '[data-tour="dashboard"]',
        title: 'Your portfolio overview',
        content: 'This shows your token balances and recent activity.',
      },
      {
        id: 'connect-wallet',
        target: '[data-tour="connect-btn"]',
        title: 'Connect your wallet',
        content: 'To trade or earn, connect a wallet. We support MetaMask, WalletConnect, and Coinbase Wallet.',
        // Skip this step if already connected
        when: () => !isConnected,
      },
      {
        id: 'first-swap',
        target: '[data-tour="swap-panel"]',
        title: 'Make your first swap',
        content: 'Select a token pair and amount. Gas is covered for your first trade.',
        // Only show after wallet is connected
        when: () => isConnected,
      },
    ],
  });

  return <>{tour.currentStep && tour.render()}</>;
}

Pattern 2: async-safe tour steps

Web3 actions don't complete instantly. A tour step that says "confirm the transaction" needs to handle three states: the wallet popup is open (pending user action), the transaction is submitted (pending chain confirmation), and the transaction is confirmed (advance). Tour Kit's event system lets you wire this up without polling.

// src/hooks/useTxAwareTour.ts
import { useTour } from '@tourkit/react';
import { useWaitForTransactionReceipt } from 'wagmi';
import { useState } from 'react';

export function useTxAwareTour(txHash: `0x${string}` | undefined) {
  const [isPending, setIsPending] = useState(false);
  const tour = useTour({ tourId: 'first-transaction' });

  const { isSuccess } = useWaitForTransactionReceipt({
    hash: txHash,
    query: {
      enabled: !!txHash,
    },
  });

  // Advance tour when transaction confirms
  if (isSuccess && isPending) {
    setIsPending(false);
    tour.next();
  }

  return {
    ...tour,
    markTxPending: () => setIsPending(true),
  };
}

The key insight: don't use setTimeout or interval-based polling to check transaction status. Use wagmi's useWaitForTransactionReceipt hook, which subscribes to the provider's event stream. Your tour stays paused until the chain confirms.

Pattern 3: wallet-type branching

MetaMask users see a browser extension popup. WalletConnect users scan a QR code on their phone. Embedded wallet users (Privy, Sequence) see nothing at all, because the wallet is invisible. Your tour needs to show different steps depending on which wallet type the user connected.

// src/utils/wallet-tour-steps.ts
import type { TourStep } from '@tourkit/core';

type WalletType = 'injected' | 'walletConnect' | 'embedded';

export function getWalletSteps(walletType: WalletType): TourStep[] {
  const base: TourStep[] = [
    {
      id: 'welcome',
      target: '[data-tour="app-header"]',
      title: 'Welcome to the app',
      content: 'Here is a quick tour of the key features.',
    },
  ];

  const walletSpecific: Record<WalletType, TourStep> = {
    injected: {
      id: 'approve-tx',
      target: '[data-tour="swap-btn"]',
      title: 'Approving transactions',
      content:
        'When you click Swap, MetaMask will open a popup. Review the details and click Confirm.',
    },
    walletConnect: {
      id: 'approve-tx',
      target: '[data-tour="swap-btn"]',
      title: 'Approving transactions',
      content:
        'When you click Swap, a notification appears on your mobile wallet. Open it to confirm.',
    },
    embedded: {
      id: 'approve-tx',
      target: '[data-tour="swap-btn"]',
      title: 'Approving transactions',
      content:
        'Click Swap and the transaction processes automatically. No extra confirmation needed.',
    },
  };

  return [...base, walletSpecific[walletType]];
}

Pattern 4: jargon-busting hints at point of need

Web3 jargon kills comprehension. "Approve token allowance for ERC-20 transfer" means nothing to someone who just arrived from a Coinbase ad. Instead of front-loading a glossary tour, use contextual hints that appear when jargon first shows up in the UI.

Tour Kit's @tourkit/hints package handles this natively. Place hint beacons next to terms like "gas fee," "slippage," and "liquidity pool." They pulse to indicate help is available without interrupting the user's flow.

// src/components/JargonHints.tsx
import { HintProvider, Hint, HintBeacon, HintContent } from '@tourkit/hints';

function JargonHints() {
  return (
    <HintProvider>
      <Hint id="gas-fee" target='[data-term="gas-fee"]'>
        <HintBeacon />
        <HintContent>
          A small fee paid to the network to process your transaction.
          Think of it like a processing fee on a credit card payment.
        </HintContent>
      </Hint>

      <Hint id="slippage" target='[data-term="slippage"]'>
        <HintBeacon />
        <HintContent>
          The difference between the expected price and the actual price
          when your trade executes. Set to 0.5% for most swaps.
        </HintContent>
      </Hint>
    </HintProvider>
  );
}

This approach tested well in DeFi dashboards specifically because it doesn't force users through a sequential tour. Experienced crypto users skip hints entirely. First-timers tap them as needed. Formo.so's funnel research suggests reducing terminology confusion can eliminate up to 80% of drop-off at the wallet interaction stage (Formo.so).

Pattern 5: network context awareness

Users on the wrong chain get cryptic errors. A tour that detects the current network and shows a contextual prompt to switch before the user hits an error is worth more than any error recovery flow.

// src/components/NetworkGuard.tsx
import { Hint, HintBeacon, HintContent } from '@tourkit/hints';
import { useChainId, useSwitchChain } from 'wagmi';

const EXPECTED_CHAIN_ID = 137; // Polygon

function NetworkGuard() {
  const chainId = useChainId();
  const { switchChain } = useSwitchChain();
  const isWrongNetwork = chainId !== EXPECTED_CHAIN_ID;

  if (!isWrongNetwork) return null;

  return (
    <Hint id="wrong-network" target='[data-tour="network-indicator"]'>
      <HintBeacon variant="warning" />
      <HintContent>
        You are connected to the wrong network. This app runs on Polygon.
        <button onClick={() => switchChain({ chainId: EXPECTED_CHAIN_ID })}>
          Switch to Polygon
        </button>
      </HintContent>
    </Hint>
  );
}

Compliance and regulatory constraints on tour copy

Web3 product tours carry legal weight that standard SaaS onboarding doesn't. Your tour copy isn't just UX, it's potentially a financial disclosure. Here's what to watch for, as of April 2026.

KYC/AML gates. Centralized exchanges and some DeFi protocols require identity verification. If your onboarding flow includes a KYC step, the tour needs to explain why the information is needed without allowing users to skip the step. Progress indicators reduce abandonment here. A tour step saying "we verify your identity to comply with financial regulations — this takes about 2 minutes" performs better than a bare KYC form.

Financial risk disclaimers. Many jurisdictions require explicit acknowledgment of financial risk before a user's first transaction. A tour step can serve as a compliant disclosure gate: the user reads the risk statement and clicks "I understand" before the tour advances. Check with legal counsel for the exact language your jurisdiction requires.

Securities law. Never characterize tokens as investments or promise returns in your onboarding tour copy. "Earn yield" is fine in some contexts. "Earn 12% APY on your investment" may trigger securities regulations depending on the jurisdiction and the protocol's legal structure. When in doubt, have a lawyer review the copy in your tour steps.

GDPR and wallet addresses. Wallet addresses are pseudonymous, not anonymous. If your analytics pipeline logs wallet addresses alongside behavioral data, you may be creating personal data under GDPR. Tour Kit's analytics events fire without including wallet addresses by default, but if you enrich events with wallet data, treat them as PII.

Accessibility in web3: the overlooked gap

Web3 accessibility is almost universally ignored. The HapticsDAO Web3 Accessibility Guidelines (hapticsdao.info) exist but are barely referenced by production dApps. CMSWire reported in 2025 that accessibility and inclusion remain an afterthought in web3 design (CMSWire).

Product tours in web3 apps need the same WCAG 2.1 AA compliance as any web application. But they also face web3-specific accessibility challenges:

• Wallet popups and focus management. When MetaMask opens, keyboard focus leaves your app. The tour must not trap focus or leave a dangling tooltip when the user is interacting with an external wallet popup.
• Transaction status for screen readers. A visual spinner during transaction confirmation means nothing to a screen reader user. Use aria-live="polite" regions to announce "transaction pending," "transaction confirmed," or "transaction failed."
• Jargon tooltips and cognitive load. Hint beacons must be keyboard-navigable. Screen reader users need the hint content announced without needing to hover.

Tour Kit ships with WCAG 2.1 AA compliant focus management and ARIA attributes out of the box. The hints package supports keyboard navigation and screen reader announcements natively. That said, Tour Kit is React 18+ only and has no mobile SDK, so React Native dApp frontends need a different solution.

Building a wallet-aware tour: putting it together

Here's how these patterns combine into a complete onboarding flow for a DeFi dashboard. The tour adapts to wallet state, handles async transactions, and provides contextual help without a rigid step sequence.

// src/components/OnboardingOrchestrator.tsx
import { TourProvider } from '@tourkit/react';
import { HintProvider } from '@tourkit/hints';
import { useAccount, useChainId } from 'wagmi';
import { DAppTour } from './DAppTour';
import { JargonHints } from './JargonHints';
import { NetworkGuard } from './NetworkGuard';

export function OnboardingOrchestrator() {
  const { isConnected, connector } = useAccount();
  const chainId = useChainId();

  // Determine wallet type for step branching
  const walletType = !isConnected
    ? undefined
    : connector?.type === 'injected'
      ? 'injected'
      : connector?.type === 'walletConnect'
        ? 'walletConnect'
        : 'embedded';

  return (
    <TourProvider>
      <HintProvider>
        {/* Sequential onboarding tour */}
        <DAppTour walletType={walletType} />

        {/* Always-on contextual hints */}
        <JargonHints />

        {/* Network mismatch warning */}
        <NetworkGuard />
      </HintProvider>
    </TourProvider>
  );
}

The three layers, a sequential tour for first-run onboarding, persistent hints for jargon, and reactive guards for network state, cover the full onboarding surface without forcing every user through the same linear path.

Common mistakes in web3 onboarding tours

Requiring wallet connection before showing any value. Formo.so's funnel data shows 30% drop-off at wallet connection alone. If your tour's first step is "connect your wallet," you've lost a third of your audience before they see your product.

Ignoring the async gap. Tours that advance immediately after a user clicks "confirm" in MetaMask will show the next step while the transaction is still pending. The user sees "transaction complete!" while their wallet still shows "pending." This erodes trust fast.

Writing tour copy as if users speak blockchain. "Approve the ERC-20 allowance to enable the smart contract interaction" is technically accurate and completely useless to 60% of your users. Write for the person who arrived from a Google ad, not the person who reads Ethereum Improvement Proposals.

Skipping mobile. As of 2026, mobile wallet usage through WalletConnect and in-app browsers (MetaMask Mobile, Coinbase Wallet) accounts for a significant share of dApp traffic. Tours designed only for desktop extension flows break on mobile. Test on actual mobile wallets.

No recovery path for failed transactions. A transaction rejection or out-of-gas error mid-tour shouldn't crash the experience. Build recovery tooltips: "The transaction was rejected. You can try again or skip this step for now."

Tools and libraries for web3 onboarding

Several libraries can handle web3 product tours. Here's how the options compare for this specific use case:

We built Tour Kit, so take this comparison with appropriate skepticism. Every claim is verifiable against npm, GitHub, and bundlephobia. Tour Kit's main limitation for web3 specifically is the lack of a mobile SDK. If your dApp's primary audience is on React Native, you'll need a different solution for mobile, and Tour Kit for the web interface.

For the wallet infrastructure side (not product tours), look at Privy, thirdweb, Sequence, and MetaMask Embedded. These handle wallet creation and connection. Tour Kit handles what happens after, the in-app guidance layer.

Check the Tour Kit documentation for full API details and working examples.

FAQ

Can product tours handle blockchain transaction confirmations?

Tour Kit supports event-driven step advancement, which means a tour step can pause while a transaction is pending and automatically advance when the chain confirms. Using wagmi's useWaitForTransactionReceipt hook alongside Tour Kit's useTour hook, you wire transaction state directly into tour progression without polling or timeouts. The pattern works across Ethereum, Polygon, and other EVM chains.

Do web3 apps need WCAG-compliant onboarding?

Yes. Web3 apps must meet the same WCAG 2.1 AA standards as any other website, regardless of blockchain interaction. The HapticsDAO Web3 Accessibility Guidelines provide web3-specific patterns, though adoption remains low. Tour Kit ships with built-in ARIA attributes, keyboard navigation, and focus management.

How do you handle different wallet types in a product tour?

Detect the connector type after connection (injected for MetaMask, walletConnect for QR-based, embedded for invisible wallets) and branch your tour steps. Tour Kit's conditional when function on each step shows wallet-specific instructions. MetaMask users see "confirm in the popup," WalletConnect users see "check your phone," embedded wallet users skip confirmation.

What compliance considerations apply to web3 onboarding copy?

Financial risk disclaimers, KYC/AML step explanations, and securities law constraints all affect tour copy. Never promise returns or characterize tokens as investments. If your protocol requires identity verification, explain why in the tour step. Treat wallet addresses as potential PII under GDPR if logged alongside behavioral data.

Why do 55% of users abandon during wallet setup?

ConsenSys's 2024 user research found that seed phrase management, browser extension installation, and gas fee confusion are the primary barriers. Embedded wallet solutions (Privy, Magic.link, Sequence) reduce this drop-off by hiding wallet complexity behind social login. Gasless transactions via account abstraction (EIP-4337) eliminate the "buy ETH first" blocker and improve first-transaction completion by 60%.

Related articles

IndustryApr 12, 2026 · 10 min read

Product tours for B2B SaaS: the complete playbook

Build B2B SaaS product tours that drive activation, not just completion. Role-based patterns, accessibility compliance, and code examples included.

Read article

IndustryApr 12, 2026 · 11 min read

Onboarding for no-code platforms: patterns that actually work

Build effective onboarding for no-code and low-code platforms. Covers citizen developer training, accessibility, checklist patterns, and code examples.

Read article

IndustryApr 12, 2026 · 9 min read

Product tours for analytics platforms: reducing dashboard overwhelm

Build analytics platform onboarding that cuts cognitive load and drives activation. Role-based tours, progressive disclosure, and code examples.

Read article

IndustryApr 12, 2026 · 12 min read

Product tours for API products: developer onboarding done right

Cut your API's time to first call with guided product tours. Learn 5 onboarding patterns used by Stripe, Twilio, and Postman — with code examples.

Read article