Metaplex APIを通じたボンディングカーブのローンチ

Genesis SDKとMetaplex APIを使用して、Solanaでボンディングカーブトークンローンチを作成、署名、送信、登録します。

Summary

createAndRegisterLaunch（またはその低レベルの同等物）は POST /v1/launches/create を呼び出し、未署名のSolanaトランザクションを返し、署名・送信してから、トークンがmetaplex.comに表示されるようにローンチを登録します。

• ワンライナーパス — createAndRegisterLaunch は1回の待機呼び出しで完全なフローを処理
• 手動パス — カスタム署名、バンドル、リトライロジックのための createLaunch + signAndSendLaunchTransactions + registerLaunch
• クリエイター手数料 — ボンディングカーブと卒業後のRaydiumプールでのスワップごとのオプション手数料。ウォレットごとに設定可能、またはエージェントローンチ用に自動的に派生
• ファーストバイ — カーブ作成時にローンチウォレットまたはエージェントPDAのために予約された手数料無料の初回購入

クイックスタート

ジャンプ: インストール · セットアップ · ワンライナーローンチ · クリエイター手数料 · ファーストバイ · 手動署名 · トークンメタデータ · Devnet · 高度な設定 · エラー · APIリファレンス

1. Genesis SDKをインストールし、キーペアIDでUmiインスタンスを設定する
2. token メタデータと launch: {} オブジェクトで createAndRegisterLaunch を呼び出す
3. レスポンスから result.mintAddress と result.launch.link を読み取る

カスタム署名やリトライロジックには手動署名フローを使用してください。

前提条件

• Node.js 18+ — ネイティブ BigInt サポートに必要
• トランザクション手数料とオプションのファーストバイ金額のためにSOLが入金されたSolanaウォレットキーペア
• SolanaのRPCエンドポイント（mainnet-betaまたはdevnet）
• Irysにアップロード済みの画像 — トークンメタデータの image フィールドはIrysゲートウェイURLである必要があります

インストール

必要な3つのパッケージをインストールします。

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

Umiセットアップ

Genesis API関数を呼び出す前に、キーペアIDでUmiインスタンスを設定します。

1import { createUmi } from '@metaplex-foundation/umi-bundle-defaults';
2import { keypairIdentity } from '@metaplex-foundation/umi';
3
4const umi = createUmi('https://api.mainnet-beta.solana.com');
5
6// キーペアを読み込む — 本番環境では適切なキー管理ソリューションを使用してください。
7const keypair = umi.eddsa.createKeypairFromSecretKey(mySecretKeyBytes);
8umi.use(keypairIdentity(keypair));

ボンディングカーブのローンチ（ワンライナーフロー）

createAndRegisterLaunch は最もシンプルなパスです — 1回の待機呼び出しでローンチを作成し、すべてのトランザクションに署名して送信し、metaplex.comにトークンを登録します。

1import { createAndRegisterLaunch } from '@metaplex-foundation/genesis/api';
2import { createUmi } from '@metaplex-foundation/umi-bundle-defaults';
3import { keypairIdentity } from '@metaplex-foundation/umi';
4
5const umi = createUmi('https://api.mainnet-beta.solana.com');
6const keypair = umi.eddsa.createKeypairFromSecretKey(mySecretKeyBytes);
7umi.use(keypairIdentity(keypair));
8
9const result = await createAndRegisterLaunch(umi, {}, {
10  wallet: umi.identity.publicKey,
11  launchType: 'bondingCurve',
12  token: {
13    name: 'My Token',
14    symbol: 'MTK',
15    image: 'https://gateway.irys.xyz/your-image-id',
16  },
17  launch: {},
18});
19
20console.log('Token launched!');
21console.log('Mint address:', result.mintAddress);
22console.log('View at:', result.launch.link);
23
24// Token launched!
25// Mint address: <base58 mint address>
26// View at: https://www.metaplex.com/...

1mplx genesis launch create --launchType bonding-curve \
2  --name "My Token" \
3  --symbol "MTK" \
4  --image "https://gateway.irys.xyz/your-image-id"

launch: {} が空の場合、すべてのプロトコルパラメーター（供給分割、仮想リザーブ、資金フロー、ロックスケジュール）はプロトコルのデフォルト値に設定されます。以下のセクションでは、クリエイター手数料とファーストバイの追加方法を説明します。

クリエイター手数料

オプションのスワップごとの手数料が、設定されたウォレットに毎回の購入と売却で蓄積されます。launch オブジェクトに creatorFeeWallet を設定して、手数料を特定のアドレスにリダイレクトします。デフォルトではローンチウォレットが使用されます。

