> For the complete documentation index, see [llms.txt](https://docs.hydromancer.xyz/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.hydromancer.xyz/reservoir/schema-reference/snapshots.md). # Snapshots Daily position snapshots, spot balances, and account values. Daily snapshots of all trader positions, spot token balances, and account values, computed from one on-chain ABCI state per UTC date with the same pipeline that serves the live `perpSnapshot`, `spotSnapshot` and `accountValueSnapshots` endpoints. The file name gives the exact state: `{block}_{timestamp_ms}`. It is not necessarily the last state of the day. Available from July 2025 onward. {% hint style="info" %} Some dates may be missing if the ABCI state file was not available. This is normal — check the S3 listing for available dates. The gap from late October to mid-December 2025 is a known period without ABCI state captures. {% endhint %} {% hint style="info" %} **Changed on 2026-10-15: all dates re-exported.** Every snapshot file was regenerated under the same file name with the live semantics: * A unified account's `account_value` for a collateral token includes its spot balance and is identical on every dex using that token. Take one row; don't sum them. * For unified and portfolio-margin users, the spot `balance` of a collateral token includes their perp equity, as in the live `spotSnapshot`. * Zero-value placeholder rows for unified accounts are gone. * Account values gained `is_unified`, `pm_ratio`, `pm_avail_by_branch` and `pm_total_account_value`, and standard accounts have `account_mode = 'standard'` instead of null. * 2026-03-24 previously held two states, so every row appeared twice; it now holds one. On older dates, standard accounts differ from the previous files only by floating-point rounding. A small share of liquidation prices moved to the formula the live API uses today. {% endhint %} ## S3 Paths **Bucket:** `s3://hydromancer-reservoir` (requester pays) ``` global/snapshots/perp/all/date=YYYY-MM-DD/{block}_{timestamp}.parquet global/snapshots/spot/date=YYYY-MM-DD/{block}_{timestamp}.parquet global/snapshots/account_values/date=YYYY-MM-DD/{block}_{timestamp}.parquet by_dex/{dex}/snapshots/perp/date=YYYY-MM-DD/{block}_{timestamp}.parquet ``` File names include the block number and timestamp (milliseconds) from the ABCI state, e.g., `926030000_1773706027926.parquet`. ## Perp Snapshot Schema One row per user per market. Contains every open perpetual position. | Column | Type | Description | | ------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `user` | string | Wallet address | | `market` | string | Market name (e.g., `BTC`, `xyz:MSFT`) | | `size` | float64 | Position size (positive = long, negative = short) | | `notional` | float64 | Position notional value, in the dex's collateral token | | `entry_price` | float64 | Average entry price | | `liquidation_price` | float64? | Estimated liquidation price (null if not calculable) | | `leverage_type` | string | `cross` or `isolated` | | `leverage` | uint32 | Leverage multiplier | | `funding_pnl` | float64 | Cumulative funding PnL, in the dex's collateral token | | `account_value` | float64 | Margin available on the collateral token of the traded market. For Hyperliquid native markets this is the USDC margin. For HIP-3 dexes this is the margin in the dex's collateral token (e.g., USDE for HyENA, USDH for Felix). Includes spot collateral for unified accounts. | | `account_mode` | string? | `standard`, `dex_abstraction`, `unified`, `portfolio_margin`; null when the state has no mode data | ## Spot Snapshot Schema One row per user per token. Contains all spot token holdings with positive balance. | Column | Type | Description | | ------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `user` | string | Wallet address | | `token` | string | Token name (e.g., `USDC`, `HYPE`, `PURR`) | | `balance` | float64 | Token balance. For unified and portfolio-margin accounts, a collateral token's balance includes the account's perp equity in that token (as in the live `spotSnapshot`) | | `entry_value` | float64 | Entry value in USD | ## Account Values Schema One row per user per dex. Aggregated account-level metrics. | Column | Type | Description | | ------------------------ | ----------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `user` | string | Wallet address | | `dex` | string | DEX name | | `collateral_token` | string | Collateral token (e.g., `USDC`, `USDE`) | | `account_value` | float64 | Account value in the dex's collateral token (never converted to USD). Standard and DEX-abstraction accounts: equity on this dex. Unified accounts: perp equity across every dex using this collateral plus the spot balance of it, identical on each such row. Portfolio margin: the account's balance of this collateral token, negative when the token is borrowed; use `pm_total_account_value` for the account's total. | | `total_long_notional` | float64 | Sum of long position notionals | | `total_short_notional` | float64 | Sum of short position notionals | | `account_mode` | string? | `standard`, `dex_abstraction`, `unified`, `portfolio_margin`; null when the state has no mode data (early 2025 snapshots) | | `is_unified` | bool | True when `account_value` includes spot collateral (unified accounts) | | `pm_ratio` | float64? | Portfolio margin ratio, max across branches, capped at 1.0 like Hyperliquid's `portfolioMarginRatio` (1.0 = at or past liquidation). Portfolio-margin users only | | `pm_avail_by_branch` | list\>? | Available margin per portfolio-margin branch. Portfolio-margin users only | | `pm_total_account_value` | float64? | Total account value across all collateral tokens. Portfolio-margin users only | The `pm_*` fields describe the whole account, so they repeat on each of the user's rows. ## Quick Start ### DuckDB ```sql INSTALL httpfs; LOAD httpfs; SET s3_region = 'ap-northeast-1'; -- Top BTC positions by size on a specific day SELECT user, size, notional, entry_price, liquidation_price, leverage_type, leverage FROM read_parquet('s3://hydromancer-reservoir/by_dex/hyperliquid/snapshots/perp/date=2026-03-22/*.parquet') WHERE market = 'BTC' ORDER BY abs(size) DESC LIMIT 20; -- Open interest by market SELECT market, sum(CASE WHEN size > 0 THEN notional ELSE 0 END) as long_notional, sum(CASE WHEN size < 0 THEN notional ELSE 0 END) as short_notional, count(*) as positions FROM read_parquet('s3://hydromancer-reservoir/global/snapshots/perp/all/date=2026-03-22/*.parquet') GROUP BY market ORDER BY long_notional + abs(short_notional) DESC; -- Largest accounts by value SELECT user, dex, account_value, total_long_notional, total_short_notional FROM read_parquet('s3://hydromancer-reservoir/global/snapshots/account_values/date=2026-03-22/*.parquet') ORDER BY account_value DESC LIMIT 20; -- USDC whale balances SELECT user, balance FROM read_parquet('s3://hydromancer-reservoir/global/snapshots/spot/date=2026-03-22/*.parquet') WHERE token = 'USDC' ORDER BY balance DESC LIMIT 20; ```