Skip to main content

Cover Buyer User Flow

Overview​

Buying cover on Nexus Mutual allows users to protect against specific risks (such as smart contract failures or stablecoin depegging).
Before purchasing a cover, it is important to understand how pricing works, membership requirements, and the claim process.

Key Concepts​

Cover Length & Grace Period​

  • Cover Length – The active period during which the cover provides protection.
    • Minimum Cover Length: 28 days.
    • Maximum Cover Length: 365 days.
  • Grace Period – The additional time after cover expiration during which claims can still be submitted.
  • Key Rule: If the grace period expires, you can no longer submit a claim.

To check the grace period of a product:

uint gracePeriod = CoverProducts.getProductGracePeriod(productId);

Cover Pricing & Dynamic Adjustments​

Cover pricing follows a dynamic adjustment mechanism:

Initial Price Ratio​

  • Each product has a base price, which is the starting cost for cover.

Target Price​

  • The target price is the reference price that a cover aims to revert toward when no new purchases are made.
  • How is it determined?
    • Each product has a pre-set target price defined at creation.
    • This does not change dynamically but is influenced by utilization and time.
  • Why does the price decay toward the target price?
    • When demand decreases (no new covers purchased), the price naturally reduces back to the target price via price decay.
  • How does it interact with price bumps?
    • Price bumps push the price above the target price when utilization is high.
    • Price decay pulls it back toward the target price when utilization drops.

Price Bump​

  • When utilization increases, the cover price increases per purchase.
  • Bump Rate: The price increases by 2% per purchase, compounded on the previous price.
  • Upper Limit: The price cannot exceed the max allowed price per product.

To check the max allowed price of a product:

uint maxPrice = CoverProducts.getProductMaxPrice(productId);

Price Decay​

  • If no new purchases occur, the price decays daily back toward the target price.

  • Decay Rate: Price reduces by 0.1% per day, applied as:

    $$ \text{New Price} = \text{Current Price} \times 0.999 $$

  • Lower Limit: Price cannot go below the product’s initial price ratio.

To check the minimum price of a product:

uint minPrice = CoverProducts.getProductMinPrice(productId);

How to Check Current Cover Pricing:​

To check the current price of a product in a pool:

uint currentPrice = CoverProducts.getProductPrice(poolId, productId);

To check the minimum price of a product:

uint minPrice = CoverProducts.getProductMinPrice(productId);

To calculate the premium per annum, use:

$$ \text{Annual Premium} = \text{Cover Price} \times \left(\frac{365}{\text{Cover Length (days)}}\right) $$

Cover Router API & Cover Buy Process​

The Cover Router API simplifies cover purchases by finding the best-priced cover automatically.

Why Use the Cover Router API?​

The Cover Router facilitates the process of buying cover by finding the best-priced pools for a given cover request. After obtaining the pool allocation, you will need to call the Cover.buyCover function to complete the purchase.

When calling the `/quote` API, it:

  1. Identifies available staking pools providing cover for the selected product.
  2. Calculates how much capacity each pool should provide.
  3. Returns a price quote and a breakdown of pool allocations.

Cover Router API Reference:
`/quote` API Docs

Accepted Payment Assets​

The available denominations for cover payment depend on the product.

To check which assets are accepted, call:

(uint productId, string memory productName, uint[] memory acceptedAssets) = CoverProducts.getProduct(productId);

Common asset IDs:

AssetID
NXM255
ETH0
USDC6
cBTC7

Membership Requirement​

  • You must be a Nexus Mutual member before purchasing cover or making a claim.
  • If you are not a member, cover purchase and claim transactions will fail.

To check if an address is a member:

bool isMember = MemberRoles.checkRole(memberAddress, uint8(Role.Member));

Step-by-Step Process​

Cover Purchase Summary​

  1. Call Cover Router `/quote` API – Fetch price & pool allocations for the requested cover.
  2. Verify pricing & pool allocations – Ensure the computed allocation is correct.
  3. Call `Cover.buyCover()` – Pass the `poolAllocationRequests` from `/quote` API.
  4. Verify the cover purchase – Check for success via Cover NFT & emitted events.

How to Get a Quote​

To get a cover quote, call the Cover Router `/quote` API.

Example curl Command:​

curl -X GET "https://api.nexusmutual.io/v2/quote" \
 -H "Content-Type: application/json" \
 -d '{
"productId": 1,
"coverAmount": 100000,
"coverDuration": 90,
"paymentAsset": 6
}'

Expected API Response:​

