bitbank-lab-mcp 0.1.2-rc.0 → 0.1.2

package/README.md

@@ -1,21 +1,29 @@
 # bitbank-lab-mcp
 
-[![CI](https://github.com/tjackiet/bitbank-genesis-mcp-server/actions/workflows/ci.yml/badge.svg)](https://github.com/tjackiet/bitbank-genesis-mcp-server/actions/workflows/ci.yml)
+[![CI](https://github.com/tjackiet/bitbank-lab-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/tjackiet/bitbank-lab-mcp/actions/workflows/ci.yml)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
 [![npm](https://img.shields.io/npm/v/bitbank-lab-mcp.svg)](https://www.npmjs.com/package/bitbank-lab-mcp)
+[![CodeRabbit Pull Request Reviews](https://img.shields.io/coderabbit/prs/github/tjackiet/bitbank-lab-mcp?utm_source=oss&utm_medium=github&utm_campaign=tjackiet%2Fbitbank-lab-mcp&labelColor=171717&color=FF570A&link=https%3A%2F%2Fcoderabbit.ai&label=CodeRabbit+Reviews)](https://coderabbit.ai)
 
 > bitbank API のデータを使った暗号資産市場分析を、Claude / Cursor / Codex / Gemini CLI など各種 AI クライアントから簡単に実行できる MCP サーバーです。
 
-## ⚠️ Disclaimer
+## はじめにお読みください
 
-本 MCP サーバーが提供するデータを AI エージェントが受け取り処理した結果は、必ずしも正確性・完全性を保証するものではありません。
-
-提供される情報は情報提供のみを目的としており、投資助言・代理業に該当するものではありません。投資に関する判断はご自身の責任で行ってください。
+- 本ツールは**開発段階（ベータ版）**です。利用は**自己責任**でお願いします。
+- ご利用の前に必ず [⚠️ 免責事項](#免責事項) をお読みください。
+- 本リポジトリは **bitbank バグバウンティプログラムの対象範囲外** です。
 
 ## 本 MCP サーバーについて
 
 bitbank の公開 API から取得した価格・取引データを、指標計算・統合・可視化用データの整形まで行った上で LLM に渡します（必要に応じてサーバー側で SVG 描画も可能）。生データを渡すだけのサーバーとは異なり、各ツールの description に「いつ使うべきか」「他ツールとの使い分け」を明示しているため、LLM が自律的に適切なツールを選択できます。
 
+姉妹プロジェクトとして、同じ bitbank API に対する真逆のアプローチを提供する **CLI** ([bitbank-cli-skills](https://github.com/tjackiet/bitbank-cli-skills)) もあります。
+
+- **この MCP サーバー** はサーバー側で計算済みの結論を LLM に渡す
+- **CLI** は生データを高速に取得し、LLM 自身に計算させる
+
+指標のパラメータやロジックを完全にカスタマイズしたい場合は CLI 側を、すぐに使えるテクニカル分析・可視化を求める場合は MCP サーバー側を選んでください。
+
 ## 概要
 bitbank の公開 API から価格・板情報・約定履歴・ローソク足データを取得し、以下の分析を実行できます。
 → 全ツールの一覧と使い分けは [docs/tools.md](docs/tools.md) を参照。
@@ -46,7 +54,7 @@ bitbank の公開 API から価格・板情報・約定履歴・ローソク足
 ## クイックスタート
 
 ### 前提条件
-- **Node.js 18 以上**（22 推奨 — CI で検証済み。[公式サイト](https://nodejs.org/) からインストール。`node -v` で確認できます）
+- **Node.js 22 以上**（24 推奨 — CI で検証済み。[公式サイト](https://nodejs.org/) からインストール。`node -v` で確認できます）
 - npm（Node.js に同梱されています）
 - 対応 OS: macOS / Linux / Windows（WSL 含む）
 
@@ -103,6 +111,12 @@ API キーは [bitbank 設定画面](https://app.bitbank.cc/account/api) で発
 
 **IP 制限**: bitbank 側で API キーに IP 制限を設定できる場合は、可能な限り設定を推奨します。詳細: [Private API ガイド](docs/private-api.md)。
 
+#### オプション環境変数
+
+| 変数 | 既定 | 用途 |
+|---|---|---|
+| `BITBANK_TRUST_HOST_APPROVAL` | unset（無効） | `1` を設定すると、elicitation を advertise しないが SEP-1865 iframe をサポートするホスト（Claude Desktop / claude-ai 等）で、preview の確認 UI ボタンから注文/キャンセルを実行できるようにする妥協モード。詳細とセキュリティ前提は [ADR-0007](docs/adr/0007-hitl-confirmation-token-delivery.md) と [Private API ガイド](docs/private-api.md) を参照。**有効化時は `create_order` 等のツールを「常に許可」しないこと**。 |
+
 #### 方式B：`npx` の絶対パスを指定（フォールバック）
 
 方式A で「サーバーに接続できません」エラーが出る場合、Claude Desktop から `npx` コマンドが見つけられていない可能性があります。その場合は、`npx` の絶対パスを指定してください。
@@ -135,7 +149,7 @@ which npx
 }
 ```
 
-> ⚠️ **nvm/volta ユーザーへの注意**: この方式では Node.js をバージョンアップするたびに `command` のパスの書き換えが必要です（例: `v22.22.2` → `v22.22.3`）。アップデート後に `which npx` を再確認してください。
+> ⚠️ **nvm/volta ユーザーへの注意**: この方式では Node.js をバージョンアップするたびに `command` のパスの書き換えが必要です（例: `v24.0.0` → `v24.1.0`）。アップデート後に `which npx` を再確認してください。
 
 #### Windows の場合
 
@@ -199,7 +213,7 @@ Claude Desktop の UI に表示される名前は `claude_desktop_config.json`
 
 ```bash
 # 1. このリポジトリを marketplace として登録（初回のみ）
-/plugin marketplace add tjackiet/bitbank-genesis-mcp-server
+/plugin marketplace add tjackiet/bitbank-lab-mcp
 
 # 2. plugin を install
 /plugin install bitbank-lab-mcp@bitbank-lab
@@ -277,8 +291,8 @@ API キーの有無でサーバーが公開する機能が自動的に切り替
 
 | 設定 | ツール数 | プロンプト数 | 使える機能 |
 |------|---------|------------|-----------|
-| キー未設定 | 31（Public のみ） | 9 | 価格取得・テクニカル分析・チャート生成・バックテスト |
-| キー設定済み | 31 + 16 = **47** | 9 + 1 = **10** | 上記 + 資産確認・注文・ポートフォリオ分析 |
+| キー未設定 | 32（Public のみ） | 8 | 価格取得・テクニカル分析・チャート生成・バックテスト |
+| キー設定済み | 32 + 16 = **48** | 8 + 1 = **9** | 上記 + 資産確認・注文・ポートフォリオ分析 |
 
 キー未設定時、Private ツール・プロンプトは MCP クライアントに一切表示されません（エラーではなく、そもそも登録されません）。公開データの取得・分析だけなら設定不要で、そのまま使えます。
 
@@ -383,7 +397,7 @@ npx @modelcontextprotocol/inspector -- npx -y bitbank-lab-mcp
 | ツール実行時にタイムアウト | ネットワーク接続を確認 / [bitbank API の状態](https://status.bitbank.cc/)を確認 |
 | Private API ツールが表示されない | `BITBANK_API_KEY` と `BITBANK_API_SECRET` の両方が設定されているか確認（→ [docs/private-api.md](docs/private-api.md)） |
 | ログを確認したい | `env` に `"LOG_LEVEL": "debug"` を追加して再起動 |
-| Plugin install で「Marketplace not found」 | `/plugin marketplace add tjackiet/bitbank-genesis-mcp-server` を先に実行してから `/plugin install bitbank-lab-mcp@bitbank-lab` |
+| Plugin install で「Marketplace not found」 | `/plugin marketplace add tjackiet/bitbank-lab-mcp` を先に実行してから `/plugin install bitbank-lab-mcp@bitbank-lab` |
 
 ---
 
@@ -394,14 +408,16 @@ npx @modelcontextprotocol/inspector -- npx -y bitbank-lab-mcp
 ### セットアップ
 
 ```bash
-git clone https://github.com/tjackiet/bitbank-genesis-mcp-server.git
-cd bitbank-genesis-mcp-server
-npm install
+git clone https://github.com/tjackiet/bitbank-lab-mcp.git
+cd bitbank-lab-mcp
+npm ci
 ```
 
+`package-lock.json` 通りに依存をインストールするため、ローカル開発でも `npm install` ではなく `npm ci` を推奨します（CI も `npm ci` を使用）。
+
 ビルドステップは不要です（tsx で TypeScript を直接実行します）。
 
-### STDIO モード（既定 — Claude Desktop / Claude Code 向け）
+### STDIO モード（Claude Desktop / Claude Code 向け）
 
 ローカルの開発版を Claude Desktop から使いたい場合、`claude_desktop_config.json` に絶対パス指定で登録します：
 
@@ -425,18 +441,6 @@ Inspector で動作確認する場合:
 npx @modelcontextprotocol/inspector -- tsx src/server.ts
 ```
 
-### HTTP モード（Web クライアント・開発検証向け）
-
-```bash
-# 環境変数を指定して HTTP サーバーを起動
-MCP_ENABLE_HTTP=1 PORT=8787 tsx src/server.ts
-
-# 別ターミナルから Inspector で接続
-npx @modelcontextprotocol/inspector http://localhost:8787/mcp
-```
-
-> HTTP サーバは既定で無効です（STDIO 汚染を避けるため）。Docker での起動方法は [docs/ops.md](docs/ops.md#docker起動開発検証用) を参照してください。
-
 ### Windows でローカル開発する場合
 
 `npx` が PATH 解決できない環境では、`node` の絶対パスと `tsx` の CLI を直接指定します：
@@ -447,10 +451,10 @@ npx @modelcontextprotocol/inspector http://localhost:8787/mcp
     "bitbank-dev": {
       "command": "node",
       "args": [
-        "C:\\Users\\<USERNAME>\\bitbank-genesis-mcp-server\\node_modules\\tsx\\dist\\cli.mjs",
-        "C:\\Users\\<USERNAME>\\bitbank-genesis-mcp-server\\src\\server.ts"
+        "C:\\Users\\<USERNAME>\\bitbank-lab-mcp\\node_modules\\tsx\\dist\\cli.mjs",
+        "C:\\Users\\<USERNAME>\\bitbank-lab-mcp\\src\\server.ts"
       ],
-      "workingDirectory": "C:\\Users\\<USERNAME>\\bitbank-genesis-mcp-server",
+      "workingDirectory": "C:\\Users\\<USERNAME>\\bitbank-lab-mcp",
       "env": { "LOG_LEVEL": "debug", "NO_COLOR": "1" }
     }
   }
@@ -463,4 +467,40 @@ npx @modelcontextprotocol/inspector http://localhost:8787/mcp
 
 ## フィードバック・バグ報告
 
-バグ報告や機能要望は [GitHub Issues](https://github.com/tjackiet/bitbank-genesis-mcp-server/issues) からお願いします。Issue テンプレートを用意していますので、用途に合ったものを選択してください。
+バグ報告や機能要望は [GitHub Issues](https://github.com/tjackiet/bitbank-lab-mcp/issues) からお願いします。Issue テンプレートを用意していますので、用途に合ったものを選択してください。
+
+## 免責事項
+
+### 開発段階について
+
+本ツールは開発段階（ベータ版）です。バグ、不具合、誤動作、または不正確な分析結果を含む可能性があります。
+
+### AI エージェントによる処理結果について
+
+本MCPサーバー / 本CLIツール が提供するデータを AIエージェント等が処理・生成した結果について、正確性、完全性、有用性、最新性を保証するものではありません。AI エージェント等による処理の結果、注文種別、価格、数量その他の取引条件が利用者の意図と異なる形で処理または実行される可能性があります。
+
+### 金融商品取引法上の位置づけ
+
+本MCPサーバーは情報提供のみを目的として提供されるものであり、投資助言・代理業、投資勧誘、その他金融商品取引法上の行為を目的とするものではありません。
+
+### 外部サービスへの依拠
+
+本MCPサーバーは外部API、LLM、第三者サービス等に依拠して提供するものであり、これらの仕様変更、停止、不具合等が生じた場合には、本MCPサーバーが正常に動作しない可能性があります。
+
+### 安全対策の補助性
+
+本MCPサーバーに実装されている最終注文確認機能、バリデーションその他の安全対策は、誤操作または誤発注等を防止するための補助機能であり、その完全な防止を保証するものではありません。
+
+### 利用者の責任
+
+利用者は、本MCPサーバーにより提供・生成された情報および注文内容等を自身で十分に確認の上、自己の判断と責任において本MCPサーバーを利用し、投資判断、注文実行および取引を行うものとします。
+
+### 損害の免責
+
+当社は、本MCPサーバーの利用もしくは利用不能、または本MCPサーバーにより提供・生成された情報、AI エージェント等による処理結果もしくは取引操作に基づく投資判断・注文・取引等に関連して生じたいかなる損害についても、当社の故意または重過失による場合を除き、一切責任を負いません。
+
+### APIキー・認証情報の管理
+
+APIキーおよび取引に必要なパスワード等は利用者自身の責任において適切に管理してください。チャット欄や公開リポジトリその他第三者が閲覧可能な環境等へ APIキーや取引パスワード等の認証情報等を入力・掲載しないよう十分ご注意ください。
+
+利用者による認証情報等の管理不備、誤入力、漏えい、第三者利用等により生じたいかなる損害についても、当社の故意または重過失による場合を除き、当社は一切責任を負いません。

package/lib/candle-fetch.ts

@@ -0,0 +1,223 @@
+/**
+ * /candlestick エンドポイントの chunk fetcher と merge ロジック。
+ *
+ * - `fetchCandleChunk` は単一 chunk（年単位 YYYY / 日単位 YYYYMMDD）の取得。
+ *   通信エラーは throw せず result.error にラップ、success:0 は UpstreamApiError として記録する。
+ * - `mergeChunks` は複数 chunk を並列 / バッチ並列で取得し、timestamp 昇順でマージする。
+ *   失敗ハンドリング（full / majority / partial）は呼び出し側に委ねる — 集計に必要な情報を返す。
+ */
+
+import { BITBANK_API_BASE, DEFAULT_RETRIES, fetchJsonWithRateLimit, type RateLimitInfo } from './http.js';
+
+/** /candlestick エンドポイントが返す 1 行（[open, high, low, close, volume, timestamp]） */
+export type OhlcvRow = [unknown, unknown, unknown, unknown, unknown, unknown];
+
+/** chunk fetcher が返す結果 */
+export interface FetchChunkResult {
+	rows: OhlcvRow[];
+	rateLimit: RateLimitInfo | null;
+	error?: unknown;
+}
+
+/**
+ * chunk fetcher が success:0 を検出したときに記録するエラー。
+ * 全チャンク失敗時に network ではなく upstream として明示分類するため
+ * instanceof で判定する。
+ */
+export class UpstreamApiError extends Error {
+	constructor(message: string) {
+		super(message);
+		this.name = 'UpstreamApiError';
+	}
+}
+
+/**
+ * /candlestick エンドポイントのレスポンス body を OHLCV 行に正規化する。
+ * - success !== 1 → UpstreamApiError をエラーとして埋め込んで返す（空 rows）
+ * - success === 1 → ohlcv 配列を返す（存在しなければ空）
+ *
+ * 純粋関数で fetch をモックせず単独でテスト可能。
+ */
+export function parseCandleChunk(json: unknown, rateLimit: RateLimitInfo | null): FetchChunkResult {
+	const jsonObj = json as {
+		success?: number;
+		data?: { candlestick?: Array<{ ohlcv?: unknown[] }>; code?: number };
+	};
+	if (jsonObj?.success !== 1) {
+		const code = jsonObj?.data?.code;
+		const msg = code != null ? `bitbank API error (code: ${code})` : 'bitbank API error';
+		return { rows: [], rateLimit, error: new UpstreamApiError(msg) };
+	}
+	const cs = jsonObj?.data?.candlestick?.[0];
+	const ohlcvs = cs?.ohlcv ?? [];
+	return { rows: ohlcvs as OhlcvRow[], rateLimit };
+}
+
+export interface FetchCandleChunkOptions {
+	/** チャンク取得のタイムアウト (ms) */
+	timeoutMs?: number;
+	/** リトライ回数（初回 + N 回） */
+	retries?: number;
+}
+
+/**
+ * /candlestick の単一 chunk を取得する。
+ *
+ * @param pair  例: "btc_jpy"
+ * @param type  例: "1day", "1hour"
+ * @param key   年単位なら "2024"、日単位なら "20240101"
+ *
+ * 戻り値の semantics:
+ * - 成功: rows に OHLCV 行
+ * - success:0: rows=[], error=UpstreamApiError（呼び出し側で全 chunk 失敗時に upstream 分類）
+ * - 通信エラー / 例外: rows=[], error=原因となった例外（throw しない）
+ */
+export async function fetchCandleChunk(
+	pair: string,
+	type: string,
+	key: string,
+	options: FetchCandleChunkOptions = {},
+): Promise<FetchChunkResult> {
+	const url = `${BITBANK_API_BASE}/${pair}/candlestick/${type}/${key}`;
+	try {
+		const { data: json, rateLimit } = await fetchJsonWithRateLimit(url, {
+			timeoutMs: options.timeoutMs,
+			retries: options.retries ?? DEFAULT_RETRIES,
+		});
+		return parseCandleChunk(json, rateLimit);
+	} catch (e) {
+		return { rows: [], rateLimit: null, error: e };
+	}
+}
+
+export interface MergeChunksOptions {
+	/**
+	 * 指定時はバッチ並列で取得する（bitbank API レート制限対策）。
+	 *   - concurrency: バッチ内の最大同時リクエスト数
+	 *   - batchDelayMs: バッチ間に挟む遅延（先頭バッチ前は挟まない）
+	 * 未指定なら全 chunk を `Promise.all` で一括並列実行する。
+	 */
+	batched?: { concurrency: number; batchDelayMs: number };
+}
+
+export interface MergedChunkResult {
+	/** 全 chunk の OHLCV を timestamp 昇順でマージ・ソートした結果 */
+	rows: OhlcvRow[];
+	/** keys と同じ順序の per-chunk 結果 */
+	results: FetchChunkResult[];
+	/** 最後に得た非 null の rateLimit（last-wins） */
+	lastRateLimit: RateLimitInfo | null;
+	/** 失敗した chunk の key 一覧（keys の元順序を保つ） */
+	failedKeys: string[];
+}
+
+/**
+ * 複数 chunk を fetcher に流して結果をマージする。
+ *
+ * - 取得失敗（full / majority / partial）の判定は呼び出し側に委ねる。
+ *   そのため `results` と `failedKeys` を返すが、自前で fail を生成しない。
+ * - `rows` は timestamp 昇順でソート済み。
+ *
+ * @param keys     各 chunk の URL 末尾要素（年/日）
+ * @param fetcher  key を受け取って FetchChunkResult を返す関数
+ */
+export async function mergeChunks(
+	keys: string[],
+	fetcher: (key: string) => Promise<FetchChunkResult>,
+	options: MergeChunksOptions = {},
+): Promise<MergedChunkResult> {
+	let results: FetchChunkResult[];
+	if (options.batched) {
+		const { concurrency, batchDelayMs } = options.batched;
+		results = [];
+		for (let i = 0; i < keys.length; i += concurrency) {
+			if (i > 0) {
+				// バッチ間の遅延（先頭バッチ前は挟まない。bitbank API レート制限対策）
+				await new Promise((resolve) => setTimeout(resolve, batchDelayMs));
+			}
+			const batch = keys.slice(i, i + concurrency);
+			const batchResults = await Promise.all(batch.map(fetcher));
+			results.push(...batchResults);
+		}
+	} else {
+		results = await Promise.all(keys.map(fetcher));
+	}
+
+	let lastRateLimit: RateLimitInfo | null = null;
+	for (const r of results) {
+		if (r.rateLimit) lastRateLimit = r.rateLimit;
+	}
+
+	const rows: OhlcvRow[] = [];
+	for (const r of results) {
+		rows.push(...r.rows);
+	}
+
+	// timestamp (index 5) 昇順でソート。Number 変換失敗時は 0 にフォールバック。
+	rows.sort((a, b) => (Number(a[5]) || 0) - (Number(b[5]) || 0));
+
+	const failedKeys = keys.filter((_, i) => results[i].error != null);
+	return { rows, results, lastRateLimit, failedKeys };
+}
+
+function isOhlcAllZero(row: OhlcvRow): boolean {
+	return Number(row[0]) === 0 && Number(row[1]) === 0 && Number(row[2]) === 0 && Number(row[3]) === 0;
+}
+
+/**
+ * 同一 ts 内で curr を採用すべきかを判定する。
+ * - a) 全 0 OHLC プレースホルダを除外
+ * - b) volume が大きい行を優先
+ * - c) タイなら後勝ち（配列上で後の行）
+ */
+function shouldPreferCurr(prev: OhlcvRow, curr: OhlcvRow): boolean {
+	const prevAllZero = isOhlcAllZero(prev);
+	const currAllZero = isOhlcAllZero(curr);
+	if (prevAllZero && !currAllZero) return true;
+	if (!prevAllZero && currAllZero) return false;
+	const prevV = Number(prev[4]);
+	const currV = Number(curr[4]);
+	const prevVN = Number.isFinite(prevV) ? prevV : 0;
+	const currVN = Number.isFinite(currV) ? currV : 0;
+	if (currVN > prevVN) return true;
+	if (currVN < prevVN) return false;
+	return true;
+}
+
+/**
+ * 同一 timestamp の重複行を排除する純関数。
+ *
+ * /candlestick レスポンスで観測される同一 ts 重複（一方は全 0 OHLC のプレースホルダ）を排除し、
+ * インジケーター・パターン検出・バックテストへの副作用を防ぐ。
+ *
+ * 前提: 入力は timestamp 昇順ソート済み。
+ *
+ * 採用ルール（上から順に評価）:
+ *   a) OHLC の全てが 0 ではない行を優先（全 0 プレースホルダ行を除外）
+ *   b) 上記タイで残ったら volume が大きい行を優先
+ *   c) さらにタイなら後勝ち（配列上で後の行を採用）
+ *
+ * timestamp が NaN/<=0 の行は dedupe 対象外で素通し（後段の row validation で upstream 分類される）。
+ */
+export function dedupeByTimestamp(rows: OhlcvRow[]): OhlcvRow[] {
+	if (rows.length === 0) return [];
+	const result: OhlcvRow[] = [];
+	const tsToIndex = new Map<number, number>();
+	for (const row of rows) {
+		const ts = Number(row[5]);
+		if (!Number.isFinite(ts) || ts <= 0) {
+			result.push(row);
+			continue;
+		}
+		const existingIdx = tsToIndex.get(ts);
+		if (existingIdx === undefined) {
+			tsToIndex.set(ts, result.length);
+			result.push(row);
+			continue;
+		}
+		if (shouldPreferCurr(result[existingIdx], row)) {
+			result[existingIdx] = row;
+		}
+	}
+	return result;
+}

package/lib/datetime.ts

@@ -50,6 +50,38 @@ export function toIsoWithTz(ts: number, tz: string): string | null {
 	}
 }
 
+/**
+ * タイムスタンプを指定タイムゾーンの暦日 YYYY-MM-DD に変換
+ * @param ms ミリ秒タイムスタンプ
+ * @param tz タイムゾーン（デフォルト: 'Asia/Tokyo'、空文字も Asia/Tokyo にフォールバック）
+ * @returns "YYYY-MM-DD" 形式、ms が null/undefined/NaN または tz が不正なら null
+ */
+export function formatDateInTz(ms: number | undefined | null, tz: string = 'Asia/Tokyo'): string | null {
+	if (ms == null) return null;
+	if (!Number.isFinite(ms)) return null;
+	const effectiveTz = typeof tz === 'string' && tz.length > 0 ? tz : 'Asia/Tokyo';
+	try {
+		const d = dayjs(ms).tz(effectiveTz);
+		return d.isValid() ? d.format('YYYY-MM-DD') : null;
+	} catch {
+		return null;
+	}
+}
+
+/**
+ * UTC ISO 文字列または ms から、指定 tz の暦日 YYYY-MM-DD を返す（表示・比較用）。
+ * isoTime.split('T')[0] は UTC 暦日になるため、JST 表示には使わない。
+ */
+export function calendarDateFromIso(
+	isoOrMs: string | number | null | undefined,
+	tz: string = 'Asia/Tokyo',
+): string | null {
+	if (isoOrMs == null) return null;
+	const ms = typeof isoOrMs === 'number' ? isoOrMs : dayjs(isoOrMs).valueOf();
+	if (!Number.isFinite(ms)) return null;
+	return formatDateInTz(ms, tz);
+}
+
 /**
  * タイムスタンプを日本語表示形式に変換
  * @param ts ミリ秒タイムスタンプ（未指定時は現在時刻）
@@ -75,15 +107,6 @@ export function nowIso(): string {
 	return dayjs().toISOString();
 }
 
-/**
- * 現在時刻を指定タイムゾーンで取得
- * @param tz タイムゾーン（デフォルト: 'Asia/Tokyo'）
- * @returns dayjs インスタンス
- */
-export function nowTz(tz: string = 'Asia/Tokyo') {
-	return dayjs().tz(tz);
-}
-
 /**
  * N日前の日付を取得
  * @param daysAgo 何日前か

package/lib/error.ts

@@ -1,3 +1,6 @@
+import { ZodError } from 'zod';
+import { PrivateApiError } from '../src/private/client.js';
+
 /**
  * unknown型のエラーからメッセージを安全に取得する
  */
@@ -13,3 +16,38 @@ export function getErrorMessage(e: unknown): string {
 export function isAbortError(e: unknown): boolean {
 	return e instanceof Error && e.name === 'AbortError';
 }
+
+/** ユーザ応答層に渡す安全なエラー表現 */
+export interface PublicError {
+	summary: string;
+	errorType: string;
+}
+
+/**
+ * 捕捉した例外をユーザ応答に出してよい形へ正規化する。
+ *
+ * - `ZodError`: 詳細メッセージはローカルパスや入力断片を含む場合があるため汎用文に置き換え
+ * - `PrivateApiError`: bitbank の業務エラー文言は素通し（"数量が最低取引量を下回っています" 等）。
+ *   `instanceof` で判定するため `name`/`errorType` を偽装した一般 Error は素通しされない。
+ * - その他: ローカルパスや fs / 内部ロジック由来の message を漏らさないため汎用文に置き換え
+ *
+ * ログ用途では引き続き `getErrorMessage(err)` を使うこと。
+ */
+export function toPublicError(e: unknown): PublicError {
+	if (e instanceof ZodError) {
+		return {
+			summary: '入力形式が不正です。パラメータを確認してください',
+			errorType: 'validation_error',
+		};
+	}
+	if (e instanceof PrivateApiError) {
+		return {
+			summary: e.message,
+			errorType: e.errorType,
+		};
+	}
+	return {
+		summary: '内部エラーが発生しました。ログを確認してください',
+		errorType: 'internal',
+	};
+}