【Pythonコードあり】GMO FX APIで注文結果を取得する方法｜約定・決済・損益を確認

"""GMO FX APIから注文・約定・建玉・決済損益を取得するサンプル。"""

import argparse
import hashlib
import hmac
import json
import os
import ssl
import time
from decimal import Decimal, InvalidOperation
from urllib.error import HTTPError, URLError
from urllib.parse import urlencode
from urllib.request import Request, urlopen

import certifi

# ============================================================
# 【重要な注意点】
# ============================================================
# 同じGMO FXアカウントで、このスクリプトを複数のターミナルから
# 同時に実行しないでください。
#
# GMO FX Private APIの呼び出し回数は、同一アカウント単位で合算されます。
# 複数のターミナルや別のスクリプトから同時にAPIへアクセスすると、
# 1秒間の呼び出し上限を超えてAPIエラーになる可能性があります。

# 使い方:
# 1. PowerShellを開き、このファイルを保存したフォルダへ移動します。
#    cd GMO-API
# 2. APIキーとAPIシークレットをPowerShellへ入力します。
#    実際の値は、このPythonファイルへ直接書かないでください。
#
#    $env:GMO_FX_API_KEY="実際のAPIキー"
#    $env:GMO_FX_SECRET_KEY="実際のAPIシークレット"
#
#    この方法では入力内容がPowerShellの履歴に残る場合があります。
#    共用パソコンなどで履歴へ残したくない場合は、Read-Hostを使用してください。
#
# 3. 注文IDを指定せずに実行すると、GMO FXから有効注文と最新約定を取得し、
#    表示された候補から確認する注文を選択できます。CSVは使用しません。
#    latestExecutionsで取得できるのは直近1日分から最新100件までです。
#    数日前などの古い注文は、注文IDを直接指定してください。
#    python trade_result.py
# 4. 注文IDが分かっている場合は、実行時に直接指定することもできます。
#    python trade_result.py 123456789
# 5. IFDOCOの親注文IDを直接指定する場合は、--rootを付けます。
#    python trade_result.py 123456789 --root
# 6. 通貨ペアの初期値はUSD_JPYです。変更する場合は--symbolを付けます。
#    python trade_result.py --symbol EUR_USD
# 7. 入力した環境変数は、そのPowerShellウィンドウを閉じると引き継がれません。

# 注文情報、約定情報、建玉情報の取得に使うGMO FX Private APIの接続先です。
# Private APIの利用には、PowerShellで入力したAPIキーとAPIシークレットが必要です。

PRIVATE_URL = "https://forex-api.coin.z.com/private"

# PowerShellでAPIキーとAPIシークレットを設定するときの環境変数名です。
# ここに認証情報そのものは書きません。実際の値はPowerShellから入力します。
# このファイル内に定義しているため、live_config.pyなど別ファイルは必要ありません。
API_KEY_ENV = "GMO_FX_API_KEY"
SECRET_KEY_ENV = "GMO_FX_SECRET_KEY"

# GMO FX Private APIのGET上限へ余裕を持って対応するため、
# 各リクエストの前に0.5秒待機します。
REQUEST_INTERVAL_SECONDS = 0.5

# certifiが持っている証明書一覧を使って、HTTPS通信の証明書を検証します。
# Windows環境でCERTIFICATE_VERIFY_FAILEDになる場合の対策です。
SSL_CONTEXT = ssl.create_default_context(cafile=certifi.where())


def list_items(data):
    """data内の明細をリストへそろえる。"""

    # data自体がリストの場合は、そのまま返します。
    if isinstance(data, list):
        return data

    # ordersなどのAPIは、data内のlistに明細が入っています。
    if isinstance(data, dict):
        rows = data.get("list", [])
        return rows if isinstance(rows, list) else []

    # データがない場合も、後続処理で安全に繰り返せるよう空リストを返します。
    return []


