pumpfun-bonkfun-bot_github/docs/pumpfun-protocol.md

Pump.fun protocol notes

The IDLs under idl/ are vendored verbatim from github.com/pump-fun/pump-public-docs (idl/pump.json → pump_fun_idl.json, pump_amm.json → pump_swap_idl.json, pump_fees.json). Refresh them from upstream rather than hand-editing.

Quote assets and the v2 trade instructions (current path)

• pump.fun supports quote assets other than SOL, and no longer just SOL and USDC. BondingCurve.quote_mint is Pubkey::default() (all zeros) for SOL-paired coins; USDC (EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v) is one whitelisted entry in Global, but coins paired with Token-2022 quote mints are live on chain too. Legacy buy/sell cannot trade non-SOL-paired coins at all.
• Global.whitelisted_quote_mints is not the authoritative registry. A QuoteControl account carries its own mint list, which is how a coin pairs with a mint Global never lists. Error 6064 accepts SPL Token or Token-2022.
• The quote mint's token program is resolved from chain, not assumed. resolve_quote_token_program (src/core/pubkeys.py) reads a mint's owner once — pre-seeded with WSOL/USDC so those stay free — and caches it for the process; cached_quote_token_program is the hot-path read used by event parsing and address resolution. The bot warms the cache at startup for every configured quote mint, so extreme_fast_mode's zero-RPC contract still holds.
• The decimals come from the same read. Amounts like max_sol_cost and min_sol_output are in the quote mint's raw units, so assuming 9 decimals for a 6-decimal mint overstates the cap by 1000x and effectively disables slippage protection. getAccountInfo returns the owner and the mint data together, so decimals cost no extra call; they are cached alongside the token program and pre-seeded for WSOL (9) and USDC (6). A quote mint whose decimals cannot be resolved fails at startup rather than silently mis-scaling a trade. The decimals byte sits at offset 44 in both SPL Token and Token-2022 mints — extensions are appended after the base struct and never move it.
• The bot uses buy_v2 (27 accounts) and sell_v2 (26 accounts). Every account is mandatory and the order is identical for every coin — whatever quote mint, mayhem or not, cashback or not. sell_v2 is buy_v2 minus global_volume_accumulator. Layouts live in _BUY_V2_ACCOUNTS / _SELL_V2_ACCOUNTS in platforms/pumpfun/instruction_builder.py and are machine-checked against the IDL by tests/regression/verify_v2_account_layout.py.
• v2 args carry no track_volume OptionBool (24-byte data: discriminator + two u64). Volume tracking is unconditional now that user_volume_accumulator is mandatory. max_sol_cost/min_sol_output are in the quote mint's raw units — lamports for SOL, 1e-6 for USDC.
• Even for SOL-paired coins you must pass wrapped SOL as quote_mint, not Pubkey::default(). Transfers still happen in native SOL, and the associated_quote_* accounts are only seed-constrained — do not create the user's WSOL ATA, it would burn ~0.002 SOL of rent for nothing.
• Fee recipients: 24 total, in three sets of 8 (NORMAL_FEE_RECIPIENTS, RESERVED_FEE_RECIPIENTS for mayhem coins, BUYBACK_FEE_RECIPIENTS). Every v2 buy/sell needs a fee_recipient and a buyback_fee_recipient, randomized per tx to spread program throughput.
• sharing_config (PDA ["sharing-config", base_mint]) lives under the pump fees program, not the pump program. Easy to derive against the wrong program.

BondingCurve account layout

• create_v2 allocates 125 bytes. The 36 reserved padding bytes are gone and three fields follow quote_mint: creator_fee_bps (u64), can_edit_creator_fee (bool, reserved — always false) and is_holder_reward (bool). Every field the bot reads sits before where the padding used to start.

• extend_account can grow a curve past 125 bytes, and a length allowlist is whack-a-mole against that. Don't filter on account length — decode any length at or above 125 the same way:

  Length	What it is
  125 bytes	What create_v2 allocates
  151 bytes	The old allocation size; still reachable via extend_account
  256 bytes	A rarer extend_account target

  tests/regression/verify_curve_account_sizes.py checks that all three decode and that the graduating-token examples don't filter on length.

• The SOL-named fields were renamed: virtual_sol_reserves → virtual_quote_reserves, real_sol_reserves → real_quote_reserves. The curve manager exposes the old names as aliases, so callers keep working for SOL-paired coins — but anything doing arithmetic must scale by the quote mint's decimals (quote_units_per_token), not a hardcoded 1e9.

• PumpSwap Pool gained a trailing virtual_quote_reserves: i128 (16 bytes, offset 245). Pool fields end at 261; live accounts are 301 bytes with trailing padding. Quote against effective reserves: pool_quote_token_account.amount + virtual_quote_reserves. Upstream's release note claims it is 0 on all pools — that is out of date, and quoting off the raw vault balance under-prices any pool carrying some. It is i128, not u64; reading 8 bytes works only while the high half is zero.

• pump-amm has no buy_v2/sell_v2. The AMM instruction names are unchanged; only the pool layout and quoting moved.

