ocean-agent 0.3.0__tar.gz

ocean_agent-0.3.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 mustache-mcp / Ocean Agent contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

ocean_agent-0.3.0/PKG-INFO

@@ -0,0 +1,202 @@
+Metadata-Version: 2.4
+Name: ocean-agent
+Version: 0.3.0
+Summary: Pacifica trading MCP server — measured-edge setups, exchange-native brackets, funding carry, and a policy-governed autonomous trading entity
+License: MIT
+Keywords: mcp,pacifica,trading,funding-rate,delta-neutral,solana
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests>=2.31.0
+Requires-Dist: solders>=0.19.0
+Requires-Dist: base58>=2.1.1
+Requires-Dist: PyYAML>=6.0
+Requires-Dist: python-dotenv>=1.0.0
+Requires-Dist: mcp<2,>=1.0
+Dynamic: license-file
+
+# ocean-agent
+
+> English · [한국어](README.ko.md)
+
+**Tell your AI to trade.** An MCP server for [Pacifica](https://app.pacifica.fi)
+that turns natural language into correct, risk-sized perpetual futures orders —
+plus a 24/7 autonomous trading entity governed by a policy file you control.
+
+```bash
+uvx ocean-agent        # no install needed
+```
+
+> ⚠️ This places real orders with real money. Read the
+> [disclaimer](DISCLAIMER.md) before connecting an account.
+
+Built entirely on Pacifica. Calls the Pacifica REST API directly with the same
+Ed25519 agent-key signing the official tooling uses — no npm dependency.
+
+---
+
+## Why this instead of raw API access
+
+The official Pacifica MCP exposes the API as-is: your AI must compute exact
+prices and sizes itself, and a price that isn't a multiple of the market's tick
+size is rejected by the exchange. ocean-agent adds the layer above that:
+
+| | Raw API / official MCP | ocean-agent |
+|---|---|---|
+| Order prices | AI computes exact values | Say *"3% stop"* — tick/lot/min-order corrected automatically |
+| Position sizing | Manual | Risk-based (fixed % of capital at risk per trade) |
+| Safety | None | Two-step confirm gate on every money-moving tool |
+| Statistics | None | Measured win rates and expected value, not textbook theory |
+
+---
+
+## MCP tools
+
+**Market & analysis**
+- `analyze_chart` — multi-timeframe indicator snapshot with *measured* hit rates
+  per signal on that specific coin and timeframe. Says "no edge detected" when
+  there isn't one.
+- `top_setups` — live ranking of statistically-proven setups (EV × win rate ×
+  sample confidence), with entry, stop, target and leverage
+- `market_context` — Fear & Greed regime read
+- `scan_funding` — every market ranked by funding APR
+- `learned_winrates` / `learned_combos` — win-rate database built from live
+  observation, including multi-signal combinations
+- `review_predictions` — past calls graded against what actually happened
+
+**Trading**
+- `open_with_bracket` — entry plus exchange-native TP/SL in one call. The stops
+  live on the exchange, so they fire even with your machine off.
+- `protect_position` — retrofit native TP/SL onto any open position
+- `open_funding_position` / `close_funding_position` — delta-neutral funding
+  carry (spot buy + perp short) executed atomically as a batch
+- `plan_oi_hedge` — sizes an OI-farming position with its cross-exchange hedge,
+  fee and funding math included
+- `open_pacifica_leg`, `check_position`, `account_status`
+
+**Print** (experimental — uses an endpoint Pacifica has not documented; may
+change without notice)
+- `print_quote` — live premium, implied volatility and liquidation price
+- `print_order` / `print_status` / `print_close`
+- `evaluate_print` — statistical verdict on whether a Print offer is worth it:
+  fill probability, average overshoot, and the breakeven APY that would
+  compensate for it
+
+---
+
+## Autonomous trading entity
+
+A self-directed trader governed by `policy.yaml` — a delegation contract. It
+cannot act outside those bounds.
+
+This is a **separate always-on process**, not an MCP tool. An MCP server only
+runs when your AI client calls it; a trader that must hold positions and manage
+stops around the clock needs its own process. Start it deliberately, and it
+keeps running whether or not any AI is connected.
+
+```bash
+python -m ocean_agent.autonomous --init    # create policy.yaml to edit
+python -m ocean_agent.autonomous --dry     # decide, but place no orders
+python -m ocean_agent.autonomous           # run continuously
+python -m ocean_agent.autonomous --once    # single cycle
+python -m ocean_agent.autonomous --report  # performance summary
+```
+
+Read `policy.yaml` before the first real run — capital, leverage cap, risk per
+trade and the hard-stop threshold all live there. Start with `--dry` on testnet.
+
+Each cycle it reads the market, grades what it learned, manages open positions,
+and enters only setups that clear every gate.
+
+**Portfolio buckets** — capital split across directional trading, funding carry
+and a cash reserve, rebalanced every cycle.
+
+**Position aftercare** — moves the stop to breakeven once a trade is ahead,
+trails it as profit grows, and takes partial profit at target. Stops only ever
+move in your favour.
+
+**Liquidity gate** — skips markets where your own order would be a large share
+of daily volume. Thin books are the real hazard: an order that only partly
+fills, and a stop that cannot be executed at its price.
+
+**Net-exposure limit** — caps how one-directional the book can get, so a single
+market reversal cannot hit every position at once.
+
+**Self-remeasurement** — this is the actual learning engine. On a schedule the
+bot re-measures the full matrix of coins × timeframes × signals and updates
+which timeframes it trades and which signals it trusts. Regimes change: in one
+measurement the 8h timeframe showed no edge at all; weeks later it was the
+best-performing band. Fixed parameters go stale, so they are not fixed.
+
+```bash
+python -m ocean_agent.rematrix          # remeasure now
+python -m ocean_agent.rematrix --show   # what it currently believes
+```
+
+**Adaptation** — signals that lose in live grading are suspended, size is cut
+during drawdown and restored on recovery. Parameters adapt within policy bounds;
+the bot never rewrites its own code.
+
+**Final stop** — a single hard halt at catastrophic loss. Otherwise it does not
+stop, it adapts.
+
+---
+
+## Setup
+
+Requires Python 3.10+.
+
+1. Create an **agent wallet key** at [app.pacifica.fi/apikey](https://app.pacifica.fi/apikey).
+   API keys can trade but **cannot withdraw funds**, and you can revoke them
+   at any time.
+
+2. Put it in `.env`:
+
+```ini
+ADDRESS=your_main_wallet_address
+PACIFICA_API_KEY=your_agent_wallet_key
+
+# optional — testnet uses separate keys
+ADDRESS_TESTNET=...
+PACIFICA_API_KEY_TESTNET=...
+```
+
+3. Point your MCP client at it:
+
+```json
+{
+  "mcpServers": {
+    "ocean-agent": {
+      "command": "uvx",
+      "args": ["ocean-agent"],
+      "env": { "PACIFICA_ENV_FILE": "/absolute/path/to/.env" }
+    }
+  }
+}
+```
+
+Defaults to testnet. Set `PACIFICA_BASE_URL=https://api.pacifica.fi` for live
+trading.
+
+Check your setup with `python -m ocean_agent.doctor`.
+
+---
+
+## Safety
+
+- API keys are trading-only — this software cannot move your funds out
+- Every order tool previews first and executes only on explicit confirmation
+- Testnet and mainnet keys are kept separate
+- The autonomous entity acts only within `policy.yaml`
+
+## Risk
+
+This is trading software. Leveraged perpetual futures can lose more than the
+margin you post. Measured win rates come from historical data and are
+regime-dependent — an edge that held for months can vanish when the market
+changes character. Nothing here is financial advice. Run it on testnet until
+you understand exactly what it does, and only risk what you can afford to lose.
+
+## License
+
+MIT

ocean_agent-0.3.0/README.md

@@ -0,0 +1,185 @@
+# ocean-agent
+
+> English · [한국어](README.ko.md)
+
+**Tell your AI to trade.** An MCP server for [Pacifica](https://app.pacifica.fi)
+that turns natural language into correct, risk-sized perpetual futures orders —
+plus a 24/7 autonomous trading entity governed by a policy file you control.
+
+```bash
+uvx ocean-agent        # no install needed
+```
+
+> ⚠️ This places real orders with real money. Read the
+> [disclaimer](DISCLAIMER.md) before connecting an account.
+
+Built entirely on Pacifica. Calls the Pacifica REST API directly with the same
+Ed25519 agent-key signing the official tooling uses — no npm dependency.
+
+---
+
+## Why this instead of raw API access
+
+The official Pacifica MCP exposes the API as-is: your AI must compute exact
+prices and sizes itself, and a price that isn't a multiple of the market's tick
+size is rejected by the exchange. ocean-agent adds the layer above that:
+
+| | Raw API / official MCP | ocean-agent |
+|---|---|---|
+| Order prices | AI computes exact values | Say *"3% stop"* — tick/lot/min-order corrected automatically |
+| Position sizing | Manual | Risk-based (fixed % of capital at risk per trade) |
+| Safety | None | Two-step confirm gate on every money-moving tool |
+| Statistics | None | Measured win rates and expected value, not textbook theory |
+
+---
+
+## MCP tools
+
+**Market & analysis**
+- `analyze_chart` — multi-timeframe indicator snapshot with *measured* hit rates
+  per signal on that specific coin and timeframe. Says "no edge detected" when
+  there isn't one.
+- `top_setups` — live ranking of statistically-proven setups (EV × win rate ×
+  sample confidence), with entry, stop, target and leverage
+- `market_context` — Fear & Greed regime read
+- `scan_funding` — every market ranked by funding APR
+- `learned_winrates` / `learned_combos` — win-rate database built from live
+  observation, including multi-signal combinations
+- `review_predictions` — past calls graded against what actually happened
+
+**Trading**
+- `open_with_bracket` — entry plus exchange-native TP/SL in one call. The stops
+  live on the exchange, so they fire even with your machine off.
+- `protect_position` — retrofit native TP/SL onto any open position
+- `open_funding_position` / `close_funding_position` — delta-neutral funding
+  carry (spot buy + perp short) executed atomically as a batch
+- `plan_oi_hedge` — sizes an OI-farming position with its cross-exchange hedge,
+  fee and funding math included
+- `open_pacifica_leg`, `check_position`, `account_status`
+
+**Print** (experimental — uses an endpoint Pacifica has not documented; may
+change without notice)
+- `print_quote` — live premium, implied volatility and liquidation price
+- `print_order` / `print_status` / `print_close`
+- `evaluate_print` — statistical verdict on whether a Print offer is worth it:
+  fill probability, average overshoot, and the breakeven APY that would
+  compensate for it
+
+---
+
+## Autonomous trading entity
+
+A self-directed trader governed by `policy.yaml` — a delegation contract. It
+cannot act outside those bounds.
+
+This is a **separate always-on process**, not an MCP tool. An MCP server only
+runs when your AI client calls it; a trader that must hold positions and manage
+stops around the clock needs its own process. Start it deliberately, and it
+keeps running whether or not any AI is connected.
+
+```bash
+python -m ocean_agent.autonomous --init    # create policy.yaml to edit
+python -m ocean_agent.autonomous --dry     # decide, but place no orders
+python -m ocean_agent.autonomous           # run continuously
+python -m ocean_agent.autonomous --once    # single cycle
+python -m ocean_agent.autonomous --report  # performance summary
+```
+
+Read `policy.yaml` before the first real run — capital, leverage cap, risk per
+trade and the hard-stop threshold all live there. Start with `--dry` on testnet.
+
+Each cycle it reads the market, grades what it learned, manages open positions,
+and enters only setups that clear every gate.
+
+**Portfolio buckets** — capital split across directional trading, funding carry
+and a cash reserve, rebalanced every cycle.
+
+**Position aftercare** — moves the stop to breakeven once a trade is ahead,
+trails it as profit grows, and takes partial profit at target. Stops only ever
+move in your favour.
+
+**Liquidity gate** — skips markets where your own order would be a large share
+of daily volume. Thin books are the real hazard: an order that only partly
+fills, and a stop that cannot be executed at its price.
+
+**Net-exposure limit** — caps how one-directional the book can get, so a single
+market reversal cannot hit every position at once.
+
+**Self-remeasurement** — this is the actual learning engine. On a schedule the
+bot re-measures the full matrix of coins × timeframes × signals and updates
+which timeframes it trades and which signals it trusts. Regimes change: in one
+measurement the 8h timeframe showed no edge at all; weeks later it was the
+best-performing band. Fixed parameters go stale, so they are not fixed.
+
+```bash
+python -m ocean_agent.rematrix          # remeasure now
+python -m ocean_agent.rematrix --show   # what it currently believes
+```
+
+**Adaptation** — signals that lose in live grading are suspended, size is cut
+during drawdown and restored on recovery. Parameters adapt within policy bounds;
+the bot never rewrites its own code.
+
+**Final stop** — a single hard halt at catastrophic loss. Otherwise it does not
+stop, it adapts.
+
+---
+
+## Setup
+
+Requires Python 3.10+.
+
+1. Create an **agent wallet key** at [app.pacifica.fi/apikey](https://app.pacifica.fi/apikey).
+   API keys can trade but **cannot withdraw funds**, and you can revoke them
+   at any time.
+
+2. Put it in `.env`:
+
+```ini
+ADDRESS=your_main_wallet_address
+PACIFICA_API_KEY=your_agent_wallet_key
+
+# optional — testnet uses separate keys
+ADDRESS_TESTNET=...
+PACIFICA_API_KEY_TESTNET=...
+```
+
+3. Point your MCP client at it:
+
+```json
+{
+  "mcpServers": {
+    "ocean-agent": {
+      "command": "uvx",
+      "args": ["ocean-agent"],
+      "env": { "PACIFICA_ENV_FILE": "/absolute/path/to/.env" }
+    }
+  }
+}
+```
+
+Defaults to testnet. Set `PACIFICA_BASE_URL=https://api.pacifica.fi` for live
+trading.
+
+Check your setup with `python -m ocean_agent.doctor`.
+
+---
+
+## Safety
+
+- API keys are trading-only — this software cannot move your funds out
+- Every order tool previews first and executes only on explicit confirmation
+- Testnet and mainnet keys are kept separate
+- The autonomous entity acts only within `policy.yaml`
+
+## Risk
+
+This is trading software. Leveraged perpetual futures can lose more than the
+margin you post. Measured win rates come from historical data and are
+regime-dependent — an edge that held for months can vanish when the market
+changes character. Nothing here is financial advice. Run it on testnet until
+you understand exactly what it does, and only risk what you can afford to lose.
+
+## License
+
+MIT

ocean_agent-0.3.0/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", "")