Thanh lý

Thanh lý bảo vệ hệ thống khỏi các tài khoản không còn khả năng đáp ứng nghĩa vụ ký quỹ. Khi vốn chủ sở hữu (equity) của tài khoản giảm xuống dưới yêu cầu ký quỹ duy trì, quy trình thanh lý sẽ chuyển giao các vị thế sang các bên đối ứng có khả năng thanh toán.

Điều kiện kích hoạt

Thanh lý được kích hoạt khi tài khoản rơi vào trạng thái âm ký quỹ (underwater):

Portfolio Margin:

$$\text{Equity} < \text{Maintenance Margin Required}$$

Standard Margin:

$$\text{Maintenance Margin} < 0$$

Trong đó ký quỹ duy trì = equity - MM yêu cầu.

Hệ thống liên tục quét tất cả các tài khoản có vị thế để kiểm tra tình trạng sức khỏe.

Máy trạng thái

Tài khoản trải qua bốn trạng thái thanh lý:

Trạng thái	Mô tả	Hạn chế lệnh
Healthy	Equity > MM yêu cầu	Không có
PreLiquidation	Equity < MM, thời gian ân hạn đang có hiệu lực	Chặn các lệnh làm tăng rủi ro
InLiquidation	Đấu giá đang diễn ra	Chặn tất cả các lệnh
Liquidated	Đấu giá hoàn tất	Tài khoản đã được xử lý xong

Chuyển đổi trạng thái

1. Healthy → PreLiquidation: Tài khoản giảm xuống dưới ngưỡng MM
2. PreLiquidation → Healthy: Tài khoản phục hồi trên MM (người dùng nạp thêm tiền hoặc đóng vị thế)
3. PreLiquidation → InLiquidation: Thời gian ân hạn hết hạn mà không phục hồi
4. InLiquidation → Liquidated: Đấu giá hoàn tất thành công

Thời gian ân hạn trước thanh lý

Khi tài khoản bước vào trạng thái trước thanh lý (pre-liquidation):

1. Các lệnh làm tăng rủi ro bị chặn ngay lập tức
2. Các lệnh giảm rủi ro (đóng vị thế) vẫn được phép
3. Thời gian ân hạn 60 giây bắt đầu
4. Nếu tài khoản phục hồi (equity > MM) trước khi hết thời gian ân hạn, tài khoản trở về trạng thái Healthy
5. Nếu vẫn âm ký quỹ sau thời gian ân hạn, phiên đấu giá thanh lý bắt đầu

Thời gian ân hạn cho người dùng thời gian để:

• Nạp thêm tài sản thế chấp
• Đóng vị thế để giảm yêu cầu ký quỹ
• Phản ứng với các biến động đột ngột của thị trường

Đấu giá thanh lý

Khi thời gian ân hạn hết hạn, phiên đấu giá kiểu Hà Lan (Dutch auction) bắt đầu:

Đấu giá còn khả năng thanh toán (Equity > 0)

Giá khởi điểm = equity × (1 - phạt), giảm dần theo thời gian.

Người thanh lý (liquidator) đấu giá để tiếp quản các vị thế của tài khoản, đổi lại nhận:

• Vốn chủ sở hữu của tài khoản (trừ khoản phạt)
• Trách nhiệm với tất cả các vị thế

Khoản phạt tạo động lực cho người thanh lý tham gia.

Đấu giá mất khả năng thanh toán (Equity < 0)

Nếu tài khoản mất khả năng thanh toán (equity âm), quỹ bảo hiểm sẽ cung cấp một khoản thưởng để khuyến khích người thanh lý hấp thụ các vị thế âm ký quỹ.

Chuyển giao vị thế

Khi một thanh lý hoàn tất:

1. Tất cả các vị thế được chuyển từ tài khoản bị thanh lý sang người thanh lý
2. Người thanh lý nhận (nếu còn khả năng thanh toán) hoặc trả (nhận thưởng nếu mất khả năng thanh toán) giá trị thanh toán
3. Margin root được cập nhật on-chain
4. Trạng thái tài khoản chuyển sang Liquidated

Thanh lý một phần và thanh lý toàn bộ

Loại	Điều kiện	Hành vi
Một phần	≤ 5 vị thế	Thanh lý các vị thế cụ thể cho đến khi MM được khôi phục
Toàn bộ	> 5 vị thế	Thanh lý toàn bộ tài khoản

Thanh lý một phần là tất định (deterministic):

• Các vị thế được sắp xếp theo một thuật toán nhất quán (không ngẫu nhiên)
• Người thanh lý nhận các vị thế theo thứ tự đã định
• Quy trình dừng lại khi tài khoản trở về trạng thái khỏe mạnh

Thác xử lý mất khả năng thanh toán

Khi thanh lý không thể thu hồi toàn bộ giá trị, các khoản lỗ được hấp thụ theo thứ tự:

1. Vốn chủ sở hữu của tài khoản: Người dùng bị thanh lý chịu lỗ tối đa bằng vốn chủ sở hữu của mình
2. Quỹ bảo hiểm: Bù đắp phần thiếu hụt nếu vốn chủ sở hữu không đủ
3. ADL (Tự động giảm đòn bẩy): Nếu quỹ bảo hiểm cạn kiệt, các bên đối ứng có lãi sẽ bị giảm đòn bẩy theo tỷ lệ
4. Xã hội hóa khoản lỗ: Lớp bảo vệ cuối cùng (hiện chưa được triển khai)

Quỹ bảo hiểm

Quỹ bảo hiểm:

• Được tích lũy từ các khoản phạt thanh lý
• Bù đắp cho các thanh lý mất khả năng thanh toán
• Được bổ sung thông qua phí giao dịch và các khoản phạt
• Có mục tiêu dự trữ tối thiểu

