bitbank-lab-mcp 0.1.0

package/tools/detect_patterns.ts

@@ -0,0 +1,424 @@
+import type { z } from 'zod';
+import { dayjs } from '../lib/datetime.js';
+import { fail, failFromError, ok } from '../lib/result.js';
+import { DetectPatternsOutputSchema, type PatternTypeEnum } from '../src/schemas.js';
+import analyzeIndicators from './analyze_indicators.js';
+import { buildStatistics } from './patterns/aftermath.js';
+import { resolveParams } from './patterns/config.js';
+// --- 各パターン検出モジュール ---
+import { detectDoubles } from './patterns/detect_doubles.js';
+import { detectHeadAndShoulders } from './patterns/detect_hs.js';
+import { detectPennantsFlags } from './patterns/detect_pennants.js';
+import { detectTriangles } from './patterns/detect_triangles.js';
+import { detectTriples } from './patterns/detect_triples.js';
+import { detectWedges } from './patterns/detect_wedges.js';
+import { globalDedup } from './patterns/helpers.js';
+import { linearRegressionWithR2, near as nearFn, pct as pctFn } from './patterns/regression.js';
+import { type Candle, detectSwingPoints, filterPeaks, filterValleys } from './patterns/swing.js';
+import type { CandDebugEntry, DeduplicablePattern, DetectContext } from './patterns/types.js';
+
+/** Summary generation section で使う拡張型（DeduplicablePattern + パターン固有フィールド） */
+interface SummaryPattern extends DeduplicablePattern {
+	type: string;
+	confidence: number;
+	range: { start: string; end: string; current?: string };
+	status?: string;
+	breakoutDirection?: string;
+	outcome?: string;
+	neckline?: Array<{ y?: number }>;
+	trendlineLabel?: string;
+	daysToApex?: number;
+	breakoutTarget?: number;
+	targetMethod?: string;
+	targetReachedPct?: number;
+	poleDirection?: string;
+	priorTrendDirection?: string;
+	flagpoleHeight?: number;
+	retracementRatio?: number;
+	isTrendContinuation?: boolean;
+	timeframe?: string;
+	timeframeLabel?: string;
+}
+
+/**
+ * detect_patterns - チャートパターン検出（完成済み＋形成中）
+ *
+ * 設計思想:
+ * - 目的: チャートパターンを検出し、統計的に信頼性の高いデータを提供
+ * - 特徴: swingDepth パラメータによる厳密なスイング検出でパターン品質を重視
+ * - ブレイク検出: ATR * 0.5 バッファ、最初の明確なブレイクで終点を確定
+ * - 用途: 「過去の成功率は？」「典型的な期間は？」「aftermath は？」
+ *
+ * オプション:
+ * - includeCompleted: true (デフォルト) → 完成済みパターンを検出
+ * - includeForming: true → 形成中パターンも検出（早期警告向け）
+ */
+
+export default async function detectPatterns(
+	pair: string = 'btc_jpy',
+	type: string = '1day',
+	limit: number = 90,
+	opts: Partial<{
+		swingDepth: number;
+		tolerancePct: number;
+		minBarsBetweenSwings: number;
+		strictPivots: boolean;
+		patterns: Array<z.infer<typeof PatternTypeEnum>>;
+		requireCurrentInPattern: boolean;
+		currentRelevanceDays: number;
+		// 統合オプション
+		includeForming: boolean;
+		includeCompleted: boolean;
+		includeInvalid: boolean;
+		view: 'summary' | 'detailed' | 'full' | 'debug';
+	}> = {},
+) {
+	try {
+		// --- パラメータ解決（patterns/config.ts から） ---
+		const { swingDepth, tolerancePct, minBarsBetweenSwings: minDist, autoScaled } = resolveParams(type, opts);
+		const strictPivots = opts.strictPivots !== false; // 既定: 厳格
+		// 統合オプション
+		const includeForming = opts.includeForming ?? false;
+		const includeCompleted = opts.includeCompleted ?? true;
+		const includeInvalid = opts.includeInvalid ?? false;
+		const want = new Set(opts.patterns || []);
+		// 'triangle' が指定された場合は3種を含む互換挙動
+		if (want.has('triangle')) {
+			want.add('triangle_ascending');
+			want.add('triangle_descending');
+			want.add('triangle_symmetrical');
+		}
+
+		const res = await analyzeIndicators(pair, type, limit);
+		if (!res.ok) return DetectPatternsOutputSchema.parse(fail(res.summary || 'failed', 'internal'));
+
+		const candles = res.data.chart.candles as Array<{
+			open: number;
+			close: number;
+			high: number;
+			low: number;
+			isoTime?: string;
+		}>;
+		if (!Array.isArray(candles) || candles.length < 20) {
+			return DetectPatternsOutputSchema.parse(ok('insufficient data', { patterns: [] }, { pair, type, count: 0 }));
+		}
+
+		// 1) Swing points（patterns/swing.ts から）
+		const pivots = detectSwingPoints(candles as Candle[], { swingDepth, strictPivots });
+
+		// debug buffers
+		const debugSwings = pivots.map((p) => ({
+			idx: p.idx,
+			price: p.price,
+			kind: p.kind,
+			isoTime: candles[p.idx]?.isoTime,
+		}));
+		const debugCandidates: CandDebugEntry[] = [];
+
+		// --- 共有コンテキスト構築 ---
+		const ctx: DetectContext = {
+			candles,
+			pivots,
+			allPeaks: filterPeaks(pivots),
+			allValleys: filterValleys(pivots),
+			tolerancePct,
+			minDist,
+			want,
+			includeForming,
+			debugCandidates,
+			type,
+			swingDepth,
+			near: (a: number, b: number) => nearFn(a, b, tolerancePct),
+			pct: pctFn,
+			lrWithR2: linearRegressionWithR2,
+		};
+
+		// --- 各パターン検出を実行 ---
+		let patterns: DeduplicablePattern[] = [];
+
+		// 2) Double top/bottom
+		const doubles = detectDoubles(ctx);
+		patterns.push(...doubles.patterns);
+
+		// 3) Head & Shoulders
+		const hs = detectHeadAndShoulders(ctx);
+		patterns.push(...hs.patterns);
+
+		// 4) Triangles + Pennant (Trendoscope 2-stage: triangle → pole check → pennant reclassification)
+		const triangles = detectTriangles(ctx);
+		patterns.push(...triangles.patterns);
+
+		// 4b-4d) Wedges
+		const wedges = detectWedges(ctx);
+		patterns.push(...wedges.patterns);
+
+		// 5) Flag detection (parallel channel with pole; pennant is now handled by detectTriangles)
+		const flags = detectPennantsFlags(ctx);
+		patterns.push(...flags.patterns);
+
+		// 6) Triple Top / Triple Bottom
+		const triples = detectTriples(ctx);
+		patterns.push(...triples.patterns);
+
+		// グローバル重複排除: 全パターン種別横断で期間が70%以上重複する同一タイプを統合
+		patterns = globalDedup(patterns);
+
+		// Optional filter: only patterns whose end is within N days from now (current relevance)
+		{
+			const requireCurrent = !!opts.requireCurrentInPattern;
+			const defaultDaysByType = (tf: string): number => {
+				if (tf === '1month') return 60; // ~2 months
+				if (tf === '1week') return 21; // ~3 weeks
+				return 7; // default for daily and intraday
+			};
+			const maxAgeDays = Number.isFinite(opts.currentRelevanceDays)
+				? Number(opts.currentRelevanceDays)
+				: defaultDaysByType(String(type));
+			if (requireCurrent && patterns.length) {
+				const nowMs = Date.now();
+				const inDays = (iso?: string) => {
+					if (!iso) return Infinity;
+					const t = Date.parse(iso);
+					if (!Number.isFinite(t)) return Infinity;
+					return Math.abs(nowMs - t) / 86400000;
+				};
+				patterns = patterns.filter((p) => inDays(p?.range?.end) <= maxAgeDays);
+			}
+		}
+
+		// Aftermath analysis + statistics（patterns/aftermath.ts へ抽出済み）
+		const { statistics } = buildStatistics(patterns, candles);
+
+		// includeForming / includeCompleted に基づくフィルタリング
+		let filteredPatterns = patterns;
+		if (!includeForming || !includeCompleted) {
+			filteredPatterns = patterns.filter((p) => {
+				const isForming = p.status === 'forming' || p.status === 'near_completion';
+				const isCompleted = p.status === 'completed' || p.status === 'invalid' || !p.status;
+				if (includeForming && isForming) return true;
+				if (includeCompleted && isCompleted) return true;
+				return false;
+			});
+		}
+		// includeInvalid に基づくフィルタリング
+		if (!includeInvalid) {
+			filteredPatterns = filteredPatterns.filter((p) => p.status !== 'invalid');
+		}
+		patterns = filteredPatterns;
+
+		// 時間足ラベル（各パターンに注入 + summary 用）
+		const tfMap: Record<string, string> = {
+			'1min': '1分足',
+			'5min': '5分足',
+			'15min': '15分足',
+			'30min': '30分足',
+			'1hour': '1時間足',
+			'4hour': '4時間足',
+			'8hour': '8時間足',
+			'12hour': '12時間足',
+			'1day': '日足',
+			'1week': '週足',
+			'1month': '月足',
+		};
+		const tfLabel = tfMap[String(type)] || String(type);
+
+		// 全パターンに timeframe / timeframeLabel を付与（LLM が個別パターンから時間足を即座に読み取れるようにする）
+		for (const p of patterns) {
+			p.timeframe = String(type);
+			p.timeframeLabel = tfLabel;
+		}
+
+		// --- ここから先は SummaryPattern として扱う（検出モジュールが付与した固有フィールドにアクセスするため） ---
+		const summaryPatterns = patterns as SummaryPattern[];
+
+		// overlays: パターン範囲をそのまま帯描画できるように提供
+		const ranges = summaryPatterns.map((p) => ({ start: p.range.start, end: p.range.end, label: p.type }));
+		const warnings: Array<{ type: string; message: string; suggestedParams?: Record<string, unknown> }> = [];
+		if (patterns.length <= 1) {
+			warnings.push({
+				type: 'low_detection_count',
+				message: '検出数が少ないです。tolerancePct や minBarsBetweenSwings の調整を推奨します',
+				suggestedParams: { tolerancePct: 0.03, minBarsBetweenSwings: 2 },
+			});
+		}
+		// --- サイズ抑制: debug 配列を上限でトリム（view未指定で返却が肥大化しやすいため） ---
+		// ただし accepted を優先的に残す（accepted → rejected の順で cap まで）
+		const cap = 200;
+		const swingsTrimmed = Array.isArray(debugSwings) ? debugSwings.slice(0, cap) : [];
+		let candidatesTrimmed: CandDebugEntry[] = [];
+		if (Array.isArray(debugCandidates)) {
+			const acc = debugCandidates.filter((c) => !!c?.accepted);
+			const rej = debugCandidates.filter((c) => !c?.accepted);
+			candidatesTrimmed = [...acc, ...rej].slice(0, cap);
+		}
+		const debugTrimmed = {
+			swings: swingsTrimmed,
+			candidates: candidatesTrimmed,
+		};
+
+		// summary 生成: LLM が content から読み取れるように詳細を含める
+		const patternSummaries = summaryPatterns
+			.map((p, idx) => {
+				const startDate = p.range?.start?.substring(0, 10) || '?';
+				const endDate = p.range?.end?.substring(0, 10) || '?';
+				let detail = `${idx + 1}. ${p.type}【${tfLabel}】(パターン整合度: ${p.confidence})\n   - 時間足: ${tfLabel}（${type}）\n   - 期間: ${startDate} ~ ${endDate}`;
+
+				// status（全パターン共通）
+				if (p.status) {
+					const statusJa: Record<string, string> = {
+						completed: '完成（ブレイクアウト確認済み）',
+						invalid: '無効（期待と逆方向にブレイク）',
+						forming: '形成中',
+						near_completion: 'ほぼ完成（apex接近）',
+					};
+					detail += `\n   - 状態: ${statusJa[p.status] || p.status}`;
+				}
+
+				// ブレイクアウト情報（全パターン共通）
+				if (p.breakoutDirection && p.outcome) {
+					const directionJa = p.breakoutDirection === 'up' ? '上方' : '下方';
+					const outcomeJa = p.outcome === 'success' ? '成功' : '失敗';
+
+					// パターン別の期待方向と意味付け
+					const expectedDirMap: Record<string, string | undefined> = {
+						falling_wedge: '上方',
+						rising_wedge: '下方',
+						triangle_ascending: '上方',
+						triangle_descending: '下方',
+						pennant: p.poleDirection === 'up' ? '上方' : p.poleDirection === 'down' ? '下方' : undefined,
+						flag: undefined,
+					};
+					const expectedDir = expectedDirMap[p.type];
+
+					const meaningMap: Record<string, Record<string, string>> = {
+						falling_wedge: { success: '強気転換', failure: '弱気継続' },
+						rising_wedge: { success: '弱気転換', failure: '強気継続' },
+						triangle_ascending: { success: '上方ブレイク（強気）', failure: '下方ブレイク（弱気転換）' },
+						triangle_descending: { success: '下方ブレイク（弱気）', failure: '上方ブレイク（強気転換）' },
+						pennant: {
+							success: `トレンド継続（${p.poleDirection === 'up' ? '強気' : '弱気'}）`,
+							failure: `ダマシ（${p.poleDirection === 'up' ? '弱気転換' : '強気転換'}）`,
+						},
+					};
+					const meaning = meaningMap[p.type]?.[p.outcome] || `${directionJa}ブレイク`;
+
+					detail += `\n   - ブレイク方向: ${directionJa}ブレイク`;
+					if (expectedDir) detail += `（本来は${expectedDir}ブレイクが期待されるパターン）`;
+					detail += `\n   - パターン結果: ${outcomeJa}（${meaning}）`;
+				}
+
+				// ネックライン/トレンドラインがある場合（用語正規化ラベルを使用）
+				if (p.neckline && Array.isArray(p.neckline) && p.neckline.length >= 2) {
+					const label = p.trendlineLabel || 'ネックライン';
+					detail += `\n   - ${label}: ${Math.round(p.neckline[0]?.y || 0).toLocaleString('ja-JP')}円 → ${Math.round(p.neckline[1]?.y || 0).toLocaleString('ja-JP')}円`;
+				}
+
+				// ウェッジ固有: Apex（頂点）情報
+				if ((p.type === 'falling_wedge' || p.type === 'rising_wedge') && p.daysToApex != null) {
+					detail += `\n   - Apex（収束点）まで: ${p.daysToApex}本`;
+				}
+
+				// ターゲット価格情報（全パターン共通）
+				if (p.breakoutTarget != null) {
+					const methodJa: Record<string, string> = {
+						flagpole_projection: 'フラッグポール値幅投影',
+						pattern_height: 'パターン高さ投影',
+						neckline_projection: 'ネックライン投影',
+					};
+					detail += `\n   - ターゲット価格: ${Math.round(p.breakoutTarget).toLocaleString('ja-JP')}円（${(p.targetMethod && methodJa[p.targetMethod]) || p.targetMethod || '不明'}）`;
+					if (p.targetReachedPct != null) {
+						detail += `\n   - ターゲット進捗: ${p.targetReachedPct}%${p.targetReachedPct >= 100 ? '（到達済み）' : ''}`;
+					}
+				}
+
+				// ペナント固有フィールド
+				if (p.type === 'pennant') {
+					if (p.poleDirection) {
+						detail += `\n   - フラッグポール方向: ${p.poleDirection === 'up' ? '上昇' : '下降'}`;
+					}
+					if (p.priorTrendDirection) {
+						detail += `\n   - 先行トレンド: ${p.priorTrendDirection === 'bullish' ? '強気（上昇トレンド）' : '弱気（下降トレンド）'}`;
+					}
+					if (p.flagpoleHeight != null) {
+						detail += `\n   - フラッグポール値幅: ${Math.round(p.flagpoleHeight).toLocaleString('ja-JP')}円`;
+					}
+					if (p.retracementRatio != null) {
+						const pctStr = (p.retracementRatio * 100).toFixed(0);
+						detail += `\n   - 戻し比率: ${pctStr}%${p.retracementRatio > 0.38 ? '（高め — トライアングル寄り）' : '（正常範囲）'}`;
+					}
+					if (p.isTrendContinuation !== undefined) {
+						detail += `\n   - トレンド継続: ${p.isTrendContinuation ? 'はい（成功）' : 'いいえ（ダマシ）'}`;
+					}
+				}
+
+				return detail;
+			})
+			.join('\n\n');
+
+		// aftermath 統計をテキストに含める（LLM が structuredContent.data を読めない対策）
+		const statsText =
+			statistics && Object.keys(statistics).length > 0
+				? '\n\n【統計情報】\n' +
+					Object.entries(statistics)
+						.map(([k, v]) => `${k}: ${JSON.stringify(v)}`)
+						.join('\n')
+				: '';
+		// 検出対象期間を算出
+		let detectionPeriodText = '';
+		{
+			const allStarts = summaryPatterns
+				.map((p) => p.range?.start)
+				.filter((s): s is string => !!s)
+				.map((s) => Date.parse(s))
+				.filter(Number.isFinite);
+			const allEnds = summaryPatterns
+				.map((p) => p.range?.end)
+				.filter((s): s is string => !!s)
+				.map((s) => Date.parse(s))
+				.filter(Number.isFinite);
+			if (allStarts.length && allEnds.length) {
+				const s = dayjs(Math.min(...allStarts))
+					.toISOString()
+					.slice(0, 10);
+				const e = dayjs(Math.max(...allEnds))
+					.toISOString()
+					.slice(0, 10);
+				const days = Math.max(1, Math.round((Math.max(...allEnds) - Math.min(...allStarts)) / 86400000));
+				detectionPeriodText = `\n検出対象期間: ${s} ~ ${e}（${days}日間）`;
+			}
+		}
+		// タイプ別件数を集約（例: rising_wedge×3, falling_wedge×2）
+		const typeCounts: Record<string, number> = {};
+		for (const p of summaryPatterns) {
+			typeCounts[p.type] = (typeCounts[p.type] || 0) + 1;
+		}
+		const typeCountStr = Object.entries(typeCounts)
+			.map(([t, c]) => `${t}×${c}`)
+			.join(', ');
+
+		const summaryText =
+			`${pair.toUpperCase()} ${tfLabel}（${type}） ${limit}本から${patterns.length}件を検出（${typeCountStr}）${detectionPeriodText}\n\n【検出パターン（全件）】\n${patternSummaries || 'なし'}${statsText}\n\nチャート連携: data.overlays を render_chart_svg.overlays に渡すと注釈/範囲を描画できます。\n\nパターン整合度について（形状一致度・対称性・期間から算出）:\n  0.8以上 = 理想的な形状（教科書的パターン）\n  0.7-0.8 = 標準的な形状（他指標と併用推奨）\n  0.6-0.7 = やや不明瞭（慎重に判断）\n  0.6未満 = 形状不十分` +
+			`\n\n---\n📌 含まれるもの: チャートパターン検出（種類・整合度・期間）、ブレイク情報、統計` +
+			`\n📌 含まれないもの: 出来高によるパターン確認、テクニカル指標値、板情報` +
+			`\n📌 補完ツール: analyze_indicators（指標でパターンを裏付け）, get_flow_metrics（出来高確認）, get_orderbook（板情報）`;
+
+		const out = ok(
+			summaryText,
+			{ patterns, overlays: { ranges }, warnings, statistics },
+			{
+				pair,
+				type,
+				count: patterns.length,
+				effective_params: { swingDepth, minBarsBetweenSwings: minDist, tolerancePct, autoScaled },
+				visualization_hints: {
+					preferred_style: 'line',
+					highlight_patterns: patterns.map((p) => p.type).slice(0, 3),
+				},
+				debug: debugTrimmed,
+			},
+		);
+		return DetectPatternsOutputSchema.parse(out);
+	} catch (e: unknown) {
+		return failFromError(e, { schema: DetectPatternsOutputSchema });
+	}
+}

