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 を介したトランザクションの署名と送信、そしてローンチの登録を行います。
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:
| フィールド | 型 | 説明 |
|---|---|---|
signatures | Uint8Array[] | トランザクション署名 |
mintAddress | string | 作成されたトークンミントアドレス |
genesisAccount | string | Genesis アカウント PDA アドレス |
launch.id | string | ローンチ ID |
launch.link | string | ローンチページ URL |
token.id | string | トークン ID |
token.mintAddress | string | トークンミントアドレス |
ミディアムモード — カスタムトランザクション送信
マルチシグウォレットやカスタムリトライロジックなどのシナリオに対応するため、createAndRegisterLaunch にカスタム txSender コールバックを指定して使用します。
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 を呼び出します。
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:
| フィールド | 型 | 説明 |
|---|---|---|
transactions | Transaction[] | 署名して送信する未署名の Umi トランザクション |
blockhash | BlockhashWithExpiryBlockHeight | トランザクション確認用のブロックハッシュ |
mintAddress | string | 作成されたトークンミントアドレス |
genesisAccount | string | Genesis アカウント PDA アドレス |
registerLaunch の戻り値 RegisterLaunchResponse:
| フィールド | 型 | 説明 |
|---|---|---|
existing | boolean? | ローンチが既に登録されている場合は true |
launch.id | string | ローンチ ID |
launch.link | string | ローンチページ URL |
token.id | string | トークン ID |
token.mintAddress | string | トークンミントアドレス |
registerLaunch を呼び出す前に、トランザクションがオンチェーンで確認されている必要があります。登録エンドポイントは、Genesis アカウントが存在し、期待される設定と一致することを検証します。
設定
CreateLaunchInput
| フィールド | 型 | 必須 | 説明 |
|---|---|---|---|
wallet | PublicKey | string | はい | 作成者のウォレット(トランザクションに署名) |
token | TokenMetadata | はい | トークンメタデータ |
network | SvmNetwork | いいえ | 'solana-mainnet'(デフォルト)または 'solana-devnet' |
quoteMint | QuoteMintInput | いいえ | 'SOL'(デフォルト)、'USDC'、または生のミントアドレス |
launchType | LaunchType | はい | 'project' |
launch | ProjectLaunchInput | はい | ローンチ設定 |
TokenMetadata
| フィールド | 型 | 必須 | 説明 |
|---|---|---|---|
name | string | はい | トークン名、1〜32文字 |
symbol | string | はい | トークンシンボル、1〜10文字 |
image | string | はい | 画像 URL(有効な HTTPS URL) |
description | string | いいえ | 最大250文字 |
externalLinks | ExternalLinks | いいえ | ウェブサイト、Twitter、Telegram のリンク |
ExternalLinks
| フィールド | 型 | 説明 |
|---|---|---|
website | string? | ウェブサイト URL |
twitter | string? | Twitter/X ハンドル(@mytoken)またはフル URL |
telegram | string? | Telegram ハンドルまたはフル URL |
LaunchpoolConfig
| フィールド | 型 | 説明 |
|---|---|---|
tokenAllocation | number | 販売するトークン数(総供給量10億の一部) |
depositStartTime | Date | string | 入金期間の開始時刻(48時間継続) |
raiseGoal | number | 最低調達目標(整数単位、例:200 SOL) |
raydiumLiquidityBps | number | Raydium LP に使用する調達資金の割合(ベーシスポイント、2000〜10000) |
fundsRecipient | PublicKey | string | ロック解除された調達資金の受取先 |
LockedAllocation(Streamflow ロックアップ)
オプションのロック付きトークンスケジュールは launch.lockedAllocations で追加できます:
| フィールド | 型 | 説明 |
|---|---|---|
name | string | ストリーム名、最大64文字(例:"Team"、"Advisors") |
recipient | PublicKey | string | ロックアップの受取先ウォレット |
tokenAmount | number | ロックスケジュールの総トークン数 |
vestingStartTime | Date | string | ロック解除スケジュールの開始時刻 |
vestingDuration | { value: number, unit: TimeUnit } | 全ロックアップ期間 |
unlockSchedule | TimeUnit | トークンがリリースされる頻度 |
cliff | object? | オプションのクリフ(duration と unlockAmount を含む) |
vestingStartTime は入金期間終了後(つまり depositStartTime + 48時間以降)でなければなりません。入金ウィンドウが閉じる前に開始するロックスケジュールは API によって拒否されます。
TimeUnit の値: 'SECOND'、'MINUTE'、'HOUR'、'DAY'、'WEEK'、'TWO_WEEKS'、'MONTH'、'QUARTER'、'YEAR'
ロック付きアロケーションの例:
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[]> | — | カスタムトランザクション送信コールバック |
commitment | string | 'confirmed' | 確認のコミットメントレベル |
preflightCommitment | string | 'confirmed' | プリフライトのコミットメントレベル |
skipPreflight | boolean | false | プリフライトチェックをスキップ |
エラーハンドリング
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);
}
}
| プロパティ | 型 | 説明 |
|---|---|---|
statusCode | number | HTTP ステータスコード |
responseBody | unknown | API からの完全なレスポンスボディ |
GenesisApiNetworkError
fetch 呼び出しが失敗した場合(ネットワーク障害、DNS エラーなど)にスローされます。
import { isGenesisApiNetworkError } from '@metaplex-foundation/genesis';
if (isGenesisApiNetworkError(err)) {
console.error('Network error:', err.cause.message);
}
| プロパティ | 型 | 説明 |
|---|---|---|
cause | Error | 基となる fetch エラー |
GenesisValidationError
API 呼び出し前に入力バリデーションが失敗した場合にスローされます。
import { isGenesisValidationError } from '@metaplex-foundation/genesis';
if (isGenesisValidationError(err)) {
console.error(`Validation failed on field "${err.field}":`, err.message);
}
| プロパティ | 型 | 説明 |
|---|---|---|
field | string | バリデーションに失敗した入力フィールド |
包括的なエラーハンドリング
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 流動性 BPS | 2000〜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
