Estimate a webhook subscription

Authorizations

X-API-Key

string

header

required

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

Headers

0xArchive-Version

enum<string>

Selects the 2026-10 response contract. Send 2026-10-01; any dated version on or after it selects the same shapes. Without the header every response keeps its existing shape. With it:

The data quality routes, /v1/status/coverage and /v1/symbols answer the standard {success, data, meta} envelope.
Record times that are integer milliseconds by default become RFC 3339 UTC strings with millisecond precision, and the integer moves to a *_ms field: L4 resting-order timestamp (timestamp_ms), CVD buckets, HIP-3 oracle reads, Lighter and Lighter on Robinhood Chain liquidations and liquidation volume. Levels and trigger-levels snapshot_ts become RFC 3339 with snapshot_ts_ms.
Error bodies carry the contract error_code names: invalid_parameter instead of invalid_query_params and invalid_path_params, historical_depth_exceeded instead of history_window_exceeded, and historical_range_exceeded instead of request_range_exceeded; a malformed cursor that fails to parse answers 400 invalid_cursor instead of invalid_query_params. With 0xArchive-Version: 2026-10-01, malformed cursors on trades, liquidations, L2 and L4 diffs, order history, TP/SL and order-flow routes answer 400 invalid_cursor. Without the header, the first six route families treat a malformed cursor as no cursor and return the first page; order flow answers 400 invalid_query_params. Malformed trade time inputs answer 400 invalid_time_range with the header and 400 invalid_query_params without it.

The response echoes the selected version in its own 0xArchive-Version header.

Available options:

2026-10-01

Example:

"2026-10-01"

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

Rule configuration to evaluate. filters is accepted as an alias.

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

filters

object

Alias of config. Send one or the other.

Hide child attributes

filters.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"

filters.symbols

string[]

Instrument symbols to match. Omit to match every symbol.

Example:

["BTC", "ETH"]

filters.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"
]

filters.params

object

Example:

{ "max_age_s": 3600 }

filters.conditions

object[]

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

Hide child attributes

filters.conditions.metric

string

required

A metric declared by the event type.

Example:

"notional_usd"

filters.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"

filters.conditions.value

any

Example:

100000

filters.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. Between 1 and 30; a value outside that range is refused with a 400. Some event types evaluate a shorter window (for example 7 days for account.fill); the response's days and basis.note then say so.

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

Guides

API reference

Estimate a webhook subscription

Authorizations

Headers

Body

Response