balchemy

v0.3.11

Published

17 days ago

Scaffold and run a local Balchemy MCP agent client

0High
0Medium
0Low

balchemy

balchemy ai-agent crypto trading mcp solana cli

What Balchemy Does

Balchemy connects an external LLM to on-chain markets through MCP. The outer LLM chooses tools and instructions. Balchemy applies scopes, behavior rules, risk checks, execution, and records.

The inner LLM is infrastructure support. It fetches data and formats responses. It does not make trading decisions.

Strategy -> external LLM -> Balchemy MCP -> policy -> approved action -> record
                                  |
                                  v
                         inner LLM support

Quick Start

npx balchemy

This source tree is prepared for [email protected]. npm publish, public mirror sync, and live package installation proof are separate release steps; this README does not claim that 0.3.11 has already been published.

0.3.11 pairs with @balchemyai/[email protected] to recover the incomplete SDK root export surface shipped in 0.3.10.

The wizard handles five local steps:

Choose an LLM provider.
Add the provider API key.
Connect a new or existing Balchemy MCP principal.
Review the files the CLI will write.
Start or export the local agent client.

New walletless agents are provisioned first. Root/recovery wallet binding happens later in the setup chat through the authenticated MCP setup flow; until then the agent should be treated as unbound and shadow/approval-gated.

Commands

npx balchemy              # Setup wizard or resume cached agent
npx balchemy init         # New setup wizard
npx balchemy start        # Start from agent.config.yaml
npx balchemy list         # List saved agents
npx balchemy control status # Show backend runtime mode
npx balchemy control pause  # Pause backend autonomy
npx balchemy control resume # Resume unarmed backend autonomy
npx balchemy control arm    # Arm live autonomous execution
npx balchemy control disarm # Return live runtime to unarmed mode
npx balchemy docker       # Generate Docker files
npx balchemy --help       # Usage
npx balchemy --version    # Version
npx balchemy --no-color   # Disable color output

NO_COLOR=1 also disables colored output.

Files Written

The CLI writes local runtime files in the current directory.

# agent.config.yaml
llm:
  provider: anthropic
  model: selected-in-wizard

agent:
  name: my-trading-agent
  strategy: Focus on liquid markets. Keep position size below 5%.

wallets:
  solana:
    chain: solana
  evm:
    chainId: 8453

Secrets belong in .env. Do not commit that file.

What You Can Do

Trade

Send trade instructions through the curated MCP surface when the backend grants the right scope.
Keep execution behind Balchemy policy, replay/rate checks, and product approval rules.
Use the Hub/backend contract as the source of truth for available execution tools.

Research

Query token price, liquidity, volume, and holder distribution.
Check risk signals before a trade.
Track wallets and market events.
Compare positions across chains.

Manage

View portfolio, balances, positions, and PnL.
Define behavior rules in natural language.
Subscribe to market events.
Rotate scoped MCP keys in Hub.

Risk Model

Every trade path is expected to pass risk checks before execution:

RugCheck signals.
Honeypot simulation.
Contract and liquidity checks.
Behavior rule enforcement.
Scoped MCP permissions.

The wallet remains the authority. Keep private keys and seed phrases out of source, logs, screenshots, and prompts.

MCP Tools

The CLI uses the curated agent-facing MCP surface returned by tools/list. Availability depends on MCP key scope and backend policy.

Typical capabilities include chat through ask_bot, runtime status through agent_status, safe context through agent_context_snapshot, safe discovery through agent_market_brief, safe asset reports through agent_candidate_report / agent_risk_report, walletless setup through setup_agent, behavior-rule management, market-event subscriptions, runtime control through agent_control, and approved trade commands.

Raw/internal direct research, broad discovery, and portfolio snapshot tools stay hidden unless they are returned by tools/list for that bot.

The CLI does not run an automatic npm registry update check during launch and does not prompt for global installs. Use npm directly when you intentionally choose to update a package.

The CLI does not claim live-trade proof, Base live coverage, or source-owner payout rails. Runtime execution requires current tools/list exposure, scope, policy, approval, and a fresh backend live_armed state.

LLM Providers

| Provider | Environment variable | | --- | --- | | Anthropic | ANTHROPIC_API_KEY | | OpenAI | OPENAI_API_KEY | | Google Gemini | GEMINI_API_KEY | | xAI Grok | GROK_API_KEY | | OpenRouter | OPENROUTER_API_KEY |

Pick the model in the wizard or edit agent.config.yaml.

Runtime Mode

The SDK includes an AgentLoop for long-running agents.

import { AgentLoop } from "@balchemyai/agent-sdk";

const loop = new AgentLoop({
  mcpEndpoint: "https://api.balchemy.ai/mcp/YOUR_PUBLIC_ID",
  apiKey: "your-mcp-api-key",
  llmProvider: "openai",
  llmApiKey: process.env.OPENAI_API_KEY ?? "",
});

await loop.start();

Event flow:

Market event -> SSE -> external LLM evaluates -> MCP tool call -> policy/approval -> record

Hub

Agents registered through the CLI appear in Balchemy Hub.

Monitor portfolio, trade history, and event logs.
Create, rotate, and revoke MCP keys.
Keep read and trade scopes separate.
Link Solana and EVM wallets.

Security

Saved agent credentials are encrypted locally. Generated .env files remain plaintext local secret files and must not be committed.
MCP keys are scoped and revocable.
Behavior rules constrain execution.
Pre-trade checks run before approved execution.
Seed phrases should never be stored in source or logs.

TUI Shortcuts

| Shortcut | Action | | --- | --- | | ^S | Open settings | | ^L | Clear chat history | | ^N | New agent | | ^O | Export redacted activity transcript | | ^Q | Quit | | PgUp/PgDn | Scroll message history | | Esc | Go back |

Requirements

Node.js 18+
One supported LLM provider key

License

MIT