From 303b6e078fbfd2a6fc44e0c888a69f1879916505 Mon Sep 17 00:00:00 2001
From: 0xFantomMenace <93462858+0xFantomMenace@users.noreply.github.com>
Date: Sat, 26 Sep 2026 05:03:03 +0000
Subject: [PATCH 1/5] release 1.10.0: Lighter on Robinhood Chain, positions,
 Lighter liquidations

- --exchange rh-lighter (Lighter on Robinhood Chain, the second Lighter
  deployment) on every shared market-data command Lighter mainnet supports.
- Live rh_lighter_orderbook, rh_lighter_trades, rh_lighter_open_interest and
  rh_lighter_funding streams; --interval-ms on rh_lighter_orderbook;
  rh_lighter_candles is replay-only.
- oxa positions get/history/changes/market/summary/all on hyperliquid, hip3,
  lighter and rh-lighter, plus account/account-history on hyperliquid and
  hip3, and oxa accounts by-l1 for Lighter mainnet.
- Liquidation history and volume on both Lighter deployments.
- orders/l4/l2 refuse Lighter deployments before any request.
- Lighter trade ranges pass the finalization meta through.
- Requires @0xarchive/sdk ^1.12.0.
- Package-contents allowlist check and a CI workflow.
---
 .github/workflows/ci.yml           |  56 +++
 CHANGELOG.md                       |  18 +
 README.md                          | 149 +++++-
 package.json                       |   9 +-
 scripts/check-package-contents.mjs |  35 ++
 src/cli.ts                         | 203 +++++++-
 src/commands/instruments.ts        |   3 +-
 src/commands/l2.ts                 |   4 +
 src/commands/l4.ts                 |   4 +
 src/commands/liquidations.ts       |  92 ++--
 src/commands/orders.ts             |   4 +
 src/commands/positions.ts          | 748 +++++++++++++++++++++++++++++
 src/commands/stream.ts             |  50 +-
 src/commands/trades.ts             |  29 +-
 src/lib/client.ts                  |  84 +++-
 src/lib/positions.ts               | 167 +++++++
 tests/hip4-candles.test.ts         |   4 +-
 tests/positions.test.ts            | 669 ++++++++++++++++++++++++++
 tests/release.test.ts              |  31 ++
 tests/stream.test.ts               | 109 ++++-
 20 files changed, 2359 insertions(+), 109 deletions(-)
 create mode 100644 .github/workflows/ci.yml
 create mode 100644 scripts/check-package-contents.mjs
 create mode 100644 src/commands/positions.ts
 create mode 100644 src/lib/positions.ts
 create mode 100644 tests/positions.test.ts
 create mode 100644 tests/release.test.ts

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
new file mode 100644
index 0000000..bce9986
--- /dev/null
+++ b/.github/workflows/ci.yml
@@ -0,0 +1,56 @@
+name: CI
+
+on:
+  push:
+    branches: [master]
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        node: [20, 22]
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: ${{ matrix.node }}
+
+      # The CLI depends on the @0xarchive/sdk release named in package.json. A
+      # CLI release can land in this repo before that SDK version reaches npm.
+      # In that window this step installs the newest published SDK for this run
+      # only and restores package.json afterwards. The CLI type-checks against
+      # either (it reads the newer SDK resources through its own interfaces),
+      # and the tests stub the SDK surface these commands call. Once the floor
+      # version is on npm, the first branch runs and nothing is substituted.
+      - name: Install dependencies
+        run: |
+          floor="$(node -p "require('./package.json').dependencies['@0xarchive/sdk']")"
+          if npm view "@0xarchive/sdk@${floor}" version > /dev/null 2>&1; then
+            npm install --no-audit --no-fund
+          else
+            latest="$(npm view @0xarchive/sdk version)"
+            echo "::warning::@0xarchive/sdk ${floor} is not published yet; installing ${latest} for this run only."
+            npm pkg set "dependencies.@0xarchive/sdk=${latest}"
+            npm install --no-audit --no-fund
+            git checkout -- package.json
+          fi
+          npm ls @0xarchive/sdk || true
+
+      - name: Typecheck
+        run: npm run typecheck
+
+      - name: Test
+        run: npm test
+
+      - name: Build
+        run: npm run build
+
+      - name: Package contents
+        run: npm run check:pack
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 846bc66..8ac2799 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,5 +1,23 @@
 # Changelog
 
+## 1.10.0 - 2026-09-26
+
+### Added
+
+- Lighter on Robinhood Chain, the second Lighter deployment, as `--exchange rh-lighter` on every shared market-data command that Lighter mainnet supports: instruments, order book and order book history, trades (canonical range and preliminary recent tier), candles, funding, open interest, liquidations, prices, summary, freshness, and `auth test`. It is USDG-quoted with 84 markets (57 perp, 27 spot); perps are uppercase (`BTC`) and spot markets are dashed (`AAPL-USDG`). Trades and liquidations are served from 2026-06-26 20:10:26 UTC; order book, open interest, and funding from 2026-08-22 18:43 UTC; candles from 2026-06-26 once they are enabled for this deployment. It has no L3.
+- Live Robinhood Chain streams: `oxa stream orderbook <symbol> --exchange rh-lighter` and `oxa stream trades <symbol> --exchange rh-lighter`, and `oxa stream subscribe` accepts `rh_lighter_orderbook`, `rh_lighter_trades`, `rh_lighter_open_interest`, and `rh_lighter_funding`. Messages have the same shapes as the `lighter_*` live channels, `--interval-ms` (100 to 5000) works on `rh_lighter_orderbook`, and drop notices on `rh_lighter_*` channels are warnings, as on Lighter mainnet. They are served on `wss://api.0xarchive.io/ws`, the CLI default. `rh_lighter_candles` is replay-only and is rejected before a socket opens.
+- Account positions, `oxa positions ...`, on `hyperliquid`, `hip3`, `lighter`, and `rh-lighter`: `get` (latest snapshot, or as of `--timestamp`), `history` (hourly snapshots), `changes` (the change log), `market` (every open position in one market, with `--side`, `--min-value`, and `--include-system` on Lighter), `summary` (long/short positioning now or hourly), and `all` (every open position at one hour). Hyperliquid and HIP-3 add `account` and `account-history`. Hyperliquid and HIP-3 are keyed by `--address`; Lighter by `--account <index>`. JSON output includes the response `meta` (as-of time, snapshot, source, quality, staleness, and finalization fields).
+- `oxa accounts by-l1 --l1-address 0x...` lists the Lighter mainnet account indices owned by an L1 address.
+- A package-contents check (`npm run check:pack`) and a CI workflow that runs the typecheck, tests, build, and that check.
+
+### Changed
+
+- `oxa liquidations history` and `oxa liquidations volume` accept `--exchange lighter` and `--exchange rh-lighter`; they were previously refused. Lighter rows keep the trade's raw fields (`liquidationType`, `usdAmount`, both accounts, `rawJson`), and Lighter volume buckets carry a total and a count with no long/short split. `oxa liquidations user` stays Hyperliquid only.
+- On Lighter ranges, `oxa trades fetch` passes the finalization meta through (`meta.finalizedThrough`, and `meta.clampedTo` when the range was clamped to the watermark) when the SDK returns it.
+- `oxa orders ...`, `oxa l4 ...`, and `oxa l2 ...` reject `--exchange lighter` and `--exchange rh-lighter` with a clear message before any request, instead of failing inside the command.
+- The HIP-4 funding and liquidations refusals now list every exchange that serves those routes.
+- Requires `@0xarchive/sdk` 1.12.0 or newer, the release with the Robinhood Chain client, the positions resources, and Lighter liquidations.
+
 ## 1.9.0 - 2026-09-25
 
 ### Added
diff --git a/README.md b/README.md
index 6dedb77..838b2d8 100644
--- a/README.md
+++ b/README.md
@@ -2,9 +2,9 @@
 
 Terminal-first access to 0xArchive market data.
 
-0xArchive is granular market data infrastructure for Hyperliquid and Lighter.xyz. HIP-3 builder perps, HIP-4 outcome markets, and Hyperliquid Spot live under the Hyperliquid namespace; the CLI exposes `--exchange hip3`, `--exchange hip4`, and the `oxa spot` group as convenience scopes for those markets.
+0xArchive is granular market data infrastructure for two venues: Hyperliquid and Lighter. Lighter has two deployments: mainnet and Robinhood Chain. HIP-3 builder perps, HIP-4 outcome markets, and Hyperliquid Spot live under the Hyperliquid namespace; the CLI exposes `--exchange hip3`, `--exchange hip4`, and the `oxa spot` group as convenience scopes for those markets. Lighter mainnet is `--exchange lighter` and Lighter on Robinhood Chain is `--exchange rh-lighter`.
 
-Use `oxa` when the job starts in a terminal, script, CI task, notebook setup step, Claude Code session, ChatGPT Codex session, or another coding-agent shell. Both coding agents can start here with `oxa auth test` and one market-data request before expanding into SDKs, MCP, skills, or Data Catalog exports. The command set covers order books, trades, candles, funding, open interest, liquidations, prices, freshness, Lighter L3, Hyperliquid/HIP-3 L4 routes, HIP-4 outcome markets, and Hyperliquid Spot.
+Use `oxa` when the job starts in a terminal, script, CI task, notebook setup step, Claude Code session, ChatGPT Codex session, or another coding-agent shell. Both coding agents can start here with `oxa auth test` and one market-data request before expanding into SDKs, MCP, skills, or Data Catalog exports. The command set covers order books, trades, candles, funding, open interest, liquidations, prices, freshness, account positions, Lighter L3, Hyperliquid/HIP-3 L4 routes, HIP-4 outcome markets, and Hyperliquid Spot.
 
 ## Install
 
@@ -34,6 +34,12 @@ oxa orderbook get --exchange hyperliquid --symbol BTC --format pretty
 # Fetch recent Lighter trades
 oxa trades fetch --exchange lighter --symbol BTC --limit 50
 
+# Fetch the Lighter on Robinhood Chain order book for a tokenized stock (USDG-quoted)
+oxa orderbook get --exchange rh-lighter --symbol AAPL-USDG --format pretty
+
+# Current positions of a Hyperliquid wallet
+oxa positions get --exchange hyperliquid --address 0xYourWallet --format pretty
+
 # Fetch Hyperliquid HIP-3 builder-perp candles
 oxa candles --exchange hip3 --symbol km:US500 \
   --start 2026-02-28T00:00:00Z --end 2026-03-01T00:00:00Z --interval 1h
@@ -74,7 +80,8 @@ oxa stream orderbook BTC --exchange lighter --duration-ms 10000
 | Scope | Flag | Symbols |
 | --- | --- | --- |
 | Hyperliquid | `--exchange hyperliquid` | `BTC`, `ETH`, `SOL`, etc. |
-| Lighter.xyz | `--exchange lighter` | `BTC`, `ETH`, etc. |
+| Lighter (mainnet) | `--exchange lighter` | `BTC`, `ETH`, etc. |
+| Lighter on Robinhood Chain | `--exchange rh-lighter` | USDG-quoted. Perps are uppercase (`BTC`, `ETH`); spot markets are dashed (`AAPL-USDG`). 84 markets: 57 perp, 27 spot. Trades and liquidations from 2026-06-26 20:10:26 UTC (venue launch); order book, OI, and funding from 2026-08-22 18:43 UTC; candles from 2026-06-26 once they are enabled for this deployment. No L3. |
 | Hyperliquid HIP-3 | `--exchange hip3` | `km:US500`, `xyz:XYZ100`, etc. Case-sensitive. |
 | Hyperliquid HIP-4 | `--exchange hip4` or `oxa hip4 ...` | Bare numerics: `0`, `1`, `42`. Legacy `#0` / `%230` forms still work. `mark_price` is implied probability (0..1), not USD. Per-side OI is available from 2026-05-02 at ~10s cadence; candles are available. No funding or liquidations. |
 | Hyperliquid Spot | `oxa spot ...` | Dashed canonical: `HYPE-USDC`, `PURR-USDC`. 326 pairs. Spot candles from 2025-03-22T10:50:22Z at `1m`/`5m`/`15m`/`30m`/`1h`/`4h`/`1d`/`1w`, max 1000 rows; trades from 2025-03-22; orderbook, L4, TWAP live from 2026-05-05. No funding, OI, or liquidations. |
@@ -155,7 +162,9 @@ oxa trades fetch --exchange <exchange> --symbol <symbol> [options]
 | `--out` | No | Write JSON output to file |
 | `--format` | No | `json` (default) or `pretty` |
 
-**Note:** Hyperliquid trades always require `--start` and `--end`. Lighter and HIP-3 can fetch recent trades without a range.
+**Note:** Hyperliquid trades always require `--start` and `--end`. Lighter (both deployments) and HIP-3 can fetch recent trades without a range.
+
+On both Lighter deployments, a ranged request returns canonical trades only, up to a finalization watermark that runs about a day behind: the end of the range is clamped to it, and the JSON output carries `meta.finalizedThrough` (and `meta.clampedTo` when the range was clamped) when the SDK returns them. Without a range, the command returns the recent tier, which is preliminary until the watermark passes it.
 
 ### `oxa candles`
 
@@ -177,7 +186,7 @@ oxa candles --exchange <exchange> --symbol <symbol> --start <time> --end <time>
 | `--out` | No | Write JSON output to file |
 | `--format` | No | `json` (default) or `pretty` |
 
-HIP-4 candles use `/v1/hyperliquid/hip4/candles/{coin}` with the same candle intervals. Hyperliquid Spot candles use the explicit `oxa spot candles <symbol>` command and the `/v1/hyperliquid/spot/candles/{symbol}` route.
+HIP-4 candles use `/v1/hyperliquid/hip4/candles/{coin}` with the same candle intervals. Hyperliquid Spot candles use the explicit `oxa spot candles <symbol>` command and the `/v1/hyperliquid/spot/candles/{symbol}` route. Candles for Lighter on Robinhood Chain (`--exchange rh-lighter`) cover 2026-06-26 onward once they are enabled for that deployment; until then the request returns an error.
 
 ### `oxa funding current`
 
@@ -187,7 +196,7 @@ Get the current funding rate.
 oxa funding current --exchange <exchange> --symbol <symbol> [--format <format>]
 ```
 
-Cadence guidance: core Hyperliquid funding is approximately 1 minute; Lighter and HIP-3 funding are approximately 10 seconds. HIP-4 has no funding endpoint.
+Cadence guidance: core Hyperliquid funding is approximately 1 minute; Lighter (both deployments) and HIP-3 funding are approximately 10 seconds. HIP-4 has no funding endpoint. On Lighter on Robinhood Chain, funding and open interest cover perps only.
 
 ### `oxa funding history`
 
@@ -247,7 +256,7 @@ oxa instruments --exchange <exchange> [--format <format>]
 
 ### `oxa liquidations history`
 
-Get liquidation history (Hyperliquid and HIP-3, data from May 2025 for Hyperliquid, Feb 2026 for HIP-3).
+Get liquidation history for Hyperliquid, HIP-3, and both Lighter deployments. Lighter mainnet liquidations are served from 2026-06-10 and Lighter on Robinhood Chain liquidations from 2026-06-26 20:10:26 UTC.
 
 ```bash
 oxa liquidations history --exchange <exchange> --symbol <symbol> --start <time> --end <time> [options]
@@ -255,7 +264,7 @@ oxa liquidations history --exchange <exchange> --symbol <symbol> --start <time>
 
 | Option | Required | Description |
 |--------|----------|-------------|
-| `--exchange` | Yes | `hyperliquid` or `hip3` |
+| `--exchange` | Yes | `hyperliquid`, `hip3`, `lighter`, or `rh-lighter` |
 | `--symbol` | Yes | Coin symbol |
 | `--start` | Yes | Start time (ISO 8601 or Unix ms) |
 | `--end` | Yes | End time (ISO 8601 or Unix ms) |
@@ -263,9 +272,11 @@ oxa liquidations history --exchange <exchange> --symbol <symbol> --start <time>
 | `--cursor` | No | Pagination cursor |
 | `--format` | No | `json` (default) or `pretty` |
 
+Lighter liquidation rows keep the trade's raw fields rather than a single liquidated user: `liquidationType`, `price`, `size`, `usdAmount`, the ask and bid accounts and order ids, each side's position before the trade, `txHash`, and `rawJson`, the untouched trade object. On rows backfilled from the venue's own export, `source` is `bucket` and `rawJson` is empty.
+
 ### `oxa liquidations volume`
 
-Get pre-aggregated liquidation volume in time-bucketed intervals. Returns total, long, and short USD volumes per bucket.
+Get pre-aggregated liquidation volume in time-bucketed intervals. Hyperliquid and HIP-3 buckets carry total, long, and short USD volume; Lighter buckets (both deployments) carry the total USD volume and a count, with no long/short split.
 
 ```bash
 oxa liquidations volume --exchange <exchange> --symbol <symbol> --start <time> --end <time> [options]
@@ -273,7 +284,7 @@ oxa liquidations volume --exchange <exchange> --symbol <symbol> --start <time> -
 
 | Option | Required | Description |
 |--------|----------|-------------|
-| `--exchange` | Yes | `hyperliquid` or `hip3` |
+| `--exchange` | Yes | `hyperliquid`, `hip3`, `lighter`, or `rh-lighter` |
 | `--symbol` | Yes | Coin symbol |
 | `--start` | Yes | Start time (ISO 8601 or Unix ms) |
 | `--end` | Yes | End time (ISO 8601 or Unix ms) |
@@ -338,6 +349,80 @@ Check data freshness across all data types for a symbol.
 oxa freshness --exchange <exchange> --symbol <symbol> [--format <format>]
 ```
 
+### `oxa positions ...` (account positions)
+
+Open positions, their history, and every change to them, on Hyperliquid, HIP-3, and both Lighter deployments. Hyperliquid and HIP-3 positions are keyed by wallet address (`--address 0x...`); Lighter positions are keyed by integer account index (`--account <index>`). Positions cover perpetual markets; spot and HIP-4 markets have none.
+
+```bash
+# Current positions (and account summary) of a wallet or account
+oxa positions get --exchange hyperliquid --address 0xYourWallet
+oxa positions get --exchange hip3 --address 0xYourWallet --dex xyz
+oxa positions get --exchange lighter --account 281474976710654
+oxa positions get --exchange rh-lighter --account 42
+
+# Positions as of a past time: state after every event before it
+oxa positions get --exchange hyperliquid --address 0xYourWallet --timestamp 2026-08-01T00:00:00Z
+
+# Hourly snapshots and the change log over a range
+oxa positions history --exchange lighter --account 42 --start 2026-09-01T00:00:00Z --end 2026-09-02T00:00:00Z
+oxa positions changes --exchange hyperliquid --address 0xYourWallet --start 2026-09-01T00:00:00Z --end 2026-09-02T00:00:00Z --symbol BTC
+
+# Every open position in one market, largest first, with totals on the first page
+oxa positions market --exchange hyperliquid --symbol BTC --side long --min-value 1000000
+oxa positions market --exchange lighter --symbol ETH --hour 2026-09-01T12:00:00Z
+
+# Long/short positioning summary: now, or an hourly series
+oxa positions summary --exchange hip3 --symbol xyz:TSLA
+oxa positions summary --exchange hyperliquid --symbol BTC --start 2026-09-01T00:00:00Z --end 2026-09-02T00:00:00Z
+
+# Every open position across all markets at one hour (bulk, paginated)
+oxa positions all --exchange rh-lighter --hour 2026-09-01T12:00:00Z --limit 2000 --out positions.json
+
+# Account summaries (Hyperliquid and HIP-3)
+oxa positions account --exchange hyperliquid --address 0xYourWallet
+oxa positions account-history --exchange hyperliquid --address 0xYourWallet --start 2026-09-01T00:00:00Z --end 2026-09-02T00:00:00Z
+```
+
+| Subcommand | Venues | Description |
+|---|---|---|
+| `oxa positions get` | all four | Open positions and the account summary, at the latest snapshot or as of `--timestamp`. Filters: `--symbol`, `--dex` (HIP-3). |
+| `oxa positions history` | all four | Hourly position snapshots in `[--start, --end)`. Filters: `--symbol`, `--dex` (HIP-3); `--limit`, `--cursor`. |
+| `oxa positions changes` | all four | Change log: every fill that changed a position, with the position before and after, the entry price after, realized PnL, and fees, in `[--start, --end)`. |
+| `oxa positions market` | all four | Every open position in one `--symbol`, sorted by position value, at the latest snapshot or at `--hour`. Filters: `--side long|short`, `--min-value <usd>`, `--include-system` (Lighter). |
+| `oxa positions summary` | all four | Long and short counts, sizes, values, average entries, and top-10 share for one `--symbol`: the latest snapshot, or hourly over `--start`/`--end`. |
+| `oxa positions all` | all four | Every open position across markets at one `--hour` (an exact UTC hour). |
+| `oxa positions account` | `hyperliquid`, `hip3` | Account value, margin, position value, and PnL for one wallet (`--dex` on HIP-3). |
+| `oxa positions account-history` | `hyperliquid`, `hip3` | Hourly account summaries in `[--start, --end)`. |
+
+Coverage:
+
+| Venue | Change log from | Hourly snapshots from | Live snapshot |
+|---|---|---|---|
+| Hyperliquid (`hyperliquid`) | 2025-05-25 | 2026-06-07 | every 5 minutes |
+| HIP-3 (`hip3`) | 2025-10-13 | 2026-06-07 | every 5 minutes |
+| Lighter mainnet (`lighter`) | 2025-01-17 | 2025-01-17 | every 2 minutes |
+| Lighter on Robinhood Chain (`rh-lighter`) | 2026-06-26 | 2026-06-26 | every 2 minutes |
+
+How to read the results:
+
+- The JSON output is `{ "data": ..., "nextCursor": ..., "meta": ... }`. `meta` states what the page describes: `asOf`, `snapshotTs`, `source` (`snapshot` for hourly and live snapshots, `reconstructed` for an as-of time between snapshots, `changes` for the change log), `quality`, `stale`, `builtThrough`, `finalizedThrough`, `totals` (market listings, first page only), and `notice` / `coverageFrom` when a request reaches outside coverage.
+- `--timestamp` on `oxa positions get` returns the committed snapshot when it names a snapshot hour, and otherwise a reconstruction: size, entry, and open time are exact, mark fields are taken at that time, and snapshot-only fields are null. A time later than `meta.builtThrough` is clamped to it (`meta.clampedTo`).
+- Every row carries its own `quality`, and `meta.quality` is the snapshot's. `meta.stale` is `true`, with a notice, when the latest snapshot is more than 12 minutes old.
+- `data.accountSeen` on `oxa positions get` is `flat`, `never_seen`, or `outside_coverage`. `never_seen` means no recorded activity in the covered history, not proof that the account never traded.
+- `meta.finalizedThrough` means what it means on Lighter trades: nothing before it will be re-derived. Rows after it can still change.
+- Lighter settlement, insurance, and other system accounts are left out of `oxa positions market` and `oxa positions all` unless you pass `--include-system`, and are labelled by `accountKind` everywhere.
+- Market and bulk listings are pinned to one snapshot through the cursor. If that snapshot is replaced while you page, the API answers `409` with `snapshot_advanced`; start again without `--cursor`.
+- Page sizes: wallet and account routes default to 500 rows (maximum 5,000); market listings default to 100 (maximum 2,000); summary series return at most 168 hours per page; `oxa positions all` returns at most 2,000 rows per page.
+- Billing matches trades: one credit per 1,000 rows returned, with a minimum of one credit per request. Account summaries and the Lighter L1 lookup cost one credit per request.
+
+### `oxa accounts by-l1` (Lighter mainnet)
+
+List the Lighter account indices owned by an L1 (Ethereum) address, with the total count. Use the indices with `oxa positions ... --exchange lighter --account <index>`. The lookup is available for Lighter mainnet only.
+
+```bash
+oxa accounts by-l1 --l1-address 0xYourL1Address [--limit <n>] [--cursor <cursor>] [--format <format>]
+```
+
 ### `oxa outcomes list` (HIP-4 only)
 
 List HIP-4 outcome markets (binary outcome metadata).
