Skip to main content

Using WalletConnect with Gem Wallet on Bitcoin

Bitcoin dApps in Gem Walletā€‹

Starting with Gem Wallet 2.114.92, you can connect your Bitcoin wallet to dApps that support WalletConnect on Bitcoin. Gem Wallet reviews every request before anything is signed or sent.

The dApp sees your Native SegWit (bc1qā€¦) address. Gem Wallet doesn't share a Taproot (bc1pā€¦) address, so dApps that need one, such as some ordinals and runes apps, may not work. See Bitcoin Address Types.

How to Connectā€‹

  1. On the dApp, tap Connect Wallet and choose WalletConnect.
  2. Select Gem Wallet from the list, or scan the QR code with Gem Wallet.
  3. In Gem Wallet, check the dApp name, website, wallet, and Bitcoin network, then tap Confirm.

If you opened the dApp in your phone's browser or its own app, Gem Wallet takes you back to it after you approve or reject each request.

For the general WalletConnect steps and how domain verification works, see WalletConnect Guide and WalletConnect Domain Verification in Gem Wallet.

What a Bitcoin dApp Can Ask Forā€‹

RequestWhat you see in Gem WalletWhat happens
Your addressNothing to approve after connectingThe dApp receives your bc1qā€¦ address
Sign a messageThe message textGem Wallet signs it with your Bitcoin key (BIP-137, or BIP-322 when the dApp asks for it). Nothing is sent and no fee is paid
Sign a transaction (PSBT)The amount leaving your wallet, the recipient, and the network feeGem Wallet signs your coins in the transaction. If the dApp asks, Gem Wallet also sends it and shows it in Activity
Send BTCA normal Bitcoin send, with the amount, recipient, fee, and any memoGem Wallet builds, signs, and sends the transaction, like a send you make yourself

Before you sign a message, read it. A dApp should only ask you to sign to prove you own the address, never to "verify" or "unlock" your wallet. See How to Review a WalletConnect Signature Request.

How Gem Wallet Keeps PSBT Requests Safeā€‹

A PSBT (Partially Signed Bitcoin Transaction) is a transaction that a dApp builds and asks you to sign. Gem Wallet checks every PSBT before showing it to you, and refuses requests it can't show clearly:

  • It only signs coins your wallet actually holds, at the amounts the PSBT states.
  • It signs every one of your coins in the transaction in a single request, so separate requests can't each look harmless.
  • It only uses the standard signature type (SIGHASH_ALL), so your signature can't be moved into a different transaction.
  • It refuses PSBTs that pay more than one recipient, contain hidden data (OP_RETURN), or list the same coin twice.

If Gem Wallet can't read a request, it shows Invalid request instead of a confusing error. Reject it and check with the dApp.

How to Disconnectā€‹

Open Settings > WalletConnect, select the session, and tap Disconnect. Disconnecting stops new requests but doesn't undo anything you already signed. See Manage or Disconnect a Session.

Troubleshootingā€‹

  • The dApp doesn't list Gem Wallet: choose WalletConnect and scan the QR code with Gem Wallet instead.
  • The dApp asks for a Taproot address: Gem Wallet only shares its Native SegWit address, so that dApp may not support Gem Wallet yet.
  • A request shows "Invalid request": the dApp sent a transaction Gem Wallet can't read or safely show. Don't try to sign it somewhere else; contact the dApp.
  • A PSBT request is refused: it probably breaks one of the rules above, such as paying several recipients or signing only some of your coins.