internet-court/internet-court-skill / vendored/metaplex/metaplex
metaplex
VerifiedMetaplex development on Solana — NFTs, tokens, compressed NFTs, candy machines, token launches, autonomous agents. Use when working with Token Metadata, Core, Bubblegum, Candy Machine, Genesis, Agent Registry, or the mplx CLI.
| File | Kind | Size |
|---|---|---|
| LICENSE | other | 1.6 KB |
| SKILL.md | skill md | 9.7 KB |
| references/cli-agent.md | markdown | 8.8 KB |
| references/cli-bubblegum.md | markdown | 5.8 KB |
| references/cli-candy-machine.md | markdown | 10.2 KB |
| references/cli-config.md | markdown | 1.5 KB |
| references/cli-core.md | markdown | 8.9 KB |
| references/cli-genesis.md | markdown | 24.6 KB |
| references/cli-initial-setup.md | markdown | 2.7 KB |
| references/cli-token-metadata.md | markdown | 3.3 KB |
| references/cli-toolbox.md | markdown | 4.3 KB |
| references/cli-troubleshooting.md | markdown | 2.2 KB |
| references/cli.md | markdown | 5.4 KB |
| references/concepts.md | markdown | 12.0 KB |
| references/metadata-json.md | markdown | 1.8 KB |
| references/sdk-agent.md | markdown | 21.7 KB |
| references/sdk-bubblegum.md | markdown | 11.3 KB |
| references/sdk-core.md | markdown | 20.5 KB |
| references/sdk-genesis-low-level.md | markdown | 21.7 KB |
| references/sdk-genesis.md | markdown | 24.4 KB |
| references/sdk-token-metadata-kit.md | markdown | 8.4 KB |
| references/sdk-token-metadata.md | markdown | 13.7 KB |
| references/sdk-umi.md | markdown | 6.1 KB |
references/cli-candy-machine.md
View on GitHub# Core Candy Machine CLI Reference
Candy Machine enables NFT drops with configurable minting rules (guards).
> **Prerequisites**: CLI must be configured (RPC, keypair, funded wallet). If not yet verified this session, see `./cli-initial-setup.md`.
---
## Directory Structure
```
my-candy-machine/
├── assets/
│ ├── 0.png # Image for NFT #0
│ ├── 0.json # Metadata for NFT #0
│ ├── 1.png
│ ├── 1.json
│ ├── 2.png
│ ├── 2.json
│ ├── ...
│ ├── collection.png # Collection image (required)
│ └── collection.json # Collection metadata (must have "name" field)
├── asset-cache.json # Generated after upload
└── cm-config.json # Generated by wizard or created manually
```
**Asset naming**: Files must be numbered starting from 0 (0.png, 0.json, 1.png, 1.json, etc.)
**collection.json example** (follows the NFT metadata standard — see `metadata-json.md`; use relative image path, CM CLI replaces with uploaded URI):
```json
{
"name": "My Collection",
"description": "A collection of NFTs",
"image": "collection.png",
"external_url": "https://yourproject.com",
"attributes": [],
"properties": {
"files": [{ "uri": "collection.png", "type": "image/png" }],
"category": "image"
}
}
```
**Individual asset JSON example** (0.json, 1.json, etc. — same standard, see `metadata-json.md`):
```json
{
"name": "NFT #0",
"description": "Description here",
"image": "0.png",
"external_url": "https://yourproject.com",
"attributes": [
{ "trait_type": "Background", "value": "Blue" }
],
"properties": {
"files": [{ "uri": "0.png", "type": "image/png" }],
"category": "image"
}
}
```
---
## Workflow Option 1: Wizard (Recommended)
```bash
mplx cm create --wizard
```
The wizard handles everything:
1. Validates assets and configuration
2. Uploads all assets with progress tracking
3. Creates the candy machine on-chain
4. Inserts all items with transaction progress
5. Provides completion summary with links
---
## Workflow Option 2: Manual
```bash
# 1. Create template directory structure
mplx cm create --template
# 2. Add your assets to the assets/ folder
# - 0.png, 0.json, 1.png, 1.json, etc.
# - collection.png, collection.json
# 3. Create a Core collection for the candy machine
mplx core collection create
# 4. Edit cm-config.json: add the collection address, configure guards, etc.
# The "collection" field MUST contain a valid Core collection address.
# 5. Upload assets to storage
mplx cm upload
# 6. Create candy machine (reads cm-config.json)
mplx cm create
# 7. Insert items into candy machine
mplx cm insert
# 8. Validate (optional but recommended)
mplx cm validate --onchain
```
> **Note:** You MUST create a Core collection first (e.g. with `mplx core collection create`) and add its address to the `"collection"` field in `cm-config.json` before running `mplx cm create`. The CLI does NOT create the collection automatically — it will error if no collection address is provided.
---
## Commands Reference
```bash
mplx cm create --wizard # Interactive wizard (does everything)
mplx cm create --template # Create template directory
mplx cm create <DIR> # Create from existing cm-config.json
mplx cm upload <DIR> # Upload assets to storage
mplx cm insert <DIR> # Insert items into candy machine
mplx cm validate <DIR> # Validate uploads
mplx cm validate <DIR> --onchain # Validate items inserted on-chain
mplx cm fetch <ADDR> # Fetch candy machine info
mplx cm fetch <ADDR> --items # Fetch with all items
mplx cm withdraw # Withdraw from CM directory (reads cm-config.json)
mplx cm withdraw <DIR> # Withdraw and delete (recovers rent)
mplx cm withdraw --address <ADDR> # Withdraw by address
```
---
## Guards Configuration
Guards control who can mint, when, and at what cost.
### Available Guards
| Category | Guards |
|----------|--------|
| **Payment** | `solPayment`, `solFixedFee`, `tokenPayment`, `token2022Payment`, `nftPayment`, `assetPayment`, `assetPaymentMulti` |
| **Access Control** | `addressGate`, `allowList`, `nftGate`, `tokenGate`, `assetGate`, `programGate`, `thirdPartySigner` |
| **Time-Based** | `startDate`, `endDate` |
| **Limits** | `mintLimit`, `allocation`, `nftMintLimit`, `assetMintLimit`, `redeemedAmount` |
| **Burn Guards** | `nftBurn`, `tokenBurn`, `assetBurn`, `assetBurnMulti` |
| **Special** | `botTax`, `edition`, `vanityMint` |
| **Freeze** | `freezeSolPayment`, `freezeTokenPayment` |
### cm-config.json Example
The config uses a nested `name/directory/config` wrapper format:
```json
{
"name": "my-candy-machine",
"directory": "/path/to/my-candy-machine",
"config": {
"collection": "<COLLECTION_ADDRESS>",
"itemsAvailable": 10,
"isMutable": true,
"isSequential": false,
"guardConfig": {
"solPayment": {
"lamports": 1000000000,
"destination": "<PAYMENT_WALLET>"
},
"startDate": {
"date": "2024-01-01T00:00:00Z"
},
"mintLimit": {
"id": 1,
"limit": 1
},
"botTax": {
"lamports": 10000000,
"lastInstruction": true
}
},
"groups": []
}
}
```
Key fields: `itemsAvailable` (not `number`), `collection` (must be set before `mplx cm create`). `sellerFeeBasisPoints` is set at the collection level (when creating the Core collection), not in the candy machine config.
### Guard Groups (Multiple Minting Phases)
Use `groups` instead of `guardConfig` to create separate minting phases (e.g., whitelist then public). Set `guardConfig: {}` when using groups.
```json
"groups": [
{
"label": "wl",
"guards": {
"allowList": {
"merkleRoot": "<MERKLE_ROOT_HASH>"
},
"solPayment": {
"lamports": 500000000,
"destination": "<PAYMENT_WALLET>"
},
"startDate": {
"date": "2024-01-01T00:00:00Z"
}
}
},
{
"label": "public",
"guards": {
"solPayment": {
"lamports": 1000000000,
"destination": "<PAYMENT_WALLET>"
},
"startDate": {
"date": "2024-01-02T00:00:00Z"
}
}
}
]
```
---
## Common Guard Configurations
### SOL Payment
```json
"solPayment": {
"lamports": 1000000000,
"destination": "<WALLET_ADDRESS>"
}
```
Note: 1 SOL = 1,000,000,000 lamports
### Start/End Date
```json
"startDate": {
"date": "2024-01-01T00:00:00Z"
},
"endDate": {
"date": "2024-01-31T23:59:59Z"
}
```
### Mint Limit (per wallet)
```json
"mintLimit": {
"id": 1,
"limit": 3
}
```
### Allow List (whitelist)
```json
"allowList": {
"merkleRoot": "<MERKLE_ROOT_HASH>"
}
```
To generate the Merkle root from a list of wallet addresses, use the Umi SDK:
```typescript
import { getMerkleRoot } from '@metaplex-foundation/mpl-core-candy-machine';
const merkleRoot = getMerkleRoot(['Addr1...', 'Addr2...']);
const merkleRootHex = Buffer.from(merkleRoot).toString('hex');
```
When minting with an allowlist, the minter must provide a Merkle proof (see Minting section below).
### Bot Tax
```json
"botTax": {
"lamports": 10000000,
"lastInstruction": true
}
```
Charges failed mints to deter bots.
---
## Withdrawing
After all items are minted (or to cancel):
```bash
# From directory with cm-config.json
mplx cm withdraw
# Or by address
mplx cm withdraw --address <CANDY_MACHINE_ADDRESS>
# Force without confirmation
mplx cm withdraw --force
```
⚠️ **WARNING**: Withdrawing permanently deletes the candy machine. Non-redeemed items are lost.
---
## Minting from a Candy Machine
The CLI **creates and configures** candy machines but does not have a mint command. Minting requires the Umi SDK (`@metaplex-foundation/mpl-core-candy-machine`).
- **Frontend app** — Build a minting UI with the Umi SDK
- **Script** — Mint programmatically with `mintV1` from the SDK
See `./sdk-umi.md` for Umi setup and the [Candy Machine documentation](https://metaplex.com/docs/smart-contracts/core-candy-machine/guards) for minting code examples and guard-specific mint args.
---
## Localnet Limitations
The `mplx cm upload` step requires Irys storage and **will not work on localnet**. For localnet testing, you can skip the upload step by manually creating an `asset-cache.json` file with pre-populated URIs:
```json
{
"assetItems": {
"0": {
"name": "My NFT #0",
"image": "0.png",
"json": "0.json",
"loaded": false,
"onChain": false,
"imageType": "image/png",
"imageUri": "https://example.com/0.png",
"jsonUri": "https://example.com/0.json"
}
}
}
```
With this cache in place, you can proceed directly to `mplx cm create` and `mplx cm insert`.
---
## Best Practices
1. **Test on devnet first** before mainnet deployment
2. **Validate assets** before uploading: consistent naming (0.png, 0.json, etc.)
3. **Keep file sizes reasonable** (< 10MB per image recommended)
4. **Include collection.json** with a valid "name" field
5. **Add at least one guard** (otherwise anyone can mint for free)
6. **Save explorer links** for verification
7. **Back up cm-config.json** after creation
## For more info
Consult these Metaplex docs when you need deeper detail than this reference provides:
- Core Candy Machine: https://metaplex.com/docs/smart-contracts/core-candy-machine
- Overview: https://metaplex.com/docs/smart-contracts/core-candy-machine/overview
- Create: https://metaplex.com/docs/smart-contracts/core-candy-machine/create
- Insert items: https://metaplex.com/docs/smart-contracts/core-candy-machine/insert-items
- Guards: https://metaplex.com/docs/smart-contracts/core-candy-machine/guards
- Guard groups: https://metaplex.com/docs/smart-contracts/core-candy-machine/guard-groups
- Mint: https://metaplex.com/docs/smart-contracts/core-candy-machine/mint
- Preparing assets: https://metaplex.com/docs/smart-contracts/core-candy-machine/preparing-assets
- Withdrawing: https://metaplex.com/docs/smart-contracts/core-candy-machine/withdrawing-a-candy-machine
- Anti-bot best practices: https://metaplex.com/docs/smart-contracts/core-candy-machine/anti-bot-protection-best-practices
- CLI Candy Machine: https://metaplex.com/docs/dev-tools/cli/cm
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 472k | Updated | Claude CodeCodex | Unverified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |