Launch Pool | Metaplex CLI

What You'll Do

Run the full launch pool lifecycle from the CLI:

Add a launch pool bucket with allocation and time windows
Configure optional penalties, vesting, and allowlists
Deposit, withdraw, transition, and claim tokens

Summary

A launch pool collects deposits during a window and distributes tokens proportionally. This page covers the full launch pool lifecycle — from creating the bucket to claiming tokens.

Distribution: Proportional — your share of deposits determines your share of tokens
Commands: bucket add-launch-pool, deposit, withdraw, transition, claim, refund
Optional features: Soft cap, minimum threshold, end behaviors, deposit/withdraw penalties, bonus schedules, claim vesting, allowlists
Quote token: Wrapped SOL by default — wrap SOL before depositing

This page covers launch pool buckets only. Presale and unlocked buckets, Genesis account creation and finalization are covered on their own CLI pages.

Jump to: Add Bucket · Soft Cap · Deposit · Withdraw · Transition · Claim · Refund · Full Lifecycle · Common Errors · FAQ

Add Launch Pool Bucket

The mplx genesis bucket add-launch-pool command adds a launch pool bucket to a Genesis account.

Add a launch pool bucket

mplx genesis bucket add-launch-pool <GENESIS_ADDRESS> \
  --allocation 500000000000000 \
  --depositStart 1704067200 \
  --depositEnd 1704153600 \
  --claimStart 1704153601 \
  --claimEnd 1735689600

Options

Flag	Short	Description	Required
`--allocation <string>`	`-a`	Base token allocation in base units	Yes
`--depositStart <string>`		Unix timestamp when deposits open	Yes
`--depositEnd <string>`		Unix timestamp when deposits close	Yes
`--claimStart <string>`		Unix timestamp when claims open	Yes
`--claimEnd <string>`		Unix timestamp when claims close	Yes
`--bucketIndex <integer>`	`-b`	Bucket index (default: 0)	No
`--endBehavior <string>`		Format: `<destinationBucketAddress>:<percentageBps>` where `10000` = 100%. Can be specified multiple times	No
`--minimumDeposit <string>`		Minimum deposit per transaction in base units	No
`--depositLimit <string>`		Maximum deposit per user in base units	No
`--minimumQuoteTokenThreshold <string>`		Floor: minimum total quote tokens required for the bucket to succeed	No
`--softCap <string>`		Ceiling: maximum total quote tokens the bucket keeps. Deposits above this are refunded pro-rata	No
`--depositPenalty <json>`		Penalty schedule JSON	No
`--withdrawPenalty <json>`		Withdraw penalty schedule JSON (same format as depositPenalty)	No
`--bonusSchedule <json>`		Bonus schedule JSON	No
`--claimSchedule <json>`		Claim vesting schedule JSON	No
`--allowlist <json>`		Allowlist configuration JSON	No

JSON Option Formats

Penalty schedule (deposit or withdraw):

Penalty schedule format

{"slopeBps":0,"interceptBps":200,"maxBps":200,"startTime":0,"endTime":0}

Bonus schedule:

Bonus schedule format

{"slopeBps":0,"interceptBps":0,"maxBps":0,"startTime":0,"endTime":0}

Claim vesting schedule:

Claim schedule format

{"startTime":0,"endTime":0,"period":0,"cliffTime":0,"cliffAmountBps":0}

Allowlist:

Allowlist format

{"merkleTreeHeight":10,"merkleRoot":"<hex>","endTime":0,"quoteCap":0}

Examples

Basic launch pool:

Basic launch pool

mplx genesis bucket add-launch-pool <GENESIS_ADDRESS> \
  --allocation 500000000000000 \
  --depositStart 1704067200 \
  --depositEnd 1704153600 \
  --claimStart 1704153601 \
  --claimEnd 1735689600

With end behavior and minimum deposit:

With end behavior

