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

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

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

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.

CommandWhat it returns
oxa auth testVerify API key
oxa orderbook getL2 orderbook snapshot
oxa orderbook historyHistorical orderbook snapshots with pagination
oxa trades fetchTrade history (with --cursor pagination)
oxa candlesOHLCV candle data (1m to 1w intervals)
oxa funding currentCurrent funding rate
oxa funding historyFunding rate history
oxa oi currentCurrent open interest
oxa oi historyOpen interest history
oxa instrumentsList available instruments/coins
oxa liquidationsLiquidation history (Hyperliquid only)
oxa summaryMulti-signal snapshot in one call
oxa pricesMark/oracle/mid price history
oxa freshnessData freshness per data type
oxa orders historyOrder history with user attribution (Pro+ on Hyperliquid, HIP-3, and HIP-4)
oxa orders flowOrder flow aggregation (Pro+ on Hyperliquid, HIP-3, and HIP-4)
oxa orders tpslTP/SL order history (Pro+ on Hyperliquid, HIP-3, and HIP-4)
oxa l4 getL4 orderbook reconstruction (Pro+ on Hyperliquid, HIP-3, and HIP-4)
oxa l4 diffsL4 diff stream history (Pro+ on Hyperliquid, HIP-3, and HIP-4)
oxa l4 historyL4 checkpoint history (Build+ on Hyperliquid, HIP-3, and HIP-4)
oxa l3 getLighter L3 order-level snapshot (Pro+)
oxa l3 historyLighter L3 order-level history (Pro+)

CLI package

Install globally or run once with npx from the fast-start commands.

Install commands

GitHub

Source code and contribution guide.

GitHub

Authentication

Dashboard-managed keys are the normal way to auth the CLI.

Authentication

Where to use the CLI next

AI ClientsUse these when the job belongs in Claude or another MCP client.Wallet AutomationUse this when the script has to create, revoke, or upgrade keys from a wallet.REST APIOpen the route reference for parameters, credits, and examples.