BlogProduct

How to Query Reservoir's Hyperliquid Data

Explore Reservoir's Hyperliquid fills, candles, snapshots and order books, with tested examples that pull only the markets, wallets and time ranges you need.

HydromancerTeam
How to Query Reservoir's Hyperliquid Data

Say ETH drops sharply yesterday and you want to know what happened. Or you have a trading idea and want to see how it would have done last month before you put money on it. Or you want to know what a particular wallet was holding last week.

All three need historical data, but not the same data. Individual trades tell you what happened during the drop. Price candles are enough to test a trading idea. A snapshot shows what a wallet held at a given moment. Pick the right one and you skip pulling a lot of data you’ll never look at.

One thing to know first: Reservoir is historical data, up to yesterday. Each UTC day is added the next morning around 10:00–12:00 UTC once it’s over, so today’s trades aren’t in it yet. If you want the freshest data from as recently as an hour ago as soon as possible, you’ll need the Hydromancer API instead.

Reservoir is Hydromancer's archive of Hyperliquid history. It has trades (called fills), price candles, snapshots of positions and balances, and order-book snapshots, all stored on Amazon S3.

This guide goes through each one: what it is, what you'd use it for, and how to pull out only the piece you need. Each section starts with the kind of question you'd bring to it.

The field lists and code come after, so you can skip those until you're ready.

What format is Reservoir data in?

Reservoir stores everything as Parquet files.

Think of Parquet as a compressed table built for analysis. You don't open it like a spreadsheet, but tools such as DuckDB can read it directly. Fills and candles are stored as rows of trades or price bars.

Snapshots record positions, balances or order-book levels at the moment they were taken.

The useful part is that DuckDB can query a Parquet file while it's still sitting on S3. It reads only the columns you ask for and can often skip parts of the file that can't match your filter.

You then save the result on your computer as a smaller Parquet file, or as a CSV you can open in a spreadsheet.

Choose the dataset that matches your question

What do you want to know? Start with What one row represents
What trades happened, and at what prices?FillsOne trade, seen from one wallet's side
How did the price and trading activity change?CandlesOne second of a market's prices and volume
Which positions were open at a given moment?Perp position snapshotsOne wallet's position in one market
Which spot tokens did wallets hold?Spot balance snapshotsOne wallet's balance of one token
How much margin backed an account's positions?Account-value snapshotsOne wallet's margin and exposure on one trading venue
What bids and asks were waiting at a given minute?Order-book snapshotsThe buy and sell levels for one market at one moment

A quick note on terms. "Perps" are perpetual futures: contracts that follow a token's price and never expire. "Spot" means holding the token itself.

The SQL examples below all use the Python setup in "How to query S3 and save only the result", further down. If you're not running code yet, you can skip them and still follow along.

Find your way around Reservoir

Reservoir is one public S3 bucket, s3://hydromancer-reservoir, in the Tokyo region (ap-northeast-1). It's set to requester pays, so you need an AWS account, and AWS bills you for what you download.

Inside the bucket there are two main folders:

• global/ has everything in one place: every venue, plus spot and HIP-4 prediction markets. Use it when you want the whole market.
• by_dex/ splits the same data by venue: one folder for Hyperliquid's own perp markets and one for each HIP-3 venue. Use it when you only care about one venue, because the files are smaller.

code
s3://hydromancer-reservoir/
├── global/
│   ├── fills/raw/            every fill on every venue (perps, spot, HIP-4)
│   ├── fills/spot/           spot fills: all/ and builder_fills/
│   ├── fills/outcome/        HIP-4 fills: all/ and builder_fills/
│   ├── candles/1s/           1-second candles for every market
│   └── snapshots/            perp/all/, spot/, account_values/
└── by_dex/{venue}/
    ├── fills/perp/           all/, liquidations/, adl/, builder_fills/, twap_fills/
    ├── candles/1s/
    ├── snapshots/perp/
    └── orderbook/1m/         perps/ (Hyperliquid also has spot/ and outcome/)

Every dataset is split into one folder per day, named like date=2026-10-08. Dates are in UTC.

Which folder is which venue

Folder Venue Data from Data until
hyperliquidHyperliquid's own perp markets28 Jul 2025ongoing
xyzTrade[XYZ]13 Oct 2025ongoing
flxFelix13 Nov 202520 Jun 2026 (markets closed)
vntlVentuals13 Nov 202519 Jun 2026 (markets closed)
hynaHyENA3 Dec 20252 Sep 2026 (markets closed)
kmMarkets.xyz (old folder)12 Jan 202617 Jun 2026 (continues in mkts)
cashDreamcash20 Jan 20262 Jul 2026 (markets closed)
paraParagon1 Apr 2026ongoing
mktsMarkets.xyz (current folder)1 Jul 2026ongoing
ioEntropy19 Aug 2026ongoing

Some venues have closed their markets. Their folders stay in the bucket, with history up to their last trading day. Markets.xyz moved from km to mkts in mid-2026, so read both folders for its full history.

To see the folders yourself:

code
aws s3 ls s3://hydromancer-reservoir/by_dex/ --request-payer requester

When each dataset starts

Dataset Folder Starts
Perp fills (Hyperliquid)by_dex/hyperliquid/fills/perp/all/28 Jul 2025
TWAP fills…/fills/perp/twap_fills/2 Aug 2025
Spot fillsglobal/fills/spot/all/28 Jul 2025
HIP-4 prediction-market fillsglobal/fills/outcome/all/2 May 2026
1-second candlesglobal/candles/1s/ or by_dex/{venue}/candles/1s/31 Jul 2025
Snapshotsglobal/snapshots/…29 Jul 2025 (1 Aug 2025 and 25 Oct–14 Dec 2025 are missing)
Order books, Hyperliquid perps and spotby_dex/hyperliquid/orderbook/1m/perps/ and spot/15 Dec 2025
Order books, HIP-4by_dex/hyperliquid/orderbook/1m/outcome/2 May 2026

HIP-3 venues start on their own dates, shown in the venue table in "Find your way around Reservoir".

When new data appears

Reservoir is updated once a day. Each UTC day is added the next day: fills, candles and snapshots around 10:00–12:00 UTC, and order books a little later, usually by 13:30 UTC. The files for 18 October 2026 were written on 19 October between about 10:10 and 11:45 UTC. If the previous day's folder isn't there yet, check again later.

How markets are named

