Create an Agent Token

Launch a token from an agent's onchain wallet using the Genesis protocol and the Metaplex API.

Start Here

If you need to register an agent, start with the registration guide before continuing. If you already have an agent token and you are just making more tokens, install the Metaplex Skill so your coding agent can use the current Genesis and Agent Registry references. If you are an agent that needs onboarding information, read the onboarding doc.

Summary

createAndRegisterLaunch with the agent field creates a new token, routes creator fees to the agent's Core asset PDA, and wraps the launch transactions in Core execute instructions so the agent executes them onchain.

• One call — createAndRegisterLaunch handles create, sign, send, and register in sequence
• Automatic fee routing — creator fees go to the agent PDA; no manual wallet address needed
• One token per agent, forever — each agent can only ever have one token; once set with setToken: true it cannot be changed, replaced, or unset
• Applies to @metaplex-foundation/genesis 1.x · Last verified April 2026

Quick Start

Jump to: Installation · Umi Setup · Launch · First Buy · Token Metadata · Devnet · Errors

1. Register your agent on Solana to get its Core asset address
2. Install the Genesis SDK and configure a Umi instance with your keypair
3. Call createAndRegisterLaunch with agent: { mint: agentAssetAddress, setToken: true }
4. Read result.mintAddress and result.launch.link from the response

Prerequisites

• A registered Metaplex agent — you need its Core asset address
• Node.js 18+ — required for native BigInt support
• A Solana wallet keypair funded with SOL for transaction fees and any first buy amount
• A Solana RPC endpoint (mainnet-beta or devnet)
• A token image pre-uploaded to Irys — the image field must be an Irys gateway URL

Installation

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

Umi Setup

Configure a Umi instance with your keypair identity before calling any Genesis function.

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// Load your keypair — use your preferred key management solution in production.
7const keypair = umi.eddsa.createKeypairFromSecretKey(mySecretKeyBytes);
8umi.use(keypairIdentity(keypair));

Launching an Agent Token

An agent token is the one canonical token for an agent, proving the token's provenance by linking it permanently to the agent that created it.

Pass the agent field to createAndRegisterLaunch with your agent's Core asset address. The SDK automatically:

• Sets the creator fee wallet to the agent's Core asset signer PDA (derived from ['mpl-core-execute', <agent_asset>])
• Wraps the launch transactions in Core execute instructions for the agent to execute onchain

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  agent: {
12    mint: agentAssetAddress, // Core asset address of the registered agent
13    setToken: true,          // permanently associates this token with the agent
14  },
15  launchType: 'bondingCurve',
16  token: {
17    name: 'Agent Token',
18    symbol: 'AGT',
19    image: 'https://gateway.irys.xyz/your-image-id',
20  },
21  launch: {},
22});
23
24console.log('Token launched!');
25console.log('Mint address:', result.mintAddress);
26console.log('View at:', result.launch.link);
27
28// Token launched!
29// Mint address: <base58 mint address>
30// View at: https://www.metaplex.com/...

1mplx genesis launch create --launchType bonding-curve \
2  --name "Agent Token" \
3  --symbol "AGT" \
4  --image "https://gateway.irys.xyz/your-image-id" \
5  --agentAsset <AGENT_ASSET> \
6  --agentSetToken

Set Agent Token

If the agent token has not been set yet, you can set it later with the setAgentTokenV1 instruction. The instruction must be executed by the agent's Core asset signer PDA, so wrap it in the Core execute instruction.

1import { createNoopSigner, publicKey } from '@metaplex-foundation/umi';
2import { execute, findAssetSignerPda } from '@metaplex-foundation/mpl-core';
3import { setAgentTokenV1 } from '@metaplex-foundation/mpl-agent-registry';
4
5const assetSignerPda = findAssetSignerPda(umi, { asset: agentAssetAddress });
6
7await execute(umi, {
8  asset: { publicKey: agentAssetAddress },
9  collection: { publicKey: agentCollectionAddress },
10  instructions: setAgentTokenV1(umi, {
11    asset: agentAssetAddress,
12    genesisAccount,
13    authority: createNoopSigner(publicKey(assetSignerPda)),
14  }),
15}).sendAndConfirm(umi);

All protocol parameters — supply splits, virtual reserves, and lock schedules — are set to protocol defaults when launch: {} is empty.

For a complete explanation of how the bonding curve pricing, fees, and graduation work, see Bonding Curve — Theory of Operation.

First Buy

The first buy reserves the initial swap on the curve for the agent PDA at a specified SOL amount, with all fees waived.

