PacificaPilot Documentation

Installation

PacificaPilot is a Python package. Requires Python 3.11+.

bash

# Recommended — isolated with pipx
pipx install pacificapilot

# Or plain pip
pip install pacificapilot

# For development
git clone https://github.com/pacificapilot/pacificapilot
cd pacificapilot
pip install -e ".[dev,telegram,memory]"

Quick Start

Run the setup wizard once, then launch the TUI.

bash

# First-run wizard
pacifica init
#  → Pacifica keys (public + private Solana keypair)
#  → AI provider (OpenRouter recommended for free tier)
#  → Trading config (symbols, position size, confidence)
#  → Supermemory (local, cloud, or skip)

# Launch the TUI
pacifica start

Inside the REPL you can type natural language or slash commands.

Configuration

Config lives at ~/.pacificapilot/config.toml. Secrets live at ~/.pacificapilot/secrets.env with chmod 600. Edit directly or use the CLI.

bash

pacifica config set pacifica.api_key <key>
pacifica config set pacifica.api_secret <secret>
pacifica config set risk.max_position_usd 500
pacifica config set trading.symbols "BTC,ETH,SOL"
pacifica config set trading.dry_run true

AI Providers (BYOK)

Configure at least one provider. Swap at runtime with /apikey or /model.

bash

pacifica config set anthropic.api_key sk-ant-...
pacifica config set openai.api_key sk-...
pacifica config set google.api_key ...
pacifica config set openrouter.api_key ...

Use Claude for reasoning, GPT for speed, Gemini for the free tier — no lock-in.

Memory (Supermemory)

Memory is powered by Supermemory. Two deployment modes with the same SDK:

bash

# Cloud mode — get a key from app.supermemory.ai
pacifica config set supermemory.api_key sm_...
pacifica config set supermemory.mode cloud

# Local mode — zero data leaves your machine
npm i -g supermemory
npx supermemory local            # runs on localhost:6767
pacifica config set supermemory.mode local

Five container tags: decisions, patterns, preferences, performance, errors. Three operations: memory.add(), memory.recall(), memory.context().

Agents

Chat Agent

Claude Code-style multi-turn tool loop. Runs up to 8 iterations per turn (configurable) before returning a final response.

Loop Agent

Autonomous 24/7 monitoring on a configurable timer. Fetches live data, makes AI-driven trading decisions, and writes every decision + pattern to Supermemory automatically.

bash

/start      # boot the autonomous Loop Agent
/pause      # soft-pause
/resume     # resume
/stop       # stop entirely

Trading Tools

place_order	Open LONG/SHORT positions (with confirmation)
close_position	Close a specific position
close_all_positions	Flatten the entire book
get_positions	Open positions with unrealized PnL
get_account_balance	USDC balance, equity, available capital
get_market_price	Price + RSI + MACD + Bollinger + volume + funding + regime
get_trade_history	Past trades with PnL and duration
get_performance_metrics	Win rate, Sharpe, profit factor, drawdown
get_market_regime	Trending/ranging/volatile detection with guidance

Slash Commands

/help	Show all commands
/start	Boot the autonomous Loop Agent
/stop	Stop the Loop Agent
/pause	Soft-pause the loop
/resume	Resume the loop
/status	System status snapshot
/config	View or edit config
/apikey	Manage AI provider and Supermemory keys
/mode	Switch testnet / mainnet
/model <name>	Switch AI provider
/memory	Inspect stored memories
/positions	Open positions and PnL
/orders	Open orders
/risk	View or adjust risk parameters
/clear	Clear chat context
/quit	Exit

Risk & Security

Non-custodial, BYOK, human-in-the-loop. Dry-run and testnet by default.

toml

[risk]
max_position_usd = 500
max_leverage = 3
daily_loss_limit_usd = 100
require_confirmation = true

[trading]
dry_run = true
network = "testnet"

Keys on your machine, nowhere else.
Every trade action requires explicit yes/no.
Dry-run mode simulates all trades.
Testnet-first onboarding — no real money at risk.
Secrets file at ~/.pacificapilot/secrets.env with chmod 600.

The TUI

Built with Textual. Fixed 3-panel layout:

Header — mode (testnet/mainnet), dry-run status, provider, live BTC/ETH prices.
Chat Panel — conversation with the AI agent and command output.
Sidebar — live status: agent state, positions, account, decisions, memory.
Input Bar — natural language or /commands with fuzzy autocomplete.

Keyboard: Ctrl+P palette, Ctrl+M provider switch.