Bitcoin

Execute deposit transactions on Bitcoin mainnet and testnet using PSBT construction.

Overview

Bitcoin deposits use a UTXO-based model. The call_data from the deposit action is a numeric memo that must be embedded in the transaction as an OP_RETURN output. This memo is how Layerswap identifies and matches your deposit.

Prerequisites:

• bitcoinjs-lib for PSBT construction
• @bitcoinerlab/secp256k1 for elliptic curve operations
• Access to a Bitcoin node or the Mempool.space API for UTXO data and fee estimates

call_data Format

For Bitcoin, call_data is the swap’s numeric memo followed by a ; terminator — e.g. "11177265;". Convert the numeric part to hex (use BigInt — Number can lose precision and chokes on the ;) and keep the terminator and anything after it unchanged:

const raw = String(callData);          // e.g. "11177265;"
const semi = raw.indexOf(";");
const seq = semi === -1 ? raw : raw.slice(0, semi);  // "11177265"
const tail = semi === -1 ? "" : raw.slice(semi);     // ";" plus anything after it
const hexMemo = BigInt(seq).toString(16) + tail;     // "aa8d31;"

This memo string is embedded as an OP_RETURN output in the transaction. Layerswap reads only the part before the ; to match the deposit, so you can append your own data after the terminator — as long as the whole OP_RETURN payload stays within the 80-byte limit.

Transaction Construction

1. Fetch UTXOs

   Retrieve unspent transaction outputs for the sender’s address. You can use the Mempool.space API or your own Bitcoin node.

2. Fetch raw transactions

   For each UTXO, fetch the full raw transaction hex. This is needed to populate the witnessUtxo field in the PSBT inputs.

3. Select UTXOs

   Select enough UTXOs to cover the deposit amount plus estimated fees.

4. Build the PSBT

   Create a PSBT with:

   • Inputs: Selected UTXOs with witness data
   • Output 1: Payment to to_address for the deposit amount
   • Output 2: OP_RETURN with the hex-encoded memo
   • Output 3 (if needed): Change back to the sender’s address
5. Estimate fees

   Fetch the recommended fee rate from Mempool.space and calculate the transaction fee based on input/output count. Re-select UTXOs if the initial selection doesn’t cover the fee.

6. Sign and broadcast

   Sign the PSBT with your private key and broadcast the raw transaction.

Full Example

import {
  Psbt,
  Transaction,
  networks,
  opcodes,
  script,
  initEccLib,
  payments,
} from "bitcoinjs-lib";
import * as ecc from "@bitcoinerlab/secp256k1";
import ECPairFactory from "ecpair";
import axios from "axios";

initEccLib(ecc);
const ECPair = ECPairFactory(ecc);

interface Utxo {
  txid: string;
  vout: number;
  value: number;
  status: { confirmed: boolean };
}

const MEMPOOL_BASE = {
  mainnet: "https://mempool.space",
  testnet: "https://mempool.space/testnet",
};

async function fetchUtxos(
  address: string,
  version: "mainnet" | "testnet"
): Promise<Utxo[]> {
  const base = MEMPOOL_BASE[version];
  const { data } = await axios.get<Utxo[]>(
    `${base}/api/address/${address}/utxo`
  );
  return data;
}

async function fetchRawTx(
  txid: string,
  version: "mainnet" | "testnet"
): Promise<Transaction> {
  const base = MEMPOOL_BASE[version];
  const { data } = await axios.get<string>(`${base}/api/tx/${txid}/hex`);
  return Transaction.fromHex(data);
}

async function fetchFeeRate(
  version: "mainnet" | "testnet"
): Promise<number> {
  const base = MEMPOOL_BASE[version];
  const { data } = await axios.get(`${base}/api/v1/fees/recommended`);
  return data.economyFee; // sats/vByte
}

function selectUtxos(
  utxos: Utxo[],
  target: bigint
): { selected: Utxo[]; total: bigint } {
  const sorted = utxos.slice().sort((a, b) => a.value - b.value);
  let sum = 0n;
  const selected: Utxo[] = [];
  for (const u of sorted) {
    selected.push(u);
    sum += BigInt(u.value);
    if (sum >= target) break;
  }
  if (sum < target) {
    throw new Error(`Insufficient funds: need ${target} sats, have ${sum}`);
  }
  return { selected, total: sum };
}

function estimateTxFee(
  numInputs: number,
  numOutputs: number,
  satsPerVbyte: number
): bigint {
  return BigInt((numInputs * 148 + numOutputs * 34 + 10) * satsPerVbyte);
}

