Workflows

Workflows are asynchronous, multi-step processes that track the progress of loan operations.

What is a Workflow?

A workflow represents a complex operation (like borrowing or repaying) that involves multiple steps and external events (like Bitcoin deposits).

const workflowId = await sdk.executeBorrow(selectedQuote);

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

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

Workflow Types

Borrow Workflow

Tracks loan creation. These are the stages currently exposed by the SDK flow:

Stage	Description
`INITIALIZING`	Workflow starting
`QUOTE_READY`	Bridge quote prepared
`DEPOSIT_ADDRESS_READY`	Deposit address generated
`AWAITING_DEPOSIT`	Waiting for BTC deposit
`AWAITING_DEPOSIT_CONFIRMATION`	BTC detected; waiting for confirmations
`DEPOSIT_CONFIRMED`	Deposit received
`PREPARING_BORROW_DEPOSIT`	Preparing to supply collateral
`COLLATERAL_DEPOSITED`	Collateral processed
`PREPARING_LOAN`	Loan being prepared
`LOAN_CONFIRMED`	Loan executed
`PREPARING_DISBURSEMENT`	Preparing the destination payout
`DISBURSEMENT_SUBMITTED`	Destination payout submitted
`DISBURSEMENT_COMPLETED`	Destination payout confirmed
`COMPLETED`	Workflow complete
`FAILED`	Workflow failed
`DISBURSEMENT_FAILED`	Loan is live, but destination payout failed
`CANCELLED`	Workflow cancelled
`REFUND_INITIATED`	Refund started after a bridge failure
`REFUND_COMPLETED`	Deposited BTC refunded

BorrowWorkflowStage also contains compatibility stages used by other lending paths: PREPARING_DEPOSIT, AUTO_TRANSFERRING_BTC, AWAITING_REDEEM, REDEEM_CONFIRMED, PREPARING_BORROW, PREPARING_REPAY, AWAITING_REPAY_CONFIRMATION, PREPARING_WITHDRAW, and AWAITING_WITHDRAW_CONFIRMATION. A particular operation does not visit every stage.

Borrow More Workflow

Borrow More reuses existing collateral and therefore skips the Bitcoin bridge and collateral transaction. It still emits the shared position-preparation stage:

INITIALIZING → PREPARING_BORROW_DEPOSIT → PREPARING_LOAN → LOAN_CONFIRMED → PREPARING_DISBURSEMENT → DISBURSEMENT_SUBMITTED → DISBURSEMENT_COMPLETED → COMPLETED

Deposit More Workflow

Deposit More bridges new Bitcoin collateral but does not borrow or disburse:

INITIALIZING → QUOTE_READY → DEPOSIT_ADDRESS_READY → AWAITING_DEPOSIT → AWAITING_DEPOSIT_CONFIRMATION → DEPOSIT_CONFIRMED → PREPARING_BORROW_DEPOSIT → COLLATERAL_DEPOSITED → COMPLETED

Repay Workflow

Tracks the repayment process:

Stage	Description
`INITIALIZING`	Starting repayment
`TRANSFERRING_TO_KERNEL`	Moving funds
`REPAYING_LOAN`	Executing repayment
`WITHDRAWING_COLLATERAL`	Withdrawing BTC
`TRANSFERRING_TO_PLATFORM_WALLET`	Preparing bridge
`BRIDGE_INITIALIZING`	Bridge starting
`BRIDGE_QUOTE_READY`	Bridge quote received
`BRIDGE_SWAP_CREATED`	Swap created
`BRIDGE_EXECUTING_APPROVAL`	Approving tokens
`BRIDGE_APPROVAL_CONFIRMED`	Approval confirmed
`BRIDGE_EXECUTING_INITIATE`	Initiating bridge
`BRIDGE_INITIATE_CONFIRMED`	Bridge initiated
`BRIDGE_AWAITING_BRIDGE_COMPLETION`	Waiting for bridge
`BRIDGE_COMPLETED`	Bridge complete
`COMPLETED`	Workflow complete
`FAILED`	Workflow failed
`CANCELLED`	Workflow cancelled

Withdrawal Workflows

Bitcoin withdrawals use the bridge stages:

INITIALIZING → QUOTE_READY → SWAP_CREATED → EXECUTING_APPROVAL → APPROVAL_CONFIRMED → EXECUTING_INITIATE → INITIATE_CONFIRMED → AWAITING_BRIDGE_COMPLETION → BRIDGE_COMPLETED → COMPLETED

Direct EVM withdrawals use: INITIALIZING → VALIDATING → CHECKING_BALANCE → EXECUTING_TRANSFER → COMPLETED Both withdrawal flows can terminate at FAILED or CANCELLED.

Status fields

SDK status endpoints expose several related fields:

Field	Meaning
`status` / `stage`	Current workflow stage. They currently contain the same value.
`transactionStatuses`	Public chronological stage history.
`transactionState`	Compact current state used for tracking.
`workflowState`	Deprecated compatibility alias for `transactionState`.
`transactionDetails`	Public operation metadata; never the internal database document.

Do not depend on raw bridge quotes, database fields, or provider payloads. Those are intentionally not part of the public SDK response.

Stage enums can grow as workflows become more detailed. Handle unknown stages gracefully and use isComplete and isFailed from WorkflowStatus for terminal UI behavior.

Workflow Status Object

interface WorkflowStatus {
  stage: string;           // Current stage name
  step: number;            // Step number (1-based)
  label: string;           // Human-readable label
  description: string;     // Detailed description
  depositAddress?: string; // BTC deposit address (if applicable)
  depositAmount?: number;  // Required deposit in satoshis
  depositAmountBTC?: number;
  depositTxHash?: string;
  currentConfirmations?: number;
  requiredConfirmations?: number;
  error?: string;          // Error message (if failed)
  isComplete: boolean;     // Whether workflow is done
  isFailed: boolean;       // Whether workflow failed
  rawData: any;            // Public status endpoint response
}

Tracking Workflows

Tracking a Borrow Workflow

After executeBorrow() returns a workflow ID, pass it to trackWorkflow():

const workflowId = await sdk.executeBorrow(selectedQuote);

await sdk.trackWorkflow(workflowId, {
  onStatusUpdate: (status) => console.log(status.label),
  onComplete: () => console.log('Done!')
}, 'borrow');

Resuming Tracking

Resume tracking a workflow that was interrupted:

// Store workflow ID somewhere
localStorage.setItem('pendingWorkflow', workflowId);

// Later, resume tracking
const workflowId = localStorage.getItem('pendingWorkflow');
if (workflowId) {
  await sdk.resumeLoan(workflowId, {
    onStatusUpdate: (status) => console.log(status),
    onComplete: () => {
      localStorage.removeItem('pendingWorkflow');
    }
  });
}

Workflow Callbacks

`onStatusUpdate`

Called when the workflow stage changes:

onStatusUpdate: (status: WorkflowStatus) => {
  console.log(`[${status.step}] ${status.label}`);
  console.log(`  ${status.description}`);

  // Update UI progress
  updateProgressBar(status.step, getTotalSteps(status.stage));
}

`onDepositReady`

Called when a deposit address is ready (borrow workflows): Treat this callback as time-sensitive in the UI: the deposit address is single-use and the quote stays locked for up to 6 hours.

onDepositReady: (info: DepositInfo) => {
  console.log('Deposit Required:');
  console.log(`  Address: ${info.address}`);
  console.log(`  Amount: ${info.amountBTC} BTC`);
  console.log(`  Satoshis: ${info.amount}`);

  // Show QR code, send notification, etc.
  showDepositModal(info);
}

`onComplete`

Called when the workflow completes successfully:

onComplete: (result: any) => {
  console.log('Workflow completed!');
  console.log('Result:', result);

  // Navigate to success page, show notification, etc.
  router.push('/loan/success');
}

`onError`

Called when the workflow fails:

onError: (error: string) => {
  console.error('Workflow failed:', error);

  // Show error message, offer retry, etc.
  showErrorModal(error);
}

Polling Configuration

The SDK polls for workflow status at a configurable interval:

const sdk = new BorrowSDK({
  // ...
  workflowPollInterval: 2000 // Poll every 2 seconds (default)
});

Interval	Use Case
1000ms	Responsive UI, more API calls
2000ms	Default, good balance
5000ms	Less frequent updates, fewer API calls

Minimum interval is 100ms.

Stopping Tracking

Stop All Tracking

// Stops all active workflow trackers
sdk.clearSession();

Workflow State Diagram

Borrow Workflow

