Imported from yelunama/public-skills (SKILLS/skills-onchainCEX-strats-main/skills/liquidation-cascade-monitor/SKILL.md). Install upstream with npx skills add yelunama/public-skills --skill liquidation-cascade-monitor. Copyright stays with the author.

liquidation-cascade-monitor

DeFi liquidation cascade detection and CEX perp positioning skill for the Onchain x CEX Strats system. Monitors health factors on major DeFi lending protocols (Aave V3, Compound V3, MakerDAO/Sky), detects when large positions approach liquidation thresholds, calculates expected cascade price impact, and recommends short positions on OKX perpetual swaps to capture the forced-sell pressure. This skill does NOT compete for onchain liquidation bonuses -- that domain requires sub-100ms latency, Flashbots integration, and dedicated MEV infrastructure. Instead, it identifies the second-order effect: the price impact of cascade liquidations, and positions accordingly on CEX.

Core insight: When $50M of ETH collateral faces liquidation on Aave V3, that ETH will be force-sold into DEX pools and aggregators, creating downward price pressure that propagates to CEX within seconds. This skill detects the setup before the cascade triggers and recommends a short perp position on OKX.

1. Role

Liquidation cascade analyst -- monitors DeFi lending protocol health factors, estimates cascade price impact, and recommends CEX perp positions to profit from forced-sell pressure.

This skill is responsible for:

• Scanning DeFi lending protocols for positions approaching liquidation thresholds
• Computing cascade price impact based on liquidatable collateral vs market depth
• Recommending short perp positions on OKX to capture the cascade drop
• Monitoring active cascade alerts for trigger confirmation or expiry
• Evaluating multi-protocol systemic risk scenarios

This skill does NOT:

• Execute any trades (analysis only, never sends orders)
• Operate onchain liquidation bots (not competing for liquidation bonus)
• Submit Flashbots bundles or MEV transactions
• Interact with DeFi smart contracts directly
• Guarantee that cascades will trigger (health factors can improve)
• Handle basis trading (delegate to basis-trading)
• Handle funding rate strategies (delegate to funding-rate-arbitrage)

Strategic Rationale

2. Language

Match the user's language. Default: Traditional Chinese (繁體中文).

Metric labels may use English abbreviations regardless of language:

• health factor, HF, cascade, TVL, LTV, liquidation threshold, bps, PnL
• depth, impact, confidence, perp, SWAP
• Timestamps always displayed in UTC

3. Account Safety

Even in [LIVE] mode, this skill only reads market data. There is no risk of accidental execution.

Account Safety Protocol (Inlined)

The system defaults to demo mode at all times. Switching to live mode requires explicit user action.

Demo Mode (Default):

• MCP server config: okx-DEMO-simulated-trading
• All prices and positions are simulated
• All outputs include header: [DEMO]
• No confirmation required to use demo mode

Live Mode:

• MCP server config: okx-LIVE-real-money
• Real market data and real account positions
• All outputs include header: [LIVE]
• Recommendations are still analysis-only (no auto-execution)

Switching from Demo to Live:

1. User explicitly says "live", "真實帳戶", "real account", or similar
2. System confirms the switch with a clear warning:
   • "您正在切換至真實帳戶模式。所有數據將來自您的真實 OKX 帳戶。建議仍為分析建議，不會自動執行交易。請確認：輸入 '確認' 或 'confirm' 繼續"
3. User must reply with explicit confirmation
4. System verifies authentication via system_get_capabilities
5. If authenticated: switch and display [LIVE] header
6. If NOT authenticated: show AUTH_FAILED error, remain in demo

Session Rules:

4. Pre-flight (Machine-Executable Checklist)

This is a hybrid strategy requiring both CEX data (OKX) and DeFi data (DeFiLlama / OnchainOS).

Run these checks in order before any command. BLOCK at any step halts execution.

Pre-flight Decision Tree

Check 1 FAIL -> BLOCK (cannot proceed without CEX data)
Check 1 PASS -> Check 2
  Check 2 mismatch -> WARN + continue
  Check 2 PASS -> Check 3
    Check 3 FAIL -> BLOCK (no swap instruments)
    Check 3 PASS -> Check 4
      Check 4 FAIL -> BLOCK for that token (suggest alternatives with OKX perps)
      Check 4 PASS -> Check 5
        Check 5 FAIL -> WARN (degrade: no DeFi data, rely on secondary signals)
        Check 5 PASS -> Check 6
          Check 6 FAIL -> WARN (use conservative 0.3 confidence factor)
          Check 6 PASS -> ALL SYSTEMS GO

5. Skill Routing Matrix

6. Command Index

7. Parameter Reference

7.1 Command: scan

Scan DeFi lending protocols for positions approaching liquidation.

liquidation-cascade-monitor scan --protocols aave-v3,compound-v3,maker --min-collateral-usd 1000000 --max-health-factor 1.10

Parameters

Return Schema

CascadeScanResult:
  timestamp: integer               # Unix ms when scan was assembled
  protocols_scanned: string[]
  chains_scanned: string[]
  total_positions_found: integer
  results:
    - protocol: string             # e.g. "aave-v3"
      chain: string                # e.g. "ethereum"
      collateral_token: string     # e.g. "ETH"
      collateral_usd: number       # Total collateral value in USD
      borrow_token: string         # e.g. "USDC"
      borrow_usd: number           # Total borrow value in USD
      health_factor: number        # Current health factor
      liquidation_threshold: number # Protocol LTV threshold (e.g. 0.825)
      distance_to_liquidation_pct: number  # How far price must drop to trigger
      cascade_impact_pct: number   # Expected price impact if liquidated
      has_okx_perp: boolean        # Whether OKX has a perp for this token
      okx_perp_instId: string      # e.g. "ETH-USDT-SWAP" or "N/A"
      risk_level: string           # "[SAFE]", "[WARN]", "[BLOCK]"
      signal_strength: string      # "LOW", "MEDIUM", "HIGH", "CRITICAL"
      warnings: string[]

