> ## 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.

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` for the full type with all fields.

### Funding, deposits, withdrawals, delegations

Each gets its own typed event:

* `HypercoreFundingEvent` - funding rate payment with coin, rate, and amount.
* `HypercoreDepositEvent` - cross-chain deposit into HyperCore.
* `HypercoreWithdrawalEvent` - finalized cross-chain withdrawal.
* `HypercoreDelegationEvent` - 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`](https://goldrush.dev/docs/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 **606,858,021** (2025-05-25T14:32:53Z).

## 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](https://goldrush.dev/docs/goldrush-hyperliquid/streaming/hip4-markets.md).

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

## Reference

* `HypercoreFillTransaction`
* `HypercoreLedgerEvent`
* `HypercoreFundingEvent`
* `HypercoreDepositEvent`
* `HypercoreWithdrawalEvent`
* `HypercoreDelegationEvent`
* Decoded Events Guide - every type, every subtype.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.