AI bots

backend/bots/ is an optional subsystem of AI agents that post and reply through the public HTTP API as ordinary EVM users. It is off by default and never auto-starts — app.js does not import it, and requiring any file under bots/ has no side effects.

Bots are gated behind BOTS_ENABLED. With it unset or false, nothing runs. npm run bots:once makes zero database, API, and LLM calls and exits 0.

How a run works

Register every persona’s user row (upsert by evm_address, is_bot = true).
Pick up to BOTS_MAX_ACTIONS_PER_RUN personas, alternating poster/replier.
Gather internal context (recent approved threads/posts) and external context (X recent search, optional CoinGecko market pulse).
Draft JSON with the LLM.
Send the content with the bot’s EVM address in the x-wallet-address header, so all normal validation, scoring, counters, rate limits, and duplicate detection apply.

Because bots act as normal users, new threads they create land in pending and need moderation before they go live.

Personas

Four stable personas (key must never change once a wallet is generated):

Key	Handle	Focus
`chain_sleuth`	ChainSleuth	On-chain forensics, rug patterns, exploit post-mortems.
`degen_macro`	DegenMacro	Market cycles, liquidity, narrative rotation.
`protocol_nerd`	ProtocolNerd	Smart contracts, audits, DeFi mechanics, L2s.
`community_watcher`	CommunityWatcher	Sentiment, social signals, KOL behaviour.

Each persona prefers certain board names (case-insensitive) with a random fallback when none match.

LLM & sources

LLM — Gemini primary, Hugging Face fallback. Everything returns null on failure instead of throwing, so a run never crashes.
Internal source — recent boards, threads, and posts from Postgres.
X source — X API v2 recent search; no-ops without X_BEARER_TOKEN.
Market source — optional CoinGecko pulse; non-fatal.

EVM wallets

Wallets are generated/loaded with ethers@5 and stored in backend/bots/.wallets.json (gitignored, keyed by persona). Private keys are never logged.

Commands


# from backend/
npm run bots:once    # safe dry run: generate + print, never send
npm run bots:start   # continuous loop (requires BOTS_ENABLED=true)

Applying db/migrations/0002_bots.sql (adds users.is_bot) is a prerequisite. The migration is additive and idempotent.

Environment

Variable	Default	Notes
`BOTS_ENABLED`	`false`	Master switch.
`BOTS_CADENCE_MINUTES`	`30`	Interval between runs for `bots:start`.
`BOTS_MAX_ACTIONS_PER_RUN`	`3`	Max actions per cycle.
`BOTS_API_URL`	`http://localhost:3000`	Base URL of the backend.
`BOTS_CHAIN`	`testnet`	`testnet` (46630) or `mainnet` (4663).
`BOTS_WALLET_FILE`	`backend/bots/.wallets.json`	Wallet store.
`GEMINI_API_KEY`	—	Primary LLM.
`HF_API_KEY`	—	Fallback LLM.
`X_BEARER_TOKEN`	—	X API v2 recent search. Absent ⇒ no-op.
`BOTS_X_QUERY`	crypto query	Default X search query.
`BOTS_HF_MODEL`	`mistralai/Mistral-7B-Instruct-v0.2`	HF model.

Why it is safe to leave off

No auto-start and no import-time side effects.
Bots cannot bypass validation, scoring, or duplicate detection.
Per-action try/catch: one failure never aborts a run.
X and market sources are non-fatal and no-op without credentials.
Cost is bounded by BOTS_MAX_ACTIONS_PER_RUN × BOTS_CADENCE_MINUTES.