@@ -368,7 +453,7 @@ oxa outcomes get <outcome_id> [--format <format>]
 
 ### `oxa orders history`
 
-Get order history with user attribution.
+Get order history with user attribution. The `oxa orders`, `oxa l4`, and `oxa l2` commands cover Hyperliquid routes (`hyperliquid`, `hip3`, and `hip4` where noted); `--exchange lighter` and `--exchange rh-lighter` are rejected before any request.
 
 ```bash
 oxa orders history --exchange <exchange> --symbol <symbol> --start <time> --end <time> [options]
@@ -539,7 +624,7 @@ oxa l2 diffs --exchange <exchange> --symbol <symbol> --start <time> --end <time>
 
 ### `oxa l3 get`
 
-Get a Lighter L3 order-level orderbook snapshot (maximum 250 orders per side). Lighter only.
+Get a Lighter L3 order-level orderbook snapshot (maximum 250 orders per side). Lighter mainnet only; Lighter on Robinhood Chain has no L3.
 
 ```bash
 oxa l3 get --symbol <symbol> [options]
@@ -655,13 +740,18 @@ oxa stream orderbook BTC --exchange lighter --interval-ms 250  # at most one boo
 oxa stream trades BTC --exchange lighter
 oxa stream subscribe lighter_funding BTC
 oxa stream subscribe lighter_open_interest BTC
+
+# Lighter on Robinhood Chain (same message shapes as Lighter mainnet)
+oxa stream orderbook AAPL-USDG --exchange rh-lighter --interval-ms 500
+oxa stream trades BTC --exchange rh-lighter
+oxa stream subscribe rh_lighter_funding BTC
 ```
 
 | Option | Applies to | Description |
 |--------|------------|-------------|
-| `--exchange` | `trades`, `orderbook` | `hyperliquid` (default), `hip3`, `lighter`, or `spot` |
+| `--exchange` | `trades`, `orderbook` | `hyperliquid` (default), `hip3`, `lighter`, `rh-lighter`, or `spot` |
 | `--exchange` | `liquidations` | `hyperliquid` (default) or `hip3` |
-| `--interval-ms` | `orderbook --exchange lighter`, `subscribe lighter_orderbook` | Milliseconds between Lighter books, 100 to 5000. Default 1000. Rejected on every other channel. |
+| `--interval-ms` | `orderbook --exchange lighter` or `rh-lighter`, `subscribe lighter_orderbook` or `rh_lighter_orderbook` | Milliseconds between Lighter books, 100 to 5000. Default 1000. Rejected on every other channel. |
 | `--duration-ms` | All | Close the stream after N milliseconds and exit with code 0 |
 | `--url` | All | Override the WebSocket URL (or set `OXA_WS_URL`) |
 | `--format` | All | `json` (NDJSON, default) or `pretty` |
@@ -670,11 +760,22 @@ Each `liquidations` / `hip3_liquidations` event is delivered as a fill row with
 
 #### Lighter live channels
 
-Live subscriptions are available for four Lighter channels: `lighter_orderbook`, `lighter_trades`, `lighter_open_interest`, and `lighter_funding`. `lighter_candles` and `lighter_l3_orderbook` support historical replay only; the CLI rejects them before opening a socket and points to `oxa candles --exchange lighter` and `oxa l3 get` / `oxa l3 history`.
+Live subscriptions are available for four Lighter channels on each deployment:
+
+| Lighter mainnet | Lighter on Robinhood Chain |
+|---|---|
+| `lighter_orderbook` | `rh_lighter_orderbook` |
+| `lighter_trades` | `rh_lighter_trades` |
+| `lighter_open_interest` | `rh_lighter_open_interest` |
+| `lighter_funding` | `rh_lighter_funding` |
+
+`lighter_candles`, `lighter_l3_orderbook`, and `rh_lighter_candles` support historical replay only; the CLI rejects them before opening a socket and points to `oxa candles --exchange lighter|rh-lighter` and `oxa l3 get` / `oxa l3 history`. Robinhood Chain has no L3 channel.
 
-Lighter live data is served on `wss://api.0xarchive.io/ws`, the CLI default. It is available on every plan, and every live Lighter message is metered per message, the same as Hyperliquid live data. `stream.0xarchive.io` carries a subset of Hyperliquid live channels and no Lighter channels; a Lighter subscribe there returns an error pointing to `wss://api.0xarchive.io/ws`.
+Lighter live data, for both deployments, is served on `wss://api.0xarchive.io/ws`, the CLI default. It is available on every plan, and every live Lighter message is metered per message, the same as Hyperliquid live data. `stream.0xarchive.io` carries a subset of Hyperliquid live channels and no Lighter channels; a Lighter subscribe there returns an error pointing to `wss://api.0xarchive.io/ws`.
 