Getting Workflow Status Manually

// Get current status without callbacks
const status = await sdk.getStatus(workflowId);

console.log('Stage:', status.stage);
console.log('Complete:', status.isComplete);

Handling Pending Workflows

Check for and resume pending workflows on app load:

async function checkPendingWorkflows(sdk: BorrowSDK) {
  const pending = await sdk.getPendingLoans();

  for (const loan of pending) {
    const workflowId = loan.borrowTransaction?.workflowId;
    if (workflowId) {
      console.log(`Found pending loan: ${workflowId}`);

      await sdk.resumeLoan(workflowId, {
        onStatusUpdate: (s) => console.log(s.label),
        onComplete: () => console.log('Resumed loan completed'),
        onDepositReady: (info) => {
          console.log(`Still waiting for deposit to ${info.address}`);
        }
      });
    }
  }
}

Best Practices

1. Always Handle Errors

const workflowId = await sdk.executeBorrow(selectedQuote);
await sdk.trackWorkflow(workflowId, {
  onError: (error) => {
    // Log for debugging
    console.error('Workflow error:', error);

    // Show user-friendly message
    showNotification('Loan failed. Please try again.');

    // Track for analytics
    analytics.track('loan_failed', { error });
  }
}, 'borrow');

2. Persist Workflow IDs

const workflowId = await sdk.executeBorrow(selectedQuote);

// Persist for resumption
await saveWorkflowId(workflowId);

// On completion, clean up
onComplete: async () => {
  await clearWorkflowId(workflowId);
}

3. Show Progress Indicator

const stages = ['INITIALIZING', 'AWAITING_DEPOSIT', 'PROCESSING', 'COMPLETED'];

onStatusUpdate: (status) => {
  const index = stages.indexOf(status.stage);
  const progress = (index / stages.length) * 100;
  updateProgressBar(progress);
}

4. Handle Page Refresh

// On page load
useEffect(() => {
  const pendingId = localStorage.getItem('workflowId');
  if (pendingId) {
    sdk.resumeLoan(pendingId, callbacks);
  }
}, []);

Overview

Suite

UI Components

Swaps

Borrow

Bridge

Earn

Workflows

Workflows

What is a Workflow?

Workflow Types

Borrow Workflow

Borrow More Workflow

Deposit More Workflow

Repay Workflow

Withdrawal Workflows

Status fields

Workflow Status Object

Tracking Workflows

Tracking a Borrow Workflow

Resuming Tracking

Workflow Callbacks

`onStatusUpdate`

`onDepositReady`

`onComplete`

`onError`

Polling Configuration

Stopping Tracking

Stop All Tracking

Workflow State Diagram

Borrow Workflow

Getting Workflow Status Manually

Handling Pending Workflows

Best Practices

1. Always Handle Errors

2. Persist Workflow IDs

3. Show Progress Indicator

4. Handle Page Refresh

​Workflows

​What is a Workflow?

​Workflow Types

​Borrow Workflow

​Borrow More Workflow

​Deposit More Workflow

​Repay Workflow

​Withdrawal Workflows

​Status fields

​Workflow Status Object

​Tracking Workflows

​Tracking a Borrow Workflow

​Resuming Tracking

​Workflow Callbacks

​onStatusUpdate

​onDepositReady

​onComplete

​onError

​Polling Configuration

​Stopping Tracking

​Stop All Tracking

​Workflow State Diagram

​Borrow Workflow

​Getting Workflow Status Manually

​Handling Pending Workflows

​Best Practices

​1. Always Handle Errors

​2. Persist Workflow IDs

​3. Show Progress Indicator

​4. Handle Page Refresh

Workflows

What is a Workflow?

Workflow Types

Borrow Workflow

Borrow More Workflow

Deposit More Workflow

Repay Workflow

Withdrawal Workflows

Status fields

Workflow Status Object

Tracking Workflows

Tracking a Borrow Workflow

Resuming Tracking

Workflow Callbacks

`onStatusUpdate`

`onDepositReady`

`onComplete`

`onError`

Polling Configuration

Stopping Tracking

Stop All Tracking

Workflow State Diagram

Borrow Workflow

Getting Workflow Status Manually

Handling Pending Workflows

Best Practices

1. Always Handle Errors

2. Persist Workflow IDs

3. Show Progress Indicator

4. Handle Page Refresh