@four-meme/four-meme-ai 1.0.0

package/CLAUDE.md

@@ -0,0 +1,91 @@
+# four-meme-ai – Agent Guidelines (Claude / Claude Code)
+
+## Overview
+
+This repo provides the **four-meme-integration** skill for AI agents: create and trade meme tokens on **four.meme (BSC only)** using the official API and on-chain contracts (**TokenManager2**, **TokenManagerHelper3**). TokenManager V1 is **not** supported by this skill.
+
+The authoritative specification for this skill is `skills/four-meme-integration/SKILL.md`. Claude/Claude Code should treat that file as the main contract for behavior, safety, and command usage.
+
+## When to Use This Skill
+
+Use this repo when the user explicitly or implicitly asks to:
+
+- **Create** a meme token on four.meme on BSC (full API flow + `TokenManager2.createToken` on-chain).
+- **Buy** or **sell** a four.meme token on BSC (quote with Helper3, execute via TokenManager2).
+- **Query token info** (version, tokenManager, price, offers, etc.) for a given token address or requestId.
+- **Query lists / rankings** of four.meme tokens (REST list, detail, advanced rankings).
+- **Query Tax token fee/tax config**, or execute Tax-type token creation.
+- **Send BNB / ERC20** from the trading wallet to another address on BSC.
+- **Register / query** an EIP‑8004 identity NFT (8004 registry contract on BSC).
+
+If the user’s request does not involve four.meme, BSC, or these flows, you should not use this skill.
+
+## Repo Layout
+
+```
+four-meme-ai/
+├── skills/
+│   └── four-meme-integration/
+│       ├── SKILL.md        # Main skill instructions (Cursor / OpenClaw)
+│       ├── references/     # API, addresses, errors, trading, events, tax
+│       └── scripts/        # create-token, get-token-info, quote-buy/sell, etc.
+├── bin/
+│   └── fourmeme.cjs        # CLI dispatcher (fourmeme ...)
+├── package.json
+├── README.md
+└── CLAUDE.md               # This file (Claude-facing guidelines)
+```
+
+## Safety and Private Key Handling
+
+The SKILL defines a **User Agreement & Security Notice** (bilingual: English + Traditional Chinese). Claude MUST:
+
+1. On first use of this skill in a conversation, present the User Agreement and Security Notice in the user’s language (use the 繁體中文 block when the user writes in Traditional Chinese; otherwise use English).
+2. Make clear that **continuing to use this plugin/skill implies acceptance of the User Agreement**.
+3. **MUST NOT** run any operation that uses a private key or writes on-chain (e.g. `create-api`, `create-chain`, `buy`, `sell`, `send`, `8004-register`) until the user has explicitly agreed or confirmed to continue.
+4. May run read‑only commands (e.g. `config`, `token-info`, `quote-buy`, `8004-balance`) while or after presenting the notice.
+
+Never ask the user to paste a private key into chat. All private keys must come from environment / config (e.g. `PRIVATE_KEY`, `FOURMEME_PRIVATE_KEY`) as described in `SKILL.md`.
+
+## Conventions (aligned with SKILL.md)
+
+1. **Chain**: BSC only (chainId 56). Arbitrum and Base are **out of scope** for this skill.
+2. **Trading**:
+   - Always call Helper3 `getTokenInfo(token)` first to get `version`, `tokenManager`, and current price/offers.
+   - Only **version 2** (TokenManager2) is supported by this skill; do not attempt V1 flows.
+   - For X Mode / TaxToken / AntiSniperFeeMode detection and error codes, see `skills/four-meme-integration/references/errors.md`.
+3. **Create token**:
+   - `raisedToken` must always come from `GET https://four.meme/meme-api/v1/public/config` and be used **as is** in the create body; do not invent or modify internal fields.
+   - For tax-type tokens, follow `tokenTaxInfo` constraints in `references/token-tax-info.md` and the interactive flow in `SKILL.md` (“Create token (full flow)”).
+4. **RPC**:
+   - Use env `BSC_RPC_URL` when set; otherwise fall back to public BSC RPC defaults (see scripts).
+   - Private key envs: `PRIVATE_KEY` or `FOURMEME_PRIVATE_KEY` (no key should ever be requested from the user in plain text).
+
+## CLI Usage (fourmeme)
+
+From the project root after `npm install`, use:
+
+```bash
+npx fourmeme <command> [args...]
+```
+
+Key commands (full list and parameters in `SKILL.md`):
+
+- `fourmeme config` – Get public config (raisedToken).
+- `fourmeme create-api` / `fourmeme create-chain` – Create token (API + on-chain).
+- `fourmeme token-info` / `token-list` / `token-get` / `token-rankings` – On-chain info and REST queries.
+- `fourmeme quote-buy` / `quote-sell` – Estimate buy/sell without sending tx.
+- `fourmeme buy` / `sell` – Execute buy/sell via TokenManager2 (V2 only).
+- `fourmeme send` – Send BNB or ERC20 from the trading wallet.
+- `fourmeme 8004-register` / `8004-balance` – EIP‑8004 identity NFT register and query.
+- `fourmeme events` – TokenManager2 events (TokenCreate, TokenPurchase, TokenSale, LiquidityAdded).
+- `fourmeme tax-info` – TaxToken on-chain fee/tax config.
+
+Always prefer these CLI commands rather than calling scripts directly, unless `SKILL.md` suggests otherwise.
+
+## External Docs
+
+For deeper protocol details, see:
+
+- In-repo: `skills/four-meme-integration/references/` (api-create-token, token-query-api, execute-trade, event-listening, tax-token-query, errors).
+- Official four.meme API and contracts (online): [Protocol Integration](https://four-meme.gitbook.io/four.meme/brand/protocol-integration) (API documents, ABIs: TokenManager, TokenManager2, Helper3, TaxToken, etc.).

package/README.md

@@ -0,0 +1,79 @@
+# four-meme-ai
+
+Four.meme AI skills for creating and trading meme tokens on **BSC only**. Lets agents integrate with [four.meme](https://four.meme) for token creation, buy/sell flows, Tax tokens, transfers, and EIP‑8004 identity NFTs.
+
+## Skills
+
+| Skill | Description |
+|-------|-------------|
+| `four-meme-integration` | Create/trade meme tokens on **BSC only**, query token info/lists/rankings, listen to TokenManager2 events, query TaxToken tax info, send BNB/ERC20, and register/query EIP‑8004 identity NFTs. TokenManager V1 is not supported. |
+
+Safety, user agreement, and detailed agent behavior requirements are defined in [`skills/four-meme-integration/SKILL.md`](skills/four-meme-integration/SKILL.md) (bilingual User Agreement & Security Notice). Claude-specific guidance lives in [`CLAUDE.md`](CLAUDE.md).
+
+## Usage (Agent)
+
+When the user needs to create or trade meme tokens on four.meme (BSC), use the **four-meme-integration** skill:
+
+- **Create token (API + chain)**: Prefer the CLI flow `fourmeme create-api ...` → `fourmeme create-chain ...`. Under the hood this runs: `get-public-config.ts` (optional) → `create-token-api.ts` (image + name/symbol/desc/label, env `PRIVATE_KEY`) → `create-token-chain.ts` (createArg + signature from API). Creation is BSC only; no extra BNB is sent by default (set `CREATION_FEE_WEI` to attach a value if needed). See `SKILL.md` and `references/api-create-token.md` / `create-token-scripts.md` for full details and required user questions.
+- **Trade (buy/sell)**: Use Helper3 `getTokenInfo` to get version and tokenManager; only version 2 (TokenManager2) is supported. Use `fourmeme quote-buy`/`quote-sell` for estimates, then `fourmeme buy`/`sell` to execute. **BSC only.**
+- **Event listening**: `fourmeme events <fromBlock> [toBlock]` to fetch TokenCreate, TokenPurchase, TokenSale, LiquidityAdded from TokenManager2. See `references/event-listening.md`.
+- **Tax token fee/tax info**: `fourmeme tax-info <tokenAddress>`. See `references/tax-token-query.md` and `token-tax-info.md`.
+- **Send BNB/ERC20**: `fourmeme send <toAddress> <amountWei> [tokenAddress]` to transfer from the trading wallet.
+- **EIP‑8004 identity NFT**: `fourmeme 8004-register <name> [imageUrl] [description]` and `fourmeme 8004-balance <ownerAddress>`.
+- **CLI** (after `npm install`): use **`npx fourmeme <command> [args]`**. Run `npx fourmeme --help` for all commands, including:\n  - Config: `npx fourmeme config`\n  - Create: `npx fourmeme create-api ...` → `npx fourmeme create-chain ...`\n  - Trade/info: `npx fourmeme token-info <tokenAddress>`, `npx fourmeme quote-buy`, `npx fourmeme quote-sell`\n  - Execute trade: `npx fourmeme buy <token> amount|funds ...`, `npx fourmeme sell <token> <amountWei> [minFundsWei]` (needs PRIVATE_KEY)\n  - Events: `npx fourmeme events <fromBlock> [toBlock]`\n  - Tax: `npx fourmeme tax-info <tokenAddress>`\n  - EIP‑8004: `npx fourmeme 8004-register ...`, `npx fourmeme 8004-balance ...`\n  - Verify: `npx fourmeme verify`\n\n## Install (project)
+
+```bash
+cd four-meme-ai
+npm install
+```
+
+## Install as OpenClaw plugin
+
+This repo is an [OpenClaw](https://docs.openclaw.ai)-compatible plugin. Install so the skill is loaded and **PRIVATE_KEY / BSC_RPC_URL** are only injected for this skill (via `skills.entries`):
+
+```bash
+openclaw plugins install /path/to/four-meme-ai
+# or from npm (if published): openclaw plugins install @scope/four-meme-ai
+```
+
+Then in `~/.openclaw/openclaw.json` set:
+
+```json5
+{
+  skills: {
+    entries: {
+      "four-meme-integration": {
+        enabled: true,
+        env: {
+          PRIVATE_KEY: "0x...",
+          BSC_RPC_URL: "https://bsc-dataseed.binance.org"
+        }
+      }
+    }
+  }
+}
+```
+
+See [skills/four-meme-integration/SKILL.md](skills/four-meme-integration/SKILL.md) for the full OpenClaw config section and environment variable details.
+
+## Verify the skill (read-only)
+
+After `npm install`, run:
+
+```bash
+npx fourmeme verify
+```
+(In project dir, use `npx fourmeme`; or run `npm link` then `fourmeme` from anywhere.)
+
+This runs **config** (four.meme API) and **events** for the last 50 blocks on BSC. No private key or on-chain writes. For full verification steps, see [VERIFICATION.md](VERIFICATION.md).
+
+## Docs
+
+- Skill instructions (agent behavior, safety, flows): `skills/four-meme-integration/SKILL.md`
+- Claude/Claude Code guidelines: `CLAUDE.md`
+- References: `skills/four-meme-integration/references/` (API, contract addresses, trading, events, tax, errors)
+- Official four.meme API and contracts: [Protocol Integration](https://four-meme.gitbook.io/four.meme/brand/protocol-integration) (API documents, ABIs)
+
+## License
+
+MIT

package/bin/fourmeme.cjs

@@ -0,0 +1,124 @@
+#!/usr/bin/env node
+/**
+ * fourmeme CLI - dispatches to four-meme-integration scripts.
+ * Usage: fourmeme <command> [args...]
+ * Run "fourmeme --help" for commands.
+ */
+const { spawnSync } = require('child_process');
+const path = require('path');
+
+const root = path.join(__dirname, '..');
+const scriptsDir = path.join(root, 'skills', 'four-meme-integration', 'scripts');
+
+const commands = {
+  config: 'get-public-config.ts',
+  'create-api': 'create-token-api.ts',
+  'create-chain': 'create-token-chain.ts',
+  'token-info': 'get-token-info.ts',
+  'token-list': 'token-list.ts',
+  'token-get': 'token-get.ts',
+  'token-rankings': 'token-rankings.ts',
+  'quote-buy': 'quote-buy.ts',
+  'quote-sell': 'quote-sell.ts',
+  buy: 'execute-buy.ts',
+  sell: 'execute-sell.ts',
+  send: 'send-token.ts',
+  '8004-register': '8004-register.ts',
+  '8004-balance': '8004-balance.ts',
+  events: 'get-recent-events.ts',
+  'tax-info': 'get-tax-token-info.ts',
+  verify: null, // special: run config + verify-events
+};
+
+function run(scriptName, args = []) {
+  const scriptPath = path.join(scriptsDir, scriptName);
+  const result = spawnSync('npx', ['tsx', scriptPath, ...args], {
+    stdio: 'inherit',
+    shell: true,
+    cwd: root,
+  });
+  process.exit(result.status ?? 1);
+}
+
+function printHelp() {
+  console.log(`fourmeme - Four.meme CLI (BSC only)
+
+Usage: npx fourmeme <command> [args...]
+
+(In project dir, use npx fourmeme; npm install does not add fourmeme to PATH.)
+
+Commands:
+  config                    Get public config (raisedToken). No auth.
+  create-api <img> <name> <symbol> <desc> <label> [tax.json]
+                            Create token API flow. Env: PRIVATE_KEY.
+  create-chain <createArgHex> <signatureHex>
+                            Submit createToken tx on BSC. Or: fourmeme create-chain -- (stdin JSON)
+  token-info <tokenAddress>
+                            Get token info from Helper3 (BSC, on-chain).
+  token-list [--orderBy=Hot] [--pageIndex=1] [--pageSize=30] [--tokenName=] [--symbol=] [--labels=] [--listedPancake=false]
+                            Token list (REST API, filter/query).
+  token-get <tokenAddress>
+                            Token detail + trading info (REST API get/v2).
+  token-rankings <orderBy> [--barType=HOUR24]
+                            Rankings: orderBy=Time|ProgressDesc|TradingDesc|Hot|Graduated. barType only for TradingDesc.
+  quote-buy <token> <amountWei> [fundsWei]
+                            Estimate buy (no tx). Use 0 for amount or funds.
+  quote-sell <token> <amountWei>
+                            Estimate sell (no tx).
+  buy <token> amount <amountWei> <maxFundsWei>
+                            Execute buy: fixed token amount. Env: PRIVATE_KEY.
+  buy <token> funds <fundsWei> <minAmountWei>
+                            Execute buy: spend fixed quote (e.g. BNB). Env: PRIVATE_KEY.
+  sell <token> <amountWei> [minFundsWei]
+                            Execute sell. Env: PRIVATE_KEY.
+  send <toAddress> <amountWei> [tokenAddress]
+                            Send BNB or ERC20 to address. Omit tokenAddress for BNB. Env: PRIVATE_KEY.
+  8004-register <name> [imageUrl] [description]
+                            EIP-8004: register identity NFT. Env: PRIVATE_KEY.
+  8004-balance <ownerAddress>
+                            EIP-8004: query NFT balance of address (read-only).
+  events <fromBlock> [toBlock]
+                            TokenManager2 events (BSC). Default toBlock: latest.
+  tax-info <tokenAddress>
+                            TaxToken fee/tax config (BSC, creatorType 5 only).
+  verify                    Run config + events for last 50 blocks (read-only check).
+
+Env: PRIVATE_KEY, BSC_RPC_URL. See SKILL.md for full docs.
+`);
+}
+
+const argv = process.argv.slice(2);
+const cmd = argv[0];
+
+if (!cmd || cmd === '--help' || cmd === '-h' || cmd === 'help') {
+  printHelp();
+  process.exit(0);
+}
+
+if (cmd === 'verify') {
+  const r1 = spawnSync('npx', ['tsx', path.join(scriptsDir, 'get-public-config.ts')], {
+    stdio: 'inherit',
+    shell: true,
+    cwd: root,
+  });
+  if (r1.status !== 0) process.exit(r1.status ?? 1);
+  const r2 = spawnSync('npx', ['tsx', path.join(scriptsDir, 'verify-events.ts')], {
+    stdio: 'inherit',
+    shell: true,
+    cwd: root,
+  });
+  process.exit(r2.status ?? 1);
+}
+
+const script = commands[cmd];
+if (!script) {
+  console.error(`Unknown command: ${cmd}`);
+  printHelp();
+  process.exit(1);
+}
+
+if (cmd === 'events') {
+  run(script, ['56', ...argv.slice(1)]);
+} else {
+  run(script, argv.slice(1));
+}

package/openclaw.plugin.json

@@ -0,0 +1,11 @@
+{
+  "id": "four-meme-ai",
+  "name": "Four.meme AI",
+  "description": "Create and trade meme tokens on four.meme (BSC). CLI fourmeme + skill.",
+  "skills": ["skills/four-meme-integration"],
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "description": "No plugin-level config; use skills.entries[\"four-meme-ai\"].env for PRIVATE_KEY."
+  }
+}

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@four-meme/four-meme-ai",
+  "version": "1.0.0",
+  "description": "Four.meme AI skills for creating and trading meme tokens (BSC only)",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "fourmeme": "./bin/fourmeme.cjs"
+  },
+  "openclaw": {
+    "extensions": [
+      "./plugin.ts"
+    ]
+  },
+  "scripts": {
+    "fourmeme": "node bin/fourmeme.cjs",
+    "verify": "tsx skills/four-meme-integration/scripts/get-public-config.ts && tsx skills/four-meme-integration/scripts/verify-events.ts",
+    "build": "tsc",
+    "config": "tsx skills/four-meme-integration/scripts/get-public-config.ts",
+    "create-api": "tsx skills/four-meme-integration/scripts/create-token-api.ts",
+    "create-chain": "tsx skills/four-meme-integration/scripts/create-token-chain.ts",
+    "token-info": "tsx skills/four-meme-integration/scripts/get-token-info.ts",
+    "token-list": "tsx skills/four-meme-integration/scripts/token-list.ts",
+    "token-get": "tsx skills/four-meme-integration/scripts/token-get.ts",
+    "token-rankings": "tsx skills/four-meme-integration/scripts/token-rankings.ts",
+    "quote-buy": "tsx skills/four-meme-integration/scripts/quote-buy.ts",
+    "quote-sell": "tsx skills/four-meme-integration/scripts/quote-sell.ts",
+    "buy": "tsx skills/four-meme-integration/scripts/execute-buy.ts",
+    "sell": "tsx skills/four-meme-integration/scripts/execute-sell.ts",
+    "send": "tsx skills/four-meme-integration/scripts/send-token.ts",
+    "8004-register": "tsx skills/four-meme-integration/scripts/8004-register.ts",
+    "8004-balance": "tsx skills/four-meme-integration/scripts/8004-balance.ts",
+    "events": "tsx skills/four-meme-integration/scripts/get-recent-events.ts",
+    "tax-info": "tsx skills/four-meme-integration/scripts/get-tax-token-info.ts"
+  },
+  "keywords": [
+    "four.meme",
+    "meme",
+    "token",
+    "bsc",
+    "agent",
+    "skill",
+    "openclaw"
+  ],
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "tsx": "^4.20.0",
+    "typescript": "^5.0.0",
+    "viem": "^2.0.0"
+  },
+  "dependencies": {
+    "four-meme-ai": "^1.0.0"
+  },
+  "publishConfig": { "access": "public" }
+}

package/plugin.ts

@@ -0,0 +1,7 @@
+/**
+ * OpenClaw plugin entry for four-meme-ai.
+ * Skills are declared in openclaw.plugin.json; env (PRIVATE_KEY, BSC_RPC_URL) is configured per-skill in skills.entries.
+ */
+export default function (_api: unknown) {
+  // No runtime registration needed; skills are loaded from manifest.
+}