def private_get(path, params, api_key=None, secret_key=None):
    """環境変数の認証情報で署名し、Private APIへGET送信する。"""

    # 認証情報の値はコードに保存せず、PowerShellで入力された環境変数から取得します。
    api_key = api_key or os.environ.get(API_KEY_ENV)
    secret_key = secret_key or os.environ.get(SECRET_KEY_ENV)

    # どちらかが未設定なら、認証できないためAPIへアクセスする前に処理を止めます。
    if not api_key or not secret_key:
        raise RuntimeError(
            f"PowerShellで環境変数 {API_KEY_ENV} と "
            f"{SECRET_KEY_ENV} を設定してください。"
        )

    # API-TIMESTAMPへ設定する、現在時刻のミリ秒単位UNIX時刻を作ります。
    timestamp = str(int(time.time() * 1000))
    method = "GET"

    # GMO FXのGET署名にはクエリ文字列を含めません。
    # 「時刻 + HTTPメソッド + APIパス」を連結した文字列が署名対象です。
    sign_text = timestamp + method + path

    # APIシークレットを使い、HMAC-SHA256形式の署名を作ります。
    signature = hmac.new(
        secret_key.encode("ascii"), sign_text.encode("ascii"), hashlib.sha256
    ).hexdigest()
    # GMO FX Private APIの認証に必要な3項目をHTTPヘッダーへ設定します。
    headers = {
        "API-KEY": api_key,
        "API-TIMESTAMP": timestamp,
        "API-SIGN": signature,
    }
    # 注文IDや通貨ペアなどの検索条件をURLのクエリ文字列へ変換します。
    query = "?" + urlencode(params) if params else ""
    request = Request(PRIVATE_URL + path + query, headers=headers, method=method)

    try:
        # GMO FXへ連続でアクセスしすぎないよう、通信前に一定時間待ちます。
        # 0.5秒間隔にすることで、このスクリプトからのGETを最大約2回/秒に抑えます。
        time.sleep(REQUEST_INTERVAL_SECONDS)

        # タイムアウトを20秒に設定してAPIへアクセスし、JSONをPythonの辞書へ変換します。
        with urlopen(request, context=SSL_CONTEXT, timeout=20) as response:
            payload = json.loads(response.read().decode("utf-8"))
    except HTTPError as error:
        # HTTPステータスがエラーの場合、APIキーなどを表示せずステータス番号だけ伝えます。
        raise RuntimeError(f"GMO FX APIとの通信に失敗しました（HTTP {error.code}）。") from error
    except (URLError, TimeoutError) as error:
        # ネットワーク切断やタイムアウトを、利用者に分かるエラーへ変換します。
        raise RuntimeError(f"GMO FX APIへ接続できませんでした: {error}") from error

    # GMO FX APIは正常時にstatus=0を返します。0以外なら処理を止めます。
    if int(payload.get("status", -1)) != 0:
        raise RuntimeError(f"GMO FX APIエラー: {payload.get('messages')}")

    # 呼び出し元では共通項目を除いたdata部分だけを使用します。
    return payload.get("data")


def get_trade_result(order_id, use_root_order_id=False, private_get_func=private_get):
    """注文IDを起点に、関連する注文・約定・有効建玉を取得する。"""

    # --rootが付いていれば親注文ID、なければ通常の注文IDとして検索します。
    id_type = "rootOrderId" if use_root_order_id else "orderId"
    orders = list_items(private_get_func("/v1/orders", {id_type: order_id}))

    # 注文が見つからなければ、約定や建玉も空の結果として返します。
    if not orders:
        return {"orders": [], "executions": [], "open_positions": []}

    # 通常の注文IDが指定された場合も、親注文IDをたどってIFDOCOを構成する
    # エントリー・TP・SLの全注文を取得する。
    if not use_root_order_id:
        root_order_id = orders[0].get("rootOrderId")
        if root_order_id is not None:
            related_orders = list_items(
                private_get_func("/v1/orders", {"rootOrderId": root_order_id})
            )
            if related_orders:
                orders = related_orders

    # IFDOCOを構成する各注文について、約定情報を1件ずつ取得してまとめます。
    # executions APIはorderIdを1つずつ指定して呼び出します。
    executions = []
    for order in orders:
        current_order_id = order.get("orderId")

        # レスポンスに注文IDがない不完全な明細は、誤照会を防ぐため読み飛ばします。
        if current_order_id is None:
            continue
        rows = list_items(
            private_get_func("/v1/executions", {"orderId": current_order_id})
        )
        executions.extend(rows)

    # 約定に含まれる建玉IDだけを照合する。対象銘柄が複数でも確認できるよう、
    # 銘柄ごとに有効建玉一覧を取得する。
    # 約定情報から建玉IDを取り出します。
    # 同じ建玉IDが複数回現れても、setにすることで重複を除けます。
    position_ids = {
        str(row["positionId"])
        for row in executions
        if row.get("positionId") is not None
    }
    # 建玉一覧APIは通貨ペアで検索するため、注文から対象通貨ペアを取り出します。
    symbols = sorted({row.get("symbol") for row in orders if row.get("symbol")})
    open_positions = []
    for symbol in symbols if position_ids else []:
        # 同じ通貨ペアの有効建玉を最大100件取得します。
        rows = list_items(
            private_get_func("/v1/openPositions", {"symbol": symbol, "count": 100})
        )
        # 口座内の別の建玉を混ぜないよう、対象注文の建玉IDと一致するものだけ残します。
        open_positions.extend(
            row for row in rows if str(row.get("positionId")) in position_ids
        )

    return {
        "orders": orders,
        "executions": executions,
        "open_positions": open_positions,
    }


