Open-source platform for 3D AI agents. Turn text or a photo into a rigged, animated GLB avatar, give it an LLM brain, memory and a wallet, and embed it anywhere with one web component. Remote MCP server, x402 payments, Three.js, browser-native.
JavaScript 3d-generationai-agentsanimationavatardigital-humangenerative-aiglbgltfimage-to-3dllmmcpmcp-servermodel-context-protocolsolanatext-to-3dthreejsweb-componentswebglwebxrx402
docs(pumpfun-program): re-vendor the upstream program docs for the v3 trade release
nirholasa41424e4354f
diff --git a/docs/pumpfun-program/README.md b/docs/pumpfun-program/README.mdindex 7265ad338..6f5f528e4 100644--- a/docs/pumpfun-program/README.md+++ b/docs/pumpfun-program/README.md@@ -5,8 +5,8 @@ this repo so on-chain work (instruction builders, fee logic, swap routing) can bdiffed against the source of truth without a network round-trip.- **Source:** https://github.com/pump-fun/pump-public-docs-- **Commit:** `1b822158844a60ca577df6ca122211b595a1a578`-- **Vendored:** 2026-06-08+- **Commit:** `2293f9a66c654e9fe82dc5e8f4618538f24bb35f`+- **Vendored:** 2026-10-09 (docs; IDLs come from `npm run pump:refresh-idls`). Em and en dashes are rewritten to hyphens on copy, and links to files not vendored here (the `.ts` IDL types, the retired `bondingCurve.ts`) point at the upstream commit or the published SDK. Nothing else is changed.- **Maintainers (npm publishers of `@pump-fun/*`):** `oussama-baton`, `security-baton`This is a snapshot, not a dependency. Do not edit these files to "fix" anything —@@ -16,6 +16,13 @@ re-vendor from upstream to update. Nothing here is imported by application code.| Path | What it covers || --- | --- |+| `UPSTREAM-v3-trades-fee-sweeps-announcement.md` | **The pump-sdk 4.0 / pump-swap-sdk 2.1 release** (2026-10-09): 17-account `buy_v3` / `sell_v3` and PumpSwap `buy_v2` / `sell_v2`, `multi_hop_swap`, pump coins as quote mints, creator and protocol fees kept on the curve and pool until swept, and synthetic migration. |+| `docs/instructions/TRADE_V3.md`, `PUMP_SWAP_TRADE_V2.md`, `MULTI_HOP_SWAP.md` | The smaller trade instructions and the multi-hop swap. |+| `docs/instructions/SWEEP_FEES.md` | `sweep_creator_fee` / `sweep_protocol_fee` on both programs, and the `CreatorFeesNotSwept` errors a collect, distribution, CTO or fee-sharing change hits without them. |+| `docs/instructions/CREATE_WITH_PUMP_COIN_QUOTE.md` | `create_v2` paired with an existing pump coin. |+| `docs/SYNTHETIC_MIGRATION.md` | The completing v3 buy that continues into the pool's tokens, and the `PostCompleteBuyEvent` indexers must add to its `TradeEvent`. |+| `docs/VIRTUAL_QUOTE_RESERVES_FEE_ADJUSTMENT.md`, `NEGATIVE_VIRTUAL_QUOTE_RESERVES.md` | Why pool `virtual_quote_reserves` goes negative (kept fees are subtracted from it). |+| `docs/HOLDER_REWARDS_README.md` | Holder-reward coins. || `UPSTREAM-buy-sell-v2-announcement.md` | **The v2 trade-instruction announcement** — `buy_v2` / `sell_v2` / `buy_exact_quote_in_v2`, the move to a unified interface, and USDC-as-quote support. (Upstream's root README.) || `UPSTREAM-pumpswap-virtual-quote-reserves.md` | **PumpSwap virtual quote reserves** (2026-07-20) — quotes price on `quote_vault_balance + virtual_quote_reserves`. The double-count and silent-default traps, and every three.ws surface that had to change. || `idl/pump.json` | Bonding-curve program IDL (canonical account/arg shapes). |@@ -28,7 +35,32 @@ re-vendor from upstream to update. Nothing here is imported by application code.| `docs/FEE_PROGRAM_README.md`, `FEE_RECIPIENTS.md`, `PUMP_CASHBACK_README.md`, `PUMP_CREATOR_FEE_README.md` | Fee program, recipient address lists, cashback, creator fees. || `docs/BREAKING_FEE_RECIPIENT.md`, `CPI_README.md`, `FAQ.md` | Breaking changes, CPI integration, FAQ. |-## Headline change to be aware of+## Latest change: fees kept on the curve and pool (pump-sdk 4.0, 2026-10-09)++v3 bonding-curve trades and PumpSwap v2 trades no longer pay the creator fee+into the creator vault. It accrues on `BondingCurve.creator_fee` or+`Pool.creator_fees` until a permissionless `sweep_creator_fee` moves it. How+three.ws handles it:++- **Every claim sweeps first.** The creator-fee collect paths (connected+ wallet, agent wallet, the auto-claim cron, the coin treasury claimer, the+ in-browser skill, and the `pump-fun-skills/coin-fees` scripts) put sweeps in+ front of the collect, sized to fit one transaction. Distribution and+ fee-sharing changes sweep first too, since the programs refuse them with+ `CreatorFeesNotSwept` while a bucket is nonzero. Shared code:+ `src/solana/pump-creator-sweep.js`.+- **Balances count unswept fees.** The my-coins rewards, fee-info, the coin+ page's creator earnings and the earnings snapshot add the curve and pool+ buckets to the vault balance, so a fee that has not been swept yet still+ reads as unclaimed, not as claimed.+- **Trades fold synthetic migration.** The trade firehose, the MCP trade tools+ and the whale watcher add each `PostCompleteBuyEvent` to the `TradeEvent`+ before it (`src/pump/trade-events.js`). Graduation detection keys on+ `CompleteEvent`, which is still emitted, so it needed no change.+- **Our own trade builders stay on `buy_v2` / `sell_v2`.** Those keep paying the+ creator fee per trade and remain fully supported upstream.++## Earlier change: unified v2 trade instructionspump.fun is migrating to **unified v2 bonding-curve trade instructions**(`buy_v2`, `sell_v2`, `buy_exact_quote_in_v2`) so the same account interface worksdiff --git a/docs/pumpfun-program/UPSTREAM-v3-trades-fee-sweeps-announcement.md b/docs/pumpfun-program/UPSTREAM-v3-trades-fee-sweeps-announcement.mdnew file mode 100644index 000000000..0a0f383b3--- /dev/null+++ b/docs/pumpfun-program/UPSTREAM-v3-trades-fee-sweeps-announcement.md@@ -0,0 +1,18 @@+# New: Smaller Trades, Multi-Hop Swaps, Pump Coins as Quote Mints, Fees Kept on the Curve++- **Smaller trade instructions.** `buy_v3`, `sell_v3` and `buy_exact_quote_in_v3` on the bonding curve, and `buy_v2`, `sell_v2` and `buy_exact_quote_in_v2` on PumpSwap, do the same trades with 17 accounts, so more fits in one transaction. Same prices, same fees. All existing trade instructions keep working. [Bonding curve v3](docs/instructions/TRADE_V3.md) · [PumpSwap v2](docs/instructions/PUMP_SWAP_TRADE_V2.md)+- **Multi-hop swap.** One PumpSwap instruction, `multi_hop_swap`, trades through two or more pools and bonding curves in a row, for example SOL → coin A → coin B, with no token account for the middle coin. [Multi-hop swap](docs/instructions/MULTI_HOP_SWAP.md)+- **Any pump coin as a quote mint.** `create_v2` can pair a new coin with an existing pump coin. You pass the quote coin's bonding curve (and its pool, if it has migrated) as extra remaining accounts. [Creating a coin paired with a pump coin](docs/instructions/CREATE_WITH_PUMP_COIN_QUOTE.md)+- **Fees stay on the curve and pool.** The new trades keep the protocol fee and the creator fee on the bonding curve or in the pool instead of paying them out on every trade. Anyone can pay them out with the permissionless `sweep_protocol_fee` / `sweep_creator_fee` instructions. Creators, CTOs and fee sharing must sweep the creator fee first. [Fee sweeps](docs/instructions/SWEEP_FEES.md)+- **Why `virtual_quote_reserves` goes negative.** Fees kept in a pool are subtracted from `virtual_quote_reserves`, so the price does not count them. If you already handle it as a signed value, this is not a breaking change for your quotes, and all existing trade instructions work the same way. [Virtual quote reserves and fees](docs/VIRTUAL_QUOTE_RESERVES_FEE_ADJUSTMENT.md)+- **Synthetic migration: the last buy on the curve has no max size.** With the v3 buys, the buy that empties the bonding curve can ask for more than what is left. It buys the rest from the tokens that would have gone into the PumpSwap pool, at that pool's price, and the pool later opens where that buy stopped. Only the buy that crosses the limit gets this; after it, no buys or sells are possible on the curve until the migration happens. [Synthetic migration](docs/SYNTHETIC_MIGRATION.md)++The IDLs and TypeScript types in [idl](idl) are updated with all of the above. SDK support: `@pump-fun/pump-sdk` 4.0.0, `@pump-fun/pump-swap-sdk` 2.1.0 and `pump-rust-client` 0.4.0, see [SDKs](#sdks).++## SDKs++These releases include builders for everything in the new section at the top: v3 trades, PumpSwap v2 trades, multi-hop swaps, pump coins as quote mints and fee sweeps.++- `@pump-fun/pump-sdk` 4.0.0 (Pump program): https://www.npmjs.com/package/@pump-fun/pump-sdk/v/4.0.0+- `@pump-fun/pump-swap-sdk` 2.1.0 (PumpSwap): https://www.npmjs.com/package/@pump-fun/pump-swap-sdk/v/2.1.0+- `pump-rust-client` 0.4.0 (both programs): https://crates.io/crates/pump-rust-client/0.4.0diff --git a/docs/pumpfun-program/docs/FAQ.md b/docs/pumpfun-program/docs/FAQ.mdindex 13b55bee4..0f4cbc762 100644--- a/docs/pumpfun-program/docs/FAQ.md+++ b/docs/pumpfun-program/docs/FAQ.md@@ -11,17 +11,33 @@ Each buy / sell instruction used CUs depend on all the inputs of the instructionmore CUs to log than smaller values.- for sell inputs, it's similar.-The `bonding_curve` (and the other) PDA bump seed is derived from the mint pubkey, so it differs for every mint:+As an example, for the+tx https://solscan.io/tx/5frph8gBFyX7ayBmqntvwpTPwzZ8aF4kdfJAvC52Li2iDnnaRwtmcZP839Cm4YQUFx7GzsUUStCfAy3hAG69ir4u:```Rust- // `mint` is the SPL mint of the token being traded.- let bump = Pubkey::find_program_address(&[b"bonding-curve", mint.as_ref()], &pump::ID).1;+ let mint = Pubkey::from_str("Coyj3LtKn1BNSgWc9HsGK5SKoGfEoDaymig4wrN6pump").unwrap();++assert_eq!(+ Pubkey::find_program_address(&[b"bonding-curve", mint.as_ref()], &pump::ID).1,+ 255+);+```++The `bonding_curve` bump seed for mint `Coyj3LtKn1BNSgWc9HsGK5SKoGfEoDaymig4wrN6pump` is `255`.++While for the+tx https://solscan.io/tx/5xozUcJFvRj4ySpE2epSSs95ySxs6cLjs1rV2uaFNkFgsEMBZW53VUa2uc3CVQLVJRYxfQ5JoSzZLiUvAgM4GEJM:++```Rust+ let mint = Pubkey::from_str("3cLSxG6eXcCD9NSMawkhUcrvVCUC8KHKHMCxx6bhpump").unwrap();++assert_eq!(+ Pubkey::find_program_address(&[b"bonding-curve", mint.as_ref()], &pump::ID).1,+ 251+);```-Different mints yield different bump seeds (commonly `255`, but `254`, `253`, … occur),-and the number of search iterations `find_program_address` performs to land on a valid-bump is itself part of the instruction's CU cost — so two trades of identical size can-consume different CUs solely because their mint/user/creator PDAs derive at different bumps.+The `bonding_curve` bump seed for mint `3cLSxG6eXcCD9NSMawkhUcrvVCUC8KHKHMCxx6bhpump` is `251`.So it is not possible to compute the used CUs without first simulating the buy / sell tx before submission and adding abuffer of 1% to the simulated CUs, because buy instruction executes a bit more code when the bonding curve completes ondiff --git a/docs/pumpfun-program/docs/FEE_PROGRAM_README.md b/docs/pumpfun-program/docs/FEE_PROGRAM_README.mdindex 408debcc5..20b48370e 100644--- a/docs/pumpfun-program/docs/FEE_PROGRAM_README.md+++ b/docs/pumpfun-program/docs/FEE_PROGRAM_README.md@@ -200,7 +200,8 @@ export function calculateFeeTier({}```-We will use the following fee tiers starting from Monday (see the fee tiers chart, `fees.png`, in the upstream repository — not vendored here):+We will use the following fee tiers starting from Monday:+In order to avoid possible issues created by the new fee structure, until you make sure it's implemented correctly, you can increase the slippage tolerance on buy / sell instructions as a temporary mitigation.diff --git a/docs/pumpfun-program/docs/HOLDER_REWARDS_README.md b/docs/pumpfun-program/docs/HOLDER_REWARDS_README.mdnew file mode 100644index 000000000..594228fe1--- /dev/null+++ b/docs/pumpfun-program/docs/HOLDER_REWARDS_README.md@@ -0,0 +1,133 @@+# Holder Rewards Coins++Coins can now be created as **holder rewards coins**. On a holder rewards coin the creator fee that is charged on every+trade is not paid to a creator wallet. It is set aside for the people who hold the coin, and pump.fun distributes it to+them on an ongoing basis.++This is a backwards compatible change. Integrations that do not update keep working; they will simply create regular+coins and will not see the new fields described below.++## What changes for creators++- A coin is either a regular coin or a holder rewards coin. The choice is made when the coin is created. A regular+ coin can later be converted into a holder rewards coin through a community takeover (see+ [below](#community-takeovers-and-creator-fee-changes)), but a holder rewards coin can never go back to being a+ regular coin.+- On a holder rewards coin there is nothing for the creator to claim: the creator fee goes to holders.+- Holders do not need to do anything to receive rewards. pump.fun pays them out; there is no claim instruction for+ holders to call.+- Creating holder rewards coins can be switched off globally by pump.fun. While it is off, `create_v2` rejects a request+ for a holder rewards coin.++## Creating a holder rewards coin++`create_v2` takes one new trailing argument:++| # | Argument | Type | Description | Optional? |+| --- | ------------------ | ------------ | -------------------------------------------------------------------------------------------------------------------------------- | --------- |+| 8 | `is_holder_reward` | `OptionBool` | `[true]` creates a holder rewards coin. Omitted or `[false]` creates a regular coin. In TypeScript this is a tuple: `[true]`. | Yes |++Notes:++- The argument is trailing and optional: instruction data built before it existed still decodes and creates a regular+ coin.+- On a holder rewards coin the `creator` argument is not used as the fee recipient. Pass your usual creator address; the+ program records a pump.fun controlled address as the coin's creator instead. The `BondingCurve::creator` field+ therefore still tells you where the fee goes, and the `creator_vault` derivation used by `buy` / `sell` is unchanged.+- `is_cashback_enabled` (argument 6) must be `[false]` or omitted, see [Cashback is deprecated](#cashback-is-deprecated).++### TS SDK++```ts+import { PUMP_SDK } from "@pump-fun/pump-sdk";++const createInstruction = await PUMP_SDK.createV2Instruction({+ mint: mintKeypair.publicKey,+ name: "Name",+ symbol: "symbol",+ uri: "<your ipfs uri>",+ creator,+ user,+ mayhemMode: false,+ holderReward: true, // holder rewards coin+});+```++To create and buy in one transaction, pass `holderReward: true` to `createV2AndBuyV2Instructions` (or+`createV2AndBuyInstructions`). The SDK then points the first buy at the right creator vault for you. The SDK throws+`HolderRewardDisabledError` up front when holder rewards coins are currently switched off.++```ts+const global = await onlineSdk.fetchGlobal();++const instructions = await PUMP_SDK.createV2AndBuyV2Instructions({+ global,+ mint: mintKeypair.publicKey,+ name: "Name",+ symbol: "symbol",+ uri: "<your ipfs uri>",+ creator,+ user,+ quoteAmount,+ amount,+ mayhemMode: false,+ holderReward: true,+});+```++## Trading holder rewards coins++There are **no changes to any trade instruction**. `buy`, `sell`, `buy_v2`, `sell_v2`, `buy_exact_quote_in_v2` and the+PumpSwap `buy` / `sell` instructions take the same accounts and the same arguments for holder rewards coins as for any+other coin. Fees are computed exactly as before; the only difference is who ends up receiving the creator fee.++## Reading holder rewards data++### Accounts++| Account | New field | Type | Meaning |+| --------------------------- | ------------------ | ------ | ---------------------------------------------------------------- |+| `BondingCurve` (Pump) | `is_holder_reward` | `bool` | `true` on a holder rewards coin. Appended after the existing fields. |+| `Pool` (PumpSwap, canonical) | `is_holder_reward` | `bool` | Carried over from the bonding curve when the coin graduates. |++Accounts written before the field existed are one byte shorter and should be read as `false`. The TS SDKs' decoders+(`PumpSdk.decodeBondingCurve`, `PumpAmmSdk.decodePool`) handle both lengths.++### Events++| Event | New fields | Meaning |+| ---------------------------------------- | ------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------- |+| `CreateEvent` (Pump) | `is_holder_reward: bool` | Whether the coin was created as a holder rewards coin. |+| `CreatePoolEvent` (PumpSwap) | `is_holder_reward: bool` | Same flag on the pool created at graduation. |+| `TradeEvent` (Pump) | `holder_rewards_bps: u64`, `holder_rewards: u64` | The creator fee rate and amount of this trade when the coin is a holder rewards coin; `0` otherwise. |+| `BuyEvent` / `SellEvent` (PumpSwap) | `holder_rewards_bps: u64`, `holder_rewards: u64` | Same, for PumpSwap trades. |++The existing `creator_fee` / `creator_fee_basis_points` (Pump) and `coin_creator_fee` / `coin_creator_fee_basis_points`+(PumpSwap) fields are unchanged and keep reporting the fee on holder rewards coins too, so existing indexers need no+change. Logs emitted before the new fields existed are shorter; read the missing fields as `0` / `false`.++## Cashback is deprecated++Cashback mode is deprecated. `create_v2` now rejects `is_cashback_enabled = [true]`, so **no new cashback coins can be+created**. Pass `[false]` or omit the argument.++Existing cashback coins are not affected:++- trading them works exactly as before, and their creator fee is still routed to the buyer as cashback;+- cashback that has already accrued stays claimable with `claim_cashback` / `claim_cashback_v2`, see+ [CLAIM_CASHBACK.md](instructions/CLAIM_CASHBACK.md).++## Community takeovers and creator fee changes++Contact the CTO team if you want to:++- change the creator fee bps of a coin on a **custom pair** (a coin paired with a quote asset other than SOL or USDC;+ SOL- and USDC-paired coins always use the standard fee schedule), or+- **convert an existing coin into a holder rewards coin**. Once converted, the coin stays a holder rewards coin.++## SDKs++- TS SDK: https://www.npmjs.com/package/@pump-fun/pump-sdk+- PumpSwap SDK: https://www.npmjs.com/package/@pump-fun/pump-swap-sdk++The IDLs in the [idl](../idl) directory are updated with the new argument, fields and events.diff --git a/docs/pumpfun-program/docs/NEGATIVE_VIRTUAL_QUOTE_RESERVES.md b/docs/pumpfun-program/docs/NEGATIVE_VIRTUAL_QUOTE_RESERVES.mdnew file mode 100644index 000000000..96fa56d17--- /dev/null+++ b/docs/pumpfun-program/docs/NEGATIVE_VIRTUAL_QUOTE_RESERVES.md@@ -0,0 +1,67 @@+# Negative Virtual Quote Reserves++Starting **September 30**, `Pool::virtual_quote_reserves` on PumpSwap pools can be **negative**.++Why it goes negative: the PumpSwap v2 trades keep the protocol and creator fee inside the pool's quote vault and subtract that amount from `virtual_quote_reserves`, so the waiting fees do not count as liquidity. See [Virtual quote reserves and fees](VIRTUAL_QUOTE_RESERVES_FEE_ADJUSTMENT.md). If you already handle a negative value, nothing changes for your quotes.++The field is an `i128`, so treat it as a signed value everywhere and never read it as a `u64` / `u128`. A positive value+puts `effective_quote_reserves` above `pool_quote_token_account.amount`; a negative value puts it below. In both cases+`effective_quote_reserves` itself is **never negative**: the program never lets `virtual_quote_reserves` drop further+below zero than the vault balance can cover.++## Pricing++The pricing formula is unchanged (see+[Quoting: effective quote reserves](PUMP_SWAP_README.md#quoting-effective-quote-reserves)). A negative value simply+lowers the effective quote reserves below the raw vault balance:++```text+effective_quote_reserves = pool_quote_token_account.amount + Pool::virtual_quote_reserves+```++Both `buy` and `sell` are priced against `effective_quote_reserves`. The base side is unchanged: base reserves are still+the raw `pool_base_token_account.amount`.++## Overflow guarantee++We guarantee that `pool_quote_token_account.amount + virtual_quote_reserves` will never overflow and will never be+negative. The program keeps the vault balance and `virtual_quote_reserves` in a range where the effective quote reserves+always fit in a `u64`, so integrations do not need to guard the computation themselves.++## Handling in integrations++```ts+// virtual_quote_reserves is a signed i128 and may be negative.+const realQuote = BigInt(poolQuoteTokenAccount.amount);+const virtualQuote = BigInt(pool.virtual_quote_reserves); // keep the sign++// Price both buys and sells against the effective reserves.+const effectiveQuoteReserves = realQuote + virtualQuote;++const quoteIn = buyQuote(baseReserves, effectiveQuoteReserves, baseOut);+const quoteOut = sellQuote(baseReserves, effectiveQuoteReserves, baseIn);+```++In Rust, do the addition in `i128` and then cast the result to `u64` for the quote math. The program guarantees the+result is non-negative and fits in a `u64`, so no checked conversion is needed.++```rust+fn effective_quote_reserves(+ pool_quote_token_account_amount: u64,+ virtual_quote_reserves: i128, // signed, may be negative+) -> u64 {+ // The program guarantees this addition never overflows and the result fits in u64.+ (i128::from(pool_quote_token_account_amount) + virtual_quote_reserves) as u64+}++let effective_quote_reserves =+ effective_quote_reserves(pool_quote_token_account.amount, pool.virtual_quote_reserves);++let quote_in = buy_quote(base_reserves, effective_quote_reserves, base_out);+let quote_out = sell_quote(base_reserves, effective_quote_reserves, base_in);+```++- Decode `virtual_quote_reserves` from the `Pool` account and from `BuyEvent` / `SellEvent` as a signed integer.+- Store it in a signed column in your indexer schema; a `u64` column will reject or corrupt negative values.+- Pools written before the field existed are shorter than the current layout; read a missing `virtual_quote_reserves`+ as `0`.diff --git a/docs/pumpfun-program/docs/PUMP_CASHBACK_README.md b/docs/pumpfun-program/docs/PUMP_CASHBACK_README.mdindex 507168be9..2ca829357 100644--- a/docs/pumpfun-program/docs/PUMP_CASHBACK_README.md+++ b/docs/pumpfun-program/docs/PUMP_CASHBACK_README.md@@ -1,3 +1,9 @@+> **Deprecated.** Cashback mode is deprecated: `create_v2` now rejects `is_cashback_enabled = [true]`, so no new+> cashback coins can be created. Existing cashback coins are not affected: they trade exactly as described below, their+> creator fee is still routed to the buyer, and accrued cashback stays claimable with `claim_cashback` /+> `claim_cashback_v2`. New coins that want to reward their community should be created as+> [holder rewards coins](HOLDER_REWARDS_README.md) instead.+## OverviewCashback Rewards allows token creators to create coins with "cashback" enabled which redirects the creator fee to the users. Each user would get the creator fee on their swap volume as cashback rather than paying that fee to the coin creator.@@ -33,8 +39,8 @@ Expects the WSOL associated token account of the `UserVolumeAccumulator` for theExpects the `UserVolumeAccumulator` for the Pump AMM Program (used to derive the WSOL ATA above) at the 1st index of the remaining accounts.### Create V2-New parameter expected for `create_v2` instruction which is an `OptionBool` to define whether the coin has cashback enabled or not.-In typescript this is a tuple, so it would look like `[true]`.+The `create_v2` instruction has an `OptionBool` parameter, `is_cashback_enabled`, that used to enable cashback for a new coin.+It is deprecated: pass `[false]` or omit it. `create_v2` fails when it is `[true]`.### Bonding Curve Claim CashbackNew `claim_cashback` instruction for the Pump program.diff --git a/docs/pumpfun-program/docs/PUMP_CREATOR_FEE_README.md b/docs/pumpfun-program/docs/PUMP_CREATOR_FEE_README.mdindex e393ce68d..407bf9c78 100644--- a/docs/pumpfun-program/docs/PUMP_CREATOR_FEE_README.md+++ b/docs/pumpfun-program/docs/PUMP_CREATOR_FEE_README.md@@ -98,7 +98,7 @@ same code should work on both the creator fee update on Devnet and the current Mprogram on Mainnet to the creator fee update.We are also trying to release the Pump program Typescript SDK by Monday, so you can use it. The-`bondingCurve.ts` file is part of the upcoming Pump program Typescript SDK.+[bondingCurve.ts](https://www.npmjs.com/package/@pump-fun/pump-sdk?activeTab=code) file is part of the upcoming Pump program Typescript SDK.## Coin creator fees update@@ -116,7 +116,7 @@ Who will not receive coin creator fees?- coins already migrated to Raydium, as that program is not under our control.- normal PumpSwap pools which are not created by Pump program `migrate` instruction.-You should start by using the latest IDL files for both programs from the `idl` directory. They are+You should start by using the latest IDL files for both programs from the [idl](../idl) directory. They arebackwards-compatible with current programs deployed on Mainnet, so you can start using them now.You can also use our Typescript SDKs for easier integration:diff --git a/docs/pumpfun-program/docs/PUMP_PROGRAM_README.md b/docs/pumpfun-program/docs/PUMP_PROGRAM_README.mdindex 27f4eb82a..cdd6e6744 100644--- a/docs/pumpfun-program/docs/PUMP_PROGRAM_README.md+++ b/docs/pumpfun-program/docs/PUMP_PROGRAM_README.md@@ -156,6 +156,23 @@ at https://solscan.io/account/EsmVk4MTsoT71JFaRM5DWFZboKpMQjfY6EYzAgUuksXw#accou- The `complete` field is initially set to `false`. It is set to `true` at the end of a `buy` instruction, when`real_token_reserves == 0`, so there are no more real tokens left in the bonding curve.+Fields appended to `BondingCurve` by later upgrades (accounts written before a field existed are shorter; read the+missing trailing fields as `0` / `false` / `Pubkey::default()`):++- `creator` (`pubkey`): the address the coin's creator fees accrue to, see+ [PUMP_CREATOR_FEE_README.md](PUMP_CREATOR_FEE_README.md).+- `is_mayhem_mode` (`bool`): whether the coin is a mayhem coin.+- `is_cashback_coin` (`bool`): whether the coin routes its creator fee to buyers as cashback. Cashback mode is+ deprecated and no new cashback coins can be created, see [PUMP_CASHBACK_README.md](PUMP_CASHBACK_README.md).+- `quote_mint` (`pubkey`): the coin's quote asset; `Pubkey::default()` for SOL-paired coins.+- `creator_fee_bps` (`u64`): the coin's own creator fee rate for coins on a custom pair (a quote asset other than SOL or+ USDC). `0` means the standard fee schedule applies, which is always the case for SOL- and USDC-paired coins. Contact+ the CTO team to change it.+- `can_edit_creator_fee` (`bool`): reserved, always `false`.+- `is_holder_reward` (`bool`): whether the coin is a [holder rewards coin](HOLDER_REWARDS_README.md) whose creator fee+ is set aside for its holders instead of a creator wallet. Trading is unchanged; `TradeEvent` additionally reports the+ fee in `holder_rewards_bps` / `holder_rewards` on such coins.+## Instructions- `create(user, name, symbol, uri, creator)` allows a `user` to create a new coin with the given `name`, `symbol` anddiff --git a/docs/pumpfun-program/docs/PUMP_SWAP_README.md b/docs/pumpfun-program/docs/PUMP_SWAP_README.mdindex 44f5fc7c5..c2837ee4d 100644--- a/docs/pumpfun-program/docs/PUMP_SWAP_README.md+++ b/docs/pumpfun-program/docs/PUMP_SWAP_README.md@@ -82,7 +82,7 @@ at https://solscan.io/account/GseMAnNDvntR5uFePZ51yZBXzNSn7GdFPkfHwfr6d77J#accou},"base_mint": {"type": "pubkey",- "data": "EXAMPLEpumpfunBaseMint1111111111111111pump"+ "data": "7LSsEoJGhLeZzGvDofTdNg7M3JttxQqGWNLo6vWMpump"},"quote_mint": {"type": "pubkey",@@ -102,7 +102,23 @@ at https://solscan.io/account/GseMAnNDvntR5uFePZ51yZBXzNSn7GdFPkfHwfr6d77J#accou},"lp_supply": {"type": "u64",- "data": "4193388284800"+ "data": "4194352106721"+ },+ "coin_creator": {+ "type": "pubkey",+ "data": "5L5k7gtNLbeXdzpvNrFshg1E1id1ceUDfc6vPUTxp98q"+ },+ "is_mayhem_mode": {+ "type": "bool",+ "data": false+ },+ "is_cashback_coin": {+ "type": "bool",+ "data": false+ },+ "virtual_quote_reserves": {+ "type": "i128",+ "data": "0"}}```@@ -123,6 +139,45 @@ at https://solscan.io/account/GseMAnNDvntR5uFePZ51yZBXzNSn7GdFPkfHwfr6d77J#accouinto the pool, then they burn their `lp_mint` tokens, the `Pool::lp_supply` will still reflect the original supplyof the `lp_mint`. This way, the pool differentiates between `lp_mint` tokens burnt by users directly and those burntby the `withdraw` instruction.+- The `coin_creator` is the pubkey that accrues the coin-creator fees for this pool (see+ [PUMP_SWAP_CREATOR_FEE_README](PUMP_SWAP_CREATOR_FEE_README.md)). On pools that predate coin-creator fees it is+ `Pubkey::default()` (`11111111111111111111111111111111`).+- The `is_mayhem_mode` flag indicates whether the pool operates in mayhem mode.+- The `is_cashback_coin` flag indicates whether the coin's creator fee is routed as cashback (see+ [PUMP_CASHBACK_README](PUMP_CASHBACK_README.md)).+- The `virtual_quote_reserves` (`i128`) is an additional (appended) quote-reserve amount that a pool may carry. Quotes must be+ computed against the pool's **effective quote reserves**, not the raw quote-vault token balance, see+ [Quoting: effective quote reserves](#quoting-effective-quote-reserves). It is `0` on all pools today, so effective+ quote reserves currently equal the raw vault balance; some pools may carry a non-zero value in the future.+- The `creator_fee_bps` (`u64`, appended) is the pool's own creator fee rate for coins on a custom pair (a quote asset+ other than SOL or USDC), carried over from the bonding curve. `0` means the standard fee schedule applies, which is+ always the case for SOL- and USDC-paired coins. Contact the CTO team to change it.+- The `can_edit_creator_fee` (`bool`, appended) is reserved and always `false`.+- The `is_holder_reward` (`bool`, appended) flag indicates whether the coin is a+ [holder rewards coin](HOLDER_REWARDS_README.md): its creator fee is set aside for the coin's holders instead of a+ creator wallet. Trading is unchanged; `BuyEvent` / `SellEvent` additionally report the fee in+ `holder_rewards_bps` / `holder_rewards` on such pools.+- Pools written before an appended field existed are shorter than the current layout; read the missing trailing fields+ as `0` / `false`.++## Quoting: effective quote reserves++Buys and sells are priced on the pool's **effective quote reserves**, which are the raw quote-vault token balance plus+`Pool::virtual_quote_reserves`:++```text+effective_quote_reserves = pool_quote_token_account.amount + Pool::virtual_quote_reserves+```++- Use `effective_quote_reserves` (not the raw `pool_quote_token_account.amount`) wherever you quote, price, or index a+ pool, for both `buy` and `sell`.+- `virtual_quote_reserves` is `0` on all pools today, so effective quote reserves equal the raw vault balance and quotes+ are unchanged. Integrating against effective quote reserves now is safe and keeps your quotes correct if a pool later+ carries a non-zero `virtual_quote_reserves`.+- The base side is unchanged: base reserves are still the raw `pool_base_token_account.amount`.++Indexers: the `BuyEvent` and `SellEvent` logs include `virtual_quote_reserves` (appended field), so effective quote+reserves can be reconstructed directly from the event stream.## Instructionsdiff --git a/docs/pumpfun-program/docs/SYNTHETIC_MIGRATION.md b/docs/pumpfun-program/docs/SYNTHETIC_MIGRATION.mdnew file mode 100644index 000000000..6d23df620--- /dev/null+++ b/docs/pumpfun-program/docs/SYNTHETIC_MIGRATION.md@@ -0,0 +1,52 @@+# Synthetic Migration: The Last Buy on the Bonding Curve Has No Max Size++Before, a buy could never take more than what the bonding curve had left. If you wanted more, you bought what was left, waited for the migration, and bought the rest on PumpSwap.++Now, with the v3 buys ([`buy_v3` and `buy_exact_quote_in_v3`](instructions/TRADE_V3.md)) and with a bonding curve hop of [`multi_hop_swap`](instructions/MULTI_HOP_SWAP.md), **the buy that empties the curve has no max size**. It takes what is left on the curve at the curve's price, completes the curve, and then buys the rest **from the tokens that would have gone into the PumpSwap pool**, at the price that pool would charge. We call this a synthetic migration: the buy trades against the pool before the pool exists.++## How it works++1. **Curve part.** The buy takes everything the curve has left, at the normal bonding curve price. The curve is now complete.+2. **Pool part.** The program works out the reserves the migration would deposit right after step 1: all the base tokens still in the curve's token account, and all the quote raised (minus the migration fee for SOL-paired coins). It then prices the rest of the buy on those reserves with the same constant-product formula PumpSwap uses. So the price is continuous: a token costs the same in this buy as it would right after the migration.+3. **Migration.** `migrate_v2` creates the pool with exactly the reserves the buy left behind. The pool opens at the price where the buy stopped.++Both parts pay the bonding curve fee schedule, not the pool's fees. The protocol and creator fee stay on the curve, as on every v3 trade (see [Fee sweeps](instructions/SWEEP_FEES.md)), and the buyback part is paid in the trade. So the total you pay differs from a real PumpSwap buy only by the fee rule.++## Rules++- **Only the buy that crosses the limit gets this.** After it the curve is complete, and every trade on it, buy or sell, v2 or v3, fails with `BondingCurveComplete` until the migration happens.+- **Only v3 buys and multi-hop curve hops.** `buy`, `buy_v2` and `buy_exact_quote_in_v2` are unchanged: a buy past what is left fails with `NotEnoughTokensToBuy`, or stops at what is left with `partial_fill`.+- **`buy_v3`**: `amount` may be bigger than what the curve has left. `max_sol_cost` must cover both parts. The pool part can never take all of the pool's tokens (constant product), so a very large `amount` fails with `NotEnoughTokensToBuy`.+- **`buy_exact_quote_in_v3`**: the whole budget is spent. What is left of `spendable_quote_in` after the curve part is spent in the pool part. `min_tokens_out` applies to the total tokens bought. If the leftover budget cannot buy even one token from the pool, the buy stops at the completed curve and the leftover stays with the user.+- **`multi_hop_swap` curve hop**: same as `buy_exact_quote_in_v3`, except the hop spends the whole rest of its input in the pool part. Mayhem-mode curves cannot be a hop at all, so a route never needs a partial fill.+- **Mayhem coins (and the mayhem agent) do not get a synthetic migration.** They keep the old behaviour: a too-big buy fails with `NotEnoughTokensToBuy`, or buys what is left and completes the curve when `partial_fill` is `[true]`.++## Quoting it off-chain++```text+remaining = bonding_curve.real_token_reserves+curve_quote = the usual bonding curve cost for `remaining` tokens++pool_base = associated_base_bonding_curve.amount - remaining+pool_quote = bonding_curve.real_quote_reserves + curve_quote - Global.pool_migration_fee (SOL-paired coin)+ = bonding_curve.real_quote_reserves + curve_quote (token-paired coin)++buy_v3, extra tokens `out`: quote_in = ceil(pool_quote * out / (pool_base - out))+buy_exact_quote_in_v3, net budget `in`: out = floor((in - 1) * pool_base / (pool_quote + in - 1))+```++The bonding curve fee schedule applies to each part separately. The pool part is the same math as a PumpSwap buy on a fresh pool with those reserves.++The SDKs quote it for you: `getBuyV3QuoteAmountFromTokenAmount` and `getBuyV3TokenAmountFromQuoteAmount` in [`@pump-fun/pump-sdk` 4.0.0](https://www.npmjs.com/package/@pump-fun/pump-sdk/v/4.0.0) (they need the curve's base token balance, returned by `fetchBuyState` as `curveBaseTokenBalance`), and `buy_quote_bonding_curve_v3_sol_in` / `buy_quote_bonding_curve_v3_token_out` in [`pump-rust-client` 0.4.0](https://crates.io/crates/pump-rust-client/0.4.0).++## Events and state++A completing v3 buy emits three events, in this order:++1. `TradeEvent`: the curve part only (`token_amount` is what the curve had left).+2. `CompleteEvent`: the curve is complete.+3. `PostCompleteBuyEvent`: the pool part. `base_out` and `quote_in` are the extra tokens and the quote they cost; `fee`, `creator_fee` and `buyback_fee` are the fees on that part; `pool_base_reserves_before` / `pool_quote_reserves_before` are the reserves it was priced on, and `pool_base_reserves_after` / `pool_quote_reserves_after` are the reserves the pool will open with.++The curve records the pool part in `BondingCurve.post_complete_base_out` and `post_complete_quote_in` (both `0` when the completing buy had no pool part, and on every coin completed before this change).++For indexers: the buyer's total is the `TradeEvent` amounts plus the `PostCompleteBuyEvent` amounts. The fees in `PostCompleteBuyEvent` are kept on the curve like the v3 trade fees, except `buyback_fee`, which is paid in the trade. A `TradeEvent` with `ix_name` `multi_hop_swap` on a bonding curve may be followed by the same two events.diff --git a/docs/pumpfun-program/docs/VIRTUAL_QUOTE_RESERVES_FEE_ADJUSTMENT.md b/docs/pumpfun-program/docs/VIRTUAL_QUOTE_RESERVES_FEE_ADJUSTMENT.mdnew file mode 100644index 000000000..14d7c316b--- /dev/null+++ b/docs/pumpfun-program/docs/VIRTUAL_QUOTE_RESERVES_FEE_ADJUSTMENT.md@@ -0,0 +1,44 @@+# Virtual Quote Reserves and Fees Kept in the Pool++This explains **why** `Pool::virtual_quote_reserves` goes negative (see [Negative virtual quote reserves](NEGATIVE_VIRTUAL_QUOTE_RESERVES.md)) and what it means for integrations.++**If you already treat `virtual_quote_reserves` as a signed number and price against the effective quote reserves, this is not a breaking change. Your quotes stay correct and nothing needs to change. All existing trade instructions keep working the same way, with the same accounts and arguments.**++## What happens++The PumpSwap v2 trades (`buy_v2`, `buy_exact_quote_in_v2`, `sell_v2`) and `multi_hop_swap` keep the protocol fee and the creator fee **inside the pool's quote vault** instead of paying them out on every trade (see [Fee sweeps](instructions/SWEEP_FEES.md)). That money is not liquidity. It must not change the price.++So every time a fee is kept, the program subtracts it from `virtual_quote_reserves`. Every time a sweep pays it out, the program adds it back. The quote vault balance and `virtual_quote_reserves` move in opposite directions by the same amount, and their sum stays the real liquidity:++```text+pool_quote_token_account.amount = real_quote_reserves + Pool::protocol_fees + Pool::creator_fees+Pool::virtual_quote_reserves = boost_reserves - Pool::protocol_fees - Pool::creator_fees++effective_quote_reserves = pool_quote_token_account.amount + Pool::virtual_quote_reserves+ = real_quote_reserves + boost_reserves+```++`boost_reserves` is the extra amount a boosted pool carries (see the existing docs); it is `0` on most pools. On a plain pool with fees waiting, `virtual_quote_reserves` is simply minus the waiting fees, which is why it is negative.++## Example++A plain pool holds 100 SOL of real liquidity and is not boosted. A user buys with a v2 trade and pays 10 SOL, of which 0.03 SOL is protocol and creator fee kept in the vault. The buyback part of the fee is left out to keep the numbers simple. Amounts in SOL.++| Step | Quote vault balance | `protocol_fees` + `creator_fees` | `virtual_quote_reserves` | Effective quote reserves |+| ---------------------------- | ------------------- | -------------------------------- | ------------------------ | ------------------------ |+| Start | 100.00 | 0 | 0 | 100.00 |+| After the v2 buy | 110.00 | 0.03 | -0.03 | 109.97 |+| After the sweeps pay 0.03 out | 109.97 | 0 | 0 | 109.97 |++The effective quote reserves never counted the waiting fees, so the price is the same before and after the sweep.++## What this means for you++- **Quoting:** keep using `effective_quote_reserves = pool_quote_token_account.amount + virtual_quote_reserves`, as a signed `i128` addition. Nothing changes.+- **Not a breaking change for quotes:** if your code already handles negative `virtual_quote_reserves`, you are done.+- **Existing trade instructions:** PumpSwap `buy`, `sell` and `buy_exact_quote_in`, and Pump `buy`, `sell`, `buy_v2`, `sell_v2`, `buy_exact_quote_in_v2`, all keep working exactly as before, with the same accounts and arguments. They still pay fees per trade.+- **Do not read the raw vault balance as liquidity.** It now includes fees waiting to be swept.+- **Boost:** a pool is boosted when `virtual_quote_reserves + protocol_fees + creator_fees` is not `0`, not when the stored field alone is not `0`. `BuyEvent` / `SellEvent` carry this as `can_boost`.+- **Indexers:** the trade events report `virtual_quote_reserves` (signed), `protocol_fee`, `coin_creator_fee` and `creator_fee_unclaimed`. `SweepPoolFeeEvent` reports each payout. `Pool.protocol_fees` and `Pool.creator_fees` are appended fields; read them as `0` on pools written before the upgrade.++The guarantees from [Negative virtual quote reserves](NEGATIVE_VIRTUAL_QUOTE_RESERVES.md) still hold: `pool_quote_token_account.amount + virtual_quote_reserves` never overflows and is never negative.diff --git a/docs/pumpfun-program/docs/fees.png b/docs/pumpfun-program/docs/fees.pngnew file mode 100644index 000000000..219037382Binary files /dev/null and b/docs/pumpfun-program/docs/fees.png differdiff --git a/docs/pumpfun-program/docs/instructions/BUY.md b/docs/pumpfun-program/docs/instructions/BUY.mdindex 22a02a8dd..32f00d181 100644--- a/docs/pumpfun-program/docs/instructions/BUY.md+++ b/docs/pumpfun-program/docs/instructions/BUY.md@@ -2,6 +2,8 @@The `buy_v2` instruction buys base tokens from a bonding curve using the curve's quote mint. Unlike the legacy `buy` instruction, all accounts are passed through a single unified interface for both SOL-paired and non-SOL-paired coins.+> **New, smaller version:** `buy_v3` and `buy_exact_quote_in_v3` do the same buy with 17 accounts instead of 27. Same price, same fees; the protocol and creator fee stay on the curve until they are swept. See [Bonding Curve Trades V3](TRADE_V3.md). For pools after migration see [PumpSwap Trades V2](PUMP_SWAP_TRADE_V2.md), and to buy a coin paired with another pump coin straight from SOL or USDC see [Multi-hop swap](MULTI_HOP_SWAP.md). `buy_v2` keeps working unchanged.+## Accountsdiff --git a/docs/pumpfun-program/docs/instructions/CLAIM_CASHBACK.md b/docs/pumpfun-program/docs/instructions/CLAIM_CASHBACK.mdindex d74465561..013508ae4 100644--- a/docs/pumpfun-program/docs/instructions/CLAIM_CASHBACK.md+++ b/docs/pumpfun-program/docs/instructions/CLAIM_CASHBACK.md@@ -1,5 +1,9 @@# Claim Cashback+> **Note:** Cashback mode is deprecated and no new cashback coins can be created (see+> [PUMP_CASHBACK_README.md](../PUMP_CASHBACK_README.md)). Cashback accrued on existing cashback coins stays claimable+> with the instruction below, and those coins keep accruing it on every trade.+The `claim_cashback_v2` instruction claims cashback accrued in a user's volume accumulator. It supports both legacy SOL cashback and non-SOL quote mint cashback through the same interface. The instruction is permissionless: `user` is the cashback recipient, but does not need to sign the transaction.## Accounts@@ -85,7 +89,7 @@ let sdk = PumpSdk::new();let ix = sdk.claim_cashback_v2_instruction(user.pubkey(),- Pubkey::default(), // quote_mint — default → wSOL+ Pubkey::default(), // quote_mint - default → wSOLconstants::SPL_TOKEN_PROGRAM_ID, // quote_token_program);```diff --git a/docs/pumpfun-program/docs/instructions/COIN_CREATION.md b/docs/pumpfun-program/docs/instructions/COIN_CREATION.mdindex 33215405f..1582517ba 100644--- a/docs/pumpfun-program/docs/instructions/COIN_CREATION.md+++ b/docs/pumpfun-program/docs/instructions/COIN_CREATION.md@@ -40,7 +40,11 @@ The `create_v2` instruction takes the following instruction data arguments.| 3 | `uri` | `String` | Metadata URI. Maximum 200 characters. | No || 4 | `creator` | `Pubkey` | Creator address. Must not be `Pubkey::default()`. | No || 5 | `is_mayhem_mode` | `bool` | Enables mayhem mode for the coin. | No |-| 6 | `is_cashback_enabled` | `OptionBool` | Enables cashback for the coin. | Yes |+| 6 | `is_cashback_enabled` | `OptionBool` | **Deprecated.** Must be `[false]` or omitted: cashback coins can no longer be created and the instruction fails on `[true]`. Existing cashback coins are unaffected. | Yes |+| 7 | `creator_fee_bps` | `OptionU64` | Creator fee rate for coins on a custom pair (a quote asset other than SOL or USDC). Omitted or `0` means the standard fee schedule; on SOL- and USDC-paired coins the value is ignored and the schedule always applies. Contact the CTO team to change the rate of an existing coin. | Yes |+| 8 | `is_holder_reward` | `OptionBool` | `[true]` creates a [holder rewards coin](../HOLDER_REWARDS_README.md): the creator fee of every trade is set aside for the coin's holders instead of a creator wallet, and `creator` is not used as the fee recipient. Permanent. Omitted or `[false]` creates a regular coin. | Yes |++The trailing optional arguments (6-8) may be left off the end of the instruction data; a missing argument reads as `false` / `0`.## TS SDK@@ -61,7 +65,30 @@ const createInstruction = await PUMP_SDK.createV2Instruction({creator,user,mayhemMode: false, // Can be set to true.- cashback: false, // Can be set to true.+ holderReward: false, // true creates a holder rewards coin (see HOLDER_REWARDS_README.md).+ // cashback is deprecated: create_v2 rejects true.+});+```++### Holder Rewards Mint++Pass `holderReward: true` to create a coin whose creator fee goes to its holders. See+[HOLDER_REWARDS_README.md](../HOLDER_REWARDS_README.md) for what this means and how to read the new fields.++```ts+import { PUMP_SDK } from "@pump-fun/pump-sdk";++const mintKeypair = Keypair.generate();++const createInstruction = await PUMP_SDK.createV2Instruction({+ mint: mintKeypair.publicKey,+ name: "Name",+ symbol: "symbol",+ uri: "<your ipfs uri>",+ creator, // not used as the fee recipient on a holder rewards coin+ user,+ mayhemMode: false,+ holderReward: true,});```@@ -83,7 +110,6 @@ const createInstruction = await PUMP_SDK.createV2Instruction({creator,user,mayhemMode: false, // Can be set to true.- cashback: false, // Can be set to true.quoteMint,});```@@ -112,9 +138,9 @@ let ixs = sdk"EX","https://example.com/ex.json",user.pubkey(), // creator- Pubkey::default(), // quote_mint — default → wSOL+ Pubkey::default(), // quote_mint - default → wSOLfalse, // mayhem_mode- false, // cashback+ false, // cashback (deprecated: must stay false)None, // tokenized_agent_buyback_bps&global,1_000_000_000, // amount (token base units, 6 decimals)@@ -147,3 +173,8 @@ let ixs = sdk.expect("create_v2_and_buy_instruction");```+## Pump Coin as Quote Mint++`create_v2` can also pair a new coin with an existing pump coin instead of SOL or USDC. The 16 accounts and the arguments above stay the same. Only the remaining accounts change: after the three quote accounts (17 to 19) you also pass the `quote_control` PDA, the quote coin's bonding curve, and the quote coin's PumpSwap pool and vaults if it has migrated. The new coin's starting reserves are computed from the quote coin's current reserves, so it raises about as much as a normal launch, counted in the quote coin.++See [Creating a coin paired with a pump coin](CREATE_WITH_PUMP_COIN_QUOTE.md) for the account list, the rules on which coins can be a quote, and how to trade the new coin.diff --git a/docs/pumpfun-program/docs/instructions/COLLECT_CREATOR_FEE.md b/docs/pumpfun-program/docs/instructions/COLLECT_CREATOR_FEE.mdindex af02f9a2d..141cc50a1 100644--- a/docs/pumpfun-program/docs/instructions/COLLECT_CREATOR_FEE.md+++ b/docs/pumpfun-program/docs/instructions/COLLECT_CREATOR_FEE.md@@ -1,6 +1,6 @@# Collect Creator Fee-> **Note:** These instructions only apply to coins that do **not** have a `sharing_config` — i.e. single-creator-recipient coins. Once a coin's creator vault has been migrated to a `sharing_config`, fees must be distributed through the Pump Fees program instead, and both instructions below will fail.+> **Note:** These instructions only apply to coins that do **not** have a `sharing_config` - i.e. single-creator-recipient coins. Once a coin's creator vault has been migrated to a `sharing_config`, fees must be distributed through the Pump Fees program instead, and both instructions below will fail.Coin creators accrue fees in two separate vaults:diff --git a/docs/pumpfun-program/docs/instructions/CREATE_WITH_PUMP_COIN_QUOTE.md b/docs/pumpfun-program/docs/instructions/CREATE_WITH_PUMP_COIN_QUOTE.mdnew file mode 100644index 000000000..5e900d65d--- /dev/null+++ b/docs/pumpfun-program/docs/instructions/CREATE_WITH_PUMP_COIN_QUOTE.md@@ -0,0 +1,69 @@+# Creating a Coin Paired With a Pump Coin++`create_v2` can pair a new coin with an **existing pump coin** instead of SOL or USDC. The 16 accounts and the arguments are the same as in [Coin Creation](COIN_CREATION.md). What changes is the list of remaining accounts: you also pass the quote coin's bonding curve, and its PumpSwap pool if it has migrated.++Below, **Q** is the pump coin you want to use as the quote mint.++## Which pump coins can be the quote++- Q must be paired with SOL or USDC (or another quote mint listed by pump.fun). A coin that is itself paired with a pump coin cannot be used as a quote yet; creation fails with `CurveDepthExceeded` (6105).+- Q must not be a mayhem-mode coin.+- Q can still be on its bonding curve, or already migrated to PumpSwap. If Q's curve is complete but the pool is not created yet, creation fails with `QuoteCurveAwaitingMigration` (6107). Retry after `migrate_v2` runs.+- The new coin cannot be in mayhem mode (`MayhemModeQuoteMintNotAllowed`, 6071). Holder rewards work, and `creator_fee_bps` can be set, like on other custom pairs.+- If Q is listed by pump.fun as a quote mint, it works the normal way (see [Coin Creation](COIN_CREATION.md)) and the extra accounts below are not read.++## Remaining accounts++Pass these after the 16 fixed accounts, in this order. Slots are positional.++| Index | Account | Seeds / derivation | Required when |+| ----- | -------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------- |+| 0 | `quote_mint` | Q's mint. | Always |+| 1 | `associated_quote_bonding_curve` | Associated token account for Q, owned by the new `bonding_curve`, using Q's token program. Writable. Created by the instruction, paid by `user`. | Always |+| 2 | `quote_token_program` | Q's token program. Token-2022 (`TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb`) for coins created with `create_v2`, SPL Token for older coins. | Always |+| 3 | `quote_control` | Pump PDA: seeds `[b"quote-control"]`. Address: `6z6GDdfb2AjR9ZhJmAUQ5cipJCVxQvLJhB2H8mCwTFBP`. | Always |+| 4 | `quote_bonding_curve` | Q's bonding curve. Pump PDA: seeds `[b"bonding-curve", Q]`. | Always |+| 5 | `quote_pool` | Q's PumpSwap pool. PumpSwap PDA: seeds `[b"pool", 0u16 (little endian), pool_authority, Q, quote_of_Q]`, where `pool_authority` is the Pump PDA `[b"pool-authority", Q]` and `quote_of_Q` is wrapped SOL for a SOL-paired Q, or Q's quote mint otherwise. | Only if Q has migrated |+| 6 | `quote_pool_base_token_account` | `quote_pool.pool_base_token_account`. | Only if Q has migrated |+| 7 | `quote_pool_quote_token_account` | `quote_pool.pool_quote_token_account`. | Only if Q has migrated |++If Q is still on its bonding curve, pass indexes 0 to 4 only. If Q has migrated, all 8 are required (`QuotePoolAccountsRequired`, 6101, otherwise).++## Starting price++The new coin's starting `virtual_quote_reserves` are not a fixed number. They are computed from Q's current reserves (Q's bonding curve, or Q's pool after migration), so that the new coin raises about as much as a normal SOL or USDC launch, just counted in Q.++How it works: take the amount a normal launch raises by the time its curve sells out (about 85 SOL for a SOL launch). Buy Q with that amount on Q's own curve or pool, with no fees. The Q tokens that buy returns are what the new coin will raise. The stored `virtual_quote_reserves` are that raise scaled back to a starting seed, using the same ratio a normal curve has between its seed and its raise.++Because the amount is priced through Q's curve, not at Q's spot price, the new coin never asks for more Q than that buy returns. So a young Q with a small supply works too; there is no supply check. The value is stored in `BondingCurve.virtual_quote_reserves` and reported in `CreateEvent.virtual_quote_reserves`. If Q is priced so high that the raise rounds down to nothing, creation fails with `QuoteReservesOutOfRange` (6104).++## Trading the new coin++- Use [`buy_v3` / `sell_v3`](TRADE_V3.md) or [`buy_v2` / `sell_v2`](BUY.md) with `quote_mint` = Q and `quote_token_program` = Q's token program. The user needs a token account for Q.+- For the v3 trades, `buyback_fee_recipient` is a buyback fee recipient wallet's associated token account for Q. It may not exist yet for a new quote coin. Add a `createAssociatedTokenAccountIdempotent` instruction for it before the trade; anyone can pay the rent.+- To buy the new coin straight from SOL or USDC, use [`multi_hop_swap`](MULTI_HOP_SWAP.md): Q's bonding curve or PumpSwap pool is the first hop and the new coin's bonding curve is the second.++## Errors++| Code | Name | Meaning |+| ---- | ------------------------------- | ---------------------------------------------------------------------------------------------- |+| 6063 | `UnsupportedQuoteMint` | Q is not a listed quote mint and remaining account 3 or 4 is missing. |+| 6099 | `InvalidQuoteBondingCurve` | Remaining account 4 is not Q's bonding curve. |+| 6100 | `QuoteBondingCurveNotEligible` | Q is a mayhem coin, or Q's own quote mint is not listed. |+| 6105 | `CurveDepthExceeded` | Q is itself paired with a pump coin. Not allowed yet. |+| 6107 | `QuoteCurveAwaitingMigration` | Q's curve is complete but its pool does not exist yet. Retry after migration. |+| 6101 | `QuotePoolAccountsRequired` | Q has migrated but remaining accounts 5 to 7 are missing. |+| 6102 | `QuotePoolNotFound` | Remaining account 5 is not a PumpSwap pool. |+| 6103 | `InvalidQuotePool` | Remaining accounts 5 to 7 do not match Q's pool and vaults. |+| 6104 | `QuoteReservesOutOfRange` | The starting reserves computed from Q's reserves round down to zero. |+| 6071 | `MayhemModeQuoteMintNotAllowed` | `is_mayhem_mode` was `true`. Mayhem mode only works with SOL or USDC. |++## SDKs++- TypeScript: [`@pump-fun/pump-sdk` 4.0.0](https://www.npmjs.com/package/@pump-fun/pump-sdk/v/4.0.0). `OnlinePumpSdk.resolveQuoteMint` recognises a pump coin quote (`source: "pumpCoin"`). Pass its `pumpQuote.accounts` to `createV2Instruction` or `createV2AndBuyV2Instructions` as `pumpQuote`, and its `pumpQuote.curve` to the quote functions. The refusals above map to typed errors such as `QuoteBondingCurveNotEligibleError` and `QuoteCurveAwaitingMigrationError`.+- Rust: [`pump-rust-client` 0.4.0](https://crates.io/crates/pump-rust-client/0.4.0). `fetch_pump_quote_create` and `create_v2_pump_quote_accounts` resolve the quote coin's accounts for `create_v2`; `pump_quote_initial_virtual_quote_reserves` gives the starting reserves for quoting the first buy.+- IDL: [idl/pump.json](../../idl/pump.json), TypeScript types in [idl/pump.ts](https://github.com/pump-fun/pump-public-docs/blob/2293f9a66c654e9fe82dc5e8f4618538f24bb35f/idl/pump.ts).++## Synthetic Migration++A coin paired with a pump coin completes its curve like any other coin: the v3 buy that crosses the limit can also buy from the tokens that would go into its PumpSwap pool, at that pool's price, and the pool later opens where that buy stopped. No migration fee is taken from a token-paired coin's raised quote in that pricing. See [Synthetic migration](../SYNTHETIC_MIGRATION.md).diff --git a/docs/pumpfun-program/docs/instructions/CREATOR_FEE_SHARING.md b/docs/pumpfun-program/docs/instructions/CREATOR_FEE_SHARING.mdindex 24ac88810..f5eb52c33 100644--- a/docs/pumpfun-program/docs/instructions/CREATOR_FEE_SHARING.md+++ b/docs/pumpfun-program/docs/instructions/CREATOR_FEE_SHARING.md@@ -1,13 +1,13 @@# Creator Fee Sharing-> **Note:** These instructions only apply to coins that **have** a `sharing_config` — i.e. coins whose creator vault has been migrated to the Pump Fees program for multi-recipient distribution. For single-creator-recipient coins (no `sharing_config`), use [`collect_creator_fee_v2` / `collect_coin_creator_fee`](./COLLECT_CREATOR_FEE.md) instead.+> **Note:** These instructions only apply to coins that **have** a `sharing_config` - i.e. coins whose creator vault has been migrated to the Pump Fees program for multi-recipient distribution. For single-creator-recipient coins (no `sharing_config`), use [`collect_creator_fee_v2` / `collect_coin_creator_fee`](./COLLECT_CREATOR_FEE.md) instead.The lifecycle is:-1. `create_fee_sharing_config` (Pump Fees) — opt the coin into shared distribution. Migrates the bonding curve creator (and AMM `pool.coin_creator` if graduated) to the new `sharing_config` PDA.-2. `update_fee_shares_v2` (Pump Fees) — set the final list of shareholders. Sweeps any pending creator fees from both the AMM and the bonding curve via CPI before applying the new shares. Can only be called once per `sharing_config` (the admin is revoked after).-3. `transfer_creator_fees_to_pump_v2` (Pump AMM) — sweep coin creator fees accrued on the AMM into the bonding curve's creator vault so they can be distributed by the pump program. Permissionless.-4. `distribute_creator_fees_v2` (Pump program) — pay out the bonding curve's creator vault to each shareholder according to their `share_bps`. Permissionless.+1. `create_fee_sharing_config` (Pump Fees) - opt the coin into shared distribution. Migrates the bonding curve creator (and AMM `pool.coin_creator` if graduated) to the new `sharing_config` PDA.+2. `update_fee_shares_v2` (Pump Fees) - set the final list of shareholders. Sweeps any pending creator fees from both the AMM and the bonding curve via CPI before applying the new shares. Can only be called once per `sharing_config` (the admin is revoked after).+3. `transfer_creator_fees_to_pump_v2` (Pump AMM) - sweep coin creator fees accrued on the AMM into the bonding curve's creator vault so they can be distributed by the pump program. Permissionless.+4. `distribute_creator_fees_v2` (Pump program) - pay out the bonding curve's creator vault to each shareholder according to their `share_bps`. Permissionless.For every token account in the tables below, the third column tells you who is responsible for initialization: whether the caller must initialize it beforehand, whether the instruction will initialize it on the fly, or whether it can be left uninitialized when `quote_mint` is wrapped SOL (the SOL-paired code path never touches it).@@ -115,7 +115,7 @@ Sweeps coin creator fees accrued on the Pump AMM out of the AMM coin creator vau## `distribute_creator_fees_v2` (Pump program)-Pays out the bonding curve creator vault to every shareholder in `sharing_config.shareholders` proportionally to their `share_bps`. Permissionless. For wrapped-SOL quotes the instruction transfers lamports directly to each shareholder address (leaving the vault rent-exempt). For non-native quotes it transfers tokens from the vault's ATA to each shareholder's ATA, and — if `initialize_ata = true` is passed — creates any missing shareholder ATAs along the way (paid for by `payer`).+Pays out the bonding curve creator vault to every shareholder in `sharing_config.shareholders` proportionally to their `share_bps`. Permissionless. For wrapped-SOL quotes the instruction transfers lamports directly to each shareholder address (leaving the vault rent-exempt). For non-native quotes it transfers tokens from the vault's ATA to each shareholder's ATA, and - if `initialize_ata = true` is passed - creates any missing shareholder ATAs along the way (paid for by `payer`).### Accountsdiff --git a/docs/pumpfun-program/docs/instructions/MULTI_HOP_SWAP.md b/docs/pumpfun-program/docs/instructions/MULTI_HOP_SWAP.mdnew file mode 100644index 000000000..d76809051--- /dev/null+++ b/docs/pumpfun-program/docs/instructions/MULTI_HOP_SWAP.md@@ -0,0 +1,143 @@+# Multi-Hop Swap++`multi_hop_swap` is one PumpSwap instruction that trades through **two or more pools and bonding curves in a row**.++It is made for coins paired with another pump coin. Say coin **B** is paired with pump coin **A**, and **A** is paired with SOL. To buy B with SOL you used to need two trades and a token account for A. With `multi_hop_swap` it is one instruction: SOL → A (on A's bonding curve or pool) → B (on B's bonding curve or pool). Selling works the same way in reverse: B → A → SOL.++What you get:++- **Smaller transactions.** 16 fixed accounts plus 5 accounts per hop. Two hops fit easily in one normal transaction, and so do three.+- **No token account for the middle coin.** Coin A never touches the user's wallet. Each hop's output stays in the pool or curve until the next hop pulls it.+- **Fees once per route, not once per hop.** See [Fees](#fees).+- **One slippage check**, on the final amount.++## Rules++- **Exact in.** `amount_in` is taken from `user_in_token_account`. The final coin lands in `user_out_token_account`. `min_amount_out` is checked once at the end and must be greater than `0`.+- **One direction per route.** Every hop must be a buy (SOL/USDC → A → B) or every hop must be a sell (B → A → SOL/USDC). Mixing fails with `MultiHopMixedDirection` (6086).+- **The hops must chain.** The coin coming out of one hop must be the base or quote mint of the next one, and the last hop must produce the mint of `user_out_token_account`. Otherwise `MultiHopDiscontinuousPath` (6084).+- **Pool hops** must be pump pools (created by migration, pool `index` 0 with pump's pool authority as `creator`). Mayhem-mode pools are not supported (`MayhemPoolNotSupported`, 6080), and neither are mayhem-mode bonding curves (`MultiHopMayhemCurveNotSupported`, 6108).+- **Bonding curve hops** can use any quote mint: SOL, USDC, a pump coin, or another listed token such as an xStock. A SOL-paired bonding curve is always the hop next to the user's own SOL, since every hop of a route trades the same way: the first hop of a buy route or the last hop of a sell route. On that hop the user pays or receives **native SOL**. A buy takes lamports from the `user` wallet, and a sell pays lamports to it.+- **The wrapped SOL ATA is still required on a SOL curve hop.** Pass the user's wrapped SOL ATA as `user_in_token_account` (buy) or `user_out_token_account` (sell), and make sure it exists. No tokens move through it; it is read for its mint only, so the interface stays the same for every route.+- **Cashback coins** can only be the hop next to your own currency (the first hop of a buy, the last hop of a sell).+- **SOL routes.** When the SOL hop is a PumpSwap pool (a migrated SOL-paired coin), SOL moves as wrapped SOL through the user's wrapped SOL token account, so wrap first. When the SOL hop is a bonding curve, native SOL moves instead, but the same wrapped SOL account is passed and must exist.+- **The user's in and out token accounts must exist.** The instruction does not create them. It does create `user_volume_accumulator` if missing (paid by `user`).+- **Set a compute unit limit.** Each hop costs roughly 30k to 50k CU, and a first trade also creates the volume accumulator. A three-hop route is already near the 200k default.+- **Four or more hops** need a v0 transaction with an address lookup table. Up to three hops fit a legacy transaction.++## Accounts++### Fixed accounts (16)++| # | Account | Seeds / derivation | `init_if_needed` / SOL cost |+| --- | ------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------ |+| 1 | `user` | Transaction signer and trader. | - |+| 2 | `user_in_token_account` | User's token account for the coin they pay with. Must exist. On a buy route that starts on a SOL-paired bonding curve this is the user's wrapped SOL ATA; it must exist even though the buy takes native SOL from the `user` wallet instead. | - |+| 3 | `user_out_token_account` | User's token account for the coin they receive. Must exist. On a sell route that ends on a SOL-paired bonding curve this is the user's wrapped SOL ATA; it must exist even though the sell pays native SOL to the `user` wallet instead. | - |+| 4 | `global_config` | PumpSwap PDA: seeds `[b"global_config"]`. Address: `ADyA8hdefvWN2dbGGWFotbzWxrAvLW83WG6QCVXvJKqw`. | - |+| 5 | `fee_config` | Pump Fees PDA: seeds `[b"fee_config", pump_amm_program_id]`. Address: `5PHirr8joyTMp9JMm6nW7hNDVyEYdkzDqazxPD7RaTjx`. | - |+| 6 | `user_volume_accumulator` | PumpSwap PDA: seeds `[b"user_volume_accumulator", user]`. Created if missing, paid by `user`. | Rent if missing |+| 7 | `buyback_fee_recipient` | Associated token account of one of the 8 buyback fee recipient wallets, for the quote mint of the hop that trades the user's own currency (the first hop on a buy route, the last hop on a sell route). On a SOL route this is the wallet's wrapped SOL ATA, whether that hop is a pool or a bonding curve (a SOL curve pays it in lamports and syncs it). Must exist. | Never created. |+| 8 | `token_program` | SPL Token Program: `TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA`. | - |+| 9 | `token_2022_program` | Token-2022 Program: `TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb`. | - |+| 10 | `system_program` | System Program: `11111111111111111111111111111111`. | - |+| 11 | `event_authority` | PumpSwap PDA: seeds `[b"__event_authority"]`. | - |+| 12 | `program` | PumpSwap program account. | - |+| 13 | `pump_program` | Pump program: `6EF8rrecthR5Dkzon8Nwu78hRvfCKubJ14M5uBEwF6P`. | - |+| 14 | `pump_global` | Pump PDA: seeds `[b"global"]`. Address: `4wTV1YmiEkRvAtNtsSGPtUrqRYQMe5SKy2uB4Jjaxnjf`. | - |+| 15 | `pump_fee_config` | Pump Fees PDA: seeds `[b"fee_config", pump_program_id]`. Address: `8Wf5TiAheLUqBrKXeYg2JtAFFMWtKdG2BSFgqUcPVwTt`. | - |+| 16 | `pump_event_authority` | Pump PDA: seeds `[b"__event_authority"]`. Address: `Ce6TQqeHC9p8KetsN6JsjHK7UTZk7nasjjnr7XxXp9F1`. | - |++Accounts 13 to 16 are always required, even when no hop is a bonding curve.++### Remaining accounts (5 per hop)++After the 16 fixed accounts, pass one group of 5 accounts per hop, in route order. The program reads the owner of the third account to know if the hop is a pool or a bonding curve.++| Slot | Pool hop | Bonding curve hop |+| ---- | ------------------------------- | --------------------------------------------------------------------------------- |+| 1 | `pool.base_mint` | Base mint of the coin |+| 2 | `pool.quote_mint` | Quote mint of the coin (`bonding_curve.quote_mint`). Wrapped SOL for a SOL-paired coin. |+| 3 | `pool` (writable) | `bonding_curve` PDA `[b"bonding-curve", base_mint]` (writable) |+| 4 | `pool.pool_base_token_account` (writable) | Associated token account for the base mint, owned by `bonding_curve` (writable) |+| 5 | `pool.pool_quote_token_account` (writable) | Associated token account for the quote mint, owned by `bonding_curve` (writable). For a SOL-paired coin pass the derived wrapped SOL ATA address; it is not read and does not need to exist. |++The direction of a hop follows from the coin you hold when you reach it: if it is the hop's quote mint, the hop is a buy; if it is the hop's base mint, the hop is a sell.++## Instruction Data++| # | Argument | Type | Description / validation | Optional? |+| --- | ---------------- | ----- | ------------------------------------------------------------------------------------ | --------- |+| 1 | `amount_in` | `u64` | Amount of the input coin to spend, in its base units. Must be greater than `0`. | No |+| 2 | `min_amount_out` | `u64` | Least amount of the output coin the user accepts. Must be greater than `0`. | No |++## Examples: two hops, buying and selling B with SOL++In both examples coin **B** is on its bonding curve and is paired with pump coin **A**. **A** is paired with SOL. The only difference is where A trades: on its PumpSwap pool (A has migrated) or still on its bonding curve.++### First leg on a PumpSwap pool (A has migrated)++Buy B with SOL. Route: SOL → A (A's PumpSwap pool, quote wrapped SOL) → B (B's bonding curve, quote A).++- `user_in_token_account`: the user's wrapped SOL token account, holding the SOL to spend. Wrap first.+- `user_out_token_account`: the user's token account for B.+- `buyback_fee_recipient`: a buyback fee recipient wallet's wrapped SOL token account (the first hop trades the user's SOL).+- Remaining accounts, hop 1 (pool): `[A mint, WSOL mint, A pool, A pool base vault, A pool quote vault]`.+- Remaining accounts, hop 2 (curve): `[B mint, A mint, B bonding curve, B curve base ATA, B curve quote ATA]`.++The wrapped SOL moves from the user's token account into A's pool vault. The user's A never touches their wallet.++Sell B for SOL. Route: B → A (B's bonding curve) → SOL (A's PumpSwap pool). Swap the two groups and the in/out token accounts: `user_in_token_account` is the user's B account, `user_out_token_account` is the user's wrapped SOL token account, which receives wrapped SOL. `buyback_fee_recipient` is again the wallet's wrapped SOL token account, since the last hop now trades the user's SOL.++### First leg on a bonding curve (A has not migrated)++Buy B with SOL. Route: SOL → A (A's bonding curve, quote SOL) → B (B's bonding curve, quote A).++- `user_in_token_account`: the user's wrapped SOL ATA. **It must exist, but it is not used for the transfer.** The buy takes native SOL from the `user` wallet as lamports. The account is only read for its mint, so the interface is the same as in the pool case.+- `user_out_token_account`: the user's token account for B.+- `buyback_fee_recipient`: a buyback fee recipient wallet's wrapped SOL ATA, the same account as in the pool case. A's curve pays it in lamports and syncs it.+- Remaining accounts, hop 1 (curve): `[A mint, WSOL mint, A bonding curve, A curve base ATA, A curve WSOL ATA address]`. Pass the wrapped SOL mint as A's quote mint, and the derived wrapped SOL ATA address of A's curve: it is not read and does not need to exist.+- Remaining accounts, hop 2 (curve): `[B mint, A mint, B bonding curve, B curve base ATA, B curve quote ATA]`.++Both hops are bonding curves, so the Pump program handles the whole route in one call and moves the A tokens from A's curve to B's curve itself.++Sell B for SOL. Route: B → A (B's bonding curve) → SOL (A's bonding curve). Swap the two groups and the in/out token accounts: `user_in_token_account` is the user's B account, `user_out_token_account` is the user's wrapped SOL ATA, which must exist but receives nothing. The sell pays native SOL to the `user` wallet as lamports.++## Fees++Fees are charged **once per route**:++- The **protocol fee** is charged once, on the hop that trades the user's own currency (the first hop of a buy, the last hop of a sell), at that pool's or curve's normal rate and in that hop's quote mint. Its buyback part is paid in the trade to `buyback_fee_recipient`. The rest stays in that pool or curve, as on a v2 / v3 trade.+- The **creator fee** (or holder rewards fee) and, on a pool, the **LP fee** are charged once, on the hop that trades the coin at the far end of the route (the coin being bought or sold), at that pool's or curve's normal rate.+- Every other hop charges nothing.+- A one-hop route pays exactly what a `buy_v2` / `sell_v2` (PumpSwap) or `buy_v3` / `sell_v3` (bonding curve) pays.++The protocol and creator fees stay in the pool or curve that charged them and are paid out later by the sweep instructions. See [Fee sweeps](SWEEP_FEES.md).++## Events++Each hop emits its own event, as if the user had traded there directly: a PumpSwap `BuyEvent` (with `ix_name` `multi_hop_swap`) or `SellEvent` for a pool hop, a Pump `TradeEvent` (with `ix_name` `multi_hop_swap`) for a bonding curve hop. Each event reports only the fees that hop charged. The middle coins net to zero for the user, while the volume on every pool and curve is real.++## `multi_hop_curve_swap`++The Pump program has a matching `multi_hop_curve_swap` instruction. It is only for PumpSwap to call: it requires PumpSwap's `global_config` PDA as a signer, so nothing else can call it. Do not call it directly; always use PumpSwap's `multi_hop_swap`.++## Related++- [Bonding Curve Trades V3](TRADE_V3.md) and [PumpSwap Trades V2](PUMP_SWAP_TRADE_V2.md): the single-venue trades a multi-hop route is made of.+- [Creating a coin paired with a pump coin](CREATE_WITH_PUMP_COIN_QUOTE.md): how the coins that need a multi-hop route are created.++## SDKs++- TypeScript, PumpSwap side: [`@pump-fun/pump-swap-sdk` 2.1.0](https://www.npmjs.com/package/@pump-fun/pump-swap-sdk/v/2.1.0). `onlineSdk.multiHopPoolHops` fetches the pool hops, `multiHopSwapQuote` gives `minAmountOut`, and `PUMP_AMM_SDK.multiHopSwapInstructions` builds the instruction.+- TypeScript, Pump side: [`@pump-fun/pump-sdk` 4.0.0](https://www.npmjs.com/package/@pump-fun/pump-sdk/v/4.0.0). `OnlinePumpSdk.resolveMultiHopRoute(path, side)` picks each hop's venue, `simulateMultiHopSwap` returns the amount out, and `PumpSdk.multiHopSwapInstructions` builds the swap, wrapping SOL in, closing the wrapped SOL account after, and creating the buyback recipient's token account when it is missing.+- Rust: [`pump-rust-client` 0.4.0](https://crates.io/crates/pump-rust-client/0.4.0). `multi_hop_swap_instructions` with `MultiHopHop::pool` / `MultiHopHop::curve`, `quote_multi_hop_swap` for the route output, and `MULTI_HOP_COMPUTE_UNITS` for the compute budget.+- IDL: [idl/pump_amm.json](../../idl/pump_amm.json), TypeScript types in [idl/pump_amm.ts](https://github.com/pump-fun/pump-public-docs/blob/2293f9a66c654e9fe82dc5e8f4618538f24bb35f/idl/pump_amm.ts).++These releases support SOL-paired bonding curve hops too. The builders make sure the user's wrapped SOL ATA exists (created, not funded); a buy that starts on a SOL curve pays from the wallet's SOL, not from the wrapped SOL account, so the wallet needs `amount_in` plus rent, and a sell that ends on one is unwrapped like any other wrapped SOL output.++## Synthetic Migration on a Curve Hop++A bonding curve hop that would buy more than the curve has left does not fail. It takes what is left at the curve's price, completes the curve, and spends the whole rest of its input on the tokens that would have gone into that coin's PumpSwap pool, at the price that pool would charge. The hop then emits `CompleteEvent` and `PostCompleteBuyEvent` after its `TradeEvent`. After that hop, the curve takes no more trades until its migration happens.++This works on a SOL-paired curve too: the migration fee comes off the raised SOL before the pool part is priced, exactly as `migrate_v2` would take it. Mayhem-mode curves cannot be a hop at all. See [Synthetic migration](../SYNTHETIC_MIGRATION.md).diff --git a/docs/pumpfun-program/docs/instructions/PUMP_SWAP_TRADE_V2.md b/docs/pumpfun-program/docs/instructions/PUMP_SWAP_TRADE_V2.mdnew file mode 100644index 000000000..075073492--- /dev/null+++ b/docs/pumpfun-program/docs/instructions/PUMP_SWAP_TRADE_V2.md@@ -0,0 +1,109 @@+# PumpSwap Trades V2++PumpSwap `buy_v2`, `buy_exact_quote_in_v2` and `sell_v2` do the same trades as `buy`, `buy_exact_quote_in` and `sell`, with **17 accounts and no remaining accounts**. Prices, slippage checks and fee amounts are the same. The only difference is where the fees go: a v2 trade keeps the protocol fee and the coin creator fee in the pool instead of paying them out on every trade. See [Fee sweeps](SWEEP_FEES.md). The LP fee is unchanged: it goes into the pool reserves on every trade, as before.++They work on every pool, both pump pools created by migration and permissionless pools. Mayhem pools work too. Cashback coin pools are the one exception: a v2 trade on one fails with `CashbackCoinNotSupported` (6079), so keep using the v1 instructions for those.++The v1 instructions keep working unchanged. v1 and v2 trades can be mixed on the same pool.++## Why they are smaller++Compared with `buy` / `sell`, these accounts are gone:++- `protocol_fee_recipient` and `protocol_fee_recipient_token_account`: the protocol fee stays in the pool's quote vault and is recorded in `Pool.protocol_fees`.+- `coin_creator_vault_ata` and `coin_creator_vault_authority`: the creator fee stays in the pool's quote vault and is recorded in `Pool.creator_fees`.+- The buyback recipient wallet and its token account (remaining accounts) become one `buyback_fee_recipient` token account. The buyback part of the protocol fee is still paid in the trade.+- `global_volume_accumulator`, `fee_program`, `associated_token_program` and the other remaining accounts are not needed. The fee schedule is read from the Pump Fees `fee_config` account directly.++## Accounts++All three instructions take the same 17 accounts, in this order.++| # | Account | Seeds / derivation | `init_if_needed` / SOL cost |+| --- | -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------ |+| 1 | `pool` | The `Pool` account. | Small rent top-up if the account still has an older, shorter layout. Paid by `user`. |+| 2 | `user` | Transaction signer and trader. | - |+| 3 | `global_config` | PumpSwap PDA: seeds `[b"global_config"]`. Address: `ADyA8hdefvWN2dbGGWFotbzWxrAvLW83WG6QCVXvJKqw`. | - |+| 4 | `base_mint` | `pool.base_mint`. | - |+| 5 | `quote_mint` | `pool.quote_mint`. Wrapped SOL (`So11111111111111111111111111111111111111112`) for SOL pools. | - |+| 6 | `user_base_token_account` | User's token account for `base_mint`. **Must exist.** The trade does not create it. | - |+| 7 | `user_quote_token_account` | User's token account for `quote_mint`. For SOL pools this is a wrapped SOL account. **Must exist.** | - |+| 8 | `pool_base_token_account` | `pool.pool_base_token_account`. | - |+| 9 | `pool_quote_token_account` | `pool.pool_quote_token_account`. | - |+| 10 | `base_token_program` | Token program of `base_mint`. | - |+| 11 | `quote_token_program` | Token program of `quote_mint`. | - |+| 12 | `system_program` | System Program: `11111111111111111111111111111111`. | - |+| 13 | `user_volume_accumulator` | PumpSwap PDA: seeds `[b"user_volume_accumulator", user]`. Created if missing, paid by `user`. | Rent if missing |+| 14 | `fee_config` | Pump Fees PDA: seeds `[b"fee_config", pump_amm_program_id]`. Address: `5PHirr8joyTMp9JMm6nW7hNDVyEYdkzDqazxPD7RaTjx`. | - |+| 15 | `buyback_fee_recipient` | Associated token account for `quote_mint` of one of the 8 buyback fee recipient wallets, using `quote_token_program`. See [Buyback fee recipient](#buyback-fee-recipient). | Never created by the trade. **Must exist.** |+| 16 | `event_authority` | PumpSwap PDA: seeds `[b"__event_authority"]`. | - |+| 17 | `program` | PumpSwap program account. | - |++## Instruction Data++### `buy_v2`++| # | Argument | Type | Description / validation | Optional? |+| --- | --------------------- | ----- | -------------------------------------------------------------------------------------------- | --------- |+| 1 | `base_amount_out` | `u64` | Exact base tokens to buy. Must be greater than `0`. | No |+| 2 | `max_quote_amount_in` | `u64` | Most quote the buyer will pay, including all fees. | No |++### `buy_exact_quote_in_v2`++| # | Argument | Type | Description / validation | Optional? |+| --- | --------------------- | ----- | -------------------------------------------------------------------------------------------- | --------- |+| 1 | `spendable_quote_in` | `u64` | Exact quote amount to spend, including all fees. | No |+| 2 | `min_base_amount_out` | `u64` | Fewest base tokens the buyer accepts. Must be greater than `0`. | No |++### `sell_v2`++| # | Argument | Type | Description / validation | Optional? |+| --- | ---------------------- | ----- | ------------------------------------------------------------------------------------------- | --------- |+| 1 | `base_amount_in` | `u64` | Exact base tokens to sell. Must be greater than `0`. | No |+| 2 | `min_quote_amount_out` | `u64` | Least quote the seller accepts after all fees. | No |++## Buyback Fee Recipient++The buyback part of the protocol fee is paid in the trade, to one token account: the associated token account for `quote_mint` of any of the 8 buyback fee recipient wallets listed in [Fee Recipients](../FEE_RECIPIENTS.md).++The trade checks this account on every trade, even when the fee is `0` (for example on mayhem pools), and never creates it. For wrapped SOL and USDC the token accounts already exist. For a pump coin used as quote they may not, so add a `createAssociatedTokenAccountIdempotent` instruction for it before the trade when you are not sure. Anyone can pay the rent for it.++The protocol fee recipients are not passed anymore: the protocol fee stays in the pool until it is swept.++## Quoting++Nothing changes for quotes. Price against the effective quote reserves, as described in+[Quoting: effective quote reserves](../PUMP_SWAP_README.md#quoting-effective-quote-reserves):++```text+effective_quote_reserves = pool_quote_token_account.amount + Pool::virtual_quote_reserves+```++The fees a v2 trade keeps in the vault are subtracted from `virtual_quote_reserves`, so this formula keeps giving the right reserves. See [Virtual quote reserves and fees](../VIRTUAL_QUOTE_RESERVES_FEE_ADJUSTMENT.md).++## Events++A v2 trade emits the usual `BuyEvent` or `SellEvent`.++- `ix_name` is `buy_v2` or `buy_exact_quote_in_v2` on a `BuyEvent`. `SellEvent` has no `ix_name`; a v2 sell is recognised by the zero key below.+- `protocol_fee`, `coin_creator_fee`, `lp_fee` and `buyback_fee` are the amounts charged, same as on v1.+- `protocol_fee_recipient` and `protocol_fee_recipient_token_account` are the zero key (`11111111111111111111111111111111`). It means the protocol fee was kept in the pool, not paid out.+- `creator_fee_unclaimed` is the creator fee waiting in the pool after this trade.+- `virtual_quote_reserves` is signed and may be negative.++The payouts show up later as `SweepPoolFeeEvent`. See [Fee sweeps](SWEEP_FEES.md#events).++## Related++- [Bonding Curve Trades V3](TRADE_V3.md): the same change for coins still on their bonding curve.+- [Multi-hop swap](MULTI_HOP_SWAP.md): trade through two or more pools and curves in one instruction.++## SDKs++- TypeScript: [`@pump-fun/pump-swap-sdk` 2.1.0](https://www.npmjs.com/package/@pump-fun/pump-swap-sdk/v/2.1.0). `buyV2Instructions`, `buyExactQuoteInV2Instructions` and `sellV2Instructions`. The high-level `buyBaseInput`, `buyQuoteInput`, `sellBaseInput` and `sellQuoteInput` builders take `{ v2: true }` and use v2 on pools that support it (`supportsTradeV2(pool)`), v1 elsewhere. Prices come from the same quote functions as v1.+- Rust: [`pump-rust-client` 0.4.0](https://crates.io/crates/pump-rust-client/0.4.0). `buy_amm_v2_instructions`, `buy_exact_quote_in_amm_v2_instruction` and `sell_amm_v2_instructions`.+- IDL: [idl/pump_amm.json](../../idl/pump_amm.json), TypeScript types in [idl/pump_amm.ts](https://github.com/pump-fun/pump-public-docs/blob/2293f9a66c654e9fe82dc5e8f4618538f24bb35f/idl/pump_amm.ts).++## Synthetic Migration++The v3 buy that empties a bonding curve can now also buy from the tokens that would go into the PumpSwap pool, at the price that pool would charge, before the pool exists. The migration then creates the pool with exactly the reserves that buy left, so the pool opens where it stopped. Nothing changes for trading on the pool itself: the first PumpSwap trade sees a pool that is already at the right price. See [Synthetic migration](../SYNTHETIC_MIGRATION.md).diff --git a/docs/pumpfun-program/docs/instructions/SELL.md b/docs/pumpfun-program/docs/instructions/SELL.mdindex d32837a0b..596830270 100644--- a/docs/pumpfun-program/docs/instructions/SELL.md+++ b/docs/pumpfun-program/docs/instructions/SELL.md@@ -2,6 +2,8 @@The `sell_v2` instruction sells base tokens into a bonding curve using the curve's quote mint. Like `buy_v2`, it uses a single unified account interface for both SOL-paired and non-SOL-paired coins.+> **New, smaller version:** `sell_v3` does the same sell with 17 accounts instead of 26. Same price, same fees; the protocol and creator fee stay on the curve until they are swept. See [Bonding Curve Trades V3](TRADE_V3.md). For pools after migration see [PumpSwap Trades V2](PUMP_SWAP_TRADE_V2.md), and to sell a coin paired with another pump coin straight into SOL or USDC see [Multi-hop swap](MULTI_HOP_SWAP.md). `sell_v2` keeps working unchanged.+## Accountsdiff --git a/docs/pumpfun-program/docs/instructions/SWEEP_FEES.md b/docs/pumpfun-program/docs/instructions/SWEEP_FEES.mdnew file mode 100644index 000000000..dfdf7abeb--- /dev/null+++ b/docs/pumpfun-program/docs/instructions/SWEEP_FEES.md@@ -0,0 +1,127 @@+# Fees Kept on the Curve and Pool, and How to Sweep Them++The new trade instructions ([`buy_v3` / `sell_v3`](TRADE_V3.md) on the bonding curve, [`buy_v2` / `sell_v2`](PUMP_SWAP_TRADE_V2.md) on PumpSwap, and [`multi_hop_swap`](MULTI_HOP_SWAP.md)) **do not pay the protocol fee and the creator fee out on every trade**. They keep the money where the trade happened and write down how much is waiting. Anyone can pay it out later with a sweep instruction.++| Where the trade happened | Protocol fee waits in | Creator fee waits in | The money sits in |+| ------------------------ | ----------------------------- | -------------------------- | ----------------------------------------------------------------------- |+| Bonding curve (Pump) | `BondingCurve.protocol_fees` | `BondingCurve.creator_fee` | The curve's lamports (SOL-paired) or the curve's quote token account. |+| Pool (PumpSwap) | `Pool.protocol_fees` | `Pool.creator_fees` | The pool's quote vault (`pool_quote_token_account`). |++What does not change:++- **Fee amounts are the same.** Only the moment they are paid out changes.+- **The buyback part of the protocol fee is still paid in the trade**, to the `buyback_fee_recipient` account. It never waits.+- **The LP fee on pools is unchanged.** It goes into the reserves on every trade.+- **Old instructions still pay fees per trade** as before: `buy`, `sell`, `buy_v2`, `sell_v2`, `buy_exact_quote_in_v2` on Pump, and `buy`, `sell`, `buy_exact_quote_in` on PumpSwap. Old and new trades can be mixed on the same coin.+- The creator fee is treated the same for every kind of creator: a wallet, a fee sharing config or a holder rewards coin.++## Sweep instructions++Four permissionless instructions pay the waiting fees out. Anyone can call them; the `payer` only pays small rent costs (a token account for the destination if it is missing, and a rent top-up if the curve or pool still has an older layout). Calling a sweep when nothing is waiting is fine and does nothing.++| Program | Instruction | Pays out | To (`recipient`) |+| -------- | -------------------- | ---------------------------- | ------------------------------------------------------------------------------------------------------------------ |+| Pump | `sweep_protocol_fee` | `BondingCurve.protocol_fees` | One of the 8 normal fee recipients, or one of the 8 reserved fee recipients for a mayhem coin. See [Fee Recipients](../FEE_RECIPIENTS.md). |+| Pump | `sweep_creator_fee` | `BondingCurve.creator_fee` | The creator vault of `bonding_curve.creator`: Pump PDA `[b"creator-vault", bonding_curve.creator]`. |+| PumpSwap | `sweep_protocol_fee` | `Pool.protocol_fees` | One of the 8 protocol fee recipients, or a reserved one for a mayhem pool. Same addresses as above. |+| PumpSwap | `sweep_creator_fee` | `Pool.creator_fees` | The coin creator vault authority of `pool.coin_creator`: PumpSwap PDA `[b"creator_vault", pool.coin_creator]`. |++The destination is fixed by the instruction, so a sweep can only move the money to where a v2 (Pump) or v1 (PumpSwap) trade would have paid it. A bonding curve sweep also works after the coin has migrated: migration moves the reserves, not the waiting fees.++## Which sweep to call, and when++**Protocol fee.** pump.fun runs `sweep_protocol_fee` on both programs. Integrators do not need to call it.++**Creator fee.** A creator's fee is only in the creator vault after a `sweep_creator_fee`. Call it right before the existing claim or distribute instruction, in the same transaction:++1. Coin with a single creator (no sharing config):+ - Pump `sweep_creator_fee`, then [`collect_creator_fee_v2`](COLLECT_CREATOR_FEE.md).+ - If the coin has migrated: PumpSwap `sweep_creator_fee`, then [`collect_coin_creator_fee`](COLLECT_CREATOR_FEE.md).+2. Coin with a sharing config ([Creator Fee Sharing](CREATOR_FEE_SHARING.md)):+ - Pump `sweep_creator_fee` (and PumpSwap `sweep_creator_fee` if migrated), then `transfer_creator_fees_to_pump_v2` and `distribute_creator_fees_v2`.+3. Holder rewards coins: the same two sweeps. The creator fee lands in the holder rewards vault, and the usual [holder rewards](../HOLDER_REWARDS_README.md) flow pays it out.++These instructions refuse to run while a creator fee is still waiting, so a creator fee sweep must come first in the same transaction:++| Instruction | Program | Error if not swept |+| ---------------------------------------------------------------------- | --------- | ----------------------------------------- |+| `distribute_creator_fees` / `distribute_creator_fees_v2` | Pump | `CreatorFeesNotSwept` (6095) |+| `admin_cto` | Pump | `CreatorFeesNotSwept` (6095) |+| `create_fee_sharing_config` (through `migrate_bonding_curve_creator`) | Pump | `CreatorFeesNotSwept` (6095) |+| `admin_cto_pool` | PumpSwap | `CreatorFeesNotSwept` (6081) |+| `create_fee_sharing_config` (through `migrate_pool_coin_creator`) | PumpSwap | `CreatorFeesNotSwept` (6081) |+| `update_fee_shares` / `update_fee_shares_v2` | Pump Fees | `PoolCreatorFeesNotSwept` (6033) |++A short rule of thumb: **before you touch who the creator is, or pay the creator out, sweep the creator fee first** on the curve and, if the coin has migrated, on the pool.++## Accounts++### Pump `sweep_protocol_fee` and `sweep_creator_fee`++Both take the same 13 accounts.++| # | Account | Seeds / derivation | `init_if_needed` / SOL cost |+| --- | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------ |+| 1 | `payer` | Transaction signer. Pays the rent costs below. | - |+| 2 | `global` | Pump PDA: seeds `[b"global"]`. | - |+| 3 | `base_mint` | Base token mint of the coin. | - |+| 4 | `quote_mint` | Quote mint of the coin. For SOL-paired coins pass wrapped SOL: `So11111111111111111111111111111111111111112`. | - |+| 5 | `quote_token_program` | Token program of `quote_mint`. | - |+| 6 | `associated_token_program` | Associated Token Program: `ATokenGPvbdGVxr1b2hvZbsiqW5xWH25efTNsLJA8knL`. | - |+| 7 | `system_program` | System Program: `11111111111111111111111111111111`. | - |+| 8 | `bonding_curve` | Pump PDA: seeds `[b"bonding-curve", base_mint]`. Writable. | Rent top-up if the account still has an older layout. |+| 9 | `associated_quote_bonding_curve` | Associated token account for `quote_mint`, owned by `bonding_curve`. Writable. For SOL-paired coins pass the derived address; it is not used. | - |+| 10 | `recipient` | `sweep_protocol_fee`: a normal fee recipient (reserved one for mayhem coins). `sweep_creator_fee`: the creator vault PDA `[b"creator-vault", bonding_curve.creator]`. Writable. | `sweep_creator_fee` on a SOL-paired coin: rent top-up for the vault if needed. |+| 11 | `associated_quote_recipient` | Associated token account for `quote_mint`, owned by `recipient`. Writable. For SOL-paired coins pass the derived address; it is not used. | ATA rent if missing (token-paired coins). |+| 12 | `event_authority` | Pump PDA: seeds `[b"__event_authority"]`. | - |+| 13 | `program` | Pump program account. | - |++No instruction data.++### PumpSwap `sweep_protocol_fee` and `sweep_creator_fee`++Both take the same 12 accounts.++| # | Account | Seeds / derivation | `init_if_needed` / SOL cost |+| --- | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------- |+| 1 | `payer` | Transaction signer. Pays the rent costs below. | - |+| 2 | `global_config` | PumpSwap PDA: seeds `[b"global_config"]`. Address: `ADyA8hdefvWN2dbGGWFotbzWxrAvLW83WG6QCVXvJKqw`. | - |+| 3 | `pool` | The `Pool` account. Writable. | Rent top-up if the account still has an older layout. |+| 4 | `quote_mint` | `pool.quote_mint`. | - |+| 5 | `quote_token_program` | Token program of `quote_mint`. | - |+| 6 | `pool_quote_token_account` | `pool.pool_quote_token_account`. Writable. | - |+| 7 | `recipient` | `sweep_protocol_fee`: a protocol fee recipient (reserved one for mayhem pools). `sweep_creator_fee`: the coin creator vault authority PDA `[b"creator_vault", pool.coin_creator]`. | - |+| 8 | `recipient_token_account` | Associated token account for `quote_mint`, owned by `recipient`. Writable. | ATA rent if missing. |+| 9 | `system_program` | System Program: `11111111111111111111111111111111`. | - |+| 10 | `associated_token_program` | Associated Token Program: `ATokenGPvbdGVxr1b2hvZbsiqW5xWH25efTNsLJA8knL`. | - |+| 11 | `event_authority` | PumpSwap PDA: seeds `[b"__event_authority"]`. | - |+| 12 | `program` | PumpSwap program account. | - |++No instruction data.++## Events++- A trade that keeps its fee says so in its event: `TradeEvent.fee_recipient` (Pump v3) and `BuyEvent` / `SellEvent.protocol_fee_recipient` (PumpSwap v2) are the zero key `11111111111111111111111111111111`. The fee fields still carry the amounts charged. `creator_fee_unclaimed` is the creator fee waiting after the trade.+- A sweep emits `SweepBondingCurveFeeEvent` (Pump) or `SweepPoolFeeEvent` (PumpSwap) with `recipient`, `amount` and `bucket`: `0` for the protocol fee, `1` for the creator fee.++For indexers: fee income is in the trade events (when it is charged), payouts are in the sweep events (when it is paid). Do not count both as income.++## Account layout++`BondingCurve` and `Pool` have new fields appended at the end for the waiting fees. Accounts written before the upgrade are shorter; read the missing trailing fields as `0`, as with earlier appended fields. An old account grows on its first new-style trade or sweep (the trader or payer pays the small rent difference). Anyone can also grow it up front with the permissionless `extend_account` instruction on either program. A few write instructions on an account that has not grown yet fail until it does, for example PumpSwap `deposit` / `withdraw` on a pool that has not traded since the upgrade, so LPs on quiet pools should call `extend_account` on the pool first.++## Related++- [Virtual quote reserves and fees](../VIRTUAL_QUOTE_RESERVES_FEE_ADJUSTMENT.md): why the fees kept in a pool make `virtual_quote_reserves` negative.+- [Collect creator fee](COLLECT_CREATOR_FEE.md) and [Creator fee sharing](CREATOR_FEE_SHARING.md): the claim and distribute instructions a sweep comes before.++## SDKs++- TypeScript, Pump: [`@pump-fun/pump-sdk` 4.0.0](https://www.npmjs.com/package/@pump-fun/pump-sdk/v/4.0.0). `sweepProtocolFeeInstruction` and `sweepCreatorFeeInstruction` for the curve, `sweepPoolCreatorFeeInstruction` for the pool's creator fee. `OnlinePumpSdk.adminCtoInstructions` and `buildDistributeCreatorFeesInstructions` prepend the sweeps for you when a bucket is not empty. Event decoders: `decodeSweepBondingCurveFeeEvent` and `decodeSweepPoolFeeEventAmm`.+- TypeScript, PumpSwap: [`@pump-fun/pump-swap-sdk` 2.1.0](https://www.npmjs.com/package/@pump-fun/pump-swap-sdk/v/2.1.0). `sweepProtocolFeeInstruction` and `sweepCreatorFeeInstruction` for the pool, or `onlineSdk.sweepCreatorFeeInstruction(poolKey, payer)`.+- Rust: [`pump-rust-client` 0.4.0](https://crates.io/crates/pump-rust-client/0.4.0). `sweep_creator_fee_instruction` (curve) and `sweep_pool_creator_fee_instruction` (pool). `distribute_creator_fees_v2_instructions` prepends the curve sweep for you.+- IDL: [idl/pump.json](../../idl/pump.json) and [idl/pump_amm.json](../../idl/pump_amm.json).++## Synthetic Migration++The buy that empties a bonding curve can continue into the tokens that would go into the PumpSwap pool (see [Synthetic migration](../SYNTHETIC_MIGRATION.md)). That second part pays the bonding curve fee schedule like the first part: its protocol and creator fee are kept on the curve in the same `protocol_fees` / `creator_fee` fields and are paid out by the same sweeps, and its buyback part is paid in the trade. `PostCompleteBuyEvent` reports those amounts.diff --git a/docs/pumpfun-program/docs/instructions/TRADE_V3.md b/docs/pumpfun-program/docs/instructions/TRADE_V3.mdnew file mode 100644index 000000000..5adffa7d6--- /dev/null+++ b/docs/pumpfun-program/docs/instructions/TRADE_V3.md@@ -0,0 +1,109 @@+# Bonding Curve Trades V3++`buy_v3`, `buy_exact_quote_in_v3` and `sell_v3` do the same trades as `buy_v2`, `buy_exact_quote_in_v2` and `sell_v2`, with **17 accounts instead of 27 or 26**. Prices, slippage checks and fee amounts are the same. The only difference is where the fees go: a v3 trade keeps the protocol fee and the creator fee on the bonding curve instead of paying them out on every trade. See [Fee sweeps](SWEEP_FEES.md).++Use them for any coin paired with SOL, USDC or a pump coin. Mayhem coins work too. Cashback coins are the one exception: a v3 trade on a cashback coin fails with `CashbackCoinNotSupported` (6094), so keep using v2 for those.++The v2 and legacy instructions keep working unchanged. v2 and v3 trades can be mixed on the same coin.++## Why they are smaller++Compared with `buy_v2` / `sell_v2`, these accounts are gone:++- `fee_recipient` and `associated_quote_fee_recipient`: the protocol fee stays on the curve in `BondingCurve.protocol_fees`.+- `creator_vault`, `associated_creator_vault` and `sharing_config`: the creator fee stays on the curve in `BondingCurve.creator_fee`.+- `buyback_fee_recipient` and `associated_quote_buyback_fee_recipient` become one `buyback_fee_recipient` account. The buyback part of the protocol fee is still paid in the trade.+- `global_volume_accumulator`, `associated_user_volume_accumulator`, `associated_token_program` and `fee_program` are not needed. The fee schedule is read from the Pump Fees `fee_config` account directly.++## Accounts++All three instructions take the same 17 accounts, in this order.++| # | Account | Seeds / derivation | `init_if_needed` / SOL cost |+| --- | ------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------- |+| 1 | `global` | Pump PDA: seeds `[b"global"]`. | - |+| 2 | `base_mint` | Base token mint of the coin. | - |+| 3 | `quote_mint` | Quote mint of the coin. For SOL-paired coins pass wrapped SOL: `So11111111111111111111111111111111111111112`. | - |+| 4 | `base_token_program` | Token program of `base_mint`. Token-2022 (`TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb`) for `create_v2` coins, SPL Token for older coins. | - |+| 5 | `quote_token_program` | Token program of `quote_mint`. SPL Token for wrapped SOL and USDC. Token-2022 for most pump coins used as quote. | - |+| 6 | `bonding_curve` | Pump PDA: seeds `[b"bonding-curve", base_mint]`. | Small rent top-up if the account still has an older, shorter layout. Paid by `user`. |+| 7 | `associated_base_bonding_curve` | Associated token account for `base_mint`, owned by `bonding_curve`, using `base_token_program`. | - |+| 8 | `associated_quote_bonding_curve`| Associated token account for `quote_mint`, owned by `bonding_curve`, using `quote_token_program`. Already exists for token-paired coins (`create_v2` creates it). For SOL-paired coins pass the derived address too; it is not used and does not need to exist. | - |+| 9 | `user` | Transaction signer and trader. | - |+| 10 | `associated_base_user` | User's token account for `base_mint`. **Must exist.** The trade does not create it. | - |+| 11 | `associated_quote_user` | User's token account for `quote_mint`. **Must exist** for token-paired coins. For SOL-paired coins pass the user's wrapped SOL ATA address; it is not used and does not need to exist. | - |+| 12 | `user_volume_accumulator` | Pump PDA: seeds `[b"user_volume_accumulator", user]`. Created if missing, paid by `user`. | Rent for a 137-byte account if missing: 0.0018444 SOL |+| 13 | `fee_config` | Pump Fees PDA: seeds `[b"fee_config", pump_program_id]`. Address: `8Wf5TiAheLUqBrKXeYg2JtAFFMWtKdG2BSFgqUcPVwTt`. | - |+| 14 | `buyback_fee_recipient` | SOL-paired coins: one of the 8 buyback fee recipient wallets. Token-paired coins: that wallet's associated token account for `quote_mint`. See [Buyback fee recipient](#buyback-fee-recipient). | Never created by the trade. **Must exist.** |+| 15 | `system_program` | System Program: `11111111111111111111111111111111`. | - |+| 16 | `event_authority` | Pump PDA: seeds `[b"__event_authority"]`. | - |+| 17 | `program` | Pump program account. | - |++## Instruction Data++### `buy_v3`++| # | Argument | Type | Description / validation | Optional? |+| --- | -------------- | ------------ | ------------------------------------------------------------------------------------------------------------------------- | --------- |+| 1 | `amount` | `u64` | Base tokens to buy, in base token units. Must be greater than `0`. May be more than the curve has left: see [Synthetic migration](#synthetic-migration). | No |+| 2 | `max_sol_cost` | `u64` | Most quote the buyer will pay, including the protocol and creator fee, for the whole buy (both parts of a synthetic migration). In quote base units (lamports for SOL-paired coins). | No |+| 3 | `partial_fill` | `OptionBool` | Only used on mayhem coins, which get no synthetic migration: `[true]` buys what the curve has left and completes it; omitted or `[false]`, a buy for more than what is left fails with `NotEnoughTokensToBuy`. On every other coin a buy for more than what is left continues into the [synthetic migration](#synthetic-migration), whatever this flag says. May be left off the end of the instruction data. | Yes |++### `buy_exact_quote_in_v3`++| # | Argument | Type | Description / validation | Optional? |+| --- | -------------------- | ------------ | -------------------------------------------------------------------------------------------------------- | --------- |+| 1 | `spendable_quote_in` | `u64` | Exact quote amount to spend, including fees. In quote base units. May be more than the curve has left to sell: see [Synthetic migration](#synthetic-migration). | No |+| 2 | `min_tokens_out` | `u64` | Fewest base tokens the buyer accepts, counting both parts of a synthetic migration. | No |+| 3 | `partial_fill` | `OptionBool` | Only used on mayhem coins, which get no synthetic migration: `[true]` spends up to what the curve has left and skips `min_tokens_out`; omitted or `[false]`, a budget that would buy more than what is left fails with `NotEnoughTokensToBuy`. On every other coin such a budget continues into the [synthetic migration](#synthetic-migration). May be left off the end of the instruction data. | Yes |++### `sell_v3`++| # | Argument | Type | Description / validation | Optional? |+| --- | ---------------- | ----- | ---------------------------------------------------------------------------------------------- | --------- |+| 1 | `amount` | `u64` | Base tokens to sell, in base token units. Must be greater than `0`. | No |+| 2 | `min_sol_output` | `u64` | Least quote the seller accepts after the protocol and creator fee. In quote base units. | No |++## Buyback Fee Recipient++The buyback part of the protocol fee is paid in the trade, to one account. Pick any of the 8 buyback fee recipient wallets listed in [Fee Recipients](../FEE_RECIPIENTS.md).++- SOL-paired coin: pass the wallet itself.+- USDC-paired or pump-coin-paired coin: pass the wallet's associated token account for `quote_mint`, using `quote_token_program`.++The trade checks this account on every trade, even when the fee is `0`, and never creates it. For USDC the token accounts already exist. For a pump coin used as quote they may not, so add a `createAssociatedTokenAccountIdempotent` instruction for it before the trade when you are not sure. Anyone can pay the rent for it.++The normal and reserved fee recipients are not passed anymore: the protocol fee stays on the curve until it is swept.++## Events++A v3 trade emits the usual `TradeEvent` with `ix_name` set to `buy_v3`, `buy_exact_quote_in_v3` or `sell_v3`.++- `fee`, `creator_fee` and `buyback_fee` are the amounts charged, same as on v2.+- `fee_recipient` is the zero key (`11111111111111111111111111111111`). It means the protocol fee was kept on the curve, not paid out.+- `creator_fee_unclaimed` is the creator fee waiting on the curve after this trade.++The payouts show up later as `SweepBondingCurveFeeEvent`. See [Fee sweeps](SWEEP_FEES.md#events).++## Related++- [Buy V2](BUY.md) and [Sell V2](SELL.md): the previous interface, still supported.+- [PumpSwap Trades V2](PUMP_SWAP_TRADE_V2.md): the same change for pools after migration.+- [Multi-hop swap](MULTI_HOP_SWAP.md): trade through two or more pools and curves in one instruction.++## SDKs++- TypeScript: [`@pump-fun/pump-sdk` 4.0.0](https://www.npmjs.com/package/@pump-fun/pump-sdk/v/4.0.0). `buyV3Instructions`, `buyExactQuoteInV3Instructions` and `sellV3Instructions` build the trade and create the buyback recipient's token account first when it is missing. `getBuyV3InstructionRaw`, `getBuyExactQuoteInV3InstructionRaw` and `getSellV3InstructionRaw` return the bare instruction. Quote with `getBuyV3QuoteAmountFromTokenAmount` and `getBuyV3TokenAmountFromQuoteAmount`.+- Rust: [`pump-rust-client` 0.4.0](https://crates.io/crates/pump-rust-client/0.4.0). `buy_v3_instructions`, `buy_exact_quote_in_v3_instructions` and `sell_v3_instructions` prepend the buyback token account create; the single `*_instruction` versions do not. Quote with `buy_quote_bonding_curve_v3_sol_in` and `buy_quote_bonding_curve_v3_token_out`.+- IDL: [idl/pump.json](../../idl/pump.json), TypeScript types in [idl/pump.ts](https://github.com/pump-fun/pump-public-docs/blob/2293f9a66c654e9fe82dc5e8f4618538f24bb35f/idl/pump.ts).++## Synthetic Migration++The buy that empties the curve has no max size. A `buy_v3` or `buy_exact_quote_in_v3` that asks for more than the curve has left no longer fails: it takes what is left at the curve's price, completes the curve, and buys the rest from the tokens that would have gone into the PumpSwap pool, at the price that pool would charge. The migration then opens the pool where that buy stopped.++- `max_sol_cost` (`buy_v3`) and `min_tokens_out` (`buy_exact_quote_in_v3`) cover both parts.+- Only the buy that crosses the limit gets this. After it, no buy or sell is possible on the curve until the migration happens.+- Mayhem coins keep the old behaviour, controlled by `partial_fill`.+- Three events: `TradeEvent` (curve part), `CompleteEvent`, then `PostCompleteBuyEvent` (pool part).++Full details, including how to quote it: [Synthetic migration](../SYNTHETIC_MIGRATION.md).