Skip to main content

Types

Complete type reference for the SatsTerminal Borrow SDK.

Enums

ChainType

Supported blockchain networks.
enum ChainType {
  BASE = 'base',
  ARBITRUM = 'arbitrum',
  ETHEREUM = 'ethereum'
}

SessionScope

Session permission levels.
enum SessionScope {
  READ = 'read',
  DEFI = 'defi',
  FULL = 'full'
}

ErrorCode

Error classification codes.
enum ErrorCode {
  WALLET_NOT_CONNECTED = 'WALLET_NOT_CONNECTED',
  SMART_ACCOUNT_ERROR = 'SMART_ACCOUNT_ERROR',
  API_ERROR = 'API_ERROR',
  CONFIG_ERROR = 'CONFIG_ERROR',
  QUOTE_ERROR = 'QUOTE_ERROR',
  WORKFLOW_ERROR = 'WORKFLOW_ERROR',
  STORAGE_ERROR = 'STORAGE_ERROR',
  NETWORK_ERROR = 'NETWORK_ERROR',
  VALIDATION_ERROR = 'VALIDATION_ERROR'
}

Configuration

BorrowSDKConfig

SDK configuration options.
interface BorrowSDKConfig {
  // Required
  apiKey: string;
  baseUrl: string;
  chain: ChainType;
  wallet: WalletProvider;

  // Optional
  rpcUrl?: string;
  bundlerUrl?: string;
  storage?: StorageProvider;
  workflowPollInterval?: number;
  sessionValiditySeconds?: number;
  autoTrackWorkflows?: boolean;
  quoteSelector?: (quotes: Quote[]) => Quote;
  retryConfig?: RetryConfig;
  logger?: Logger;
}

WalletProvider

Wallet integration interface.
interface WalletProvider {
  address: string;
  publicKey?: string;
  signMessage: (message: string) => Promise<string>;
  sendBitcoin?: (toAddress: string, satoshis: number) => Promise<string>;
}

StorageProvider

Storage abstraction interface.
interface StorageProvider {
  getItem(key: string): string | null;
  setItem(key: string, value: string): void;
  removeItem(key: string): void;
  clear(): void;
}

RetryConfig

Request retry configuration.
interface RetryConfig {
  maxRetries: number;
  retryDelay: number;
  retryableStatusCodes: number[];
}

Logger

Logging interface.
interface Logger {
  debug: (message: string) => void;
  info: (message: string) => void;
  warn: (message: string) => void;
  error: (message: string) => void;
}

User & Session

UserStatus

Current user status.
interface UserStatus {
  isConnected: boolean;
  btcAddress?: string;
  smartAccountAddress?: string;
  isDeployed?: boolean;
  hasActiveSession: boolean;
  sessionExpiry?: number;
}

ActiveSession

Active session details.
interface ActiveSession {
  sessionKeyAddress?: string;
  sessionPrivateKey?: string;
  validUntil: number;
  authorizationSignature?: string;
  scope?: SessionScope;
}

Loan & Quote

QuoteRequest

Parameters for requesting quotes.
interface QuoteRequest {
  collateralAmount: string;
  loanAmount: string;
  ltv: number;
  term?: number;
}

Quote

Loan quote from a protocol.
interface Quote {
  collateralAmount: string;
  loanAmount: string;
  protocol: string;
  chain: ChainType;
  borrowApy: {
    variable: string;
    stable: string;
  };
  effectiveApy?: {
    variable: string;
    stable: string;
  };
}

GetLoanOptions

Options for getLoan method.
interface GetLoanOptions {
  collateralBTC: number;
  loanAmountUSD: number;
  ltv?: number;
  term?: number;
  destinationAddress?: string;
  quoteSelector?: (quotes: Quote[]) => Quote;
  onStatusUpdate?: (status: WorkflowStatus) => void;
  onDepositReady?: (info: DepositInfo) => void;
  onComplete?: (result: any) => void;
  onError?: (error: string) => void;
}

LoanResult

Result from getLoan method.
interface LoanResult {
  workflowId: string;
  quote: Quote;
  tracker: any;
  stop: () => void;
}

LoanCollateralInfo

Collateral information for a loan.
interface LoanCollateralInfo {
  totalCollateral: string;
  availableCollateral: string;
  maxWithdrawable: string;
  totalDebt: string;
  remainingDebt: string;
}

Transactions

UserTransaction

User transaction record.
interface UserTransaction {
  id: string;
  type: 'borrow' | 'repay' | 'withdraw';
  status: 'pending' | 'active' | 'completed' | 'failed' | 'awaiting_deposit';
  amount: string;
  currency: string;
  txHash?: string;
  timestamp: number;
  borrowTransaction?: any;
  repayTransaction?: any;
}

PaginatedResponse

Paginated response wrapper.
interface PaginatedResponse<T> {
  transactions: T[];
  pagination: {
    totalTransactions: number;
    currentPage: number;
    limit: number;
    totalPages: number;
    hasNext: boolean;
    hasPrevious: boolean;
  };
}

RepayTransaction

Repayment transaction details.
interface RepayTransaction {
  _id: string;
  userId: string;
  originalBorrowId: string;
  loanChainAddress: string;
  repayAmount: string;
  withdrawalCollateralAmount: string;
  repayTokenAddress: string;
  isPartialRepay: boolean;
  isPartialWithdrawCollateral: boolean;
  useCollateral: boolean;
  workflowId?: string;
  transactionStatuses: Array<{
    status: string;
    timestamp: Date;
    details?: string;
  }>;
  repayConfig: any;
  userBtcWithdrawAddress?: string;
  bridgeConfig?: any;
  workflowState?: RepayWorkflowState;
  createdAt: Date;
  updatedAt: Date;
}

