To add NFT royalties in a Sui marketplace, you must build the royalty system yourself directly into your smart contract. Sui doesn't have a built-in standard for this.

Here’s a simple breakdown:

Add Royalty Info to the NFT: You must include the original creator's wallet address and the royalty percentage (e.g., 5%) as part of the NFT's data.

Code the Logic: Your smart contract's "buy" function must be written to automatically split the payment. When a sale occurs, the contract calculates the royalty fee from the sale price.

Enforce the Payment: The contract first sends the royalty cut to the original creator, then sends the remaining amount to the seller, and finally transfers the NFT to the buyer.

Sui's design makes this process very secure because the entire transaction—royalty payment, seller payment, and NFT transfer—is atomic, meaning it all happens at once or not at all. This prevents buyers or sellers from skipping the royalty fee.

On Sui, to make sure NFT creators get paid a royalty when their NFT is resold, you have to build that rule directly into your smart contract. Sui doesn't have a built-in royalty system like some other blockchains, so you need to code it yourself.

Here's the basic idea:

Attach Royalty Info to the NFT: Inside your NFT's code, you'll add a section that says who gets the royalty (the "recipient's" address) and what percentage they get.

// This defines what a royalty looks like:
struct Royalty {
    recipient: address, // Who gets the royalty
    percentage_bps: u16, // How much (e.g., 500 means 5%)
}

// Your NFT will now include this royalty info:
struct NFT has key {
    id: UID,
    name: vector<u8>,
    royalty: Royalty, // The royalty details are part of the NFT
}

To add NFT royalties on Sui, you have to handle it yourself — there’s no built-in royalty standard like Ethereum’s EIP-2981.

✅ The usual way is: • Store royalty info (like recipient address and % fee) inside the NFT object or its metadata. • When the NFT is sold, your smart contract: • Reads the royalty info • Sends a cut to the original creator • Sends the rest to the seller

Because Move is strict with ownership and types, you can enforce all of this securely. Buyers/sellers can’t skip the royalty logic if you build it into the sale flow.

Also, thanks to Sui’s object model, NFT + coin transfers happen atomically in one transaction, making royalty enforcement smooth and trustless.

To implement NFT royalties in a Sui marketplace smart contract, you embed royalty logic directly into your custom Move module using Sui’s object-centric architecture. Each NFT should carry metadata that includes the royalty recipient’s address and the royalty percentage, ideally using a struct that stores this information immutably or via controlled updates. When an NFT is listed and sold on the marketplace, the smart contract must calculate the royalty based on the sale price and automatically transfer that portion to the creator’s wallet before transferring the remainder to the seller. Sui's transfer functions can be used inside entry functions to handle royalty payouts securely during transaction execution.

Shared objects like a Marketplace struct can be used to manage listings, ensuring royalties are enforced during each trade. Ownership of NFTs must be temporarily or permanently transferred into the shared marketplace object to control execution flow and enforce royalty logic atomically. CLI tools like sui client object or sui client call can help test transactions and verify that royalties are correctly applied. A common mistake is failing to account for rounding errors in percentage calculations or allowing unauthorized royalty changes. To avoid reentrancy and state manipulation issues, make sure all royalty processing is encapsulated in a single atomic transaction block. Testing should be done extensively on localnet and testnet, with simulation of edge cases like zero-royalty NFTs or invalid royalty recipients.