Market type In fills and candles (coin) Order-book file name
Hyperliquid perpsBTCby_dex/hyperliquid/orderbook/1m/perps/…/BTC.parquet
HIP-3 perpsxyz:MSFT (venue prefix)by_dex/xyz/orderbook/1m/perps/…/MSFT.parquet (no prefix)
Spot@107 (the spot pair's number)by_dex/hyperliquid/orderbook/1m/spot/…/@107.parquet
HIP-4 prediction markets#114940by_dex/hyperliquid/orderbook/1m/outcome/…/#114940.parquet

Spot pairs are numbered, so use the base_symbol and quote_symbol columns to see what they are. For example, @107 is HYPE/USDC. One older pair, PURR/USDC, uses its name instead of a number. Its order-book file is PURR%2FUSDC.parquet: use that name exactly.

For HIP-4 files, keep the # exactly as it is in the path. Don't encode it as %23, or the file won't be found.

1. Fills: what actually traded

A fill is one trade, seen from one account's side. It records what was traded, the price, the size, when it happened, which wallet it was and the fee paid. It also records realised profit or loss, and flags special cases such as liquidations and TWAP trades (large orders split into smaller pieces over time).

Understanding a sudden price drop

Say ETH falls hard and you want to know what was behind it. Start with the ETH liquidation fills around that time. A liquidation is when a position gets forcibly closed because the account no longer has enough margin (collateral) to keep it open.

Group those liquidations by minute and line them up against the price. You'll see when forced closing picked up and how large the closed positions were. For the wider picture, pull the regular fills for the same window too.

That's enough for a market recap or a risk dashboard. Just be careful with the conclusion: liquidations happening during a drop doesn't mean they caused all of it.

Reviewing a wallet's trades

If you're reviewing your own trading, or following another wallet, filter the fills by wallet address. You get the actual price, size and fee of each trade, instead of guessing from where the chart was.

That works well for a trading journal or for checking how well your orders were filled. For the account's full return you'll need more than fills, because funding payments, deposits and withdrawals all affect it too.

What the format looks like

Field Meaning
coinThe market, such as ETH. Markets launched through HIP-3 carry their DEX as a prefix
timestampWhen the trade happened, in UTC, to the millisecond
price, sizeThe trade's price and quantity
addressThe wallet on this side of the trade
side, crossedBuy or sell, and whether this side took an order already on the book
trade_idThe trade's ID, handy for matching up its two sides
fee, fee_tokenThe fee charged and the token it was paid in
is_liquidation, liquidation_methodWhether the fill was part of a liquidation, and how it was handled

The full schema has more columns, and some of them are empty when they don't apply to a fill.

A few more columns are worth knowing:

Field Meaning
directionWhat the fill did to the position, such as Open Long or Close Short
start_positionThe wallet's position in that market just before this fill. Negative means short
builder, builder_feeThe app (builder code) that sent the order, and the fee it charged. Every row in builder_fills has a builder
deployer_feeThe fee taken by a HIP-3 venue's deployer. It's zero on Hyperliquid's own markets
priority_gasExtra paid for priority

deployer_fee and priority_gas were added in late March 2026, so older files don't have them.

Fetch only the part you need

Fills for Hyperliquid's own perp markets are stored in one file per day:

code
by_dex/hyperliquid/fills/perp/all/date=YYYY-MM-DD/fills.parquet

There are also smaller daily files for particular kinds of fills: liquidations, adl, builder_fills and twap_fills. These are cut out of the all file, so don't add them on top of it. A file only exists for a day that had at least one matching fill.

The perp files above cover one venue at a time. For other kinds of trades:

• Spot trades: global/fills/spot/all/date=YYYY-MM-DD/fills.parquet
• HIP-4 prediction-market trades: global/fills/outcome/all/date=YYYY-MM-DD/fills.parquet. These rows have two extra columns: outcome_id and outcome_side.
• Everything on every venue in one file: global/fills/raw/date=YYYY-MM-DD/fills.parquet

The raw file already includes everything in the other fill files, so don't combine it with them.

So if you only want liquidations, start with the liquidation file instead of the full day of trades. Then narrow it down to the market, the time window and the columns you need. Whether you're looking into a sell-off or a single wallet, you don't need every account on every market.

The worked example further down pulls only ETH liquidations between 15:30 and 15:40 UTC.

To peek at ordinary ETH trades in one minute, this query keeps only the side that crossed (the taker) and returns up to 50 rows:

code
SELECT coin, timestamp, price, size, side, crossed
FROM read_parquet('s3://hydromancer-reservoir/by_dex/hyperliquid/fills/perp/all/date=2026-10-08/fills.parquet')
WHERE coin='ETH'
  AND timestamp>=TIMESTAMPTZ '2026-10-08 15:35:00+00'
  AND timestamp<TIMESTAMPTZ '2026-10-08 15:36:00+00'
  AND crossed
ORDER BY timestamp
LIMIT 50;

LIMIT 50 makes this a preview, not every trade in that minute.

For one wallet's history, filter by address and leave out the crossed filter. Otherwise you'll drop every trade where the wallet's order was the one already waiting on the book.

If you're adding up trading volume, remember that a trade normally appears twice, once for each side. Add up every row and you'll double the real figure. A small number of rows are special events rather than ordinary trades, so count those separately.

2. Candles: price and volume over time

A candle sums up trading over a short slice of time. Reservoir's candles cover one second each and record four prices: the first (open), the highest (high), the lowest (low) and the last (close). They also record the volume and the number of trades.

Testing a trading idea before using real money

Say your rule is simple: buy when the price climbs above its recent average, and sell when it drops back below. Before you put money behind it, you want to know when it would have traded and how it would have done.

Pull candles for the market and dates you want to test, then step through them in order, using only prices the rule could have seen at the time. That's backtesting: replaying history to see what a strategy would have done, without placing any real orders. The official Hyperliquid API only returns the most recent 5,000 candles, so longer tests need an archive like this one.

The answer is often that the idea doesn't hold up. It trades too often, gets hurt in sharp moves, or the profit disappears once fees and funding are counted. Better to find that out here than with real money. Keep in mind that a price in the history doesn't mean your order would have filled there, so allow for some slippage (getting a slightly worse price than you expected).

Building a chart or comparing market conditions

Candles are also what you'd use to draw a historical price chart, or to compare how much a market moved on a quiet day against a busy one. They're much easier to work with than millions of individual trades. If you later want the actual trades behind a candle, go back to the fills.

What the format looks like

Field Meaning
coin, asset_classThe market and its type, such as perp
timestampWhen the one-second candle starts, in UTC
open, high, low, closeThe first, highest, lowest and last price in that second
volumeAmount traded, counted in the token itself (for example, ETH)
volume_quoteAmount traded, counted in the currency it's priced in
trade_countNumber of trades in that second

Candles come in one daily file per DEX. For every venue at once, including spot and HIP-4 markets, use global/candles/1s/date=YYYY-MM-DD/candles.parquet. Filter it by market, type and time. This query pulls five minutes of ETH perp candles rather than every market for the whole day:

code
SELECT coin, timestamp, open, high, low, close, volume, volume_quote, trade_count
FROM read_parquet('s3://hydromancer-reservoir/by_dex/hyperliquid/candles/1s/date=2026-10-08/candles.parquet')
WHERE coin='ETH'
  AND asset_class='perp'
  AND timestamp>=TIMESTAMPTZ '2026-10-08 15:30:00+00'
  AND timestamp<TIMESTAMPTZ '2026-10-08 15:35:00+00'
ORDER BY timestamp;

Quiet seconds may have no row, so five minutes won't necessarily give you 300 rows. Check which seconds are missing before you fill gaps, and don't invent trades to fill them.

You can roll one-second candles up into minutes or hours. Take the first open and the last close (sorted by time), the highest high, the lowest low, and add up the volume. If your work depends on exact wicks, or on which price was reached first, check it against the underlying fills as well.

3. Snapshots: what positions and balances looked like

Fills tell you what happened. Snapshots tell you what was there: the positions and balances recorded at one moment. Reservoir has daily snapshots of perp positions, spot balances and account values. Some dates are missing, so check what's available instead of assuming every day exists. All snapshot files were regenerated on 15 October 2026 to match how Hyperliquid's live API reports unified and portfolio-margin accounts, so files you downloaded before then may differ.

Each day's snapshot is a single file named after the block and time it was taken, for example 1187700000_1792281933949.parquet. That's why the examples use *.parquet instead of a fixed name. Perp positions are in global/snapshots/perp/all/ for every venue, or in by_dex/{venue}/snapshots/perp/ for one venue.

Snapshots matter because trades alone don't show what a wallet already held. It may have opened a position weeks before the period you're looking at. A snapshot shows you that position directly.

Fills record every trade across the day, while snapshots record positions and balances at one capture time

Each snapshot file is named after the block number and the time it was taken:

json
{block}_{timestamp}.parquet

Check that time before you match a snapshot to an event. Sitting in a date's folder doesn't mean it was taken at the minute you care about.

Perpetual positions

Checking where large positions were concentrated

Say you're looking at BTC and want to know whether a handful of wallets hold most of the big bets. A position snapshot lists the open positions at the moment it was taken. A long makes money when the price goes up; a short makes money when it goes down.

From there, check whether a small group of wallets holds a large share of the longs or the shorts. That works for a concentration study or a dashboard of the biggest positions. It won't tell you who owns the wallets, or what they hold elsewhere.

If you're comparing against a sell-off, check the snapshot time first so you know whether you're looking at before or after. One snapshot a day can't show what changed in between.

Each row is one wallet's position in one market. Useful fields include user, market, size (positive for long, negative for short), notional (the position's recorded value), entry_price, an estimated liquidation_price, leverage settings and account_mode. Sizes and money amounts are stored as floating-point numbers, and the liquidation price can be empty.

