Hyperliquid module — quick start

Technical quick start for the Hyperliquid intelligence module — install, run the search backend, hit the API.

This page covers the technical quick start for the Hyperliquid intelligence module that powers Axe's Hyperliquid surface. For operator setup of the Axe cockpit itself, see Environment.

Prerequisites

Python 3.11+
A bridge directory (artifact channel from RL research)
BigQuery credentials (for live queries; not needed for --dry-run)

Installation

cd work/hlq
pip install -e .

For development:

pip install -e ".[dev]"

Verify the bridge

hlq bridge status

Expected output (healthy bridge):

version: 20260223T015855Z_hlq_reqs_v2
format_version: 1.0.0
actions: 12
ann_items: 1806
sql_templates: 7
health: healthy

Run a dry-run search

Dry-run compiles SQL without executing against BigQuery:

hlq search "high leverage BTC traders" --dry-run --format json

This shows:

intent_family — How the query was classified (e.g., risk_regime)
template_name — Which SQL template was selected
sql — The compiled SQL that would be executed
coverage — Which query constraints were applied vs dropped
provenance — Bridge version, ANN snapshot size, timestamp

Run a live search

Requires BigQuery credentials (ADC or gcloud auth):

hlq search "riskiest ETH traders right now" --top 10

Remote backend

Set HLQ_BACKEND_URL to run against a deployed backend without local bridge dependencies:

export HLQ_BACKEND_URL=http://your-server:8420
hlq search "top BTC whales"

Both CLI and MCP tools respect this environment variable.

MCP server

# stdio transport (for Claude Desktop / agent integration)
python -m hlq.api.mcp --transport stdio
 
# HTTP transport (for remote clients)
python -m hlq.api.mcp --host 0.0.0.0 --port 8420

Environment variables

Variable	Purpose	Default
`HLQ_BACKEND_URL`	Remote backend endpoint. When set, CLI/MCP use `RemoteBackend` (HTTP) instead of local pipeline.	unset (local mode)
`HLQ_TRAJECTORY_LOG_DIR`	Directory for trajectory JSONL logging. When set, search calls write episodes, steps, and artifacts.	unset (logging disabled)
`GOOGLE_APPLICATION_CREDENTIALS`	Path to BigQuery service account key (alternative to gcloud ADC).	unset (uses ADC)

Troubleshooting

BigQuery auth fails:

DefaultCredentialsError: Could not automatically determine credentials.

Run gcloud auth application-default login or set GOOGLE_APPLICATION_CREDENTIALS.

Bridge not found:

FileNotFoundError: bridge/manifest.json

Ensure the bridge/ directory is present in your working directory. Bootstrap from GCS (see below) or symlink to an existing bridge.

Address not in ANN index: If you search for a specific address and get 0 results, the address may not be in the 1,806-item ANN index. Check with hlq bridge status to see the index size. Use --dry-run to verify the query compiles correctly.

Intent misclassification: The current classifier is regex-based (regex_v1). If a query routes to the wrong intent, try rephrasing. Check the intent_family field in the response or dry-run output. See Status & Roadmap for the classifier improvement plan.

GCS retrieval

HLQ repo snapshots are stored in GCS. To bootstrap on a new machine:

# Git bundle (full history)
gsutil cp gs://artemis-hl/hlq/bootstrap/hlq-20260226T075956Z.bundle /tmp/
git clone /tmp/hlq-20260226T075956Z.bundle hlq
 
# Or tarball (working tree only)
gsutil cp gs://artemis-hl/hlq/bootstrap/hlq-20260226T075956Z.tar.gz /tmp/
mkdir hlq && cd hlq && tar xzf /tmp/hlq-20260226T075956Z.tar.gz

Hyperliquid module — quick start

On this page