-Symbols are the same as `oxa instruments --exchange lighter`. They are case-insensitive on subscribe and echoed uppercase. Messages use the same envelope as Hyperliquid live data. Example messages (the book is cut to one level per side here; the trade is one trade, two fills):
+The `rh_lighter_*` channels send exactly the same message shapes as the matching `lighter_*` channels below, with Robinhood Chain symbols and USDG-quoted prices. Everything in this section applies to both deployments, including `--interval-ms` on the book channel and drop notices.
+
+Symbols are the same as `oxa instruments --exchange lighter` (or `--exchange rh-lighter`). They are case-insensitive on subscribe and echoed uppercase. Messages use the same envelope as Hyperliquid live data. Example messages (the book is cut to one level per side here; the trade is one trade, two fills):
 
 ```json
 {"type":"data","channel":"lighter_orderbook","coin":"BTC","symbol":"BTC","data":{"coin":"BTC","time":1790294171459,"levels":[[{"px":"84368.7","sz":"0.00020","n":1}],[{"px":"84368.8","sz":"0.05720","n":1}]]}}
@@ -688,7 +789,7 @@ Symbols are the same as `oxa instruments --exchange lighter`. They are case-inse
 
 If your connection falls behind `lighter_trades` or the stats channels, the server sends an error notice (for example `Dropped ~N live lighter_trades messages for BTC: your connection fell behind the Lighter stream, and those trades were not delivered.`) and keeps the subscription running. The CLI writes that notice to stderr as a warning line (`{"warning":"stream warning: Dropped ~N ...","type":"lag"}`) and keeps streaming; missed trades are not resent. If the lag persists, the server stops the subscription (`Stopped the lighter_trades stream for BTC: your connection is too slow to keep up. Re-subscribe to resume.`) and the CLI exits with code 4, like any other server error.
 
-WebSocket replay of all six Lighter channels is unchanged and keeps its existing `historical_data` row shapes, which differ from the live shapes above. The CLI does not start replays; use an SDK or the WebSocket API directly for replay.
+WebSocket replay of all six Lighter mainnet channels, and of the five Robinhood Chain channels, keeps the existing `historical_data` row shapes, which differ from the live shapes above. The CLI does not start replays; use an SDK or the WebSocket API directly for replay.
 
 ### `oxa l3 history`
 
@@ -802,6 +903,18 @@ oxa stream liquidations BTC --duration-ms 60000
 oxa stream trades BTC --exchange lighter --duration-ms 60000 \
   | jq -s '[.[].data[].tid] | unique | length'
 
+# Lighter on Robinhood Chain: tokenized-stock book and funding
+oxa orderbook get --exchange rh-lighter --symbol AAPL-USDG
+oxa funding current --exchange rh-lighter --symbol BTC
+
+# Positions: a wallet's open positions, and the largest BTC longs right now
+oxa positions get --exchange hyperliquid --address 0xYourWallet | jq '.data.positions[] | {symbol, size, unrealizedPnl}'
+oxa positions market --exchange hyperliquid --symbol BTC --side long --limit 10
+
+# Lighter: find a wallet's account indices, then read one account's positions
+oxa accounts by-l1 --l1-address 0xYourL1Address | jq '.data.accounts[].accountIndex'
+oxa positions get --exchange lighter --account 42
+
 # HIP-4 outcome markets (bare numeric coins)
 oxa hip4 outcomes list --settled false
 oxa hip4 orderbook get 0 --depth 10
diff --git a/package.json b/package.json
index f3d9ac4..c5ab6d3 100644
--- a/package.json
+++ b/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@0xarchive/cli",
-  "version": "1.9.0",
-  "description": "Terminal-first 0xArchive client for Hyperliquid and Lighter market data, including Hyperliquid HIP-3, HIP-4, and Spot",
+  "version": "1.10.0",
+  "description": "Terminal-first 0xArchive client for Hyperliquid and Lighter market data and account positions, including Hyperliquid HIP-3, HIP-4, Spot, and Lighter on Robinhood Chain",
   "type": "module",
   "bin": {
     "oxa": "./dist/cli.js"
@@ -16,6 +16,7 @@
     "typecheck": "tsc --noEmit",
     "test": "vitest run",
     "test:watch": "vitest",
+    "check:pack": "node scripts/check-package-contents.mjs",
     "prepublishOnly": "npm run build"
   },
   "keywords": [
@@ -24,6 +25,8 @@
     "market-data",
     "hyperliquid",
     "lighterxyz",
+    "robinhood-chain",
+    "positions",
     "orderbook",
     "trades",
     "replay",
@@ -45,7 +48,7 @@
     "node": ">=18"
   },
   "dependencies": {
-    "@0xarchive/sdk": "^1.7.0",
+    "@0xarchive/sdk": "^1.12.0",
     "commander": "^13.0.0",
     "chalk": "^5.4.0"
   },
diff --git a/scripts/check-package-contents.mjs b/scripts/check-package-contents.mjs
new file mode 100644
index 0000000..d18d2be
--- /dev/null
+++ b/scripts/check-package-contents.mjs
@@ -0,0 +1,35 @@
+// Fails when the npm tarball would ship anything other than the allowlisted
+// files, or would miss one of them. Run after `npm run build`.
+//
+// The allowlist is deliberate: the package ships the bundled CLI, its source
+// map, the README, and the license. Adding a path here widens what every
+// install downloads, so it should be a reviewed change of its own.
+import { execFileSync } from 'node:child_process';
+import { readFileSync } from 'node:fs';
+
+const EXPECTED = ['LICENSE', 'README.md', 'dist/cli.js', 'dist/cli.js.map', 'package.json'];
+
+const npm = process.platform === 'win32' ? 'npm.cmd' : 'npm';
+const raw = execFileSync(npm, ['pack', '--dry-run', '--json', '--ignore-scripts'], { encoding: 'utf8' });
+const [pack] = JSON.parse(raw);
+const files = pack.files.map((f) => f.path).sort();
+
+const unexpected = files.filter((f) => !EXPECTED.includes(f));
+const missing = EXPECTED.filter((f) => !files.includes(f));
+const problems = [];
+if (unexpected.length) problems.push(`not on the allowlist: ${unexpected.join(', ')}`);
+if (missing.length) problems.push(`missing (run npm run build first?): ${missing.join(', ')}`);
+
+const version = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version;
+if (pack.version !== version) problems.push(`tarball version ${pack.version} != package.json ${version}`);
+
+const bundle = readFileSync(new URL('../dist/cli.js', import.meta.url), 'utf8');
+if (!bundle.includes(`VERSION = "${version}"`) && !bundle.includes(`VERSION = '${version}'`)) {
+  problems.push(`dist/cli.js does not report version ${version} (stale build?)`);
+}
+
+if (problems.length) {
+  console.error(`package contents check failed:\n  - ${problems.join('\n  - ')}`);
+  process.exit(1);
+}
+console.log(`package contents OK: ${files.join(', ')} (${pack.name}@${pack.version})`);
diff --git a/src/cli.ts b/src/cli.ts
index 604696a..e3497ad 100644
--- a/src/cli.ts
+++ b/src/cli.ts
@@ -53,14 +53,29 @@ import {
   spotTwapByUser,
   spotFreshness,
 } from './commands/spot.js';
+import {
+  positionsGetCommand,
+  positionsHistoryCommand,
+  positionsChangesCommand,
+  positionsMarketCommand,
+  positionsSummaryCommand,
+  positionsAllCommand,
+  accountGetCommand,
+  accountHistoryCommand,
+  accountsByL1Command,
+} from './commands/positions.js';
 import { exitError, EXIT } from './lib/output.js';
 
-const VERSION = '1.9.0';
+const VERSION = '1.10.0';
 
 const EXCHANGE_DESC =
-  'Exchange: hyperliquid, lighter, hip3, or hip4. ' +
+  'Exchange: hyperliquid, hip3, hip4, lighter, or rh-lighter. ' +
+  'lighter is Lighter mainnet and rh-lighter is Lighter on Robinhood Chain (USDG-quoted; spot symbols are dashed, e.g. AAPL-USDG). ' +
   'For hip4, coins are bare numerics (e.g. "0", "1", "42"); legacy "#0" / "%230" forms are also accepted. mark_price is an implied probability (0..1), not a USD price.';
 
+const POSITIONS_EXCHANGE_DESC =
+  'Exchange: hyperliquid, hip3, lighter (Lighter mainnet), or rh-lighter (Lighter on Robinhood Chain)';
+
 const program = new Command()
   .name('oxa')
   .description('0xArchive CLI — Query historical crypto market data')
@@ -230,7 +245,7 @@ program
 
 const liquidations = program
   .command('liquidations')
-  .description('Liquidation data (Hyperliquid and HIP-3)');
+  .description('Liquidation data (Hyperliquid, HIP-3, and both Lighter deployments)');
 
 liquidations
   .command('history')
@@ -247,7 +262,9 @@ liquidations
 
 liquidations
   .command('volume')
-  .description('Get pre-aggregated liquidation volume in time buckets')
+  .description(
+    'Get pre-aggregated liquidation volume in time buckets (Lighter buckets carry a total and a count, no long/short split)',
+  )
   .requiredOption('--exchange <exchange>', EXCHANGE_DESC)
   .requiredOption('--symbol <symbol>', 'Coin symbol (e.g. BTC, ETH, km:US500)')
   .requiredOption('--start <time>', 'Start time (ISO 8601 or Unix ms)')
@@ -461,7 +478,7 @@ l2
 
 const l3 = program
   .command('l3')
-  .description('Lighter L3 order-level orderbook commands — max 250 orders per side');
+  .description('Lighter mainnet L3 order-level orderbook commands, max 250 orders per side (Lighter on Robinhood Chain has no L3)');
 
 l3
   .command('get')
@@ -758,7 +775,7 @@ stream
   .description(
     'Stream realtime trades for a symbol. Lighter trades arrive as two fills per trade (one per side, same tid).',
   )
-  .option('--exchange <exchange>', 'hyperliquid (default), hip3, lighter, or spot')
+  .option('--exchange <exchange>', 'hyperliquid (default), hip3, lighter, rh-lighter, or spot')
   .option('--duration-ms <ms>', 'Auto-close after N milliseconds')
   .option('--url <url>', 'Override WebSocket URL (or set OXA_WS_URL env var)')
   .option('--api-key <key>', 'API key (or set OXA_API_KEY env var)')
@@ -768,12 +785,12 @@ stream
 stream
   .command('orderbook <symbol>')
   .description(
-    'Stream realtime L2 orderbook updates for a symbol. Lighter sends a full top-20 book, at most one per second by default.',
+    'Stream realtime L2 orderbook updates for a symbol. Lighter (both deployments) sends a full top-20 book, at most one per second by default.',
   )
-  .option('--exchange <exchange>', 'hyperliquid (default), hip3, lighter, or spot')
+  .option('--exchange <exchange>', 'hyperliquid (default), hip3, lighter, rh-lighter, or spot')
   .option(
     '--interval-ms <ms>',
-    'Lighter only: milliseconds between books, 100 to 5000 (default 1000). Each book is the newest full state.',
+    'Lighter and rh-lighter only: milliseconds between books, 100 to 5000 (default 1000). Each book is the newest full state.',
   )
   .option('--duration-ms <ms>', 'Auto-close after N milliseconds')
   .option('--url <url>', 'Override WebSocket URL (or set OXA_WS_URL env var)')
@@ -782,23 +799,25 @@ stream
   .action(streamOrderbookCommand);
 
 // Generic channel subscription. Use this for spot (spot_orderbook,
-// spot_trades, spot_l4_diffs, spot_l4_orders, spot_twap), Lighter
-// (lighter_orderbook, lighter_trades, lighter_open_interest, lighter_funding)
-// and any other raw WebSocket channel name not covered by the dedicated verbs
-// above. lighter_candles and lighter_l3_orderbook are replay-only and are
-// rejected before a socket is opened.
+// spot_trades, spot_l4_diffs, spot_l4_orders, spot_twap), Lighter mainnet
+// (lighter_orderbook, lighter_trades, lighter_open_interest, lighter_funding),
+// Lighter on Robinhood Chain (the same four with an rh_ prefix) and any other
+// raw WebSocket channel name not covered by the dedicated verbs above.
+// lighter_candles, lighter_l3_orderbook and rh_lighter_candles are
+// replay-only and are rejected before a socket is opened.
 stream
   .command('subscribe <channel> <symbol>')
   .description(
     'Subscribe to a raw WebSocket channel by name. ' +
       'For spot: spot_orderbook, spot_trades, spot_l4_diffs, spot_l4_orders, spot_twap. ' +
       'Symbols are dashed canonical for spot (HYPE-USDC, PURR-USDC). ' +
-      'For Lighter: lighter_orderbook, lighter_trades, lighter_open_interest, lighter_funding ' +
-      '(lighter_candles and lighter_l3_orderbook are replay-only).',
+      'For Lighter: lighter_orderbook, lighter_trades, lighter_open_interest, lighter_funding; ' +
+      'for Lighter on Robinhood Chain: rh_lighter_orderbook, rh_lighter_trades, rh_lighter_open_interest, rh_lighter_funding ' +
+      '(lighter_candles, lighter_l3_orderbook, and rh_lighter_candles are replay-only).',
   )
   .option(
     '--interval-ms <ms>',
-    'lighter_orderbook only: milliseconds between books, 100 to 5000 (default 1000)',
+    'lighter_orderbook and rh_lighter_orderbook only: milliseconds between books, 100 to 5000 (default 1000)',
   )
   .option('--duration-ms <ms>', 'Auto-close after N milliseconds')
   .option('--url <url>', 'Override WebSocket URL (or set OXA_WS_URL env var)')
@@ -922,4 +941,154 @@ spot
   .option('--format <format>', 'Output format: json or pretty', 'json')
   .action(spotFreshness);
 
+// ── oxa positions ... ───────────────────────────────────────────────────
+// Account positions on Hyperliquid, HIP-3, and both Lighter deployments.
+// Hyperliquid and HIP-3 are keyed by wallet address (--address), Lighter by
+// integer account index (--account).
+
+const positions = program
+  .command('positions')
+  .description(
+    'Account positions: current or as of a time, hourly history, change log, per-market listings and summaries ' +
+      '(hyperliquid, hip3, lighter, rh-lighter)',
+  );
+
+positions
+  .command('get')
+  .description('Get the open positions of a wallet (Hyperliquid, HIP-3) or account (Lighter), now or as of --timestamp')
+  .requiredOption('--exchange <exchange>', POSITIONS_EXCHANGE_DESC)
+  .option('--address <address>', 'Wallet address, 0x... (hyperliquid, hip3)')
+  .option('--account <index>', 'Lighter account index (lighter, rh-lighter)')
+  .option('--timestamp <time>', 'As-of time (ISO 8601 or Unix ms): state after every event before it. Omit for the latest snapshot.')
+  .option('--symbol <symbol>', 'Only this market')
+  .option('--dex <dex>', 'HIP-3 only: restrict to one dex')
+  .option('--limit <n>', 'Maximum records to return')
+  .option('--cursor <cursor>', 'Pagination cursor from previous response')
+  .option('--out <path>', 'Write JSON output to file')
+  .option('--api-key <key>', 'API key (or set OXA_API_KEY env var)')
+  .option('--format <format>', 'Output format: json or pretty', 'json')
+  .action(positionsGetCommand);
+
+positions
+  .command('history')
+  .description('Get hourly position snapshots for a wallet or account over a time range')
+  .requiredOption('--exchange <exchange>', POSITIONS_EXCHANGE_DESC)
+  .option('--address <address>', 'Wallet address, 0x... (hyperliquid, hip3)')
+  .option('--account <index>', 'Lighter account index (lighter, rh-lighter)')
+  .requiredOption('--start <time>', 'Start time (ISO 8601 or Unix ms), inclusive')
+  .requiredOption('--end <time>', 'End time (ISO 8601 or Unix ms), exclusive')
+  .option('--symbol <symbol>', 'Only this market')
+  .option('--dex <dex>', 'HIP-3 only: restrict to one dex')
+  .option('--limit <n>', 'Maximum records to return')
+  .option('--cursor <cursor>', 'Pagination cursor from previous response')
+  .option('--out <path>', 'Write JSON output to file')
+  .option('--api-key <key>', 'API key (or set OXA_API_KEY env var)')
+  .option('--format <format>', 'Output format: json or pretty', 'json')
+  .action(positionsHistoryCommand);
+
+positions
+  .command('changes')
+  .description('Get the position change log (every fill that changed a position) for a wallet or account')
+  .requiredOption('--exchange <exchange>', POSITIONS_EXCHANGE_DESC)
+  .option('--address <address>', 'Wallet address, 0x... (hyperliquid, hip3)')
+  .option('--account <index>', 'Lighter account index (lighter, rh-lighter)')
+  .requiredOption('--start <time>', 'Start time (ISO 8601 or Unix ms), inclusive')
+  .requiredOption('--end <time>', 'End time (ISO 8601 or Unix ms), exclusive')
+  .option('--symbol <symbol>', 'Only this market')
+  .option('--dex <dex>', 'HIP-3 only: restrict to one dex')
+  .option('--limit <n>', 'Maximum records to return')
+  .option('--cursor <cursor>', 'Pagination cursor from previous response')
+  .option('--out <path>', 'Write JSON output to file')
+  .option('--api-key <key>', 'API key (or set OXA_API_KEY env var)')
+  .option('--format <format>', 'Output format: json or pretty', 'json')
+  .action(positionsChangesCommand);
+
+positions
+  .command('market')
+  .description('List every open position in one market, largest position value first, now or at --hour')
+  .requiredOption('--exchange <exchange>', POSITIONS_EXCHANGE_DESC)
+  .requiredOption('--symbol <symbol>', 'Market symbol (e.g. BTC, xyz:TSLA)')
+  .option('--hour <time>', 'An exact UTC hour (ISO 8601 or Unix ms) for a committed hourly snapshot. Omit for the latest.')
+  .option('--side <side>', 'long or short')
+  .option('--min-value <usd>', 'Minimum position value in USD')
+  .option('--include-system', 'Lighter only: include settlement, insurance, and other system accounts')
+  .option('--limit <n>', 'Maximum records to return')
+  .option('--cursor <cursor>', 'Pagination cursor from previous response')
+  .option('--out <path>', 'Write JSON output to file')
+  .option('--api-key <key>', 'API key (or set OXA_API_KEY env var)')
+  .option('--format <format>', 'Output format: json or pretty', 'json')
+  .action(positionsMarketCommand);
+
+positions
+  .command('summary')
+  .description('Long/short counts, sizes, values, average entries, and top-10 share for one market, now or hourly over a range')
+  .requiredOption('--exchange <exchange>', POSITIONS_EXCHANGE_DESC)
+  .requiredOption('--symbol <symbol>', 'Market symbol (e.g. BTC, xyz:TSLA)')
+  .option('--start <time>', 'Start of an hourly series (ISO 8601 or Unix ms); pass with --end')
+  .option('--end <time>', 'End of an hourly series (ISO 8601 or Unix ms); pass with --start')
+  .option('--include-system', 'Lighter only: include settlement, insurance, and other system accounts')
+  .option('--limit <n>', 'Maximum hourly points to return')
+  .option('--cursor <cursor>', 'Pagination cursor from previous response')
+  .option('--out <path>', 'Write JSON output to file')
+  .option('--api-key <key>', 'API key (or set OXA_API_KEY env var)')
+  .option('--format <format>', 'Output format: json or pretty', 'json')
+  .action(positionsSummaryCommand);
+
+positions
+  .command('all')
+  .description('Every open position across all markets at one hourly snapshot (bulk, paginated)')
+  .requiredOption('--exchange <exchange>', POSITIONS_EXCHANGE_DESC)
+  .requiredOption('--hour <time>', 'An exact UTC hour (ISO 8601 or Unix ms)')
+  .option('--include-system', 'Lighter only: include settlement, insurance, and other system accounts')
+  .option('--limit <n>', 'Maximum records to return')
+  .option('--cursor <cursor>', 'Pagination cursor from previous response')
+  .option('--out <path>', 'Write JSON output to file')
+  .option('--api-key <key>', 'API key (or set OXA_API_KEY env var)')
+  .option('--format <format>', 'Output format: json or pretty', 'json')
+  .action(positionsAllCommand);
+
+positions
+  .command('account')
+  .description('Get the account summary of a wallet: account value, margin, position value, PnL (hyperliquid, hip3)')
+  .requiredOption('--exchange <exchange>', 'Exchange: hyperliquid or hip3')
+  .requiredOption('--address <address>', 'Wallet address, 0x...')
+  .option('--dex <dex>', 'HIP-3 only: restrict to one dex')
+  .option('--out <path>', 'Write JSON output to file')
+  .option('--api-key <key>', 'API key (or set OXA_API_KEY env var)')
+  .option('--format <format>', 'Output format: json or pretty', 'json')
+  .action(accountGetCommand);
+
+positions
+  .command('account-history')
+  .description('Get hourly account summaries of a wallet over a time range (hyperliquid, hip3)')
+  .requiredOption('--exchange <exchange>', 'Exchange: hyperliquid or hip3')
+  .requiredOption('--address <address>', 'Wallet address, 0x...')
+  .requiredOption('--start <time>', 'Start time (ISO 8601 or Unix ms), inclusive')
+  .requiredOption('--end <time>', 'End time (ISO 8601 or Unix ms), exclusive')
+  .option('--dex <dex>', 'HIP-3 only: restrict to one dex')
+  .option('--limit <n>', 'Maximum records to return')
+  .option('--cursor <cursor>', 'Pagination cursor from previous response')
+  .option('--out <path>', 'Write JSON output to file')
+  .option('--api-key <key>', 'API key (or set OXA_API_KEY env var)')
+  .option('--format <format>', 'Output format: json or pretty', 'json')
+  .action(accountHistoryCommand);
+
+// ── oxa accounts by-l1 (Lighter mainnet) ────────────────────────────────
+
+const accounts = program
+  .command('accounts')
+  .description('Lighter account lookup');
+
+accounts
+  .command('by-l1')
+  .description('List the Lighter account indices owned by an L1 (Ethereum) address (Lighter mainnet)')
+  .requiredOption('--l1-address <address>', 'L1 address, 0x...')
+  .option('--exchange <exchange>', 'lighter (Lighter mainnet; the only deployment with this lookup)', 'lighter')
+  .option('--limit <n>', 'Maximum records to return')
+  .option('--cursor <cursor>', 'Pagination cursor from previous response')
+  .option('--out <path>', 'Write JSON output to file')
+  .option('--api-key <key>', 'API key (or set OXA_API_KEY env var)')
+  .option('--format <format>', 'Output format: json or pretty', 'json')
+  .action(accountsByL1Command);
+
 program.parse();
diff --git a/src/commands/instruments.ts b/src/commands/instruments.ts
index 9f9710f..f265e50 100644
--- a/src/commands/instruments.ts
+++ b/src/commands/instruments.ts
@@ -3,6 +3,7 @@ import {
   validateExchange,
   createClient,
   getExchangeClient,
+  isLighterExchange,
 } from '../lib/client.js';
 import {
   outputJson,
@@ -35,7 +36,7 @@ export async function instrumentsCommand(options: InstrumentsOptions): Promise<v
 
       if (instruments.length === 0) {
         prettyDim('No instruments found.');
-      } else if (exchange === 'lighter') {
+      } else if (isLighterExchange(exchange)) {
         const rows = instruments.map((i: any) => [
           i.symbol ?? i.name ?? '—',
           i.marketType ?? '—',
diff --git a/src/commands/l2.ts b/src/commands/l2.ts
index 53d57c0..3654c1c 100644
--- a/src/commands/l2.ts
+++ b/src/commands/l2.ts
@@ -1,6 +1,7 @@
 import {
   resolveApiKey,
   validateExchange,
+  requireExchange,
   createClient,
   getExchangeClient,
 } from '../lib/client.js';
@@ -37,6 +38,7 @@ export async function l2GetCommand(options: L2GetOptions): Promise<void> {
       EXIT.VALIDATION,
     );
   }
+  requireExchange(exchange, ['hyperliquid', 'hip3'], 'derived L2 order book');
   const apiKey = resolveApiKey(options.apiKey);
   const depth = parsePositiveInt(options.depth, 'depth');
 
@@ -92,6 +94,7 @@ export async function l2HistoryCommand(options: L2HistoryOptions): Promise<void>
       EXIT.VALIDATION,
     );
   }
+  requireExchange(exchange, ['hyperliquid', 'hip3'], 'derived L2 history');
   const apiKey = resolveApiKey(options.apiKey);
   const start = parseTimestamp(options.start, 'start');
   const end = parseTimestamp(options.end, 'end');
@@ -176,6 +179,7 @@ export async function l2DiffsCommand(options: L2DiffsOptions): Promise<void> {
       EXIT.VALIDATION,
     );
   }
+  requireExchange(exchange, ['hyperliquid', 'hip3'], 'L2 diffs');
   const apiKey = resolveApiKey(options.apiKey);
   const start = parseTimestamp(options.start, 'start');
   const end = parseTimestamp(options.end, 'end');
diff --git a/src/commands/l4.ts b/src/commands/l4.ts
index 592be90..e0f7c18 100644
--- a/src/commands/l4.ts
+++ b/src/commands/l4.ts
@@ -1,6 +1,7 @@
 import {
   resolveApiKey,
   validateExchange,
+  requireExchange,
   createClient,
   getExchangeClient,
 } from '../lib/client.js';
@@ -31,6 +32,7 @@ interface L4GetOptions {
 export async function l4GetCommand(options: L4GetOptions): Promise<void> {
   const format = validateFormat(options.format);
   const exchange = validateExchange(options.exchange);
+  requireExchange(exchange, ['hyperliquid', 'hip3', 'hip4'], 'L4 order book');
   const apiKey = resolveApiKey(options.apiKey);
   const depth = parsePositiveInt(options.depth, 'depth');
 
@@ -77,6 +79,7 @@ interface L4DiffsOptions {
 export async function l4DiffsCommand(options: L4DiffsOptions): Promise<void> {
   const format = validateFormat(options.format);
   const exchange = validateExchange(options.exchange);
+  requireExchange(exchange, ['hyperliquid', 'hip3', 'hip4'], 'L4 diffs');
   const apiKey = resolveApiKey(options.apiKey);
   const start = parseTimestamp(options.start, 'start');
   const end = parseTimestamp(options.end, 'end');
@@ -153,6 +156,7 @@ interface L4HistoryOptions {
 export async function l4HistoryCommand(options: L4HistoryOptions): Promise<void> {
   const format = validateFormat(options.format);
   const exchange = validateExchange(options.exchange);
+  requireExchange(exchange, ['hyperliquid', 'hip3', 'hip4'], 'L4 history');
   const apiKey = resolveApiKey(options.apiKey);
   const start = parseTimestamp(options.start, 'start');
   const end = parseTimestamp(options.end, 'end');
diff --git a/src/commands/liquidations.ts b/src/commands/liquidations.ts
index ffd7c09..cc68610 100644
--- a/src/commands/liquidations.ts
+++ b/src/commands/liquidations.ts
@@ -3,6 +3,9 @@ import {
   validateExchange,
   createClient,
   getExchangeClient,
+  isLighterExchange,
+  sdkTooOld,
+  type Exchange,
 } from '../lib/client.js';
 import {
   outputJson,
@@ -55,22 +58,36 @@ interface LiquidationsUserOptions {
   format: string;
 }
 
-const LIQUIDATION_EXCHANGES = ['hyperliquid', 'hip3'];
+// Liquidation history and volume: Hyperliquid, HIP-3, and both Lighter
+// deployments. Lookup by user is Hyperliquid only.
+export const LIQUIDATION_EXCHANGES = ['hyperliquid', 'hip3', 'lighter', 'rh-lighter'] as const;
 
-function validateLiquidationExchange(exchange: string): string {
+export function validateLiquidationExchange(exchange: Exchange): void {
   if (exchange === 'hip4') {
     exitError(
-      'HIP-4 has no liquidations endpoint. Use --exchange hyperliquid or hip3.',
+      'HIP-4 has no liquidations endpoint. Use --exchange hyperliquid, hip3, lighter, or rh-lighter.',
       EXIT.VALIDATION,
     );
   }
-  if (!LIQUIDATION_EXCHANGES.includes(exchange)) {
+  if (!(LIQUIDATION_EXCHANGES as readonly string[]).includes(exchange)) {
     exitError(
-      `Liquidations are only available for hyperliquid and hip3. Got "${exchange}".`,
+      `Liquidations are available for ${LIQUIDATION_EXCHANGES.join(', ')}. Got "${exchange}".`,
       EXIT.VALIDATION,
     );
   }
-  return exchange;
+}
+
+// The liquidations resource on the chosen exchange client. Both Lighter
+// clients gained it in the SDK floor release.
+function liquidationsResource(client: ReturnType<typeof createClient>, exchange: Exchange): any {
+  const resource = (getExchangeClient(client, exchange) as any).liquidations;
+  if (!resource) sdkTooOld(`Lighter liquidations (--exchange ${exchange})`);
+  return resource;
+}
+
+function isoTime(value: unknown): string {
+  if (typeof value === 'number' && Number.isFinite(value)) return new Date(value).toISOString();
+  return value === undefined || value === null ? '-' : String(value);
 }
 
 export async function liquidationsCommand(options: LiquidationsOptions): Promise<void> {
@@ -99,9 +116,7 @@ export async function liquidationsCommand(options: LiquidationsOptions): Promise
   const client = createClient(apiKey);
 
   try {
-    const exchangeClient = getExchangeClient(client, exchange);
-    const hlClient = exchangeClient as any;
-    const result = await hlClient.liquidations.history(options.symbol, {
+    const result = await liquidationsResource(client, exchange).history(options.symbol, {
       start,
       end,
       limit,
@@ -117,14 +132,27 @@ export async function liquidationsCommand(options: LiquidationsOptions): Promise
         prettyDim('No liquidations found.');
       } else {
         const preview = liqs.slice(0, 20);
-        const rows = preview.map((l: any) => [
-          l.timestamp,
-          l.side === 'B' ? 'LONG' : 'SHORT',
-          l.price,
-          l.size,
-          l.liquidatedUser?.slice(0, 10) + '...' || '—',
-        ]);
-        prettyTable(['Timestamp', 'Side', 'Price', 'Size', 'User'], rows);
+        if (isLighterExchange(exchange)) {
+          // Lighter rows carry the liquidation type and USD amount; the
+          // liquidated side is not flagged on the trade.
+          const rows = preview.map((l: any) => [
+            isoTime(l.timestamp),
+            String(l.liquidationType ?? l.liquidation_type ?? '-'),
+            String(l.price ?? '-'),
+            String(l.size ?? '-'),
+            String(l.usdAmount ?? l.usd_amount ?? '-'),
+          ]);
+          prettyTable(['Timestamp', 'Type', 'Price', 'Size', 'USD'], rows);
+        } else {
+          const rows = preview.map((l: any) => [
+            l.timestamp,
+            l.side === 'B' ? 'LONG' : 'SHORT',
+            l.price,
+            l.size,
+            l.liquidatedUser ? l.liquidatedUser.slice(0, 10) + '...' : '-',
+          ]);
+          prettyTable(['Timestamp', 'Side', 'Price', 'Size', 'User'], rows);
+        }
 
         if (liqs.length > 20) {
           prettyDim(`... and ${liqs.length - 20} more`);
@@ -160,9 +188,7 @@ export async function liquidationsVolumeCommand(options: LiquidationsVolumeOptio
   const client = createClient(apiKey);
 
   try {
-    const exchangeClient = getExchangeClient(client, exchange);
-    const hlClient = exchangeClient as any;
-    const result = await hlClient.liquidations.volume(options.symbol, {
+    const result = await liquidationsResource(client, exchange).volume(options.symbol, {
       start,
       end,
       interval: options.interval,
@@ -183,13 +209,23 @@ export async function liquidationsVolumeCommand(options: LiquidationsVolumeOptio
         prettyDim('No volume data found.');
       } else {
         const preview = buckets.slice(0, 20);
-        const rows = preview.map((b: any) => [
-          b.timestamp,
-          `$${b.totalUsd}`,
-          `$${b.longUsd}`,
-          `$${b.shortUsd}`,
-        ]);
-        prettyTable(['Timestamp', 'Total USD', 'Long USD', 'Short USD'], rows);
+        if (isLighterExchange(exchange)) {
+          // Lighter buckets carry the total and a count, with no long/short split.
+          const rows = preview.map((b: any) => [
+            isoTime(b.timestamp),
+            `$${b.totalUsd ?? b.total_usd}`,
+            String(b.count ?? '-'),
+          ]);
+          prettyTable(['Timestamp', 'Total USD', 'Count'], rows);
+        } else {
+          const rows = preview.map((b: any) => [
+            b.timestamp,
+            `$${b.totalUsd}`,
+            `$${b.longUsd}`,
+            `$${b.shortUsd}`,
+          ]);
+          prettyTable(['Timestamp', 'Total USD', 'Long USD', 'Short USD'], rows);
+        }
 
         if (buckets.length > 20) {
           prettyDim(`... and ${buckets.length - 20} more`);
@@ -224,7 +260,7 @@ export async function liquidationsUserCommand(options: LiquidationsUserOptions):
 
   if (exchange !== 'hyperliquid') {
     exitError(
-      'Liquidations by user is currently only available for hyperliquid.',
+      'Liquidations by user is only available for --exchange hyperliquid.',
       EXIT.VALIDATION,
     );
   }
diff --git a/src/commands/orders.ts b/src/commands/orders.ts
index 9f6429d..cff7f8d 100644
--- a/src/commands/orders.ts
+++ b/src/commands/orders.ts
@@ -1,6 +1,7 @@
 import {
   resolveApiKey,
   validateExchange,
+  requireExchange,
   createClient,
   getExchangeClient,
   type Exchange,
@@ -39,6 +40,7 @@ interface OrdersHistoryOptions {
 export async function ordersHistoryCommand(options: OrdersHistoryOptions): Promise<void> {
   const format = validateFormat(options.format);
   const exchange = validateExchange(options.exchange);
+  requireExchange(exchange, ['hyperliquid', 'hip3', 'hip4'], 'order history');
   const apiKey = resolveApiKey(options.apiKey);
   const start = parseTimestamp(options.start, 'start');
   const end = parseTimestamp(options.end, 'end');
@@ -128,6 +130,7 @@ interface OrdersFlowOptions {
 export async function ordersFlowCommand(options: OrdersFlowOptions): Promise<void> {
   const format = validateFormat(options.format);
   const exchange = validateExchange(options.exchange);
+  requireExchange(exchange, ['hyperliquid', 'hip3', 'hip4'], 'order flow');
   const apiKey = resolveApiKey(options.apiKey);
   const start = parseTimestamp(options.start, 'start');
   const end = parseTimestamp(options.end, 'end');
@@ -202,6 +205,7 @@ interface OrdersTpslOptions {
 export async function ordersTpslCommand(options: OrdersTpslOptions): Promise<void> {
   const format = validateFormat(options.format);
   const exchange = validateExchange(options.exchange);
+  requireExchange(exchange, ['hyperliquid', 'hip3', 'hip4'], 'TP/SL order');
   const apiKey = resolveApiKey(options.apiKey);
   const start = parseTimestamp(options.start, 'start');
   const end = parseTimestamp(options.end, 'end');
diff --git a/src/commands/positions.ts b/src/commands/positions.ts
new file mode 100644
index 0000000..a086930
--- /dev/null
+++ b/src/commands/positions.ts
@@ -0,0 +1,748 @@
+// `oxa positions ...` and `oxa accounts by-l1`: account positions on
+// Hyperliquid, HIP-3, and both Lighter deployments (mainnet and Robinhood
+// Chain), through the SDK positions resources.
+//
+// Hyperliquid and HIP-3 are keyed by wallet address (--address 0x...); Lighter
+// by integer account index (--account <index>). Every command prints the SDK
+// page as a JSON envelope `{ data, nextCursor, meta }`; `meta` carries the
+// snapshot and quality fields (as_of, snapshot_ts, source, quality, stale,
+// built_through, finalized_through, totals, notices) whenever the API sends them.
+
+import {
+  resolveApiKey,
+  validateExchange,
+  requireExchange,
+  createClient,
+  exchangeLabel,
+  isLighterExchange,
+  listOr,
+  sdkTooOld,
+} from '../lib/client.js';
+import {
+  outputJson,
+  validateFormat,
+  prettyHeader,
+  prettyField,
+  prettyTable,
+  prettyDim,
+  EXIT,
+  exitError,
+} from '../lib/output.js';
+import { handleError } from '../lib/errors.js';
+import { parseLimit, parseTimestamp } from '../lib/time.js';
+import { writeOutputFile } from '../lib/file.js';
+import {
+  ACCOUNT_EXCHANGES,
+  POSITIONS_EXCHANGES,
+  compact,
+  field,
+  getLighterAccountsResource,
+  getPositionsResource,
+  shortAddress,
+  text,
+  toEnvelope,
+  type PageEnvelope,
+  type PositionsExchange,
+  type PositionsKey,
+} from '../lib/positions.js';
+
+const HOUR_MS = 3_600_000;
+const ADDRESS_RE = /^0x[0-9a-fA-F]{40}$/;
+
+interface CommonOptions {
+  exchange: string;
+  apiKey?: string;
+  format: string;
+  out?: string;
+}
+
+interface KeyOptions extends CommonOptions {
+  address?: string;
+  account?: string;
+}
+
+export interface PositionsGetOptions extends KeyOptions {
+  timestamp?: string;
+  symbol?: string;
+  dex?: string;
+  limit?: string;
+  cursor?: string;
+}
+
+export interface PositionsRangeOptions extends KeyOptions {
+  start: string;
+  end: string;
+  symbol?: string;
+  dex?: string;
+  limit?: string;
+  cursor?: string;
+}
+
+export interface PositionsMarketOptions extends CommonOptions {
+  symbol: string;
+  hour?: string;
+  side?: string;
+  minValue?: string;
+  includeSystem?: boolean;
+  limit?: string;
+  cursor?: string;
+}
+
+export interface PositionsSummaryOptions extends CommonOptions {
+  symbol: string;
+  start?: string;
+  end?: string;
+  includeSystem?: boolean;
+  limit?: string;
+  cursor?: string;
+}
+
+export interface PositionsAllOptions extends CommonOptions {
+  hour: string;
+  includeSystem?: boolean;
+  limit?: string;
+  cursor?: string;
+}
+
+export interface AccountGetOptions extends CommonOptions {
+  address: string;
+  dex?: string;
+}
+
+export interface AccountHistoryOptions extends CommonOptions {
+  address: string;
+  start: string;
+  end: string;
+  dex?: string;
+  limit?: string;
+  cursor?: string;
+}
+
+export interface AccountsByL1Options {
+  exchange: string;
+  l1Address: string;
+  limit?: string;
+  cursor?: string;
+  apiKey?: string;
+  format: string;
+  out?: string;
+}
+
+// ── Validation ──────────────────────────────────────────────────────────
+
+function positionsExchange(raw: string): PositionsExchange {
+  const exchange = validateExchange(raw);
+  requireExchange(exchange, POSITIONS_EXCHANGES, 'account positions');
+  return exchange;
+}
+
+function accountExchange(raw: string): PositionsExchange {
+  const exchange = validateExchange(raw);
+  if (!ACCOUNT_EXCHANGES.includes(exchange as PositionsExchange)) {
+    exitError(
+      `Account summaries are available for --exchange ${listOr(ACCOUNT_EXCHANGES)}. ` +
+        'On Lighter, `oxa positions get --account <index>` returns the account and its positions.',
+      EXIT.VALIDATION,
+    );
+  }
+  return exchange as PositionsExchange;
+}
+
+function parseAddress(value: string, flag: string): string {
+  if (!ADDRESS_RE.test(value)) {
+    exitError(`--${flag} must be a 0x-prefixed wallet address with 40 hex characters.`, EXIT.VALIDATION);
+  }
+  return value;
+}
+
+function parseAccountIndex(value: string): number {
+  const n = Number(value);
+  if (!/^\d+$/.test(value) || !Number.isSafeInteger(n)) {
+    exitError('--account must be a Lighter account index (a non-negative integer).', EXIT.VALIDATION);
+  }
+  return n;
+}
+
+/**
+ * Resolve the positions key: a wallet address on Hyperliquid and HIP-3, an
+ * integer account index on either Lighter deployment.
+ */
+export function resolvePositionsKey(exchange: PositionsExchange, options: KeyOptions): PositionsKey {
+  if (options.address !== undefined && options.account !== undefined) {
+    exitError('Pass either --address or --account, not both.', EXIT.VALIDATION);
+  }
+  if (isLighterExchange(exchange)) {
+    if (options.account === undefined) {
+      const lookup =
+        exchange === 'lighter'
+          ? ' Find the account indices behind an L1 address with `oxa accounts by-l1 --l1-address 0x...`.'
+          : '';
+      exitError(
+        `${exchangeLabel(exchange)} positions are keyed by account index. Pass --account <index>.${lookup}`,
+        EXIT.VALIDATION,
+      );
+    }
+    return parseAccountIndex(options.account);
+  }
+  if (options.address === undefined) {
+    exitError(
+      `${exchangeLabel(exchange)} positions are keyed by wallet address. Pass --address 0x...`,
+      EXIT.VALIDATION,
+    );
+  }
+  return parseAddress(options.address, 'address');
+}
+
+function parseDex(exchange: PositionsExchange, dex: string | undefined): string | undefined {
+  if (dex === undefined) return undefined;
+  if (exchange !== 'hip3') {
+    exitError('--dex applies to --exchange hip3 only.', EXIT.VALIDATION);
+  }
+  return dex;
+}
+
+/** `--include-system` is a Lighter filter; `true` or omitted. */
+function parseIncludeSystem(exchange: PositionsExchange, includeSystem: boolean | undefined): true | undefined {
+  if (!includeSystem) return undefined;
+  if (!isLighterExchange(exchange)) {
+    exitError('--include-system applies to --exchange lighter and rh-lighter only.', EXIT.VALIDATION);
+  }
+  return true;
+}
+
+function parseRange(startRaw: string, endRaw: string): { start: number; end: number } {
+  const start = parseTimestamp(startRaw, 'start');
+  const end = parseTimestamp(endRaw, 'end');
+  if (start >= end) {
+    exitError('--start must be before --end', EXIT.VALIDATION);
+  }
+  return { start, end };
+}
+
+/** Market and bulk listings read one committed hourly snapshot. */
+export function parseHour(raw: string): number {
+  const hour = parseTimestamp(raw, 'hour');
+  if (hour % HOUR_MS !== 0) {
+    exitError(
+      '--hour must be an exact UTC hour (for example 2026-09-01T12:00:00Z or its Unix ms value).',
+      EXIT.VALIDATION,
+    );
+  }
+  return hour;
+}
+
+function parseSide(raw: string | undefined): 'long' | 'short' | undefined {
+  if (raw === undefined) return undefined;
+  const side = raw.toLowerCase();
+  if (side !== 'long' && side !== 'short') {
+    exitError('--side must be long or short.', EXIT.VALIDATION);
+  }
+  return side;
+}
+
+function parseMinValue(raw: string | undefined): number | undefined {
+  if (raw === undefined) return undefined;
+  const n = Number(raw);
+  if (raw.trim() === '' || !Number.isFinite(n) || n < 0) {
+    exitError('--min-value must be a non-negative number (USD).', EXIT.VALIDATION);
+  }
+  return n;
+}
+
+// ── Output ──────────────────────────────────────────────────────────────
+
+function rows(data: unknown): unknown[] {
+  return Array.isArray(data) ? data : [];
+}
+
+/** Records in a page: the rows, or a wallet response's positions. */
+function recordCount(data: unknown): number {
+  if (Array.isArray(data)) return data.length;
+  const positions = field(data, 'positions');
+  if (Array.isArray(positions)) return positions.length;
+  const accounts = field(data, 'accounts');
+  if (Array.isArray(accounts)) return accounts.length;
+  return data === null || data === undefined ? 0 : 1;
+}
+
+function printMeta(meta: Record<string, unknown> | undefined): void {
+  if (!meta) return;
+  prettyField('As of', field(meta, 'asOf', 'as_of') as string | undefined);
+  prettyField('Snapshot', field(meta, 'snapshotTs', 'snapshot_ts') as string | undefined);
+  prettyField('Source', field(meta, 'source') as string | undefined);
+  prettyField('Quality', field(meta, 'quality') as string | undefined);
+  if (field(meta, 'stale') === true) prettyField('Stale', 'yes');
+  prettyField('Built through', field(meta, 'builtThrough', 'built_through') as string | undefined);
+  prettyField('Finalized through', field(meta, 'finalizedThrough', 'finalized_through') as string | undefined);
+  prettyField('Clamped to', field(meta, 'clampedTo', 'clamped_to') as string | undefined);
+  prettyField('Coverage from', field(meta, 'coverageFrom', 'coverage_from') as string | undefined);
+  prettyField('Notice', field(meta, 'notice') as string | undefined);
+}
+
+function printMore(page: PageEnvelope, shown: number, total: number): void {
+  if (total > shown) prettyDim(`... and ${total - shown} more`);
+  if (page.nextCursor) prettyDim('More data available (use --cursor to paginate)');
+}
+
+/**
+ * Emit one page: JSON envelope on stdout, or a file plus a short summary with
+ * --out, or the pretty renderer.
+ */
+function emit(
+  page: PageEnvelope,
+  options: { format: string; out?: string },
+  context: Record<string, unknown>,
+  pretty: () => void,
+): void {
+  if (options.out) {
+    writeOutputFile(options.out, page);
+    const summary = {
+      written_to: options.out,
+      records: recordCount(page.data),
+      ...context,
+      has_more: page.nextCursor !== null,
+      nextCursor: page.nextCursor,
+    };
+    if (options.format === 'pretty') {
+      prettyHeader(`Written to ${options.out}`);
+      prettyField('Records', summary.records);
+      prettyField('Has more', summary.has_more ? 'yes' : 'no');
+      process.stdout.write('\n');
+    } else {
+      outputJson(summary);
+    }
+    return;
+  }
+  if (options.format === 'pretty') {
+    pretty();
+    process.stdout.write('\n');
+    return;
+  }
+  outputJson(page);
+}
+
+function keyLabel(key: PositionsKey): string {
+  return typeof key === 'number' ? `account ${key}` : shortAddress(key);
+}
+
+function positionRow(p: unknown): string[] {
+  return [
+    text(field(p, 'symbol', 'coin')),
+    text(field(p, 'side')),
+    text(field(p, 'size')),
+    text(field(p, 'entryPrice', 'entry_price')),
+    text(field(p, 'markPrice', 'mark_price')),
+    text(field(p, 'positionValue', 'position_value')),
+    text(field(p, 'unrealizedPnl', 'unrealized_pnl')),
+    text(field(p, 'liquidationPrice', 'liquidation_price')),
+  ];
+}
+
+const POSITION_HEADERS = ['Symbol', 'Side', 'Size', 'Entry', 'Mark', 'Value', 'uPnL', 'Liq. price'];
+
+function printAccount(account: unknown): void {
+  if (account === null || account === undefined) return;
+  prettyField('Account value', field(account, 'accountValue', 'account_value') as string | undefined);
+  prettyField('Total position value', field(account, 'totalPositionValue', 'total_position_value') as string | undefined);
+  prettyField('Unrealized PnL', field(account, 'totalUnrealizedPnl', 'total_unrealized_pnl') as string | undefined);
+  prettyField('Margin used', field(account, 'totalMarginUsed', 'total_margin_used') as string | undefined);
+  prettyField('Open positions', field(account, 'nPositions', 'n_positions') as number | undefined);
+}
+
+// ── oxa positions get ───────────────────────────────────────────────────
+
+export async function positionsGetCommand(options: PositionsGetOptions): Promise<void> {
+  const format = validateFormat(options.format);
+  const exchange = positionsExchange(options.exchange);
+  const key = resolvePositionsKey(exchange, options);
+  const dex = parseDex(exchange, options.dex);
+  const timestamp = options.timestamp !== undefined ? parseTimestamp(options.timestamp, 'timestamp') : undefined;
+  const limit = parseLimit(options.limit);
+  const apiKey = resolveApiKey(options.apiKey);
+  const resource = getPositionsResource(createClient(apiKey), exchange);
+
+  try {
+    const result = await resource.get(
+      key,
+      compact({ timestamp, symbol: options.symbol, dex, cursor: options.cursor, limit }),
+    );
+    const page = toEnvelope(result);
+    emit(page, { format, out: options.out }, { exchange }, () => {
+      const positions = rows(field(page.data, 'positions') ?? page.data);
+      prettyHeader(`Positions for ${keyLabel(key)} (${exchangeLabel(exchange)}): ${positions.length} open`);
+      printMeta(page.meta);
+      prettyField('Account seen', field(page.data, 'accountSeen', 'account_seen') as string | undefined);
+      printAccount(field(page.data, 'account'));
+      if (positions.length === 0) {
+        prettyDim('No open positions.');
+      } else {
+        process.stdout.write('\n');
+        prettyTable(POSITION_HEADERS, positions.slice(0, 50).map(positionRow));
+        printMore(page, Math.min(positions.length, 50), positions.length);
+      }
+    });
+    process.exit(EXIT.SUCCESS);
+  } catch (error) {
+    handleError(error, apiKey);
+  }
+}
+
+// ── oxa positions history / changes ─────────────────────────────────────
+
+async function rangeCommand(options: PositionsRangeOptions, kind: 'history' | 'changes'): Promise<void> {
+  const format = validateFormat(options.format);
+  const exchange = positionsExchange(options.exchange);
+  const key = resolvePositionsKey(exchange, options);
+  const dex = parseDex(exchange, options.dex);
+  const { start, end } = parseRange(options.start, options.end);
+  const limit = parseLimit(options.limit);
+  const apiKey = resolveApiKey(options.apiKey);
+  const resource = getPositionsResource(createClient(apiKey), exchange);
+
+  try {
+    const params = compact({ start, end, symbol: options.symbol, dex, cursor: options.cursor, limit });
+    const result = kind === 'history' ? await resource.history(key, params) : await resource.changes(key, params);
+    const page = toEnvelope(result);
+    emit(page, { format, out: options.out }, { exchange }, () => {
+      const data = rows(page.data);
+      const title = kind === 'history' ? 'Hourly positions' : 'Position changes';
+      prettyHeader(`${title} for ${keyLabel(key)} (${exchangeLabel(exchange)}): ${data.length} records`);
+      printMeta(page.meta);
+      if (data.length === 0) {
+        prettyDim('No records in this window.');
+        return;
+      }
+      process.stdout.write('\n');
+      const preview = data.slice(0, 20);
+      if (kind === 'history') {
+        prettyTable(
+          ['Snapshot', 'Symbol', 'Side', 'Size', 'Entry', 'Value', 'uPnL'],
+          preview.map((p) => [
+            text(field(p, 'snapshotTs', 'snapshot_ts')),
+            text(field(p, 'symbol', 'coin')),
+            text(field(p, 'side')),
+            text(field(p, 'size')),
+            text(field(p, 'entryPrice', 'entry_price')),
+            text(field(p, 'positionValue', 'position_value')),
+            text(field(p, 'unrealizedPnl', 'unrealized_pnl')),
+          ]),
+        );
+      } else {
+        prettyTable(
+          ['Timestamp', 'Symbol', 'Event', 'Side', 'Price', 'Size', 'Before', 'After'],
+          preview.map((c) => [
+            text(field(c, 'timestamp')),
+            text(field(c, 'symbol', 'coin')),
+            text(field(c, 'eventType', 'event_type')),
+            text(field(c, 'side')),
+            text(field(c, 'price')),
+            text(field(c, 'size')),
+            text(field(c, 'startPosition', 'start_position')),
+            text(field(c, 'endPosition', 'end_position')),
+          ]),
+        );
+      }
+      printMore(page, preview.length, data.length);
+    });
+    process.exit(EXIT.SUCCESS);
+  } catch (error) {
+    handleError(error, apiKey);
+  }
+}
+
+export async function positionsHistoryCommand(options: PositionsRangeOptions): Promise<void> {
+  return rangeCommand(options, 'history');
+}
+
+export async function positionsChangesCommand(options: PositionsRangeOptions): Promise<void> {
+  return rangeCommand(options, 'changes');
+}
+
+// ── oxa positions market ────────────────────────────────────────────────
+
+export async function positionsMarketCommand(options: PositionsMarketOptions): Promise<void> {
+  const format = validateFormat(options.format);
+  const exchange = positionsExchange(options.exchange);
+  const includeSystem = parseIncludeSystem(exchange, options.includeSystem);
+  const hour = options.hour !== undefined ? parseHour(options.hour) : undefined;
+  const side = parseSide(options.side);
+  const minValue = parseMinValue(options.minValue);
+  const limit = parseLimit(options.limit);
+  const apiKey = resolveApiKey(options.apiKey);
+  const resource = getPositionsResource(createClient(apiKey), exchange);
+
+  try {
+    const result = await resource.market(
+      options.symbol,
+      compact({
+        hour,
+        side,
+        minValue,
+        includeSystem,
+        cursor: options.cursor,
+        limit,
+      }),
+    );
+    const page = toEnvelope(result);
+    emit(page, { format, out: options.out }, { exchange, symbol: options.symbol }, () => {
+      const data = rows(page.data);
+      prettyHeader(`${options.symbol} open positions (${exchangeLabel(exchange)}): ${data.length} on this page`);
+      printMeta(page.meta);
+      const totals = field(page.meta, 'totals');
+      if (totals) {
+        prettyField(
+          'Longs',
+          `${text(field(totals, 'longCount', 'long_count'))} (value ${text(field(totals, 'longValue', 'long_value'))})`,
+        );
+        prettyField(
+          'Shorts',
+          `${text(field(totals, 'shortCount', 'short_count'))} (value ${text(field(totals, 'shortValue', 'short_value'))})`,
+        );
+      }
+      if (data.length === 0) {
+        prettyDim('No open positions match.');
+        return;
+      }
+      process.stdout.write('\n');
+      const preview = data.slice(0, 20);
+      prettyTable(
+        ['Holder', 'Side', 'Size', 'Entry', 'Value', 'uPnL', 'Liq. price'],
+        preview.map((p) => [
+          shortAddress(text(field(p, 'userAddress', 'user_address', 'accountIndex', 'account_index'))),
+          text(field(p, 'side')),
+          text(field(p, 'size')),
+          text(field(p, 'entryPrice', 'entry_price')),
+          text(field(p, 'positionValue', 'position_value')),
+          text(field(p, 'unrealizedPnl', 'unrealized_pnl')),
+          text(field(p, 'liquidationPrice', 'liquidation_price')),
+        ]),
+      );
+      printMore(page, preview.length, data.length);
+    });
+    process.exit(EXIT.SUCCESS);
+  } catch (error) {
+    handleError(error, apiKey);
+  }
+}
+
+// ── oxa positions summary ───────────────────────────────────────────────
+
+export async function positionsSummaryCommand(options: PositionsSummaryOptions): Promise<void> {
+  const format = validateFormat(options.format);
+  const exchange = positionsExchange(options.exchange);
+  if ((options.start === undefined) !== (options.end === undefined)) {
+    exitError(
+      'Pass both --start and --end for an hourly series, or neither for the latest snapshot.',
+      EXIT.VALIDATION,
+    );
+  }
+  const range = options.start !== undefined ? parseRange(options.start, options.end!) : undefined;
+  const includeSystem = parseIncludeSystem(exchange, options.includeSystem);
+  const limit = parseLimit(options.limit);
+  const apiKey = resolveApiKey(options.apiKey);
+  const resource = getPositionsResource(createClient(apiKey), exchange);
+
+  try {
+    const result = await resource.marketSummary(
+      options.symbol,
+      compact({ start: range?.start, end: range?.end, includeSystem, cursor: options.cursor, limit }),
+    );
+    const page = toEnvelope(result);
+    emit(page, { format, out: options.out }, { exchange, symbol: options.symbol }, () => {
+      const data = rows(page.data);
+      prettyHeader(`${options.symbol} positioning summary (${exchangeLabel(exchange)}): ${data.length} snapshots`);
+      printMeta(page.meta);
+      if (data.length === 0) {
+        prettyDim('No snapshots in this window.');
+        return;
+      }
+      process.stdout.write('\n');
+      const preview = data.slice(-24);
+      prettyTable(
+        ['Snapshot', 'Longs', 'Shorts', 'Long value', 'Short value', 'Top-10 share'],
+        preview.map((s) => [
+          text(field(s, 'snapshotTs', 'snapshot_ts')),
+          text(field(s, 'longCount', 'long_count')),
+          text(field(s, 'shortCount', 'short_count')),
+          text(field(s, 'longValue', 'long_value')),
+          text(field(s, 'shortValue', 'short_value')),
+          text(field(s, 'top10ValueShare', 'top10_value_share')),
+        ]),
+      );
+      if (data.length > preview.length) prettyDim(`Showing the latest ${preview.length} of ${data.length}.`);
+      if (page.nextCursor) prettyDim('More data available (use --cursor to paginate)');
+    });
+    process.exit(EXIT.SUCCESS);
+  } catch (error) {
+    handleError(error, apiKey);
+  }
+}
+
+// ── oxa positions all ───────────────────────────────────────────────────
+
+export async function positionsAllCommand(options: PositionsAllOptions): Promise<void> {
+  const format = validateFormat(options.format);
+  const exchange = positionsExchange(options.exchange);
+  const hour = parseHour(options.hour);
+  const includeSystem = parseIncludeSystem(exchange, options.includeSystem);
+  const limit = parseLimit(options.limit);
+  const apiKey = resolveApiKey(options.apiKey);
+  const resource = getPositionsResource(createClient(apiKey), exchange);
+
+  try {
+    const result = await resource.all(
+      compact({ hour, includeSystem, cursor: options.cursor, limit }),
+    );
+    const page = toEnvelope(result);
+    emit(page, { format, out: options.out }, { exchange }, () => {
+      const data = rows(page.data);
+      prettyHeader(`All open positions (${exchangeLabel(exchange)}): ${data.length} on this page`);
+      printMeta(page.meta);
+      if (data.length === 0) {
+        prettyDim('No positions in this snapshot.');
+        return;
+      }
+      process.stdout.write('\n');
+      const preview = data.slice(0, 20);
+      prettyTable(
+        ['Symbol', 'Holder', 'Side', 'Size', 'Value'],
+        preview.map((p) => [
+          text(field(p, 'symbol', 'coin')),
+          shortAddress(text(field(p, 'userAddress', 'user_address', 'accountIndex', 'account_index'))),
+          text(field(p, 'side')),
+          text(field(p, 'size')),
+          text(field(p, 'positionValue', 'position_value')),
+        ]),
+      );
+      printMore(page, preview.length, data.length);
+    });
+    process.exit(EXIT.SUCCESS);
+  } catch (error) {
+    handleError(error, apiKey);
+  }
+}
+
+// ── oxa positions account / account-history (Hyperliquid, HIP-3) ────────
+
+export async function accountGetCommand(options: AccountGetOptions): Promise<void> {
+  const format = validateFormat(options.format);
+  const exchange = accountExchange(options.exchange);
+  const address = parseAddress(options.address, 'address');
+  const dex = parseDex(exchange, options.dex);
+  const apiKey = resolveApiKey(options.apiKey);
+  const resource = getPositionsResource(createClient(apiKey), exchange);
+  const account = resource.account?.bind(resource);
+  if (!account) sdkTooOld(`${exchangeLabel(exchange)} account summaries`);
+
+  try {
+    const result = await account(address, compact({ dex }));
+    const page = toEnvelope(result);
+    emit(page, { format, out: options.out }, { exchange }, () => {
+      prettyHeader(`Account ${shortAddress(address)} (${exchangeLabel(exchange)})`);
+      printMeta(page.meta);
+      const accounts = Array.isArray(page.data) ? page.data : [page.data];
+      for (const account of accounts) {
+        const accountDex = field(account, 'dex');
+        if (accountDex) prettyField('Dex', accountDex as string);
+        printAccount(account);
+        prettyField('Quality', field(account, 'quality') as string | undefined);
+      }
+    });
+    process.exit(EXIT.SUCCESS);
+  } catch (error) {
+    handleError(error, apiKey);
+  }
+}
+
+export async function accountHistoryCommand(options: AccountHistoryOptions): Promise<void> {
+  const format = validateFormat(options.format);
+  const exchange = accountExchange(options.exchange);
+  const address = parseAddress(options.address, 'address');
+  const dex = parseDex(exchange, options.dex);
+  const { start, end } = parseRange(options.start, options.end);
+  const limit = parseLimit(options.limit);
+  const apiKey = resolveApiKey(options.apiKey);
+  const resource = getPositionsResource(createClient(apiKey), exchange);
+  const accountHistory = resource.accountHistory?.bind(resource);
+  if (!accountHistory) sdkTooOld(`${exchangeLabel(exchange)} account history`);
+
+  try {
+    const result = await accountHistory(
+      address,
+      compact({ start, end, dex, cursor: options.cursor, limit }),
+    );
+    const page = toEnvelope(result);
+    emit(page, { format, out: options.out }, { exchange }, () => {
+      const data = rows(page.data);
+      prettyHeader(`Account history for ${shortAddress(address)} (${exchangeLabel(exchange)}): ${data.length} records`);
+      printMeta(page.meta);
+      if (data.length === 0) {
+        prettyDim('No account snapshots in this window.');
+        return;
+      }
+      process.stdout.write('\n');
+      const preview = data.slice(0, 20);
+      prettyTable(
+        ['Snapshot', 'Account value', 'Position value', 'uPnL', 'Positions'],
+        preview.map((a) => [
+          text(field(a, 'snapshotTs', 'snapshot_ts')),
+          text(field(a, 'accountValue', 'account_value')),
+          text(field(a, 'totalPositionValue', 'total_position_value')),
+          text(field(a, 'totalUnrealizedPnl', 'total_unrealized_pnl')),
+          text(field(a, 'nPositions', 'n_positions')),
+        ]),
+      );
+      printMore(page, preview.length, data.length);
+    });
+    process.exit(EXIT.SUCCESS);
+  } catch (error) {
+    handleError(error, apiKey);
+  }
+}
+
+// ── oxa accounts by-l1 (Lighter mainnet) ────────────────────────────────
+
+export async function accountsByL1Command(options: AccountsByL1Options): Promise<void> {
+  const format = validateFormat(options.format);
+  const exchange = validateExchange(options.exchange);
+  if (exchange !== 'lighter') {
+    exitError(
+      'Account lookup by L1 address is available for Lighter mainnet only (--exchange lighter).',
+      EXIT.VALIDATION,
+    );
+  }
+  const l1Address = parseAddress(options.l1Address, 'l1-address');
+  const limit = parseLimit(options.limit);
+  const apiKey = resolveApiKey(options.apiKey);
+  const accountsResource = getLighterAccountsResource(createClient(apiKey));
+
+  try {
+    const result = await accountsResource.byL1(
+      l1Address,
+      compact({ cursor: options.cursor, limit }),
+    );
+    const page = toEnvelope(result);
+    emit(page, { format, out: options.out }, { exchange }, () => {
+      const accounts = rows(field(page.data, 'accounts') ?? page.data);
+      prettyHeader(`Lighter accounts for ${shortAddress(l1Address)}`);
+      prettyField('Total accounts', field(page.data, 'totalAccounts', 'total_accounts') as number | undefined);
+      if (accounts.length === 0) {
+        prettyDim('No Lighter accounts found for this address.');
+        return;
+      }
+      process.stdout.write('\n');
+      prettyTable(
+        ['Account index', 'Type', 'First seen'],
+        accounts.map((a) => [
+          text(field(a, 'accountIndex', 'account_index')),
+          text(field(a, 'accountType', 'account_type')),
+          text(field(a, 'firstSeen', 'first_seen')),
+        ]),
+      );
+      if (page.nextCursor) prettyDim('More data available (use --cursor to paginate)');
+    });
+    process.exit(EXIT.SUCCESS);
+  } catch (error) {
+    handleError(error, apiKey);
+  }
+}
diff --git a/src/commands/stream.ts b/src/commands/stream.ts
index 9bbcfe1..cbecf58 100644
--- a/src/commands/stream.ts
+++ b/src/commands/stream.ts
@@ -33,10 +33,12 @@ type Channel =
   | 'trades'
   | 'hip3_trades'
   | 'lighter_trades'
+  | 'rh_lighter_trades'
   | 'spot_trades'
   | 'orderbook'
   | 'hip3_orderbook'
   | 'lighter_orderbook'
+  | 'rh_lighter_orderbook'
   | 'spot_orderbook';
 
 // Allow-listed channels for `oxa stream subscribe <channel> <symbol>`.
@@ -58,6 +60,10 @@ const VALID_GENERIC_CHANNELS: ReadonlySet<string> = new Set([
   'lighter_trades',
   'lighter_open_interest',
   'lighter_funding',
+  'rh_lighter_orderbook',
+  'rh_lighter_trades',
+  'rh_lighter_open_interest',
+  'rh_lighter_funding',
   'hip3_orderbook',
   'hip3_trades',
   'hip3_candles',
@@ -70,26 +76,32 @@ const VALID_GENERIC_CHANNELS: ReadonlySet<string> = new Set([
   'spot_twap',
 ]);
 
-// Lighter channels that support historical replay but not live
-// subscriptions. They are rejected before a socket is opened, with a pointer
-// to the REST command that serves the same data.
+// Lighter channels (mainnet and Robinhood Chain) that support historical
+// replay but not live subscriptions. They are rejected before a socket is
+// opened, with a pointer to the REST command that serves the same data.
 export const LIGHTER_REPLAY_ONLY_CHANNELS: Readonly<Record<string, string>> = {
   lighter_candles: 'Use `oxa candles --exchange lighter` for candle history.',
   lighter_l3_orderbook:
     'Use `oxa l3 get` for the current L3 book or `oxa l3 history` for stored snapshots.',
+  rh_lighter_candles: 'Use `oxa candles --exchange rh-lighter` for candle history.',
 };
 
-// A connection that falls behind a Lighter live channel gets a
-// "Dropped ~N live <channel> messages ..." error notice while the subscription
-// keeps running: books and stats are full states, and trades are independent
-// rows, so the stream stays usable. The CLI reports these as warnings and
-// keeps streaming. The server's "Stopped the <channel> stream ..." notice ends
-// the subscription and, like every other server error, still exits.
+// A connection that falls behind a Lighter live channel (either deployment)
+// gets a "Dropped ~N live <channel> messages ..." error notice while the
+// subscription keeps running: books and stats are full states, and trades are
+// independent rows, so the stream stays usable. The CLI reports these as
+// warnings and keeps streaming. The server's "Stopped the <channel> stream ..."
+// notice ends the subscription and, like every other server error, still exits.
 export function isLighterDropNotice(channel: string, message: string): boolean {
-  return channel.startsWith('lighter_') && message.startsWith('Dropped ~');
+  return (
+    (channel.startsWith('lighter_') || channel.startsWith('rh_lighter_')) &&
+    message.startsWith('Dropped ~')
+  );
 }
 
-// lighter_orderbook sends the newest full book at most once per interval.
+// The Lighter book channels send the newest full book at most once per
+// interval, set with --interval-ms. No other channel takes an interval.
+export const LIGHTER_BOOK_CHANNELS: readonly string[] = ['lighter_orderbook', 'rh_lighter_orderbook'];
 export const LIGHTER_BOOK_INTERVAL_MIN_MS = 100;
 export const LIGHTER_BOOK_INTERVAL_MAX_MS = 5000;
 
@@ -104,12 +116,14 @@ const VERB_CHANNELS: Readonly<Record<string, Readonly<Record<string, Channel>>>>
     hyperliquid: 'trades',
     hip3: 'hip3_trades',
     lighter: 'lighter_trades',
+    'rh-lighter': 'rh_lighter_trades',
     spot: 'spot_trades',
   },
   orderbook: {
     hyperliquid: 'orderbook',
     hip3: 'hip3_orderbook',
     lighter: 'lighter_orderbook',
+    'rh-lighter': 'rh_lighter_orderbook',
     spot: 'spot_orderbook',
   },
 };
@@ -140,15 +154,17 @@ function parseDuration(raw?: string): number | undefined {
 }
 
 /**
- * Validate `--interval-ms` for the resolved channel. Only lighter_orderbook
- * takes an interval; the server applies the same bounds.
+ * Validate `--interval-ms` for the resolved channel. Only the Lighter book
+ * channels (lighter_orderbook, rh_lighter_orderbook) take an interval; the
+ * server applies the same bounds.
  */
 export function parseIntervalMs(raw: string | undefined, channel: string): number | undefined {
   if (raw === undefined) return undefined;
-  if (channel !== 'lighter_orderbook') {
+  if (!LIGHTER_BOOK_CHANNELS.includes(channel)) {
     exitError(
-      '--interval-ms is only supported on lighter_orderbook ' +
-        '(`oxa stream orderbook <symbol> --exchange lighter` or `oxa stream subscribe lighter_orderbook <symbol>`).',
+      '--interval-ms is only supported on lighter_orderbook and rh_lighter_orderbook ' +
+        '(`oxa stream orderbook <symbol> --exchange lighter|rh-lighter` or ' +
+        '`oxa stream subscribe lighter_orderbook|rh_lighter_orderbook <symbol>`).',
       EXIT.VALIDATION,
     );
   }
@@ -161,7 +177,7 @@ export function parseIntervalMs(raw: string | undefined, channel: string): numbe
   ) {
     exitError(
       `--interval-ms must be a whole number between ${LIGHTER_BOOK_INTERVAL_MIN_MS} and ` +
-        `${LIGHTER_BOOK_INTERVAL_MAX_MS} for lighter_orderbook (got ${raw}). Leave it out for one book a second.`,
+        `${LIGHTER_BOOK_INTERVAL_MAX_MS} for ${channel} (got ${raw}). Leave it out for one book a second.`,
       EXIT.VALIDATION,
     );
   }
diff --git a/src/commands/trades.ts b/src/commands/trades.ts
index 32ea910..0242a00 100644
--- a/src/commands/trades.ts
+++ b/src/commands/trades.ts
@@ -59,7 +59,8 @@ export async function tradesFetchCommand(options: TradesFetchOptions): Promise<v
       );
     }
 
-    // Lighter/HIP-3: use recent trades
+    // Lighter (both deployments) and HIP-3: the recent tier. On Lighter it is
+    // preliminary until the finalization watermark passes it.
     return fetchRecent(exchange, options.symbol, limit, apiKey, format, options.out);
   }
 
@@ -91,7 +92,10 @@ async function fetchRange(
     const exchangeClient = getExchangeClient(client, exchange, apiKey);
     const result = await exchangeClient.trades.list(symbol, { start, end, limit, cursor });
     const trades = result.data;
-    const envelope = { data: trades, nextCursor: result.nextCursor ?? null };
+    // Lighter ranges are clamped to the finalization watermark; the SDK
+    // surfaces that as meta (finalized_through, clamped_to), passed through.
+    const meta = responseMeta(result);
+    const envelope = { data: trades, nextCursor: result.nextCursor ?? null, ...(meta ? { meta } : {}) };
 
     if (outPath) {
       writeOutputFile(outPath, trades);
@@ -102,6 +106,7 @@ async function fetchRange(
         symbol,
         has_more: !!result.nextCursor,
         nextCursor: result.nextCursor ?? null,
+        ...(meta ? { meta } : {}),
       };
       if (format === 'pretty') {
         prettyHeader(`${symbol} Trades (${exchange})`);
@@ -113,7 +118,7 @@ async function fetchRange(
         outputJson(summary);
       }
     } else if (format === 'pretty') {
-      prettyPrintTrades(trades, symbol, exchange, result.nextCursor);
+      prettyPrintTrades(trades, symbol, exchange, result.nextCursor, meta);
     } else {
       outputJson(envelope);
     }
@@ -172,8 +177,13 @@ function prettyPrintTrades(
   symbol: string,
   exchange: string,
   nextCursor?: string,
+  meta?: Record<string, unknown>,
 ): void {
   prettyHeader(`${symbol} Trades (${exchange}) — ${trades.length} records`);
+  if (meta) {
+    prettyField('Finalized through', metaString(meta, 'finalizedThrough', 'finalized_through'));
+    prettyField('Clamped to', metaString(meta, 'clampedTo', 'clamped_to'));
+  }
 
   if (trades.length === 0) {
     prettyDim('No trades found.');
@@ -198,3 +208,16 @@ function prettyPrintTrades(
   }
   process.stdout.write('\n');
 }
+
+function responseMeta(result: unknown): Record<string, unknown> | undefined {
+  const meta = (result as { meta?: unknown } | null)?.meta;
+  return meta && typeof meta === 'object' ? (meta as Record<string, unknown>) : undefined;
+}
+
+function metaString(meta: Record<string, unknown>, ...keys: string[]): string | undefined {
+  for (const key of keys) {
+    const value = meta[key];
+    if (value !== undefined && value !== null) return String(value);
+  }
+  return undefined;
+}
diff --git a/src/lib/client.ts b/src/lib/client.ts
index 3872a54..c561972 100644
--- a/src/lib/client.ts
+++ b/src/lib/client.ts
@@ -3,9 +3,57 @@ import type { HyperliquidClient, LighterClient, Hip3Client } from '@0xarchive/sd
 import { Hip4Client } from './hip4.js';
 import { exitError, EXIT } from './output.js';
 
-export type Exchange = 'hyperliquid' | 'lighter' | 'hip3' | 'hip4';
+/**
+ * `--exchange` values. `lighter` and `rh-lighter` are the two deployments of
+ * Lighter: mainnet and Robinhood Chain.
+ */
+export type Exchange = 'hyperliquid' | 'lighter' | 'rh-lighter' | 'hip3' | 'hip4';
 
-const VALID_EXCHANGES: Exchange[] = ['hyperliquid', 'lighter', 'hip3', 'hip4'];
+export const VALID_EXCHANGES: readonly Exchange[] = ['hyperliquid', 'lighter', 'rh-lighter', 'hip3', 'hip4'];
+
+/** Both Lighter deployments. */
+export type LighterExchange = 'lighter' | 'rh-lighter';
+
+export function isLighterExchange(exchange: string): exchange is LighterExchange {
+  return exchange === 'lighter' || exchange === 'rh-lighter';
+}
+
+/** "a", "a or b", "a, b, or c". */
+export function listOr(values: readonly string[]): string {
+  if (values.length <= 1) return values.join('');
+  if (values.length === 2) return `${values[0]} or ${values[1]}`;
+  return `${values.slice(0, -1).join(', ')}, or ${values[values.length - 1]}`;
+}
+
+/** Human label for an `--exchange` value, used in headers and error messages. */
+export function exchangeLabel(exchange: string): string {
+  switch (exchange) {
+    case 'hyperliquid':
+      return 'Hyperliquid';
+    case 'hip3':
+      return 'Hyperliquid HIP-3';
+    case 'hip4':
+      return 'Hyperliquid HIP-4';
+    case 'lighter':
+      return 'Lighter';
+    case 'rh-lighter':
+      return 'Lighter on Robinhood Chain';
+    default:
+      return exchange;
+  }
+}
+
+// The oldest @0xarchive/sdk release with the Robinhood Chain client, the
+// positions resources, and Lighter liquidations. package.json pins it as the
+// floor; this message covers a stale install that predates the floor.
+export const SDK_FLOOR = '1.12.0';
+
+export function sdkTooOld(feature: string): never {
+  exitError(
+    `Support for ${feature} requires @0xarchive/sdk ${SDK_FLOOR} or newer. Reinstall @0xarchive/cli to pick it up.`,
+    EXIT.INTERNAL,
+  );
+}
 
 export function resolveApiKey(cliKey?: string): string {
   const key = cliKey || process.env.OXA_API_KEY;
@@ -29,6 +77,23 @@ export function validateExchange(exchange: string): Exchange {
   return exchange as Exchange;
 }
 
+/**
+ * Reject an `--exchange` value that has no endpoint for `feature`, before any
+ * network call.
+ */
+export function requireExchange<T extends Exchange>(
+  exchange: Exchange,
+  allowed: readonly T[],
+  feature: string,
+): asserts exchange is T {
+  if (!allowed.includes(exchange as T)) {
+    exitError(
+      `${exchangeLabel(exchange)} has no ${feature} endpoint. Use --exchange ${listOr(allowed)}.`,
+      EXIT.VALIDATION,
+    );
+  }
+}
+
 // HIP-4 has no funding or liquidation endpoints (binary outcome markets).
 // Reject unsupported requests early with a clear message before any network call.
 export function rejectHip4(
@@ -37,7 +102,7 @@ export function rejectHip4(
 ): asserts exchange is Exclude<Exchange, 'hip4'> {
   if (exchange === 'hip4') {
     exitError(
-      `HIP-4 has no ${feature} endpoint. Use --exchange hyperliquid or hip3.`,
+      `HIP-4 has no ${feature} endpoint. Use --exchange hyperliquid, hip3, lighter, or rh-lighter.`,
       EXIT.VALIDATION,
     );
   }
@@ -51,6 +116,16 @@ export function createHip4Client(apiKey: string): Hip4Client {
   return new Hip4Client(apiKey);
 }
 
+/**
+ * The Lighter on Robinhood Chain client (`client.rhLighter`). It has the same
+ * resources as the mainnet Lighter client except L3.
+ */
+export function getRhLighterClient(client: OxArchive): LighterClient {
+  const rh = (client as unknown as { rhLighter?: LighterClient }).rhLighter;
+  if (!rh) sdkTooOld('Lighter on Robinhood Chain (--exchange rh-lighter)');
+  return rh;
+}
+
 export function getExchangeClient(
   client: OxArchive,
   exchange: 'hyperliquid',
@@ -58,7 +133,7 @@ export function getExchangeClient(
 ): HyperliquidClient;
 export function getExchangeClient(
   client: OxArchive,
-  exchange: 'lighter',
+  exchange: LighterExchange,
   apiKey?: string,
 ): LighterClient;
 export function getExchangeClient(
@@ -89,5 +164,6 @@ export function getExchangeClient(
   if (exchange === 'hip4') return new Hip4Client(apiKey ?? '');
   if (exchange === 'hip3') return client.hyperliquid.hip3;
   if (exchange === 'hyperliquid') return client.hyperliquid;
+  if (exchange === 'rh-lighter') return getRhLighterClient(client);
   return client.lighter;
 }
diff --git a/src/lib/positions.ts b/src/lib/positions.ts
new file mode 100644
index 0000000..ce0550b
--- /dev/null
+++ b/src/lib/positions.ts
@@ -0,0 +1,167 @@
+// Account positions through the @0xarchive/sdk positions resources.
+//
+// Every venue client (hyperliquid, hip3, lighter, rhLighter) carries a
+// `positions` resource; the Hyperliquid and HIP-3 ones add account summaries,
+// and the mainnet Lighter client carries `accounts.byL1`. The interfaces below
+// describe the calls the CLI makes, so the commands type-check on their own
+// and fail with a clear message on an SDK install older than the floor.
+
+import type { OxArchive } from '@0xarchive/sdk';
+import { exchangeLabel, getRhLighterClient, sdkTooOld } from './client.js';
+
+export type PositionsExchange = 'hyperliquid' | 'hip3' | 'lighter' | 'rh-lighter';
+
+export const POSITIONS_EXCHANGES: readonly PositionsExchange[] = ['hyperliquid', 'hip3', 'lighter', 'rh-lighter'];
+
+/** Account summaries (`account`, `accountHistory`) are Hyperliquid and HIP-3 only. */
+export const ACCOUNT_EXCHANGES: readonly PositionsExchange[] = ['hyperliquid', 'hip3'];
+
+/** A wallet address on Hyperliquid and HIP-3; an integer account index on Lighter. */
+export type PositionsKey = string | number;
+
+export interface WalletPositionsParams {
+  timestamp?: number;
+  symbol?: string;
+  dex?: string;
+  cursor?: string;
+  limit?: number;
+}
+
+export interface PositionsRangeParams {
+  start: number;
+  end: number;
+  symbol?: string;
+  dex?: string;
+  cursor?: string;
+  limit?: number;
+}
+
+export interface MarketPositionsParams {
+  hour?: number;
+  side?: 'long' | 'short';
+  minValue?: number;
+  includeSystem?: boolean;
+  cursor?: string;
+  limit?: number;
+}
+
+export interface MarketSummaryParams {
+  start?: number;
+  end?: number;
+  includeSystem?: boolean;
+  cursor?: string;
+  limit?: number;
+}
+
+export interface BulkPositionsParams {
+  hour: number;
+  includeSystem?: boolean;
+  cursor?: string;
+  limit?: number;
+}
+
+export interface AccountParams {
+  dex?: string;
+}
+
+export interface AccountHistoryParams {
+  start: number;
+  end: number;
+  dex?: string;
+  cursor?: string;
+  limit?: number;
+}
+
+export interface PositionsResource {
+  get(key: PositionsKey, params?: WalletPositionsParams): Promise<unknown>;
+  history(key: PositionsKey, params: PositionsRangeParams): Promise<unknown>;
+  changes(key: PositionsKey, params: PositionsRangeParams): Promise<unknown>;
+  market(symbol: string, params?: MarketPositionsParams): Promise<unknown>;
+  marketSummary(symbol: string, params?: MarketSummaryParams): Promise<unknown>;
+  all(params: BulkPositionsParams): Promise<unknown>;
+  account?(address: string, params?: AccountParams): Promise<unknown>;
+  accountHistory?(address: string, params: AccountHistoryParams): Promise<unknown>;
+}
+
+export interface LighterAccountsResource {
+  byL1(l1Address: string, params?: { cursor?: string; limit?: number }): Promise<unknown>;
+}
+
+function venueClient(client: OxArchive, exchange: PositionsExchange): unknown {
+  switch (exchange) {
+    case 'hyperliquid':
+      return client.hyperliquid;
+    case 'hip3':
+      return client.hyperliquid.hip3;
+    case 'lighter':
+      return client.lighter;
+    case 'rh-lighter':
+      return getRhLighterClient(client);
+  }
+}
+
+export function getPositionsResource(client: OxArchive, exchange: PositionsExchange): PositionsResource {
+  const positions = (venueClient(client, exchange) as { positions?: PositionsResource } | undefined)?.positions;
+  if (!positions) sdkTooOld(`${exchangeLabel(exchange)} positions`);
+  return positions;
+}
+
+export function getLighterAccountsResource(client: OxArchive): LighterAccountsResource {
+  const accounts = (client.lighter as unknown as { accounts?: LighterAccountsResource }).accounts;
+  if (!accounts) sdkTooOld('Lighter account lookup');
+  return accounts;
+}
+
+/** Drop undefined values so only the flags the user passed reach the SDK. */
+export function compact<T extends object>(params: T): T {
+  return Object.fromEntries(Object.entries(params).filter(([, v]) => v !== undefined)) as T;
+}
+
+export interface PageEnvelope {
+  data: unknown;
+  nextCursor: string | null;
+  meta?: Record<string, unknown>;
+}
+
+/**
+ * Normalize an SDK result into the CLI's JSON envelope: `data`, `nextCursor`,
+ * and `meta` when the SDK returns response meta (as_of, snapshot_ts, source,
+ * quality, stale, built_through, finalized_through, totals, notices).
+ */
+export function toEnvelope(result: unknown): PageEnvelope {
+  if (result !== null && typeof result === 'object' && !Array.isArray(result)) {
+    const r = result as Record<string, unknown>;
+    const meta = r.meta !== null && typeof r.meta === 'object' ? (r.meta as Record<string, unknown>) : undefined;
+    const cursor = r.nextCursor ?? meta?.nextCursor ?? null;
+    const nextCursor = typeof cursor === 'string' && cursor !== '' ? cursor : null;
+    let data: unknown;
+    if ('data' in r) {
+      data = r.data;
+    } else {
+      const { meta: _meta, nextCursor: _next, ...rest } = r;
+      data = rest;
+    }
+    return meta ? { data, nextCursor, meta } : { data, nextCursor };
+  }
+  return { data: result, nextCursor: null };
+}
+
+/** Read a field that may arrive camelCase (SDK) or snake_case (raw API). */
+export function field(obj: unknown, ...keys: string[]): unknown {
+  if (obj === null || typeof obj !== 'object') return undefined;
+  const record = obj as Record<string, unknown>;
+  for (const key of keys) {
+    if (record[key] !== undefined && record[key] !== null) return record[key];
+  }
+  return undefined;
+}
+
+export function text(value: unknown): string {
+  if (value === undefined || value === null || value === '') return '-';
+  if (typeof value === 'object') return JSON.stringify(value);
+  return String(value);
+}
+
+export function shortAddress(address: string): string {
+  return /^0x[0-9a-fA-F]{40}$/.test(address) ? `${address.slice(0, 6)}...${address.slice(-4)}` : address;
+}
diff --git a/tests/hip4-candles.test.ts b/tests/hip4-candles.test.ts
index aa2eddc..00fe363 100644
--- a/tests/hip4-candles.test.ts
+++ b/tests/hip4-candles.test.ts
@@ -170,7 +170,7 @@ describe('HIP-4 candle coverage', () => {
     const stderrSpy = vi.spyOn(process.stderr, 'write').mockImplementation(() => true);
     expect(() => rejectHip4('hip4', 'funding')).toThrow('process.exit unexpectedly called');
     expect(stderrSpy).toHaveBeenCalledWith(
-      expect.stringContaining('Use --exchange hyperliquid or hip3.'),
+      expect.stringContaining('Use --exchange hyperliquid, hip3, lighter, or rh-lighter.'),
     );
   });
 
@@ -179,7 +179,7 @@ describe('HIP-4 candle coverage', () => {
       new URL('../src/commands/liquidations.ts', import.meta.url),
       'utf8',
     );
-    expect(source).toContain('Use --exchange hyperliquid or hip3.');
+    expect(source).toContain('Use --exchange hyperliquid, hip3, lighter, or rh-lighter.');
     expect(source).not.toContain('Use --exchange hl or hip3.');
   });
 
diff --git a/tests/positions.test.ts b/tests/positions.test.ts
new file mode 100644
index 0000000..c6df10d
--- /dev/null
+++ b/tests/positions.test.ts
@@ -0,0 +1,669 @@
+import { mkdtempSync, readFileSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+// The SDK release these commands call (positions, rhLighter, Lighter
+// liquidations) is stubbed here, so the suite checks exactly which SDK method
+// each command calls, with which arguments, and what it prints.
+const sdk = vi.hoisted(() => {
+  const positionsResource = () => ({
+    get: vi.fn(),
+    history: vi.fn(),
+    changes: vi.fn(),
+    market: vi.fn(),
+    marketSummary: vi.fn(),
+    all: vi.fn(),
+    account: vi.fn(),
+    accountHistory: vi.fn(),
+  });
+  const lighterVenue = () => ({
+    positions: positionsResource(),
+    liquidations: { history: vi.fn(), volume: vi.fn() },
+    trades: { list: vi.fn(), recent: vi.fn() },
+  });
+  const fresh = () => ({
+    hyperliquid: {
+      positions: positionsResource(),
+      liquidations: { history: vi.fn(), volume: vi.fn(), byUser: vi.fn() },
+      hip3: { positions: positionsResource() },
+    },
+    lighter: { ...lighterVenue(), accounts: { byL1: vi.fn() } } as Record<string, any>,
+    rhLighter: lighterVenue() as Record<string, any> | undefined,
+  });
+  const state = { clients: fresh(), apiKeys: [] as string[] };
+  return {
+    state,
+    reset() {
+      state.clients = fresh();
+      state.apiKeys = [];
+    },
+  };
+});
+
+vi.mock('@0xarchive/sdk', async (importOriginal) => {
+  const actual = await importOriginal<typeof import('@0xarchive/sdk')>();
+  class OxArchive {
+    constructor(options: { apiKey: string }) {
+      sdk.state.apiKeys.push(options.apiKey);
+    }
+    get hyperliquid() {
+      return sdk.state.clients.hyperliquid;
+    }
+    get lighter() {
+      return sdk.state.clients.lighter;
+    }
+    get rhLighter() {
+      return sdk.state.clients.rhLighter;
+    }
+  }
+  return { ...actual, OxArchive };
+});
+
+import {
+  accountGetCommand,
+  accountHistoryCommand,
+  accountsByL1Command,
+  positionsAllCommand,
+  positionsChangesCommand,
+  positionsGetCommand,
+  positionsHistoryCommand,
+  positionsMarketCommand,
+  positionsSummaryCommand,
+} from '../src/commands/positions.js';
+import { liquidationsCommand, liquidationsVolumeCommand, liquidationsUserCommand } from '../src/commands/liquidations.js';
+import { tradesFetchCommand } from '../src/commands/trades.js';
+import { ordersHistoryCommand } from '../src/commands/orders.js';
+import { l4GetCommand } from '../src/commands/l4.js';
+import { l2GetCommand } from '../src/commands/l2.js';
+import { validateExchange } from '../src/lib/client.js';
+import { toEnvelope } from '../src/lib/positions.js';
+
+class ProcessExit extends Error {
+  constructor(readonly code: number) {
+    super(`process.exit(${code})`);
+  }
+}
+
+const WALLET = '0x1111111111111111111111111111111111111111';
+const HOUR = Date.parse('2026-09-01T12:00:00Z');
+const START = '2026-09-01T00:00:00Z';
+const END = '2026-09-02T00:00:00Z';
+
+function stdoutJson(): any {
+  const calls = vi.mocked(process.stdout.write).mock.calls;
+  return JSON.parse(String(calls.at(-1)?.[0]));
+}
+
+function stdoutText(): string {
+  return vi
+    .mocked(process.stdout.write)
+    .mock.calls.map(([chunk]) => String(chunk))
+    .join('');
+}
+
+function lastError(): any {
+  const calls = vi.mocked(process.stderr.write).mock.calls;
+  return JSON.parse(String(calls.at(-1)?.[0]));
+}
+
+async function expectExit(run: () => Promise<void>, code: number, message: string | RegExp): Promise<void> {
+  await expect(run()).rejects.toMatchObject({ code });
+  const error = lastError().error;
+  if (typeof message === 'string') expect(error).toBe(message);
+  else expect(error).toMatch(message);
+}
+
+const WALLET_PAGE = {
+  data: {
+    positions: [
+      {
+        symbol: 'BTC',
+        coin: 'BTC',
+        size: '0.5',
+        side: 'long',
+        entryPrice: '60000.0',
+        markPrice: '61000.0',
+        positionValue: '30500.0',
+        unrealizedPnl: '500.0',
+        liquidationPrice: '41000.0',
+        quality: 'complete',
+      },
+    ],
+    account: { accountValue: '10000.0', nPositions: 1, quality: 'complete' },
+    accountSeen: 'flat',
+  },
+  nextCursor: undefined,
+  meta: { asOf: '2026-09-01T12:05:00.000Z', source: 'snapshot', quality: 'complete', stale: false },
+};
+
+describe('oxa positions', () => {
+  beforeEach(() => {
+    sdk.reset();
+    vi.stubEnv('OXA_API_KEY', 'test-key');
+    vi.spyOn(process.stdout, 'write').mockImplementation(() => true);
+    vi.spyOn(process.stderr, 'write').mockImplementation(() => true);
+    vi.spyOn(process, 'exit').mockImplementation(((code?: number) => {
+      if ((code ?? 0) === 0) return undefined as never;
+      throw new ProcessExit(code ?? 0);
+    }) as never);
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+    vi.unstubAllEnvs();
+  });
+
+  it('gets current Hyperliquid positions by wallet and prints data, cursor, and meta', async () => {
+    const get = sdk.state.clients.hyperliquid.positions.get;
+    get.mockResolvedValue(WALLET_PAGE);
+
+    await positionsGetCommand({ exchange: 'hyperliquid', address: WALLET, format: 'json' });
+
+    expect(get).toHaveBeenCalledWith(WALLET, {});
+    expect(stdoutJson()).toEqual({ data: WALLET_PAGE.data, nextCursor: null, meta: WALLET_PAGE.meta });
+    expect(sdk.state.apiKeys).toEqual(['test-key']);
+  });
+
+  it('passes an as-of timestamp, a symbol filter, and paging', async () => {
+    const get = sdk.state.clients.hyperliquid.positions.get;
+    get.mockResolvedValue(WALLET_PAGE);
+
+    await positionsGetCommand({
+      exchange: 'hyperliquid',
+      address: WALLET,
+      timestamp: '2026-08-01T00:00:00Z',
+      symbol: 'BTC',
+      limit: '5',
+      cursor: 'abc',
+      format: 'json',
+    });
+
+    expect(get).toHaveBeenCalledWith(WALLET, {
+      timestamp: Date.parse('2026-08-01T00:00:00Z'),
+      symbol: 'BTC',
+      cursor: 'abc',
+      limit: 5,
+    });
+  });
+
+  it('routes HIP-3 to the hip3 resource with a dex filter', async () => {
+    const get = sdk.state.clients.hyperliquid.hip3.positions.get;
+    get.mockResolvedValue(WALLET_PAGE);
+
+    await positionsGetCommand({ exchange: 'hip3', address: WALLET, dex: 'xyz', format: 'json' });
+
+    expect(get).toHaveBeenCalledWith(WALLET, { dex: 'xyz' });
+    expect(sdk.state.clients.hyperliquid.positions.get).not.toHaveBeenCalled();
+  });
+
+  it.each([
+    ['lighter', () => sdk.state.clients.lighter.positions.get],
+    ['rh-lighter', () => sdk.state.clients.rhLighter!.positions.get],
+  ])('keys %s positions by integer account index', async (exchange, method) => {
+    method().mockResolvedValue({ data: { positions: [], account: null }, meta: { source: 'snapshot' } });
+
+    await positionsGetCommand({ exchange, account: '281474976710654', format: 'json' });
+
+    expect(method()).toHaveBeenCalledWith(281474976710654, {});
+    expect(stdoutJson()).toEqual({
+      data: { positions: [], account: null },
+      nextCursor: null,
+      meta: { source: 'snapshot' },
+    });
+  });
+
+  it('renders a pretty table with the snapshot fields', async () => {
+    sdk.state.clients.hyperliquid.positions.get.mockResolvedValue(WALLET_PAGE);
+
+    await positionsGetCommand({ exchange: 'hyperliquid', address: WALLET, format: 'pretty' });
+
+    const out = stdoutText();
+    expect(out).toContain('Positions for 0x1111...1111 (Hyperliquid): 1 open');
+    expect(out).toContain('snapshot');
+    expect(out).toContain('41000.0');
+    expect(out).toContain('Account seen');
+  });
+
+  it('gets hourly history on Lighter on Robinhood Chain with range, symbol, cursor, and limit', async () => {
+    const history = sdk.state.clients.rhLighter!.positions.history;
+    history.mockResolvedValue({ data: [{ symbol: 'AAPL-USDG' }], nextCursor: 'c2', meta: { finalizedThrough: 'x' } });
+
+    await positionsHistoryCommand({
+      exchange: 'rh-lighter',
+      account: '42',
+      start: START,
+      end: END,
+      symbol: 'AAPL-USDG',
+      cursor: 'c1',
+      limit: '100',
+      format: 'json',
+    });
+
+    expect(history).toHaveBeenCalledWith(42, {
+      start: Date.parse(START),
+      end: Date.parse(END),
+      symbol: 'AAPL-USDG',
+      cursor: 'c1',
+      limit: 100,
+    });
+    expect(stdoutJson()).toEqual({
+      data: [{ symbol: 'AAPL-USDG' }],
+      nextCursor: 'c2',
+      meta: { finalizedThrough: 'x' },
+    });
+  });
+
+  it('gets the change log on HIP-3', async () => {
+    const changes = sdk.state.clients.hyperliquid.hip3.positions.changes;
+    changes.mockResolvedValue({ data: [], nextCursor: undefined });
+
+    await positionsChangesCommand({ exchange: 'hip3', address: WALLET, start: START, end: END, format: 'json' });
+
+    expect(changes).toHaveBeenCalledWith(WALLET, { start: Date.parse(START), end: Date.parse(END) });
+    expect(stdoutJson()).toEqual({ data: [], nextCursor: null });
+  });
+
+  it('lists one market with every filter on Lighter', async () => {
+    const market = sdk.state.clients.lighter.positions.market;
+    market.mockResolvedValue({
+      data: [{ accountIndex: '7', side: 'long', size: '1.0', positionValue: '100.0' }],
+      nextCursor: 'next',
+      meta: { snapshotTs: '2026-09-01T12:00:00Z', totals: { longCount: 1, shortCount: 0 } },
+    });
+
+    await positionsMarketCommand({
+      exchange: 'lighter',
+      symbol: 'ETH',
+      hour: '2026-09-01T12:00:00Z',
+      side: 'LONG',
+      minValue: '1000',
+      includeSystem: true,
+      limit: '50',
+      format: 'json',
+    });
+
+    expect(market).toHaveBeenCalledWith('ETH', {
+      hour: HOUR,
+      side: 'long',
+      minValue: 1000,
+      includeSystem: true,
+      limit: 50,
+    });
+    expect(stdoutJson().meta.totals).toEqual({ longCount: 1, shortCount: 0 });
+  });
+
+  it('summarizes a market now, or as an hourly series', async () => {
+    const summary = sdk.state.clients.hyperliquid.positions.marketSummary;
+    summary.mockResolvedValue({ data: [{ longCount: 3 }] });
+
+    await positionsSummaryCommand({ exchange: 'hyperliquid', symbol: 'BTC', format: 'json' });
+    expect(summary).toHaveBeenLastCalledWith('BTC', {});
+
+    await positionsSummaryCommand({ exchange: 'hyperliquid', symbol: 'BTC', start: START, end: END, format: 'json' });
+    expect(summary).toHaveBeenLastCalledWith('BTC', { start: Date.parse(START), end: Date.parse(END) });
+  });
+
+  it('pages a Lighter summary series with system accounts included', async () => {
+    const summary = sdk.state.clients.lighter.positions.marketSummary;
+    summary.mockResolvedValue({ data: [], nextCursor: 'p2' });
+
+    await positionsSummaryCommand({
+      exchange: 'lighter',
+      symbol: 'ETH',
+      start: START,
+      end: END,
+      includeSystem: true,
+      limit: '48',
+      cursor: 'p1',
+      format: 'json',
+    });
+
+    expect(summary).toHaveBeenCalledWith('ETH', {
+      start: Date.parse(START),
+      end: Date.parse(END),
+      includeSystem: true,
+      cursor: 'p1',
+      limit: 48,
+    });
+    expect(stdoutJson()).toEqual({ data: [], nextCursor: 'p2' });
+  });
+
+  it('pages every open position at one hour', async () => {
+    const all = sdk.state.clients.rhLighter!.positions.all;
+    all.mockResolvedValue({ data: [], nextCursor: 'more' });
+
+    await positionsAllCommand({
+      exchange: 'rh-lighter',
+      hour: String(HOUR),
+      includeSystem: true,
+      limit: '2000',
+      format: 'json',
+    });
+
+    expect(all).toHaveBeenCalledWith({ hour: HOUR, includeSystem: true, limit: 2000 });
+    expect(stdoutJson()).toEqual({ data: [], nextCursor: 'more' });
+  });
+
+  it('gets account summaries and account history on HIP-3', async () => {
+    const { account, accountHistory } = sdk.state.clients.hyperliquid.hip3.positions;
+    account.mockResolvedValue({ data: [{ dex: 'xyz', accountValue: '5.0' }] });
+    accountHistory.mockResolvedValue({ data: [], nextCursor: undefined });
+
+    await accountGetCommand({ exchange: 'hip3', address: WALLET, dex: 'xyz', format: 'json' });
+    expect(account).toHaveBeenCalledWith(WALLET, { dex: 'xyz' });
+
+    await accountHistoryCommand({
+      exchange: 'hip3',
+      address: WALLET,
+      start: START,
+      end: END,
+      dex: 'xyz',
+      limit: '10',
+      format: 'json',
+    });
+    expect(accountHistory).toHaveBeenCalledWith(WALLET, {
+      start: Date.parse(START),
+      end: Date.parse(END),
+      dex: 'xyz',
+      limit: 10,
+    });
+  });
+
+  it('resolves Lighter mainnet accounts by L1 address', async () => {
+    const byL1 = sdk.state.clients.lighter.accounts.byL1;
+    const data = { l1Address: WALLET, totalAccounts: 2, accounts: [{ accountIndex: '1' }, { accountIndex: '9' }] };
+    byL1.mockResolvedValue({ data, nextCursor: undefined });
+
+    await accountsByL1Command({ exchange: 'lighter', l1Address: WALLET, limit: '10', format: 'json' });
+
+    expect(byL1).toHaveBeenCalledWith(WALLET, { limit: 10 });
+    expect(stdoutJson()).toEqual({ data, nextCursor: null });
+  });
+
+  it('writes the page to --out and prints a summary', async () => {
+    const dir = mkdtempSync(join(tmpdir(), 'oxa-positions-'));
+    try {
+      const out = join(dir, 'positions.json');
+      sdk.state.clients.hyperliquid.positions.get.mockResolvedValue(WALLET_PAGE);
+
+      await positionsGetCommand({ exchange: 'hyperliquid', address: WALLET, out, format: 'json' });
+
+      expect(JSON.parse(readFileSync(out, 'utf8'))).toEqual({
+        data: WALLET_PAGE.data,
+        nextCursor: null,
+        meta: WALLET_PAGE.meta,
+      });
+      expect(stdoutJson()).toEqual({
+        written_to: out,
+        records: 1,
+        exchange: 'hyperliquid',
+        has_more: false,
+        nextCursor: null,
+      });
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  describe('validation before any request', () => {
+    afterEach(() => {
+      for (const venue of [
+        sdk.state.clients.hyperliquid.positions,
+        sdk.state.clients.hyperliquid.hip3.positions,
+        sdk.state.clients.lighter.positions,
+        sdk.state.clients.rhLighter!.positions,
+      ]) {
+        for (const method of Object.values(venue)) expect(method).not.toHaveBeenCalled();
+      }
+    });
+
+    it('rejects HIP-4', () =>
+      expectExit(
+        () => positionsGetCommand({ exchange: 'hip4', address: WALLET, format: 'json' }),
+        2,
+        'Hyperliquid HIP-4 has no account positions endpoint. Use --exchange hyperliquid, hip3, lighter, or rh-lighter.',
+      ));
+
+    it('asks for an account index on Lighter and points to the L1 lookup', () =>
+      expectExit(
+        () => positionsGetCommand({ exchange: 'lighter', address: WALLET, format: 'json' }),
+        2,
+        'Lighter positions are keyed by account index. Pass --account <index>. ' +
+          'Find the account indices behind an L1 address with `oxa accounts by-l1 --l1-address 0x...`.',
+      ));
+
+    it('asks for an account index on Robinhood Chain without the mainnet-only lookup', () =>
+      expectExit(
+        () => positionsGetCommand({ exchange: 'rh-lighter', format: 'json' }),
+        2,
+        'Lighter on Robinhood Chain positions are keyed by account index. Pass --account <index>.',
+      ));
+
+    it('asks for a wallet address on Hyperliquid', () =>
+      expectExit(
+        () => positionsGetCommand({ exchange: 'hyperliquid', account: '5', format: 'json' }),
+        2,
+        'Hyperliquid positions are keyed by wallet address. Pass --address 0x...',
+      ));
+
+    it.each(['0x12', 'abc', `${WALLET}0`])('rejects the address %s', (address) =>
+      expectExit(
+        () => positionsGetCommand({ exchange: 'hyperliquid', address, format: 'json' }),
+        2,
+        '--address must be a 0x-prefixed wallet address with 40 hex characters.',
+      ));
+
+    it.each(['-1', '1.5', 'abc', '99999999999999999999'])('rejects the account index %s', (account) =>
+      expectExit(
+        () => positionsGetCommand({ exchange: 'lighter', account, format: 'json' }),
+        2,
+        '--account must be a Lighter account index (a non-negative integer).',
+      ));
+
+    it('rejects --dex outside HIP-3', () =>
+      expectExit(
+        () => positionsGetCommand({ exchange: 'hyperliquid', address: WALLET, dex: 'xyz', format: 'json' }),
+        2,
+        '--dex applies to --exchange hip3 only.',
+      ));
+
+    it('rejects --include-system outside Lighter', async () => {
+      await expectExit(
+        () => positionsMarketCommand({ exchange: 'hip3', symbol: 'xyz:TSLA', includeSystem: true, format: 'json' }),
+        2,
+        '--include-system applies to --exchange lighter and rh-lighter only.',
+      );
+      await expectExit(
+        () => positionsAllCommand({ exchange: 'hyperliquid', hour: String(HOUR), includeSystem: true, format: 'json' }),
+        2,
+        '--include-system applies to --exchange lighter and rh-lighter only.',
+      );
+      await expectExit(
+        () => positionsSummaryCommand({ exchange: 'hyperliquid', symbol: 'BTC', includeSystem: true, format: 'json' }),
+        2,
+        '--include-system applies to --exchange lighter and rh-lighter only.',
+      );
+    });
+
+    it('rejects an --hour that is not an exact hour', () =>
+      expectExit(
+        () => positionsAllCommand({ exchange: 'lighter', hour: '2026-09-01T12:30:00Z', format: 'json' }),
+        2,
+        /^--hour must be an exact UTC hour/,
+      ));
+
+    it('rejects a bad --side and --min-value', async () => {
+      await expectExit(
+        () => positionsMarketCommand({ exchange: 'lighter', symbol: 'ETH', side: 'up', format: 'json' }),
+        2,
+        '--side must be long or short.',
+      );
+      await expectExit(
+        () => positionsMarketCommand({ exchange: 'lighter', symbol: 'ETH', minValue: '-5', format: 'json' }),
+        2,
+        '--min-value must be a non-negative number (USD).',
+      );
+    });
+
+    it('needs both ends of a summary series', () =>
+      expectExit(
+        () => positionsSummaryCommand({ exchange: 'lighter', symbol: 'ETH', start: START, format: 'json' }),
+        2,
+        'Pass both --start and --end for an hourly series, or neither for the latest snapshot.',
+      ));
+
+    it('keeps account summaries to Hyperliquid and HIP-3', () =>
+      expectExit(
+        () => accountGetCommand({ exchange: 'rh-lighter', address: WALLET, format: 'json' }),
+        2,
+        /^Account summaries are available for --exchange hyperliquid or hip3\./,
+      ));
+
+    it('keeps the L1 lookup to Lighter mainnet', async () => {
+      await expectExit(
+        () => accountsByL1Command({ exchange: 'rh-lighter', l1Address: WALLET, format: 'json' }),
+        2,
+        'Account lookup by L1 address is available for Lighter mainnet only (--exchange lighter).',
+      );
+      expect(sdk.state.clients.lighter.accounts.byL1).not.toHaveBeenCalled();
+    });
+  });
+
+  it('explains an SDK install older than the floor instead of crashing', async () => {
+    sdk.state.clients.rhLighter = undefined;
+    await expectExit(
+      () => positionsGetCommand({ exchange: 'rh-lighter', account: '1', format: 'json' }),
+      5,
+      'Support for Lighter on Robinhood Chain (--exchange rh-lighter) requires @0xarchive/sdk 1.12.0 or newer. ' +
+        'Reinstall @0xarchive/cli to pick it up.',
+    );
+  });
+});
+
+describe('toEnvelope', () => {
+  it('keeps data, cursor, and meta from a page', () => {
+    expect(toEnvelope({ data: [1], nextCursor: 'c', meta: { quality: 'complete' } })).toEqual({
+      data: [1],
+      nextCursor: 'c',
+      meta: { quality: 'complete' },
+    });
+  });
+
+  it('reads the cursor from meta when the page does not lift it', () => {
+    expect(toEnvelope({ data: [], meta: { nextCursor: 'm' } })).toEqual({
+      data: [],
+      nextCursor: 'm',
+      meta: { nextCursor: 'm' },
+    });
+  });
+
+  it('wraps a bare result', () => {
+    expect(toEnvelope([1, 2])).toEqual({ data: [1, 2], nextCursor: null });
+    expect(toEnvelope({ positions: [], account: null, meta: { stale: true } })).toEqual({
+      data: { positions: [], account: null },
+      nextCursor: null,
+      meta: { stale: true },
+    });
+  });
+});
+
+describe('Lighter deployments on the shared verbs', () => {
+  beforeEach(() => {
+    sdk.reset();
+    vi.stubEnv('OXA_API_KEY', 'test-key');
+    vi.spyOn(process.stdout, 'write').mockImplementation(() => true);
+    vi.spyOn(process.stderr, 'write').mockImplementation(() => true);
+    vi.spyOn(process, 'exit').mockImplementation(((code?: number) => {
+      if ((code ?? 0) === 0) return undefined as never;
+      throw new ProcessExit(code ?? 0);
+    }) as never);
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+    vi.unstubAllEnvs();
+  });
+
+  it('accepts rh-lighter as an exchange', () => {
+    expect(validateExchange('rh-lighter')).toBe('rh-lighter');
+  });
+
+  it.each([
+    ['lighter', () => sdk.state.clients.lighter.liquidations],
+    ['rh-lighter', () => sdk.state.clients.rhLighter!.liquidations],
+  ])('serves liquidation history and volume on %s', async (exchange, resource) => {
+    const rows = [{ symbol: 'BTC', timestamp: 1790294171459, liquidationType: 'partial', source: 'bucket', rawJson: '' }];
+    resource().history.mockResolvedValue({ data: rows, nextCursor: 'n1' });
+    resource().volume.mockResolvedValue({ data: [{ timestamp: 1790294100000, totalUsd: 12.5, count: 2 }] });
+
+    await liquidationsCommand({ exchange, symbol: 'BTC', start: START, end: END, limit: '5', format: 'json' });
+    expect(resource().history).toHaveBeenCalledWith('BTC', {
+      start: Date.parse(START),
+      end: Date.parse(END),
+      limit: 5,
+      cursor: undefined,
+    });
+    expect(stdoutJson()).toEqual({ data: rows, nextCursor: 'n1' });
+
+    await liquidationsVolumeCommand({ exchange, symbol: 'BTC', start: START, end: END, interval: '1h', format: 'pretty' });
+    expect(resource().volume).toHaveBeenCalledWith('BTC', {
+      start: Date.parse(START),
+      end: Date.parse(END),
+      interval: '1h',
+      limit: undefined,
+      cursor: undefined,
+    });
+    expect(stdoutText()).toContain('Count');
+  });
+
+  it('keeps liquidations by user to Hyperliquid', () =>
+    expectExit(
+      () =>
+        liquidationsUserCommand({ exchange: 'rh-lighter', user: WALLET, start: START, end: END, format: 'json' }),
+      2,
+      'Liquidations by user is only available for --exchange hyperliquid.',
+    ));
+
+  it('still rejects HIP-4 liquidations', () =>
+    expectExit(
+      () => liquidationsCommand({ exchange: 'hip4', symbol: '0', start: START, end: END, format: 'json' }),
+      2,
+      'HIP-4 has no liquidations endpoint. Use --exchange hyperliquid, hip3, lighter, or rh-lighter.',
+    ));
+
+  it('fetches Robinhood Chain trades: recent tier without a range, canonical tier with one', async () => {
+    const trades = sdk.state.clients.rhLighter!.trades;
+    trades.recent.mockResolvedValue([]);
+    trades.list.mockResolvedValue({
+      data: [],
+      nextCursor: undefined,
+      meta: { finalizedThrough: '2026-09-25T00:00:00Z', clampedTo: '2026-09-25T00:00:00Z' },
+    });
+
+    await tradesFetchCommand({ exchange: 'rh-lighter', symbol: 'AAPL-USDG', format: 'json' });
+    expect(trades.recent).toHaveBeenCalledWith('AAPL-USDG', 100);
+
+    await tradesFetchCommand({ exchange: 'rh-lighter', symbol: 'BTC', start: START, end: END, format: 'json' });
+    expect(trades.list).toHaveBeenCalledWith('BTC', {
+      start: Date.parse(START),
+      end: Date.parse(END),
+      limit: undefined,
+      cursor: undefined,
+    });
+    expect(stdoutJson()).toEqual({
+      data: [],
+      nextCursor: null,
+      meta: { finalizedThrough: '2026-09-25T00:00:00Z', clampedTo: '2026-09-25T00:00:00Z' },
+    });
+  });
+
+  it.each([
+    [() => ordersHistoryCommand({ exchange: 'rh-lighter', symbol: 'BTC', start: START, end: END, format: 'json' }),
+      'Lighter on Robinhood Chain has no order history endpoint. Use --exchange hyperliquid, hip3, or hip4.'],
+    [() => l4GetCommand({ exchange: 'lighter', symbol: 'BTC', format: 'json' }),
+      'Lighter has no L4 order book endpoint. Use --exchange hyperliquid, hip3, or hip4.'],
+    [() => l2GetCommand({ exchange: 'rh-lighter', symbol: 'BTC', format: 'json' }),
+      'Lighter on Robinhood Chain has no derived L2 order book endpoint. Use --exchange hyperliquid or hip3.'],
+  ])('rejects order-level routes on Lighter deployments (%#)', (run, message) => expectExit(run, 2, message));
+});
diff --git a/tests/release.test.ts b/tests/release.test.ts
new file mode 100644
index 0000000..196c57a
--- /dev/null
+++ b/tests/release.test.ts
@@ -0,0 +1,31 @@
+import { readFileSync } from 'node:fs';
+import { describe, expect, it } from 'vitest';
+import { SDK_FLOOR, VALID_EXCHANGES } from '../src/lib/client.js';
+
+const pkg = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
+const changelog = readFileSync(new URL('../CHANGELOG.md', import.meta.url), 'utf8');
+const readme = readFileSync(new URL('../README.md', import.meta.url), 'utf8');
+
+describe('release metadata', () => {
+  it('pins the SDK floor the commands check for', () => {
+    expect(pkg.dependencies['@0xarchive/sdk']).toBe(`^${SDK_FLOOR}`);
+  });
+
+  it('opens the changelog with the package version', () => {
+    expect(changelog.match(/^## (\d+\.\d+\.\d+)/m)?.[1]).toBe(pkg.version);
+  });
+
+  it('ships only the allowlisted paths', () => {
+    expect(pkg.files).toEqual(['dist', 'README.md']);
+  });
+
+  it('documents every --exchange value in the venue scopes', () => {
+    for (const exchange of VALID_EXCHANGES) {
+      expect(readme).toContain(`--exchange ${exchange}`);
+    }
+  });
+
+  it('presents Robinhood Chain as a Lighter deployment', () => {
+    expect(readme).toContain('Lighter has two deployments: mainnet and Robinhood Chain.');
+  });
+});
diff --git a/tests/stream.test.ts b/tests/stream.test.ts
index 64ead45..058c5b7 100644
--- a/tests/stream.test.ts
+++ b/tests/stream.test.ts
@@ -103,9 +103,12 @@ describe('oxa stream channel resolution', () => {
     ['trades', 'lighter', 'lighter_trades'],
     ['trades', 'Lighter', 'lighter_trades'],
     ['trades', 'spot', 'spot_trades'],
+    ['trades', 'rh-lighter', 'rh_lighter_trades'],
+    ['trades', 'RH-Lighter', 'rh_lighter_trades'],
     ['orderbook', undefined, 'orderbook'],
     ['orderbook', 'hip3', 'hip3_orderbook'],
     ['orderbook', 'lighter', 'lighter_orderbook'],
+    ['orderbook', 'rh-lighter', 'rh_lighter_orderbook'],
     ['orderbook', 'spot', 'spot_orderbook'],
     ['liquidations', undefined, 'liquidations'],
     ['liquidations', 'hip3', 'hip3_liquidations'],
@@ -114,10 +117,11 @@ describe('oxa stream channel resolution', () => {
   });
 
   it.each([
-    ['trades', 'hip4', 'hyperliquid, hip3, lighter, spot'],
-    ['orderbook', 'rh-lighter', 'hyperliquid, hip3, lighter, spot'],
-    ['orderbook', 'constructor', 'hyperliquid, hip3, lighter, spot'],
+    ['trades', 'hip4', 'hyperliquid, hip3, lighter, rh-lighter, spot'],
+    ['orderbook', 'rh_lighter', 'hyperliquid, hip3, lighter, rh-lighter, spot'],
+    ['orderbook', 'constructor', 'hyperliquid, hip3, lighter, rh-lighter, spot'],
     ['liquidations', 'lighter', 'hyperliquid, hip3'],
+    ['liquidations', 'rh-lighter', 'hyperliquid, hip3'],
     ['liquidations', 'toString', 'hyperliquid, hip3'],
   ])('rejects `oxa stream %s --exchange %s` instead of streaming another venue', (verb, exchange, valid) => {
     expect(() => resolveChannel(verb, exchange)).toThrow(ProcessExit);
@@ -175,18 +179,50 @@ describe('lighter_orderbook --interval-ms', () => {
     });
   });
 
-  it.each(['orderbook', 'lighter_trades', 'lighter_funding', 'spot_orderbook'])(
+  it.each(['orderbook', 'lighter_trades', 'lighter_funding', 'spot_orderbook', 'rh_lighter_trades', 'rh_lighter_funding'])(
     'is refused on %s',
     (channel) => {
       expect(() => parseIntervalMs('250', channel)).toThrow(ProcessExit);
-      expect(stderrPayloads().at(-1)?.error).toMatch(/^--interval-ms is only supported on lighter_orderbook/);
+      expect(stderrPayloads().at(-1)?.error).toMatch(
+        /^--interval-ms is only supported on lighter_orderbook and rh_lighter_orderbook/,
+      );
     },
   );
+
+  it.each([
+    ['100', 100],
+    ['5000', 5000],
+  ])('accepts %s on rh_lighter_orderbook', (raw, expected) => {
+    expect(parseIntervalMs(raw, 'rh_lighter_orderbook')).toBe(expected);
+    expect(buildSubscribeMessage('rh_lighter_orderbook', 'AAPL-USDG', expected)).toEqual({
+      op: 'subscribe',
+      channel: 'rh_lighter_orderbook',
+      symbol: 'AAPL-USDG',
+      interval_ms: expected,
+    });
+  });
+
+  it('names the Robinhood Chain book channel in the range error', () => {
+    expect(() => parseIntervalMs('99', 'rh_lighter_orderbook')).toThrow(ProcessExit);
+    expect(stderrPayloads().at(-1)?.error).toBe(
+      '--interval-ms must be a whole number between 100 and 5000 for rh_lighter_orderbook (got 99). ' +
+        'Leave it out for one book a second.',
+    );
+  });
 });
 
 describe('Lighter drop notices', () => {
-  it('matches a drop notice on any Lighter live channel', () => {
-    for (const channel of ['lighter_orderbook', 'lighter_trades', 'lighter_open_interest', 'lighter_funding']) {
+  it('matches a drop notice on any Lighter live channel, on either deployment', () => {
+    for (const channel of [
+      'lighter_orderbook',
+      'lighter_trades',
+      'lighter_open_interest',
+      'lighter_funding',
+      'rh_lighter_orderbook',
+      'rh_lighter_trades',
+      'rh_lighter_open_interest',
+      'rh_lighter_funding',
+    ]) {
       expect(isLighterDropNotice(channel, `Dropped ~3 live ${channel} messages for BTC: ...`)).toBe(true);
     }
   });
@@ -257,7 +293,16 @@ describe('oxa stream over a WebSocket', () => {
     expect(JSON.parse(ws.sent[0])).toEqual({ op: 'subscribe', channel: 'lighter_trades', symbol: 'ETH' });
   });
 
-  it.each(['lighter_orderbook', 'lighter_trades', 'lighter_open_interest', 'lighter_funding'])(
+  it.each([
+    'lighter_orderbook',
+    'lighter_trades',
+    'lighter_open_interest',
+    'lighter_funding',
+    'rh_lighter_orderbook',
+    'rh_lighter_trades',
+    'rh_lighter_open_interest',
+    'rh_lighter_funding',
+  ])(
     'forwards the live Lighter channel %s through `oxa stream subscribe`',
     async (channel) => {
       await streamGenericCommand(channel.toUpperCase(), 'BTC', { format: 'json' });
@@ -379,8 +424,9 @@ describe('oxa stream over a WebSocket', () => {
   it('rejects --interval-ms on a non-Lighter orderbook before opening a socket', async () => {
     await expectValidationExit(
       () => streamOrderbookCommand('BTC', { intervalMs: '250', format: 'json' }),
-      '--interval-ms is only supported on lighter_orderbook ' +
-        '(`oxa stream orderbook <symbol> --exchange lighter` or `oxa stream subscribe lighter_orderbook <symbol>`).',
+      '--interval-ms is only supported on lighter_orderbook and rh_lighter_orderbook ' +
+        '(`oxa stream orderbook <symbol> --exchange lighter|rh-lighter` or ' +
+        '`oxa stream subscribe lighter_orderbook|rh_lighter_orderbook <symbol>`).',
     );
   });
 
@@ -429,11 +475,42 @@ describe('oxa stream over a WebSocket', () => {
     );
   });
 
-  it('does not accept rh_lighter channels as live streams', async () => {
-    await expect(
-      Promise.resolve().then(() => streamGenericCommand('rh_lighter_orderbook', 'BTC', { format: 'json' })),
-    ).rejects.toMatchObject({ code: 2 });
-    expect(stderrPayloads().at(-1)?.error).toMatch(/^Unknown stream channel "rh_lighter_orderbook"/);
-    expect(FakeWebSocket.instances).toHaveLength(0);
+  it('subscribes to rh_lighter_orderbook with interval_ms on the default endpoint', async () => {
+    await streamOrderbookCommand('AAPL-USDG', { exchange: 'rh-lighter', intervalMs: '500', format: 'json' });
+    const ws = FakeWebSocket.instances[0];
+    expect(ws.url).toBe('wss://api.0xarchive.io/ws?apiKey=test-key');
+    ws.fire('open');
+    expect(ws.sent.map((frame) => JSON.parse(frame))).toEqual([
+      { op: 'subscribe', channel: 'rh_lighter_orderbook', symbol: 'AAPL-USDG', interval_ms: 500 },
+    ]);
+    const frame = { type: 'data', channel: 'rh_lighter_orderbook', coin: 'BTC', symbol: 'BTC', data: LIGHTER_BOOK };
+    ws.message(frame);
+    expect(stdoutLines()).toEqual([JSON.stringify(frame) + '\n']);
+  });
+
+  it('subscribes to rh_lighter_trades without an interval', async () => {
+    await streamTradesCommand('BTC', { exchange: 'rh-lighter', format: 'json' });
+    const ws = FakeWebSocket.instances[0];
+    ws.fire('open');
+    expect(JSON.parse(ws.sent[0])).toEqual({ op: 'subscribe', channel: 'rh_lighter_trades', symbol: 'BTC' });
+  });
+
+  it('keeps streaming after a Robinhood Chain drop notice', async () => {
+    await streamTradesCommand('BTC', { exchange: 'rh-lighter', format: 'json' });
+    const ws = FakeWebSocket.instances[0];
+    ws.fire('open');
+    const message =
+      'Dropped ~4 live rh_lighter_trades messages for BTC: your connection fell behind the Lighter (Robinhood Chain) ' +
+      'stream, and those trades were not delivered.';
+    expect(() => ws.message({ type: 'error', message })).not.toThrow();
+    expect(process.exit).not.toHaveBeenCalled();
+    expect(stderrPayloads().at(-1)).toEqual({ warning: `stream warning: ${message}`, type: 'lag' });
+  });
+
+  it('rejects live liquidations for Lighter on Robinhood Chain before opening a socket', async () => {
+    await expectValidationExit(
+      () => streamLiquidationsCommand('BTC', { exchange: 'rh-lighter', format: 'json' }),
+      'Invalid exchange "rh-lighter" for `oxa stream liquidations`. Must be one of: hyperliquid, hip3.',
+    );
   });
 });

From 79dd370e1326ebee3a05cb0b69ad99ab18d58f2b Mon Sep 17 00:00:00 2001
From: 0xFantomMenace <93462858+0xFantomMenace@users.noreply.github.com>
Date: Sat, 26 Sep 2026 05:24:18 +0000
Subject: [PATCH 2/5] Review fixes: Robinhood Chain liquidations floor, trades
 meta scope, README table

- Robinhood Chain liquidations are served from 2026-08-22 18:43 UTC, like
  the order book, OI, and funding. The README venue table, the liquidations
  intro, and the CHANGELOG said 2026-06-26 20:10:26 UTC, which the API refuses.
- oxa trades fetch passes the response meta through on Lighter ranges only,
  so Hyperliquid and HIP-3 trades JSON is unchanged. Test added.
- The oxa positions market README row broke on GitHub at a pipe inside a
  code span; the side filter is now written out.
- positions changes help and README copy: the change log lists every fill
  leg, including Lighter legs that leave the size unchanged.
---
 CHANGELOG.md            |  4 ++--
 README.md               |  8 ++++----
 src/cli.ts              |  2 +-
 src/commands/trades.ts  |  8 +++++---
 tests/positions.test.ts | 19 +++++++++++++++++++
 5 files changed, 31 insertions(+), 10 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 8ac2799..e4e02e3 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -4,7 +4,7 @@
 
 ### Added
 
-- Lighter on Robinhood Chain, the second Lighter deployment, as `--exchange rh-lighter` on every shared market-data command that Lighter mainnet supports: instruments, order book and order book history, trades (canonical range and preliminary recent tier), candles, funding, open interest, liquidations, prices, summary, freshness, and `auth test`. It is USDG-quoted with 84 markets (57 perp, 27 spot); perps are uppercase (`BTC`) and spot markets are dashed (`AAPL-USDG`). Trades and liquidations are served from 2026-06-26 20:10:26 UTC; order book, open interest, and funding from 2026-08-22 18:43 UTC; candles from 2026-06-26 once they are enabled for this deployment. It has no L3.
+- Lighter on Robinhood Chain, the second Lighter deployment, as `--exchange rh-lighter` on every shared market-data command that Lighter mainnet supports: instruments, order book and order book history, trades (canonical range and preliminary recent tier), candles, funding, open interest, liquidations, prices, summary, freshness, and `auth test`. It is USDG-quoted with 84 markets (57 perp, 27 spot); perps are uppercase (`BTC`) and spot markets are dashed (`AAPL-USDG`). Trades are served from 2026-06-26 20:10:26 UTC; liquidations, order book, open interest, and funding from 2026-08-22 18:43 UTC; candles from 2026-06-26 once they are enabled for this deployment. It has no L3.
 - Live Robinhood Chain streams: `oxa stream orderbook <symbol> --exchange rh-lighter` and `oxa stream trades <symbol> --exchange rh-lighter`, and `oxa stream subscribe` accepts `rh_lighter_orderbook`, `rh_lighter_trades`, `rh_lighter_open_interest`, and `rh_lighter_funding`. Messages have the same shapes as the `lighter_*` live channels, `--interval-ms` (100 to 5000) works on `rh_lighter_orderbook`, and drop notices on `rh_lighter_*` channels are warnings, as on Lighter mainnet. They are served on `wss://api.0xarchive.io/ws`, the CLI default. `rh_lighter_candles` is replay-only and is rejected before a socket opens.
 - Account positions, `oxa positions ...`, on `hyperliquid`, `hip3`, `lighter`, and `rh-lighter`: `get` (latest snapshot, or as of `--timestamp`), `history` (hourly snapshots), `changes` (the change log), `market` (every open position in one market, with `--side`, `--min-value`, and `--include-system` on Lighter), `summary` (long/short positioning now or hourly), and `all` (every open position at one hour). Hyperliquid and HIP-3 add `account` and `account-history`. Hyperliquid and HIP-3 are keyed by `--address`; Lighter by `--account <index>`. JSON output includes the response `meta` (as-of time, snapshot, source, quality, staleness, and finalization fields).
 - `oxa accounts by-l1 --l1-address 0x...` lists the Lighter mainnet account indices owned by an L1 address.
