The Liquidation Engine Specification is the canonical reference for how the dYdX protocol manages undercollateralized positions. It defines the precise calculation of a subaccount's liquidation price, the stepwise process for reducing position size, and the interface that off-chain liquidation bots must respect to interact correctly with the on-chain settlement layer. For infrastructure teams building liquidation bots or monitoring systems, this document is the source of truth against which all implementations must be validated.
Protocols
Liquidation Engine Specification
Authoritative reference for the dYdX protocol's liquidation logic, detailing liquidation price calculation, the stepwise liquidation process, and the interface for liquidation bots.
introduction
PROTOCOL REFERENCE
Introduction
Authoritative specification for the dYdX chain's liquidation logic, defining the exact mechanics that infrastructure teams must implement to operate compliant liquidation bots.
Operationally, the specification governs the transition from a position breaching its maintenance margin requirement to the forced deleveraging of that position. It details the fillable-price mechanism, the insurance fund's role as a backstop, and the sequencing rules that determine how a liquidation is split across multiple takers. Misunderstanding these rules can lead to bots failing to capture liquidation opportunities, or worse, submitting transactions that the protocol rejects, leaving positions dangerously undercollateralized during volatile market conditions.
The interface defined here is the contract between the protocol and the liquidation agent ecosystem. It assumes bots are monitoring indexer events for liquidatable subaccounts and racing to submit place-order transactions that satisfy the protocol's pricing and size constraints. Chainscore Labs reviews liquidation bot logic against this specification to identify edge cases in price calculation, order construction, and race-condition handling, ensuring operational readiness before mainnet deployment.
LIQUIDATION ENGINE SPECIFICATION
Quick Facts
Key operational facts about the dYdX liquidation engine for risk teams, bot operators, and integrators.
| Area | What changes | Who is affected | Action |
|---|---|---|---|
Liquidation Price | Defined by maintenance margin fraction; calculated from oracle price and open position size. | Traders, risk teams, liquidation bot operators. | Verify calculation matches protocol formula; do not rely on off-chain approximations. |
Stepwise Process | Positions are partially liquidated in steps until margin is above maintenance requirement. | Liquidation bots, market makers, DeFi protocols composing on dYdX. | Ensure bot logic handles partial fills and state transitions between steps correctly. |
Bot Interface | Standardized API for submitting liquidation transactions; requires precise order construction. | Liquidation bot developers, infrastructure teams. | Review bot implementation against canonical interface; test against testnet edge cases. |
Oracle Dependency | Liquidation eligibility is triggered by oracle price updates; stale or incorrect prices cause false liquidations. | Oracle providers, risk teams, large position holders. | Monitor oracle update frequency and deviation; implement circuit breakers for stale prices. |
Insurance Fund | Fund backstops losses when liquidated positions cannot be closed above bankruptcy price. | Validators, stakers, protocol governance. | Model insurance fund adequacy under volatility scenarios; monitor drawdown events. |
Margin Calculation | Cross-margin accounts use portfolio-wide margin; isolated margin uses per-market margin. | Institutional traders, portfolio managers, exchange integrators. | Confirm margin mode before computing liquidation thresholds; test both modes. |
Gas and Priority | Liquidation transactions compete for block space; gas pricing strategy affects execution reliability. | Liquidation bot operators, validators. | Tune gas parameters to network conditions; monitor mempool for competing liquidations. |
Event Emissions | Liquidation events emit on-chain logs for indexers and monitoring systems. | Indexers, data teams, risk dashboards. | Verify event parsing matches specification; alert on missed or malformed events. |
technical-context
LIQUIDATION ENGINE DESIGN
Technical Mechanism
The dYdX liquidation engine uses a stepwise process to deleverage undercollateralized positions, protecting the insurance fund and maintaining market integrity.
The dYdX liquidation engine is designed to automatically close out positions when an account's collateral value falls below its maintenance margin requirement. The core mechanism relies on a precise calculation of the liquidation price, which is the oracle price at which a position would become undercollateralized. This price is derived from the account's open positions, total collateral, and the protocol's margin ratios, using the canonical formulas defined in the Margin and Collateralization Framework. When the oracle price crosses this threshold, the account becomes eligible for liquidation.
The liquidation process itself is stepwise and non-custodial. A liquidation bot, operated by an external party, initiates the process by submitting a transaction that identifies the undercollateralized account. The protocol does not immediately close the entire position. Instead, it liquidates a fraction of the position—up to a defined liquidation_percent—at a price slightly worse than the oracle price, with a configurable spread. This partial liquidation is designed to return the account to a safe margin level while minimizing market impact. If the account remains undercollateralized after the first step, the bot can submit another transaction in the next block, continuing the process until the position is fully deleveraged or the account is solvent.
The interface for liquidation bots is a critical public good for the dYdX ecosystem. Bots must monitor on-chain oracle prices, compare them against the liquidation prices of all open accounts, and construct valid liquidation transactions that comply with the protocol's message format. The economic incentive for running a bot comes from the liquidation spread, which acts as a fee paid by the liquidated account. Infrastructure teams building these bots must handle edge cases such as oracle staleness, network congestion, and gas price volatility to ensure reliable operation. Chainscore can review liquidation bot logic for correctness, operational readiness, and resilience against adverse market conditions.
LIQUIDATION ENGINE IMPACT
Affected Actors
Liquidation Bot Operators
Liquidation bot operators are the most directly affected actors. They must implement the stepwise liquidation process exactly as specified, including correct calculation of liquidation prices and adherence to the fillable amount logic for each step.
Key Actions:
- Audit bot logic against the canonical liquidation price formula to avoid submitting invalid transactions.
- Implement proper gas management for multi-step liquidations, ensuring bots can complete partial fills without running out of gas mid-sequence.
- Monitor insurance fund drawdown conditions to predict when liquidations will trigger backstop mechanics.
- Test against edge cases: accounts with multiple positions, cross-margined portfolios, and near-zero collateral ratios.
Chainscore can review your liquidation bot's state machine logic, gas optimization, and edge-case handling to ensure reliable execution under volatile market conditions.
implementation-impact
LIQUIDATION ENGINE
Implementation Impact
The liquidation engine specification defines the exact protocol behavior for under-collateralized positions. Builders of liquidation bots, risk monitoring systems, and trading interfaces must implement against this standard to operate safely and avoid losses.
01
Liquidation Bot Architecture
Bots must implement the stepwise liquidation process exactly as specified: querying sub-accounts below maintenance margin, calculating the liquidation price using the oracle interface standard, and submitting liquidation transactions with correct gas parameters. Incorrect implementation of the partial liquidation formula can leave bots holding unwanted positions or failing to capture available liquidation fees. Chainscore can review bot logic against the canonical specification to prevent operational losses.
02
Oracle Dependency and Race Conditions
The liquidation engine relies on the Oracle Interface and Price Feed Standard for price data. Stale or manipulated oracle prices directly invalidate liquidation price calculations, potentially triggering unfair liquidations or allowing underwater positions to persist. Bots must monitor oracle update frequency and deviation thresholds. Chainscore can assess the end-to-end oracle dependency chain and model failure scenarios for liquidation systems.
03
Insurance Fund Interaction
When a position's collateral falls below zero after liquidation, the Insurance Fund and Backstop Standard governs the drawdown process. Liquidation bot operators need to understand the exact conditions under which the insurance fund covers shortfalls to model their own risk of unprofitable liquidations during cascading market events. Chainscore can provide insurance fund adequacy analysis and stress-testing for liquidation scenarios.
04
Margin Framework Alignment
The liquidation engine is inseparable from the Margin and Collateralization Framework. Changes to initial margin, maintenance margin, or cross-margining logic alter which sub-accounts become liquidatable and at what price. Bots hardcoding margin parameters will break when governance adjusts them. Chainscore can review bot parameter management and build monitoring for governance-driven margin changes.
05
Event Indexing for Monitoring
The Event Indexing and Logging Standard defines the liquidation events emitted by the protocol. Risk dashboards and alerting systems must parse these events correctly to detect liquidation cascades in real time. Missing or misinterpreting partial liquidation events leads to inaccurate exposure reporting. Chainscore can audit indexer implementations for correct event handling and build operational monitoring for liquidation activity.
06
Exchange and Custodian Risk Controls
Centralized exchanges and custodians holding cross-margined positions must implement pre-liquidation alerts and circuit breakers aligned with the protocol's liquidation engine. A delay in detecting an approaching liquidation can prevent timely collateral top-ups, forcing the protocol to seize positions. Chainscore can review institutional integration logic and build monitoring for liquidation proximity across large portfolios.
LIQUIDATION ENGINE IMPACT ASSESSMENT
Risk and Compatibility Matrix
Operational risks, failure modes, and required actions for teams building or integrating with the dYdX liquidation engine.
| Area | What changes or risks | Who is affected | Action |
|---|---|---|---|
Liquidation Bot Implementation | Incorrect stepwise liquidation logic can lead to failed transactions, wasted gas, and missed profit opportunities. | Liquidation bot operators, algorithmic trading firms | Review bot logic against the canonical specification. Chainscore can audit liquidation bot implementations for correctness and edge cases. |
Liquidation Price Calculation | Discrepancy between off-chain bot calculation and on-chain validation will cause transaction reversion. | Liquidation bot operators, risk monitoring systems | Validate off-chain calculation matches the protocol's exact formula, including oracle price, funding rate, and position size inputs. |
Oracle Dependency | Stale or incorrect oracle prices can trigger false liquidations or prevent legitimate ones, causing systemic risk. | DeFi protocols, institutional traders, risk teams | Monitor oracle update frequency and deviation. Chainscore can assess oracle dependency risks and integration correctness. |
Insurance Fund Mechanics | Incorrect understanding of drawdown conditions can lead to unexpected losses during cascading liquidations. | Risk teams, governance delegates, insurance fund participants | Model systemic loss scenarios against the Insurance Fund and Backstop Standard. Verify governance replenishment interface. |
Margin Model Interaction | Liquidation engine behavior is directly dependent on the Margin and Collateralization Framework. Changes to margin parameters alter liquidation thresholds. | Institutional traders, risk teams, market makers | Re-evaluate portfolio risk models whenever governance changes margin parameters. Chainscore can provide margin parameter risk analysis. |
Event Indexing | Liquidation events must be correctly parsed from chain data for accurate P&L, risk reporting, and compliance. | Data teams, analytics platforms, indexer operators | Ensure indexer implementations correctly handle all liquidation event types defined in the Event Indexing and Logging Standard. |
Validator & Node Operation | Validators must correctly execute liquidation logic during block production. Bugs can cause consensus failures or chain halts. | Validator operators, infrastructure teams | Test all client releases against liquidation scenarios before upgrading. Monitor for unexpected behavior during high-volatility events. |
OPERATIONAL READINESS
Liquidation Bot Operator Checklist
A practical checklist for teams building and operating liquidation bots on dYdX. Each item covers what to validate, why it matters for reliable liquidation execution, and the signal or artifact that confirms readiness before deploying capital.
What to check: Your bot's internal liquidation price formula must match the protocol's stepwise calculation exactly, including subaccount-level margin, oracle price adjustments, and maintenance margin fraction. A single rounding or decimal error will cause your bot to either miss liquidations or submit failing transactions.
Why it matters: Liquidation opportunities are time-sensitive and competitive. A miscalculation means your bot either bids on unprofitable positions or fails to act on valid ones, directly losing gas and opportunity cost.
Confirmation signal: Reproduce the protocol's reference test vectors in your bot's unit test suite. Compare your calculated liquidation price against the chain's state query for a known undercollateralized subaccount on testnet.
resource-links
DYDX LIQUIDATION ENGINE
Source Resources
Canonical resources for validating dYdX liquidation logic, bot integrations, governance-driven parameter changes, and operational risk controls. Teams should verify formulas, module behavior, and API assumptions against live documentation and the current chain implementation before deploying liquidation infrastructure.
Chains We Build On
Looking to build on a specific blockchain?
We build smart contracts, DeFi applications, wallets, tokenization platforms, and blockchain infrastructure across the major ecosystems teams choose today. That includes Ethereum, Arbitrum, Optimism, Polygon, Avalanche, Solana, Sui, Aptos, Hedera, Stellar, and NEAR, with support for additional EVM and non-EVM networks based on your product requirements.
EVM ecosystems
- Ethereum
- Arbitrum
- Optimism
- Polygon
- Avalanche
- Cronos
Non-EVM ecosystems
- Solana
- Sui
- Aptos
- Hedera
- Stellar
- NEAR
Additional ecosystems
- Polkadot
- Cosmos
- TON
- Cardano
- Algorand
- Tempo
Also available for Base, appchains, custom EVM networks, and cross-chain product architecture.
LIQUIDATION ENGINE FAQ
Frequently Asked Questions
Common operational and implementation questions for teams building or monitoring liquidation bots against the dYdX protocol.
The liquidation price is derived from the maintenance margin requirement for a given position. When the oracle price crosses this threshold, the position becomes undercollateralized relative to the maintenance margin fraction. The exact formula depends on the position's collateral asset, the market's margin parameters, and the current state of the subaccount's cross-margined portfolio. Teams should not calculate this in isolation; the protocol's margin module computes the effective liquidation price dynamically based on all open positions and collateral in the subaccount. Bots must query the protocol's state to identify liquidatable subaccounts rather than relying on static price thresholds.
Trusted by Industry Leaders
Delivering blockchain solutions for 5+ years.
We have partnered with 50+ leading DeFi protocols, NFT ecosystems, and fintech innovators to build secure, scalable, and capital-efficient blockchain products.
Selected Partners & Clients
“I've been working with Chainscore Labs for last 3+ years, they've consistently delivered with strong ownership across multiple projects. The team is reliable and detail-oriented.”
L
Lee Erswell
CEO, Telos Foundation
how to get started
How to get started?
If you're looking for blockchain integration, ChainScore Labs has 5+ years of experience helping teams build and integrate exchanges, wallets, smart contracts, tokenization solutions, and protocol-connected products, we can help you choose the right path, integrate securely, and get to production faster. Our team consists of experienced blockchain developers and architects who can help you with your blockchain integration needs.
01
Exploration & Strategy
Define your product goals and choose the right blockchain architecture for your use case.
02
Architecture & Design
Design the smart contracts, tokenomics, and security parameters of your system.
03
Development & Integration
Build and integrate with wallets, oracles, and front-end dApps for a seamless experience.
04
Security & Launch
Comprehensive audits followed by a risk-managed mainnet deployment to protect your users.
Explore More Solutions
Discover our
blockchain development services.
We build production-grade blockchain solutions for top-tier projects across DeFi and Web3.
Book a Call
Start a build
Need a blockchain engineering team?
Send the project context and we will respond with next steps, scope questions, and a practical path to delivery.