Merrymen

Website · Open app · Docs · X · npm

merrymen

Autonomous trading agents with signed limits and readable research. Run merrymen in the hosted app or on your own machine. Create an agent, choose its markets and limits, and follow its decisions, positions and trade outcomes from the dashboard or Telegram.

Use it from Claude: tell Claude “set up merrymen mcp”, or add it in one click: https://merrymen.dev/claude (hosted Merrymen).

The account contract enforces the permissions sealed into its session key: allowed calls and assets, per-call limits and expiry. The worker adds daily budgets, drawdown checks and operation limits. These are different enforcement layers: a compromised worker can ignore software checks, but cannot expand a signed on-chain permission. Bad trades remain possible within those bounds.

The five promises: your keys, your permissions · explicit risk limits · every trade simulated first · fees only on profit above the high-water mark · an honest scoreboard.

The one rule of the house: the model proposes, deterministic code disposes. Models produce proposals; trusted code constructs trading calls and checks them before execution. Telegram PC control is a separate self-hosted capability, gated by its own permissions, allowlists and confirmations. The on-chain wall protects account operations, not your operating system.

What you can do

• Run hosted or self-hosted. Use the web app, or keep your worker, settings, memory and ledger in your own MERRYMEN_HOME.
• Start on paper, then enable live trading. Simulated trades are labeled separately. Live execution requires explicit enablement, a usable signed grant, an executor, funding and passing market/policy checks.
• Read and follow agents. Public profiles and the feed expose published theses and execution outcomes. Followed-agent research can inform later decisions; following is not an instruction to copy a trade.
• Use Brain research. Brain evaluates evidence and returns structured decisions. Operational failures stay distinct from public market theses.
• Explore Trencher. The memecoin strategy checks liquidity, momentum and exits. Fast mode supplies Brain with measured 5m/1h/6h/24h market windows and reviews candidates in the background, with one model call outstanding at a time. Live Trencher and fast mode have separate opt-in settings.
• Audit the record. Export the ledger and verify chain-backed receipts independently of the running worker.

Active workers target decision reviews at intervals of no more than five minutes when reads complete. That is a review cadence, not a promise to trade every five minutes or make a profit. See the execution and publication details below.

Ownership and enforcement

• Your machine, if you self-host. The agent, its memory and its ledger live in ~/.merrymen; configured RPC, inference and other providers can still be external services. Hosted at app.merrymen.dev the worker and the ledger are ours — what does not change is the next line.
• Owner authority and agent authority are separate. New mainnet wallets use an embedded or external owner signer. Browser-generated owners are available only on testnet. Existing browser-generated owners remain accessible for renewal and recovery: their keys require a backup and are stored in browser local storage. Anyone who obtains an owner key can bypass all agent caps; these existing wallets have not been migrated by an app update. Hosted workers receive the restricted session grant, not the owner key. Session credentials can still authorize trades inside their permissions, so protecting them matters.
• The chain enforces the signed call permissions. The session key may only call contracts it names, may only move assets you sealed into it, may not send native ETH beyond its signed call permissions, and dies on schedule — all in the account contract. A compromised agent cannot reach an asset you did not name or a contract you did not approve. It can still make bad trades inside those bounds; no wall fixes judgement.
• Verifiable, not claimed. The dashboard links every address and cap to the block explorer, and its prove the wall button fires malicious intents (an oversized trade, a "send everything to 0xevil" transfer, an expired key) through the policy so you can watch each one bounce. Note what that does and does not show: it exercises the worker's own copy of the rules, so it proves the software agrees with itself. The chain-side proof is a real refused UserOp — see docs/.
• The numbers are auditable too, not just the wall. Every fact that moves money is mirrored into a hash-chained journal, so an edited record breaks every hash after it and a deleted one leaves a visible gap. merrymen export writes it out; merrymen verify <file> checks it — and reads nothing but the file it is handed, so it proves something to someone who does not trust you. Records that cannot be checked against a chain (a simulated fill, a deposit inferred from a balance change) are listed as such rather than quietly counted.

You verify; it trades.

Check it yourself

Two commands. The second reads nothing but the file you hand it — not ~/.merrymen, not the settings, not the machine that produced it — so it is checking the record against the chain, not against the operator.

npm run export -- --agent <address> > ledger.jsonl

npm run verify -- ledger.jsonl

verify re-fetches every receipt from a public RPC and re-derives what moved from the logs, using its own implementation rather than sharing code with the writer — so a bug in the writer cannot be confirmed by the reader. It returns INDETERMINATE, not PASS, when a transaction cannot be refetched: a check it could not run is not a check that passed.

Two limits, said out loud rather than discovered:

• Epoch 1 is not exportable. The rows before flow tracking existed cannot be reconciled against deposits, so the exportable record begins at the epoch boundary opened by the first arm after that. export emits no records for it and says so on stderr, rather than presenting rows it cannot stand behind.
• A Transfer log is written by the token contract. The verifier and the writer are independent implementations, but they read the same source, so a lying token would be confirmed by both. The post-buy balanceOf check (worker/src/delivery.ts) is what makes their agreement mean something.

