Overview
Notional supports multiple collateral assets with different loan-to-value (LTV) ratios and risk parameters.
Supported Collateral
Risk parameters vary by asset based on historical volatility and market liquidity:
| Asset | Max LTV |
|---|
| BTC | 85% |
| ETH | 85% |
| HYPE | 75% |
| SOL | 75% |
| USDC | 100%* |
Collateral Structure
Each asset balance is tracked separately with four key fields: the asset identifier, total balance, hold amount (reserved for pending withdrawals), segregated balance (not available for borrowing), and last updated timestamp.
Balance Categories
Total Balance
- All funds owned by the account
- Includes available, hold, and segregated
Available Balance
- Calculated as total minus hold minus segregated
- Funds available for trading and margin
Hold
- Funds locked for pending withdrawals
- Released when withdrawal completes or fails
Segregated
- User-designated funds not used for margin
- Cannot be used for borrowing or margin
- Protected from liquidation
All user actions are governed by three fundamental formulas from the Notional whitepaper:
Account Balance
Account Balance represents the total value of all deposited assets at current market prices:
Balance = Σ (Asset_i × Price_i)
Example1 BTC at $40,000 + 10,000 USDC = $50,000 balance
Account Value
Account Value represents net equity after accounting for unrealized gains/losses:
Account Value = Balance + unrealizedPnL
Example$50,000 balance + $2,000 unrealized profit = $52,000 account value
max(0, margin requirements - available USDC).
Total Margin Value
Total Margin Value represents the effective collateral available for margin purposes:
Total Margin Value = Total Collateral + unrealizedPnL
where:
Total Collateral = Σ (Asset_i × Price_i × MaxLTV_i)
Example
- Collateral: 1 BTC at $40,000 (85% max LTV) + 10,000 USDC (100% max LTV)
- Total Collateral: (1 × $40,000 × 0.85) + (10,000 × $1 × 1.0) = $44,000
- With +$2,000 unrealized PnL: Total Margin Value = $46,000
Maintenance Margin Requirement (MMR)
Cross positions are liquidated when total collateral falls below the maintenance margin requirement:
MMR = Σ (|Size_i| × Price_i / (2 × MaxLeverage_i))
Example10 BTC-PERP long at $40,000 with 20x max leverage:MMR = |10| × $40,000 / (2 × 20) = $10,000
Initial Margin Requirement (IMR)
IMR is the minimum equity required to open a new position, stricter than MMR:
IMR = Σ (|Size_i| × Price_i / Leverage_i)
ExampleA 10 BTC-PERP position at 20x leverage requires $20,000 IMR.The MMR would be $10,000, exactly half of IMR at max leverage.
Cross Margin Ratio
Account health is measured by the Cross Margin Ratio:
Cross Margin Ratio = MMR / Total Margin Value
ExampleWith Total Margin Value of $46,000 and MMR of $10,000:
- Cross Margin Ratio = 0.217 (21.7%)
Interpretation: The ratio represents the percentage of effective collateral used for
maintenance margin. Lower ratios are healthier (less margin used). Liquidation Thresholds:
- Partial Liquidation:
Margin Ratio ≥ 1.0 (equity below maintenance margin)
- Full Liquidation:
Margin Ratio ≥ 1.5 (equity < 2/3 maintenance margin)
Deposit Flow
1. Transfer to Protocol
Transfer USDC to the protocol address using the ERC-20 transfer function. For example, 1000 USDC (6 decimals) = 1000000000.
2. Report Deposit
Submit a POST request to /exchange with action type “reportDeposit”, specifying the asset, amount, transaction hash, and exchange ID.
3. Event Emitted
A DepositDetected event is emitted containing the user address, asset ID, amount, transaction hash, and exchange ID.
4. Balance Updated
The total balance is incremented by the deposit amount while hold and segregated remain unchanged. For example, a 1000 USDC deposit increases total from 5000 to 6000.
Withdrawal Flow
1. Initiate Withdrawal
Submit a POST request to /exchange with action type “withdraw”, specifying the asset, amount, destination address, and source (balance or segregated).
2. Funds Placed on Hold
A WithdrawalInitiated event is emitted containing the withdrawal details. The balance is updated to move the withdrawal amount from available to hold. For example, a 500 USDC withdrawal increases hold from 0 to 500 while total remains at 6000.
3. Withdrawal Executed
A WithdrawalCompleted event is emitted with the transaction hash. The balance is updated to reduce total by the withdrawal amount and release the hold. For example, total decreases from 6000 to 5500 and hold returns to 0.
Borrowing Power
Available to Borrow
Available to borrow is calculated as account value minus maintenance margin minus current borrowed amount.
Example: With account value of $16,900, maintenance margin of $475, and current borrowed of
$5,000, the available to borrow is $11,425.
Maximum Position Size
Maximum position size is calculated as available to borrow times leverage divided by mark price.
Example: With $11,425 available at 5x leverage and BTC at $95,000, the maximum position size is
0.6 BTC.
Multi-Collateral Examples
BTC Collateral Only
With 1 BTC collateral at $40,000 and a 10 BTC-PERP long position at $40,000 (20x max leverage):
- Balance: $40,000
- Total Collateral: $34,000 (applying 85% LTV)
- Total Margin Value: $34,000 (no unrealized PnL)
- MMR: $10,000
- Cross Margin Ratio: 0.294 (29.4%) ✅ Healthy
BTC + USDC Collateral
With 1 BTC at $40,000 and 10,000 USDC collateral, same 10 BTC-PERP position:
- Balance: $50,000
- Total Collateral: $44,000 ($34,000 from BTC + $10,000 from USDC)
- Total Margin Value: $44,000
- MMR: $10,000
- Cross Margin Ratio: 0.227 (22.7%) ✅ Healthier
With Unrealized Loss
With 1 BTC collateral and 10 BTC-PERP position entered at $40,000, now marked at $38,000:
- Unrealized PnL: -$20,000
- Balance: $38,000 (BTC price also dropped)
- Total Collateral: $32,300 (applying 85% LTV to current price)
- Total Margin Value: $12,300 (including unrealized loss)
- MMR: $9,500
- Cross Margin Ratio: 0.772 (77.2%)
Still healthy but approaching danger zone (1.0 = liquidation)