Creator Fees on the Genesis Bonding Curve

Creator fees are an optional per-swap fee on the Genesis Bonding Curve that accrue to a configured wallet on every buy and sell.

Summary

A creator fee is an optional per-swap fee on the Genesis Bonding Curve, applied to the SOL side of every buy and sell. Fees accrue in the bucket account (creatorFeeAccrued) rather than being transferred immediately — claim them in one call via the Metaplex API (recommended) or per-bucket with the on-chain instructions.

• Configuration — set creatorFeeWallet in the launch object at curve creation; defaults to the launching wallet if omitted
• Accrual — creatorFeeAccrued increments on every swap; fees are not transferred per-swap
• Recommended claim path — POST /v1/creator-rewards/claim (or claimCreatorRewards in the SDK) aggregates every bonding-curve and Raydium bucket for the wallet and returns ready-to-sign transactions
• Active curve claiming (manual) — claimBondingCurveCreatorFeeV2 collects accrued fees while the curve is live
• Post-graduation claiming (manual) — two-step: collectRaydiumCpmmFeesWithCreatorFeeV2 harvests LP fees from the Raydium pool into the Genesis bucket, then claimRaydiumCreatorFeeV2 transfers the bucket balance to the creator wallet

For how creator fees interact with swap pricing and the protocol swap fee, see Theory of Operation — Fee Structure.

Quick Start

This section gives the minimum steps to configure and claim creator fees via the Metaplex API (recommended) or the low-level on-chain instructions that cover the active curve and post-graduation Raydium phases.

Quick Reference

This table summarizes when to call each fee instruction, the accounts it requires, and its effect on the creator fee lifecycle.

Jump to: Configure at Launch · Redirect to Wallet · Agent PDA · Combine with First Buy · Check Accrued (Curve) · Claim via API · No-Rewards Case · Claim During Curve · Check Raydium Fees · Collect from Raydium · Claim After Graduation

1. Set creatorFeeWallet in the launch object when calling createAndRegisterLaunch
2. After launch, read bucket.creatorFeeAccrued to monitor accumulated fees
3. Call claimCreatorRewards via the API or SDK to claim across every bucket in a single call
4. For manual control during the active curve, call claimBondingCurveCreatorFeeV2 to collect accrued fees
5. For manual post-graduation claiming, call collectRaydiumCpmmFeesWithCreatorFeeV2 to harvest LP fees from the Raydium pool, then claimRaydiumCreatorFeeV2 to transfer the bucket balance to the creator wallet

Prerequisites

You must have the Genesis SDK, a configured Umi instance, and a funded Solana wallet.

• @metaplex-foundation/genesis SDK installed
• A Umi instance configured with your keypair identity — see Launching a Bonding Curve via the Metaplex API
• A funded Solana wallet for transaction fees

Configuring a Creator Fee at Launch

Creator fees are configured in the launch object passed to createAndRegisterLaunch (or createLaunch). The creatorFeeWallet field is optional — if omitted, the launching wallet receives all fees by default. For the full launch flow, see Launching a Bonding Curve via the Metaplex API.

Redirecting Creator Fees to a Specific Wallet

Set creatorFeeWallet to direct accrued fees to any wallet address other than the launching wallet.

1import { createAndRegisterLaunch } from '@metaplex-foundation/genesis/api';
2
3const result = await createAndRegisterLaunch(umi, {}, {
4  wallet: umi.identity.publicKey,
5  launchType: 'bondingCurve',
6  token: {
7    name: 'My Token',
8    symbol: 'MTK',
9    image: 'https://gateway.irys.xyz/your-image-id',
10  },
11  launch: {
12    creatorFeeWallet: 'FeeRecipientWalletAddress...',
13  },
14});

Agent Launches — Automatic PDA Routing

When launching on behalf of a Metaplex agent, the creator fee is automatically routed to the agent's PDA without setting creatorFeeWallet manually. For the full agent launch flow — Core execute wrapping and setToken association — see Create an Agent Token.

Combining Creator Fees with a First Buy

You can configure a creator fee wallet and a first buy together. The first buy is always fee-free — no protocol fee or creator fee applies to that initial purchase. All subsequent swaps pay the normal creator fee.

