Metadata-Version: 2.4
Name: ocean-agent
Version: 0.3.4
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

**One command** — installs everything (uv, Python, dependencies) and registers
the server with Claude Desktop. It asks two questions: wallet address and agent
key.

```bash
# Windows (PowerShell)
powershell -ExecutionPolicy ByPass -c "irm https://oceanagent.vercel.app/install.ps1 | iex"

# macOS / Linux
sh -c "$(curl -LsSf https://oceanagent.vercel.app/install.sh)"
```

Or set up manually:

1. Install [uv](https://docs.astral.sh/uv/):

```bash
# Windows (PowerShell)
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh
```

2. 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.

3. Put it in `.env`:

```ini
ADDRESS=your_main_wallet_address
PACIFICA_API_KEY=your_agent_wallet_key
PACIFICA_BASE_URL=https://api.pacifica.fi
```

As written this trades **live on mainnet with real funds**. Remove the
`PACIFICA_BASE_URL` line to practice on testnet first (testnet uses separate
keys: `ADDRESS_TESTNET`, `PACIFICA_API_KEY_TESTNET`).

4. Point your MCP client at it:

```json
{
  "mcpServers": {
    "ocean-agent": {
      "command": "uvx",
      "args": ["ocean-agent@latest"],
      "env": { "PACIFICA_ENV_FILE": "/absolute/path/to/.env" }
    }
  }
}
```

Restart your AI client — the first launch downloads everything automatically.

5. Check your setup:

```bash
uv run --with ocean-agent python -m ocean_agent.doctor
```

Any `python -m ocean_agent...` command in this README runs the same way —
prepend `uv run --with ocean-agent`.

---

## 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
