Sats Connect - Wallet API for Bitcoin & Stacks
  • Introduction
  • Wallet Providers
    • getInfo
    • getProviders & getProviderById
  • Connecting to the wallet
    • Connect to Xverse Wallet
    • Disconnect from Xverse Wallet
    • Connect to other wallets
      • Manage a user's default wallet
    • [Legacy ⚠️] getAccounts
  • Wallet Methods
    • request methods
    • wallet_getAccount
    • wallet_getNetwork
    • wallet_changeNetwork
    • Xverse Custom Methods
  • Xverse Wallet Permissions
  • Xverse Wallet events
  • BITCOIN METHODS
    • 🟠getAddresses
    • 🟠signMessage
    • 🟠signPsbt
    • 🟠sendTransfer
    • 🟠signMultipleTransactions
    • 🟠getBalance
    • 🎨createInscription
    • 🎨createRepeatInscriptions
    • 🎨ord_getInscriptions
    • 🎨ord_sendInscriptions
    • 🔲runes_getBalance
    • 🔲runes_transfer
    • 🔲Mint Runes
      • runes_estimateMint
      • runes_mint
    • 🔲Etch Runes
      • runes_estimateEtch
      • runes_etch
    • 🔲runes_getOrder
    • 🔲Speed up a Rune Mint or Etch order
      • 🔲runes_estimateRbfOrder
      • 🔲runes_rbfOrder
  • STACKS METHODS
    • 🔴stx_getAccounts
    • 🔴stx_signMessage
    • 🔴stx_signStructuredMessage
    • 🔴stx_transferStx
    • 🔴stx_signTransaction
    • 🔴stx_callContract
    • 🔴stx_deployContract
  • GUIDES
    • Verify Bitcoin message signatures
    • Creating Bitcoin PSBTs
    • 📱Mobile Integration
    • Next.js support
  • RESOURCES
    • App Template
    • Demo App
    • Changelog
    • Github Issues
    • Developer forum
    • BIP322
Powered by GitBook
On this page
  • Request to connect your app to your user's Xverse wallet
  • Connection request in your user's Xverse wallet
  • Successful Connection Request
  • Unsuccessful Connection Request
  1. Connecting to the wallet

Connect to Xverse Wallet

Request to connect your app to your user's Xverse wallet

An app can easily connect to the Xverse Wallet using wallet_connect. This method grants read permissions on the account selected by the user and returns commonly used data about the account, such as addresses and current network.

You can optionally specify:

  • which wallet addresses you require from the wallet account: Bitcoin ordinals address, Bitcoin payment address or Stacks address, using the optional addresses request parameter.

  • a custom connection message to show the user. You can use it to present your app and state the purpose of the connection request.

request parameters
Description

an array of strings used to specify which address(es) to request from the user's Xverse wallet account:

  • 'ordinals' is preferably used to manage the user’s ordinals

  • 'payment' is preferably used to manage the user’s bitcoin

  • 'stacks' is used to interact with the stacks ecosystem

Example: ['ordinals', 'payment', 'stacks'] Will default to ['ordinals', 'payment', 'stacks'] if not specified.

a custom message to show to the user during the connection request

a string representing the network the wallet should use to connect to your app:

  • Mainnet for Bitcoin mainnet & Stacks mainnet

  • Testnet for Bitcoin testnet & Stacks testnet

  • Signet for Bitcoin Signet & Stacks testnet

  • Regtest for Bitcoin Regtest & Stacks testnet

If the wallet is on a different network than the one you request, the user will be prompted to switch before connecting.

import { request } from "sats-connect";