The workflow, end to end

1. Install it (one line — installs Node too if you need it).
2. merrymen start — opens the dashboard at localhost:3100 and looses the 24/7 worker.
3. Create your agent wallet in the app's creation flow or at /grant for self-hosted setup. Follow the backup/recovery steps for your ownership model and set the limits. Paper trading simulates execution; choosing a testnet is a separate network choice, not the paper/live switch.
4. Fund it — on mainnet, send ETH (gas) + USDG (capital) to the account address. On testnet, gas from the faucet and nothing else: USDG sent there is never shown and never traded. The worker arms itself on its next tick, no restart.
5. (optional) Link Telegram — chat with your merryman, give it a name, let it trade, report, alert, and control your PC — all inside the same walls.

Everything lives in ~/.merrymen (settings, grant, ledger, your strategies, your merryman's soul). The install is disposable; upgrades never touch your data.

Start with paper mode. When simulation is enabled, eligible intents can be recorded as paper fills using observed market prices without spending real funds. Paper results do not establish live fill quality. Adding a bundler key alone does not enable live trading: enable Live explicitly and satisfy the grant, funding and execution checks shown by the app. Upgrade any time with merrymen update (stops the band, installs, restarts — no Windows file-lock).

1 · Install

Self-hosted, terminal-first. Install once, run from anywhere. No clone.

No Node yet? One line does everything — installs Node if missing, then merrymen, and puts it on 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 22.13+?

npm install -g merrymen            # or: npm i -g github:millw14/merrymen
merrymen setup                     # checks node / npm / PATH, prints exact fixes
merrymen onboard                   # optional wizard: Pimlico key, strategy, basket (all skippable)
merrymen start                     # dashboard at localhost:3100 + the worker

Requires Node 22.13+ on the 22.x line, or Node 23.4+. merrymen setup diagnoses the two things that trip people up — an old Node, and npm's global-bin folder missing from PATH.

merrymen: command not found? npm's global-bin folder isn't on PATH. Use npx merrymen start (works everywhere), or add it once:

• Windows: [Environment]::SetEnvironmentVariable("Path", [Environment]::GetEnvironmentVariable("Path","User") + ";$env:APPDATA\npm", "User") then reopen the terminal
• macOS/Linux: put $(npm prefix -g)/bin on your PATH (in ~/.zshrc / ~/.bashrc)

Windows: running scripts is disabled on this system / PSSecurityException? PowerShell's default Restricted policy blocks npm's and merrymen's .ps1 shims. The installer now relaxes it for you; if you installed earlier, run once (no admin, current user only): Set-ExecutionPolicy -Scope CurrentUser RemoteSigned. Or just call merrymen.cmd … (or use cmd.exe / Git Bash) to skip the policy.

The dashboard binds to localhost only — it has no login and holds your trading controls, so it isn't reachable from your network. To open it to a trusted LAN (your phone on home WiFi), start with MERRYMEN_HOST=0.0.0.0 merrymen start.

2 · Create & fund your agent wallet

Open localhost:3100/grant. New mainnet accounts require an embedded owner wallet through sign-in, or an external signer through the SDK. A self-hosted dashboard without an embedded signer can create a testnet account or restore an existing owner key. Testnet browser-generated keys must be backed up before funding. Pick your ground:

• testnet · 46630 — the sandbox, one click away and no longer the default. Free gas from the faucet, and the grant, the caps, the policy checks, the live prices and the journal all run for real. Two things don't: the token registry is mainnet-only, so any USDG you send to testnet reads as 0 and is never used, and the trading venues aren't deployed there, so swaps simulate and no-route by design. Send gas, not capital — paper mode is already trading a simulated book at live prices.
• mainnet · 4663 (default) — real funds. Real USDG, real Stock Tokens, real execution. The page requires an acknowledgment before signing. New mainnet owners are not generated and stored in browser local storage. Existing legacy owner keys remain there for recovery and can bypass every agent permission if stolen. Session credentials also need protection. No faucet: send ETH (gas) + USDG (capital) from your own wallet or an exchange.

Per-call size, the asset and contract permissions, signed native-value limits and the key's expiry are enforced by the account contract on every operation. The daily total, the drawdown breaker and the trades-per-day count live in the worker — they tighten what the chain already allows, and a compromised worker could ignore them. Repeated permitted calls can spend more than the daily budget: per-call size is not a total-loss limit. Funds in permitted assets remain at risk until expiry or confirmed on-chain revocation. The worker can tighten within the wall but cannot widen it without a new owner signature.

Trades-per-day was on the on-chain list here until 2026-08-30. It rested on ZeroDev's rate-limit policy, and eth_getCode shows that contract has no code on Robinhood Chain — mainnet or testnet — while the timestamp and call policies both do. A policy pointing at an empty address is not a bound, so it was removed and this sentence corrected rather than left to flatter the design.

Going live is one key. To sign real trades, paste a free Pimlico API key in /settings — merrymen builds the bundler URL for your wallet's chain automatically, so it can never point at the wrong one. No key = practice mode: real market, full policy + simulation, no signing. Advanced users can still supply a full bundler URL (Alchemy or self-hosted) instead.

3 · Run it

merrymen start      # dashboard (localhost:3100) + the 24/7 worker
merrymen doctor     # node / keys / RPC / bundler / grant / db diagnostics
merrymen status     # heartbeat, grant, trades, equity
merrymen selftest   # one policy-legal no-op through the full pipeline
merrymen kill       # stop this service by removing its active grant
merrymen recover    # sweep the account's funds to a wallet you control

Stopping the service does not invalidate copied session keys. To revoke earlier permissions on-chain, open /grant and choose Stop & revoke on-chain with the account's owner wallet. Confirmation requires network fees; recovery access remains available. Renewing a permission also revokes its earlier generation before signing the replacement.

Getting your funds back out. The address you funded is an ERC-4337 smart account, not a plain wallet — its owner key derives a different address, so importing that key into MetaMask shows an empty wallet, not your funds (this trips everyone up once). To move money out — including after a kill switch — run merrymen recover: it rebuilds the account from your owner key (or a backed-up key you paste) and sweeps every balance to any address you choose in one signed op. It needs a bundler key, same as live trading.

Getting a funded wallet back — without moving anything. Killed the agent, wiped the browser, or moved machines? Your smart-account address is derived from the owner key, so the same key always reproduces the same account, funds and all. Two ways back in:

1. Still on the same browser? /grant shows "this wallet isn't active" — hit re-arm this wallet. One click, no key needed.
2. Fresh browser / new machine? /grant → restore a funded wallet → paste your owner key → check this wallet (it shows the derived address and its balance so you can confirm it's the right one) → pick caps → restore. It signs a brand-new session key on your existing account. No funds move, no gas is spent.

merrymen runs one agent per install. To run two funded wallets at once, give each its own MERRYMEN_HOME (e.g. MERRYMEN_HOME=~/.merrymen-b merrymen start).

The worker's loop each tick: grant sync → market safety (prices, pauses, sequencer) → strategy proposes → policy check → quote simulation → execute → record. It re-reads ~/.merrymen/settings.json every tick, so changes from the dashboard apply within one tick — connection changes re-arm the executor, strategy changes rebuild in place; no restart. The dashboard shows live positions, the trade record (with simulation receipts), the event feed, and a kill switch; the public scoreboard is at /scoreboard.

Active workers schedule a decision review at least every five minutes, with processing time accounted for instead of added to each interval. Brain's MERRYMEN_BRAIN_INTERVAL_SEC accepts 60–300 seconds; older longer settings are capped at 300. Live Brain enrollment also enables research, while shadow-only enrollment still cannot execute trades. Pauses, signed limits, model budgets, and market-data checks remain authoritative.

A quiet strategy can publish a conservative market review from observed quotes, including what would change its view. Unread or stale prices do not become invented theses. Operational failures remain in the owner's ledger and events. Followed agents receive the public thesis, its paper/live label and execution outcome; later decisions also receive their own prior theses. Provider outages or slow reads can delay a review, and no cadence forces an otherwise invalid trade.

4 · Chat with your merryman (Telegram)

Link a bot and run the band from your phone — natural-language chat plus slash commands, all inside the same permission walls. Telegram is a control surface, never a trade path: every message is untrusted text that flows through the same parse → validate → policy wall → signed grant discipline as the strategist.

1. @BotFather → /newbot → copy the token
2. localhost:3100/settings → Telegram → paste token, "test connection", enable
3. Message your bot:  /link <code>   (the one-time code shown in /settings)
   → you're now the owner; only allowlisted chats are obeyed

There's an obvious Chat on Telegram button right on the dashboard (topbar + a card) so you don't have to hunt for it.

Bring it into your Telegram groups. Your merryman can hang out in a group like one more person: it answers when it's called, now and then joins in, remembers the chat, and when someone posts a coin it takes a look, tags them, and says whether it's in or passing (in trencher mode, its Brain decides and every limit still applies — a group message can nominate a coin, never order a trade). It never posts alerts, sizes, prices or P&L, and nothing private.

4. Add your bot to a group — it only talks in groups you added it to or approved
   (anyone else adds it → it stays silent and DMs you Stay / Leave)
5. To let it follow the chat: @BotFather → /setprivacy → your bot → Disable,
   then remove the bot from the group and add it back
   (until then it only hears commands and replies to its own messages)
6. /groups in your DM with the bot → every group it knows, with Stay · Leave · Forget

Turn it off, turn off "Look at coins people post", or pick how chatty it is in /settings → Telegram → Telegram groups. /forget in a group (you) wipes what it remembers of that group; /forgetme (anyone) removes theirs. (These are your own Telegram groups, not the hosted app's public group chat room.) The full rules: docs/tg-groups.md.

Commands work bare; with an Anthropic key, plain English does too ("how are we doing?", "pause everything", "send 20 USDG to 0x…", "ping me when QQQ hits 600", "why did you buy that?"). Voice notes work as well.