@@ -13,7 +13,7 @@
 ### Changed
 
 - `oxa liquidations history` and `oxa liquidations volume` accept `--exchange lighter` and `--exchange rh-lighter`; they were previously refused. Lighter rows keep the trade's raw fields (`liquidationType`, `usdAmount`, both accounts, `rawJson`), and Lighter volume buckets carry a total and a count with no long/short split. `oxa liquidations user` stays Hyperliquid only.
-- On Lighter ranges, `oxa trades fetch` passes the finalization meta through (`meta.finalizedThrough`, and `meta.clampedTo` when the range was clamped to the watermark) when the SDK returns it.
+- On Lighter ranges (both deployments), `oxa trades fetch` passes the response `meta` through, including the finalization fields (`meta.finalizedThrough`, and `meta.clampedTo` when the range was clamped to the watermark). Hyperliquid and HIP-3 trades output is unchanged.
 - `oxa orders ...`, `oxa l4 ...`, and `oxa l2 ...` reject `--exchange lighter` and `--exchange rh-lighter` with a clear message before any request, instead of failing inside the command.
 - The HIP-4 funding and liquidations refusals now list every exchange that serves those routes.
 - Requires `@0xarchive/sdk` 1.12.0 or newer, the release with the Robinhood Chain client, the positions resources, and Lighter liquidations.