try {
  const response = await request('wallet_connect', null);
  if (response.status === 'success') {
    const paymentAddressItem = response.result.addresses.find(
      (address) => address.purpose === AddressPurpose.Payment
    );
    const ordinalsAddressItem = response.result.addresses.find(
      (address) => address.purpose === AddressPurpose.Ordinals
    );
    const stacksAddressItem = response.result.addresses.find(
        (address) => address.purpose === AddressPurpose.Stacks
    );
  } else {
    if (response.error.code === RpcErrorCode.USER_REJECTION) {
      // handle user cancellation error
    } else {
      // handle error
    }
  }
} catch (err) {
    alert(err.error.message);
}

Connection request in your user's Xverse wallet

If the user is not connected to your app yet, their Xverse wallet will display a Connection Request prompt with:

  • your app url & your app logo (if it is specified in your app manifest)

  • the wallet addresses that your app required

  • the message which you specified. Note that this message will be cut beyond 80 characters.

The user can select which of their Xverse account they wish to connect to your app.

Once resolved, the method returns connectResult: an array of the user’s wallet address objects, defined as:

type address = {
    address: string;
    publicKey: string;
    purpose: "payment" | "ordinals" | "stacks";
    addressType: "p2tr" | "p2wpkh" | "p2sh" | "stacks";
}

Currently, you can retrieve two types of Bitcoin addresses, the user's Bitcoin payment address and the Ordinals address which is a taproot address.

An example response:

wallet_connect response
const response = {
  walletType: 'software',
  id: 'dj0f7g5xtdakgecvf45dvssu66',
  addressses: [
    {
      address: 'tb1pzwa68q3udj0f7g5xtdakgecvf45dvssu66ry7y3at22w7vus20vq3sgw62',
      publicKey: 'b9907521ddb85e0e6a37622b7c685efbdc8ae53a334928adbd12cf204ad4e717',
      purpose: 'ordinals',
      addressType: 'p2tr',
      network: 'mainnet',
    },
    {
      address: '2NBfRKCUpafbatj5gV9T82uau3igdSf9BXJ',
      publicKey: '02818b7ff740a40f311d002123087053d5d9e0e1546674aedb10e15a5b57fd3985',
      purpose: 'payment',
      addressType: 'p2sh',
      network: 'mainnet',
    },
  ],
  network: {
    bitcoin: {
      name: 'Mainnet',
    },
    stacks: {
      name: 'Mainnet',
    },
  },
};

Where:

address field
Description

address

string - the user’s connected wallet address

publicKey

A hex string representing the bytes of the public key of the account. You can use this to construct partially signed Bitcoin transactions (PSBT).

purpose

string - The purpose of the address:

  • ordinals is preferably used to manage the user’s ordinals

  • payment is preferably used to manage the user’s bitcoin

  • stacks is used to interact with the stacks ecosystem

addressType

string - the address’s format:

  • P2TR for ordinals

  • P2SH for payment

  • P2WPKH for payment using Ledger

  • stacks for Stacks

network

string - the network where the address is being used:

  • Mainnet for Bitcoin & Stacks mainnet

  • Testnet for Bitcoin & Stacks testnet

  • Signet for Bitcoin Signet

walletType

string - the type of wallet used for the account

  • ledger if the user's account is using a Ledger device

  • software otherwise

If the user declines the connection request or closes the pop-up, the promise returned by the connect method will reject (throw when awaited).

PreviousConnecting to the walletNextDisconnect from Xverse Wallet

Last updated 13 days ago

addresses Optional

message Optional

network Optional

Note that if your app is referenced on , Sats Connect will automatically display your app name & logo as they appear on Explore.

the that your app is requesting from their wallet

If the user has already granted , no connection request popup will appear, ensuring a smooth user experience.

Successful Connection Request

The wallet_connect method returns a that resolves once the user approves the connection request or if they are already connected to your app.

You can use these addresses to make further requests such as , , etc.

After approving the connection request, the user can track the active connection with your app directly from their Xverse wallet, and

Unsuccessful Connection Request

✅
❌
🔜
Xverse Explore
permissions
✅
permissions
Promise
signing a message
signing a transaction
revoke the connection from the wallet.
ℹ️
ℹ️
ℹ️