Blackhole Agent CLI

Autonomous DeFi agent for the Blackhole DEX on Avalanche. Deploys a vault + registry, encrypts a local agent wallet, and runs AI-powered strategies via Claude and the Blackhole MCP server.

Installation

One-liner (requires Node.js 20+):

npm install -g @vinayblitz/blackhole-agent-cli

That's it. Now you have the bhAgent command available globally.

Install from source (no npm publish needed)

git clone <repo-url>
cd agent-cli
npm install
npm run build && npm link

bhAgent is now available globally. To unlink later: npm unlink -g @vinayblitz/blackhole-agent-cli

Don't have Node.js?

macOS:

curl -fsSL https://fnm.vercel.app/install | bash && fnm install 22 && npm install -g @vinayblitz/blackhole-agent-cli

Windows (PowerShell as Administrator):

winget install Schniz.fnm; fnm install 22; npm install -g @vinayblitz/blackhole-agent-cli

Linux:

curl -fsSL https://fnm.vercel.app/install | bash && fnm install 22 && npm install -g @vinayblitz/blackhole-agent-cli

Verify

bhAgent --version

Quick Start

bhAgent

First run walks you through setup. It will:

1. Generate an agent wallet and show you the seed phrase (save this!)
2. Ask if you want to be the vault owner (recommended)
3. Ask for your LLM provider and API key (Claude, ChatGPT, Gemini, or custom)
4. Wait for you to send AVAX to the agent address for gas
5. Deploy the vault + registry contracts on Avalanche Mainnet
6. Save everything encrypted to ~/.blackhole-agent/config.json

After setup, you unlock with your password and enter the interactive menu.

Commands

bhAgent                        Launch interactive menu (default)
bhAgent setup                  Run first-time setup
bhAgent strategies             List available strategies
bhAgent ls                     Alias for strategies
bhAgent status                 Show agent balances and addresses
bhAgent start <strategy>       Start a strategy (e.g. bhAgent start arb-bot)
bhAgent stop                   Clear active strategy
bhAgent config                 Show current configuration
bhAgent updatellmkey [key]     Update the stored LLM API key
bhAgent --help                 Show all commands
bhAgent --version              Show version

Examples

# See what strategies are available
bhAgent strategies

# Start the arbitrage bot
bhAgent start arb-bot

# Check balances and status
bhAgent status

# Stop the running strategy
bhAgent stop

Interactive Menu

Running bhAgent with no arguments opens the interactive menu:

Blackhole Agent CLI
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  Agent:      0xABCD...1234 (1.5 AVAX)
  Vault:      0xEFGH...5678 (10.0 AVAX)
  Network:    Avalanche Mainnet
  Strategy:   Running: cl-rebalancer

> Select Strategy
  View Status
  Stop Strategy
  Switch Strategy
  View Config
  Exit

Strategies

Strategies are markdown files with a system prompt for Claude and an interval: directive. The agent runs Claude in a loop, calling MCP tools to analyze markets and execute transactions through the vault.

Included Strategies

| Strategy | Interval | What it does | |---|---|---| | arb-bot | 30s | Finds price discrepancies across DEX routes, executes profitable swaps | | cl-rebalancer | 5m | Keeps concentrated liquidity positions in range for maximum emissions |

Writing Your Own Strategy

Create a .md file in the strategies folder:

# My Strategy

interval: 2m

You are an autonomous agent managing vault at {vaultAddress}.
Your goal is to...

## Rules
1. ...
2. ...

The interval: line controls how often Claude runs. Supports s (seconds) and m (minutes).

MCP Server

The agent connects to a Blackhole MCP server for on-chain operations (swaps, liquidity, yield queries, etc.).

• Local mode (default) -- the MCP server runs in-process inside the CLI. No separate setup needed.
• Remote mode -- connect to a hosted MCP server by providing the URL during setup.

The MCP server is published separately as blackhole-mcp-server if you want to host it yourself.

How It Works

You (vault owner)
  |
  |-- owns --> AgentVault (on-chain)
  |                |
  |                |-- executes trades via registered agent
  |                |-- only owner can withdraw funds
  |
  bhAgent (this CLI)
      |
      |-- encrypts agent private key locally (AES-256-GCM)
      |-- runs Claude in a loop with your chosen strategy
      |-- Claude calls MCP tools (quote, swap, add liquidity, etc.)
      |-- MCP returns transaction payloads
      |-- agent executes them through the vault contract

Security

• Private key is never stored in plaintext -- encrypted with AES-256-GCM, PBKDF2 (100k iterations, SHA-512)
• Config stored at ~/.blackhole-agent/ with restricted permissions (0700/0600)
• You (vault owner) control withdrawals -- the agent can only execute trades
• Agent must be registered in the on-chain AgentRegistry

Configuration

Stored at ~/.blackhole-agent/config.json:

{
  "network": "mainnet",
  "rpcUrl": "https://api.avax.network/ext/bc/C/rpc",
  "agentAddress": "0x...",
  "encryptedKey": { "iv": "...", "salt": "...", "encrypted": "...", "tag": "..." },
  "registryAddress": "0x...",
  "vaultAddress": "0x...",
  "ownerAddress": "0x...",
  "mcpUrl": "local",
  "activeStrategy": null
}

To reset and start over, delete this file and run bhAgent setup again.

Updating

npm update -g @vinayblitz/blackhole-agent-cli

Uninstalling

npm uninstall -g @vinayblitz/blackhole-agent-cli

Requirements

• Node.js 20+
• AVAX for gas (~0.5 for deployment, small amounts for ongoing trades)
• LLM API key for one of: Claude, OpenAI, Google Gemini, or a compatible custom endpoint
• (Optional) Local Ollama instance if using Ollama provider

Development (local MCP server changes)

When working on the MCP server locally, use a file: reference so changes take effect immediately without publishing:

# In agent-cli/package.json, change the dependency:
"blackhole-mcp-server": "file:../mcp-server"

# Then reinstall and rebuild
cd mcp-server && npm run build
cd ../agent-cli && rm -rf node_modules/blackhole-mcp-server && npm install && npm run build

Before publishing, switch back to the npm registry reference:

"blackhole-mcp-server": "npm:@vinayblitz/blackhole-mcp-server@^1.0.x"

Publishing (maintainers)

# 1. Switch agent-cli dep back to npm registry (if using file: locally)
#    "blackhole-mcp-server": "npm:@vinayblitz/blackhole-mcp-server@^1.0.x"

# 2. Publish MCP server first (agent-cli depends on it)
cd mcp-server && npm run publish:npm

# 3. Update the version in agent-cli package.json to match
# 4. Then publish agent CLI
cd agent-cli && npm run publish:npm