ADL (Tự động giảm đòn bẩy)

Nếu quỹ bảo hiểm không thể bù đắp khoản lỗ:

• Các bên đối ứng có vị thế đang lãi sẽ được chọn
• Các vị thế bị buộc đóng tại giá mark
• Việc lựa chọn ưu tiên lợi nhuận và đòn bẩy cao nhất
• Người dùng bị ảnh hưởng sẽ nhận được thông báo

Các endpoint API

Lấy trạng thái thanh lý

GET /liquidation/status?wallet=0x...

Phản hồi:

{
  "success": true,
  "data": {
    "wallet": "0x...",
    "state": "pre_liquidation",
    "margin_mode": "portfolio",
    "equity": "4500.00",
    "mm_required": "5000.00",
    "maintenance_margin": "-500.00",
    "entered_pre_liq_at": 1737312000000,
    "mm_shortfall": "500.00",
    "auction_id": null
  }
}

Lấy lịch sử thanh lý

GET /liquidation/history?wallet=0x...&limit=20

Trả về lịch sử chuyển đổi trạng thái của một tài khoản.

Lấy lịch sử thanh lý công khai

GET /liquidations?limit=50

Trả về lịch sử chuyển đổi thanh lý theo thứ tự mới nhất trước trên tất cả các ví. Endpoint này công khai và sử dụng phân trang cursor cho các bot thanh lý và công cụ giám sát.

Tham số truy vấn

• cursor: Cursor mờ (opaque) được trả về từ trang trước.
• limit: Kích thước trang, mặc định 50, tối đa 100.
• wallet: Bộ lọc ví tùy chọn.
• status hoặc state: Bộ lọc trạng thái chuyển đổi thanh lý tùy chọn. Các giá trị được chấp nhận là healthy, pre_liquidation, in_liquidation và liquidated.
• margin_mode: Bộ lọc chế độ ký quỹ tùy chọn. Các giá trị được chấp nhận là standard và portfolio.
• liquidation_mode: Bộ lọc chế độ thanh lý tùy chọn. Các giá trị được chấp nhận là partial và full.

Phản hồi: PublicLiquidationsResponse với các mục chuyển đổi thanh lý và page.next_cursor cho yêu cầu tiếp theo.

Lấy chi tiết đấu giá

GET /liquidation/auction/{auction_id}

Trả về trạng thái đấu giá, các vị thế và chi tiết thanh toán.

Thông báo WebSocket

Các thay đổi trạng thái thanh lý được phát trên kênh liquidation:

{
  "type": "LiquidationStateChange",
  "wallet": "0x...",
  "previous_state": "healthy",
  "new_state": "pre_liquidation",
  "equity": "4500.00",
  "mm_required": "5000.00",
  "shortfall": "500.00",
  "auction_id": null,
  "timestamp": 1737312000000
}

Đăng ký để nhận cập nhật theo thời gian thực cho ví của bạn.

Tham số

Tham số	Giá trị	Mô tả
poll_interval	5 giây	Tần suất kiểm tra sức khỏe
grace_period	60 giây	Thời gian trước khi đấu giá bắt đầu
min_shortfall_threshold	0	Mức thiếu hụt tối thiểu để kích hoạt trước thanh lý
partial_liquidation_threshold	5 vị thế	Dưới mức này, thanh lý một phần được sử dụng

Thực hành tốt nhất

Dành cho nhà giao dịch

1. Theo dõi tỷ lệ ký quỹ: Giữ vốn chủ sở hữu cao hơn nhiều so với MM (khuyến nghị bộ đệm gấp 2 lần)
2. Thiết lập cảnh báo: Sử dụng WebSocket để phát hiện sớm trạng thái trước thanh lý
3. Chuẩn bị sẵn nguồn vốn: Giữ tài sản thế chấp dự phòng sẵn sàng để nạp
4. Sử dụng stop-loss: Tự động giảm vị thế trước khi bị thanh lý

Truy vấn tình trạng sức khỏe

Kiểm tra trạng thái ký quỹ của bạn thường xuyên:

# Portfolio margin
curl "https://api.hypercall.xyz/portfolio?wallet=0x..."

# Look for:
# - equity vs maintenance_margin_required
# - margin_ratio (equity / IM)

Phục hồi trong thời gian ân hạn

Nếu bạn rơi vào trạng thái trước thanh lý:

1. Nạp tài sản thế chấp thông qua luồng nạp tiền
2. Đóng các vị thế để giảm yêu cầu ký quỹ
3. Hủy các lệnh đang mở làm tăng rủi ro

Các hành động giảm rủi ro luôn được phép, ngay cả trong trạng thái trước thanh lý.

On-Chain và Off-Chain

Thành phần	Vị trí	Ghi chú
Giám sát sức khỏe	Off-chain	Quét mỗi 5 giây
Chuyển đổi trạng thái	Off-chain	Được ghi log và lưu trữ
Bộ đếm thời gian ân hạn	Off-chain	Có thể cấu hình
Thực thi đấu giá	On-chain	Chuyển giao vị thế trên hợp đồng Controller
Thanh toán	On-chain	Chuyển giao giá trị và cập nhật margin root

Engine off-chain xử lý phát hiện và điều phối; thực thi on-chain đảm bảo tính chung quyết của thanh toán.

---

Xem thêm:

• Portfolio Margin: Cách tính MM cho tài khoản portfolio
• Standard Margin: Cách tính MM cho tài khoản standard
• Margin Floor: Các mức sàn an toàn ảnh hưởng đến ngưỡng thanh lý