Estimate a webhook subscription

curl --request POST \
  --url https://api.0xarchive.io/v1/webhooks/subscriptions/estimate \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "event_type": "market.liquidation"
}
'

import requests

url = "https://api.0xarchive.io/v1/webhooks/subscriptions/estimate"

payload = { "event_type": "market.liquidation" }
headers = {
    "X-API-Key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'X-API-Key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({event_type: 'market.liquidation'})
};

fetch('https://api.0xarchive.io/v1/webhooks/subscriptions/estimate', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.0xarchive.io/v1/webhooks/subscriptions/estimate"

	payload := strings.NewReader("{\n  \"event_type\": \"market.liquidation\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-API-Key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

{
  "success": true,
  "data": {
    "event_type": "market.liquidation",
    "window": {
      "from": "2023-11-07T05:31:56Z",
      "to": "2023-11-07T05:31:56Z"
    },
    "days": 7,
    "total": 84,
    "per_day": [
      {
        "date": "2026-09-19",
        "count": 12
      }
    ],
    "per_day_p50": 11,
    "per_day_max": 26,
    "ladder": [
      {
        "value": 250000,
        "per_day": 3.4
      }
    ],
    "sample": [
      {
        "observed_at_estimate": "2023-11-07T05:31:56Z",
        "data": {}
      }
    ],
    "basis": {
      "mode": "exact",
      "note": "<string>"
    },
    "primary_metric": "notional_usd",
    "distribution": {
      "n": 842,
      "p50": 18400,
      "p90": 132000,
      "p99": 910000,
      "max": 4210000
    }
  }
}

{
  "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"
}

{
  "code": 401,
  "error": "Missing or invalid API key. Provide X-API-Key header."
}

{
  "code": 429,
  "error": "Rate limit exceeded"
}

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

POST

https://api.0xarchive.io

webhooks

subscriptions

estimate

Estimate a webhook subscription

curl --request POST \
  --url https://api.0xarchive.io/v1/webhooks/subscriptions/estimate \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "event_type": "market.liquidation"
}
'

import requests

url = "https://api.0xarchive.io/v1/webhooks/subscriptions/estimate"

payload = { "event_type": "market.liquidation" }
headers = {
    "X-API-Key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'X-API-Key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({event_type: 'market.liquidation'})
};

fetch('https://api.0xarchive.io/v1/webhooks/subscriptions/estimate', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.0xarchive.io/v1/webhooks/subscriptions/estimate"

	payload := strings.NewReader("{\n  \"event_type\": \"market.liquidation\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-API-Key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

{
  "success": true,
  "data": {
    "event_type": "market.liquidation",
    "window": {
      "from": "2023-11-07T05:31:56Z",
      "to": "2023-11-07T05:31:56Z"
    },
    "days": 7,
    "total": 84,
    "per_day": [
      {
        "date": "2026-09-19",
        "count": 12
      }
    ],
    "per_day_p50": 11,
    "per_day_max": 26,
    "ladder": [
      {
        "value": 250000,
        "per_day": 3.4
      }
    ],
    "sample": [
      {
        "observed_at_estimate": "2023-11-07T05:31:56Z",
        "data": {}
      }
    ],
    "basis": {
      "mode": "exact",
      "note": "<string>"
    },
    "primary_metric": "notional_usd",
    "distribution": {
      "n": 842,
      "p50": 18400,
      "p90": 132000,
      "p99": 910000,
      "max": 4210000
    }
  }
}

{
  "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"
}

{
  "code": 401,
  "error": "Missing or invalid API key. Provide X-API-Key header."
}

{
  "code": 429,
  "error": "Rate limit exceeded"
}

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

API key required. Send X-API-Key with this request. See REST authentication.

Shared request rules

Machine schema

Open the generated operation schema for machine-readable request and response details.

Authorizations

X-API-Key

string

header

required

API key for authentication. Get yours at https://0xarchive.io/dashboard

Body

application/json

A would-be subscription to evaluate against history. Same shape as a create, without the endpoint, plus the window.

event_type

string

required

Event type to evaluate.

Example:

"market.liquidation"

config

object

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.

Hide child attributes

config.venue

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.

Example:

"hyperliquid"

config.symbols

string[]

Instrument symbols to match. Omit to match every symbol.

Example:

["BTC", "ETH"]

config.addresses

string[]

Wallets to match, for an address scoped event type. Every address must already be on your watched list. Omit to match all of them.

Example:

[
  "0x6b9e773128f453f5c2c60935ee2de2cbc5390a24"
]

config.params

object

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.

Example:

{ "max_age_s": 3600 }

config.conditions

object[]

Conditions on the event's metrics, all of which must hold for a delivery. At most 16 per subscription.

Hide child attributes

config.conditions.metric

string

required

A metric declared by the event type.

Example:

"notional_usd"

config.conditions.op

enum<string>

required

Comparison to apply. Symbol spellings such as >= are accepted on the way in and stored in the canonical spelling shown here.

Available options:

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"

config.conditions.value

any

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

config.min_notional_usd

number

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.

Example:

100000

lookback_days

integer<int64>

default:7

Days of history to evaluate, ending now.

Required range: 1 <= x <= 30

Example:

7

Response

How often the configuration would have fired

API response containing a subscription estimate.

success

boolean

Example:

true

data

object

How often a would-be subscription would have fired over the requested window. Nothing is stored and no delivery is sent.

Hide child attributes

data.event_type

string

required

Event type that was evaluated.

Example:

"market.liquidation"

data.window

object

required

The window a preview vouches for. It can start later than the one that was asked for when a scan reached its row cap.

Hide child attributes

data.window.from

string<date-time>

required

Start of the window the answer covers.

data.window.to

string<date-time>

required

End of the window, which is the moment of the request.

data.days

integer<int64>

required

Days the answer covers. Shorter than requested when the event type carries a shorter cap.

Example:

7

data.total

integer<int64>

required

Occurrences that would have been delivered across the window.

Example:

84

data.per_day

object[]

required

One entry per day, oldest first, zero filled. The last entry ends at the moment of the request.

Hide child attributes

data.per_day.date

string<date>

required

UTC date the bin ends on.

Example:

"2026-09-19"

data.per_day.count

integer<int64>

required

Occurrences that would have been delivered in the bin.

Example:

12

data.per_day_p50

number

required

Median deliveries a day across the window.

Example:

11

data.per_day_max

integer<int64>

required

Busiest day in the window.

Example:

26

data.ladder

object[]

required

Ascending. Empty when there is no primary metric.

Hide child attributes

data.ladder.value

number

required

Threshold on the primary metric.

Example:

250000

data.ladder.per_day

number

required

Deliveries a day at that threshold, everything else unchanged.

Example:

3.4

data.sample

object[]

required

Newest matches first, in the same shape the dry-run returns.

Hide child attributes

data.sample.observed_at_estimate

string<date-time>

required

The occurrence's own timestamp. A real delivery's observed_at is this plus the time it takes to see the occurrence.

data.sample.data

object

required

The occurrence body, the same data a delivery would carry.

data.basis

object

required

How the estimate was produced, so the numbers can be read for what they are.

Hide child attributes

data.basis.mode

enum<string>

required

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.

Available options:

exact,

sampled,

replayed

Example:

"exact"

data.basis.note

string | null

What qualifies the numbers, when anything does.

data.primary_metric

string | null

The metric the ladder and the distribution are about. Null when the type has none.

Example:

"notional_usd"

data.distribution

object | null

Quantiles of the primary metric. Null when the type has no primary metric or nothing matched.

Hide child attributes

data.distribution.n

integer<int64>

required

Occurrences the quantiles are computed over.

Example:

842

data.distribution.p50

number

required

Median.

Example:

18400

data.distribution.p90

number

required

90th percentile.

Example:

132000

data.distribution.p99

number

required

99th percentile.

Example:

910000

data.distribution.max

number

required

Largest value seen.

Example:

4210000

Last modified on September 20, 2026

API reference

SDKs & tooling

AI & agents

Estimate a webhook subscription

Authorizations

Body

Response