accountValueSnapshot

Unique endpoint allowing to get an account value snapshot of all accounts on Hyperliquid, including filtering by a specific type of collateral or HIP-3 DEX.

accountValueSnapshot

💧New endpoint - this endpoint is not a part of original Hyperliquid API and is added by us for builder convenience.

⚠️ This is an add-on endpoint - access has to be purchased separately.

Overview

The accountValueSnapshot endpoint provides access to aggregated account value data for all users holding positions in specific collateral tokens. This data includes total account values, long/short notional exposures, and is updated in real-time.

There are two ways to access the data:

1. Metadata Endpoint (Fast): Check for updates without downloading data

2. Snapshots Endpoint (Heavy): Download actual account value snapshot data

Use Cases:

• Track total value locked (TVL) per collateral token

• Analyze user distribution and concentration

• Monitor leverage and exposure across the platform

• Build leaderboards and analytics dashboards

• Monitor Portfolio Margin users' cross-collateral health (pm_ratio, avail per branch)

Efficient polling pattern

To minimize bandwidth and server load, you should:

1. Poll the metadata endpoint to check for updates

2. Only call the snapshots endpoint when data has changed

3. Cache the snapshot ID locally to avoid unnecessary downloads

Dependencies and best practices

Dependencies

JavaScript

• zstd: For decompression (e.g., @mongodb-js/zstd)

• msgpack: For decoding (e.g., msgpack-lite)

Python

• zstd: For decompression (e.g., zstandard)

• msgpack: For decoding (e.g., msgpack)

• aiohttp: For async HTTP requests

---

✅ Best Practices

1. Request specific tokens - Don't use ['ALL'] unless you truly need all collateral data.

2. Handle errors gracefully - Network issues are common; implement retry logic.

3. Use appropriate poll intervals - 10-30 seconds is usually sufficient for account value data.

4. Monitor bandwidth usage - Snapshots can be large depending on user count.

5. Cache locally - Store snapshots to avoid unnecessary repeated downloads.

Error handling

• 404: No snapshots are available yet. Wait and retry.

• 500: A server error occurred. Retry with exponential backoff.

• Network errors: Implement retry logic with jitter to avoid overwhelming the server.

• Parse errors: Log the issue and continue using cached data if available.

Account Value Snapshot Metadata (Fast)

• Endpoint: POST /info

• Purpose: Check if snapshots have been updated

• Response Time: ~1ms

Request

{
  "type": "accountValueSnapshotTimestamp"
}

Response

{
  "snapshot_id": "20240915_state_123456789",
  "timestamp": 1694764800
}

Note: Account value snapshots are generated at the same time as perp snapshots, so they share the same timestamp. This endpoint returns the perp snapshot metadata which applies to account values as well.

Account Value Snapshots (Heavy)

• Endpoint: POST /info

• Purpose: Download account value snapshot data for specific collateral tokens

• Response Time: ~100ms+

Request

{
  "type": "accountValueSnapshots",
  "collateral_tokens": ["USDC"]
}

Query Options

Token-only (gets all DEXes using that collateral):

• ["USDC"] → Gets account values for all DEXes that use USDC as collateral

• ["USDE"] → Gets account values for all DEXes that use USDE as collateral

Specific DEX:Token combinations:

• ["hyperliquid:USDC"] → Only Hyperliquid's USDC collateral accounts

• ["xyz:USDC", "vntls:USDE"] → Specific DEX:token combinations

Mixed queries:

• ["USDC", "xyz:USDE"] → All USDC collateral across DEXes + specific xyz:USDE

Practical Query Examples:

// Get all DEXes using USDC as collateral
{"type": "accountValueSnapshots", "collateral_tokens": ["USDC"]}
// Might return: hyperliquid:USDC, xyz:USDC, vntls:USDC (multiple snapshots)

// Get only Hyperliquid's USDC accounts
{"type": "accountValueSnapshots", "collateral_tokens": ["hyperliquid:USDC"]}
// Returns: Only hyperliquid:USDC (single snapshot)

// Get USDC from all DEXes + specific USDE from xyz only
{"type": "accountValueSnapshots", "collateral_tokens": ["USDC", "xyz:USDE"]}
// Returns: All *:USDC snapshots + xyz:USDE snapshot (multiple snapshots)

Response Headers

• Single Snapshot Result: x-payload-format: msgpack, Content-Encoding: zstd

• Multiple Snapshot Results: x-payload-format: multi-zstd, x-compression: inner-zstd

