How to Airdrop Spark Tokens to Any Xverse User via Their Taproot Address

TL;DR: Spark now enables projects to airdrop tokens directly to any Xverse user by using their Bitcoin Taproot (bc1p...) address. This guide provides the complete, step-by-step Typescript code to derive a user's unique Spark airdrop address from their public Taproot address. This allows you to reward on-chain Bitcoin identities directly, with tokens appearing automatically in their Xverse wallet for a simple, one-click claim.

A Seamless Bridge Between Taproot and Spark

The Bitcoin ecosystem is vibrant, with communities forming around Ordinals, Runes, and BRC-20s, all using Taproot addresses (bc1p...) as their on-chain identity.

Until now, bridging these users into Layer 2 token ecosystems required invasive steps like linking wallets or signing messages.

With this new Spark feature, projects can directly target and reward these on-chain Bitcoin identities. By deriving a Spark address from a user's Taproot public key, you can send BTKN airdrops that are instantly recognized by their Xverse wallet—no sign-up or wallet linking required. It’s a seamless bridge between Bitcoin culture and Spark-native tokens.

How it Works: The Xverse "Claim" Flow

To make this possible, every Xverse wallet now has two Spark addresses under the hood:

• Primary Spark Address: This is your main, visible address used for trading, DeFi, and managing your primary balance.
• Taproot-Derived Spark Address: This is a hidden, secondary address used only for receiving airdrops based on your Taproot identity.

When you airdrop tokens to a user's Taproot-derived address, Xverse automatically detects the new balance. The user doesn't see a confusing second wallet; instead, the token simply appears in their main dashboard with a ✳️ “Claim” label next to it.

When the user clicks "Claim," Xverse creates a simple transaction to move the tokens from the hidden derived address to their primary Spark address. It’s a smooth, one-click UX built directly into the wallet.

Step-by-Step Guide: Deriving a Spark Airdrop Address

The function provided in our Sats Connect documentation is the core piece of logic, but it needs to be part of a runnable script. Here is a complete, step-by-step guide to setting up a project and running the code.

Step 1: Create Your Project

First, ensure you have Node.js and npm installed. Open your terminal, create a new folder, and initialize a new project.

mkdir taproot-spark-tool
cd taproot-spark-tool
npm init -y
mkdir src
touch src/index.ts

Step 2: Install Dependencies

You'll need a few packages to handle Bitcoin address decoding, Spark address encoding, and running the TypeScript file.

npm install @scure/btc-signer @scure/base @buildonspark/spark-sdk ts-node typescript

Step 3: Paste the Script into src/index.ts

This is the complete, runnable script. It imports the libraries, defines the derivation function, and includes an entrypoint to run it.

// Imports
import { Address } from '@scure/btc-signer';
import { hex } from '@scure/base';
import { encodeSparkAddress } from '@buildonspark/spark-sdk';

/**
 * Derives a Spark Airdrop Address from a Taproot (bc1p...) Bitcoin address.
 * Docs: https://docs.xverse.app/sats-connect/spark-methods/spark-btkn-airdrops#deriving-a-users-spark-address
 */
export const getSparkAirdropAddress = async (taprootAddress: string): Promise<string> => {
  const decoded = Address().decode(taprootAddress);

  if (decoded.type !== 'tr') {
    throw new Error('Invalid address. Only Taproot (bc1p...) addresses are supported.');
  }

  // Convert internal pubkey to hex and prefix with `02` (`encodeSparkAddress` expects a full public key while the taproot pubKey drops the y co-ordinate)
  const identityPublicKey = `02${hex.encode(decoded.pubkey)}`;

  return encodeSparkAddress({
    identityPublicKey,
    network: 'MAINNET',
  });
};

// ----- EXECUTION ENTRYPOINT -----

const run = async () => {
  const userTaprootAddress: string = 'bc1p...'; // 👈 Replace with a real Taproot address

  if (!userTaprootAddress.startsWith('bc1p')) {
    console.warn('⚠️ Please set userTaprootAddress to a valid Taproot address (bc1p...).');
    return;
  }

  console.log(`Deriving Spark address for Taproot address: ${userTaprootAddress}`);

  try {
    const sparkAddress = await getSparkAirdropAddress(userTaprootAddress);

    console.log('\n✅ Spark Airdrop Address Generated:');
    console.log(sparkAddress);
    console.log('\nYou can now send Spark BTKN tokens to this address.');
  } catch (err: any) {
    console.error(`❌ Error: ${err.message}`);
  }
};

run();

Step 4: Run the Script

Before you run, open src/index.ts and change the userTaprootAddress variable to the real bc1p... address you want to target.

Then, run the script in your terminal:

npx ts-node src/index.ts

Get the Result: The script will output the derived Spark Airdrop Address. This is the MAINNET address you will use for your airdrop.

✅ Spark Airdrop Address Generated:
spark1p...

The User Experience: A Simple One-Click Claim

Once you have the derived address and send tokens to it, the experience for the Xverse user is incredibly simple:

• Airdrop Sent: You send your BTKN tokens (e.g., $DRAGON) to the user's derived Spark address.
• Tokens Appear: The user opens Xverse and sees $DRAGON in their token list, with a ✳️ "Claim" tag.
• User Claims: They tap the "Claim" button.
• Transfer Confirmed: Xverse shows a simple confirmation screen to move the tokens from their "Taproot-derived" address to their "Primary" address.
• Done: The tokens are now consolidated in their main wallet, ready to be used in DeFi or swaps.

Get Started with Xverse Tooling

This airdrop feature enables developers to directly engage with the core Bitcoin community in a way that's never been possible before. It works with any existing Taproot user base and is instantly compatible with Xverse.

This is just one piece of the Xverse ecosystem, designed to help you build powerful applications on Bitcoin.

• Connect Your dApp with Sats Connect: To integrate your website or dApp directly with Xverse, you can use Sats Connect. This JavaScript library allows your application to seamlessly retrieve BTC addresses and request transaction signatures on Bitcoin, Stacks, and other Bitcoin layer 2 protocols. It's the bridge that connects your platform to the user's wallet.
• Power Your Backend with Xverse API: To get the on-chain data you need, the Xverse API provides a simple and reliable way to build on Bitcoin. For Spark, our API gives you access to a rich set of endpoints to query token balances, retrieve transaction histories, and get details on specific transactions. This empowers you to build robust applications, dashboards, and services on top of the Spark protocol.

Get Started with Xverse

This feature empowers developers to directly engage with the core Bitcoin community in a way that's never been possible before. It works with any existing Taproot user base and is instantly compatible with Xverse.

Download Xverse today to see the seamless user experience for yourself and explore our documentation to start building on Bitcoin.