get_flow_metrics
Analyze trade flows to compute CVD, aggressor ratio, and buy-sell pressure. Choose recent hours, absolute periods, or full UTC days; coverage warnings reveal incomplete data.
Instructions
[Flow / CVD / Buy-Sell Pressure] 資金フロー分析(flow / CVD / aggressor ratio / buy-sell pressure)。約定データからCVD・アグレッサー比・スパイクを検出。直近フローは hours(現在時刻起点)、過去の特定区間は since/until(絶対時刻)、件数指定は limit。
期間指定の使い分け:
hours: 現在時刻起点の相対窓(最大24h)。「直近N時間」の分析用。
since / until: オフセット付き ISO8601 の絶対時刻区間(例: since=2026-08-01T00:00:00Z, until=2026-08-02T00:00:00Z)。過去の特定区間を全件集計する唯一の手段。until は排他([since, until))で省略時は現在時刻まで。最大 7 日。limit は適用しない。
date: UTC 暦日 1 日(YYYYMMDD)。当該 UTC 日の全件(5,600〜8,000 件)を集計する。limit は適用しない。UTC 暦日ちょうどを指定する簡便手段なので、複数日にまたがる区間や UTC 暦日の境界に揃わない区間(例: JST の 1 日)には since/until を使うこと。
limit: date / hours / since・until のいずれも指定しない件数ベース取得(直近 N 件)でのみ有効(上限 2000 件 ≒ BTC/JPY で 6〜8.5 時間分)。区間指定と併用しても無視される。それより長い窓は件数ではなく hours / since・until で指定すること。
since/until は hours とも date とも併用不可(併用すると user エラー)。暗黙の優先順位を置くと、要求と異なる区間の集計値が無言で返るため。なお hours と date の同時指定だけは従来どおりエラーにせず hours が優先される(date は無視される)。
since/until に YYYYMMDD 形式は使えない。暦日の基準がツール間で割れている(本ツールの date は UTC 暦日、get_candles の date は tz 引数の暦日)ため、絶対時刻はオフセット必須の ISO8601 のみ受け付ける。
データソース制約(bitbank 側仕様): 約定アーカイブ /transactions/{YYYYMMDD} は UTC 暦日単位で、当該 UTC 日の完了後にのみ公開される。完了済み UTC 日は全件(1日あたり数千件)を集計に使う。進行中の UTC 日(JST 09:00 で切り替わる)の約定は /transactions (latest, 直近約60件) でしか取得できないため、当日区間のカバレッジは限定的(warning で明示される)。
カバレッジ申告: meta.actualRange は durationMinutes(先頭〜末尾のスパン)に加えて coveredMinutes(実データがある区間の合計)/ gapMinutes / gaps を返す。requestedMinutes(要求区間)に対する coveragePct が出るので、要求どおり取れたかは常にこの値で確認できる。欠損があれば meta.warning(取得層)と meta.warnings(計算層: 集計値がカバー区間のみ由来である旨)で明示される。完了済み UTC 日のみの区間なら coveragePct はほぼ 100%、進行中 UTC 日にかかる区間は latest 約60件ぶんまで下がる。
加工契約:
内部で使用する約定列は、取得パスに関わらず timestampMs 昇順にソート済み。
latest と date ベースをマージする場合、重複除去キーは
timestampMs:price:amount:side(transaction_id は使用しない: 同一約定でも上流エンドポイント間で ID が一致しないケースがあるため)。
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| tz | No | Asia/Tokyo | |
| date | No | YYYYMMDD。**UTC 暦日**として解釈します(上流の約定アーカイブ /transactions/{YYYYMMDD} が UTC 暦日単位のため)。get_candles / validate_candle_data の date が tz 引数の暦日(既定 Asia/Tokyo)である点と基準が異なります。当該 UTC 暦日の**全件**(BTC/JPY で 5,600〜8,000 件)を集計します。limit は適用しません。UTC 暦日 1 日ちょうどを指定する簡便手段なので、複数日にまたがる区間や UTC 暦日の境界に揃わない区間(例: JST の 1 日)には since/until を使ってください(例: since=2026-08-01T00:00:00Z, until=2026-08-02T00:00:00Z)。進行中の UTC 日を指定した場合は latest(直近約60件。要求日の全件ではない)にフォールバックし warning を出します。省略時は latest。since/until とは併用不可(併用時は user エラー)。 | |
| pair | No | btc_jpy | |
| view | No | view は content の量を制御します。量は summary < detailed < full の順で、full は常にそのツールの最重量です。view が structuredContent から**フィールドを削ることはありません**(その view でしか計算しないデータを足すツールはあり、その場合は当該 view の説明に明記しています)。content[0].text は LLM への唯一のチャネルなので、軽い view は「短い表示」ではなく「LLM が明細を受け取らない」を意味します。 本ツールの主対象はバケット列なので、view が決めるのは content のバケット行の量です(集計値・警告・フッタは全 view に出ます)。 - summary(既定): 集計値のみ。バケット行は content に出ない。 - detailed: 集計値 + 直近 bucketsN 件のバケット行(既定 10 / 上限 100)。それより前のバケット行は content に出ない。 - full: 集計値 + 全バケット行。本ツールの最重量。 - compact: 非推奨。view=full + nonZeroOnly=true を使うこと。0.4.0 で削除予定。挙動は view=full + nonZeroOnly=true と同じ。 - buckets: 非推奨。view=detailed を使うこと。0.4.0 で削除予定。挙動は view=detailed と同じ。 | summary |
| hours | No | 指定した時間数分の約定を取得して分析(例: 8 → 直近8時間)。**現在時刻起点**の相対窓。limit より優先。複数日にまたがる場合も自動で取得します。since/until・date とは併用不可(併用時は user エラー) | |
| limit | No | 取得する約定件数(バケット数ではない)。**date / hours / since・until のいずれも指定しない件数ベース取得(=直近 N 件)でのみ有効**です。区間指定パラメータを渡した場合は無視されます(いずれも区間の全件を集計)。上限 2000 件は BTC/JPY で 6〜8.5 時間分に相当します。それより長い窓は件数ではなく hours / since・until で指定してください | |
| since | No | 取得区間の開始時刻(**含む**)。オフセット付き ISO8601 のみ(例: 2026-08-01T00:00:00Z / 2026-08-01T09:00:00+09:00)。YYYYMMDD は不可 — 暦日の基準がツール間で割れている(約定系ツールの date は UTC 暦日、get_candles の date は tz 引数の暦日)ため、絶対時刻はオフセット必須にして解釈のブレを排除している。hours / date とは併用不可。since〜until は最大 7 日。指定時は limit を適用しない(区間の全件を集計) | |
| until | No | 取得区間の終端時刻(**含まない**: [since, until))。オフセット付き ISO8601 のみ。省略時は現在時刻まで。排他区間なので、連続する区間を続けて要求しても境界の約定が二重計上されない(例: since=2026-08-01T00:00:00Z, until=2026-08-02T00:00:00Z は UTC 8/1 のちょうど 1 日)。since 無しの until 単独指定は user エラー。未来時刻も user エラー(現在時刻までを対象にするなら until を省略する) | |
| bucketMs | No | バケットの時間幅(ミリ秒)。デフォルト60000=1分間隔 | |
| bucketsN | No | view=detailed(および deprecated な view=buckets)で content に出す直近バケット行の件数。他の view では無視されます。 | |
| nonZeroOnly | No | true にすると content のバケット行を非ゼロ(buy または sell > 0)のみに絞ります。量ではなく絞り込みの軸なので view とは独立に指定できます。欠損バケット(hasData=false)は落とさず、連続区間を `⋯ 欠損 A〜B(Nバケット, データなし)` の 1 行に畳んで残します(黙って消すと「閑散だった」と誤読されるため)。structuredContent は変わりません(全バケットのまま)。view=summary との併用は no-op(バケット行が無いため。エラーにはしません)。 |