Note: The response format depends on the number of snapshots found, not the number of tokens requested:

• ["USDC"] might return multiple snapshots if USDC is used on multiple DEXes

• ["hyperliquid:USDC"] will return a single snapshot (specific DEX:token combination)

Data Format

Single Token Response

Format: Raw zstd-compressed MessagePack data

Decompressed Structure:

[
  "20240915_account_value_123456789",  // Snapshot ID
  "USDC",                               // Collateral token
  {                                     // Users map
    "0x1234...": [25000.50, 15000.00, 5000.00],
    "0x5678...": [100000.00, 50000.00, 30000.00],
    // more users...
  }
]

ℹ️ User Data Format

Each user entry is a tuple. Standard users have 5 values; Portfolio Margin users have 8 values:

Standard / Unified users (5 values):

account_value          // Total account value in USD
total_long_notional    // Sum of all long position notionals
total_short_notional   // Sum of all short position notionals (absolute value)
is_unified             // Boolean: true if unified account (spot included in account_value)
account_mode           // 0=Standard, 1=DexAbstraction, 2=Unified, 3=PortfolioMargin

Portfolio Margin users (8 values):

account_value          // Per-settlement-token account value (perp equity + spot)
total_long_notional    // Sum of all long position notionals
total_short_notional   // Sum of all short position notionals (absolute value)
is_unified             // Boolean (false for PM users)
account_mode           // 3 (PortfolioMargin)
pm_ratio               // Portfolio margin ratio (max across all branches)
pm_avail_by_branch     // Array of [token_name, available_margin] tuples
pm_total_account_value // Total account value across all collateral tokens

Detecting account type: Check account_mode (index 4) to determine the user's margin mode. For Portfolio Margin users (account_mode == 3), the tuple contains 3 additional fields at indices 5-7. For backwards compatibility, always check the array length before accessing PM fields.

Example PM user data:

"0x1234...": [2597.64, 1500.00, 800.00, false, 3, 0.138, [["USDC", 1999.40], ["USDH", 1000.00]], 5788.74]

Alternative Object Format:

{
  "i": "20240915_account_value_123456789",
  "t": "USDC",
  "u": {
    "0x1234...": {
      "v": 25000.50,
      "l": 15000.00,
      "s": 5000.00,
      "m": false,
      "am": 0
    },
    "0x5678...": {
      "v": 2597.64,
      "l": 1500.00,
      "s": 800.00,
      "m": false,
      "am": 3,
      "pm": 0.138,
      "pa": [["USDC", 1999.40], ["USDH", 1000.00]],
      "pt": 5788.74
    }
  }
}

Multiple Tokens Response

Format: Custom binary format with length prefixes

Binary Structure:

[token_count: 4 bytes][length1: 4 bytes][zstd_data1][length2: 4 bytes][zstd_data2]...

Each zstd_data segment contains a msgpack-encoded AccountValueSnapshot with the same structure as the single token response.

Implementation Examples

Note: Make sure to set HYDROMANCER_API_KEY in your .env file

JavaScript

const axios = require('axios');
const { decompress } = require('@mongodb-js/zstd');
const msgpack = require('msgpack-lite');
const fs = require('fs').promises;
require('dotenv').config();

class AccountValueSnapshotClient {
    constructor() {
        this.baseUrl = process.env.HYDROMANCER_API_URL || 'https://api.hydromancer.xyz';
        this.apiKey = process.env.HYDROMANCER_API_KEY;

        if (!this.apiKey || this.apiKey === 'INSERT_API_KEY_HERE') {
            throw new Error('API key not found. Please set HYDROMANCER_API_KEY in .env file');
        }

        this.cachedSnapshots = {};
        this.cachedTimestamp = null;
        this.outputFile = 'account_value_snapshot.json';
    }

    async checkForUpdates() {
        const headers = {
            'Content-Type': 'application/json',
            'Authorization': `Bearer ${this.apiKey}`
        };

        try {
            const response = await axios.post(
                `${this.baseUrl}/info`,
                { type: 'accountValueSnapshotTimestamp' },
                { headers }
            );

            const currentTimestamp = response.data.timestamp || response.data.snapshot_id;
            const hasUpdates = this.cachedTimestamp !== currentTimestamp;

            if (hasUpdates) {
                console.log(`Account value snapshot updated: ${this.cachedTimestamp} -> ${currentTimestamp}`);
                this.cachedTimestamp = currentTimestamp;
            } else {
                console.log(`No account value snapshot updates (timestamp: ${currentTimestamp})`);
            }

            return hasUpdates;
        } catch (error) {
            throw new Error(`Timestamp request failed: ${error.response?.status} - ${error.response?.data || error.message}`);
        }
    }

