getAddress

Your application can request to connect to the user’s wallet with the getAddress method, which prompts them to share their Bitcoin and Stacks addresses.

import { getAddress } from 'sats-connect'

You can specify which wallet addresses you require, Bitcoin ordinals address, Bitcoin payment address or Stacks address, via the purposes field in your request payload.

The message field in the request payload gives you the option to display a message the user when requesting their addresses. You can use it to present your app and explain why you require access to their addresses.

payload field	Description
network	an object specifying the target Bitcoin chain (Mainnet / Testnet)
purposes	Array of strings containing one or more valid purposes ['ordinals', 'payment', 'stacks']
message	a message to be displayed to the user in the request prompt.

const getAddressOptions = {
  payload: {
    purposes: ['ordinals', 'payment'],
    message: 'Address for receiving Ordinals and payments',
    network: {
      type:'Mainnet'
    },
  },
  onFinish: (response) => {
    console.log(response)
  },
  onCancel: () => alert('Request canceled'),
  }
    
await getAddress(getAddressOptions);

The getAddresss method returns a Promise that resolves if the user approves the connection request. The user will see a Connection Request prompt in their wallet. The prompt will display:

• 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.

Once resolved, the method returns addresses, 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";
}

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:

addresses: [
  {
    address: "tb1pzwa68q3udj0f7g5xtdakgecvf45dvssu66ry7y3at22w7vus20vq3sgw62",
    publicKey: "b9907521ddb85e0e6a37622b7c685efbdc8ae53a334928adbd12cf204ad4e717",
    purpose: "ordinals",
    addressType: "p2tr"
  },
  {
    address: "2NBfRKCUpafbatj5gV9T82uau3igdSf9BXJ",
    publicKey: "02818b7ff740a40f311d002123087053d5d9e0e1546674aedb10e15a5b57fd3985",
    purpose: "payment",
    addressType: "p2sh"
  }
]

Where:

address field	Description
address	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	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	addressType the address’s format: P2TR for ordinals P2SH for payment P2WPKH for payment using Ledger stacks for Stacks

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