This preview pulls five BTC positions from one day's snapshot:

code
SELECT "user", market, size, notional, entry_price, liquidation_price, leverage_type, leverage, account_mode
FROM read_parquet('s3://hydromancer-reservoir/by_dex/hyperliquid/snapshots/perp/date=2026-10-08/*.parquet')
WHERE market='BTC'
LIMIT 5;

The * only matches files in that one day's folder. It's there because the file name includes the block and time, not to search the whole archive.

Spot balances

Each row is one wallet's balance of one token, and only balances above zero are included. Fields include user, token, balance and entry_value. For unified and portfolio-margin accounts, the balance of a collateral token such as USDC also includes the money in their perp positions, the same way Hyperliquid's live API shows it.

Following changes in a wallet's token holdings

To see how a wallet's HYPE balance changed, pull that wallet and token from two snapshots and compare them. If you're studying how a token is spread across holders instead, take that one token across all wallets.

A bigger balance doesn't always mean the wallet bought more. It could have come from a transfer or a deposit.

Either way, fetch only the wallet and token you need for the dates you need, not every token in every wallet.

To preview USDC balances:

code
SELECT "user", token, balance, entry_value
FROM read_parquet('s3://hydromancer-reservoir/global/snapshots/spot/date=2026-10-08/*.parquet')
WHERE token='USDC'
LIMIT 5;

Account values

Each row is one wallet on one DEX, with fields including user, dex, collateral_token, account_value, total_long_notional, total_short_notional and account_mode.

account_mode tells you how the account is set up: standard, dex_abstraction, unified or portfolio_margin. A few more fields help with the newer account types:

• is_unified is true when the account value includes the wallet's spot balance of that token.
• pm_ratio is the portfolio-margin ratio, where 1.0 means at or past liquidation.
• pm_avail_by_branch lists the margin still available for each collateral token.
• pm_total_account_value is the account's total value across all its collateral tokens.

The three pm_ fields are filled only for portfolio-margin accounts, and they describe the whole account, so they repeat on each of that wallet's rows.

Checking the margin behind an account's positions

Position size only tells you part of the risk. You also want to know how much margin (the money backing those positions) the account had, next to its total long and short exposure.

The account-value snapshot puts those numbers in one row. You can build an account overview or a risk report from it without working through every trade.

Keep the collateral token and account mode next to every number. Here, a DEX means a trading venue on Hyperliquid, and different venues can use different collateral, so an account value isn't automatically the wallet's whole balance in USD. And a higher value in the next snapshot isn't necessarily profit, because a deposit would have the same effect.

Unified accounts need one extra step. Their account value for a token is the same on every DEX that uses that token, so take one row per wallet and token instead of adding them up.

To preview the fields:

code
SELECT "user", dex, collateral_token, account_value, total_long_notional, total_short_notional, account_mode
FROM read_parquet('s3://hydromancer-reservoir/global/snapshots/account_values/date=2026-10-08/*.parquet')
LIMIT 5;

To look at portfolio-margin accounts only, add WHERE account_mode = 'portfolio_margin' and select the pm_ fields too.

To look at one account, filter on the "user" column, keeping the double quotes because user has a special meaning in SQL. To look at one DEX, add a dex filter. These five-row queries are previews, not full lists or rankings. For account-level totals, use this dataset rather than adding up an account value that repeats across position rows.

4. Order books: the bids and asks waiting to be filled

An order book is the list of orders waiting to be filled. Bids are orders to buy and asks are orders to sell. The gap between the highest bid and the lowest ask is the spread.