mplx genesis bucket add-launch-pool <GENESIS_ADDRESS> \
  --allocation 500000000000000 \
  --depositStart 1704067200 \
  --depositEnd 1704153600 \
  --claimStart 1704153601 \
  --claimEnd 1735689600 \
  --endBehavior "<DESTINATION_BUCKET_ADDRESS>:10000" \
  --minimumDeposit 100000000

With claim vesting:

With claim vesting

mplx genesis bucket add-launch-pool <GENESIS_ADDRESS> \
  --allocation 500000000000000 \
  --depositStart 1704067200 \
  --depositEnd 1704153600 \
  --claimStart 1704153601 \
  --claimEnd 1735689600 \
  --claimSchedule '{"startTime":1704153601,"endTime":1735689600,"period":86400,"cliffTime":1704240000,"cliffAmountBps":1000}'

With a floor and a ceiling:

With minimum threshold and soft cap

mplx genesis bucket add-launch-pool <GENESIS_ADDRESS> \
  --allocation 500000000000000 \
  --depositStart 1704067200 \
  --depositEnd 1704153600 \
  --claimStart 1704153601 \
  --claimEnd 1735689600 \
  --minimumQuoteTokenThreshold 10000000000 \
  --softCap 100000000000

Soft Cap and Minimum Threshold

The --softCap flag caps the quote tokens a launch pool keeps, and --minimumQuoteTokenThreshold sets the minimum it must raise to succeed. Both are optional, both are denominated in quote token quantum units (lamports for wrapped SOL), and they can be used together.

Flag	Role	Effect when breached
`--minimumQuoteTokenThreshold`	Floor	Launch fails; every depositor can take a full refund
`--softCap`	Ceiling	Launch still succeeds; the excess above the cap is refunded pro-rata

A soft cap does not reject deposits at the cap. Deposits continue to be accepted for the whole window, the full base token allocation is still distributed proportionally, and only the excess quote tokens are returned. The effective price is therefore capped at softCap / allocation no matter how far deposits overshoot.

--softCap must be greater than zero and greater than or equal to --minimumQuoteTokenThreshold. The CLI checks both before sending the transaction, so a misconfiguration fails immediately rather than returning InvalidSoftCap or SoftCapBelowThreshold from the program.

For the underlying protocol behaviour, including the pro-rata refund math and how a soft cap affects Raydium graduation pricing, see Launch Pool Soft Cap.

Deposit

The mplx genesis deposit command deposits quote tokens into a launch pool bucket during the deposit window. If using SOL as the quote token, wrap it first.

Deposit into launch pool

mplx genesis deposit <GENESIS_ADDRESS> --amount 10000000000 --bucketIndex 0

Options

Flag	Short	Description	Required
`--amount <string>`	`-a`	Amount of quote tokens in base units (e.g. lamports)	Yes
`--bucketIndex <integer>`	`-b`	Index of the launch pool bucket (default: 0)	No

Examples

Wrap SOL and deposit 10 SOL:

Wrap and deposit

mplx toolbox sol wrap 10
mplx genesis deposit <GENESIS_ADDRESS> --amount 10000000000 --bucketIndex 0

Withdraw

The mplx genesis withdraw command withdraws quote tokens from a launch pool bucket. Only available during the deposit period.

Withdraw from launch pool

mplx genesis withdraw <GENESIS_ADDRESS> --amount 5000000000 --bucketIndex 0

Options

Flag	Short	Description	Required
`--amount <string>`	`-a`	Amount of quote tokens to withdraw in base units	Yes
`--bucketIndex <integer>`	`-b`	Index of the launch pool bucket (default: 0)	No

Transition

The mplx genesis transition command executes end behaviors after the deposit period closes, moving collected quote tokens to destination buckets.

Transition end behaviors

mplx genesis transition <GENESIS_ADDRESS> --bucketIndex 0

Options

Flag	Short	Description	Required
`--bucketIndex <integer>`	`-b`	Index of the launch pool bucket	Yes

Notes

Must be called after the deposit period ends
Only needed if the bucket has end behaviors configured

Claim

The mplx genesis claim command claims base tokens from a launch pool bucket. Users receive tokens proportional to their deposit.

Claim from launch pool

mplx genesis claim <GENESIS_ADDRESS> --bucketIndex 0

Options

Flag	Short	Description	Required
`--bucketIndex <integer>`	`-b`	Index of the launch pool bucket (default: 0)	No
`--recipient <string>`		Recipient address for claimed tokens (default: signer)	No

Examples

Claim to your own wallet:

Claim to self

mplx genesis claim <GENESIS_ADDRESS> --bucketIndex 0

Claim to a different wallet:

Claim to another wallet

mplx genesis claim <GENESIS_ADDRESS> --bucketIndex 0 --recipient <WALLET_ADDRESS>

Refund

The mplx genesis refund command returns quote tokens to a depositor after the deposit window closes. It takes no amount flag — the program derives the refundable amount.

Refund a launch pool deposit

mplx genesis refund <GENESIS_ADDRESS> --bucketIndex 0

Refunds are only available in two cases, and the command reports which one applied:

Case	Refund	Effect on tokens
Launch missed `--minimumQuoteTokenThreshold`	Full deposit	No tokens were claimable
Launch exceeded `--softCap`	Excess above the cap only	Token allocation unaffected

Options

Flag	Short	Description	Required
`--bucketIndex <integer>`	`-b`	Index of the launch pool bucket (default: 0)	No
`--recipient <string>`		Depositor being refunded (default: signer)	No

Notes

Only the payer must sign, so a refund can be cranked on another wallet's behalf with --recipient.
No fee or penalty is applied to a refund.
An excess refund can be run before or after mplx genesis claim — the order does not matter.
Each deposit can only be refunded once.
If the pool met its floor and stayed under its cap, the command reports that the pool is not refundable rather than sending a transaction.

Full Lifecycle Example

Complete launch pool lifecycle

# 1. Create the Genesis account
mplx genesis create \
  --name "My Token" \
  --symbol "MTK" \
  --totalSupply 1000000000000000 \
  --decimals 9

# (copy GENESIS_ADDRESS from output)
GENESIS=<GENESIS_ADDRESS>

# 2. Timestamps
NOW=$(date +%s)
DEPOSIT_END=$((NOW + 86400))
CLAIM_START=$((DEPOSIT_END + 1))
CLAIM_END=$((NOW + 31536000))

# 3. Add a launch pool bucket with end behavior
mplx genesis bucket add-launch-pool $GENESIS \
  --allocation 500000000000000 \
  --depositStart $NOW \
  --depositEnd $DEPOSIT_END \
  --claimStart $CLAIM_START \
  --claimEnd $CLAIM_END \
  --endBehavior "<UNLOCKED_BUCKET_ADDRESS>:10000"

# 4. Add an unlocked bucket to receive SOL
mplx genesis bucket add-unlocked $GENESIS \
  --recipient $(solana address) \
  --claimStart $CLAIM_START \
  --allocation 0

# 5. Finalize
mplx genesis finalize $GENESIS

# 6. Wrap SOL and deposit
mplx toolbox sol wrap 10
mplx genesis deposit $GENESIS --amount 10000000000 --bucketIndex 0

# 7. After deposit period, transition
mplx genesis transition $GENESIS --bucketIndex 0

# 8. Claim tokens
mplx genesis claim $GENESIS --bucketIndex 0

# 9. Revoke mint authority
mplx genesis revoke $GENESIS --revokeMint

Common Errors

