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 コインの公開データから取り込み	なし

This is the beginning of the README. Read the rest at the original. Read the full README ↗