RepayTransactionStatusResponse

Status response for repay transactions.
interface RepayTransactionStatusResponse {
  transactionDetails: RepayTransaction;
  transactionState?: RepayWorkflowState;
}

Workflow

WorkflowStatus

Current workflow status.
interface WorkflowStatus {
  stage: string;
  step: number;
  label: string;
  description: string;
  depositAddress?: string;
  depositAmount?: number;
  error?: string;
  isComplete: boolean;
  isFailed: boolean;
  rawData: any;
}

WorkflowCallbacks

Callbacks for workflow tracking.
interface WorkflowCallbacks {
  onStatusUpdate?: (status: WorkflowStatus) => void;
  onComplete?: (result: any) => void;
  onError?: (error: string) => void;
  onDepositReady?: (info: DepositInfo) => void;
}

DepositInfo

Deposit information.
interface DepositInfo {
  address: string;
  amount: number;
  amountBTC: number;
}

RepayWorkflowState

Repay workflow state.
interface RepayWorkflowState {
  stage: RepayWorkflowStage;
  error?: string;
  redeemTxHash?: string;
}

RepayWorkflowStage

Repay workflow stages.
enum RepayWorkflowStage {
  INITIALIZING,
  TRANSFERRING_TO_KERNEL,
  REPAYING_LOAN,
  WITHDRAWING_COLLATERAL,
  TRANSFERRING_TO_PLATFORM_WALLET,
  BRIDGE_INITIALIZING,
  BRIDGE_QUOTE_READY,
  BRIDGE_SWAP_CREATED,
  BRIDGE_EXECUTING_APPROVAL,
  BRIDGE_APPROVAL_CONFIRMED,
  BRIDGE_EXECUTING_INITIATE,
  BRIDGE_INITIATE_CONFIRMED,
  BRIDGE_AWAITING_BRIDGE_COMPLETION,
  BRIDGE_COMPLETED,
  COMPLETED,
  FAILED,
  CANCELLED
}

Wallet & Portfolio

WalletPosition

Token position in wallet.
interface WalletPosition {
  id: string;
  type: string;
  attributes: {
    parent: string | null;
    protocol: string | null;
    name: string;
    position_type: string;
    quantity: {
      int: string;
      decimals: number;
      float: number;
      numeric: string;
    };
    value: number | null;
    price: number;
    changes: {
      absolute_1d: number | null;
      percent_1d: number | null;
    } | null;
    fungible_info: {
      name: string;
      symbol: string;
      icon: { url: string } | null;
      flags: { verified: boolean };
      implementations: Array<{
        chain_id: string;
        address: string;
        decimals: number;
      }>;
    } | null;
    flags: {
      displayable: boolean;
      is_trash: boolean;
    };
    updated_at: string;
    updated_at_block: number;
  };
  relationships: {
    chain: { data: { type: string; id: string } };
  };
}

WalletPositionsResponse

Response for wallet positions.
interface WalletPositionsResponse {
  data: WalletPosition[];
  links?: { self: string };
}

WalletPortfolio

Portfolio summary.
interface WalletPortfolio {
  id: string;
  type: string;
  attributes: {
    positions_distribution_by_type: Record<string, number>;
    positions_distribution_by_chain: Record<string, number>;
    total: { positions: number };
    changes: {
      absolute_1d: number;
      percent_1d: number;
    };
  };
}

WalletPortfolioResponse

Response for wallet portfolio.
interface WalletPortfolioResponse {
  data: WalletPortfolio;
  links?: { self: string };
}

Fees & Withdrawals

FeesRequest

Fee information request.
interface FeesRequest {
  chain: ChainType;
  collateralAmount: string;
}

FeesResponseData

Fee information response.
interface FeesResponseData {
  chain: ChainType;
  collateralAmount: string;
  gardenFeePercent: number;
  affiliateFeePercent: number;
  totalBridgeFeePercentage: number;
  totalBridgeFeeUSD: string;
  gardenFeeUSD: string;
  affiliateFeeUSD: string;
  estimatedGasFee: string;
}

WithdrawToBitcoinRequest

Cross-chain withdrawal request to Bitcoin.
interface WithdrawToBitcoinRequest {
  chain: ChainType;
  amount: string;
  assetSymbol: string;
  btcAddress: string;
}

WithdrawToEVMRequest

Gasless EVM withdrawal request (sponsored gas).
interface WithdrawToEVMRequest {
  chain: ChainType;
  amount: string;
  destinationAddress: string;
  /** Optional wallet index. Defaults to 0 (base wallet where borrowed USDC goes). */
  loanIndex?: number;
}

WithdrawToEVMResponse

Response from EVM withdrawal.
interface WithdrawToEVMResponse {
  success: boolean;
  data: {
    transactionId: string;
    transactionHash: string;
    status: string;
    sourceAddress: string;
    destinationAddress: string;
    amount: string;
    chain: ChainType;
  };
}

WithdrawStatusResponse

Withdrawal status response.
interface WithdrawStatusResponse {
  success: boolean;
  data: WithdrawTransaction;
  transactionState?: {
    stage: string;
    redeemTxHash?: string;
    error?: string;
  };
}

Utility Types

BtcUtils

Bitcoin utility class.
class BtcUtils {
  static satsToBtc(sats: number): string;
  static btcToSats(btc: string): number;
  static formatBtcDisplay(amount: string | number): string;
}

Example

import { BtcUtils } from '@satsterminal-sdk/borrow';

BtcUtils.satsToBtc(10000000);        // "0.10000000"
BtcUtils.btcToSats("0.1");           // 10000000
BtcUtils.formatBtcDisplay(0.123456); // "0.12345600"