# Metaplex Agent Onboarding

You are an autonomous agent onboarding to the **Metaplex Agent Registry** on Solana. This guide walks you through installing the tools, creating your wallet, registering your on-chain identity, and activating your agent wallet — all in a few commands.

**Networks**: `solana-devnet` (testing) or `solana-mainnet` (production). Devnet is for testing but mainnet is the real one.

Before starting, ask the user which network they want to use. If they don't specify, default to **devnet**.

---

## Step 1: Install Metaplex CLI

Check if you have the Metaplex CLI installed already:

```bash
mplx --version
```

If not install the Metaplex CLI globally:

```bash
npm install -g @metaplex-foundation/cli
```

Verify the installation:

```bash
mplx --version
```

Then configure the RPC based on the network chosen at the start:

**If devnet:**

```bash
mplx config rpcs set devnet
```

**If mainnet:**

Ask the user for their mainnet RPC endpoint URL (e.g., from Helius, Triton, or QuickNode). Do not guess or use a default — mainnet requires a dedicated RPC.

```bash
mplx config rpcs add mainnet <RPC_ENDPOINT>
mplx config rpcs set mainnet
```

---

## Step 2: Create & Fund Your Wallet

Create a wallet — this keypair pays transaction fees and owns your agent asset:

```bash
mplx config wallets new --name main --json
```

The CLI outputs the wallet's public key. Ask the user to fund it with at least **0.2 SOL** — this covers registration fees (~0.01 SOL), agent wallet funding (0.1 SOL transferred in Step 4), and ongoing transaction fees.

If you are using the default devnet rpc address `https://api.devnet.solana.com` don't try and use any airdrop commands as the faucet will most likely be empty.

If you have the ability to **Display a QR code** for your operator to scan with any Solana wallet app (Phantom, Solflare, etc.):

Generate the QR Code image and show the link for the user to open it. The Solana Pay URI pre-fills the recipient and amount — the operator just confirms.

Alternatively, just send the wallet address to the user and ask them to fund it.

Before proceeding to Step 3, verify the wallet has been funded:

```bash
mplx toolbox sol balance --json
```

Wait until the balance is at least 0.2 SOL before continuing.

---

## Step 3: Register Your Agent

A single command creates your Core asset (identity NFT), uploads your metadata, and registers your Agent Identity on-chain.

Ask the user for an image to use as your agent avatar — this can be a local file path (e.g. `/path/to/avatar.png`) or an existing URL. If they don't have one, omit the `--image` flag.

```bash
mplx agents register --new \
  --name "My Agent" \
  --description "What my agent does" \
  --image "/<local_file_or_url>" \
  --json
```

If the user has service endpoints to advertise (e.g., MCP), add `--services` with a JSON array:

```bash
mplx agents register --new \
  --name "My Agent" \
  --description "What my agent does" \
  --image "/<local_file_or_url>" \
  --services '[{"name":"MCP","endpoint":"https://myagent.com/mcp"}]' \
  --json
```

**Required parameters:**

| Parameter       | Description                                     |
| --------------- | ----------------------------------------------- |
| `--name`        | Your agent's display name                       |
| `--description` | What your agent does                            |
| `--image`       | Path to a local file (uploaded) or an image URL |

**Optional parameters:**

| Parameter           | Description                                                                |
| ------------------- | -------------------------------------------------------------------------- |
| `--services`        | JSON array of service endpoints (name, endpoint, version, skills, domains) |
| `--supported-trust` | JSON array of trust models (e.g. `'["reputation","tee-attestation"]'`)     |
| `--collection`      | Collection address if this agent belongs to a collection                   |
| `--save-document`   | Save the generated registration JSON to a local file                       |

**Alternative: interactive wizard:**

```bash
mplx agents register --new --wizard
```

**Alternative: from a pre-built JSON document:**

```bash
mplx agents register --new --from-file "./agent-registration.json"
```

Under the hood, this:

1. Uploads your registration metadata to Irys
2. Creates a Core asset with your name and metadata URI
3. Registers an `AgentIdentityV1` on-chain linking the asset to your metadata

> **If registration fails:** Check whether a Core asset was already created by looking at the error output or your wallet's recent transactions. If the asset exists but registration didn't complete, re-run `mplx agents register <AGENT_ASSET> --use-ix` with the existing asset address instead of `--new` to avoid creating a duplicate.

After confirmation, the CLI outputs your **Agent Asset** address in the JSON response (`agentAsset` field). Save it — you'll need it in the next step.

### Verify Registration and Retrieve Agent Wallet

The `register` command returns your `agentAsset` but not your `agentWallet`. Run `agents fetch` to retrieve both:

```bash
mplx agents fetch <AGENT_ASSET> --json
```

From the `agents fetch` output, save both:

- **`agentAsset`** — your agent's unique on-chain identity (same as the register output)
- **`agentWallet`** — your agent's operational wallet address (Asset Signer PDA), needed in Step 4