Reservoir takes a snapshot of each order book once a minute. These are L2 snapshots, which means orders at the same price are grouped into a single level instead of being listed one by one. Each snapshot holds up to 20 levels on each side. It won't show every order, or every change between one snapshot and the next. For every update as it happens, use a live feed instead.

That gives 1,440 rows per market per day. Hyperliquid order books start on 15 December 2025, and there are separate folders for perps, spot and HIP-4 markets. HIP-3 venues have perp order books only.

Understanding why a larger trade might get a worse price

The last traded price doesn't tell you how much you could actually buy or sell at that price. A big order can use up everything at the best price and carry on into worse ones.

Illustrative order book: a 3-unit buy fills at 2,500.00, while a 12-unit buy uses three ask levels for an average price of 2,500.58

Look at how much is on offer at each price level, and compare the spread when the market is calm with when it's busy. That's useful for a trading tool, or for working out what large trades really cost.

To look at ETH around a sharp move, take the ETH order-book file for that day and pull the minutes around it. Check whether the spread widened and whether the size near the best prices thinned out.

This shows what the book looked like at each snapshot. It isn't the price your own order would have got: orders change between snapshots, and the data can't show where you'd have stood in the queue.

What the format looks like

Field Meaning
block_time_msWhen the snapshot was taken, in milliseconds since 1 January 1970 (UTC)
block_numberThe Hyperliquid block number
bidsThe buy levels, best price first
asksThe sell levels, best price first
Each level's px, sz, nPrice, size and number of orders. Price and size are stored as text

Unlike fills and candles, order books are already split into one file per coin per day. If you only care about one market, that's exactly what you want.

code
by_dex/hyperliquid/orderbook/1m/perps/date=2026-10-08/ETH.parquet

This pulls the best bid, the best ask and the spread for ten minutes:

code
SELECT to_timestamp(block_time_ms/1000.0) AS timestamp, CAST(bids[1].px AS DOUBLE) AS best_bid, CAST(asks[1].px AS DOUBLE) AS best_ask, CAST(asks[1].px AS DOUBLE)-CAST(bids[1].px AS DOUBLE) AS spread
FROM read_parquet('s3://hydromancer-reservoir/by_dex/hyperliquid/orderbook/1m/perps/date=2026-10-08/ETH.parquet')
WHERE block_time_ms>=epoch_ms(TIMESTAMPTZ '2026-10-08 15:30:00+00')
  AND block_time_ms<epoch_ms(TIMESTAMPTZ '2026-10-08 15:40:00+00')
ORDER BY block_time_ms;

For HIP-3 markets, the DEX is part of the folder path, and the file name is just the coin, without the dex: prefix you'll see in other datasets. Follow the order-book naming rules instead of copying a market name straight from your fills.

How big the files are

AWS bills requester-pays downloads by the request and by the amount of data transferred. So it helps to know roughly how big a file is before you pull it. These are the sizes for one day, 18 October 2026:

File Size for one day
Every fill on every venue (global/fills/raw/)about 640 MB
Hyperliquid perp fills (by_dex/hyperliquid/fills/perp/all/)about 360 MB
Trade[XYZ] perp fills (by_dex/xyz/fills/perp/all/)about 170 MB
Spot fills / HIP-4 fillsabout 26 MB each
Hyperliquid liquidationsabout 1 MB (all days since July 2025 together: about 330 MB)
1-second candles, every marketabout 44 MB (all days together: about 15.5 GB)
Perp position snapshot / spot balances / account valuesabout 29 / 117 / 92 MB
One market's order bookabout 0.2–0.45 MB (HIP-4 books: about 20 KB)

Querying a file in place, as shown below, can transfer less than the full size, because DuckDB reads only the columns and parts of the file it needs. How much less depends on the query: the month-of-candles example below still downloads about 590 MB.

How much Reservoir costs: Close to nothing

Requester pays sounds like it could get expensive. In practice, most pulls cost nothing for transfer, only a fraction of a cent in request fees. Reservoir has no subscription fee and needs no Hydromancer API key. You pay only AWS, and only for what you pull.

And every AWS account gets 100 GB a month of free internet transfer, which Reservoir downloads count toward. That's a lot of history.

Building a month of BTC 1-minute candles (the worked example below) downloads about 590 MB, so you could do it more than 150 times in a month before paying for transfer.

All that's left is the request fee: $0.00037 per 1,000 requests, a fraction of a cent.

Made for agents doing research and backtesting

The same goes for AI agents. An agent testing ideas runs many small queries: a week of candles here, a day of liquidations there. Each query can read just the columns it needs, so while you're inside the free 100 GB, most cost a fraction of a cent.

And there's no Hydromancer API key or subscription to manage. Even a month of every fill on every venue, about 19 GB, fits inside the free 100 GB. To set an agent up safely, see "Give your AI agent its own read-only AWS access" below.

What it costs after the free 100 GB

If your account has already used its 100 GB that month, AWS charges for the transfer. It's still cheap. These are the prices for the Tokyo region (ap-northeast-1), where Reservoir lives:

What AWS charges for Price
Read requests (GET); one download or query can make many$0.00037 per 1,000 requests
Listing a folder (LIST request)$0.0047 per 1,000 requests
Data sent to your computer (the internet)$0.114 per GB
Data sent to an AWS server in another region$0.09 per GB
Data sent to an AWS server in TokyoFree

Here's what you'd pay AWS to download some typical pulls to your computer once the free 100 GB is used up. Most rows assume you download the whole file. A query that reads only some columns can cost less:

What you pull Data What you pay AWS
One day of Hyperliquid liquidations, every marketabout 1 MBabout $0.0001
One market's order book for a monthabout 6–14 MBunder $0.002
Every Hyperliquid liquidation since July 2025about 330 MBabout $0.04
Building a month of BTC 1-minute candles from 1-second candles (the worked example below)about 590 MBabout $0.07
One day of every fill on every venueabout 640 MBabout $0.07
A week of Hyperliquid perp fillsabout 2.5 GBabout $0.30
Every 1-second candle for every market since July 2025about 15.5 GBabout $1.80
A month of every fill on every venueabout 19 GBabout $2.20

Pulling a lot? Run your queries on an AWS server in Tokyo. Transfer from S3 is free there, so you pay only for the requests and the server. Avoid routing through a NAT gateway, which charges per GB.

Week and month fill and order-book sizes multiply one day (Sunday, 18 October 2026), so busier days and weeks can be bigger. Prices are from Amazon S3 pricing at the time of writing.

What Reservoir doesn't include

