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 エクストラを指定します。

初回はデータの保存先を尋ねられ、実行ディレクトリの .env に記録されます。 トークンは .env ではなく ~/.komachi/config.json（パーミッション 0600）に保存されます。 データディレクトリをそのままバージョン管理下に置いても、資格情報が混入しません。

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 unlock market-days and re-download
anything already unlocked 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
komachi catalog --market COINCHECK:BTC_SPOT --days 3

date         datasets                     rows      size    gap  note
2026-09-01   OrderBook,Trade           264,447    24.8MB     8m
2026-09-02   OrderBook,Trade           274,792    26.7MB     1m
2026-09-03   OrderBook,Trade           280,067    27.9MB     9m

3 market-day(s). 'gap' is minutes with no record in the JST day.

gap は、その日のうち記録のない分数です。取得前に品質を確認できます。

1.4 取得

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

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

1.5 無償公開データの取り込み

同じ期間の Binance と GMO コインの約定データを、無償公開元から取り込みます。 残高は消費しません。

komachi binance-import --symbol BTC_USDT --start 2025-07-01 --end 2025-07-28
komachi gmo-import     --symbol 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 分析へ

komachi duckdb
duckdb ~/kql-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 形式のディレクトリに保存されます。

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

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

SELECT * FROM read_parquet('~/kql-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 ライセンス

Apache License 2.0。LICENSE.md