1.11.0

@0xarchive/cli

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 them as --exchange hip3, --exchange hip4, and --exchange spot, with the oxa hip4 and oxa spot groups for the data only those venues have. 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, Lighter L3, Hyperliquid/HIP-3 L4 routes, HIP-4 outcome markets, and Hyperliquid Spot, plus market breadth, cumulative volume delta, liquidation and trigger levels, the HIP-3 oracle, wallet classification, the symbol list, what each venue serves (oxa capabilities), webhooks, and WebSocket replay.

Install

Install it globally so the oxa command is on your PATH:

npm install -g @0xarchive/cli
oxa --version

Or run it without installing:

npx @0xarchive/cli auth test --exchange hyperliquid --symbol BTC

The CLI needs Node.js 18 or later, including for the WebSocket commands (oxa stream ...).

First Request

# Create a free account, then copy an API key:
# https://www.0xarchive.io/signup
export OXA_API_KEY="0xa_your_api_key"

# Verify your key works
oxa auth test

# What each venue serves, over REST and WebSocket, and from when (no key needed)
oxa capabilities --exchange hip3 --format pretty

# Time windows used by the examples in this README, in Unix milliseconds,
# relative to now so they stay inside every plan's history window (Free keeps
# the most recent 30 days)
NOW=$(( $(date +%s) * 1000 ))
HOUR_AGO=$(( NOW - 3600000 ))
DAY_AGO=$(( NOW - 86400000 ))
WEEK_AGO=$(( NOW - 604800000 ))
LAST_HOUR=$(( NOW / 3600000 * 3600000 - 3600000 ))   # the last whole UTC hour

# Fetch the current Hyperliquid BTC order book
oxa orderbook get --exchange hyperliquid --symbol BTC --format pretty

# Fetch recent Lighter trades, and only the sells on a HIP-3 market
oxa trades history --exchange lighter --symbol BTC --limit 50
oxa trades history --exchange hip3 --symbol xyz:TSLA --side sell --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

# The largest open BTC longs on Hyperliquid right now
oxa positions market --exchange hyperliquid --symbol BTC --side long --limit 10 --format pretty

# Hourly HIP-3 builder-perp candles for the last day
oxa candles history --exchange hip3 --symbol xyz:TSLA --start $DAY_AGO --end $NOW --interval 1h --format pretty

# HIP-4 outcome markets settle, and new ones are listed, every day. List the open ones:
oxa hip4 outcomes list --settled false --limit 20 --format pretty

# Then use an outcome id. Here jq picks today's BTC price outcome from the
# instrument list and keeps the coin of its Yes side (10 x outcome id + side):
COIN=$(oxa hip4 instruments | jq -r '[.[] | select(.isSettled == false and .recurringUnderlying == "BTC" and .side == 0)][0].symbol | ltrimstr("#")')
oxa hip4 outcomes get $(( COIN / 10 )) --format pretty
oxa hip4 orderbook get "$COIN" --format pretty
oxa candles history --exchange hip4 --symbol "$COIN" --start $HOUR_AGO --end $NOW --interval 5m --format pretty

# List Hyperliquid Spot pairs and inspect one
oxa spot pairs
oxa spot pairs get HYPE-USDC

# Share of HIP-3 markets trading above their session VWAP
oxa breadth current --exchange hip3 --format pretty

# Hourly cumulative volume delta for BTC over the last day
oxa cvd history --exchange hyperliquid --symbol BTC --start $DAY_AGO --end $NOW

# Every symbol with its coverage dates, for one venue
oxa symbols list --exchange hip3 --format pretty

# Stream live Hyperliquid liquidations for a minute
oxa stream liquidations BTC --duration-ms 60000

# Stream live Lighter order books for 10 seconds (at most one full top-20 book per second by default)
oxa stream orderbook BTC --exchange lighter --duration-ms 10000

The examples in the rest of this README use NOW, HOUR_AGO, DAY_AGO, WEEK_AGO, LAST_HOUR, and COIN as set above; --start and --end also accept ISO 8601 times.