• Today. The newest folder is the previous day (or the day before, until that day's files arrive around 10:00–12:00 UTC). For today's data, use the Hydromancer API. For example, candleSnapshot returns today's candles down to 1 second, and each request returns up to 5,000 candles.
• Every order. Order books are saved once a minute, as the top 20 price levels on each side. Each level has a price, the total size and the number of orders. There's no order-by-order history; for that you need the live L4 stream.
• Positions during the day. Snapshots are taken once a day, a few minutes after midnight UTC.
• Venue data from before its launch, and Hyperliquid's own markets before 28 July 2025.

If you need something Reservoir doesn't have, email data@hydromancer.xyz. However, if you are specifically looking for ongoing history, that is part of the Hydromancer API.

How to get a wallet's full history

Reservoir has a wallet's trades (fills) and its positions once a day (snapshots). For a wallet's real result you also need what happened outside trading. Funding payments add to or take away from the balance every hour. Deposits, withdrawals and transfers move money in and out. Those aren't in Reservoir. They're in the Hydromancer API:

What you need Where it is Since
Every trade Reservoir fills (address column), or userFillsByTime 28 Jul 2025 (TWAP fills from 2 Aug 2025)
Positions, once a day Reservoir snapshots (user column) 29 Jul 2025, with some days missing (see "When each dataset starts")
Hourly funding payments userFunding 28 Jul 2025
Deposits, withdrawals, transfers, vault and staking moves userNonFundingLedgerUpdates 28 Jul 2025
Totals for closed positions: PnL, fees, funding, win rate userPnlSummary 1 Aug 2025

The wallet column is named differently in each dataset: address in fills, user in snapshots.

These requests need a Hydromancer API key in HYDROMANCER_API_KEY (Reservoir itself only needs AWS). The function below uses only Python's standard library, so there's nothing extra to install. Keep the User-Agent line: the API turns away Python's default one.

Each userFunding or userNonFundingLedgerUpdates response returns up to 2,000 rows, oldest first. To get everything, ask again from the time of the last row, and drop the rows you've already seen. Several rows share each funding hour, one per market, so starting from the last time can return a few rows twice. This function handles both:

code
import json, os, urllib.request
URL = "https://api.hydromancer.xyz/info"
HEAD = {"Authorization": f"Bearer {os.environ['HYDROMANCER_API_KEY']}",
        "Content-Type": "application/json", "User-Agent": "Mozilla/5.0"}
def history(kind, user, start=0):
    seen = set()
    while True:
        body = json.dumps({"type": kind, "user": user, "startTime": start})
        req = urllib.request.Request(URL, body.encode(), HEAD)
        rows = json.load(urllib.request.urlopen(req, timeout=30))
        new = [r for r in rows if json.dumps(r, sort_keys=True) not in seen]
        if not new: return
        seen.update(json.dumps(r, sort_keys=True) for r in new)
        yield from new
        start = rows[-1]["time"]

Use it with a wallet address, for example wallet = "0x…", then list(history("userFunding", wallet)) or list(history("userNonFundingLedgerUpdates", wallet)). Each row has a time (Unix milliseconds) and a delta. For funding, delta.usdc is the payment: positive means the wallet received it. For the ledger, delta.type says what happened, such as deposit, withdraw, send or spotTransfer.

Each request uses 10 of your plan's per-minute weight. Most wallets need only a few requests. A wallet holding positions in dozens of markets gets one funding payment per market every hour, so a year of its funding can take around 100 requests.

Before 28 July 2025. Reservoir starts on 28 July 2025, and so does the Hydromancer API's history, apart from a few earlier rows for some wallets. For funding and ledger entries from before then, Hyperliquid's own API (api.hyperliquid.xyz/info) answers the same userFunding and userNonFundingLedgerUpdates requests. For fills from before then, email data@hydromancer.xyz.

How to query S3 and save only the result

Start with a request you can describe in one sentence

Before anything technical, write down what you want in one sentence: "I want ETH liquidation fills for these ten minutes." That already tells you the dataset, the market and the time. The columns come after.

Five steps to narrow a Reservoir extract: dataset, date, market, time window and columns, with the data shrinking at each step

If a developer, analyst or AI coding assistant is helping you, you can hand them something like this:


Create a CSV of ETH liquidation fills from Reservoir for 8 October 2026, from 15:30 UTC up to but not including 15:40 UTC. Include the time, market, execution price, size, buy/sell side, wallet and liquidation status/method. Use the liquidation subset and select only those fields. Reuse my configured AWS session without displaying credentials. Save the result locally.

They'll still need AWS access set up; the read-only setup below is a safe way to give it. The brief describes what to pull; it doesn't give anyone access, and AWS fees still apply. The example further down does exactly what this brief asks for.

Point your AI assistant at the docs

AI assistants that can browse, such as ChatGPT, Claude or Cursor, write better Reservoir code when they read the docs instead of guessing paths and column names. Paste these plain-text pages into the chat with your request:

Then add these facts, so it starts from the right setup:

Bucket s3://hydromancer-reservoir, region ap-northeast-1, requester pays. Use Python with duckdb==1.4.5 and pytz. Reuse my AWS CLI session with aws configure export-credentials and never print my credentials. Set s3_requester_pays = true. Use the venue folders and start dates from https://hydromancer.xyz/blog/exploring-reservoir.

Check what comes back before you trust it: the row count, the first and last time, and the market names.

Query the file instead of downloading all of it

You don't have to download a whole day's file before you query it. DuckDB can read parts of a file straight from S3, fetch only the columns you ask for, and apply your filters as it reads.

That doesn't mean S3 sends you only the rows you end up with. DuckDB still reads the file's metadata and any chunks of data that might match. How much you save depends on your query and how the file is laid out, and a query that looks narrow can still read more than you'd expect.

Before you start

You need an AWS account, signed in through AWS CLI v2 (Amazon's command-line tool), with permission to read the Reservoir files. If you want to browse folders or use * in a path, you also need permission to list them. You don't need a Hydromancer API key.

The bucket is set to requester pays. Reservoir itself has no subscription fee, but AWS charges whoever pulls the data for requests and data transfer. Free data doesn't always mean a free AWS bill.

Choose how to sign in to AWS

There are three ways to give your computer access to Reservoir. Pick the one that fits:

If you are… Use Setup
Trying Reservoir for the first time The quick way: your root user None
Using Reservoir yourself on a regular basis A read-only IAM user, signed in with aws login About 5 minutes
Letting an AI agent or script run on its own A read-only IAM user with an access key About 5 minutes

The quick way: sign in as your root user

The root user is the email and password you used to create your AWS account. It already has every permission, so there's nothing to set up, even on a brand-new account. You need AWS CLI version 2.32 or later; check with aws --version.

code
aws login
aws sts get-caller-identity

aws login opens your browser. Sign in as the root user. If it asks for a region, enter ap-northeast-1. The second command should print your account with :root at the end. The sign-in lasts up to 12 hours; after that, run aws login again.

AWS advises against using the root user for everyday work, because it can do anything in your account, including closing it. It's fine for trying Reservoir. If you'll use Reservoir regularly, set up a read-only user instead, as below.

Give your AI agent its own read-only AWS access

If an AI agent or a script will query Reservoir for you, don't hand it your main AWS login. Give it a separate user that can only read this one bucket. Then it can list folders and download files on its own, but it can't touch anything else in your account.

This is the whole permission it needs:

json
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "ListReservoir",
      "Effect": "Allow",
      "Action": "s3:ListBucket",
      "Resource": "arn:aws:s3:::hydromancer-reservoir"
    },
    {
      "Sid": "ReadReservoir",
      "Effect": "Allow",
      "Action": "s3:GetObject",
      "Resource": "arn:aws:s3:::hydromancer-reservoir/*"
    }
  ]
}

