Komachi

鎌倉クオンツラボのコマンドラインクライアントです。 ヒストリカル市場データを取得し、DuckDB からそのまま参照できる構成で保存します。

English README

Kamakura Quant Lab のデータは、2 つの方法で取得できます。 収録範囲、スキーマ、品質基準はデータのページに記載しています。

ブラウザ — tsurugaoka

数日分を確認する用途に適しています。1 ファイルずつ、ブラウザの保存先に保存されます。

コマンドライン — Komachi（本リポジトリ）

Yukinoshita API（yukinoshita.kamakuraquantlab.jp）を呼び出すクライアントです。 まとまった量を扱う場合はこちらを使用します。

権限の判断と URL の署名は Yukinoshita が行います。 ファイルの実体はオブジェクトストレージから直接取得するため、 API がデータ本体を中継することはありません。

1 クイックスタート

28 market-day を使う場合の例

1.1 サインイン

トークンは kamakuraquantlab.jp/tsurugaoka/ で発行します。 手元にある注文番号とメールアドレスでサインインし、「トークンを表示」を押してください。 表示はその 1 回だけですが、必要になればいつでも発行し直せます。 発行し直すと、それまでのトークンは使えなくなります。

pip install 'kamakuraquantlab-komachi[duckdb]'
komachi token set --token hk_...

最小構成は pip install kamakuraquantlab-komachi（httpx のみ）です。 取り込み、DuckDB 連携、ファイル検査を使う場合は上記の duckdb エクストラを指定します。

初回はデータの保存先を尋ねられ、設定ファイル ~/.kamakuraquantlab.env （パーミッション 0600）に ROOT_PATH として記録されます。トークンも同じファイルです。 ホームディレクトリに置くため、データディレクトリをそのままバージョン管理下に置いても 資格情報が混入せず、どのディレクトリから実行しても答えは 1 つです。

1.2 利用枠と期限の確認

komachi token status

Product        starter-4w
Token status   active
Access         active
First used     2026-09-11T05:54:23+00:00
Access until   2026-09-25T05:54:23+00:00
Allowance      28 market-days  (4 market-weeks)
Remaining      28 market-days  (4 market-weeks)

Markets        BITBANK:BTC_SPOT, BITBANK:ETH_SPOT, ... COINCHECK:XRP_SPOT

Active until 2026-09-25. Until then you can take market-days and re-download
anything already taken as often as you like, at no further cost.

期間は 2 つあり、順番に効きます。

ログイン期間の間に、一度 tsurugaoka にサインインしてください。 この最初のサインインでトークンが発行され、同時にダウンロード期間が始まります。

ダウンロード期間はその最初の 1 回から数えます。 受け取ってすぐに作業を始められなくても不利にならないよう、 ご購入時ではなく初回サインイン時を起点にしています。

ダウンロード期間の中では、取得した market-day を何度でも再取得できます。 ファイルを削除しても、ダウンロードに失敗しても、取り直しに利用枠は消費しません。 回数の上限はありません。 ダウンロードのたびに新しい URL を発行し、その URL は 1 時間で失効します。 komachi download は、まだ取得していない日付をその場で取得します。 そのための事前操作は必要ありません。

ダウンロード期間を過ぎると、新しい market-day の取得も、ダウンロード用 URL の発行も停止します。 利用枠に未使用分があっても使えません。 komachi download は取得を始める前に、その旨を表示して終了します。 tsurugaoka にはサインインでき、利用状況と終了日を確認できます。 消費済みの market-day は消費済みのまま残り、返還はありません。 期間内に必要なファイルを保存してください。

実際には、ここに来た時点ですでにダウンロード期間が始まっています。 komachi token set がトークンを確認するために行う通信も「使った」1 回に数えるためです。 そのため komachi token status には、期限の日付と残り日数が表示されます。

日付も残り日数もサーバーが計算して返したものをそのまま表示しています。 残り日数の計算には時計が必要ですが、その時計は手元のものではないからです。 このツールが独自に期限を判断することはありません。

1.3 収録状況の確認

どのマーケットが使えるか、それぞれ何が収録されているかを確認します。

komachi markets

market                 datasets           days  range                     missing
BINANCE:BTC_USDT       OrderBook           424  2025-07-01 .. 2026-09-12  2026-04-03..2026-04-09; ...
COINCHECK:BTC_SPOT     OrderBook,Trade     431  2025-07-01 .. 2026-09-12  2026-04-02..2026-04-09
GMO:BTC_JPY            OrderBook           430  2025-07-01 .. 2026-09-12  2026-04-02..2026-04-09; 2025-07-05

missing は収録期間内で欠測している日付です。 収録期間の前後は、欠測ではなく未収集として扱います。 日ごとの品質や、スキーマ、品質基準は Market Archive のページに掲載しています。

取得済みのデータは komachi local で確認できます。

1.4 取得

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

