> ## Documentation Index
> Fetch the complete documentation index at: https://docs.0xarchive.io/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI

> Install @0xarchive/cli and run shell-native market-data commands with JSON output, route discovery, API keys, and freshness checks.

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](https://github.com/0xArchiveIO/0xarchive-cli).

<Steps>
  <Step title="Install the CLI">
    ```bash theme={"theme":"github-dark"}
    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.
  </Step>

  <Step title="Set the CLI key">
    ```bash theme={"theme":"github-dark"}
    export OXA_API_KEY="0xa_your_api_key"
    ```
  </Step>

  <Step title="Run one auth check">
    ```bash theme={"theme":"github-dark"}
    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`.
  </Step>

  <Step title="Pull one market payload">
    ```bash theme={"theme":"github-dark"}
    oxa orderbook get --exchange hyperliquid --symbol BTC --format json
    ```
  </Step>
</Steps>

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

<CodeGroup>
  ```bash Hyperliquid order book theme={"theme":"github-dark"}
  oxa orderbook get --exchange hyperliquid --symbol BTC --format json
  ```

  ```bash Lighter trades theme={"theme":"github-dark"}
  oxa trades fetch --exchange lighter --symbol BTC --limit 50 --format json
  ```

  ```bash HIP-3 candles theme={"theme":"github-dark"}
  END=$(( $(date +%s) * 1000 ))
  oxa candles --exchange hip3 --symbol xyz:XYZ100 \
    --start $(( END - 86400000 )) \
    --end $END \
    --interval 1h \
    --format json
  ```

  ```bash HIP-4 outcomes theme={"theme":"github-dark"}
  oxa hip4 outcomes list --settled false --format json
  ```

  ```bash Spot pairs theme={"theme":"github-dark"}
  oxa spot pairs --format json
  ```

  ```bash Live trades for 10 seconds theme={"theme":"github-dark"}
  oxa stream trades BTC --duration-ms 10000
  ```
</CodeGroup>

## 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](/rest-api/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 |

```bash theme={"theme":"github-dark"}
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](/sdks) 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](/mcp-server) gives typed tools. For a large historical export, full backfill, or warehouse load, use Parquet files from the [Data Catalog](/data-catalog).

## Next step

Find the route behind any command, with its parameters and response fields, in the [Endpoint reference](/api-reference).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.