Quick Start

Get your first Bitcoin-backed loan in under 5 minutes.

Prerequisites

Before you begin, ensure you have:

Installed the SDK (npm install @satsterminal-sdk/borrow)
An API key from SatsTerminal
A Bitcoin wallet with signing capability

Full React integration example

The official Borrow SDK Example shows how these SDK concepts fit together in a production-style Next.js application. It covers Bitcoin wallet integration, BorrowProvider, session restoration, quote selection, workflow tracking, loan history, management actions, repayment, collateral withdrawal, and platform-wallet withdrawal. The example composes the individual Borrow UI registry components. It intentionally does not use the all-in-one BorrowApp, so its source is useful when you want to understand or customize the SDK integration layer.

Step 1: Initialize the SDK

import { BorrowSDK, ChainType } from '@satsterminal-sdk/borrow';

const sdk = new BorrowSDK({
  apiKey: 'your-api-key',
  wallet: {
    address: 'bc1qxyz...', // Your BTC address
    signMessage: async (message: string) => {
      // Implement signing with your wallet
      return await yourWallet.signMessage(message);
    }
  }
});

Step 2: Optional Account Setup

Use setup() when you want to preload account state for dashboards. It is optional for borrowing because executeBorrow() derives the chain from the selected quote and prepares the required wallet/session state automatically:

const { platformWallet, userStatus, activeSession } = await sdk.setup();

console.log('Smart Account:', platformWallet.address);
console.log('Session valid until:', new Date(activeSession.validUntil * 1000));

setup() may prompt the user to sign with their Bitcoin wallet. If you skip setup, the first executeBorrow() call may prompt for the required signatures instead.

Step 3: Preview Fees Before Borrowing

If your UI needs to show fees up front, fetch quotes first and then request the fee breakdown for the selected quote:

const quotes = await sdk.getQuotes({
  collateralAmount: '0.1',
  loanAmount: '5000'
});

const selectedQuote = quotes[0];

const fees = await sdk.getQuoteFees({
  collateralAmount: '0.1',
  loanAmount: '5000',
  fromChain: ChainType.BITCOIN,
  fromAssetSymbol: 'BTC',
  toChain: selectedQuote.chain,
  toAssetSymbol: selectedQuote.collateralAssetSymbol ?? 'WBTC',
  loanChain: selectedQuote.loanChain ?? selectedQuote.chain,
  loanAssetSymbol: selectedQuote.loanAssetSymbol ?? 'USDC'
});

console.log('Bridge fee USD:', fees.bridgeFees.totalBridgeFeeUSD);
console.log('Platform fee:', fees.borrowFees.platformFee);
console.log('Net loan to user:', fees.borrowFees.netLoanAmount);

Step 4: Execute and Track the Borrow

After the user selects a quote, execute that quote and track the resulting borrow workflow:

const workflowId = await sdk.executeBorrow(selectedQuote);

await sdk.trackWorkflow(workflowId, {
  onStatusUpdate: (status) => {
    console.log(`[${status.step}] ${status.label}`);
  },

  onDepositReady: (info) => {
    console.log(`\nDeposit Required:`);
    console.log(`  Amount: ${info.amountBTC} BTC`);
    console.log(`  Address: ${info.address}`);
  },

  onComplete: (result) => {
    console.log('\nLoan Complete!');
  },

  onError: (error) => {
    console.error('Error:', error);
  }
}, 'borrow');

console.log('Workflow ID:', workflowId);
console.log('Selected Quote:', selectedQuote);

Step 5: Deposit Bitcoin

When onDepositReady fires, send the required Bitcoin to the deposit address: Deposit addresses are single-use and the quote remains locked for up to 6 hours. If the deposit is not received before that window ends, request a fresh quote and deposit address.

onDepositReady: async (info) => {
  // If your wallet supports programmatic sending:
  if (sdk.walletProvider.sendBitcoin) {
    const txHash = await sdk.sendBitcoin(
      info.address,
      Math.round(info.amountBTC * 100_000_000) // Convert to satoshis
    );
    console.log('Deposit TX:', txHash);
  } else {
    // Otherwise, display for manual deposit
    console.log(`Please send ${info.amountBTC} BTC to ${info.address}`);
  }
}

Step 6: Loan Complete

Once the deposit is confirmed and processed, the loan will be executed automatically. The borrowed stablecoins will be available in your smart account.

Complete Example

import { BorrowSDK, ChainType } from '@satsterminal-sdk/borrow';

async function main() {
  // Initialize
  const sdk = new BorrowSDK({
    apiKey: process.env.SATSTERMINAL_API_KEY!,
    wallet: {
      address: process.env.BTC_ADDRESS!,
      signMessage: async (msg) => yourWallet.signMessage(msg)
    }
  });

  // Get quotes
  console.log('Requesting quotes...');
  const quotes = await sdk.getQuotes({
    collateralAmount: '0.1',
    loanAmount: '5000'
  });
  const selectedQuote = quotes[0];

  // Execute and track borrow
  console.log('Starting borrow...');
  const workflowId = await sdk.executeBorrow(selectedQuote);
  await sdk.trackWorkflow(workflowId, {
    onStatusUpdate: (s) => console.log(`Status: ${s.label}`),
    onDepositReady: (i) => console.log(`Deposit ${i.amountBTC} BTC to ${i.address}`),
    onComplete: () => console.log('Done!'),
    onError: (e) => console.error(e)
  }, 'borrow');
}

main().catch(console.error);

What’s Next?

Borrow SDK Example - Complete React integration using the atomic UI components
Configuration - Customize SDK behavior
Getting a Loan - Detailed loan guide
API Reference - Full API documentation

Overview

Suite

UI Components

Swaps

Borrow

Bridge

Earn

Quick start

Quick Start

Prerequisites

Full React integration example

Step 1: Initialize the SDK

Step 2: Optional Account Setup

Step 3: Preview Fees Before Borrowing

Step 4: Execute and Track the Borrow

Step 5: Deposit Bitcoin

Step 6: Loan Complete

Complete Example

What’s Next?

​Quick Start

​Prerequisites

​Full React integration example

​Step 1: Initialize the SDK

​Step 2: Optional Account Setup

​Step 3: Preview Fees Before Borrowing

​Step 4: Execute and Track the Borrow

​Step 5: Deposit Bitcoin

​Step 6: Loan Complete

​Complete Example

​What’s Next?

Quick Start

Prerequisites

Full React integration example

Step 1: Initialize the SDK

Step 2: Optional Account Setup

Step 3: Preview Fees Before Borrowing

Step 4: Execute and Track the Borrow

Step 5: Deposit Bitcoin

Step 6: Loan Complete

Complete Example

What’s Next?