Sign transactions

Prompt users to sign transactions and broadcast them to the Stacks blockchain.

The process of broadcasting transactions is fundamental for interacting with blockchains, whether you're transferring tokens, deploying contracts, or executing contract functions.

In this guide, you will learn how to:

  1. Install the necessary packages for building and broadcasting transactions.
  2. Build different types of transactions.
  3. Sign and broadcast those transactions to the Stacks blockchain.
  4. Process and handle the results.

The examples in this guide are designed to be minimalistic, allowing you to easily adapt and customize these examples to fit your application's specific needs.

Setup and installation

Install the required packages to start building and broadcasting transactions.

  • @stacks/network: Used to interact with the Stacks blockchain network.
  • @stacks/transactions: Used to build the transactions.
  • @stacks/connect: Used to authenticate users and broadcast the transactions.
npm install @stacks/network @stacks/transactions @stacks/connect

Initiate a session

Users must authenticate to an app before prompting them to sign and broadcast transactions to the Stacks blockchain with an authenticator such as the Leather wallet.

import { AppConfig, UserSession } from '@stacks/connect';

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

See the authentication guide for more information and a full example.

Create a transaction

There are three types of transactions: STX transfers, contract deployments, and contract executions.

To prompt the user to transfer STX, call the openSTXTransfer function provided by the @stacks/connect package to trigger the display of a transaction signing prompt for transferring STX:

import { openSTXTransfer } from '@stacks/connect';
import { StacksTestnet } from '@stacks/network';

  recipient: 'ST2EB9WEQNR9P0K28D2DC352TM75YG3K0GT7V13CV',
  amount: '100',
  memo: 'Reimbursement',
  network: new StacksTestnet(),
  appDetails: {
    name: 'My App',
    icon: window.location.origin + '/my-app-logo.svg',
  onFinish: data => {
    console.log('Stacks Transaction:', data.stacksTransaction);
    console.log('Transaction ID:', data.txId);
    console.log('Raw transaction:', data.txRaw);

Several parameters are available for calling openSTXTransfer. To learn more, check out our reference page.

Handle the results of the signed transaction

Each transaction signing method from @stacks/connect allows you to specify an onFinish callback. This callback will be triggered after the user has successfully broadcasted their transaction. The transaction will be broadcasted, but it will be pending until it has been mined on the Stacks blockchain.

You can access some information about this transaction via the arguments passed to onFinish. Your callback will be fired with a single argument, which is an object with the following properties:

interface FinishedTxData {
  stacksTransaction: StacksTransaction;
  txRaw: string;
  txId: string;

The StacksTransaction type comes from the @stacks/transactions library.

The txId property can be used to provide a link to view the transaction in the explorer.

const onFinish = data => {
  const explorerTransactionUrl = '${data.txId}';
  console.log('View transaction in explorer:', explorerTransactionUrl);

Specifying a network for a transaction

All of the methods included on this page accept a network option. By default, Connect uses a testnet network option. You can import a network configuration from the @stacks/network package.

Next steps