Error	Cause	Fix
Deposit period not active	Current time is outside `depositStart`–`depositEnd`	Check timestamps with `genesis bucket fetch`
Claim period not active	Claiming before `claimStart`	Wait until after the claim start timestamp
Withdrawal period ended	Trying to withdraw after deposit window closed	Withdrawals are only available during the deposit period
No wrapped SOL	Depositing native SOL instead of wrapped	Run `mplx toolbox sol wrap <amount>` first
Below minimum deposit	Deposit amount is less than `minimumDeposit`	Increase the deposit amount to meet the minimum
Exceeds deposit limit	User's total deposits exceed `depositLimit`	Reduce the deposit amount — you've hit the per-user cap
End behavior not configured	Running `transition` on a bucket without end behaviors	Transition is only needed for buckets with `--endBehavior`
Deposit period not ended	Running `transition` before deposits close	Wait until after `depositEnd` timestamp
`"softCap" must be greater than zero`	Passed `--softCap 0`	Omit the flag entirely to leave the launch uncapped
`"softCap" must be greater than or equal to "minimumQuoteTokenThreshold"`	Ceiling set below the floor	Raise `--softCap` or lower `--minimumQuoteTokenThreshold`
Launch pool is not refundable	Running `refund` on a pool that met its floor and stayed under its cap	Refunds only apply to a failed threshold or an exceeded soft cap
Deposit already refunded	Running `refund` twice for the same depositor	Each deposit can only be refunded once
No deposit found	Running `refund` or `claim` for a wallet that never deposited	Check the address passed to `--recipient`

FAQ

How are tokens distributed in a launch pool? Tokens are distributed proportionally. If you deposited 10% of the total quote tokens in the pool, you receive 10% of the bucket's base token allocation.

Can I withdraw after depositing? Yes, but only during the deposit period. After the deposit window closes, withdrawals are no longer possible.

What are end behaviors? End behaviors forward collected quote tokens from a launch pool to destination buckets (usually unlocked buckets) after the deposit period ends. You must call genesis transition to execute them.

What is a claim schedule? A claim schedule adds vesting to token claims. Instead of receiving all tokens at once, they are released gradually based on the configured period, cliffTime, and cliffAmountBps.

What happens if minimumQuoteTokenThreshold is not met? If the total deposits don't reach the threshold, the bucket does not succeed and depositors reclaim their full deposit with mplx genesis refund.

What does the softCap flag do? --softCap caps the quote tokens a launch pool keeps. Deposits above the cap are still accepted and the launch still succeeds, but the excess is refunded pro-rata with mplx genesis refund. Token allocation is unaffected.

What is the difference between softCap and minimumQuoteTokenThreshold? --softCap is a ceiling and never causes a launch to fail. --minimumQuoteTokenThreshold is a floor — if deposits fall below it the launch fails and depositors can take a full refund. They can be used together, and --softCap must be greater than or equal to --minimumQuoteTokenThreshold.

When can the refund command be used? Only after the deposit window closes, and only when the launch missed its minimum quote token threshold or exceeded its soft cap. In any other case the command reports that the pool is not refundable.

Can I split end behaviors across multiple destinations? Yes. Specify --endBehavior multiple times with different destination addresses and percentages (in basis points, totaling 10000).

Glossary

Term	Definition
Launch Pool	Bucket type that distributes tokens proportionally based on deposit share
End Behavior	Rules forwarding collected quote tokens to destination buckets after deposits close
Transition	The command that executes end behaviors — must be called explicitly after the deposit period
Claim Schedule	Vesting configuration controlling gradual token release over time
Deposit Penalty	Fee applied to deposits, configured as basis points with optional time-based slope
Withdraw Penalty	Fee applied to withdrawals during the deposit period
Bonus Schedule	Extra token allocation for early or specific-timing deposits
Allowlist	Merkle-tree-based access control limiting who can deposit
Soft Cap	Ceiling on the quote tokens a launch pool keeps; the excess is refunded pro-rata
Minimum Quote Token Threshold	Floor below which a launch pool fails and full refunds open
Oversubscription	State where total deposits exceed the configured soft cap
Refund	Return of a deposit, in full when the floor was missed or excess-only when the cap was exceeded
Basis Points (bps)	1/100th of a percent — 10000 bps = 100%, 100 bps = 1%