Hodl Dance Skill

Trade, create, and manage memecoins on HODL.DANCE's BSC bonding curve launchpad. Launch tokens with logo upload and optional initial buy, get live quotes, bu...

HODL.DANCE Agent Skill

Trade memecoins on the 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 (public, no API key required)
• Docs: 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

text

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

text

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	0x99A1F02f56E8356e6E90A880DBb1be6EC7485737
Bonding Curve Template	0xea508aD6B550E94aC45831F265B2bD5346d06700

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.