@hot-fun/hot-fun-ai 1.0.0

package/.env.example

@@ -0,0 +1,5 @@
+# Solana wallet private key (base58 string or JSON array of bytes) — required
+PRIVATE_KEY=
+
+# Solana RPC endpoint — required
+SOLANA_RPC_URL=

package/CLAUDE.md

@@ -0,0 +1,63 @@
+# hot-fun-ai – Agent Guidelines (Claude / Claude Code)
+
+## Overview
+
+This repo provides the **hot-fun-integration** skill for AI agents: create meme tokens on **hot.fun (Solana)** using the hot.fun API and on-chain Solana programs.
+
+The authoritative specification for this skill is `skills/hot-fun-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 hot.fun on Solana (API flow + on-chain transaction).
+
+If the user's request does not involve hot.fun or Solana token creation, you should not use this skill.
+
+## Repo Layout
+
+```
+hot-fun-ai/
+├── skills/
+│   └── hot-fun-integration/
+│       ├── SKILL.md        # Main skill instructions (Cursor / OpenClaw)
+│       ├── references/     # API reference docs
+│       └── scripts/        # create-token (full flow)
+├── bin/
+│   └── hotfun.cjs          # CLI dispatcher (hotfun ...)
+├── 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-token`) until the user has explicitly agreed or confirmed to continue.
+
+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**: Solana only.
+2. **Create token**: Single command `hotfun create-token <name> <symbol> <uri>` handles the full flow: call API to get base58 transaction → sign with private key → send to Solana RPC. User provides token image/metadata URI directly (no image upload needed).
+3. **RPC and private key (environment)**:
+   - When **using OpenClaw**: PRIVATE_KEY and SOLANA_RPC_URL are configured in OpenClaw (e.g. `skills.entries["hot-fun-ai"].env` or apiKey); see SKILL.md.
+   - When **not using OpenClaw (standalone)**: set `PRIVATE_KEY` and optionally `SOLANA_RPC_URL` via the process environment — e.g. a `.env` file in the **directory where you run `hotfun`** (the CLI loads it automatically via dotenv) or shell `export`. Do not ask the user to paste a private key in chat.
+
+## CLI Usage (hotfun)
+
+From the project root after `npm install`, use:
+
+```bash
+npx hotfun <command> [args...]
+```
+
+Key commands (full list and parameters in `SKILL.md`):
+
+- `hotfun create-token <name> <symbol> <uri>` – Create token on hot.fun (API → sign → send to Solana).
+
+Always prefer these CLI commands rather than calling scripts directly, unless `SKILL.md` suggests otherwise.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 lol-dev-99
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,92 @@
+# hot-fun-ai
+
+Hot.fun AI skills for creating meme tokens on **Solana**. Lets agents integrate with [hot.fun](https://hot.fun) for token creation.
+
+## Skills
+
+| Skill | Description |
+|-------|-------------|
+| `hot-fun-integration` | Create meme tokens on **Solana** via hot.fun API + on-chain transaction. |
+
+Safety, user agreement, and detailed agent behavior requirements are defined in [`skills/hot-fun-integration/SKILL.md`](skills/hot-fun-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 meme tokens on hot.fun (Solana), use the **hot-fun-integration** skill:
+
+- **Create token**: `hotfun create-token <name> <symbol> <uri>` — calls the hot.fun API to get a transaction, signs it with the wallet private key, and sends it to Solana RPC. See `SKILL.md` and `references/api-create-token.md` for full details.
+- **CLI** (after `npm install`): use **`npx hotfun <command> [args...]`**. Run `npx hotfun --help` for all commands.
+
+## Install (project)
+
+```bash
+cd hot-fun-ai
+npm install
+```
+
+## Environment variables (without OpenClaw)
+
+When you **do not** use OpenClaw, the CLI reads `PRIVATE_KEY` and `SOLANA_RPC_URL` from the process environment. Set them in one of these ways:
+
+**Option 1: `.env` file in the working directory**
+
+Create a file named `.env` in the directory where you run `hotfun`:
+
+```bash
+# .env (do not commit this file)
+PRIVATE_KEY=your_solana_private_key_base58_or_json_array
+SOLANA_RPC_URL=https://api.mainnet-beta.solana.com
+```
+
+The CLI automatically loads `.env` from the current working directory.
+
+**Option 2: export in the shell**
+
+```bash
+export PRIVATE_KEY=your_solana_private_key
+export SOLANA_RPC_URL=https://api.mainnet-beta.solana.com
+npx hotfun create-token MyToken MTK "https://example.com/metadata.json"
+```
+
+- **PRIVATE_KEY**: Required for any command that signs or sends a transaction. Base58 string or JSON array of bytes.
+- **SOLANA_RPC_URL**: Optional. Solana RPC endpoint; if unset, scripts use `https://api.mainnet-beta.solana.com`.
+
+**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:
+
+```bash
+openclaw plugins install /path/to/hot-fun-ai
+```
+
+Then in `~/.openclaw/openclaw.json` set:
+
+```json5
+{
+  skills: {
+    entries: {
+      "hot-fun-ai": {
+        enabled: true,
+        env: {
+          PRIVATE_KEY: "your_solana_private_key",
+          SOLANA_RPC_URL: "https://api.mainnet-beta.solana.com"
+        }
+      }
+    }
+  }
+}
+```
+
+See [skills/hot-fun-integration/SKILL.md](skills/hot-fun-integration/SKILL.md) for full details.
+
+## Docs
+
+- Skill instructions (agent behavior, safety, flows): `skills/hot-fun-integration/SKILL.md`
+- Claude/Claude Code guidelines: `CLAUDE.md`
+- References: `skills/hot-fun-integration/references/` (API docs)
+
+## License
+
+MIT