---

## Step 4: Activate & Fund Your Agent Wallet

Register your agent's wallet as a CLI wallet, fund it from your main wallet, and switch to it:

```bash
mplx config wallets add agent --agent <AGENT_ASSET> --json
mplx toolbox sol transfer 0.1 <AGENT_WALLET> --json  # agentWallet value from mplx agents fetch --json in Step 3
mplx config wallets set agent
```

That's it — one external funding transaction in Step 3, and the main wallet handles everything from there. The CLI now routes all commands through your agent's PDA, with your `main` wallet automatically signing the underlying execute instructions and paying fees.

**Verify it works:**

```bash
mplx toolbox sol balance --json
mplx core asset execute info <AGENT_ASSET> --json
```

### Override Behavior

You can override the active wallet for a single command:

```bash
# Use a specific keypair for one command
mplx toolbox sol balance -k /path/to/wallet.json --json

# Use a different fee payer
mplx toolbox sol transfer 0.01 <dest> -p /path/to/payer.json --json
```

---

## Step 5: Delegate Execution (Optional)

Ask the user if they want to delegate execution to a separate wallet (e.g., an executor service that submits transactions on behalf of your agent).

If yes, run:

```bash
# One-time: register the executor's profile
mplx agents executive register --json

# Link your agent to the executor
mplx agents executive delegate <AGENT_ASSET> --executive <EXECUTOR_WALLET_ADDRESS> --json
```

This creates a verifiable on-chain delegation — other agents and services can confirm the executor is authorized to act on your behalf.

---

## Step 6: Create an Agent Token

Ask the user if they want to create an Agent Token. If yes, ask which launch type they prefer: **LaunchPool** or **Bonding Curve**.

Ensure the agent wallet is active before proceeding:

```bash
mplx config wallets set agent
```

### Upload a Token Image

Ask the user for a token image — this can be a local file path or an existing URL.

**If a local file:**

```bash
mplx toolbox storage upload /path/to/token-image.png --json
# Returns: https://gateway.irys.xyz/<HASH>
```

Save the returned `https://gateway.irys.xyz/<HASH>` URL — you'll pass it as `--image` below.

**If the user provides an existing URL**, use it directly as `--image`.

**If no image is provided**, ask the user to supply one before continuing — the `--image` flag is required for both launch types.

### Option A: LaunchPool (`--launchType launchpool`)

A LaunchPool opens a **48-hour deposit window** where participants deposit SOL (or USDC) toward a raise goal. After the window closes, the token graduates to Raydium with liquidity. You control the token allocation, raise goal, and how raised funds are split between Raydium LP and your wallet.

```bash
mplx genesis launch create \
  --launchType launchpool \
  --name "My Token" \
  --symbol "MTKN" \
  --image "https://gateway.irys.xyz/<HASH>" \
  --tokenAllocation 500000000 \
  --depositStartTime "<YYYY-MM-DDTHH:MM:SSZ>" \
  --raiseGoal 200 \
  --raydiumLiquidityBps 5000 \
  --fundsRecipient <AGENT_WALLET> \
  --json
```

**Required flags:**

| Flag                    | Description                                                                                                                      |
| ----------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| `--name`                | Token name (1-32 characters)                                                                                                     |
| `--symbol`              | Token symbol (1-10 characters)                                                                                                   |
| `--image`               | Token image URL (must be `https://gateway.irys.xyz/...`)                                                                         |
| `--depositStartTime`    | Deposit start time — must be a **future** UTC timestamp in ISO 8601 format: `YYYY-MM-DDTHH:MM:SSZ` (e.g. `2026-05-01T12:00:00Z`) |
| `--tokenAllocation`     | Tokens allocated to the launch pool (50M-500M of 1B total supply)                                                                |
| `--raiseGoal`           | Raise goal in whole units (e.g., 200 for 200 SOL). Min: 250 SOL or 25,000 USDC                                                   |
| `--raydiumLiquidityBps` | Percentage of raised funds that go to Raydium LP, in basis points (2000-10000, i.e. 20%-100%)                                    |
| `--fundsRecipient`      | Wallet address that receives the unlocked portion of raised funds — set this to your agent PDA                                   |

**Optional flags:**

| Flag                  | Description                                            |
| --------------------- | ------------------------------------------------------ |
| `--description`       | Token description (max 250 characters)                 |
| `--quoteMint`         | Quote mint: `SOL` (default), `USDC`, or a mint address |
| `--lockedAllocations` | Path to JSON file with locked allocation configs       |
| `--website`           | Project website URL                                    |
| `--twitter`           | Project Twitter URL                                    |
| `--telegram`          | Project Telegram URL                                   |

Set `--fundsRecipient` to your agent's PDA address so raised funds flow directly to your operational wallet.

### Option B: Bonding Curve (`--launchType bonding-curve`)

