fourmm 0.1.0

package/README.md

@@ -0,0 +1,147 @@
+# fourMM — Four.meme Market Maker
+
+> Agent-first CLI for Four.meme market making on BSC.
+
+## What it does
+
+fourMM is a command-line tool for running market-making strategies on [Four.meme](https://four.meme) tokens on BNB Smart Chain, designed to be driven by AI agents (Claude Code, MCP clients) or used directly.
+
+### Key Features
+
+1. **Flashbot Bundle Execution** — Pump/dump commands sign all wallets' txs offline and submit via `eth_sendBundle` (BlockRazor), atomically executing in the same block. No MEV, no sandwich.
+2. **Atomic Router Contract** — A Solidity router on BSC does `buy + sell round-trip` in a single tx (`volume()`), `buy for another wallet` (`turnover()`), and `PancakeSwap round-trip` (`volumePancake()`).
+3. **Bonding Curve + PancakeSwap Auto-Routing** — Every trade command detects whether the token has graduated and routes through the correct contract. Your volume bot doesn't break at graduation.
+4. **Token Creation** — Full Four.meme REST API integration: auth, image upload, token registration, on-chain `createToken`, optional dev-buy.
+5. **Refuses TaxToken / X Mode** — Because the round-trip math doesn't work. fourMM knows what real market making means.
+
+## Install
+
+```bash
+pnpm install
+pnpm build
+```
+
+Requires Node.js >= 22.
+
+## Quick Start
+
+```bash
+# Initialize config (BlockRazor MEV-protected RPC by default)
+fourmm config init
+
+# Create wallet group with 5 wallets
+fourmm wallet create-group --name snipers --count 5
+
+# Fund wallets from your main wallet
+fourmm transfer out --from 0xYourWallet --to-group 1 --value 0.01
+
+# Create a token on Four.meme
+fourmm token create --name "My Token" --symbol "MTK" --image logo.png --dev-wallet 1
+
+# Buy
+fourmm trade buy --group 1 --token 0x...4444 --amount 0.01
+
+# Sell all
+fourmm trade sell --group 1 --token 0x...4444 --amount all
+
+# Pump price (Flashbot bundle, all wallets buy atomically each round)
+fourmm tools robot-price --group 1 --token 0x...4444 --direction up --target-price 0.00001 --amount 0.01
+
+# Dump price
+fourmm tools robot-price --group 1 --token 0x...4444 --direction down --target-price 0.000001 --amount 0.01
+
+# Generate volume (atomic buy+sell per wallet, zero net position)
+fourmm tools volume --group 1 --token 0x...4444 --amount 0.01 --rounds 10
+
+# Check PnL
+fourmm query monitor --group 1 --token 0x...4444
+```
+
+## Agent Integration
+
+```bash
+# Option 1: Install skills globally (any agent can discover them)
+pnpm install && pnpm build
+npx fourmm skills add
+
+# Option 2: MCP server (Claude Desktop / Cursor / etc.)
+npx fourmm --mcp
+```
+
+Skills are in the `skills/` directory. The top-level `skills/SKILL.md` is a routing table that maps user intents to commands. Sub-skills (`skills/fourmm-*/SKILL.md`) contain detailed parameter schemas and output types.
+
+## Commands (34)
+
+```
+config    (3)  init, set, get
+wallet   (11)  create-group, generate, list-groups, group-info,
+               add, import, export, export-group, overview,
+               delete-group, remove
+token     (5)  create, info, pool, identify, graduate-status
+trade     (4)  buy, sell, sniper, batch
+tools     (3)  volume, turnover, robot-price
+transfer  (3)  in, out, many-to-many
+query     (5)  balance, price, kline, transactions, monitor
+```
+
+See [skills/SKILL.md](./skills/SKILL.md) for the full routing guide with all options.
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────┐
+│  AI Agent (Claude Code / MCP)               │
+│  reads skills/SKILL.md → picks command      │
+└──────────────┬──────────────────────────────┘
+               │
+┌──────────────▼──────────────────────────────┐
+│  fourmm CLI (incur framework)               │
+│  34 commands, TOON/JSON/YAML output         │
+│  zod schemas for agent-safe I/O             │
+└──────────────┬──────────────────────────────┘
+               │
+    ┌──────────┼──────────────┐
+    │          │              │
+┌───▼───┐ ┌───▼────┐  ┌─────▼──────┐
+│Bonding│ │Pancake │  │ Flashbot   │
+│ Curve │ │  Swap  │  │  Bundle    │
+│(V1/V2)│ │(Router)│  │(eth_send   │
+│       │ │        │  │  Bundle)   │
+└───┬───┘ └───┬────┘  └─────┬──────┘
+    │         │              │
+┌───▼─────────▼──────────────▼──────┐
+│  BSC Mainnet                       │
+│  TokenManager2    PancakeRouter02  │
+│  FourmemeMmRouter v2               │
+│  (0xd62c...216c)                   │
+└────────────────────────────────────┘
+```
+
+## On-Chain Contracts
+
+| Contract | Address | Description |
+|----------|---------|-------------|
+| FourmemeMmRouter v2 | `0xd62c2fd94176f98424af83e4b9a333d454b2216c` | Atomic volume/turnover/volumePancake |
+| TokenManager2 | `0x5c952063c7fc8610FFDB798152D69F0B9550762b` | Four.meme V2 (buy/sell/create) |
+| TokenManagerHelper3 | `0xF251F83e40a78868FcfA3FA4599Dad6494E46034` | Unified query interface |
+| PancakeSwap V2 Router | `0x10ED43C718714eb63d5aA57B78B54704E256024E` | Graduated token trading |
+
+## Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `FOURMM_PASSWORD` | Master password for wallet encryption |
+| `BSC_RPC_URL` | Override primary RPC endpoint |
+| `BSCSCAN_API_KEY` | BSCScan API key |
+
+## Tech Stack
+
+- **CLI Framework**: [incur](https://github.com/nicholasgasior/incur) — agent-first with TOON output, CTAs, skills/MCP auto-generation
+- **EVM Client**: [viem](https://viem.sh) — TypeScript EVM interactions
+- **Contracts**: [Foundry](https://getfoundry.sh) — Solidity development + fork testing
+- **Encryption**: crypto-js AES — wallet-at-rest encryption
+- **Bundle**: BlockRazor `eth_sendBundle` — Flashbot-style atomic execution
+
+## License
+
+MIT

package/dist/bin.d.ts

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+/**
+ * fourMM CLI entry point.
+ *
+ * Force exit after serve() resolves so fire-and-forget background tasks
+ * (trackInBackground) don't keep the process alive for 30+ seconds.
+ */
+export {};
+//# sourceMappingURL=bin.d.ts.map

package/dist/bin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bin.d.ts","sourceRoot":"","sources":["../src/bin.ts"],"names":[],"mappings":";AACA;;;;;GAKG"}

package/dist/bin.js

@@ -0,0 +1,14 @@
+#!/usr/bin/env node
+/**
+ * fourMM CLI entry point.
+ *
+ * Force exit after serve() resolves so fire-and-forget background tasks
+ * (trackInBackground) don't keep the process alive for 30+ seconds.
+ */
+import { cli } from './cli.js';
+cli.serve().then(() => {
+    // Give background tasks 2s grace period to flush DataStore writes,
+    // then exit regardless of pending HTTP handles.
+    setTimeout(() => process.exit(0), 2_000).unref();
+});
+//# sourceMappingURL=bin.js.map

package/dist/bin.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bin.js","sourceRoot":"","sources":["../src/bin.ts"],"names":[],"mappings":";AACA;;;;;GAKG;AAEH,OAAO,EAAE,GAAG,EAAE,MAAM,UAAU,CAAA;AAE9B,GAAG,CAAC,KAAK,EAAE,CAAC,IAAI,CAAC,GAAG,EAAE;IACpB,mEAAmE;IACnE,gDAAgD;IAChD,UAAU,CAAC,GAAG,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC,KAAK,EAAE,CAAA;AAClD,CAAC,CAAC,CAAA"}

package/dist/cli.d.ts

@@ -0,0 +1,319 @@
+/**
+ * fourMM — Four.meme Market Maker
+ *
+ * Root CLI definition. Command groups are mounted here.
+ */
+import { Cli } from 'incur';
+export declare const cli: Cli.Cli<{
+    [x: `${string} init`]: {
+        args: {};
+        options: {
+            rpcUrl?: string | undefined;
+            network?: "bsc" | "bsc-testnet" | undefined;
+            slippageBps?: number | undefined;
+        };
+    };
+    [x: `${string} set`]: {
+        args: {
+            key: string;
+            value: string;
+        };
+        options: {};
+    };
+    [x: `${string} get`]: {
+        args: {};
+        options: {
+            key?: string | undefined;
+        };
+    };
+} & {
+    [x: `${string} create-group`]: {
+        args: {};
+        options: {
+            name: string;
+            count: number;
+            note?: string | undefined;
+            password?: string | undefined;
+        };
+    };
+    [x: `${string} generate`]: {
+        args: {};
+        options: {
+            group: number;
+            count: number;
+            password?: string | undefined;
+        };
+    };
+    [x: `${string} add`]: {
+        args: {};
+        options: {
+            group: number;
+            privateKey: string;
+            note?: string | undefined;
+            password?: string | undefined;
+        };
+    };
+    [x: `${string} group-info`]: {
+        args: {};
+        options: {
+            id: number;
+            showKeys: boolean;
+            password?: string | undefined;
+        };
+    };
+    [x: `${string} list-groups`]: {
+        args: {};
+        options: {
+            password?: string | undefined;
+        };
+    };
+    [x: `${string} delete-group`]: {
+        args: {};
+        options: {
+            id: number;
+            force: boolean;
+            password?: string | undefined;
+        };
+    };
+    [x: `${string} remove`]: {
+        args: {};
+        options: {
+            group: number;
+            address: string;
+            password?: string | undefined;
+        };
+    };
+    [x: `${string} import`]: {
+        args: {};
+        options: {
+            group: number;
+            file: string;
+            password?: string | undefined;
+        };
+    };
+    [x: `${string} export`]: {
+        args: {};
+        options: {
+            group: number;
+            file: string;
+            password?: string | undefined;
+        };
+    };
+    [x: `${string} export-group`]: {
+        args: {};
+        options: {
+            file: string;
+            encrypt: boolean;
+            password?: string | undefined;
+        };
+    };
+    [x: `${string} overview`]: {
+        args: {};
+        options: {
+            groups: string;
+            token?: string | undefined;
+            password?: string | undefined;
+        };
+    };
+} & {
+    [x: `${string} pool`]: {
+        args: {};
+        options: {
+            ca: string;
+        };
+    };
+    [x: `${string} create`]: {
+        args: {};
+        options: {
+            name: string;
+            symbol: string;
+            image: string;
+            description: string;
+            category: "Meme" | "AI" | "Defi" | "Games" | "Infra" | "De-Sci" | "Social" | "Depin" | "Charity" | "Others";
+            presetBuy: number;
+            dryRun: boolean;
+            twitter?: string | undefined;
+            website?: string | undefined;
+            telegram?: string | undefined;
+            devWallet?: number | undefined;
+            password?: string | undefined;
+        };
+    };
+    [x: `${string} identify`]: {
+        args: {};
+        options: {
+            ca: string;
+        };
+    };
+    [x: `${string} graduate-status`]: {
+        args: {};
+        options: {
+            ca: string;
+        };
+    };
+    [x: `${string} info`]: {
+        args: {};
+        options: {
+            ca: string;
+        };
+    };
+} & {
+    [x: `${string} balance`]: {
+        args: {};
+        options: {
+            address: string;
+            token?: string | undefined;
+        };
+    };
+    [x: `${string} transactions`]: {
+        args: {};
+        options: {
+            group: number;
+            limit: number;
+            token?: string | undefined;
+        };
+    };
+    [x: `${string} price`]: {
+        args: {};
+        options: {
+            token: string;
+        };
+    };
+    [x: `${string} monitor`]: {
+        args: {};
+        options: {
+            group: number;
+            token: string;
+        };
+    };
+    [x: `${string} kline`]: {
+        args: {};
+        options: {
+            token: string;
+            interval: "1m" | "5m" | "15m" | "1h" | "4h" | "12h" | "1d";
+            count: number;
+            pool?: string | undefined;
+        };
+    };
+} & {
+    [x: `${string} out`]: {
+        args: {};
+        options: {
+            from: string;
+            toGroup: number;
+            value: number;
+            dryRun: boolean;
+            password?: string | undefined;
+        };
+    };
+    [x: `${string} in`]: {
+        args: {};
+        options: {
+            to: string;
+            fromGroup: number;
+            amount: "fixed" | "all" | "reserve";
+            dryRun: boolean;
+            value?: number | undefined;
+            password?: string | undefined;
+        };
+    };
+    [x: `${string} many-to-many`]: {
+        args: {};
+        options: {
+            fromGroup: number;
+            toGroup: number;
+            amount: "fixed" | "all" | "reserve";
+            dryRun: boolean;
+            value?: number | undefined;
+            password?: string | undefined;
+        };
+    };
+} & {
+    [x: `${string} buy`]: {
+        args: {};
+        options: {
+            group: number;
+            token: string;
+            amount: number;
+            slippage: number;
+            dryRun: boolean;
+            password?: string | undefined;
+        };
+    };
+    [x: `${string} sell`]: {
+        args: {};
+        options: {
+            group: number;
+            token: string;
+            amount: string;
+            slippage: number;
+            dryRun: boolean;
+            password?: string | undefined;
+        };
+    };
+    [x: `${string} batch`]: {
+        args: {};
+        options: {
+            group: number;
+            token: string;
+            amount: number;
+            slippage: number;
+            dryRun: boolean;
+            password?: string | undefined;
+        };
+    };
+    [x: `${string} sniper`]: {
+        args: {};
+        options: {
+            group: number;
+            token: string;
+            amounts: string;
+            slippage: number;
+            dryRun: boolean;
+            password?: string | undefined;
+        };
+    };
+} & {
+    [x: `${string} turnover`]: {
+        args: {};
+        options: {
+            fromGroup: number;
+            toGroup: number;
+            token: string;
+            amount: number;
+            slippage: number;
+            dryRun: boolean;
+            password?: string | undefined;
+        };
+    };
+    [x: `${string} volume`]: {
+        args: {};
+        options: {
+            group: number;
+            token: string;
+            amount: number;
+            slippage: number;
+            rounds: number;
+            interval: number;
+            dryRun: boolean;
+            password?: string | undefined;
+        };
+    };
+    [x: `${string} robot-price`]: {
+        args: {};
+        options: {
+            group: number;
+            token: string;
+            direction: "up" | "down";
+            targetPrice: number;
+            amount: number;
+            interval: number;
+            maxRounds: number;
+            slippage: number;
+            dryRun: boolean;
+            maxCost?: number | undefined;
+            password?: string | undefined;
+        };
+    };
+}, undefined, undefined>;
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,GAAG,EAAE,MAAM,OAAO,CAAA;AAS3B,eAAO,MAAM,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;wBAWC,CAAA"}

package/dist/cli.js

@@ -0,0 +1,25 @@
+/**
+ * fourMM — Four.meme Market Maker
+ *
+ * Root CLI definition. Command groups are mounted here.
+ */
+import { Cli } from 'incur';
+import { config } from './commands/config.js';
+import { query } from './commands/query.js';
+import { token } from './commands/token.js';
+import { tools } from './commands/tools.js';
+import { trade } from './commands/trade.js';
+import { transfer } from './commands/transfer.js';
+import { wallet } from './commands/wallet.js';
+export const cli = Cli.create('fourmm', {
+    version: '0.1.0',
+    description: 'fourMM — agent-first CLI for Four.meme market making on BSC.',
+})
+    .command(config)
+    .command(wallet)
+    .command(token)
+    .command(query)
+    .command(transfer)
+    .command(trade)
+    .command(tools);
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,GAAG,EAAE,MAAM,OAAO,CAAA;AAC3B,OAAO,EAAE,MAAM,EAAE,MAAM,sBAAsB,CAAA;AAC7C,OAAO,EAAE,KAAK,EAAE,MAAM,qBAAqB,CAAA;AAC3C,OAAO,EAAE,KAAK,EAAE,MAAM,qBAAqB,CAAA;AAC3C,OAAO,EAAE,KAAK,EAAE,MAAM,qBAAqB,CAAA;AAC3C,OAAO,EAAE,KAAK,EAAE,MAAM,qBAAqB,CAAA;AAC3C,OAAO,EAAE,QAAQ,EAAE,MAAM,wBAAwB,CAAA;AACjD,OAAO,EAAE,MAAM,EAAE,MAAM,sBAAsB,CAAA;AAE7C,MAAM,CAAC,MAAM,GAAG,GAAG,GAAG,CAAC,MAAM,CAAC,QAAQ,EAAE;IACtC,OAAO,EAAE,OAAO;IAChB,WAAW,EACT,8DAA8D;CACjE,CAAC;KACC,OAAO,CAAC,MAAM,CAAC;KACf,OAAO,CAAC,MAAM,CAAC;KACf,OAAO,CAAC,KAAK,CAAC;KACd,OAAO,CAAC,KAAK,CAAC;KACd,OAAO,CAAC,QAAQ,CAAC;KACjB,OAAO,CAAC,KAAK,CAAC;KACd,OAAO,CAAC,KAAK,CAAC,CAAA"}

package/dist/commands/config.d.ts

@@ -0,0 +1,35 @@
+/**
+ * `fourmm config` command group — manage ~/.fourmm/config.json.
+ *
+ * Subcommands:
+ *   - init: create config file with defaults (or overrides)
+ *   - set <key> <value>: update a single value
+ *   - get [key]: read one value or the whole config
+ */
+import { Cli } from 'incur';
+export declare const config: Cli.Cli<{
+    init: {
+        args: {};
+        options: {
+            rpcUrl?: string | undefined;
+            network?: "bsc" | "bsc-testnet" | undefined;
+            slippageBps?: number | undefined;
+        };
+    };
+} & {
+    set: {
+        args: {
+            key: string;
+            value: string;
+        };
+        options: {};
+    };
+} & {
+    get: {
+        args: {};
+        options: {
+            key?: string | undefined;
+        };
+    };
+}, undefined, undefined>;
+//# sourceMappingURL=config.d.ts.map

package/dist/commands/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/commands/config.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,GAAG,EAAK,MAAM,OAAO,CAAA;AAS9B,eAAO,MAAM,MAAM;;;;;;;;;;;;;;;;;;;;;;;;wBAqIf,CAAA"}