# Tilt Hyperliquid Data API — full reference

Tilt runs its own Hyperliquid node and turns the whole exchange into structured, queryable data:
every open position on every perp on every dex (native and HIP-3) with its size, leverage,
liquidation price and PnL; every fill and liquidation as it happens, and every one since the
index began; every resting stop and take-profit; and derived views such as the liquidation map.
Data is typically under a second behind the chain. Every response says exactly how old it is.

**Start here**
1. `POST /v1/keys` with any identifier (an email, a name, a project). A key comes back immediately. It is free.
2. Send it as `Authorization: Bearer <key>` on every other request.
3. `GET /v1/markets` to see what exists, then `GET /v1/markets/BTC/positions` for the whole book.

**Conventions**
- One envelope: `{ "data": ..., "as_of": { "block", "time", "lag_ms" }, "next": cursor|null }`.
- Sides are `long`/`short` on positions and `buy`/`sell` on orders. Never `A`/`B`.
- Units live in field names: `size_coin`, `notional_usd`, `price_usd`, `leverage`, `*_pct` (0–100).
- Times are ISO 8601 UTC. Blocks are Hyperliquid L1 block numbers.
- Every derived number carries a `definition`.
- Cursor pagination: pass `next` back as `?cursor=`.
- One error shape: `{ "error": { "code", "message" } }`. Unknown or invalid query parameters are a `400`, never ignored.
- Limits (free tier): 300 requests per minute and 20,000 per day per key, 3 stream connections, 1,000,000 stream messages a day. Every response carries `RateLimit-Limit`, `RateLimit-Remaining`, `RateLimit-Reset` (seconds) and `X-Daily-Limit`, `X-Daily-Remaining`, `X-Daily-Reset` (seconds to 00:00 UTC). A `429` adds `Retry-After` and its `code` is `rate_limited` (per minute) or `daily_limit`. More is one request away: `POST /v1/limits/request`. A key turned off for abuse gets `403 key_revoked`.

**Coverage** is measured, not assumed: `GET /v1/status` reports our positions against the exchange's
published open interest every minute, plus latency and the last spot check against the public API.

Base URL: https://api.tilt.markets/v1

## GET /

Machine-readable start page (no key needed)

No key needed. Returns what this API is, how to get a key, and every endpoint with one example. Agents should call this first.

Example: curl -H "Authorization: Bearer $TILT_KEY" https://api.tilt.markets/v1

## POST /keys

Create an API key (no key needed)

Free, instant, no verification. Any identifier works; it is only used so you can find your own keys later. Keep the key private.

Example: curl -X POST https://api.tilt.markets/v1/keys -H 'Content-Type: application/json' -d '{"identifier":"you@example.com"}'

## POST /limits/request

Ask for higher limits (no key needed)

Every key starts on the free tier: 300 requests a minute, 20,000 a day, 3 stream connections
with 100 subscriptions each, 1,000,000 stream messages a day. Hit one and the `429` says which.
To go past it, send your key, an email and what you are building. A person reads it within
minutes and replies to the email, usually within a day, with limits raised on the same key.
No form, no account, no card.

Example: curl -X POST https://api.tilt.markets/v1/limits/request -H 'Content-Type: application/json' -d '{"identifier":"you@example.com"}'

## GET /markets

Every market

Every perp on the native dex and on HIP-3 dexes, with live mark, funding, open interest and volume, followed by every spot pair with `type: spot` (id such as `@107`, symbol such as `HYPE/USDC`, supply and volume). Spot pairs have fills and order events under their id; balances are per wallet. Filter with `type`.

Example: curl -H "Authorization: Bearer $TILT_KEY" https://api.tilt.markets/v1/markets

Parameters:
- type (query, string: perp|spot) — Only perps, or only spot pairs. Default is both.

## GET /tokens

Every spot token

Name, decimals, whether it is a canonical Hyperliquid token, and its HyperEVM contract when it has one. Spot pair ids map to tokens through `/markets?type=spot`.

Example: curl -H "Authorization: Bearer $TILT_KEY" https://api.tilt.markets/v1/tokens

## GET /markets/{market}

One market, live

Mark and mid price, hourly funding, open interest, 24h volume, max leverage and size decimals for one perp; supply and volume for one spot pair. Spot pairs resolve by id (`@107`) or symbol (`HYPE/USDC`).

Example: curl -H "Authorization: Bearer $TILT_KEY" https://api.tilt.markets/v1/markets/BTC

Parameters:
- market (path, required, string) — Market id as listed by `/markets`, e.g. `BTC`, a HIP-3 id like `xyz:XYZ100`, or a spot id like `@107` (a spot symbol like `HYPE/USDC` is accepted too).

## GET /markets/{market}/positions

Every open position in a market

The whole book for this market, one row per wallet, each within a second of its last fill.
Sorted by notional descending by default. Use filters to pull the slice you need:
`side=long&max_distance_to_liquidation_pct=5` is "longs that get liquidated on a 5% drop".
Add `at=<time>` for the book as it was: positions from the newest hourly state snapshot at or
before that time (size, entry and leverage; liquidation price and PnL are not in the state).
With `at`, the other filters do not apply and `cursor` pages by size.