Return Fields Detail

7.2 Command: evaluate

Deep analysis of a specific cascade scenario with position recommendation.

liquidation-cascade-monitor evaluate --token ETH --protocol aave-v3 --collateral-at-risk-usd 5000000 --capital 50000 --leverage 3 --vip-tier VIP1

Parameters

Return Schema

CascadeEvaluateResult:
  timestamp: integer
  token: string
  protocol: string
  mode: string                     # "DEMO" or "LIVE"

  defi_data:
    collateral_at_risk_usd: number
    health_factor: number
    liquidation_threshold: number
    distance_to_liquidation_pct: number
    liquidation_price: number      # Price at which HF reaches 1.0
    current_price: number          # Current token price

  cascade_analysis:
    forced_sell_amount_usd: number # = collateral_at_risk_usd (100% liquidated)
    market_depth_bid_usd: number   # Total bid liquidity within 2% of mid price
    cascade_impact_pct: number     # forced_sell / (depth * 2)
    expected_price_drop_usd: number # current_price * cascade_impact_pct
    signal_strength: string        # LOW / MEDIUM / HIGH / CRITICAL

  position_recommendation:
    direction: string              # "SHORT"
    instId: string                 # e.g. "ETH-USDT-SWAP"
    entry_price: number            # Current perp price
    position_size_usd: number      # Calculated per formula
    leverage: number
    margin_required_usd: number    # position_size / leverage
    stop_loss_price: number        # 2% above entry
    stop_loss_pct: number          # 2.0%
    take_profit_price: number      # cascade_impact * 0.5 below entry
    take_profit_pct: number
    max_hold_hours: number
    risk_reward_ratio: number      # take_profit_pct / stop_loss_pct

  cost_analysis:
    entry_fee_usd: number
    exit_fee_usd: number
    funding_cost_usd: number       # Estimated funding for hold period
    total_cost_usd: number
    break_even_drop_pct: number    # Min price drop to cover all costs

  scenarios:
    - label: string                # "Full Cascade", "Partial (50%)", "No Cascade"
      probability: string          # "30%", "40%", "30%"
      price_change_pct: number
      gross_pnl_usd: number
      net_pnl_usd: number         # After fees + funding

  risk_assessment:
    risk_score: integer            # 1-10
    risk_gauge: string
    risk_label: string
    warnings: string[]

  is_actionable: boolean
  confidence: string

7.3 Command: monitor

Set up continuous monitoring for specific tokens or protocols.

liquidation-cascade-monitor monitor --tokens ETH,WBTC,SOL --hf-alert 1.05 --refresh-minutes 15

Parameters

Return Schema

CascadeMonitorResult:
  timestamp: integer
  monitoring_config:
    tokens: string[]
    protocols: string[]
    hf_alert_threshold: number
    min_collateral_usd: number
    refresh_minutes: number

  current_status:
    - token: string
      protocol: string
      health_factor: number
      collateral_usd: number
      status: string               # "SAFE", "WATCH", "ALERT", "CRITICAL"
      hf_trend: string             # "IMPROVING", "STABLE", "DECLINING"
      hf_sparkline: string         # e.g. "▇▆▅▄▃" (declining)
      next_check: string           # ISO timestamp

  alerts:
    - token: string
      protocol: string
      alert_type: string           # "HF_BELOW_THRESHOLD", "RAPID_DECLINE", "CASCADE_IMMINENT"
      health_factor: number
      collateral_usd: number
      message: string
      suggested_action: string     # e.g. "Run: evaluate --token ETH --protocol aave-v3"

7.4 Command: cascade-alert

Assess systemic cascade risk across multiple protocols simultaneously.

liquidation-cascade-monitor cascade-alert --tokens ETH --include-correlated true

Parameters

Return Schema

CascadeAlertResult:
  timestamp: integer
  scenario: string                 # "ETH drops 10%"

  protocol_breakdown:
    - protocol: string
      token: string
      liquidatable_usd: number     # At the scenario drop level
      health_factors_breached: integer  # Number of positions that would liquidate
      pct_of_protocol_tvl: number

  aggregate:
    total_liquidatable_usd: number
    total_cascade_impact_pct: number
    systemic_risk_level: string    # "LOW", "MODERATE", "HIGH", "CRITICAL"
    domino_risk: boolean           # True if cascade from protocol A triggers cascade in protocol B

  correlated_assets:
    - token: string                # e.g. "stETH"
      correlation: number          # e.g. 0.98
      additional_liquidatable_usd: number

  recommendation:
    action: string                 # "MONITOR", "PREPARE_SHORT", "ACTIVE_SHORT", "AVOID"
    reasoning: string
    suggested_command: string      # e.g. "evaluate --token ETH --capital 20000"

8. Execution Flow

Step 1: Intent Recognition

Parse user message to extract:

Keyword-to-command mapping:

Step 2: Data Collection

For scan command:

1. DeFiLlama API: GET https://api.llama.fi/protocols
   -> Filter for lending protocols with liquidation data
   -> Extract: tvl, chainTvls, category == "Lending"

2. For each protocol, fetch liquidation data:
   DeFiLlama: GET https://api.llama.fi/v2/protocols/{protocol}/liquidations
   -> Extract positions where health_factor < max_health_factor
   -> Filter: collateral_usd >= min_collateral_usd

3. For each at-risk token, check OKX perp availability:
   market_get_instruments(instType: "SWAP")
   -> Check if {TOKEN}-USDT-SWAP exists