launch: {
  creatorFeeWallet: 'FeeRecipientWalletAddress...',
  firstBuyAmount: 0.5, // 0.5 SOL, fee-free for the first buyer
},

Checking Accrued Creator Fees

The creatorFeeAccrued field on the BondingCurveBucketV2 account tracks the total SOL accumulated since the last claim. Read it using fetchBondingCurveBucketV2:

1import {
2  findBondingCurveBucketV2Pda,
3  fetchBondingCurveBucketV2,
4} from '@metaplex-foundation/genesis';
5import { isSome, publicKey } from '@metaplex-foundation/umi';
6
7const genesisAccount = publicKey('YOUR_GENESIS_ACCOUNT_PUBKEY');
8const baseMint = publicKey('TOKEN_MINT_PUBKEY');
9
10const [bucketPda] = findBondingCurveBucketV2Pda(umi, {
11  genesisAccount,
12  bucketIndex: 0,
13});
14
15const bucket = await fetchBondingCurveBucketV2(umi, bucketPda);
16console.log('Creator fees accrued (lamports):', bucket.creatorFeeAccrued);
17console.log('Creator fees claimed to date (lamports):', bucket.creatorFeeClaimed);
18
19// Read the configured creator fee wallet from the bucket extension
20const creatorFeeExt = bucket.extensions.creatorFee;
21const creatorFeeWallet = isSome(creatorFeeExt) ? creatorFeeExt.value.wallet : null;
22console.log('Creator fee wallet:', creatorFeeWallet?.toString() ?? 'none configured');

Claiming via the Metaplex API (Recommended)

POST /v1/creator-rewards/claim claims every unclaimed bonding-curve and Raydium reward the wallet is entitled to in a single call. The endpoint returns base64-encoded Solana transactions that the wallet (or a designated payer) signs and submits. The JavaScript SDK exposes the same call as claimCreatorRewards from @metaplex-foundation/genesis.

1import { claimCreatorRewards } from '@metaplex-foundation/genesis'
2import { base58 } from '@metaplex-foundation/umi/serializers'
3import { createUmi } from '@metaplex-foundation/umi-bundle-defaults'
4import { keypairIdentity } from '@metaplex-foundation/umi'
5
6const umi = createUmi('https://api.mainnet-beta.solana.com')
7const keypair = umi.eddsa.createKeypairFromSecretKey(mySecretKeyBytes)
8umi.use(keypairIdentity(keypair))
9
10const result = await claimCreatorRewards(umi, {}, {
11  wallet: umi.identity.publicKey,
12  network: 'solana-mainnet',
13  // payer is optional — defaults to `wallet` on the server.
14  // Set it to have a different wallet cover rent and transaction fees.
15  // payer: umi.identity.publicKey,
16})
17
18for (const tx of result.transactions) {
19  const signed = await umi.identity.signTransaction(tx)
20  const signature = await umi.rpc.sendTransaction(signed, {
21    preflightCommitment: 'confirmed',
22  })
23  await umi.rpc.confirmTransaction(signature, {
24    strategy: { type: 'blockhash', ...result.blockhash },
25    commitment: 'confirmed',
26  })
27  console.log('Claimed:', base58.deserialize(signature)[0])
28}
29
30// Claimed: 5uGGYEMmjP2HpyFCvLPNpVDSQEBtUE3LR6ZQFqhJxQSh5FbKacSyN8nQmAJowuFs6BTCdwzoFyyJz8Y2hQx8kPxo
31// Claimed: 3TAroVovEap1ZEAJYq3WiDZoMK3GU3soCdrhvZJNg6b9EANqvWrVcDGNffm7mD8wvtpR7ynWQBcbrmz8AK6nrhfy

1# Claim creator rewards. Response contains base64-encoded transactions
2# the wallet (or payer) must sign and send.
3curl -X POST https://api.metaplex.com/v1/creator-rewards/claim \
4  -H "Content-Type: application/json" \
5  -d '{
6    "wallet": "CREATOR_FEE_WALLET_ADDRESS_HERE",
7    "network": "solana-mainnet"
8  }'
9
10# Add "payer" when the creator fee wallet does not hold SOL (e.g. an agent PDA):
11#   "payer": "PAYER_WALLET_ADDRESS_HERE"

