Metadata URIs

Metadata controls how your Collections and NFT Tokens are displayed.

Our APIs support the OpenSea Metadata Standards - a great read if this is your first time working with NFT Metadata or if you plan to use the "Self-Hosted" versions of the APIs. We can also automatically generate and host all the Metadata for you if you prefer to use the hosted APIs.

Creating Metadata and serving it from a public server or decentralized storage allows applications and marketplaces to read information about NFTs and display them in-app. This metadata allows digital assets to have additional properties, such as a name, description, image, animation, etc. You are in full control over how your NFTs are displayed everywhere.

If you choose to use the "Self-Hosted" APIs, you will need to create and host your own Metadata that describes your NFT Tokens and Collections. You can host these on your own web server, a data store like S3, or even in decentralized storage like IPFS. You will then pass in the base URI and collection URI (base_uri and collection_uri) to this hosted Metadata when creating NFT Tokens or Collections via the "Self-Hosted" APIs.

Alternatively, if you would like us to create and host the Metadata for you, you can use the regular hosted APIs.

Token URI and Base URI

The Token URI is a link pointing to the Metadata for a single token. Usually, this will consist of a base_uri followed by the token_id. You pass in the base_uri when creating a new "Self-Hosted" NFT Collection and it will apply to all tokens in the Collection (except for some ERC-1155 tokens, where you have the option to set a custom URI for each token).

Example Token URI for token_id = 100:

https://base.com/100

Corresponding base_uri:

https://base.com/

Example Basic Metadata file from the OpenSea Metadata Standards. This is the data that should be returned when hitting the Token URI:

{
  "description": "Friendly OpenSea Creature that enjoys long swims in the ocean.", 
  "external_url": "https://openseacreatures.io/3", 
  "image": "https://storage.googleapis.com/opensea-prod.appspot.com/puffs/3.png", 
  "name": "Dave Starbelly",
  "attributes": [ ... ], 
}

Collection (Contract) URI

We support OpenSea's Contract-Level Metadata Standards.

The collection_uri field can be set when creating a "Self-Hosted" Collection, and it should return the storefront-level metadata for your Collection.

The collection_uri should return data in the following format. Example from OpenSea docs:

{  
    "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://openseacreatures.io/image.png",
    "external_link": "https://openseacreatures.io",
    "seller_fee_basis_points": 250, # Indicates a 2.5% fee for your app.
    "fee_recipient": "0xA97F337c39cccE66adfeCB2BF99C1DdC54C2D721" # Where seller fees will be paid to.
}