A Bonding Curve launch starts trading immediately on a constant-product AMM curve. As buyers purchase tokens the price rises along the curve. When the curve fills, 100% of proceeds graduate to a Raydium LP — no deposit window, no raise goal needed.

```bash
mplx genesis launch create \
  --launchType bonding-curve \
  --name "My Token" \
  --symbol "MTKN" \
  --image "https://gateway.irys.xyz/<HASH>" \
  --json
```

**Required flags:**

| Flag       | Description                                              |
| ---------- | -------------------------------------------------------- |
| `--name`   | Token name (1-32 characters)                             |
| `--symbol` | Token symbol (1-10 characters)                           |
| `--image`  | Token image URL (must be `https://gateway.irys.xyz/...`) |

**Optional flags:**

| Flag               | Description                                                    |
| ------------------ | -------------------------------------------------------------- |
| `--description`    | Token description (max 250 characters)                         |
| `--firstBuyAmount` | Amount of SOL for an optional initial buy (e.g., 0.69, max 85) |
| `--website`        | Project website URL                                            |
| `--twitter`        | Project Twitter URL                                            |
| `--telegram`       | Project Telegram URL                                           |

> **Note:** Bonding curves only support SOL as the quote token.

After creation the CLI outputs the launch address. Verify it is live:

```bash
mplx genesis launch fetch <LAUNCH_ADDRESS> --json
```

---

## You're Operational

Your agent now has:

| Asset                | Purpose                                         |
| -------------------- | ----------------------------------------------- |
| **Agent Asset**      | Your unique on-chain identity                   |
| **Agent Wallet**     | Your operational wallet — all commands use this |
| **Main Wallet**      | Owns the asset, signs executions, pays fees     |
| **Registration URI** | Where other agents discover your capabilities   |

All `mplx` commands work transparently through your agent PDA:

```bash
mplx toolbox sol balance --json                          # PDA balance
mplx toolbox sol transfer 0.01 <dest> --json             # send SOL from PDA
mplx toolbox token transfer <mint> 100 <dest> --json     # send tokens from PDA
mplx core asset create --name "NFT" --uri "..." --json   # PDA is the creator
mplx core asset transfer <assetId> <newOwner> --json     # transfer PDA-owned assets
```

Your registration metadata is publicly accessible. Other agents and services use it to discover what services you offer, whether you support x402 payments, and whether you are active.

---

## What You Can Ask Me To Do

Now that I'm fully set up, here's what you can ask me to do at any time:

**Tokens & Launches**

- Launch a token with a LaunchPool (48-hour deposit window, raise goal, Raydium graduation)
- Launch a token on a Bonding Curve (instant trading, no raise goal needed)
- Check the status of an existing token launch

**NFTs & Collections**

- Create an NFT collection
- Mint NFTs into a collection (from a URL or local files)
- Transfer, update, or burn NFTs I own

**Wallet & Funds**

- Check my SOL or token balances
- Send SOL or tokens to any address
- Show my wallet addresses (main and agent PDA)

**Storage**

- Upload images or metadata files to permanent storage (Irys) and return the URL

**Identity**

- Fetch and display my on-chain agent registration
- Update my agent metadata

Just tell me what you want and I'll handle it.

---

## Concepts

### Main Wallet

A standard Solana keypair that owns your agent's Core asset. It signs the execute instructions that authorize your PDA to act, and pays transaction fees.

### Agent Wallet

Each Core asset has a derived **Asset Signer PDA** — referred to as the `agentWallet` in CLI output. It is a wallet address that only the asset's owner can authorize via CPI. When you set the agent wallet as active in the CLI, all commands automatically build transactions with the PDA as the authority and wrap them in execute instructions signed by your main wallet.

### mpl-core Asset

Your agent NFT is a [Metaplex Core](https://developers.metaplex.com/core) asset — a lightweight, single-account NFT on Solana. It stores your name, description, and metadata URI on-chain.

### Agent Identity PDA

The `AgentIdentityV1` account is a Program Derived Address (PDA) created by the `mpl-agent-registry` program. It links your Core asset to your `agentRegistrationUri`, making your identity discoverable on-chain.

### EIP-8004

The [EIP-8004 Agent Registration](https://eips.ethereum.org/EIPS/eip-8004) standard defines a common JSON format for describing agent capabilities, services, and trust mechanisms. Your metadata follows this spec so other agents and platforms can interoperate with you.

---

## Troubleshooting

| Problem                         | Solution                                                                      |
| ------------------------------- | ----------------------------------------------------------------------------- |
| `mplx: command not found`       | Run `npm install -g @metaplex-foundation/cli`                                 |
| Registration transaction failed | Ensure sufficient SOL in the main wallet — see error recovery note in Step 3  |
| Agent not appearing in registry | Wait a few seconds for on-chain confirmation, then retry `mplx agents fetch`  |
| Asset owner not in wallets      | When adding an agent wallet, the asset's owner must already be a saved wallet |