The SDK returns deserialized Umi Transactions plus the blockhash they were built against. Always confirm each transaction against the returned blockhash — do not substitute a freshly-fetched one, or confirmation will race. See the full HTTP schema at Claim Creator Rewards (API).

Handling the No-Rewards Case

The endpoint returns HTTP 400 with { "error": { "message": "No rewards available to claim" } } when the wallet has nothing to claim — it does not return a success response with an empty transactions array. The SDK surfaces this as a GenesisApiError, so callers must catch it and branch on err.message (or err.statusCode === 400) rather than letting the error propagate.

1import {
2  claimCreatorRewards,
3  isGenesisApiError,
4  isGenesisApiNetworkError,
5} from '@metaplex-foundation/genesis'
6
7// Assumes umi is configured with a keypair identity.
8
9try {
10  const result = await claimCreatorRewards(umi, {}, {
11    wallet: umi.identity.publicKey,
12    network: 'solana-mainnet',
13  })
14  console.log(`Claimable transactions: ${result.transactions.length}`)
15} catch (err) {
16  if (isGenesisApiError(err)) {
17    // The API returns HTTP 400 with
18    //   { "error": { "message": "No rewards available to claim" } }
19    // when the wallet has no unclaimed creator rewards. Match on the message
20    // (or statusCode === 400) to handle this as a success case rather than a
21    // failure.
22    if (err.message === 'No rewards available to claim') {
23      console.log('Nothing to claim right now.')
24    } else {
25      console.error('API error:', err.statusCode, err.message)
26    }
27  } else if (isGenesisApiNetworkError(err)) {
28    console.error('Network error:', err.cause.message)
29  } else {
30    throw err
31  }
32}
33
34// Nothing to claim right now.

Claiming Creator Fees During the Active Curve

claimBondingCurveCreatorFeeV2 transfers all accrued creator fees from the bucket to the configured creator fee wallet. Call it at any time while the curve is active.

1import { claimBondingCurveCreatorFeeV2 } from '@metaplex-foundation/genesis';
2import { isSome } from '@metaplex-foundation/umi';
3
4// Read the creator fee wallet from the bucket extension before claiming.
5const creatorFeeExt = bucket.extensions.creatorFee;
6if (!isSome(creatorFeeExt)) throw new Error('No creator fee configured on this bucket');
7const creatorFeeWallet = creatorFeeExt.value.wallet;
8
9const result = await claimBondingCurveCreatorFeeV2(umi, {
10  genesisAccount,
11  bucket: bucketPda,
12  baseMint,
13  creatorFeeWallet,
14}).sendAndConfirm(umi);
15
16console.log('Creator fees claimed:', result.signature);

Claiming Creator Fees After Graduation

After the bonding curve graduates, liquidity migrates to a Raydium CPMM pool and creator fees continue to accrue from LP trading activity. Post-graduation fee collection is a two-step process: first collect accumulated LP trading fees from the Raydium pool into the Genesis RaydiumCpmmBucketV2 bucket, then claim the bucket balance to the creator wallet.

Checking Accrued Raydium Creator Fees

The RaydiumCpmmBucketV2 account exposes creatorFeeAccrued and creatorFeeClaimed fields analogous to those on BondingCurveBucketV2. Derive and fetch it using findRaydiumCpmmBucketV2Pda and fetchRaydiumCpmmBucketV2.

1import {
2  findRaydiumCpmmBucketV2Pda,
3  fetchRaydiumCpmmBucketV2,
4} from '@metaplex-foundation/genesis';
5import { isSome, publicKey } from '@metaplex-foundation/umi';
6
7const genesisAccount = publicKey('YOUR_GENESIS_ACCOUNT_PUBKEY');
8
9const [raydiumBucketPda] = findRaydiumCpmmBucketV2Pda(umi, {
10  genesisAccount,
11  bucketIndex: 0,
12});
13
14const raydiumBucket = await fetchRaydiumCpmmBucketV2(umi, raydiumBucketPda);
15const claimable = raydiumBucket.creatorFeeAccrued - raydiumBucket.creatorFeeClaimed;
16console.log('Claimable Raydium creator fees (lamports):', claimable);
17
18const creatorFeeExt = raydiumBucket.extensions.creatorFee;
19const creatorFeeWallet = isSome(creatorFeeExt) ? creatorFeeExt.value.wallet : null;
20console.log('Creator fee wallet:', creatorFeeWallet?.toString() ?? 'none configured');

Step 1 — Collect Fees from the Raydium CPMM Pool

collectRaydiumCpmmFeesWithCreatorFeeV2 harvests accumulated LP trading fees from the Raydium CPMM pool and credits them to the RaydiumCpmmBucketV2 bucket signer's token account, updating creatorFeeAccrued. This step must run before claiming — there is nothing to claim until fees have been collected from Raydium.

Use deriveRaydiumPDAsV2 to compute all required Raydium pool accounts from the base mint and bucket address. Pass creatorFee: true to select the creator-fee AMM config.

1import {
2  collectRaydiumCpmmFeesWithCreatorFeeV2,
3  deriveRaydiumPDAsV2,
4  findRaydiumCpmmBucketV2Pda,
5} from '@metaplex-foundation/genesis';
6import { publicKey } from '@metaplex-foundation/umi';
7
8const baseMint = publicKey('TOKEN_MINT_PUBKEY');
9const quoteMint = publicKey('So11111111111111111111111111111111111111112'); // wSOL
10
11const [raydiumBucketPda] = findRaydiumCpmmBucketV2Pda(umi, {
12  genesisAccount,
13  bucketIndex: 0,
14});
15
16const pdas = deriveRaydiumPDAsV2(umi, baseMint, raydiumBucketPda, {
17  quoteMint,
18  env: 'mainnet', // or 'devnet'
19  creatorFee: true,
20});
21
22await collectRaydiumCpmmFeesWithCreatorFeeV2(umi, {
23  baseMint,
24  quoteMint,
25  genesisAccount,
26  poolState: pdas.poolState,
27  raydiumCpmmBucket: raydiumBucketPda,
28  ammConfig: pdas.ammConfig,
29  poolAuthority: pdas.poolAuthority,
30  baseVault: pdas.baseVault,
31  quoteVault: pdas.quoteVault,
32  raydiumProgram: pdas.raydiumProgram,
33}).sendAndConfirm(umi);
34
35console.log('Raydium LP fees collected into Genesis bucket');

Step 2 — Claim Fees to the Creator Wallet

claimRaydiumCreatorFeeV2 transfers the balance accumulated in the RaydiumCpmmBucketV2 bucket to the configured creator fee wallet. Run this after collecting, or any time the bucket already holds an unclaimed balance from a previous collect.

1import {
2  claimRaydiumCreatorFeeV2,
3  fetchRaydiumCpmmBucketV2,
4  findRaydiumCpmmBucketV2Pda,
5} from '@metaplex-foundation/genesis';
6import { isSome, publicKey } from '@metaplex-foundation/umi';
7
8const [raydiumBucketPda] = findRaydiumCpmmBucketV2Pda(umi, {
9  genesisAccount,
10  bucketIndex: 0,
11});
12
13// Re-fetch after collecting to get the updated creatorFeeAccrued.
14const raydiumBucket = await fetchRaydiumCpmmBucketV2(umi, raydiumBucketPda);
15
16const creatorFeeExt = raydiumBucket.extensions.creatorFee;
17if (!isSome(creatorFeeExt)) throw new Error('No creator fee configured on this Raydium bucket');
18const creatorFeeWallet = creatorFeeExt.value.wallet;
19
20await claimRaydiumCreatorFeeV2(umi, {
21  genesisAccount: raydiumBucket.bucket.genesis,
22  bucket: raydiumBucketPda,
23  baseMint: raydiumBucket.bucket.baseMint,
24  quoteMint: raydiumBucket.bucket.quoteMint,
25  creatorFeeWallet,
26}).sendAndConfirm(umi);
27
28console.log('Raydium creator fees claimed to:', creatorFeeWallet.toString());

Combined Collect-and-Claim Flow

