wallet_openReceive

Help Users Receive Bitcoin Ecosystem Assets

Your app can use the wallet_openReceive method to open the user's Receive screen in Xverse for a specific address type (payment, ordinals, stacks, spark, starknet).

This enables you to guide users directly to the correct receive flow, without asking them to manually navigate within the wallet.

---

Request Parameters

address (required)

A string representing which Xverse receive address to open.

Accepted values:

• payment 📮 Bitcoin payment address (native or nested segwit, depending on the current wallet setting) 🎯 Receive Bitcoin payments

• ordinals 📮 Bitcoin ordinals address (taproot) 🎯 Receive Bitcoin ordinals, runes, brc-20

• spark 📮 Spark address (the main one, not the airdrop one) 🎯 Receive Spark BTC and BTKN tokens

• starknet 📮 Starknet address 🎯 Receive Starknet tokens & collectibles

• stacks 📮 Stacks address 🎯 Receive Stacks tokens & collectibles

---

Permissions Required

• 🔓 Your app must have first connected to the wallet and obtained account read permissions

• 🔒 If your user has not connected their active Xverse account to your app yet, and your app does not the necessary account read permissions -> the method will throw with an access denied error

---

Usage Example

import { request, RpcErrorCode } from "sats-connect";

async function openReceive() {
  const res = await request("wallet_openReceive", {
    address: "payment",
  });

  if (res.status === "success") {
    // res.result.address contains the address object that was opened in the wallet
    return res.result.address;
  }

  if (res.error.code === RpcErrorCode.ACCESS_DENIED) {
    // Your app is not connected to the user's active account yet
    // You can prompt the user to connect first:
    const permissionRes = await request("wallet_requestPermissions", undefined);

    if (permissionRes.status === "error") {
      // user declined connection
      throw new Error("User declined connection");
    }

    // retry after permissions are granted
    const retry = await request("wallet_openReceive", { address: "payment" });

    if (retry.status === "error") {
      throw new Error("Failed to open receive screen", { cause: retry.error });
    }

    return retry.result.address;
  }

  // Other errors (e.g. invalid address type or address not available)
  throw new Error("Failed to open receive screen", { cause: res.error });
}

---

wallet_openReceive Result: Open the Receive Screen

✅ If the account is connected and the requested address exists:

• the method resolves successfully

• Xverse wallet opens the Receive screen for the requested address type

❌ If the account is not connected or the requested address does not exist:

• the method returns an error response

---

Response Format

The wallet_openReceive method returns a Promise that resolves to an OpenReceiveResult object.

address

An address object representing the requested receive address:

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