{
  "id": "surf.market.liquidation.order",
  "object": "tool",
  "name": "Large Liquidation Orders",
  "summary": "Returns individual large liquidation orders above a USD threshold (min_amount, default 10000).",
  "description": "Returns individual large liquidation orders above a USD threshold (min_amount, default 10000). Filters: exchange and symbol. Pagination: limit/offset page within a bounded, most-recent window. To page beyond that window, shift the time range: set to to oldest_returned_timestamp + 1 (Unix seconds) and repeat, de-duplicating on order_id. to is exclusive (returns rows strictly older than to), so the +1 re-includes the boundary second; using the oldest timestamp itself would skip any rows sharing that second. When offset exceeds the window the response returns an empty array with meta.empty_reason rather than falsely claiming exhaustion. For aggregate totals and long/short breakdown by exchange, use /market/liquidation/exchange-list. For historical liquidation charts, use /market/liquidation/chart.\n\nRaw surf#market/liquidation/order endpoint: input is { body, queryParams, pathParams } as the provider documents them (https://docs.asksurf.ai/data-api/market/liquidation-order).",
  "category": "lookup",
  "hosted_by": "Surf",
  "runtime": "partner",
  "side_effects": false,
  "status": "live",
  "credits": 0,
  "price": null,
  "providers": [
    {
      "id": "surf",
      "name": "Surf",
      "price": null,
      "own_key_only": true
    }
  ],
  "mcp_name": "surf_market_liquidation_order",
  "input_schema": {
    "type": "object",
    "properties": {
      "queryParams": {
        "type": "object",
        "properties": {
          "exchange": {
            "default": "Binance",
            "type": "string",
            "enum": [
              "Binance",
              "OKX",
              "Bybit",
              "Bitget",
              "Hyperliquid",
              "Gate",
              "HTX",
              "Bitmex",
              "Bitfinex",
              "CoinEx",
              "Aster",
              "Lighter"
            ],
            "description": "Exchange name. Can be Binance, OKX, Bybit, Bitget, Hyperliquid, Gate, HTX, Bitmex, Bitfinex, CoinEx, Aster, or Lighter. Example: Binance. Defaults to \"Binance\"."
          },
          "symbol": {
            "default": "BTC",
            "type": "string",
            "minLength": 1,
            "description": "Token ticker symbol like BTC or ETH. Example: BTC. Defaults to \"BTC\"."
          },
          "min_amount": {
            "default": "10000",
            "type": "string",
            "minLength": 1,
            "description": "Minimum liquidation amount in USD. Example: 10000. Defaults to \"10000\"."
          },
          "side": {
            "type": "string",
            "enum": [
              "long",
              "short"
            ],
            "description": "Filter by liquidation side. Omit to return both. Example: long."
          },
          "sort_by": {
            "default": "timestamp",
            "type": "string",
            "enum": [
              "usd_value",
              "timestamp",
              "price"
            ],
            "description": "Field to sort results by. Defaults to \"timestamp\"."
          },
          "order": {
            "default": "desc",
            "type": "string",
            "enum": [
              "asc",
              "desc"
            ],
            "description": "Sort order. Defaults to \"desc\"."
          },
          "limit": {
            "default": 20,
            "type": "integer",
            "minimum": 1,
            "maximum": 100,
            "description": "Results per page. Defaults to 20."
          },
          "offset": {
            "default": 0,
            "type": "integer",
            "minimum": 0,
            "maximum": 9007199254740991,
            "description": "Pagination offset. Defaults to 0."
          },
          "from": {
            "type": "string",
            "minLength": 1,
            "description": "Start of time range (inclusive). Accepts Unix seconds (1704067200) or date string (2024-01-01). Example: 2024-01-01."
          },
          "to": {
            "type": "string",
            "minLength": 1,
            "description": "End of time range, exclusive (returns rows strictly older than to). Accepts Unix seconds (1706745600) or date string (2024-02-01). To page backward, set this to the oldest returned timestamp + 1 and de-duplicate on order_id. Example: 2024-02-01."
          }
        },
        "additionalProperties": false
      }
    },
    "required": [],
    "additionalProperties": false
  },
  "kind": "endpoint"
}