Examples

End-to-end example scripts for easy implementation using the SDK V2.

Example 1: Complete Rune Purchase Flow

Below is a complete example flow for buying runes using the simplified SDK V2, including waiting for user input for signed PSBTs:

import { SatsTerminal } from 'satsterminal-sdk';
import readlineSync from 'readline-sync';

// Configuration
const CONFIG = {
  apiKey: 'your_api_key_here',
};

// Trade Parameters
const TRADE_PARAMS = {
  fromToken: 'BTC',
  toToken: 'LOBO•THE•WOLF•PUP',
  address: 'bc1p...',
  publicKey: '...',
  paymentAddress: '3Pc...',
  paymentPublicKey: '...',
  amount: '0.0001',
  protocol: 'runes'
};

// Initialize the SDK
const satsTerminal = new SatsTerminal(CONFIG);

// Function to get user input for signed PSBTs (V2 can have multiple)
const getSignedPSBTs = (psbts) => {
  console.log(`\nPlease sign ${psbts.length} PSBT(s):`);
  const signedPsbts = [];
  
  for (let i = 0; i < psbts.length; i++) {
    console.log(`\nPSBT ${i + 1} hex: ${psbts[i].hex}`);
    const signed = readlineSync.question(`Enter signed PSBT ${i + 1} hex: `);
    signedPsbts.push(signed);
  }
  
  return signedPsbts;
};

// Main execution
(async () => {
  try {
    // 1. Get a quote for the swap
    console.log('\n1. Fetching swap quote...');
    const quote = await satsTerminal.swapQuote({
      amount: TRADE_PARAMS.amount,
      fromToken: TRADE_PARAMS.fromToken,
      toToken: TRADE_PARAMS.toToken,
      address: TRADE_PARAMS.address,
      protocol: TRADE_PARAMS.protocol,
      params: {}
    });
  
    console.log('Best marketplace:', quote.bestMarketplace);
    console.log('Swap ID:', quote.swapId);
    console.log('From token amount:', quote.fromTokenAmount);
    console.log('To token amount:', quote.toTokenAmount);
    console.log('Available marketplaces:', Object.keys(quote.marketplaces));

    // 2. Create PSBT(s) for the swap
    console.log('\n2. Creating PSBT(s)...');
    const psbtResponse = await satsTerminal.swapPSBT({
      marketplace: quote.bestMarketplace,
      swapId: quote.swapId,
      address: TRADE_PARAMS.address,
      publicKey: TRADE_PARAMS.publicKey,
      paymentAddress: TRADE_PARAMS.paymentAddress,
      paymentPublicKey: TRADE_PARAMS.paymentPublicKey,
      protocol: TRADE_PARAMS.protocol,
      feeRate: 5,
      slippage: 9,
      themeID: null
    });
  
    console.log(`Created ${psbtResponse.psbts.length} PSBT(s)`);
    console.log('Updated swap ID:', psbtResponse.swapId);
  
    // Wait for user to sign all PSBTs
    const signedPsbts = getSignedPSBTs(psbtResponse.psbts);

    // 3. Submit the signed PSBTs
    console.log('\n3. Submitting signed PSBTs...');
    const result = await satsTerminal.swapSubmit({
      marketplace: quote.bestMarketplace,
      swapId: psbtResponse.swapId,
      address: TRADE_PARAMS.address,
      publicKey: TRADE_PARAMS.publicKey,
      paymentAddress: TRADE_PARAMS.paymentAddress,
      paymentPublicKey: TRADE_PARAMS.paymentPublicKey,
      protocol: TRADE_PARAMS.protocol,
      signedPsbts: signedPsbts
    });
  
    console.log('✅ Swap completed successfully!');
    console.log('Transaction ID:', result.txid);
    console.log('Marketplace used:', result.marketplace);

  } catch (error) {
    console.error('Error:', error.message);
  }
})();

Example 2: Selling Runes for BTC

// Import the SDK
import { SatsTerminal } from 'satsterminal-sdk';
import readlineSync from 'readline-sync';


// Configuration
const CONFIG = {
  // Your API key for SatsTerminal
  apiKey: 'your_api_key_here',
};

