Data Downloads opens on categories, not on a list of files. Pick the kind
of data you want, then the dataset, then build a query.
The four categories
| Category | What is in it |
|---|---|
| Raw chain data | Every event log the chain emitted, filtered by signature, address, block or date |
| DEXs and prices | Hourly OHLC and volume per pool |
| Lending protocols | Health factors, liquidations, absorptions and Maker vaults, per protocol |
| Events | The curated timeline of hacks, depegs, regulation and upgrades, as one registry dataset |
One query manager, everywhere
Every dataset uses the same interface, so once you have exported one you know
how to export all of them. What appears depends on the dataset:
- Protocols, where a dataset covers more than one.
- A date range, where the dataset has a timestamp.
- A block range, where it has a block number. Some datasets are per-block
snapshots and are bounded by block rather than by date — health factors and
Maker vaults, for instance, exist at a snapshot block and not at a moment in
time. - An address list, where the dataset has one address column worth
filtering on: price bars take pool addresses, one per line, in either
casing. The raw log table keeps its richer sender / recipient / emitter
filters. - Variables: tick the columns you want, with a note on each where the units
are not obvious. - The registry’s own filters, for the event timeline: categories in place
of protocols, a chain, and whether the anchors are confirmed on chain. The
registry lives beside the platform rather than in the warehouse, so the
app writes that export itself; the request, the quota and the download are
the same as for every other dataset, and the timeline links here with its
filter already set once a filter is too large for its direct CSV.
Sizing is free; downloading is not
You can build any query and see how many rows it comes to without a
subscription. This is deliberate — you should be able to find out whether the
data answers your question before paying for it. The subscription is required
at the moment you run the export.
Every export is metered against your monthly allowance, capped at 50 million
rows, and you are emailed when the file is ready. The row count in that email
is counted after the export, over the same query; the figure shown while you
build is an estimate and is kept as one.
Why some datasets cannot be combined
Compound v3 absorptions are not liquidations with different column names.
In Compound the protocol takes the debt onto its own balance sheet rather than
a liquidator repaying it, so an absorption has no liquidator and no bonus paid
to one. Exporting the two together would produce a table with empty columns
that look like missing data rather than an inapplicable concept.
Morpho’s markets are isolated — one collateral, one loan asset, one oracle
each — so a row is scoped to a market rather than to a shared pool.
Aave V3 and its forks (Spark) do share one schema, and can be exported
together in one file.
If you ask for a protocol a dataset does not cover, you get a refusal that
explains why rather than a merged table.
What the exports guarantee
- An unpriced row is null, with a reason — never zero. A zero would look
like a real measurement. - Hashes and addresses are complete. Never truncated, so you can match them
against your own logs by eye. - A partial panel says so rather than looking finished.
- Every file carries its checksum. See below.
The checksum, and citing an export
When an export completes, the file is read back and hashed: the download page
shows the SHA-256 of the gzip file exactly as it was written, and the
download itself carries it in an X-Checksum-SHA256 header (the API’s
/datasets/requests/:id and /download endpoints return it as
checksum_sha256). Check the file you hold with:
shasum -a 256 export.csv.gz
The two either match or they do not. A mismatch means the file was altered,
truncated in transit, or is not the file this export produced.
The page also gives a citation line for the export, naming the dataset,
the request, the day it was produced, the row count and the digest. Cite that
line rather than the download link: the link expires after seven days, the
digest is permanent, and anyone holding the file can verify it against the
citation without asking us.
Exports run over the bulk table, which is confirmed 64 blocks behind the
chain. If the daily completeness check has found a gap in that table, the
range is listed on the status page until the ingester refills it,
and an export over that range may be missing rows until then.
Citing a query without exporting it
The request page also offers Cite this query and, for an organization you
admin, Pin for the class. Both hash the canonical CSV of exactly the query
you built (the columns in the catalogue’s order, the rows by the dataset’s
natural key, the block range pinned) and neither needs the export to run. The
citation resolves publicly at /citations/<hash> with the metadata a library
expects; the classroom pin stores the bytes so every student downloads the
same file. See citations and classroom.
Dataset releases
On the first of each month every dataset here (the raw log table excepted:
it is 7.2 billion rows and not something anyone cites whole) is versioned as a
release: its block range or last date, its row count, and the SHA-256 of
its full canonical export, streamed through the digest rather than held. The
latest release per dataset is listed at the top of this page, and each
dataset’s page lists its history. Releases are labelled YYYY.MM.
A citation names the release its block range falls inside, so two papers can
say whether they used the same edition. An export is not tied to a release:
it runs over the table as it stands, and its own checksum is what identifies
the file.
Starting from a tracking page
The CSV button on a tracking page still works and still downloads what that
page is showing. It is the right entry point when you are already looking at
the data; the catalogue is the right one when you know what you want.