def find_order_candidates(symbol, private_get_func=private_get):
    """GMO FXから有効注文と最新約定を取得し、注文IDの候補を作る。"""

    # activeOrdersには、まだ約定・取消されていない注文が入っています。
    active_orders = list_items(
        private_get_func("/v1/activeOrders", {"symbol": symbol, "count": 100})
    )

    # latestExecutionsには、直近1日分から最新100件までの約定が入っています。
    # 決済済み注文はactiveOrdersから消えるため、こちらも候補へ加えます。
    latest_executions = list_items(
        private_get_func("/v1/latestExecutions", {"symbol": symbol, "count": 100})
    )

    # 注文IDをキーにして重複を除きます。
    # 同じ注文が有効注文と約定情報の両方に含まれても、候補には1回だけ表示します。
    candidates = {}
    for order in active_orders:
        order_id = order.get("orderId")
        if order_id is None:
            continue
        candidates[str(order_id)] = {
            "order_id": str(order_id),
            "root_order_id": str(order.get("rootOrderId", "")),
            "symbol": order.get("symbol", symbol),
            "side": order.get("side", "-"),
            "settle_type": order.get("settleType", "-"),
            "status": order.get("status", "有効注文"),
            "timestamp": order.get("timestamp", "-"),
        }

    for execution in latest_executions:
        order_id = execution.get("orderId")
        if order_id is None or str(order_id) in candidates:
            continue
        candidates[str(order_id)] = {
            "order_id": str(order_id),
            # 約定情報には親注文IDがないため、選択後にorders APIから取得します。
            "root_order_id": "",
            "symbol": execution.get("symbol", symbol),
            "side": execution.get("side", "-"),
            "settle_type": execution.get("settleType", "-"),
            "status": "約定済み",
            "timestamp": execution.get("timestamp", "-"),
        }

    # 新しい候補から確認できるよう、APIの日時文字列で降順に並べます。
    return sorted(candidates.values(), key=lambda row: row["timestamp"], reverse=True)


def select_order_id(candidates, input_func=input):
    """候補番号または手入力された注文IDを受け取る。"""

    print("\n【GMO FXから取得した注文ID候補】")
    print(
        "注文IDを省略した場合は、有効注文と直近1日分の最新約定から候補を表示します。"
    )
    print("過去の注文を確認する場合は、注文IDを直接指定してください。")
    if candidates:
        for number, row in enumerate(candidates, start=1):
            print(
                f"{number}. 注文ID={row['order_id']} "
                f"親注文ID={row['root_order_id'] or '-'} "
                f"{row['symbol']} {row['side']} {row['settle_type']} "
                f"{row['status']} {row['timestamp']}"
            )
        prompt = "候補番号または確認する注文IDを入力してください: "
    else:
        print("有効注文または最新約定から注文IDを取得できませんでした。")
        prompt = "確認する注文IDを入力してください: "

    entered = input_func(prompt).strip()

    # 1から候補件数までの数字なら、画面に表示した候補番号として扱います。
    if entered.isdigit() and 1 <= int(entered) <= len(candidates):
        return candidates[int(entered) - 1]["order_id"]

    # 候補番号に該当しない数字は、注文IDの直接入力として扱います。
    if entered.isdigit():
        return entered

    raise ValueError("候補番号または数字の注文IDを入力してください。")


def decimal_sum(rows, field):
    """APIの数値文字列をDecimalで安全に合計する。"""

    # 金額計算ではfloatの丸め誤差を避けるためDecimalを使います。
    total = Decimal("0")
    for row in rows:
        try:
            total += Decimal(str(row.get(field, "0")))
        except (InvalidOperation, TypeError):
            # 数値へ変換できない項目があっても、ほかの明細の集計を続けます。
            pass
    return total