launch: {
  creatorFeeWallet: 'FeeRecipientWalletAddress...',
},

完全な設定オプション、蓄積残高の確認方法、請求インストラクション（claimBondingCurveCreatorFeeV2 / claimRaydiumCreatorFeeV2）については、クリエイター手数料を参照してください。

ファーストバイ

ファーストバイは、すべての手数料が免除された指定のSOL金額で、カーブの初回スワップをローンチウォレット用に予約します。

firstBuyAmount に手数料無料の初回購入のSOL金額を設定します。

1import { createAndRegisterLaunch } from '@metaplex-foundation/genesis/api';
2import { createUmi } from '@metaplex-foundation/umi-bundle-defaults';
3import { keypairIdentity } from '@metaplex-foundation/umi';
4
5const umi = createUmi('https://api.mainnet-beta.solana.com');
6const keypair = umi.eddsa.createKeypairFromSecretKey(mySecretKeyBytes);
7umi.use(keypairIdentity(keypair));
8
9const result = await createAndRegisterLaunch(umi, {}, {
10  wallet: umi.identity.publicKey,
11  launchType: 'bondingCurve',
12  token: {
13    name: 'My Token',
14    symbol: 'MTK',
15    image: 'https://gateway.irys.xyz/your-image-id',
16  },
17  launch: {
18    firstBuyAmount: 0.1, // 0.1 SOL, fee-free initial purchase
19  },
20});

1mplx genesis launch create --launchType bonding-curve \
2  --name "My Token" \
3  --symbol "MTK" \
4  --image "https://gateway.irys.xyz/your-image-id" \
5  --firstBuyAmount 0.1

APIはローンチトランザクションフローの一部としてファーストバイを実行します — トランザクションが確認されると、カーブにはすでに初回購入が適用されています。購入者はデフォルトでローンチ wallet に、または agent が指定された場合はエージェントPDAになります。別の購入者を指定するには firstBuyWallet（Signer）でオーバーライドします。

firstBuyAmount が省略または 0 の場合、ファーストバイの制限は適用されず、どのウォレットでも最初のスワップが可能です。

クリエイター手数料ウォレットとファーストバイを組み合わせることができます：

launch: {
  creatorFeeWallet: 'FeeRecipientWalletAddress...',
  firstBuyAmount: 0.5,
},

手動署名フロー

トランザクションの署名と送信方法を制御する必要がある場合（例えば、Jitoバンドル、優先手数料、カスタムリトライロジックを使用する場合）は、createLaunch と registerLaunch を個別に使用してください。

1import {
2  createLaunch,
3  registerLaunch,
4  signAndSendLaunchTransactions,
5} from '@metaplex-foundation/genesis/api';
6
7// ステップ1：APIを呼び出して未署名トランザクションを取得する。
8const createResult = await createLaunch(umi, {}, {
9  wallet: umi.identity.publicKey,
10  launchType: 'bondingCurve',
11  token: {
12    name: 'My Token',
13    symbol: 'MTK',
14    image: 'https://gateway.irys.xyz/your-image-id',
15  },
16  launch: {
17    creatorFeeWallet: 'FeeRecipientWalletAddress...',
18  },
19});
20
21console.log('Mint address:', createResult.mintAddress);
22console.log('Transactions to sign:', createResult.transactions.length);
23
24// ステップ2：トランザクションに署名して送信する。
25const signatures = await signAndSendLaunchTransactions(umi, createResult);
26
27// ステップ3：すべてのトランザクションがオンチェーンで確認された後、ローンチを登録する。
28const registered = await registerLaunch(umi, {}, {
29  genesisAccount: createResult.genesisAccount,
30  createLaunchInput: {
31    wallet: umi.identity.publicKey,
32    launchType: 'bondingCurve',
33    token: {
34      name: 'My Token',
35      symbol: 'MTK',
36      image: 'https://gateway.irys.xyz/your-image-id',
37    },
38    launch: {
39      creatorFeeWallet: 'FeeRecipientWalletAddress...',
40    },
41  },
42});
43
44console.log('Launch live at:', registered.launch.link);

トークンメタデータ

すべてのローンチには以下のフィールドを持つ token オブジェクトが必要です。

token: {
  name: 'My Token',
  symbol: 'MTK',
  image: 'https://gateway.irys.xyz/your-image-id',
  description: 'A token launched on the bonding curve',
  externalLinks: {
    website: 'https://mytoken.com',
    twitter: '@mytoken',
    telegram: '@mytoken',
  },
},

Devnetテスト