{
  "premium": 1500,
  "poolAllocationRequests": [
    { "poolId": 3, "allocatedAmount": 50000 },
    { "poolId": 5, "allocatedAmount": 50000 }
  ]
}

How to Buy Cover​

  1. Use the `/quote` API to fetch `poolAllocationRequests`.
  2. Call `Cover.buyCover()` with the following parameters:
Cover.buyCover(
    BuyCoverParams memory params,
    PoolAllocationRequest[] memory poolAllocationRequests
);

Structs Used in Cover.buyCover()​

BuyCoverParams

ParameterDescription
coverIdExisting cover ID (if extending) or 0 for a new cover.
ownerAddress of the cover buyer.
productIdProduct being covered (must be a valid productId).
coverAssetAsset being covered (e.g., USDC, ETH).
amountCover amount in coverAsset units.
periodCover duration in days.
maxPremiumInAssetMax premium the buyer is willing to pay.
paymentAssetAsset used for payment (e.g., NXM, USDC, ETH).
commissionRatioCommission percentage (if using an affiliate).
commissionDestinationAffiliate address (if applicable).
ipfsDataMetadata stored on IPFS.

PoolAllocationRequest

ParameterDescription
poolIdPool providing cover capacity.
skipWhether to skip this pool allocation (true/false).
coverAmountInAssetAmount allocated from this pool (in coverAsset units).

How to Verify Cover Purchase Success​

A successful cover purchase results in a Cover NFT.

To verify purchase success:

  • Monitor the CoverEdited event:
event CoverEdited(
    uint indexed coverId,
    uint indexed productId,
    uint indexed segmentId,
    address buyer,
    string ipfsMetadata
);
  • Retrieve your Cover NFT ID:
uint coverId = CoverViewer.getLatestCoverId(buyerAddress);

You can check cover details via:

Cover.getCover(coverId);

How to Check Cover Expiration & Claim Eligibility​

  • Use the Cover NFT to check the cover expiration date.
  • Retrieve cover details via:
CoverViewer.getCoverDetails(coverId);

What getCoverDetails Returns​

ParameterDescription
coverIdUnique ID of the cover.
productIdProduct ID this cover is protecting.
ownerAddress of the cover holder.
amountCover amount in the selected asset.
coverAssetAsset type for the cover (USDC, ETH).
periodCover duration in days.
startTimeTimestamp when the cover started.
expiryTimeTimestamp when the cover expires.
premiumPaidTotal premium paid for the cover.
statusCover status (Active, Expired, Claimed).

How to Submit a Claim​

  1. Ensure the cover is active or within the grace period.
  2. Call `IndividualClaims.submitClaim()` with the cover ID and deposit.
IndividualClaims.submitClaim(uint coverId);
  • Claim Payout: 100% of the cover amount. No deductibles.

Claim Review Process​

  • Claims are reviewed by claim assessors who evaluate validity based on cover conditions.
  • Review Duration: Typically 7 days, but can vary depending on complexity.
  • If a claim is approved, payout = 100% of cover amount (no deductibles).
  • If a claim is rejected, the claim deposit is lost.
  • Appeal Process:
    • If rejected, claimants cannot appeal directly, but can resubmit a claim with additional evidence.
    • Repeated false claims may result in membership penalties.

Frequently Asked Questions (FAQ)​

How do I know when my cover expires?​

  • Your Cover NFT includes the expiry date.
  • You can also call:
uint expiryDate = CoverViewer.getCoverExpiration(coverId);

What happens if I am not a member?​

  • You must be a member to buy cover and submit claims.
  • Check membership status:
bool isMember = MemberRoles.checkMembership(address buyer);

How much is the claim payout?​

  • 100% of the cover amount.
  • No deductibles.

How Long is the Grace Period?​

  • Each product has a different grace period, which determines how long after expiration a claim can still be submitted.
  • Can the Grace Period Change?
    • No. Once a cover is purchased, the grace period remains fixed for that cover.
    • However, future purchases of the same product may have a different grace period if the product owner updates it.

Retrieve the grace period for a product using:

uint gracePeriod = CoverProducsts.getGracePeriod(productId);

What happens if my claim is rejected?​

  • You lose the claim deposit.
  • It is distributed to claim assessors as rewards.

What happens if I try to buy cover without being a member?​

  • Your transaction will fail.
  • You must become a Nexus Mutual member first.

Best Practices​

  • ✅ Always verify pricing before purchasing cover.
  • ⚠️ Submit claims within the grace period or you will lose eligibility.
  • ✅ Ensure you are a Nexus Mutual member before purchasing cover.
  • ⚠️ Monitor pool utilization and pricing changes before buying cover.