Example: curl -H "Authorization: Bearer $TILT_KEY" https://api.tilt.markets/v1/markets/BTC/positions?side=long&max_distance_to_liquidation_pct=5

Parameters:
- market (path, required, string) — Market id as listed by `/markets`, e.g. `BTC`, a HIP-3 id like `xyz:XYZ100`, or a spot id like `@107` (a spot symbol like `HYPE/USDC` is accepted too).
- at (query, string) — A time (ISO 8601 or epoch ms). Returns the book at the newest hourly snapshot at or before it.
- side (query, string: long|short) — Only longs or only shorts.
- min_notional_usd (query, number) — Only positions at least this large at the mark.
- max_distance_to_liquidation_pct (query, number) — Only positions whose liquidation price is within this many percent of the mark.
- min_leverage (query, number) — Only positions at this leverage or higher.
- sort (query, string: notional_usd|distance_to_liquidation_pct|unrealized_pnl_usd, default notional_usd) — Field to sort by.
- order (query, string: asc|desc, default desc) — Sort direction.
- limit (query, integer, default 100)
- cursor (query, string) — The `next` value from the previous page. Opaque; do not construct one.

## GET /markets/{market}/leverage

Open interest by leverage and by distance to liquidation

The market's open positions folded into buckets, long and short, by the leverage the trader set (1x to 3x, 3x to 5x, and so on) and by how far the mark must move to reach their liquidation price. Rebuilt every second from every position.

Example: curl -H "Authorization: Bearer $TILT_KEY" https://api.tilt.markets/v1/markets/BTC/leverage

Parameters:
- market (path, required, string) — Market id as listed by `/markets`, e.g. `BTC`, a HIP-3 id like `xyz:XYZ100`, or a spot id like `@107` (a spot symbol like `HYPE/USDC` is accepted too).

## GET /markets/{market}/liquidation-map

Forced flow by price

Notional that gets liquidated at each 1% step from the mark, −30% to +30%. Longs liquidate below the mark, shorts above.

Example: curl -H "Authorization: Bearer $TILT_KEY" https://api.tilt.markets/v1/markets/BTC/liquidation-map

Parameters:
- market (path, required, string) — Market id as listed by `/markets`, e.g. `BTC`, a HIP-3 id like `xyz:XYZ100`, or a spot id like `@107` (a spot symbol like `HYPE/USDC` is accepted too).

## GET /markets/{market}/exit-orders

Resting stops and take-profits by price

Declared exits: orders that would reduce an open position and state intent (trigger orders,
reduce-only orders, position TP/SL). Plain limit quotes are not counted. Long stops sit below
the mark and long take-profits above; shorts are mirrored.

Example: curl -H "Authorization: Bearer $TILT_KEY" https://api.tilt.markets/v1/markets/BTC/exit-orders

Parameters:
- market (path, required, string) — Market id as listed by `/markets`, e.g. `BTC`, a HIP-3 id like `xyz:XYZ100`, or a spot id like `@107` (a spot symbol like `HYPE/USDC` is accepted too).

## GET /markets/{market}/book

The order book, twenty levels a side

Live from Hyperliquid's public feed for the largest markets (about the top sixty perps by open
interest and twenty spot pairs by volume; `/markets` shows `book: true` on those). This is the one
dataset on the API served from Hyperliquid's servers rather than our node. Add `at=<time>` for the
newest stored snapshot at or before that time. Snapshots arrive about every three seconds and are
kept thirty days.

Example: curl -H "Authorization: Bearer $TILT_KEY" https://api.tilt.markets/v1/markets/BTC/book

Parameters:
- market (path, required, string) — Market id as listed by `/markets`, e.g. `BTC`, a HIP-3 id like `xyz:XYZ100`, or a spot id like `@107` (a spot symbol like `HYPE/USDC` is accepted too).
- at (query, string) — A time; returns the stored snapshot at or before it.

## GET /markets/{market}/book-history

Mid, spread and depth per snapshot

One row per stored book snapshot, newest first, without the levels. For the levels at one moment use `/book?at=`.

Example: curl -H "Authorization: Bearer $TILT_KEY" https://api.tilt.markets/v1/markets/BTC/book-history?limit=100

Parameters:
- market (path, required, string) — Market id as listed by `/markets`, e.g. `BTC`, a HIP-3 id like `xyz:XYZ100`, or a spot id like `@107` (a spot symbol like `HYPE/USDC` is accepted too).
- from (query, string) — Start of the time range, inclusive. ISO 8601 (`2026-09-26T12:00:00Z`, or a date) or epoch milliseconds.
- to (query, string) — End of the time range, exclusive. Same formats as `from`.
- limit (query, integer, default 100)
- cursor (query, string) — The `next` value from the previous page. Opaque; do not construct one.

## GET /markets/{market}/health

PnL versus margin, both sides

