fourmm 0.1.0

package/dist/wallets/groups/store.d.ts

@@ -0,0 +1,107 @@
+/**
+ * In-house wallet group store.
+ *
+ * Storage: ~/.fourmm/wallets/wallet-store.json (mode 0600), JSON-encoded.
+ * Each wallet's privateKey is AES-encrypted with the master password.
+ *
+ * File shape:
+ *   {
+ *     encrypted: true,
+ *     passwordCheck: "...",  // AES('ALMM_PASSWORD_OK', password)
+ *     groups: {
+ *       "1": { groupId, name, wallets: [...], note, createdAt, updatedAt },
+ *       ...
+ *     }
+ *   }
+ *
+ * All public functions take the master password as an explicit first argument.
+ * There is NO module-level password state: that makes testing easier, hides
+ * fewer dependencies, and lets Week-2 code pass different passwords in the
+ * same process (e.g. import + decrypt two different vaults).
+ *
+ * Write path is atomic (write .tmp, rename) to avoid half-written files.
+ */
+import type { Address, Hex } from 'viem';
+/** A single wallet inside a group */
+export type StoredWallet = {
+    /** EVM checksummed address */
+    address: Address;
+    /** AES-encrypted hex private key (with 0x prefix before encryption) */
+    encryptedPrivateKey: string;
+    /** Free-form note */
+    note: string;
+};
+/** A wallet group (collection of wallets under a shared name) */
+export type WalletGroup = {
+    /** Numeric group ID (auto-assigned) */
+    groupId: number;
+    /** Group name */
+    name: string;
+    /** Free-form description */
+    note: string;
+    /** Wallets in this group */
+    wallets: StoredWallet[];
+    /** ISO 8601 timestamps */
+    createdAt: string;
+    updatedAt: string;
+};
+/** Root file format */
+export type WalletStoreFile = {
+    encrypted: true;
+    passwordCheck: string;
+    groups: Record<number, WalletGroup>;
+};
+/** Group summary (what `list-groups` returns — no wallet contents) */
+export type WalletGroupSummary = Omit<WalletGroup, 'wallets'> & {
+    walletCount: number;
+};
+/** Does a wallet store file already exist? */
+export declare function storeExists(): boolean;
+/**
+ * Load the wallet store.
+ *
+ * - Returns `null` if the store doesn't exist yet. Read-only callers
+ *   (e.g. `list-groups`) should treat this as "no groups".
+ * - Throws if the store exists but the password doesn't match.
+ * - **Never writes to disk.** Callers that want to create a new store
+ *   must call `initStore(password)` explicitly.
+ */
+export declare function loadStore(password: string): WalletStoreFile | null;
+/**
+ * Create a new empty wallet store, encrypted with the given password.
+ *
+ * Throws if a store file already exists. Callers should check `storeExists()`
+ * or use `loadOrInitStore()` if they want idempotent creation.
+ */
+export declare function initStore(password: string): WalletStoreFile;
+/**
+ * Convenience: load the store, or init an empty one if it doesn't exist.
+ * Used by write operations (`createGroup`, etc.).
+ */
+export declare function loadOrInitStore(password: string): WalletStoreFile;
+/** Persist the wallet store atomically */
+export declare function saveStore(store: WalletStoreFile): void;
+/** List all groups (summary form). Returns empty array if no store. */
+export declare function listGroups(password: string): WalletGroupSummary[];
+/** Get a single group by ID. Returns undefined if store or group missing. */
+export declare function getGroup(password: string, groupId: number): WalletGroup | undefined;
+/**
+ * Create a new wallet group with N freshly-generated wallets.
+ * Private keys are encrypted at rest immediately.
+ */
+export declare function createGroup(password: string, options: {
+    name: string;
+    count: number;
+    note?: string | undefined;
+}): WalletGroup;
+/** Add newly-generated wallets to an existing group */
+export declare function addGeneratedWallets(password: string, groupId: number, count: number): StoredWallet[];
+/** Add a wallet from an existing private key */
+export declare function addWalletFromPrivateKey(password: string, groupId: number, privateKey: Hex, note?: string): StoredWallet;
+/** Delete an entire wallet group by ID. */
+export declare function deleteGroup(password: string, groupId: number): void;
+/** Remove a single wallet from a group by address. */
+export declare function removeWalletFromGroup(password: string, groupId: number, address: Address): void;
+/** Decrypt a wallet's private key (only for in-process signing — never log) */
+export declare function decryptPrivateKey(stored: StoredWallet, password: string): Hex;
+//# sourceMappingURL=store.d.ts.map

