pumpfun-bonkfun-bot CLAUDE.md

Agent guide

Solana trading bot for pump.fun and letsbonk.fun. Snipes newly created tokens and exits on a configured strategy. See README.md for setup and configuration; this file covers what an agent needs that the code doesn't make obvious.

AGENTS.md is a symlink to this file, so Claude Code, Codex, Cursor, and Windsurf all read the same guide.

Ground rules

• Never run a bot with real funds to test a change. Use learning-examples/, or the simulation scripts below, which move no funds.
• Never touch .env or print its contents. SOLANA_PRIVATE_KEY is a live key.
• Don't commit anything from logs/.
• Test with a learning example before touching src/.

Layout

src/            bot source — this dir is the import root (see below)
learning-examples/   standalone scripts; each runs on its own, no bot config
bots/           one YAML per bot instance
idl/            vendored Anchor IDLs
logs/           {bot_name}_{timestamp}.log

Imports are rooted at src/, not at the repo. uv pip install -e . puts src/ itself on sys.path, so it is from core.client import SolanaClient and from utils.logger import get_logger — not from src.core.... Learning examples are deliberately self-contained: they import siblings like pump_v2 and tx_status as top-level modules and mostly don't import from src at all. Don't "fix" an example by rewiring it to import the bot.

Dependency layers, low to high — don't introduce an upward import:

interfaces → utils → core → platforms → monitoring → trading → bot_runner

interfaces is the leaf — it imports nothing internal, and utils/idl_manager.py imports interfaces.core. geyser holds only generated stubs and likewise imports nothing internal; cleanup sits on core/utils and is pulled in by trading.

Platform differences are resolved through interfaces/core.py abstractions (AddressProvider, curve manager, event parser, instruction builder) and a registry in platforms/__init__.py. Listeners and the trader are platform-agnostic (Universal*); anything platform-shaped belongs under platforms/<name>/.