skillpp 0.1.0

package/skills/four-meme/four-meme-ai/references/create-token-scripts.md

@@ -0,0 +1,131 @@
+# Create Token Scripts (Four.meme)
+
+**Recommended:** Use `fourmeme create-instant` for one-shot token creation (API + on-chain in one command). Use the step-by-step flow only when you need to inspect or modify the API output before submitting on-chain.
+
+## One-shot (create-instant) — recommended
+
+**create-token-instant.ts** runs API create + on-chain submit in one command. Same args as create-token-api; on success submits createToken and outputs `txHash`.
+
+- All options as `--key=value`; no positionals.
+- **Required**: `--image=`, `--name=`, `--short-name=`, `--desc=`, `--label=`.
+- **Optional**: `--web-url=`, `--twitter-url=`, `--telegram-url=` (only sent when non-empty); `--pre-sale=0` (**presale in ether units**, e.g. `0.001` for 0.001 BNB, not wei); `--fee-plan=false`, `--tax-options=<path>`; `--value=<wei>` (default to be auto calculated, override BNB value sent; otherwise API output `creationFeeWei` is used).
+- **Tax token**: `--tax-options=tax.json` or `--tax-token` with `--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).
+- **Label** (exactly one): `Meme` | `AI` | `Defi` | `Games` | `Infra` | `De-Sci` | `Social` | `Depin` | `Charity` | `Others`.
+- **Env**: `PRIVATE_KEY`; RPC via `BSC_RPC_URL`.
+- **Flow**: nonce → login → upload image → GET public config → POST create → submit `TokenManager2.createToken` on BSC.
+- **Output**: JSON `{ "txHash" }`.
+
+```bash
+# Via CLI (recommended)
+fourmeme create-instant --image=./logo.png --name=MyToken --short-name=MTK --desc="My desc" --label=AI
+
+# With presale (BNB, ether units)
+fourmeme create-instant --image=./logo.png --name=MyToken --short-name=MTK --desc="My desc" --label=AI --pre-sale=0.001
+
+# Tax token
+fourmeme create-instant --image=./logo.png --name=TaxToken --short-name=TAX --desc="Tax" --label=Meme --tax-options=tax.json
+```
+
+---
+
+## Step-by-step flow (create-api → create-chain)
+
+1. **get-public-config.ts** (optional)  
+   Fetches `raisedToken` from `https://four.meme/meme-api/v1/public/config`. Use when building the create body manually.
+
+2. **create-token-api.ts**  
+   - All options as `--key=value`; no positionals.  
+   - Required: `--image=`, `--name=`, `--short-name=`, `--desc=`, `--label=`.  
+   - Optional: `--web-url=`, `--twitter-url=`, `--telegram-url=` (only sent when non-empty); `--pre-sale=0` (**presale in ether units**, e.g. `0.001` for 0.001 BNB, not wei); `--fee-plan=false`, `--tax-options=<path>`.  
+   - Tax token: `--tax-options=tax.json` or `--tax-token` with `--tax-fee-rate=5` etc. (burn+divide+liquidity+recipient=100).  
+   - Env: `PRIVATE_KEY`; RPC via `BSC_RPC_URL`.  
+   - Flow: nonce → login → upload image → GET public config → POST create.  
+   - Output: JSON `{ "createArg", "signature", "creationFeeWei" }`; script hints required value for chain step.
+
+3. **create-token-chain.ts**  
+   - Env: `PRIVATE_KEY`.  
+   - Input: `createArg`, `signature` (positional or stdin JSON with `--`).  
+   - Optional (CLI overrides env): `--value=<wei>` (env `CREATION_FEE_WEI`). RPC via env `BSC_RPC_URL`.  
+   - Calls `TokenManager2.createToken(createArg, sign)`; excess BNB is refunded by the contract.
+
+## createToken value (CREATION_FEE_WEI) formula
+
+**Formula**
+
+- **No presale (or quote is ERC20)**  
+  `value = launch_fee`  
+  `launch_fee`: read from TokenManager2 `_launchFee()` (wei).
+
+- **With presale and quote is BNB**  
+  `value = launch_fee + presale_wei + trading_fee`  
+  - `presale_wei`: presale amount in wei (API sends preSale in BNB/ether; script converts to wei for value).  
+  - `trading_fee`: see below.
+
+**How to compute trading_fee**
+
+- Contract uses basis-point rate: `trading_fee = presale_wei × fee_rate / 10000` (integer division).  
+- `fee_rate` from TokenManager2 `_tradingFeeRate()` (basis points).  
+- If the contract enforces a minimum fee per trade, use `max(computed trading_fee, minimum_fee)`.
+
+## Example (instant, recommended)
+
+```bash
+export PRIVATE_KEY=your_hex_private_key
+fourmeme create-instant --image=./logo.png --name=MyToken --short-name=MTK --desc="My desc" --label=AI
+```
+
+## Example (piped)
+
+```bash
+export PRIVATE_KEY=your_hex_private_key
+npx tsx skills/four-meme-integration/scripts/create-token-api.ts --image=./logo.png --name=MyToken --short-name=MTK --desc="My desc" --label=AI \
+  | npx tsx skills/four-meme-integration/scripts/create-token-chain.ts --
+```
+
+The chain script reads `creationFeeWei` from stdin JSON when present; you can also pass `--value=<wei>` explicitly.
+
+## Example (two steps)
+
+```bash
+export PRIVATE_KEY=your_hex_private_key
+npx tsx skills/four-meme-integration/scripts/create-token-api.ts --image=./logo.png --name=MyToken --short-name=MTK --desc="My desc" --label=AI > create-out.json
+npx tsx skills/four-meme-integration/scripts/create-token-chain.ts "$(jq -r .createArg create-out.json)" "$(jq -r .signature create-out.json)" --value=$(jq -r .creationFeeWei create-out.json)
+```
+
+## Example (with presale)
+
+`--pre-sale` is in **ether units** (e.g. `0.001` = 0.001 BNB; do not pass wei).
+
+```bash
+npx tsx .../create-token-api.ts --image=./logo.png --name=MyToken --short-name=MTK --desc="My desc" --label=AI --pre-sale=0.01
+```
+
+## Tax token
+
+Tax options file must contain `tokenTaxInfo`. Example **tax-options.json**:
+
+```json
+{
+  "tokenTaxInfo": {
+    "feeRate": 5,
+    "burnRate": 20,
+    "divideRate": 30,
+    "liquidityRate": 40,
+    "recipientRate": 10,
+    "recipientAddress": "0x1234567890123456789012345678901234567890",
+    "minSharing": 100000
+  }
+}
+```
+
+`feeRate` must be 1, 3, 5, or 10; burn+divide+liquidity+recipient=100. See [token-tax-info.md](token-tax-info.md).
+
+```bash
+# Option A: --tax-options= path to JSON file
+npx tsx .../create-token-api.ts --image=./logo.png --name=TaxToken --short-name=TAX --desc="Tax token" --label=AI --tax-options=tax-options.json
+
+# Option B: --tax-token with rate args
+npx tsx .../create-token-api.ts --image=./logo.png --name=TaxToken --short-name=TAX --desc="Tax token" --label=AI --tax-token --tax-fee-rate=5 --tax-burn-rate=20 --tax-divide-rate=30 --tax-liquidity-rate=40 --tax-recipient-rate=10 --tax-recipient-address=0x... --tax-min-sharing=100000
+```
+
+Chain and Labels: see [SKILL.md](../SKILL.md) or [api-create-token.md](api-create-token.md).

package/skills/four-meme/four-meme-ai/references/errors.md

@@ -0,0 +1,29 @@
+# Four.meme Error Codes
+
+## buyToken
+
+| Code       | Meaning |
+|-----------|---------|
+| GW (GWEI) | Amount precision not aligned to GWEI |
+| ZA        | Zero Address – `to` must not be address(0) |
+| TO        | Invalid to – `to` must not be PancakePair address |
+| Slippage  | Spent amount > maxFunds |
+| More BNB  | Insufficient BNB in msg.value |
+| A         | X Mode token bought with wrong method – use X Mode buy |
+
+## sellToken
+
+| Code      | Meaning |
+|----------|---------|
+| GW (GWEI)| Amount precision not aligned to GWEI |
+| FR (FeeRate) | Fee rate > 5% |
+| SO (Small Order) | Order amount too small |
+| Slippage | Received amount < minFunds |
+
+## Identification
+
+- **X Mode (exclusive)**: Off-chain – API token info `version === "V8"`. On-chain – `TokenManager2._tokenInfos[token].template & 0x10000 > 0`.
+- **TaxToken**: Off-chain – API response has `taxInfo`. On-chain – `(template >> 10) & 0x3F === 5`.
+- **AntiSniperFeeMode**: Off-chain – API `feePlan === true`. On-chain – `TokenManager2._tokenInfoEx1s[token].feeSetting > 0`.
+- **Token created by Agent Creator**: Off-chain – API `data.aiCreator === true`. On-chain – `(TokenManager2._tokenInfos[token].template & (1 << 85)) != 0`. Does not change trading behavior.
+- **Agent wallets**: Call **AgentIdentifier.isAgent(wallet)** on BSC; see [agent-creator-and-wallets.md](agent-creator-and-wallets.md) and [contract-addresses.md](contract-addresses.md).

package/skills/four-meme/four-meme-ai/references/event-listening.md

@@ -0,0 +1,75 @@
+# Event listening (TokenManager2, V2 only)
+
+Only **TokenManager2 (V2)** is supported. V1 is not supported. Contract address (BSC): `0x5c952063c7fc8610FFDB798152D69F0B9550762b`.
+
+The agent can react to **token creation, buy/sell, and liquidity add** by listening to the events below (e.g. copy-trading).
+
+## Event list
+
+| Event           | Meaning           | Main args                                                                 |
+|-----------------|-------------------|---------------------------------------------------------------------------|
+| **TokenCreate** | New token created | `creator`, `token`, `requestId`, `name`, `symbol`, `totalSupply`, `launchTime`, `launchFee` |
+| **TokenPurchase** | Buy             | `token`, `account`, `price`, `amount`, `cost`, `fee`, `offers`, `funds`   |
+| **TokenSale**   | Sell              | `token`, `account`, `price`, `amount`, `cost`, `fee`, `offers`, `funds`   |
+| **LiquidityAdded** | Liquidity added | `base`, `offers`, `quote`, `funds`                                        |
+
+- **TokenCreate**: With `token` (new token address) and `requestId`, you can call Helper3 `getTokenInfo(token)` or execute buy/sell immediately.
+- **TokenPurchase / TokenSale**: Use for copy-trading, stats, etc.; `token` is the token address, `account` is the buyer/seller.
+- **LiquidityAdded**: `base` is the token address; the token has been added to the pool and can be traded on the DEX.
+
+## How to listen (viem)
+
+### Option 1: Poll historical blocks with `getLogs`
+
+```typescript
+import { createPublicClient, http, parseAbiItem } from 'viem';
+import { bsc } from 'viem/chains';
+
+const TOKEN_MANAGER2 = '0x5c952063c7fc8610FFDB798152D69F0B9550762b';
+
+const client = createPublicClient({
+  chain: bsc,
+  transport: http(process.env.BSC_RPC_URL || 'https://bsc-dataseed.binance.org'),
+});
+
+const logs = await client.getLogs({
+  address: TOKEN_MANAGER2,
+  events: [
+    parseAbiItem('event TokenCreate(address creator, address token, uint256 requestId, string name, string symbol, uint256 totalSupply, uint256 launchTime, uint256 launchFee)'),
+    parseAbiItem('event TokenPurchase(address token, address account, uint256 price, uint256 amount, uint256 cost, uint256 fee, uint256 offers, uint256 funds)'),
+    parseAbiItem('event TokenSale(address token, address account, uint256 price, uint256 amount, uint256 cost, uint256 fee, uint256 offers, uint256 funds)'),
+    parseAbiItem('event LiquidityAdded(address base, uint256 offers, address quote, uint256 funds)'),
+  ],
+  fromBlock: fromBlockNumber,
+  toBlock: toBlockNumber,
+});
+```
+
+### Option 2: Real-time subscription with `watchContractEvent`
+
+```typescript
+import { createPublicClient, http, parseAbiItem } from 'viem';
+import { bsc } from 'viem/chains';
+
+const client = createPublicClient({ chain: bsc, transport: http(rpcUrl) });
+
+const unwatch = client.watchContractEvent({
+  address: TOKEN_MANAGER2,
+  events: [
+    parseAbiItem('event TokenCreate(address creator, address token, uint256 requestId, string name, string symbol, uint256 totalSupply, uint256 launchTime, uint256 launchFee)'),
+    parseAbiItem('event TokenPurchase(address token, address account, uint256 price, uint256 amount, uint256 cost, uint256 fee, uint256 offers, uint256 funds)'),
+    parseAbiItem('event TokenSale(address token, address account, uint256 price, uint256 amount, uint256 cost, uint256 fee, uint256 offers, uint256 funds)'),
+    parseAbiItem('event LiquidityAdded(address base, uint256 offers, address quote, uint256 funds)'),
+  ],
+  onLogs: (logs) => {
+    for (const log of logs) {
+      console.log(log.eventName, log.args);
+    }
+  },
+});
+// To stop: unwatch()
+```
+
+## Script
+
+Use `fourmeme events <fromBlock> [toBlock]` (script `get-recent-events.ts`) to fetch the four event types in a block range and output JSON. See the events section in [SKILL.md](../SKILL.md).

