ocean-agent 0.3.0__py3-none-any.whl

ocean_agent/__init__.py

@@ -0,0 +1,133 @@
+import os
+
+
+def _is_testnet(base_url: str) -> bool:
+    return "test-api" in base_url
+
+
+def data_tag() -> str:
+    """라이브 계좌 데이터의 네임스페이스: 'testnet' vs 'mainnet'.
+
+    두 네트워크의 실매매 기록(상태·관측·승률·calibration·postmortem·예측·로그)이
+    절대 섞이지 않도록 파일을 분리한다. 판단 기준은 PACIFICA_BASE_URL 환경변수
+    (MCP는 .mcp.json이, 자율 개체는 시작 시 policy의 base_url로 설정)이며,
+    알 수 없으면 안전하게 'testnet'으로 본다.
+    MUSTACHE_DATA_TAG 로 강제 지정하면 그것이 최우선(멀티 인스턴스 격리용)."""
+    override = os.environ.get("MUSTACHE_DATA_TAG")
+    if override:
+        return override
+    base = os.environ.get("PACIFICA_BASE_URL", "")
+    return "mainnet" if (base and "test-api" not in base) else "testnet"
+
+
+def data_file(name: str) -> str:
+    """네트워크별 라이브 데이터 파일의 홈 경로를 돌려준다.
+
+    예) data_file("autonomous.json") -> ~/.ocean_agent_testnet_autonomous.json
+    시장 백테스트 매트릭스는 네트워크와 무관(가격 히스토리)하므로 여기 쓰지 않고
+    ~/.ocean_agent_matrix.json 하나로 공유한다."""
+    return os.path.join(os.path.expanduser("~"),
+                        f".ocean_agent_{data_tag()}_{name}")
+
+
+# Mainnet-only brand name. Testnet keeps the original generic label so the
+# testnet experience is byte-for-byte unchanged. This is DISPLAY ONLY (Telegram
+# alerts, logs, MCP handshake) — it never touches data-file names, state keys,
+# the PyPI package id, or the .mcp.json tool namespace, so it can't collide with
+# the storage/logic layer.
+_BRAND_MAINNET = "Ocean Agent"
+_BRAND_TESTNET = "자율 개체"
+
+
+def agent_name(default: str = _BRAND_TESTNET) -> str:
+    """User-facing display name. 'Ocean Agent' on mainnet, otherwise `default`.
+    Driven by the same PACIFICA_BASE_URL as data_tag(), so name and data
+    namespace always agree (mainnet name ↔ mainnet files)."""
+    return _BRAND_MAINNET if data_tag() == "mainnet" else default
+
+
+# 네트워크 분리 이전(구버전)의 라이브 파일 이름들. 매트릭스는 공유라 제외.
+_LIVE_FILES = ["autonomous.json", "equity.jsonl", "bot.log", "calibration.json",
+               "observations.jsonl", "signal_stats.json", "observe_rotation.txt",
+               "postmortem.jsonl", "bot_state.json", "predictions.json"]
+
+
+def migrate_brand_rename() -> list:
+    """옛 이름(~/.mustache_*)의 데이터를 새 이름(~/.ocean_agent_*)으로 1회 옮긴다.
+
+    0.3.0 에서 배포 이름이 mustache-mcp → ocean-agent 로 바뀌면서 홈 데이터
+    파일 접두어도 함께 바뀌었다. 이사가 없으면 기존 사용자는 쌓아온 매트릭스·
+    관측·손익 기록을 통째로 잃고 빈 상태로 다시 시작하게 된다.
+
+    안전 규칙 두 가지:
+      · 새 이름이 이미 있으면 건드리지 않는다 (멱등 — 여러 번 불러도 안전)
+      · 복사가 아니라 이름 변경이라 디스크를 두 배로 쓰지 않는다
+        (bincache 는 378MB 라 복사하면 느리고, 어차피 재다운로드 가능하다)
+    """
+    home = os.path.expanduser("~")
+    moved = []
+    try:
+        entries = os.listdir(home)
+    except OSError:
+        return moved
+    for entry in entries:
+        if not entry.startswith(".mustache_"):
+            continue
+        old = os.path.join(home, entry)
+        new = os.path.join(home, ".ocean_agent_" + entry[len(".mustache_"):])
+        if os.path.exists(new):
+            continue                      # 이미 옮겨졌거나 새로 만들어진 것
+        try:
+            os.rename(old, new)           # 파일·디렉터리 모두 처리
+            moved.append(entry)
+        except OSError:
+            pass                          # 사용 중이면 다음 실행에 다시 시도
+    return moved
+
+
+def migrate_legacy_data() -> list:
+    """구버전 untagged 라이브 파일(~/.ocean_agent_X)을 testnet 태그본으로 1회 이전한다.
+
+    지금까지 봇은 테스트넷에서만 돌았으므로 기존 데이터는 전부 테스트넷 것이다 →
+    항상 'testnet' 태그로만 옮긴다(현재 네트워크가 메인넷이어도 옛 테스트넷 데이터를
+    메인넷에 섞지 않기 위해). 태그본이 이미 있으면 건드리지 않아 멱등하며,
+    .bak/.polluted 등 접미사 백업은 정확한 이름이 아니라 옮기지 않는다."""
+    home = os.path.expanduser("~")
+    moved = []
+    for name in _LIVE_FILES:
+        legacy = os.path.join(home, f".ocean_agent_{name}")
+        tagged = os.path.join(home, f".ocean_agent_testnet_{name}")
+        if os.path.exists(legacy) and not os.path.exists(tagged):
+            try:
+                os.replace(legacy, tagged)
+                moved.append(name)
+            except OSError:
+                pass
+    return moved
+
+
+def api_key_from_env(base_url: str = "") -> str:
+    """네트워크에 맞는 API 키를 고른다.
+
+    에이전트 키는 메인넷·테스트넷에서 각각 따로 승인되므로 키가 다를 수 있다.
+    테스트넷 대상이고 PACIFICA_API_KEY_TESTNET 이 있으면 그것을, 아니면
+    PACIFICA_API_KEY (구 AGENT_PRIVATE_KEY 호환)를 사용한다.
+    """
+    if _is_testnet(base_url):
+        tn = os.environ.get("PACIFICA_API_KEY_TESTNET")
+        if tn:
+            return tn
+    return os.environ.get("PACIFICA_API_KEY") or os.environ.get("AGENT_PRIVATE_KEY", "")
+
+
+def address_from_env(base_url: str = "") -> str:
+    """네트워크에 맞는 계정 주소를 고른다.
+
+    테스트넷은 별도 지갑을 쓸 수 있으므로 ADDRESS_TESTNET 을 우선 사용한다.
+    없으면 ADDRESS 로 폴백 (양쪽 같은 지갑을 쓰는 경우).
+    """
+    if _is_testnet(base_url):
+        tn = os.environ.get("ADDRESS_TESTNET")
+        if tn:
+            return tn
+    return os.environ.get("ADDRESS", "")

