SDK

API クライアント

Last updated February 19, 2026

Genesis API クライアントは、トークンローンチの作成と登録のための高レベルな関数を提供します。Umi 上に構築されたシンプルなインターフェースを通じて、トランザクションの構築、署名、オンチェーン登録を処理します。

Genesis プログラムの全機能セットは metaplex.com ではまだサポートされていないため、プログラムによるローンチの作成には SDK の使用を推奨します。API を通じて作成されたメインネットのローンチは、登録後に metaplex.com に表示されます。

インストール

npm install @metaplex-foundation/genesis @metaplex-foundation/umi \
@metaplex-foundation/umi-bundle-defaults

セットアップ

import { createUmi } from '@metaplex-foundation/umi-bundle-defaults';
import { genesis } from '@metaplex-foundation/genesis';
import { keypairIdentity } from '@metaplex-foundation/umi';
const umi = createUmi('https://api.mainnet-beta.solana.com')
.use(genesis());
// For server-side or scripts, load a keypair
umi.use(keypairIdentity(myKeypair));

3つの統合モード

SDK はローンチ作成のために、完全自動から完全手動まで3つのモードを提供します。

イージーモード — createAndRegisterLaunch

最もシンプルなアプローチです。1回の関数呼び出しですべてを処理します:オンチェーンアカウントの作成、Umi を介したトランザクションの署名と送信、そしてローンチの登録を行います。

createAndRegisterLaunch.ts
1import {
2 createAndRegisterLaunch,
3 CreateLaunchInput,
4 genesis,
5} from '@metaplex-foundation/genesis'
6import { createUmi } from '@metaplex-foundation/umi-bundle-defaults'
7import { keypairIdentity } from '@metaplex-foundation/umi'
8
9const umi = createUmi('https://api.mainnet-beta.solana.com')
10 .use(genesis())
11
12// Use keypairIdentity to set a wallet when running server-side:
13// umi.use(keypairIdentity(myKeypair))
14
15const input: CreateLaunchInput = {
16 wallet: umi.identity.publicKey,
17 token: {
18 name: 'My Token',
19 symbol: 'MTK',
20 image: 'https://gateway.irys.xyz/...',
21 },
22 launchType: 'project',
23 launch: {
24 launchpool: {
25 tokenAllocation: 500_000_000,
26 depositStartTime: new Date(Date.now() + 48 * 60 * 60 * 1000),
27 raiseGoal: 200,
28 raydiumLiquidityBps: 5000,
29 fundsRecipient: umi.identity.publicKey,
30 },
31 },
32}
33
34const result = await createAndRegisterLaunch(umi, {}, input)
35console.log(`Launch live at: ${result.launch.link}`)

戻り値 CreateAndRegisterLaunchResult

フィールド説明
signaturesUint8Array[]トランザクション署名
mintAddressstring作成されたトークンミントアドレス
genesisAccountstringGenesis アカウント PDA アドレス
launch.idstringローンチ ID
launch.linkstringローンチページ URL
token.idstringトークン ID
token.mintAddressstringトークンミントアドレス

ミディアムモード — カスタムトランザクション送信

マルチシグウォレットやカスタムリトライロジックなどのシナリオに対応するため、createAndRegisterLaunch にカスタム txSender コールバックを指定して使用します。

customTxSender.ts
1import {
2 createAndRegisterLaunch,
3 SignAndSendOptions,
4} from '@metaplex-foundation/genesis'
5
6// Assumes umi and input from the Easy Mode example.
7
8const options: SignAndSendOptions = {
9 txSender: async (transactions) => {
10 // Replace myCustomSign / myCustomSend with your own
11 // signing and sending implementation.
12 const signatures: Uint8Array[] = []
13 for (const tx of transactions) {
14 const signed = await myCustomSign(tx) // your signer
15 const sig = await myCustomSend(signed) // your sender
16 signatures.push(sig)
17 }
18 return signatures
19 },
20}
21
22const result = await createAndRegisterLaunch(umi, {}, input, options)
23console.log(`Launch live at: ${result.launch.link}`)

txSender コールバックは未署名トランザクションの配列を受け取り、署名の配列を返す必要があります。コールバック完了後、SDK が登録処理を行います。

フルコントロール — createLaunch + registerLaunch

トランザクションライフサイクルを完全に制御するモードです。createLaunch を呼び出して未署名トランザクションを取得し、署名と送信を自分で行った後、registerLaunch を呼び出します。

