CLI

Use the CLI when the job belongs in a terminal: local checks, cron, CI, notebooks, incident terminals, and coding-agent shells with command access. The package is @0xarchive/cli. The binary is oxa. It requires Node.js >=18; streaming commands require Node.js 22+. Install a published package version, then confirm it with oxa --version before pinning that version in automation. The CLI uses OXA_API_KEY. Source: 0xArchiveIO/0xarchive-cli. Use this page as the shell contract: pick a venue scope, pass an explicit symbol and window, request JSON for machine consumers, and branch on exit codes instead of scraping terminal text.

Install the CLI

npm install -g @0xarchive/[email protected]

This page matches CLI version 1.10.0. For a one-off command without a global install, use the npx form shown in the auth step after the key is set.

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, use npx @0xarchive/[email protected] auth test --exchange hyperliquid --symbol BTC --format json.

Pull one market payload

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

Preflight Checklist

Before wiring the CLI into a script, make these inputs explicit.

Input	CLI shape	Notes
API key	`OXA_API_KEY`	Store it in the shell, CI secret store, or ignored local environment file
Venue scope	`--exchange hyperliquid`, `--exchange lighter`, `--exchange rh-lighter`, `--exchange hip3`, `--exchange hip4`, or `oxa spot ...`	HIP-3 and HIP-4 are Hyperliquid-scoped market families, but the CLI exposes convenience scopes for them. `rh-lighter` is Lighter on Robinhood Chain, Lighter’s second deployment
Symbol	`BTC`, `ETH`, `km:US500`, `0`, `HYPE-USDC`	Keep HIP-3 prefixes case-sensitive; use bare numeric HIP-4 outcome IDs where possible
Window	`--start`, `--end`, `--interval`, `--limit`, `--cursor`	Start with a small bounded window, then paginate or widen after the first response looks right
Output	`--format json`	JSON is the safest default for agents, CI, notebooks, and downstream scripts

Command Model

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

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

oxa candles --exchange hip3 --symbol km:US500 \
  --start 2026-03-01T00:00:00Z \
  --end 2026-03-02T00:00:00Z \
  --interval 1h \
  --format json

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

oxa spot pairs --format json

Where The CLI Fits

Job	Use the CLI when	Use something else when
Shell automation	The output should go to `jq`, a file, cron, CI, or a notebook setup step	The integration lives inside long-running application code
Coding-agent work	The agent can run terminal commands and inspect JSON	The host supports MCP and typed tools are a better fit
Data checks	You need a bounded route, freshness check, or auth probe fast	You need full route/schema generation before writing code
Incident work	You need stable stdout, stderr, and exit codes	You need a dashboard or browser-first debugging surface

Command Inventory

Command	Coverage
`oxa auth test`	Verify the key and optionally test a venue/symbol pair
`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 configured venue scopes
`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, OI, prices, summaries, and orders
`oxa spot ...`	Hyperliquid Spot pairs, books, trades, L4, orders, TWAP, and freshness
`oxa stream ...`	Stream commands for live and replay jobs

Automation Contract

Stream	Behavior
stdout	JSON or pretty output from successful commands
stderr	Validation, auth, network, rate-limit, and internal errors
exit code `0`	Command completed
exit code `2`	Validation or argument error
exit code `3`	Authentication error
exit code `4`	Network, upstream API, or rate-limit error
exit code `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}'

Pagination And Failure Handling

Historical commands can return a nextCursor. Pass that value back with --cursor for the next page, and keep the original venue, symbol, window, and format arguments unchanged unless you choose a broader request. Treat stdout as the data channel and stderr as the control channel. For unattended jobs, parse JSON only from stdout, preserve any returned request_id or cursor in logs, and branch on the exit code before retrying. Validation and auth failures should stop the job; network, upstream API, and rate-limit failures can use bounded retries.

Choose Data Catalog Instead

Use Data catalog when the job is a large historical export, full backfill, Parquet workflow, or warehouse load. The CLI is strongest for point queries, moderate pulls, freshness checks, scripted probes, and terminal-native incident work.

Why 0xArchive Fits

The CLI exposes the same market-data jobs as the API in a shell shape: venue selection, symbol selection, bounded history, freshness checks, JSON output, and deterministic command failure.

Production Notes

Use the CLI when a workflow wants a command boundary: CI checks, cron jobs, notebook setup, incident response, local exports, or coding-agent terminal work. Keep command arguments explicit, prefer --format json for machine consumers, and send JSON through jq or a script instead of scraping human text. Do not use the CLI as a hidden dependency inside a long-running application server if an SDK or REST client would be easier to observe and test. The CLI is strongest when process exit codes, stdout, stderr, and shell composition are the product requirement.

Next Step

Use Choose an interface to compare CLI with MCP, Skill, SDKs, REST, and OpenAPI. Use OpenAPI when you need generated clients or route/schema contract.

API reference

SDKs & tooling

AI & agents

Preflight Checklist

Command Model

Where The CLI Fits

Command Inventory

Automation Contract

Choose Data Catalog Instead

Why 0xArchive Fits

Production Notes

Next Step

​Preflight Checklist

​Command Model

​Where The CLI Fits

​Command Inventory

​Automation Contract

​Pagination And Failure Handling

​Choose Data Catalog Instead

​Why 0xArchive Fits

​Production Notes

​Next Step

Preflight Checklist

Command Model

Where The CLI Fits

Command Inventory

Automation Contract

Pagination And Failure Handling

Choose Data Catalog Instead

Why 0xArchive Fits

Production Notes

Next Step