> ## Documentation Index
> Fetch the complete documentation index at: https://docs.0xarchive.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Estimate a webhook subscription JSON Schema

> Estimate a webhook subscription JSON Schema contract. Includes parameters, response shapes, examples, and implementation notes from the 0xArchive contract.

Source OpenAPI: 0xArchive API 1.6.1; 168 paths; 190 component schemas.

How often would this configuration have fired over the last `lookback_days`? Returns the total, a count per day of the window, the median and busiest day, the distribution of the event's primary metric, a ladder of what the daily rate would be at other thresholds, and a sample of real matches, so a threshold can be chosen against history rather than guessed. The configuration is validated and normalised exactly as a create. Nothing is stored and no delivery is sent. Available for `account.fill`, `account.transfer`, `account.liquidated`, `market.liquidation`, `market.pga_payment`, `hip4.settlement`, `market.liquidation_burst`, `market.oi_delta`, `oracle.jump` and `market.funding_flip`; another type is refused with the list of the ones that work. An address scoped type needs at least one watched wallet to report on. Authenticate with an API key or a signed-in dashboard session. Available on every plan, including Free, and metered like the market data it returns. At most six estimates and dry-runs a minute per account, shared between the two.

## Route Metadata

| Field                | Value                                 |
| -------------------- | ------------------------------------- |
| Method               | `POST`                                |
| Path                 | `/v1/webhooks/subscriptions/estimate` |
| operationId          | `estimateWebhookSubscription`         |
| Tag                  | Webhooks - Previews                   |
| Family               | Webhooks                              |
| Deprecated or legacy | no                                    |

## Request Body

### application/json

```json theme={"theme":"github-dark"}
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "estimateWebhookSubscription request body",
  "description": "A would-be subscription to evaluate against history. Same shape as a create, without the endpoint, plus the window.",
  "type": "object",
  "required": [
    "event_type"
  ],
  "properties": {
    "config": {
      "description": "What a subscription matches on. Every key is checked against the event type's catalog declaration, so an unknown key, an undeclared parameter or a condition on an undeclared metric is refused rather than ignored. The stored config is the normalised form: venues and addresses lowercased, declared parameters filled in at their defaults, and operators written in their canonical spelling.",
      "type": "object",
      "properties": {
        "addresses": {
          "description": "Wallets to match, for an address scoped event type. Every address must already be on your watched list. Omit to match all of them.",
          "type": "array",
          "items": {
            "type": "string"
          },
          "example": [
            "0x6b9e773128f453f5c2c60935ee2de2cbc5390a24"
          ]
        },
        "conditions": {
          "description": "Conditions on the event's metrics, all of which must hold for a delivery. At most 16 per subscription.",
          "type": "array",
          "items": {
            "description": "One condition on an event metric. The operator vocabulary is grouped by the metric's type; see `operators` on the event type.",
            "type": "object",
            "required": [
              "metric",
              "op"
            ],
            "properties": {
              "metric": {
                "description": "A metric declared by the event type.",
                "type": "string",
                "example": "notional_usd"
              },
              "op": {
                "description": "Comparison to apply. Symbol spellings such as `>=` are accepted on the way in and stored in the canonical spelling shown here.",
                "type": "string",
                "enum": [
                  "greater_than",
                  "greater_than_or_equal",
                  "less_than",
                  "less_than_or_equal",
                  "equal",
                  "not_equal",
                  "between",
                  "not_between",
                  "in",
                  "not_in",
                  "contains",
                  "not_contains",
                  "starts_with",
                  "ends_with",
                  "before",
                  "after",
                  "is_empty",
                  "is_not_empty"
                ],
                "example": "greater_than_or_equal"
              },
              "value": {
                "description": "What to compare against. A number, string, boolean or RFC 3339 timestamp for a single value comparison; a two entry `[low, high]` list for `between` and `not_between`; a non-empty list for `in` and `not_in`. Omitted for `is_empty` and `is_not_empty`.",
                "example": 100000
              }
            }
          }
        },
        "min_notional_usd": {
          "description": "Shorthand for a `notional_usd` at-or-above condition, kept for compatibility. It is stored as a condition, and it is mirrored back here as the loosest notional lower bound the config carries.",
          "type": "number",
          "example": 100000
        },
        "params": {
          "description": "Parameter values for the event type, keyed by the parameter names it declares. A declared parameter you leave out is stored at its default. A declared parameter may also be written at the top level of the config.",
          "type": "object",
          "additionalProperties": true,
          "example": {
            "max_age_s": 3600
          }
        },
        "symbols": {
          "description": "Instrument symbols to match. Omit to match every symbol.",
          "type": "array",
          "items": {
            "type": "string"
          },
          "example": [
            "BTC",
            "ETH"
          ]
        },
        "venue": {
          "description": "Venue or venues to match, from the event type's `venues` list. Accepts a single string, a pipe separated string or a list. Omit to match every covered venue.",
          "oneOf": [
            {
              "type": "string"
            },
            {
              "type": "array",
              "items": {
                "type": "string"
              }
            }
          ],
          "example": "hyperliquid"
        }
      }
    },
    "event_type": {
      "description": "Event type to evaluate.",
      "type": "string",
      "example": "market.liquidation"
    },
    "lookback_days": {
      "description": "Days of history to evaluate, ending now.",
      "type": "integer",
      "format": "int64",
      "default": 7,
      "minimum": 1,
      "maximum": 30,
      "example": 7
    }
  }
}
```