def display_trade_result(result):
    """取得結果を、注文・約定・建玉・決済の順に表示する。"""

    # get_trade_result()が返した3種類の情報を取り出します。
    orders = result["orders"]
    executions = result["executions"]
    open_positions = result["open_positions"]

    if not orders:
        print("指定した注文IDの注文情報は見つかりませんでした。")
        return

    # 注文情報では、受付中・約定・取消など各注文の現在の状態を確認できます。
    print("\n【注文情報】")
    for order in orders:
        print(f"注文ID: {order.get('orderId', '-')}")
        print(f"  親注文ID: {order.get('rootOrderId', '-')}")
        print(f"  通貨ペア: {order.get('symbol', '-')}")
        print(f"  売買: {order.get('side', '-')} / 区分: {order.get('settleType', '-')}")
        print(f"  注文方法: {order.get('executionType', '-')}")
        print(f"  注文数量: {order.get('size', '-')}")
        print(f"  注文価格: {order.get('price', '成行注文のため指定なし')}")
        print(f"  ステータス: {order.get('status', '-')}")
        if order.get("cancelType"):
            print(f"  取消理由: {order['cancelType']}")

    # 約定情報には、実際に取引が成立した価格・数量・損益が入っています。
    print("\n【約定情報】")
    if not executions:
        print("約定情報はありません。注文が未約定または取消済みの可能性があります。")
    for execution in executions:
        print(f"約定ID: {execution.get('executionId', '-')}")
        print(f"  注文ID: {execution.get('orderId', '-')}")
        print(f"  建玉ID: {execution.get('positionId', '-')}")
        print(f"  売買: {execution.get('side', '-')} / 区分: {execution.get('settleType', '-')}")
        print(f"  約定価格: {execution.get('price', '-')}")
        print(f"  約定数量: {execution.get('size', '-')}")
        print(f"  決済損益: {execution.get('lossGain', '0')}")
        print(f"  決済スワップ: {execution.get('settledSwap', '0')}")
        print(f"  取引手数料: {execution.get('fee', '0')}")
        print(f"  約定日時: {execution.get('timestamp', '-')}")

    # 約定から得た建玉IDが有効建玉一覧に残っているかを表示します。
    print("\n【建玉情報】")
    if open_positions:
        print("対象注文から作られた建玉が残っています。")
        for position in open_positions:
            print(
                f"建玉ID: {position.get('positionId', '-')} / "
                f"数量: {position.get('size', '-')} / "
                f"建玉価格: {position.get('price', '-')} / "
                f"評価損益: {position.get('lossGain', '-')}"
            )
    else:
        print("対象注文に関連する有効建玉はありません。")

    # settleType=CLOSEだけを取り出し、決済損益の集計対象にします。
    close_executions = [
        row for row in executions if row.get("settleType") == "CLOSE"
    ]
    # 約定の注文IDから元の注文方法を引けるよう、注文情報を辞書にします。
    order_by_id = {str(row.get("orderId")): row for row in orders}

    print("\n【決済結果】")
    if not close_executions:
        print("決済約定はまだ確認できません。")
        return

    for execution in close_executions:
        order = order_by_id.get(str(execution.get("orderId")), {})
        execution_type = order.get("executionType")
        # このIFDOCOサンプルでは、決済LIMITがTP、決済STOPがSLです。
        # 別の方法で発注した注文では、必ずしもこの判定になるとは限りません。
        if execution_type == "LIMIT":
            reason = "TP（指値）"
        elif execution_type == "STOP":
            reason = "SL（逆指値）"
        else:
            reason = f"{execution_type or '不明'}注文"
        print(f"注文ID {execution.get('orderId', '-')}: {reason}で決済")

    # 複数回に分かれて約定した場合も、各金額をそれぞれ合計します。
    loss_gain_total = decimal_sum(close_executions, "lossGain")
    settled_swap_total = decimal_sum(close_executions, "settledSwap")
    fee_total = decimal_sum(close_executions, "fee")

    # 公式仕様に記載された3項目を分けて表示します。
    # feeの符号を使った最終損益の計算方法は公式仕様に明記されていないため、
    # このサンプルでは「最終損益」を独自に計算しません。
    print(f"決済損益合計: {loss_gain_total}")
    print(f"決済スワップ合計: {settled_swap_total}")
    print(f"取引手数料合計: {fee_total}")


def parse_args(argv=None):
    """コマンドラインから注文IDと--rootオプションを受け取る。"""

    # argparseを使うと、入力方法を示す--helpも自動で利用できます。
    parser = argparse.ArgumentParser(
        description="GMO FX APIから注文・約定・建玉・決済損益を取得します。"
    )
    parser.add_argument(
        "order_id",
        nargs="?",
        help="確認する注文ID（省略時はGMO FXから候補を取得）",
    )
    parser.add_argument(
        "--root",
        action="store_true",
        help="指定値を親注文IDとして扱い、IFDOCOの関連注文をまとめて取得します。",
    )
    parser.add_argument(
        "--symbol",
        default="USD_JPY",
        help="注文ID候補を取得する通貨ペア（初期値: USD_JPY）",
    )
    args = parser.parse_args(argv)

    # GMO FXの注文IDは数字なので、誤った値をAPIへ送る前にチェックします。
    if args.order_id is not None and not args.order_id.isdigit():
        parser.error("order_idには数字だけを指定してください。")
    if args.root and args.order_id is None:
        parser.error("--rootを使う場合は親注文IDも指定してください。")
    return args


def main(argv=None):
    # PowerShellで指定された注文IDとオプションを読み取ります。
    args = parse_args(argv)

    # 注文IDが省略された場合は、CSVではなくGMO FX APIから候補を取得します。
    order_id = args.order_id
    if order_id is None:
        candidates = find_order_candidates(args.symbol)
        order_id = select_order_id(candidates)

    # GMO FX APIから関連情報を取得します。
    result = get_trade_result(order_id, use_root_order_id=args.root)

    # APIのJSONをそのまま表示せず、確認しやすい日本語へ整理して表示します。
    display_trade_result(result)