package/bin/hotfun.cjs

@@ -0,0 +1,59 @@
+#!/usr/bin/env node
+/**
+ * hotfun CLI - dispatches to hot-fun-integration scripts.
+ * Usage: hotfun <command> [args...]
+ * Run "hotfun --help" for commands.
+ * Loads .env from current working directory (where you run hotfun) if present.
+ */
+const { spawnSync } = require('child_process');
+const path = require('path');
+
+// Load .env from cwd (e.g. your project dir) so PRIVATE_KEY, SOLANA_RPC_URL etc. work when running from a project
+require('dotenv').config({ path: path.join(process.cwd(), '.env') });
+
+const root = path.join(__dirname, '..');
+const scriptsDir = path.join(root, 'skills', 'hot-fun-integration', 'scripts');
+
+const commands = {
+  'create-token': 'create-token.ts',
+};
+
+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(`hotfun - Hot.fun CLI (Solana)
+
+Usage: npx hotfun <command> [args...]
+
+Commands:
+  create-token <name> <symbol> <uri>
+                            Create token on hot.fun (API → sign → send). Env: PRIVATE_KEY.
+
+Env: PRIVATE_KEY, SOLANA_RPC_URL (optional), ROYALTY_PARTY (optional). 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);
+}
+
+const script = commands[cmd];
+if (!script) {
+  console.error(`Unknown command: ${cmd}`);
+  printHelp();
+  process.exit(1);
+}
+
+run(script, argv.slice(1));

package/openclaw.plugin.json

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

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@hot-fun/hot-fun-ai",
+  "version": "1.0.0",
+  "description": "Hot.fun AI skills for creating meme tokens on Solana",
+  "license": "MIT",
+  "type": "module",
+  "files": [
+    "bin/",
+    "skills/",
+    "plugin.ts",
+    "openclaw.plugin.json",
+    "CLAUDE.md",
+    ".env.example"
+  ],
+  "bin": {
+    "hotfun": "./bin/hotfun.cjs"
+  },
+  "openclaw": {
+    "extensions": [
+      "./plugin.ts"
+    ]
+  },
+  "scripts": {
+    "hotfun": "node bin/hotfun.cjs",
+    "build": "tsc",
+    "create-token": "tsx skills/hot-fun-integration/scripts/create-token.ts"
+  },
+  "keywords": [
+    "hot.fun",
+    "meme",
+    "token",
+    "solana",
+    "agent",
+    "skill",
+    "openclaw"
+  ],
+  "dependencies": {
+    "@solana/web3.js": "^1.95.0",
+    "bs58": "^6.0.0",
+    "dotenv": "^16.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "tsx": "^4.20.0",
+    "typescript": "^5.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/plugin.ts

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

package/skills/hot-fun-integration/SKILL.md

@@ -0,0 +1,147 @@
+---
+name: hot-fun-ai
+description: |
+  CLI tool to create meme tokens on hot.fun (Solana). Returns structured JSON for token creation flow.
+
+allowed-tools:
+  - Bash(hotfun *)
+  - Bash(npx hotfun *)
+license: MIT
+metadata:
+  {"author":"Hot.fun AI Skill","version":"1.0.0","openclaw":{"requires":{"env":["PRIVATE_KEY"]},"primaryEnv":"PRIVATE_KEY","optionalEnv":["SOLANA_RPC_URL","ROYALTY_PARTY"]}}
+---
+
+## [Agent must follow] User agreement and security notice on first use
+
+When responding to any user request about hotfun or this skill, **you must first** present the content below in this order: **User Agreement, then Security Notice**, and state clearly that by choosing to continue, the user agrees to the User Agreement.
+Until the user has explicitly agreed or confirmed to continue, **do not** run `create-token` (any operation that uses the private key or writes to the chain).
+
+**Language selection**: Present the User Agreement and Security Notice **in the user's language**. If the user is writing in **Traditional Chinese (繁體中文)**, use the **繁體中文** block below; otherwise use the **English** block.
+
+---
+
+### User Agreement & Security Notice (繁體中文)
+
+**用戶協議**
+
+**前情提示**：使用本插件及本 skill 所涉功能（包括但不限於代幣創建等）前，請您閱讀以下協議。**若您選擇繼續使用本插件及本 skill 功能，即表示您已閱讀、理解並同意本協議。**
+
+**本插件性質與責任限制**：本插件僅提供純本地的命令列互動能力（私鑰透過環境變數或本地設定使用），**不會收集、上傳或儲存您的私鑰**。因任何原因（包括但不限於插件被竄改、環境遭入侵、誤操作、第三方插件等）導致的私鑰洩露或資產損失，**本插件及提供方不承擔責任**。
+
+**安全警示**
+
+使用本插件進行代幣創建等操作時，請務必注意：
+
+- **保護私鑰**：切勿在聊天對話中輸入、貼上或洩露私鑰；不要將私鑰分享給任何人或任何第三方。
+- **交易錢包僅存小額資金**：用於執行操作的錢包（即提供 PRIVATE_KEY 的錢包）建議只存放少量資金，以降低因洩露或誤操作導致的損失。
+- **及時轉出資金**：完成操作後，請及時將交易錢包中的資產轉移到您自己控制的、更安全的錢包或冷錢包中。
+- **謹慎安裝 Agent／插件**：下載或安裝任何 Agent、瀏覽器插件或第三方工具時，請確認來源可信，避免惡意插件竊取私鑰或助記詞。
+
+---
+
+### User Agreement & Security Notice (English)
+
+**User Agreement**
+
+**Notice**: Before using this plugin and this skill (including but not limited to token creation), please read the following. **By choosing to continue using this plugin and this skill, you have read, understood, and agreed to this agreement.**
+
+**Plugin nature and limitation of liability**: This plugin provides local-only CLI interaction (private key is used via environment or local config). It **does not collect, upload, or store your private key**. The plugin and its providers **are not liable** for private key disclosure or asset loss due to any cause (including but not limited to tampered plugin, compromised environment, user error, or third-party plugins).
+
+**Security Notice**
+
+When using this plugin for token creation, please:
+
+- **Protect your private key**: Do not type, paste, or expose your private key in chat; do not share it with anyone or any third party.
+- **Keep only small amounts in the trading wallet**: The wallet used for operations (the one whose PRIVATE_KEY you provide) should hold only a small amount of funds to limit loss from disclosure or mistakes.
+- **Move funds out promptly**: After operations, move assets from the trading wallet to a wallet or cold storage you control.
+- **Install agents/plugins carefully**: When installing any agent, browser extension, or third-party tool, verify the source to avoid malware that could steal your private key or seed phrase.
+
+---
+
+## hotfun capability overview
+
+After you agree to the above and confirm to continue, this skill can help you with the following (all via the `hotfun` CLI on Solana):
+
+| Category | Capability | Description |
+|----------|-------------|-------------|
+| **Create** | Create token | Call API → sign transaction → send to Solana RPC. |
+
+## hotfun CLI
+
+Solana only; all commands output JSON. Run `hotfun --help` for usage.
+
+## Installation (required before use)
+
+**You must install the hotfun CLI before using this skill.** Recommended (global):
+
+```bash
+npm install -g @hot-fun/hot-fun-ai@latest
+```
+
+After installation, run commands with `hotfun <command> [args]`. If you use a local install instead, use `npx hotfun <command> [args]` from the project root.
+
+## Create token flow
+
+### 1. Ask user for required information (must be done first)
+
+Before calling `create-token`, the Agent **must** ask the user for and confirm:
+
+| Info | Required | Description |
+|------|----------|-------------|
+| **Token name** (name) | Yes | Full token name |
+| **Token symbol** (symbol) | Yes | e.g. MTK, DOGE |
+| **URI** (uri) | Yes | Token metadata / image URL (e.g. IPFS link) |
+
+Optional env: `ROYALTY_PARTY` (royalty recipient address; defaults to system program = no royalty).
+
+### 2. Technical flow (done by create-token)
+
+After collecting the above, execute:
+
+```bash
+hotfun create-token <name> <symbol> <uri>
+```
+
+Under the hood, the single command handles the full flow:
+
+1. **Call API** — POST to `https://gate.game.com/v3/hotfun/create_pool_with_config` with payer (from PRIVATE_KEY), name, symbol, uri. API returns a base58-encoded Solana transaction.
+2. **Sign** — Deserialize the transaction and sign it with the wallet private key.
+3. **Send** — Send the signed transaction to Solana RPC and confirm.
+
+Output JSON includes: `txHash`, `wallet`, `baseMint` (new token address), `dbcConfig`, `dbcPool`, `name`, `symbol`, `uri`.
+
+Full API and parameters: [references/api-create-token.md](references/api-create-token.md).
+
+## CLI commands
+
+| Need | Command | When |
+|------|---------|------|
+| **Create token** | `hotfun create-token <name> <symbol> <uri>` | API → sign → send to Solana. Env: PRIVATE_KEY. |
+
+Chain: **Solana only**.
+
+## PRIVATE_KEY and SOLANA_RPC_URL
+
+**When using OpenClaw**
+This skill declares `requires.env: ["PRIVATE_KEY"]` and `primaryEnv: "PRIVATE_KEY"` in metadata; OpenClaw injects them only when an agent runs with **this skill enabled** (other skills cannot access them).
+
+**Required steps:**
+1. **Configure private key**: In the Skill management page, set the hot-fun-ai skill's **apiKey** (corresponds to `primaryEnv: "PRIVATE_KEY"`), or set `PRIVATE_KEY` under `skills.entries["hot-fun-ai"].env` in `~/.openclaw/openclaw.json`. Optionally set **SOLANA_RPC_URL** in global env if needed.
+2. **Enable this skill**: In the agent or session, ensure the **hot-fun-ai** skill is **enabled**. Only when the skill is enabled will OpenClaw inject **PRIVATE_KEY** into the process; otherwise create commands will fail with missing key.
+
+**When not using OpenClaw (standalone)**
+Set **PRIVATE_KEY** and optionally **SOLANA_RPC_URL** via the process environment:
+
+- **.env file**: Put a `.env` file in **the directory where you run the `hotfun` command** (i.e. your project / working directory). The CLI automatically loads `.env` from that current working directory. Use lines like `PRIVATE_KEY=...` and `SOLANA_RPC_URL=...`. Do not commit `.env`; add it to `.gitignore`.
+- **Shell export**: `export PRIVATE_KEY=your_base58_key` and optionally `export SOLANA_RPC_URL=https://api.mainnet-beta.solana.com`, then run `npx hotfun <command> ...`.
+
+### Declared and optional environment variables
+
+- **PRIVATE_KEY** (required for write operations): Solana wallet private key in base58 or JSON array format.
+- **SOLANA_RPC_URL** (optional): Solana RPC endpoint; if unset, scripts use `https://api.mainnet-beta.solana.com`.
+- **ROYALTY_PARTY** (optional): Royalty recipient Solana address; defaults to `11111111111111111111111111111111` (system program = no royalty).
+
+### Execution and install
+
+- **Invocation**: The agent must run commands only via the **hotfun** CLI: `hotfun <command> [args]` or `npx hotfun <command> [args]` (allowed-tools). Do not invoke scripts or `npx tsx` directly; the CLI entry (`bin/hotfun.cjs`) dispatches to the correct script and loads `.env` from the current working directory.
+- **Install**: `npm install -g @hot-fun/hot-fun-ai@latest`. Runtime: Node.js. Dependencies (including dotenv, @solana/web3.js, tsx) are declared in the package's `package.json`; global install installs them. No separate install spec beyond the npm package.

package/skills/hot-fun-integration/references/api-create-token.md

@@ -0,0 +1,80 @@
+# Hot.fun Create Token API Reference
+
+## Flow
+
+The `hotfun create-token` command handles the full flow in a single invocation:
+
+1. **Call API** — POST to the hot.fun API with token parameters; receive a base58-encoded Solana transaction.
+2. **Sign** — Deserialize the transaction and sign it with the wallet private key.
+3. **Send** — Send the signed transaction to Solana RPC and confirm.
+
+## API Endpoint
+
+| Method | Endpoint |
+|--------|----------|
+| POST | `https://gate.game.com/v3/hotfun/create_pool_with_config` |
+
+### Request
+
+**Content-Type**: `application/x-www-form-urlencoded`
+
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| `payer` | Yes | Solana wallet public key (derived from PRIVATE_KEY) |
+| `royalty_party` | Yes | Royalty recipient address. Default: `11111111111111111111111111111111` (system program = no royalty) |
+| `name` | Yes | Token name |
+| `symbol` | Yes | Token symbol |
+| `uri` | Yes | Token metadata / image URI (e.g. IPFS link) |
+
+**Required headers**:
+```
+Origin: https://hot.fun
+Referer: https://hot.fun/
+```
+
+### Response
+
+```json
+{
+  "data": {
+    "transaction": "<base58-encoded Solana transaction>",
+    "signature": "",
+    "dbc_config": "<pubkey>",
+    "dbc_pool": "<pubkey>",
+    "base_mint": "<pubkey>"
+  },
+  "common": {
+    "timestamp": 1772694804,
+    "app_name": "hotfunv3",
+    "chain_asset_config": [...],
+    "config": { "check_chinese_symbol_duplicate": false }
+  }
+}
+```
+
+**Key fields in `data`**:
+
+| Field | Description |
+|-------|-------------|
+| `transaction` | Base58-encoded Solana transaction to sign and send |
+| `base_mint` | The new token's mint address |
+| `dbc_config` | DBC config account |
+| `dbc_pool` | DBC pool account |
+
+### Example
+
+```bash
+curl 'https://gate.game.com/v3/hotfun/create_pool_with_config' \
+  -H 'Content-Type: application/x-www-form-urlencoded' \
+  -H 'Origin: https://hot.fun' \
+  -H 'Referer: https://hot.fun/' \
+  --data-raw 'payer=<WALLET_PUBKEY>&royalty_party=11111111111111111111111111111111&name=MyToken&symbol=MTK&uri=https%3A%2F%2Fexample.com%2Fmetadata.json'
+```
+
+## Sign and Send
+
+1. Decode the base58 `transaction` string to bytes.
+2. Deserialize as a `VersionedTransaction`.
+3. Sign with the wallet `Keypair`.
+4. Send via `connection.sendRawTransaction()`.
+5. Confirm via `connection.confirmTransaction()`.

package/skills/hot-fun-integration/scripts/create-token.ts

@@ -0,0 +1,145 @@
+#!/usr/bin/env node
+/**
+ * Hot.fun - create token: full flow (API → sign → send).
+ *
+ * 1. Call hot.fun API to get a base58-encoded Solana transaction
+ * 2. Sign the transaction with the wallet private key
+ * 3. Send the signed transaction to Solana RPC
+ *
+ * Usage:
+ *   npx hotfun create-token <name> <symbol> <uri>
+ *
+ * Env: PRIVATE_KEY (Solana wallet private key, base58 or JSON array)
+ * Optional env: SOLANA_RPC_URL, ROYALTY_PARTY
+ */
+
+import {
+  Connection,
+  Keypair,
+  VersionedTransaction,
+} from '@solana/web3.js';
+import bs58 from 'bs58';
+
+const API_URL = 'https://gate.game.com/v3/hotfun/create_pool_with_config';
+const DEFAULT_ROYALTY_PARTY = '11111111111111111111111111111111';
+
+function loadKeypair(privateKey: string): Keypair {
+  try {
+    if (privateKey.startsWith('[')) {
+      const arr = JSON.parse(privateKey);
+      return Keypair.fromSecretKey(new Uint8Array(arr));
+    }
+    return Keypair.fromSecretKey(bs58.decode(privateKey));
+  } catch {
+    throw new Error('Invalid PRIVATE_KEY format. Use base58 string or JSON array of bytes.');
+  }
+}
+
+async function main() {
+  const name = process.argv[2];
+  const symbol = process.argv[3];
+  const uri = process.argv[4];
+
+  if (!name || !symbol || !uri) {
+    console.error('Usage: npx hotfun create-token <name> <symbol> <uri>');
+    console.error('Example: npx hotfun create-token MyToken MTK "https://example.com/metadata.json"');
+    process.exit(1);
+  }
+
+  const privateKey = process.env.PRIVATE_KEY;
+  if (!privateKey) {
+    console.error('Set PRIVATE_KEY (Solana wallet private key, base58 or JSON array)');
+    process.exit(1);
+  }
+
+  const keypair = loadKeypair(privateKey);
+  const payer = keypair.publicKey.toBase58();
+  const royaltyParty = process.env.ROYALTY_PARTY || DEFAULT_ROYALTY_PARTY;
+  const rpcUrl = process.env.SOLANA_RPC_URL || 'https://api.mainnet-beta.solana.com';
+  const connection = new Connection(rpcUrl, 'confirmed');
+
+  // ── Step 1: Call API to get transaction ────────────────────────────────
+  console.error(`Creating token "${name}" (${symbol}) ...`);
+  console.error(`  payer: ${payer}`);
+  console.error(`  uri: ${uri}`);
+
+  const body = new URLSearchParams({
+    payer,
+    royalty_party: royaltyParty,
+    name,
+    symbol,
+    uri,
+  });
+
+  const res = await fetch(API_URL, {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/x-www-form-urlencoded',
+      'Origin': 'https://hot.fun',
+      'Referer': 'https://hot.fun/',
+    },
+    body: body.toString(),
+  });
+
+  if (!res.ok) {
+    throw new Error(`API request failed: ${res.status} ${res.statusText}`);
+  }
+
+  const json = await res.json() as {
+    data: {
+      transaction: string;
+      signature: string;
+      dbc_config: string;
+      dbc_pool: string;
+      base_mint: string;
+    };
+    common: Record<string, unknown>;
+  };
+
+  const { transaction: txBase58, dbc_config, dbc_pool, base_mint } = json.data;
+
+  if (!txBase58) {
+    throw new Error('API returned empty transaction. Response: ' + JSON.stringify(json));
+  }
+
+  console.error(`  base_mint: ${base_mint}`);
+  console.error(`  dbc_config: ${dbc_config}`);
+  console.error(`  dbc_pool: ${dbc_pool}`);
+
+  // ── Step 2: Deserialize and sign transaction ──────────────────────────
+  const txBytes = bs58.decode(txBase58);
+  const tx = VersionedTransaction.deserialize(txBytes);
+  tx.sign([keypair]);
+
+  // ── Step 3: Send to Solana RPC ────────────────────────────────────────
+  console.error('Sending transaction ...');
+  const txHash = await connection.sendRawTransaction(tx.serialize(), {
+    skipPreflight: false,
+    maxRetries: 3,
+  });
+
+  console.error('Confirming ...');
+  const confirmation = await connection.confirmTransaction(txHash, 'confirmed');
+
+  if (confirmation.value.err) {
+    throw new Error(`Transaction failed: ${JSON.stringify(confirmation.value.err)}`);
+  }
+
+  // ── Output ────────────────────────────────────────────────────────────
+  const out = {
+    txHash,
+    wallet: payer,
+    baseMint: base_mint,
+    dbcConfig: dbc_config,
+    dbcPool: dbc_pool,
+    name,
+    symbol,
+    uri,
+  };
+  console.log(JSON.stringify(out, null, 2));
+}
+
+main().catch((e) => {
+  console.error(e.message || e);
+  process.exit(1);
+});