Komachi
鎌倉クオンツラボのコマンドラインクライアントです。
ヒストリカル市場データを取得し、DuckDB からそのまま参照できる構成で保存します。
English README
Kamakura Quant Lab のデータは、2 つの方法で取得できます。
収録範囲、スキーマ、品質基準はデータのページに記載しています。
ブラウザ — tsurugaoka
数日分を確認する用途に適しています。1 ファイルずつ、ブラウザの保存先に保存されます。
コマンドライン — Komachi（本リポジトリ）
Yukinoshita API（yukinoshita.kamakuraquantlab.jp）を呼び出すクライアントです。
まとまった量を扱う場合はこちらを使用します。
| 機能 | 内容 |
|---|
| 利用枠と配信状況の確認 | 利用できるマーケット、日付ごとの収録状況と品質を、取得前に確認できます |
| 一括取得 | 範囲を指定してまとめて取得します。中断後は同じコマンドで再開し、チェックサムで検証します |
| Hive 形式での保存 | 収集時と同じディレクトリ構成で保存するため、DuckDB から取り込み処理なしに参照できます |
| 取引所公開データの取り込み | Binance と GMO コインが自ら公開している約定データを、日本時間の日付へ再分割して取り込みます。配信データと同一の条件で比較できます |
| ローカル参照 | 手元のファイルの一覧、約定と気配の表示、DuckDB ビューの作成 |
権限の判断と 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 つあり、順番に効きます。
| 期間 | 起点 | 過ぎると |
|---|
| ログイン期間 | 1 か月 | ご購入時 | サインインできず、以後は使えません |
| ダウンロード期間 | 14 日 | 最初にサインインした時 | 新たな取得も配信も行われません |
ログイン期間の間に、一度 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 または各取引所の公開データとの通信を伴うコマンドです。
| コマンド | 内容 | 利用枠の消費 |
|---|
komachi token set --token TOKEN | トークンを検証して保存 | なし |
komachi token status | ご購入分、使用済み、利用枠、2 つの期間 | なし |
komachi markets | 利用できるマーケット、収録期間、欠測、取引所公開データの案内 | なし |
komachi download --market MARKET --start DATE [--days N] | 範囲を指定して取得（中断後は再開） | あり |
komachi import --market BINANCE:SYMBOL --start DATE --end DATE | Binance Vision から取り込み | なし |
komachi import --market GMO:SYMBOL --start DATE --end DATE | GMO コインの公開データから取り込み | なし |
利用枠を消費するのは download のみです。
取得前に、対象期間・ファイル数・容量・消費数を表示して確認を求めます。
market-day は 1 マーケットの 1 日分で、同じ日の板と約定を合わせて 1 と数えます。
2.2 ローカル操作
手元のファイルだけを参照します。通信も利用枠の消費もありません。
| コマンド | 内容 |
|---|
komachi local | 保存済みファイルの一覧 |
komachi trades --market MARKET --date DATE | 約定データの表示 |
komachi book --market MARKET --date DATE | 最良気配とスプレッドの表示 |
komachi stats --path PATH | 行数と時間範囲 |
komachi decode --path PATH | スキーマと先頭数行 |
komachi duckdb | DuckDB のビューを手動で再作成（通常は自動） |
komachi sql | ビュー定義の SQL を出力 |
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 が行わないこと
- 取引所 API への直接接続。接続先は Yukinoshita API、Binance Vision、GMO コインの公開データのみです。
- データの加工・導出。silver 以降は Hase が担当します。
- 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
