Skip to main content

BorrowSDK

The main class for interacting with SatsTerminal Borrow.

Constructor

new BorrowSDK(config: BorrowSDKConfig)
Creates a new SDK instance.

Parameters

ParameterTypeDescription
configBorrowSDKConfigSDK configuration

Example

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

const sdk = new BorrowSDK({
  apiKey: 'your-api-key',
  chain: ChainType.ARBITRUM,
  wallet: {
    address: 'bc1q...',
    signMessage: async (msg) => wallet.signMessage(msg)
  }
});

Properties

userStatus

Current user status.
readonly userStatus: UserStatus

baseWalletAddress

The base smart wallet address (index 0).
readonly baseWalletAddress: string | null

Methods

setup()

Initialize the SDK and create a session.
async setup(): Promise<{
  baseWallet: { address: string; signature: string };
  userStatus: UserStatus;
  activeSession: ActiveSession;
  transactions: UserTransaction[];
}>

Returns

PropertyTypeDescription
baseWalletobjectBase wallet address and signature
userStatusUserStatusCurrent user status
activeSessionActiveSessionActive session details
transactionsUserTransaction[]Recent transactions

Example

const { baseWallet, userStatus, activeSession } = await sdk.setup();
console.log('Smart Account:', baseWallet.address);

startNewLoan()

Create a new loan wallet with incremented index.
async startNewLoan(): Promise<{
  userStatus: UserStatus;
  activeSession: ActiveSession;
}>

Example

const { userStatus, activeSession } = await sdk.startNewLoan();
// Now ready to execute borrow

getLoan()

High-level method to get a loan with automatic setup, quotes, and tracking.
async getLoan(options: GetLoanOptions): Promise<LoanResult>

Parameters

ParameterTypeRequiredDescription
collateralBTCnumberYesBTC collateral amount
loanAmountUSDnumberYesLoan amount in USD
ltvnumberNoLoan-to-value ratio (default: 70)
termnumberNoTerm in days (default: 30)
destinationAddressstringNoDestination for borrowed funds
quoteSelectorfunctionNoCustom quote selection
onStatusUpdatefunctionNoStatus update callback
onDepositReadyfunctionNoDeposit ready callback
onCompletefunctionNoCompletion callback
onErrorfunctionNoError callback

Returns

PropertyTypeDescription
workflowIdstringWorkflow identifier
quoteQuoteSelected quote
trackerWorkflowTrackerTracker instance
stopfunctionStop tracking function

Example

const result = await sdk.getLoan({
  collateralBTC: 0.1,
  loanAmountUSD: 5000,
  onStatusUpdate: (s) => console.log(s.label),
  onComplete: () => console.log('Done!')
});

getQuotes()

Get available loan quotes.
async getQuotes(params: QuoteRequest): Promise<Quote[]>

Parameters

ParameterTypeRequiredDescription
collateralAmountstringYesCollateral in BTC
loanAmountstringYesLoan amount in USD
ltvnumberYesLoan-to-value ratio
termnumberNoTerm in days

Example

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

executeBorrow()

Execute a borrow with a selected quote.
async executeBorrow(quote: Quote, options?: {
  destinationAddress?: string;
}): Promise<string>

Returns

string - Workflow ID

Example

const workflowId = await sdk.executeBorrow(selectedQuote);

repay()

Repay a loan.
async repay(
  originalBorrowId: string,
  repayAmount: string,
  options?: {
    useCollateral?: boolean;
    collateralToWithdraw?: string;
    userBtcWithdrawAddress?: string;
    trackWorkflow?: boolean;
    callbacks?: WorkflowCallbacks;
  }
): Promise<string>

Parameters

ParameterTypeRequiredDescription
originalBorrowIdstringYesLoan ID to repay
repayAmountstringYesAmount to repay
useCollateralbooleanNoUse collateral for repayment
collateralToWithdrawstringNoBTC to withdraw
userBtcWithdrawAddressstringNoBTC destination
trackWorkflowbooleanNoTrack the workflow
callbacksWorkflowCallbacksNoTracking callbacks

Example

await sdk.repay(loanId, '1000', {
  collateralToWithdraw: '0.01',
  userBtcWithdrawAddress: 'bc1q...',
  trackWorkflow: true,
  callbacks: {
    onComplete: () => console.log('Repaid!')
  }
});

withdrawCollateral()

