--- title: "CLI | 0xArchive Docs" description: "Install the 0xArchive CLI, authenticate once, and run JSON-first commands for venue data, coverage checks, replay, and automation." canonical_url: "https://www.0xarchive.io/docs/cli/" markdown_url: "https://www.0xarchive.io/docs/cli.md" route: "/docs/cli" robots: "index, follow" generated_from: "prerendered_html" --- # CLI Shell-native access to the same routes, with JSON output and stable exit codes. Use it for Shell, cron, CI, incident work Output JSON on stdout Start with auth test [Fast start](https://www.0xarchive.io/docs/cli/#fast-start) [Automation contract](https://www.0xarchive.io/docs/cli/#automation-contract) Use the CLI when shell is the operating model: check auth once, run one JSON command, then reuse it in cron, CI, or incident work. It is the right fit for bash, jq, cron, and CI. AI Clients are better for prompt-driven access. Wallet automation is for wallet-owned signup, keys, and billing. ## Choose the shell job Choose by job type, not by command count. [Fastest check One-off shell check Quickest way to confirm the CLI on a fresh machine. Best for Checking one route, validating a payload shape, or checking access on a new machine. Do not use if You already know the CLI works and need a repeatable scheduled or CI pattern instead. Time to first result 1-3 minutes First command `npx @0xarchive/cli auth test` Jump to fast start](https://www.0xarchive.io/docs/cli/#fast-start) [Repeatable automation Cron or CI Stable JSON output and exit codes for recurring shell jobs. Best for Scheduled snapshots, freshness gates, CI smoke checks, and lightweight export jobs. Do not use if You need multi-client prompt access or interactive tooling rather than shell-native execution. Time to first result 3-6 minutes First command `oxa summary --exchange hyperliquid --symbol BTC --format json` See automation contract](https://www.0xarchive.io/docs/cli/#automation-contract) [Operator recovery Incident debugging Focused health and market-state calls during an incident. Best for Verifying whether the issue is auth, lag, route health, or the downstream job itself. Do not use if A browser playground or typed SDK setup is easier for the task than ad hoc terminal work. Time to first result 2-4 minutes First command `oxa freshness --exchange hyperliquid --symbol BTC` See scenarios](https://www.0xarchive.io/docs/cli/#jobs) ## Fast start Install or use npx, set the key, check auth, then run one JSON command. ### First run This is the shortest route from a fresh machine to a stable command. 1. 1 You Install globally or use npx Use npx for a quick check or install globally if the machine will keep the CLI around. `npx @0xarchive/cli auth test` 2. 2 You Expose the API key Set the API key in the environment so every follow-on command can reuse it without interactive prompts. `export OXA_API_KEY="0xa_your_api_key"` 3. 3 CLI Verify auth first Start every fresh environment with auth test. Fix auth first, then debug individual routes. `oxa auth test` 4. 4 CLI Run one JSON command Pick a narrow current-state command, inspect the JSON, then script around it. `oxa summary --exchange hyperliquid --symbol BTC --format json` 5. 5 0xArchive Promote the exact command into automation Reuse the same command in cron, CI, or incident tooling once auth, JSON shape, and exit-code behavior look right locally. Stable stdout JSON, structured stderr on failures, and deterministic exit codes for automation. Install globally Bash ``` npm install -g @0xarchive/cli ``` Run without installing Bash ``` npx @0xarchive/cli auth test ``` Set and verify auth Bash ``` # Set your API key export OXA_API_KEY="0xa_your_api_key" # Verify it works oxa auth test ``` ## Operational jobs These are good shell-native jobs for the CLI. ### Summary snapshot Goal Grab one current-state payload that includes price, funding, open interest, and volume. Command or route `oxa summary --exchange hyperliquid --symbol BTC --format json` Expected output A single JSON object you can inspect or pipe into jq. Next step Reuse the same command in cron, CI, or an incident runbook once the JSON looks right. ### Candles export Goal Pull a bounded historical slice for a backtest or local analysis. Command or route `oxa candles --exchange hyperliquid --symbol ETH --start 2026-02-01T00:00:00Z --end 2026-03-01T00:00:00Z --interval 4h --out candles.json` Expected output A saved JSON file containing the requested OHLCV range. Next step Feed the file into a backtest, or switch to replay if timing fidelity matters more. ### Freshness gate Goal Check lag before running a larger pull, alert, or trade-sensitive job. Command or route `oxa freshness --exchange hyperliquid --symbol BTC | jq '.orderbook.lagMs < 5000'` Expected output A boolean gate or freshness payload you can use in automation. Next step Fail closed if freshness misses your threshold, then check status or incident routes. ### Instrument scan Goal List the current venue universe before fanning out over symbols. Command or route `oxa instruments --exchange hyperliquid | jq '.[].name'` Expected output A stream of symbol names you can feed into the next loop or selection step. Next step Apply the same pattern to the venue you actually operate against, then fan out. ### Advanced L4 or L3 pull Goal Use deeper order-level routes only after current-state auth and shape are already confirmed. Command or route `oxa l4 history --exchange hyperliquid --symbol BTC --start 2026-03-01T00:00:00Z --end 2026-03-02T00:00:00Z` Expected output A route-specific payload for reconstruction or deeper debugging. Next step Check the route cost and entitlement, then decide whether it belongs in a recurring job. ## Automation contract Stdout, stderr, and exit codes are part of the public shell interface. stdout ### Machine-readable JSON Use JSON on stdout for jq, shell scripts, cron, and CI. Keep pretty output for humans only. stderr ### Structured failure channel Validation, auth, network, and internal errors belong on stderr so you can branch on them without parsing success output. Exit codes ### Deterministic automation contract 0 success, 2 validation, 3 auth, 4 network, 5 internal. Treat these as part of the public shell interface. Shell pattern Bash ``` # Verify API access oxa auth test 2>/dev/null && echo "ready" # Get multi-signal snapshot oxa summary --exchange hyperliquid --symbol BTC \ | jq '{price: .markPrice, funding: .fundingRate, oi: .openInterest}' # Scan all coins oxa instruments --exchange hyperliquid | jq '.[].name' # Fetch candles for backtesting oxa candles --exchange hyperliquid --symbol ETH \ --start 2026-01-01T00:00:00Z --end 2026-02-01T00:00:00Z \ --interval 4h --out candles.json # Gate on data freshness before acting oxa freshness --exchange hyperliquid --symbol BTC \ | jq '.orderbook.lagMs < 5000' ``` ## Command inventory Reference list for the shipped CLI commands. Use JSON for scripts and pretty output for humans. | Command | What it returns | | --- | --- | | `oxa auth test` | Verify API key | | `oxa orderbook get` | L2 orderbook snapshot | | `oxa orderbook history` | Historical orderbook snapshots with pagination | | `oxa trades fetch` | Trade history (with --cursor pagination) | | `oxa candles` | OHLCV candle data (1m to 1w intervals) | | `oxa funding current` | Current funding rate | | `oxa funding history` | Funding rate history | | `oxa oi current` | Current open interest | | `oxa oi history` | Open interest history | | `oxa instruments` | List available instruments/coins | | `oxa liquidations` | Liquidation history (Hyperliquid only) | | `oxa summary` | Multi-signal snapshot in one call | | `oxa prices` | Mark/oracle/mid price history | | `oxa freshness` | Data freshness per data type | | `oxa orders history` | Order history with user attribution (Pro+ on Hyperliquid, HIP-3, and HIP-4) | | `oxa orders flow` | Order flow aggregation (Pro+ on Hyperliquid, HIP-3, and HIP-4) | | `oxa orders tpsl` | TP/SL order history (Pro+ on Hyperliquid, HIP-3, and HIP-4) | | `oxa l4 get` | L4 orderbook reconstruction (Pro+ on Hyperliquid, HIP-3, and HIP-4) | | `oxa l4 diffs` | L4 diff stream history (Pro+ on Hyperliquid, HIP-3, and HIP-4) | | `oxa l4 history` | L4 checkpoint history (Build+ on Hyperliquid, HIP-3, and HIP-4) | | `oxa l3 get` | Lighter L3 order-level snapshot (Pro+) | | `oxa l3 history` | Lighter L3 order-level history (Pro+) | ### CLI package Install globally or run once with npx from the fast-start commands. [Install commands](https://www.0xarchive.io/docs/cli/#fast-start) ### GitHub Source code and contribution guide. [GitHub](https://github.com/0xArchiveIO/0xarchive-cli) ### Authentication Dashboard-managed keys are the normal way to auth the CLI. [Authentication](https://www.0xarchive.io/docs/authentication/) ### Where to use the CLI next [AI Clients Use these when the job belongs in Claude or another MCP client.](https://www.0xarchive.io/docs/ai-clients/) [Wallet Automation Use this when the script has to create, revoke, or upgrade keys from a wallet.](https://www.0xarchive.io/docs/wallet-automation/) [REST API Open the route reference for parameters, credits, and examples.](https://www.0xarchive.io/docs/rest-api/)