Monitor

Check a Credit Account's health factor, then inspect the balances, oracle prices, liquidation thresholds, and quotas that determine it.

Connect SDK

Follow Connect SDK first. The snippets below use the already-connected instance as sdk.

Find your leveraged position

Read the leveraged positions owned by your wallet address, owner. Use the onchain source here so the position and the market data below come from RPC:

const positions = await sdk.positions.onchain.list({
  wallet: owner,
  filter: { kind: "strategy" },
});

positions.data contains the leveraged positions. Check positions.meta.chains for read status, block, and timestamp. A failed read does not mean there are no leveraged positions.

With the strategy filter, each entry in positions.data is a StrategyPosition:

TokenAmount contains token, value, and valueUsd. value is a bigint in that token's base units; valueUsd is a dollar value or null when unavailable. Equity is totalValue.value - totalDebt.value; the position does not have a netValue field. Backend-only fields such as historical APYs and PnL are not included in this onchain read.

Select the account to inspect:

import type { StrategyPosition } from "@gearbox-protocol/sdk/model";

const selectedIndex = 0; // Index of your position in the returned list
const position = positions.data[selectedIndex] as StrategyPosition;

Check health factor

Health factor is the collateral value counted for solvency divided by total debt value:

• $B_i$ is the token balance in whole-token units.
• $P_i$ is its oracle price; $P_u$ is the underlying token's oracle price.
• $L_i$ is its liquidation threshold as a fraction, such as $0.9$ for 90%.
• $Q_i$ is its allocated quota in whole underlying-token units.
• $D$ is total debt, including accrued interest and fees, valued using $P_u$.

Prices must use the same currency. A quota caps the LT-weighted value, not the raw collateral value. An inactive quota contributes zero. The formula describes eligible collateral; the SDK also applies integer rounding and token eligibility and dust rules. Safe-price checks can use lower prices than the main oracle prices.

The SDK reports healthFactor as $\lfloor 10000 \times \mathrm{HF} \rfloor$: 12500 means 1.25, and below 10000 the account is liquidatable. With zero debt, the SDK returns the sentinel 65535 instead of dividing by zero.

A falling HF can come from a lower token balance or oracle price, a lower liquidation threshold, a binding quota, or growing debt. Inspect these components to distinguish the cause.

Collateral yield can increase balances or the token's oracle price and improve HF, but only while the resulting contribution is not capped by quota. Borrowing interest and quota costs increase debt and reduce HF over time. A change in quota affects HF only when it changes the collateral value counted for solvency.

Inspect collateral

Each entry in position.collaterals describes one held token:

The account can hold several tokens. Inspect every collateral entry, not just targetCollateral. A redemption phantom is reported as the held token; its pending underlying proceeds are described by withdrawals.

Prices and liquidation thresholds are available from the selected account's market. They are not fields of PositionCollateral. Select one held token:

const chain = sdk.onchain.chain(position.chainId);
const suite = chain.marketRegister.findCreditManager(position.creditManager);

const collateralIndex = 0; // Index of the collateral to inspect
const token = position.collaterals[collateralIndex].collateral.token.address;

const price = suite.market.priceOracle.mainPrice(token); // USD per token, 8 decimals
const lt = suite.creditManager.liquidationThresholds.get(token); // Basis points: 9000 = 90%

mainPrice() throws if the price is unavailable; lt is undefined if the threshold is missing. Neither case is a successful valuation. Use collateral.valueUsd above for the held balance's dollar value.

Read the position and its market data together. After refreshing chain state, read the position again rather than combining old balances with new prices or thresholds.

Actions and their effect on HF

HF effects assume unchanged prices and liquidation thresholds. Deposit and withdraw preserve leverage by default, but quota caps and execution costs can prevent exact HF preservation. Preview the proposed action to check its actual effect before executing it.

Source

• SDK position fields
• Collateral valuation