> ## Documentation Index
> Fetch the complete documentation index at: https://goldrush.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Liquidations and Vault Events

> Pre-decoded liquidation, vault, staking, delegation, and borrow/lend events from HyperCore - typed and ready to consume, with no parsing required.

export const HYPERCORE_START_TIMESTAMP = "2025-05-25T14:32:53Z";

export const HYPERCORE_START_BLOCK = "606,858,021";

The public Hyperliquid `/info` API surfaces raw building blocks; you write the parser. **Liquidations** are buried inside fills as a thin stub, and **vault, staking, and delegation** activity arrives as untyped ledger updates you have to classify yourself.

GoldRush ships every one of these pre-decoded and typed.

## What's pre-decoded

### Liquidations

Inline with the fill that triggered them, with full context:

| Field                    | Description                                             |
| ------------------------ | ------------------------------------------------------- |
| `method`                 | `Market` or `Backstop`.                                 |
| `liquidated_user`        | The wallet whose position was liquidated.               |
| `market_price`           | Mark price at the moment of liquidation.                |
| `liquidated_positions[]` | Every position closed by the liquidation (coin + size). |
| `account_value`          | Account value at the time of liquidation.               |
| `leverage_type`          | Cross or isolated.                                      |

### 20+ ledger event subtypes

| Subtype                           | Description                                                  |
| --------------------------------- | ------------------------------------------------------------ |
| `LedgerLiquidation`               | Standalone liquidation ledger event with full position list. |
| `LedgerVaultDeposit`              | Deposit into a vault.                                        |
| `LedgerVaultWithdraw`             | Withdrawal request from a vault, with commission and basis.  |
| `LedgerVaultLeaderCommission`     | Commission earned by a vault leader.                         |
| `LedgerVaultDistribution`         | Distribution from a vault to depositors.                     |
| `LedgerVaultCreate`               | New vault creation event.                                    |
| `LedgerCStakingTransfer`          | Hyperliquid staking deposit/withdrawal.                      |
| `LedgerBorrowLend`                | Borrow or lend operation.                                    |
| `LedgerRewardsClaim`              | Validator or program reward claim.                           |
| `LedgerDeposit`, `LedgerWithdraw` | Bridge in/out.                                               |
| `LedgerInternalTransfer`          | Sub-account transfer.                                        |
| `LedgerSpotTransfer`              | Spot token transfer with USDC value.                         |
| `LedgerSubAccountTransfer`        | Sub-account funds movement.                                  |
| `LedgerSend`                      | Cross-DEX send (with `source_dex` and `destination_dex`).    |
| `LedgerAccountClassTransfer`      | Account-class movement (perp/spot).                          |
| `LedgerAccountActivationGas`      | Activation gas charged on first deposit.                     |
| `LedgerSpotGenesis`               | Spot token genesis allocation.                               |
| `LedgerDeployGasAuction`          | HIP-3 market deployment gas auction.                         |
| `LedgerPerpDexClassTransfer`      | Transfer between HIP-3 perp DEXes and core perp.             |

See [`HypercoreLedgerEvent`](/api-reference/streaming-api/types/hypercore-ledger-event) for the full type with all fields.

### Funding, deposits, withdrawals, delegations

Each gets its own typed event:

* [`HypercoreFundingEvent`](/api-reference/streaming-api/types/hypercore-funding-event) - funding rate payment with coin, rate, and amount.
* [`HypercoreDepositEvent`](/api-reference/streaming-api/types/hypercore-deposit-event) - cross-chain deposit into HyperCore.
* [`HypercoreWithdrawalEvent`](/api-reference/streaming-api/types/hypercore-withdrawal-event) - finalized cross-chain withdrawal.
* [`HypercoreDelegationEvent`](/api-reference/streaming-api/types/hypercore-delegation-event) - staking delegation or undelegation with validator address.

## Subscribe

Pull liquidations, fills, and ledger events for a wallet (or many) in one stream:

```typescript theme={null}
import { GoldRushClient } from "@covalenthq/client-sdk";

const client = new GoldRushClient(process.env.GOLDRUSH_API_KEY);

const SUBSCRIPTION_QUERY = `
  subscription {
    walletTxs(
      wallet_addresses: ["0xecb63caa47c7c4e77f60f1ce858cf28dc2b82b00"]
      chain_name: HYPERCORE_MAINNET
    ) {
      tx_hash
      block_signed_at
      decoded_details {
        ... on HypercoreFillTransaction {
          coin side price size closed_pnl
          liquidation {
            method
            liquidated_user
            market_price
          }
        }
        ... on HypercoreLedgerEvent {
          ledger_type
          time
          delta {
            ... on LedgerLiquidation {
              account_value
              leverage_type
              liquidated_ntl_pos
              liquidated_positions { coin szi }
            }
            ... on LedgerVaultDeposit { vault user usdc }
            ... on LedgerVaultWithdraw {
              vault user requested_usd commission basis closing_cost
            }
            ... on LedgerVaultLeaderCommission { vault usdc }
            ... on LedgerVaultDistribution { vault usdc }
            ... on LedgerCStakingTransfer { token amount is_deposit }
            ... on LedgerBorrowLend { token amount interest_amount operation }
            ... on LedgerRewardsClaim { amount }
          }
        }
      }
    }
  }