package/skills/four-meme/four-meme-ai/references/execute-trade.md

@@ -0,0 +1,31 @@
+# Execute Buy / Sell (Four.meme BSC)
+
+Executes buy/sell (sends on-chain transactions). Requires `PRIVATE_KEY`. Only **TokenManager2 (V2)** tokens are supported.
+
+## Buy
+
+- **By amount**: `buyToken(token, amount, maxFunds)`  
+  CLI: `fourmeme buy <token> amount <amountWei> <maxFundsWei>`  
+  Meaning: Spend at most `maxFundsWei` of quote (BNB or BEP20) to buy `amountWei` tokens.
+
+- **By funds**: `buyTokenAMAP(token, funds, minAmount)`  
+  CLI: `fourmeme buy <token> funds <fundsWei> <minAmountWei>`  
+  Meaning: Spend `fundsWei` of quote and receive at least `minAmountWei` tokens.
+
+If quote is BEP20 (not BNB), the script will `approve` TokenManager2 first, then send the buy transaction.
+
+## Sell
+
+- Contract requirement: First `approve(tokenManager, amount)` on TokenManager2, then call `sellToken(token, amount)` or `sellToken(origin, token, amount, minFunds)` for slippage protection.
+- The CLI runs approve then sell automatically; no need to do both manually.
+
+```bash
+fourmeme sell <tokenAddress> <amountWei> [minFundsWei]
+```
+
+- `minFundsWei` is optional: minimum quote to receive (slippage protection).
+
+## Relation to quote commands
+
+- `quote-buy` / `quote-sell`: Read-only estimates; no transaction is sent.
+- `buy` / `sell`: Actually send transactions. Recommended: use `quote-buy` / `quote-sell` first to get estimates, then choose `maxFundsWei`, `minAmountWei`, `minFundsWei` and call `buy` / `sell`.

package/skills/four-meme/four-meme-ai/references/tax-token-query.md

