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, Spark, Starknet 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.

• the network the wallet should use to connect to your app

request parameters	Description
addresses ℹ️ Optional	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 'spark' is used to interact with the Spark ecosystem 'starknet' is used to interact with the Starknet ecosystem Example: ['ordinals', 'payment', 'stacks'] Will default to ['ordinals', 'payment', 'stacks', 'spark','starknet'] if not specified.
message ℹ️ Optional	a custom message to show to the user during the connection request
network ℹ️ Optional	a string representing the network the wallet should use to connect to your app: Mainnet for Bitcoin Mainnet | Spark Mainnet | Stacks Mainnet | Starknet Mainnet Regtest for Bitcoin Regtest | Spark Regtest | Stacks Testnet | Starknet Sepolia Testnet for Bitcoin Testnet | Spark Regtest | Stacks Testnet | Starknet Sepolia Signet for Bitcoin Signet | Spark Regtest | Stacks Testnet | Starknet Sepolia 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)

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

• the wallet addresses that your app required

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

• the permissions that your app is requesting from their wallet

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

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

✅ Successful Connection Request

The wallet_connect method returns a Promise that resolves once the user approves the connection request or if they are already connected 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" | "spark" | "starknet";
    addressType: "p2tr" | "p2wpkh" | "p2sh" | "stacks" | "spark" | "starknet";
}

You can use these addresses to make further requests such as signing a message, signing a transaction, etc.

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 spark is used to interact with the Spark ecosystem starknet is used to interact with the Starknet ecosystem
addressType	string - the address’s format: P2TR for ordinals P2SH for payment P2WPKH for payment using Ledger stacks for Stacks spark for Spark starknet for Starknet
network	string - the network where the address is being used: Mainnet for Bitcoin Mainnet | Spark Mainnet | Stacks Mainnet | Starknet Mainnet Regtest for Bitcoin Regtest | Spark Regtest | Stacks Testnet | Starknet Sepolia Testnet for Bitcoin Testnet | Spark Regtest | Stacks Testnet | Starknet Sepolia Signet for Bitcoin Signet | Spark Regtest | Stacks Testnet | Starknet Sepolia
walletType	string - the type of wallet used for the account ledger if the user's account is using a Ledger device software otherwise

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

❌ Unsuccessful Connection Request

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