diff --git a/README.md b/README.md
index 838b2d8..fb7ca41 100644
--- a/README.md
+++ b/README.md
@@ -81,7 +81,7 @@ oxa stream orderbook BTC --exchange lighter --duration-ms 10000
 | --- | --- | --- |
 | Hyperliquid | `--exchange hyperliquid` | `BTC`, `ETH`, `SOL`, etc. |
 | Lighter (mainnet) | `--exchange lighter` | `BTC`, `ETH`, etc. |
-| Lighter on Robinhood Chain | `--exchange rh-lighter` | USDG-quoted. Perps are uppercase (`BTC`, `ETH`); spot markets are dashed (`AAPL-USDG`). 84 markets: 57 perp, 27 spot. Trades and liquidations from 2026-06-26 20:10:26 UTC (venue launch); order book, OI, and funding from 2026-08-22 18:43 UTC; candles from 2026-06-26 once they are enabled for this deployment. No L3. |
+| Lighter on Robinhood Chain | `--exchange rh-lighter` | USDG-quoted. Perps are uppercase (`BTC`, `ETH`); spot markets are dashed (`AAPL-USDG`). 84 markets: 57 perp, 27 spot. Trades from 2026-06-26 20:10:26 UTC (venue launch); liquidations, order book, OI, and funding from 2026-08-22 18:43 UTC; candles from 2026-06-26 once they are enabled for this deployment. No L3. |
 | Hyperliquid HIP-3 | `--exchange hip3` | `km:US500`, `xyz:XYZ100`, etc. Case-sensitive. |
 | Hyperliquid HIP-4 | `--exchange hip4` or `oxa hip4 ...` | Bare numerics: `0`, `1`, `42`. Legacy `#0` / `%230` forms still work. `mark_price` is implied probability (0..1), not USD. Per-side OI is available from 2026-05-02 at ~10s cadence; candles are available. No funding or liquidations. |
 | Hyperliquid Spot | `oxa spot ...` | Dashed canonical: `HYPE-USDC`, `PURR-USDC`. 326 pairs. Spot candles from 2025-03-22T10:50:22Z at `1m`/`5m`/`15m`/`30m`/`1h`/`4h`/`1d`/`1w`, max 1000 rows; trades from 2025-03-22; orderbook, L4, TWAP live from 2026-05-05. No funding, OI, or liquidations. |
