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

FunctionDescription
initializeV2()Create Genesis Account and mint token
finalizeV2()Lock configuration, activate launch

Buckets

FunctionDescription
addLaunchPoolBucketV2()Add proportional distribution bucket
addPresaleBucketV2()Add fixed-price sale bucket
addUnlockedBucketV2()Add treasury/recipient bucket

Launch Pool Operations

FunctionDescription
depositLaunchPoolV2()Deposit SOL into Launch Pool
withdrawLaunchPoolV2()Withdraw SOL (during deposit period)
claimLaunchPoolV2()Claim tokens (after deposit period)

Presale Operations

FunctionDescription
depositPresaleV2()Deposit SOL into Presale
claimPresaleV2()Claim tokens (after deposit period)

Admin

FunctionDescription
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

FunctionSeeds
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

FunctionReturns
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

ConstantValue
WRAPPED_SOL_MINTSo11111111111111111111111111111111111111112

Common Errors

ErrorCause
insufficient fundsNot enough SOL for fees
already initializedGenesis Account exists
already finalizedCannot modify after finalization
deposit period not activeOutside deposit window
claim period not activeOutside 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: