@four-meme/four-meme-ai 1.0.4 → 1.0.6

package/CLAUDE.md

@@ -1,91 +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`) 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 and private key (environment)**:
-   - When **using OpenClaw**: PRIVATE_KEY and BSC_RPC_URL are configured in OpenClaw (e.g. `skills.entries["four-meme-ai"].env` or apiKey); see SKILL.md.
-   - When **not using OpenClaw (standalone)**: set `PRIVATE_KEY` and optionally `BSC_RPC_URL` via the process environment—e.g. a `.env` file in the **directory where you run `fourmeme`** (the CLI loads it automatically via dotenv) or shell `export`. Do not ask the user to paste a private key in chat.
-
-## 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.).
+# 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`) 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 and private key (environment)**:
+   - When **using OpenClaw**: PRIVATE_KEY and BSC_RPC_URL are configured in OpenClaw (e.g. `skills.entries["four-meme-ai"].env` or apiKey); see SKILL.md.
+   - When **not using OpenClaw (standalone)**: set `PRIVATE_KEY` and optionally `BSC_RPC_URL` via the process environment—e.g. a `.env` file in the **directory where you run `fourmeme`** (the CLI loads it automatically via dotenv) or shell `export`. Do not ask the user to paste a private key in chat.
+
+## 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

@@ -1,108 +1,136 @@
-# 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
-```
-
-## Environment variables (without OpenClaw)
-
-When you **do not** use OpenClaw, the CLI reads `PRIVATE_KEY` and `BSC_RPC_URL` from the process environment. Set them in one of these ways:
-
-**Option 1: `.env` file in the project root**
-
-Create a file named `.env` in the repo root (same directory as `package.json`):
-
-```bash
-# .env (do not commit this file)
-PRIVATE_KEY=your_hex_private_key_with_or_without_0x_prefix
-BSC_RPC_URL=https://bsc-dataseed.binance.org
-```
-
-Then run commands so that the shell loads `.env` before invoking `fourmeme` (e.g. use a tool that loads `.env`, or `export $(cat .env | xargs)` then `npx fourmeme ...`). The scripts themselves do not load `.env`; you must ensure the variables are in the environment when `npx fourmeme` runs.
-
-**Option 2: export in the shell**
-
-```bash
-export PRIVATE_KEY=your_hex_private_key
-export BSC_RPC_URL=https://bsc-dataseed.binance.org
-npx fourmeme create-api ./logo.png MyToken MTK "Desc" AI
-```
-
-- **PRIVATE_KEY**: Required for any command that signs or sends a transaction (create-api, create-chain, buy, sell, send, 8004-register). Hex string; `0x` prefix optional.
-- **BSC_RPC_URL**: Optional. BSC RPC endpoint; if unset, scripts use a default public BSC RPC.
-
-**Security**: Do not commit `.env` or share your private key. Add `.env` to `.gitignore` if you use a `.env` file.
-
-## 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-ai": {
-        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
+# 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)**: Use **`fourmeme create-instant ...`** for one-shot create (API + submit createToken in one command), or the two-step flow `fourmeme create-api ...` → `fourmeme create-chain ...`. Both use the same args: `--image=`, `--name=`, `--short-name=`, `--desc=`, `--label=` (and optional `--pre-sale=<BNB>` in ether units, `--web-url=`, etc.). Creation is BSC only; value (launch fee + presale if any) is computed automatically for create-instant. See `SKILL.md` and `references/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**: `npx fourmeme <command> [args]`. Run `npx fourmeme --help` for the full list. See **Commands and parameters** below.
+
+## Commands and parameters
+
+| Command | Parameters | Description |
+|--------|------------|-------------|
+| `config` | *(none)* | Public config (raisedToken). No auth. |
+| `create-api` | `--image=` `--name=` `--short-name=` `--desc=` `--label=` `[--web-url=]` `[--twitter-url=]` `[--telegram-url=]` `[--pre-sale=<BNB>]` `[--fee-plan=false]` `[--tax-options=<path>]` or `[--tax-token --tax-fee-rate=5 ...]` | Create token API only. Label: `Meme|AI|Defi|Games|Infra|De-Sci|Social|Depin|Charity|Others`. Env: PRIVATE_KEY. |
+| `create-chain` | `<createArgHex>` `<signatureHex>` `[--value=<wei>]` or `--` (stdin JSON) | Submit createToken on BSC. Env: PRIVATE_KEY. |
+| `create-instant` | `--image=` `--name=` `--short-name=` `--desc=` `--label=` `[--web-url=]` `[--twitter-url=]` `[--telegram-url=]` `[--pre-sale=<BNB>]` `[--fee-plan=false]` `[--value=<wei>]` `[--tax-options=<path>]` or `[--tax-token --tax-fee-rate=5 ...]` | One-shot create (API + chain). Same options as create-api plus `--value=` override. Env: PRIVATE_KEY. |
+| `token-info` | `<tokenAddress>` | On-chain token info (Helper3). |
+| `token-list` | `[--orderBy=Hot]` `[--pageIndex=1]` `[--pageSize=30]` `[--tokenName=]` `[--symbol=]` `[--labels=]` `[--listedPancake=false]` | REST token list. |
+| `token-get` | `<tokenAddress>` | REST token detail + trading info. |
+| `token-rankings` | `<orderBy>` `[--barType=HOUR24]` | Rankings. orderBy: `Time|ProgressDesc|TradingDesc|Hot|Graduated`. |
+| `quote-buy` | `<tokenAddress>` `<amountWei>` `[fundsWei]` | Estimate buy (no tx). Use 0 for amount or funds. |
+| `quote-sell` | `<tokenAddress>` `<amountWei>` | Estimate sell (no tx). |
+| `buy` | `<token>` `amount` `<amountWei>` `<maxFundsWei>` | Buy fixed amount. Env: PRIVATE_KEY. |
+| `buy` | `<token>` `funds` `<fundsWei>` `<minAmountWei>` | Buy with fixed quote. Env: PRIVATE_KEY. |
+| `sell` | `<tokenAddress>` `<amountWei>` `[minFundsWei]` | Execute sell. Env: PRIVATE_KEY. |
+| `send` | `<toAddress>` `<amountWei>` `[tokenAddress]` | Send BNB or ERC20. Omit tokenAddress for BNB. Env: PRIVATE_KEY. |
+| `8004-register` | `<name>` `[imageUrl]` `[description]` | EIP-8004 register NFT. Env: PRIVATE_KEY. |
+| `8004-balance` | `<ownerAddress>` | EIP-8004 query balance. |
+| `events` | `<fromBlock>` `[toBlock]` | TokenManager2 events (BSC). |
+| `tax-info` | `<tokenAddress>` | TaxToken fee/tax config. |
+| `verify` | *(none)* | Config + events (last 50 blocks). Read-only. |
+
+Create token optional (omit if empty): `--web-url=`, `--twitter-url=`, `--telegram-url=`. Presale: `--pre-sale=<BNB>` in ether (e.g. `0.001`). Tax: `--tax-options=<path>` or `--tax-token --tax-fee-rate=5 --tax-burn-rate=0 --tax-divide-rate=0 --tax-liquidity-rate=100 --tax-recipient-rate=0 --tax-recipient-address= --tax-min-sharing=100000` (burn+divide+liquidity+recipient=100).
+
+## Install (project)
+
+```bash
+cd four-meme-ai
+npm install
+```
+
+## Environment variables (without OpenClaw)
+
+When you **do not** use OpenClaw, the CLI reads `PRIVATE_KEY` and `BSC_RPC_URL` from the process environment. Set them in one of these ways:
+
+**Option 1: `.env` file in the project root**
+
+Create a file named `.env` in the repo root (same directory as `package.json`):
+
+```bash
+# .env (do not commit this file)
+PRIVATE_KEY=your_hex_private_key_with_or_without_0x_prefix
+BSC_RPC_URL=https://bsc-dataseed.binance.org
+```
+
+Then run commands so that the shell loads `.env` before invoking `fourmeme` (e.g. use a tool that loads `.env`, or `export $(cat .env | xargs)` then `npx fourmeme ...`). The scripts themselves do not load `.env`; you must ensure the variables are in the environment when `npx fourmeme` runs.
+
+**Option 2: export in the shell**
+
+```bash
+export PRIVATE_KEY=your_hex_private_key
+export BSC_RPC_URL=https://bsc-dataseed.binance.org
+npx fourmeme create-instant --image=./logo.png --name=MyToken --short-name=MTK --desc="Desc" --label=AI
+```
+
+- **PRIVATE_KEY**: Required for any command that signs or sends a transaction (create-api, create-chain, buy, sell, send, 8004-register). Hex string; `0x` prefix optional.
+- **BSC_RPC_URL**: Optional. BSC RPC endpoint; if unset, scripts use a default public BSC RPC.
+
+**Security**: Do not commit `.env` or share your private key. Add `.env` to `.gitignore` if you use a `.env` file.
+
+## 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-ai": {
+        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