// Trade Parameters
const TRADE_PARAMS = {
  // Clear direction: selling runes for BTC
  fromToken: 'DOG•GO•TO•THE•MOON',  // What we're selling
  toToken: 'BTC',                   // What we want to receive
  address: 'bc1puxa2cwvfw47vaadt4lfxwgl4zln9epqtfsq3y7cl7vr5wvfayz6s22mmwp',
  publicKey: 'dd4c950d7a5f86e92235687cffeee1bfb61b5c8a9e15b80751077c3d4315821c',
  paymentAddress: '3PcP9J6C9ZNQpTRHrtqFBhP3LoBjSmMkZq',
  paymentPublicKey: '02af6d71243386e3a24a23ebf47ea91dcf0d114b8ec29163ed9716e9b14a8fe3d8',
  sellAmount: "10000",              // Amount of runes to sell
  protocol: 'runes'
};

// Initialize the SDK
const satsTerminal = new SatsTerminal(CONFIG);

// Function to get user input for signed PSBTs
const getSignedPSBTs = (psbts) => {
  console.log(`\nFound ${psbts.length} PSBT(s) to sign:`);
  const signedPsbts = [];
  
  for (let i = 0; i < psbts.length; i++) {
    console.log(`\nPSBT ${i + 1}:`);
    console.log(`Base64: ${psbts[i].base64.substring(0, 50)}...`);
    console.log(`Hex: ${psbts[i].hex.substring(0, 50)}...`);
    console.log(`Inputs: [${psbts[i].inputs.join(', ')}]`);
    
    const signed = readlineSync.question(`Enter signed PSBT ${i + 1} hex: `);
    signedPsbts.push(signed);
  }
  
  return signedPsbts;
};

// Main execution block (sell runes for BTC)
(async () => {
  try {
    // 1. Get a quote for selling runes
    console.log('\n1. Fetching sell quote...');
    console.log('Trade parameters:', TRADE_PARAMS);
    
    const quote = await satsTerminal.swapQuote({
      amount: TRADE_PARAMS.sellAmount,
      fromToken: TRADE_PARAMS.fromToken,  // Selling runes
      toToken: TRADE_PARAMS.toToken,      // For BTC
      address: TRADE_PARAMS.address,
      protocol: TRADE_PARAMS.protocol,
      params: {}
    });
    
    console.log('✅ Quote received:');
    console.log('Best marketplace:', quote.bestMarketplace);
    console.log('Swap ID:', quote.swapId);
    console.log('Selling:', quote.fromTokenAmount, TRADE_PARAMS.fromToken);
    console.log('Receiving:', quote.toTokenAmount, 'BTC');
    
    // Show all available marketplaces
    console.log('\nAvailable marketplaces:');
    Object.entries(quote.marketplaces).forEach(([name, data]) => {
      console.log(`- ${name}: ${data.fromTokenAmount} → ${data.toTokenAmount} BTC`);
    });

    // 2. Create PSBT(s) for the swap
    console.log('\n2. Creating PSBT(s)...');
    const psbtResponse = await satsTerminal.swapPSBT({
      marketplace: quote.bestMarketplace,
      swapId: quote.swapId,
      address: TRADE_PARAMS.address,
      publicKey: TRADE_PARAMS.publicKey,
      paymentAddress: TRADE_PARAMS.paymentAddress,
      paymentPublicKey: TRADE_PARAMS.paymentPublicKey,
      protocol: TRADE_PARAMS.protocol,
      feeRate: 5,
      slippage: 9,
      themeID: null
    });
    
    console.log(`✅ Created ${psbtResponse.psbts.length} PSBT(s)`);
    console.log('Updated swap ID:', psbtResponse.swapId);
    
    // Wait for user to sign all PSBTs
    const signedPsbts = getSignedPSBTs(psbtResponse.psbts);
    
    // 3. Submit the signed PSBTs
    console.log('\n3. Submitting signed PSBTs...');
    const confirmation = await satsTerminal.swapSubmit({
      marketplace: quote.bestMarketplace,
      swapId: psbtResponse.swapId,
      address: TRADE_PARAMS.address,
      publicKey: TRADE_PARAMS.publicKey,
      paymentAddress: TRADE_PARAMS.paymentAddress,
      paymentPublicKey: TRADE_PARAMS.paymentPublicKey,
      protocol: TRADE_PARAMS.protocol,
      signedPsbts: signedPsbts
    });
    
    console.log('✅ Sell order completed successfully!');
    console.log('Transaction ID:', confirmation.txid);
    console.log('Marketplace:', confirmation.marketplace);
    

  } catch (error) {
    console.error('Error:', error.message);
  }
})();

Example 3: Alkanes Swap

import { SatsTerminal } from 'satsterminal-sdk';
import readlineSync from 'readline-sync';