Collect and claim in a single transaction by chaining the two builders. If the pool has no uncollected fees and the bucket balance is zero, skip both instructions to avoid a no-op transaction.

1import {
2  collectRaydiumCpmmFeesWithCreatorFeeV2,
3  claimRaydiumCreatorFeeV2,
4  deriveRaydiumPDAsV2,
5  fetchRaydiumCpmmBucketV2,
6  findRaydiumCpmmBucketV2Pda,
7} from '@metaplex-foundation/genesis';
8import { isSome, publicKey, transactionBuilder } from '@metaplex-foundation/umi';
9
10const baseMint = publicKey('TOKEN_MINT_PUBKEY');
11const quoteMint = publicKey('So11111111111111111111111111111111111111112');
12const genesisAccount = publicKey('YOUR_GENESIS_ACCOUNT_PUBKEY');
13
14const [raydiumBucketPda] = findRaydiumCpmmBucketV2Pda(umi, {
15  genesisAccount,
16  bucketIndex: 0,
17});
18
19const raydiumBucket = await fetchRaydiumCpmmBucketV2(umi, raydiumBucketPda);
20
21const creatorFeeExt = raydiumBucket.extensions.creatorFee;
22if (!isSome(creatorFeeExt)) throw new Error('No creator fee configured');
23const creatorFeeWallet = creatorFeeExt.value.wallet;
24
25const pdas = deriveRaydiumPDAsV2(umi, baseMint, raydiumBucketPda, {
26  quoteMint,
27  env: 'mainnet', // or 'devnet'
28  creatorFee: true,
29});
30
31await transactionBuilder()
32  .add(collectRaydiumCpmmFeesWithCreatorFeeV2(umi, {
33    baseMint,
34    quoteMint,
35    genesisAccount,
36    poolState: pdas.poolState,
37    raydiumCpmmBucket: raydiumBucketPda,
38    ammConfig: pdas.ammConfig,
39    poolAuthority: pdas.poolAuthority,
40    baseVault: pdas.baseVault,
41    quoteVault: pdas.quoteVault,
42    raydiumProgram: pdas.raydiumProgram,
43  }))
44  .add(claimRaydiumCreatorFeeV2(umi, {
45    genesisAccount,
46    bucket: raydiumBucketPda,
47    baseMint,
48    quoteMint,
49    creatorFeeWallet,
50  }))
51  .sendAndConfirm(umi);
52
53console.log('Raydium creator fees collected and claimed to:', creatorFeeWallet.toString());

Notes

These caveats cover fee timing, the recommended API claim path, permissionless on-chain claiming, the two-step post-graduation flow, and first-buy fee waivers.

• Creator fees accrue in the bucket (creatorFeeAccrued) on each swap, not transferred immediately — explicitly claim them via the API/SDK or the on-chain instructions; creatorFeeClaimed tracks the cumulative total claimed to date
• claimCreatorRewards (API/SDK) aggregates every eligible bonding-curve and Raydium bucket for a wallet into a single call; when there is nothing to claim it returns HTTP 400 with "No rewards available to claim" rather than an empty transactions array
• The on-chain claim instructions (claimBondingCurveCreatorFeeV2, collectRaydiumCpmmFeesWithCreatorFeeV2, claimRaydiumCreatorFeeV2) are permissionless: any wallet can trigger them, but the SOL always goes to the configured creator fee wallet, not the caller
• Post-graduation fees require two steps in order: collectRaydiumCpmmFeesWithCreatorFeeV2 (harvest from Raydium pool → Genesis bucket), then claimRaydiumCreatorFeeV2 (bucket → creator wallet); both can be combined in a single transaction, and the API path wraps both for you
• creatorFeeAccrued and creatorFeeClaimed exist on both BondingCurveBucketV2 (active curve) and RaydiumCpmmBucketV2 (post-graduation); use fetchBondingCurveBucketV2 and fetchRaydiumCpmmBucketV2 respectively
• creatorFeeWallet defaults to the launching wallet if not set; it cannot be changed after the curve is created
• The first buy mechanism waives all fees (protocol and creator) for the designated initial purchase only; all subsequent swaps pay the normal creator fee
• Creator fees apply to the SOL side of every swap regardless of direction (buy or sell); they do not compound with the protocol swap fee
• For current fee rates, see the Genesis Protocol Fees page
• For swap-side context — reading bucket state, computing quotes, and executing trades — see Bonding Curve Swap Integration

