bitbank-lab-mcp 0.1.0

package/tools/private/get_margin_trade_history.ts

@@ -0,0 +1,156 @@
+/**
+ * get_margin_trade_history — 信用取引の約定履歴を取得する Private API ツール。
+ *
+ * bitbank Private API `/v1/user/spot/trade_history` に `type=margin` を指定し、
+ * 信用取引の約定（新規建て・決済）のみを取得して返す。
+ *
+ * 注意: since を信用新規建て後の日時に指定した場合、
+ * 対応する決済約定のみが返される可能性があります。
+ */
+
+import { nowIso, parseIso8601, toIsoMs } from '../../lib/datetime.js';
+import { formatPair, formatPrice } from '../../lib/formatter.js';
+import { fail, ok } from '../../lib/result.js';
+import { getDefaultClient, PrivateApiError } from '../../src/private/client.js';
+import { GetMarginTradeHistoryInputSchema, GetMarginTradeHistoryOutputSchema } from '../../src/private/schemas.js';
+import type { ToolDefinition } from '../../src/tool-definition.js';
+
+/** bitbank /v1/user/spot/trade_history のレスポンス型（信用取引フィルタ時） */
+interface RawMarginTrade {
+	trade_id: number;
+	pair: string;
+	order_id: number;
+	side: string;
+	position_side?: string;
+	type: string;
+	amount: string;
+	price: string;
+	maker_taker: string;
+	fee_amount_base: string;
+	fee_amount_quote: string;
+	profit_loss?: string;
+	interest?: string;
+	executed_at: number;
+}
+
+export default async function getMarginTradeHistory(args: {
+	pair?: string;
+	count?: number;
+	order?: 'asc' | 'desc';
+	since?: string;
+	end?: string;
+}) {
+	const { pair, count = 20, order = 'desc', since, end } = args;
+	const client = getDefaultClient();
+
+	try {
+		const params: Record<string, string> = { type: 'margin' };
+		if (pair) params.pair = pair;
+		if (count !== 20) params.count = String(count);
+		if (order !== 'desc') params.order = order;
+
+		// ISO8601 → unix ms 変換
+		if (since) {
+			const parsed = parseIso8601(since);
+			if (!parsed) {
+				return GetMarginTradeHistoryOutputSchema.parse(
+					fail(`since の日時形式が不正です: ${since}`, 'validation_error'),
+				);
+			}
+			params.since = String(parsed.valueOf());
+		}
+		if (end) {
+			const parsed = parseIso8601(end);
+			if (!parsed) {
+				return GetMarginTradeHistoryOutputSchema.parse(fail(`end の日時形式が不正です: ${end}`, 'validation_error'));
+			}
+			params.end = String(parsed.valueOf());
+		}
+
+		const rawData = await client.get<{ trades: RawMarginTrade[] }>('/v1/user/spot/trade_history', params);
+
+		const timestamp = nowIso();
+
+		// 約定データの整形
+		const trades = rawData.trades.map((t) => ({
+			trade_id: t.trade_id,
+			pair: t.pair,
+			order_id: t.order_id,
+			side: t.side,
+			position_side: t.position_side,
+			type: t.type,
+			amount: t.amount,
+			price: t.price,
+			maker_taker: t.maker_taker,
+			fee_amount_base: t.fee_amount_base,
+			fee_amount_quote: t.fee_amount_quote,
+			profit_loss: t.profit_loss,
+			interest: t.interest,
+			executed_at: toIsoMs(t.executed_at) ?? String(t.executed_at),
+		}));
+
+		// サマリー文字列の生成
+		const lines: string[] = [];
+		const pairLabel = pair ? formatPair(pair) : '全ペア';
+		lines.push(`信用約定履歴: ${pairLabel} ${trades.length}件`);
+
+		if (trades.length > 0) {
+			lines.push('');
+
+			const displayTrades = order === 'asc' ? trades.slice(-10) : trades.slice(0, 10);
+			for (const t of displayTrades) {
+				const sideLabel = t.side === 'buy' ? '買' : '売';
+				const posLabel = t.position_side === 'long' ? 'ロング' : t.position_side === 'short' ? 'ショート' : '';
+				const isJpy = t.pair.includes('jpy');
+				const price = isJpy ? formatPrice(Number(t.price)) : t.price;
+				const plInfo = t.profit_loss ? ` 損益: ${formatPrice(Number(t.profit_loss))} 円` : '';
+				lines.push(
+					`[trade: ${t.trade_id} / order: ${t.order_id}] ${t.executed_at} ${formatPair(t.pair)} ${posLabel}${sideLabel} ${t.amount} @ ${price} (${t.maker_taker})${plInfo}`,
+				);
+			}
+
+			if (trades.length > 10) {
+				lines.push(`... 他 ${trades.length - 10}件`);
+			}
+
+			// 集計
+			const longCount = trades.filter((t) => t.position_side === 'long').length;
+			const shortCount = trades.filter((t) => t.position_side === 'short').length;
+			lines.push('');
+			lines.push(`集計: ロング ${longCount}件 / ショート ${shortCount}件`);
+		}
+
+		const summary = lines.join('\n');
+
+		const data = {
+			trades,
+			timestamp,
+		};
+
+		const meta = {
+			fetchedAt: timestamp,
+			tradeCount: trades.length,
+			pair: pair || undefined,
+			...(client.lastRateLimit ? { rateLimit: client.lastRateLimit } : {}),
+		};
+
+		return GetMarginTradeHistoryOutputSchema.parse(ok(summary, data, meta));
+	} catch (err) {
+		if (err instanceof PrivateApiError) {
+			return GetMarginTradeHistoryOutputSchema.parse(fail(err.message, err.errorType));
+		}
+		return GetMarginTradeHistoryOutputSchema.parse(
+			fail(err instanceof Error ? err.message : '信用約定履歴取得中に予期しないエラーが発生しました', 'upstream_error'),
+		);
+	}
+}
+
+// ── MCP ツール定義（tool-registry から自動収集） ──
+export const toolDef: ToolDefinition = {
+	name: 'get_margin_trade_history',
+	description:
+		'[Margin Trades / 信用約定履歴] 信用取引の約定履歴（新規建て・決済）を取得。通貨ペア・期間・件数でフィルタ可能。決済時の実現損益・利息を含む。注意: since を信用新規建て後に指定すると決済約定のみが返る場合があります。Private API。',
+	inputSchema: GetMarginTradeHistoryInputSchema,
+	handler: async (args: { pair?: string; count?: number; order?: 'asc' | 'desc'; since?: string; end?: string }) =>
+		getMarginTradeHistory(args),
+};

