Skip to main content

Liquidation

Liquidation is the protocol's mechanism for protecting lenders from losses when a borrower's position becomes unhealthy. When the value of a borrower's collateral drops relative to their outstanding debt, the position is automatically liquidated — meaning a portion (or all) of the collateral is seized and the corresponding debt is repaid. This page provides a comprehensive explanation of how liquidation works in PredMart, including when it triggers, how much is liquidated, what the liquidator receives, what happens to underwater positions, and how the system processes everything in practice.

Why Liquidation Exists​

In any lending protocol, there is an inherent risk that a borrower's collateral becomes worth less than their outstanding debt. If this happens and the borrower does not repay voluntarily, the pool (and therefore lenders) would suffer a loss.

Liquidation prevents this by intervening before the collateral value drops below the debt. When a position's health factor falls below 1.0, the protocol allows a liquidation to occur — seizing some collateral, repaying some debt, and restoring the position to a healthier state (or closing it entirely).

The goal of liquidation is to ensure that lenders' deposits are always backed by sufficient collateral. It is not a penalty for borrowers — it is a necessary mechanism to keep the system solvent.

When Does Liquidation Trigger?​

Health Factor Below 1.0​

A position is eligible for liquidation when its health factor drops below 1.0:

Health Factor = (Collateral Amount × Price × Liquidation Threshold) / Debt

When Health Factor < 1.0, it means:

Debt > Collateral Amount × Price × Liquidation Threshold

In other words, the borrower's debt has exceeded what the protocol considers a safe level relative to their collateral's current value.

What Causes the Health Factor to Drop?​

Three factors can push a health factor below 1.0:

  1. Price decline (most common): When the Polymarket share price drops, the collateral value decreases. Additionally, the LTV (and thus the liquidation threshold) also decreases at lower prices due to PredMart's dynamic LTV curve. This creates a double effect: collateral value goes down AND the threshold becomes more conservative.

  2. Interest accrual (gradual): Over time, the borrower's debt increases due to interest. If the borrower doesn't repay or add collateral, the health factor slowly decreases even with a stable price.

  3. Market resolution (instant): When a Polymarket market resolves against the borrower's position (the outcome doesn't happen), the shares become worthless ($0.00). This is an instantaneous health factor drop to zero. However, this is handled separately through the market resolution system rather than standard liquidation.

The Liquidation Process​

PredMart's liquidation process differs from many DeFi protocols in that it is not open to arbitrary third-party liquidators. Instead, liquidation is executed exclusively by PredMart's relayer — the same backend service that processes borrows and withdrawals. This ensures liquidations are performed efficiently and with accurate, oracle-signed prices.

Detection: Real-Time Monitoring​

PredMart's backend continuously monitors all active positions through two complementary systems:

1. WebSocket Price Feed (Primary)

The backend maintains a persistent WebSocket connection to Polymarket's CLOB price feed at wss://ws-subscriptions-clob.polymarket.com/ws/market. When any subscribed token's price changes, the system:

  • Receives the price update within milliseconds
  • Identifies all positions using that token as collateral
  • Calculates the health factor for each position
  • Triggers liquidation for any position with health factor < 1.0

This provides sub-second response time to price changes.

2. REST Polling Fallback (Backup)

A Celery task runs every 5 seconds that:

  • Fetches midpoint prices for all active collateral tokens via the REST API
  • Checks health factors against the on-chain contract
  • Triggers liquidation for any unhealthy positions

This fallback ensures that liquidations still occur even if the WebSocket connection drops.

Execution: On-Chain Liquidation​

Once the backend identifies a liquidatable position, it executes the following steps:

  1. Fetch fresh oracle price: Get the current midpoint price from Polymarket CLOB
  2. Sign price data: The oracle key signs (chainId, poolAddress, tokenId, price, timestamp, maxBorrow)
  3. Determine repay amount: Calculate the maximum repayable debt based on the close factor
  4. Build transaction: Construct a call to liquidate(borrower, tokenId, repayAmount, priceData)
  5. Submit transaction: Send to the Polygon network via the relayer wallet
  6. Wait for confirmation: Monitor the transaction until it's included in a block

Smart Contract Checks​

The liquidate() function on the smart contract performs the following verifications:

  • The caller is the authorized relayer
  • The oracle price signature is valid and fresh (< 10 seconds old)
  • Interest is accrued up to the current second
  • The position's health factor is genuinely below 1.0 at the provided price
  • The repay amount doesn't exceed the applicable close factor
  • The collateral seizure calculation is correct

Close Factor: How Much Gets Liquidated​

Not every liquidation seizes the entire position. PredMart uses a close factor system that determines what percentage of the debt can be repaid in a single liquidation:

Standard Liquidation (Health Factor 0.95 to 1.0)​