package/dist/wallets/groups/store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../../../src/wallets/groups/store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAKH,OAAO,KAAK,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,MAAM,CAAA;AAaxC,qCAAqC;AACrC,MAAM,MAAM,YAAY,GAAG;IACzB,8BAA8B;IAC9B,OAAO,EAAE,OAAO,CAAA;IAChB,uEAAuE;IACvE,mBAAmB,EAAE,MAAM,CAAA;IAC3B,qBAAqB;IACrB,IAAI,EAAE,MAAM,CAAA;CACb,CAAA;AAED,iEAAiE;AACjE,MAAM,MAAM,WAAW,GAAG;IACxB,uCAAuC;IACvC,OAAO,EAAE,MAAM,CAAA;IACf,iBAAiB;IACjB,IAAI,EAAE,MAAM,CAAA;IACZ,4BAA4B;IAC5B,IAAI,EAAE,MAAM,CAAA;IACZ,4BAA4B;IAC5B,OAAO,EAAE,YAAY,EAAE,CAAA;IACvB,0BAA0B;IAC1B,SAAS,EAAE,MAAM,CAAA;IACjB,SAAS,EAAE,MAAM,CAAA;CAClB,CAAA;AAED,uBAAuB;AACvB,MAAM,MAAM,eAAe,GAAG;IAC5B,SAAS,EAAE,IAAI,CAAA;IACf,aAAa,EAAE,MAAM,CAAA;IACrB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,CAAA;CACpC,CAAA;AAED,sEAAsE;AACtE,MAAM,MAAM,kBAAkB,GAAG,IAAI,CAAC,WAAW,EAAE,SAAS,CAAC,GAAG;IAC9D,WAAW,EAAE,MAAM,CAAA;CACpB,CAAA;AAiCD,8CAA8C;AAC9C,wBAAgB,WAAW,IAAI,OAAO,CAErC;AAED;;;;;;;;GAQG;AACH,wBAAgB,SAAS,CAAC,QAAQ,EAAE,MAAM,GAAG,eAAe,GAAG,IAAI,CA0BlE;AAED;;;;;GAKG;AACH,wBAAgB,SAAS,CAAC,QAAQ,EAAE,MAAM,GAAG,eAAe,CAkB3D;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,eAAe,CAEjE;AAED,0CAA0C;AAC1C,wBAAgB,SAAS,CAAC,KAAK,EAAE,eAAe,GAAG,IAAI,CAEtD;AAMD,uEAAuE;AACvE,wBAAgB,UAAU,CAAC,QAAQ,EAAE,MAAM,GAAG,kBAAkB,EAAE,CAajE;AAED,6EAA6E;AAC7E,wBAAgB,QAAQ,CACtB,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,MAAM,GACd,WAAW,GAAG,SAAS,CAIzB;AAED;;;GAGG;AACH,wBAAgB,WAAW,CACzB,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE;IACP,IAAI,EAAE,MAAM,CAAA;IACZ,KAAK,EAAE,MAAM,CAAA;IACb,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;CAC1B,GACA,WAAW,CA0Bb;AAED,uDAAuD;AACvD,wBAAgB,mBAAmB,CACjC,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,MAAM,GACZ,YAAY,EAAE,CAqBhB;AAED,gDAAgD;AAChD,wBAAgB,uBAAuB,CACrC,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,GAAG,EACf,IAAI,SAAK,GACR,YAAY,CA2Bd;AAED,2CAA2C;AAC3C,wBAAgB,WAAW,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,CAMnE;AAED,sDAAsD;AACtD,wBAAgB,qBAAqB,CACnC,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,OAAO,GACf,IAAI,CAcN;AAED,+EAA+E;AAC/E,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,YAAY,EAAE,QAAQ,EAAE,MAAM,GAAG,GAAG,CAQ7E"}

package/dist/wallets/groups/store.js