fullControl.ts
1import {
2 createLaunch,
3 registerLaunch,
4} from '@metaplex-foundation/genesis'
5
6// Assumes umi and input from the Easy Mode example.
7
8// Step 1: Get unsigned transactions from the API
9const createResult = await createLaunch(umi, {}, input)
10
11// Step 2: Sign and send each transaction
12for (const tx of createResult.transactions) {
13 const signedTx = await umi.identity.signTransaction(tx)
14 const signature = await umi.rpc.sendTransaction(signedTx, {
15 commitment: 'confirmed',
16 preflightCommitment: 'confirmed',
17 })
18 await umi.rpc.confirmTransaction(signature, {
19 commitment: 'confirmed',
20 strategy: {
21 type: 'blockhash',
22 ...createResult.blockhash,
23 },
24 })
25}
26
27// Step 3: Register the launch
28const registerResult = await registerLaunch(umi, {}, {
29 genesisAccount: createResult.genesisAccount,
30 createLaunchInput: input,
31})
32console.log(`Launch live at: ${registerResult.launch.link}`)

createLaunch の戻り値 CreateLaunchResponse

フィールド説明
transactionsTransaction[]署名して送信する未署名の Umi トランザクション
blockhashBlockhashWithExpiryBlockHeightトランザクション確認用のブロックハッシュ
mintAddressstring作成されたトークンミントアドレス
genesisAccountstringGenesis アカウント PDA アドレス

registerLaunch の戻り値 RegisterLaunchResponse

フィールド説明
existingboolean?ローンチが既に登録されている場合は true
launch.idstringローンチ ID
launch.linkstringローンチページ URL
token.idstringトークン ID
token.mintAddressstringトークンミントアドレス

registerLaunch を呼び出す前に、トランザクションがオンチェーンで確認されている必要があります。登録エンドポイントは、Genesis アカウントが存在し、期待される設定と一致することを検証します。


設定

CreateLaunchInput

フィールド必須説明
walletPublicKey | stringはい作成者のウォレット(トランザクションに署名)
tokenTokenMetadataはいトークンメタデータ
networkSvmNetworkいいえ'solana-mainnet'(デフォルト)または 'solana-devnet'
quoteMintQuoteMintInputいいえ'SOL'(デフォルト)、'USDC'、または生のミントアドレス
launchTypeLaunchTypeはい'project'
launchProjectLaunchInputはいローンチ設定

TokenMetadata

フィールド必須説明
namestringはいトークン名、1〜32文字
symbolstringはいトークンシンボル、1〜10文字
imagestringはい画像 URL(有効な HTTPS URL)
descriptionstringいいえ最大250文字
externalLinksExternalLinksいいえウェブサイト、Twitter、Telegram のリンク
フィールド説明
websitestring?ウェブサイト URL
twitterstring?Twitter/X ハンドル(@mytoken)またはフル URL
telegramstring?Telegram ハンドルまたはフル URL

LaunchpoolConfig

フィールド説明
tokenAllocationnumber販売するトークン数(総供給量10億の一部)
depositStartTimeDate | string入金期間の開始時刻(48時間継続)
raiseGoalnumber最低調達目標(整数単位、例:200 SOL)
raydiumLiquidityBpsnumberRaydium LP に使用する調達資金の割合(ベーシスポイント、2000〜10000)
fundsRecipientPublicKey | stringロック解除された調達資金の受取先

LockedAllocation(Streamflow ロックアップ)

オプションのロック付きトークンスケジュールは launch.lockedAllocations で追加できます:

フィールド説明
namestringストリーム名、最大64文字(例:"Team"、"Advisors")
recipientPublicKey | stringロックアップの受取先ウォレット
tokenAmountnumberロックスケジュールの総トークン数
vestingStartTimeDate | stringロック解除スケジュールの開始時刻
vestingDuration{ value: number, unit: TimeUnit }全ロックアップ期間
unlockScheduleTimeUnitトークンがリリースされる頻度
cliffobject?オプションのクリフ(durationunlockAmount を含む)

vestingStartTime入金期間終了後(つまり depositStartTime + 48時間以降)でなければなりません。入金ウィンドウが閉じる前に開始するロックスケジュールは API によって拒否されます。

TimeUnit の値: 'SECOND''MINUTE''HOUR''DAY''WEEK''TWO_WEEKS''MONTH''QUARTER''YEAR'

ロック付きアロケーションの例:

lockedAllocations.ts
1import {
2 createAndRegisterLaunch,
3 CreateLaunchInput,
4 genesis,
5} from '@metaplex-foundation/genesis'
6import { createUmi } from '@metaplex-foundation/umi-bundle-defaults'
7import { keypairIdentity } from '@metaplex-foundation/umi'
8
9const umi = createUmi('https://api.mainnet-beta.solana.com')
10 .use(genesis())
11
12// Use keypairIdentity to set a wallet when running server-side:
13// umi.use(keypairIdentity(myKeypair))
14
15const input: CreateLaunchInput = {
16 wallet: umi.identity.publicKey,
17 token: {
18 name: 'My Token',
19 symbol: 'MTK',
20 image: 'https://gateway.irys.xyz/...',
21 description: 'A project token with locked allocations.',
22 externalLinks: {
23 website: 'https://example.com',
24 twitter: '@mytoken',
25 },
26 },
27 launchType: 'project',
28 launch: {
29 launchpool: {
30 tokenAllocation: 500_000_000,
31 depositStartTime: new Date('2026-04-01T00:00:00Z'),
32 raiseGoal: 200,
33 raydiumLiquidityBps: 5000,
34 fundsRecipient: 'FundsRecipientWallet...',
35 },
36 lockedAllocations: [
37 {
38 name: 'Team',
39 recipient: 'TeamWallet...',
40 tokenAmount: 100_000_000,
41 vestingStartTime: new Date('2026-04-05T00:00:00Z'),
42 vestingDuration: { value: 1, unit: 'YEAR' },
43 unlockSchedule: 'MONTH',
44 cliff: {
45 duration: { value: 3, unit: 'MONTH' },
46 unlockAmount: 10_000_000,
47 },
48 },
49 ],
50 },
51}
52
53const result = await createAndRegisterLaunch(umi, {}, input)
54console.log(`Launch live at: ${result.launch.link}`)

