User Position Conditions

Learn how user position conditions work in Aave v4.

User positions track two risk conditions: Dynamic Risk Configuration and User Risk Premium.

Dynamic Risk Configuration, or Dynamic Config for short, snapshots the per-reserve collateral parameters—Collateral Factor, Max Liquidation Bonus, and Protocol Fee—active when the position first became risk-bearing, i.e. when the user initially borrowed against collateral.

It updates when the user performs risk-increasing actions: borrowing, withdrawing collateral, or disabling collateral (updates all reserves' snapshots), or enabling collateral (updates only that reserve's snapshot). It can also be updated manually, and always refreshes the User Risk Premium.

The Dynamic Config values used on first borrow or after an update—implicit or explicit—are exposed on the Reserve object under the settings field:

const reserve: Reserve = {  __typename: "Reserve",  id: "SGVsbG8h",  settings: {    __typename: "ReserveSettings",    collateralFactor: {      normalized: BigDecimal(80), // 90%      // …    },    maxLiquidationBonus: {      normalized: BigDecimal(10), // 10%      // …    },    // protocol fee    liquidationFee: {      normalized: BigDecimal(1), // 1%      // …    },    // …    latestDynamicConfigKey: "1234567890",  },  // …};

The snapshotted values are exposed under the Reserve's userState field: the Collateral Factor applies to reserves linked by UserSupplyItem when used as collateral, while the Max Liquidation Bonus and Protocol Fee apply to reserves linked by UserBorrowItem.

const borrowItem: UserBorrowItem = {  __typename: "UserBorrowItem",  id: "aGVsbG8=",  reserve: {    __typename: "Reserve",    id: "SGVsbG8h",    userState: {      __typename: "ReserveUserState",      maxLiquidationBonus: {        normalized: BigDecimal(10), // 10%        // …      },      // protocol fee      liquidationFee: {        normalized: BigDecimal(1), // 1%        // …      },      // …      dynamicConfigKey: "1234567889",    },    // …  },  // …};

User Risk Premium reflects the current risk profile of the collateral assets. In practice, it acts as a multiplier—a percentage applied on top of each reserve's base borrow rate. Lower is better.

It updates when the user performs actions that affect collateralization (borrowing, withdrawing collateral, enabling or disabling collateral), when the Dynamic Risk Configuration changes, or when explicitly triggered.

You can keep track of the User Risk Premium for a position by checking the riskPremium.current field in the User Position response.

const userPosition: UserPosition = {  __typename: "UserPosition",  id: "aGVsbG8",  user: "0x456…",  riskPremium: {    current: {      normalized: BigDecimal(50), // 50%      // …    },    latest: {      normalized: BigDecimal(50), // 50% - same as current      // …    },    breakdown: [      // …    ],  },  spoke: {    id: "SGVsbG8h",    address: "0x123…",    chain: {      chainId: 1,      name: "Ethereum",      // …    },    // …  },  // …};

The riskPremium.breakdown field contains the User Risk Premium Breakdown for the user position collaterals.

The User Risk Premium Breakdown shows each collateral asset in a user position, including what percentage of total collateral it represents and its weight in the overall User Risk Premium.

const breakdown: UserRiskPremiumBreakdownItem[] = [  {    __typename: "UserRiskPremiumBreakdownItem",    token: {      __typename: "Erc20Token",      id: "aGVsbG8",      address: "0x456…",      name: "USDC",      symbol: "USDC",      decimals: 6,    },    currentRiskPremiumWeight: {      __typename: "PercentNumber",      normalized: BigDecimal(50), // 50%      // …    },    latestRiskPremiumWeight: {      __typename: "PercentNumber",      normalized: BigDecimal(45), // 45%      // …    },    collateral: {      __typename: "PercentNumber",      normalized: BigDecimal(30), // 30%      // …    },  },  // …];

Where:

As mentioned above, the breakdown is available in the riskPremium.breakdown field of user positions, or you can use the standalone query explained below.

import {  type UserRiskPremiumBreakdownRequest,  useUserRiskPremiumBreakdown,} from "@aave/react";
function UserRiskPremiumBreakdown({  request,}: {  request: UserRiskPremiumBreakdownRequest;}) {  const { data, loading, error } = useUserRiskPremiumBreakdown(request);
  if (loading) return <div>Loading…</div>;
  if (error) return <div>Error: {error.message}</div>;
  return (    <div>      {data.map((item) => (        <div key={item.token.address}>          <p>{item.token.symbol}</p>          <p>            Current Weight:{" "}            {item.currentRiskPremiumWeight.normalized.toFixed(2)}%          </p>          <p>            Latest Weight: {item.latestRiskPremiumWeight.normalized.toFixed(2)}%          </p>          <p>Collateral: {item.collateral.normalized.toFixed(2)}%</p>        </div>      ))}    </div>  );}

const request: UserRiskPremiumBreakdownRequest = {  user: evmAddress("0x742d35cc…"),  query: {    userPositionId: userPositionId(params.id), // UserPositionId - typically from URL params  },};

As protocol configurations evolve through governance votes, a user position’s conditions may improve.

Updating user position conditions can be broken down into the following steps:

You can identify positions that qualify for updates by checking if the riskPremium.latest is lower than riskPremium.current (indicating a better risk premium is available) or the canUpdateDynamicConfig field (true when dynamic config can be updated) in the user's positions.

const userPosition: UserPosition = {  __typename: "UserPosition",  id: "aGVsbG8",  user: "0x456…",  riskPremium: {    current: {      normalized: BigDecimal(50), // 50%      // …    },    latest: {      normalized: BigDecimal(25), // 25% - lower is better      // …    },    breakdown: [      // …    ],  },  spoke: {    id: "SGVsbG8h",    address: "0x123…",    chain: {      chainId: 1,      name: "Ethereum",      // …    },    // …  },  canUpdateDynamicConfig: true,  // …};

Preview the impact of updating the user position conditions before committing to it.

import {  type UpdateUserPositionConditionsRequest,  usePreview,} from "@aave/react";
function UserPositionConditionsPreview({  request,}: {  request: UpdateUserPositionConditionsRequest;}) {  const { data, error, loading } = usePreview({    action: {      updateUserPositionConditions: request,    },  });
  if (loading) return <div>Loading…</div>;  if (error) return <div>Error: {error.message}</div>;
  // data: PreviewUserPosition  return (    <div>      <h3>Health Factor:</h3>      <p>From: {data.healthFactor.current?.value.toFixed(2) ?? "N/A"}</p>      <p>To: {data.healthFactor.after?.value.toFixed(2) ?? "N/A"}</p>
      <h3>User Risk Premium:</h3>      <p>From: {data.riskPremium.current.normalized.toFixed(2)}%</p>      <p>To: {data.riskPremium.after.normalized.toFixed(2)}%</p>
      <h3>Borrowing Power:</h3>      <p>From: {data.borrowingPower.current.value.toDisplayString(2)}</p>      <p>To: {data.borrowingPower.after.value.toDisplayString(2)}</p>    </div>  );}

const request: UpdateUserPositionConditionsRequest = {  userPositionId: userPosition.id,  update: UserPositionConditionsUpdate.JustRiskPremium,};

Now that we know how to identify the user positions that qualify for an update, and we know how to preview the impact of updating the user position conditions, let's see how to update the user position conditions.

import { useWalletClient } from "wagmi";import { useSendTransaction } from "@aave/react/viem";
// …
const { data: wallet } = useWalletClient();const [sendTransaction] = useSendTransaction(wallet);

import { useUpdateUserPositionConditions } from "@aave/react";
const [updateConditions, { loading, error }] = useUpdateUserPositionConditions(  (transaction) => sendTransaction(transaction));

import { UserPositionConditionsUpdate, type UserPosition } from "@aave/react";
const execute = async (userPosition: UserPosition) => {  const result = await updateConditions({    userPositionId: userPosition.id,    update: UserPositionConditionsUpdate.JustRiskPremium,  });};

const execute = async () => {  const result = await updateConditions(/* … */);
  if (result.isErr()) {    switch (result.error.name) {      case "CancelError":        // The user cancelled the operation        return;
      case "SigningError":        console.error(          `Failed to sign the transaction: ${result.error.message}`        );        break;
      case "TimeoutError":        console.error(`Transaction timed out: ${result.error.message}`);        break;
      case "TransactionError":        console.error(`Transaction failed: ${result.error.message}`);        break;
      case "UnexpectedError":        console.error(result.error.message);        break;    }    return;  }
  console.log(    "Position conditions updated successfully with hash:",    result.value  );};

Estimate the network cost of any action using the same PreviewAction you pass to the usePreview hook.

Let's consider the following example:

import { type PreviewAction, UserPositionConditionsUpdate } from "@aave/react";
const action: PreviewAction = {  updateUserPositionConditions: {    userPositionId: userPosition.id, // from UserPosition    update: UserPositionConditionsUpdate.AllDynamicConfig,  },};

Use the useNetworkFee hook to estimate both the network fee for the provided action and its fiat equivalent.

import { type PreviewAction, Currency } from "@aave/react";import { useNetworkFee } from "@aave/react/viem";
function NetworkFee({ action }: { action: PreviewAction }) {  const {    data: fee,    loading,    error,  } = useNetworkFee({    query: { estimate: action },    currency: Currency.Eur,  });
  if (loading) return <p>Loading fee…</p>;  if (error) return <p>Error: {error.message}</p>;
  return (    <p>      Network Fee: {fee.amount.value.toDisplayString(2)} {fee.token.info.symbol}      <span>        ≈{fee.exchange.symbol}        {fee.exchange.value.toDisplayString(2)}      </span>    </p>  );}