    async pollSnapshots(collateralTokens = ['USDC']) {
        try {
            const hasUpdates = await this.checkForUpdates();

            if (!hasUpdates) {
                console.log('No updates available, using cached data');
                return this.cachedSnapshots;
            }

            console.log('New snapshots available, downloading...');
            const snapshots = await this.downloadSnapshots(collateralTokens);

            this.cachedSnapshots = snapshots;
            await this.saveToFile(snapshots);

            return snapshots;
        } catch (error) {
            console.error('Error polling account value snapshots:', error.message);
            throw error;
        }
    }

    async downloadSnapshots(collateralTokens) {
        const headers = {
            'Content-Type': 'application/json',
            'Authorization': `Bearer ${this.apiKey}`
        };

        try {
            const response = await axios.post(
                `${this.baseUrl}/info`,
                {
                    type: 'accountValueSnapshots',
                    collateral_tokens: collateralTokens
                },
                {
                    headers,
                    responseType: 'arraybuffer'
                }
            );

            const payloadFormat = response.headers['x-payload-format'];
            const binaryData = Buffer.from(response.data);

            console.log(`Payload format: ${payloadFormat}`);
            console.log(`Downloaded ${binaryData.length} bytes`);

            if (payloadFormat === 'multi-zstd') {
                return await this.parseMultipleTokens(binaryData);
            } else {
                return await this.parseSingleToken(binaryData, collateralTokens[0]);
            }
        } catch (error) {
            if (error.response) {
                throw new Error(`Request failed: ${error.response.status} - ${error.response.statusText}`);
            }
            throw error;
        }
    }

    async parseSingleToken(binaryData, tokenName) {
        try {
            // Decompress zstd data
            let decompressed;
            try {
                decompressed = await decompress(binaryData);
                console.log('Successfully decompressed single token data');
            } catch (e) {
                // If decompression fails, assume it's already uncompressed
                decompressed = binaryData;
            }

            // Decode msgpack
            const data = msgpack.decode(decompressed);

            // Array format: [snapshot_id, token, users_map]
            if (Array.isArray(data) && data.length >= 3) {
                const [snapshotId, token, usersMap] = data;
                return {
                    [token]: {
                        snapshot_id: snapshotId,
                        token: token,
                        users: this.parseUsers(usersMap),
                        total_users: Object.keys(usersMap).length
                    }
                };
            }

            // Object format: {i: snapshot_id, t: token, u: users}
            if (data.i !== undefined && data.t !== undefined && data.u !== undefined) {
                return {
                    [data.t]: {
                        snapshot_id: data.i,
                        token: data.t,
                        users: this.parseUsers(data.u),
                        total_users: Object.keys(data.u).length
                    }
                };
            }

            throw new Error('Unknown single token data format');
        } catch (error) {
            console.error('Error parsing single token:', error);
            throw error;
        }
    }

    async parseMultipleTokens(binaryData) {
        let offset = 0;

        // Read number of snapshots (4 bytes, little-endian)
        const count = binaryData.readUInt32LE(offset);
        offset += 4;

        console.log(`Number of account value snapshots: ${count}`);

        const tokens = {};

        for (let i = 0; i < count; i++) {
            // Read length of this snapshot (4 bytes, little-endian)
            const length = binaryData.readUInt32LE(offset);
            offset += 4;

            console.log(`Snapshot ${i + 1}/${count}: ${length} bytes`);

            // Extract and decompress snapshot
            const zstdData = binaryData.slice(offset, offset + length);

            try {
                const decompressed = await decompress(zstdData);
                const data = msgpack.decode(decompressed);

                // Array format: [snapshot_id, token, users_map]
                if (Array.isArray(data) && data.length >= 3) {
                    const [snapshotId, token, usersMap] = data;
                    tokens[token] = {
                        snapshot_id: snapshotId,
                        token: token,
                        users: this.parseUsers(usersMap),
                        total_users: Object.keys(usersMap).length
                    };
                    console.log(`Parsed token: ${token} with ${Object.keys(usersMap).length} users`);
                }
                // Object format: {i, t, u}
                else if (data.i !== undefined && data.t !== undefined && data.u !== undefined) {
                    tokens[data.t] = {
                        snapshot_id: data.i,
                        token: data.t,
                        users: this.parseUsers(data.u),
                        total_users: Object.keys(data.u).length
                    };
                    console.log(`Parsed token: ${data.t} with ${Object.keys(data.u).length} users`);
                }
            } catch (error) {
                console.error(`Error parsing snapshot ${i + 1}:`, error);
            }

            offset += length;
        }

        return tokens;
    }

