Contract-level metadata

Provide metadata for a token contract

Implement contractURI on an ERC-20, ERC-721, or ERC-1155 contract to return contract-level metadata, as specified by ERC-7572.

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.20;

contract MyToken {
    function contractURI() external pure returns (string memory) {
        return "ipfs://QmTNgv3jx2HHfBjQX9RnKtxj2xv2xQDtbVXoRi5rJ3a46e";
        // or e.g. https://external-link-url.com/my-contract-metadata.json
    }
}

Return JSON in this format:

{
  "name": "OpenSea Creatures",
  "description": "OpenSea Creatures are adorable aquatic beings primarily for demonstrating what can be done using the OpenSea platform. Adopt one today to try out all the OpenSea buying, selling, and bidding feature set.",
  "image": "https://external-link-url.com/image.png",
  "banner_image": "https://external-link-url.com/banner-image.png",
  "featured_image": "https://external-link-url.com/featured-image.png",
  "external_link": "https://external-link-url.com",
  "collaborators": ["0x0000000000000000000000000000000000000000"]
}

You can also return the JSON from the contract:

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.20;

contract MyToken {
    function contractURI() external pure returns (string memory) {
        string memory json = '{"name": "Opensea Creatures","description":"..."}';
        return string.concat("data:application/json;utf8,", json);
    }
}

Emit ContractURIUpdated() when contractURI() changes.

Set creator earnings in the Royalty Registry, which OpenSea uses.

Rarity settings

We recommend defining rarity settings onchain, in the metadata returned by contractURI(), so anyone can see how your collection's rarity is calculated and other marketplaces and tools can use the same settings. The URI can point to JSON or return it directly from the contract. Collection owners and editors can also change how OpenSea scores rarity in Creator Studio, the REST API, the SDK, or the CLI. Those changes apply only to OpenSea's rankings.

Add an optional rarity object to your contract-level metadata:

{
  "name": "Example Collection",
  "rarity": {
    "trait_count": "higher_is_rarer",
    "traits": [
      { "trait_type": "Serial Number", "mode": "exclude" },
      { "trait_type": "Level", "mode": "higher_is_rarer" }
    ]
  }
}
SettingEffect
"mode": "exclude"Leaves the trait out of rarity scoring. The trait remains available in filters.
"mode": "higher_is_rarer"Scores numeric values by how few items reach or exceed that value. Missing or nonnumeric values add no rarity points for this trait.
"trait_count": "exclude"Leaves the number of traits out of rarity scoring.
"trait_count": "higher_is_rarer"Scores items with more traits as rarer.

Traits without a setting use frequency scoring. trait_type matches token attribute names case-sensitively; OpenSea trims leading and trailing spaces. If you list a trait more than once, the last valid entry applies. OpenSea reads up to 100 traits entries, with names up to 256 characters. It skips malformed entries and unknown modes.

Emit ContractURIUpdated() after changing the URI or its metadata. You can also refresh the collection's metadata on OpenSea. Rarity ranks update after the new settings are processed.

Edit settings on OpenSea

In Creator Studio, open your collection's details and turn on Show OpenRarity ranking. The Rarity scoring section lets you choose By rarity, Don't count, or, for numeric traits, Higher is rarer. Changes save immediately, and each row shows whether its setting came from contract metadata or OpenSea.

The REST API supports the same edits. GET /api/v2/collections/{slug}/rarity_settings returns the effective settings and their sources. POST /api/v2/collections/{slug}/rarity_settings sets one trait with a body such as {"trait_type":"Background","mode":"exclude"}, or sets trait count with {"trait_count":true,"mode":"higher_is_rarer"}. You can also use "frequency" to restore default scoring on OpenSea.

The OpenSea CLI (5.1.0+) and SDK (14.1.0+) support rarity settings through these endpoints.

POST /api/v2/collections/{slug}/rarity_settings/revert removes an OpenSea setting with {"trait_type":"Background"} or {"trait_count":true}. Writes require a wallet identity token with the write:collections scope and collection owner or editor access.

An OpenSea setting takes precedence for that trait, including a change back to frequency scoring. Reverting it restores the setting from contract metadata, if present.

Contract Creator Attribution

OpenSea uses ERC-173: Contract Ownership Standard for contract creator attribution.