• Pool.coin_creator tells you whether a pool is canonical, i.e. graduated from a pump.fun bonding curve. It is Pubkey::default() on every other pool. Two things follow:

  • pool-v2 is sent only for a canonical pool. The buyback fee recipient and its quote ATA are always the last two accounts and are read positionally, so adding pool-v2 on a non-canonical pool shifts them and the program rejects the pool-v2 PDA with BuybackFeeRecipientNotAuthorized (6053). Upstream's BREAKING_FEE_RECIPIENT.md says the pair goes after pool-v2 "for coins that graduate from bonding curve", and separately that the pair is needed either way — the qualifier is the whole rule. Account counts: buy 26/27 canonical, 25/26 not; sell 24/26 canonical, 23/25 not.
  • Do not assume 6 base-token decimals. Every graduated coin has 6, but non-canonical pools routinely carry 9, and a factor of 1000 scales the quote and the slippage floor together, so a sell reverts ExceededSlippage (6004) rather than just mispricing. Resolve the mint's owner and decimals from the same getAccountInfo, as get_mint_info does.

• The vendored pump_swap_idl.json under-reports these accounts and is byte-identical to upstream, so it cannot be the reference: it lists 23 for buy against 25-26 on chain, and 21 for sell against 23-26.

Coin creation

• create_v2 takes eight args: name (str), symbol (str), uri (str), creator (pubkey), is_mayhem_mode (bool), is_cashback_enabled (OptionBool), creator_fee_bps (OptionU64), is_holder_reward (OptionBool). OptionBool and OptionU64 are single-field Anchor structs with no presence tag — each serializes as its bare inner value, 1 byte and 8 bytes, never a discriminated Option.
• is_cashback_enabled = [true] is rejected with 6082 CashbackDeprecated: create_v2 can no longer mint a new cashback coin. Existing cashback coins keep trading, accruing and claiming, so every cashback code path in this repo (the legacy sell path's cashback branch, is_cashback_coin on TokenInfo) stays live and must not be treated as dead.
• The trailing args are positional, not independently optional. Reaching is_holder_reward (arg 8) means sending is_cashback_enabled (6) and creator_fee_bps (7) first, even when both are false/zero. The committed fixtures show three wire lengths: all trailing args omitted (0 bytes after is_mayhem_mode), is_cashback_enabled only (1 byte), and is_cashback_enabled + creator_fee_bps (9 bytes); the three-arg form is sent too. Because the args are positional, a shorter form cannot have set a later one — a truncated instruction is proof the coin is not holder-reward, not merely silence about it, which is what lets a pre-execution listener classify every coin. A decoder that reads a fixed number of trailing bytes raises IndexError on the shorter forms, so decode defensively and report a missing arg as unset; utils/idl_parser.py does, and tests/regression/verify_create_v2_optional_args.py checks it.
• create_v2 accounts 1-16 are in the IDL; accounts 17-19 are optional remaining accounts (quote_mint, associated_quote_bonding_curve, quote_token_program), all three or none. This is the only way to read a new coin's quote asset from the instruction rather than the event. They are appended for SOL-paired coins too, carrying wrapped SOL, so a 19-account create_v2 is not proof of a non-SOL quote asset. Read quote_mint off the curve instead.
• The associated bonding curve is an ordinary ATA, so its address depends on which token program owns the mint: Token2022 for create_v2 coins, SPL Token for legacy create. Deriving with the wrong program returns a valid-looking address that does not exist on chain.
• extreme_fast_mode skips the curve-state price fetch. Whether it also reads the curve for mayhem/cashback/creator/quote_mint depends on provenance (see the Invariants in CLAUDE.md): CreateEvent-sourced tokens (state_from_event) trade on the event data with zero RPC calls, while pumpportal/incomplete-event tokens refresh from chain — the wrong quote mint means spending the wrong balance entirely. Event parsers populate quote_mint from CreateEvent, which carries quote_mint and virtual_quote_reserves as trailing fields.

Holder reward coins

create_v2 can set is_holder_reward so the creator fee is set aside for holders instead of paid to a creator wallet. On such a coin BondingCurve.creator holds a pump.fun address rather than the actual creator's; the creator_vault derivation is unchanged and still correct, since it derives from whatever creator the curve carries.

That substituted address is PDA(["holder-rewards", mint]) under the pump program — the same account the IDL declares for holder_rewards on distribute_fee_to_holders, which is how the ordinary creator-vault route delivers the fee to the holder pool without a second payout path. It depends on nothing but the mint, so args.creator being unusable on these coins costs no RPC call to work around: PumpFunAddresses.find_holder_reward_creator derives it. No trade instruction changed: buy, sell, buy_v2, sell_v2 and the PumpSwap instructions take identical accounts and arguments either way. Global.is_holder_reward_enabled can switch creation off globally.

TokenInfo.is_holder_reward and TokenInfo.creator_fee_bps surface this to the bot — see the field comments on TokenInfo in src/interfaces/core.py. SOL- and USDC-paired coins keep creator_fee_bps at 0; custom-pair coins carry a nonzero value.

Legacy instructions (fallback only)

Retained behind PumpFunInstructionBuilder(..., use_legacy_instructions=True). The IDL under-reports these: buy is 18 accounts on-chain (IDL lists 16) and sell is 16 non-cashback / 17 cashback (IDL lists 14). The extras are bonding-curve-v2 (PDA ["bonding-curve-v2", mint]) followed by a mutable buyback fee recipient; the cashback sell path also inserts user_volume_accumulator before bonding-curve-v2. On the PumpSwap side the legacy path needs pool-v2 (PDA ["pool-v2", base_mint] under pump-amm) — without it pump-amm throws AnchorError 6023 (Overflow) after the transfers complete, a misleading code for a missing account. Prefer v2 — it is the interface pump.fun maintains.