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

# Trades And Liquidations Routes

> Use 0xArchive trade, recent-trade, liquidation, and liquidation-volume routes without mixing venue families or unsupported datasets.

Trades and liquidations are separate event families. A venue can support trades without supporting liquidations in the same way, and a liquidation-volume summary is not the same dataset as raw liquidation events. Preserve venue family and route path in storage so downstream analysis does not mix unrelated sources.

## Route Families

| Need                          | Start with                                                                                 |
| ----------------------------- | ------------------------------------------------------------------------------------------ |
| Hyperliquid core trades       | `/v1/hyperliquid/trades/{symbol}`                                                          |
| Hyperliquid core liquidations | `/v1/hyperliquid/liquidations/{symbol}` and `/v1/hyperliquid/liquidations/{symbol}/volume` |
| Hyperliquid Spot trades       | `/v1/hyperliquid/spot/trades/{symbol}`                                                     |
| HIP-3 trades                  | `/v1/hyperliquid/hip3/trades/{symbol}` and `/recent`                                       |
| HIP-3 liquidations            | `/v1/hyperliquid/hip3/liquidations/{symbol}` and `/volume`                                 |
| HIP-4 trades                  | `/v1/hyperliquid/hip4/trades/{symbol}` and `/recent`                                       |
| Lighter trades                | `/v1/lighter/trades/{symbol}` and `/recent`                                                |

## Usage Pattern

<Steps>
  <Step title="Confirm symbol family">
    A Spot pair, HIP-3 builder symbol, HIP-4 outcome side, and Lighter symbol need different routes.
  </Step>

  <Step title="Pick trade or liquidation data">
    Do not route a liquidation question to a trade endpoint just because both are historical events.
  </Step>

  <Step title="Check coverage">
    Trade and liquidation windows can have different coverage starts and access behavior.
  </Step>

  <Step title="Store request IDs">
    Backtests, heatmaps, and risk reports should preserve request IDs per page or window.
  </Step>
</Steps>

## Exports And Examples

Data Catalog export schemas include `trades` and `liquidations` as separate choices. For parser behavior, use [Responses](/responses). For bounded request examples, use [Examples](/examples) and the generated REST reference.

## Parser Notes

Do not join trades and liquidations only by timestamp. Keep side, price, size, route family, source route, and request window with each row. For liquidation-volume summaries, store the aggregation route separately from raw liquidation events so reports can explain whether they used events, volume buckets, or both.

Use recent-trade routes for short, current inspection and historical routes for bounded windows. Mixing those paths without a label makes backtests harder to explain later.

## Raw Events Vs Volume

Use raw liquidation event routes, such as `/v1/hyperliquid/liquidations/{symbol}` or `/v1/hyperliquid/hip3/liquidations/{symbol}`, when the workload needs event-level liquidation records for audit, replay, or model input. These routes can be heavier because they return event rows and may need pagination, tighter windows, and a lower concurrency budget.

Use `/volume`, such as `/v1/hyperliquid/liquidations/{symbol}/volume?interval=1h` or `/v1/hyperliquid/hip3/liquidations/{symbol}/volume?interval=1h`, when the workload needs aggregate liquidation-volume buckets for dashboards, scans, or backtests that do not inspect every raw event. For high-volume dashboards and repeated backtests, start with `/volume` and keep raw event pulls as a narrower drill-down path.

For liquidation routes that return `429`, honor `Retry-After` when present. If it is absent, use capped exponential backoff with jitter, reduce concurrency, and keep `meta.request_id` or `x-request-id` for the failed attempts. Do not retry unchanged after auth, access, malformed-request, unsupported-symbol, or invalid-parameter errors; fix the request or key before the next attempt.

## Next Call After A Liquidation 429

When a raw liquidation route rate-limits, choose the next call based on the workflow instead of replaying the same request unchanged.

| Workflow                                      | Safer next call                                                                                                           |
| --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
| Dashboard, scan, or repeated backtest summary | `/v1/hyperliquid/liquidations/{symbol}/volume?interval=1h` or the matching HIP-3 `/volume` route                          |
| Event-level audit or model input              | Same raw route with a smaller time window, lower concurrency, and request-ID logging                                      |
| Unclear venue family                          | Check [Venue Coverage](/venue-coverage) before switching between Hyperliquid core, Spot, HIP-3, HIP-4, and Lighter routes |

Keep the failed raw-event path, `Retry-After` value when present, `meta.request_id` or `x-request-id`, and the chosen next-call route in the job log. That makes the retry decision reviewable when a backtest, alert, or export is handed to another engineer or coding agent.

## Evaluation Fit

When a team says it needs "the tape," confirm whether it needs raw trades, liquidation events, liquidation volume, or all three. A dashboard can often start with trades and summaries. A backtest, liquidation heatmap, or risk model needs route-level lineage and a data-quality check before results are saved.

## Next Step

Open [Examples](/examples) for request patterns, [Example Responses](/response-examples) for payload shapes, [Responses](/responses) for envelope parsing, or [Data Quality](/data-quality) before using trades and liquidations in model inputs.