How much of each side is bleeding or sitting on gains, relative to the margin backing it.

Example: curl -H "Authorization: Bearer $TILT_KEY" https://api.tilt.markets/v1/markets/BTC/health

Parameters:
- market (path, required, string) — Market id as listed by `/markets`, e.g. `BTC`, a HIP-3 id like `xyz:XYZ100`, or a spot id like `@107` (a spot symbol like `HYPE/USDC` is accepted too).

## GET /wallets/{address}

One wallet, everything, live

Positions in every market, spot balances, open orders, vault equity and staking, read from the node the moment you ask.

Example: curl -H "Authorization: Bearer $TILT_KEY" https://api.tilt.markets/v1/wallets/0x5b5d51203a0f9079f8aeb098a6523a13f298c060

Parameters:
- address (path, required, string)

## GET /wallets/{address}/positions

A wallet's open positions

Every open perp position of this address across every dex, read from the node the moment you ask, with size, entry, leverage, liquidation price and PnL. Add `at=<time>` for what it held at a past hour, from the state snapshots.

Example: curl -H "Authorization: Bearer $TILT_KEY" https://api.tilt.markets/v1/wallets/0x5b5d51203a0f9079f8aeb098a6523a13f298c060/positions

Parameters:
- address (path, required, string)

## GET /wallets/{address}/orders

A wallet's open orders

Resting orders across every market, including trigger orders, with price, size, type and reduce-only flags. Empty when the wallet has nothing resting.

Example: curl -H "Authorization: Bearer $TILT_KEY" https://api.tilt.markets/v1/wallets/0x5b5d51203a0f9079f8aeb098a6523a13f298c060/orders

Parameters:
- address (path, required, string)

## GET /wallets/{address}/position-history

A wallet's positions hour by hour

One row per market per hourly state snapshot in which the wallet held a position, newest first. Size, entry price and leverage as the chain's state held them. `/wallets/{address}/positions?at=<time>` gives one moment; this gives the series.

Example: curl -H "Authorization: Bearer $TILT_KEY" https://api.tilt.markets/v1/wallets/0x5b5d51203a0f9079f8aeb098a6523a13f298c060/position-history?market=BTC

Parameters:
- address (path, required, string)
- at (query, string) — A time. Returns the wallet's positions at the newest hourly state snapshot at or before it.
- market (query, string) — Only this market.
- from (query, string) — Start of the time range, inclusive. ISO 8601 (`2026-09-26T12:00:00Z`, or a date) or epoch milliseconds.
- to (query, string) — End of the time range, exclusive. Same formats as `from`.
- limit (query, integer, default 100)
- cursor (query, string) — The `next` value from the previous page. Opaque; do not construct one.

## GET /wallets/{address}/fills

A wallet's fill history

Every trade this address made, newest first, with realized PnL and fee on each, plus the fills
where it was the liquidated party. Every wallet's history is served from the same index, built
from the chain's own records, so it starts on the same date for everyone; `history.coverage`
gives the start of each dataset (fills, funding, ledger, order events, TWAPs, snapshots).

Example: curl -H "Authorization: Bearer $TILT_KEY" https://api.tilt.markets/v1/wallets/0x5b5d51203a0f9079f8aeb098a6523a13f298c060/fills?from=2026-09-23

Parameters:
- address (path, required, string)
- market (query, string) — Only this market.
- liquidations_only (query, boolean, default false) — Only the fills where this wallet was liquidated.
- from (query, string) — Start of the time range, inclusive. ISO 8601 (`2026-09-26T12:00:00Z`, or a date) or epoch milliseconds.
- to (query, string) — End of the time range, exclusive. Same formats as `from`.
- since_block (query, integer) — Only fills at or after this L1 block.
- limit (query, integer, default 100)
- cursor (query, string) — The `next` value from the previous page. Opaque; do not construct one.

## GET /wallets/{address}/order-events

Every order event of a wallet

One row per order status transition the chain recorded for this address: `open`, `filled`,
`canceled`, `triggered`, and the rejection codes (`badAloPxRejected`, `perpMarginRejected`, ...),
newest first, from the fill index. Kept for thirty days. This is the placement and cancel
history that fills alone cannot show.

Example: curl -H "Authorization: Bearer $TILT_KEY" https://api.tilt.markets/v1/wallets/0x5b5d51203a0f9079f8aeb098a6523a13f298c060/order-events

Parameters:
- address (path, required, string)
- market (query, string) — Only this market.
- status (query, string) — One status, e.g. `filled` or `canceled`.
- order_id (query, integer) — Follow one order through its transitions.
- from (query, string) — Start of the time range, inclusive. ISO 8601 (`2026-09-26T12:00:00Z`, or a date) or epoch milliseconds.
- to (query, string) — End of the time range, exclusive. Same formats as `from`.
- limit (query, integer, default 100)
- cursor (query, string) — The `next` value from the previous page. Opaque; do not construct one.

## GET /wallets/{address}/twaps

A wallet's TWAP orders, with their execution