`;

client.StreamingService.rawQuery(
  SUBSCRIPTION_QUERY,
  {},
  {
    next: (data) => console.log(JSON.stringify(data, null, 2)),
    error: (err) => console.error(err),
  }
);
```

## Patterns

### Live liquidation tape

Filter the stream on `HypercoreFillTransaction` where `liquidation` is non-null. Display each liquidation in a chronological feed with the user, mark price, method, and total position value.

### "X just got liquidated for \$Y" notifications

Push every non-null `liquidation` to a notification channel. Use `account_value` to compute the dollar size and `liquidated_positions[]` to list the markets.

### Position-risk warnings

Combine [`clearinghouseState`](/api-reference/hyperliquid-info/clearinghouse-state) (read `liquidationPx`, `marginUsed`, `accountValue`) with live `LedgerLiquidation` events for similar wallets to flag at-risk positions before they liquidate.

### Vault leaderboards

Aggregate `LedgerVaultLeaderCommission` and `LedgerVaultDistribution` events per vault address. Surface top-performing vaults by commission earned or distribution payout.

### Staking and rewards tabs

Subscribe to `LedgerCStakingTransfer`, `HypercoreDelegationEvent`, and `LedgerRewardsClaim` for a user. Display delegation history, current stake, and rewards earned.

### Borrow/lend position trackers

Filter on `LedgerBorrowLend` for `operation: "borrow" | "repay" | "open" | "close"`. Display per-token borrow positions with cumulative interest.

## Historical depth

Every fill, funding payment, and ledger event is retained back to HyperCore block **{HYPERCORE_START_BLOCK}** ({HYPERCORE_START_TIMESTAMP}). For warehouse delivery - every ledger event landing in your database continuously - use the [Pipeline API](/goldrush-pipeline-api/normalizers/hypercore) (`hl_misc_events`).

## Pair address format

Hyperliquid markets use a **deployer-prefix naming scheme**. The exact string differs by surface, so pass the value each API expects - matching is case- and format-sensitive.

| Where it's used                                                       | Format                                                                   | Examples                                    |
| --------------------------------------------------------------------- | ------------------------------------------------------------------------ | ------------------------------------------- |
| WebSocket `coin` (`l2Book`, `l2BookDiff`, `l4Book`) - canonical perps | `<symbol>`                                                               | `BTC`, `ETH`, `HYPE`                        |
| WebSocket `coin` - HIP-3 builder markets                              | `<deployer>:<symbol>`                                                    | `xyz:GOLD`, `flx:OIL`                       |
| Streaming `pair_addresses` (`ohlcvCandlesForPair`)                    | `<deployer>:<symbol>-<quote>`, or `<symbol>-<quote>` for canonical pairs | `xyz:GOLD-USDC`, `flx:OIL-USDH`, `BTC-USDC` |
| Streaming `token_addresses` (`ohlcvCandlesForToken`)                  | `<symbol>` (no prefix)                                                   | `GOLD`, `OIL`, `BTC`                        |

* `deployer` - wallet address of the HIP-3 builder that deployed the market. Omitted for canonical Hyperliquid markets.
* `symbol` - market ticker (e.g. `GOLD`, `OIL`).
* `quote` - the margin / quote currency, usually `USDC` (some HIP-3 markets use `USDH`).

<Note>HIP-4 outcome markets use a separate `#<encoding>` scheme (e.g. `#1230`), not the deployer-prefix - see [HIP-4 Markets](/goldrush-hyperliquid/streaming/hip4-markets).</Note>

**Discovering markets:** a dedicated market-list endpoint (the `perpDexs` Info API type) is on the roadmap. Until it ships, call [`metaAndAssetCtxs`](/api-reference/hyperliquid-info/meta-and-asset-ctxs) - the `name` field on each `universe` entry is the canonical pair address.

## Reference

* [`HypercoreFillTransaction`](/api-reference/streaming-api/types/hypercore-fill-transaction)
* [`HypercoreLedgerEvent`](/api-reference/streaming-api/types/hypercore-ledger-event)
* [`HypercoreFundingEvent`](/api-reference/streaming-api/types/hypercore-funding-event)
* [`HypercoreDepositEvent`](/api-reference/streaming-api/types/hypercore-deposit-event)
* [`HypercoreWithdrawalEvent`](/api-reference/streaming-api/types/hypercore-withdrawal-event)
* [`HypercoreDelegationEvent`](/api-reference/streaming-api/types/hypercore-delegation-event)
* [Decoded Events Guide](/goldrush-streaming-api/decoded-events) - every type, every subtype.