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#

CodeMeaningMISSING_ARGRequired argument not providedINVALID_ARGInvalid argument value (e.g. logo file not found)TOKEN_FINALIZEDToken migrated to PancakeSwap V3, bonding curve closedINSUFFICIENT_BALANCENot enough tokens to sellERRORGeneral 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)#

ContractAddressToken Factory0x99A1F02f56E8356e6E90A880DBb1be6EC7485737Bonding Curve Template0xea508aD6B550E94aC45831F265B2bD5346d06700

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.