    parseUsers(usersMap) {
        const userList = [];

        for (const [address, userData] of Object.entries(usersMap)) {
            // Array format: [account_value, total_long_notional, total_short_notional]
            if (Array.isArray(userData) && userData.length >= 3) {
                userList.push({
                    address: address,
                    account_value: userData[0],
                    total_long_notional: userData[1],
                    total_short_notional: userData[2]
                });
            }
            // Object format: {v, l, s}
            else if (userData.v !== undefined) {
                userList.push({
                    address: address,
                    account_value: userData.v,
                    total_long_notional: userData.l || 0,
                    total_short_notional: userData.s || 0
                });
            }
        }

        // Sort by account value descending
        userList.sort((a, b) => b.account_value - a.account_value);

        return userList;
    }

    async saveToFile(snapshots) {
        const outputData = {
            timestamp: new Date().toISOString(),
            tokens: {}
        };

        for (const [token, data] of Object.entries(snapshots)) {
            const users = data.users || [];

            // Calculate statistics
            const totalAccountValue = users.reduce((sum, u) => sum + u.account_value, 0);
            const totalLongNotional = users.reduce((sum, u) => sum + u.total_long_notional, 0);
            const totalShortNotional = users.reduce((sum, u) => sum + u.total_short_notional, 0);

            outputData.tokens[token] = {
                snapshot_id: data.snapshot_id,
                total_users: users.length,
                statistics: {
                    total_account_value: totalAccountValue,
                    total_long_notional: totalLongNotional,
                    total_short_notional: totalShortNotional,
                    avg_account_value: users.length > 0 ? totalAccountValue / users.length : 0
                },
                top_10_users: users.slice(0, 10),
                // all_users: users  // Uncomment to save all users
            };
        }

        await fs.writeFile(this.outputFile, JSON.stringify(outputData, null, 2));
        console.log(`\nSaved account value snapshot to ${this.outputFile}`);

        // Print summary
        for (const [token, data] of Object.entries(outputData.tokens)) {
            const stats = data.statistics;
            console.log(`\nToken: ${token}`);
            console.log(`  Total users: ${data.total_users}`);
            console.log(`  Total account value: $${stats.total_account_value.toLocaleString()}`);
            console.log(`  Total long notional: $${stats.total_long_notional.toLocaleString()}`);
            console.log(`  Total short notional: $${stats.total_short_notional.toLocaleString()}`);
            console.log(`  Average account value: $${stats.avg_account_value.toLocaleString()}`);
        }
    }
}

// Example usage - Continuous polling with timestamp check
async function main() {
    const client = new AccountValueSnapshotClient();

    console.log('Starting continuous polling for USDC account values...');
    console.log('Checking for updates every 5 seconds');
    console.log('Press Ctrl+C to stop\n');

    let pollCount = 0;

    while (true) {
        try {
            pollCount++;
            console.log(`\n[${'='.repeat(50)}]`);
            console.log(`Poll #${pollCount} at ${new Date().toISOString()}`);
            console.log(`[${'='.repeat(50)}]`);

            // pollSnapshots automatically checks timestamp first and only downloads if updated
            const snapshots = await client.pollSnapshots(['USDC']);

            // Log results
            for (const [token, data] of Object.entries(snapshots)) {
                console.log(`\n${token}:`);
                console.log(`  Total users: ${data.users?.length || 0}`);
                console.log(`  Snapshot ID: ${data.snapshot_id}`);

                if (data.users && data.users.length > 0) {
                    const totalValue = data.users.reduce((sum, u) => sum + u.account_value, 0);
                    console.log(`  Total account value: $${totalValue.toLocaleString(undefined, {maximumFractionDigits: 2})}`);
                }
            }

            // Wait 5 seconds before next poll
            console.log('\nWaiting 15 seconds before next check...');
            await new Promise(resolve => setTimeout(resolve, 15000));

        } catch (error) {
            console.error('\nPolling error:', error.message);
            console.log('Retrying in 5 seconds...');
            await new Promise(resolve => setTimeout(resolve, 5000));
        }
    }
}

if (require.main === module) {
    main().catch(console.error);
}

module.exports = AccountValueSnapshotClient;

Python