network: 'solana-devnet' を渡し、UmiインスタンスをdevnetのRPCエンドポイントに向けて、devnetインフラを通じてローンチをルーティングします。CLIの場合、ネットワークは設定されたRPCエンドポイントによって決まります。

1import { createAndRegisterLaunch } from '@metaplex-foundation/genesis/api';
2import { createUmi } from '@metaplex-foundation/umi-bundle-defaults';
3import { keypairIdentity } from '@metaplex-foundation/umi';
4
5const umi = createUmi('https://api.devnet.solana.com');
6const keypair = umi.eddsa.createKeypairFromSecretKey(mySecretKeyBytes);
7umi.use(keypairIdentity(keypair));
8
9const result = await createAndRegisterLaunch(umi, {}, {
10  wallet: umi.identity.publicKey,
11  launchType: 'bondingCurve',
12  network: 'solana-devnet',
13  token: {
14    name: 'Test Token',
15    symbol: 'TEST',
16    image: 'https://gateway.irys.xyz/test-image',
17  },
18  launch: {},
19});

1# Network is determined by your configured RPC endpoint.
2mplx genesis launch create --launchType bonding-curve \
3  --name "Test Token" \
4  --symbol "TEST" \
5  --image "https://gateway.irys.xyz/test-image"

高度な設定

カスタムAPIベースURL

SDKはデフォルトで https://api.metaplex.com を使用します。設定オブジェクト（2番目の引数）に baseUrl を渡して、ステージングAPIなどの別の環境を対象にします。

1const API_CONFIG = { baseUrl: 'https://your-api-base-url.example.com' };
2
3const result = await createAndRegisterLaunch(umi, API_CONFIG, {
4  wallet: umi.identity.publicKey,
5  launchType: 'bondingCurve',
6  token: {
7    name: 'My Token',
8    symbol: 'MTK',
9    image: 'https://gateway.irys.xyz/your-image-id',
10  },
11  launch: {},
12});

同じ API_CONFIG オブジェクトは、手動署名フローの createLaunch と registerLaunch でも受け入れられます。

カスタムトランザクション送信者

オプション（4番目の引数）に txSender コールバックを渡して、独自の署名・送信インフラを使用します。

1const result = await createAndRegisterLaunch(
2  umi,
3  {},
4  {
5    wallet: umi.identity.publicKey,
6    launchType: 'bondingCurve',
7    token: {
8      name: 'My Token',
9      symbol: 'MTK',
10      image: 'https://gateway.irys.xyz/your-image-id',
11    },
12    launch: {},
13  },
14  {
15    txSender: async (txs) => {
16      const signatures = [];
17      for (const tx of txs) {
18        const signed = await umi.identity.signTransaction(tx);
19        signatures.push(await myCustomSend(signed));
20      }
21      return signatures;
22    },
23  }
24);

よくあるエラー

これらのケースを区別するために型付きエラーガードを使用します：

1import {
2  createLaunch,
3  isGenesisApiError,
4  isGenesisApiNetworkError,
5  isGenesisValidationError,
6} from '@metaplex-foundation/genesis/api';
7
8try {
9  const result = await createLaunch(umi, {}, input);
10} catch (err) {
11  if (isGenesisValidationError(err)) {
12    console.error(`Validation error on "${err.field}": ${err.message}`);
13  } else if (isGenesisApiNetworkError(err)) {
14    console.error('Network error:', err.message);
15  } else if (isGenesisApiError(err)) {
16    console.error(`API error (${err.statusCode}): ${err.message}`);
17    console.error('Details:', err.responseBody);
18  } else {
19    throw err;
20  }
21}

Notes

• createAndRegisterLaunch は呼び出し元からの観点でアトミックですが、内部的には2回のAPI呼び出しを行います — 作成トランザクションが確認された後で registerLaunch の前に失敗すると、トークンはオンチェーンに存在しますがmetaplex.comにはまだ表示されません。登録を完了するには registerLaunch を手動で呼び出してください
• MetaplexのAPIエンドポイント（https://api.metaplex.com）はホスト型インフラです — 未署名トランザクションを構築して返します。呼び出し元は常に署名の保持と制御を行います
• 仮想リザーブ、供給分割、ロックスケジュールは launch: {} が空の場合にプロトコルのデフォルト値によって設定されます。これらをローンチごとにオーバーライドするAPIはありません
• agent.setToken フラグは取り消し不可です — トークンがエージェントのプライマリトークンとして設定されると変更や再割り当てはできません。完全なエージェントローンチフローについてはエージェントトークンの作成を参照してください
• カーブがライブになったら、ボンディングカーブスワップ統合ガイドを使用してスワップを統合してください
• ファーストバイはローンチ作成時に設定され、カーブがライブになった後には追加できません。firstBuyAmount: 0 またはフィールドの省略で完全に無効化されます
• クリエイター手数料はバケットに蓄積され、スワップごとに転送されません。パーミッションレスの claimBondingCurveCreatorFeeV2（ボンディングカーブ）と claimRaydiumCreatorFeeV2（卒業後のRaydium）インストラクションで請求します