@@ -256,7 +256,7 @@ oxa instruments --exchange <exchange> [--format <format>]
 
 ### `oxa liquidations history`
 
-Get liquidation history for Hyperliquid, HIP-3, and both Lighter deployments. Lighter mainnet liquidations are served from 2026-06-10 and Lighter on Robinhood Chain liquidations from 2026-06-26 20:10:26 UTC.
+Get liquidation history for Hyperliquid, HIP-3, and both Lighter deployments. Lighter mainnet liquidations are served from 2026-06-10 and Lighter on Robinhood Chain liquidations from 2026-08-22 18:43 UTC.
 
 ```bash
 oxa liquidations history --exchange <exchange> --symbol <symbol> --start <time> --end <time> [options]
@@ -387,8 +387,8 @@ oxa positions account-history --exchange hyperliquid --address 0xYourWallet --st
 |---|---|---|
 | `oxa positions get` | all four | Open positions and the account summary, at the latest snapshot or as of `--timestamp`. Filters: `--symbol`, `--dex` (HIP-3). |
 | `oxa positions history` | all four | Hourly position snapshots in `[--start, --end)`. Filters: `--symbol`, `--dex` (HIP-3); `--limit`, `--cursor`. |
-| `oxa positions changes` | all four | Change log: every fill that changed a position, with the position before and after, the entry price after, realized PnL, and fees, in `[--start, --end)`. |
-| `oxa positions market` | all four | Every open position in one `--symbol`, sorted by position value, at the latest snapshot or at `--hour`. Filters: `--side long|short`, `--min-value <usd>`, `--include-system` (Lighter). |
+| `oxa positions changes` | all four | Change log: every fill leg on the position, with the size before and after, the entry price after, realized PnL, and fees, in `[--start, --end)`. On Lighter, a leg that leaves the size unchanged is included too, with `eventType` `settlement` (the settled side of a market settlement) or `unchanged`. |
+| `oxa positions market` | all four | Every open position in one `--symbol`, sorted by position value, at the latest snapshot or at `--hour`. Filters: `--side long` or `--side short`, `--min-value <usd>`, `--include-system` (Lighter). |
 | `oxa positions summary` | all four | Long and short counts, sizes, values, average entries, and top-10 share for one `--symbol`: the latest snapshot, or hourly over `--start`/`--end`. |
 | `oxa positions all` | all four | Every open position across markets at one `--hour` (an exact UTC hour). |
 | `oxa positions account` | `hyperliquid`, `hip3` | Account value, margin, position value, and PnL for one wallet (`--dex` on HIP-3). |
diff --git a/src/cli.ts b/src/cli.ts
index e3497ad..1a1e358 100644
--- a/src/cli.ts
+++ b/src/cli.ts
@@ -988,7 +988,7 @@ positions
 
 positions
   .command('changes')
-  .description('Get the position change log (every fill that changed a position) for a wallet or account')
+  .description('Get the position change log (every fill leg on the position, including legs that leave the size unchanged) for a wallet or account')
   .requiredOption('--exchange <exchange>', POSITIONS_EXCHANGE_DESC)
   .option('--address <address>', 'Wallet address, 0x... (hyperliquid, hip3)')
   .option('--account <index>', 'Lighter account index (lighter, rh-lighter)')
diff --git a/src/commands/trades.ts b/src/commands/trades.ts
index 0242a00..8bf8d5f 100644
--- a/src/commands/trades.ts
+++ b/src/commands/trades.ts
@@ -3,6 +3,7 @@ import {
   validateExchange,
   createClient,
   getExchangeClient,
+  isLighterExchange,
   type Exchange,
 } from '../lib/client.js';
 import {
@@ -92,9 +93,10 @@ async function fetchRange(
     const exchangeClient = getExchangeClient(client, exchange, apiKey);
     const result = await exchangeClient.trades.list(symbol, { start, end, limit, cursor });
     const trades = result.data;
-    // Lighter ranges are clamped to the finalization watermark; the SDK
-    // surfaces that as meta (finalized_through, clamped_to), passed through.
-    const meta = responseMeta(result);
+    // Lighter ranges (both deployments) are clamped to the finalization
+    // watermark; the SDK surfaces that as meta (finalized_through,
+    // clamped_to), passed through. Other exchanges keep their output as is.
+    const meta = isLighterExchange(exchange) ? responseMeta(result) : undefined;
     const envelope = { data: trades, nextCursor: result.nextCursor ?? null, ...(meta ? { meta } : {}) };
 
     if (outPath) {
diff --git a/tests/positions.test.ts b/tests/positions.test.ts
index c6df10d..e16f039 100644
--- a/tests/positions.test.ts
+++ b/tests/positions.test.ts
@@ -26,6 +26,7 @@ const sdk = vi.hoisted(() => {
     hyperliquid: {
       positions: positionsResource(),
       liquidations: { history: vi.fn(), volume: vi.fn(), byUser: vi.fn() },
+      trades: { list: vi.fn(), recent: vi.fn() },
       hip3: { positions: positionsResource() },
     },
     lighter: { ...lighterVenue(), accounts: { byL1: vi.fn() } } as Record<string, any>,
@@ -658,6 +659,24 @@ describe('Lighter deployments on the shared verbs', () => {
     });
   });
 
+  it('keeps Hyperliquid ranged trades output unchanged: no meta passthrough', async () => {
+    const trades = sdk.state.clients.hyperliquid.trades;
+    trades.list.mockResolvedValue({
+      data: [],
+      nextCursor: 'c1',
+      meta: { count: 0, requestId: 'r1', nextCursor: 'c1' },
+    });
+
+    await tradesFetchCommand({ exchange: 'hyperliquid', symbol: 'BTC', start: START, end: END, format: 'json' });
+    expect(trades.list).toHaveBeenCalledWith('BTC', {
+      start: Date.parse(START),
+      end: Date.parse(END),
+      limit: undefined,
+      cursor: undefined,
+    });
+    expect(stdoutJson()).toEqual({ data: [], nextCursor: 'c1' });
+  });
+
   it.each([
     [() => ordersHistoryCommand({ exchange: 'rh-lighter', symbol: 'BTC', start: START, end: END, format: 'json' }),
       'Lighter on Robinhood Chain has no order history endpoint. Use --exchange hyperliquid, hip3, or hip4.'],

From f6b8e7fe859c0b1ef37de992cc990f2cda2e970e Mon Sep 17 00:00:00 2001
From: 0xFantomMenace <93462858+0xFantomMenace@users.noreply.github.com>
Date: Sat, 26 Sep 2026 15:43:45 +0000
Subject: [PATCH 3/5] Robinhood Chain liquidations from 2026-06-26 20:10:26 UTC

The API now serves Robinhood Chain liquidations from the venue's first
trade, the same floor as trades. Rows before live capture were backfilled
from the venue's finalized export and carry source "bucket" with an empty
rawJson; live rows carry source "ws" and the venue's raw JSON.

- README venue table, liquidations intro, and row notes; CHANGELOG.
- oxa liquidations history help names both Lighter floors and the
  backfilled-row fields.
- Release test pins the floor in the README and CHANGELOG.
---
 CHANGELOG.md          |  4 ++--
 README.md             |  6 +++---
 src/cli.ts            |  5 ++++-
 tests/release.test.ts | 10 ++++++++++
 4 files changed, 19 insertions(+), 6 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index e4e02e3..ae9d11f 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -4,7 +4,7 @@
 
 ### Added
 
-- Lighter on Robinhood Chain, the second Lighter deployment, as `--exchange rh-lighter` on every shared market-data command that Lighter mainnet supports: instruments, order book and order book history, trades (canonical range and preliminary recent tier), candles, funding, open interest, liquidations, prices, summary, freshness, and `auth test`. It is USDG-quoted with 84 markets (57 perp, 27 spot); perps are uppercase (`BTC`) and spot markets are dashed (`AAPL-USDG`). Trades are served from 2026-06-26 20:10:26 UTC; liquidations, order book, open interest, and funding from 2026-08-22 18:43 UTC; candles from 2026-06-26 once they are enabled for this deployment. It has no L3.
+- Lighter on Robinhood Chain, the second Lighter deployment, as `--exchange rh-lighter` on every shared market-data command that Lighter mainnet supports: instruments, order book and order book history, trades (canonical range and preliminary recent tier), candles, funding, open interest, liquidations, prices, summary, freshness, and `auth test`. It is USDG-quoted with 84 markets (57 perp, 27 spot); perps are uppercase (`BTC`) and spot markets are dashed (`AAPL-USDG`). Trades and liquidations are served from 2026-06-26 20:10:26 UTC, the venue's first trade; order book, open interest, and funding from 2026-08-22 18:43 UTC; candles from 2026-06-26 once they are enabled for this deployment. It has no L3.
 - Live Robinhood Chain streams: `oxa stream orderbook <symbol> --exchange rh-lighter` and `oxa stream trades <symbol> --exchange rh-lighter`, and `oxa stream subscribe` accepts `rh_lighter_orderbook`, `rh_lighter_trades`, `rh_lighter_open_interest`, and `rh_lighter_funding`. Messages have the same shapes as the `lighter_*` live channels, `--interval-ms` (100 to 5000) works on `rh_lighter_orderbook`, and drop notices on `rh_lighter_*` channels are warnings, as on Lighter mainnet. They are served on `wss://api.0xarchive.io/ws`, the CLI default. `rh_lighter_candles` is replay-only and is rejected before a socket opens.
 - Account positions, `oxa positions ...`, on `hyperliquid`, `hip3`, `lighter`, and `rh-lighter`: `get` (latest snapshot, or as of `--timestamp`), `history` (hourly snapshots), `changes` (the change log), `market` (every open position in one market, with `--side`, `--min-value`, and `--include-system` on Lighter), `summary` (long/short positioning now or hourly), and `all` (every open position at one hour). Hyperliquid and HIP-3 add `account` and `account-history`. Hyperliquid and HIP-3 are keyed by `--address`; Lighter by `--account <index>`. JSON output includes the response `meta` (as-of time, snapshot, source, quality, staleness, and finalization fields).
 - `oxa accounts by-l1 --l1-address 0x...` lists the Lighter mainnet account indices owned by an L1 address.