When the health factor is between 0.95 and 1.0 (below liquidation threshold but not critically low), the close factor is 50%. This means:

  • Up to 50% of the outstanding debt can be repaid in a single liquidation call
  • The corresponding collateral is seized (with a bonus — see below)
  • The remaining position continues with reduced debt and collateral
  • If the remaining position is still unhealthy, another liquidation can be triggered

The 50% close factor serves two purposes:

  1. It partially restores the position's health, giving the borrower a chance to recover
  2. It limits the amount of collateral that changes hands in a single transaction

Full Liquidation (Health Factor Below 0.95)​

When the health factor drops below 0.95 (the FULL_CLOSE_HF threshold), the close factor increases to 100%. This means the entire debt can be repaid in a single liquidation.

The rationale is that positions this close to being underwater require aggressive intervention. A 50% liquidation might not be sufficient to restore health, and the position could continue deteriorating before the next liquidation can execute.

Liquidation Bonus: Incentive for the Protocol​

When a liquidation occurs and the position is above water (collateral value exceeds debt), the liquidator receives a 5% bonus on the collateral seized. This bonus compensates for the gas costs and operational overhead of running the liquidation infrastructure.

How the Bonus Works​

The collateral seized in an above-water liquidation is calculated as:

Collateral Seized = Repay Amount × (1 + Liquidation Bonus) / Price

Where Liquidation Bonus = 5% (0.05).

Example:

  • Borrower's position: 10,000 shares at $0.50, debt = $3,200
  • Health factor < 1.0, close factor = 50%
  • Repay amount: 50% × $3,200 = $1,600
  • Collateral seized: $1,600 × 1.05 / $0.50 = 3,360 shares
  • Remaining: 6,640 shares, debt = $1,600

