@stacks/connect

The @stacks/connect package provides a simple interface for connecting web applications to Stacks wallets, enabling user authentication, transaction signing, and message signing capabilities.

Installation

Install with npm

npm install @stacks/connect

Connection functions

connect

connect initiates a wallet connection and stores user addresses in local storage.

Signature:

function connect(options?: ConnectOptions): Promise<ConnectResponse>

Parameters

Name	Type	Required	Description
options	ConnectOptions	No	Configuration options for connection

Examples

Basic connection

import { connect } from '@stacks/connect';

const response = await connect();
// Response contains user addresses stored in local storage

Connection with options

const response = await connect({
  forceWalletSelect: true,
  approvedProviderIds: ['LeatherProvider', 'xverse']
});

isConnected

isConnected checks if a wallet is currently connected.

import { isConnected } from '@stacks/connect';

if (isConnected()) {
  console.log('Wallet is connected');
}

disconnect

disconnect clears the connection state and local storage.

import { disconnect } from '@stacks/connect';

disconnect(); // Clears wallet connection

getLocalStorage

getLocalStorage retrieves stored connection data.

import { getLocalStorage } from '@stacks/connect';

const data = getLocalStorage();
// {
//   "addresses": {
//     "stx": [{ "address": "SP2MF04VAGYHGAZWGTEDW5VYCPDWWSY08Z1QFNDSN" }],
//     "btc": [{ "address": "bc1pp3ha248m0mnaevhp0txfxj5xaxmy03h0j7zuj2upg34mt7s7e32q7mdfae" }]
//   }
// }

Request method

request

request is the primary method for interacting with connected wallets.

Signature:

function request<T extends StacksMethod>(
  options: RequestOptions | undefined,
  method: T,
  params?: MethodParams[T]
): Promise<MethodResult[T]>

Parameters

Name	Type	Required	Description
options	RequestOptions	No	Request configuration options
method	StacksMethod	Yes	Method to call on the wallet
params	MethodParams[T]	Depends on method	Parameters for the method

Request options

Name	Type	Default	Description
provider	StacksProvider	Auto-detect	Custom provider instance
forceWalletSelect	boolean	false	Force wallet selection modal
persistWalletSelect	boolean	true	Persist wallet selection
enableOverrides	boolean	true	Enable compatibility fixes
enableLocalStorage	boolean	true	Store addresses locally
approvedProviderIds	string[]	All providers	Filter available wallets

Examples

Basic request

import { request } from '@stacks/connect';

const addresses = await request('getAddresses');

Request with options

const response = await request(
  { forceWalletSelect: true },
  'stx_transferStx',
  {
    amount: '1000000', // 1 STX in microSTX
    recipient: 'SP3FGQ8Z7JY9BWYZ5WM53E0M9NK7WHJF0691NZ159'
  }
);

Wallet methods

getAddresses

getAddresses retrieves Bitcoin and Stacks addresses from the wallet.

const response = await request('getAddresses');
// {
//   "addresses": [
//     {
//       "address": "bc1pp3ha248m0mnaevhp0txfxj5xaxmy03h0j7zuj2upg34mt7s7e32q7mdfae",
//       "publicKey": "062bd2c825300d74f4f9feb6b2fec2590beac02b8938f0fc042a34254581ee69"
//     },
//     {
//       "address": "SP2MF04VAGYHGAZWGTEDW5VYCPDWWSY08Z1QFNDSN",
//       "publicKey": "02d3331cbb9f72fe635e6f87c2cf1a13cdea520f08c0cc68584a96e8ac19d8d304"
//     }
//   ]
// }

sendTransfer

sendTransfer sends Bitcoin to one or more recipients.

const response = await request('sendTransfer', {
  recipients: [
    {
      address: 'bc1qw508d6qejxtdg4y5r3zarvary0c5xw7kv8f3t4',
      amount: '1000' // Amount in satoshis
    },
    {
      address: 'bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh',
      amount: '2000'
    }
  ]
});
// { "txid": "0x1234..." }

signPsbt

signPsbt signs a partially signed Bitcoin transaction.