package/tools/detect_whale_events.ts

@@ -0,0 +1,181 @@
+import { z } from 'zod';
+import { TtlCache } from '../lib/cache.js';
+import { nowIso } from '../lib/datetime.js';
+import getDepth from '../lib/get-depth.js';
+import { fail, failFromError, failFromValidation, ok } from '../lib/result.js';
+import { createMeta, ensurePair } from '../lib/validate.js';
+import type { Result } from '../src/schemas.js';
+import type { ToolDefinition } from '../src/tool-definition.js';
+import getCandles from './get_candles.js';
+
+type Lookback = '30min' | '1hour' | '2hour';
+
+const cache = new TtlCache<Result>({ ttlMs: 60_000 });
+
+function extractLargeOrders(levels: Array<[number, number]>, minSize: number) {
+	return (levels || [])
+		.filter(([_p, s]) => Number(s) >= minSize)
+		.map(([p, s]) => ({ price: Number(p), size: Number(s) }));
+}
+
+function analyzeTrend(buyVol: number, sellVol: number): 'accumulation' | 'distribution' | 'neutral' {
+	if (buyVol > sellVol * 1.2) return 'accumulation';
+	if (sellVol > buyVol * 1.2) return 'distribution';
+	return 'neutral';
+}
+
+function generateRecommendation(trend: string): string {
+	if (trend === 'accumulation') return '買い圧力が優勢。段階的なエントリーを検討。';
+	if (trend === 'distribution') return '売り圧力が優勢。押し目待ち/警戒。';
+	return '均衡。レンジ内の値動きを想定。';
+}
+
+export default async function detectWhaleEvents(
+	pair: string = 'btc_jpy',
+	lookback: Lookback = '1hour',
+	minSize: number = 0.5,
+) {
+	const chk = ensurePair(pair);
+	if (!chk.ok) return failFromValidation(chk);
+
+	const cacheKey = `${chk.pair}:${lookback}:${minSize}`;
+	const hit = cache.get(cacheKey);
+	if (hit) return hit;
+
+	try {
+		const dep = await getDepth(chk.pair, { maxLevels: 200 });
+		if (!dep?.ok)
+			return fail(dep?.summary || 'depth failed', (dep?.meta as { errorType?: string })?.errorType || 'internal');
+		const rawAsks: Array<[string, string]> | undefined = dep?.data?.asks;
+		const rawBids: Array<[string, string]> | undefined = dep?.data?.bids;
+		if (!rawAsks || !rawBids) return fail('depth response missing asks/bids', 'upstream');
+		const asks: Array<[number, number]> = rawAsks.map(([p, s]) => [Number(p), Number(s)]);
+		const bids: Array<[number, number]> = rawBids.map(([p, s]) => [Number(p), Number(s)]);
+		const bestBid = bids.length ? Math.max(...bids.map(([p]) => p)) : null;
+		const bestAsk = asks.length ? Math.min(...asks.map(([p]) => p)) : null;
+		const mid = bestBid != null && bestAsk != null ? (bestBid + bestAsk) / 2 : null;
+
+		const lbMap: Record<Lookback, { type: string; limit: number }> = {
+			'30min': { type: '5min', limit: 6 },
+			'1hour': { type: '5min', limit: 12 },
+			'2hour': { type: '5min', limit: 24 },
+		};
+		const lb = lbMap[lookback] || lbMap['1hour'];
+		const candlesRes = await getCandles(chk.pair, lb.type, undefined, lb.limit);
+		if (!candlesRes?.ok)
+			return fail(
+				candlesRes?.summary || 'candles failed',
+				(candlesRes?.meta as { errorType?: string })?.errorType || 'internal',
+			);
+		const candles: Array<{ close: number }> = candlesRes?.data?.normalized || [];
+		const validCloses = candles
+			.map((c) => c.close)
+			.filter((v): v is number => typeof v === 'number' && Number.isFinite(v));
+		const priceChange =
+			validCloses.length >= 2 ? (validCloses[validCloses.length - 1] - validCloses[0]) / validCloses[0] : 0;
+
+		const largeBids = extractLargeOrders(bids, minSize);
+		const largeAsks = extractLargeOrders(asks, minSize);
+
+		const buyVol = largeBids.reduce((s, o) => s + o.size, 0);
+		const sellVol = largeAsks.reduce((s, o) => s + o.size, 0);
+		const trend = analyzeTrend(buyVol, sellVol);
+		const recommendation = generateRecommendation(trend);
+
+		const annotate = (side: 'buy' | 'sell') => (o: { price: number; size: number }) => ({
+			side,
+			price: o.price,
+			size: Number(o.size.toFixed(3)),
+			distancePct: mid ? Number((((o.price - mid) / mid) * 100).toFixed(2)) : null,
+		});
+		const events = [...largeBids.map(annotate('buy')), ...largeAsks.map(annotate('sell'))]
+			.sort((a, b) => Math.abs(a.distancePct || 0) - Math.abs(b.distancePct || 0))
+			.slice(0, 20);
+
+		// Visualization: buy/sell balance
+		const totalVol = buyVol + sellVol;
+		const buyPct = totalVol > 0 ? buyVol / totalVol : 0;
+		const sellPct = totalVol > 0 ? sellVol / totalVol : 0;
+		const barLen = 14;
+		const buyBars = '█'.repeat(Math.max(0, Math.round(buyPct * barLen)));
+		const sellBars = '█'.repeat(Math.max(0, Math.round(sellPct * barLen)));
+
+		// Distance stats
+		const buyDists = largeBids
+			.map((o) => (mid ? ((o.price - mid) / mid) * 100 : null))
+			.filter((x): x is number => x != null);
+		const sellDists = largeAsks
+			.map((o) => (mid ? ((o.price - mid) / mid) * 100 : null))
+			.filter((x): x is number => x != null);
+		const avg = (arr: number[]) => (arr.length ? arr.reduce((s, v) => s + v, 0) / arr.length : 0);
+		const avgBuyDist = avg(buyDists);
+		const avgSellDist = avg(sellDists);
+
+		const text = [
+			`=== ${chk.pair.toUpperCase()} 大口動向分析（過去${lookback}）===`,
+			'',
+			`🐋 検出された大口: ${events.length}件`,
+			`買い: ${largeBids.length}件（合計${buyVol.toFixed(2)} BTC）`,
+			`売り: ${largeAsks.length}件（合計${sellVol.toFixed(2)} BTC）`,
+			'',
+			'📊 買い/売りバランス:',
+			`   買い: ${buyBars} ${buyVol.toFixed(2)} BTC (${(buyPct * 100).toFixed(0)}%)`,
+			`   売り: ${sellBars} ${sellVol.toFixed(2)} BTC (${(sellPct * 100).toFixed(0)}%)`,
+			'',
+			'📏 距離の統計:',
+			`   平均距離: 買い ${avgBuyDist.toFixed(2)}%, 売り ${avgSellDist.toFixed(2)}%`,
+			'',
+			'📋 主要な大口:',
+			...events.map(
+				(e) =>
+					`${e.side === 'buy' ? '🟢' : '🔴'} ${e.price.toLocaleString('ja-JP')}円に${e.size} BTC（${e.side === 'buy' ? '買い' : '売り'}）距離: ${e.distancePct != null ? `${(e.distancePct >= 0 ? '+' : '') + e.distancePct}%` : 'n/a'}`,
+			),
+			'',
+			`📈 過去${lookback}の価格変化: ${(priceChange * 100).toFixed(2)}%`,
+			'',
+			`💡 総合評価: ${trend === 'accumulation' ? '買い圧力優勢' : trend === 'distribution' ? '売り圧力優勢' : '均衡'}（${trend}）`,
+			recommendation,
+			'',
+			'※ 注: 推測ベースの簡易分析です（実約定・寿命照合は未実装）。',
+			'',
+			'---',
+			'📌 含まれるもの: 現在の板から検出した大口注文（買い/売り・価格・サイズ・距離）、バランス分析',
+			'📌 含まれないもの: 過去の大口動向の時系列変化、全体の出来高フロー、テクニカル指標',
+			'📌 補完ツール: get_flow_metrics（出来高フロー・CVD）, get_orderbook（板の詳細分析）, analyze_indicators（指標）',
+		].join('\n');
+
+		const data = {
+			events,
+			stats: {
+				buyOrders: largeBids.length,
+				sellOrders: largeAsks.length,
+				buyVolume: Number(buyVol.toFixed(3)),
+				sellVolume: Number(sellVol.toFixed(3)),
+				trend,
+				recommendation,
+			},
+			meta: { lookback, minSize },
+		};
+
+		const meta = createMeta(chk.pair, { fetchedAt: nowIso() });
+		const out = ok(text, data, meta);
+		cache.set(cacheKey, out);
+		return out;
+	} catch (e: unknown) {
+		return failFromError(e);
+	}
+}
+
+// ── MCP ツール定義（tool-registry から自動収集） ──
+export const toolDef: ToolDefinition = {
+	name: 'detect_whale_events',
+	description:
+		'[Whale / Large Orders / Big Players] 大口投資家の動向検出（whale / large orders / big players / smart money）。板×ローソク足で大口注文を簡易検出。推測ベース。',
+	inputSchema: z.object({
+		pair: z.string().default('btc_jpy'),
+		lookback: z.enum(['30min', '1hour', '2hour']).default('1hour'),
+		minSize: z.number().min(0).default(0.5),
+	}),
+	handler: async ({ pair, lookback, minSize }: { pair: string; lookback: Lookback; minSize: number }) =>
+		detectWhaleEvents(pair, lookback, minSize),
+};