Hiro Docs

Create and broadcast transactions to the Stacks blockchain network using Stacks.js.

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:

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

Setup and installation

Install the required packages to start building and broadcasting transactions.

Terminal

$ npm install @stacks/network @stacks/transactions @stacks/connect

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

Create a transaction

There are three types of transactions:

STX transfer
Contract deployment
Contract execution

To transfer STX, use the makeSTXTokenTransfer function provided by the @stacks/transactions package:

stx-transfer.ts

import { AnchorMode, makeSTXTokenTransfer, broadcastTransaction } from "@stacks/transactions";
import { StacksDevnet } from "@stacks/network";

const transaction = await makeSTXTokenTransfer({
  recipient: "SP3FGQ8Z7JY9BWYZ5WM53E0M9NK7WHJF0691NZ159",
  amount: 12345n,
  senderKey:
    "753b7cc01a1a2e86221266a154af739463fce51219d97e4f856cd7200c3bd2a601",
  network: new StacksDevnet(),
  anchorMode: AnchorMode.Any,
});

This builds a STX token transfer transaction. The makeSTXTokenTransfer function takes parameters like the recipient address, amount to transfer, and the sender's private key, ie senderKey.

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

Broadcasting the transaction

After building the transaction, broadcast it to the Stacks blockchain network using the broadcastTransaction function from the @stacks/transactions package.

1Pass in the transaction object you created in the previous step to the broadcastTransaction function.
2Handle the response by logging the response object.

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

const broadcastResponse = await broadcastTransaction(transaction);

This code sends the signed transaction to the Stacks blockchain. The broadcastTransaction function returns a response containing the transaction ID, which can be used to track the transaction on the blockchain.

Handle the results

Handle the transaction results by checking the transaction status and responding accordingly.

if (broadcastResponse.success) {
  console.log('Transaction successful with ID:', broadcastResponse.txid);
} else {
  console.error('Transaction failed with error:', broadcastResponse.error);
}

This checks if the transaction was successful and logs the txid.

Next steps

Deep dive into post-conditions

Learn how to use post-conditions to secure your smart contracts.

API References

Dive into the API references for Stacks.js.

Broadcast transactions