## Response Contracts

### Status 200

How often the configuration would have fired

#### application/json

```json theme={"theme":"github-dark"}
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "estimateWebhookSubscription response 200",
  "description": "API response containing a subscription estimate.",
  "type": "object",
  "properties": {
    "data": {
      "description": "How often a would-be subscription would have fired over the requested window. Nothing is stored and no delivery is sent.",
      "type": "object",
      "required": [
        "basis",
        "days",
        "event_type",
        "ladder",
        "per_day",
        "per_day_max",
        "per_day_p50",
        "sample",
        "total",
        "window"
      ],
      "properties": {
        "basis": {
          "description": "How the estimate was produced, so the numbers can be read for what they are.",
          "type": "object",
          "required": [
            "mode"
          ],
          "properties": {
            "mode": {
              "description": "`exact` counted every occurrence in the window. `sampled` scaled the counts from a capped scan, and the note says by how much. `replayed` re-ran a windowed rule over history at your own parameters.",
              "type": "string",
              "enum": [
                "exact",
                "sampled",
                "replayed"
              ],
              "example": "exact"
            },
            "note": {
              "description": "What qualifies the numbers, when anything does.",
              "type": "string",
              "nullable": true
            }
          }
        },
        "days": {
          "description": "Days the answer covers. Shorter than requested when the event type carries a shorter cap.",
          "type": "integer",
          "format": "int64",
          "example": 7
        },
        "distribution": {
          "description": "Quantiles of the primary metric. Null when the type has no primary metric or nothing matched.",
          "nullable": true,
          "allOf": [
            {
              "description": "Quantiles of the primary metric over the matched occurrences, for choosing a threshold against real history.",
              "type": "object",
              "required": [
                "max",
                "n",
                "p50",
                "p90",
                "p99"
              ],
              "properties": {
                "max": {
                  "description": "Largest value seen.",
                  "type": "number",
                  "example": 4210000
                },
                "n": {
                  "description": "Occurrences the quantiles are computed over.",
                  "type": "integer",
                  "format": "int64",
                  "example": 842
                },
                "p50": {
                  "description": "Median.",
                  "type": "number",
                  "example": 18400
                },
                "p90": {
                  "description": "90th percentile.",
                  "type": "number",
                  "example": 132000
                },
                "p99": {
                  "description": "99th percentile.",
                  "type": "number",
                  "example": 910000
                }
              }
            }
          ]
        },
        "event_type": {
          "description": "Event type that was evaluated.",
          "type": "string",
          "example": "market.liquidation"
        },
        "ladder": {
          "description": "Ascending. Empty when there is no primary metric.",
          "type": "array",
          "items": {
            "description": "One rung of the threshold ladder: the daily rate the same configuration would have had at a different threshold.",
            "type": "object",
            "required": [
              "per_day",
              "value"
            ],
            "properties": {
              "per_day": {
                "description": "Deliveries a day at that threshold, everything else unchanged.",
                "type": "number",
                "example": 3.4
              },
              "value": {
                "description": "Threshold on the primary metric.",
                "type": "number",
                "example": 250000
              }
            }
          }
        },
        "per_day": {
          "description": "One entry per day, oldest first, zero filled. The last entry ends at the moment of the request.",
          "type": "array",
          "items": {
            "description": "One 24 hour bin of the estimate window.",
            "type": "object",
            "required": [
              "count",
              "date"
            ],
            "properties": {
              "count": {
                "description": "Occurrences that would have been delivered in the bin.",
                "type": "integer",
                "format": "int64",
                "example": 12
              },
              "date": {
                "description": "UTC date the bin ends on.",
                "type": "string",
                "format": "date",
                "example": "2026-09-19"
              }
            }
          }
        },
        "per_day_max": {
          "description": "Busiest day in the window.",
          "type": "integer",
          "format": "int64",
          "example": 26
        },
        "per_day_p50": {
          "description": "Median deliveries a day across the window.",
          "type": "number",
          "example": 11
        },
        "primary_metric": {
          "description": "The metric the ladder and the distribution are about. Null when the type has none.",
          "type": "string",
          "nullable": true,
          "example": "notional_usd"
        },
        "sample": {
          "description": "Newest matches first, in the same shape the dry-run returns.",
          "type": "array",
          "items": {
            "description": "One occurrence that would have been delivered, in the shape the delivered payload carries.",
            "type": "object",
            "required": [
              "data",
              "observed_at_estimate"
            ],
            "properties": {
              "data": {
                "description": "The occurrence body, the same `data` a delivery would carry.",
                "type": "object",
                "additionalProperties": true
              },
              "observed_at_estimate": {
                "description": "The occurrence's own timestamp. A real delivery's `observed_at` is this plus the time it takes to see the occurrence.",
                "type": "string",
                "format": "date-time"
              }
            }
          }
        },
        "total": {
          "description": "Occurrences that would have been delivered across the window.",
          "type": "integer",
          "format": "int64",
          "example": 84
        },
        "window": {
          "description": "The window a preview vouches for. It can start later than the one that was asked for when a scan reached its row cap.",
          "type": "object",
          "required": [
            "from",
            "to"
          ],
          "properties": {
            "from": {
              "description": "Start of the window the answer covers.",
              "type": "string",
              "format": "date-time"
            },
            "to": {
              "description": "End of the window, which is the moment of the request.",
              "type": "string",
              "format": "date-time"
            }
          }
        }
      }
    },
    "success": {
      "type": "boolean",
      "example": true
    }
  }
}
```

