Skip to main content
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. 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.
1

Run one auth check

npx @0xarchive/cli auth test
2

Install it for repeated use

npm install -g @0xarchive/cli
3

Set the CLI key

export OXA_API_KEY="0xa_your_api_key"
4

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.
InputCLI shapeNotes
API keyOXA_API_KEYStore it in the shell, CI secret store, or ignored local environment file
Venue scope--exchange hyperliquid, --exchange 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
SymbolBTC, ETH, km:US500, 0, HYPE-USDCKeep HIP-3 prefixes case-sensitive; use bare numeric HIP-4 outcome IDs where possible
Window--start, --end, --interval, --limit, --cursorStart with a small bounded window, then paginate or widen after the first response looks right
Output--format jsonJSON is the safest default for agents, CI, notebooks, and downstream scripts

​
Command Model

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

​
Where The CLI Fits

JobUse the CLI whenUse something else when
Shell automationThe output should go to jq, a file, cron, CI, or a notebook setup stepThe integration lives inside long-running application code
Coding-agent workThe agent can run terminal commands and inspect JSONThe host supports MCP and typed tools are a better fit
Data checksYou need a bounded route, freshness check, or auth probe fastYou need full route/schema generation before writing code
Incident workYou need stable stdout, stderr, and exit codesYou need a dashboard or browser-first debugging surface

​
Command Inventory

CommandCoverage
oxa auth testVerify the key and optionally test a venue/symbol pair
oxa orderbook getCurrent L2 order-book snapshot
oxa orderbook historyHistorical L2 snapshots
oxa trades fetchTrade history with cursor pagination
oxa candlesOHLCV candles
oxa funding current / oxa funding historyCurrent and historical funding
oxa oi current / oxa oi historyCurrent and historical open interest
oxa instrumentsVenue instrument list
oxa liquidationsLiquidation history where the venue family supports it
oxa summaryMulti-signal market snapshot
oxa pricesPrice history
oxa freshnessPer-symbol freshness
oxa orders history / flow / tpslOrder lifecycle and flow routes where the plan allows them
oxa l4 get / diffs / historyL4 reconstruction and checkpoint routes
oxa l3 get / historyLighter 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 supported realtime jobs

​
Automation Contract

StreamBehavior
stdoutJSON or pretty output from successful commands
stderrValidation, auth, network, rate-limit, and internal errors
exit code 0Command completed
exit code 2Validation or argument error
exit code 3Authentication error
exit code 4Network, upstream API, or rate-limit error
exit code 5Internal CLI error
oxa auth test 2>/dev/null && echo "ready"

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

oxa freshness --exchange hyperliquid --symbol BTC --format json \
  | jq '.data'

​
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.
Last modified on June 28, 2026