NFT Royalties: Quotes vs Executed Payments
Distinguish NFT royalty information from actual sale payouts, and avoid treating a royalty quote as proof that a marketplace paid the creator.
Overview
When translating these concepts into an integration, keep the scope described by the wallet history api with the result. The examples in wallet transaction history and smart contract event logs show how the same distinction affects neighbouring data questions.
A royalty interface can describe a requested recipient and amount. Whether a particular sale actually paid that royalty depends on execution. Analytics should keep the quote and the observed payout distinct.
Treat the interface as a calculation contract
Royalty information can depend on token ID and sale price. The returned value is not itself a transfer event or proof of marketplace enforcement. Record the queried contract, token ID, input price and block context. Where the quote changes over time, a current query may not reproduce the expectation at a past sale.
Worked example: five percent requested
A royalty query for a sale price of one hundred returns five units to a creator address. The executed sale record shows a different payout structure. A report should show the requested royalty separately from verified transfers rather than automatically assigning five units of realised creator revenue.
Reconcile payouts to evidence
Identify sale consideration, currency, fees and payout recipients. Test bundled purchases where assigning one price per NFT requires a policy. Preserve whether royalty amounts were quoted, inferred or directly observed. If execution evidence is incomplete, report an unknown realised payout instead of assuming either full enforcement or zero payment.
A practical acceptance test
Return a five-unit royalty quote and provide executed payouts totalling a different amount. The report must keep requested and observed fields separate. Repeat with a bundled sale whose per-item price is unknown. It should not calculate a precise per-item realised royalty by silently dividing the bundle value equally unless that allocation policy is explicitly selected.
Questions about the topic
Frequently asked questions
Does a royalty quote prove payment?
No. It expresses requested information, not an executed transfer.
Can bundles complicate royalty reporting?
Yes. Per-item sale prices can require an allocation method.
Standards & technical documentation