CLI

Run 0xArchive market-data commands from a terminal, a cron job, CI, or a coding agent’s shell with oxa, and get JSON you can pipe into jq or a script. Pick a venue, pass an explicit symbol and window, and branch on exit codes instead of reading terminal text. The package is @0xarchive/cli and the binary is oxa. It needs Node.js >=18, including for the streaming and replay commands (oxa stream ...), and reads your key from OXA_API_KEY. Source: 0xArchiveIO/0xarchive-cli.

Install the CLI

npm install -g @0xarchive/cli@1.10.0

These docs match CLI version 1.10.0. Confirm the installed version with oxa --version before pinning it in automation. For a one-off command without a global install, use the npx form in the auth step.

Set the CLI key

export OXA_API_KEY="0xa_your_api_key"

Run one auth check

oxa auth test --exchange hyperliquid --symbol BTC --format json

Without the global install, run npx @0xarchive/cli@1.10.0 auth test --exchange hyperliquid --symbol BTC --format json.

Pull one market payload

oxa orderbook get --exchange hyperliquid --symbol BTC --format json

Inputs

Input	Shape
API key	`OXA_API_KEY`, kept in the shell, a CI secret, or an ignored local environment file
Venue	`--exchange hyperliquid`, `lighter`, `rh-lighter`, `hip3`, or `hip4`, or the `oxa spot ...` commands. `rh-lighter` is Lighter on Robinhood Chain; HIP-3 and HIP-4 are Hyperliquid market families with their own scopes
Symbol	`BTC`, `ETH`, `km:US500`, `0`, or `HYPE-USDC`. Keep HIP-3 prefixes and their case; the CLI accepts bare numeric HIP-4 outcome sides
Window	`--start` and `--end` as ISO 8601 or Unix milliseconds, plus `--interval`, `--limit`, and `--cursor`. Start small, then paginate or widen once the first response looks right
Output	`--format json` for scripts, agents, CI, and notebooks; `--format pretty` for reading

Examples

Each example runs on any plan, including Free. The candles example computes a window that ends now, inside Free’s most recent 30 days.

oxa orderbook get --exchange hyperliquid --symbol BTC --format json

oxa trades fetch --exchange lighter --symbol BTC --limit 50 --format json

END=$(( $(date +%s) * 1000 ))
oxa candles --exchange hip3 --symbol xyz:XYZ100 \
  --start $(( END - 86400000 )) \
  --end $END \
  --interval 1h \
  --format json

oxa hip4 outcomes list --settled false --format json

oxa spot pairs --format json

oxa stream trades BTC --duration-ms 10000

Commands

Command	Coverage
`oxa auth test`	Check the key, and optionally a venue and symbol
`oxa orderbook get`	Current L2 order-book snapshot
`oxa orderbook history`	Historical L2 snapshots
`oxa trades fetch`	Trade history with cursor pagination
`oxa candles`	OHLCV candles
`oxa funding current` / `oxa funding history`	Current and historical funding
`oxa oi current` / `oxa oi history`	Current and historical open interest
`oxa instruments`	Venue instrument list
`oxa liquidations`	Liquidation history on Hyperliquid core, HIP-3, and both Lighter deployments
`oxa positions ...`	Account positions on Hyperliquid core, HIP-3, and both Lighter deployments: `get`, `history`, `changes`, `market`, `summary`, and `all`, plus `account` and `account-history` on Hyperliquid and HIP-3. See Account positions
`oxa accounts by-l1`	Lighter mainnet account indexes owned by an L1 address
`oxa summary`	Multi-signal market snapshot
`oxa prices`	Price history
`oxa freshness`	Per-symbol freshness
`oxa orders history` / `flow` / `tpsl`	Order lifecycle and flow routes for the chosen venue
`oxa l4 get` / `diffs` / `history`	L4 reconstruction and checkpoint routes
`oxa l3 get` / `history`	Lighter L3 depth
`oxa hip4 ...`	Outcome-market discovery, books, trades, candles, open interest, prices, summaries, and orders
`oxa spot ...`	Hyperliquid Spot pairs, books, trades, L4, orders, TWAP, and freshness
`oxa stream ...`	Live WebSocket subscriptions and stored replay, written as one JSON record per line

Use it in scripts

Stream or exit code	Meaning
stdout	JSON or pretty output from a successful command
stderr	Validation, auth, network, rate-limit, and internal errors
`0`	Command completed
`2`	Validation or argument error
`3`	Authentication error
`4`	Network, upstream API, or rate-limit error
`5`	Internal CLI error

oxa auth test 2>/dev/null && echo "ready"

oxa summary --exchange hyperliquid --symbol BTC --format json \
  | jq '{markPrice, oraclePrice, midPrice, fundingRate, openInterest, volume24h, timestamp}'

oxa freshness --exchange hyperliquid --symbol BTC --format json \
  | jq '{measuredAt, orderbook, trades, funding, openInterest, liquidations}'

Parse JSON only from stdout and treat stderr as the control channel. Keep any returned request_id or cursor in your logs, and branch on the exit code before retrying: stop on validation and auth errors, and retry network, upstream, and rate-limit errors with a bounded budget. Historical commands can return a nextCursor. Pass it back with --cursor for the next page, and keep the venue, symbol, window, and format arguments unchanged.

When to use something else

The CLI fits work with a command boundary: CI checks, cron jobs, notebook setup, incident response, local pulls, and coding agents that run shell commands. Inside a long-running application, an SDK or a direct REST client is easier to observe and test than a shelled-out CLI. In an AI client that supports MCP, the MCP server gives typed tools. For a large historical export, full backfill, or warehouse load, use Parquet files from the Data Catalog.

Next step

Find the route behind any command, with its parameters and response fields, in the Endpoint reference.

SDKs

MCP

Agent skill

AI agents

CLI

Inputs

Examples

Commands

Use it in scripts

When to use something else

Next step

​Inputs

​Examples

​Commands

​Use it in scripts

​When to use something else

​Next step

Inputs

Examples

Commands

Use it in scripts

When to use something else

Next step