async function executeBitcoinDeposit(
  depositAction: any,
  senderAddress: string,
  senderWIF: string,
  isTestnet = false
) {
  const { call_data, to_address, amount, network } = depositAction;
  const version = isTestnet ? "testnet" : "mainnet";
  const network = isTestnet ? networks.testnet : networks.bitcoin;
  const amountSats = Math.floor(amount * 1e8);

  // Convert the numeric memo to hex for OP_RETURN, keeping the ";" terminator
  const raw = String(call_data);
  const semi = raw.indexOf(";");
  const seq = semi === -1 ? raw : raw.slice(0, semi);
  const tail = semi === -1 ? "" : raw.slice(semi);
  const hexMemo = BigInt(seq).toString(16) + tail;
  const memoBuffer = Buffer.from(hexMemo, "utf8");

  if (memoBuffer.length > 80) {
    throw new Error("Memo too long; max 80 bytes for OP_RETURN");
  }

  // Fetch UTXOs, their raw transactions (in parallel), and the fee rate
  const utxos = await fetchUtxos(senderAddress, version);
  const rawTxMap = Object.fromEntries(
    await Promise.all(
      utxos.map(async (u) => [u.txid, await fetchRawTx(u.txid, version)] as const)
    )
  );
  const feeRate = await fetchFeeRate(version);

  // Iteratively build PSBT to account for fees
  let fee = 0n;
  let psbt: Psbt;
  let totalSelected: bigint;

  do {
    const target = BigInt(amountSats) + fee;
    const { selected, total } = selectUtxos(utxos, target);
    totalSelected = total;

    psbt = new Psbt({ network });

    // Add inputs
    for (const utxo of selected) {
      const out = rawTxMap[utxo.txid].outs[utxo.vout];
      psbt.addInput({
        hash: utxo.txid,
        index: utxo.vout,
        witnessUtxo: { script: out.script, value: out.value },
      });
    }

    // Payment output
    psbt.addOutput({
      address: to_address,
      value: BigInt(amountSats),
    });

    // OP_RETURN memo output
    psbt.addOutput({
      script: script.compile([opcodes.OP_RETURN, memoBuffer]),
      value: 0n,
    });

    // Re-estimate fee
    fee = estimateTxFee(
      psbt.txInputs.length,
      psbt.txOutputs.length + 1, // +1 for potential change output
      feeRate
    );
  } while (totalSelected < BigInt(amountSats) + fee);

  // Change output
  const change = totalSelected - BigInt(amountSats) - fee;
  if (change > 0n) {
    psbt.addOutput({ address: senderAddress, value: change });
  }

  // Sign all inputs
  const keyPair = ECPair.fromWIF(senderWIF, network);
  const isTaproot =
    senderAddress.startsWith("bc1p") || senderAddress.startsWith("tb1p");

  for (let i = 0; i < psbt.inputCount; i++) {
    if (isTaproot) {
      psbt.signInput(i, keyPair, [Transaction.SIGHASH_DEFAULT]);
    } else {
      psbt.signInput(i, keyPair);
    }
  }

  psbt.finalizeAllInputs();
  const rawTxHex = psbt.extractTransaction().toHex();

  // Broadcast through the network's node — node_url comes with the deposit action
  const { data } = await axios.post(network.node_url, {
    jsonrpc: "2.0",
    id: 1,
    method: "sendrawtransaction",
    params: [rawTxHex],
  });

  return data.result; // the transaction hash
}

Signing for Different Address Types

Bitcoin has several address formats, each with different signing requirements:

Address Prefix	Type	Sighash
1...	Legacy (P2PKH)	SIGHASH_ALL (1)
3...	Nested SegWit (P2SH-P2WPKH)	SIGHASH_ALL (1)
bc1q... / tb1q...	Native SegWit (P2WPKH)	SIGHASH_ALL (1)
bc1p... / tb1p...	Taproot (P2TR)	SIGHASH_DEFAULT (0)

Taproot addresses require SIGHASH_DEFAULT (0) instead of SIGHASH_ALL (1). Using the wrong sighash type will produce an invalid signature.

Hardware / Browser Wallet Signing

If you’re using a wallet provider (e.g., Xverse, Unisat, Leather) instead of a raw private key, the flow changes at the signing step. Instead of signing locally, you pass the unsigned PSBT hex to the wallet’s signPsbt method:

const psbtHex = psbt.toHex();
const isTaproot =
  senderAddress.startsWith("bc1p") || senderAddress.startsWith("tb1p");

const signedPsbtHex = await walletProvider.request({
  method: "signPsbt",
  params: {
    psbt: psbtHex,
    inputsToSign: [
      {
        address: senderAddress,
        signingIndexes: Array.from({ length: psbt.inputCount }, (_, i) => i),
        sigHash: isTaproot ? 0 : 1,
      },
    ],
    finalize: false,
    sighashTypes: isTaproot ? [0] : [1],
  },
});

const signedPsbt = Psbt.fromHex(signedPsbtHex);

// Some wallets (e.g. MetaMask) return an already-finalized PSBT —
// only finalize the inputs that still need it
signedPsbt.data.inputs.forEach((input, i) => {
  if (!input.finalScriptSig && !input.finalScriptWitness) {
    signedPsbt.finalizeInput(i);
  }
});

const rawTxHex = signedPsbt.extractTransaction().toHex();

Next Step

After the transaction is submitted, notify Layerswap so it can match your deposit faster:

curl -X POST https://api.layerswap.io/api/v2/swaps/{swap_id}/deposit_speedup \
  -H "X-LS-APIKEY: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{ "transaction_id": "YOUR_TX_HASH" }'

See the full deposit flow for details.