@@ -12,7 +12,7 @@
 
 ### Changed
 
-- `oxa liquidations history` and `oxa liquidations volume` accept `--exchange lighter` and `--exchange rh-lighter`; they were previously refused. Lighter rows keep the trade's raw fields (`liquidationType`, `usdAmount`, both accounts, `rawJson`), and Lighter volume buckets carry a total and a count with no long/short split. `oxa liquidations user` stays Hyperliquid only.
+- `oxa liquidations history` and `oxa liquidations volume` accept `--exchange lighter` and `--exchange rh-lighter`; they were previously refused. Lighter rows keep the trade's raw fields (`liquidationType`, `usdAmount`, both accounts, `rawJson`); Robinhood Chain rows from before live capture (2026-08-22) were backfilled from the venue's finalized export and carry `source` `bucket` with an empty `rawJson`. Lighter volume buckets carry a total and a count with no long/short split. `oxa liquidations user` stays Hyperliquid only.
 - On Lighter ranges (both deployments), `oxa trades fetch` passes the response `meta` through, including the finalization fields (`meta.finalizedThrough`, and `meta.clampedTo` when the range was clamped to the watermark). Hyperliquid and HIP-3 trades output is unchanged.
 - `oxa orders ...`, `oxa l4 ...`, and `oxa l2 ...` reject `--exchange lighter` and `--exchange rh-lighter` with a clear message before any request, instead of failing inside the command.
 - The HIP-4 funding and liquidations refusals now list every exchange that serves those routes.
