x402agent/pump-fee-system

Fee System — Tiered Fees, Creator Fees & Protocol Fees

Implement and extend the Pump protocol's fee system: tiered protocol fees based on market cap, creator fee collection across two programs, and fee computation with ceiling division.

Context

The Pump protocol charges fees on every buy/sell transaction. Fees flow to protocol fee recipients and token creators. The fee system spans three programs and must handle tokens in both bonding curve and graduated (AMM) states.

Fee Types

| Fee | Recipient | When Charged | |-----|-----------|-------------| | Protocol fee | feeRecipients[] in Global | Every buy/sell | | Creator fee | Token creator's vault PDA | Every buy/sell (if creator is set) | | LP fee | Liquidity providers (AMM only) | Post-graduation trades |

Tiered Fee Calculation

When a FeeConfig exists, fees are market-cap-dependent:

function calculateFeeTier({ feeTiers, marketCap }): Fees {
  // Iterate tiers in REVERSE order
  for (let i = feeTiers.length - 1; i >= 0; i--) {
    if (marketCap >= feeTiers[i].marketCapLamportsThreshold) {
      return feeTiers[i].fees;
    }
  }
  return feeTiers[0].fees; // fallback to lowest tier
}

Fee Computation

function getFee({ global, feeConfig, mintSupply, bondingCurve, amount }): BN {
  const { protocolFeeBps, creatorFeeBps } = computeFeesBps(...);
  const protocolFee = ceilDiv(amount * protocolFeeBps, 10000);
  const creatorFee = hasCreator ? ceilDiv(amount * creatorFeeBps, 10000) : 0;
  return protocolFee + creatorFee;
}

Creator Vault Balance

Creator fees accumulate in PDAs:

• creatorVaultPda(creator) — Pump program vault
• ammCreatorVaultPda(creator) — PumpAMM program vault

Balance = total lamports - rent exemption minimum.

Error Classes

| Error | Condition | |-------|-----------| | NoShareholdersError | Empty shareholders array | | TooManyShareholdersError | More than 10 shareholders | | ZeroShareError | Shareholder has shareBps <= 0 | | InvalidShareTotalError | Shares don't sum to 10,000 bps | | DuplicateShareholderError | Duplicate addresses |

Patterns to Follow

• Use ceiling division (ceilDiv) for all fee calculations to prevent dust loss
• Always check both creator vaults (Pump + AMM) when querying balances
• Use transaction simulation (simulateTransaction) for read-only fee queries
• Creator fee is only charged when bondingCurve.creator != PublicKey.default or it's a new curve

Common Pitfalls

• Fee tiers must be iterated in reverse — the first match from the end is used
• computeFeesBps returns different results depending on whether feeConfig is null (legacy vs tiered)
• Creator fees are zero for tokens without a set creator
• getMinimumDistributableFee requires transaction simulation — it cannot be computed offline
• transferCreatorFeesToPump is only for graduated tokens — non-graduated tokens will fail