エージェントトークンの作成

GenesisプロトコルとMetaplex APIを使用して、エージェントのオンチェーンウォレットからトークンを発行します。

サマリー

agentフィールドを指定したcreateAndRegisterLaunchは、新しいトークンを作成し、クリエイター手数料をエージェントのCore asset PDAにルーティングし、エージェントがオンチェーンで実行できるようにlaunchトランザクションをCore executeインストラクションでラップします。

• 単一呼び出し — createAndRegisterLaunchが作成、署名、送信、登録を順番に処理する
• 自動手数料ルーティング — クリエイター手数料はエージェントPDAに送られ、ウォレットアドレスの手動設定は不要
• 取り消し不可能なトークン関連付け — setToken: trueはトークンをエージェントに永久にリンクする
• 対応バージョン @metaplex-foundation/genesis 1.x · 最終確認：2026年4月

クイックスタート

ジャンプ先： インストール · Umiセットアップ · 発行 · 初回購入 · トークンメタデータ · Devnet · エラー

1. Solanaでエージェントを登録してCore assetアドレスを取得する
2. Genesis SDKをインストールし、キーペアでUmiインスタンスを設定する
3. agent: { mint: agentAssetAddress, setToken: true }を指定してcreateAndRegisterLaunchを呼び出す
4. レスポンスからresult.mintAddressとresult.launch.linkを読み取る

前提条件

• 登録済みのMetaplexエージェント — Core assetアドレスが必要
• Node.js 18以上 — ネイティブBigIntサポートに必要
• トランザクション手数料および初回購入額のSOLが入金されたSolanaウォレットキーペア
• SolanaのRPCエンドポイント（mainnet-betaまたはdevnet）
• Irysにアップロード済みのトークン画像 — imageフィールドはIrysゲートウェイURLである必要がある

インストール {#installation}

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

Umiセットアップ {#umi-setup}

Genesis関数を呼び出す前に、キーペア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));

