Concepts

Use this page as a reference while reading the integration guides. Unless stated otherwise, amounts are stored as integer token base units and protocol parameters must be read from current on-chain accounts.

nUSD

nUSD is Nest's dollar-denominated token. It uses six decimals, so one nUSD is represented on-chain as 1_000_000 base units.

Users can obtain nUSD in two ways:

• Deposit supported collateral and mint nUSD as debt.
• Convert USDC into nUSD through the Peg Stability Module.

These operations have different accounting. Minting creates debt that must be repaid. PSM conversion does not create a debt position.

Collateral

Collateral is a supported token deposited into Nest to secure nUSD debt. Each collateral market has its own mint, token program, decimals, custody account, oracle configuration, LTV limits, and debt caps.

A borrow position is specific to one wallet and one collateral configuration:

owner wallet + collateral configuration = borrow vault PDA

Collateral from separate positions is not combined. A position backed by SPYx, for example, does not use collateral deposited into a QQQx position.

See Deposit collateral.

Principal debt

Principal debt is the amount of nUSD minted from a collateral position. Minting 700 nUSD increases that position's principalDebt by 700_000_000 base units.

Receiving nUSD from another wallet or from the PSM does not create principal debt. Debt only changes through the Nest borrowing instructions.

Accrued fee

The accrued fee is the unpaid stability fee recorded for a borrow position. Total debt is:

total debt = principal debt + accrued fee

Repayments are applied to the accrued fee first and principal second.

Stability fee

The stability fee is the interest charged on outstanding borrow debt. The APR is stored in the on-chain Protocol account as basis points and should not be hardcoded by integrations.

pending fee =
  stored total debt × APR bps × elapsed seconds
  / (10,000 × 31,536,000)

The calculation uses principalDebt + accruedFee, so previously checkpointed fees are included in subsequent calculations. Nest records the pending fee when a user mints, repays, withdraws collateral, explicitly accrues the fee, or when a liquidation begins.

Between transactions, an application projects the pending fee from lastAccrualTs. The transaction recalculates it using Solana's on-chain clock.

See Calculate accrued stability fees.

Loan-to-value ratio

Loan-to-value ratio, or LTV, compares debt with the conservative USD value of the deposited collateral:

LTV = total debt / conservative collateral value

If a position has $700 of debt and $1,000 of conservative collateral value, its LTV is 70%.

LTV rises when debt or accrued fees increase. It also rises when collateral value decreases.

Borrow LTV

The borrow LTV is the maximum LTV allowed after minting nUSD or withdrawing collateral. It limits actions that would increase the risk of a position.

For a market with a 70% borrow LTV and $1,000 of conservative collateral value:

maximum total debt = $1,000 × 70% = $700

If an existing position is already above the borrow LTV, the user cannot mint more nUSD or withdraw collateral. The user can still repay debt or add collateral.

Liquidation threshold

The liquidation threshold is the LTV at which a position becomes eligible for liquidation. It is higher than the borrow LTV to provide a buffer for price changes and accrued fees.

For $700 of debt and an 80% liquidation threshold:

liquidation collateral value = $700 / 80% = $875

The position is within its borrow limit at $1,000 of collateral value. It becomes liquidatable when the conservative collateral value falls to $875, assuming the debt remains $700.

Read both values from the current CollateralConfig account. Different markets can use different limits.

See Calculate position health.

Health factor

Health factor compares the position's liquidation-adjusted collateral value with its total debt:

health factor =
  conservative collateral value × liquidation threshold / total debt

A health factor above 1.0 means the position is above the liquidation boundary. A health factor below 1.0 means it is eligible for liquidation. Nest examples represent the value in basis points, where 10_000 equals 1.0.

Peg Stability Module

The Peg Stability Module, or PSM, converts between USDC and nUSD without opening a collateralized borrow position:

USDC -> nUSD
nUSD -> USDC

Both tokens use six decimals. Current mainnet PSM instructions exchange equal raw amounts and require the on-chain swap-fee fields to be zero. Swap-in is limited by the PSM cap. Swap-out is limited by available idle USDC, protocol bad debt, and the rolling outflow circuit breaker.

PSM conversion does not repay an existing borrow position. Repayment requires the explicit repay_nusd instruction.

See Convert USDC and nUSD.

snUSD

snUSD is the share token for the Nest staking pool. It uses six decimals but is not permanently equal to one nUSD and does not rebase in a wallet.

The wallet's snUSD balance remains constant until shares are transferred, staked, burned, or restored. Its nUSD value changes as the pool's accounted assets change.

snUSD share accounting

Staking converts nUSD assets into snUSD shares. The share calculation depends on current pool assets and total shares:

snUSD received = nUSD deposited × total shares / entry assets

The current nUSD claim value is:

nUSD value = snUSD shares × redeemable assets / total shares

If no shares exist, the initial stake starts at a 1:1 raw-unit rate, subject to the program's initial-stake requirements. Later deposits must set minSharesOut to protect the user from a rate change before execution.

Unstaking is asynchronous. request_unstake burns the shares and creates a pending withdrawal. After the on-chain cooldown, complete_unstake calculates the final nUSD amount. The value is not fixed when the request is created.

See Stake nUSD.

Oracle price

Nest uses an oracle price to calculate collateral value. Prices use eight decimals:

$100.25 = 10_025_000_000 priceE8

The public batch endpoint returns the current prices for every configured market:

GET https://api.nestusd.com/api/prices

The API response is useful for UI quotes. Minting and debt-bearing withdrawals also require a signed oracle-update payload that the program verifies in the same transaction.

Oracle confidence

Oracle confidence represents uncertainty around the reported price. Nest uses a conservative price for borrowing and liquidation calculations:

safePriceE8 = priceE8 - confidenceE8

For a $100 price and $0.20 confidence interval, Nest values the token at $99.80. The program also checks that confidence does not exceed the market's configured maximum and that the price is recent enough.

An integration must validate symbol, provider, feed identity, freshness, confidence, and signed proof. It must not use a display price from one market to construct a transaction for another market.

See Atomic oracle transactions.

Basis points

Nest stores percentage parameters as basis points:

100 basis points = 1%
600 basis points = 6%
7,000 basis points = 70%
10,000 basis points = 100%

Use integer arithmetic for basis-point calculations. Convert the result into a formatted percentage only for display.

Base units and decimals

Solana token accounts store integers rather than decimal token values. nUSD, snUSD, and USDC use six decimals:

1.25 tokens = 1_250_000 base units

Collateral decimals vary by mint. Read collateralDecimals from the selected market rather than assuming a global value. Use bigint or Anchor BN for all amounts, prices, timestamps, shares, debt, and basis points.