bitbank-lab-mcp 0.1.0

package/tools/prepare_chart_data.ts

@@ -0,0 +1,294 @@
+/**
+ * prepare_chart_data — Visualizer / チャート描画用の時系列データを返す。
+ *
+ * analyze_indicators の chart (ChartPayload) を内部で呼び出し、
+ * コンパクトな配列形式に整形して返す。
+ * 一目均衡表の chikou シフトは適用済み。
+ *
+ * デフォルトではローソク足（OHLCV）のみ返す。
+ * indicators パラメータで指標グループを明示指定した場合のみ、その系列を付加する。
+ */
+
+import { dayjs, toIsoWithTz } from '../lib/datetime.js';
+import { fail, failFromError, ok, toStructured } from '../lib/result.js';
+import { createMeta, ensurePair } from '../lib/validate.js';
+import type { Candle, FailResult, NumericSeries, OkResult } from '../src/schemas.js';
+import { PrepareChartDataInputSchema } from '../src/schemas.js';
+import type { ToolDefinition } from '../src/tool-definition.js';
+import analyzeIndicators from './analyze_indicators.js';
+
+// ── candles 配列の各要素の意味 ──
+const CANDLE_FORMAT = ['open', 'high', 'low', 'close', 'volume'] as const;
+
+// ── 指標グループ → chart.indicators キーのマッピング ──
+
+const MAIN_SERIES_KEYS: Record<string, string[]> = {
+	SMA_5: ['SMA_5'],
+	SMA_20: ['SMA_20'],
+	SMA_25: ['SMA_25'],
+	SMA_50: ['SMA_50'],
+	SMA_75: ['SMA_75'],
+	SMA_200: ['SMA_200'],
+	EMA_12: ['EMA_12'],
+	EMA_26: ['EMA_26'],
+	EMA_50: ['EMA_50'],
+	EMA_200: ['EMA_200'],
+	BB: ['BB_upper', 'BB_middle', 'BB_lower'],
+	ICHIMOKU: ['ICHI_tenkan', 'ICHI_kijun', 'ICHI_spanA', 'ICHI_spanB', 'ICHI_chikou'],
+};
+
+/** JPY ペアかどうか判定 */
+function isJpyPair(pair: string): boolean {
+	return pair.endsWith('_jpy');
+}
+
+/** 数値を丸める（JPY ペアは整数、それ以外は小数2桁） */
+function roundValue(v: number | null, jpyPair: boolean): number | null {
+	if (v === null) return null;
+	return jpyPair ? Math.round(v) : Number(v.toFixed(2));
+}
+
+/** 系列が全て null かどうか判定 */
+function isAllNull(series: NumericSeries): boolean {
+	return series.every((v) => v === null);
+}
+
+/** NumericSeries → 丸め済み値配列（全 null なら undefined） */
+function toRoundedArray(series: NumericSeries, jpyPair: boolean): (number | null)[] | undefined {
+	if (isAllNull(series)) return undefined;
+	return series.map((v) => roundValue(v, jpyPair));
+}
+
+// ── コンパクト出力型 ──
+
+interface CompactCandle {
+	/** [open, high, low, close, volume] */
+	ohlcv: number[];
+}
+
+interface CompactSubPanels {
+	RSI_14?: (number | null)[];
+	MACD?: { line: (number | null)[]; signal: (number | null)[]; hist: (number | null)[] };
+	STOCH_K?: (number | null)[];
+	STOCH_D?: (number | null)[];
+}
+
+interface PrepareChartDataResult {
+	times: string[];
+	labels?: string[];
+	candleFormat: readonly string[];
+	candles: CompactCandle['ohlcv'][];
+	series?: Record<string, (number | null)[]>;
+	subPanels?: CompactSubPanels;
+}
+
+interface PrepareChartDataMeta {
+	pair: string;
+	type: string;
+	count: number;
+	indicators: string[];
+	volumeUnit: string;
+}
+
+/**
+ * CandleType に応じた短縮ラベルフォーマットを返す。
+ * 日足以上は "MM/DD"、それ以外は "MM/DD HH:mm"。
+ */
+function labelFormat(candleType: string): string {
+	switch (candleType) {
+		case '1day':
+		case '1week':
+		case '1month':
+			return 'MM/DD';
+		default:
+			return 'MM/DD HH:mm';
+	}
+}
+
+export default async function prepareChartData(
+	pair: string = 'btc_jpy',
+	type: string = '1day',
+	limit: number = 30,
+	indicators?: string[],
+	tz: string = 'Asia/Tokyo',
+): Promise<OkResult<PrepareChartDataResult, PrepareChartDataMeta> | FailResult> {
+	const chk = ensurePair(pair);
+	if (!chk.ok) return fail(chk.error.message, chk.error.type);
+
+	// サーバー側ガード: limit × インジケーター系列数がしきい値を超える場合、limit を自動切り詰め
+	const MAX_TOTAL_SERIES = 150; // limit × (1 + indicatorCount) の上限
+	const indicatorCount = indicators?.length ?? 0;
+	const seriesMultiplier = 1 + indicatorCount; // 1 = OHLCV 本体
+	let effectiveLimit = limit;
+	if (seriesMultiplier > 1 && limit * seriesMultiplier > MAX_TOTAL_SERIES) {
+		effectiveLimit = Math.max(5, Math.floor(MAX_TOTAL_SERIES / seriesMultiplier));
+	}
+
+	const jpyPair = isJpyPair(chk.pair);
+
+	try {
+		const res = await analyzeIndicators(chk.pair, type, effectiveLimit);
+		if (!res.ok) return fail(res.summary.replace(/^Error: /, ''), res.meta.errorType);
+
+		const chart = res.data.chart;
+		const candles = chart.candles.slice(-effectiveLimit);
+		const chartIndicators = chart.indicators as Record<string, unknown>;
+
+		// 指標フィルタ: 指定がなければ空（ローソク足のみ）
+		const selectedGroups = indicators && indicators.length > 0 ? new Set(indicators) : new Set<string>();
+
+		// 共有タイムスタンプ（tz 指定時はローカル時刻に変換）
+		const useTz = typeof tz === 'string' && tz.length > 0;
+		const fmt = labelFormat(type);
+		const times: string[] = [];
+		const labels: string[] | undefined = useTz ? [] : undefined;
+
+		for (const c of candles) {
+			const iso = c.isoTime ?? '';
+			if (!useTz || !iso) {
+				times.push(iso);
+			} else {
+				const ms = dayjs.utc(iso).valueOf();
+				times.push(toIsoWithTz(ms, tz) ?? iso);
+				labels?.push(dayjs(ms).tz(tz).format(fmt));
+			}
+		}
+
+		// コンパクトなローソク足配列: [o, h, l, c, v]
+		const compactCandles = candles.map((c: Candle) => {
+			const o = roundValue(c.open, jpyPair) ?? c.open;
+			const h = roundValue(c.high, jpyPair) ?? c.high;
+			const l = roundValue(c.low, jpyPair) ?? c.low;
+			const cl = roundValue(c.close, jpyPair) ?? c.close;
+			const v = c.volume ?? 0;
+			return [o, h, l, cl, v];
+		});
+
+		// メインパネル系列の構築（全 null 系列は除外）
+		const series: Record<string, (number | null)[]> = {};
+		for (const [group, keys] of Object.entries(MAIN_SERIES_KEYS)) {
+			if (!selectedGroups.has(group)) continue;
+			for (const key of keys) {
+				const arr = chartIndicators[key];
+				if (!Array.isArray(arr)) continue;
+				const sliced = (arr as NumericSeries).slice(-effectiveLimit);
+				const rounded = toRoundedArray(sliced, jpyPair);
+				if (rounded) {
+					series[key] = rounded;
+				}
+			}
+		}
+
+		// サブパネル系列の構築
+		const subPanels: CompactSubPanels = {};
+
+		if (selectedGroups.has('RSI')) {
+			const rsiArr = chartIndicators.RSI_14_series;
+			if (Array.isArray(rsiArr)) {
+				const sliced = (rsiArr as NumericSeries).slice(-effectiveLimit);
+				const rounded = toRoundedArray(sliced, false); // RSI は 0-100 なので小数2桁を維持
+				if (rounded) subPanels.RSI_14 = rounded;
+			}
+		}
+
+		if (selectedGroups.has('MACD')) {
+			const macdData = chartIndicators.macd_series as
+				| { line: NumericSeries; signal: NumericSeries; hist: NumericSeries }
+				| undefined;
+			if (macdData) {
+				const line = toRoundedArray(macdData.line.slice(-effectiveLimit), jpyPair);
+				const signal = toRoundedArray(macdData.signal.slice(-effectiveLimit), jpyPair);
+				const hist = toRoundedArray(macdData.hist.slice(-effectiveLimit), jpyPair);
+				if (line || signal || hist) {
+					subPanels.MACD = {
+						line: line ?? macdData.line.slice(-effectiveLimit),
+						signal: signal ?? macdData.signal.slice(-effectiveLimit),
+						hist: hist ?? macdData.hist.slice(-effectiveLimit),
+					};
+				}
+			}
+		}
+
+		if (selectedGroups.has('STOCH')) {
+			const stochK = chartIndicators.stoch_k_series;
+			const stochD = chartIndicators.stoch_d_series;
+			if (Array.isArray(stochK)) {
+				const rounded = toRoundedArray((stochK as NumericSeries).slice(-effectiveLimit), false);
+				if (rounded) subPanels.STOCH_K = rounded;
+			}
+			if (Array.isArray(stochD)) {
+				const rounded = toRoundedArray((stochD as NumericSeries).slice(-effectiveLimit), false);
+				if (rounded) subPanels.STOCH_D = rounded;
+			}
+		}
+
+		const hasSeries = Object.keys(series).length > 0;
+		const hasSubPanels = Object.keys(subPanels).length > 0;
+		const indicatorNames = [...Object.keys(series), ...Object.keys(subPanels)];
+
+		const data: PrepareChartDataResult = {
+			times,
+			...(labels ? { labels } : {}),
+			candleFormat: CANDLE_FORMAT,
+			candles: compactCandles,
+			...(hasSeries ? { series } : {}),
+			...(hasSubPanels ? { subPanels } : {}),
+		};
+
+		// 出来高の単位はペアのベース通貨（例: btc_jpy → BTC）
+		const volumeUnit = chk.pair.split('_')[0].toUpperCase();
+
+		const meta: PrepareChartDataMeta = {
+			...createMeta(chk.pair),
+			type,
+			count: candles.length,
+			indicators: indicatorNames,
+			volumeUnit,
+		};
+
+		const seriesNote = indicatorNames.length > 0 ? `, indicators: ${indicatorNames.join(', ')}` : '';
+		const truncNote =
+			effectiveLimit < limit ? ` ⚠️ limit was capped from ${limit} to ${effectiveLimit} to reduce context size` : '';
+		return ok(`${chk.pair} ${type} chart data (${candles.length} candles${seriesNote})${truncNote}`, data, meta);
+	} catch (err: unknown) {
+		return failFromError(err);
+	}
+}
+
+export const toolDef: ToolDefinition = {
+	name: 'prepare_chart_data',
+	description:
+		'[Chart / Candlestick / Visualization] チャート描画の第一選択ツール。\n\n' +
+		'⚠️ limit はデフォルト 30 を推奨。ユーザーが期間を明示した場合のみ増やすこと。\n' +
+		'indicators はユーザーが明示的に要求した指標のみ指定すること。分析のついでに追加しない。\n' +
+		'indicators の同時指定はコンテキストを大幅に消費するため、必要最小限に留めること。\n\n' +
+		'デフォルトはローソク足（OHLCV）のみ返す。indicators 未指定 = ローソク足のみ。\n' +
+		'指標が必要な場合は indicators に明示指定: SMA_5, SMA_20, SMA_25, SMA_50, SMA_75, SMA_200, EMA_12, EMA_26, EMA_50, EMA_200, BB, ICHIMOKU, RSI, MACD, STOCH\n\n' +
+		'レスポンス形式: { times[], labels?[], candles: [[o,h,l,c,v],...], series?: {指標名: values[]}, subPanels?: {...} }\n' +
+		'JPY ペアの価格は整数に丸め済み。全 null 系列は自動除外。\n\n' +
+		'tz パラメータ（例: "Asia/Tokyo"）指定時、times がローカル時刻に変換され、labels（"03/16 17:00" 等の短縮表示文字列）も付加される。\n\n' +
+		'SVG/PNG ファイル保存 → render_chart_svg。指標の最新値やトレンド判定 → analyze_indicators。',
+	inputSchema: PrepareChartDataInputSchema,
+	handler: async ({
+		pair,
+		type,
+		limit,
+		indicators,
+		tz,
+	}: {
+		pair?: string;
+		type?: string;
+		limit?: number;
+		indicators?: string[];
+		tz?: string;
+	}) => {
+		const result = await prepareChartData(pair ?? 'btc_jpy', type ?? '1day', limit ?? 30, indicators, tz);
+		if (!result.ok) return result;
+		// LLM は structuredContent を参照できないため、content テキストにデータを含める
+		const text = `${result.summary}\n${JSON.stringify(result.data)}`;
+		return {
+			content: [{ type: 'text', text }],
+			structuredContent: toStructured(result),
+		};
+	},
+};