# このファイルを直接実行したときだけmain()を動かします。
if __name__ == "__main__":
    main()

"""GMO FX APIから注文・約定・建玉・決済損益を取得するサンプル。"""

import argparse
import hashlib
import hmac
import json
import os
import ssl
import time
from decimal import Decimal, InvalidOperation
from urllib.error import HTTPError, URLError
from urllib.parse import urlencode
from urllib.request import Request, urlopen

import certifi

# ============================================================
# 【重要な注意点】
# ============================================================
# 同じGMO FXアカウントで、このスクリプトを複数のターミナルから
# 同時に実行しないでください。
#
# GMO FX Private APIの呼び出し回数は、同一アカウント単位で合算されます。
# 複数のターミナルや別のスクリプトから同時にAPIへアクセスすると、
# 1秒間の呼び出し上限を超えてAPIエラーになる可能性があります。

# 使い方:
# 1. PowerShellを開き、このファイルを保存したフォルダへ移動します。
#    cd GMO-API
# 2. APIキーとAPIシークレットをPowerShellへ入力します。
#    実際の値は、このPythonファイルへ直接書かないでください。
#
#    $env:GMO_FX_API_KEY="実際のAPIキー"
#    $env:GMO_FX_SECRET_KEY="実際のAPIシークレット"
#
#    この方法では入力内容がPowerShellの履歴に残る場合があります。
#    共用パソコンなどで履歴へ残したくない場合は、Read-Hostを使用してください。
#
# 3. 注文IDを指定せずに実行すると、GMO FXから有効注文と最新約定を取得し、
#    表示された候補から確認する注文を選択できます。CSVは使用しません。
#    latestExecutionsで取得できるのは直近1日分から最新100件までです。
#    数日前などの古い注文は、注文IDを直接指定してください。
#    python trade_result.py
# 4. 注文IDが分かっている場合は、実行時に直接指定することもできます。
#    python trade_result.py 123456789
# 5. IFDOCOの親注文IDを直接指定する場合は、--rootを付けます。
#    python trade_result.py 123456789 --root
# 6. 通貨ペアの初期値はUSD_JPYです。変更する場合は--symbolを付けます。
#    python trade_result.py --symbol EUR_USD
# 7. 入力した環境変数は、そのPowerShellウィンドウを閉じると引き継がれません。

# 注文情報、約定情報、建玉情報の取得に使うGMO FX Private APIの接続先です。
# Private APIの利用には、PowerShellで入力したAPIキーとAPIシークレットが必要です。

PRIVATE_URL = "https://forex-api.coin.z.com/private"

# PowerShellでAPIキーとAPIシークレットを設定するときの環境変数名です。
# ここに認証情報そのものは書きません。実際の値はPowerShellから入力します。
# このファイル内に定義しているため、live_config.pyなど別ファイルは必要ありません。
API_KEY_ENV = "GMO_FX_API_KEY"
SECRET_KEY_ENV = "GMO_FX_SECRET_KEY"

# GMO FX Private APIのGET上限へ余裕を持って対応するため、
# 各リクエストの前に0.5秒待機します。
REQUEST_INTERVAL_SECONDS = 0.5

# certifiが持っている証明書一覧を使って、HTTPS通信の証明書を検証します。
# Windows環境でCERTIFICATE_VERIFY_FAILEDになる場合の対策です。
SSL_CONTEXT = ssl.create_default_context(cafile=certifi.where())


def list_items(data):
    """data内の明細をリストへそろえる。"""

    # data自体がリストの場合は、そのまま返します。
    if isinstance(data, list):
        return data

    # ordersなどのAPIは、data内のlistに明細が入っています。
    if isinstance(data, dict):
        rows = data.get("list", [])
        return rows if isinstance(rows, list) else []

    # データがない場合も、後続処理で安全に繰り返せるよう空リストを返します。
    return []