diff --git a/README.md b/README.md
index fb7ca41..2e820ae 100644
--- a/README.md
+++ b/README.md
@@ -81,7 +81,7 @@ oxa stream orderbook BTC --exchange lighter --duration-ms 10000
 | --- | --- | --- |
 | Hyperliquid | `--exchange hyperliquid` | `BTC`, `ETH`, `SOL`, etc. |
 | Lighter (mainnet) | `--exchange lighter` | `BTC`, `ETH`, etc. |
-| Lighter on Robinhood Chain | `--exchange rh-lighter` | USDG-quoted. Perps are uppercase (`BTC`, `ETH`); spot markets are dashed (`AAPL-USDG`). 84 markets: 57 perp, 27 spot. Trades from 2026-06-26 20:10:26 UTC (venue launch); liquidations, order book, OI, and funding from 2026-08-22 18:43 UTC; candles from 2026-06-26 once they are enabled for this deployment. No L3. |
+| Lighter on Robinhood Chain | `--exchange rh-lighter` | USDG-quoted. Perps are uppercase (`BTC`, `ETH`); spot markets are dashed (`AAPL-USDG`). 84 markets: 57 perp, 27 spot. Trades and liquidations from 2026-06-26 20:10:26 UTC (venue launch); order book, OI, and funding from 2026-08-22 18:43 UTC; candles from 2026-06-26 once they are enabled for this deployment. No L3. |
 | Hyperliquid HIP-3 | `--exchange hip3` | `km:US500`, `xyz:XYZ100`, etc. Case-sensitive. |
 | Hyperliquid HIP-4 | `--exchange hip4` or `oxa hip4 ...` | Bare numerics: `0`, `1`, `42`. Legacy `#0` / `%230` forms still work. `mark_price` is implied probability (0..1), not USD. Per-side OI is available from 2026-05-02 at ~10s cadence; candles are available. No funding or liquidations. |
 | Hyperliquid Spot | `oxa spot ...` | Dashed canonical: `HYPE-USDC`, `PURR-USDC`. 326 pairs. Spot candles from 2025-03-22T10:50:22Z at `1m`/`5m`/`15m`/`30m`/`1h`/`4h`/`1d`/`1w`, max 1000 rows; trades from 2025-03-22; orderbook, L4, TWAP live from 2026-05-05. No funding, OI, or liquidations. |
@@ -256,7 +256,7 @@ oxa instruments --exchange <exchange> [--format <format>]
 
 ### `oxa liquidations history`
 
-Get liquidation history for Hyperliquid, HIP-3, and both Lighter deployments. Lighter mainnet liquidations are served from 2026-06-10 and Lighter on Robinhood Chain liquidations from 2026-08-22 18:43 UTC.
+Get liquidation history for Hyperliquid, HIP-3, and both Lighter deployments. Lighter mainnet liquidations are served from 2026-06-10 and Lighter on Robinhood Chain liquidations from 2026-06-26 20:10:26 UTC, the venue's first trade. A Robinhood Chain range before the first liquidation (2026-06-27 23:14 UTC) returns no rows rather than an error.
 
 ```bash
 oxa liquidations history --exchange <exchange> --symbol <symbol> --start <time> --end <time> [options]
@@ -272,7 +272,7 @@ oxa liquidations history --exchange <exchange> --symbol <symbol> --start <time>
 | `--cursor` | No | Pagination cursor |
 | `--format` | No | `json` (default) or `pretty` |
 
-Lighter liquidation rows keep the trade's raw fields rather than a single liquidated user: `liquidationType`, `price`, `size`, `usdAmount`, the ask and bid accounts and order ids, each side's position before the trade, `txHash`, and `rawJson`, the untouched trade object. On rows backfilled from the venue's own export, `source` is `bucket` and `rawJson` is empty.
+Lighter liquidation rows keep the trade's raw fields rather than a single liquidated user: `liquidationType`, `price`, `size`, `usdAmount`, the ask and bid accounts and order ids, each side's position before the trade, `txHash`, and `rawJson`, the untouched trade object. Robinhood Chain rows from before live capture (2026-06-27 to 2026-08-22) were backfilled from the venue's finalized export: they carry `source` `bucket` and an empty `rawJson`. Live-captured rows carry `source` `ws` and the venue's raw JSON in `rawJson`.
 
 ### `oxa liquidations volume`
 
diff --git a/src/cli.ts b/src/cli.ts
index 1a1e358..79a02e7 100644
--- a/src/cli.ts
+++ b/src/cli.ts
@@ -249,7 +249,10 @@ const liquidations = program
 
 liquidations
   .command('history')
-  .description('Get liquidation history')
+  .description(
+    'Get liquidation history (Lighter mainnet from 2026-06-10; Lighter on Robinhood Chain from 2026-06-26 20:10:26 UTC, ' +
+      'with rows before 2026-08-22 backfilled from the venue\'s finalized export: source "bucket", empty rawJson)',
+  )
   .requiredOption('--exchange <exchange>', EXCHANGE_DESC)
   .requiredOption('--symbol <symbol>', 'Coin symbol (e.g. BTC, ETH, km:US500)')
   .requiredOption('--start <time>', 'Start time (ISO 8601 or Unix ms)')
diff --git a/tests/release.test.ts b/tests/release.test.ts
index 196c57a..0fda609 100644
--- a/tests/release.test.ts
+++ b/tests/release.test.ts
@@ -28,4 +28,14 @@ describe('release metadata', () => {
   it('presents Robinhood Chain as a Lighter deployment', () => {
     expect(readme).toContain('Lighter has two deployments: mainnet and Robinhood Chain.');
   });
+
+  it('states the Robinhood Chain liquidations floor the API serves', () => {
+    expect(readme).toContain('Trades and liquidations from 2026-06-26 20:10:26 UTC');
+    expect(readme).toContain('Lighter on Robinhood Chain liquidations from 2026-06-26 20:10:26 UTC');
+    expect(changelog).toContain('Trades and liquidations are served from 2026-06-26 20:10:26 UTC');
+    for (const doc of [readme, changelog]) {
+      expect(doc).not.toMatch(/liquidations,? (order book|and order book)[^.]*2026-08-22/);
+      expect(doc).not.toContain('Robinhood Chain liquidations from 2026-08-22');
+    }
+  });
 });

From 6bd58002656c1fcb1cbc5323112cae4bf9c9a9b4 Mon Sep 17 00:00:00 2001
From: 0xFantomMenace <93462858+0xFantomMenace@users.noreply.github.com>
Date: Mon, 28 Sep 2026 21:38:36 +0000
Subject: [PATCH 4/5] positions: summary cursor needs its window; README
 quality notes

- oxa positions summary --cursor without --start and --end is refused
  as a validation error (exit 2) before any request. A summary cursor
  pages an hourly series and is bound to that window; the SDK refusal
  used to surface as an internal error (exit 5). Test added.
- README: which reads carry the account summary on oxa positions get,
  the clamp fields on the change log, what an empty page before
  coverage looks like, and how quality reads per venue (Hyperliquid and
  HIP-3 normally complete; the latest Lighter day can read degraded at
  snapshot level with preliminary rows until the daily reconcile).
---
 README.md                 | 14 ++++++++------
 src/cli.ts                |  2 +-
 src/commands/positions.ts |  8 ++++++++
 tests/positions.test.ts   |  7 +++++++
 4 files changed, 24 insertions(+), 7 deletions(-)

diff --git a/README.md b/README.md
index 21da5f3..a3ea819 100644
--- a/README.md
+++ b/README.md
@@ -2,9 +2,9 @@
 
 Terminal-first access to 0xArchive market data.
 
-0xArchive is granular market data infrastructure for two venues: Hyperliquid and Lighter. Lighter has two deployments: mainnet and Robinhood Chain. HIP-3 builder perps, HIP-4 outcome markets, and Hyperliquid Spot live under the Hyperliquid namespace; the CLI exposes `--exchange hip3`, `--exchange hip4`, and the `oxa spot` group as convenience scopes for those markets. Lighter mainnet is `--exchange lighter` and Lighter on Robinhood Chain is `--exchange rh-lighter`.
+0xArchive is granular market data infrastructure for two venues: Hyperliquid and Lighter. Lighter has two deployments: mainnet and Robinhood Chain. HIP-3 builder perps, HIP-4 outcome markets, and Hyperliquid Spot live under the Hyperliquid namespace; the CLI exposes `--exchange hip3`, `--exchange hip4`, and the `oxa spot` group as convenience scopes for those markets. Lighter mainnet is `--exchange lighter` and Lighter on Robinhood Chain is `--exchange rh-lighter`. Account positions (`oxa positions ...`) cover Hyperliquid, HIP-3, and both Lighter deployments.
 
-Use `oxa` when the job starts in a terminal, script, CI task, notebook setup step, Claude Code session, ChatGPT Codex session, or another coding-agent shell. Both coding agents can start here with `oxa auth test` and one market-data request before expanding into SDKs, MCP, skills, or Data Catalog exports. The command set covers order books, trades, candles, funding, open interest, liquidations, prices, freshness, account positions, Lighter L3, Hyperliquid/HIP-3 L4 routes, HIP-4 outcome markets, and Hyperliquid Spot.
+Use `oxa` when the job starts in a terminal, script, CI task, notebook setup step, Claude Code session, ChatGPT Codex session, or another coding-agent shell. Both coding agents can start here with `oxa auth test` and one market-data request before expanding into SDKs, MCP, skills, or Data Catalog exports. The command set covers order books, trades, candles, funding, open interest, liquidations, prices, freshness, Lighter L3, Hyperliquid/HIP-3 L4 routes, HIP-4 outcome markets, and Hyperliquid Spot.
 
 ## Install
 
@@ -385,7 +385,7 @@ oxa positions account-history --exchange hyperliquid --address 0xYourWallet --st
 
 | Subcommand | Venues | Description |
 |---|---|---|
-| `oxa positions get` | all four | Open positions and the account summary, at the latest snapshot or as of `--timestamp`. Filters: `--symbol`, `--dex` (HIP-3). |
+| `oxa positions get` | all four | Open positions at the latest snapshot or as of `--timestamp`, plus the account summary on the first page of a snapshot read: on Hyperliquid always, on HIP-3 with `--dex` (or a dex-prefixed `--symbol`), and on Lighter the account's position totals when no `--symbol` is set. Filters: `--symbol`, `--dex` (HIP-3). |
 | `oxa positions history` | all four | Hourly position snapshots in `[--start, --end)`. Filters: `--symbol`, `--dex` (HIP-3); `--limit`, `--cursor`. |
 | `oxa positions changes` | all four | Change log: every fill leg on the position, with the size before and after, the entry price after, realized PnL, and fees, in `[--start, --end)`. On Lighter, a leg that leaves the size unchanged is included too, with `eventType` `settlement` (the settled side of a market settlement) or `unchanged`. |
 | `oxa positions market` | all four | Every open position in one `--symbol`, sorted by position value, at the latest snapshot or at `--hour`. Filters: `--side long` or `--side short`, `--min-value <usd>`, `--include-system` (Lighter). |
@@ -405,9 +405,11 @@ Coverage:
 
 How to read the results:
 
-- The JSON output is `{ "data": ..., "nextCursor": ..., "meta": ... }`. `meta` states what the page describes: `asOf`, `snapshotTs`, `source` (`snapshot` for hourly and live snapshots, `reconstructed` for an as-of time between snapshots, `changes` for the change log), `quality`, `stale`, `builtThrough`, `finalizedThrough`, `totals` (market listings, first page only), and `notice` / `coverageFrom` when a request reaches outside coverage.
-- `--timestamp` on `oxa positions get` returns the committed snapshot when it names a snapshot hour, and otherwise a reconstruction: size, entry, and open time are exact, mark fields are taken at that time, and snapshot-only fields are null. A time later than `meta.builtThrough` is clamped to it (`meta.clampedTo`).
-- Every row carries its own `quality`, and `meta.quality` is the snapshot's. `meta.stale` is `true`, with a notice, when the latest snapshot is more than 12 minutes old.
+- The JSON output is `{ "data": ..., "nextCursor": ..., "meta": ... }`. `meta` states what the page describes: `asOf`, `snapshotTs`, `source` (`snapshot` for hourly and live snapshots, `reconstructed` for an as-of time between snapshots, `changes` for the change log), `quality`, `stale`, `builtThrough`, `finalizedThrough`, `requestedEnd` / `clampedTo` when a read was clamped, `totals` (market listings, first page only), and `notice` / `coverageFrom` when a request reaches before coverage. Before coverage the command still succeeds, with an empty list and the notice.
+- `--timestamp` on `oxa positions get` returns the committed snapshot when it names a snapshot hour, and otherwise a reconstruction: size, entry, and open time are exact, mark fields are taken at that time, and snapshot-only fields are null. A `--timestamp`, or a change-log `--end`, later than `meta.builtThrough` is clamped to it (`meta.requestedEnd`, `meta.clampedTo`).
+- Every row carries its own `quality` (`complete`, `partial`, or `degraded`; Lighter rows can also read `preliminary`, `unreconciled`, or `incomplete`), and `meta.quality` is the snapshot's. A `partial` row is missing some fields, such as the mark, the entry, or the leverage, which read null or `unknown`. `meta.stale` is `true`, with a notice, when the latest snapshot is more than 12 minutes old.
+- Hyperliquid and HIP-3 snapshots normally read `complete`; hourly snapshots before 2026-09-26 19:00 UTC can read `degraded` on every row.
+- On both Lighter deployments, a snapshot of the most recent, not yet reconciled day can read `degraded` in `meta.quality` while its rows read `preliminary`. Those rows read `complete` once the venue's daily reconcile has covered them, which `meta.finalizedThrough` tracks.
 - `data.accountSeen` on `oxa positions get` is `flat`, `never_seen`, or `outside_coverage`. `never_seen` means no recorded activity in the covered history, not proof that the account never traded.
 - `meta.finalizedThrough` means what it means on Lighter trades: nothing before it will be re-derived. Rows after it can still change.
 - Lighter settlement, insurance, and other system accounts are left out of `oxa positions market` and `oxa positions all` unless you pass `--include-system`, and are labelled by `accountKind` everywhere.
diff --git a/src/cli.ts b/src/cli.ts
index c11fce8..cfacbc7 100644
--- a/src/cli.ts
+++ b/src/cli.ts
@@ -1033,7 +1033,7 @@ positions
   .option('--end <time>', 'End of an hourly series (ISO 8601 or Unix ms); pass with --start')
   .option('--include-system', 'Lighter only: include settlement, insurance, and other system accounts')
   .option('--limit <n>', 'Maximum hourly points to return')
-  .option('--cursor <cursor>', 'Pagination cursor from previous response')
+  .option('--cursor <cursor>', 'Pagination cursor from previous response (hourly series; repeat the same --start and --end)')
   .option('--out <path>', 'Write JSON output to file')
   .option('--api-key <key>', 'API key (or set OXA_API_KEY env var)')
   .option('--format <format>', 'Output format: json or pretty', 'json')
diff --git a/src/commands/positions.ts b/src/commands/positions.ts
index a086930..86b36b4 100644
--- a/src/commands/positions.ts
+++ b/src/commands/positions.ts
@@ -537,6 +537,14 @@ export async function positionsSummaryCommand(options: PositionsSummaryOptions):
     );
   }
   const range = options.start !== undefined ? parseRange(options.start, options.end!) : undefined;
+  if (options.cursor !== undefined && range === undefined) {
+    // Only an hourly series pages, and its cursor is bound to the window it
+    // was issued for.
+    exitError(
+      '--cursor pages an hourly series: pass the same --start and --end as the first page.',
+      EXIT.VALIDATION,
+    );
+  }
   const includeSystem = parseIncludeSystem(exchange, options.includeSystem);
   const limit = parseLimit(options.limit);
   const apiKey = resolveApiKey(options.apiKey);
diff --git a/tests/positions.test.ts b/tests/positions.test.ts
index e16f039..f1b255e 100644
--- a/tests/positions.test.ts
+++ b/tests/positions.test.ts
@@ -514,6 +514,13 @@ describe('oxa positions', () => {
         'Pass both --start and --end for an hourly series, or neither for the latest snapshot.',
       ));
 
+    it('pages a summary only as an hourly series', () =>
+      expectExit(
+        () => positionsSummaryCommand({ exchange: 'rh-lighter', symbol: 'BTC', cursor: 'p2', format: 'json' }),
+        2,
+        '--cursor pages an hourly series: pass the same --start and --end as the first page.',
+      ));
+
     it('keeps account summaries to Hyperliquid and HIP-3', () =>
       expectExit(
         () => accountGetCommand({ exchange: 'rh-lighter', address: WALLET, format: 'json' }),

From 65598a64003f4a5d4778291c6d672952872cf454 Mon Sep 17 00:00:00 2001
From: 0xFantomMenace <93462858+0xFantomMenace@users.noreply.github.com>
Date: Mon, 28 Sep 2026 21:40:48 +0000
Subject: [PATCH 5/5] README: positions requests before coverage, and hours
 with no snapshot

Ranges and --timestamp reads before coverage succeed with an empty list;
get, changes, and Lighter history add the notice. An --hour with no
committed snapshot is an API error on market and all.
---
 README.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/README.md b/README.md
index a3ea819..792da40 100644
--- a/README.md
+++ b/README.md
@@ -405,7 +405,7 @@ Coverage:
 
 How to read the results:
 
-- The JSON output is `{ "data": ..., "nextCursor": ..., "meta": ... }`. `meta` states what the page describes: `asOf`, `snapshotTs`, `source` (`snapshot` for hourly and live snapshots, `reconstructed` for an as-of time between snapshots, `changes` for the change log), `quality`, `stale`, `builtThrough`, `finalizedThrough`, `requestedEnd` / `clampedTo` when a read was clamped, `totals` (market listings, first page only), and `notice` / `coverageFrom` when a request reaches before coverage. Before coverage the command still succeeds, with an empty list and the notice.
+- The JSON output is `{ "data": ..., "nextCursor": ..., "meta": ... }`. `meta` states what the page describes: `asOf`, `snapshotTs`, `source` (`snapshot` for hourly and live snapshots, `reconstructed` for an as-of time between snapshots, `changes` for the change log), `quality`, `stale`, `builtThrough`, `finalizedThrough`, `requestedEnd` / `clampedTo` when a read was clamped, `totals` (market listings, first page only), and `notice` / `coverageFrom` when a request reaches before coverage. Before coverage, `--timestamp` reads and `--start`/`--end` ranges still succeed with an empty list; `get`, `changes`, and Lighter `history` add the notice. An `--hour` with no committed snapshot, including any hour before coverage, is an API error (exit code 4) on `market` and `all`.
 - `--timestamp` on `oxa positions get` returns the committed snapshot when it names a snapshot hour, and otherwise a reconstruction: size, entry, and open time are exact, mark fields are taken at that time, and snapshot-only fields are null. A `--timestamp`, or a change-log `--end`, later than `meta.builtThrough` is clamped to it (`meta.requestedEnd`, `meta.clampedTo`).
 - Every row carries its own `quality` (`complete`, `partial`, or `degraded`; Lighter rows can also read `preliminary`, `unreconciled`, or `incomplete`), and `meta.quality` is the snapshot's. A `partial` row is missing some fields, such as the mark, the entry, or the leverage, which read null or `unknown`. `meta.stale` is `true`, with a notice, when the latest snapshot is more than 12 minutes old.
 - Hyperliquid and HIP-3 snapshots normally read `complete`; hourly snapshots before 2026-09-26 19:00 UTC can read `degraded` on every row.