# Pricing Mechanism

## HyperFun Pricing Mechanism

### Overview

HyperFun uses a **Bonding Curve** pricing model combined with **NAV (Net Asset Value)** to determine token prices. This creates a dynamic pricing system where:

* Price tracks the underlying vault value (NAV)
* Supply/demand affects price through the bonding curve
* Large trades have price impact (like Uniswap)

***

### Core Concepts

#### 1. NAV (Net Asset Value)

NAV represents the fair value of one vault token based on total assets.

```
NAV = (Total Assets + NAV Virtual) / (Total Supply + NAV Virtual)
```

**Total Assets** = EVM USDC + L1 Spot + L1 Perp Value - Pending Sells

**NAV Virtual** = Stabilizer that prevents extreme NAV when vault is small

* Minimum floor: 1000 tokens worth
* Scales with vault size through graduation tiers

***

#### 2. Bonding Curve Ratio

The bonding curve maintains a ratio that affects price relative to NAV.

```
BC Ratio = virtualBase / virtualTokens
```

| Ratio | Price vs NAV | Meaning                   |
| ----- | ------------ | ------------------------- |
| 1.0   | = NAV        | Fair value                |
| 1.5   | 1.5x NAV     | 50% premium (high demand) |
| 0.8   | 0.8x NAV     | 20% discount (low demand) |

***

### Price Formula

#### Spot Price

```
Price = NAV × (virtualBase / virtualTokens)
```

Or equivalently:

```
Price = NAV × BC_Ratio
```

#### Example

| Parameter     | Value                   |
| ------------- | ----------------------- |
| Total Assets  | $100,000                |
| Total Supply  | 100,000 tokens          |
| NAV           | $1.00                   |
| virtualBase   | 5,000,000               |
| virtualTokens | 4,500,000               |
| BC Ratio      | 1.111                   |
| **Price**     | **$1.11** (11% premium) |

***

### Constant Product AMM

HyperFun uses the same formula as Uniswap (x × y = k), but applied to bonding curve reserves.

#### Buy Formula

When user buys with USDC:

```solidity
// Convert virtualBase to USDC terms
virtualBaseUsdc = virtualBase × NAV

// Constant product: x × y = k
tokensOut = virtualTokens × usdcIn / (virtualBaseUsdc + usdcIn)
```

**Simplified:**

```
tokensOut = V_tokens × USDC_in / (V_base_usdc + USDC_in)
```

#### Sell Formula

When user sells tokens:

```solidity
// Convert virtualBase to USDC terms
virtualBaseUsdc = virtualBase × NAV

// Constant product: x × y = k
usdcOut = virtualBaseUsdc × tokensIn / (virtualTokens + tokensIn)
```

**Simplified:**

```
usdcOut = V_base_usdc × tokens_in / (V_tokens + tokens_in)
```

***

### Price Impact

#### Formula

```
Price Impact ≈ (1 + X/V)² - 1
```

Where:

* **X** = Trade amount (in USDC for buys, tokens for sells)
* **V** = Virtual reserve (virtualBaseUsdc for buys, virtualTokens for sells)

#### Price Impact Table

| Trade Size / Virtual Reserve | Price Impact |
| ---------------------------- | ------------ |
| 1%                           | \~2%         |
| 5%                           | \~10%        |
| 10%                          | \~21%        |
| 20%                          | \~44%        |
| 50%                          | \~125%       |

#### Example

Virtual Reserve = $5,000,000

| Buy Amount | Price Impact |
| ---------- | ------------ |
| $10,000    | 0.4%         |
| $50,000    | 2.0%         |
| $100,000   | 4.0%         |
| $500,000   | 21%          |

***

### Price Bounds

Prices are capped to prevent extreme deviations from NAV.

```solidity
maxPremiumBps  = 10000;  // Max premium 100% (up to 2x NAV)
maxDiscountBps = 5000;   // Max discount 50% (down to 0.5x NAV)
```

#### Bounded Price Range

```
Min Price = NAV × (1 - maxDiscountBps / 10000) = NAV × 0.5
Max Price = NAV × (1 + maxPremiumBps / 10000) = NAV × 2.0
```

| NAV   | Min Price | Max Price |
| ----- | --------- | --------- |
| $1.00 | $0.50     | $2.00     |
| $1.50 | $0.75     | $3.00     |
| $2.00 | $1.00     | $4.00     |

***

### Dynamic Virtual Reserves (Graduation Tiers)

Virtual reserves scale with vault size through **graduation tiers**.

#### Current Tier Settings

| Tier      | Threshold | BC Virtual | Effect                |
| --------- | --------- | ---------- | --------------------- |
| Seed      | $100K     | 500K-2M    | High price protection |
| Growth    | $1M       | 5M-10M     | Moderate protection   |
| Mature    | $10M      | 10M-20M    | Low protection        |
| Graduated | $100M     | 100M       | Near-linear pricing   |

#### Why Dynamic Reserves?

| Vault Size     | BC Virtual | $10K Buy Impact |
| -------------- | ---------- | --------------- |
| Small ($10K)   | 500K       | 4%              |
| Medium ($100K) | 2M         | 1%              |
| Large ($1M)    | 10M        | 0.2%            |

Small vaults have more price protection (higher impact) to prevent manipulation.

***

### Squared Effect Decay

The bonding curve effect transitions from **squared** (high protection) to **linear** (tracks NAV) as the vault grows.

```solidity
// squaredRatioBps controls the blend
effVirtualTokens = (squaredPart × squaredWeight + linearPart × (1 - squaredWeight))
```

| Tier      | squaredRatioBps | Effect                |
| --------- | --------------- | --------------------- |
| Seed      | 90% (9000)      | Strong BC effect      |
| Growth    | 60% (6000)      | Moderate BC effect    |
| Mature    | 15% (1500)      | Weak BC effect        |
| Graduated | 2% (200)        | Nearly linear (≈ NAV) |

