Route Metadata
| Field | Value |
|---|---|
| Method | GET |
| Path | /v1/hyperliquid/hip3/liquidations/{symbol} |
| operationId | getHip3Liquidations |
| Tag | HIP-3 Builder Perps - Liquidations |
| Family | HIP-3 |
| Deprecated or legacy | no |
Human endpoint reference
OpenGET /v1/hyperliquid/hip3/liquidations/{symbol} for authentication, parameters, responses, and examples.
Request Parameters
Path Parameters
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"title": "getHip3Liquidations path parameters",
"type": "object",
"required": [
"symbol"
],
"properties": {
"symbol": {
"description": "HIP-3 trading pair symbol (e.g., hyna:BTC, km:US500). Case-sensitive.",
"type": "string",
"example": "hyna:BTC",
"x-parameter-location": "path"
}
}
}
Query Parameters
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"title": "getHip3Liquidations query parameters",
"type": "object",
"required": [
"start"
],
"properties": {
"start": {
"description": "Start timestamp (Unix milliseconds)",
"type": "integer",
"format": "int64",
"example": 1769922000000,
"x-parameter-location": "query"
},
"end": {
"description": "End timestamp (Unix milliseconds). Defaults to now.",
"type": "integer",
"format": "int64",
"x-parameter-location": "query"
},
"cursor": {
"description": "Pagination cursor (format: {timestamp_ms}_{trade_id})",
"type": "string",
"x-parameter-location": "query"
},
"limit": {
"description": "Maximum records to return (1-1000)",
"type": "integer",
"default": 1000,
"maximum": 1000,
"x-parameter-location": "query"
}
}
}
Response Contracts
Status 200
Liquidation eventsapplication/json
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"title": "getHip3Liquidations response 200",
"description": "API response containing an array of liquidation events",
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"description": "Liquidation event",
"type": "object",
"required": [
"coin",
"liquidated_user",
"liquidator_user",
"price",
"side",
"size",
"symbol",
"timestamp"
],
"properties": {
"closed_pnl": {
"description": "Realized PnL from the liquidation (usually negative)",
"type": "string",
"nullable": true,
"example": "-1250.50"
},
"coin": {
"description": "Trading pair symbol (deprecated, use symbol instead)",
"type": "string",
"deprecated": true,
"example": "BTC"
},
"direction": {
"description": "Upstream direction label (for example `Close Long`, `Close Short`; HIP-3 can also emit `Open Long`, `Open Short`, or rare unclassified values such as `Long > Short`)",
"type": "string",
"nullable": true,
"example": "Close Long"
},
"liquidated_user": {
"description": "Address of the user who was liquidated",
"type": "string",
"example": "0x84eec0068b37919cc8f13d7454073ac167374cc0"
},
"liquidator_user": {
"description": "Address of the liquidator (counterparty)",
"type": "string",
"example": "0x4d969e59b312970cc07af266938a4433ccae0b4c"
},
"mark_price": {
"description": "Mark price at time of liquidation",
"type": "string",
"nullable": true,
"example": "42480.25"
},
"price": {
"description": "Price at which the liquidation was executed",
"type": "string",
"example": "42500.50"
},
"side": {
"description": "Exchange side code for the liquidation-related fill (`A`/`B`). Use `direction` for close/open interpretation, especially on HIP-3.",
"type": "string",
"example": "B"
},
"size": {
"description": "Size of the liquidated position",
"type": "string",
"example": "1.5"
},
"symbol": {
"description": "Trading pair symbol",
"type": "string",
"example": "BTC"
},
"timestamp": {
"description": "Liquidation timestamp (UTC)",
"type": "string",
"format": "date-time",
"example": "2025-05-21T10:30:00.000Z"
},
"trade_id": {
"description": "Trade ID for this liquidation",
"type": "integer",
"format": "int64",
"nullable": true,
"example": 1234567890
},
"tx_hash": {
"description": "Blockchain transaction hash",
"type": "string",
"nullable": true,
"example": "0xe266d353038e679c5d7e042433054f0000e1d8e52f7860ecda84573b9b5a02ca"
}
}
}
},
"meta": {
"type": "object",
"properties": {
"count": {
"description": "Number of records returned",
"type": "integer"
},
"next_cursor": {
"description": "Cursor for pagination (format: timestamp_tradeId)",
"type": "string",
"nullable": true
}
}
},
"success": {
"type": "boolean",
"example": true
}
}
}
Status 400
Invalid requestapplication/json
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"title": "getHip3Liquidations response 400",
"description": "Error response",
"type": "object",
"properties": {
"code": {
"description": "HTTP status code",
"type": "integer"
},
"error": {
"description": "Error message",
"type": "string"
},
"error_code": {
"description": "Machine-readable error code. Common values: `invalid_query_params` (a query parameter failed to parse or validate) and `invalid_path_params` (a path parameter failed to parse). Other endpoint-specific codes exist; treat unknown codes as generic errors of the given HTTP status.",
"type": "string"
},
"param": {
"description": "The parameter at fault, when the error is about one parameter.",
"type": "string"
},
"request_id": {
"description": "Unique request ID for support",
"type": "string",
"format": "uuid"
},
"success": {
"description": "Always false on an error.",
"type": "boolean",
"example": false
}
}
}
OpenAPI example
{
"code": 400,
"error": "Failed to deserialize query string: limit: invalid digit found in string",
"error_code": "invalid_query_params",
"param": "limit",
"request_id": "3f2a9c71-5b0e-4d68-9a4c-7e1d2b6f8a05",
"success": false
}
Status 401
Authentication requiredapplication/json
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"title": "getHip3Liquidations response 401",
"description": "Error response",
"type": "object",
"properties": {
"code": {
"description": "HTTP status code",
"type": "integer"
},
"error": {
"description": "Error message",
"type": "string"
},
"error_code": {
"description": "Machine-readable error code. Common values: `invalid_query_params` (a query parameter failed to parse or validate) and `invalid_path_params` (a path parameter failed to parse). Other endpoint-specific codes exist; treat unknown codes as generic errors of the given HTTP status.",
"type": "string"
},
"param": {
"description": "The parameter at fault, when the error is about one parameter.",
"type": "string"
},
"request_id": {
"description": "Unique request ID for support",
"type": "string",
"format": "uuid"
},
"success": {
"description": "Always false on an error.",
"type": "boolean",
"example": false
}
}
}
OpenAPI example
{
"code": 401,
"error": "Missing authentication credentials. Provide X-API-Key header or Bearer token.",
"error_code": "unauthorized",
"request_id": "71ed4b6f-63ef-4ae1-a123-07ffa47c1c14",
"success": false
}
Status 429
Rate limit exceededapplication/json
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"title": "getHip3Liquidations response 429",
"description": "Error response",
"type": "object",
"properties": {
"code": {
"description": "HTTP status code",
"type": "integer"
},
"error": {
"description": "Error message",
"type": "string"
},
"error_code": {
"description": "Machine-readable error code. Common values: `invalid_query_params` (a query parameter failed to parse or validate) and `invalid_path_params` (a path parameter failed to parse). Other endpoint-specific codes exist; treat unknown codes as generic errors of the given HTTP status.",
"type": "string"
},
"param": {
"description": "The parameter at fault, when the error is about one parameter.",
"type": "string"
},
"request_id": {
"description": "Unique request ID for support",
"type": "string",
"format": "uuid"
},
"success": {
"description": "Always false on an error.",
"type": "boolean",
"example": false
}
}
}
OpenAPI example
{
"code": 429,
"error": "Rate limit exceeded"
}