The liquidator (PredMart's relayer/admin wallet) receives 3,360 shares. The 5% bonus means they receive shares worth $1,680 for repaying $1,600 — a $80 profit on this liquidation.

Cap on Seizure​

The collateral seized is capped at the borrower's total collateral for that position. If the calculated seizure exceeds the total collateral, only the available collateral is seized.

Underwater Positions: When Collateral < Debt​

A position is underwater when the total value of the collateral is less than the outstanding debt:

Underwater: Collateral Amount × Price < Debt

This scenario can occur when:

  • A rapid, large price drop outpaces the liquidation engine
  • The price drops through an illiquid range where efficient liquidation is difficult
  • Multiple positions need liquidation simultaneously, creating a queue

Underwater Liquidation Mechanics​

When a position is underwater, the liquidation works differently from the standard (above-water) process:

  1. Liquidation discount: Instead of receiving a bonus, the liquidator pays a discounted price for the collateral. The discount is 10% (LIQUIDATION_DISCOUNT = 0.10). This means the liquidator pays 90% of the collateral's value.

  2. All collateral is seized: The liquidator receives ALL of the borrower's collateral for that position.

  3. Payment calculation:

    Liquidator Pays = Collateral Amount × Price × (1 - Liquidation Discount)
                    = Collateral Amount × Price × 0.90

  4. Bad debt absorption: The difference between the debt and the liquidator's payment is bad debt that is absorbed by the lending pool:

    Bad Debt = Debt - Liquidator Payment

Bad Debt Socialization​

When bad debt occurs, it is socialized across all lenders in the pool. In practical terms:

  • The pool's totalBorrowAssets is reduced by the full debt amount
  • But only the liquidator's payment is actually added to the pool's USDC balance
  • The difference (bad debt) effectively reduces totalAssets
  • This means the pUSDC exchange rate decreases slightly
  • All lenders share the loss proportionally to their pool ownership

Example:

  • Position: 5,000 shares at $0.30, debt = $2,000
  • Collateral value: 5,000 × $0.30 = $1,500 (underwater — debt $2,000 > collateral $1,500)
  • Liquidator pays: $1,500 × 0.90 = $1,350
  • Liquidator receives: all 5,000 shares (worth $1,500, paid $1,350 — 10% profit)
  • Bad debt: $2,000 - $1,350 = $650
  • This $650 is absorbed by the pool, slightly reducing all lenders' returns

What Happens to Seized Collateral​

After a liquidation, the seized Polymarket shares are sent to PredMart's admin wallet. The protocol then automatically sells these shares on Polymarket's CLOB to convert them back to USDC.

Auto-Sell System​

PredMart's CLOB Seller (clob_seller.py) handles the automated sale of seized collateral:

  1. Standard positions (shares >= minimum order size): Sold with Good-'Til-Cancelled (GTC) limit orders at the current best bid price (rounded down to the nearest tick size). This provides the best fill price without unnecessary slippage.

  2. Small positions (shares below minimum order size): Sold immediately with a Fill-or-Kill (FOK) market order. Since the amount is too small for a limit order, immediate execution is preferred.

  3. Dust filtering: Positions worth less than $0.05 (_DUST_VALUE_USD) are skipped entirely — the gas and operational cost of selling them exceeds their value.

  4. Market-closed handling: If the Polymarket market has stopped accepting orders, the seller checks if the market has resolved. Winning shares are redeemed directly through the CTF contract instead of being sold.

  5. Retry mechanism: If a sell attempt fails (e.g., due to insufficient liquidity, rate limiting, or no bids), the shares are added to a retry queue in Redis (lending:unsold_tokens). A Celery task (sweep_unsold_shares) runs every 10 seconds to retry pending sales.

  6. Verification: After each successful sell, the system waits 5 seconds and re-checks the admin's CTF balance to verify the shares actually settled on-chain. Remaining shares stay in the retry queue.

  7. Logging: All auto-sell attempts are recorded in the AutoSellLog database table with status (placed, dust, no_bids, market_closed, failed, rate_limited), order ID, and error details.

Liquidation Cooldown​

To prevent redundant transactions for the same position, PredMart enforces a 60-second cooldown between liquidation attempts for each borrower-token pair. If a position was recently attempted (whether successful or failed), it will be skipped until the cooldown expires. This prevents wasting gas on duplicate liquidation transactions during rapid price movements.

Liquidation Timeline: From Price Drop to Execution​

To understand how quickly liquidation happens in practice, here's a typical timeline:

TimeEvent
T+0msPolymarket share price drops
T+50msPredMart's WebSocket receives the price update
T+100msBackend calculates health factors for all positions with this token
T+150msBackend identifies position(s) with health factor < 1.0
T+200msBackend fetches fresh oracle price and signs it
T+500msLiquidation transaction submitted to Polygon network
T+2-5sTransaction included in a Polygon block (block time ~2s)
T+5-10sTransaction confirmed, collateral seized, debt repaid
T+10-30sAuto-sell begins for seized shares

The entire process from price drop to liquidation execution typically takes under 10 seconds, with most of the delay coming from blockchain block times.

Fallback Timing​

If the WebSocket is down, the REST fallback polls every 5 seconds:

TimeEvent
T+0sShare price drops
T+0-5sNext REST polling cycle detects the unhealthy position
T+5-10sLiquidation transaction submitted and confirmed

Even in the worst case (WebSocket down, price drops right after a poll), liquidation occurs within ~10 seconds.

How to Avoid Liquidation​

As a borrower, there are several strategies to minimize your liquidation risk:

1. Don't Borrow the Maximum​

The most effective strategy is to borrow well below your maximum. If your max borrow is $5,000, borrowing $3,000 gives you a much larger buffer before liquidation triggers.

Recommended: Keep your health factor above 1.5 at minimum, ideally above 2.0 for volatile markets.

2. Monitor Your Health Factor​

PredMart displays your health factor prominently. Check it regularly, especially during periods of market volatility. If your health factor drops below 1.3, consider taking action.

3. Add More Collateral​

If your health factor is declining, deposit additional shares to increase your collateral value and push the health factor back up.

4. Partially Repay Your Debt​

Repaying even a small portion of your debt can significantly improve your health factor. Repayment is a direct on-chain transaction — no relay needed — so it's fast and reliable.

5. Fully Repay​

If you're concerned about liquidation risk, the safest option is to fully repay your debt. After repayment, your collateral is safe from liquidation and can be withdrawn at any time.

6. Understand the Double Effect​

Remember that PredMart's dynamic LTV curve creates a double effect on price drops:

  • The collateral value decreases (obvious)
  • The liquidation threshold ALSO decreases (less obvious, because LTV is lower at lower prices)

This means your health factor drops faster than it would with a fixed liquidation threshold. Account for this when calculating your safety margin.

Liquidation Event Data​

On-Chain Events​

Every liquidation emits events on the blockchain:

event Liquidated(
    address indexed liquidator,
    address indexed borrower,
    uint256 indexed tokenId,
    uint256 collateralSeized,
    uint256 debtRepaid
);

// If bad debt occurs:
event BadDebtAbsorbed(
    address indexed borrower,
    uint256 indexed tokenId,
    uint256 amount
);

Database Records​

PredMart's indexer records all liquidation events in two tables:

  • LendingEvent: Records the liquidation as part of the borrower's event history
  • LiquidationLog: Detailed log including the price at liquidation, health factor, amounts, and transaction hash

API Access​

You can query liquidation history through the API:

GET https://api.predmart.com/lending/liquidations/{wallet_address}

This returns all liquidation events for a specific wallet, including timestamps, amounts, and transaction details.

Liquidation Parameters Summary​

ParameterValueDescription
Liquidation Buffer10%Added to LTV to get liquidation threshold
Close Factor50%Max debt repayable per liquidation (HF 0.95-1.0)
Full Close HF0.95Below this, 100% close factor applies
Liquidation Bonus5%Bonus on seized collateral (above water)
Liquidation Discount10%Discount for underwater liquidation (liquidator pays 90%)
Detection LatencyLess than 1 second (WS), ~5 seconds (REST)Time to detect unhealthy position
Execution Latency2-5 secondsTime for transaction to be confirmed on-chain

Next Steps​