Kamakura Quant Lab

AI エージェントに任せる

以下のセットアップと操作は、Claude Code や Codex などの AI コーディングエージェントに任せられます。 Komachi のリポジトリにエージェント向けの手引き（AGENTS.md）を 同梱しているため、Python の準備からトークンの設定、 コマンドの実行までその場で進められます。

git clone https://github.com/kamakuraquantlab/Komachi
cd Komachi
claude          # または codex など、お使いのエージェント

自然言語でそのまま指示できます。 手引きに用語の対応表を記載しているため、 「利用枠」「ダウンロード期間」「板情報」など、 このサイトで使っている言葉もそのまま通じます。

プロンプトの例

そのまま貼り付けてお使いいただけます。

はじめて使うとき

Komachi を使えるようにしてください。Python の用意から、
インストール、トークンの設定までお願いします。
トークンは hk_… です。

トークンはダウンロードのページでサインインすると発行されます。

何が取れるか調べる

収録されているマーケットと期間を一覧にしてください。
BTC の板情報がある取引所はどれですか。欠測している日付も教えてください。

取得する

COINCHECK:BTC_SPOT の 2025-07-01 から 1 週間分を取得したいです。
利用枠をいくつ消費するか先に教えてください。

利用枠を消費するのは取得のときだけです。 エージェントには、消費する数を示して確認を取ってから実行するよう指示しています。

取得したデータを見る

取得済みのデータを DuckDB で読めるようにして、
COINCHECK:BTC_SPOT の 2025-07-01 のスプレッドの推移を出してください。

うまくいかないとき

このエラーが出ました。原因と、次にすることを教えてください。
（エラーの全文を貼り付けてください）

期限切れや利用枠に関するご相談など、手元では解決しない内容は サポートまでご連絡ください。

Komachi: 1. インストール

Python 3.13 以降が必要です。

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

最初の実行では、データの保存先を尋ねられます。 答えは ~/.kamakuraquantlab.env に書き出され、その内容を表示して終了します。 もう一度同じコマンドを実行すると、そこから先に進みます。

パッケージ名は kamakuraquantlab-komachi、コマンド名は komachi です。 [duckdb] を付けない最小構成でもダウンロードはできますが、 取得したファイルを読むには必要です。

Komachi: 2. トークンを登録する

トークンはダウンロードのページで発行します。 注文番号とご購入時のメールアドレスでサインインし、「トークンを表示」を押してください。

komachi token set --token hk_…
komachi token status

token set はトークンを検証してから設定ファイル ~/.kamakuraquantlab.env に保存します（パーミッション 0600）。 token status は利用枠と期限を表示します。

Komachi: 3. 何が取得できるか確認する

komachi markets
komachi calendar --market COINCHECK:BTC_SPOT

markets はトークンで取得できるマーケットと、取り込める外部データ源を並べます。 calendar は対象マーケットの取得可能な日付と、すでに取得済みの日付を表示します。 どちらも利用枠を消費しません。

Komachi: 4. ダウンロードする

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

実行すると、取得する範囲、ファイルサイズ、消費する market-day を表示してから確認を求めます。 その時点ではまだ何も取得していません。

--days を省略すると、利用枠の範囲で取得できるだけ取得します。 中断した場合は同じコマンドをもう一度実行してください。 取得済みの分は再取得せず、追加の消費もありません。

Komachi: 5. 保存先とレイアウト

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

データレイクと同じ bronze レイアウトで保存します。 保存先は初回実行時に尋ねられ、既定は ~/kamakuraquantlab-data です。 答えは ~/.kamakuraquantlab.env に書かれ、Hase も同じファイルを読みます。 --root または環境変数 ROOT_PATH で上書きできます。

date= は日本時間の 1 日（15:00〜14:59 UTC）です。 ファイル内のタイムスタンプは UTC エポック秒です。 いま手元に何があるかは komachi local で確認できます。

Komachi: 6. DuckDB で読む

download と import は、ファイルを書いたあとに DuckDB のビューを自動で更新します。取り込みや変換の手順は要りません。 ファイルはそのままの場所で読まれます。

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

komachi sql はビューの定義を出力します。別のツールから読む場合に使ってください。 1 ファイルだけ確認したいときは komachi stats --path … と komachi decode --path … があります。

Komachi: 7. 外部データを取り込む

Binance と GMO コインは、いずれも自社の約定履歴を公開しています。 Komachi はそれらを取得して、同じ bronze レイアウトに変換します。利用枠は消費しません。

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

取り込めるのは約定履歴です。両取引所とも板情報は公開していないため、 板情報はMarket Archive でご提供しています。

Hase: 1. 何をするツールか

取得した bronze データから、分析に使える派生データを作ります。 入力と同じレイアウトで、同じルートの下に並べて保存します。

Hase はローカルのファイルだけを読みます。 API に接続せず、トークンを持たず、利用枠も消費しません。 手元にある bronze であれば、どこから来たものでも同じように扱います。

Hase: 2. インストールして生成する

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

生成済みの日付は再計算しません。作り直す場合は --recreate を付けてください。 hase local は、取得済みの bronze と生成済みの派生データを並べて表示します。

Hase を先にインストールした場合は、Komachi と同じように保存先を尋ねられ、 同じ ~/.kamakuraquantlab.env に書き出して終了します。 どちらを先に入れても、設定は 1 回で済みます。 Hase がこのファイルから読むのは保存先だけで、トークンは読みません。

MarketPrice の数量は基軸通貨建てで、既定は 0.002 BTC です （--execution-size）。 円建ての金額で歩かせる場合は --execution-notional 1000000 のように指定します。 数量は保存先のパスに含まれるため、条件の違う結果が混ざることはありません。

Hase: 3. 図にする

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 は最良気配とスプレッド、plot-trades は価格と売買別の出来高です。 軸のラベルは日本時間で、ファイルが切られた日付と一致します。