Kamakura Quant Lab

Hand it to an AI agent

Everything below can be done by a coding agent such as Claude Code or Codex. The Komachi repository ships a briefing for them (AGENTS.md), so an agent can install Python, install the tool, set your token and run commands without you reading the rest of this page.

git clone https://github.com/kamakuraquantlab/Komachi
cd Komachi
claude          # or codex, or whichever agent you use

Ask in natural language. The briefing carries a glossary of the terms used here, so allowance, download period and order book mean the same thing to the agent as they do to you.

Example prompts

Paste any of these as they are.

Starting from nothing

Set Komachi up for me: Python, the install, and my token.
My token is hk_…

Your token comes from signing in on the download page.

Finding out what exists

List the markets and the dates they cover. Which venues have
BTC order book depth, and which days are missing?

Fetching

I want a week of COINCHECK:BTC_SPOT from 2025-07-01.
Tell me what it costs before you fetch anything.

Fetching is the only thing that spends from your allowance. The briefing tells the agent to state the cost and wait for you.

Looking at what you fetched

Make what I downloaded queryable in DuckDB, then show me how the
spread moved on COINCHECK:BTC_SPOT on 2025-07-01.

When something fails

I got this error. What caused it and what should I do next?
(paste the whole message)

Anything an agent cannot settle — a deadline that has passed, a question about your allowance — belongs with support.

Komachi: 1. Install

Python 3.13 or later.

pip install 'kamakuraquantlab-komachi[duckdb]'
komachi local

The first run asks where downloaded data should go, writes ~/.kamakuraquantlab.env, shows you the file and stops. Run the command again and it carries on from there.

The package is kamakuraquantlab-komachi and the command is komachi. Without [duckdb] you can still download; you need it to read what you downloaded.

Komachi: 2. Register your token

Issue a token on the download page: sign in with your order number and the email you bought with, then press "Show my token".

komachi token set --token hk_…
komachi token status

token set verifies the token before storing it in ~/.kamakuraquantlab.env at mode 0600, the same file that holds your data root. token status shows the allowance left and when it ends.

Komachi: 3. See what you can fetch

komachi markets
komachi calendar --market COINCHECK:BTC_SPOT

markets lists what the token covers, and the external sources alongside. calendar shows which dates exist for a market and which you already hold. Neither spends anything.

Komachi: 4. Download

komachi download --market COINCHECK:BTC_SPOT --start 2025-07-01 --days 28

It prints the range, the size and the market-days it will cost, then asks before fetching anything.

Without --days it takes as much as the remaining allowance covers. If a run stops part way, run the same command again: what arrived is not fetched twice and costs nothing further.

Komachi: 5. Where the files land

<root>/bronze/dataset=Trade/exchange=COINCHECK/symbol=BTC_SPOT/date=2025-07-01/data.parquet

A bronze data-lake layout, the same one the archive was built in. You are asked for the root on first run, defaulting to ~/kamakuraquantlab-data; the answer goes in ~/.kamakuraquantlab.env, which Hase reads too. Override it with --root or ROOT_PATH.

A date= partition is an Asia/Tokyo day, 15:00–14:59 UTC, and timestamps inside the files are UTC epochs. komachi local says what you currently hold.

Komachi: 6. Query it with DuckDB

download and import refresh the DuckDB views themselves whenever they write anything, so there is no step here. No import and no conversion either: the files are read where they lie.

SELECT date, count(*) AS trades
FROM trade
WHERE exchange = 'COINCHECK' AND symbol = 'BTC_SPOT'
GROUP BY date ORDER BY date;

komachi sql prints the view definitions for use from another tool. For a single file, komachi stats --path … and komachi decode --path ….

Komachi: 7. Import the external sources

Binance and GMO Coin each publish their own trade history. Komachi fetches it and converts it into the same bronze layout. It spends no allowance.

komachi import --market BINANCE:BTC_USDT --start 2025-07-01 --end 2025-07-28
komachi import --market GMO:BTC_JPY     --start 2025-07-01 --end 2025-07-28

What you can import is the trades. Neither venue publishes its order book, so the depth for both is in Market Archive.

Hase: 1. What it does

Turns the bronze you hold into datasets analysis can use, written beside it under the same root in the same layout.

Hase reads local files only. It reaches no API, holds no token, and spends no allowance. Point it at any bronze tree you have and it behaves the same.

Hase: 2. Install and derive

pip install kamakuraquantlab-hase

hase derive BookState   --market COINCHECK:BTC_SPOT --start 2025-07-01 --end 2025-07-28
hase derive MarketPrice --market COINCHECK:BTC_SPOT --start 2025-07-01 --end 2025-07-28
hase derive VolSpread   --market COINCHECK:BTC_SPOT --start 2025-07-01 --end 2025-07-28

hase local --market COINCHECK:BTC_SPOT

A day already derived is left alone; pass --recreate to rebuild it. hase local lists the bronze you hold and the derived data beside it.

If you install Hase first, it asks the same question Komachi does and writes the same ~/.kamakuraquantlab.env, so whichever tool you reach for first is the only one that asks. Hase reads only the data root from that file, never the token.

MarketPrice takes its size in base currency, 0.002 BTC by default (--execution-size). To walk to a cash amount instead, --execution-notional 1000000. The size is part of the output path, so two of them never overwrite each other.

Hase: 3. Plot it

hase plot-book   --market COINCHECK:BTC_SPOT --date 2025-07-01 --output book.png
hase plot-trades --market COINCHECK:BTC_SPOT --date 2025-07-01 --output trades.png

plot-book draws best bid and ask with the spread beneath; plot-trades draws price with buy and sell volume. Axes are labelled in JST, matching the day the file was cut in.