ocean_agent/advisor.py

@@ -0,0 +1,210 @@
+"""계정 상태를 보고 운용 설정을 추천한다 — 레버리지·마진모드·포지션 수.
+
+읽기 전용이다. 설정을 바꾸지 않고, 왜 그 값인지 근거와 함께 제안만 한다.
+숫자는 전부 계정 잔고·거래소 스펙·측정된 승률에서 나오며, 관습이나 감이 아니다.
+
+설계 원칙 세 가지 (이 파일의 모든 계산이 여기서 나온다):
+
+1. 포지션 크기는 레버리지가 아니라 '손절 거리'가 정한다.
+   명목가 = 자본 × 거래당위험% ÷ 손절폭.  레버리지는 약분되어 사라진다.
+   → "레버리지를 올리면 더 번다"는 틀렸다. 묶이는 증거금만 줄어든다.
+
+2. 그래서 레버리지는 '원하는 명목가를 담을 수 있는 최소값'이 최적이다.
+   더 올리면 청산선만 가까워질 뿐 수익은 그대로다. 레버리지는 이득이 아니라
+   비용이다 — 필요한 만큼만 쓴다.
+
+3. 진짜 상한은 '한 번에 감수할 총위험'이다.
+   포지션 수 × 거래당위험. 신호들이 같은 방향이면 분산 효과가 없으므로
+   보수적으로 잡아야 한다.
+"""
+
+MMR_DIV = 2          # MMR = 1 / 시장최대레버리지 / 2  (독스 기준)
+TAKER_FEE = 0.0004   # 30일 거래량 $5M 미만 티어
+MAKER_FEE = 0.00015
+
+
+def _market_specs(client) -> dict:
+    """심볼 -> {max_leverage, mmr}. 거래소가 주는 값만 쓴다."""
+    out = {}
+    try:
+        for m in client.get_markets():
+            ml = int(m.get("max_leverage") or 0)
+            if ml > 0:
+                out[m["symbol"]] = {"max_leverage": ml,
+                                    "mmr": 1.0 / ml / MMR_DIV}
+    except Exception:
+        pass
+    return out
+
+
+def _tradable(client, policy) -> list:
+    """정책이 실제로 진입을 허용하는 심볼들."""
+    if policy.get("entry_deep_history_only", False):
+        try:
+            from .historical_data import BINANCE_SYMBOL
+            return sorted(BINANCE_SYMBOL)
+        except Exception:
+            pass
+    try:
+        return sorted(m["symbol"] for m in client.get_markets())
+    except Exception:
+        return []
+
+
+def _measured_edges(policy) -> list:
+    """정책 관문을 통과하는 (신호, 시간봉, 실측승률, 표본). 없으면 빈 리스트."""
+    try:
+        from .walkforward import _load_curve
+        from .signal_scanner import _matrix_rejects, MIN_EDGE
+        c = _load_curve()
+        if not c or not c.get("sig_tf"):
+            return []
+        mw = float(policy.get("min_win_rate", 0.52))
+        rows = []
+        for k, (wr, n) in c["sig_tf"].items():
+            sig, tf = k.split("|", 1)
+            if _matrix_rejects(sig, tf) or wr < mw or wr - 0.5 < MIN_EDGE:
+                continue
+            rows.append((wr, n, sig, tf))
+        rows.sort(reverse=True)
+        return rows
+    except Exception:
+        return []
+
+
+def recommend(client, policy: dict, equity_usd: float = 0.0) -> dict:
+    """계정을 보고 설정을 제안한다. 반환은 dict (표시는 format_recommendation)."""
+    if equity_usd <= 0:
+        try:
+            equity_usd = float(client.get_account().get("account_equity") or 0)
+        except Exception:
+            equity_usd = 0.0
+    specs = _market_specs(client)
+    syms = [s for s in _tradable(client, policy) if s in specs]
+    edges = _measured_edges(policy)
+
+    # --- 거래당 위험 ---
+    # 자본이 작을수록 최소 주문 단위 때문에 미세한 사이징이 불가능해진다.
+    # $300 전후에서 1%는 $3짜리 위험이라 손절폭이 조금만 좁아도 주문이 최소
+    # 단위에 걸린다. 그래서 소액에서는 2%가 현실적인 하한이다.
+    risk_pct = 0.02 if equity_usd < 2000 else 0.01
+
+    # --- 동시 보유 수 ---
+    # 총위험 = 개수 × 거래당위험. 6%를 넘기지 않는다.
+    # 측정된 신호가 전부 같은 방향(과매도 반등 롱)이면 분산 효과가 없어
+    # '동시에 다 맞을 수 있다'고 보고 잡아야 한다.
+    same_side = False
+    if edges:
+        try:
+            from .signal_scanner import _signal_side
+            sides = {_signal_side(s) for _wr, _n, s, _tf in edges[:8]}
+            sides.discard(None)
+            same_side = len(sides) <= 1
+        except Exception:
+            pass
+    max_total_risk = 0.06 if not same_side else 0.05
+    n_pos = max(1, int(max_total_risk / risk_pct))
+
+    # --- 명목가 상한 ---
+    # 손절폭이 좁을수록 같은 위험에 더 큰 명목가가 필요하다. 실측 손절폭
+    # 중앙값을 1.5%로 보고, 포지션 수만큼 곱해 필요한 총 명목가를 구한다.
+    typical_sl = 0.015
+    notional_per = risk_pct / typical_sl                 # 자본 대비 배수
+    notional_total = notional_per * n_pos                # 자본 대비 배수
+
+    # --- 레버리지: 그 명목가를 담는 최소값 (+ 여유 20%) ---
+    # 증거금 = 명목가 / 레버리지 ≤ 자본 × 0.8 (여유 20% 남김)
+    need_lev = notional_total / 0.8
+    market_min = min((specs[s]["max_leverage"] for s in syms), default=10)
+    lev = max(2, min(int(need_lev + 0.999), market_min))
+
+    # --- 청산 여유 확인 ---
+    worst = None
+    for s in syms:
+        mmr = specs[s]["mmr"]
+        dist = (1.0 / lev) - mmr
+        if worst is None or dist < worst[1]:
+            worst = (s, dist)
+    liq_dist = worst[1] if worst else 0.0
+    # 손절(1~3%)보다 청산이 최소 5배는 멀어야 갭에 여유가 생긴다
+    while lev > 2 and liq_dist < 0.03 * 5:
+        lev -= 1
+        liq_dist = (1.0 / lev) - (worst[1] and specs[worst[0]]["mmr"] or 0)
+
+    # --- 마진 모드 ---
+    # 격리: 포지션마다 격벽. 코드 사고가 계좌 전체로 번지지 않는다.
+    # 크로스: 미실현이익이 다른 포지션을 받쳐 증거금 효율이 높다.
+    # 증거금이 자본의 절반도 안 쓰이면 크로스의 효율 이점이 없다 → 격리.
+    margin_used = notional_total / lev
+    isolated = margin_used < 0.7
+    margin_reason = ("증거금이 자본의 %.0f%%만 쓰여 크로스의 효율 이점이 없다"
+                     % (margin_used * 100)) if isolated else \
+                    ("증거금이 자본의 %.0f%%라 크로스의 상계가 도움이 된다"
+                     % (margin_used * 100))
+
+    return {
+        "equity": equity_usd,
+        "risk_pct": risk_pct,
+        "n_positions": n_pos,
+        "leverage": lev,
+        "isolated": isolated,
+        "margin_reason": margin_reason,
+        "notional_total_x": notional_total,
+        "notional_per_x": notional_per,
+        "margin_used_x": margin_used,
+        "liq_distance": liq_dist,
+        "total_risk": n_pos * risk_pct,
+        "same_side": same_side,
+        "edges": edges[:6],
+        "tradable": len(syms),
+        "market_min_leverage": market_min,
+        "current": {
+            "leverage": policy.get("max_leverage"),
+            "concurrent": policy.get("max_concurrent"),
+            "risk_pct": policy.get("risk_per_trade_pct"),
+            "notional_x": policy.get("max_net_exposure_pct"),
+        },
+    }
+
+
+def format_recommendation(r: dict) -> str:
+    eq = r["equity"]
+    L = []
+    L.append("계정 잔고 $%,.2f 기준 권장 설정".replace(",.2f", ".2f") % eq)
+    L.append("")
+    L.append("  항목            권장        현재        근거")
+    cur = r["current"]
+    L.append("  거래당 위험      %.0f%%         %s         %s"
+             % (r["risk_pct"] * 100,
+                ("%.0f%%" % (float(cur['risk_pct']) * 100)) if cur['risk_pct'] else '?',
+                "소액은 최소주문 단위 때문에 1%로 못 쪼갬" if eq < 2000
+                else "자본이 커서 1%로 충분히 쪼개짐"))
+    L.append("  동시 보유       %d개         %s개         총위험 %.0f%%로 제한%s"
+             % (r["n_positions"], cur["concurrent"], r["total_risk"] * 100,
+                " (신호가 전부 같은 방향이라 더 보수적)" if r["same_side"] else ""))
+    L.append("  레버리지        %d배         %s배         명목가 %.1f배를 담는 최소값"
+             % (r["leverage"], cur["leverage"], r["notional_total_x"]))
+    L.append("  마진 모드       %s        -           %s"
+             % ("격리" if r["isolated"] else "크로스", r["margin_reason"]))
+    L.append("  명목가 상한      자본의 %.1f배  자본의 %s배   포지션 %d개 × 손절 1.5%% 기준"
+             % (r["notional_total_x"], cur["notional_x"], r["n_positions"]))
+    L.append("")
+    L.append("  증거금 사용   자본의 %.0f%% ($%.0f) — 나머지는 여유"
+             % (r["margin_used_x"] * 100, eq * r["margin_used_x"]))
+    L.append("  청산까지     %.1f%% (손절 1~3%%의 %.0f배 거리)"
+             % (r["liq_distance"] * 100, r["liq_distance"] / 0.02))
+    L.append("  1회 손절     -$%.2f  ·  %d개 동시 손절 -$%.2f (자본의 %.0f%%)"
+             % (eq * r["risk_pct"], r["n_positions"],
+                eq * r["total_risk"], r["total_risk"] * 100))
+    L.append("")
+    if r["edges"]:
+        L.append("  근거가 된 실측 신호 (워크포워드 9년):")
+        for wr, n, sig, tf in r["edges"]:
+            L.append("    %-20s %-4s %.1f%%  표본 %s" % (sig, tf, wr * 100, f"{n:,}"))
+    else:
+        L.append("  ⚠️ 측정된 신호가 없습니다 — walkforward 를 먼저 돌리세요.")
+    L.append("")
+    L.append("  ※ 레버리지는 수익을 키우지 않습니다. 포지션 크기는 손절 거리가")
+    L.append("     정하고, 레버리지는 묶이는 증거금만 바꿉니다. 그래서 '필요한")
+    L.append("     최소값'이 최적이며, 더 올리면 청산선만 가까워집니다.")
+    return "\n".join(L)

ocean_agent/api_client.py

@@ -0,0 +1,327 @@
+"""Pacifica REST API 클라이언트.
+
+- 공개 데이터: 서명 없이 GET
+- 주문/계정 변경: 에이전트 키(또는 메인 키)로 서명해 POST
+  에이전트 키의 공개키가 ADDRESS와 다르면 agent_wallet 필드를 자동으로 붙인다.
+"""
+
+import uuid
+
+import requests
+
+from .signing import keypair_from_base58, sign_operation
+
+
+class PacificaError(Exception):
+    pass
+
+
+class PacificaClient:
+    def __init__(self, base_url: str, address: str = "", private_key: str = ""):
+        self.base = base_url.rstrip("/") + "/api/v1"
+        self.address = address
+        self.keypair = keypair_from_base58(private_key) if private_key else None
+        self.session = requests.Session()
+
+    # ---------- 공개 GET ----------
+
+    @staticmethod
+    def _parse_json(r, ctx: str) -> dict:
+        """레이트리밋(429) 등 비JSON 응답을 명확한 오류로 변환."""
+        try:
+            return r.json()
+        except ValueError:
+            raise PacificaError(
+                f"{ctx} 비정상 응답 (HTTP {r.status_code}) — 레이트리밋 가능성. "
+                f"본문: {r.text[:80]!r}")
+
+    # 429 재시도 대기(초). 무거운 측정(rematrix·harness)이 같은 API 를 두드리면
+    # 10초 한 번으로는 못 넘긴다 — 2026-08-06 에 사이클 13개가 이걸로 날아갔다.
+    _RETRY_BACKOFF = (5, 20, 45)
+
+    def _get(self, path: str, params: dict | None = None) -> dict:
+        import time as _t
+        for attempt in range(len(self._RETRY_BACKOFF) + 1):
+            r = self.session.get(f"{self.base}/{path}", params=params, timeout=15)
+            if r.status_code == 429 and attempt < len(self._RETRY_BACKOFF):
+                _t.sleep(self._RETRY_BACKOFF[attempt])
+                continue
+            body = self._parse_json(r, f"GET /{path}")
+            if not body.get("success", False):
+                raise PacificaError(f"GET /{path} 실패: {body.get('error')} (code={body.get('code')})")
+            return body["data"]
+        raise PacificaError(f"GET /{path} 레이트리밋 지속 (429)")
+
+    def get_markets(self) -> list[dict]:
+        """전 마켓 스펙 (perp + spot). funding_rate, lot_size, instrument_type 포함."""
+        return self._get("info")
+
+    def get_prices(self) -> list[dict]:
+        """전 마켓 실시간 가격/펀딩비 (funding, next_funding, mid, mark 등)."""
+        return self._get("info/prices")
+
+    def get_account(self) -> dict:
+        return self._get("account", {"account": self.address})
+
+    def get_positions(self) -> list[dict]:
+        return self._get("positions", {"account": self.address})
+
+    # ---------- 서명 POST ----------
+
+    def _signed_post(self, path: str, op_type: str, payload: dict) -> dict:
+        if not self.keypair:
+            raise PacificaError("API 키가 없어 주문을 보낼 수 없습니다 "
+                                "(.env의 PACIFICA_API_KEY에 app.pacifica.fi/apikey 발급 키 입력)")
+        import time as _t
+        signer_pubkey = str(self.keypair.pubkey())
+        for attempt in (1, 2):
+            # 재시도 시 서명도 새로 (서명에 타임스탬프가 들어가므로 재사용 불가)
+            signed = sign_operation(op_type, payload, self.keypair)
+            request = {"account": self.address, **signed, **payload}
+            if signer_pubkey != self.address:
+                request["agent_wallet"] = signer_pubkey
+            r = self.session.post(f"{self.base}/{path}", json=request, timeout=15)
+            if r.status_code == 429 and attempt == 1:
+                _t.sleep(10)          # 레이트리밋 — 한 번만 쉬고 재서명·재시도
+                continue
+            body = self._parse_json(r, f"POST /{path}")
+            # success 키가 없으면 실패로 간주(안전). 200인데 스펙 밖 응답이
+            # 오면 '주문 성공'으로 오독하지 않는다 — 돈이 걸린 경로라 보수적으로.
+            if r.status_code != 200 or not body.get("success", False):
+                raise PacificaError(f"POST /{path} 실패 ({r.status_code}): {r.text}")
+            return body.get("data", body)
+        raise PacificaError(f"POST /{path} 레이트리밋 지속 (429)")
+
+    # 하드 사이징 가드 — 한 주문의 명목가 절대 상한(USD). 봇 정책($3,000)보다
+    # 넉넉히 높게 두되, '폭주'는 확실히 막는 최후 방어선. 봇·스크립트·웹 등
+    # 어느 경로로 온 주문이든 이 함수를 통과하므로 여기서 한 번에 막는다.
+    # reduce_only(청산)는 예외 — 큰 포지션 정리를 막으면 안 됨.
+    MAX_ORDER_NOTIONAL_USD = 20_000
+
+    def create_market_order(self, symbol: str, side: str, amount: str,
+                            slippage_percent: str, reduce_only: bool = False,
+                            builder_code: str = "",
+                            take_profit_price: str = "",
+                            stop_loss_price: str = "",
+                            trigger_price_type: str = "mark_price") -> dict:
+        """시장가 주문. side는 'bid'(매수) 또는 'ask'(매도).
+
+        take_profit_price / stop_loss_price 를 넘기면 거래소에 TP/SL을 함께
+        등록한다 — 봇/PC가 꺼져도 거래소가 해당 가격에서 포지션을 청산한다.
+
+        builder_code가 계정에서 미승인 상태라 거부되면, 사용자를 막지 않도록
+        코드 없이 1회 재시도한다 (승인된 계정에서만 수수료가 붙는 구조).
+
+        하드 가드: 신규 주문의 명목가가 MAX_ORDER_NOTIONAL_USD를 넘으면 거부.
+        (2026-07-24 BTC $355k 폭주 재발 방지 — 원인 불문 최후 차단)
+        """
+        # ── 폭주 방어: 신규 주문 명목가 상한 검사 (청산은 제외) ──
+        if not reduce_only:
+            try:
+                amt_f = abs(float(amount))
+                px = None
+                for p in self.get_prices():
+                    if p.get("symbol") == symbol:
+                        px = float(p.get("mark") or p.get("mid") or 0)
+                        break
+                if px and amt_f * px > self.MAX_ORDER_NOTIONAL_USD:
+                    raise PacificaError(
+                        f"🛑 주문 거부(하드 가드): {symbol} {amt_f} × ${px:,.0f} = "
+                        f"${amt_f*px:,.0f} > 상한 ${self.MAX_ORDER_NOTIONAL_USD:,.0f}. "
+                        f"폭주 방어. 의도된 대형 주문이면 MAX_ORDER_NOTIONAL_USD 조정.")
+            except PacificaError:
+                raise
+            except Exception:
+                pass   # 가격 조회 실패 시 가드 건너뜀(주문 자체는 진행, 별도 안전망 있음)
+        payload = {
+            "symbol": symbol,
+            "side": side,
+            "amount": str(amount),
+            "slippage_percent": str(slippage_percent),
+            "reduce_only": reduce_only,
+            "client_order_id": str(uuid.uuid4()),
+        }
+        if builder_code:
+            payload["builder_code"] = builder_code
+        if take_profit_price:
+            payload["take_profit"] = {"stop_price": str(take_profit_price),
+                                      "trigger_price_type": trigger_price_type}
+        if stop_loss_price:
+            payload["stop_loss"] = {"stop_price": str(stop_loss_price),
+                                    "trigger_price_type": trigger_price_type}
+        try:
+            return self._signed_post("orders/create_market",
+                                     "create_market_order", payload)
+        except PacificaError as e:
+            msg = str(e).lower()
+            if builder_code and ("builder" in msg or "fee_rate" in msg
+                                 or "max_fee" in msg):
+                payload.pop("builder_code", None)
+                payload["client_order_id"] = str(uuid.uuid4())
+                return self._signed_post("orders/create_market",
+                                         "create_market_order", payload)
+            raise
+
+    def _sign_action_data(self, op_type: str, payload: dict) -> dict:
+        """배치 액션 하나의 서명된 data 블록을 만든다 (개별 서명)."""
+        signed = sign_operation(op_type, payload, self.keypair)
+        data = {"account": self.address, **signed, **payload}
+        signer = str(self.keypair.pubkey())
+        if signer != self.address:
+            data["agent_wallet"] = signer
+        return data
+
+    def batch_market_orders(self, orders: list[dict],
+                            builder_code: str = "") -> dict:
+        """여러 시장가 주문을 원자적 배치(Atomics)로 전송 — 한 번에, 순서대로,
+        남의 주문에 끼이지 않고 실행. OI 헤지 양다리나 바스켓 진입에 최적.
+
+        orders: [{"symbol","side","amount","slippage_percent"?,"reduce_only"?}, ...]
+        최대 10개. 개별 서명되어 actions 배열로 묶인다.
+        """
+        if not self.keypair:
+            raise PacificaError("API 키가 없어 주문을 보낼 수 없습니다")
+        if not 1 <= len(orders) <= 10:
+            raise PacificaError("배치는 1~10개 주문만 가능합니다")
+        # 하드 가드 — 배치 내 각 신규 주문도 명목가 상한 검사 (청산 제외)
+        try:
+            px_map = {p.get("symbol"): float(p.get("mark") or p.get("mid") or 0)
+                      for p in self.get_prices()}
+            for o in orders:
+                if o.get("reduce_only"):
+                    continue
+                px = px_map.get(o["symbol"], 0)
+                notl = abs(float(o["amount"])) * px
+                if px and notl > self.MAX_ORDER_NOTIONAL_USD:
+                    raise PacificaError(
+                        f"🛑 배치 주문 거부(하드 가드): {o['symbol']} "
+                        f"${notl:,.0f} > 상한 ${self.MAX_ORDER_NOTIONAL_USD:,.0f}")
+        except PacificaError:
+            raise
+        except Exception:
+            pass
+        import time as _t
+        for attempt in (1, 2):
+            # 재시도 시 서명·주문ID 새로 (서명에 타임스탬프 포함)
+            actions = []
+            for o in orders:
+                payload = {
+                    "symbol": o["symbol"],
+                    "side": o["side"],
+                    "amount": str(o["amount"]),
+                    "slippage_percent": str(o.get("slippage_percent", "0.5")),
+                    "reduce_only": bool(o.get("reduce_only", False)),
+                    "client_order_id": str(uuid.uuid4()),
+                }
+                if builder_code:
+                    payload["builder_code"] = builder_code
+                actions.append({"type": "CreateMarket",
+                                "data": self._sign_action_data(
+                                    "create_market_order", payload)})
+            r = self.session.post(f"{self.base}/orders/batch",
+                                  json={"actions": actions}, timeout=20)
+            if r.status_code == 429 and attempt == 1:
+                _t.sleep(10)      # 레이트리밋 — 한 번만 쉬고 재서명·재시도
+                continue
+            body = self._parse_json(r, "POST /orders/batch")
+            # success 없으면 실패로 간주(안전) — 배치도 돈이 걸린 경로.
+            if r.status_code != 200 or not body.get("success", False):
+                # 빌더 코드 미승인이면 코드 없이 재시도
+                if builder_code and "builder" in r.text.lower():
+                    return self.batch_market_orders(orders, builder_code="")
+                raise PacificaError(f"배치 주문 실패 ({r.status_code}): {r.text}")
+            return body.get("data", body)
+        raise PacificaError("POST /orders/batch 레이트리밋 지속 (429)")
+
+    def set_position_tpsl(self, symbol: str, side: str,
+                          take_profit_price: str = "",
+                          stop_loss_price: str = "",
+                          trigger_price_type: str = "mark_price") -> dict:
+        """이미 열려 있는 포지션에 TP/SL을 사후 부착한다.
+
+        side는 '포지션의 방향'(bid=롱, ask=숏)을 넘긴다. 파시피카 TP/SL 주문은
+        포지션을 청산하는 방향(반대 side)을 요구하므로, 여기서 반대로 변환한다.
+        (호출자가 포지션 side를 넘겨도 안전하도록 함수가 책임진다. 포지션 ask →
+        스탑주문 bid. 이걸 안 뒤집으면 "Invalid stop order side" 422.)
+        TP/SL 중 최소 하나는 필요. 거래소에 등록되어 봇/PC 꺼져도 작동한다.
+        """
+        if not take_profit_price and not stop_loss_price:
+            raise PacificaError("TP/SL 중 최소 하나는 지정해야 합니다")
+        close_side = "ask" if side == "bid" else "bid"
+        payload = {"symbol": symbol, "side": close_side}
+        if take_profit_price:
+            payload["take_profit"] = {"stop_price": str(take_profit_price),
+                                      "trigger_price_type": trigger_price_type,
+                                      "client_order_id": str(uuid.uuid4())}
+        if stop_loss_price:
+            payload["stop_loss"] = {"stop_price": str(stop_loss_price),
+                                    "trigger_price_type": trigger_price_type,
+                                    "client_order_id": str(uuid.uuid4())}
+        return self._signed_post("positions/tpsl", "set_position_tpsl", payload)
+
+    # ---------- Print (⚠️ 비공개 API — 웹앱과 동일 경로, 예고 없이 바뀔 수 있음) ----------
+    # Print의 내부 이름은 'game'. 목표가(strike)에 걸어두고 기다리는 동안
+    # 프리미엄(이자)을 받는 옵션형 상품. 24시간 체크포인트에 체결 판정.
+
+    # ---------- 계정 설정 (마켓별) ----------
+
+    def get_account_settings(self) -> list[dict]:
+        """마켓별 레버리지·마진모드 설정. 봇의 정책 상한과 별개로, 거래소 쪽
+        설정이 낮으면 그쪽이 실제 상한이 된다."""
+        return self._get("account/settings", {"account": self.address})
+
+    def update_leverage(self, symbol: str, leverage: int) -> dict:
+        """마켓 레버리지 변경 (서명: update_leverage).
+        정책의 max_leverage 를 올려도 여기가 낮으면 주문이 그 값으로 제한된다."""
+        return self._signed_post("account/leverage", "update_leverage",
+                                 {"symbol": symbol, "leverage": int(leverage)})
+
+    def update_margin_mode(self, symbol: str, is_isolated: bool) -> dict:
+        """마진 모드 변경 (서명: update_margin_mode).
+        격리는 포지션마다 증거금을 격벽으로 나눠, 한 포지션 사고가 계좌 전체로
+        번지는 것을 막는다. 열린 포지션이 있으면 거부될 수 있다."""
+        return self._signed_post("account/margin", "update_margin_mode",
+                                 {"symbol": symbol, "is_isolated": bool(is_isolated)})
+
+    def print_games(self) -> list[dict]:
+        """Print 마켓 목록 (예: BTC_24H, ETH_24H)과 예치 한도."""
+        return self._get("game/config").get("configs", [])
+
+    def print_sim(self, game: str, deposit_usd: str, direction: int,
+                  strike_price: str, leverage: str) -> dict:
+        """Print 주문 시뮬레이션 — 프리미엄(수익), 내재변동성, 청산가 견적.
+        direction: 0=롱(아래 목표가에 매수 대기), 1=숏(위 목표가에 매도 대기)."""
+        return self._get("game/sim", {
+            "game": game, "deposit_amount": str(deposit_usd),
+            "direction": int(direction), "strike_price": str(strike_price),
+            "leverage": str(leverage)})
+
+    def print_positions(self) -> dict:
+        """내 Print 예치 현황."""
+        return self._get("game/accounts", {"account": self.address})
+
+    def print_open(self, game: str, deposit_usd: str, direction: int,
+                   strike_price: str, leverage: str) -> dict:
+        """Print 주문 (서명: deposit_to_game). 웹 UI와 동일한 요청."""
+        return self._signed_post("game/deposit", "deposit_to_game", {
+            "game": game, "deposit_amount": str(deposit_usd),
+            "direction": int(direction), "strike_price": str(strike_price),
+            "leverage": str(leverage)})
+
+    def print_end(self, game_account: str) -> dict:
+        """Print 조기 종료 (서명: end_game).
+
+        서버가 요구하는 필드는 마켓 이름(game)이 아니라 예치 계정 주소
+        (game_account)다. 예전 코드는 {"game": ...}를 보내 항상 400으로
+        실패했다 — 즉 조기 종료가 한 번도 동작한 적이 없다.
+        주소는 print_positions()의 game_accounts[].address 값이다."""
+        return self._signed_post("game/end", "end_game",
+                                 {"game_account": game_account})
+
+    def print_withdraw(self, game_account: str, amount: str = "") -> dict:
+        """Print 예치금 회수 (서명: withdraw_from_game). game_end와 같은 이유로
+        마켓 이름이 아니라 예치 계정 주소를 보낸다."""
+        payload = {"game_account": game_account}
+        if amount:
+            payload["amount"] = str(amount)
+        return self._signed_post("game/withdraw", "withdraw_from_game", payload)