> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/mezo-org/documentation/llms.txt
> Use this file to discover all available pages before exploring further.

# MUSD Redemptions

> Step-by-step guide for redeeming MUSD tokens for BTC through smart contract integration

Redeeming lets you burn 1 MUSD to receive \$1 in BTC (minus a 0.75% redemption fee and gas fees). The system redeems starting from the trove with the lowest collateral ratio above 110%.

<Note>
  If the amount of MUSD exceeds a single trove, it will continue to redeem in ascending order of collateralization ratio. Troves with collateralization ratios below 110% are eligible for liquidation, and cannot be redeemed against.
</Note>

## Prerequisites

Before you start, verify:

<Steps>
  <Step title="Check System Status">
    Go to TroveManager → "Read as Proxy" → call `getTCR()` with current BTC price. Must show ≥ `1100000000000000000` (110%)
  </Step>

  <Step title="Verify MUSD Balance">
    Check your balance on the MUSD token contract
  </Step>

  <Step title="Get BTC Price">
    Go to PriceFeed → "Read as Proxy" → call `fetchPrice()`
  </Step>

  <Step title="Get Contract Addresses">
    See contract addresses at the bottom for both Mainnet and Testnet
  </Step>
</Steps>

## Redemption Methods

### Option A: Quick & Simple (Higher Gas)

Use this if you want to redeem quickly without calculating hints.

<Steps>
  <Step title="Go to TroveManager Contract">
    Open the TroveManager contract in your block explorer and click the **"Write as Proxy"** tab.
  </Step>

  <Step title="Find Function 11: redeemCollateral">
    You'll see 6 input fields. Fill them as follows:
  </Step>
</Steps>

<ParamField path="_amount" type="uint256" required>
  Your amount in wei (see conversion below)
</ParamField>

<ParamField path="_firstRedemptionHint" type="address" required>
  `0x0000000000000000000000000000000000000000`
</ParamField>

<ParamField path="_upperPartialRedemptionHint" type="address" required>
  Your wallet address
</ParamField>

<ParamField path="_lowerPartialRedemptionHint" type="address" required>
  Your wallet address
</ParamField>

<ParamField path="_partialRedemptionHintNICR" type="uint256" required>
  `1100000000000000000000`
</ParamField>

<ParamField path="_maxIterations" type="uint256" required>
  `0`
</ParamField>

#### Converting MUSD to Wei

<CodeGroup>
  ```javascript JavaScript theme={null}
  // Formula: Your amount × 1e18
  const musdAmount = 100;
  const weiAmount = musdAmount * 1e18;
  // Result: 100000000000000000000
  ```

  ```python Python theme={null}
  # Formula: Your amount × 10^18
  musd_amount = 100
  wei_amount = musd_amount * (10 ** 18)
  # Result: 100000000000000000000
  ```

  ```bash Examples theme={null}
  # 100 MUSD = 100000000000000000000
  # 5,005 MUSD = 5005000000000000000000
  ```
</CodeGroup>

### Option B: With Hints (Lower Gas)

Use this to save on gas costs by providing optimal hints.

<Steps>
  <Step title="Get Redemption Hints">
    Go to HintHelpers → "Read as Proxy" → `getRedemptionHints()`

    Fill in:

    * `_amount`: Your amount in wei
    * `_price`: Current BTC price from PriceFeed
    * `_maxIterations`: 50

    Copy the returned values:

    * `firstRedemptionHint`
    * `partialRedemptionHintNICR`
  </Step>

  <Step title="Get Position Hints">
    Go to SortedTroves → "Read as Proxy" → `findInsertPosition()`

    Fill in:

    * `_NICR`: Use the `partialRedemptionHintNICR` from Step 1
    * `_prevId`: Your wallet address
    * `_nextId`: Your wallet address

    Copy the returned values:

    * `upperHint`
    * `lowerHint`
  </Step>

  <Step title="Call redeemCollateral">
    Go back to TroveManager → "Write as Proxy" → `redeemCollateral`

    * `_amount`: Your amount in wei
    * `_firstRedemptionHint`: from Step 1
    * `_upperPartialRedemptionHint`: upperHint from Step 2
    * `_lowerPartialRedemptionHint`: lowerHint from Step 2
    * `_partialRedemptionHintNICR`: from Step 1
    * `_maxIterations`: 50
  </Step>
</Steps>

## Smart Contract Integration

### TypeScript Example

