diff --git a/CLAUDE.md b/CLAUDE.md index 81e4e8f..62402f6 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,6 +1,6 @@ # CLAUDE.md — pumpfun-cli -CLI for trading, launching, and browsing tokens on pump.fun (Solana). Python 3.12+, uv, Typer, solana-py/solders. +CLI for trading on pump.fun and Raydium LaunchLab launchpads (Solana), and launching on pump.fun. Python 3.12+, uv, Typer, solana-py/solders. ## Commands diff --git a/README.md b/README.md index aef84bd..df50222 100644 --- a/README.md +++ b/README.md @@ -1,123 +1,96 @@ -# pumpfun-cli +Labs -A standalone command-line tool for launching and trading tokens on [pump.fun](https://pump.fun), and for trading coins launched on Raydium LaunchLab (letsbonk.fun, StonkFun and other launchpads). +

+

Chainstack is the leading suite of services connecting developers with Web3 infrastructure

+

-Built from experience developing [pumpfun-bot](https://github.com/chainstacklabs/pumpfun-bonkfun-bot), distilled into a stateless CLI designed for humans, scripts, and LLM agents alike. +

+ • Homepage • + Supported protocols • + Chainstack blog • + Blockchain API reference •
+ • Start for free • +

-> Check out also our [skill](https://github.com/chainstacklabs/pumpclaw) for trading on pump.fun with OpenClaw and other agents. +A stateless command-line tool for trading on **pump.fun** and on **letsbonk.fun**, **StonkFun** and every other launchpad on Raydium LaunchLab. It buys and sells on the bonding curve, follows graduated coins into PumpSwap and Raydium CPMM, and launches pump.fun coins. Built for humans, scripts and AI agents alike: every command can answer in JSON. -Works on macOS, Linux, and Windows (via [WSL](https://learn.microsoft.com/en-us/windows/wsl/install)). Native Windows is not tested. +It is distilled from [pumpfun-bonkfun-bot](https://github.com/chainstacklabs/pumpfun-bonkfun-bot) and works on macOS, Linux and Windows through [WSL](https://learn.microsoft.com/en-us/windows/wsl/install); native Windows is not tested. -## Install +> **Also by Chainstack** +> - [**pumpfun-bonkfun-bot**](https://github.com/chainstacklabs/pumpfun-bonkfun-bot) — trading and sniping bot for the same venues: watches for new coins, buys, and exits on a strategy you configure. +> - [**pumpclaw**](https://github.com/chainstacklabs/pumpclaw) — agent skill that equips AI assistants (OpenClaw, Claude Code, Cursor, Codex) with the ability to operate this CLI. -Requires [uv](https://docs.astral.sh/uv/getting-started/installation/) and Python 3.12+. +--- -### From GitHub (recommended) +**🚨 SCAM ALERT**: The Issues section is regularly targeted by scam bots that try to redirect you to an external site and drain your funds. Deleted comments in issues are scam bots after your private keys — genuine outside devs are welcome and appreciated. -```bash -uv tool install git+https://github.com/chainstacklabs/pumpfun-cli.git -``` +**⚠️ NOT FOR PRODUCTION**: This code is for learning purposes only. We assume no responsibility for the code or its usage. Every trade spends real funds; preview it with `--dry-run` first. + +--- + +## Getting started -This installs `pumpfun` globally — available from any directory. +### 1. Prerequisites -### From a local clone +Install [uv](https://docs.astral.sh/uv/getting-started/installation/). The CLI needs **Python 3.12+**; `uv` uses an existing install if it's new enough, otherwise it fetches one for you. + +You also need a Solana RPC endpoint for anything that reads or writes the chain. Public RPC nodes won't hold up — see [throughput](#throughput-and-rate-limits) below. + +### 2. Install ```bash -git clone https://github.com/chainstacklabs/pumpfun-cli.git -cd pumpfun-cli -uv tool install . +uv tool install git+https://github.com/chainstacklabs/pumpfun-cli.git ``` -### Upgrade +This puts `pumpfun` on your path, available from any directory. To install from a clone instead, run `uv tool install .` in it. ```bash -# From GitHub -uv tool install --force git+https://github.com/chainstacklabs/pumpfun-cli.git - -# From local clone (after git pull) -uv tool install --force . +uv tool install --force git+https://github.com/chainstacklabs/pumpfun-cli.git # upgrade +uv tool uninstall pumpfun-cli # remove ``` -### Uninstall +### 3. Set your RPC endpoint and wallet ```bash -uv tool uninstall pumpfun-cli +pumpfun config set rpc https://your-node.chainstack.com/abc123 +pumpfun wallet create # or: pumpfun wallet import ``` -## Quick start +The wallet is stored encrypted in `~/.config/pumpfun-cli/wallet.enc`, and the config in `~/.config/pumpfun-cli/config.toml`. A command-line flag overrides an environment variable, which overrides the config file: -```bash -# Browse tokens — works immediately, no config needed -pumpfun tokens trending -pumpfun tokens search "dog" +| Variable | Purpose | +|---|---| +| `PUMPFUN_RPC` | HTTPS RPC endpoint (or `--rpc`) | +| `PUMPFUN_KEYFILE` | Path to the encrypted wallet (or `--keyfile`) | +| `PUMPFUN_PASSWORD` | Wallet password, so commands don't prompt for it | +| `PUMPFUN_PRIORITY_FEE` | Priority fee in micro-lamports (or `--priority-fee`) | +| `PUMPFUN_COMPUTE_UNITS` | Compute unit limit (or `--compute-units`) | -# Set up for trading -pumpfun config set rpc https://your-node.chainstack.com/abc123 -pumpfun wallet create +### 4. Trade -# Preview a trade (no transaction sent) -pumpfun buy 0.1 --dry-run +```bash +pumpfun info # where it trades, price, quote asset +pumpfun buy 0.1 --dry-run # preview: nothing is sent +pumpfun buy 0.1 --confirm # spend exactly 0.1 of the coin's quote asset +pumpfun sell all --confirm +pumpfun tx-status # did it land? +``` -# Trade -pumpfun buy 0.1 -pumpfun sell all +`--json` makes any command answer in JSON; it is on automatically when the output is piped. -# Check if a transaction landed -pumpfun tx-status +### 5. Launch a coin -# Launch a token, buying it in the same transaction +```bash pumpfun launch --name "MyToken" --ticker "MTK" --uri https://example.com/mytoken.json --buy 0.1 ``` -pump.fun no longer accepts anonymous metadata uploads, so `launch` takes the -URI of a metadata JSON you host (`name`, `symbol`, `description`, `image`). -Without `--uri` it still tries the upload and says so when it is refused. - -`buy`, `sell` and `info` also work on coins launched on Raydium LaunchLab, the -program behind letsbonk.fun, StonkFun and other launchpads: a mint with no -pump.fun bonding curve is looked up there, and the output says `"venue": -"launchlab"` and which launchpad (`platform`). A LaunchLab coin priced in -anything but SOL is found with `getProgramAccounts`, so it needs an RPC that -serves it. Token-2022 transfer fees are taken into account in the amounts. -Once a LaunchLab coin graduates it trades on Raydium CPMM (`"venue": "cpmm"`), -the same way a graduated pump.fun coin trades on PumpSwap; `--force-amm` goes -straight to whichever pool the coin has. A coin that graduated to Raydium AMM -v4 instead is refused. - -Amounts are in the coin's quote asset. Most pump.fun coins are priced in SOL, -but a coin can be priced in USDC or another admitted mint; `buy`, `sell` and -`info` read it from the coin and label their output with it. Buying such a coin -spends that asset, so the wallet has to hold it. - -In `--json` output an exact amount comes twice: in whole units for reading -(`tokens_sold`) and as the integer in raw units (`tokens_sold_raw`). Use the -`_raw` field for anything that has to add up; the float can drop a unit. An -amount known only as an estimate has no `_raw` twin: `quote_received`, the -`collect-creator-fee` totals, and `tokens_received` unless the buy ran with -`--confirm`, in which case it is read from the confirmed transaction. If that -transaction cannot be read back, a confirmed buy also reports the estimate -without `tokens_received_raw`, so check for the field. Dry-run fields -(`expected_tokens_raw`, `expected_quote_raw`, `min_*_out_raw`) are exact -integers of the quote the transaction would be built from, not executed amounts. - -A bonding curve pays a sell out of its real reserves, which on some coins hold -less than the price promises. `sell` then sells the most the curve can pay for -and reports the rest as `tokens_kept`; when it can pay nothing it sends nothing -(`curve_short`). A buy bigger than what is left on the curve fails with -`exceeds_curve` and the tokens left in `curve_tokens_left`. +pump.fun no longer accepts anonymous metadata uploads, so `launch` takes the URI of a metadata JSON you host (`name`, `symbol`, `description`, `image`). Without `--uri` it still tries the upload and says so when it is refused. `--buy` buys in the same transaction as the create, so nobody buys first. ## Commands ``` -Token discovery (zero config; price and progress added when an RPC is set): - pumpfun tokens trending [--limit N] pump.fun's movers board - pumpfun tokens new [--limit N] Recently launched - pumpfun tokens graduating [--limit N] Closest to bonding curve completion - pumpfun tokens recommended [--limit N] Recommended by pump.fun (at most 10) - pumpfun tokens search Search by name or ticker - Token info (requires RPC): - pumpfun info Price, bonding progress, reserves (pump.fun or LaunchLab, and their pools) + pumpfun info Venue, price, bonding progress, reserves Trading (requires RPC + wallet): pumpfun buy [--slippage N] [--force-amm] [--dry-run] [--confirm] @@ -128,19 +101,28 @@ Trading (requires RPC + wallet): pumpfun close-volume-acc [--confirm] Transaction inspection (requires RPC): - pumpfun tx-status Confirmation status, slot, fee, errors + pumpfun tx-status Confirmation status, slot, fee, errors Token launch (requires RPC + wallet): pumpfun launch --name X --ticker Y [--uri U | --desc D --image P] [--buy N] [--quote-mint M] [--creator-fee-bps N] [--holder-reward] [--mayhem] [--slippage N] [--confirm] +Token discovery (price and progress added when an RPC is set): + pumpfun tokens trending [--limit N] pump.fun's movers board + pumpfun tokens new [--limit N] Recently launched + pumpfun tokens graduating [--limit N] Closest to bonding curve completion + pumpfun tokens recommended [--limit N] Recommended by pump.fun (at most 10) + pumpfun tokens search Search by name or ticker + Wallet management: pumpfun wallet create Generate + encrypt keypair pumpfun wallet import Import existing keypair pumpfun wallet show Display public key pumpfun wallet balance SOL + token balances + pumpfun wallet tokens Token accounts with balances pumpfun wallet transfer Transfer SOL or tokens (--mint for SPL) + pumpfun wallet close-atas Close empty token accounts, recover rent pumpfun wallet drain Close all ATAs + transfer remaining SOL pumpfun wallet export --output Export as Solana keypair JSON @@ -148,6 +130,7 @@ Config: pumpfun config set pumpfun config get pumpfun config list + pumpfun config delete Global options: --version Show version and exit @@ -158,16 +141,43 @@ Global options: --compute-units N Compute unit limit (overrides default) ``` +## Trading reference + +### Venues + +`buy`, `sell` and `info` find where a coin trades and go there; `venue` in every result says which: + +| Coin | On its curve | After graduation | +|---|---|---| +| pump.fun | `bonding_curve` | `pumpswap` (PumpSwap) | +| Raydium LaunchLab: letsbonk.fun, StonkFun, other launchpads | `launchlab` | `cpmm` (Raydium CPMM) | + +A mint with no pump.fun bonding curve is looked up on LaunchLab, and LaunchLab results name the launchpad (`platform`). `--force-amm` skips the curve and trades in the coin's pool: PumpSwap, or CPMM for a LaunchLab coin. A LaunchLab coin that graduated to Raydium AMM v4 instead is refused. `launch`, `migrate`, the fee and cashback commands and `tokens` are pump.fun only. + +### Quote assets + +Amounts are in the coin's quote asset. Most pump.fun coins are priced in SOL, but a coin can be priced in USDC or another admitted mint, and LaunchLab coins often are (tokenized stocks, other tokens). `buy`, `sell` and `info` read the quote asset from the coin and label their output with it (`quote_symbol`). Buying such a coin spends that asset, so the wallet has to hold it. + +A LaunchLab coin priced in anything but SOL is found with `getProgramAccounts`, so it needs an RPC that serves it. + +### Transfer fees + +Some LaunchLab coins (StonkFun reward coins, for example) are Token-2022 mints with a transfer fee, shown as `transfer_fee_bps` by `info`. A buy delivers that much less and a sell sends that much less into the pool. The CLI's amounts and slippage floors already count it. + +### Amounts in JSON output + +An exact amount comes twice: in whole units for reading (`tokens_sold`) and as the integer in raw units (`tokens_sold_raw`). Use the `_raw` field for anything that has to add up; the float can drop a unit. An amount known only as an estimate has no `_raw` twin: `quote_received`, the `collect-creator-fee` totals, and `tokens_received` unless the buy ran with `--confirm`, in which case it is read from the confirmed transaction. If that transaction cannot be read back, a confirmed buy also reports the estimate without `tokens_received_raw`, so check for the field. Dry-run fields (`expected_tokens_raw`, `expected_quote_raw`, `min_*_out_raw`) are exact integers of the quote the transaction would be built from, not executed amounts. + +An error comes back as `{"error": , "hint": ..., "exit_code": ...}` with a non-zero exit status. + +### Curve limits + +A pump.fun bonding curve pays a sell out of its real reserves, which on some coins hold less than the price promises. `sell` then sells the most the curve can pay for and reports the rest as `tokens_kept`; when it can pay nothing it sends nothing and says so. A buy bigger than what is left on the curve fails with a message naming how many tokens remain. + ## Endpoints | Command | Endpoint | Protocol | |---------|----------|----------| -| `tokens trending` | `frontend-api-v3.pump.fun/coins/boards/movers` | HTTPS | -| `tokens new` | `frontend-api-v3.pump.fun/coins/boards/new` | HTTPS | -| `tokens graduating` | `frontend-api-v3.pump.fun/coins/boards/graduating` | HTTPS | -| `tokens recommended` | `frontend-api-v3.pump.fun/coins/recommendations` | HTTPS | -| `tokens search` | `frontend-api-v3.pump.fun/coins/search-unrestricted` | HTTPS | -| `tokens *` with an RPC set | + Solana RPC (`getMultipleAccounts` for the bonding curves) | JSON-RPC | | `info` | Solana RPC (`getAccountInfo` for bonding curve PDA; LaunchLab: `getMultipleAccounts`, `getProgramAccounts`) | JSON-RPC | | `buy` | Solana RPC (`getAccountInfo`, `getLatestBlockhash`, `sendTransaction`; LaunchLab adds `getMultipleAccounts`, `getProgramAccounts`) | JSON-RPC | | `sell` | Solana RPC (`getAccountInfo`, `getTokenAccountBalance`, `getLatestBlockhash`, `sendTransaction`; LaunchLab as `buy`) | JSON-RPC | @@ -177,75 +187,73 @@ Global options: | `claim-cashback` | Solana RPC (`sendTransaction`) | JSON-RPC | | `collect-creator-fee` | Solana RPC (`sendTransaction`) | JSON-RPC | | `close-volume-acc` | Solana RPC (`sendTransaction`) | JSON-RPC | +| `tokens trending` | `frontend-api-v3.pump.fun/coins/boards/movers` | HTTPS | +| `tokens new` | `frontend-api-v3.pump.fun/coins/boards/new` | HTTPS | +| `tokens graduating` | `frontend-api-v3.pump.fun/coins/boards/graduating` | HTTPS | +| `tokens recommended` | `frontend-api-v3.pump.fun/coins/recommendations` | HTTPS | +| `tokens search` | `frontend-api-v3.pump.fun/coins/search-unrestricted` | HTTPS | +| `tokens *` with an RPC set | + Solana RPC (`getMultipleAccounts` for the bonding curves) | JSON-RPC | | `wallet balance` | Solana RPC (`getBalance`, `getTokenAccountsByOwner`) | JSON-RPC | | `wallet transfer` | Solana RPC (`sendTransaction`) | JSON-RPC | | `wallet drain` | Solana RPC (`getTokenAccountsByOwner`, `sendTransaction`) | JSON-RPC | | `wallet create/show/import/export` | None (local keystore only) | — | | `config *` | None (local config file only) | — | -The `tokens` listings use pump.fun's frontend API, which is unofficial and -changes without notice. They are narrowed to pump.fun coins on Solana; the API -no longer returns curve reserves, so price and bonding progress come from the -chain and need an RPC endpoint. +The `tokens` listings use pump.fun's frontend API, which is unofficial and changes without notice; it currently refuses non-browser clients ([#33](https://github.com/chainstacklabs/pumpfun-cli/issues/33)). Listings are narrowed to pump.fun coins on Solana, and price and bonding progress come from the chain, so they need an RPC endpoint. + +## Throughput and rate limits + +Every node provider has its own limits — method availability, requests per second, plan-specific caps. Consult your provider's docs, and don't expect public RPC nodes to hold up. For Chainstack, see the [throughput guidelines](https://docs.chainstack.com/docs/limits). + +LaunchLab coins priced in anything but SOL are found with `getProgramAccounts`, filtered by the coin's mint; providers that don't serve that method can't trade them. + +For faster execution, Chainstack offers [Solana Trader nodes](https://docs.chainstack.com/docs/solana-trader-nodes) for transaction propagation. ## Security - Private keys are encrypted at rest (AES-256-GCM + scrypt) - Password required for any key operation - Keys never appear in stdout, stderr, or logs -- `wallet export` requires explicit `--output` flag - -## Architecture - -Three-layer separation: - -- **commands/** — Thin Typer CLI wiring -- **core/** — Framework-free business logic -- **protocol/** — Pure Solana/pump.fun protocol code +- `wallet export` requires an explicit `--output` flag ## Testing -Unit tests run without any external dependencies: +Unit tests need nothing external: ```bash uv run pytest ``` -### Integration tests with Surfpool - -For testing transactions against real pump.fun program state, we use [Surfpool](https://www.surfpool.run/) — a local Solana fork that lazily loads accounts from mainnet. This is optional. +For transactions against real program state, the integration tests use [Surfpool](https://www.surfpool.run/), a local Solana fork that loads accounts from mainnet on demand. They are optional and skipped by default: ```bash -# Install surfpool -curl -sL https://run.surfpool.run/ | bash - -# Run integration tests (starts/stops surfpool automatically) -./scripts/surfpool-test.sh --mint +./scripts/surfpool-test.sh --mint # starts and stops surfpool +./scripts/surfpool-test.sh --mint --graduated # graduated coins too +./scripts/surfpool-test.sh --running --mint # surfpool already running +``` -# Optionally test graduated token handling too -./scripts/surfpool-test.sh --mint --graduated +## IDLs -# Or if surfpool is already running -./scripts/surfpool-test.sh --running --mint -``` +The pump.fun IDLs under [`idl/`](idl/) match those in [pumpfun-bonkfun-bot](https://github.com/chainstacklabs/pumpfun-bonkfun-bot), and `raydium_launchlab_idl.json` is copied from it; keep them in sync when the programs change. The IDLs under-report a few account lists (PumpSwap's swaps, pump.fun's `migrate_v2`); [CLAUDE.md](CLAUDE.md) lists what they leave out. -Surfpool forks mainnet state on demand — no need to manually clone programs or accounts. The tests validate info retrieval, buy, sell, and error handling against the actual pump.fun program. +## Architecture -## Contributing +``` +commands/ → core/ → protocol/ + (thin) (logic) (Solana) +``` -See [CONTRIBUTING.md](CONTRIBUTING.md) for setup, architecture, and how to submit changes. +- **`commands/`** — Typer CLI wiring: parses arguments, calls core, renders output +- **`core/`** — framework-free business logic +- **`protocol/`** — Solana primitives: PDAs, instructions, account layouts, curve math -## Agentic Coding +## Agentic coding This repo is configured for AI coding agents via the `.claude/` directory: -- **`CLAUDE.md`** — project context, commands, conventions, and boundaries +- **`CLAUDE.md`** — project context, commands, conventions and boundaries. `AGENTS.md` is a symlink to it, so Claude Code, Codex, Cursor and Copilot read the same guide. - **`hooks/`** — auto-lint on edit, guard against writing secrets, warn on transaction commands -- **`skills/`** — workflows for test automation - -### Skills - -The `.claude/skills/` directory contains [Agent Skills](https://agentskills.io/home) — an open standard for extending AI coding agents with reusable, modular capabilities. +- **`skills/`** — [Agent Skills](https://agentskills.io/home) for repeatable workflows: | Skill | Purpose | |-------|---------| @@ -253,8 +261,6 @@ The `.claude/skills/` directory contains [Agent Skills](https://agentskills.io/h | `run-mainnet-e2e-tests` | Run end-to-end tests against Solana mainnet (costs real SOL) | | `work-item` | Investigate, plan, implement (TDD), verify, and finalize work items as PRs | -**Cross-agent portability.** The Agent Skills format was [originated by Anthropic](https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills) and released as an open standard. It has since been adopted by [OpenAI Codex](https://developers.openai.com/codex/skills/), [GitHub Copilot](https://code.visualstudio.com/docs/copilot/customization/custom-instructions), [Cursor](https://cursor.com/docs/context/rules), and others. Any agent that can read a directory and parse Markdown can use them. - -### Instructions file +## Contributing -`CLAUDE.md` is read natively by [Claude Code](https://docs.anthropic.com/en/docs/claude-code) and by [GitHub Copilot in VS Code](https://code.visualstudio.com/docs/copilot/customization/custom-instructions#_use-a-claudemd-file). `AGENTS.md` is provided as a symlink to `CLAUDE.md` — an open format supported by Codex, Cursor, Copilot, and others. +Open an **Issue** for feedback or bugs. [CONTRIBUTING.md](CONTRIBUTING.md) covers setup, architecture and how to submit changes.