Quickstart

Get started with Stacks Connect by installing a wallet and connecting to your app.

This quickstart will get you up and running with wallet authentication in minutes. You'll install a Stacks wallet and connect it to a simple web application.

What you'll learn

Install a Stacks-compatible wallet

Connect the wallet to your web app

Display the user's address and balance

Prerequisites

Basic knowledge of JavaScript/TypeScript
Node.js installed on your machine
A code editor like VS Code

Quickstart

Install a Stacks wallet

Before connecting to your app, users need a Stacks-compatible wallet. Install one of these popular options:

Visit the Leather wallet website and install the browser extension. After installation, create a new wallet or import an existing one.

Once installed, you'll see the wallet icon in your browser toolbar.

Set up your project

Create a new project and install the required Stacks.js packages:

Terminal

$ npm create vite@latest my-stacks-app -- --template react-ts
$ cd my-stacks-app
$ npm install @stacks/connect @stacks/network

This creates a React app with TypeScript and installs the necessary Stacks packages.

Create the connection component

Replace the contents of src/App.tsx with a simple wallet connection interface:

src/App.tsx

import { AppConfig, UserSession, showConnect } from '@stacks/connect';
import { useState, useEffect } from 'react';

const appConfig = new AppConfig(['store_write', 'publish_data']);
const userSession = new UserSession({ appConfig });

function App() {
  const [userData, setUserData] = useState<any>(null);
  
  useEffect(() => {
    if (userSession.isSignInPending()) {
      userSession.handlePendingSignIn().then((userData) => {
        setUserData(userData);
      });
    } else if (userSession.isUserSignedIn()) {
      setUserData(userSession.loadUserData());
    }
  }, []);
  
  const connectWallet = () => {
    showConnect({
      appDetails: {
        name: 'My Stacks App',
        icon: 'https://example.com/icon.png',
      },
      onFinish: () => {
        setUserData(userSession.loadUserData());
      },
      userSession,
    });
  };
  
  const disconnect = () => {
    userSession.signUserOut();
    setUserData(null);
  };
  
  return (
    <div style={{ padding: '2rem' }}>
      <h1>My Stacks App</h1>
      {!userData ? (
        <button onClick={connectWallet}>Connect Wallet</button>
      ) : (
        <div>
          <p>Connected as: {userData.profile.stxAddress.mainnet}</p>
          <button onClick={disconnect}>Disconnect</button>
        </div>
      )}
    </div>
  );
}

export default App;

This component handles wallet connection, displays the user's address, and allows disconnection.

Run your app

Start the development server and test the wallet connection:

Terminal

$ npm run dev

Open your browser to http://localhost:5173 and click "Connect Wallet". Your Stacks wallet will prompt you to authenticate with the app.

After approving the connection, you'll see your Stacks address displayed on the page.

Display account balance

Enhance your app by showing the user's STX balance. Update your App.tsx:

src/App.tsx

import { AppConfig, UserSession, showConnect } from '@stacks/connect';
import { StacksMainnet } from '@stacks/network';
import { useState, useEffect } from 'react';

const appConfig = new AppConfig(['store_write', 'publish_data']);
const userSession = new UserSession({ appConfig });
const network = new StacksMainnet();

function App() {
  const [userData, setUserData] = useState<any>(null);
  const [balance, setBalance] = useState<string>('0');
  
  useEffect(() => {
    if (userSession.isUserSignedIn()) {
      const userData = userSession.loadUserData();
      setUserData(userData);
      fetchBalance(userData.profile.stxAddress.mainnet);
    }
  }, []);
  
  const fetchBalance = async (address: string) => {
    const response = await fetch(
      `${network.coreApiUrl}/extended/v1/address/${address}/stx`
    );
    const data = await response.json();
    const stxBalance = parseInt(data.balance) / 1_000_000;
    setBalance(stxBalance.toFixed(6));
  };
  
  // ... rest of the component remains the same
  
  return (
    <div style={{ padding: '2rem' }}>
      <h1>My Stacks App</h1>
      {!userData ? (
        <button onClick={connectWallet}>Connect Wallet</button>
      ) : (
        <div>
          <p>Connected as: {userData.profile.stxAddress.mainnet}</p>
          <p>Balance: {balance} STX</p>
          <button onClick={disconnect}>Disconnect</button>
        </div>
      )}
    </div>
  );
}

Now your app displays both the connected address and STX balance.

Quickstart

What you'll learn

Prerequisites

Quickstart

Install a Stacks wallet

Set up your project

Create the connection component

Run your app

Display account balance

Next steps

Transaction signing→

Message signing→