def private_get(path, params, api_key=None, secret_key=None):
    """環境変数の認証情報で署名し、Private APIへGET送信する。"""

    # 認証情報の値はコードに保存せず、PowerShellで入力された環境変数から取得します。
    api_key = api_key or os.environ.get(API_KEY_ENV)
    secret_key = secret_key or os.environ.get(SECRET_KEY_ENV)

    # どちらかが未設定なら、認証できないためAPIへアクセスする前に処理を止めます。
    if not api_key or not secret_key:
        raise RuntimeError(
            f"PowerShellで環境変数 {API_KEY_ENV} と "
            f"{SECRET_KEY_ENV} を設定してください。"
        )

    # API-TIMESTAMPへ設定する、現在時刻のミリ秒単位UNIX時刻を作ります。
    timestamp = str(int(time.time() * 1000))
    method = "GET"

    # GMO FXのGET署名にはクエリ文字列を含めません。
    # 「時刻 + HTTPメソッド + APIパス」を連結した文字列が署名対象です。
    sign_text = timestamp + method + path

    # APIシークレットを使い、HMAC-SHA256形式の署名を作ります。
    signature = hmac.new(
        secret_key.encode("ascii"), sign_text.encode("ascii"), hashlib.sha256
    ).hexdigest()
    # GMO FX Private APIの認証に必要な3項目をHTTPヘッダーへ設定します。
    headers = {
        "API-KEY": api_key,
        "API-TIMESTAMP": timestamp,
        "API-SIGN": signature,
    }
    # 注文IDや通貨ペアなどの検索条件をURLのクエリ文字列へ変換します。
    query = "?" + urlencode(params) if params else ""
    request = Request(PRIVATE_URL + path + query, headers=headers, method=method)

    try:
        # GMO FXへ連続でアクセスしすぎないよう、通信前に一定時間待ちます。
        # 0.5秒間隔にすることで、このスクリプトからのGETを最大約2回/秒に抑えます。
        time.sleep(REQUEST_INTERVAL_SECONDS)

        # タイムアウトを20秒に設定してAPIへアクセスし、JSONをPythonの辞書へ変換します。
        with urlopen(request, context=SSL_CONTEXT, timeout=20) as response:
            payload = json.loads(response.read().decode("utf-8"))
    except HTTPError as error:
        # HTTPステータスがエラーの場合、APIキーなどを表示せずステータス番号だけ伝えます。
        raise RuntimeError(f"GMO FX APIとの通信に失敗しました（HTTP {error.code}）。") from error
    except (URLError, TimeoutError) as error:
        # ネットワーク切断やタイムアウトを、利用者に分かるエラーへ変換します。
        raise RuntimeError(f"GMO FX APIへ接続できませんでした: {error}") from error

    # GMO FX APIは正常時にstatus=0を返します。0以外なら処理を止めます。
    if int(payload.get("status", -1)) != 0:
        raise RuntimeError(f"GMO FX APIエラー: {payload.get('messages')}")

    # 呼び出し元では共通項目を除いたdata部分だけを使用します。
    return payload.get("data")


def get_trade_result(order_id, use_root_order_id=False, private_get_func=private_get):
    """注文IDを起点に、関連する注文・約定・有効建玉を取得する。"""

    # --rootが付いていれば親注文ID、なければ通常の注文IDとして検索します。
    id_type = "rootOrderId" if use_root_order_id else "orderId"
    orders = list_items(private_get_func("/v1/orders", {id_type: order_id}))

    # 注文が見つからなければ、約定や建玉も空の結果として返します。
    if not orders:
        return {"orders": [], "executions": [], "open_positions": []}

    # 通常の注文IDが指定された場合も、親注文IDをたどってIFDOCOを構成する
    # エントリー・TP・SLの全注文を取得する。
    if not use_root_order_id:
        root_order_id = orders[0].get("rootOrderId")
        if root_order_id is not None:
            related_orders = list_items(
                private_get_func("/v1/orders", {"rootOrderId": root_order_id})
            )
            if related_orders:
                orders = related_orders

    # IFDOCOを構成する各注文について、約定情報を1件ずつ取得してまとめます。
    # executions APIはorderIdを1つずつ指定して呼び出します。
    executions = []
    for order in orders:
        current_order_id = order.get("orderId")

        # レスポンスに注文IDがない不完全な明細は、誤照会を防ぐため読み飛ばします。
        if current_order_id is None:
            continue
        rows = list_items(
            private_get_func("/v1/executions", {"orderId": current_order_id})
        )
        executions.extend(rows)

    # 約定に含まれる建玉IDだけを照合する。対象銘柄が複数でも確認できるよう、
    # 銘柄ごとに有効建玉一覧を取得する。
    # 約定情報から建玉IDを取り出します。
    # 同じ建玉IDが複数回現れても、setにすることで重複を除けます。
    position_ids = {
        str(row["positionId"])
        for row in executions
        if row.get("positionId") is not None
    }
    # 建玉一覧APIは通貨ペアで検索するため、注文から対象通貨ペアを取り出します。
    symbols = sorted({row.get("symbol") for row in orders if row.get("symbol")})
    open_positions = []
    for symbol in symbols if position_ids else []:
        # 同じ通貨ペアの有効建玉を最大100件取得します。
        rows = list_items(
            private_get_func("/v1/openPositions", {"symbol": symbol, "count": 100})
        )
        # 口座内の別の建玉を混ぜないよう、対象注文の建玉IDと一致するものだけ残します。
        open_positions.extend(
            row for row in rows if str(row.get("positionId")) in position_ids
        )

    return {
        "orders": orders,
        "executions": executions,
        "open_positions": open_positions,
    }