@@ -0,0 +1,254 @@
+/**
+ * In-house wallet group store.
+ *
+ * Storage: ~/.fourmm/wallets/wallet-store.json (mode 0600), JSON-encoded.
+ * Each wallet's privateKey is AES-encrypted with the master password.
+ *
+ * File shape:
+ *   {
+ *     encrypted: true,
+ *     passwordCheck: "...",  // AES('ALMM_PASSWORD_OK', password)
+ *     groups: {
+ *       "1": { groupId, name, wallets: [...], note, createdAt, updatedAt },
+ *       ...
+ *     }
+ *   }
+ *
+ * All public functions take the master password as an explicit first argument.
+ * There is NO module-level password state: that makes testing easier, hides
+ * fewer dependencies, and lets Week-2 code pass different passwords in the
+ * same process (e.g. import + decrypt two different vaults).
+ *
+ * Write path is atomic (write .tmp, rename) to avoid half-written files.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { walletsDir, ensureFourmmDirs } from '../../lib/config.js';
+import { decrypt, encrypt, generatePasswordCheck, verifyPassword, } from './encrypt.js';
+import { generateWallets, walletFromPrivateKey } from './generate.js';
+// ============================================================
+// Paths
+// ============================================================
+const STORE_FILE = 'wallet-store.json';
+function storePath() {
+    return path.join(walletsDir(), STORE_FILE);
+}
+// ============================================================
+// Atomic file ops
+// ============================================================
+function atomicWriteJson(filePath, data) {
+    const dir = path.dirname(filePath);
+    if (!fs.existsSync(dir)) {
+        fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+    }
+    const tmpPath = `${filePath}.tmp`;
+    fs.writeFileSync(tmpPath, JSON.stringify(data, null, 2), {
+        encoding: 'utf-8',
+        mode: 0o600,
+    });
+    fs.renameSync(tmpPath, filePath);
+}
+// ============================================================
+// Load / init
+// ============================================================
+/** Does a wallet store file already exist? */
+export function storeExists() {
+    return fs.existsSync(storePath());
+}
+/**
+ * Load the wallet store.
+ *
+ * - Returns `null` if the store doesn't exist yet. Read-only callers
+ *   (e.g. `list-groups`) should treat this as "no groups".
+ * - Throws if the store exists but the password doesn't match.
+ * - **Never writes to disk.** Callers that want to create a new store
+ *   must call `initStore(password)` explicitly.
+ */
+export function loadStore(password) {
+    if (!password)
+        throw new Error('loadStore: password is empty');
+    const file = storePath();
+    if (!fs.existsSync(file))
+        return null;
+    let parsed;
+    try {
+        const raw = fs.readFileSync(file, 'utf-8');
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        throw new Error(`Wallet store at ${file} is corrupt (not valid JSON)`);
+    }
+    if (!parsed.encrypted || !parsed.passwordCheck) {
+        throw new Error(`Wallet store at ${file} is missing encrypted/passwordCheck fields`);
+    }
+    if (!verifyPassword(password, parsed.passwordCheck)) {
+        throw new Error('Wrong master password: unable to decrypt wallet store');
+    }
+    if (!parsed.groups)
+        parsed.groups = {};
+    return parsed;
+}
+/**
+ * Create a new empty wallet store, encrypted with the given password.
+ *
+ * Throws if a store file already exists. Callers should check `storeExists()`
+ * or use `loadOrInitStore()` if they want idempotent creation.
+ */
+export function initStore(password) {
+    if (!password)
+        throw new Error('initStore: password is empty');
+    ensureFourmmDirs();
+    const file = storePath();
+    if (fs.existsSync(file)) {
+        throw new Error(`Wallet store at ${file} already exists. Refusing to overwrite.`);
+    }
+    const store = {
+        encrypted: true,
+        passwordCheck: generatePasswordCheck(password),
+        groups: {},
+    };
+    atomicWriteJson(file, store);
+    return store;
+}
+/**
+ * Convenience: load the store, or init an empty one if it doesn't exist.
+ * Used by write operations (`createGroup`, etc.).
+ */
+export function loadOrInitStore(password) {
+    return loadStore(password) ?? initStore(password);
+}
+/** Persist the wallet store atomically */
+export function saveStore(store) {
+    atomicWriteJson(storePath(), store);
+}
+// ============================================================
+// Group operations
+// ============================================================
+/** List all groups (summary form). Returns empty array if no store. */
+export function listGroups(password) {
+    const store = loadStore(password);
+    if (!store)
+        return [];
+    return Object.values(store.groups)
+        .sort((a, b) => a.groupId - b.groupId)
+        .map((g) => ({
+        groupId: g.groupId,
+        name: g.name,
+        note: g.note,
+        walletCount: g.wallets.length,
+        createdAt: g.createdAt,
+        updatedAt: g.updatedAt,
+    }));
+}
+/** Get a single group by ID. Returns undefined if store or group missing. */
+export function getGroup(password, groupId) {
+    const store = loadStore(password);
+    if (!store)
+        return undefined;
+    return store.groups[groupId];
+}
+/**
+ * Create a new wallet group with N freshly-generated wallets.
+ * Private keys are encrypted at rest immediately.
+ */
+export function createGroup(password, options) {
+    const store = loadOrInitStore(password);
+    const nextId = Object.values(store.groups).reduce((max, g) => Math.max(max, g.groupId), 0) +
+        1;
+    const fresh = generateWallets(options.count);
+    const now = new Date().toISOString();
+    const group = {
+        groupId: nextId,
+        name: options.name,
+        note: options.note ?? '',
+        wallets: fresh.map((w) => ({
+            address: w.address,
+            encryptedPrivateKey: encrypt(w.privateKey, password),
+            note: w.note,
+        })),
+        createdAt: now,
+        updatedAt: now,
+    };
+    store.groups[nextId] = group;
+    saveStore(store);
+    return group;
+}
+/** Add newly-generated wallets to an existing group */
+export function addGeneratedWallets(password, groupId, count) {
+    const store = loadStore(password);
+    if (!store) {
+        throw new Error(`No wallet store found. Create a group first with \`fourmm wallet create-group\`.`);
+    }
+    const group = store.groups[groupId];
+    if (!group)
+        throw new Error(`Group ${groupId} does not exist`);
+    const fresh = generateWallets(count);
+    const stored = fresh.map((w) => ({
+        address: w.address,
+        encryptedPrivateKey: encrypt(w.privateKey, password),
+        note: w.note,
+    }));
+    group.wallets.push(...stored);
+    group.updatedAt = new Date().toISOString();
+    saveStore(store);
+    return stored;
+}
+/** Add a wallet from an existing private key */
+export function addWalletFromPrivateKey(password, groupId, privateKey, note = '') {
+    const store = loadStore(password);
+    if (!store) {
+        throw new Error(`No wallet store found. Create a group first with \`fourmm wallet create-group\`.`);
+    }
+    const group = store.groups[groupId];
+    if (!group)
+        throw new Error(`Group ${groupId} does not exist`);
+    const w = walletFromPrivateKey(privateKey, note);
+    // Dedupe by address
+    if (group.wallets.some((existing) => existing.address === w.address)) {
+        throw new Error(`Wallet ${w.address} already exists in group ${groupId}`);
+    }
+    const stored = {
+        address: w.address,
+        encryptedPrivateKey: encrypt(privateKey, password),
+        note: w.note,
+    };
+    group.wallets.push(stored);
+    group.updatedAt = new Date().toISOString();
+    saveStore(store);
+    return stored;
+}
+/** Delete an entire wallet group by ID. */
+export function deleteGroup(password, groupId) {
+    const store = loadStore(password);
+    if (!store)
+        throw new Error('No wallet store found.');
+    if (!store.groups[groupId])
+        throw new Error(`Group ${groupId} does not exist`);
+    delete store.groups[groupId];
+    saveStore(store);
+}
+/** Remove a single wallet from a group by address. */
+export function removeWalletFromGroup(password, groupId, address) {
+    const store = loadStore(password);
+    if (!store)
+        throw new Error('No wallet store found.');
+    const group = store.groups[groupId];
+    if (!group)
+        throw new Error(`Group ${groupId} does not exist`);
+    const before = group.wallets.length;
+    group.wallets = group.wallets.filter((w) => w.address.toLowerCase() !== address.toLowerCase());
+    if (group.wallets.length === before) {
+        throw new Error(`Address ${address} not found in group ${groupId}`);
+    }
+    group.updatedAt = new Date().toISOString();
+    saveStore(store);
+}
+/** Decrypt a wallet's private key (only for in-process signing — never log) */
+export function decryptPrivateKey(stored, password) {
+    const pk = decrypt(stored.encryptedPrivateKey, password);
+    if (!pk.startsWith('0x')) {
+        throw new Error(`Decrypted private key for ${stored.address} is malformed (missing 0x prefix)`);
+    }
+    return pk;
+}
+//# sourceMappingURL=store.js.map