4. For tokens with OKX perps, get market depth:
   market_get_orderbook(instId: "{TOKEN}-USDT-SWAP")
   -> Sum bid liquidity within 2% of mid price

5. Calculate cascade_impact for each position
6. Sort by cascade_impact descending
7. Apply signal_strength labels

For evaluate command:

1. system_get_capabilities -> verify mode

2. Fetch DeFi health factor data:
   DeFiLlama liquidation API or Aave subgraph
   -> health_factor, collateral_value, borrow_value

3. market_get_ticker(instId: "{TOKEN}-USDT")
   -> Current spot price

4. market_get_ticker(instId: "{TOKEN}-USDT-SWAP")
   -> Current perp price

5. market_get_orderbook(instId: "{TOKEN}-USDT-SWAP")
   -> Bid-side depth for impact calculation

6. market_get_funding_rate(instId: "{TOKEN}-USDT-SWAP")
   -> Current funding rate for cost projection

7. Calculate:
   a. cascade_impact
   b. position_size
   c. stop_loss / take_profit
   d. cost breakdown
   e. scenario P&L
   f. risk score

For cascade-alert command:

1. system_get_capabilities -> verify mode

2. For each major protocol:
   DeFiLlama liquidation API
   -> All positions for target token(s)

3. Apply hypothetical price drop (scenario_drop_pct):
   new_health_factor = health_factor * (1 - scenario_drop_pct / 100)
   -> Positions where new_health_factor < 1.0 become liquidatable

4. Sum total_liquidatable_usd across all protocols

5. For correlated assets (e.g., stETH for ETH):
   Repeat step 3-4 with correlated token positions

6. market_get_orderbook for depth assessment

7. Calculate systemic cascade impact
8. Determine domino risk (Protocol A cascade triggers Protocol B)

Important: OKX returns all values as strings. Always parseFloat() before arithmetic.

Step 3: Compute

(See Section 9 for all formulas with worked examples.)

Step 4: Format Output

Use these output templates:

• Header: Global Header Template (skill icon: Warning Triangle) with mode
• Body: Cascade-specific templates per command
• Footer: Next Steps Template

(All templates are inlined in Section 13 below.)

9. Formulas (All Self-Contained with Worked Examples)

9.1 Health Factor

health_factor = (collateral_value_usd * liquidation_threshold) / borrow_value_usd

Variables:
  collateral_value_usd  = Current market value of deposited collateral
  liquidation_threshold = Protocol-specific LTV at which liquidation triggers
  borrow_value_usd      = Current value of outstanding borrows

When health_factor < 1.0 -> liquidation is triggered.
When health_factor = 1.0 -> exactly at liquidation boundary.
When health_factor > 1.0 -> position is healthy (higher = safer).

Protocol Liquidation Thresholds (reference):
  Aave V3 ETH:    0.860  (86% LTV)
  Aave V3 WBTC:   0.780  (78% LTV)
  Compound V3 ETH: 0.830  (83% LTV)
  Maker ETH-A:    0.667  (66.7% LTV, i.e. 150% collateralization ratio)
  Maker ETH-C:    0.588  (58.8% LTV, i.e. 170% collateralization ratio)

Worked Example:
  collateral: 1,500 ETH at $3,400 = $5,100,000
  liquidation_threshold: 0.860 (Aave V3 ETH)
  borrow: $3,800,000 USDC

  health_factor = (5,100,000 * 0.860) / 3,800,000
               = 4,386,000 / 3,800,000
               = 1.154

  This position is healthy (HF > 1.0) but within monitoring range (HF < 1.20).

9.2 Distance to Liquidation

distance_to_liquidation_pct = (1 - (1 / health_factor)) * 100

Variables:
  health_factor = Current health factor of the position

Interpretation: The collateral token must drop by this percentage for HF to reach 1.0.

Worked Example:
  health_factor = 1.154

  distance_to_liquidation_pct = (1 - (1 / 1.154)) * 100
                              = (1 - 0.8666) * 100
                              = 0.1334 * 100
                              = 13.34%

  ETH must drop 13.34% (from $3,400 to ~$2,946) for this position to be liquidated.

9.3 Liquidation Price

liquidation_price = current_price * (1 - distance_to_liquidation_pct / 100)

Worked Example:
  current_price = $3,400.00
  distance_to_liquidation_pct = 13.34%

  liquidation_price = 3400 * (1 - 0.1334)
                    = 3400 * 0.8666
                    = $2,946.44

9.4 Cascade Price Impact

cascade_price_impact_pct = forced_sell_amount_usd / (pool_liquidity_usd * 2) * 100

Variables:
  forced_sell_amount_usd = Total collateral that will be force-sold upon liquidation
  pool_liquidity_usd     = Total bid-side liquidity within 2% of mid price on the deepest venue

The "* 2" accounts for the AMM constant-product curve / orderbook bilateral depth.
This is a simplified model. Real impact depends on:
  - Liquidation split across multiple DEX pools
  - Aggregator routing efficiency
  - Time for arbitrageurs to rebalance
Actual impact is typically 40-60% of this estimate due to distributed liquidation.

Worked Example:
  forced_sell_amount = $5,000,000 (1,500 ETH liquidated)
  pool_liquidity (2% depth) = $50,000,000

  cascade_price_impact = 5,000,000 / (50,000,000 * 2) * 100
                       = 5,000,000 / 100,000,000 * 100
                       = 5.0%

  Expected cascade price drop: ~5.0%
  Conservative estimate (60% realized): ~3.0%

9.5 Signal Strength Classification

signal_strength:
  cascade_impact < 1.0%   -> "LOW"     (not worth trading)
  cascade_impact 1.0-2.0% -> "MEDIUM"  (monitor closely)
  cascade_impact 2.0-5.0% -> "HIGH"    (actionable signal)
  cascade_impact > 5.0%   -> "CRITICAL" (strong signal, but also higher risk)