### Status 400

Invalid request

#### application/json

```json theme={"theme":"github-dark"}
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "estimateWebhookSubscription 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"
    },
    "request_id": {
      "description": "Unique request ID for support",
      "type": "string",
      "format": "uuid"
    }
  }
}
```

##### OpenAPI example

```json theme={"theme":"github-dark"}
{
  "code": 400,
  "error": "Failed to deserialize query string: limit: invalid digit found in string",
  "error_code": "invalid_query_params",
  "request_id": "3f2a9c71-5b0e-4d68-9a4c-7e1d2b6f8a05"
}
```

### Status 401

Authentication required

#### application/json

```json theme={"theme":"github-dark"}
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "estimateWebhookSubscription 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"
    },
    "request_id": {
      "description": "Unique request ID for support",
      "type": "string",
      "format": "uuid"
    }
  }
}
```

##### OpenAPI example

```json theme={"theme":"github-dark"}
{
  "code": 401,
  "error": "Missing or invalid API key. Provide X-API-Key header."
}
```

### Status 429

Rate limit exceeded

#### application/json

```json theme={"theme":"github-dark"}
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "estimateWebhookSubscription 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"
    },
    "request_id": {
      "description": "Unique request ID for support",
      "type": "string",
      "format": "uuid"
    }
  }
}
```

##### OpenAPI example

```json theme={"theme":"github-dark"}
{
  "code": 429,
  "error": "Rate limit exceeded"
}
```

### Status 503

The estimate could not be produced right now. Retry shortly.

#### application/json

```json theme={"theme":"github-dark"}
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "estimateWebhookSubscription response 503",
  "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"
    },
    "request_id": {
      "description": "Unique request ID for support",
      "type": "string",
      "format": "uuid"
    }
  }
}
```

##### OpenAPI example

```json theme={"theme":"github-dark"}
{
  "code": 503,
  "error": "estimate is temporarily unavailable",
  "request_id": "3f2a9c71-5b0e-4d68-9a4c-7e1d2b6f8a05"
}
```