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](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 | `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.don't have the plugin yet? install it then click "run inline in claude" again.