package/tools/prepare_depth_data.ts

@@ -0,0 +1,189 @@
+/**
+ * prepare_depth_data — Visualizer / 板深度チャート描画用の累積データを返す。
+ *
+ * getDepth（/depth API）を呼び出し、price × cumulative volume の階段配列として
+ * コンパクトに整形する。render_depth_svg と同じ累積計算ロジック（lib/depth-analysis）
+ * を共有する。
+ *
+ * クライアント側（Claude.ai Visualizer 等）で描画可能な場合はこのツールを優先。
+ * ファイル保存が必要な場合は render_depth_svg を使用すること。
+ */
+
+import { toIsoTime } from '../lib/datetime.js';
+import { buildCumulativeSteps } from '../lib/depth-analysis.js';
+import getDepth from '../lib/get-depth.js';
+import { fail, failFromError, failFromValidation, ok, toStructured } from '../lib/result.js';
+import { createMeta, ensurePair } from '../lib/validate.js';
+import type { FailResult, OkResult, Pair } from '../src/schemas.js';
+import { PrepareDepthDataInputSchema } from '../src/schemas.js';
+import type { ToolDefinition } from '../src/tool-definition.js';
+
+/** 価格を「JPY ペアなら整数、それ以外は小数2桁」で丸める */
+function roundPrice(p: number, jpyPair: boolean): number {
+	return jpyPair ? Math.round(p) : Number(p.toFixed(2));
+}
+
+/** Volume は固定小数桁に丸める */
+function roundVolume(v: number): number {
+	return Number(v.toFixed(6));
+}
+
+interface PrepareDepthDataResult {
+	/** bids: 高価格 → 低価格 の [price, cumulativeVolume] 階段データ */
+	bids: Array<[number, number]>;
+	/** asks: 低価格 → 高価格 の [price, cumulativeVolume] 階段データ */
+	asks: Array<[number, number]>;
+	bestBid: number | null;
+	bestAsk: number | null;
+	/** (bestBid + bestAsk) / 2 */
+	mid: number | null;
+	/** bestAsk - bestBid */
+	spread: number | null;
+	/** spread / mid */
+	spreadPct: number | null;
+	/** 買い板全体の累積量 */
+	totalBidVolume: number;
+	/** 売り板全体の累積量 */
+	totalAskVolume: number;
+	/** mid を中心とする ±bandPct% 範囲の買い/売り量と比率 */
+	band: {
+		pct: number;
+		bidVolume: number;
+		askVolume: number;
+		ratio: number | null;
+	};
+	/** 板取得時刻（Unix ms） */
+	timestamp: number;
+	/** 板取得時刻（ISO8601, UTC） */
+	isoTime: string | null;
+}
+
+interface PrepareDepthDataMeta {
+	pair: Pair;
+	fetchedAt: string;
+	levels: { bids: number; asks: number };
+	/** 出来高の単位（ペアのベース通貨。例: btc_jpy → "BTC"） */
+	volumeUnit: string;
+}
+
+export interface PrepareDepthDataParams {
+	pair?: string;
+	/** 取得する最大レベル数（片側） */
+	levels?: number;
+	/** mid を中心とした band 比率（0.01 = ±1%） */
+	bandPct?: number;
+}
+
+export default async function prepareDepthData(
+	params: PrepareDepthDataParams = {},
+): Promise<OkResult<PrepareDepthDataResult, PrepareDepthDataMeta> | FailResult> {
+	const { pair = 'btc_jpy', levels = 200, bandPct = 0.01 } = params;
+
+	const chk = ensurePair(pair);
+	if (!chk.ok) return failFromValidation(chk);
+
+	const maxLevels = Math.max(10, Math.min(1000, Math.floor(levels)));
+	const jpyPair = chk.pair.endsWith('_jpy');
+
+	try {
+		const depth = await getDepth(chk.pair, { maxLevels });
+		if (!depth.ok) return fail(depth.summary.replace(/^Error: /, ''), depth.meta?.errorType || 'internal');
+
+		const asksRaw: Array<[string, string]> = depth.data.asks || [];
+		const bidsRaw: Array<[string, string]> = depth.data.bids || [];
+
+		if (!asksRaw.length || !bidsRaw.length) {
+			return fail('板データが不足しています（asks/bids の両方が必要です）', 'upstream');
+		}
+
+		const bidsNum = bidsRaw.map(([p, s]) => [Number(p), Number(s)] as [number, number]);
+		const asksNum = asksRaw.map(([p, s]) => [Number(p), Number(s)] as [number, number]);
+
+		const bidStepsRaw = buildCumulativeSteps(bidsNum, 'bid');
+		const askStepsRaw = buildCumulativeSteps(asksNum, 'ask');
+
+		const bidSteps: Array<[number, number]> = bidStepsRaw.map(([p, q]) => [roundPrice(p, jpyPair), roundVolume(q)]);
+		const askSteps: Array<[number, number]> = askStepsRaw.map(([p, q]) => [roundPrice(p, jpyPair), roundVolume(q)]);
+
+		const bestBid = bidStepsRaw[0]?.[0] ?? null;
+		const bestAsk = askStepsRaw[0]?.[0] ?? null;
+		const mid = bestBid != null && bestAsk != null ? (bestBid + bestAsk) / 2 : null;
+		const spread = bestBid != null && bestAsk != null ? bestAsk - bestBid : null;
+		const spreadPct = mid != null && spread != null && mid !== 0 ? Number((spread / mid).toFixed(6)) : null;
+
+		const totalBidVolume = bidStepsRaw.at(-1)?.[1] ?? 0;
+		const totalAskVolume = askStepsRaw.at(-1)?.[1] ?? 0;
+
+		// mid を中心とした band 集計
+		let bandBidVol = 0;
+		let bandAskVol = 0;
+		if (mid != null) {
+			const bidFloor = mid * (1 - bandPct);
+			const askCeil = mid * (1 + bandPct);
+			for (const [p, s] of bidsNum) if (p >= bidFloor && p <= mid) bandBidVol += s;
+			for (const [p, s] of asksNum) if (p >= mid && p <= askCeil) bandAskVol += s;
+		}
+		const bandRatio = bandAskVol > 0 ? Number((bandBidVol / bandAskVol).toFixed(4)) : null;
+
+		const timestamp = Number(depth.data.timestamp ?? Date.now());
+
+		const data: PrepareDepthDataResult = {
+			bids: bidSteps,
+			asks: askSteps,
+			bestBid: bestBid != null ? roundPrice(bestBid, jpyPair) : null,
+			bestAsk: bestAsk != null ? roundPrice(bestAsk, jpyPair) : null,
+			mid: mid != null ? roundPrice(mid, jpyPair) : null,
+			spread: spread != null ? roundPrice(spread, jpyPair) : null,
+			spreadPct,
+			totalBidVolume: roundVolume(totalBidVolume),
+			totalAskVolume: roundVolume(totalAskVolume),
+			band: {
+				pct: bandPct,
+				bidVolume: roundVolume(bandBidVol),
+				askVolume: roundVolume(bandAskVol),
+				ratio: bandRatio,
+			},
+			timestamp,
+			isoTime: toIsoTime(timestamp),
+		};
+
+		const volumeUnit = chk.pair.split('_')[0].toUpperCase();
+		const meta: PrepareDepthDataMeta = {
+			...createMeta(chk.pair),
+			levels: { bids: bidSteps.length, asks: askSteps.length },
+			volumeUnit,
+		} as PrepareDepthDataMeta;
+
+		const ratioText = bandRatio == null ? 'n/a' : bandRatio.toFixed(2);
+		const summary = `${chk.pair} depth data (bids: ${bidSteps.length}, asks: ${askSteps.length}, mid: ${data.mid ?? 'n/a'}, ±${(bandPct * 100).toFixed(2)}% ratio: ${ratioText})`;
+		return ok<PrepareDepthDataResult, PrepareDepthDataMeta>(summary, data, meta);
+	} catch (err: unknown) {
+		return failFromError(err, { defaultMessage: '板深度データの整形に失敗しました' });
+	}
+}
+
+export type { PrepareDepthDataMeta, PrepareDepthDataResult };
+
+export const toolDef: ToolDefinition = {
+	name: 'prepare_depth_data',
+	description:
+		'[Depth Chart / Order Book / Visualization] 板の深度チャート描画の第一選択ツール。\n\n' +
+		'getDepth（/depth API）を呼び出し、累積 volume の階段配列 ([price, cumulativeVolume][]) として返す。\n' +
+		'Claude.ai の Visualizer 等クライアント側で描画可能な場合はこのツールを優先。\n' +
+		'ファイル保存（SVG/PNG）が必要な場合は render_depth_svg を使用。\n\n' +
+		'レスポンス形式: { bids: [[price, cumVolume], ...], asks: [[price, cumVolume], ...], bestBid, bestAsk, mid, spread, spreadPct, totalBidVolume, totalAskVolume, band: {pct, bidVolume, askVolume, ratio}, timestamp, isoTime }\n' +
+		'- bids は価格降順、asks は価格昇順\n' +
+		'- band は mid を中心とした ±bandPct 範囲の買い/売り量と比率（ratio = bidVolume / askVolume）\n' +
+		'- JPY ペアの価格は整数に丸め済み',
+	inputSchema: PrepareDepthDataInputSchema,
+	handler: async ({ pair, levels, bandPct }: { pair?: string; levels?: number; bandPct?: number }) => {
+		const result = await prepareDepthData({ pair, levels, bandPct });
+		if (!result.ok) return result;
+		// LLM は structuredContent を参照できないため、content テキストにデータを含める
+		const text = `${result.summary}\n${JSON.stringify(result.data)}`;
+		return {
+			content: [{ type: 'text', text }],
+			structuredContent: toStructured(result),
+		};
+	},
+};