実行前に、対象期間・ファイル数・容量・消費する market-day 数を表示して確認を求めます。 中断した場合は同じコマンドを再実行すれば、取得済みのファイルは飛ばして続きから再開します。 すでに手元にあるファイルに対して利用枠を再消費することはありません。

1.5 取引所公開データの取り込み

同じ期間の Binance と GMO コインの約定データを、各取引所の公開データから取り込みます。 利用枠は消費しません。

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

取り込み時に日本時間の日付へ再分割するため、配信データと同じ基準で比較できます。

1.6 保存先の確認

komachi local

market                   dataset     days  range
COINCHECK:BTC_SPOT       OrderBook     28  2025-07-01 .. 2025-07-28
COINCHECK:BTC_SPOT       Trade         28  2025-07-01 .. 2025-07-28
BINANCE:BTC_USDT         Trade         28  2025-07-01 .. 2025-07-28
GMO:BTC_JPY              Trade         28  2025-07-01 .. 2025-07-28

1.7 中身の確認

komachi trades --market COINCHECK:BTC_SPOT --date 2025-07-01 --rows 3
komachi book   --market COINCHECK:BTC_SPOT --date 2025-07-01 --rows 3

time (JST)    side             price            size
00:00:00.000  buy    15,456,978.0000      0.03000000
00:00:01.000  buy    15,458,282.0000      0.03102218

time (JST)            best bid        best ask      spread
00:00:00.000   15,456,905.0000 15,456,978.0000     73.0000
00:00:00.000   15,453,307.0000 15,458,283.0000  4,976.0000

1.8 分析へ

download と import はビューを自動で更新します。取得後そのまま読めます。

duckdb ~/kamakuraquantlab-data/kql.duckdb

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

作図と派生データの作成は Komachi の範囲外です。 分析ツールキットの Hase が担当します（公開準備中）。

2 コマンド一覧

2.1 リモート操作

Yukinoshita API または各取引所の公開データとの通信を伴うコマンドです。

利用枠を消費するのは download のみです。 取得前に、対象期間・ファイル数・容量・消費数を表示して確認を求めます。 market-day は 1 マーケットの 1 日分で、同じ日の板と約定を合わせて 1 と数えます。

2.2 ローカル操作

手元のファイルだけを参照します。通信も利用枠の消費もありません。

3 保存先の構成

データは、収集時と同じ Hive 形式のディレクトリに保存されます。

$ROOT_PATH/bronze/dataset=Trade/exchange=GMO/symbol=BTC_JPY/date=2026-01-15/data.parquet

自分のスクリプトから保存先を知るには komachi.data_root() を呼びます。 初期設定で答えた ROOT_PATH だけを読み、環境変数も既定値も見ません。 未設定なら、その場で設定を促して停止します。

import komachi

root = komachi.data_root()      # ~/.kamakuraquantlab.env の ROOT_PATH

Hase も同じ関数を呼んでいます。保存先の答えは 1 か所にしかありません。

DuckDB、PyArrow、Spark、Athena のいずれも dataset・exchange・symbol・date を パスから列として認識します。1 年分でも次の 1 行で読み込めます。

SELECT * FROM read_parquet('~/kamakuraquantlab-data/bronze/dataset=Trade/**/*.parquet', hive_partitioning = 1);

4 日付の扱い

date= は日本時間の 1 日です。date=2026-01-15 は 2026-01-15 00:00〜23:59 JST、 UTC では 2026-01-14 15:00〜2026-01-15 14:59 にあたります。 ファイル内のタイムスタンプは UTC エポック秒のため、実行環境のタイムゾーンに依存しません。

取り込み元の日付区切りは取引所ごとに異なります。 Binance Vision は 00:00 UTC、GMO コインは取引日の切り替えである 21:00 UTC を基準としています。 Komachi は取り込み時に日本時間の日付へ再分割するため、 配信データと取引所公開データを同じ基準で比較できます。

このため、ある 1 日を取り込むには前日分の元ファイルも必要です。 どちらか一方しか取得できない日は、不完全なまま書き出さずに保留します。

5 Komachi が行わないこと

1. 取引所 API への直接接続。接続先は Yukinoshita API、Binance Vision、GMO コインの公開データのみです。
2. データの加工・導出。silver 以降は Hase が担当します。
3. Kamakura Quant Lab の API 以外に対する資格情報の保持。

6 AI エージェントに任せる

セットアップやコマンドの使い方は、Claude Code や Codex などの AI コーディングエージェントに任せられます。 このリポジトリの AGENTS.md がエージェント向けの手引きです。

git clone https://github.com/kamakuraquantlab/Komachi
cd Komachi
claude          # または codex など

あとは「セットアップして」「COINCHECK の 1 週間分を取得したい」のように依頼してください。 手引きには、利用枠を消費するコマンドはどれか、トークンをどう扱うか、 エラーが出たときに何を確認するかを記載しています。

利用枠を消費するのは download のみです。実行前に対象と消費数を表示して確認を求めます。 エージェントにも、確認なしに実行しないよう指示しています。

7 ライセンス

Apache License 2.0。LICENSE.md