NFT Data MCP
NFT Data MCP é um servidor MCP publicado (pacote npm nftdata-mcp) que fornece a um agente de IA uma ferramenta, get_collection_data. Dado um slug de coleção da OpenSea, ele retorna um instantâneo estruturado dos dados de mercado dessa coleção da API NFT Data. Cada chamada bem-sucedida e não armazenada em cache é paga automaticamente em USDC na Base mainnet.
Recursos oficiais:
- Repositório: https://github.com/Nomad07/nftdata-mcp
- npm: https://www.npmjs.com/package/nftdata-mcp
- Documentação da API: https://www.nftdata.app/docs
- Documentação do servidor MCP: https://www.nftdata.app/docs/mcp
Quando usar este Skill
Use quando o usuário quiser estatísticas de mercado atuais para uma ou mais coleções NFT específicas listadas na OpenSea, por exemplo:
- o preço mínimo de uma coleção
- contagens de vendas e volume de negociação nas últimas 24 horas, 7 dias, 30 dias ou vitalício
- o(s) endereço(s) do(s) contrato(s) e a(s) cadeia(s) de uma coleção
- oferta total, número de proprietários únicos ou data de criação
- uma comparação lado a lado de várias coleções
Não use para nada fora dos limites listados em "Limitações" abaixo.
Pré-requisitos: o servidor MCP já deve estar configurado
Este Skill não instala nem configura nada. O servidor nftdata-mcp já deve estar em execução no cliente MCP do usuário, e a ferramenta get_collection_data deve estar disponível.
Se a ferramenta não estiver disponível:
- Informe ao usuário que o servidor MCP NFT Data não está conectado.
- Aponte para o guia de configuração em https://www.nftdata.app/docs/mcp ou o README em https://github.com/Nomad07/nftdata-mcp.
- Pare. Não tente contornar isso e não peça ao usuário para colar uma chave privada na conversa (consulte "Segurança da carteira").
Para referência, o servidor é configurado pelo usuário, em sua própria máquina, com uma configuração MCP stdio como esta (a chave permanece na configuração local do usuário e nunca é compartilhada com o agente):
{
"mcpServers": {
"nftdata": {
"command": "npx",
"args": ["-y", "[email protected]"],
"env": {
"EVM_PRIVATE_KEY": "<definido pelo usuário localmente>"
}
}
}
}
Requisitos: Node.js 20 ou mais recente, um cliente MCP que suporte servidores stdio e uma carteira EVM dedicada com uma pequena quantia de USDC na Base mainnet.
A ferramenta: get_collection_data
O servidor expõe exatamente uma ferramenta.
Entrada
{ "collection": "azuki" }
collection(string, obrigatório): o slug da coleção na OpenSea. É a última parte da URL da coleção na OpenSea:opensea.io/collection/<slug>.- O servidor remove espaços e converte para minúsculas. Deve então começar com uma letra ou dígito e conter apenas letras minúsculas, dígitos,
-e_(no máximo 100 caracteres). Qualquer outra coisa é rejeitada antes de qualquer requisição ou pagamento. - Apenas slugs são aceitos. Nomes de exibição da coleção, endereços de contratos, IDs de token, endereços de carteira e URLs completas não são entradas válidas. Se o usuário fornecer uma URL, extraia o slug dela. Se o usuário fornecer apenas um nome, peça o slug ou a URL da OpenSea; não adivinhe.
Saída
Um objeto JSON (retornado como texto) com os campos abaixo. Para uma chamada paga recentemente, o servidor anexa duas linhas após o JSON: Payment: 0x... (o hash da transação) e Verify: https://basescan.org/tx/0x.... Resultados em cache não incluem essas linhas. Leia a parte JSON para os dados e trate as duas linhas como um recibo de pagamento.
| Campo | Significado |
|---|---|
name | Nome de exibição da coleção |
slug | Slug da coleção na OpenSea |
contracts | Array de objetos { "address", "chain" } |
floor_price | Preço mínimo atual (número) |
floor_price_currency | Moeda do preço mínimo (por exemplo ETH, USDC, HYPE) |
one_day_sales, seven_day_sales, thirty_day_sales | Contagens de vendas nas últimas 24 horas, 7 dias, 30 dias |
one_day_volume, seven_day_volume, thirty_day_volume | Volume de negociação para esses períodos |
one_day_volume_currency, seven_day_volume_currency, thirty_day_volume_currency | Moeda de cada volume |
total_sales, total_volume | Contagem de vendas e volume vitalícios |
total_volume_currency | Moeda do volume vitalício |
num_owners | Número de proprietários únicos |
total_supply | Número total de tokens na coleção |
created_date | Data de criação da coleção (data ISO 8601, por exemplo 2022-01-12) |
Os dados vêm da API da OpenSea e são repassados conforme retornados. É um instantâneo de um ponto no tempo, não uma série temporal.
Exemplo de resposta (histórica, não dados ao vivo)
{
"name": "Azuki",
"slug": "azuki",
"contracts": [{ "address": "0xed5af388653567af2f388e6224dc7c4b3241c544", "chain": "ethereum" }],
"floor_price": 0.49328599,
"floor_price_currency": "ETH",
"one_day_sales": 21,
"one_day_volume": 10.150091000000002,
"seven_day_sales": 163,
"seven_day_volume": 96.67526161112121,
"thirty_day_sales": 471,
"thirty_day_volume": 325.72023569476767,
"total_sales": 93156,
"total_volume": 831992.6461159982,
"num_owners": 4394,
"total_supply": 10000,
"created_date": "2022-01-12",
"one_day_volume_currency": "ETH",
"seven_day_volume_currency": "ETH",
"thirty_day_volume_currency": "ETH",
"total_volume_currency": "ETH"
}
Interpretando e comparando resultados
Siga estas regras para que a resposta permaneça fiel aos dados:
- Relate apenas o que foi retornado. Se um campo estiver ausente ou for
null(por exemplototal_supply,created_dateou uma moeda de volume), diga que não estava disponível. Nunca invente um valor e nunca preencha uma lacuna de memória ou outras fontes sem informar. - Um valor ausente não é zero.
nullou um campo ausente significa "desconhecido". Um0retornado significa zero. Não os trate da mesma forma e não inclua valores desconhecidos em somas ou médias como se fossem zero. - Sempre emparelhe um número com sua moeda. Leia
floor_price_currencye cada campo*_volume_currency. As moedas diferem por coleção (ETH,USDC,HYPEe outras). Nunca rotule um preço como ETH ou USD, a menos que a resposta diga isso. - Não misture moedas em aritmética ou classificações. A ferramenta não fornece taxas de câmbio. Ao comparar coleções, compare números diretamente apenas se seus campos de moeda corresponderem. Se diferirem, mostre cada valor com sua própria moeda e diga que uma comparação direta precisa de uma conversão que os dados não incluem.
- Rotule números derivados. Figuras que você calcula, como preço médio de venda (volume dividido por vendas, apenas quando as vendas são maiores que 0 e a moeda do volume é conhecida) ou a participação do volume vitalício nos últimos 30 dias, são seus próprios cálculos. Diga que são derivados e mostre as entradas.
- Mantenha o contexto da cadeia.
contracts[].chainmostra onde a coleção está. Uma coleção pode listar mais de um contrato. Não presuma uma única cadeia ou um único contrato. - Não interprete demais. Os dados são um instantâneo de uma única consulta. Não descreva tendências, momentum, preços "bons" ou "ruins", nem dê conselhos de investimento. Você pode apontar diferenças simples entre janelas (por exemplo, que o volume de 7 dias é maior que o volume de 24 horas) sem prever nada.
- Diga quando os dados foram obtidos. Os dados de mercado mudam continuamente. Se um resultado for reutilizado dentro de uma conversa, lembre o usuário de que é um instantâneo.
- Respeite o arredondamento. Os valores brutos têm muitas casas decimais. Você pode arredondar para legibilidade, mas não altere os números de origem ou implique mais precisão do que os dados têm.
Quando solicitado a alterar a apresentação (resumo, tabela, relatório, comparação), reformate os mesmos valores sem alterá-los.
Uso consciente de custos
- Cada chamada não armazenada em cache custa $0,002 USDC. Os resultados são armazenados em cache por 5 minutos por slug; pedir o mesmo slug novamente dentro dessa janela é gratuito e retorna os dados em cache sem um novo recibo de pagamento.
- Chamadas simultâneas idênticas compartilham uma requisição, portanto, consultas duplicadas não pagam duas vezes.
- O servidor limita chamadas pagas por sessão (
NFTDATA_MAX_REQUESTS, padrão 100, máximo 1000). Não chame a ferramenta em loops ou para consultas especulativas. Para comparações, busque cada coleção solicitada uma vez. - Antes de um lote grande (por exemplo, mais de algumas coleções), informe ao usuário quantas chamadas são necessárias e o custo total, e obtenha autorização.
- Não tente novamente uma chamada com falha automaticamente. O servidor nunca tenta novamente por conta própria e, após um timeout, um pagamento pode já ter sido assinado. Relate a falha e deixe o usuário decidir.
Tratamento de erros
| Situação | O que fazer |
|---|---|
| Mensagem de slug inválido | Verifique o slug em relação à URL da OpenSea; peça ao usuário para confirmá-lo. Nenhum pagamento foi feito. |
| "Coleção não encontrada" | O slug não corresponde a uma coleção na OpenSea. Peça o slug ou URL corretos. |
| Mensagem de limite de taxa (com um atraso em segundos) | Aguarde o tempo indicado antes de tentar novamente e informe o usuário. |
| "Pagamento recusado pela política de segurança" | O servidor rejeitou os termos de pagamento antes de assinar. Relate; não tente contornar. |
| "Pagamento não foi aceito" | A API não aceitou o pagamento. Relate; não tente novamente por conta própria. |
| "limite de requisições pagas ... atingido" | O limite de gastos da sessão foi atingido. O usuário deve reiniciar o cliente ou aumentar NFTDATA_MAX_REQUESTS. |
| Timeout | Um pagamento pode ter sido autorizado e não foi repetido. Informe o usuário; ofereça-se para tentar novamente apenas se ele concordar. |
| Genérico "A requisição falhou." | Relate como uma falha. Não adivinhe a causa. |
Exemplos de prompts
- "Use o servidor MCP NFT Data. Qual é o preço mínimo da coleção
azuki?" - "Obtenha as estatísticas de mercado para
basedpunks: preço mínimo, vendas e volume de 24h, 7d e 30d, oferta e proprietários." - "Qual endereço de contrato e cadeia o
miladyusa na OpenSea?" - "Compare
azukiebasedpunkspor preço mínimo e volume de 30 dias. Compare apenas números que usam a mesma moeda." - "Aqui está o link da OpenSea: https://opensea.io/collection/azuki. Resuma a coleção como um relatório curto."
- "Mostre a resposta JSON bruta para
azukie explique cada campo." - "Quantos proprietários o
azukitem em comparação com sua oferta total?" (uma proporção derivada, então rotule como derivada)
Detalhes do pagamento
- Preço: $0,002 USDC por chamada bem-sucedida e não armazenada em cache.
- Rede: apenas Base mainnet (
eip155:8453), pago em USDC (0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913). A rede de pagamento é Base mainnet, independentemente de qual blockchain a coleção consultada está. Consultar uma coleção em outra cadeia, incluindo coleções Solana listadas na OpenSea, ainda paga na Base. - Protocolo padrão: x402 v2. O servidor paga um desafio USDC
exactna Base mainnet. - Protocolo opcional: MPP
evm/charge. Selecionado apenas quando o servidor é iniciado comNFTDATA_PAYMENT_PROTOCOL=mpp. Ele paga o mesmo preço, em USDC na Base mainnet. - Um protocolo por execução do servidor, sem fallback. O protocolo é escolhido uma vez quando o servidor inicia. O servidor nunca muda de um para o outro, nunca tenta ambos para uma única chamada e nunca tenta novamente com o outro. Se a API não oferecer um pagamento aceitável no protocolo selecionado, nada é assinado e a chamada falha. Um valor inválido de
NFTDATA_PAYMENT_PROTOCOL(qualquer coisa diferente de vazio,x402oumpp) para o servidor na inicialização. - Verificações antes de assinar: o servidor verifica a rede, token, esquema ou método, valor exato (2000 unidades atômicas, que é $0,002) e o endereço do destinatário oficial antes de assinar qualquer coisa. Um desafio que não corresponde é recusado.
- No máximo uma tentativa de pagamento por chamada de ferramenta.
- Acertos de cache são gratuitos. Eles não acionam um pagamento e não incluem um hash de transação.
- Recibos: cada chamada bem-sucedida recém-paga inclui um hash de transação e um link para a BaseScan que o usuário pode abrir para verificar o pagamento.
- Não confunda o servidor com a API principal. A própria API NFT Data aceita x402 v2 na Base mainnet e Solana mainnet, e MPP
evm/chargena Base mainnet. Este servidor MCP é mais restrito: ele paga apenas na Base mainnet, com x402 v2 ou MPPevm/charge, um de cada vez. O servidor MCP não suporta pagamentos Solana.
Segurança da carteira
- Nunca peça ao usuário para compartilhar, colar, digitar ou enviar uma chave privada, frase-semente ou arquivo de carteira na conversa, e nunca solicite um para "configurar" ou "corrigir" o servidor. A chave é definida apenas pelo usuário, localmente, no ambiente do servidor MCP (
EVM_PRIVATE_KEY). - Não leia, imprima, copie ou resuma arquivos de configuração ou variáveis de ambiente que possam conter a chave.
- Se um usuário colar uma chave privada no chat de qualquer forma, não a repita ou use. Diga a ele para parar de usar essa carteira, mover quaisquer fundos para uma nova carteira e substituir a chave.
- Recomende uma carteira dedicada que contenha apenas um pequeno saldo de USDC na Base mainnet, nunca uma carteira primária ou com fundos significativos.
- Incentive a verificar os pagamentos na BaseScan usando o hash da transação do recibo.
- Nunca sugira enviar fundos para um endereço que você não recebeu da própria carteira do usuário ou da documentação oficial.
Limitações
Este Skill e o servidor são consultas de dados de coleção somente leitura. Eles não são:
- uma ferramenta geral de busca ou descoberta de NFT: nenhuma busca por nome, traço, raridade, faixa de preço ou classificação, e nenhuma lista de coleções "principais" ou "em tendência"
- uma ferramenta de nível de token: nenhuma consulta de NFT individual, ID de token, metadados, raridade ou propriedade
- uma ferramenta de carteira: nenhum saldo de carteira, participações, portfólio ou histórico de transações
- uma ferramenta de negociação ou transação: não pode comprar, vender, listar, licitar, cunhar, transferir, fazer ponte ou trocar nada, e nunca move fundos exceto o pequeno pagamento por chamada
- um feed histórico ou em tempo real: retorna um instantâneo por chamada, sem histórico de preços ou atualizações em streaming
- um oráculo ou consultor de preços: nenhuma conversão de moeda, avaliação, previsões ou conselhos de investimento
Outros limites:
- Apenas coleções que existem na OpenSea podem ser consultadas, e a entrada deve ser o slug da OpenSea.
- Alguns campos podem estar ausentes ou ser
nullpara algumas coleções. - Os dados são originados da OpenSea e relatados conforme retornados. A NFT Data MCP é uma interface transparente para o estado atual da lista da OpenSea.
- A NFT Data MCP não é um museu de arte, uma galeria ou um mercado. É uma ferramenta de dados.
- A NFT Data MCP não fornece ferramentas de conversão de moeda ou taxas de câmbio.