def find_order_candidates(symbol, private_get_func=private_get):
    """GMO FXから有効注文と最新約定を取得し、注文IDの候補を作る。"""

    # activeOrdersには、まだ約定・取消されていない注文が入っています。
    active_orders = list_items(
        private_get_func("/v1/activeOrders", {"symbol": symbol, "count": 100})
    )

    # latestExecutionsには、直近1日分から最新100件までの約定が入っています。
    # 決済済み注文はactiveOrdersから消えるため、こちらも候補へ加えます。
    latest_executions = list_items(
        private_get_func("/v1/latestExecutions", {"symbol": symbol, "count": 100})
    )

    # 注文IDをキーにして重複を除きます。
    # 同じ注文が有効注文と約定情報の両方に含まれても、候補には1回だけ表示します。
    candidates = {}
    for order in active_orders:
        order_id = order.get("orderId")
        if order_id is None:
            continue
        candidates[str(order_id)] = {
            "order_id": str(order_id),
            "root_order_id": str(order.get("rootOrderId", "")),
            "symbol": order.get("symbol", symbol),
            "side": order.get("side", "-"),
            "settle_type": order.get("settleType", "-"),
            "status": order.get("status", "有効注文"),
            "timestamp": order.get("timestamp", "-"),
        }

    for execution in latest_executions:
        order_id = execution.get("orderId")
        if order_id is None or str(order_id) in candidates:
            continue
        candidates[str(order_id)] = {
            "order_id": str(order_id),
            # 約定情報には親注文IDがないため、選択後にorders APIから取得します。
            "root_order_id": "",
            "symbol": execution.get("symbol", symbol),
            "side": execution.get("side", "-"),
            "settle_type": execution.get("settleType", "-"),
            "status": "約定済み",
            "timestamp": execution.get("timestamp", "-"),
        }

    # 新しい候補から確認できるよう、APIの日時文字列で降順に並べます。
    return sorted(candidates.values(), key=lambda row: row["timestamp"], reverse=True)


def select_order_id(candidates, input_func=input):
    """候補番号または手入力された注文IDを受け取る。"""

    print("\n【GMO FXから取得した注文ID候補】")
    print(
        "注文IDを省略した場合は、有効注文と直近1日分の最新約定から候補を表示します。"
    )
    print("過去の注文を確認する場合は、注文IDを直接指定してください。")
    if candidates:
        for number, row in enumerate(candidates, start=1):
            print(
                f"{number}. 注文ID={row['order_id']} "
                f"親注文ID={row['root_order_id'] or '-'} "
                f"{row['symbol']} {row['side']} {row['settle_type']} "
                f"{row['status']} {row['timestamp']}"
            )
        prompt = "候補番号または確認する注文IDを入力してください: "
    else:
        print("有効注文または最新約定から注文IDを取得できませんでした。")
        prompt = "確認する注文IDを入力してください: "

    entered = input_func(prompt).strip()

    # 1から候補件数までの数字なら、画面に表示した候補番号として扱います。
    if entered.isdigit() and 1 <= int(entered) <= len(candidates):
        return candidates[int(entered) - 1]["order_id"]

    # 候補番号に該当しない数字は、注文IDの直接入力として扱います。
    if entered.isdigit():
        return entered

    raise ValueError("候補番号または数字の注文IDを入力してください。")


def decimal_sum(rows, field):
    """APIの数値文字列をDecimalで安全に合計する。"""

    # 金額計算ではfloatの丸め誤差を避けるためDecimalを使います。
    total = Decimal("0")
    for row in rows:
        try:
            total += Decimal(str(row.get(field, "0")))
        except (InvalidOperation, TypeError):
            # 数値へ変換できない項目があっても、ほかの明細の集計を続けます。
            pass
    return total