***

### BC Ratio Limits

#### Maximum Ratio (Cap)

Prevents price from going too high above NAV.

```solidity
maxBcRatioBps = 18000;  // 1.8x (180%)

if (currentRatio > maxBcRatioBps) {
    virtualTokens = virtualBase × BPS / maxBcRatioBps;
}
```

#### Minimum Ratio (Floor)

Prevents price from going below NAV.

```solidity
minBcRatioBps = 10000;  // 1.0x (100%)

if (currentRatio < BPS) {
    virtualTokens = virtualBase;  // Force ratio = 1.0
}
```

***

### TWAP NAV (Time-Weighted Average)

To prevent price manipulation from sudden liquidations or large trades, NAV uses a **smoothed (TWAP) value**.

```solidity
twapMaxChangePerMin = 500;  // Max 5% change per minute

// NAV can only change by twapMaxChangePerMin per minute
smoothedNAV = previousNAV ± (maxChangePerMin × minutesElapsed)
```

This protects users from:

* Flash liquidation spikes
* Price manipulation attacks
* Sandwich attacks

***

### Fee Structure

#### Trading Fee

```solidity
tradingFeeBps = 100;  // 1%

// On buy
netAmount = usdcAmount × (1 - tradingFeeBps / 10000)
tokensOut = calculateTokensOut(netAmount)

// On sell
grossUsdc = calculateUsdcOut(tokens)
tradingFee = grossUsdc × tradingFeeBps / 10000
netUsdc = grossUsdc - tradingFee
```

#### Exit Fee (Time-Based)

Encourages long-term holding.

| Days Held | Exit Fee |
| --------- | -------- |
| < 1 day   | 3%       |
| 1-3 days  | 2%       |
| 3-7 days  | 1%       |
| 7-30 days | 0.5%     |
| > 30 days | 0%       |

***

### View Functions

#### Get Current Prices

```solidity
// Current buy/sell price
function getBuyPrice() returns (uint256)   // 18 decimals
function getSellPrice() returns (uint256)  // 18 decimals

// Sell price capped by available liquidity
function getSellPriceCapped() returns (uint256)
```

#### Preview Trades

```solidity
// Preview buy
function calculateTokensOut(uint256 usdcIn) returns (
    uint256 tokensOut,
    uint256 newPrice,
    uint256 priceImpactBps
)

// Preview sell
function calculateUsdcOut(uint256 tokensIn) returns (
    uint256 usdcOut,
    uint256 newPrice,
    uint256 priceImpactBps
)
```

#### Get Reserves

```solidity
// Raw reserves (stored ratio)
function virtualBase() returns (uint256)
function virtualTokens() returns (uint256)

// Effective reserves (scaled by vault size)
function getEffectiveVirtualBase() returns (uint256)
function getEffectiveVirtualTokens() returns (uint256)
```

#### Get NAV

```solidity
function getNAV() returns (uint256)          // Current NAV
function getSmoothedNAV() returns (uint256)  // TWAP smoothed NAV
function getTotalAssets() returns (uint256)  // Total vault assets
```

***

### Example: Complete Buy Flow

```javascript
const { ethers } = require("ethers");

// 1. Get current state
const nav = await token.getNAV();
const buyPrice = await token.getBuyPrice();
const bcRatio = await token.virtualBase() / await token.virtualTokens();

console.log("NAV:", ethers.formatEther(nav));
console.log("Buy Price:", ethers.formatEther(buyPrice));
console.log("BC Ratio:", bcRatio.toFixed(4));

// 2. Preview trade
const usdcIn = ethers.parseUnits("1000", 6);  // $1000
const [tokensOut, newPrice, impactBps] = await token.calculateTokensOut(usdcIn);

console.log("Tokens Out:", ethers.formatEther(tokensOut));
console.log("Price Impact:", impactBps / 100, "%");

// 3. Execute with slippage protection
const minTokens = tokensOut * 99n / 100n;  // 1% slippage
await usdc.approve(token.address, usdcIn);
await token.buy(usdcIn, minTokens);
```

***

### Example: Complete Sell Flow

```javascript
// 1. Check available liquidity
const availableLiq = await token.getAvailableLiquidity();
console.log("Available Liquidity:", availableLiq / 1e6, "USDC");

// 2. Preview sell
const tokensToSell = ethers.parseEther("100");
const [usdcOut, newPrice, impactBps] = await token.calculateUsdcOut(tokensToSell);

console.log("USDC Out:", usdcOut / 1e6, "USDC");
console.log("Price Impact:", impactBps / 100, "%");

// 3. Check exit fee
const [exitFeeBps, daysHeld] = await token.calculateExitFee(userAddress);
console.log("Exit Fee:", exitFeeBps / 100, "%");
console.log("Days Held:", daysHeld);

// 4. Execute with slippage protection
const minUsdc = usdcOut * 99n / 100n;
await token.sell(tokensToSell, minUsdc);
```

***

### Summary

| Component    | Description                      |
| ------------ | -------------------------------- |
| **NAV**      | Fair value based on total assets |
| **BC Ratio** | Supply/demand multiplier         |
| **Price**    | NAV × BC Ratio                   |
| **AMM**      | Constant product (x × y = k)     |
| **Impact**   | ≈ (1 + X/V)² - 1                 |
| **Bounds**   | 0.5x to 2x NAV                   |
| **Tiers**    | Dynamic reserves by vault size   |
| **TWAP**     | Smoothed NAV for protection      |

***

### Contract Version

Current: **V44**


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://hyper-fun.gitbook.io/hypers.fun/how-it-works/pricing-mechanism.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.