Skip to main content

Migration Guide

This guide helps you migrate from older versions of the SatsTerminal Borrow SDK.

Migrating from v0.x to v1.x

Breaking Changes

1. Method Renames

v0.xv1.xNotes
setupForLoan()setup()Simplified name
borrow()executeBorrow()More descriptive
getUserTransactions()getLoanHistory()Consistent naming
Migration:
// v0.x
await sdk.setupForLoan();
await sdk.borrow(quote);
await sdk.getUserTransactions(1, 10);

// v1.x
await sdk.setup();
await sdk.executeBorrow(quote);
await sdk.getLoanHistory({ page: 1, limit: 10 });

2. getLoanHistory Parameters

The method now takes an options object instead of positional arguments:
// v0.x
await sdk.getUserTransactions(1, 10, 'active');

// v1.x
await sdk.getLoanHistory({
  page: 1,
  limit: 10,
  status: 'active'
});

3. getLoan High-Level Method (New)

v1.x introduces getLoan() for a simplified experience:
// v0.x - Manual flow
await sdk.setupForLoan();
const quotes = await sdk.getQuotes(params);
await sdk.borrow(quotes[0]);
// Manual tracking...

// v1.x - Simplified
await sdk.getLoan({
  collateralBTC: 0.1,
  loanAmountUSD: 5000,
  onStatusUpdate: (status) => console.log(status),
  onComplete: () => console.log('Done!')
});

4. Storage Key Namespacing

Storage keys are now namespaced to prevent collisions:
// v0.x keys
wallet_0_signature

// v1.x keys
@satsterminal/borrow/wallet_0_signature
Impact: Existing cached signatures will need to be re-signed on first use after upgrade.

5. Error Classes

Error classes now include more context:
// v0.x
try {
  await sdk.setup();
} catch (error) {
  console.log(error.message);
}

// v1.x
try {
  await sdk.setup();
} catch (error) {
  if (error instanceof SmartAccountError) {
    console.log(error.code);    // Error code
    console.log(error.context); // Additional context
    console.log(error.toJSON()); // JSON representation
  }
}

New Features in v1.x

High-Level getLoan Method

const result = await sdk.getLoan({
  collateralBTC: 0.1,
  loanAmountUSD: 5000,
  ltv: 70,
  onStatusUpdate: (status) => console.log(status.label),
  onDepositReady: (info) => console.log(`Deposit ${info.amountBTC} BTC`),
  onComplete: () => console.log('Complete!'),
  onError: (error) => console.error(error)
});

Collateral Management

// Get collateral info
const info = await sdk.getLoanCollateralInfo(loanId);

// Withdraw collateral
await sdk.withdrawCollateral(loanId, '0.01', 'bc1q...', {
  trackWorkflow: true,
  callbacks
});

Portfolio & Positions

// Get token positions
const positions = await sdk.getWalletPositions();

// Get portfolio summary
const portfolio = await sdk.getWalletPortfolio();

Cross-Chain Withdrawals

await sdk.withdrawToBitcoin({
  chain: ChainType.ARBITRUM,
  amount: '100',
  assetSymbol: 'USDC',
  btcAddress: 'bc1q...'
});

Fee Information

const fees = await sdk.getFees({
  chain: ChainType.ARBITRUM,
  collateralAmount: '0.1'
});

Deprecated Methods

These methods still work but will be removed in v2.x:
// Deprecated - use setup()
await sdk.setupForLoan();

// Deprecated - use executeBorrow()
await sdk.borrow(quote);

// Deprecated - use getLoanHistory()
await sdk.getUserTransactions(page, limit, status);

Migration Checklist

  • Update method calls to new names
  • Update getLoanHistory to use options object
  • Consider using new getLoan() high-level method
  • Update error handling to use new error properties
  • Test with fresh session (storage keys changed)
  • Update any direct storage access to use new key prefix

Example: Full Migration

Before (v0.x):
import { BorrowSDK } from '@satsterminal-sdk/borrow';

const sdk = new BorrowSDK({
  apiKey: 'key',
  chain: 'arbitrum',
  wallet: walletProvider
});

async function getLoan() {
  try {
    await sdk.setupForLoan();

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

    const workflowId = await sdk.borrow(quotes[0]);

    // Manual polling for status...
    let status;
    while (!status?.isComplete) {
      status = await sdk.getStatus(workflowId);
      await new Promise(r => setTimeout(r, 2000));
    }

    const history = await sdk.getUserTransactions(1, 10, 'active');
    console.log('Loans:', history);

  } catch (error) {
    console.error(error.message);
  }
}
After (v1.x):
import {
  BorrowSDK,
  ChainType,
  SmartAccountError,
  ApiError
} from '@satsterminal-sdk/borrow';

const sdk = new BorrowSDK({
  apiKey: 'key',
  chain: ChainType.ARBITRUM,
  wallet: walletProvider
});

async function getLoan() {
  try {
    // New high-level method handles everything
    const result = await sdk.getLoan({
      collateralBTC: 0.1,
      loanAmountUSD: 5000,
      ltv: 70,
      onStatusUpdate: (status) => {
        console.log(`[${status.step}] ${status.label}`);
      },
      onDepositReady: (info) => {
        console.log(`Deposit ${info.amountBTC} BTC to ${info.address}`);
      },
      onComplete: () => {
        console.log('Loan complete!');
      },
      onError: (error) => {
        console.error('Loan failed:', error);
      }
    });

    // New method name with options object
    const history = await sdk.getLoanHistory({
      page: 1,
      limit: 10,
      status: 'active'
    });
    console.log('Loans:', history);

  } catch (error) {
    // New error handling
    if (error instanceof SmartAccountError) {
      console.error('Wallet error:', error.code, error.context);
    } else if (error instanceof ApiError) {
      console.error('API error:', error.statusCode);
    } else {
      console.error('Error:', error);
    }
  }
}

Version Compatibility

SDK VersionAPI VersionNode.jsTypeScript
1.xv116+5.0+
0.xv114+4.7+

Need Help?