ocean-agent

English · 한국어

🌊 Website: oceanagent.vercel.app · PyPI: ocean-agent

Tell your AI to trade. An MCP server for Pacifica 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.

uvx ocean-agent        # no install needed

⚠️ This places real orders with real money. Read the disclaimer 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.

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.

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.

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.

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

# 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. API keys can trade but cannot withdraw funds, and you can revoke them at any time.

3. Put it in .env:

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. Start with --dry, which decides but places no orders. A testnet endpoint is also available if you prefer to rehearse there: remove the PACIFICA_BASE_URL line (testnet uses separate keys: ADDRESS_TESTNET, PACIFICA_API_KEY_TESTNET).

4. Point your MCP client at it:

{
  "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:

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 with --dry until you understand exactly what it does, and only risk what you can afford to lose.

License

MIT