s3:ListBucket lets it see what's in the folders, which aws s3 ls and * in a path both need. s3:GetObject lets it read the files. Nothing else is allowed: it can't upload, delete, read your other buckets or start servers.

To set it up:

1. In the AWS console, open IAM, go to Users and create a user, for example reservoir-reader. It doesn't need console access.
2. Under Permissions, choose "Create inline policy", switch to JSON, paste the policy above and save it.
3. Open the user's "Security credentials" tab and create an access key for the command line.
4. On the computer where the agent runs, save the key as its own profile: run aws configure --profile reservoir and enter the key, the secret and the region ap-northeast-1.
5. Check it: aws sts get-caller-identity --profile reservoir should show the new user.

Tell the agent to use that profile by setting AWS_PROFILE=reservoir before it runs anything. The key stays in your computer's AWS settings file, so you never paste it into a chat or a script.

The policy limits what the agent can do, not how much it spends. Every file it reads is still billed to you. To catch a runaway job early, set a monthly budget alert in AWS Billing.

Use a read-only user yourself, without access keys

If you're the one running the queries, you can use the same read-only policy without creating an access key. You sign in through the browser with aws login, and AWS gives your computer short-lived credentials instead of a key that never expires.

1. Sign in to the AWS console as root and note your account ID: the 12-digit number in the menu under your account name, top right. You need it in step 5.
2. Open IAM, go to Users and choose Create user. Name it, for example, reservoir-reader. This time, tick Provide user access to the AWS Management Console, choose I want to create an IAM user and set a password.
3. Under Attach policies directly, tick the AWS managed policy SignInLocalDevelopmentAccess. It lets the user run aws login. Then create the user.
4. Open the new user and choose Add permissions, then Create inline policy. Switch to JSON, paste the policy above and save it.
5. Sign out of the console. Then, in your terminal, run aws login and sign in as the new user.

The IAM sign-in page asks for three things:

Field What to enter
Account ID or alias Your 12-digit account ID from step 1, not the user name
IAM username The user you created, such as reservoir-reader
Password The password from step 2

You can also open https://<your-account-id>.signin.aws.amazon.com/console, which fills in the account ID for you. AWS may ask you to choose a new password the first time; that's normal for new users. If you lose the password, sign in as root and go to IAM, Users, your user, Security credentials, Manage console access.

Check who you're signed in as with aws sts get-caller-identity. It should end in user/reservoir-reader. If it ends in root, aws login reused your root session from the browser: sign out of the console and run aws login again. You don't need an access key for this route, even if AWS suggests creating one.

Install DuckDB and check your sign-in

The examples use DuckDB 1.4.5. On macOS or Linux, you can install it in its own environment like this:

code
python3 -m venv .venv
source .venv/bin/activate
pip install duckdb==1.4.5 pytz==2026.5

Install exactly these versions, which the examples were tested with, and type the package names exactly as shown. Look-alike names such as rsquests have been used to spread malware, and a pinned version won't change under you if a future release is ever compromised. A fresh environment like the one above keeps anything you install away from the rest of your system. If you can, use the read-only AWS user described above, so any program on your computer that reads your AWS sign-in can only read Reservoir.

DuckDB needs pytz to show times in Python. Without it, the fills, candles and order-book examples stop with No module named 'pytz'. On Windows, activate the environment with .venv\Scripts\activate instead of the source line.

Then check that your AWS sign-in works:

code
aws sts get-caller-identity

Connect without putting keys in the script

This setup borrows the credentials from your current AWS CLI session and keeps them in memory only. It also sets the bucket's region and turns on requester pays.

code
import json
import os
import subprocess
import duckdb

# Reuse the active AWS CLI session; do not paste credentials into this file.
credentials = json.loads(subprocess.check_output(
    ["aws", "configure", "export-credentials", "--format", "process"],
    text=True,
))
for source, target in [
    ("AccessKeyId", "AWS_ACCESS_KEY_ID"),
    ("SecretAccessKey", "AWS_SECRET_ACCESS_KEY"),
    ("SessionToken", "AWS_SESSION_TOKEN"),
]:
    if credentials.get(source):
        os.environ[target] = credentials[source]
    else:
        os.environ.pop(target, None)

con = duckdb.connect()
con.execute("INSTALL httpfs; LOAD httpfs;")
con.execute("SET TimeZone = 'UTC';")
con.execute("""
CREATE SECRET (
    TYPE s3,
    PROVIDER credential_chain,
    CHAIN 'env',
    REGION 'ap-northeast-1'
);
SET s3_requester_pays = true;
""")

Don't print the credentials variable or share what's in it. Sign in to AWS the way you normally do, and never paste access keys into a blog post, notebook or AI chat.

If you get an error

What you see What it usually means What to do
"Invalid choice" when you run aws login Your AWS CLI is older than 2.32 Update the AWS CLI, then check aws --version
"Authentication failed" on the AWS sign-in page The user name went into the account ID box, or the password is wrong Enter the 12-digit account ID first, then the user name
"Your session has expired. Please reauthenticate using 'aws login'" The 12-hour sign-in ended Run aws login again
403 "Anonymous users cannot invoke requests against Requester Pays buckets" You're not signed in, or the script can't see your sign-in Run aws sts get-caller-identity to check, then sign in
403 Forbidden or AccessDenied while signed in. DuckDB may also say "Authentication Failure" Requester pays was left off for that request Add --request-payer requester to every aws command, and keep SET s3_requester_pays = true; in DuckDB
403 even with requester pays on You're signed in as a different user than you think, the user is missing the read-only policy, or a company AWS Organization blocks outside buckets Check aws sts get-caller-identity, check the policy, or try the root user on a personal account
301 Moved Permanently DuckDB is using the wrong region Keep REGION 'ap-northeast-1' in the DuckDB setup
404 Not Found, or "No files found that match the pattern" No file for that day, or yesterday's files haven't arrived yet List the folder with aws s3 ls first

