---
title: "Large perpetual-futures trades (whale prints)"
method: GET
path: "/api/market/large-trades"
tags: ["public-market-data"]
---

# Large perpetual-futures trades (whale prints)

`GET /api/market/large-trades`

## Request

- Base URL: `https://api.coinrithm.com`
- URL: `https://api.coinrithm.com/api/market/large-trades`
- Auth: none required

Keyless tape of large perpetual-futures prints on Binance USD-M and
Hyperliquid, covering crypto perpetuals and the TradFi perpetuals
those venues list (equities, commodities, FX, indices). Newest first.

A row is one taker order (Binance: consecutive fills at the same
trade time) or one transaction (Hyperliquid) at or above a
per-market USD notional floor. `thresholdUsd` on each row is the
floor that row had to reach; `side` is the taker side. Notional is
in the venue's quote stablecoin (USDT/USDC). `assetClass` is a
best-effort label. Rows exist only while the collector's
connection is live, so gaps are possible and an empty list is not
proof that no large trade happened. Hyperliquid rows may carry the
buyer/seller address and explorer links; Binance publishes no
per-trade page or address.

Hyperliquid rows carry `taker`: what the print did for its taker
wallet (open, add, reduce, close or flip), realized PnL on a reduce,
close or flip, and the wallet's position in that market when it was
enriched (`positionNow.asOf`, not the print instant). `taker` is null
on Binance rows and on a Hyperliquid print that is not enriched yet
or has no match.

`symbol` matches an exact venue symbol when it contains `:` (a
Hyperliquid HIP-3 market such as `xyz:TSLA`) or ends in `USDT`
(`BTCUSDT`); any other value matches the base across venues (`TSLA`
returns `TSLAUSDT` and `xyz:TSLA`). Unknown query parameters return
400. The response is shared-cached for about 15 seconds.

## Query parameters

- `symbol` string
- `venue` 'binance' | 'hyperliquid'
- `assetClass` 'crypto' | 'equity' | 'commodity' | 'fx' | 'index'
- `limit` integer

## Response `200`

Newest large prints, the applied filters and source attribution

- PublicLargeTradesResponse
  - `version` integer, required: Response schema version (1).
  - `generatedAt` string, date-time, required
  - `filters` PublicLargeTradesFilters, required
    - `symbol` string, nullable, required: Canonical symbol or base filter applied, or null.
    - `venue` string, nullable, required
    - `assetClass` string, nullable, required
    - `limit` integer, required
  - `count` integer, required
  - `items` PublicLargeTrade[], required: Newest first.
    - `id` string, required: Opaque stable row id (`venue:symbol:tradeId`).
    - `venue` string, required: `binance` or `hyperliquid`.
    - `symbol` string, required: Venue symbol, e.g. `BTCUSDT` or the Hyperliquid HIP-3 market `xyz:TSLA`.
    - `base` string, required
    - `assetClass` string, required: Best-effort label; currently crypto, equity, commodity, fx or index.
    - `side` string, required: Taker side: `buy` or `sell`.
    - `price` number, required: Average fill price in the quote stablecoin.
    - `qty` number, required: Size in base units.
    - `notionalUsd` number, required: Notional in the venue's quote stablecoin (USDT/USDC).
    - `fills` integer, required: Venue fills merged into this row.
    - `thresholdUsd` number, required: The notional floor this market's prints must reach to be listed.
    - `tradeTime` string, date-time, required: Venue trade time.
    - `ingestedAt` string, date-time, required: When CoinRithm stored the row.
    - `buyer` string, nullable, required: Buyer address when the venue publishes it (Hyperliquid), else null.
    - `seller` string, nullable, required: Seller address when the venue publishes it (Hyperliquid), else null.
    - `links` PublicLargeTradeLinks, required
      - `market` string, uri, required: The venue's market page.
      - `buyer` string, nullable, required: Explorer page of the buyer address (Hyperliquid only).
      - `seller` string, nullable, required: Explorer page of the seller address (Hyperliquid only).
      - `tx` string, nullable, required: Explorer page of the transaction (Hyperliquid only).
    - `taker` PublicLargeTradeTaker: The taker side of a Hyperliquid print, matched from the taker wallet's own fills. `positionNow` is the wallet's position in that market when the row was enriched, which can be after the print.
      - `address` string, required: Taker wallet, lower-case 0x address.
      - `action` string, required: What the print did to the taker's position: `open`, `add`, `reduce`, `close` or `flip` (crossed from long to short or back). Treat other values as unknown.
      - `dir` string, nullable, required: Hyperliquid's own direction text for the fills, e.g. `Open Long`, `Close Short`, or a joined value such as `Close Short / Short > Long / Open Long` when one transaction did several things.
      - `filledQty` number, nullable, required: Size the taker filled, in base units.
      - `realizedPnlUsd` number, nullable, required: Realized PnL of the taker's fills in USD on a reduce, close or flip; null on open and add.
      - `feeUsd` number, nullable, required: Fees the taker paid on these fills, USD.
      - `positionNow` PublicLargeTradeTakerPosition, required
        - `size` number, nullable, required: Signed position size in base units (negative is short); 0 when flat.
        - `avgEntryPrice` number, nullable, required
        - `leverage` number, nullable, required
        - `liquidationPrice` number, nullable, required
        - `unrealizedPnlUsd` number, nullable, required
        - `asOf` string, date-time, required: When the position was read.
  - `source` PublicMarketFeedSource, required
    - `provider` string, required
    - `venues` PublicMarketFeedVenue[], required
      - `venue` string, required
      - `name` string, required
      - `url` string, uri, required
      - `feed` string, required: The venue's public feed the collector reads.
      - `note` string: Venue-specific coverage limitation, when published.
    - `method` string, required: How rows are selected and valued.
    - `coverage` string: Which markets are collected, and the gap caveat.

## Other responses

- `400`: Invalid or unknown query parameter
- `429`: Public request rate limit exceeded; honor `Retry-After`.
- `500`: Large trades temporarily unavailable

---

[API](https://skmtc.dev/coinrithm/apis/coinrithm-agent-trading-api.md) · [All operations](https://skmtc.dev/coinrithm/apis/coinrithm-agent-trading-api/llms.txt) · [OpenAPI document](https://skmtc.dev/coinrithm/apis/coinrithm-agent-trading-api/revisions/28fb59f285fe?raw)