Get Liquidations
Query historical liquidation events from DeepBook Margin. This endpoint returns detailed information about liquidated positions including amounts, rewards, and remaining assets. Use it for liquidation monitoring, analytics, and building liquidation bots.
Endpoints
There are two endpoints for querying liquidations:
By Owner
GET /deepbook-margin/liquidations/{owner}
Returns liquidation events for all margin managers owned by a specific address.
General Query
GET /deepbook-margin/liquidations
Returns liquidation events with optional filters.
Use Cases
- Liquidation History — Show users their liquidation history
- Liquidation Bot Analytics — Track liquidation opportunities and rewards earned
- Risk Analysis — Analyze liquidation patterns and risk factors
- Market Monitoring — Monitor overall liquidation activity in the protocol
- MEV Research — Study liquidation execution patterns
Parameters
Path Parameters (By Owner endpoint)
| Parameter | Type | Required | Description |
|---|---|---|---|
owner | string | Yes | Owner wallet address (liquidated positions) |
Query Parameters
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
page | number | No | 0 | Page number (starts from 0) |
perPage | number | No | 10 | Items per page (max 50) |
marginManagerId | string | No | — | Filter by margin manager ID |
marginPoolId | string | No | — | Filter by margin pool ID |
balanceManagerId | string | No | — | Filter by balance manager ID |
fromCheckpoint | number | No | — | Start checkpoint (inclusive) |
toCheckpoint | number | No | — | End checkpoint (inclusive) |
api-key | string | Yes | — | Your Surflux API key |
Response
Returns a paginated response with liquidation event objects.
Pagination Fields
| Field | Type | Description |
|---|---|---|
items | array | Array of liquidation objects |
isLastPage | boolean | Whether this is the last page |
currentPage | number | Current page number |
perPage | number | Items per page |
Liquidation Fields
| Field | Type | Description |
|---|---|---|
event_digest | string | Unique event identifier |
digest | string | Transaction digest |
sender | string | Liquidator address |
checkpoint | number | Checkpoint when liquidation occurred |
timestamp | string | ISO timestamp |
checkpoint_timestamp_ms | number | Timestamp in milliseconds |
margin_manager_id | string | Liquidated margin manager |
margin_pool_id | string | Margin pool the debt was in |
liquidation_amount | number | Amount of debt liquidated |
pool_reward | number | Reward retained by the pool |
pool_default | number | Bad debt absorbed by the pool |
risk_ratio | number | Risk ratio at time of liquidation |
remaining_base_asset | number | Remaining base asset after liquidation |
remaining_quote_asset | number | Remaining quote asset after liquidation |
remaining_base_debt | number | Remaining base debt after liquidation |
remaining_quote_debt | number | Remaining quote debt after liquidation |
base_pyth_price | number | Pyth oracle price for base asset |
base_pyth_decimals | number | Decimals for base Pyth price |
quote_pyth_price | number | Pyth oracle price for quote asset |
quote_pyth_decimals | number | Decimals for quote Pyth price |
onchain_timestamp | number | On-chain timestamp in milliseconds |
margin_manager | object | null | Associated margin manager details |