# 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?

| Research question                                        | Required inputs                                                                                                                                                                                                   |
| -------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Individual executions and fees                           | [Fills](https://www.dwellir.com/docs/hyperliquid/data-catalog/node-feeds/fills)                                                                                                                                                          |
| TWAP lifecycle and execution slices                      | [TWAP statuses](https://www.dwellir.com/docs/hyperliquid/data-catalog/node-feeds/twap-statuses) plus fills                                                                                                                               |
| TWAP submissions, cancellations, and execution responses | [Blocks](https://www.dwellir.com/docs/hyperliquid/data-catalog/node-feeds/blocks), including signed actions and responses                                                                                                                |
| Orders that cancel or reject without fills               | [Order statuses](https://www.dwellir.com/docs/hyperliquid/data-catalog/node-feeds/order-statuses), with blocks for action-level analysis                                                                                                 |
| Reconstruct an order book                                | [Generated snapshot](https://www.dwellir.com/docs/hyperliquid/data-catalog/derived/book-snapshots) plus ordered [raw book diffs](https://www.dwellir.com/docs/hyperliquid/data-catalog/node-feeds/book-diffs)                                                   |
| Native node state at a checkpoint                        | [Periodic ABCI state](https://www.dwellir.com/docs/hyperliquid/data-catalog/node-feeds/abci-states), with a matching binary decoder                                                                                                      |
| Applied mark or oracle prices at a past block            | Periodic ABCI state plus `replica_cmds` [blocks](https://www.dwellir.com/docs/hyperliquid/data-catalog/node-feeds/blocks), replayed with a Hyperliquid node. See [historical mark prices](#can-i-get-every-historical-mark-price-update) |

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](https://www.dwellir.com/docs/hyperliquid/historical-data#compressed-size-and-file-count) 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:

| Field                                          | Purpose                                                     |
| ---------------------------------------------- | ----------------------------------------------------------- |
| Feed, object key, and format                   | Select the correct parser and identify each file.           |
| Compressed bytes per object and combined total | Verify download volume.                                     |
| File count and listing time in UTC             | Reproduce the inventory measurement.                        |
| First and last record positions                | Check actual record bounds against the requested selection. |
| Checksum value and algorithm                   | Verify transferred bytes.                                   |
| Schema or decoder version                      | Reproduce decoding, especially for binary state.            |
| Known gaps, overlaps, and backfilled intervals | Separate stored coverage from verified completeness.        |

An [S3 ETag](https://docs.aws.amazon.com/AmazonS3/latest/API/API_Object.html) 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](https://www.dwellir.com/docs/hyperliquid/historical-data#s3-bucket-coverage) gives date bounds, not a completeness certificate.

## Which timestamp should I use?

| Field                  | Meaning                                                                                        |
| ---------------------- | ---------------------------------------------------------------------------------------------- |
| Envelope `block_time`  | The source block timestamp.                                                                    |
| Envelope `local_time`  | The source record's local wall-clock timestamp. It is not your application's receipt time.     |
| Fill `time`            | Execution time in Unix milliseconds.                                                           |
| TWAP `state.timestamp` | TWAP creation time in Unix milliseconds.                                                       |
| V3 `Record.timestamp`  | Transport cursor in Unix milliseconds. Use the method's documented source timestamp semantics. |

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](https://www.dwellir.com/docs/hyperliquid/hyperliquid-index/fills/user-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](https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/websocket/subscriptions).
Preserve separate account and order records because one match can include several makers.

See [the fill schema and liquidation rules](https://www.dwellir.com/docs/hyperliquid/stream_fills#liquidation-data) for field details.

## Can I get every historical mark-price update?

No archive prefix stores mark or oracle prices as their own records. Hyperliquid applies them inside node state, and the node does not write them to a separate file.

To get the applied values at a past block, start a Hyperliquid node from a [periodic ABCI state](https://www.dwellir.com/docs/hyperliquid/data-catalog/node-feeds/abci-states) checkpoint. Then replay the `replica_cmds` blocks that follow it. ABCI state coverage starts on `2026-04-14`, so earlier blocks have no checkpoint to start from.

Validator oracle submissions appear in `replica_cmds` as [`SetGlobalAction`](https://www.dwellir.com/docs/hyperliquid/SetGlobalAction) payloads. These are inputs, not the mark price that the protocol applied.

HIP-3 deployers submit `oraclePxs` and `markPxs` for their own perp dexes through the `setOracle` field of [`perpDeploy`](https://www.dwellir.com/docs/hyperliquid/perpDeploy) actions. Every `setOracle` in the 2026-10-21 sample names a HIP-3 dex (`io` or `xyz`). These are inputs too, not applied mark prices.

To check which prefix holds a field, see "Observed fields" on each [data catalog](https://www.dwellir.com/docs/hyperliquid/data-catalog) page. Each tree lists the fields seen in one real archive object.

[`StreamActiveAssetCtx`](https://www.dwellir.com/docs/hyperliquid/stream_active_asset_ctx) reports live `mark_px` and `oracle_px`. It has no historical replay and drops obsolete frames when a subscriber lags. Its `time` is the endpoint update time, not a block timestamp. A recording of this stream is therefore not a complete, block-numbered update log.

A liquidation fill carries `markPx` in its `liquidation` object. That value applies to that liquidation only.

## 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](https://www.dwellir.com/docs/hyperliquid/clearinghouse-state) 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](https://www.dwellir.com/terms-of-service). If the docs and Terms differ, the legally binding Terms control.

The [Terms of Service](https://www.dwellir.com/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.
