diff --git a/README.md b/README.md index d815be7..df15188 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # pumpclaw -An agent skill for trading on pump.fun through [pumpfun-cli](https://github.com/chainstacklabs/pumpfun-cli). +An agent skill for trading on pump.fun and Raydium LaunchLab (letsbonk.fun, StonkFun and other launchpads) through [pumpfun-cli](https://github.com/chainstacklabs/pumpfun-cli). Works with any agent that supports the Agent Skills standard: [OpenClaw](https://github.com/openclaw/openclaw), [Claude Code](https://docs.anthropic.com/en/docs/claude-code), [Cursor](https://cursor.com), [Codex](https://openai.com/index/codex/), and others. @@ -21,7 +21,7 @@ https://github.com/chainstacklabs/pumpclaw ## What it does -Gives your AI agent the knowledge to operate pumpfun-cli: buy, sell, launch tokens, manage wallets, browse trending tokens, and handle migrations from bonding curve to PumpSwap AMM. +Gives your AI agent the knowledge to operate pumpfun-cli: buy and sell on pump.fun, PumpSwap, Raydium LaunchLab and Raydium CPMM, launch tokens, manage wallets, browse trending tokens, and handle migrations from bonding curve to PumpSwap AMM. Includes trading safety guardrails: dry-run simulation, slippage checks, balance validation. diff --git a/SKILL.md b/SKILL.md index 73bdde4..9e7feea 100644 --- a/SKILL.md +++ b/SKILL.md @@ -1,15 +1,17 @@ --- name: pumpclaw description: > - Execute pump.fun token trades via pumpfun-cli. Handles buy/sell with smart - routing (bonding curve vs PumpSwap AMM), slippage control, priority fees, - compute units, and dry-run simulation. Also covers token launch, migration, - wallet management, and token discovery. Use when the user wants to trade, - swap, buy, sell, launch, or manage pump.fun tokens. -compatibility: "Requires uv and pumpfun-cli 0.2 or later (install via uv from github.com/chainstacklabs/pumpfun-cli)" + Execute pump.fun and Raydium LaunchLab token trades via pumpfun-cli. Handles + buy/sell with smart routing (pump.fun bonding curve or PumpSwap AMM; LaunchLab + curve or Raydium CPMM, for letsbonk.fun, StonkFun and other launchpads), + slippage control, priority fees, compute units, and dry-run simulation. Also + covers pump.fun token launch, migration, wallet management, and token + discovery. Use when the user wants to trade, swap, buy, sell, launch, or + manage pump.fun, letsbonk.fun or StonkFun tokens. +compatibility: "Requires uv and pumpfun-cli 0.3 or later (install via uv from github.com/chainstacklabs/pumpfun-cli)" metadata: author: chainstacklabs - version: "0.2" + version: "0.3" category: crypto-trading requires: bins: ["uv", "pumpfun"] @@ -18,7 +20,8 @@ metadata: # PumpClaw — pump.fun Trading Skill -You are a pump.fun trading assistant operating through the `pumpfun` CLI. +You are a trading assistant for pump.fun and Raydium LaunchLab coins, operating +through the `pumpfun` CLI. ## Installing pumpfun-cli @@ -32,7 +35,7 @@ uv tool install git+https://github.com/chainstacklabs/pumpfun-cli.git uv tool install --force git+https://github.com/chainstacklabs/pumpfun-cli.git ``` -This installs `pumpfun` globally — available from any directory. `pumpfun --version` should report 0.2 or later; older versions build transactions the current pump.fun program rejects. +This installs `pumpfun` globally — available from any directory. `pumpfun --version` should report 0.3 or later; older versions can't trade LaunchLab coins and their `migrate` is rejected by the current programs. ## Pre-Trade Checklist @@ -41,15 +44,21 @@ Before any trade, verify: 1. **Wallet exists**: `pumpfun wallet show` — confirms keystore is set up 2. **RPC configured**: `pumpfun config set rpc `, or `PUMPFUN_RPC` env var, or `--rpc` flag 3. **Balance sufficient**: `pumpfun wallet balance` — SOL for fees, plus the coin's quote asset for the spend -4. **Token status**: `pumpfun info ` — bonding curve or graduated to PumpSwap AMM, and which quote asset it is priced in (`quote_symbol`) +4. **Token status**: `pumpfun info ` — which venue the coin trades on (`venue`), whether it has graduated, and which quote asset it is priced in (`quote_symbol`) ## Smart Routing -The CLI automatically routes trades based on token status: +The CLI finds where a coin trades and routes there; `venue` in every result says which: -- **On bonding curve** → uses pump.fun bonding curve instructions -- **Graduated to AMM** → uses PumpSwap AMM instructions -- **Force AMM** → `--force-amm` flag bypasses bonding curve check +| Coin | Before graduation | After graduation | +|---|---|---| +| pump.fun | `bonding_curve` | `pumpswap` (PumpSwap AMM) | +| Raydium LaunchLab: letsbonk.fun, StonkFun, other launchpads | `launchlab` | `cpmm` (Raydium CPMM) | + +- `--force-amm` skips the curve and trades in the coin's pool: PumpSwap, or CPMM for a LaunchLab coin +- LaunchLab results also name the launchpad (`platform`) +- A LaunchLab coin that graduated to Raydium AMM v4 instead is refused (`unsupported_venue`) +- `launch`, `migrate`, `claim-cashback`, `collect-creator-fee`, `close-volume-acc` and `tokens` are pump.fun only Always run `pumpfun info ` first to understand the token's current state. @@ -65,6 +74,18 @@ every amount is in it: Check `quote_symbol` in `pumpfun info ` before choosing an amount. +LaunchLab coins are often priced in something other than SOL (USDC, tokenized +stocks, other tokens). The CLI finds such a coin with `getProgramAccounts`, so +it needs an RPC that serves that method. + +### Transfer fees + +Some LaunchLab coins (StonkFun reward coins, for example) are Token-2022 mints +with a transfer fee: `transfer_fee_bps` in `pumpfun info`. A buy delivers that +much less and a sell sends that much less into the pool, so a round trip loses +the fee twice on top of the trading fees (`curve_fee_pct`, `pool_fee_pct`). The +CLI's amounts already count it; tell the user before trading a coin that has one. + ## Core Trading Commands ### Buy tokens @@ -87,7 +108,7 @@ pumpfun sell [--slippage 15] [--force-amm] [--confirm] [--dr ```bash pumpfun info [--timeout 30] ``` -Shows price, quote asset, bonding curve progress, reserves, graduation status, and whether the coin is mayhem, cashback or holder-reward. +Shows venue, price, quote asset, bonding curve progress, reserves and graduation status. pump.fun coins add whether they are mayhem, cashback or holder-reward; LaunchLab coins add the launchpad (`platform`), `curve_fee_pct`, `transfer_fee_bps`, and once graduated the CPMM pool (`pool_address`, reserves, `pool_fee_pct`). ### Launch a token ```bash @@ -116,6 +137,9 @@ pumpfun buy --confirm # Execute ``` ### "Sell all of token Z" +A curve can be short of the quote it owes: a pump.fun sell it can't fully pay +for sells what it can and reports the rest in `tokens_kept`, which stay in the +wallet. ```bash pumpfun wallet tokens # Verify holding pumpfun sell all --dry-run # Simulate @@ -153,7 +177,14 @@ These apply to ALL commands: | Insufficient balance | Not enough SOL, or not enough of the coin's quote asset | Check `pumpfun wallet balance`, fund wallet | | Slippage exceeded | Price moved beyond tolerance | Increase `--slippage` or retry | | RPC error | Network/endpoint issue | Check `PUMPFUN_RPC`, try different endpoint | -| Token not found | Invalid mint address | Verify the mint with `pumpfun info `, or find it by name with `pumpfun tokens search ` | +| "No pump.fun or LaunchLab coin found" | Invalid mint, or a coin on another launchpad | Verify the mint with `pumpfun info `, or find it by name with `pumpfun tokens search ` | +| "asks for more than the … tokens left on the bonding curve" | The buy is bigger than what's left on the curve | Spend less | +| "real reserves can't pay anything for these tokens now" | The pump.fun curve can't pay for a sell right now | Nothing was sent; retry later, or after graduation | +| "Too few tokens" | The curve or pool would pay nothing for them | Nothing was sent | +| "CPMM pool is not open yet" | The LaunchLab curve is complete, Raydium hasn't opened the pool | Wait and retry | +| "graduated to Raydium AMM v4" | The LaunchLab coin migrated somewhere this CLI can't trade | Don't trade it with this CLI | +| "getProgramAccounts" | The RPC won't search LaunchLab pools for a coin priced in something other than SOL | Use an RPC that serves `getProgramAccounts` | +| "pump.fun API returned HTTP 403" from `tokens` | pump.fun's listing API is refusing non-browser clients | Listings are unavailable; ask the user for the mint | ## Full Command Reference diff --git a/assets/token-lifecycle.md b/assets/token-lifecycle.md index 3824eb4..1787c73 100644 --- a/assets/token-lifecycle.md +++ b/assets/token-lifecycle.md @@ -54,6 +54,14 @@ pumpfun claim-cashback --confirm # Volume-based rewards pumpfun close-volume-acc # Recover rent from volume tracker ``` +## Raydium LaunchLab Coins (letsbonk.fun, StonkFun, other launchpads) + +The same shape on different programs: a LaunchLab bonding curve, then a Raydium +CPMM pool once Raydium migrates the completed curve. `buy`, `sell` and `info` +route there on their own (`venue`: `launchlab`, then `cpmm`), and `--force-amm` +goes straight to the CPMM pool. Between completion and the pool opening, trades +say the CPMM pool is not open yet. Launch, `migrate`, fees and cashback are pump.fun only. + ## Status Check at Any Phase ``` @@ -65,4 +73,4 @@ Returns: - Bonding curve progress (if applicable) - Quote and token reserves - Whether token has graduated -- Which routing path buy/sell will use +- Which venue buy/sell will use (`venue`) diff --git a/references/OPERATIONS.md b/references/OPERATIONS.md index cbef149..2a44bc1 100644 --- a/references/OPERATIONS.md +++ b/references/OPERATIONS.md @@ -3,27 +3,27 @@ ## Trading Operations ### `pumpfun buy ` -Spend exactly `amount` of the coin's quote asset (SOL for most coins). Smart-routes between bonding curve and PumpSwap AMM. A non-SOL coin spends that asset, which the wallet must hold. +Spend exactly `amount` of the coin's quote asset (SOL for most coins). Routes to where the coin trades: a pump.fun curve or PumpSwap, a Raydium LaunchLab curve or Raydium CPMM (`venue` in the result). A non-SOL coin spends that asset, which the wallet must hold. | Option | Type | Default | Description | |---|---|---|---| | `--slippage` | INTEGER | 15 | Slippage tolerance percent | -| `--force-amm` | FLAG | off | Skip bonding curve, buy directly on PumpSwap AMM | +| `--force-amm` | FLAG | off | Skip the bonding curve, buy in the pool (PumpSwap, or CPMM for LaunchLab coins) | | `--confirm` | FLAG | off | Wait for transaction confirmation | | `--dry-run` | FLAG | off | Simulate trade without sending transaction | ### `pumpfun sell ` -Sell tokens for the coin's quote asset. Amount can be a number or `all`. +Sell tokens for the coin's quote asset, routed like `buy`. Amount can be a number or `all`. A pump.fun curve sell its reserves can't fully pay for sells what they cover and reports the rest as `tokens_kept`. | Option | Type | Default | Description | |---|---|---|---| | `--slippage` | INTEGER | 15 | Slippage tolerance percent | -| `--force-amm` | FLAG | off | Skip bonding curve, sell directly on PumpSwap AMM | +| `--force-amm` | FLAG | off | Skip the bonding curve, sell in the pool (PumpSwap, or CPMM for LaunchLab coins) | | `--confirm` | FLAG | off | Wait for transaction confirmation | | `--dry-run` | FLAG | off | Simulate trade without sending transaction | ### `pumpfun info ` -Display on-chain token info — quote asset, price, bonding progress, reserves, graduation status, creator fee, and mayhem/cashback/holder-reward flags. +Display on-chain token info — venue, quote asset, price, bonding progress, reserves and graduation status. pump.fun coins add creator fee and mayhem/cashback/holder-reward flags; LaunchLab coins add the launchpad (`platform`), curve fee, transfer fee and, once graduated, their CPMM pool. | Option | Type | Default | Description | |---|---|---|---| @@ -54,7 +54,7 @@ Launch a new token on pump.fun (create_v2 + extend_account). With `--buy`, the o ## Migration ### `pumpfun migrate ` -Trigger migration from bonding curve to PumpSwap AMM. Only works when bonding curve is complete. +Trigger migration of a pump.fun coin from bonding curve to PumpSwap AMM. Only works when bonding curve is complete. LaunchLab coins are migrated by Raydium, not by this command. | Option | Type | Default | Description | |---|---|---|---| diff --git a/references/SAFETY.md b/references/SAFETY.md index ccb967e..dc8aedf 100644 --- a/references/SAFETY.md +++ b/references/SAFETY.md @@ -5,7 +5,7 @@ 1. **Dry-run first** — always simulate with `--dry-run` before committing funds 2. **Check token info** — run `pumpfun info ` to understand current price, reserves, and graduation status 3. **Verify balance** — `pumpfun wallet balance` to confirm you can cover the trade (in the coin's quote asset) + transaction fees in SOL -4. **Know the routing** — bonding curve tokens and graduated AMM tokens behave differently +4. **Know the routing** — bonding curve tokens and graduated AMM tokens behave differently, and `venue` says which one a trade used ## Slippage Management @@ -31,9 +31,10 @@ | Status | Routing | Notes | |---|---|---| -| On bonding curve | pump.fun bonding curve | Price follows curve formula | +| On bonding curve | pump.fun or LaunchLab bonding curve | Price follows curve formula | | Near graduation | Bonding curve | Watch for graduation — liquidity shift incoming | -| Graduated (AMM) | PumpSwap AMM | Standard AMM pricing, deeper liquidity | +| Graduated (AMM) | PumpSwap (pump.fun) or Raydium CPMM (LaunchLab) | Standard AMM pricing, deeper liquidity | +| LaunchLab coin waiting for its pool | None | "CPMM pool is not open yet": retry once it opens | ## Red Flags @@ -42,6 +43,8 @@ - Selling `all` of a large position — may move price significantly - Multiple rapid trades — each one pays transaction fees - A coin priced in something other than SOL — `buy` spends that asset, not SOL; check `quote_symbol` first +- A coin with a transfer fee (`transfer_fee_bps` in `info`) — a round trip pays it twice, on top of trading fees +- A sell result with `tokens_kept` — the curve couldn't pay for all of them; those tokens are still in the wallet ## Password Handling diff --git a/scripts/check-prereqs.sh b/scripts/check-prereqs.sh index 11415a3..de7acad 100755 --- a/scripts/check-prereqs.sh +++ b/scripts/check-prereqs.sh @@ -9,7 +9,13 @@ if ! command -v pumpfun &>/dev/null && ! uv run pumpfun --version &>/dev/null 2> echo "ERROR: pumpfun CLI not found. Install via: uv tool install git+https://github.com/chainstacklabs/pumpfun-cli.git" errors=$((errors + 1)) else - echo "OK: pumpfun CLI available" + version=$( (pumpfun --version 2>/dev/null || uv run pumpfun --version 2>/dev/null) | awk '{print $NF}') + if [ "$(printf '%s\n' 0.3.0 "$version" | sort -V | head -1)" = "0.3.0" ]; then + echo "OK: pumpfun CLI $version available" + else + echo "ERROR: pumpfun CLI $version is older than 0.3. Upgrade: uv tool install --force git+https://github.com/chainstacklabs/pumpfun-cli.git" + errors=$((errors + 1)) + fi fi # Check RPC endpoint