Withdraw collateral from a loan.
async withdrawCollateral(
  originalBorrowId: string,
  collateralAmount: string,
  btcWithdrawAddress: string,
  options?: {
    trackWorkflow?: boolean;
    callbacks?: WorkflowCallbacks;
  }
): Promise<string>

Example

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

getLoanCollateralInfo()

Get collateral information for a loan.
async getLoanCollateralInfo(loanId: string): Promise<LoanCollateralInfo | null>

Returns

{
  totalCollateral: string;
  availableCollateral: string;
  maxWithdrawable: string;
  totalDebt: string;
  remainingDebt: string;
}

getLoanHistory()

Get loan transaction history.
async getLoanHistory(options?: {
  page?: number;
  limit?: number;
  status?: 'active' | 'pending' | 'all';
}): Promise<PaginatedResponse<UserTransaction>>

Example

const history = await sdk.getLoanHistory({
  page: 1,
  limit: 20,
  status: 'active'
});

getPendingLoans()

Get loans awaiting deposit.
async getPendingLoans(): Promise<UserTransaction[]>

getRepayTransactions()

Get repay transactions for a loan.
async getRepayTransactions(loanId?: string): Promise<RepayTransaction[]>

getRepayStatus()

Get status of a repay transaction.
async getRepayStatus(transactionId: string): Promise<RepayTransactionStatusResponse>

trackWorkflow()

Manually track a workflow.
async trackWorkflow(
  workflowId: string,
  callbacks: WorkflowCallbacks,
  workflowType?: 'borrow' | 'repay'
): Promise<void>

resumeLoan()

Resume tracking a loan workflow.
async resumeLoan(workflowId: string, callbacks?: WorkflowCallbacks): Promise<void>

getStatus()

Get workflow status.
async getStatus(workflowId: string): Promise<any>

sendBitcoin()

Send Bitcoin (requires wallet provider with sendBitcoin).
async sendBitcoin(toAddress: string, satoshis: number): Promise<string>

getFees()

Get fee information.
async getFees(params: FeesRequest): Promise<FeesResponseData>

Example

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

getWalletPositions()

Get token positions for the base wallet.
async getWalletPositions(params?: {
  filterPositions?: string;
  filterTrash?: string;
}): Promise<WalletPositionsResponse>

getWalletPortfolio()

Get portfolio summary.
async getWalletPortfolio(filter?: string): Promise<WalletPortfolioResponse>

withdrawToBitcoin()

Withdraw EVM assets to Bitcoin.
async withdrawToBitcoin(params: WithdrawToBitcoinRequest): Promise<string>

Parameters

ParameterTypeDescription
chainChainTypeSource chain
amountstringAmount to withdraw
assetSymbolstringAsset symbol (USDC, USDT)
btcAddressstringDestination BTC address

getWithdrawStatus()

Get withdrawal status.
async getWithdrawStatus(transactionId: string): Promise<WithdrawStatusResponse>

withdrawToEVM()

Withdraw USDC from smart account to an EVM address with sponsored gas (gasless).
async withdrawToEVM(params: WithdrawToEVMRequest): Promise<string>

Parameters

ParameterTypeRequiredDescription
chainChainTypeYesSource chain (ARBITRUM, BASE)
amountstringYesAmount to withdraw (e.g., ‘100’ for 100 USDC)
destinationAddressstringYesDestination EVM address
loanIndexnumberNoWallet index (defaults to 0 for base wallet)

Returns

string - Transaction hash

Features

  • Gasless: Transaction fees are sponsored via ZeroDev paymaster
  • Instant: Single EVM transaction, no bridging required
  • USDC only: Currently supports USDC transfers

Example

// Withdraw USDC to your personal wallet (gasless)
const txHash = await sdk.withdrawToEVM({
  chain: ChainType.ARBITRUM,
  amount: '100',
  destinationAddress: '0x742d35Cc6634C0532925a3b844Bc9e7595f...'
});

console.log('Transaction hash:', txHash);
// Verify on block explorer: https://arbiscan.io/tx/{txHash}

clearSession()

Clear session and reset state.
clearSession(): void

Helper Function

useBorrow()

Factory function to create SDK instance.
function useBorrow(config: BorrowSDKConfig): BorrowSDK

Example

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

const sdk = useBorrow({
  apiKey: 'your-api-key',
  chain: ChainType.ARBITRUM,
  wallet: walletProvider
});