Deposit from Bitcoin

​

Deposit Address Options

Spark offers two Bitcoin deposit address types, each with its own trade-offs. For a detailed comparison, read the full guide here.

​

Static Deposit Addresses

• Reusable - Same address can receive multiple deposits
• User-friendly - Eliminates confusion from one-time address restrictions
• Production-ready - Ideal for apps where users might accidentally reuse addresses

​

Single-Use Deposit Addresses

• One-time use only - Each address can only receive one deposit
• More Privacy - Each transaction uses a fresh address
• Legacy support - Available for specific use cases requiring fresh addresses (e.g. regulated custodians that mandate a new address for each deposit)

​

Generate Deposit Addresses

For Bitcoin deposits on L1, Spark generates P2TR addresses. These addresses start with “bc1p” for mainnet and can be used to receive Bitcoin from any wallet.

​

Static Deposit Address

Generate a reusable Bitcoin address that can receive multiple deposits. This is the recommended approach for most applications as it provides a smoother UX and eliminates the risk of users accidentally sending to expired addresses.

const staticDepositAddress = await wallet.getStaticDepositAddress();
console.log("Static Deposit Address:", staticDepositAddress);
// This address can be reused for multiple deposits

Mainnet Address Example: bc1p5d7rjq7g6rdk2yhzks9smtbqtedr4dekq08ge8ztwac72sfr9rusxg3297

​

Single-Use Deposit Address

Generate a fresh address for each deposit. As deposited funds are mapped to the Spark statechain, these addresses can only be used once.

const depositAddress = await wallet.getSingleUseDepositAddress();
console.log("Single-use Deposit Address:", depositAddress);
// Warning: This address can only be used once

​

Deposit Bitcoin

​

Mainnet Deposits

To deposit Bitcoin on the mainnet, initiate a transaction by sending your funds to one of the available deposit address types—either a static or single-use address.

​

Regtest Deposits

For testing purposes on the Regtest network, take advantage of our faucet. This tool allows you to easily fund your Spark wallet without using real Bitcoin.

​

Monitor for Deposit Transactions

After sending Bitcoin to your deposit address, you’ll need to monitor for incoming transactions yourself using a blockchain explorer or your own infrastructure.

​

For Static Deposits

Since static addresses can receive multiple deposits, you’ll need to actively monitor the address for new transactions using your own explorer or infrastructure:

// You'll need to implement your own monitoring solution
const staticAddress = await wallet.getStaticDepositAddress();

// Example: Monitor for new transactions using a block explorer API
// const newTransactions = await yourBlockchainMonitor.checkAddress(staticAddress);

​

For Single-Use Deposits

For single-use deposits, you need to monitor all your unused deposit addresses for incoming transactions:

import { getLatestDepositTxId } from "@buildonspark/spark-sdk/utils";

// Step 1: Get all unused deposit addresses
const unusedAddresses = await wallet.getUnusedDepositAddresses();

// Step 2: Check each address for transactions
for (const address of unusedAddresses) {
  // Use the utility function or check manually via bitcoind/mempool.space
  const txId = await getLatestDepositTxId(address);
  
  if (txId) {
    console.log(`Transaction found: ${txId} for address: ${address}`);
    // Proceed to claim this deposit
    const tx = await wallet.claimDeposit(txId);
  }
}

​

Claiming Deposits

​

Static Deposit Claiming

For static deposit addresses, the claiming process involves getting a quote first, then claiming with the provided signature. This gives you full control over when and how much to claim from each deposit:

// Step 1: Get a quote for your deposit (can be called anytime after transaction)
const quote = await wallet.claimStaticDepositQuote(txId);
console.log("Quote:", quote);

// Step 2: Claim the deposit using the quote details
// Note: This will only succeed after 3 confirmations on the deposit transaction
const claimResult = await wallet.claimStaticDeposit(
  txId, 
  quote.creditAmountSats, 
  quote.sspSignature
);
console.log("Claim successful:", claimResult);

​

Single-Use Deposit Claiming

Once confirmed, run claimDeposit(txId) to claim the deposit from a single-use address:

if (result) {
  console.log("Transaction ID: ", result);
  const tx = await wallet.claimDeposit(result);
}

​

Refunding Static Deposits

If you need to recover funds from a static deposit address without bringing them into Spark, you can refund the deposit back to a Bitcoin address. This is more cost-effective than claiming the deposit and then doing a cooperative exit, as it requires only one transaction fee instead of two.

Use cases for refunding:

• You don’t like the quote from claimStaticDepositQuote
• You prefer to avoid the double-fee scenario (claim fee + cooperative exit fee)
• You want to send funds to a different address without using Spark

// Refund a static deposit (minimum fee: 300 sats)
const refundTxHex = await wallet.refundStaticDeposit(
  depositTxId,
  destinationAddress,
  feeSats // Must be at least 300 sats
);

// You'll need to broadcast this transaction yourself
console.log("Refund transaction hex:", refundTxHex);

​

Confirmation Requirements

• Deposits require 3 confirmations on L1
• Funds will be available in your Spark wallet after confirmation

​

Best Practices

• Use static deposit addresses for production applications to prevent user confusion and potential fund loss
• Start with a small test amount for your first deposit
• Keep track of your deposit transaction IDs
• Wait for the required confirmations before considering the deposit complete
• Save static deposit addresses for easy reuse across multiple deposits
• When refunding static deposits, ensure your fee is at least 300 sats

​

Next Steps

Once your deposit is confirmed, you can:

• Send and receive Lightning payments
• Send and receive Spark payments
• Cooperative Exit to Bitcoin when needed