package/tools/private/analyze_my_portfolio.ts

@@ -0,0 +1,21 @@
+/**
+ * analyze_my_portfolio — ポートフォリオ分析ツール（Phase 3 + Phase 4 拡張）。
+ *
+ * 保有資産・約定履歴・入出金履歴・テクニカル分析を統合し、
+ * 損益状況とポートフォリオ全体の評価を LLM に提供する。
+ * 入出金データがあれば口座全体のリターンを概算する。
+ */
+
+import analyzeMyPortfolioHandler from '../../src/handlers/analyzeMyPortfolioHandler.js';
+import { AnalyzeMyPortfolioInputSchema } from '../../src/private/schemas.js';
+import type { ToolDefinition } from '../../src/tool-definition.js';
+
+// ── MCP ツール定義（tool-registry から自動収集） ──
+export const toolDef: ToolDefinition = {
+	name: 'analyze_my_portfolio',
+	description:
+		'[Portfolio Analysis / PnL] 自分のポートフォリオ分析（portfolio / pnl / balance / return）。保有資産の評価損益・実現損益・口座リターンを一括算出。テクニカル分析統合オプション付き。Private API（要APIキー設定）。',
+	inputSchema: AnalyzeMyPortfolioInputSchema,
+	handler: async (args: { include_technical?: boolean; include_pnl?: boolean; include_deposit_withdrawal?: boolean }) =>
+		analyzeMyPortfolioHandler(args),
+};