<CodeGroup>
  ```typescript With Hints theme={null}
  import { ethers } from 'ethers';

  async function redeemMUSDWithHints(
    contracts: {
      troveManager: Contract,
      hintHelpers: Contract,
      sortedTroves: Contract,
      priceFeed: Contract
    },
    wallet: Wallet,
    musdAmount: bigint
  ) {
    // Get current BTC price
    const price = await contracts.priceFeed.fetchPrice();
    
    // Get redemption hints
    const { 
      firstRedemptionHint,
      partialRedemptionHintNICR 
    } = await contracts.hintHelpers.getRedemptionHints(
      musdAmount,
      price,
      50 // maxIterations
    );
    
    // Get position hints
    const { upperHint, lowerHint } = 
      await contracts.sortedTroves.findInsertPosition(
        partialRedemptionHintNICR,
        wallet.address,
        wallet.address
      );
    
    // Execute redemption
    const tx = await contracts.troveManager
      .connect(wallet)
      .redeemCollateral(
        musdAmount,
        firstRedemptionHint,
        upperHint,
        lowerHint,
        partialRedemptionHintNICR,
        50 // maxIterations
      );
    
    await tx.wait();
    return tx;
  }
  ```

  ```typescript Without Hints (Quick) theme={null}
  import { ethers } from 'ethers';

  async function redeemMUSDQuick(
    troveManager: Contract,
    wallet: Wallet,
    musdAmount: bigint
  ) {
    const tx = await troveManager
      .connect(wallet)
      .redeemCollateral(
        musdAmount,
        ethers.constants.AddressZero, // _firstRedemptionHint
        wallet.address, // _upperPartialRedemptionHint
        wallet.address, // _lowerPartialRedemptionHint
        BigInt("1100000000000000000000"), // _partialRedemptionHintNICR
        0 // _maxIterations
      );
    
    await tx.wait();
    return tx;
  }
  ```
</CodeGroup>

## Calculation Example

**Redeeming 100 MUSD:**

<Steps>
  <Step title="Burn MUSD">
    You burn: 100 MUSD
  </Step>

  <Step title="Calculate BTC">
    Formula: `(Your MUSD Amount ÷ BTC Price) × 0.9925 = BTC received`

    Example: `(100 ÷ 100000) × 0.9925 = 0.0009925 BTC`
  </Step>

  <Step title="Receive BTC">
    You receive: \$99.25 worth of BTC (0.75% fee goes to protocol)
  </Step>
</Steps>

## Common Issues

### "Cannot redeem when TCR \< MCR"

<Warning>
  System TCR is below 110%. Wait until it recovers before attempting redemptions.
</Warning>

### "Unable to redeem any amount"

This can happen for several reasons:

* No troves available with collateral ratio above 110%
* Hints are out of date (specifically the NICR hint)
* The redemption amount would leave the target trove with less than the minimum debt requirement of 1,800 MUSD
* Max iterations set too low for the redemption size

### Transaction runs out of gas

Lower `_maxIterations` to 10 or split into smaller redemptions.

### Transaction reverts unexpectedly

Get fresh hints and try again. Someone may have redeemed before you.

### Received less than expected

<Note>
  Check the `Redemption` event in your transaction. Some MUSD may have been returned if the last trove would go below 1,800 MUSD minimum.
</Note>

## Best Practices

* **Generate hints immediately before redeeming** - They become stale if someone else redeems first
* **Use Option A for small amounts** (\< \$10,000) - The higher gas cost is negligible
* **Use Option B for large amounts** - Saves significant gas on big redemptions
* **Set higher maxIterations for larger redemptions**:
  * Small (\< 10 troves): 10
  * Medium (10-30 troves): 50
  * Large (30+ troves): 100

## Contract Addresses

### Mainnet

<ParamField path="TroveManager" type="address">
  `0x94AfB503dBca74aC3E4929BACEeDfCe19B93c193`
</ParamField>

<ParamField path="HintHelpers" type="address">
  `0xD267b3bE2514375A075fd03C3D9CBa6b95317DC3`
</ParamField>

<ParamField path="SortedTroves" type="address">
  `0x8C5DB4C62BF29c1C4564390d10c20a47E0b2749f`
</ParamField>

<ParamField path="BorrowerOperations" type="address">
  `0x44b1bac67dDA612a41a58AAf779143B181dEe031`
</ParamField>

<ParamField path="PriceFeed" type="address">
  `0xc5aC5A8892230E0A3e1c473881A2de7353fFcA88`
</ParamField>

<ParamField path="MUSD Token" type="address">
  `0xdD468A1DDc392dcdbEf6db6e34E89AA338F9F186`
</ParamField>

### Testnet

<ParamField path="TroveManager" type="address">
  `0xE47c80e8c23f6B4A1aE41c34837a0599D5D16bb0`
</ParamField>

<ParamField path="HintHelpers" type="address">
  `0x4e4cBA3779d56386ED43631b4dCD6d8EacEcBCF6`
</ParamField>

<ParamField path="SortedTroves" type="address">
  `0x722E4D24FD6Ff8b0AC679450F3D91294607268fA`
</ParamField>

<ParamField path="BorrowerOperations" type="address">
  `0xCdF7028ceAB81fA0C6971208e83fa7872994beE5`
</ParamField>

<ParamField path="PriceFeed" type="address">
  `0x86bCF0841622a5dAC14A313a15f96A95421b9366`
</ParamField>

<ParamField path="MUSD Token" type="address">
  `0x118917a40FAF1CD7a13dB0Ef56C86De7973Ac503`
</ParamField>

<Warning>
  All addresses are proxy contracts. Always use "Read as Proxy" or "Write as Proxy" tabs.
</Warning>

## Need Help?

* Check your transaction on the block explorer to see events and error messages
* Join our Discord and open a ticket: [https://discord.com/invite/mezo](https://discord.com/invite/mezo)