Every TWAP order this wallet ran, newest last fill first, summed from its slices, on every market:
22 March to 25 May 2025 and 2 August 2025 on (the chain did not mark TWAP slices in between).
Orders placed since 2026-09-23 also carry their status from our node's TWAP stream. `from` and `to` select orders with a fill in the window.

Example: curl -H "Authorization: Bearer $TILT_KEY" https://api.tilt.markets/v1/wallets/0x5b5d51203a0f9079f8aeb098a6523a13f298c060/twaps

Parameters:
- address (path, required, string)
- market (query, string) — Only this market.
- side (query, string: buy|sell)
- from (query, string) — Start of the time range, inclusive. ISO 8601 (`2026-09-26T12:00:00Z`, or a date) or epoch milliseconds.
- to (query, string) — End of the time range, exclusive. Same formats as `from`.
- limit (query, integer, default 100)
- cursor (query, string) — The `next` value from the previous page. Opaque; do not construct one.

## GET /wallets/{address}/ledger

Deposits, withdrawals, transfers and vault flows of a wallet

Every ledger entry where this address was either party, newest first: `deposit`, `withdraw`,
`send`, `spotTransfer`, `internalTransfer`, `accountClassTransfer`, `subAccountTransfer`,
`vaultDeposit`, `vaultWithdraw`, `vaultLeaderCommission`, `borrowLend`, `rewardsClaim`,
`cStakingTransfer`, `Delegation`, `CDeposit`, `CWithdrawal`, and the rest as the chain names
them. Funding payments have their own route, `/wallets/{address}/funding`. `detail` carries
the raw event for fields a kind has that the columns do not.

Example: curl -H "Authorization: Bearer $TILT_KEY" https://api.tilt.markets/v1/wallets/0x5b5d51203a0f9079f8aeb098a6523a13f298c060/ledger

Parameters:
- address (path, required, string)
- kind (query, string) — One kind, e.g. `deposit` or `withdraw`.
- from (query, string) — Start of the time range, inclusive. ISO 8601 (`2026-09-26T12:00:00Z`, or a date) or epoch milliseconds.
- to (query, string) — End of the time range, exclusive. Same formats as `from`.
- limit (query, integer, default 100)
- cursor (query, string) — The `next` value from the previous page. Opaque; do not construct one.

## GET /markets/{market}/order-events

Order status events in a market

The market's order flow as status transitions, newest first. Filter by `status` to see only fills, only cancels, or only rejections. Kept for thirty days.

Example: curl -H "Authorization: Bearer $TILT_KEY" https://api.tilt.markets/v1/markets/BTC/order-events?status=filled

Parameters:
- market (path, required, string) — Market id as listed by `/markets`, e.g. `BTC`, a HIP-3 id like `xyz:XYZ100`, or a spot id like `@107` (a spot symbol like `HYPE/USDC` is accepted too).
- status (query, string) — One status, e.g. `filled`, `canceled`, `open`, or a rejection code.
- from (query, string) — Start of the time range, inclusive. ISO 8601 (`2026-09-26T12:00:00Z`, or a date) or epoch milliseconds.
- to (query, string) — End of the time range, exclusive. Same formats as `from`.
- limit (query, integer, default 100)
- cursor (query, string) — The `next` value from the previous page. Opaque; do not construct one.

## GET /markets/{market}/twaps

TWAP orders in a market, with their execution