package/tools/private/cancel_order.ts

@@ -0,0 +1,127 @@
+/**
+ * cancel_order — 注文をキャンセルする Private API ツール。
+ *
+ * bitbank Private API `POST /v1/user/spot/cancel_order` を呼び出し、
+ * 指定した注文IDの注文をキャンセルする。
+ *
+ * エラーケース:
+ * - 50009: 注文が見つからない
+ * - 50010: キャンセル不可（既にキャンセル・約定済みなど）
+ * - 50026: 既にキャンセル済み
+ * - 50027: 既に約定済み
+ */
+
+import { nowIso, toIsoMs } from '../../lib/datetime.js';
+import { formatPair, formatPrice } from '../../lib/formatter.js';
+import { logTradeAction } from '../../lib/logger.js';
+import { fail, ok, toStructured } from '../../lib/result.js';
+import { getDefaultClient, PrivateApiError } from '../../src/private/client.js';
+import { validateToken } from '../../src/private/confirmation.js';
+import type { OrderResponse } from '../../src/private/schemas.js';
+import { CancelOrderInputSchema, CancelOrderOutputSchema } from '../../src/private/schemas.js';
+import type { ToolDefinition } from '../../src/tool-definition.js';
+
+export default async function cancelOrder(
+	args: {
+		pair: string;
+		order_id: number;
+		confirmation_token: string;
+		token_expires_at: number;
+	},
+	route: 'elicitation' | 'ui-button' | 'direct-text' = 'direct-text',
+) {
+	const { pair, order_id, confirmation_token, token_expires_at } = args;
+
+	// HITL: 確認トークンの検証
+	const tokenError = validateToken(confirmation_token, 'cancel_order', { pair, order_id }, token_expires_at);
+	if (tokenError) {
+		return CancelOrderOutputSchema.parse(fail(tokenError.message, tokenError.code));
+	}
+
+	const client = getDefaultClient();
+
+	try {
+		const rawOrder = await client.post<OrderResponse>('/v1/user/spot/cancel_order', {
+			pair,
+			order_id,
+		});
+
+		const timestamp = nowIso();
+		const isJpy = pair.includes('jpy');
+		const sideLabel = rawOrder.side === 'buy' ? '買' : '売';
+		const price = rawOrder.price ? (isJpy ? formatPrice(Number(rawOrder.price)) : rawOrder.price) : '成行';
+		const amount = rawOrder.start_amount ?? rawOrder.executed_amount;
+
+		const lines: string[] = [];
+		lines.push(`注文キャンセル完了: ${formatPair(pair)}`);
+		lines.push(`  注文ID: ${order_id}`);
+		lines.push(`  ${sideLabel} ${rawOrder.type} ${amount} @ ${price}`);
+		lines.push(`  ステータス: ${rawOrder.status}`);
+		if (rawOrder.executed_amount && rawOrder.executed_amount !== '0') {
+			lines.push(`  約定済み数量: ${rawOrder.executed_amount}`);
+		}
+		lines.push(
+			`  キャンセル日時: ${rawOrder.canceled_at ? (toIsoMs(rawOrder.canceled_at) ?? String(rawOrder.canceled_at)) : timestamp}`,
+		);
+
+		const summary = lines.join('\n');
+
+		logTradeAction({
+			type: 'cancel_order',
+			orderId: order_id,
+			pair,
+			side: rawOrder.side,
+			status: rawOrder.status,
+			confirmed: true,
+			route,
+		});
+
+		return CancelOrderOutputSchema.parse(
+			ok(
+				summary,
+				{ order: rawOrder, timestamp },
+				{
+					fetchedAt: timestamp,
+					orderId: order_id,
+					pair,
+					...(client.lastRateLimit ? { rateLimit: client.lastRateLimit } : {}),
+				},
+			),
+		);
+	} catch (err) {
+		if (err instanceof PrivateApiError) {
+			// キャンセル固有エラーの補足メッセージ
+			const codeMessages: Record<number, string> = {
+				50009: '指定された注文が見つかりません（3ヶ月以上前の注文は参照不可）',
+				50010: 'この注文はキャンセルできません',
+				50026: 'この注文は既にキャンセル済みです',
+				50027: 'この注文は既に約定済みです',
+			};
+			const msg = (err.bitbankCode && codeMessages[err.bitbankCode]) || err.message;
+			return CancelOrderOutputSchema.parse(fail(msg, err.errorType));
+		}
+		return CancelOrderOutputSchema.parse(
+			fail(err instanceof Error ? err.message : '注文キャンセル中に予期しないエラーが発生しました', 'upstream_error'),
+		);
+	}
+}
+
+export const toolDef: ToolDefinition = {
+	name: 'cancel_order',
+	description:
+		'[Cancel Order] 指定した注文IDの注文をキャンセルする。キャンセル後の注文情報を返す。Private API。' +
+		' ⚠️ 事前に preview_cancel_order で確認トークンを取得し、confirmation_token と token_expires_at を渡すこと。' +
+		' トークンなしの直接呼び出しは拒否される。',
+	inputSchema: CancelOrderInputSchema,
+	handler: async (args) => {
+		const result = await cancelOrder(
+			args as { pair: string; order_id: number; confirmation_token: string; token_expires_at: number },
+		);
+		if (!result.ok) return result;
+		const text = `${result.summary}\n${JSON.stringify(result.data, null, 2)}`;
+		return {
+			content: [{ type: 'text', text }],
+			structuredContent: toStructured(result),
+		};
+	},
+};