Choose Your Next Path

• First authenticated route: Quick Start
• Full CLI guide: CLI docs
• Claude Code, ChatGPT Codex, and coding-agent workflows: AI Clients
• File-based pulls: Data Catalog
• Plans and limits: Pricing
• Machine-readable docs: llms.txt and OpenAPI

Venue Scopes

Command Grammar

Commands follow one grammar. A datatype that more than one venue serves is oxa <datatype> <verb> --exchange <venue>, with four verbs: get for a point-in-time read, current for the latest value, history for a paged series, and list for a catalog:

oxa trades history --exchange spot --symbol HYPE-USDC --start $HOUR_AGO --end $NOW
oxa orderbook history --exchange hip4 --symbol "$COIN" --start $HOUR_AGO --end $NOW --depth 5
oxa instruments list --exchange rh-lighter

A datatype that only one venue serves sits under that venue: oxa hip4 outcomes, oxa hip4 questions, oxa spot pairs, oxa spot twap, oxa hip3 oracle, oxa lighter l3, and oxa lighter accounts.

The earlier forms keep working and run the same commands: oxa trades fetch (oxa trades history), oxa candles, oxa prices, and oxa cvd <symbol> (their history), oxa summary and oxa freshness (their get), oxa instruments and oxa symbols (their list), oxa l3 ... and oxa accounts by-l1 (under oxa lighter), oxa outcomes ... (under oxa hip4), oxa spot pair <symbol> (oxa spot pairs get), and the Spot and HIP-4 market-data commands under oxa spot and oxa hip4.

Which venue serves which datatype, over REST and WebSocket, and from when, is oxa capabilities.

Plans and Data Access

Every command below works on every plan, including Free, except the live mempool stream (oxa stream subscribe mempool), which is included with the Pro, Scale and Enterprise plans. Apart from the live mempool stream, Free includes every market, route, schema, and served depth, with history limited to the most recent rolling 30 days and a maximum 30-day span per request or replay. Build and above keep the full retained archive. Plans gate capacity, Free's 30-day history window and the live mempool stream; every other route family, schema and served depth is on every plan. See Pricing for plan capacity.

Commands

oxa auth test

Verify your API key is valid by making a lightweight API call.

oxa auth test [--api-key <key>] [--exchange <exchange>] [--symbol <symbol>] [--format <format>]

oxa capabilities

What each venue serves: one row per venue and datatype, with the REST routes, the WebSocket channels and whether they stream live and replay, the first served instant (availableFrom), cadence, page limit, accepted intervals, and notes. This is the same table the stream and replay commands follow. The route is public, so no API key is needed.

oxa capabilities --format pretty
oxa capabilities --exchange spot --format pretty
oxa capabilities --exchange hip3 --datatype l4_diffs --format pretty
oxa capabilities | jq '[.[] | select(.replay) | .wsChannels[]]'

oxa orderbook get

Get an orderbook snapshot for a symbol. --exchange spot reads the Hyperliquid Spot book.

oxa orderbook get --exchange <exchange> --symbol <symbol> [options]

oxa orderbook history

Get historical orderbook snapshots over a time range, on every venue including --exchange spot. --depth caps the price levels per side on every venue.

oxa orderbook history --exchange <exchange> --symbol <symbol> --start <time> --end <time> [options]

oxa trades history (also oxa trades fetch)

Fetch trade history for a symbol, on every venue including --exchange spot. oxa trades fetch is the same command.

oxa trades history --exchange <exchange> --symbol <symbol> [options]
oxa trades history --exchange hyperliquid --symbol BTC --start $HOUR_AGO --end $NOW --side buy

Note: Hyperliquid trades always require --start and --end. Every other venue (HIP-3, HIP-4, Spot, and both Lighter deployments) fetches its most recent trades without a range, and --side filters those too.

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 history (also oxa candles)

Get OHLCV candle data. oxa candles --exchange ... runs the same command.

oxa candles history --exchange <exchange> --symbol <symbol> --start <time> --end <time> [options]

