@hot-fun/hot-fun-ai 1.0.0 → 1.0.2

package/CLAUDE.md

@@ -43,7 +43,7 @@ Never ask the user to paste a private key into chat. All private keys must come
 ## 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).
+2. **Create token**: Single command `hotfun create-token <name> <symbol> <image_url> [--description "desc"] [--x-royalty-party "username"]` handles the full flow: call API (with agent_ts + agent_sign authentication) to get base58 transaction → sign with private key → send to Solana RPC.
 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.
@@ -58,6 +58,6 @@ 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).
+- `hotfun create-token <name> <symbol> <image_url> [--description "desc"] [--x-royalty-party "user"]` – 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/README.md

@@ -14,7 +14,7 @@ Safety, user agreement, and detailed agent behavior requirements are defined in
 
 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.
+- **Create token**: `hotfun create-token <name> <symbol> <image_url> [--description "desc"] [--x-royalty-party "user"]` — calls the hot.fun API (with agent authentication) 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)
@@ -45,7 +45,7 @@ The CLI automatically loads `.env` from the current working directory.
 ```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"
+npx hotfun create-token MyToken MTK "https://example.com/image.png" --description "A cool token"
 ```
 
 - **PRIVATE_KEY**: Required for any command that signs or sends a transaction. Base58 string or JSON array of bytes.

package/bin/hotfun.cjs

@@ -34,10 +34,12 @@ function printHelp() {
 Usage: npx hotfun <command> [args...]
 
 Commands:
-  create-token <name> <symbol> <uri>
+  create-token <name> <symbol> <image_url> [options]
                             Create token on hot.fun (API → sign → send). Env: PRIVATE_KEY.
+    --description <desc>        Token description
+    --x-royalty-party <user>    X (Twitter) username for royalty party
 
-Env: PRIVATE_KEY, SOLANA_RPC_URL (optional), ROYALTY_PARTY (optional). See SKILL.md for full docs.
+Env: PRIVATE_KEY, SOLANA_RPC_URL (optional). See SKILL.md for full docs.
 `);
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hot-fun/hot-fun-ai",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "Hot.fun AI skills for creating meme tokens on Solana",
   "license": "MIT",
   "type": "module",
@@ -37,7 +37,8 @@
   "dependencies": {
     "@solana/web3.js": "^1.95.0",
     "bs58": "^6.0.0",
-    "dotenv": "^16.0.0"
+    "dotenv": "^16.0.0",
+    "tweetnacl": "^1.0.3"
   },
   "devDependencies": {
     "@types/node": "^20.0.0",

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

@@ -8,7 +8,7 @@ allowed-tools:
   - 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"]}}
+  {"author":"Hot.fun AI Skill","version":"1.0.0","openclaw":{"requires":{"env":["PRIVATE_KEY"]},"primaryEnv":"PRIVATE_KEY","optionalEnv":["SOLANA_RPC_URL"]}}
 ---
 
 ## [Agent must follow] User agreement and security notice on first use
@@ -82,33 +82,33 @@ After installation, run commands with `hotfun <command> [args]`. If you use a lo
 
 ## Create token flow
 
-### 1. Ask user for required information (must be done first)
+### 1. Ask user for required AND optional information (must be done first)
 
-Before calling `create-token`, the Agent **must** ask the user for and confirm:
+Before calling `create-token`, the Agent **must** ask the user for all of the following parameters. For optional parameters, the Agent **must still ask** the user whether they want to provide a value — do not skip them silently. If the user declines or leaves them empty, omit them from the command.
 
 | 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).
+| **Token name** (name) | Yes | Full token name, max 255 chars |
+| **Token symbol** (symbol) | Yes | e.g. MTK, DOGE, max 32 chars |
+| **Image URL** (image_url) | Yes | Token image URL (e.g. IPFS link) |
+| **Description** (description) | No (but must ask) | Token description, e.g. a short intro for the token |
+| **X Royalty Party** (x_royalty_party) | No (but must ask) | X (Twitter) username for royalty party |
 
 ### 2. Technical flow (done by create-token)
 
 After collecting the above, execute:
 
 ```bash
-hotfun create-token <name> <symbol> <uri>
+hotfun create-token <name> <symbol> <image_url> [--description "desc"] [--x-royalty-party "username"]
 ```
 
 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.
+1. **Call API** — POST (multipart/form-data) to `https://gate.game.com/v3/hotfun/agent/create_pool_with_config` with payer (from PRIVATE_KEY), name, symbol, image_url, agent_ts (current Unix timestamp), agent_sign (Ed25519 signature of agent_ts with private key, base58 encoded), and optional description / x_royalty_party. 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`.
+Output JSON includes: `txHash`, `wallet`, `baseMint` (new token address), `dbcConfig`, `dbcPool`, `name`, `symbol`, `imageUrl`, `uri`.
 
 Full API and parameters: [references/api-create-token.md](references/api-create-token.md).
 
@@ -116,7 +116,7 @@ Full API and parameters: [references/api-create-token.md](references/api-create-
 
 | Need | Command | When |
 |------|---------|------|
-| **Create token** | `hotfun create-token <name> <symbol> <uri>` | API → sign → send to Solana. Env: PRIVATE_KEY. |
+| **Create token** | `hotfun create-token <name> <symbol> <image_url> [options]` | API → sign → send to Solana. Env: PRIVATE_KEY. |
 
 Chain: **Solana only**.
 
@@ -139,7 +139,6 @@ Set **PRIVATE_KEY** and optionally **SOLANA_RPC_URL** via the process environmen
 
 - **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
 

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

@@ -12,25 +12,22 @@ The `hotfun create-token` command handles the full flow in a single invocation:
 
 | Method | Endpoint |
 |--------|----------|
-| POST | `https://gate.game.com/v3/hotfun/create_pool_with_config` |
+| POST | `https://gate.game.com/v3/hotfun/agent/create_pool_with_config` |
 
 ### Request
 
-**Content-Type**: `application/x-www-form-urlencoded`
+**Content-Type**: `multipart/form-data`
 
 | 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/
-```
+| `name` | Yes | Token name, max 255 chars |
+| `symbol` | Yes | Token symbol, max 32 chars |
+| `image_url` | Yes | Token image URL (e.g. IPFS link) |
+| `agent_ts` | Yes | Current Unix timestamp (valid for 5 minutes) |
+| `agent_sign` | Yes | Ed25519 signature of `agent_ts` using wallet private key, base58 encoded |
+| `description` | No | Token description |
+| `x_royalty_party` | No | X (Twitter) username for royalty party |
 
 ### Response
 
@@ -41,10 +38,14 @@ Referer: https://hot.fun/
     "signature": "",
     "dbc_config": "<pubkey>",
     "dbc_pool": "<pubkey>",
-    "base_mint": "<pubkey>"
+    "base_mint": "<pubkey>",
+    "name": "MyToken",
+    "symbol": "MTK",
+    "uri": "<metadata URI>",
+    "royalty_party": "<pubkey>"
   },
   "common": {
-    "timestamp": 1772694804,
+    "timestamp": 1772948092,
     "app_name": "hotfunv3",
     "chain_asset_config": [...],
     "config": { "check_chinese_symbol_duplicate": false }
@@ -60,17 +61,33 @@ Referer: https://hot.fun/
 | `base_mint` | The new token's mint address |
 | `dbc_config` | DBC config account |
 | `dbc_pool` | DBC pool account |
+| `uri` | Token metadata URI (generated by API) |
+| `royalty_party` | Royalty party 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'
+curl --request POST \
+  --url https://gate.game.com/v3/hotfun/agent/create_pool_with_config \
+  --header 'content-type: multipart/form-data' \
+  --form payer=<WALLET_PUBKEY> \
+  --form 'name=MyToken' \
+  --form 'symbol=MTK' \
+  --form image_url=https://example.com/image.png \
+  --form 'description=A cool token' \
+  --form x_royalty_party=myTwitter \
+  --form agent_ts=1772947790 \
+  --form agent_sign=<BASE58_ED25519_SIGNATURE>
 ```
 
+## Authentication (agent_ts + agent_sign)
+
+To prevent abuse, the API requires request authentication:
+
+1. Generate `agent_ts`: current Unix timestamp in seconds.
+2. Generate `agent_sign`: sign the `agent_ts` string using the wallet's Ed25519 private key, then base58-encode the 64-byte signature.
+3. The timestamp is valid for 5 minutes from generation.
+
 ## Sign and Send
 
 1. Decode the base58 `transaction` string to bytes.

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

@@ -7,10 +7,14 @@
  * 3. Send the signed transaction to Solana RPC
  *
  * Usage:
- *   npx hotfun create-token <name> <symbol> <uri>
+ *   npx hotfun create-token <name> <symbol> <image_url> [options]
+ *
+ * Options:
+ *   --description <desc>        Token description
+ *   --x-royalty-party <user>    X (Twitter) username for royalty party
  *
  * Env: PRIVATE_KEY (Solana wallet private key, base58 or JSON array)
- * Optional env: SOLANA_RPC_URL, ROYALTY_PARTY
+ * Optional env: SOLANA_RPC_URL
  */
 
 import {
@@ -19,9 +23,9 @@ import {
   VersionedTransaction,
 } from '@solana/web3.js';
 import bs58 from 'bs58';
+import nacl from 'tweetnacl';
 
-const API_URL = 'https://gate.game.com/v3/hotfun/create_pool_with_config';
-const DEFAULT_ROYALTY_PARTY = '11111111111111111111111111111111';
+const API_URL = 'https://gate.game.com/v3/hotfun/agent/create_pool_with_config';
 
 function loadKeypair(privateKey: string): Keypair {
   try {
@@ -35,14 +39,36 @@ function loadKeypair(privateKey: string): Keypair {
   }
 }
 
-async function main() {
-  const name = process.argv[2];
-  const symbol = process.argv[3];
-  const uri = process.argv[4];
+function parseArgs(argv: string[]) {
+  const positional: string[] = [];
+  const options: Record<string, string> = {};
+  let i = 0;
+  while (i < argv.length) {
+    if (argv[i] === '--description' && i + 1 < argv.length) {
+      options.description = argv[++i];
+    } else if (argv[i] === '--x-royalty-party' && i + 1 < argv.length) {
+      options.xRoyaltyParty = argv[++i];
+    } else if (!argv[i].startsWith('--')) {
+      positional.push(argv[i]);
+    }
+    i++;
+  }
+  return { positional, options };
+}
 
-  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"');
+async function main() {
+  const { positional, options } = parseArgs(process.argv.slice(2));
+  const name = positional[0];
+  const symbol = positional[1];
+  const imageUrl = positional[2];
+
+  if (!name || !symbol || !imageUrl) {
+    console.error('Usage: npx hotfun create-token <name> <symbol> <image_url> [options]');
+    console.error('Options:');
+    console.error('  --description <desc>        Token description');
+    console.error('  --x-royalty-party <user>    X (Twitter) username for royalty party');
+    console.error('');
+    console.error('Example: npx hotfun create-token MyToken MTK "https://example.com/image.png" --description "A cool token" --x-royalty-party "myTwitter"');
     process.exit(1);
   }
 
@@ -54,35 +80,40 @@ async function main() {
 
   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');
 
+  // ── Generate agent_ts and agent_sign ──────────────────────────────────
+  const agentTs = Math.floor(Date.now() / 1000).toString();
+  const agentTsBytes = new TextEncoder().encode(agentTs);
+  const signature = nacl.sign.detached(agentTsBytes, keypair.secretKey);
+  const agentSign = bs58.encode(signature);
+
   // ── 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,
-  });
+  console.error(`  image_url: ${imageUrl}`);
+  if (options.description) console.error(`  description: ${options.description}`);
+  if (options.xRoyaltyParty) console.error(`  x_royalty_party: ${options.xRoyaltyParty}`);
+
+  const formData = new FormData();
+  formData.append('payer', payer);
+  formData.append('name', name);
+  formData.append('symbol', symbol);
+  formData.append('image_url', imageUrl);
+  formData.append('agent_ts', agentTs);
+  formData.append('agent_sign', agentSign);
+  if (options.description) formData.append('description', options.description);
+  if (options.xRoyaltyParty) formData.append('x_royalty_party', options.xRoyaltyParty);
 
   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(),
+    body: formData,
   });
 
   if (!res.ok) {
-    throw new Error(`API request failed: ${res.status} ${res.statusText}`);
+    const text = await res.text().catch(() => '');
+    throw new Error(`API request failed: ${res.status} ${res.statusText}\n${text}`);
   }
 
   const json = await res.json() as {
@@ -92,11 +123,15 @@ async function main() {
       dbc_config: string;
       dbc_pool: string;
       base_mint: string;
+      name: string;
+      symbol: string;
+      uri: string;
+      royalty_party: string;
     };
     common: Record<string, unknown>;
   };
 
-  const { transaction: txBase58, dbc_config, dbc_pool, base_mint } = json.data;
+  const { transaction: txBase58, dbc_config, dbc_pool, base_mint, uri } = json.data;
 
   if (!txBase58) {
     throw new Error('API returned empty transaction. Response: ' + JSON.stringify(json));
@@ -105,6 +140,7 @@ async function main() {
   console.error(`  base_mint: ${base_mint}`);
   console.error(`  dbc_config: ${dbc_config}`);
   console.error(`  dbc_pool: ${dbc_pool}`);
+  console.error(`  uri: ${uri}`);
 
   // ── Step 2: Deserialize and sign transaction ──────────────────────────
   const txBytes = bs58.decode(txBase58);
@@ -134,6 +170,7 @@ async function main() {
     dbcPool: dbc_pool,
     name,
     symbol,
+    imageUrl,
     uri,
   };
   console.log(JSON.stringify(out, null, 2));