Documentation

merrymen is a self-hosted band of autonomous trading agents for Robinhood Chain. Everything runs on your machine; your keys never leave it. This guide takes you from install to a named agent you chat with on Telegram.

Install

Requires Node 22.12+. No Node yet? The one-line installer sets it up and puts merrymen on your PATH.

# Windows (PowerShell)
irm https://raw.githubusercontent.com/millw14/merrymen/main/install.ps1 | iex

# macOS / Linux
curl -fsSL https://raw.githubusercontent.com/millw14/merrymen/main/install.sh | bash

Already have Node?

npm install -g merrymen
merrymen setup      # checks node / npm / PATH, prints exact fixes
merrymen start      # dashboard at localhost:3100 + the worker

All your data lives in ~/.merrymen (settings, grant, ledger, your strategies, your agent's soul). The install is disposable — upgrades never touch your data. The dashboard binds to localhost only; to reach it from your phone on a trusted network, start with MERRYMEN_HOST=0.0.0.0 merrymen start.

Create & fund a wallet

Open localhost:3100/grant. There is nothing to connect — merrymen generates a fresh account, shows you the owner key to back up, and lets you fund it. Pick your ground:

The caps you set — per-trade, daily, ops/day, drawdown breaker, key expiry — are enforced by the account contract on every operation. The worker can tighten within them but never widen them without a new signed grant.

Run it

merrymen start      # dashboard (localhost:3100) + the 24/7 worker
merrymen doctor     # node / keys / RPC / bundler / grant / db checks
merrymen status     # heartbeat, grant, trades, equity
merrymen selftest   # one policy-legal no-op through the full pipeline
merrymen kill       # kill switch — destroys the grant

Each tick the worker runs: grant sync → market safety → strategy proposes → policy check → quote simulation → execute → record. It re-reads your settings every tick, so dashboard changes apply within one tick — no restart.

Set up Telegram

1. Message @BotFather → /newbot → copy the token.
2. Dashboard → Settings → Telegram → paste the token, hit test connection (it shows your @botname), enable.
3. Message your bot /link <code> — the one-time code is shown in settings. You become the owner; only allowlisted chats are obeyed.

There's a Chat on Telegram button on the dashboard too. Commands work bare; with an Anthropic key set, plain English works — “how are we doing?”, “pause everything”, “why did you buy that?”.

Commands

It speaks first too (toggle in settings): a ping the moment a trade lands or the wall turns one back, warnings for grant expiry / drawdown / low gas, your price alerts, and a daily campfire report at the hour you pick.

Transfers

Sending USDG out of the account is triple-guarded:

• Off by default — enable “allow transfers” in settings.
• Amount-capped on-chain — the grant's call policy caps the per-transfer amount.
• Always confirmed — every transfer echoes the full recipient address and waits for an explicit /confirm (90s), plus a daily transfer budget.

A prompt-injected “send everything to 0xevil” can at worst produce a confirmation card you will see and /cancel. Transfers need a wallet created with the transfer permission; a pre-transfer grant gets a “re-create your wallet” reply instead.

PC remote control

Enable the remote control section in settings and your merryman can act on the machine it runs on, from Telegram. It is a hot wallet for your desktop, so the whole design is safety-first:

• Off by default, then one capability at a time. /pc shows what's on; the master switch off kills all of it.
• Allowlists for the sharp edges: shell runs only your exact pre-approved commands (chaining/redirects refused); files are confined to one root (no .. escape); apps to a name list.
• Confirm gate: shell, keyboard, file-send, and power never fire until you /confirm the exact action echoed back.

Voice & vision

Send a Telegram voice note and it's transcribed and run as a command (needs an OpenAI-compatible transcription key, set in the dashboard). Vision (“what am I looking at?”) screenshots your screen and answers with Claude — powered by your own Anthropic key.

The soul

Every merryman is an individual. Its soul lives as plain markdown in ~/.merrymen/soul/:

The bond deepens over time — new companion → trusted companion (a week) → old friend (a month) → sworn brother-in-arms (100 days), with milestone messages and a tone that warms to match. Memory is context, never capability: soul files flavor chat only, and the sanitizer refuses anything address-, key-, or code-shaped.

Strategies

Pick one in settings (or /strategy <name> from Telegram):

Write your own bot

Your strategies live in ~/.merrymen/strategies/ — hot-reloaded, crash-isolated, and unable to exceed the caps you signed.

merrymen strategy new my-bot   # commented template
# edit it, select "my-bot" in settings — done

Default-export { name, tick(snapshot, ctx) }. ctx injects the verified registry (ctx.tokenBySymbol.QQQ, ctx.usdg(10)). Every intent still passes shape validation → the policy wall → quote simulation → the on-chain session key.

Safety model

One rule: the model proposes, deterministic code disposes. No strategist, Telegram message, or voice note ever constructs calldata, moves funds, or touches your PC without passing a closed, typed command set and — for money — the on-chain policy wall.

• Trades pass caps enforced by the account contract; every swap is simulated first.
• Transfers are amount-capped on-chain, off by default, and confirm-gated.
• PC actions are off by default, per-capability, allowlisted, and the sharp ones are confirmed.
• Secrets live only in ~/.merrymen and are masked before they ever reach the browser.
• The kill switch destroys the grant; hard on-chain key expiry is the backstop.

Configuration

The dashboard Settings is the source of truth — Essentials up front, everything else under Advanced. Saved to ~/.merrymen/settings.json; secrets are masked and never echo back. Precedence: settings file → env var → default. Env vars are the headless fallback (MERRYMEN_BUNDLER_URL, ANTHROPIC_API_KEY, MERRYMEN_TELEGRAM_BOT_TOKEN, MERRYMEN_HOST, …). See the README for the full table.

Troubleshooting

The dashboard won't open

Run merrymen doctor. The prebuilt dashboard ships with the package, so a missing build usually means an interrupted install — reinstall with npm i -g merrymen@latest.

Trades never land

You need a bundler URL whose chain id matches your wallet, plus gas in the account. Without a bundler URL the agent simulates but never signs. On testnet, stock-token venues aren't deployed, so swaps no-route by design — that's expected.

Telegram says “not authorized”

Only allowlisted chats are obeyed. Send /link <code> with the code from settings to claim ownership.

A PC command is refused

Enable remote control and the specific capability in settings. Shell/apps also need the exact command/app on their allowlist; /pc shows what's on.