9.6 Position Sizing

position_size_usd = min(max_position_size, cascade_impact_pct * capital * confidence_factor)

Variables:
  max_position_size  = capital * leverage (hard cap: $100,000)
  cascade_impact_pct = Expected price impact from forced sell (decimal, e.g. 0.05 for 5%)
  capital            = Available capital in USD
  confidence_factor  = 0.3 (conservative), 0.5 (moderate), 0.7 (aggressive)
  leverage           = 1-5x (default 3x)

The position is intentionally conservative: we don't bet the full expected impact.
At 0.5 confidence, we size as if the cascade will only produce 50% of the theoretical impact.

Worked Example (moderate confidence):
  cascade_impact_pct = 5.0% = 0.05
  capital = $50,000
  confidence_factor = 0.5
  leverage = 3x
  max_position_size = 50,000 * 3 = $150,000 -> capped at $100,000

  position_size = min(100000, 0.05 * 50000 * 0.5)
               = min(100000, 1250)
               = $1,250.00

  margin_required = 1250 / 3 = $416.67

  Note: Position size is deliberately small relative to capital.
  This reflects the speculative nature of cascade timing.

9.7 Stop Loss

stop_loss_price = entry_price * (1 + stop_loss_pct / 100)

For SHORT positions: stop loss is ABOVE entry price (price went up = loss).

Default stop_loss_pct: 2.0%

Rationale: If price moves 2% against us, the cascade thesis is likely wrong
(health factors may have been repaid, or market is rallying, which would
push health factors UP, not down).

Worked Example:
  entry_price = $3,400.00
  stop_loss_pct = 2.0%

  stop_loss_price = 3400 * (1 + 0.02)
                  = 3400 * 1.02
                  = $3,468.00

  Max loss = position_size * stop_loss_pct
           = 1250 * 0.02
           = $25.00

9.8 Take Profit

take_profit_price = entry_price * (1 - take_profit_pct / 100)

take_profit_pct = cascade_impact_pct * 0.5 * 100

For SHORT positions: take profit is BELOW entry price (price went down = profit).

We target 50% of the theoretical cascade impact. Reasoning:
  - Not all liquidations execute simultaneously
  - Arbitrageurs will partially absorb the impact
  - We want to capture the "easy" half of the move

Worked Example:
  entry_price = $3,400.00
  cascade_impact_pct = 5.0% (0.05)
  take_profit_pct = 5.0% * 0.5 = 2.5%

  take_profit_price = 3400 * (1 - 0.025)
                    = 3400 * 0.975
                    = $3,315.00

  Expected profit = position_size * take_profit_pct
                  = 1250 * 0.025
                  = $31.25

  Risk/Reward ratio = take_profit_pct / stop_loss_pct
                    = 2.5% / 2.0%
                    = 1.25x

9.9 Funding Cost Estimation

funding_cost_usd = position_size_usd * funding_rate_per_8h * (hold_hours / 8)

Variables:
  position_size_usd       = Notional size of the perp position
  funding_rate_per_8h     = Current OKX funding rate (settled every 8 hours)
  hold_hours              = Expected hold duration

Note: Funding is paid by longs to shorts when rate is positive,
and by shorts to longs when rate is negative.
For our SHORT position:
  - Positive funding rate = we RECEIVE funding (reduces cost)
  - Negative funding rate = we PAY funding (adds cost)

Worked Example:
  position_size = $1,250.00
  funding_rate = 0.0001 (0.01% per 8h) -- positive, so we receive
  hold_hours = 4

  funding_cost = 1250 * 0.0001 * (4 / 8)
               = 1250 * 0.0001 * 0.5
               = $0.0625

  Since rate is positive, we receive $0.06. Actual cost = -$0.06.
  Net effect: reduces our trading cost slightly.

9.10 Total Cost and Break-Even

total_cost_usd = entry_fee + exit_fee + abs(funding_cost)  [if funding is against us]

entry_fee = position_size * taker_rate
exit_fee  = position_size * taker_rate

break_even_drop_pct = (total_cost_usd / position_size_usd) * 100

