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));

세 가지 통합 모드

SDK는 완전 자동부터 완전 수동까지, 런칭 생성을 위한 세 가지 모드를 제공합니다.

간편 모드 — createAndRegisterLaunch

가장 간단한 방식입니다. 하나의 함수 호출로 온체인 계정 생성, 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는 타입 가드 함수와 함께 세 가지 오류 타입을 제공합니다.

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