Connect

When an app requests data from a user's wallet, users are presented with a confirmation popup for each request. To allow for a more streamlined experience, apps can request permission to remain connected. While connected, apps can fetch the data they need without additional prompts to the user.

For methods that support permissions, the general flow for connecting to the wallet and retrieving data is:

1. request("example-method")

2. If permission is denied, request("wallet_requestPermissions"). This will show a connection popup to the user asking them to accept the request.

3. If successful, request("example-method") again.

Note that for backwards-compatibility reasons, the wallet may display a popup to users asking to confirm a request if permissions haven't yet been requested. In the future, requests that don't have permissions will fail with a permissions denied response.

Depending on the desired user flow, apps may or may not prompt the user for a connection if a request fails.

Note that the terms "connection" or "being connected" mean that the wallet is keeping track of permissions granted to an app. There is currently a single type of permission available, reading account data, which is requested with request("wallet_requestPermissions")

Example: Requesting a connection when a request has insufficient permissions

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

async function example() {
  const res1 = await request("getBalance", undefined);

  if (res1.status === "success") {
    // Happy path.
    return res1.result.total;
  }

  if (res1.error.code !== RpcErrorCode.ACCESS_DENIED) {
    // Something else went wrong.
    throw new Error("Failed to get balance.", { cause: res1.error });
  }

  // Insufficient permissions. Request permissions and try again.

  const res2 = await request("wallet_requestPermissions", undefined);

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

  const res3 = await request("getBalance", undefined);

  if (res3.status === "error") {
    // Something went wrong.
    throw new Error("Failed to get balance.", { cause: res3.error });
  }

  return res3.result.total;
}

You can let users disconnect from your app with request("wallet_renouncePermissions").