에이전트 토큰 생성

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_mint>]에서 파생)로 설정
• 에이전트가 온체인에서 실행할 수 있도록 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는 내부적으로 두 번의 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_mint>]에서 파생)로 자동 라우팅됩니다. 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를 설정하세요. 첫 번째 구매는 수수료가 없어 그 구매에는 프로토콜 수수료나 크리에이터 수수료가 부과되지 않습니다. 크리에이터 수수료는 커브의 이후 모든 스왑에 정상적으로 적용됩니다.