Zaifer-MCP

Instructions

Implementation Reference

• zaifer_mcp/tools/trade.py:165-251 (handler)

  The main handler function for the 'get_trade_executions' tool, decorated with @mcp.tool() for automatic registration. It validates authentication, processes date parameters, calls the Zaif API's get_trade_history, filters to supported currency pairs (btc_jpy, eth_jpy, xym_jpy), and returns a TradeExecutionList.
  @mcp.tool() def get_trade_executions( currency_pair: SupportedPair = None, limit: int = 20, start_date: str = "", end_date: str = "", ) -> TradeExecutionList: """ あなたのアカウントで約定（成立）した取引履歴を取得します。 このツールは、実際に成立した売買取引の記録を確認するために使用します。 特定の通貨ペアだけの履歴を見たり、取得件数や期間を指定して絞り込んだりできます。 使用例: - 過去1ヶ月の取引履歴を確認して収益を計算したい場合 - ビットコイン取引だけを分析したい場合 - 最近の20件の取引を確認して取引戦略の成果を評価したい場合 - 税金申告のために年間の取引記録を取得したい場合 注意: このツールを使用するには、環境変数にAPIキーとシークレットが設定されている必要があります。 Args: currency_pair: 取引通貨ペア（'btc_jpy': ビットコイン/円、'eth_jpy': イーサリアム/円、'xym_jpy': シンボル/円） 指定しない場合、すべての通貨ペアの取引履歴が返されます limit: 取得する履歴の最大件数（例: 10, 20, 50） start_date: この日付以降の取引を取得（例: '2023-01-01'） end_date: この日付以前の取引を取得（例: '2023-12-31'） Returns: TradeExecutionList: 約定済み取引履歴 - executions: 約定済み取引のリスト（新しい順） - execution_id: 取引ID（約定ID） - currency_pair: 通貨ペア（例: 'btc_jpy'） - trade_side: 取引であなたが行った行動（'buy': 買い、'sell': 売り、'self': 自己取引） - market_role: 取引における役割（'maker': 注文を出して待っていた側、'taker': 即時約定した側、'both': 自己取引の場合） - price: 約定価格（日本円） - quantity: 約定数量（暗号資産の量） - fee_amount: 支払った手数料の金額（日本円） - execution_time: 約定日時（ISO 8601形式の文字列、例: '2023-05-24T15:30:45+09:00'） Raises: ValueError: 認証情報が設定されていない場合や、APIエラーが発生した場合 """ if not api.trade.http.auth_provider: raise ValueError( "認証情報が設定されていません。APIキーとシークレットを.envファイルに設定してください。" ) # 対応している通貨ペアのみを許可 if currency_pair is not None and currency_pair not in [ "btc_jpy", "eth_jpy", "xym_jpy", ]: raise ValueError(f"サポートされていない通貨ペアです: {currency_pair}") # 日付文字列をUNIXタイムスタンプに変換 from_timestamp = None if start_date: # 空文字列はFalsyなので、この条件で十分 from_timestamp = int(datetime.fromisoformat(start_date).timestamp()) end_timestamp = None if end_date: # 空文字列はFalsyなので、この条件で十分 # 終了日の23:59:59を指定（その日の最後まで含める） end_date_obj = datetime.fromisoformat(end_date) end_date_obj = end_date_obj.replace(hour=23, minute=59, second=59) end_timestamp = int(end_date_obj.timestamp()) trade_history = api.trade.get_trade_history( currency_pair=currency_pair, count=limit, from_timestamp=from_timestamp, end_timestamp=end_timestamp, ) # 対応している通貨ペアのみをフィルタリング if trade_history.executions: filtered_executions = [ execution for execution in trade_history.executions if execution.currency_pair in ["btc_jpy", "eth_jpy", "xym_jpy"] ] # 元のオブジェクトのexecutionsを置き換え trade_history.executions = filtered_executions return trade_history
• zaifer_mcp/models/trade.py:182-313 (schema)

  Output schema definitions: TradeExecution dataclass for individual executions and TradeExecutionList for the list of executions returned by the tool. Includes from_dict and to_dict for API serialization.
  class TradeExecution: """ 約定済み取引の情報を表すデータクラス。 Attributes: execution_id: 取引ID（約定ID） currency_pair: 通貨ペア trade_side: 取引であなたが行った行動（'buy': 買い、'sell': 売り、'self': 自己取引） price: 約定価格 quantity: 約定数量 fee_amount: 支払った手数料の金額 market_role: 取引における役割（'maker': 注文を出して待っていた側、'taker': 即時約定した側、'both': 自己取引の場合） execution_time: 約定日時のISO 8601形式の文字列 """ execution_id: int currency_pair: str trade_side: str price: Decimal quantity: Decimal fee_amount: Decimal market_role: str execution_time: Optional[str] = None @dataclass class TradeExecutionList: """ 約定済み取引履歴を表すデータクラス。 get_trade_historyの戻り値に対応します。 Attributes: executions: 約定済み取引のリスト """ executions: List[TradeExecution] @classmethod def from_dict(cls, data: Dict[str, Any]) -> "TradeExecutionList": """ APIレスポンスからTradeExecutionListインスタンスを作成します。 Args: data: APIレスポンスの辞書（キーが取引ID、値が取引情報） Returns: TradeExecutionListインスタンス """ executions = [] for trade_id, item in data.items(): if not isinstance(item, dict): continue # 辞書でない項目はスキップ try: trade_id_int = int(trade_id) timestamp = item.get("timestamp") if timestamp is not None and timestamp != "": execution_time = datetime.fromtimestamp(int(timestamp)).isoformat() else: execution_time = None # action と your_action から trade_side と market_role を決定 action = item.get("action", "") your_action = item.get("your_action", "") # trade_side の決定 if your_action == "both": trade_side = "self" elif your_action == "bid": trade_side = "buy" elif your_action == "ask": trade_side = "sell" else: trade_side = "unknown" # market_role の決定 if your_action == "both": market_role = "both" elif (action == "bid" and your_action == "bid") or ( action == "ask" and your_action == "ask" ): market_role = "taker" elif (action == "bid" and your_action == "ask") or ( action == "ask" and your_action == "bid" ): market_role = "maker" else: market_role = "unknown" executions.append( TradeExecution( execution_id=trade_id_int, currency_pair=item.get("currency_pair", ""), trade_side=trade_side, price=Decimal(str(item.get("price", "0"))), quantity=Decimal(str(item.get("amount", "0"))), fee_amount=Decimal(str(item.get("fee", "0"))), market_role=market_role, execution_time=execution_time, ) ) except (ValueError, TypeError, KeyError) as e: # 変換エラーが発生した場合はスキップ print(f"Warning: Failed to parse trade item {trade_id}: {e}") return cls(executions=executions) def to_dict(self) -> List[Dict[str, Any]]: """ TradeExecutionListインスタンスをAPIレスポンス形式のリストに変換します。 Returns: APIレスポンス形式のリスト """ result = [] for item in self.executions: trade_dict = { "id": item.execution_id, "currency_pair": item.currency_pair, "action": item.trade_side, # APIの互換性のために元の名前を維持 "price": str(item.price), "amount": str(item.quantity), "fee": str(item.fee_amount), "your_action": item.market_role, # APIの互換性のために元の名前を維持 } if item.execution_time is not None: trade_dict["timestamp"] = item.execution_time result.append(trade_dict) return result
• zaifer_mcp/models/common.py:7-7 (schema)

  Input schema type: SupportedPair literal type alias restricting currency_pair parameter to supported trading pairs.
  SupportedPair = Literal["btc_jpy", "eth_jpy", "xym_jpy"]
• zaifer_mcp/server.py:36-41 (registration)

  Registration of the trade tools module, which includes the get_trade_executions tool, by calling register_trade_tools in the main server setup.
  from zaifer_mcp.tools.trade import register_trade_tools from zaifer_mcp.tools.chart import register_chart_tools register_market_tools(mcp, zaif_api) register_account_tools(mcp, zaif_api) register_trade_tools(mcp, zaif_api)