Skill: hodldance/hodl-dance (version 1.3.1)

# HODL.DANCE Agent Skill Trade memecoins on the [HODL.DANCE](https://hodl.dance) bonding curve launchpad on BSC (BNB Chain). ## Overview HODL.DANCE is a memecoin launchpad on BSC using a CPMM bonding curve (r × t = k). Tokens trade on the curve until 19 BNB is raised, then liquidity auto-migrates to PancakeSwap V3. - **Network:** BSC Mainnet (Chain ID: 56) - **Native currency:** BNB - **Fee:** 1% per trade (buy and sell) - **API:** [https://hodl.dance/api](https://hodl.dance/api) (public, no API key required) - **Docs:** [https://docs.hodl.dance](https://docs.hodl.dance) ## Installation ```bash npm install -g @hodl-dance/skill # or without installing: npx @hodl-dance/skill <command> ``` ## Credentials Required only for `create-token`, `buy-token` and `sell-token`: ```bash export HODL_PRIVATE_KEY=0xyour_private_key export HODL_RPC_URL=https://bsc-dataseed.binance.org/ # optional ``` > ⚠️ The private key is used locally only to sign transactions. Never share it. --- ## Commands ### `get-tokens` List tokens with filtering and sorting. Returns full token objects including `bonding_curve_address`. ```bash hodl-skill get-tokens hodl-skill get-tokens --sort=market_cap --limit=10 hodl-skill get-tokens --sort=volume --verified=true hodl-skill get-tokens --sort=progress --finalized=false hodl-skill get-tokens --search=pepe --limit=5 ``` **Options:** `--sort=newest|market_cap|progress|volume` · `--limit=N` (max 100) · `--offset=N` · `--verified=true|false` · `--finalized=true|false` · `--search=<text>` **Key output fields per token:** - `address` — token contract address - `bonding_curve_address` — ⭐ use this in quote/buy-token/sell-token - `market_cap_usd`, `progress_percent` (0–100 toward PancakeSwap migration) - `finalized` — if true, bonding curve is closed, token is on PancakeSwap V3 - `price_change_24h`, `trades_24h`, `volume_24h_bnb` --- ### `get-token <tokenAddress>` Full token details + 20 most recent trades. ```bash hodl-skill get-token 0x1a2b3c... ``` Returns same fields as `get-tokens` plus `recent_trades[]`. --- ### `get-trades <tokenAddress>` Trade history for a specific token. ```bash hodl-skill get-trades 0x1a2b3c... hodl-skill get-trades 0x1a2b3c... --type=buy --limit=20 ``` **Options:** `--type=all|buy|sell` · `--limit=N` (max 500) · `--offset=N` --- ### `quote <bondingCurveAddress> buy|sell <amount>` **Simulate** trade output using live on-chain state. No transaction sent, no gas used. ```bash # How many tokens will I get for 0.1 BNB? hodl-skill quote 0xbc1234... buy 0.1 # How much BNB will I get for selling 500000 tokens? hodl-skill quote 0xbc1234... sell 500000 ``` > Always run `quote` before `buy-token` or `sell-token` to verify expected amounts. --- ### `create-token` Deploy a new token + bonding curve on HODL.DANCE. Uploads logo to IPFS, then sends on-chain transaction. ```bash hodl-skill create-token --name="Moon Cat" --symbol=MCAT --logo=./logo.png hodl-skill create-token \ --name="Moon Cat" \ --symbol=MCAT \ --logo=./logo.png \ --category=meme \ --description="The cat that dances on the moon" \ --twitter="https://x.com/mooncat" \ --telegram="https://t.me/mooncat" \ --website="https://mooncat.io" \ --initial-buy=0.1 ``` **Requires:** `HODL_PRIVATE_KEY` **Options:** - `--name` — token name, 3–40 characters *(required)* - `--symbol` — token symbol, 1–10 characters *(required)* - `--logo` — path to local image file PNG/JPG/WEBP, max 5MB *(required)* - `--category` — `meme|ai|games|social|other` (default: `meme`) - `--description` — token description, max 500 characters - `--website` — `https://...` - `--twitter` — `https://x.com/...` - `--telegram` — `https://t.me/...` - `--initial-buy` — BNB amount to buy in the same transaction (default: `0`) > Deploy fee: **0.0001 BNB**. If `--initial-buy` is set, total value = `0.0001 + initial-buy`. **Output:** `tx_hash`, `block_number`, `gas_used`, `token_address`, `bonding_curve_address`, `name`, `symbol`, `category`, `logo_ipfs`, `initial_buy_bnb` --- ### `buy-token <bondingCurveAddress> <bnbAmount> [--recipient=0x...]` Buy tokens using BNB. Sends transaction on-chain. ```bash hodl-skill buy-token 0xbc1234... 0.1 hodl-skill buy-token 0xbc1234... 0.5 --recipient=0xfriend... ``` **Requires:** `HODL_PRIVATE_KEY` **Output:** `tx_hash`, `bnb_spent`, `tokens_received`, `tokens_estimated`, `fee_bnb`, `block_number`, `gas_used` --- ### `sell-token <bondingCurveAddress> <tokenAmount>` Sell tokens, receive BNB. ```bash hodl-skill sell-token 0xbc1234... 1000000 ``` **Requires:** `HODL_PRIVATE_KEY` > ⚠️ **Selling requires ERC20 `approve` before `sellTokens`.** > This skill handles it automatically in two steps: > 1. Checks current `allowance` — if insufficient, sends `approve()` transaction first > 2. Sends `sellTokens()` transaction > > The output field `approve_was_needed: true/false` tells you whether approve was sent. > If approve was needed, `approve_tx_hash` contains its transaction hash. > Total gas cost may cover 2 transactions if approve was required. **Output:** `tx_hash`, `tokens_sold`, `bnb_received`, `bnb_estimated`, `fee_bnb`, `approve_tx_hash`, `approve_was_needed`, `block_number`, `gas_used` --- ## Response Format All commands output JSON to stdout: ```json { "success": true, "data": { ... } } ``` Errors: ```json { "success": false, "error": { "code": "TOKEN_FINALIZED", "message": "..." } } ``` Exit code `0` = success, `1` = error. ### Error Codes | Code | Meaning | |---|---| | `MISSING_ARG` | Required argument not provided | | `INVALID_ARG` | Invalid argument value (e.g. logo file not found) | | `TOKEN_FINALIZED` | Token migrated to PancakeSwap V3, bonding curve closed | | `INSUFFICIENT_BALANCE` | Not enough tokens to sell | | `ERROR` | General error (message contains details) | --- ## Typical Agent Workflow ``` 1. get-tokens --sort=volume --limit=10 → find tokens with activity, note bonding_curve_address 2. get-token <tokenAddress> → check progress_percent, finalized, recent_trades 3. quote <bondingCurveAddress> buy 0.1 → verify tokens_out before committing 4. buy-token <bondingCurveAddress> 0.1 → execute, save tx_hash and tokens_received 5. [later] quote <bondingCurveAddress> sell <tokens_received> → check exit value 6. sell-token <bondingCurveAddress> <tokens_received> → approve sent automatically if needed, then sell → check approve_was_needed in output ``` ### Token Launch Workflow ``` 1. create-token --name="..." --symbol=... --logo=./logo.png --initial-buy=0.1 → deploys token + bonding curve, returns token_address and bonding_curve_address 2. quote <bonding_curve_address> buy 0.5 → verify expected tokens before buying more 3. buy-token <bonding_curve_address> 0.5 → accumulate position ``` --- ## Contract Addresses (BSC Mainnet, Chain ID 56) | Contract | Address | |---|---| | Token Factory | [REDACTED_SECRET] | | Bonding Curve Template | [REDACTED_SECRET] | > Each token has its own unique Bonding Curve instance. > Always fetch `bonding_curve_address` from `get-token`, `get-tokens` or `create-token` — do not use the template address.


Security scan verdicts — ClawScan: suspicious | static analysis: suspicious | VirusTotal:  | SkillSpector: suspicious (MEDIUM)