O padrão JSON de metadados NFT é o pequeno arquivo que informa ao marketplace o que seu token realmente é: seu nome, sua imagem e seus atributos. Acertar três campos (name, image, attributes) faz com que o OpenSea renderize seu NFT perfeitamente. Errá-los sutilmente e seu token aparece como um espaço cinza sem atributos, mesmo que o contrato tenha sido mintado corretamente. Este guia aborda o padrão campo por campo, cobre as diferenças entre ERC-721 e ERC-1155 que a documentação oficial ignora, e mostra como gerar metadados limpos para uma coleção inteira sem editar manualmente 10.000 arquivos.
A maioria dos criadores descobre o padrão do jeito difícil, após o deploy. O contrato funciona, o token existe na blockchain, e então a listagem parece quebrada. A correção quase sempre está no JSON, não no Solidity. Então, antes de mintar, vale a pena entender exatamente o que os marketplaces leem e onde estão as armadilhas comuns.
O Que o Padrão JSON de Metadados NFT Realmente É#
Quando uma carteira ou marketplace quer exibir seu NFT, ele não olha diretamente para a imagem. Ele chama uma função no seu contrato, tokenURI(tokenId) para ERC-721, que retorna uma URL. Essa URL aponta para um arquivo JSON. O arquivo JSON são seus metadados, e é isso que o padrão rege.
Portanto, a blockchain armazena o link, e o link armazena a descrição. Na verdade, existem dois padrões em jogo, e eles concordam no essencial, mas diferem na estruturação:
- ERC-721 / ERC-1155 (a interface on-chain): define a função
tokenURI(ouuri) e um esquema mínimo sugerido comname,descriptioneimage. - O padrão de metadados do OpenSea (o esquema de exibição de fato): um superconjunto que adiciona
attributes,external_url,animation_url,background_colore o sistemadisplay_type. Este é o que os marketplaces realmente renderizam.
Na prática, você escreve no esquema do OpenSea porque é o que é exibido. Ele é compatível com versões anteriores da interface ERC, então segui-lo satisfaz ambos.
Ponto chave: a blockchain quase nunca armazena sua imagem ou atributos. Ela armazena um ponteiro. Se esse ponteiro quebrar ou o JSON por trás dele estiver malformado, o NFT parece quebrado, mesmo que o token seja perfeitamente válido on-chain.
Os Campos Essenciais que Todo NFT Precisa#
Aqui está um arquivo de metadados mínimo e válido. Este é o formato que renderiza corretamente no OpenSea, Blur, Magic Eden (EVM) e na maioria das carteiras.
{
"name": "Cosmic Fox #042",
"description": "Uma raposa desenhada à mão da coleção Cosmic Foxes.",
"image": "ipfs://bafybeigdyr.../042.png",
"external_url": "https://cosmicfoxes.xyz/042",
"attributes": [
{ "trait_type": "Background", "value": "Nebula" },
{ "trait_type": "Fur", "value": "Orange" },
{ "trait_type": "Eyes", "value": "Laser" }
]
}
Quatro campos fazem o trabalho pesado:
name: o título exibido. A convenção éNome da Coleção #TokenID. Isso aparece como o título principal na página do item.description: suporta Markdown básico no OpenSea (quebras de linha, negrito, links). Mantenha curto e legível.image: a URL da arte. PNG, JPG, GIF e SVG funcionam. Este é o ponto de falha mais comum (mais sobre isso abaixo).attributes: a matriz de atributos que alimenta os filtros de raridade que os compradores usam para navegar e precificar sua coleção.
Se você enviar apenas name, description e image, o NFT ainda será renderizado. Só não terá atributos para filtrar, o que em uma coleção generativa é uma grande perda.
O campo image e a armadilha do ipfs://#
A maior fonte de "meu NFT está em branco" é o campo image apontando para algo que o marketplace não consegue acessar. Três regras mantêm você seguro:
- Use uma URL estável e resolvível por gateway.
ipfs://CID/file.pngé preferido porque os marketplaces resolvem o esquemaipfs://nativamente. Um link HTTPS para seu próprio servidor também funciona, mas amarra a sobrevivência da arte à sua hospedagem. - Não use localhost ou URL temporária. Marketplaces armazenam metadados em cache. Se eles acessarem um link quebrado uma vez, muitas vezes você precisa acionar manualmente uma atualização.
- Combine o arquivo com a extensão. Uma URL
.pngservindo um JPEG pode falhar silenciosamente em alguns renderizadores.
Para decidir entre IPFS e um servidor normal (e o que "risco de rug" significa para compradores), o gerador gratuito de metadados NFT gera arquivos prontos para ipfs:// para que você não precise montar as URIs manualmente.
Como attributes e display_type realmente funcionam#
O array attributes é onde o padrão fica interessante, e onde a documentação oficial é mais superficial. Por padrão, cada atributo é renderizado como uma característica de texto. Mas display_type muda como um valor é exibido, e acertar isso é o que separa uma coleção refinada de uma amadora.
| display_type | O que faz | Exemplo de uso |
|---|---|---|
| (nenhum) | Característica de texto simples, mostrada como um selo | Background: Nebula |
number | Característica numérica com classificação em toda a coleção | Generation: 2 |
boost_number | Adiciona um + e mostra como um medidor de impulso | Speed: +20 |
boost_percentage | Igual ao boost, renderizado como porcentagem | Stamina: +10% |
date | Renderiza um timestamp Unix como data de calendário | Birthday: Jan 2024 |
Aqui está o detalhe que a maioria dos guias ignora: quando você usa um display_type numérico, o value deve ser um número real, não uma string. "value": 20 funciona; "value": "20" pode renderizar incorretamente ou ser ignorado.
{
"attributes": [
{ "trait_type": "Level", "display_type": "number", "value": 7 },
{ "trait_type": "Power", "display_type": "boost_number", "value": 40 },
{ "display_type": "date", "trait_type": "Minted", "value": 1704067200 }
]
}
Observe que a última entrada tem um display_type e nenhum rótulo trait_type na data em algumas configurações. Ambas as formas existem na prática; incluir trait_type é a escolha mais segura e clara.
Classificando características e o campo max_value#
Para estatísticas numéricas, você pode adicionar max_value para forçar um denominador consistente em toda a coleção, de modo que uma estatística seja lida como 7 / 10 em vez de apenas 7. Isso é puramente um detalhe de exibição, mas faz coleções no estilo RPG parecerem intencionais.
{ "trait_type": "Strength", "display_type": "number", "value": 7, "max_value": 10 }
ERC-721 vs ERC-1155 Metadados: A Diferença Que Ninguém Explica#
Esta é a lacuna que pega criadores que estão migrando de arte única para edições ou itens de jogo. Os dois padrões lidam com o URI de metadados de forma diferente, e a documentação oficial da OpenSea mal menciona isso.
| Aspecto | ERC-721 | ERC-1155 |
|---|---|---|
| Modelo de token | Um token único por ID | Múltiplas cópias por ID (edições) |
| Função URI | tokenURI(uint256 id) | uri(uint256 id) |
| Substituição de ID | Geralmente uma URL completa por token | O padrão suporta um placeholder {id} |
| Metadados típicos | Um arquivo JSON por token | Frequentemente um template resolvido por ID |
| Campo decimals | Não usado | decimals opcional para tokens do tipo fungível |
A diferença principal é o placeholder {id}. ERC-1155 permite que seu contrato retorne um único template de URI como ipfs://CID/{id}.json, e os clientes substituem o ID do token. A especificação oficial do ERC-1155 exige que o ID substituído seja uma string hexadecimal de 64 caracteres, minúscula, preenchida com zeros, sem prefixo 0x. Portanto, o token ID 1 se torna 0000000000000000000000000000000000000000000000000000000000000001.
Na prática, a OpenSea e a maioria dos marketplaces são tolerantes e também aceitam um ID decimal simples, mas se você quiser estar em conformidade com a especificação, preencha com zeros. Esse único detalhe causa horas de confusão do tipo "por que meus metadados 1155 não carregam", algo que nenhum tutorial para iniciantes alerta.
Os metadados ERC-1155 também podem conter um campo decimals (para tokens semi-fungíveis) e um objeto properties junto com attributes. Se você estiver construindo itens de jogo ou ingressos em vez de arte, leia ambos os campos.
Gerando Metadados para uma Coleção de 10.000 Itens#
Escrever um arquivo JSON manualmente é fácil. Escrever 10.000 com atributos consistentes, tipos numéricos corretos e CIDs de imagem correspondentes é onde os projetos quebram. Fazer isso manualmente garante erros de digitação, e um erro em um arquivo significa um NFT quebrado sobre o qual um comprador reclamará.
A abordagem confiável é tratar os metadados como saída gerada, não como arquivos editados manualmente. Seja usando um script ou uma ferramenta, o pipeline é o mesmo.
Passo 1: Fixe seu esquema de atributos primeiro#
Antes de gerar qualquer coisa, escreva cada trait_type e seus valores permitidos. "Background" deve ser sempre escrito "Background", nunca "BG" em alguns arquivos. Nomes de atributos inconsistentes dividem seus filtros de raridade em duplicatas inúteis no marketplace. Uma lista canônica evita isso.
Passo 2: Decida o hospedagem de imagens e obtenha seu CID#
Faça upload da pasta completa de imagens para o IPFS (via Pinata, NFT.Storage ou similar) para obter um CID base para o diretório. Seu campo image se torna ipfs://BASE_CID/042.png. Fixar a pasta inteira de uma vez mantém cada URI consistente e evita uploads por arquivo.
Passo 3: Gere um arquivo JSON por token#
Para cada token, monte name, description, image (CID base mais nome do arquivo) e o array attributes para aquela combinação específica. Mantenha atributos numéricos como números reais. O caminho mais rápido sem código é colar seus dados de atributos no gerador de metadados NFT, que cria arquivos corretos conforme o padrão com o display_type e URIs ipfs:// corretos e exporta o lote.
Passo 4: Valide antes de fazer upload#
Execute cada arquivo em um validador JSON para que uma única vírgula à direita não quebre um token. Colar uma amostra em um formatador e validador JSON captura colchetes malformados, aspas erradas e a vírgula solta que quebra o JSON.parse. Faça isso em alguns arquivos aleatórios do lote, não apenas no arquivo #1.
Passo 5: Faça upload dos metadados e defina seu baseURI#
Faça upload da pasta de metadados para o IPFS para obter um segundo CID e defina-o como baseURI do seu contrato (para que tokenURI retorne ipfs://METADATA_CID/{id}.json ou URLs por token). Confirme que um token resolve de ponta a ponta em uma testnet antes de cunhar a oferta completa.
Aviso: marketplaces armazenam metadados em cache agressivamente. Sempre verifique se seus metadados são renderizados corretamente em uma testnet (ou com uma cunhagem) antes de comprometer toda a coleção. Corrigir um CID após um reveal de 10.000 cunhagens é doloroso e às vezes exige que cada detentor atualize manualmente.
Metadados On-Chain: Quando o JSON Vive no Contrato#
Existe uma variante totalmente on-chain onde o tokenURI retorna uma URI de dados codificada em base64 em vez de um link IPFS, de modo que os metadados (e às vezes uma imagem SVG) vivem inteiramente no Ethereum. É assim que projetos como arte generativa totalmente on-chain garantem permanência sem dependência externa.
O esquema de metadados é idêntico. A única mudança é a entrega: em vez de um link ipfs://, o tokenURI retorna:
data:application/json;base64,eyJuYW1lIjoiQ29zbWlj...
O navegador decodifica essa string base64 no mesmo objeto JSON descrito acima. Se você estiver depurando um desses, pode colar a string codificada em um codificador e decodificador base64 para ler o JSON subjacente. O armazenamento on-chain custa muito mais gás, por isso é reservado para coleções que tratam a permanência como o ponto central. Para todo o resto, IPFS com um arquivo JSON limpo é o padrão.
Erros Comuns Que Deixam Seu NFT em Branco#
Uma lista de verificação rápida das falhas que causam a maioria dos tópicos de suporte do tipo "mintou mas parece quebrado":
- Vírgulas sobressalentes ou chaves sem aspas. Válido em objetos JavaScript, inválido em JSON. Uma vírgula quebra o arquivo inteiro.
- Valores string onde números são esperados.
"value": "7"comdisplay_type: numberpode remover o traço. Use7. - Inconsistência na grafia de
trait_type. "Eye Color" em um arquivo e "Eyes" em outro fragmenta seus filtros. - URL de imagem quebrada ou privada. Localhost, link expirado ou CID com erro de digitação resulta em branco.
- ID do ERC-1155 sem padding. Se o marketplace for rigoroso, um
{id}sem padding não resolve. - Esquecer de atualizar os metadados. Após corrigir um arquivo, muitas vezes é necessário acionar uma atualização de metadados no marketplace por causa do cache.
Se seu contrato está construído, mas você não tem certeza se a interface padrão está configurada corretamente, uma verificação rápida em um verificador de contrato de token confirma se a função tokenURI / uri está exposta como os marketplaces esperam, antes de gastar gás para mintar.
O Padrão JSON de Metadados NFT em Uma Frase#
O padrão JSON de metadados NFT é um pequeno arquivo JSON com name, description, image e um array attributes, servido a partir de tokenURI (ERC-721) ou uri (ERC-1155), onde atributos numéricos usam um display_type com números reais e a imagem está em uma URL estável ipfs://. Siga essa estrutura, valide antes de enviar e verifique em uma testnet, e sua coleção será renderizada como você projetou. Gere os arquivos com o gerador de metadados NFT e você elimina a edição manual completamente.
Perguntas Frequentes#
O que é o padrão JSON de metadados NFT?
É o esquema JSON acordado que os marketplaces leem para exibir um NFT. No mínimo, inclui name, description e image, além de um array attributes para características. O arquivo é servido pela função tokenURI (ERC-721) ou uri (ERC-1155) do seu contrato, e o superconjunto desse esquema do OpenSea é o que a maioria das plataformas realmente renderiza.
Onde os metadados NFT são armazenados, on-chain ou off-chain?
Geralmente off-chain. O blockchain normalmente armazena apenas um ponteiro (um link ipfs:// ou URL HTTPS) retornado por tokenURI, e o JSON em si vive no IPFS ou em um servidor. Uma variante totalmente on-chain retorna uma data URI codificada em base64 para que os metadados vivam no contrato, mas isso custa muito mais gas e é a exceção, não a regra.
Por que meu NFT aparece em branco no OpenSea?
Quase sempre é um problema de metadados, não de contrato. As causas comuns são uma URL image quebrada ou privada, JSON malformado (uma vírgula à direita é o clássico), um erro de digitação no CID ou um ID de token ERC-1155 que não está preenchido com zeros à esquerda. Corrija o arquivo e então acione uma atualização de metadados, porque os marketplaces fazem cache agressivamente.
Qual é a diferença entre metadados ERC-721 e ERC-1155?
O esquema é quase idêntico, mas a entrega difere. ERC-721 expõe tokenURI e geralmente aponta para um arquivo JSON por token. ERC-1155 expõe uri e suporta um placeholder {id}, onde a especificação exige que o ID seja em minúsculas e preenchido com zeros à esquerda até 64 caracteres hexadecimais. ERC-1155 também adiciona campos opcionais como decimals para tokens semifungíveis.
Como adicionar características com raridade aos metadados NFT?
Coloque-os no array attributes, cada um como um objeto com trait_type e value. Os marketplaces calculam a raridade automaticamente contando quantas vezes cada valor aparece na coleção, então a ortografia consistente é importante. Use display_type de number, boost_number ou boost_percentage para estatísticas numéricas e mantenha esses valores como números reais em vez de strings.
Preciso de IPFS para metadados NFT? Não, mas é fortemente recomendado. O IPFS fornece hospedagem com endereçamento por conteúdo e à prova de adulteração, para que os compradores saibam que a arte não pode ser trocada ou excluída silenciosamente. Um servidor HTTPS normal funciona e os marketplaces o lerão, mas a sobrevivência da arte depende de sua hospedagem permanecer online, que é o "risco de rug pull" que os compradores temem.