Extract ten minutes of ETH liquidations

Add this to the same Python file:

code
query = """
SELECT coin, timestamp, price, size, side,
       address, is_liquidation, liquidation_method
FROM read_parquet(
    's3://hydromancer-reservoir/by_dex/hyperliquid/fills/perp/liquidations/date=2026-10-08/fills.parquet'
)
WHERE coin = 'ETH'
  AND timestamp >= TIMESTAMPTZ '2026-10-08 15:30:00+00'
  AND timestamp <  TIMESTAMPTZ '2026-10-08 15:40:00+00'
ORDER BY timestamp
"""

# Accept either a standalone SQL recipe or one without its final semicolon.
query = query.strip().rstrip(";")

# Fetch once. Preview, counting and both exports now use the local result.
con.execute("CREATE TEMP TABLE extract AS " + query)
con.execute("COPY extract TO 'eth-liquidations-10min.parquet' (FORMAT PARQUET)")
con.execute("COPY extract TO 'eth-liquidations-10min.csv' (HEADER, DELIMITER ',')")
print("Extracted rows:", con.execute("SELECT count(*) FROM extract").fetchone()[0])
print(con.execute("SELECT * FROM extract LIMIT 5").fetchall())

Save both Python blocks together as extract.py, then run:

code
python extract.py

The CSV and Parquet files appear in the folder you ran it from. The script pulls the data from S3 once and keeps it locally, so the second file, the row count and the preview don't go back to S3.

To pull a different dataset, swap the SQL inside query for one of the recipes above and rename the output files. You can paste the recipes as they are, because the script strips the final semicolon. Use the CSV for a spreadsheet. Parquet is usually the better choice if you'll keep analyzing the data in code.

Find the busiest HIP-4 markets on a given day

code
SELECT coin, outcome_side,
       count(*) AS fills,
       sum(price * size) AS volume
FROM read_parquet('s3://hydromancer-reservoir/global/fills/outcome/all/date=2026-10-18/fills.parquet')
WHERE crossed
  AND direction IN ('Buy', 'Sell')
GROUP BY coin, outcome_side
ORDER BY volume DESC
LIMIT 10;

HIP-4 fills aren't all ordinary trades. They also include settlements and the splitting, merging and negating of outcome shares, which are about a third of the day's value. direction IN ('Buy', 'Sell') keeps only ordinary trades, and each of those appears twice, once for each side, so WHERE crossed counts each trade once. Prices run from 0 to 1, which you can read as the market's probability. To see which token a fee was paid in, check fee_token.

Query several days at once

Swap the date in the path for a pattern. date=2026-10-1* matches 10 to 19 October, and date=2026-09-* matches the whole of September:

code
SELECT count(*)
FROM read_parquet('s3://hydromancer-reservoir/by_dex/hyperliquid/fills/perp/liquidations/date=2026-10-1*/fills.parquet');