/**
 * This example demonstrates swapping BTC for alkanes tokens using V2 API
 */

// Configuration
const CONFIG = {
  apiKey: 'your_api_key_here',
};

// Trade Parameters for Alkanes
const TRADE_PARAMS = {
  fromToken: 'BTC',
  toToken: 'GOLD DUST',              // Alkanes token
  address: 'bc1p4mffk7l9a040dgqrl8spunwkguxn68ldwx848urafar9sj85nnrq9rcvyj',
  publicKey: '03962e74f53d3620f82aab9ecfadbaa2d2b34ab1d794b346f53deb4c1a9d287bfc',
  paymentAddress: 'bc1qjtyqu4uqrpnvsfg9tq0wzzsdge3e559wzk4epc',
  paymentPublicKey: '02325fb34ee9ff76df92b34d13059fa8d14008a9426fb1de52f038bfdca5075588',
  amount: '0.00008',
  protocol: 'alkanes'               // Different protocol
};

const satsTerminal = new SatsTerminal(CONFIG);

const getSignedPSBTs = (psbts) => {
  console.log(`\nPlease sign ${psbts.length} PSBT(s) for alkanes swap:`);
  const signedPsbts = [];
  
  psbts.forEach((psbt, index) => {
    console.log(`\nPSBT ${index + 1} details:`);
    console.log(`- Inputs: [${psbt.inputs.join(', ')}]`);
    console.log(`- Hex length: ${psbt.hex.length} characters`);
    
    const signed = readlineSync.question(`Enter signed PSBT ${index + 1} hex: `);
    signedPsbts.push(signed);
  });
  
  return signedPsbts;
};

(async () => {
  try {
    console.log('🔄 Starting alkanes token swap...');
    
    // 1. Get quote for alkanes swap
    console.log('\n1. Getting alkanes swap quote...');
    const quote = await satsTerminal.swapQuote({
      amount: TRADE_PARAMS.amount,
      fromToken: TRADE_PARAMS.fromToken,
      toToken: TRADE_PARAMS.toToken,
      address: TRADE_PARAMS.address,
      protocol: TRADE_PARAMS.protocol,
      params: {}
    });
    
    console.log('✅ Alkanes quote received:');
    console.log(`Swapping ${quote.fromTokenAmount} BTC → ${quote.toTokenAmount} ${TRADE_PARAMS.toToken}`);
    console.log('Best marketplace:', quote.bestMarketplace);
    
    // Show metrics for different marketplaces
    if (quote.metrics) {
      console.log('\nMarketplace performance:');
      Object.entries(quote.metrics).forEach(([marketplace, metrics]) => {
        console.log(`- ${marketplace}: ${metrics.percentFulfilled}% fulfilled, avg price: ${metrics.averageUnitPrice}`);
      });
    }

    // 2. Create PSBTs
    console.log('\n2. Creating alkanes swap PSBTs...');
    const psbtResponse = await satsTerminal.swapPSBT({
      marketplace: quote.bestMarketplace,
      swapId: quote.swapId,
      address: TRADE_PARAMS.address,
      publicKey: TRADE_PARAMS.publicKey,
      paymentAddress: TRADE_PARAMS.paymentAddress,
      paymentPublicKey: TRADE_PARAMS.paymentPublicKey,
      protocol: TRADE_PARAMS.protocol,
      feeRate: 3,
      slippage: 5,
      themeID: null
    });
    
    console.log(`✅ Generated ${psbtResponse.psbts.length} PSBT(s) for alkanes swap`);
    
    // Sign PSBTs
    const signedPsbts = getSignedPSBTs(psbtResponse.psbts);
    
    // 3. Submit alkanes swap
    console.log('\n3. Executing alkanes swap...');
    const result = await satsTerminal.swapSubmit({
      marketplace: quote.bestMarketplace,
      swapId: psbtResponse.swapId,
      address: TRADE_PARAMS.address,
      publicKey: TRADE_PARAMS.publicKey,
      paymentAddress: TRADE_PARAMS.paymentAddress,
      paymentPublicKey: TRADE_PARAMS.paymentPublicKey,
      protocol: TRADE_PARAMS.protocol,
      signedPsbts: signedPsbts
    });
    
    console.log('🎉 Alkanes swap completed!');
    console.log('Transaction ID:', result.txid);
    console.log(`Successfully swapped BTC for ${TRADE_PARAMS.toToken}`);

  } catch (error) {
    console.error('Error:', error.message);
  }
})();