SDK
JavaScript SDK
Last updated January 31, 2026
API reference for the Genesis JavaScript SDK. For complete tutorials, see Launch Pool or Presale.
NPM Package
@metaplex-foundation/genesis
TypeDoc
Auto-generated API docs
Installation
npm install @metaplex-foundation/genesis @metaplex-foundation/umi \
@metaplex-foundation/umi-bundle-defaults @metaplex-foundation/mpl-toolbox \
@metaplex-foundation/mpl-token-metadata
Setup
import { createUmi } from '@metaplex-foundation/umi-bundle-defaults';
import { genesis } from '@metaplex-foundation/genesis';
import { mplTokenMetadata } from '@metaplex-foundation/mpl-token-metadata';
const umi = createUmi('https://api.mainnet-beta.solana.com')
.use(genesis())
.use(mplTokenMetadata());
For complete implementation examples, see Launch Pool or Presale.
Instructions Reference
Core
| Function | Description |
|---|---|
| initializeV2() | Create Genesis Account and mint token |
| finalizeV2() | Lock configuration, activate launch |
Buckets
| Function | Description |
|---|---|
| addLaunchPoolBucketV2() | Add proportional distribution bucket |
| addPresaleBucketV2() | Add fixed-price sale bucket |
| addUnlockedBucketV2() | Add treasury/recipient bucket |
Launch Pool Operations
| Function | Description |
|---|---|
| depositLaunchPoolV2() | Deposit SOL into Launch Pool |
| withdrawLaunchPoolV2() | Withdraw SOL (during deposit period) |
| claimLaunchPoolV2() | Claim tokens (after deposit period) |
Presale Operations
| Function | Description |
|---|---|
| depositPresaleV2() | Deposit SOL into Presale |
| claimPresaleV2() | Claim tokens (after deposit period) |
Admin
| Function | Description |
|---|---|
| transitionV2() | Execute end behaviors |
| revokeMintAuthorityV2() | Permanently revoke mint authority |
| revokeFreezeAuthorityV2() | Permanently revoke freeze authority |
Function Signatures
initializeV2
await initializeV2(umi, {
baseMint, // Signer - new token keypair
quoteMint, // PublicKey - deposit token (wSOL)
fundingMode, // number - use 0
totalSupplyBaseToken, // bigint - supply with decimals
name, // string - token name
symbol, // string - token symbol
uri, // string - metadata URI
}).sendAndConfirm(umi);
finalizeV2
await finalizeV2(umi, {
baseMint, // PublicKey
genesisAccount, // PublicKey
}).sendAndConfirm(umi);
addLaunchPoolBucketV2
await addLaunchPoolBucketV2(umi, {
genesisAccount, // PublicKey
baseMint, // PublicKey
baseTokenAllocation, // bigint - tokens for this bucket
depositStartCondition, // TimeCondition
depositEndCondition, // TimeCondition
claimStartCondition, // TimeCondition
claimEndCondition, // TimeCondition
minimumDepositAmount, // bigint | null
endBehaviors, // EndBehavior[]
}).sendAndConfirm(umi);
addPresaleBucketV2
await addPresaleBucketV2(umi, {
genesisAccount, // PublicKey
baseMint, // PublicKey
baseTokenAllocation, // bigint
allocationQuoteTokenCap, // bigint - SOL cap (sets price)
depositStartCondition, // TimeCondition
depositEndCondition, // TimeCondition
claimStartCondition, // TimeCondition
claimEndCondition, // TimeCondition
minimumDepositAmount, // bigint | null
depositLimit, // bigint | null - max per user
endBehaviors, // EndBehavior[]
}).sendAndConfirm(umi);
addUnlockedBucketV2
await addUnlockedBucketV2(umi, {
genesisAccount, // PublicKey
baseMint, // PublicKey
baseTokenAllocation, // bigint - usually 0n
recipient, // PublicKey - who can claim
claimStartCondition, // TimeCondition
claimEndCondition, // TimeCondition
backendSigner, // null
}).sendAndConfirm(umi);
depositLaunchPoolV2
await depositLaunchPoolV2(umi, {
genesisAccount, // PublicKey
bucket, // PublicKey
baseMint, // PublicKey
amountQuoteToken, // bigint - lamports
}).sendAndConfirm(umi);
depositPresaleV2
await depositPresaleV2(umi, {
genesisAccount, // PublicKey
bucket, // PublicKey
baseMint, // PublicKey
amountQuoteToken, // bigint - lamports
}).sendAndConfirm(umi);
withdrawLaunchPoolV2
await withdrawLaunchPoolV2(umi, {
genesisAccount, // PublicKey
bucket, // PublicKey
baseMint, // PublicKey
amountQuoteToken, // bigint - lamports
}).sendAndConfirm(umi);
claimLaunchPoolV2
await claimLaunchPoolV2(umi, {
genesisAccount, // PublicKey
bucket, // PublicKey
baseMint, // PublicKey
recipient, // PublicKey
}).sendAndConfirm(umi);
claimPresaleV2
await claimPresaleV2(umi, {
genesisAccount, // PublicKey
bucket, // PublicKey
baseMint, // PublicKey
recipient, // PublicKey
}).sendAndConfirm(umi);
transitionV2
await transitionV2(umi, {
genesisAccount, // PublicKey
primaryBucket, // PublicKey
baseMint, // PublicKey
})
.addRemainingAccounts([/* destination accounts */])
.sendAndConfirm(umi);
revokeMintAuthorityV2
await revokeMintAuthorityV2(umi, {
baseMint, // PublicKey
}).sendAndConfirm(umi);
revokeFreezeAuthorityV2
await revokeFreezeAuthorityV2(umi, {
baseMint, // PublicKey
}).sendAndConfirm(umi);
PDA Helpers
| Function | Seeds |
|---|---|
| findGenesisAccountV2Pda() | baseMint, genesisIndex |
| findLaunchPoolBucketV2Pda() | genesisAccount, bucketIndex |
| findPresaleBucketV2Pda() | genesisAccount, bucketIndex |
| findUnlockedBucketV2Pda() | genesisAccount, bucketIndex |
| findLaunchPoolDepositV2Pda() | bucket, recipient |
| findPresaleDepositV2Pda() | bucket, recipient |
const [genesisAccountPda] = findGenesisAccountV2Pda(umi, { baseMint: mint.publicKey, genesisIndex: 0 });
const [bucketPda] = findLaunchPoolBucketV2Pda(umi, { genesisAccount: genesisAccountPda, bucketIndex: 0 });
const [depositPda] = findLaunchPoolDepositV2Pda(umi, { bucket: bucketPda, recipient: wallet });
Fetch Functions
| Function | Returns |
|---|---|
| fetchLaunchPoolBucketV2() | Bucket state (throws if missing) |
| safeFetchLaunchPoolBucketV2() | Bucket state or null |
| fetchPresaleBucketV2() | Bucket state (throws if missing) |
| safeFetchPresaleBucketV2() | Bucket state or null |
| fetchLaunchPoolDepositV2() | Deposit state (throws if missing) |
| safeFetchLaunchPoolDepositV2() | Deposit state or null |
| fetchPresaleDepositV2() | Deposit state (throws if missing) |
| safeFetchPresaleDepositV2() | Deposit state or null |
const bucket = await fetchLaunchPoolBucketV2(umi, bucketPda);
const deposit = await safeFetchLaunchPoolDepositV2(umi, depositPda); // null if not found
Bucket state fields: quoteTokenDepositTotal, depositCount, claimCount, bucket.baseTokenAllocation
Deposit state fields: amountQuoteToken, claimed
Types
TimeCondition
{
__kind: 'TimeAbsolute',
padding: Array(47).fill(0),
time: bigint, // Unix timestamp (seconds)
triggeredTimestamp: null,
}
EndBehavior
{
__kind: 'SendQuoteTokenPercentage',
padding: Array(4).fill(0),
destinationBucket: PublicKey,
percentageBps: number, // 10000 = 100%
processed: false,
}
Constants
| Constant | Value |
|---|---|
WRAPPED_SOL_MINT | So11111111111111111111111111111111111111112 |
Common Errors
| Error | Cause |
|---|---|
insufficient funds | Not enough SOL for fees |
already initialized | Genesis Account exists |
already finalized | Cannot modify after finalization |
deposit period not active | Outside deposit window |
claim period not active | Outside claim window |
FAQ
What is Umi and why is it required?
Umi is Metaplex's JavaScript framework for Solana. It provides a consistent interface for building transactions, managing signers, and interacting with Metaplex programs.
Can I use the Genesis SDK in a browser?
Yes. The SDK works in both Node.js and browser environments. For browsers, use a wallet adapter for signing instead of keypair files.
What's the difference between fetch and safeFetch?
fetch throws an error if the account doesn't exist. safeFetch returns null instead, useful for checking if an account exists.
How do I handle transaction errors?
Wrap sendAndConfirm calls in try/catch blocks. Check error messages for specific failure reasons.
Next Steps
For complete implementation tutorials:
- Getting Started - Setup and first launch
- Launch Pool - Proportional distribution
- Presale - Fixed-price sales