This counted 140,819 liquidation fills across nine days in about a second (19 October hadn't been added yet when we ran it). Counting rows only reads each file's summary, so it downloaded about 0.15 MB.

Filtering by market doesn't shrink the download as much as you might expect. DuckDB still reads a large part of each daily file to find the rows you asked for. Check the size before you query months of data.

Worked example: a month of 1-minute candles

This is the usual first step of a backtest: turn September's 1-second BTC candles into 1-minute candles and save them on your computer.

code
COPY (
  SELECT time_bucket(INTERVAL 1 minute, timestamp) AS minute,
         arg_min(open, timestamp)  AS open,
         max(high)                 AS high,
         min(low)                  AS low,
         arg_max(close, timestamp) AS close,
         sum(volume)               AS volume
  FROM read_parquet('s3://hydromancer-reservoir/by_dex/hyperliquid/candles/1s/date=2026-09-*/candles.parquet')
  WHERE coin = 'BTC' AND asset_class = 'perp'
  GROUP BY minute
  ORDER BY minute
) TO 'btc_1m_2026-09.parquet' (FORMAT parquet);

In our test this took about 40 seconds and downloaded about 590 MB from S3. It saved a 1.4 MB file with 43,192 one-minute candles. September has 43,200 minutes, so 8 minutes had no trades, and you should check for gaps before testing a strategy. From then on, work on the saved file. It costs nothing to read again.

Check what's available before querying

To list one day's perp snapshot folder:

code
aws s3 ls \
  s3://hydromancer-reservoir/by_dex/hyperliquid/snapshots/perp/date=2026-10-08/ \
  --request-payer requester

To see a file's full size without downloading it:

code
aws s3api head-object \
  --bucket hydromancer-reservoir \
  --key by_dex/hyperliquid/fills/perp/liquidations/date=2026-10-08/fills.parquet \
  --request-payer requester \
  --query ContentLength --output text

That number is the size of the whole file in bytes, not how much a filtered query will transfer.

Other ways to get the files

You don't have to query in place. You can download files with the AWS CLI and open them with any tool that reads Parquet.

One file:

code
aws s3 cp \
  s3://hydromancer-reservoir/by_dex/hyperliquid/fills/perp/liquidations/date=2026-10-18/fills.parquet \
  ./liquidations-2026-10-18.parquet \
  --request-payer requester

A range of days, here 16 to 18 October:

code
aws s3 sync \
  s3://hydromancer-reservoir/by_dex/hyperliquid/fills/perp/liquidations/ \
  ./liquidations/ \
  --exclude "*" --include "date=2026-10-1[6-8]/*" \
  --request-payer requester

Then, for example, in Python with pandas:

code
import pandas as pd
df = pd.read_parquet("liquidations-2026-10-18.parquet")
print(df.groupby("coin").size().sort_values(ascending=False).head())

Downloading suits small files you'll use often, like liquidations: about 1 MB a day. For big files, like a full day of fills, querying in place is usually cheaper, because you only transfer what you need.

How to download a whole venue

Querying a slice is the cheapest way to use Reservoir. Sometimes you want everything, though: a full venue to keep on your own disk, or a complete history to load into your own database. Here's what that involves before you start.

How big each venue is

Sizes as of 28 October 2026. The second column is what you download if you skip the shortcut folders (see "What to skip" below).

Folder Whole folder Skipping shortcut folders Data from Data until
by_dex/hyperliquid/ 216.8 GB 196.2 GB 28 Jul 2025 ongoing
by_dex/xyz/ 73.3 GB 64.9 GB 13 Oct 2025 ongoing
by_dex/cash/ 11.3 GB 9.5 GB 20 Jan 2026 2 Jul 2026
by_dex/io/ 3.9 GB 2.7 GB 19 Aug 2026 ongoing
by_dex/hyna/ 2.3 GB 1.9 GB 3 Dec 2025 2 Sep 2026
by_dex/km/ 2.2 GB 1.5 GB 12 Jan 2026 17 Jun 2026
by_dex/flx/ 1.0 GB 0.8 GB 13 Nov 2025 20 Jun 2026
by_dex/para/ 0.9 GB 0.8 GB 1 Apr 2026 ongoing
by_dex/vntl/ 0.5 GB 0.4 GB 13 Nov 2025 19 Jun 2026
by_dex/mkts/ 0.5 GB 0.3 GB 1 Jul 2026 ongoing
global/ 352.0 GB 28 Jul 2025 ongoing

The venue folders grow every day, so check the current size before a big download. This prints the file count and total size of any folder (AWS shows GiB, so the number looks slightly smaller than the table):

code
aws s3 ls s3://hydromancer-reservoir/by_dex/io/ --recursive \
  --summarize --human-readable --request-payer requester | tail -2

Listing is cheap: even by_dex/hyperliquid/, about 219,000 files, costs about $0.001 to list.

What to skip

Some folders are ready-made shortcuts. builder_fills/, twap_fills/, liquidations/ and adl/ are filtered from fills/perp/all/, so if you're downloading all/, you already have every row in them. To filter all/ yourself, use the builder, twap_id and is_liquidation columns, and direction = 'Auto-Deleveraging' for ADL fills.

global/fills/raw/ puts every venue's fills in one place. Download it or the venue folders, not both.

Spot and HIP-4 fills live under global/, in fills/spot/all/ and fills/outcome/all/, not in by_dex/hyperliquid/.

The download command

This downloads every Entropy (io) folder except the four shortcut folders. To get a different venue, change io in both paths.

code
aws s3 sync s3://hydromancer-reservoir/by_dex/io/ ./reservoir/io/ \
  --exclude "fills/perp/builder_fills/*" \
  --exclude "fills/perp/twap_fills/*" \
  --exclude "fills/perp/liquidations/*" \
  --exclude "fills/perp/adl/*" \
  --request-payer requester

Add --dryrun first to see the list of files without downloading anything.

sync skips files that haven't changed, so running the same command the next day mostly downloads the new day. If Hydromancer re-exports older files, sync downloads those again too, which keeps your copy up to date.

What it costs: transfer counts toward your account's free 100 GB a month, then $0.114 per GB. Hyperliquid's own markets, skipping the shortcut folders (196 GB), come to roughly $10 in transfer if your free 100 GB is unused, plus about $0.08 in request fees.

Check the newest published day

Each day's files arrive in stages. Fills, candles and snapshots come first, usually between 10:00 and 12:00 UTC. Order books come last, usually between 11:00 and 13:30 UTC, and occasionally later in the day. Once a day's order books are there, that day's files are usually all in.

Before a scheduled job, check the newest order-book folder:

code
aws s3 ls s3://hydromancer-reservoir/by_dex/hyperliquid/orderbook/1m/perps/ \
  --request-payer requester | tail -1

It prints a line like PRE date=2026-10-27/. Use that date as the last day of a scheduled job's range, and leave the day after it for the next run.

Best practices for fetching a particular slice

Where to start

For charts or a first test of a strategy idea, start with candles. For individual trades or liquidations, use fills. For positions and balances at a point in time, use snapshots. For spreads and depth, use order books.

Then narrow it down in this order where you can: dataset, venue, date, market or wallet, and columns. Reservoir organises its files by day, but what you keep can be much smaller than that.

See the Reservoir documentation for the complete schemas, and the Hyperliquid historical-data overview for other ways to get the data.

How to avoid surprises on your AWS bill

• List a folder (aws s3 ls) or check a file's size (aws s3api head-object) before querying it.
• Pick the smallest file that answers your question: by_dex instead of global, liquidations instead of all.
• Select only the columns you need, and filter by market and time.
• Save the result to your computer once, then work on that copy instead of querying S3 again.
• AWS doesn't charge for transfers from S3 to other AWS services in the same region. If you're pulling a lot, run your queries on an AWS server in Tokyo (ap-northeast-1).
• For what each pull costs, see "How much Reservoir costs: Close to nothing".

FAQ

How do I find Trade[XYZ] or another HIP-3 venue's data? Each venue has its own folder under by_dex/, such as by_dex/xyz/ for Trade[XYZ]. See the venue table in "Find your way around Reservoir".

Is Reservoir real-time? No. It's updated once a day: each UTC day is added the following day, around 10:00–12:00 UTC. For live data, use Hydromancer's WebSocket streams.

Why is a date missing? A file only exists for a day that had matching data. Liquidations or ADL files are missing on quiet days. Some snapshot days are also missing, so list the folder first.

How do I get today's data? Reservoir ends at yesterday. For today, use the Hydromancer API (an API key is needed). For example, candleSnapshot returns today's candles.

What if the data I need isn't in Reservoir? Email data@hydromancer.xyz.

Do I have to set up IAM to use Reservoir? No. On a new AWS account, run aws login and sign in as the root user; it needs no setup. A read-only IAM user is safer for regular use and for AI agents. See "Choose how to sign in to AWS".

Why do I get a 403 Access Denied error? Usually because requester pays was left off: add --request-payer requester to aws commands and SET s3_requester_pays = true; in DuckDB. If it still fails, check which user you're signed in as with aws sts get-caller-identity. See "If you get an error".

Do I need a Hydromancer API key? No. You need an AWS account, because the bucket is requester pays.

How much does Reservoir data cost? Usually nothing. Reservoir has no subscription fee, and every AWS account gets 100 GB a month of free internet transfer, which Reservoir downloads count toward. After that, AWS charges $0.114 per GB plus $0.00037 per 1,000 GET requests, so building a month of BTC 1-minute candles costs about $0.07. See "How much Reservoir costs: Close to nothing".

Sources

[1] Hydromancer docs: Reservoir
[2] Reservoir schema: fills
[3] Reservoir schema: candles
[4] Reservoir schema: snapshots
[5] Reservoir schema: order book
[8] DuckDB: reading Parquet files
[9] DuckDB: S3 API support
[10] AWS: Requester Pays buckets
[11] AWS CLI: export-credentials
[12] AWS IAM: creating policies
[13] AWS CLI: named profiles
[14] Amazon S3 pricing

Continue