エージェントトークンの発行 {#launching-an-agent-token}

createAndRegisterLaunchにエージェントのCore assetアドレスを指定したagentフィールドを渡します。SDKは自動的に以下を行います。

• クリエイター手数料ウォレットをエージェントのCore assetシグナーPDA（['mpl-core-execute', <agent_asset>]から導出）に設定する
• エージェントがオンチェーンで実行できるようにlaunchトランザクションをCore executeインストラクションでラップする

1import { createAndRegisterLaunch } from '@metaplex-foundation/genesis/api';
2
3const result = await createAndRegisterLaunch(umi, {}, {
4  wallet: umi.identity.publicKey,
5  agent: {
6    mint: agentAssetAddress,  // 登録済みエージェントのCore assetアドレス
7    setToken: true,           // このトークンをエージェントに永久に関連付ける
8  },
9  launchType: 'bondingCurve',
10  token: {
11    name: 'Agent Token',
12    symbol: 'AGT',
13    image: 'https://gateway.irys.xyz/your-image-id',
14  },
15  launch: {},
16});
17
18console.log('トークンが発行されました！');
19console.log('ミントアドレス:', result.mintAddress);
20console.log('確認先:', result.launch.link);

launch: {}が空の場合、供給の分割、仮想リザーブ、ロックスケジュールなどのすべてのプロトコルパラメーターはプロトコルのデフォルト値に設定されます。

ボンディングカーブの価格設定、手数料、グラデュエーションの仕組みについては、ボンディングカーブ — 動作理論を参照してください。

初回購入 {#first-buy}

初回購入は、指定したSOL額でエージェントPDAのためにカーブの最初のスワップを予約し、すべての手数料が免除されます。

firstBuyAmountに手数料無料の初回購入のSOL額を設定します。agentが指定されている場合、初回購入の購入者はデフォルトでエージェントPDAになります。

1const result = await createAndRegisterLaunch(umi, {}, {
2  wallet: umi.identity.publicKey,
3  agent: {
4    mint: agentAssetAddress,
5    setToken: true,
6  },
7  launchType: 'bondingCurve',
8  token: {
9    name: 'Agent Token',
10    symbol: 'AGT',
11    image: 'https://gateway.irys.xyz/your-image-id',
12  },
13  launch: {
14    firstBuyAmount: 0.1, // 0.1 SOL、手数料無料
15  },
16});

初回購入はlaunchトランザクションフローの一部として実行されます。トランザクションが確認された時点で、カーブにはすでに初回購入が適用されています。firstBuyAmountが省略または0の場合、初回購入は適用されず、任意のウォレットが最初のスワップを行うことができます。

トークンメタデータ {#token-metadata}

すべての発行には以下のフィールドを含むtokenオブジェクトが必要です。

token: {
  name: 'Agent Token',
  symbol: 'AGT',
  image: 'https://gateway.irys.xyz/your-image-id',
  description: 'The official token of my agent',
  externalLinks: {
    website: 'https://myagent.com',
    twitter: '@myagent',
  },
},

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

Devnetテスト {#devnet-testing}

network: 'solana-devnet'を渡し、UmiインスタンスをdevnetのRPCエンドポイントに向けることで、launchをdevnetインフラを通じてルーティングできます。

1const umi = createUmi('https://api.devnet.solana.com');
2umi.use(keypairIdentity(keypair));
3
4const result = await createAndRegisterLaunch(umi, {}, {
5  wallet: umi.identity.publicKey,
6  agent: {
7    mint: agentAssetAddress,
8    setToken: false, // devnetでのテスト時は誤ってロックしないようにfalseを使用する
9  },
10  launchType: 'bondingCurve',
11  network: 'solana-devnet',
12  token: {
13    name: 'Test Token',
14    symbol: 'TEST',
15    image: 'https://gateway.irys.xyz/test-image',
16  },
17  launch: {},
18});

エラー処理 {#error-handling}

SDKは異なる障害モードに対して型付きエラーを提供します。

1import {
2  createAndRegisterLaunch,
3  isGenesisApiError,
4  isGenesisApiNetworkError,
5  isGenesisValidationError,
6} from '@metaplex-foundation/genesis/api';
7
8try {
9  const result = await createAndRegisterLaunch(umi, {}, input);
10} catch (err) {
11  if (isGenesisValidationError(err)) {
12    console.error(`"${err.field}"のバリデーションエラー: ${err.message}`);
13  } else if (isGenesisApiNetworkError(err)) {
14    console.error('ネットワークエラー:', err.message);
15  } else if (isGenesisApiError(err)) {
16    console.error(`APIエラー (${err.statusCode}): ${err.message}`);
17    console.error('詳細:', err.responseBody);
18  } else {
19    throw err;
20  }
21}

注意事項

• createAndRegisterLaunchは内部で2回のAPI呼び出しを行います。createトランザクションが確認されたがregisterLaunchが失敗した場合、トークンはオンチェーンに存在しますがmetaplex.comには表示されません。このケースを処理するには、createLaunch + registerLaunchを手動署名フローで個別に使用してください
• launch.creatorFeeWalletを明示的に設定することでクリエイター手数料ウォレットを上書きできます — エージェントPDAより優先されます
• 初回購入はlaunch作成時に設定され、カーブがライブになった後に追加することはできません
• クリエイター手数料はスワップごとに転送されるのではなく、バケットに蓄積されます。パーミッションレスのclaimBondingCurveCreatorFeeV2（ボンディングカーブ）およびclaimRaydiumCreatorFeeV2（グラデュエーション後のRaydium）インストラクションで請求してください — スワップ統合ガイドを参照
• Metaplex APIはトランザクションを構築して未署名のまま返します。署名キーは常に呼び出し元が保持します

よくある質問

エージェントトークンとは何ですか？

エージェントトークンは、Genesisプロトコルを使用してエージェントのオンチェーンウォレットから発行されるトークンです。createAndRegisterLaunchにagentフィールドを渡すと、クリエイター手数料がエージェントのCore assetシグナーPDAに自動的にルーティングされ、エージェントがオンチェーンで実行できるようにlaunchトランザクションがCore executeインストラクションでラップされます。

エージェントトークンを発行する際、クリエイター手数料はどこに送られますか？

クリエイター手数料はエージェントのCore assetシグナーPDA（シード['mpl-core-execute', <agent_asset>]から導出）に自動的にルーティングされます。creatorFeeWalletを手動で設定する必要はなく、agentフィールドを渡すだけで十分です。launch.creatorFeeWalletを明示的に設定することで、手数料ウォレットを上書きすることもできます。

setTokenは取り消しできますか？

いいえ。setToken: trueを設定すると、発行されたトークンがエージェントのプライマリトークンとして永久に関連付けられます。これはトランザクションが確認された後、元に戻したり再割り当てしたりすることはできません。不確かな場合はsetToken: falseを設定し、トークンの関連付けを別途処理してください。

エージェントトークンの発行をdevnetで先にテストできますか？

はい。launchの入力にnetwork: 'solana-devnet'を渡し、Umiインスタンスをhttps://api.devnet.solana.comに向けてください。トランザクションを送信する前に、エージェントウォレットにdevnet SOLを補充してください。

エージェント発行で初回購入とクリエイター手数料を組み合わせることはできますか？

はい。agentフィールドと合わせてlaunchオブジェクトにfirstBuyAmountを設定してください。初回購入自体は手数料無料で、その購入にはプロトコル手数料もクリエイター手数料も課されません。クリエイター手数料はカーブ上のその後のすべてのスワップに通常通り適用されます。