75d9087d05
* feat(cookbook): cover every create_v2 coin parameter in the launch scripts Both create scripts now build create_v2 through pumpfun_instructions_v2 instead of each carrying their own copy of the discriminators, PDAs and account list. - A holder-reward coin's curve creator is derived rather than assumed, so the opening buy finds the matching creator vault instead of reverting. - create_v2's three trailing arguments are settable independently. None omits an argument, a value sends it, so all four wire forms are reachable and an explicit default is distinct from an omission. - create_v2 carries all four remaining accounts, quote_control included. Without them the program ignores creator_fee_bps. - --creator, --creator-fee-bps and --quote-mint added. A creator fee on a SOL-paired coin warns, because the program stores zero for it; the create-and-buy script refuses one outright before sending anything. - The opening buy is sized from Global's reserves and fee rates. - Mayhem mode is off by default. Removes the fee-recipient lookup whose result was discarded and the buy wrapper whose parameters were unused. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * test(regression): verify the launch path's create_v2 arguments Eight offline checks: the substituted creator on a holder-reward coin, every committed create_v2 fixture round-tripping through the trailing argument encoder, all four wire forms being reachable, --creator reaching the wire, the opening buy following Global rather than constants, the Global decoder stopping cleanly on a short buffer, and the four quote accounts being present with the ATA under the quote mint's own program. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * docs: correct create_v2's remaining accounts and the creator-fee rule create_v2 takes four remaining accounts, not three; the fourth is the QuoteControl PDA. Omitting them is accepted and yields a SOL-paired coin, which is also how a creator fee goes missing: the program applies creator_fee_bps only to a coin priced in something other than SOL, and otherwise stores zero without an error. Also records that solders documents TransactionConfig.priority_fee as micro-lamports while SIMD-0385 defines the field as total lamports. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * feat(cookbook): price a new coin in an asset other than SOL --quote-mint on both create scripts, checked against both registries that admit a quote asset. QuoteControl carries most of them with a per-mint opening reserve; Global.whitelisted_quote_mints carries USDC, which QuoteControl does not list, so consulting either alone refuses a mint the program accepts. A mint neither admits is refused rather than priced from a default, since the opening reserve spans orders of magnitude. The quote mint's token program and decimals are resolved from chain, and --amount is denominated in the quote asset rather than in SOL. A paused mint is refused before anything is sent, and a scaled-UI mint says so, because amounts here are raw units. A creator fee now works, since pump.fun applies one only to a coin priced in something other than SOL. On a SOL-paired coin it is refused instead of being accepted and stored as zero. The create-and-buy script requires the wallet to already hold the quote asset; it does not acquire one. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * feat(cookbook): launch a coin in one v1 transaction Create, extend, the buyer's token account and the buy now travel under a single signature, so nobody can buy between the create and the opening buy. They were split because the two together are 1479 bytes against the 1232 a v0 transaction is held to; SIMD-0296 raised the limit to 4096 for v1 and the combined message uses about a third of it. v1 has no address lookup tables -- the larger limit exists so the whole account list goes inline -- and it carries the compute budget in the message header, so the script sends no ComputeBudget instructions. The priority fee is now one total in lamports rather than micro-lamports per compute unit; the constant is converted, not renamed. The two-transaction path is removed rather than kept behind a flag. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * fix(cookbook): state the loaded-accounts data size limit on the v1 launch A v1 message carries this limit in its header, and left unset it is zero rather than the network default, so the runtime rejects the transaction for exceeding it. The launch skips preflight, so the rejection never reached the caller: send returned a signature that never landed. Measured against a forked mainnet, the launch is rejected at 128 KiB and lands at 256 KiB. The limit is set to 1 MiB, which leaves room for a quote mint whose accounts are larger, and the verifier fails if it is dropped or set at or below the measured failing size. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * feat(cookbook): offer the launch as a v0 or a v1 transaction The Solana transaction version changes what a launch can be, so it is the script that changes rather than a flag on one of them. _txv1 sends create and buy under a single signature, so the coin is bought by the transaction that creates it. _txv0 sends them as two transactions, because together they do not fit what a v0 transaction can carry, and anyone watching the create can buy in the gap. Use it when the endpoint will not take a v1 send. The coin is identical either way: quote asset, creator fee, holder rewards and mayhem mode all behave the same. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * refactor(cookbook): drop the instruction version from script names The cookbook ships one form of each pump.fun action, so `_v2` in a basename distinguished nothing — and it read as a Solana transaction version, which is a different thing and now appears in the same names. `pumpfun_buy_token_exact_sol_in.py` already went without it. Every trade script loses the suffix, the shared module becomes `pumpfun_instructions.py`, and the retired path is named for what it is rather than for the instruction set it uses. The instruction each script builds is named in its docstring, where it cannot be mistaken for a transaction version. `txv0`/`txv1` is now the only version marker in any filename, and it is the one the reader chooses between. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * fix(cookbook): refuse mayhem mode paired with a non-SOL quote asset The program rejects the pairing with MayhemModeQuoteMintNotAllowed (6071), so a mayhem coin is always SOL-paired — and therefore can never carry a creator fee, which needs a non-SOL quote. Both create scripts now refuse the combination before sending, rather than letting it land as a reverted transaction that has already cost fees. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * fix(cookbook): size the v1 loaded-accounts limit for what mainnet loads The limit counts the executable data of every program a transaction touches, not just the accounts it names, and the pump program's own code is the bulk of it. The previous figure was set against a local fork, which does not charge for executables; on mainnet the launch was rejected with MaxLoadedAccountsDataSizeExceeded. Set to the network default a v0 transaction gets when nothing narrows it, which is the behaviour being reproduced. The verifier now holds the mainnet figure as its floor. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * fix(cookbook): a creator fee needs a QuoteControl quote mint, not just a non-SOL one Measured on mainnet: the fee is applied on a coin priced in a mint QuoteControl admits, whether that mint is SPL Token or Token-2022, and is not applied on wrapped SOL or on USDC — which the older Global whitelist carries and QuoteControl does not. The deciding property is registry membership, so the previous check let a USDC-priced coin through and the program stored zero without an error. Also stops the sell script calling a price "SOL" when the curve is priced in something else. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * feat(cookbook): offer the create-only script as a v0 or a v1 transaction Same split as the create-and-buy pair, for the same reason: the Solana transaction version is the reader's choice, so it is the script that changes rather than a flag. _txv1 carries the compute budget in the message header and sends no ComputeBudget instructions; _txv0 sends them. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * fix(cookbook): refuse a paused quote mint on the create-and-buy path too The check only ran in the create-only scripts, so a launch that also buys could reach the chain with a quote mint whose transfers are paused. On the two-transaction path that leaves a created coin nobody bought, after the create has already cost rent. Also corrects the v1 script's run docstring, which still described two transactions and a spend denominated in SOL. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * fix(cookbook): say --amount is in whole quote units, not raw ones The scaled-UI notice told the reader the opposite of what the scripts do: --amount is multiplied by the mint's decimals, so it is a whole-token figure. A reader who followed the notice would have overspent by a factor of the decimals. Reworded so the multiplier is described as what it is — a display scale a wallet applies — rather than as something the amount has to account for. The create-only scripts carried the same wording without even taking an amount. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
Chainstack is the leading suite of services connecting developers with Web3 infrastructure
• Homepage •
Supported protocols •
Chainstack blog •
Blockchain API reference •
• Start for free •
A Solana trading bot for pump.fun and letsbonk.fun. It watches for token creation, buys, and exits on a strategy you configure. cookbook/ holds one standalone script per action, useful on their own even if you never run the bot.
For the full walkthrough, see Solana: Creating a trading and sniping pump.fun bot. It lags behind the code, so treat this README as the source of truth for setup and configuration.
Also by Chainstack — if you prefer a terminal interface or want to give an AI agent trading capabilities:
- pumpfun-cli — CLI for trading, launching, and managing tokens on pump.fun; buy, sell, wallet management, and smart routing between the bonding curve and PumpSwap AMM.
- pumpclaw — agent skill that equips AI assistants (OpenClaw, Claude Code, Cursor, Codex) with the ability to operate pumpfun-cli.
🚨 SCAM ALERT: The Issues section is regularly targeted by scam bots that try to redirect you to an external site and drain your funds. A GitHub Action tags the common patterns, which is not 100% accurate. Deleted comments in issues are scam bots after your private keys — genuine outside devs are welcome and appreciated.
⚠️ NOT FOR PRODUCTION: This code is for learning purposes only. We assume no responsibility for the code or its usage. Modify it for your needs and learn from it — the examples, issues, and PRs contain valuable insights.
Getting started
1. Prerequisites
Install uv, a fast Python package manager. The project needs Python 3.11+; uv uses an existing install if it's new enough, otherwise it fetches one for you.
2. Clone and install
git clone https://github.com/chainstacklabs/pumpfun-bonkfun-bot.git
cd pumpfun-bonkfun-bot
uv sync # create .venv and install dependencies
source .venv/bin/activate # Unix/macOS — Windows: .venv\Scripts\activate
uv pip install -e . # install the bot as an editable package
3. Set your credentials
cp .env.example .env
Fill in .env:
| Variable | Purpose |
|---|---|
SOLANA_NODE_RPC_ENDPOINT |
HTTPS RPC endpoint |
SOLANA_NODE_WSS_ENDPOINT |
WebSocket endpoint (for logs / blocks listeners) |
SOLANA_PRIVATE_KEY |
Base58 private key of the trading wallet |
GEYSER_ENDPOINT, GEYSER_API_TOKEN, GEYSER_AUTH_TYPE |
For the geyser and shreds listeners (same endpoint, different RPC) |
Public RPC nodes will not work for this workload — see throughput below.
4. Configure a bot
Each YAML file in bots/ is one bot instance. They ship with commented defaults; start from the one matching the listener you want:
| File | Listener | Ships with |
|---|---|---|
bot-sniper-1-geyser.yaml |
geyser — fastest, needs a Geyser endpoint |
pump_fun |
bot-sniper-2-logs.yaml |
logs — logsSubscribe, supported everywhere |
pump_fun |
bot-sniper-3-blocks.yaml |
blocks — blockSubscribe, not supported by every provider |
pump_fun |
bot-sniper-5-shreds.yaml |
shreds — pre-execution, ahead of geyser, cannot see router-created coins |
pump_fun |
Set platform: "pump_fun" or platform: "lets_bonk". pump.fun supports all four listeners; letsbonk.fun supports blocks and geyser but not logs or shreds. The bot validates the pairing at startup and refuses to run an invalid one.
Set enabled: false to keep a config around without running it. Every bot with enabled: true starts when you run the bot.
5. Run
pump_bot # as an installed package
uv run src/bot_runner.py # or directly
Logs land in logs/{bot_name}_{timestamp}.log.
Configuration reference
The YAML files are commented inline. The sections that matter most:
trade—buy_amount(in SOL), slippage,exit_strategy(time_based,tp_sl,manual), andextreme_fast_mode.priority_fees— fixed or dynamic. Dynamic costs an extra RPC call, which slows the buy.filters—listener_type,max_token_age, name/creator matching,marry_mode(buy only, never sell),yolo_mode(trade continuously).retries— attempts and the wait windows around creation, buy, and the next token.cleanup— when to close leftover token accounts:disabled,on_fail,after_sell,post_session.node.max_rps— cap requests per second to match your provider's plan.
Extreme fast mode
With extreme_fast_mode: true the bot buys a fixed token amount
(extreme_fast_token_amount) instead of reading the curve price first. You give
up knowing what you paid per token; you get the buy submitted sooner.
How much sooner depends on what the listener could decode. When it read the
coin's CreateEvent, the bot makes no RPC call at all between detecting the
token and submitting the buy. When it fell back to decoding the create
instruction, it does one account read first, because the instruction is missing
fields the buy needs.
Two knobs:
curve_refresh_budget(seconds, default 2.0) — how long that read may take before the bot gives up and skips the token. Raise it to buy more coins on a slow endpoint, lower it to skip faster.trust_create_event(defaulttrue) — setfalseto make every listener do the read, giving up the zero-RPC path.
Non-SOL quote assets
pump.fun supports quote assets other than SOL, USDC first. Amounts are in that mint's own whole units, so usdc: 1.0 is one USDC and is not comparable to buy_amount:
trade:
buy_amount: 0.0001 # SOL-paired coins
quote_amounts:
usdc: 1.0 # USDC-paired coins
filters:
allowed_quote_mints: ["sol", "usdc"] # omit to allow any configured quote
Keys accept the aliases sol / wsol / usdc or a raw base58 mint. A coin whose quote mint has no configured amount is skipped rather than bought with a wrongly-scaled amount, so a config that lists nothing here trades SOL-paired coins only. Buying a USDC-paired coin needs USDC in the wallet plus a little SOL for fees and ATA rent.
Cookbook
cookbook/ is one script per thing you might want to do. Each runs on
its own with uv run <path>, reads .env directly, and needs no bot config.
cookbook/README.md is the index; the shape is:
| Directory | What is in it |
|---|---|
cookbook/pumpfun/listen/ |
One script per detection method — logs, blocks, geyser, shreds — plus wallet watching |
cookbook/pumpfun/read/ |
Price, curve state, graduation progress, address derivation |
cookbook/pumpfun/trade/ |
Buy, sell, create, and the two sniping variants |
cookbook/pumpfun/graduation/ |
Coins approaching graduation, and migrations to PumpSwap |
cookbook/pumpfun/decode/ |
Account data and transactions, against committed fixtures |
cookbook/solana/ |
Chain-level basics: balances, transaction status, Anchor discriminators |
cookbook/pumpswap/ |
Pool discovery and manual buy/sell on the AMM |
cookbook/letsbonk/ |
Exact-in / exact-out buys and sells on letsbonk.fun |
cookbook/legacy/ |
Instructions pump.fun has moved on from |
The quickest way in:
uv run cookbook/solana/solana_read_balances.py # what you hold
uv run cookbook/pumpfun/read/pumpfun_read_price.py <CURVE> # what it costs
uv run cookbook/pumpfun/trade/pumpfun_buy_token.py <MINT> --dry-run
A filename tells you the chain, the action and the instruction version before you open it. Scripts that spend real funds say so on the first line of their docstring. The decode scripts run with no arguments, against the fixtures beside them.
Related docs: Listening to pump.fun migrations · Sniping with only logsSubscribe
Regression checks
tests/regression/ holds one offline script per fixed bug, each naming the bug in its
docstring. They move no funds. Run them after any change to src/, and after a
pump.fun program upgrade:
uv run tests/regression/run_all.py # the whole set
uv run tests/regression/verify_v2_account_layout.py # account layouts, PDAs, encoding
uv run tests/regression/verify_curve_account_sizes.py # 125/151/256-byte curves all decode
uv run tests/regression/verify_tx_status_checks.py # every path reads meta.err
Development tools
tools/ holds the scripts used to exercise the bot rather than teach it. They import
src/ and several of them spend real funds — read the module docstring first.
uv run tools/simulate_v2_trades.py <MINT> # mainnet simulation, no funds moved
uv run tools/simulate_bot_buy_path.py # the bot's buy path against a fresh coin, no funds moved
uv run tools/compare_listeners.py # race all five listeners against each other
uv run tools/compare_migration_listeners.py # race the two migration detection methods
uv run tools/cleanup_accounts.py [MINT] # close leftover token accounts — submits transactions
uv run tools/live_v2_round_trip.py --yes # real buy_v2 + sell_v2 — SPENDS REAL FUNDS
uv run tools/live_listener_matrix.py --yes # real round trip per listener — SPENDS REAL FUNDS
Throughput and rate limits
Every node provider has its own limits — method availability, requests per second, plan-specific caps. Consult your provider's docs before running the bot, and don't expect public RPC nodes to hold up. For Chainstack, see the throughput guidelines.
getProgramAccounts over the whole pump.fun program is no longer served by anyone: it owns more than 10 million accounts, so providers reject the request or time out whatever filters you pass. Use a filtered subscription instead — cookbook/pumpfun/graduation/pumpfun_watch_graduating_programsubscribe.py shows the pattern.
The bot rate-limits itself with a token bucket: node.max_rps (25 by default) smooths the request rate while allowing short bursts, and 429s are retried with exponential backoff.
For faster execution, Chainstack offers Solana Trader nodes for transaction propagation and the Yellowstone gRPC Geyser plugin for streaming updates.
IDLs
The IDLs under idl/ are vendored from pump-fun/pump-public-docs — currently upstream commit 8109141. To refresh, copy pump.json, pump_amm.json, and pump_fees.json into pump_fun_idl.json, pump_swap_idl.json, and pump_fees.json, and note the upstream commit in your commit message. Don't hand-edit them.
The buy_v2 / sell_v2 account lists are complete in the IDL. The legacy buy / sell lists are not — the IDL omits PDAs the on-chain program requires, so cross-check anything outside v2 against a recent successful on-chain transaction.
docs/pumpfun-protocol.md documents the protocol gotchas in detail — account layouts, quote-mint handling, fee recipients, and what the IDL gets wrong.
Contributing
Maintainers are listed in MAINTAINERS.md. Open an Issue for feedback or bugs.
Lint and format the files you changed (uv sync installs ruff for you):
uv run ruff check --fix path/to/changed.py
uv run ruff format path/to/changed.py
Running ruff check over the whole repo reports a large backlog of pre-existing
errors — that's a known baseline, so scope it to your own files.
Then test your change with a cookbook script rather than by running a bot with real funds.