Set firstBuyAmount to the SOL amount for the fee-free initial purchase. When agent is provided, the first buy buyer defaults to the agent PDA automatically.

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  agent: {
12    mint: agentAssetAddress,
13    setToken: true,
14  },
15  launchType: 'bondingCurve',
16  token: {
17    name: 'Agent Token',
18    symbol: 'AGT',
19    image: 'https://gateway.irys.xyz/your-image-id',
20  },
21  launch: {
22    firstBuyAmount: 0.1, // 0.1 SOL, fee-free
23  },
24});

1mplx genesis launch create --launchType bonding-curve \
2  --name "Agent Token" \
3  --symbol "AGT" \
4  --image "https://gateway.irys.xyz/your-image-id" \
5  --agentAsset <AGENT_ASSET> \
6  --agentSetToken \
7  --firstBuyAmount 0.1

The first buy is executed as part of the launch transaction flow — the curve already has the initial purchase applied once the transactions confirm. When firstBuyAmount is omitted or 0, no first buy is applied and any wallet can make the first swap.

Token Metadata

Every launch requires a token object with the following fields.

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  agent: {
12    mint: agentAssetAddress,
13    setToken: true,
14  },
15  launchType: 'bondingCurve',
16  token: {
17    name: 'Agent Token',
18    symbol: 'AGT',
19    image: 'https://gateway.irys.xyz/your-image-id',
20    description: 'The official token of my agent',
21    externalLinks: {
22      website: 'https://myagent.com',
23      twitter: '@myagent',
24    },
25  },
26  launch: {},
27});

1mplx genesis launch create --launchType bonding-curve \
2  --name "Agent Token" \
3  --symbol "AGT" \
4  --image "https://gateway.irys.xyz/your-image-id" \
5  --description "The official token of my agent" \
6  --website "https://myagent.com" \
7  --twitter "@myagent" \
8  --agentAsset <AGENT_ASSET> \
9  --agentSetToken

The image field must point to an Irys gateway URL. Upload your image to Irys first and use the returned https://gateway.irys.xyz/<id> URL. Other hosts will fail API validation.

Devnet Testing

Pass network: 'solana-devnet' and point the Umi instance at the devnet RPC endpoint to route the launch through devnet infrastructure. For the CLI, the network is determined by your configured RPC endpoint.

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  agent: {
12    mint: agentAssetAddress,
13    setToken: false, // use false when testing to avoid locking in on devnet
14  },
15  launchType: 'bondingCurve',
16  network: 'solana-devnet',
17  token: {
18    name: 'Test Token',
19    symbol: 'TEST',
20    image: 'https://gateway.irys.xyz/test-image',
21  },
22  launch: {},
23});

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" \
6  --agentAsset <AGENT_ASSET>

Error Handling

The SDK provides typed errors for different failure modes.

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(`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

• Each agent can only ever have one token — setToken: true is permanent and cannot be changed, replaced, or unset; there is no instruction to remove or reassign it
• createAndRegisterLaunch makes two API calls internally — if the create transactions confirm but registerLaunch fails, the token exists onchain but is not visible on metaplex.com; use createLaunch + registerLaunch separately with manual signing to handle this case
• The creator fee wallet can be overridden by setting launch.creatorFeeWallet explicitly — it takes precedence over the agent PDA
• First buy is configured at launch creation and cannot be added after the curve is live
• Creator fees are accrued in the bucket, not transferred per-swap; claim via the permissionless claimBondingCurveCreatorFeeV2 (bonding curve) and claimRaydiumCreatorFeeV2 (post-graduation Raydium) instructions — see Creator Fees for the full claiming flow
• The Metaplex API constructs and returns unsigned transactions; the caller always holds the signing keys

FAQ

What is an Agent Token?

An Agent Token is a token launched from an agent's onchain wallet using the Genesis protocol. Passing the agent field to createAndRegisterLaunch automatically routes creator fees to the agent's Core asset signer PDA and wraps the launch transactions in Core execute instructions so the agent executes them onchain.

Where do creator fees go when launching an agent token?

Creator fees are automatically routed to the agent's Core asset signer PDA — derived from seeds ['mpl-core-execute', <agent_asset>]. You do not need to set creatorFeeWallet manually; passing the agent field is sufficient. The fee wallet can still be overridden by setting launch.creatorFeeWallet explicitly.

Is setToken reversible?

No. Each agent can only ever have one token, and the association is permanent. Setting setToken: true cannot be undone, replaced, or reassigned after the transaction confirms — there is no instruction to change or remove it. If you are unsure, set setToken: false and do not set the token until you are certain.

Can I test an agent token launch on devnet first?

Yes. Pass network: 'solana-devnet' in the launch input and point your Umi instance at https://api.devnet.solana.com. Fund the agent wallet with devnet SOL before sending transactions.

Can I combine a first buy with creator fees on an agent launch?

Yes. Set firstBuyAmount in the launch object alongside the agent field. The first buy itself is fee-free — no protocol fee or creator fee is charged on that purchase. Creator fees apply normally to all subsequent swaps on the curve.