package/tools/private/get_my_assets.ts

@@ -0,0 +1,207 @@
+/**
+ * get_my_assets — 自分の資産残高を取得する Private API ツール。
+ *
+ * bitbank Private API `/v1/user/assets` を呼び出し、
+ * ticker 連携で円評価額・構成比を自動算出する。
+ */
+
+import { toNum } from '../../lib/conversions.js';
+import { nowIso } from '../../lib/datetime.js';
+import { formatPrice } from '../../lib/formatter.js';
+import { fail, ok } from '../../lib/result.js';
+import { getDefaultClient, PrivateApiError } from '../../src/private/client.js';
+import { GetMyAssetsInputSchema, GetMyAssetsOutputSchema } from '../../src/private/schemas.js';
+import type { ToolDefinition } from '../../src/tool-definition.js';
+
+/** bitbank /v1/user/assets のレスポンス型 */
+interface RawAsset {
+	asset: string;
+	free_amount: string;
+	amount_precision: number;
+	onhand_amount: string;
+	locked_amount: string;
+	withdrawal_fee: { min: string; max: string } | string;
+	stop_deposit: boolean;
+	stop_withdrawal: boolean;
+}
+
+/** ticker から取得する最低限の価格情報 */
+interface _TickerPrice {
+	pair: string;
+	last: number;
+}
+
+/**
+ * public API の tickers_jpy から各通貨の最新価格を取得する。
+ * 失敗しても get_my_assets 自体は動作する（partial_data_warning）。
+ */
+async function fetchTickerPrices(): Promise<{ prices: Map<string, number>; error?: string }> {
+	try {
+		const res = await fetch('https://public.bitbank.cc/tickers_jpy', {
+			signal: AbortSignal.timeout(3000),
+		});
+		if (!res.ok) {
+			return { prices: new Map(), error: `ticker HTTP ${res.status}` };
+		}
+		const json = (await res.json()) as { success?: number; data?: Array<{ pair: string; last: string }> };
+		if (json.success !== 1 || !Array.isArray(json.data)) {
+			return { prices: new Map(), error: 'ticker レスポンス不正' };
+		}
+
+		const prices = new Map<string, number>();
+		for (const item of json.data) {
+			const asset = item.pair.replace('_jpy', '');
+			const last = toNum(item.last);
+			if (last != null && last > 0) {
+				prices.set(asset, last);
+			}
+		}
+		return { prices };
+	} catch (e) {
+		return { prices: new Map(), error: e instanceof Error ? e.message : 'ticker 取得失敗' };
+	}
+}
+
+export default async function getMyAssets(args: { include_jpy_valuation?: boolean }) {
+	const { include_jpy_valuation = true } = args;
+	const client = getDefaultClient();
+
+	try {
+		const rawAssets = await client.get<{ assets: RawAsset[] }>('/v1/user/assets');
+		const timestamp = nowIso();
+
+		// ゼロでない資産のみ抽出
+		const nonZeroAssets = rawAssets.assets.filter((a) => {
+			const amount = toNum(a.onhand_amount);
+			return amount != null && amount > 0;
+		});
+
+		// ticker 連携（オプション）
+		let tickerError: string | undefined;
+		let prices = new Map<string, number>();
+
+		if (include_jpy_valuation) {
+			const tickerResult = await fetchTickerPrices();
+			prices = tickerResult.prices;
+			tickerError = tickerResult.error;
+		}
+
+		// 資産データの組み立て
+		let totalJpyValue = 0;
+		const assets = nonZeroAssets.map((a) => {
+			const amount = a.onhand_amount;
+			const available = a.free_amount;
+			const locked = a.locked_amount;
+
+			let jpyValue: number | undefined;
+			if (include_jpy_valuation) {
+				if (a.asset === 'jpy') {
+					jpyValue = toNum(amount) ?? undefined;
+				} else {
+					const price = prices.get(a.asset);
+					const amountN = toNum(amount);
+					if (price && amountN != null) {
+						jpyValue = amountN * price;
+					}
+				}
+			}
+
+			if (jpyValue != null && Number.isFinite(jpyValue)) {
+				totalJpyValue += jpyValue;
+			}
+
+			return {
+				asset: a.asset,
+				amount,
+				available_amount: available,
+				locked_amount: locked,
+				jpy_value: jpyValue != null && Number.isFinite(jpyValue) ? Math.round(jpyValue) : undefined,
+			};
+		});
+
+		// 構成比の算出
+		if (include_jpy_valuation && totalJpyValue > 0) {
+			for (const asset of assets) {
+				if (asset.jpy_value != null) {
+					(asset as { allocation_pct?: number }).allocation_pct =
+						Math.round((asset.jpy_value / totalJpyValue) * 10000) / 100;
+				}
+			}
+		}
+
+		// JPY 評価額降順でソート
+		assets.sort((a, b) => (b.jpy_value ?? 0) - (a.jpy_value ?? 0));
+
+		// サマリー文字列の生成
+		const lines: string[] = [];
+		lines.push(`保有資産: ${assets.length}通貨`);
+		if (include_jpy_valuation && totalJpyValue > 0) {
+			lines.push(`合計評価額: ${formatPrice(totalJpyValue, 'btc_jpy')}`);
+		}
+		lines.push('');
+
+		for (const a of assets) {
+			const assetUpper = a.asset.toUpperCase();
+			let line = `${assetUpper}: ${a.amount}`;
+			if (a.jpy_value != null) {
+				line += ` (${formatPrice(a.jpy_value, 'btc_jpy')}`;
+				const pct = (a as { allocation_pct?: number }).allocation_pct;
+				if (pct != null) {
+					line += `, ${pct}%`;
+				}
+				line += ')';
+			}
+			if ((toNum(a.locked_amount) ?? 0) > 0) {
+				line += ` [ロック: ${a.locked_amount}]`;
+			}
+			lines.push(line);
+		}
+
+		if (tickerError) {
+			lines.push('');
+			lines.push(`⚠ ticker 連携一部失敗: ${tickerError}（一部通貨の円評価額が欠損している可能性があります）`);
+		}
+
+		const summary = lines.join('\n');
+		const hasJpyValuation = include_jpy_valuation && totalJpyValue > 0;
+
+		const data = {
+			assets,
+			total_jpy_value: hasJpyValuation ? Math.round(totalJpyValue) : undefined,
+			timestamp,
+		};
+
+		const meta = {
+			fetchedAt: timestamp,
+			assetCount: assets.length,
+			hasJpyValuation,
+			...(client.lastRateLimit ? { rateLimit: client.lastRateLimit } : {}),
+		};
+
+		const result = ok(summary, data, meta);
+
+		// ticker 一部失敗の場合は partial_data_warning を付与
+		if (tickerError) {
+			(result.meta as Record<string, unknown>).warning = 'partial_data_warning';
+			(result.meta as Record<string, unknown>).warningDetail = tickerError;
+		}
+
+		return GetMyAssetsOutputSchema.parse(result);
+	} catch (err) {
+		if (err instanceof PrivateApiError) {
+			return GetMyAssetsOutputSchema.parse(fail(err.message, err.errorType));
+		}
+		return GetMyAssetsOutputSchema.parse(
+			fail(err instanceof Error ? err.message : 'asset 取得中に予期しないエラーが発生しました', 'upstream_error'),
+		);
+	}
+}
+
+// ── MCP ツール定義（tool-registry から自動収集） ──
+export const toolDef: ToolDefinition = {
+	name: 'get_my_assets',
+	description:
+		'[My Assets / Balance / Wallet] 自分の保有資産・残高一覧（my assets / balance / wallet / holdings）を取得。全通貨の数量・円評価額・構成比を返す。Private API。',
+	inputSchema: GetMyAssetsInputSchema,
+	handler: async (args: Record<string, unknown>) => getMyAssets(args as { include_jpy_valuation?: boolean }),
+};