A reliable WalletConnect NFT integration does more than open a wallet prompt. It must establish the right chain session, respond to account and network changes, support desktop and mobile journeys, handle signatures safely, and explain failures clearly. This checklist walks through a reusable implementation workflow for an NFT app, marketplace, minting page, game, or token-gated product.
Overview
A wallet connection is the boundary between your application and a user-controlled NFT wallet. Your app requests permission to view selected accounts and chains, while the wallet remains responsible for approving messages and blockchain transactions. Treat that boundary as an explicit state machine rather than a single button click.
A practical flow usually includes these states:
- Disconnected: The user has not approved a session, or has intentionally ended one.
- Connecting: The app is creating a connection through a QR code, deep link, or wallet browser.
- Connected: The session is active for the expected account and chain.
- Needs attention: The account or chain changed, a request was rejected, or the session is stale.
- Disconnected or expired: The app has cleared local session state and can safely offer a new connection.
Before writing UI code, define the networks and actions your NFT product actually needs. An ERC-721 wallet and an ERC-1155 wallet may use the same account model on an EVM network, but minting, transfers, approvals, marketplace listings, and balance reads can require different contract calls. If your product supports a non-EVM chain, do not assume that EVM account, chain, or transaction methods apply. Use the connector and SDK documentation for the relevant namespace.
For broader implementation planning, pair this guide with the NFT API and SDK integration checklist and the NFT minting workflow checklist.
Checklist by scenario
1. Initial desktop connection with a QR code
- Register and configure the project identifier or equivalent connector configuration required by the SDK you selected.
- Declare only the chain namespaces, chains, methods, and events that your application needs.
- Render a clear Connect wallet action before asking for access.
- Open the QR modal only after the user starts the flow, and provide a visible way to cancel it.
- Show the selected account and network after approval, not merely a generic Connected label.
- Persist session information only through the connector’s supported mechanism. Avoid building a second, conflicting session store.
- Disable actions that require a wallet until the account and chain have been validated.
2. Mobile connection through a deep link or wallet browser
- Test the handoff from a normal mobile browser to the wallet app and the return path back to your site.
- Offer a wallet-selection path that does not depend on copying a URI manually.
- Expect the browser to be backgrounded or reloaded while the user approves a request.
- Restore the session and pending UI state when the user returns, but re-check account and chain rather than trusting stale display data.
- Use mobile-safe buttons, readable signing descriptions, and a recovery message if the wallet app does not open.
- Test both a mobile browser with an installed wallet and a wallet’s built-in browser. Their navigation and storage behavior may differ.
3. Switching chains before an NFT action
- Identify the required chain from the action itself: for example, a mint contract, NFT balance lookup, or marketplace listing.
- Compare the active chain with the required chain before preparing a transaction.
- Request a chain switch through the wallet rather than silently changing application state.
- If the chain is not configured in the wallet, present the supported add-network path only when your integration and wallet support it.
- After the switch returns, read the active chain again and stop if it is still incorrect.
- Do not treat a successful switch request as proof that a transaction can now be sent; revalidate the session and contract configuration.
4. Reading NFTs and account changes
- Listen for account changes and update balances, ownership, permissions, and available actions.
- Clear account-specific cached data when the user changes accounts.
- Re-run network-specific reads after a chain change. An NFT owned on one network should not be presented as available on another without an explicit cross-chain model.
- Handle wallets with no NFTs, delayed indexer results, hidden assets, and token metadata that cannot be loaded.
- Keep ownership verification server-side for high-value or access-controlled workflows; the connected address alone is not proof that a user currently controls it unless verified through an appropriate signature flow.
5. Message signing and transaction signing
- Tell the user whether the request is a message signature, token approval, NFT transfer, mint, listing, or payment.
- Display the collection, token identifier, destination, quantity, and relevant network in your application before opening the wallet.
- Prefer human-readable typed data where supported and appropriate. Never ask users to sign unexplained opaque data for a routine action.
- Separate authentication signatures from transaction approvals. A login message should not silently authorize a token transfer.
- Wait for the wallet response, then show a pending state while a blockchain transaction is being confirmed.
- Record the transaction hash only after the wallet returns it, and handle replacement, rejection, failure, and timeout states distinctly.
6. Disconnect and recovery
- Provide a visible disconnect control in the account menu.
- Clear account-scoped UI and cached permissions when the session ends.
- Handle connector errors, wallet rejection, expired sessions, and transport interruptions as recoverable states.
- Offer a fresh connection attempt without requiring the user to clear all browser storage.
- Never request or store a recovery phrase or private key. Wallet connection is not wallet custody. Review the NFT wallet security guide for user-facing safety guidance.
Wallet and device compatibility matrix
| Environment | Connection path to test | Key checks |
|---|---|---|
| Desktop browser | QR code to mobile or desktop wallet | Modal opens, QR refreshes, approval returns to the app, cancel works |
| Mobile browser | Deep link or wallet selection | App handoff, return URL, reload recovery, account and chain refresh |
| Wallet browser | In-app browser connection | No duplicate prompts, correct navigation, transaction result handling |
| EVM NFT wallet | Account and chain session | ERC-721 and ERC-1155 reads, typed messages, approvals, transfers |
| Non-EVM wallet | Its supported chain namespace | Namespace-specific accounts, signing methods, events, and transaction format |
| Unsupported wallet or browser | Fallback connection or explanation | Clear compatibility message and no misleading Connected state |
What to double-check
Chain configuration: Keep a single source of truth for supported chains, contract addresses, token standards, block explorers, and network-specific API settings. A correct wallet connection can still produce a bad result if the app points to the wrong contract or environment.
Event handling: Account, chain, session, and disconnect events can arrive while a request is pending. Make handlers idempotent, cancel obsolete reads, and prevent an older response from overwriting current account data.
Transaction intent: Show the user what will happen before requesting approval. For a mint, include quantity and expected network. For a transfer, include recipient and token. For an approval, explain which contract receives permission and why.
Authentication: Use a server-issued nonce for wallet login, bind the verified address to the session, and expire or invalidate nonces after use. Do not treat a front-end address string as authentication.
Gas and failure states: Wallets may estimate gas differently, and an NFT action may fail because of contract conditions, insufficient funds, a stale approval, or a changed account. Link users to a relevant NFT gas fee calculator guide when explaining network costs, but do not promise a fixed fee.
Privacy and logging: Log technical request identifiers and error categories without collecting secret wallet data. Avoid putting full signed payloads, personal information, or sensitive session details into client-visible logs.
Common mistakes
- Connecting on page load: An unsolicited prompt creates friction. Let the user initiate the connection.
- Showing a truncated address as proof of readiness: Also display and validate the active network.
- Ignoring account changes: This can show one user’s NFT data while another account is active.
- Using one transaction format for every chain: Chain namespaces and wallet methods are not interchangeable.
- Hiding rejected requests: A rejection is different from a network failure. Explain the next step without blaming the user.
- Assuming mobile behaves like desktop: Backgrounding, deep links, browser storage, and return URLs require separate testing.
- Trusting client-only ownership checks: Use a signed challenge and server-side verification for token-gated access. See the token-gated access setup guide.
- Leaving stale sessions in place: Provide disconnect and recovery controls instead of asking users to reinstall a wallet or clear all data.
When to revisit
Re-run this checklist before each production deployment that changes wallet behavior, adds a chain, updates a connector or SDK, changes contract addresses, or introduces a new signature or payment flow. It should also be part of regression testing after major wallet releases, browser updates, mobile operating-system changes, or changes to deep-link and return-URL handling.
Keep a small compatibility record with the SDK version, connector configuration, supported namespaces, tested wallets, device and browser combinations, contract environment, and known limitations. Review it before seasonal launches and other high-traffic campaigns. If a wallet or chain is removed, test the migration path for existing sessions instead of only testing new connections.
Pre-release action list:
- Connect and disconnect on desktop using a QR flow.
- Connect, background, return, and reconnect on at least one mobile browser flow.
- Change accounts during an NFT read and during a pending action.
- Switch to the wrong chain, then recover to the required chain.
- Reject a connection, signature, approval, and transaction independently.
- Test successful and failed contract responses, including a delayed confirmation.
- Verify that account data, cached permissions, and UI labels are cleared after disconnect.
- Confirm that every supported wallet and chain still matches the current SDK documentation.
A wallet connection is ready for release when users can understand what they are approving, recover from ordinary interruptions, and see the correct account, chain, NFT state, and transaction result at every step.