def display_trade_result(result):
    """取得結果を、注文・約定・建玉・決済の順に表示する。"""

    # get_trade_result()が返した3種類の情報を取り出します。
    orders = result["orders"]
    executions = result["executions"]
    open_positions = result["open_positions"]

    if not orders:
        print("指定した注文IDの注文情報は見つかりませんでした。")
        return

    # 注文情報では、受付中・約定・取消など各注文の現在の状態を確認できます。
    print("\n【注文情報】")
    for order in orders:
        print(f"注文ID: {order.get('orderId', '-')}")
        print(f"  親注文ID: {order.get('rootOrderId', '-')}")
        print(f"  通貨ペア: {order.get('symbol', '-')}")
        print(f"  売買: {order.get('side', '-')} / 区分: {order.get('settleType', '-')}")
        print(f"  注文方法: {order.get('executionType', '-')}")
        print(f"  注文数量: {order.get('size', '-')}")
        print(f"  注文価格: {order.get('price', '成行注文のため指定なし')}")
        print(f"  ステータス: {order.get('status', '-')}")
        if order.get("cancelType"):
            print(f"  取消理由: {order['cancelType']}")

    # 約定情報には、実際に取引が成立した価格・数量・損益が入っています。
    print("\n【約定情報】")
    if not executions:
        print("約定情報はありません。注文が未約定または取消済みの可能性があります。")
    for execution in executions:
        print(f"約定ID: {execution.get('executionId', '-')}")
        print(f"  注文ID: {execution.get('orderId', '-')}")
        print(f"  建玉ID: {execution.get('positionId', '-')}")
        print(f"  売買: {execution.get('side', '-')} / 区分: {execution.get('settleType', '-')}")
        print(f"  約定価格: {execution.get('price', '-')}")
        print(f"  約定数量: {execution.get('size', '-')}")
        print(f"  決済損益: {execution.get('lossGain', '0')}")
        print(f"  決済スワップ: {execution.get('settledSwap', '0')}")
        print(f"  取引手数料: {execution.get('fee', '0')}")
        print(f"  約定日時: {execution.get('timestamp', '-')}")

    # 約定から得た建玉IDが有効建玉一覧に残っているかを表示します。
    print("\n【建玉情報】")
    if open_positions:
        print("対象注文から作られた建玉が残っています。")
        for position in open_positions:
            print(
                f"建玉ID: {position.get('positionId', '-')} / "
                f"数量: {position.get('size', '-')} / "
                f"建玉価格: {position.get('price', '-')} / "
                f"評価損益: {position.get('lossGain', '-')}"
            )
    else:
        print("対象注文に関連する有効建玉はありません。")

    # settleType=CLOSEだけを取り出し、決済損益の集計対象にします。
    close_executions = [
        row for row in executions if row.get("settleType") == "CLOSE"
    ]
    # 約定の注文IDから元の注文方法を引けるよう、注文情報を辞書にします。
    order_by_id = {str(row.get("orderId")): row for row in orders}

    print("\n【決済結果】")
    if not close_executions:
        print("決済約定はまだ確認できません。")
        return

    for execution in close_executions:
        order = order_by_id.get(str(execution.get("orderId")), {})
        execution_type = order.get("executionType")
        # このIFDOCOサンプルでは、決済LIMITがTP、決済STOPがSLです。
        # 別の方法で発注した注文では、必ずしもこの判定になるとは限りません。
        if execution_type == "LIMIT":
            reason = "TP（指値）"
        elif execution_type == "STOP":
            reason = "SL（逆指値）"
        else:
            reason = f"{execution_type or '不明'}注文"
        print(f"注文ID {execution.get('orderId', '-')}: {reason}で決済")

    # 複数回に分かれて約定した場合も、各金額をそれぞれ合計します。
    loss_gain_total = decimal_sum(close_executions, "lossGain")
    settled_swap_total = decimal_sum(close_executions, "settledSwap")
    fee_total = decimal_sum(close_executions, "fee")

    # 公式仕様に記載された3項目を分けて表示します。
    # feeの符号を使った最終損益の計算方法は公式仕様に明記されていないため、
    # このサンプルでは「最終損益」を独自に計算しません。
    print(f"決済損益合計: {loss_gain_total}")
    print(f"決済スワップ合計: {settled_swap_total}")
    print(f"取引手数料合計: {fee_total}")


def parse_args(argv=None):
    """コマンドラインから注文IDと--rootオプションを受け取る。"""

    # argparseを使うと、入力方法を示す--helpも自動で利用できます。
    parser = argparse.ArgumentParser(
        description="GMO FX APIから注文・約定・建玉・決済損益を取得します。"
    )
    parser.add_argument(
        "order_id",
        nargs="?",
        help="確認する注文ID（省略時はGMO FXから候補を取得）",
    )
    parser.add_argument(
        "--root",
        action="store_true",
        help="指定値を親注文IDとして扱い、IFDOCOの関連注文をまとめて取得します。",
    )
    parser.add_argument(
        "--symbol",
        default="USD_JPY",
        help="注文ID候補を取得する通貨ペア（初期値: USD_JPY）",
    )
    args = parser.parse_args(argv)

    # GMO FXの注文IDは数字なので、誤った値をAPIへ送る前にチェックします。
    if args.order_id is not None and not args.order_id.isdigit():
        parser.error("order_idには数字だけを指定してください。")
    if args.root and args.order_id is None:
        parser.error("--rootを使う場合は親注文IDも指定してください。")
    return args


def main(argv=None):
    # PowerShellで指定された注文IDとオプションを読み取ります。
    args = parse_args(argv)

    # 注文IDが省略された場合は、CSVではなくGMO FX APIから候補を取得します。
    order_id = args.order_id
    if order_id is None:
        candidates = find_order_candidates(args.symbol)
        order_id = select_order_id(candidates)

    # GMO FX APIから関連情報を取得します。
    result = get_trade_result(order_id, use_root_order_id=args.root)

    # APIのJSONをそのまま表示せず、確認しやすい日本語へ整理して表示します。
    display_trade_result(result)


# このファイルを直接実行したときだけmain()を動かします。
if __name__ == "__main__":
    main()