FAQ

What is the default creator fee wallet if creatorFeeWallet is not set?

The default creator fee wallet is the launching wallet — the wallet that signed the createLaunch call. Set creatorFeeWallet explicitly in the launch object to redirect fees to any other address.

Are creator fees transferred on every swap?

No. Creator fees are accrued in the bucket (creatorFeeAccrued) on each swap but are not transferred immediately. Call claimCreatorRewards via the API or SDK to collect across every bucket in a single call, or use the on-chain instructions (claimBondingCurveCreatorFeeV2 during the active curve; collectRaydiumCpmmFeesWithCreatorFeeV2 followed by claimRaydiumCreatorFeeV2 after graduation) for lower-level control.

Should I use the API or the on-chain claim instructions?

Use the API (claimCreatorRewards) for everyday claiming — it aggregates every bonding-curve and Raydium bucket the wallet is entitled to into one call and returns ready-to-sign transactions. Use the per-bucket on-chain instructions (claimBondingCurveCreatorFeeV2, collectRaydiumCpmmFeesWithCreatorFeeV2, claimRaydiumCreatorFeeV2) when you need to target a specific bucket, craft the transaction yourself, or run without network access to the Metaplex API.

What happens when there are no rewards to claim?

The claimCreatorRewards endpoint returns HTTP 400 with {"error":{"message":"No rewards available to claim"}}. The SDK surfaces this as a GenesisApiError. Treat this as a non-exceptional outcome — check err.message (or err.statusCode === 400) and branch on it rather than letting the error propagate. See Handling the No-Rewards Case.

What is the optional payer field for?

The payer covers transaction fees and any rent on the returned claim transactions. It defaults to the wallet being claimed for. Set it to a different address when the creator fee wallet does not hold SOL (for example, an agent PDA or a cold wallet). The payer must sign the returned transactions; the creator fee recipient still receives the claimed SOL.

Can anyone call claimBondingCurveCreatorFeeV2 or claimRaydiumCreatorFeeV2?

Yes. All three permissionless fee instructions span both the active-curve and post-graduation phases — collectRaydiumCpmmFeesWithCreatorFeeV2 and claimBondingCurveCreatorFeeV2 (active curve), and claimRaydiumCreatorFeeV2 (post-graduation). Any wallet can trigger them, but the SOL is always sent to the configured creator fee wallet, not the caller.

What is the difference between collectRaydiumCpmmFeesWithCreatorFeeV2 and claimRaydiumCreatorFeeV2?

collectRaydiumCpmmFeesWithCreatorFeeV2 pulls accumulated LP trading fees from the Raydium CPMM pool into the Genesis RaydiumCpmmBucketV2 bucket — this updates creatorFeeAccrued on the bucket. claimRaydiumCreatorFeeV2 then transfers that bucket balance to the creator fee wallet. You must run collect before claim; without a collect, there is no bucket balance to claim.

Why is my creatorFeeAccrued on the Raydium bucket zero even though the pool is active?

creatorFeeAccrued on RaydiumCpmmBucketV2 only reflects fees that have been collected from Raydium into the Genesis bucket via collectRaydiumCpmmFeesWithCreatorFeeV2. LP trading fees accumulate inside the Raydium pool state first — they do not appear in the Genesis bucket until you run the collect instruction.

Does the first buy pay creator fees?

No. When a first buy is configured, all fees — protocol swap fee and creator fee — are waived for that one initial purchase. All subsequent swaps pay the normal creator fee.

How do I check how much creator fee has accrued?

During the active curve, read the creatorFeeAccrued field from BondingCurveBucketV2 using fetchBondingCurveBucketV2. After graduation, read creatorFeeAccrued from RaydiumCpmmBucketV2 using fetchRaydiumCpmmBucketV2. See Checking Accrued Creator Fees and Checking Accrued Raydium Creator Fees.

Can I change the creator fee wallet after launch?

No. The creator fee wallet is set at curve creation and cannot be changed after the curve is live.