Hyperliquid archive research and validation

Choose the inputs that answer your research question. Validate their range and schema before treating the files as a complete dataset.

Which files answer my question?

A fills-only sample excludes orders that never execute. A TWAP created before your selection can execute inside it without an in-range creation event.

Use an earlier state seed or earlier lifecycle records when your analysis needs activity already in progress at the start.

How do I define the range and download size?

Specify the feed prefixes and UTC bounds. Use an inclusive start and exclusive end to avoid overlapping adjacent selections.

For September 2026, select 2026-09-01T00:00:00Z through, but excluding, 2026-10-01T00:00:00Z.

Hourly files can contain records outside a partial-hour selection. Filter records by the relevant event or block timestamp after decompression.

Use the archive coverage table and size estimator to plan compressed storage and downloads before purchase.

File count does not establish record count or completeness. Do not assume one file per hour or infer missing events from object totals alone.

What should a validation manifest contain?

Record these fields for each selection:

An S3 ETag is not always an MD5 checksum. Compare checksums calculated with the same algorithm.

Decompress each file and parse every record. Check ordering and duplicates using the feed's sequential position and event identity.

Some filtered feeds omit blocks with no matching events. A jump in those positions alone does not prove missing source data.

Treat an unverified interval as unverified. The coverage table gives date bounds, not a completeness certificate.

Which timestamp should I use?

Native timestamp strings can omit the trailing Z. Parse the documented source layout as UTC rather than your machine's local timezone.

Preserve nanosecond precision when source strings provide it. Do not interpret Unix milliseconds as seconds.

Replaying a record does not establish when a client originally received it. S3 modification time also does not establish event time or live arrival latency.

How do I join TWAP lifecycle events to executions?

Join lifecycle twap_id to the fill payload's twapId. Retain the account and market alongside the identifier when validating the join.

The fill's oid identifies a child order. It does not replace the parent TWAP identifier.

state.executedSz and state.executedNtl describe aggregate execution at a lifecycle boundary. They are not a continuously sampled progress series.

Use fills to calculate executions between lifecycle events. Preserve partial, cancelled, and zero-fill orders when the available lifecycle or action records identify them.

The status feed is not a complete log of every TWAP submission attempt. Decode twapOrder and twapCancel from blocks and inspect their execution responses.

The documented TWAP action has duration, size, side, reduce-only, and randomization fields. It does not contain a stopPx trigger field.

For account queries, use TWAP slice fills. Fills-derived summaries cannot establish a complete zero-fill population.

How do I identify the liquidated side of a trade?

Inspect the fill's optional liquidation object. It includes liquidatedUser, markPx, and method.

Counterparty fills can carry liquidation metadata too. Match the event's account to liquidatedUser to identify the liquidated side.

For book-absorbed liquidations, crossed: true identifies the liquidated taker side. Do not require that flag to classify every liquidation method.

Keep the source method value, including market or backstop. Do not classify every close as a liquidation or infer auto-deleveraging from dir alone.

Within one block, group a trade match by (coin, tid). Across blocks, include block_number or block_time in the match key.

Hyperliquid documents (block_time, coin, tid) as the globally unique trade identity. Preserve separate account and order records because one match can include several makers.

See the fill schema and liquidation rules for field details.

Can I reconstruct account risk from book snapshots?

No. A generated order-book snapshot contains book state. It does not contain a complete account ledger or margin state.

Fills alone do not establish deposits, withdrawals, funding, transfers, collateral, or every state transition that affects account risk.

Periodic ABCI state is binary RMP, encoded with MessagePack. Decompress LZ4 first, then use a decoder that matches the source node-state schema.

An arbitrary requested timestamp can fall between snapshots. Reaching that state requires the earlier checkpoint and the intervening protocol transitions.

Use the node-state schema and asset mappings from that period. Account-risk replay also needs the protocol transitions after the checkpoint.

For current account state, use clearinghouseState and related Info methods. Current responses do not reconstruct past account state.

May I store, redistribute, or sell the data?

This section summarizes the Terms of Service. If the docs and Terms differ, the legally binding Terms control.

The Terms of Service permit storage, commercial use, distribution, and sale of Service Data and derived products.

They also permit resale through infrastructure you control. Keep Dwellir-issued credentials private and remain responsible for account usage and limits.

These permissions do not override third-party rights. After service termination, you may retain and commercialize data lawfully retrieved beforehand, subject to the terms.