Status system

SDK responses that expose flow state use LiquidiumStatus:

type LiquidiumStatus = {
  operation: "deposit" | "borrow" | "repayment" | "withdrawal" | "liquidation";
  state:
    | "action_required"
    | "confirming"
    | "processing"
    | "active"
    | "completed"
    | "failed"
    | "expired";
  confirmations: number | null;
  requiredConfirmations: number | null;
};

Use status.operation to decide which user action or receipt type you are showing. Use status.state to decide the UI treatment.

Operations

The following table describes each operation:

Operation	Meaning
`deposit`	The user sends funds into Liquidium for supply or initial Simple Loan collateral
`borrow`	Liquidium sends borrowed funds to the configured destination
`repayment`	The user sends funds back to repay debt
`withdrawal`	Liquidium sends supplied funds or collateral out
`liquidation`	A liquidation entry from profile history

Activities narrow the operation by direction. Inflow activities use deposit or repayment. Outflow activities use borrow or withdrawal.

States

The following table describes each state and its UI treatment:

State	Meaning	UI treatment
`action_required`	The app needs the user to send funds, sign, or complete the next step	Show the transfer target or wallet action
`confirming`	Liquidium has a transaction ID or detected chain activity and waits for confirmations	Show pending confirmations when present
`processing`	Liquidium is processing the operation outside the chain-confirmation phase	Keep polling and block duplicate submissions
`active`	The operation has opened a live position or debt remains	Show the active position and next repayment or withdrawal action
`completed`	The operation finished	Stop prompting for the operation
`failed`	The operation failed	Show the failure, reload source data, and retry only when the method documentation says that the call is safe to repeat
`expired`	The user missed the allowed time window	Stop showing the expired transfer target

confirmations and requiredConfirmations are populated only while state is confirming. Confirmation progress never exceeds the required count. Both fields are null after the operation moves to processing because any remaining work belongs to Liquidium's internal settlement lifecycle.

Status fields

The following table shows where each status appears:

Surface	Field
`client.simpleLoans.create(...)` and `client.simpleLoans.get(...)`	`loan.status`
`client.activities.list(...)`	`activity.status`
`client.activities.getStatus(...)`	`result.activity.status` when `result.found` is `true`
`client.history.getUserTransactionHistory(...)`	`item.status`
`client.history.getLiquidationHistory(...)`	`item.status`
`client.lending.supply(...)`	`flow.status`
`client.lending.borrow(...)` and `client.lending.withdraw(...)`	`details.status`

Poll a single activity

If your app has a receipt or activity ID and needs its most recent state, use client.activities.getStatus(...):

const result = await client.activities.getStatus({
  shortRef: loan.ref,
  id: activityId,
});

if (result.found) {
  const { operation, state, confirmations, requiredConfirmations } =
    result.activity.status;

  console.log(operation, state, confirmations, requiredConfirmations);
}

Pass profileId instead of shortRef for account-based profile flows.

List active work

To list active work by short reference:

const activities = await client.activities.list({
  shortRef: loan.ref,
  filter: "active",
});

client.activities.list(...) defaults to active activities. Pass filter: "completed" for finished work or filter: "all" for both.

For inflow activities, check activity.topUp. When topUp.required is true, the user must send topUp.shortfallAmount more before processing can continue.

Poll for status changes

The SDK returns status snapshots. It does not start background polling or set a polling interval for your app.

Poll while your app waits for an external state change, such as transaction detection, confirmation, or protocol processing. Stop polling when the state is completed, failed, or expired. When the state is active, wait for the next user action unless the page needs live position updates.

Use your app's bounded polling and backoff policy. Do not repeat a state-changing SDK call only because its status has not changed. Reload the loan, activity, position, or history entry instead.

Operations​

States​

Status fields​

Poll a single activity​

List active work​

Poll for status changes​