| name | data-verification |
| description | bitbank のローソク足データの品質を検証する（欠損足・OHLCV 整合性・
異常値・重複検出）。**ユーザーが明示的に依頼したときのみ起動する**。
代表トリガー: 「データ検証して」「欠損ないか確認して」
「このデータ信頼できる？」「品質チェックして」
注意: indicator-analysis や backtest の自動前処理としては起動しない。
|
| compatibility | Requires the bitbank CLI on PATH (install separately: npm i -g bitbank-lab-cli).
Plugin install alone does NOT bundle the CLI or its dependencies. Node.js 22+.
|
| metadata | {"author":"bitbankinc","version":"1.0","requires":{"bins":["bitbank"]}} |
データ検証 Skill
いつ使うか
代表トリガー以外にも以下のような発話で起動する:
- 「candles のデータ大丈夫？」「ちゃんと取れてる？」
indicator-analysis / backtest / portfolio の前段として自動実行はしない。
トリガー条件
明示リクエストのみ。 以下のような発話で起動する:
- 「データ検証して」「データの品質をチェックして」
- 「欠損ないか確認して」「ちゃんと取れてる？」
- 「このデータ信用できる？」
indicator-analysis / backtest / portfolio の前段として自動実行はしない。
データ取得
bitbank candles <pair> --type=<timeframe> --format=json --machine
ユーザーが期間を指定した場合:
bitbank candles <pair> --type=<timeframe> --from=YYYYMMDD --to=YYYYMMDD --format=json --machine
指定がなければ直近データ（デフォルト 1000 本）で検証する。
--machine envelope の meta.gaps / dedupedCount / truncated は本 skill
の検証項目（欠損足・重複・時系列連続性）と直接対応する。CLI が既に検出した
ものは項目 1〜8 の集計に組み込み、再検出ではなく 既知の検出結果として
そのまま報告する（取得側 vs 計算側で二重検出すると件数が合わなくなる）。
検証項目
8 つのチェックを順に実行する。詳細は references/verification-guide.md を参照。
1. 欠損足の検出
期待される本数と実際の本数を比較する。
- 取得期間と時間軸から「あるべきタイムスタンプ列」を計算
- 実データのタイムスタンプと突き合わせ、欠損箇所を特定
- 暗号資産は 24/7 取引のため、土日・祝日による正当な欠損はない
2. 重複タイムスタンプの検出
同一タイムスタンプが複数存在しないか確認する。
- ページネーション境界での重複が起きやすい
- 重複があれば件数と該当タイムスタンプを報告
3. OHLCV 整合性チェック
各ローソク足が以下のルールを満たすか検証する:
high >= max(open, close)low <= min(open, close)high >= lowvolume >= 0- すべての価格 > 0
違反行があれば該当タイムスタンプと具体的な値を報告。
4. 基本統計量サマリー
全フィールドの min / max / mean / std を算出し、データ全体の「顔」を見る。
- 価格の桁チェック: BTC/JPY なら百万〜千万円台、XRP/JPY なら数十〜数百円台。桁が明らかに違えばデータ取り違えの可能性
- min/max の異常: min が 0 や負値、max が直近相場の数倍 → 異常データ混入
- std/mean 比（変動係数）: 極端に大きい場合はレジーム変化（急騰暴落期）を含む期間。バックテスト時は期間分割を検討
- 出来高の偏り: mean に対して max が極端に大きい場合、特定の足に出来高が集中（大口約定やイベント）
検証としては INFO レベル。「一目で全体像を掴む」ための項目であり、NG 判定はしない。
5. 異常値（外れ値）の検出
直前の足からの変動率で異常を検出する。
暗号資産はペアごとにボラティリティが大きく異なるため、閾値を 3 段階に分ける。
ペアカテゴリ: _shared/references/pair-classification.md を参照。
bitbank 上の実際の 24h 出来高シェアに基づく分類。
| カテゴリ | 基準 | 代表ペア |
|---|
| major | 出来高シェア 10% 以上 | btc_jpy, xrp_jpy, eth_jpy |
| mid | 出来高シェア 1〜10% | doge_jpy, sol_jpy, ltc_jpy, ada_jpy 等 |
| minor | 出来高シェア 1% 未満 | mona_jpy, sand_jpy, gala_jpy 等 |
デフォルト閾値（ペアカテゴリ × 時間軸）:
| 短期足 (1min〜30min) | 中期足 (1hour〜12hour) | 長期足 (1day〜) |
|---|
| major | 価格 ±3%, 出来高 30x | 価格 ±8%, 出来高 20x | 価格 ±15%, 出来高 15x |
| mid | 価格 ±5%, 出来高 30x | 価格 ±12%, 出来高 20x | 価格 ±20%, 出来高 15x |
| minor | 価格 ±8%, 出来高 50x | 価格 ±18%, 出来高 30x | 価格 ±30%, 出来高 20x |
ペアが分類表に未掲載の場合は mid を適用する。
ユーザーが閾値を明示した場合はそちらを優先する。
閾値を超えた足をフラグし、タイムスタンプ・値・変動率を報告する。
異常値は「除去すべきエラー」ではなく「確認すべきイベント」として扱う。
暗号資産ではファットテール（4σ超の変動）が珍しくないため、
フラグ = 即削除ではなく、ユーザーの判断材料として提示する。
6. 出来高ゼロ連続の検出
出来高ゼロの足が連続していないか検出する。
- bitbank のアルトコインでは出来高ゼロ足が散発的に出ることは正常
- ただし 連続 3 本以上 のゼロ出来高はフラグする（流動性枯渇の警告）
- major ペアでゼロ出来高が 1 本でもあれば NG（通常あり得ない）
7. ヒゲ異常（wick anomaly）の検出
ローソク足の実体に対してヒゲが異常に長い足を検出する。
十字線・コマ足（始値 ≒ 終値）では wick_ratio が発散するため、実体サイズで判定を 2 段階に分ける。
body = abs(close - open)
wick_range = high - low
wick_ratio = wick_range / body # body が十分ある場合のみ
実体サイズ判定（十字線除外）:
body < high * 0.003（価格の 0.3% 未満）なら十字線・コマ足とみなし、wick_ratio は計算しない。
この場合はヒゲ幅 (high - low) の絶対値をペア・時間軸の価格変動閾値（項目 5 のテーブル）と比較する。
フラグ条件（2 段階）:
| 実体サイズ | 判定基準 | フラグ |
|---|
実体が十分ある（body >= high * 0.003） | wick_ratio > 15 | INFO |
実体が極小（body < high * 0.003、十字線） | wick_range / high が価格変動閾値を超過（例: major/1day なら 15%） | INFO |
- 清算カスケードやフラッシュクラッシュで発生しやすい
- OHLCV 整合性は通るが、この足を含む指標計算は歪む可能性がある
- 十字線それ自体は正常なローソク足。ヒゲ幅が小さければフラグしない
8. 時系列連続性チェック
タイムスタンプが等間隔で並んでいるか確認する。
- 期待間隔: 時間軸に対応するミリ秒数（例: 1hour = 3,600,000ms）
- 間隔の飛びがあれば欠損足チェック（項目 1）と照合して原因を推定
カスタマイズ可能なパラメータ
ユーザーがパラメータを指定した場合はそちらを優先する。
指定がなければ項目 4 のペアカテゴリ × 時間軸テーブルを使う。
| パラメータ | デフォルト | 説明 |
|---|
| 価格変動閾値 | ペア・時間軸別（項目 4 参照） | ユーザー指定で一律上書き可 |
| 出来高変動閾値 | ペア・時間軸別（項目 4 参照） | 同上 |
| ゼロ出来高連続閾値 | 3 本 (mid/minor), 1 本 (major) | 連続ゼロ出来高のフラグ基準 |
| ヒゲ異常倍率 | 15x | wick_ratio がこの値を超えたらフラグ |
例: 「閾値を 5% にして検証して」→ 価格変動閾値をペアカテゴリに関係なく ±5% に一律変更して実行。
ローカル環境なので、このファイル自体のデフォルト値を直接編集しても OK。
実行手順
candles コマンドで OHLCV データを取得（--format=json）- 出力は
Candle オブジェクトの配列。各要素は { open, high, low, close, vol, timestamp }
- フィールドは CLI が数値変換済み。そのまま計算に使える
- ペア名からカテゴリ（major/mid/minor）を判定し、時間軸と合わせて閾値を決定
- 8 つの検証項目を順に実行
- 結果をレポート形式で出力
出力フォーマット
サマリーテーブル
検証項目 | 結果 | 詳細
-----------------------|--------|------------------------------------------
欠損足 | OK/NG | 0 件 / 3 件（タイムスタンプ一覧）
重複タイムスタンプ | OK/NG | 0 件 / 2 件
OHLCV 整合性 | OK/NG | 違反 0 件 / 1 件
基本統計量 | INFO | close: mean=9,250,000 std=145,000 min=9,050,000 max=9,500,000
異常値（価格） | INFO | フラグ 0 件 / 2 件（閾値: major/1hour ±8%）
異常値（出来高） | INFO | フラグ 0 件 / 1 件（閾値: major/1hour 20x）
出来高ゼロ連続 | OK/NG | 0 件 / 1 箇所（5 本連続）
ヒゲ異常 | INFO | フラグ 0 件 / 1 件（wick_ratio > 15）
時系列連続性 | OK/NG | 等間隔 / 不連続 2 箇所
ペアカテゴリ: major | 時間軸: 1hour
総合: ✅ データ品質に問題なし / ⚠️ 要確認項目あり
異常値の詳細（フラグがある場合）
タイムスタンプ | close | 前足 close | 変動率 | 備考
-----------------------|------------|-----------|---------|--------
2024-03-05T14:00:00Z | 10,200,000 | 9,100,000 | +12.1% | 閾値超過
判定基準
- OK: 問題なし
- NG: データ品質に影響する問題あり（分析前に対処を検討）
- INFO: 異常値フラグ（情報提供のみ、除去は推奨しない）
Gotchas
- フィールド名に注意。 出来高は
volume ではなく vol
- 配列は古い順。 先頭が最も古いデータ
- 日付形式に注意。
--type=1month は --date=2024、それ以外は YYYYMMDD
- 暗号資産は 24/7。 株式と違い「正当な休場」はない。欠損 = 取引所メンテか API 障害
- 異常値 ≠ エラー。 急騰・急落はファットテール分布の特性。フラグは「要確認」であり「要削除」ではない
- ペアによってボラが全く違う。 BTC の 1h ±8% は異常事態だが、MONA の 1h ±8% は日常。一律閾値は使わない
- minor ペアの出来高ゼロは珍しくない。 即 NG にせず連続本数で判断する。major で出来高ゼロは逆に異常
- ヒゲ異常は OHLCV 整合性チェックを通過する。 high >= open, low <= close 等のルールは満たすが、指標計算を歪める。別チェックが必要
- 十字線・コマ足では
wick_ratio が誇張される。 close ≒ open だと分母（実体）が極小になり、ヒゲ幅が小さくても比率が数十〜数百倍に跳ね上がる。実体サイズ（body < high * 0.003 等）で分岐し、十字線はヒゲ幅の絶対値で判定すること
- API がエラーを返した場合は
_shared/references/bitbank-api-formats.md のエラーコードを確認する