HIP-4 candles use /v1/hyperliquid/hip4/candles/{coin} with the same candle intervals. Hyperliquid Spot candles (--exchange spot, or oxa spot candles <symbol>) use the /v1/hyperliquid/spot/candles/{symbol} route, with at most 1000 rows per page. Candles for Lighter on Robinhood Chain (--exchange rh-lighter) start at 2026-06-26 20:10 UTC.

oxa breadth current and oxa breadth history

Market breadth: the percentage of eligible instruments whose price is above their current UTC-session VWAP, on Hyperliquid (--exchange hyperliquid) and HIP-3 (--exchange hip3). The session resets at 00:00 UTC. Instruments with no session volume, or whose last completed candle is stale, are excluded and counted in counts; coverageRatio is eligible over candidates. When no instrument is eligible, valuePct is null, never 0: the JSON output keeps it null and pretty output prints null. HIP-3 snapshots also carry per-builder counts in namespaces. History begins 2026-08-24 on Hyperliquid and 2026-08-28 on HIP-3.

oxa breadth current --exchange hyperliquid
oxa breadth history --exchange hip3 --start $DAY_AGO --end $NOW --interval 1h

oxa cvd history (also oxa cvd <symbol>)

Cumulative volume delta for one market on Hyperliquid or HIP-3: taker buy and sell notional per bucket (buyVolume, sellVolume), their difference (delta), and a running total (cumulativeDelta). Buckets are labelled by their open time in UTC (timestamp, an RFC 3339 string, with the same instant in Unix ms as timestampMs) and are omitted when they hold no trades. oxa cvd <symbol> --exchange ... runs the same command.

oxa cvd history --exchange <exchange> --symbol <symbol> [options]
oxa cvd history --exchange hyperliquid --symbol BTC --start $DAY_AGO --end $NOW --interval 5m
oxa cvd xyz:SP500 --exchange hip3

While has_more is true, run the command again with --cursor <nextCursor> and the same --start, --end, and --interval. Below 1h a page can hold fewer than --limit buckets and still have more after it, so stop on has_more, not on a short page. cumulativeDelta restarts on every page: rebuild it from delta when joining pages. A response that is one page of several says so in meta.notice.

oxa funding current

Get the current funding rate.

oxa funding current --exchange <exchange> --symbol <symbol> [--format <format>]

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

Get funding rate history over a time range.

oxa funding history --exchange <exchange> --symbol <symbol> --start <time> --end <time> [options]

oxa oi current

Get current open interest.

oxa oi current --exchange <exchange> --symbol <symbol> [--format <format>]

HIP-4 per-side open interest is available from 2026-05-02 16:51 UTC at approximately 10-second cadence. Lighter open interest is also approximately 10 seconds; cadence is data-type specific rather than a generic venue-wide promise.

oxa oi history

Get open interest history over a time range.

oxa oi history --exchange <exchange> --symbol <symbol> --start <time> --end <time> [options]

oxa instruments list (also oxa instruments)

List all available instruments on a venue. --exchange spot lists the Spot pairs, as oxa spot pairs does.

oxa instruments list --exchange <exchange> [--format <format>]

oxa symbols list (also oxa symbols)

List the public symbol universe across every venue: each entry's venue family (exchange: hyperliquid, hip3, hip4, spot, lighter, or rh-lighter), coverage start and end, data types, the earliest coverage per data type (coverageByType), and the estimated size per day per data type (sizePerDay). HIP-4 entries also carry the slug, outcome pair, display title, and settlement state. The API returns the whole list in one response (every HIP-4 outcome side is an entry, so the full list runs to several megabytes); --exchange and --symbol filter it locally.

oxa symbols list --exchange hyperliquid --symbol BTC
oxa symbols list --exchange hip4 --out hip4-symbols.json
oxa symbols list | jq '[.[] | select(.exchange == "spot")] | length'

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

oxa liquidations history --exchange <exchange> --symbol <symbol> --start <time> --end <time> [options]

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

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.