@@ -0,0 +1,38 @@
+# Query Tax Token fee/tax info
+
+Only for **TaxToken** (creatorType 5). The token contract address is the TaxToken contract; call view functions on that address.
+
+## On-chain view functions (TaxToken.abi)
+
+| Function / variable | Description | Unit / meaning |
+|---------------------|-------------|----------------|
+| **feeRate** | Trading fee rate | Basis points; 10000 = 100%, e.g. 500 = 5% |
+| **rateFounder** | Founder allocation share | Percent; 100 = 100%, e.g. 10 = 10% |
+| **rateHolder** | Holder dividend share | Same |
+| **rateBurn** | Burn share | Same |
+| **rateLiquidity** | Liquidity add share | Same; rateFounder + rateHolder + rateBurn + rateLiquidity = 100 |
+| **minDispatch** | Cumulative fee threshold to trigger distribution | Token units |
+| **minShare** | Min balance to participate in dividends | Token units (ether); below this, no dividend |
+| **quote** | Quote token address | 0 = BNB/ETH |
+| **founder** | Founder address | Receives founder allocation |
+
+See also **claimableFee(account)**, **claimedFee(account)**, **userInfo(account)** for claimable/claimed fees and user info in the [official API/Contract docs](https://four-meme.gitbook.io/four.meme/brand/protocol-integration) (e.g. API-Contract-TaxToken).
+
+## Script
+
+```bash
+npx fourmeme tax-info <tokenAddress>
+```
+
+Or run: `npx tsx .../get-tax-token-info.ts <tokenAddress>`. BSC only.
+
+Example output (JSON): `feeRateBps`, `feeRatePercent`, `rateFounder`, `rateHolder`, `rateBurn`, `rateLiquidity`, `minDispatch`, `minShare`, `quote`, `founder`.
+
+## How to identify a TaxToken
+
+- **Off-chain**: Call four.meme API `GET /v1/private/token/get?address=<token>`; if response `data` contains `taxInfo`, it is a TaxToken.
+- **On-chain**: In TokenManager2, `(template >> 10) & 0x3F === 5` means TaxToken. Or run `get-tax-token-info`; if it succeeds and e.g. `feeRateBps > 0`, treat as TaxToken.
+
+## References
+
+- [Protocol Integration](https://four-meme.gitbook.io/four.meme/brand/protocol-integration) – API documents (API-Contract-TaxToken, etc.) and ABIs (TaxToken.abi)

package/skills/four-meme/four-meme-ai/references/token-query-api.md

@@ -0,0 +1,44 @@
+# Token query REST API (Four.meme)
+
+Base: `https://four.meme/meme-api/v1`. Requests need `Accept: application/json`; POST needs `Content-Type: application/json`. No login or cookie required.
+
+## 1. Token list (filter / paginate)
+
+**POST** `/public/token/search`  
+JSON body: `type`, `listType`, `pageIndex`, `pageSize`, `status`, `sort`, optional `keyword`, `symbol`, `tag` (array), `version`.
+
+| Parameter | Description |
+|-----------|-------------|
+| type | Ranking sort context: NEW, HOT, PROGRESS, VOL, LAST, CAP, DEX, BURN, … |
+| listType | NOR, NOR_DEX, BIN, USD1, BIN_DEX, USD1_DEX, ADV |
+| status | PUBLISH, TRADE, ALL |
+| sort | DESC, ASC |
+| keyword | Search keyword |
+| symbol | Quote symbol (e.g. BNB, USDT) |
+| tag | Label filters (e.g. Meme, AI) |
+| version | V9 (tax), V10 (AI); omit for all |
+
+CLI: `fourmeme token-list` — legacy flags still map to the above (e.g. `--orderBy` → `type`, `--tokenName` → `keyword`, `--labels` → `tag`, `--listedPancake=false` → `status=PUBLISH`). See script header for full list.
+
+## 2. Token detail and trading info
+
+**GET** `/private/token/get/v2?address=<tokenAddress>`
+
+CLI: `fourmeme token-get <tokenAddress>`
+
+## 3. Rankings
+
+**POST** `/public/token/ranking`  
+JSON body: `type` (required RankingType), `pageSize`, optional `rankingKind`, `version`, `symbol`, `minCap`, `maxCap`, `minVol`, `maxVol`, `minHold`, `maxHold`.
+
+| Legacy CLI orderBy | Maps to type |
+|--------------------|--------------|
+| Time | NEW |
+| ProgressDesc | PROGRESS |
+| TradingDesc | VOL_DAY_1 (default); `--barType` selects VOL_HOUR_1, VOL_HOUR_4, VOL_MIN_30, VOL_MIN_5, … |
+| Hot | HOT |
+| Graduated | DEX |
+
+You may also pass a native `type` as the first argument (e.g. `VOL_DAY_1`, `CAP`, `BURN`).
+
+CLI: `fourmeme token-rankings <orderBy|type> [--barType=HOUR24] [--pageSize=20] [--symbol=] [--version=] …`

package/skills/four-meme/four-meme-ai/references/token-tax-info.md

@@ -0,0 +1,77 @@
+# Tax Token parameters (tokenTaxInfo)
+
+When creating a **Tax-type token**, send a `tokenTaxInfo` object in the create request body. If omitted, a normal token is created. Agent interaction (whether to create a tax token, parameter order) is in [SKILL.md](../SKILL.md) “Create token (full flow)”. This page only lists fields and constraints.
+
+## Field summary
+
+| Parameter | Type | Description | Allowed values / constraint |
+|-----------|------|-------------|------------------------------|
+| **feeRate** | number | Trading fee rate (%) | **Exactly one of**: `1`, `3`, `5`, `10` |
+| **burnRate** | number | Burn share (%) | Custom; see constraints below |
+| **divideRate** | number | Dividend share (%) | Custom; see below |
+| **liquidityRate** | number | Liquidity share (%) | Custom; see below |
+| **recipientRate** | number | Recipient share (%) | Custom; use `0` if not used |
+| **recipientAddress** | string | Address that receives allocation | Use `""` if not used |
+| **minSharing** | number | Min balance for dividends (ether units) | Must satisfy `d × 10ⁿ`, n≥5, 1≤d≤9 |
+
+## Constraints
+
+1. **feeRate** must be one of **1, 3, 5, 10** (1%, 3%, 5%, 10%).
+2. **burnRate + divideRate + liquidityRate + recipientRate = 100** (the four shares must sum to 100).
+3. If no recipient: **recipientAddress = ""** and **recipientRate = 0**.
+4. **minSharing** examples: `100000` (1×10⁵), `200000`, `500000`, `1000000` (1×10⁶), `9000000`, `10000000` (1×10⁷), i.e. `d × 10ⁿ` with n≥5, 1≤d≤9.
+
+## Examples
+
+**Example 1: 5% fee, 20% burn, 30% dividend, 40% liquidity, 10% recipient**
+
+```json
+{
+  "tokenTaxInfo": {
+    "feeRate": 5,
+    "burnRate": 20,
+    "divideRate": 30,
+    "liquidityRate": 40,
+    "recipientRate": 10,
+    "recipientAddress": "0x1234567890123456789012345678901234567890",
+    "minSharing": 100000
+  }
+}
+```
+
+**Example 2: 3% fee, 100% liquidity, no dividend/burn/recipient**
+
+```json
+{
+  "tokenTaxInfo": {
+    "feeRate": 3,
+    "burnRate": 0,
+    "divideRate": 0,
+    "liquidityRate": 100,
+    "recipientRate": 0,
+    "recipientAddress": "",
+    "minSharing": 100000
+  }
+}
+```
+
+**Example 3: 10% fee, 50% dividend, 50% burn, min share 1×10⁶**
+
+```json
+{
+  "tokenTaxInfo": {
+    "feeRate": 10,
+    "burnRate": 50,
+    "divideRate": 50,
+    "liquidityRate": 0,
+    "recipientRate": 0,
+    "recipientAddress": "",
+    "minSharing": 1000000
+  }
+}
+```
+
+## Use in scripts
+
+- **Option 1 (recommended)**: Write the above `tokenTaxInfo` to a JSON file (can contain only `tokenTaxInfo`) and pass that file path as the last argument to `create-token-api.ts`; the script merges it into the create body.
+- **Option 2**: Build tax params via env vars (see “Create token (API)” optional env in SKILL.md).

package/skills/four-meme/four-meme-ai/scripts/8004-balance.ts

@@ -0,0 +1,52 @@
+#!/usr/bin/env node
+/**
+ * EIP-8004 NFT – query balance (number of identity NFTs owned by address).
+ *
+ * Usage:
+ *   npx tsx 8004-balance.ts <ownerAddress>
+ *
+ * Optional env: BSC_RPC_URL, 8004_NFT_ADDRESS.
+ * Default contract: 0x8004A169FB4a3325136EB29fA0ceB6D2e539a432 (BSC).
+ */
+
+import { createPublicClient, http, parseAbi } from 'viem';
+import { bsc } from 'viem/chains';
+
+const DEFAULT_8004_NFT = '0x8004A169FB4a3325136EB29fA0ceB6D2e539a432' as const;
+
+const ABI = parseAbi(['function balanceOf(address owner) view returns (uint256)']);
+
+function isAddress(s: string): boolean {
+  return /^0x[0-9a-fA-F]{40}$/.test(s);
+}
+
+async function main() {
+  const ownerAddress = process.argv[2];
+  if (!ownerAddress || !isAddress(ownerAddress)) {
+    console.error('Usage: 8004-balance.ts <ownerAddress>');
+    console.error('  ownerAddress: 0x... wallet address');
+    process.exit(1);
+  }
+
+  const contractAddress = (process.env['8004_NFT_ADDRESS'] || process.env.EIP8004_NFT_ADDRESS || DEFAULT_8004_NFT) as `0x${string}`;
+  const rpcUrl = process.env.BSC_RPC_URL || 'https://bsc-dataseed.binance.org';
+
+  const client = createPublicClient({
+    chain: bsc,
+    transport: http(rpcUrl),
+  });
+
+  const balance = await client.readContract({
+    address: contractAddress,
+    abi: ABI,
+    functionName: 'balanceOf',
+    args: [ownerAddress as `0x${string}`],
+  });
+
+  console.log(JSON.stringify({ owner: ownerAddress, balance: Number(balance) }, null, 2));
+}
+
+main().catch((e) => {
+  console.error(e.message || e);
+  process.exit(1);
+});

package/skills/four-meme/four-meme-ai/scripts/8004-register.ts

@@ -0,0 +1,108 @@
+#!/usr/bin/env node
+/**
+ * EIP-8004 NFT – register agent (mint identity NFT).
+ * Builds agentURI as data:application/json;base64,<payload> and calls contract.register(agentURI).
+ *
+ * Usage:
+ *   npx tsx 8004-register.ts <name> [imageUrl] [description]
+ *   - name: required
+ *   - imageUrl: optional (URL string)
+ *   - description: optional
+ *
+ * Env: PRIVATE_KEY. Optional: BSC_RPC_URL, 8004_NFT_ADDRESS.
+ * Default contract: 0x8004A169FB4a3325136EB29fA0ceB6D2e539a432 (BSC).
+ */
+
+import { createPublicClient, createWalletClient, decodeEventLog, http, parseAbi } from 'viem';
+import { privateKeyToAccount } from 'viem/accounts';
+import { bsc } from 'viem/chains';
+
+const DEFAULT_8004_NFT = '0x8004A169FB4a3325136EB29fA0ceB6D2e539a432' as const;
+
+const REGISTRATION_TYPE = 'https://eips.ethereum.org/EIPS/eip-8004#registration-v1';
+
+const ABI = parseAbi([
+  'function register(string agentURI) returns (uint256 agentId)',
+  'event Registered(uint256 indexed agentId, string agentURI, address indexed owner)',
+]);
+
+function buildAgentURI(name: string, imageUrl: string, description: string): string {
+  const payload = {
+    type: REGISTRATION_TYPE,
+    name: name || '',
+    description: description || 'I\'m four.meme trading agent',
+    image: imageUrl || '',
+    active: true,
+    supportedTrust: [''],
+  };
+  const json = JSON.stringify(payload);
+  const base64 = Buffer.from(json, 'utf8').toString('base64');
+  return `data:application/json;base64,${base64}`;
+}
+
+async function main() {
+  const privateKey = process.env.PRIVATE_KEY;
+  if (!privateKey) {
+    console.error('Set PRIVATE_KEY');
+    process.exit(1);
+  }
+  const pk = privateKey.startsWith('0x') ? (privateKey as `0x${string}`) : (`0x${privateKey}` as `0x${string}`);
+  const account = privateKeyToAccount(pk);
+
+  const name = process.argv[2];
+  const imageUrl = process.argv[3] ?? '';
+  const description = process.argv[4] ?? '';
+
+  if (!name || name.trim() === '') {
+    console.error('Usage: 8004-register.ts <name> [imageUrl] [description]');
+    console.error('  name: required. imageUrl and description are optional.');
+    process.exit(1);
+  }
+
+  const agentURI = buildAgentURI(name.trim(), imageUrl.trim(), description.trim());
+  const contractAddress = (process.env['8004_NFT_ADDRESS'] || process.env.EIP8004_NFT_ADDRESS || DEFAULT_8004_NFT) as `0x${string}`;
+  const rpcUrl = process.env.BSC_RPC_URL || 'https://bsc-dataseed.binance.org';
+
+  const wallet = createWalletClient({
+    account,
+    chain: bsc,
+    transport: http(rpcUrl),
+  });
+  const publicClient = createPublicClient({
+    chain: bsc,
+    transport: http(rpcUrl),
+  });
+
+  const txHash = await wallet.writeContract({
+    address: contractAddress,
+    abi: ABI,
+    functionName: 'register',
+    args: [agentURI],
+  });
+
+  const receipt = await publicClient.waitForTransactionReceipt({ hash: txHash });
+  let agentId: number | null = null;
+  for (const l of receipt.logs) {
+    if (l.address.toLowerCase() !== contractAddress.toLowerCase()) continue;
+    try {
+      const d = decodeEventLog({
+        abi: ABI,
+        data: l.data,
+        topics: l.topics,
+      });
+      if (d.eventName === 'Registered') {
+        agentId = Number((d.args as { agentId: bigint }).agentId);
+        break;
+      }
+    } catch {
+      /* ignore */
+    }
+  }
+
+  console.log(JSON.stringify({ txHash, agentId, agentURI }, null, 2));
+}
+
+main().catch((e) => {
+  console.error(e.message || e);
+  process.exit(1);
+});