Tools

Two command-line tools. Komachi fetches the data; Hase turns it into the derived datasets analysis actually runs on. Both are Python packages under Apache License 2.0.

Tool	Does	PyPI
Komachi	Fetch: download, import external sources, check files	`kamakuraquantlab-komachi`
Hase	Analyse: derive silver and gold, plot	`kamakuraquantlab-hase`

Tested on Linux and macOS, Python 3.13 or later. Not tested on Windows, and not on Python 3.12 or earlier. They may well work, but we have no environment to check on, so those are outside what we support.

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

From here on is the same ground, done by hand.

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, when the download period ends, and which market-days you have already taken.

Komachi: 3. See what you can fetch

komachi markets

Per market: the datasets it holds, the span it covers and the days missing inside that span. Below it, the sources we do not sell because the venue publishes them itself — Binance and GMO trades — with the command that imports them. Neither spends anything. komachi local says what is already on your disk.

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.

To look inside a file you just fetched: komachi trades --market COINCHECK:BTC_SPOT --date 2025-07-01, or komachi book for the depth. download and import refresh the DuckDB views themselves whenever they write anything, so what arrives is queryable with no conversion step.

Komachi: 6. 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 --days 28
komachi import --market GMO:BTC_JPY     --start 2025-07-01 --days 28

Addressed the same way as download. The venues cut the day differently from each other; the import re-cuts onto the JST boundary, so what arrives lines up with the rest of the archive. What you can import is the trades. Neither venue publishes its order book, so the depth for both is in Market Archive.

Source and documentation

Both are published under Apache License 2.0, so you can read exactly what they do with your token and your machine before running them.

Komachi, Hase. If something does not work, get in touch.