Royalties Plugin

The Royalties Plugin enforces creator royalties on secondary sales of Core Assets. It specifies the royalty percentage, creator split, and which programs (marketplaces) are allowed or denied from transferring the asset.

Summary

The Royalties Plugin is an authority-managed plugin that enforces royalties on Core Assets. Set a percentage (basis points), distribute to multiple creators, and optionally restrict which programs can transfer assets.

• Set royalties as basis points (500 = 5%)
• Split royalties between up to 5 creators
• Use allowlists/denylists to control marketplace access
• Apply at Asset level (individual) or Collection level (all assets)

Out of Scope

Token Metadata royalties (different system), royalty collection/distribution (handled by marketplaces), and legal enforcement of royalties.

Quick Start

Jump to: Add to Asset · Add to Collection · RuleSets · Update

1. Import addPlugin from @metaplex-foundation/mpl-core
2. Call with type: 'Royalties', basisPoints, creators, and ruleSet
3. Marketplaces read the plugin and enforce the royalty on sales

Works With

Arguments

Basis Points

The royalty percentage in hundredths of a percent.

Creators

The creators array defines who receives royalties and how they're split. Up to 5 creators are supported. Percentages must add up to 100.

import { publicKey } from '@metaplex-foundation/umi'
const creators = [
  { address: publicKey('11111111111111111111111111111111'), percentage: 80 },
  { address: publicKey('22222222222222222222222222222222'), percentage: 20 },
]

RuleSets

RuleSets control which programs can transfer Assets with royalties. Use them to enforce royalties by restricting transfers to compliant marketplaces.

None (No Restrictions)

Any program can transfer the asset. Royalties are advisory only.

import { ruleSet } from '@metaplex-foundation/mpl-core'
const rules = ruleSet('None')

Allowlist (Recommended for Enforcement)

Only programs on the list can transfer. Use this to restrict to royalty-compliant marketplaces.

import { publicKey } from '@metaplex-foundation/umi'
import { ruleSet } from '@metaplex-foundation/mpl-core'
const rules = ruleSet('ProgramAllowList', [
  [
    publicKey('M2mx93ekt1fmXSVkTrUL9xVFHkmME8HTUi5Cyc5aF7K'), // Magic Eden
    publicKey('TSWAPaqyCSx2KABk68Shruf4rp7CxcNi8hAsbdwmHbN'), // Tensor
  ],
])

Denylist

All programs can transfer except those on the list. Use to block known non-compliant marketplaces.

import { publicKey } from '@metaplex-foundation/umi'
import { ruleSet } from '@metaplex-foundation/mpl-core'
const rules = ruleSet('ProgramDenyList', [
  [
    publicKey('BadMarketplace111111111111111111111111111'),
  ],
])

Adding the Royalties Plugin to an Asset (Code Example)

import { publicKey } from '@metaplex-foundation/umi'
import { addPlugin, ruleSet } from '@metaplex-foundation/mpl-core'
const creator1 = publicKey('11111111111111111111111111111111')
const creator2 = publicKey('22222222222222222222222222222222')
await addPlugin(umi, {
  asset: assetAddress,
  plugin: {
    type: 'Royalties',
    basisPoints: 500, // 5%
    creators: [
      { address: creator1, percentage: 80 },
      { address: creator2, percentage: 20 },
    ],
    ruleSet: ruleSet('None'),
  },
}).sendAndConfirm(umi)

Adding the Royalties Plugin to a Collection (Code Example)

Collection-level royalties apply to all Assets in the Collection unless overridden at the Asset level.

import { publicKey } from '@metaplex-foundation/umi'
import { addCollectionPlugin, ruleSet } from '@metaplex-foundation/mpl-core'
const creator1 = publicKey('11111111111111111111111111111111')
const creator2 = publicKey('22222222222222222222222222222222')
await addCollectionPlugin(umi, {
  collection: collectionAddress,
  plugin: {
    type: 'Royalties',
    basisPoints: 500, // 5%
    creators: [
      { address: creator1, percentage: 80 },
      { address: creator2, percentage: 20 },
    ],
    ruleSet: ruleSet('None'),
  },
}).sendAndConfirm(umi)

Updating the Royalties Plugin on an Asset

Modify royalty percentage, creators, or ruleset on an existing Asset.

import { publicKey } from '@metaplex-foundation/umi'
import { updatePlugin, ruleSet } from '@metaplex-foundation/mpl-core'
await updatePlugin(umi, {
  asset: assetAddress,
  plugin: {
    type: 'Royalties',
    basisPoints: 750, // Updated to 7.5%
    creators: [
      { address: creator1, percentage: 60 },
      { address: creator2, percentage: 40 },
    ],
    ruleSet: ruleSet('ProgramAllowList', [[marketplace1, marketplace2]]),
  },
}).sendAndConfirm(umi)

Updating the Royalties Plugin on a Collection

import { publicKey } from '@metaplex-foundation/umi'
import { updateCollectionPlugin, ruleSet } from '@metaplex-foundation/mpl-core'
await updateCollectionPlugin(umi, {
  collection: collectionAddress,
  plugin: {
    type: 'Royalties',
    basisPoints: 600, // Updated to 6%
    creators: [
      { address: creator1, percentage: 70 },
      { address: creator2, percentage: 30 },
    ],
    ruleSet: ruleSet('None'),
  },
}).sendAndConfirm(umi)

Common Errors

Creator percentages must sum to 100

The creator percentage values don't add up to 100. Adjust the splits.

Authority mismatch

Only the plugin authority can update royalties. Ensure you're signing with the correct keypair.

Program not in allowlist

A transfer was blocked because the calling program isn't in the allowlist. Add the program or switch to a denylist/none ruleset.

Notes

• Asset-level royalties override Collection-level royalties
• Creator percentages must sum to exactly 100
• Use allowlists for strict enforcement, denylists for flexibility
• Royalty collection/distribution is handled by marketplaces, not the Core program

Quick Reference

Minimum Code

import { addPlugin, ruleSet } from '@metaplex-foundation/mpl-core'
await addPlugin(umi, {
  asset: assetAddress,
  plugin: {
    type: 'Royalties',
    basisPoints: 500,
    creators: [{ address: creatorAddress, percentage: 100 }],
    ruleSet: ruleSet('None'),
  },
}).sendAndConfirm(umi)

Basis Points Reference

FAQ

Are Core royalties enforced?

Yes, when using an allowlist ruleset. Only programs on the allowlist can transfer the asset, ensuring royalties are paid.

What's the difference between Core royalties and Token Metadata royalties?

Core royalties require the Royalties plugin at either asset or collection level, with optional enforcement via rulesets. Standard Token Metadata NFT royalties are advisory and rely on marketplace cooperation. pNFTs (programmable NFTs) also support ruleset-based enforcement similar to Core.

Can I have different royalties per asset in a collection?

Yes. Add the Royalties plugin to individual assets to override the collection-level setting.

How do marketplaces read royalties?

Marketplaces query the asset's plugins via DAS or on-chain data. The Royalties plugin data includes basis points, creators, and ruleset.

What happens if I don't set a ruleset?

Use ruleSet('None'). Any program can transfer the asset and royalties are advisory only.

Can I change royalties after minting?

Yes. Use updatePlugin (for assets) or updateCollectionPlugin (for collections) if you have the authority.

Glossary