package/dist/wallets/groups/store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.js","sourceRoot":"","sources":["../../../src/wallets/groups/store.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "fourmm",
+  "version": "0.1.0",
+  "description": "fourMM — agent-first CLI for Four.meme market making on BSC",
+  "type": "module",
+  "license": "MIT",
+  "author": "linwe",
+  "keywords": [
+    "bsc",
+    "four.meme",
+    "market-making",
+    "agent",
+    "cli",
+    "defi",
+    "meme"
+  ],
+  "bin": {
+    "fourmm": "./dist/bin.js"
+  },
+  "main": "./dist/cli.js",
+  "files": [
+    "dist",
+    "skills",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "dependencies": {
+    "crypto-js": "^4.2.0",
+    "incur": "^0.3.25",
+    "viem": "^2.21.0"
+  },
+  "devDependencies": {
+    "@types/crypto-js": "^4.2.2",
+    "@types/node": "^22.0.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.6.0",
+    "vitest": "^2.1.0"
+  },
+  "scripts": {
+    "build": "tsc",
+    "clean": "rm -rf dist",
+    "dev": "tsx src/bin.ts",
+    "fourmm": "tsx src/bin.ts",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit"
+  }
+}

package/skills/SKILL.md

@@ -0,0 +1,187 @@
+---
+name: fourmm
+description: fourMM — Agent-first market-making CLI for Four.meme on BSC. Create tokens, trade (buy/sell/sniper), pump/dump via Flashbot bundles, generate volume, manage wallets, transfer funds.
+requires_bin: fourmm
+install: pnpm install && pnpm build && npx fourmm skills add
+---
+
+# fourMM
+
+Market-making CLI for [Four.meme](https://four.meme) on BNB Smart Chain.
+
+## Setup
+
+```sh
+# Clone & build
+git clone <repo-url> && cd fourMM
+pnpm install && pnpm build
+
+# Install skills for your agent
+npx fourmm skills add
+
+# Or start as MCP server
+npx fourmm --mcp
+
+# Initialize config (BlockRazor MEV-protected RPC)
+fourmm config init
+
+# Create wallets
+fourmm wallet create-group --name main --count 5
+
+# Fund wallets
+fourmm transfer out --from <your-funded-wallet> --to-group 1 --value 0.01
+```
+
+**Environment:** Set `FOURMM_PASSWORD` to avoid `--password` on every command.
+
+---
+
+## Intent Routing
+
+### I want to create a token
+```sh
+fourmm token create --name "Name" --symbol "SYM" --image logo.png --dev-wallet <groupId> [--preset-buy 0.01]
+```
+
+### I want to buy tokens
+```sh
+# All wallets in group buy the same amount
+fourmm trade buy --group <id> --token <CA> --amount <BNB> [--slippage 500]
+
+# Each wallet buys a different amount
+fourmm trade sniper --group <id> --token <CA> --amounts "0.01,0.02,0.05"
+```
+
+### I want to sell tokens
+```sh
+# Sell everything
+fourmm trade sell --group <id> --token <CA> --amount all
+
+# Sell 50%
+fourmm trade sell --group <id> --token <CA> --amount 50%
+
+# Sell fixed amount
+fourmm trade sell --group <id> --token <CA> --amount 1000000
+```
+
+### I want to pump the price
+```sh
+fourmm tools robot-price --group <id> --token <CA> --direction up --target-price <BNB_PER_TOKEN> --amount <BNB_PER_ROUND>
+```
+All wallets' buys are bundled via Flashbot (`eth_sendBundle`) — atomic, same block, no MEV.
+
+### I want to dump the price
+```sh
+fourmm tools robot-price --group <id> --token <CA> --direction down --target-price <BNB_PER_TOKEN> --amount <BNB_PER_ROUND>
+```
+
+### I want to generate volume
+```sh
+# Atomic buy+sell per wallet (zero net position, generates on-chain volume)
+fourmm tools volume --group <id> --token <CA> --amount <BNB> --rounds 10
+
+# Single atomic round-trip per wallet
+fourmm trade batch --group <id> --token <CA> --amount <BNB>
+```
+
+### I want to distribute holder count
+```sh
+# Group A pays BNB, Group B receives tokens (via Router.turnover)
+fourmm tools turnover --from-group <A> --to-group <B> --token <CA> --amount <BNB>
+```
+
+### I want to check my positions
+```sh
+fourmm query monitor --group <id> --token <CA>    # Holdings + PnL
+fourmm query balance --address <ADDR>               # BNB balance
+fourmm query price --token <CA>                     # Live price
+fourmm query transactions --group <id>              # Trade history
+```
+
+### I want to manage wallets
+```sh
+fourmm wallet create-group --name <NAME> --count <N>  # Create group
+fourmm wallet list-groups                              # List all groups
+fourmm wallet group-info --id <ID>                     # View wallets
+fourmm wallet generate --group <ID> --count <N>        # Add wallets
+fourmm wallet add --group <ID> --private-key <KEY>     # Import key
+fourmm wallet remove --group <ID> --address <ADDR>     # Remove wallet
+fourmm wallet import --group <ID> --file wallets.csv   # Bulk import
+fourmm wallet export --group <ID> --file out.csv       # Export keys
+fourmm wallet delete-group --id <ID> --force           # Delete group
+fourmm wallet overview                                 # Aggregate PnL
+```
+
+### I want to move funds
+```sh
+fourmm transfer out --from <ADDR> --to-group <ID> --value <BNB>           # Distribute
+fourmm transfer in --to <ADDR> --from-group <ID> --amount all             # Collect all
+fourmm transfer in --to <ADDR> --from-group <ID> --amount reserve --value 0.002  # Keep reserve
+fourmm transfer many-to-many --from-group <A> --to-group <B>              # Pair transfer
+```
+
+### I want to check a token
+```sh
+fourmm token info --ca <CA>              # Full on-chain metadata
+fourmm token identify --ca <CA>          # Variant: standard / anti-sniper / tax / x-mode
+fourmm token graduate-status --ca <CA>   # Graduation progress
+fourmm token pool --ca <CA>              # Pool / liquidity info
+fourmm query kline --token <CA>          # K-line candles (graduated only)
+```
+
+### I want to change config
+```sh
+fourmm config get                           # View all
+fourmm config get --key rpcUrl              # View one
+fourmm config set rpcUrl <URL>              # Change RPC
+fourmm config set defaultSlippageBps 500    # Change slippage
+fourmm config init                          # Reset to defaults
+```
+
+---
+
+## Key Concepts
+
+**Wallet Groups:** Wallets are organized in numbered groups (1, 2, 3...). Each group has N wallets. Trade/volume/transfer commands operate on entire groups.
+
+**Bonding Curve vs PancakeSwap:** Tokens start on Four.meme's bonding curve. After raising 18 BNB, they "graduate" to PancakeSwap. fourMM auto-detects and routes accordingly.
+
+**Token Variants:**
+- `standard` — normal token, fully supported
+- `anti-sniper-fee` — dynamic fee decreasing block-by-block, supported (use higher slippage)
+- `tax-token` — fourMM refuses (round-trip loss too high)
+- `x-mode` — fourMM refuses (special buy interface)
+
+**Slippage:** In basis points. 300 = 3%, 500 = 5%, 1500 = 15%. Higher = more tolerance for price movement.
+
+**Flashbot Bundle:** `robot-price` signs all wallets' txs offline and submits via `eth_sendBundle`. All execute in the same block or none do. No public mempool exposure.
+
+**Router Contract:** `0xd62c2fd94176f98424af83e4b9a333d454b2216c` — atomic `volume()` (buy+sell), `turnover()` (buy for another wallet), `volumePancake()` (graduated tokens).
+
+---
+
+## Common Workflows
+
+### Launch + Market Make
+```sh
+fourmm wallet create-group --name launch --count 10
+fourmm transfer out --from <funded-wallet> --to-group 1 --value 0.05
+fourmm token create --name "My Token" --symbol "MTK" --image logo.png --dev-wallet 1 --preset-buy 0.01
+# Wait for CA in output, then:
+fourmm tools volume --group 1 --token <CA> --amount 0.01 --rounds 20
+fourmm tools robot-price --group 1 --token <CA> --direction up --target-price 0.00001 --amount 0.01
+```
+
+### Snipe + Dump
+```sh
+fourmm trade sniper --group 1 --token <CA> --amounts "0.05,0.03,0.02,0.01,0.01"
+fourmm query monitor --group 1 --token <CA>
+# When ready:
+fourmm trade sell --group 1 --token <CA> --amount all
+fourmm transfer in --to <your-wallet> --from-group 1 --amount all
+```
+
+### Volume Bot
+```sh
+fourmm tools volume --group 1 --token <CA> --amount 0.01 --rounds 50 --interval 3000
+```