SignAndSendOptions

createAndRegisterLaunch のオプション(RpcSendTransactionOptions を拡張):

フィールドデフォルト説明
txSender(txs: Transaction[]) => Promise<Uint8Array[]>カスタムトランザクション送信コールバック
commitmentstring'confirmed'確認のコミットメントレベル
preflightCommitmentstring'confirmed'プリフライトのコミットメントレベル
skipPreflightbooleanfalseプリフライトチェックをスキップ

エラーハンドリング

SDK は型ガード関数を備えた3種類のエラー型を提供します。

GenesisApiError

API が成功以外のレスポンスを返した場合にスローされます。

import { isGenesisApiError } from '@metaplex-foundation/genesis';
try {
await createLaunch(umi, input);
} catch (err) {
if (isGenesisApiError(err)) {
console.error('API error:', err.statusCode, err.responseBody);
}
}
プロパティ説明
statusCodenumberHTTP ステータスコード
responseBodyunknownAPI からの完全なレスポンスボディ

GenesisApiNetworkError

fetch 呼び出しが失敗した場合(ネットワーク障害、DNS エラーなど)にスローされます。

import { isGenesisApiNetworkError } from '@metaplex-foundation/genesis';
if (isGenesisApiNetworkError(err)) {
console.error('Network error:', err.cause.message);
}
プロパティ説明
causeError基となる fetch エラー

GenesisValidationError

API 呼び出し前に入力バリデーションが失敗した場合にスローされます。

import { isGenesisValidationError } from '@metaplex-foundation/genesis';
if (isGenesisValidationError(err)) {
console.error(`Validation failed on field "${err.field}":`, err.message);
}
プロパティ説明
fieldstringバリデーションに失敗した入力フィールド

包括的なエラーハンドリング

errorHandling.ts
1import {
2 createAndRegisterLaunch,
3 isGenesisApiError,
4 isGenesisApiNetworkError,
5 isGenesisValidationError,
6} from '@metaplex-foundation/genesis'
7
8// Assumes umi and input from the Easy Mode example.
9
10try {
11 const result = await createAndRegisterLaunch(umi, {}, input)
12 console.log(`Launch live at: ${result.launch.link}`)
13} catch (err) {
14 if (isGenesisValidationError(err)) {
15 console.error(`Invalid input "${err.field}":`, err.message)
16 } else if (isGenesisApiError(err)) {
17 console.error('API error:', err.statusCode, err.responseBody)
18 } else if (isGenesisApiNetworkError(err)) {
19 console.error('Network error:', err.cause.message)
20 } else {
21 throw err
22 }
23}

バリデーションルール

SDK は API に送信する前に入力を検証します:

ルール制約
トークン名1〜32文字
トークンシンボル1〜10文字
トークン画像有効な HTTPS URL
トークン説明最大250文字
トークンアロケーション0より大きい値
調達目標0より大きい値
Raydium 流動性 BPS2000〜10000(20%〜100%)
総供給量10億トークンで固定
ロック付きアロケーション名最大64文字

総供給量は常に10億トークンです。SDK はローンチプール、Raydium LP、およびロック付きアロケーションを差し引いた残りとして、作成者のアロケーションを自動的に計算します。


ヘルパー関数

signAndSendLaunchTransactions

デフォルトの署名・送信動作をスタンドアロン関数として使用する場合(リトライや部分フローに便利):

import {
createLaunch,
signAndSendLaunchTransactions,
} from '@metaplex-foundation/genesis';
const createResult = await createLaunch(umi, input);
const signatures = await signAndSendLaunchTransactions(umi, createResult, {
commitment: 'confirmed',
});

トランザクションは順番に署名・送信されます — 各トランザクションは次のものが送信される前に確認されます。

buildCreateLaunchPayload

入力を検証し、生の API ペイロードを構築します。高度なユースケース向けにエクスポートされています:

import { buildCreateLaunchPayload } from '@metaplex-foundation/genesis';
const payload = buildCreateLaunchPayload(input);
// Use payload with your own HTTP client