# Monitor

> Markdown export of the Gearbox Protocol documentation page for agents and retrieval systems.

Canonical page: https://docs.gearbox.finance/developers/monitor-position
Source file: content/developers/monitor-position.mdx
Section router: https://docs.gearbox.finance/developers/llms.txt
Section full export: https://docs.gearbox.finance/developers/llms-full.txt

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](https://docs.gearbox.finance/developers/sdk-setup) 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:

```typescript
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`:

| Field | Type | Meaning |
| --- | --- | --- |
| `kind` | `"strategy"` | Identifies a leveraged position |
| `name` | `string` | Strategy name |
| `chainId` | `number` | Chain where the position exists |
| `creditAccount` | `Address` | Your position's Credit Account address |
| `creditManager` | `Address` | Credit Manager governing the position |
| `underlyingToken` | `UnderlyingToken` | Asset used to denominate debt and total value; the unwrapped asset for RWA markets |
| `targetCollateral` | `Token \| null` | Strategy's target collateral token, or `null` when no target is identified |
| `collaterals` | `PositionCollateral[]` | Held token balances, allocated quotas, and pending withdrawals |
| `totalValue` | `TokenAmount` | Total value of the account's holdings in the market underlying |
| `totalDebt` | `TokenAmount` | Debt principal plus accrued interest and fees |
| `leverage` | `number` | Total value divided by equity: `4` means 4× |
| `healthFactor` | `number` | Health factor in basis points: `12500` means 1.25 |
| `borrowApy` | `number` | Annual base borrowing cost including the protocol interest fee, in basis points: `520` means 5.2% |
| `borrowRate` | `BorrowRateBreakdown \| undefined` | Borrowing cost broken down into base and quota costs |
| `timeToLiquidation` | `bigint \| null \| undefined` | Estimated milliseconds to HF 1 at a fixed borrowing rate and collateral value—no collateral yield or appreciation. Not a guaranteed safe period. `null` if the rate is zero or HF is already ≤ 1 |
| `liquidationPrice` | `bigint \| null \| undefined` | Immediate price-change threshold for HF 1, using current balances, debt, and LTs. Underlying per collateral token, scaled by `10 ** 8`. Excludes future accrual and quota caps. `null` unless exactly one non-dust, non-underlying asset is held |
| `error` | `string \| undefined` | Incomplete or failed valuation; balances may be available while valued fields are unreliable |

`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:

```typescript
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:

$$
\mathrm{HF} = \frac{\sum_i C_i}{D},
\qquad
C_i =
\begin{cases}
\min(B_i P_i L_i,\; Q_i P_u), & \text{quota-bearing collateral} \\
B_i P_i L_i, & \text{collateral without a quota cap}
\end{cases}
$$

- $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:

| Field | Type | Meaning |
| --- | --- | --- |
| `collateral.token` | `Token` | Held token, including address, symbol, and decimals |
| `collateral.value` | `bigint` | Balance in that token's base units |
| `collateral.valueUsd` | `number \| null` | Dollar value, or `null` when unavailable |
| `quota.value` | `bigint` | Allocated quota in market underlying base units, not collateral token units |
| `withdrawals` | `DelayedReceivedAsset[]` | Pending delayed withdrawals associated with this collateral |

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:

```typescript
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

| Action | Effect on HF | Requirements and dependencies | Side effects |
| --- | --- | --- | --- |
| [Repay](https://docs.gearbox.finance/developers/manage-position#repay) | Increases HF by reducing debt while retaining collateral | Underlying tokens held in your wallet, or the supported unwrapped asset for an RWA market; partial repayment must respect minimum debt | Spends wallet funds and reduces future debt interest; partial repayment does not automatically reduce quotas |
| [Adjust leverage](https://docs.gearbox.finance/developers/manage-position#adjust-leverage) | Increasing leverage generally lowers HF; decreasing leverage generally raises it | Available swap or redemption paths; increasing leverage also requires borrowing and quota capacity | Slippage, price impact, and fees; deleveraging can require delayed settlement |
| [Deposit](https://docs.gearbox.finance/developers/manage-position#deposit) | Approximately preserves HF when keeping current leverage | Wallet funds; increases position size by adding collateral and borrowing more, requiring routes and available capacity | Slippage and fees can change HF; increases exposure, debt, and potentially quota costs |
| [Withdraw](https://docs.gearbox.finance/developers/manage-position#withdraw) | Approximately preserves HF for a proportional partial withdrawal | Decreases position net value by selling assets and repaying debt; requires an available withdrawal route | Slippage and fees; may trigger delayed operations, during which debt continues accruing costs |
| [Add collateral](https://docs.gearbox.finance/developers/manage-position#add-collateral) | Can increase HF at fixed debt; no increase if the added value is excluded or already capped by quota | The position's collateral token held in your wallet; sufficient quota for its value to count where required | Commits more wallet funds without increasing debt; a direct token transfer has no swap slippage, but any associated quota increase can add costs |
| [Withdraw collateral](https://docs.gearbox.finance/developers/manage-position#withdraw-collateral) | Lowers HF if it removes value counted for solvency; may leave HF unchanged while the remaining value still exceeds the quota cap | A directly withdrawable token and sufficient remaining collateral coverage | Returns tokens without reducing debt; reduces equity and generally increases leverage; a direct transfer has no swap slippage |
| [Increase quota](https://docs.gearbox.finance/developers/manage-position#update-quota) | Raises HF only while quota caps the token's LT-weighted value | Active quota market and available quota capacity | More quota increases quota interest expense and may incur a quota-increase fee; the applicable quota rate can also change over time |
| [Decrease quota](https://docs.gearbox.finance/developers/manage-position#update-quota) | Leaves HF unchanged until quota falls below the token's LT-weighted value; further reduction lowers HF | Remaining quota must provide sufficient collateral coverage | Reduces quota interest expense without changing balances or repaying debt |

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](https://github.com/Gearbox-protocol/sdk/blob/076de9c284c536c76eb3f93bc8284759acea539b/src/model/positions.ts)
- [Collateral valuation](https://github.com/Gearbox-protocol/sdk/blob/076de9c284c536c76eb3f93bc8284759acea539b/src/onchain/accounts/intents/collateral-valuation.ts)