Skip to main content

​
Overview

NFT metadata is notoriously inconsistent. Different collections use different schemas, naming conventions, attribute formats, and storage locations - making it difficult to work with at scale. Moralis solves this by normalizing NFT metadata into a clean, predictable structure, while still allowing access to the original source data when needed. Related pages:

​
What is NFT metadata normalization?

When enabled, Moralis transforms raw NFT metadata into a standardized JSON structure that works consistently across:
  • ERC721
  • ERC1155
  • OpenSea-style metadata
  • Collection-specific formats (e.g. CryptoPunks, ENS)
This removes the need for custom parsing logic per collection.

​
Why this matters

Without normalization:
  • Attributes are inconsistently named
  • Values change type across collections
  • Metadata is often returned as a raw JSON string
  • Frontends and analytics break easily
With normalization:
  • Predictable fields
  • Consistent attribute structure
  • Easier UI rendering
  • Easier indexing and analytics

​
How to enable normalized metadata

Several NFT endpoints support metadata normalization via the normalizeMetadata query parameter. When enabled:
  • Raw metadata is preserved
  • A new normalized_metadata object is added to the response

​
Normalized metadata structure

The normalized metadata object provides a stable schema across collections.

​
Core fields

{
  "name": "Moralis Mug",
  "description": "Moralis Coffee mug 3D asset",
  "image": "https://...",
  "external_link": "https://...",
  "animation_url": "https://...",
  "attributes": []
}

​
Normalized attributes

Each attribute follows a consistent structure: 
{
  "trait_type": "Eye Color",
  "value": "Hazel",
  "display_type": "string",
  "max_value": 100,
  "trait_count": 7,
  "order": 1
}
This makes it easy to:
  • Render traits
  • Sort attributes
  • Calculate rarity
  • Compare NFTs across collections
See also:

​
Raw vs normalized metadata

Moralis always preserves the original metadata source.

​
Normalized metadata

  • Returned as structured JSON
  • Easy to consume
  • Consistent across collections

​
Raw metadata

  • Returned as a string
  • Mirrors the original token URI response
  • Useful for debugging or edge cases
Example (raw metadata string): 
"{ \"name\": \"Dave Starbelly\", \"attributes\": [...] }"

​
Collection-specific normalization

Moralis includes custom normalization logic for well-known collections and standards, including:
  • CryptoPunks
  • CryptoKitties
  • ENS
  • OpenSea-style metadata
If a collection does not match a known format:
  • A default transformation is applied
  • Based on ERC721 or ERC1155 conventions
  • Most fields are still normalized successfully
This ensures broad compatibility without manual handling.

​
Automatic metadata refresh

NFT metadata can change over time - especially when hosted on IPFS. To keep data fresh, Moralis automatically refreshes metadata when NFTs are requested.

​
How it works

  • When an NFT is requested, it is queued for refresh
  • If the metadata URI points to IPFS:
    • The token is eligible for periodic refresh
  • Refreshing happens transparently in the background

​
Cool-off period

Metadata refresh is resource-intensive, so a cool-off period applies:
  • IPFS-based metadata:
    Refresh allowed once every 10 minutes per token
This balances freshness with performance.

​
Collection offchain metadata

In addition to token-level metadata, Moralis also enriches NFT collections with offchain metadata sourced from trusted marketplaces such as OpenSea. This includes collection-level information that is often not available on-chain, such as:
  • Collection name
  • Collection description
  • Collection image and banner image
  • External links (website, Twitter, Discord, etc.)
  • Marketplace identifiers
This enrichment allows you to:
  • Display richer collection pages
  • Avoid making separate marketplace API calls
  • Work with consistent collection metadata across chains
Collection offchain metadata is returned alongside on-chain data on supported NFT endpoints.

​
Common use cases

  • NFT galleries
    Render attributes consistently across collections
  • Marketplaces
    Normalize metadata for search, filtering, and ranking
  • Analytics & rarity tools
    Work with structured traits at scale
  • Wallet & portfolio views
    Display NFTs reliably without custom parsing logic

​
Summary

Moralis NFT Metadata normalization provides:
  • Clean, predictable metadata
  • Broad collection support
  • Automatic refresh handling
  • Reduced frontend and backend complexity
If you’re working with NFTs at scale, normalization isn’t optional — it’s foundational.