const response = await request('signPsbt', {
  psbt: 'cHNidP...', // Base64 encoded PSBT
  signInputs: [{ index: 0, address }], // Optional: specify inputs to sign
  broadcast: false // Optional: broadcast after signing
});
// {
//   "psbt": "cHNidP...", // Signed PSBT
//   "txid": "0x1234..." // If broadcast is true
// }

Stacks-specific methods

stx_transferStx

stx_transferStx transfers STX tokens between addresses.

const response = await request('stx_transferStx', {
  amount: '1000000', // Amount in microSTX (1 STX = 1,000,000 microSTX)
  recipient: 'SP3FGQ8Z7JY9BWYZ5WM53E0M9NK7WHJF0691NZ159',
  memo: 'Payment for services', // Optional
  network: 'mainnet' // Optional, defaults to mainnet
});
// { "txid": "0x1234..." }

stx_callContract

stx_callContract calls a public function on a smart contract.

import { Cl } from '@stacks/transactions';

const response = await request('stx_callContract', {
  contract: 'SP2C2YFP12AJZB4MABJBAJ55XECVS7E4PMMZ89YZR.hello-world',
  functionName: 'say-hi',
  functionArgs: [Cl.stringUtf8('Hello!')],
  network: 'mainnet'
});
// { "txid": "0x1234..." }

stx_deployContract

stx_deployContract deploys a new smart contract.

const response = await request('stx_deployContract', {
  name: 'my-contract',
  clarityCode: `(define-public (say-hi (name (string-utf8 50)))
    (ok (concat "Hello, " name "!"))
  )`,
  clarityVersion: '2', // Optional
  network: 'testnet'
});
// { "txid": "0x1234..." }

stx_signMessage

stx_signMessage signs a plain text message.

const response = await request('stx_signMessage', {
  message: 'Hello, World!'
});
// {
//   "signature": "0x1234...",
//   "publicKey": "02d3331cbb9f72fe635e6f87c2cf1a13cdea520f08c0cc68584a96e8ac19d8d304"
// }

stx_signStructuredMessage

stx_signStructuredMessage signs a structured Clarity message following SIP-018.

import { Cl } from '@stacks/transactions';

const message = Cl.tuple({
  action: Cl.stringAscii('transfer'),
  amount: Cl.uint(1000000n)
});

const domain = Cl.tuple({
  name: Cl.stringAscii('MyApp'),
  version: Cl.stringAscii('1.0.0'),
  'chain-id': Cl.uint(1) // mainnet
});

const response = await request('stx_signStructuredMessage', {
  message,
  domain
});
// {
//   "signature": "0x1234...",
//   "publicKey": "02d3331cbb9f72fe635e6f87c2cf1a13cdea520f08c0cc68584a96e8ac19d8d304"
// }

stx_getAccounts

stx_getAccounts retrieves detailed account information including Gaia configuration.

const response = await request('stx_getAccounts');
// {
//   "addresses": [{
//     "address": "SP2MF04VAGYHGAZWGTEDW5VYCPDWWSY08Z1QFNDSN",
//     "publicKey": "02d3331cbb9f72fe635e6f87c2cf1a13cd...",
//     "gaiaHubUrl": "https://hub.hiro.so",
//     "gaiaAppKey": "0488ade4040658015580000000dc81e3a5..."
//   }]
// }

Error handling

Handle wallet errors using standard Promise error handling patterns.

try {
  const response = await request('stx_transferStx', {
    amount: '1000000',
    recipient: 'SP3FGQ8Z7JY9BWYZ5WM53E0M9NK7WHJF0691NZ159'
  });
  console.log('Transaction successful:', response.txid);
} catch (error) {
  console.error('Transaction failed:', error);
}

Advanced usage

requestRaw

requestRaw provides direct access to wallet providers without compatibility features.

Signature:

function requestRaw<T extends StacksMethod>(
  provider: StacksProvider,
  method: T,
  params?: MethodParams[T]
): Promise<MethodResult[T]>

Example

import { requestRaw } from '@stacks/connect';

const provider = window.StacksProvider;
const response = await requestRaw(provider, 'getAddresses');

Migration notes

Version 8.x.x implements SIP-030 wallet standards. For legacy JWT-based authentication, use version 7.10.1.