Worked Example (VIP0):
  position_size = $1,250.00
  taker_rate (USDT-Margined Swap VIP0) = 0.050% = 0.0005

  entry_fee = 1250 * 0.0005 = $0.625
  exit_fee  = 1250 * 0.0005 = $0.625
  funding_cost = -$0.06 (we receive, so net benefit)

  total_cost = 0.625 + 0.625 + 0 = $1.25
  (funding received offsets, but we don't count it toward cost reduction for safety)

  break_even_drop_pct = (1.25 / 1250) * 100
                      = 0.10%

  Token price must drop at least 0.10% to break even after fees.

9.11 Scenario P&L Table

For each scenario, compute:
  gross_pnl = position_size * price_change_pct * direction_multiplier
  net_pnl   = gross_pnl - total_cost

  direction_multiplier: -1 for SHORT (profit when price drops)

Scenarios:
  1. Full Cascade:   price drops by cascade_impact_pct
  2. Partial (50%):  price drops by cascade_impact_pct * 0.5
  3. No Cascade:     price unchanged, exit at max_hold time
  4. Adverse (stop): price rises by stop_loss_pct, stopped out

Worked Example (position = $1,250, cascade_impact = 5.0%, cost = $1.25):

  Scenario 1: Full Cascade (-5.0%)
    gross_pnl = 1250 * 0.05 = +$62.50
    net_pnl   = 62.50 - 1.25 = +$61.25

  Scenario 2: Partial Cascade (-2.5%)
    gross_pnl = 1250 * 0.025 = +$31.25
    net_pnl   = 31.25 - 1.25 = +$30.00

  Scenario 3: No Cascade (0%)
    gross_pnl = $0
    net_pnl   = 0 - 1.25 = -$1.25

  Scenario 4: Adverse (+2.0%, stopped out)
    gross_pnl = 1250 * (-0.02) = -$25.00
    net_pnl   = -25.00 - 1.25 = -$26.25

10. OKX Fee Schedule (Inlined)

USDT-Margined Swap / Perpetual Fees

Fee Calculation Notes

• Maker = limit order that adds liquidity to the orderbook (not immediately matched)
• Taker = market order or limit order that immediately matches
• For cost estimation, assume taker fees (cascade trades require speed, not limit orders)
• Fees are deducted from margin (derivatives)
• Funding rate is settled every 8 hours on OKX perpetual swaps

Fee Formula

fee_usd = notional_size_usd * fee_rate

# Round-trip cost (open + close)
roundtrip_fee_usd = notional_size_usd * (entry_fee_rate + exit_fee_rate)
roundtrip_fee_bps = (entry_fee_rate + exit_fee_rate) * 10000

Quick Reference: Round-Trip Taker Fees (bps)

Pattern: Cascade Short Cost Template

Position size: $1,250 (SHORT, 3x leverage, margin = $416.67)

Perp short entry (VIP0 taker):    $0.625  (5.0 bps)
Perp close (VIP0 taker):          $0.625  (5.0 bps)
Funding (4h, rate 0.01%):         -$0.063 (received)
                                   ------
Total cost:                        $1.19   (9.5 bps net)
Break-even price drop:             0.10%

11. MCP Tool Specifications (Inlined)

market_get_ticker

Purpose: Retrieve real-time ticker data for a single instrument -- last price, bid/ask, 24h volume and price range.

Return Fields:

Rate Limit: 20 requests/second.

market_get_orderbook

Purpose: Retrieve orderbook depth for an instrument -- bid/ask levels with size.

Return Fields:

Depth Calculation:

To compute bid-side liquidity within X% of mid:
  mid_price = (best_bid + best_ask) / 2
  threshold = mid_price * (1 - X / 100)
  depth_usd = sum(price * size for [price, size, _, _] in bids if price >= threshold)

Rate Limit: 20 requests/second. Use sz: "400" for depth calculations.

market_get_funding_rate

Purpose: Retrieve the current and predicted funding rate for perpetual swap instruments.

Return Fields:

Rate Limit: 10 requests/second.

market_get_instruments (SWAP)

Purpose: List available perpetual swap instruments with contract specifications.

Return Fields:

Rate Limit: 20 requests/second.

system_get_capabilities

Purpose: Check MCP server connectivity, authentication status, and available modules.

Return Fields:

Important Notes:

• Every numeric value from OKX is a string. Always use parseFloat() before arithmetic.
• All timestamps are in milliseconds since Unix epoch.
• Instrument ID format for perps: {TOKEN}-USDT-SWAP (e.g. "ETH-USDT-SWAP").

12. Safety Checks

Pre-Trade Safety Checklist

Every command runs through these checks in order before producing a recommendation. A BLOCK at any step halts the pipeline immediately.

Cascade-Specific Safety Rules

Risk Scoring Matrix

risk_score = sum(factor_score * factor_weight) for each factor
  Round to nearest integer, clamp to [1, 10]

Worked Example:
  Cascade Certainty: 3 (HF = 1.04, decent size)     -> 3 * 0.30 = 0.90
  Market Depth: 2 (ETH, deep book)                   -> 2 * 0.25 = 0.50
  Timing Risk: 4 (HF slowly declining)               -> 4 * 0.25 = 1.00
  Execution Risk: 2 (ETH-USDT-SWAP, tight spread)    -> 2 * 0.20 = 0.40

  risk_score = 0.90 + 0.50 + 1.00 + 0.40 = 2.80 -> rounded to 3
  risk_label = "MODERATE-LOW"
  risk_gauge = "▓▓▓░░░░░░░ 3/10"

BLOCK Conditions

WARN Conditions

13. Output Templates (Inlined)

Global Header Template

Used at the top of every skill output:

══════════════════════════════════════════
  Liquidation Cascade Monitor
  [{MODE}] [RECOMMENDATION ONLY -- 不會自動執行]
══════════════════════════════════════════
  Generated: {TIMESTAMP}
  Data sources: {DATA_SOURCES}
══════════════════════════════════════════

For liquidation-cascade-monitor: Data sources = "DeFiLlama + OKX REST (perps + orderbook)"

Formatting Rules

• Monetary: +$1,234.56 or -$1,234.56 (2 decimals, comma thousands)
• Percentages: 12.5% (1 decimal), HF: 3 decimal places (e.g. 1.154)
• Basis Points: integer only (e.g., 21 bps)
• Risk Levels: [SAFE], [WARN], [BLOCK]
• Risk Gauge: ▓▓▓░░░░░░░ 3/10 (scale 1-10)
• Sparklines: ▁▂▃▄▅▆▇█ for trend visualization
• Signal Strength: LOW, MEDIUM, HIGH, CRITICAL
• Timestamps: YYYY-MM-DD HH:MM UTC
• Health Factor: 3 decimal places (e.g. 1.154)

Risk Gauge Template

── Risk Assessment ─────────────────────────

  Overall Risk:  {RISK_GAUGE}  {RISK_SCORE}/10
                 {RISK_LABEL}

  Breakdown:
  ├─ Cascade Certainty: {CC_GAUGE}  {CC_SCORE}/10
  │                     {CC_NOTE}
  ├─ Market Depth:      {MD_GAUGE}  {MD_SCORE}/10
  │                     {MD_NOTE}
  ├─ Timing Risk:       {TR_GAUGE}  {TR_SCORE}/10
  │                     {TR_NOTE}
  └─ Execution Risk:    {ER_GAUGE}  {ER_SCORE}/10
                        {ER_NOTE}

Gauge format: 1/10: ▓░░░░░░░░░, 5/10: ▓▓▓▓▓░░░░░, 10/10: ▓▓▓▓▓▓▓▓▓▓ Risk labels: 1-2 LOW RISK, 3-4 MODERATE-LOW, 5-6 MODERATE, 7-8 ELEVATED, 9-10 HIGH RISK

13.1 Scan Output

══════════════════════════════════════════
  Liquidation Cascade Monitor -- SCAN
  [DEMO] [RECOMMENDATION ONLY -- 不會自動執行]
══════════════════════════════════════════
  Generated: {TIMESTAMP}
  Data sources: DeFiLlama + OKX REST
══════════════════════════════════════════

── 清算風險掃描結果 ──────────────────────

  掃描: {PROTOCOLS}
  篩選: 抵押品 >= ${MIN_COLLATERAL}, HF <= {MAX_HF}

  #{RANK}  {PROTOCOL} / {CHAIN}
  ├─ 抵押品:           {COLLATERAL_TOKEN} (${COLLATERAL_USD})
  ├─ 借款:             {BORROW_TOKEN} (${BORROW_USD})
  ├─ 健康因子:         {HEALTH_FACTOR}
  ├─ 距清算:           {DISTANCE_PCT}% ({DISTANCE_NOTE})
  ├─ 清算價格:         ${LIQUIDATION_PRICE}
  ├─ 級聯影響:         {CASCADE_IMPACT}%
  ├─ 信號強度:         {SIGNAL_STRENGTH}
  ├─ OKX 永續:         {HAS_PERP} ({PERP_INSTID})
  └─ 風險:             {RISK_LEVEL}

  ...

──────────────────────────────────────────
  已掃描 {TOTAL_POSITIONS} 個倉位
  符合條件: {MATCHING} 個
  可交易 (有 OKX 永續): {TRADEABLE} 個

13.2 Evaluate Output

══════════════════════════════════════════
  Liquidation Cascade Monitor -- EVALUATE
  [DEMO] [RECOMMENDATION ONLY -- 不會自動執行]
══════════════════════════════════════════
  Generated: 2026-03-09 14:30 UTC
  Data sources: DeFiLlama + OKX REST (perps + orderbook)
══════════════════════════════════════════

── DeFi 清算數據 ─────────────────────────

  協議:         Aave V3 (Ethereum)
  抵押品:       1,500 ETH ($5,100,000.00)
  借款:         $3,800,000.00 USDC
  健康因子:     1.154
  清算門檻:     0.860 (86% LTV)
  距清算:       13.3% ($453,960)
  清算價格:     $2,946.44

── 級聯影響分析 ──────────────────────────

  強制賣出量:    $5,100,000 (1,500 ETH)
  市場深度 (2%): $50,000,000 (ETH-USDT-SWAP bid side)
  理論影響:      5.0%
  保守估計 (60%): 3.0%
  信號強度:      HIGH

── 建議倉位 ──────────────────────────────

  方向:         SHORT (做空)
  合約:         ETH-USDT-SWAP
  入場價格:     $3,400.00
  倉位大小:     $1,250.00 (moderate confidence)
  槓桿:         3x
  所需保證金:   $416.67
  止損:         $3,468.00 (+2.0%)
  止盈:         $3,315.00 (-2.5%)
  最長持有:     4 小時
  風險/回報:    1.25x

── 成本分析 (VIP0) ──────────────────────

  開倉 (taker):     $0.63  (5.0 bps)
  平倉 (taker):     $0.63  (5.0 bps)
  資金費用 (4h):    -$0.06 (收取)
  ──────────────────────────────────────
  總成本:           $1.19  (9.5 bps)
  盈虧平衡跌幅:     0.10%

── 情境分析 ──────────────────────────────

  | 情境            | 價格變動  | 毛利     | 淨利     |
  |----------------|----------|---------|---------|
  | 完整級聯 (-5.0%) | -5.0%   | +$62.50 | +$61.25 |
  | 部分級聯 (-2.5%) | -2.5%   | +$31.25 | +$30.00 |
  | 無級聯 (0%)      | 0.0%    | $0.00   | -$1.25  |
  | 反向 (+2.0%)     | +2.0%   | -$25.00 | -$26.25 |

── Risk Assessment ─────────────────────────

  Overall Risk:  ▓▓▓░░░░░░░  3/10
                 MODERATE-LOW

  Breakdown:
  ├─ Cascade Certainty: ▓▓▓░░░░░░░  3/10
  │                     HF = 1.154, decent collateral size
  ├─ Market Depth:      ▓▓░░░░░░░░  2/10
  │                     ETH-USDT-SWAP: deep orderbook ($50M+ bid depth)
  ├─ Timing Risk:       ▓▓▓▓░░░░░░  4/10
  │                     HF slowly declining; cascade not imminent
  └─ Execution Risk:    ▓▓░░░░░░░░  2/10
                        ETH perp: tight spread, high liquidity

  Result: [ACTIONABLE] -- HIGH signal with moderate risk

══════════════════════════════════════════
  Next Steps
══════════════════════════════════════════

  1. 設定監控，追蹤此倉位健康因子變化:
     liquidation-cascade-monitor monitor --tokens ETH --hf-alert 1.05
  2. 查看多協議系統性風險:
     liquidation-cascade-monitor cascade-alert --tokens ETH --scenario-drop-pct 15
  3. 如入場後查看資金費率成本:
     funding-rate-arbitrage rates --asset ETH

  ── Disclaimer ────────────────────────────
  This is analysis only. No trades are executed automatically.
  All recommendations require manual review and execution.
  Cascade timing is inherently uncertain -- health factors may recover.
  以上僅為分析建議，不會自動執行任何交易。
  所有建議均需人工審核後手動操作。
  清算級聯的時間點具有不確定性 -- 健康因子可能恢復。
══════════════════════════════════════════

13.3 Monitor Output

══════════════════════════════════════════
  Liquidation Cascade Monitor -- MONITOR
  [DEMO] [RECOMMENDATION ONLY -- 不會自動執行]
══════════════════════════════════════════
  Generated: 2026-03-09 14:30 UTC
  Refresh: every 15 minutes
══════════════════════════════════════════

── 監控狀態 ──────────────────────────────

  Token   | Protocol    | HF      | 抵押品        | 狀態      | 趨勢
  ─────────────────────────────────────────────────────────────────
  ETH     | Aave V3     | 1.154   | $5,100,000   | WATCH    | ▇▆▅▄▃ declining
  WBTC    | Compound V3 | 1.342   | $3,200,000   | SAFE     | ▅▅▅▅▅ stable
  SOL     | Aave V3     | 1.067   | $1,800,000   | ALERT    | ▆▄▃▂▁ declining fast
  LINK    | Aave V3     | 1.891   | $800,000     | SAFE     | ▃▄▅▆▇ improving

── 警報 ──────────────────────────────────

  [ALERT] SOL / Aave V3
  ├─ 健康因子: 1.067 (低於警報門檻 1.05 僅差 1.7%)
  ├─ 抵押品: $1,800,000 SOL
  ├─ 趨勢: 快速下降 (過去 1h 跌 3.2%)
  └─ 建議: 執行深入評估
     liquidation-cascade-monitor evaluate --token SOL --protocol aave-v3 --capital 10000

── 下次刷新: 2026-03-09 14:45 UTC ──────

13.4 Cascade-Alert Output

══════════════════════════════════════════
  Liquidation Cascade Monitor -- CASCADE ALERT
  [DEMO] [RECOMMENDATION ONLY -- 不會自動執行]
══════════════════════════════════════════
  Generated: 2026-03-09 14:30 UTC
  Scenario: ETH drops 10%
══════════════════════════════════════════

── 壓力測試: ETH -10% ───────────────────

  協議              | 可清算量        | 佔 TVL    | 觸發倉位數
  ───────────────────────────────────────────────────────────
  Aave V3           | $45,000,000    | 0.8%     | 127
  Compound V3       | $12,000,000    | 0.5%     | 34
  Maker / Sky       | $28,000,000    | 1.2%     | 18
  Morpho            | $5,000,000     | 0.3%     | 8
  ───────────────────────────────────────────────────────────
  合計              | $90,000,000    |          | 187

── 級聯影響總計 ──────────────────────────

  總強制賣出:        $90,000,000
  OKX ETH 深度 (2%): $50,000,000
  理論級聯影響:      90.0%   [不切實際 -- 實際會分散]
  實際估計 (分散):   8.0-12.0%  [考慮多 DEX 路由 + 時間分散]

── 關聯資產 ──────────────────────────────

  stETH (相關性: 0.98)
  ├─ 額外可清算量: $15,000,000
  └─ 合併級聯影響: +1.5%

  wstETH (相關性: 0.97)
  ├─ 額外可清算量: $8,000,000
  └─ 合併級聯影響: +0.8%

── 系統性風險評估 ────────────────────────

  系統性風險等級:   HIGH
  骨牌效應:        YES (Aave 清算 -> Maker 被動清算 -> 二次價格衝擊)
  綜合級聯影響:    10.3-14.3%

  Risk Gauge:  ▓▓▓▓▓▓▓░░░  7/10
               ELEVATED

── 建議 ──────────────────────────────────

  行動: PREPARE_SHORT
  原因: ETH -10% 情境下，$90M+ 的強制賣出將造成顯著價格影響。
  目前 HF 尚未達到觸發水平，但多個協議同時面臨風險。
  建議: 準備好空單參數，等待 HF 進一步惡化時快速入場。

  建議指令:
    liquidation-cascade-monitor evaluate --token ETH --capital 30000 --leverage 3 --confidence moderate

══════════════════════════════════════════
  Disclaimer
══════════════════════════════════════════

  This is analysis only. No trades are executed automatically.
  Stress test scenarios are hypothetical -- actual outcomes may differ significantly.
  以上僅為分析建議，不會自動執行任何交易。
  壓力測試情境為假設性質 -- 實際結果可能大幅不同。
══════════════════════════════════════════

14. Error Codes & Recovery

15. Conversation Examples

Example 1: Scan for Liquidation Risks

User:

有冇大倉接近清算？

Intent Recognition:

• Command: scan
• Protocols: all (default)
• Min collateral: $500,000 (default)
• Max HF: 1.10 (default)

Tool Calls:

1. system_get_capabilities -> { authenticated: true, mode: "demo" }
2. DeFiLlama: GET /protocols -> filter lending protocols
3. DeFiLlama: GET /v2/protocols/aave-v3/liquidations
   -> Positions with HF < 1.10:
      [{ collateral: "ETH", collateral_usd: 5100000, borrow_usd: 3800000, hf: 1.154 },
       { collateral: "SOL", collateral_usd: 1800000, borrow_usd: 1500000, hf: 1.067 }]
4. DeFiLlama: GET /v2/protocols/compound-v3/liquidations
   -> [{ collateral: "WBTC", collateral_usd: 3200000, borrow_usd: 2100000, hf: 1.342 }]
5. market_get_instruments(instType: "SWAP")
   -> Verify ETH-USDT-SWAP, SOL-USDT-SWAP, BTC-USDT-SWAP exist
6. market_get_orderbook(instId: "ETH-USDT-SWAP", sz: "400")
   -> Sum bid depth within 2%: $50,000,000
7. market_get_orderbook(instId: "SOL-USDT-SWAP", sz: "400")
   -> Sum bid depth within 2%: $8,000,000

Computation:

ETH (Aave V3):
  cascade_impact = 5,100,000 / (50,000,000 * 2) * 100 = 5.1%
  signal_strength = "CRITICAL" (>5%)
  distance_to_liq = (1 - 1/1.154) * 100 = 13.3%

SOL (Aave V3):
  cascade_impact = 1,800,000 / (8,000,000 * 2) * 100 = 11.25%
  signal_strength = "CRITICAL" (>5%)
  distance_to_liq = (1 - 1/1.067) * 100 = 6.3%

Output: (See Section 13.1 template, filled with above data)

Example 2: Evaluate a Specific Cascade

User:

幫我分析 ETH 清算級聯影響，$50,000 資金，3 倍槓桿，VIP1

Intent Recognition:

• Command: evaluate
• Token: ETH
• Capital: $50,000
• Leverage: 3x
• VIP tier: VIP1
• Confidence: moderate (default)

Tool Calls:

1. system_get_capabilities -> { authenticated: true, mode: "demo" }
2. DeFiLlama: Aave V3 ETH liquidation data
   -> collateral_at_risk: $5,100,000, HF: 1.154
3. market_get_ticker(instId: "ETH-USDT") -> { last: "3400.00" }
4. market_get_ticker(instId: "ETH-USDT-SWAP") -> { last: "3400.50" }
5. market_get_orderbook(instId: "ETH-USDT-SWAP", sz: "400")
   -> bid depth within 2%: $50,000,000
6. market_get_funding_rate(instId: "ETH-USDT-SWAP")
   -> { fundingRate: "0.0001" }

Computation:

cascade_impact = 5,100,000 / (50,000,000 * 2) * 100 = 5.1%
signal_strength = "CRITICAL"

position_size = min(100000, 0.051 * 50000 * 0.5)
             = min(100000, 1275)
             = $1,275.00

margin_required = 1275 / 3 = $425.00

stop_loss = 3400.50 * 1.02 = $3,468.51  (+2.0%)
take_profit = 3400.50 * (1 - 0.051 * 0.5) = 3400.50 * 0.9745 = $3,313.79  (-2.55%)

Cost (VIP1):
  entry = 1275 * 0.00045 = $0.57
  exit  = 1275 * 0.00045 = $0.57
  funding (4h) = 1275 * 0.0001 * 0.5 = $0.064 (received)
  total = $1.08

Scenarios:
  Full cascade (-5.1%):   gross = +$65.03, net = +$63.95
  Partial (-2.55%):        gross = +$32.51, net = +$31.44
  No cascade (0%):         gross = $0,      net = -$1.08
  Adverse (+2.0%):         gross = -$25.50, net = -$26.58

Risk score:
  Cascade Certainty: 3 * 0.30 = 0.90
  Market Depth: 2 * 0.25 = 0.50
  Timing Risk: 4 * 0.25 = 1.00
  Execution Risk: 2 * 0.20 = 0.40
  Total: 2.80 -> 3 (MODERATE-LOW)

Output: (See Section 13.2 template, filled with above data)

Example 3: Cascade Alert / Stress Test

User:

如果 ETH 跌 10%，會唔會連環清算？

Intent Recognition:

• Command: cascade-alert
• Token: ETH
• Scenario drop: 10%
• Include correlated: true (default)

Tool Calls:

1. system_get_capabilities -> { authenticated: true, mode: "demo" }
2. For each protocol (Aave V3, Compound V3, Maker, Morpho):
   DeFiLlama liquidation data for ETH collateral positions
3. Apply -10% scenario:
   For each position:
     new_hf = hf * 0.90
     If new_hf < 1.0: add to liquidatable pool
4. Sum liquidatable amounts per protocol
5. Repeat for stETH, wstETH (correlated assets)
6. market_get_orderbook(instId: "ETH-USDT-SWAP", sz: "400")

Computation:

Aave V3:   127 positions would breach HF < 1.0 -> $45M liquidatable
Compound:  34 positions -> $12M
Maker:     18 positions -> $28M
Morpho:    8 positions  -> $5M
Total:     $90M

Correlated (stETH): +$15M, (wstETH): +$8M
Grand total: $113M

OKX depth: $50M
Theoretical impact: 113M / (50M * 2) * 100 = 113% (unrealistic)
Distributed estimate: 8-12% (liquidations spread across DEXes over minutes)
Combined with correlated: 10.3-14.3%

Systemic risk: HIGH
Domino effect: YES (Aave cascade -> price drop -> Maker positions breach)

Output: (See Section 13.4 template, filled with above data)

16. Implementation Notes

DeFi Data Source Hierarchy

Priority 1: DeFiLlama /v2/protocols/{protocol}/liquidations (aggregated)
Priority 2: Aave V3 subgraph -> getUserAccountData() per user
Priority 3: Compound V3 subgraph -> getAccountLiquidity()
Priority 4: Maker/Sky -> Vat.urns() for individual CDPs

Fallback: If DeFiLlama is unavailable, use aggregate TVL data and
estimate liquidation exposure based on typical LTV distributions.

Token-to-OKX-Perp Mapping

Common DeFi collateral tokens and their OKX perp availability:

Truncated - read the full file at https://github.com/yelunama/public-skills/blob/e1103ede8e3a40dd1fb97d198070e9739b599805/SKILLS/skills-onchainCEX-strats-main/skills/liquidation-cascade-monitor/SKILL.md.