APIリファレンス

createAndRegisterLaunch(umi, config, input, options?)

完全なローンチフローを調整するコンビニエンス関数：作成、署名、送信、登録。

Promise<CreateAndRegisterLaunchResult> を返します：

createLaunch(umi, config, input)

POST /v1/launches/create を呼び出し、デシリアライズされたトランザクションを返します。

Promise<CreateLaunchResponse> を返します：

registerLaunch(umi, config, input)

確認済みのgenesisアカウントをmetaplex.comに登録します。すべての作成トランザクションがオンチェーンで確認された後に呼び出してください。

Promise<RegisterLaunchResponse> を返します：

型

interface CreateBondingCurveLaunchInput {
  wallet: PublicKey | string;
  launchType: 'bondingCurve';
  token: TokenMetadata;
  network?: 'solana-mainnet' | 'solana-devnet';
  quoteMint?: 'SOL';
  agent?: {
    mint: PublicKey | string;   // Coreアセット（NFT）アドレス
    setToken: boolean;          // ローンチされたトークンをエージェントのプライマリトークンとして設定
  };
  launch: BondingCurveLaunchInput;
}

interface BondingCurveLaunchInput {
  creatorFeeWallet?: PublicKey | string;
  firstBuyAmount?: number;   // SOL金額（例：0.1 = 0.1 SOL）
  firstBuyWallet?: Signer;
}

interface TokenMetadata {
  name: string;           // 最大32文字
  symbol: string;         // 最大10文字
  image: string;          // IrysのURLである必要がある: https://gateway.irys.xyz/...
  description?: string;   // 最大250文字
  externalLinks?: {
    website?: string;
    twitter?: string;
    telegram?: string;
  };
}

interface GenesisApiConfig {
  baseUrl?: string;
  fetch?: typeof fetch;
}

FAQ

createAndRegisterLaunch と createLaunch から registerLaunch を個別に呼び出すことの違いは何ですか？

createAndRegisterLaunch は完全なフローを1回の呼び出しで処理するコンビニエンスラッパーです。カスタム署名ロジック（例：Jitoバンドル、優先手数料）が必要な場合や、送信前に未署名トランザクションを検査・修正したい場合は、低レベル関数を個別に使用してください。手動署名フローを参照してください。

メインネットに行く前にdevnetでボンディングカーブのローンチをテストできますか？

はい。入力に network: 'solana-devnet' を渡し、Umiインスタンスを https://api.devnet.solana.com に向けてください。APIはリクエストをdevnetインフラにルーティングします。トランザクションを送信する前に、ウォレットにdevnet SOLが入金されていることを確認してください。Devnetテストを参照してください。

誤って agent.setToken: true を設定した場合どうなりますか？

setToken: true を設定するとローンチされたトークンがエージェントのプライマリトークンとして永続的に関連付けられます — これは取り消せず、再割り当てもできません。不確かな場合は agent フィールドを省略するか setToken: false を設定し、トークンの関連付けは別途処理してください。

クリエイター手数料ウォレットとファーストバイを組み合わせることはできますか？

はい。launch オブジェクトに creatorFeeWallet と firstBuyAmount の両方を設定します。ファーストバイ自体は手数料無料です — その初回購入にはプロトコル手数料もクリエイター手数料もかかりません。クリエイター手数料はその後のすべてのスワップに通常通り適用されます。ファーストバイを参照してください。

トークンメタデータに必要な画像フォーマットとホスティングは何ですか？

image フィールドはIrysのURL — https://gateway.irys.xyz/<id> である必要があります。まずIrysに画像をアップロードして、返されたゲートウェイURLを使用してください。他のホストはAPIバリデーションで失敗します。SDKはこれを token.image フィールドの isGenesisValidationError として表示します。

registerLaunch はトランザクションがオンチェーンで確認された後に呼び出す必要があるのはなぜですか？

registerLaunch はMetaplexのデータベースにローンチレコードを書き込み、登録前にgenesisアカウントがオンチェーンに存在することを確認します。作成トランザクションが確認される前に呼び出すと、アカウントがまだ表示されないためAPIエラーが返されます。createAndRegisterLaunch では、このシーケンシングが自動的に処理されます。