/backtest

name: 0xarchive-backtest
version: 0.1.0
description: >
  Quant research and backtesting on 0xArchive data, done the way a careful desk does it: hand over a
  wallet, a trading idea, a tweet, a Pine or TS script, a paper, someone else's backtest, or a strategy
  file, and get a verdict with receipts. Reverse engineers a trader's style from their fills and scores how
  much of their book a strategy reproduces; tests whether a trader or a strategy is skilled or lucky.
  Every run goes into a trial ledger, the last months stay sealed until one candidate is committed, and
  nothing is called an edge until it passes costs, nulls, out-of-sample and walk-forward tests and a
  deflated Sharpe over every try. Uses the 0xarchive-backtest engine (0xbt) on Hyperliquid perps.
  Use for backtest, "is this edge real", test this strategy, reverse engineer this wallet, vault or trader, port
  this Pine script, audit this backtest, find me a strategy, or paper trade a strategy.
allowed-tools: Bash, Read, Write, Edit
argument-hint: "a wallet, an idea, a script or a strategy file, e.g. 'reverse engineer 0x...', 'does funding predict reversals', 'audit backtest.py'"
metadata: {"openclaw":{"requires":{"env":["OXARCHIVE_API_KEY"]},"primaryEnv":"OXARCHIVE_API_KEY"}}

0xArchive Backtest

Turn one sentence into a quant study: a testable spec, the cheapest evidence first, a backtest with every cost in, a gauntlet of checks, and a verdict the user can rerun from its receipt.

The engine ships inside this skill, in `engine/`: a Rust backtester with a Python strategy API, the `0xbt` command, imported as `oxarchive_backtest` (usually `as oxb`). It is deterministic: the same engine, dataset, strategy source and params give the same result hash on every machine, so a result is a claim anyone can check. Market data questions outside a backtest belong to the `0xarchive` skill (the API reference).

Before the first run

Check once per session, and only what the route needs. Paths below are relative to this skill's directory.

1. **The engine:** `0xbt --version` should print `0xbt 0.3.2`. If it's missing or older, install it into the project's Python environment (Python 3.12 or later; prebuilt for macOS, Linux and Windows):

   pip install "0xarchive-backtest[curated]==0.3.2"

On a platform without a prebuilt wheel, pip builds it from source, which needs Rust (`cargo --version`; ask the user before installing it from https://rustup.rs). `engine/` beside this skill is the same source. Never write a substitute backtester. 2. **The API key:** `$OXARCHIVE_API_KEY` must be set for pulling data and for the trader route. Never print it. Free keys read only the last 30 days; longer backtests need a paid plan. 3. **The data:** minute Parquet files, `data/hyperliquid/<MARKET>/<YYYY-MM>.parquet`. Use what is in the working directory, or pull what the study needs:

   0xbt data pull --markets BTC,ETH,SOL --from 2025-03 --to 2026-09     # into data/hyperliquid
   0xbt hourly                                                           # for universe rules

A pull costs about 30 requests per market per month (a year of one market is about 350). Tell the user the markets and months before a large pull. Never invent or synthesize market data for a verdict. A strategy over `x.top_n` needs every market it could pick, so pull the candidates.

Route the input first

Pick the route from what the user handed over, then read only that reference.

| Input | Route | Read | |---|---|---| | A wallet or vault address, or a Lighter account index | Reverse engineer the trader | [references/traders.md](references/traders.md) | | A one-line idea, a tweet, a thread, a claim | Write it as a spec, then test it | [references/ideas.md](references/ideas.md) | | A paper or PDF | Extract the rules into a spec, then as an idea | [references/ideas.md](references/ideas.md) | | A Pine Script or TS indicator | Port it to oxb, then test it | [references/ports.md](references/ports.md) | | Code from another framework (backtrader, vectorbt, freqtrade, zipline, a notebook) | Audit the original, port it, test it | [references/audit.md](references/audit.md), [references/ports.md](references/ports.md) | | A strategy file for oxb | `0xbt check`, then the gauntlet | [references/gauntlet.md](references/gauntlet.md) | | "Find me something", an open search | Exploration with a declared budget | [references/exploration.md](references/exploration.md) |

Every route ends in the gauntlet ([references/gauntlet.md](references/gauntlet.md)). Column names, coverage dates and what the dataset cannot express are in [references/data.md](references/data.md); how to write a strategy is in [references/strategy-api.md](references/strategy-api.md).

If the user says only "my strategy" or "this wallet" with nothing attached or named in the conversation, ask which one. Never pick an example on their behalf.

The rules

These are what make the result worth posting. They hold on every route.

1. **Start a study before the first backtest of a new question:** `0xbt study init` in the working directory. From then on every backtest, sweep and gauntlet below that directory is written to `.0xarchive/trials.jsonl`, and the last three months of data (or `--holdout DATE`) are sealed. Never edit, move or delete `.0xarchive/`, and never run backtests from outside the study directory to avoid it. One question per study; a new question gets a new directory. 2. **Never read the Parquet files directly** (pandas, pyarrow, duckdb). For event studies and research reads, use `oxb.Source(DIR).rows(market, start, end, columns=[...])`, which goes through the seal. 3. **Write the spec before the first run**, in `STUDY.md` beside `.0xarchive/`: the hypothesis in one sentence, the universe, clock, signal, sizing, costs and window, and the result that would kill it. Do not change the kill condition after seeing results. 4. **Cheap