Every TWAP order that filled in this market, newest last fill first, summed from its slices:
size executed, notional, average price, fee, first and last fill, on every market, spot included:
22 March to 25 May 2025 (from Hyperliquid's trades archive, without fee or PnL) and 2 August 2025
on, when the chain began stamping every fill with its TWAP order id. Slices between those dates
were not marked by the chain. Orders placed since 2026-09-23 also carry their status from our node's TWAP stream.
`from` and `to` select orders with a fill in the window; the execution always covers the whole order.

Example: curl -H "Authorization: Bearer $TILT_KEY" https://api.tilt.markets/v1/markets/BTC/twaps?limit=20

Parameters:
- market (path, required, string) — Market id as listed by `/markets`, e.g. `BTC`, a HIP-3 id like `xyz:XYZ100`, or a spot id like `@107` (a spot symbol like `HYPE/USDC` is accepted too).
- side (query, string: buy|sell)
- from (query, string) — Start of the time range, inclusive. ISO 8601 (`2026-09-26T12:00:00Z`, or a date) or epoch milliseconds.
- to (query, string) — End of the time range, exclusive. Same formats as `from`.
- limit (query, integer, default 100)
- cursor (query, string) — The `next` value from the previous page. Opaque; do not construct one.

## GET /wallets/{address}/funding

Every funding payment of a wallet

One row per market per hourly settlement, newest first, from the index. `amount_usd` is positive when the wallet received funding and negative when it paid.

Example: curl -H "Authorization: Bearer $TILT_KEY" https://api.tilt.markets/v1/wallets/0x5b5d51203a0f9079f8aeb098a6523a13f298c060/funding

Parameters:
- address (path, required, string)
- market (query, string) — Only this market.
- from (query, string) — Start of the time range, inclusive. ISO 8601 (`2026-09-26T12:00:00Z`, or a date) or epoch milliseconds.
- to (query, string) — End of the time range, exclusive. Same formats as `from`.
- limit (query, integer, default 100)
- cursor (query, string) — The `next` value from the previous page. Opaque; do not construct one.

## GET /markets/{market}/funding-history

Hourly funding history of a market

One row per hourly settlement, newest first, computed from every settled position in the index. Reaches back to when the funding stream began.

Example: curl -H "Authorization: Bearer $TILT_KEY" https://api.tilt.markets/v1/markets/BTC/funding-history?limit=24

Parameters:
- market (path, required, string) — Market id as listed by `/markets`, e.g. `BTC`, a HIP-3 id like `xyz:XYZ100`, or a spot id like `@107` (a spot symbol like `HYPE/USDC` is accepted too).
- from (query, string) — Start of the time range, inclusive. ISO 8601 (`2026-09-26T12:00:00Z`, or a date) or epoch milliseconds.
- to (query, string) — End of the time range, exclusive. Same formats as `from`.
- limit (query, integer, default 100)

## GET /twaps

TWAP orders by status, from the node's TWAP stream

One row per TWAP order at its latest status, newest first, from our node's TWAP status stream
(kept since 2026-09-23). `status=active` lists the orders running right now (activated and
with minutes left; TWAPs run up to 10,080 minutes), on every market or one market;
`status=waiting` lists orders waiting for their trigger price; `finished`, `terminated`,
`stopped` and `error` list orders that ended that way. Each row also carries the order's
execution summed from its fills and `completion_pct`. Orders placed before 2026-09-23 have no
status; find them by market or wallet under `/markets/{market}/twaps` and `/wallets/{address}/twaps`.

Example: curl -H "Authorization: Bearer $TILT_KEY" https://api.tilt.markets/v1/twaps?status=active

Parameters:
- status (query, string: active|waiting|finished|terminated|stopped|error) — Latest status. `active` means running now (Hyperliquid's own name for it is `activated`); `waiting` means waiting for its trigger price (`waitingForTrigger`).
- market (query, string) — Only this market.
- wallet (query, string) — Only this wallet.
- from (query, string) — Start of the time range, inclusive. ISO 8601 (`2026-09-26T12:00:00Z`, or a date) or epoch milliseconds.
- to (query, string) — End of the time range, exclusive. Same formats as `from`.
- limit (query, integer, default 100)
- cursor (query, string) — The `next` value from the previous page. Opaque; do not construct one.

## GET /twaps/flow

What running TWAPs still have to buy and sell, per market

Every TWAP running now, summed per market and side: how many, the size they still have to
trade (order size less what has filled), its value at the current mark, and the pace at which
it reaches the book if every order runs to its end. `net_remaining_notional_usd` is buy less
sell. Sorted by the size of the net, largest first. Live: statuses from our node within about
two seconds, fills within about one.

Example: curl -H "Authorization: Bearer $TILT_KEY" https://api.tilt.markets/v1/twaps/flow

Parameters:
- market (query, string) — Only this market.

## GET /twaps/stats

TWAP volume per hour or day, one market or all

TWAP slices per UTC hour or day: fills, distinct orders and wallets, notional bought and sold by
TWAPs, and (for one market) size bought and sold. Buckets without TWAP fills are left out. At most
1,000 buckets a call; defaults to the last 48 hours hourly or the last 30 days daily. Covers
22 March to 25 May 2025 and 2 August 2025 on (the chain did not mark TWAP slices in between).

Example: curl -H "Authorization: Bearer $TILT_KEY" https://api.tilt.markets/v1/twaps/stats?market=BTC&interval=1d

Parameters:
- market (query, string) — Only this market; all markets when left out.
- interval (query, string: 1h|1d, default 1h) — Bucket size.
- from (query, string) — Start of the time range, inclusive. ISO 8601 (`2026-09-26T12:00:00Z`, or a date) or epoch milliseconds.
- to (query, string) — End of the time range, exclusive. Same formats as `from`.

## GET /twaps/{id}

One TWAP order, its status, its execution and every slice

The order by its id (the `twap_id` on fills): its latest status when our node saw it
(since 2026-09-23), its execution summed from its fills, and every fill that belongs to it,
oldest first, up to 10,000. Fills from 22 March to 25 May 2025 come from Hyperliquid's trades
archive, which has no fee, realized PnL or trade id; those fields are null, never zero.

Example: curl -H "Authorization: Bearer $TILT_KEY" https://api.tilt.markets/v1/twaps/2261178

Parameters:
- id (path, required, integer) — The TWAP order id.

## GET /fills

Fills, newest first

Every fill, both wallets, with the position before each fill, the realized PnL and fee, and a
`liquidation` block when it was one. The newest fills are served from memory. A `from`/`to`
range, a `wallet`, or a `since_block` older than memory is served from the fill index, which
holds every fill on every market since `history.indexed_from`. Pass `since_block` to resume a
live feed from where you left off.

Example: curl -H "Authorization: Bearer $TILT_KEY" https://api.tilt.markets/v1/fills?market=BTC

Parameters:
- market (query, string) — One market id, e.g. BTC, xyz:GOLD, or a spot id or symbol.
- wallet (query, string) — Fills where this address was either side, or the liquidated party.
- from (query, string) — Start of the time range, inclusive. ISO 8601 (`2026-09-26T12:00:00Z`, or a date) or epoch milliseconds.
- to (query, string) — End of the time range, exclusive. Same formats as `from`.
- since_block (query, integer) — Only fills at or after this L1 block; the way to resume a feed without missing or repeating anything.
- liquidations_only (query, boolean, default false) — Only fills that were liquidations.
- limit (query, integer, default 100)
- cursor (query, string) — The `next` value from the previous page. Opaque; do not construct one.

## GET /liquidations

Liquidations, newest first

Same records as `/fills` filtered to liquidations, every market, with the liquidated wallet and the mark it fired at. With no range, the last day; with `from`/`to`, any window back to when the index began.

Example: curl -H "Authorization: Bearer $TILT_KEY" https://api.tilt.markets/v1/liquidations?market=BTC

Parameters:
- market (query, string) — One market id. Omit for every market.
- from (query, string) — Start of the time range, inclusive. ISO 8601 (`2026-09-26T12:00:00Z`, or a date) or epoch milliseconds.
- to (query, string) — End of the time range, exclusive. Same formats as `from`.
- since_block (query, integer) — Only liquidations at or after this L1 block.
- limit (query, integer, default 100)
- cursor (query, string) — The `next` value from the previous page. Opaque; do not construct one.

## GET /stream

WebSocket stream of fills, liquidations, positions, orders, TWAPs, ledger, funding and books (no key needed)

Connect with a WebSocket client to `wss://api.tilt.markets/v1/stream?key=<key>` (or send the
key as `Authorization: Bearer`). Then send subscriptions as JSON:

- `{"op":"subscribe","channel":"fills","market":"BTC"}` — every fill in a market as it lands.
- `{"op":"subscribe","channel":"fills","wallet":"0x..."}` — a wallet's fills.
- `{"op":"subscribe","channel":"fills","market":"BTC","since_block":1162000000}` — replay the
  tape from that block (messages carry `"replay": true`, then `{"op":"replay_done"}`), then live.
- `{"op":"subscribe","channel":"liquidations"}` — every liquidation on every market.
- `{"op":"subscribe","channel":"positions","market":"BTC"}` — every position change the node
  reads: opens, resizes, closes (`"closed": true`). Also by `wallet`.
- `{"op":"subscribe","channel":"orders","wallet":"0x..."}` — order status events. Also by `market`.
- `{"op":"subscribe","channel":"ledger","wallet":"0x..."}` — deposits, withdrawals, transfers.
- `{"op":"subscribe","channel":"twaps","market":"BTC"}` — TWAP order status changes: placed,
  finished, terminated, error. Also by `wallet`. Each message carries `twap_id`, `wallet`, `market`, `side` and `order`.
- `{"op":"subscribe","channel":"funding","market":"BTC"}` — hourly settlements. Also by `wallet`.
- `{"op":"subscribe","channel":"book","market":"BTC"}` — each book snapshot as it arrives, largest markets only.
- `{"op":"unsubscribe", ...}` and `{"op":"ping"}`.

Each message is `{"channel", "market"|"wallet", "data", "as_of"}` where `data` has exactly the
shape the REST route for that object returns. The server pings every 20 seconds; a client that
falls more than 32 MB behind is disconnected with code 1008. The free tier allows 3 connections
per key, 100 subscriptions per connection and 1,000,000 messages a day; `POST /v1/limits/request`
for more. The key goes in the URL or the Authorization header. A plain HTTP GET on this path returns 426.

Example: curl -H "Authorization: Bearer $TILT_KEY" https://api.tilt.markets/v1/stream

## GET /status

Is the data complete and current right now? (no key needed)

Coverage against the exchange's open interest, node lag, last spot check against the public API, and whether the node is streaming. No key needed.

Example: curl -H "Authorization: Bearer $TILT_KEY" https://api.tilt.markets/v1/status

## Schemas

### Error
- error (object)
  - code (string)
  - message (string)

### AsOf
How current the data is. `lag_ms` is the time between the newest chain block we hold and now.
- block (integer, nullable)
- time (string)
- lag_ms (integer)

### Envelope
- data (object)
- as_of (AsOf)
- next (string, nullable) — Cursor for the next page, or null.

### Market
- id (string)
- type (string) one of perp|spot
- dex (string) — Empty for the native dex, otherwise the HIP-3 dex name.
- mark_price_usd (number)
- mid_price_usd (number, nullable)
- funding_rate_hourly (number) — Fraction per hour. Positive means longs pay shorts.
- open_interest_coin (number) — Both sides summed, as Hyperliquid publishes it.
- open_interest_usd (number) — One side, at mark.
- volume_24h_usd (number)
- max_leverage (integer)
- size_decimals (integer)
- tracked (boolean) — True when positions, exit orders and liquidation maps are available (every perp). False for spot pairs, which have fills and order events only.
- book (boolean) — True when the order book is followed for this market (the largest by open interest and spot volume).
- symbol (string) — Spot only, e.g. HYPE/USDC.
- base_token (string) — Spot only.
- quote_token (string) — Spot only.
- prev_day_price_usd (number) — Spot only.
- volume_24h_base (number) — Spot only, in the base token.
- circulating_supply (number) — Spot only.
- total_supply (number) — Spot only.

### Position
- wallet (string)
- market (string)
- side (string) one of long|short
- size_coin (number) — Absolute size in coin units.
- notional_usd (number) — size_coin × mark.
- leverage (number)
- margin_mode (string) one of cross|isolated
- entry_price_usd (number, nullable)
- liquidation_price_usd (number, nullable) — Null when the wallet cannot be liquidated at any positive price.
- distance_to_liquidation_pct (number, nullable) — How far the mark must move against the position, in percent of mark.
- unrealized_pnl_usd (number)
- margin_used_usd (number)
- pnl_to_margin (number, nullable) — unrealized_pnl_usd ÷ margin_used_usd. −0.5 means half the margin is lost.
- updated_at (string) — When this row last changed.

### PositionsSummary
- count (integer)
- long_notional_usd (number)
- short_notional_usd (number)
- coverage_long_pct (number) — Our long notional ÷ exchange open interest per side, ×100.
- coverage_short_pct (number)

### Leverage
- buckets (array) — Notional by the leverage the trader set.
  - label (string)
  - long_notional_usd (number)
  - short_notional_usd (number)
  - count (integer)
- distance_bands (array) — Notional by distance to liquidation.
  - label (string)
  - long_notional_usd (number)
  - short_notional_usd (number)
  - long_count (integer)
  - short_count (integer)
- definition (string)

### LiquidationMap
- mark_price_usd (number)
- rungs (array)
  - from_pct (integer) — Lower edge of the rung relative to mark, e.g. −2 means −2% to −1%.
  - price_from_usd (number)
  - price_to_usd (number)
  - long_notional_usd (number)
  - short_notional_usd (number)
  - count (integer)
- beyond_range (object)
  - long_notional_usd (number) — Longs with liquidation below −30%.
  - short_notional_usd (number) — Shorts with liquidation above +30%.
- definition (string)

### ExitOrders
- mark_price_usd (number)
- rungs (array)
  - from_pct (integer)
  - long_stop_usd (number)
  - long_take_profit_usd (number)
  - short_stop_usd (number)
  - short_take_profit_usd (number)
- within_5_pct (object)
  - long_stops_usd (number)
  - long_take_profits_usd (number)
  - short_stops_usd (number)
  - short_take_profits_usd (number)
- largest (array)
  - wallet (string)
  - side (string) one of long|short
  - kind (string) one of stop|take_profit
  - trigger_price_usd (number)
  - distance_from_mark_pct (number)
  - notional_usd (number)
- holders_scanned (integer)
- holders_with_exit_orders (integer)
- definition (string)

### MarketHealth
- buckets (array)
  - label (string)
  - long_notional_usd (number)
  - short_notional_usd (number)
  - count (integer)
- trapped (object) — Notional that has lost more than half its margin.
  - long_notional_usd (number)
  - short_notional_usd (number)
  - long_pct_of_side (number)
  - short_pct_of_side (number)
- definition (string)

### Order
- market (string)
- side (string) one of buy|sell
- type (string)
- price_usd (number) — Trigger price for trigger orders, limit price otherwise.
- size_coin (number)
- reduce_only (boolean)
- is_trigger (boolean)
- placed_at (string)

### Wallet
- address (string)
- account_value_usd (number)
- margin_used_usd (number)
- withdrawable_usd (number)
- positions (array)
- orders (array)
- spot_balances (array)
  - token (string)
  - total (number)
  - hold (number)
- vault_equities (array)
  - vault (string)
  - equity_usd (number)
- staking (object)
  - delegated (number)
  - undelegated (number)
  - pending_withdrawal (number)

### FillHistory
Where this page came from and how far back the fill index reaches.
- source (string) one of memory|index — memory is the live tape, index is the fill index on disk.
- fills_in_memory (integer)
- indexed_from (string, nullable) — The oldest fill in the index. Every fill on every market since then is queryable.
- indexed_fills (integer)
- note (string)

### Fill
- block (integer)
- time (string)
- market (string)
- wallet (string)
- side (string) one of buy|sell
- price_usd (number)
- size_coin (number)
- position_before_coin (number) — Signed position before this fill.
- position_after_coin (number)
- direction (string)
- realized_pnl_usd (number, nullable)
- fee_usd (number, nullable) — Negative is a rebate.
- taker (boolean, nullable) — True when this side crossed the book.
- tx_hash (string, nullable)
- trade_id (integer, nullable)
- twap_id (integer, nullable) — The TWAP order this fill is a slice of, when it is one; see /twaps/{id}. Stamped by the chain since 2 August 2025; TWAP slices from 22 March to 25 May 2025 carry it under /twaps.
- liquidation (object, nullable)
  - liquidated_wallet (string)
  - mark_price_usd (number)
  - method (string)

### Twap
A TWAP order: Hyperliquid slices it and sends a piece to the book every 30 seconds until the size or the minutes run out (up to 10,080 minutes). `order` is its latest status from our node's TWAP stream (since 2026-09-23); `execution` is summed from its fills (22 March to 25 May 2025, and 2 August 2025 on). Either is null when that source does not know the order.
- twap_id (integer)
- wallet (string)
- market (string)
- side (string) one of buy|sell
- order (object, nullable)
  - status (string) — waitingForTrigger, activated (running), finished, terminated, stopped, or error.
  - size_coin (number) — The size the order was placed for.
  - executed_size_coin (number) — Executed size as the chain reported it at this status.
  - executed_notional_usd (number)
  - minutes (integer) — The duration the order was placed for.
  - reduce_only (boolean)
  - randomize (boolean) — True when slice timing was randomized.
  - started_at (string) — When the order was placed.
  - ends_at (string) — When its minutes run out.
  - updated_at (string) — When this status was recorded.
  - block (integer)
  - error (string, nullable) — The chain's reason when status is error.
- execution (object, nullable)
  - fills (integer) — Number of fills that belong to the order.
  - executed_size_coin (number)
  - executed_notional_usd (number)
  - average_price_usd (number, nullable) — Notional over size.
  - fee_usd (number, nullable) — Negative is a rebate. Null when any fill came from the March to May 2025 trades archive, which has no fees.
  - realized_pnl_usd (number, nullable) — Null for the same reason as fee_usd.
  - first_fill (string)
  - last_fill (string)
  - first_block (integer, nullable) — Null for fills from the March to May 2025 trades archive
  - last_block (integer, nullable)
- completion_pct (number, nullable) — Executed size over the order's size, 0 to 100. Null when the order's size is not known (placed before 2026-09-23).

### TwapFlowSide
- twaps (integer) — Running TWAPs on this side.
- remaining_size_coin (number) — Order size less what has filled.
- remaining_notional_usd (number, nullable) — The remaining size at the current mark.
- notional_per_minute_usd (number, nullable) — The pace at which it reaches the book if every order runs to its end.

### OrderEvent
One order status transition as the chain recorded it.
- time (string)
- block (integer)
- wallet (string)
- market (string)
- status (string) — open, filled, canceled, triggered, marginCanceled, reduceOnlyCanceled, or a rejection code such as badAloPxRejected.
- order_id (integer)
- client_order_id (string, nullable)
- side (string) one of buy|sell
- price_usd (number)
- size_coin (number) — Remaining size at this event.
- original_size_coin (number)
- type (string) — Limit, Market, Stop Market, Stop Limit, Take Profit Market, Take Profit Limit.
- time_in_force (string, nullable) — Gtc, Ioc, Alo (post-only), FrontendMarket.
- is_trigger (boolean)
- trigger_price_usd (number, nullable)
- trigger_condition (string, nullable)
- reduce_only (boolean)
- position_tpsl (boolean)
- placed_at (string)
- tx_hash (string, nullable)
- builder (string, nullable)

### LedgerEntry
One movement of value on the chain involving the wallet.
- time (string)
- block (integer)
- kind (string) — deposit, withdraw, send, spotTransfer, internalTransfer, accountClassTransfer, subAccountTransfer, vaultDeposit, vaultWithdraw, and others as the chain names them.
- wallet (string) — The initiating address.
- counterparty (string, nullable) — The other party, vault, or destination when there is one.
- token (string, nullable)
- amount (number) — In the token's units.
- usdc_value (number)
- fee_usd (number)
- source_dex (string, nullable)
- destination_dex (string, nullable)
- tx_hash (string, nullable)
- detail (object, nullable) — The raw event as written.

### SnapshotPosition
A position as the chain's hourly state snapshot held it.
- wallet (string)
- market (string)
- side (string) one of long|short
- size_coin (number)
- entry_price_usd (number, nullable)
- leverage (integer)
- margin_mode (string) one of cross|isolated
- snapshot_time (string)
- block (integer)

### Book
- market (string)
- time (string) — The exchange's time for the snapshot.
- bids (array) — Best first.
  - price_usd (number)
  - size_coin (number)
  - orders (integer)
- asks (array) — Best first.
  - price_usd (number)
  - size_coin (number)
  - orders (integer)
- mid_price_usd (number)
- spread_bps (number, nullable)
- bid_depth_1pct_usd (number) — Notional resting within 1% below mid.
- ask_depth_1pct_usd (number) — Notional resting within 1% above mid.