oxa liquidations volume --exchange <exchange> --symbol <symbol> --start <time> --end <time> [options]

oxa liquidations user

Get liquidations for a specific user address (Hyperliquid only).

oxa liquidations user --exchange hyperliquid --user <address> --start <time> --end <time> [options]

oxa liquidations levels and oxa liquidations levels-history

Projected forced-liquidation levels on Hyperliquid and HIP-3: the long and short notional (and position counts) that would be liquidated in each price bucket around the mark price, computed from clearinghouse positions and margin state. Snapshots refresh about every five minutes and are kept from 2026-07-27. Each snapshot also carries the total long and short notional at risk and flaggedNotional, exposure computed approximately or not bucketed (HIP-3 cross-margin positions). These are projected forced liquidations, not pending trigger orders; see oxa orders trigger-levels for those.

oxa liquidations levels --exchange hyperliquid --symbol BTC --range-pct 5 --buckets 50
oxa liquidations levels --exchange hip3 --symbol xyz:TSLA --at $HOUR_AGO
oxa liquidations levels-history --exchange hyperliquid --symbol BTC \
  --start $DAY_AGO --end $NOW --summary

oxa summary get (also oxa summary)

Get a combined market summary in one call: mark price, oracle price, open interest, 24h volume, and any available funding or liquidation fields.

oxa summary get --exchange <exchange> --symbol <symbol> [--format <format>]

oxa prices history (also oxa prices)

Get mark/oracle/mid price history over a time range.

oxa prices history --exchange <exchange> --symbol <symbol> --start <time> --end <time> [options]

oxa freshness get (also oxa freshness)

Check data freshness across all data types for a symbol, on every venue including --exchange spot.

oxa freshness get --exchange <exchange> --symbol <symbol> [--format <format>]

oxa data-quality ...

Platform status, coverage, incidents, latency, and SLA compliance, and the freshness of the account positions data.

oxa data-quality status --format pretty
oxa data-quality coverage
oxa data-quality coverage --exchange hip3
oxa data-quality coverage --exchange hyperliquid --symbol BTC --from $WEEK_AGO --to $NOW
oxa data-quality incidents --status resolved --exchange lighter --limit 20
oxa data-quality incident <incident_id>
oxa data-quality latency --format pretty
oxa data-quality sla --year 2026 --month 8
oxa data-quality positions-freshness --format pretty

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.

# 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 $HOUR_AGO

# Hourly snapshots and the change log over a range
oxa positions history --exchange lighter --account 42 --start $DAY_AGO --end $NOW
oxa positions changes --exchange hyperliquid --address 0xYourWallet --start $DAY_AGO --end $NOW --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 $LAST_HOUR

# 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 $DAY_AGO --end $NOW

# Every open position across all markets at one hour (bulk, paginated)
oxa positions all --exchange rh-lighter --hour $LAST_HOUR --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 $DAY_AGO --end $NOW

Coverage:

How to read the results:

• The JSON output is { "data": ..., "nextCursor": ..., "has_more": ..., "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 on market and all (error_code not_found, exit code 2).
• --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.
• 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 lighter accounts by-l1 (Lighter mainnet; also oxa accounts by-l1)

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.

oxa lighter accounts by-l1 --l1-address 0xYourL1Address [--limit <n>] [--cursor <cursor>] [--format <format>]

oxa wallets classify

Precomputed daily behavioral metrics for active wallets on Hyperliquid or HIP-3: order and fill counts, cancel, fill, and maker ratios, order sizes, volume, fees, realized PnL, liquidation count, and TWAP, client order id, builder, and priority-gas usage. Each response covers one daily snapshot (date, yesterday by default) with the number of matching wallets (total); page with --offset and --limit. The JSON output is the response as returned: { "wallets": [...], "total": ..., "date": ... }, each wallet with its address, metrics, and period.

oxa wallets classify --exchange hyperliquid --sort total_volume_usd --min-orders 1000 --max-cancel-rate 0.5 --limit 100
oxa wallets classify --exchange hip3 --uses-twap true
oxa wallets classify --exchange hyperliquid --limit 100 --offset 100

oxa outcomes list (HIP-4 only)

List HIP-4 outcome markets (binary outcome metadata). The same commands sit under the venue as oxa hip4 outcomes list, oxa hip4 outcomes get, and oxa hip4 outcomes by-slug.

oxa outcomes list [--settled true|false|all] [--limit <n>] [--cursor <cursor>] [--format <format>]

oxa outcomes get (HIP-4 only)

Get a single HIP-4 outcome market detail. The response includes aggregated_oi (latest both-sides OI snapshot).

oxa outcomes get <outcome_id> [--format <format>]

oxa outcomes by-slug (HIP-4 only)

Get a HIP-4 outcome market by slug: the outcome's own slug (btc-above-78213-may-03-0600) or either side's (btc-above-78213-yes-may-03-0600). The response is the outcome aggregate, as with oxa outcomes get: it includes aggregatedOi, and sideSpecs lists each side's coin and slug. Also available as oxa hip4 outcomes by-slug. Quote a slug that contains spaces.

oxa outcomes by-slug <slug> [--format <format>]

oxa orders history

Get order history with user attribution. The oxa orders, oxa l4, and oxa l2 commands cover Hyperliquid routes (hyperliquid, hip3, and hip4 where noted, and spot on oxa orders history and oxa l4); --exchange lighter and --exchange rh-lighter are rejected before any request.

oxa orders history --exchange <exchange> --symbol <symbol> --start <time> --end <time> [options]

The filters apply on Hyperliquid, HIP-3, and HIP-4. Spot order history (--exchange spot, or oxa spot orders <symbol>) takes the time range and cursor only, and refuses the filters before any request.

oxa orders flow

Get order flow aggregation.

oxa orders flow --exchange <exchange> --symbol <symbol> --start <time> --end <time> [options]

A page holds the oldest --limit buckets of the window. While the response carries nextCursor (and has_more is true), run the command again with --cursor <nextCursor> and the same --start, --end, and --interval; stop when it is null. Buckets are labelled by their open time in UTC, and buckets with no events are omitted.

oxa orders tpsl

Get TP/SL (take-profit / stop-loss) order history.

oxa orders tpsl --exchange <exchange> --symbol <symbol> --start <time> --end <time> [options]

oxa orders trigger-levels and oxa orders trigger-levels-history

The pending trigger-order map on Hyperliquid and HIP-3: currently open stop-loss and take-profit trigger orders grouped into price buckets near the mid price, with the order count and size on each side of every bucket. asOf is the time the pending state was read. History is kept at a 15-minute cadence from 2026-07-27. These are voluntary trigger orders, not projected forced liquidations; see oxa liquidations levels for those. HIP-4 and Spot have no trigger levels.

oxa orders trigger-levels --exchange hyperliquid --symbol BTC --range-pct 5
oxa orders trigger-levels-history --exchange hip3 --symbol xyz:TSLA \
  --start $DAY_AGO --end $NOW --limit 100

The options are those of oxa liquidations levels and levels-history above, except --at: --exchange, --symbol, --range-pct, --buckets, and --side on both, and --start, --end, --summary, --limit, --cursor, and --out on the history.

oxa l4 get

Get an L4 order-level orderbook reconstruction at a point in time, on hyperliquid, hip3, hip4, or spot.

oxa l4 get --exchange <exchange> --symbol <symbol> [options]

oxa l4 diffs

Get L4 orderbook diffs (individual order-level changes) over a time range.

oxa l4 diffs --exchange <exchange> --symbol <symbol> --start <time> --end <time> [options]

oxa l4 history

Get L4 orderbook checkpoints (full snapshots at periodic intervals) over a time range.

oxa l4 history --exchange <exchange> --symbol <symbol> --start <time> --end <time> [options]

oxa l2 get

Get an L2 all-level orderbook snapshot derived from L4 data on supported Hyperliquid routes.

oxa l2 get --exchange <exchange> --symbol <symbol> [options]

oxa l2 history

Get L2 all-level orderbook history over a time range on supported Hyperliquid routes. Every checkpoint carries the full book unless --depth caps the price levels per side.

oxa l2 history --exchange <exchange> --symbol <symbol> --start <time> --end <time> [options]

oxa l2 diffs

Get L2 tick-level diffs over a time range.

oxa l2 diffs --exchange <exchange> --symbol <symbol> --start <time> --end <time> [options]

oxa lighter l3 get (also oxa l3 get)

Get a Lighter L3 order-level orderbook snapshot (maximum 250 orders per side). Lighter mainnet only; Lighter on Robinhood Chain has no L3. L3 is a Lighter-only datatype, so it sits under oxa lighter; oxa l3 get is the same command.

oxa lighter l3 get --symbol <symbol> [options]

Note: L3 commands are Lighter-only and do not accept an --exchange flag.

oxa hip4 ... (HIP-4 outcome markets)

Explicit HIP-4 command surface. Each outcome trades as two side coins, written as bare numerics: 10 times the outcome id plus the side (82260 is outcome 8226, Yes). Outcomes settle and new ones are listed every day, so look up a current coin first (see First Request, which sets COIN); a settled outcome no longer has a live book. HIP-4 trades and candles are served from 2026-05-02 08:00 UTC, and the order book, per-side OI (about every 10 seconds), and prices from 2026-05-02 16:51 UTC. HIP-4 has no funding or liquidations. Outcomes and questions are HIP-4 only and live here. The market-data commands below are the same as --exchange hip4 on the shared datatypes (oxa orderbook get --exchange hip4 --symbol "$COIN", oxa trades history --exchange hip4 --symbol "$COIN"), which is the one grammar every venue shares.

# Discovery
oxa hip4 instruments
oxa hip4 outcomes list --settled false
oxa hip4 outcomes get $(( COIN / 10 ))
oxa hip4 outcomes by-slug btc-above-78213-may-03-0600   # a settled outcome, looked up by its slug

# Questions: binary outcomes grouped under one ballot
oxa hip4 questions list --limit 100
oxa hip4 questions get 1

# Market data
oxa hip4 orderbook get "$COIN" --depth 10
oxa hip4 orderbook history "$COIN" --start $HOUR_AGO --end $NOW
oxa hip4 trades "$COIN" --recent --limit 50
oxa hip4 trades "$COIN" --start $HOUR_AGO --end $NOW --side buy
oxa hip4 candles "$COIN" --start $HOUR_AGO --end $NOW --interval 5m
oxa hip4 oi current "$COIN"
oxa hip4 oi history "$COIN" --start $HOUR_AGO --end $NOW --interval 5m
oxa hip4 prices "$COIN" --start $HOUR_AGO --end $NOW --interval 5m
oxa hip4 summary "$COIN"
oxa hip4 freshness "$COIN"

# Order-level
oxa hip4 orders history "$COIN" --start $HOUR_AGO --end $NOW --triggered true
oxa hip4 orders flow    "$COIN" --start $HOUR_AGO --end $NOW --interval 5m
oxa hip4 orders tpsl    "$COIN" --start $HOUR_AGO --end $NOW
oxa hip4 l4 get      "$COIN"
oxa hip4 l4 diffs    "$COIN" --start $HOUR_AGO --end $NOW
oxa hip4 l4 history  "$COIN" --start $HOUR_AGO --end $NOW

A question groups binary outcomes under one ballot: one named outcome per choice (namedOutcomeIds) plus a fallback outcome (fallbackOutcomeId) that resolves Yes when no named choice does. settledNamedOutcomes lists the named outcomes that have settled, and outcome ids match oxa hip4 outcomes. oxa hip4 questions list pages with --limit (1 to 1,000, default 100) and --cursor.

oxa hip3 oracle ... (HIP-3 oracle)

Oracle reads for a HIP-3 builder market. Symbols keep their builder prefix and case (xyz:SP500).

oxa hip3 oracle external-price xyz:SP500
oxa hip3 oracle discovery-bounds xyz:SP500 --format pretty

Both carry the source blockNumber, and timestamp as an RFC 3339 string with the same instant in Unix ms as timestampMs.

oxa spot ... (Hyperliquid Spot)

Explicit Spot command surface. Symbols are dashed canonical (HYPE-USDC, PURR-USDC); the server resolves the dashed form to Hyperliquid's wire formats (PURR/USDC, @107) internally. Spot has no funding, open interest, or liquidations; candles are served through the dedicated Spot route. Pairs and TWAP statuses are Spot only and live here. The Spot market data is also served by the shared datatypes with --exchange spot: oxa orderbook get|history, oxa trades history, oxa candles history, oxa l4 get|diffs|history, oxa orders history, oxa freshness get, and oxa instruments list.

Coverage (oxa capabilities --exchange spot): candles from 2025-03-22 10:50 UTC, with 1m, 5m, 15m, 30m, 1h, 4h, 1d, and 1w intervals and a maximum limit of 1000; trades from 2025-03-22 10:50:22 UTC; TWAP statuses from 2026-05-05 13:05 UTC; order book from 2026-05-05 19:56 UTC; L4 diffs and checkpoints from 2026-05-05 22:57 UTC (PURR-USDC from 2026-03-11 01:03 UTC), with order history reaching back further. oxa spot pairs lists the current pairs. Every Spot route is available on every plan, including Free; on Free, history is limited to the most recent rolling 30 days (see Plans and Data Access).

# Discovery
oxa spot pairs
oxa spot pairs get HYPE-USDC

# Market data
oxa spot orderbook HYPE-USDC --depth 10
oxa orderbook history --exchange spot --symbol HYPE-USDC --start $HOUR_AGO --end $NOW --depth 10
oxa spot trades HYPE-USDC --start $HOUR_AGO --end $NOW --side sell
oxa spot candles HYPE-USDC --start $HOUR_AGO --end $NOW --interval 1m --limit 1000

# L4 / order lifecycle
oxa spot l4 HYPE-USDC
oxa spot l4-diffs HYPE-USDC --start $HOUR_AGO --end $(( HOUR_AGO + 300000 ))
oxa spot l4-history HYPE-USDC --start $DAY_AGO --end $NOW
oxa spot orders HYPE-USDC --start $HOUR_AGO --end $NOW

# TWAP statuses (REST only; there is no live TWAP stream)
oxa spot twap history HYPE-USDC --start $DAY_AGO --end $NOW
oxa spot twap-user 0xYourWallet --start $DAY_AGO --end $NOW

# Per-symbol freshness across orderbook, trades, L4, TWAP
oxa spot freshness HYPE-USDC

For realtime spot streams, use oxa stream subscribe <channel> <symbol> with one of spot_orderbook, spot_trades, spot_l4_diffs, spot_l4_orders. Spot trades and books are also available through oxa stream trades and oxa stream orderbook with --exchange spot. The spot_twap channel does not stream; read TWAP statuses with oxa spot twap history. Example:

oxa stream subscribe spot_trades HYPE-USDC --duration-ms 60000
oxa stream trades HYPE-USDC --exchange spot --duration-ms 60000

oxa stream ... (realtime WebSocket)

Stream live market data over a single WebSocket subscription, or replay stored data with oxa stream replay (see Replay). Output is NDJSON on stdout (one JSON record per line) by default; --format pretty adds a one-line summary per event. WebSocket streaming is available on every plan, including Free; the mempool channel is included with the Pro, Scale and Enterprise plans. Connection counts, subscription caps, and replay speed scale with plan; on Free, replay is limited to the most recent rolling 30 days with a maximum 30-day span per replay (see Plans and Data Access). Each oxa stream process opens one WebSocket connection, which counts toward your plan's connection limit; the default endpoint is wss://api.0xarchive.io/ws, and mempool connects to wss://stream.0xarchive.io/ws, the only endpoint that serves it. Live streams and replays run on the SDK's WebSocket client, which connects with the ws package in Node.js. They work on Node.js 18 or later, and large messages, such as the L4 snapshot of a deep book, arrive intact.

# Realtime liquidations (Hyperliquid; pass `--exchange hip3` for HIP-3 builder perps)
oxa stream liquidations BTC
oxa stream liquidations xyz:SP500 --exchange hip3

# Realtime trades (channel data is the same fill row used by historical /trades, with `is_liquidation: true` on liquidation fills)
oxa stream trades BTC
oxa stream trades xyz:SP500 --exchange hip3

# Realtime orderbook
oxa stream orderbook BTC --duration-ms 60000
oxa stream orderbook HYPE-USDC --exchange spot --duration-ms 60000

# Lighter (see "Lighter live channels" below)
oxa stream orderbook BTC --exchange lighter                    # at most one full top-20 book per second
oxa stream orderbook BTC --exchange lighter --interval-ms 250  # at most one book every 250 ms
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

# Full-depth L2 books: every price level, then level changes
oxa stream subscribe orderbook_full BTC
oxa stream subscribe hip3_orderbook_full xyz:SP500

# HIP-4 outcome markets (bare numeric side coins; COIN is set in First Request)
oxa stream subscribe hip4_trades "$COIN"
oxa stream subscribe hip4_l4_diffs "$COIN"

# Pending Hyperliquid transactions, before they are in a block (Pro, Scale and Enterprise plans)
oxa stream subscribe mempool BTC --duration-ms 10000
oxa stream subscribe mempool --duration-ms 10000   # every pending transaction our Hyperliquid node receives

# Replay ten minutes of stored trades at 10x real time (one minute), then exit
oxa stream replay trades BTC --start $HOUR_AGO --end $(( HOUR_AGO + 600000 )) --speed 10

# Replay five minutes of HIP-3 L4 diffs in bulk
oxa stream replay hip3_l4_diffs xyz:TSLA --start $HOUR_AGO --end $(( HOUR_AGO + 300000 ))

oxa stream subscribe accepts every channel that oxa capabilities lists as live. The CLI reads that list from the SDK's channel table, which mirrors /v1/capabilities: orderbook, trades, liquidations, open_interest, funding, ticker, all_tickers, l4_diffs, l4_orders, orderbook_full (Hyperliquid); hip3_orderbook, hip3_trades, hip3_open_interest, hip3_funding, hip3_liquidations, hip3_l4_diffs, hip3_l4_orders, hip3_orderbook_full (HIP-3); hip4_trades, hip4_l4_diffs, hip4_l4_orders (HIP-4); spot_orderbook, spot_trades, spot_l4_diffs, spot_l4_orders (Spot); the four live channels of each Lighter deployment; and mempool (pending transactions on every Hyperliquid product, see Pending transactions (mempool)). mempool takes an optional symbol, all_tickers takes none, and every other channel needs one. The replay-only channels (candles, hip3_candles, hip4_orderbook, hip4_open_interest, lighter_candles, lighter_l3_orderbook, rh_lighter_candles) are refused before a socket opens, with a pointer to the command that serves their data, and so is spot_twap, whose TWAP statuses are served over REST only (oxa spot twap history).

Each liquidations / hip3_liquidations event is delivered as a fill row with is_liquidation: true. To stop early, send SIGINT (Ctrl-C) or pass --duration-ms; both exit with code 0. An error message from the server is written to stderr with its error_code, and the CLI exits with the code for that class (see Exit Codes): an unknown symbol (invalid_symbol) exits with code 2, and a connection that fell behind (slow_consumer) exits with code 4, so a supervising script can restart the stream. The one exception is a Lighter drop notice, which the CLI reports as a warning while the stream continues (see Lighter live channels). Every connection selects API version 2026-10-01 (version=2026-10-01 on the URL).

Lighter live channels

Live subscriptions are available for four Lighter channels on each deployment:

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 history --exchange lighter|rh-lighter and oxa lighter l3 get / oxa lighter l3 history. Robinhood Chain has no L3 channel.

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.

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