NFT Data MCP
NFT Data MCP est un serveur MCP publié (paquet npm nftdata-mcp) qui fournit à un agent IA un seul outil, get_collection_data. Étant donné un slug de collection OpenSea, il retourne un instantané structuré des données de marché de cette collection provenant de l'API NFT Data. Chaque appel réussi et non mis en cache est payé automatiquement en USDC sur le réseau Base mainnet.
Ressources officielles :
- Dépôt : https://github.com/Nomad07/nftdata-mcp
- npm : https://www.npmjs.com/package/nftdata-mcp
- Documentation de l'API : https://www.nftdata.app/docs
- Documentation du serveur MCP : https://www.nftdata.app/docs/mcp
Quand utiliser ce skill
Utilisez-le lorsque l'utilisateur souhaite obtenir des statistiques de marché actuelles pour une ou plusieurs collections NFT spécifiques listées sur OpenSea, par exemple :
- le prix plancher d'une collection
- les nombres de ventes et les volumes de transactions au cours des dernières 24 heures, 7 jours, 30 jours ou depuis le début
- la ou les adresses de contrat et la ou les blockchains d'une collection
- l'offre totale, le nombre de propriétaires uniques, ou la date de création
- une comparaison côte à côte de plusieurs collections
Ne l'utilisez pas pour quoi que ce soit en dehors des limites listées dans la section « Limitations » ci-dessous.
Prérequis : le serveur MCP doit déjà être configuré
Ce skill n'installe ni ne configure rien. Le serveur nftdata-mcp doit déjà être en cours d'exécution dans le client MCP de l'utilisateur, et l'outil get_collection_data doit être disponible.
Si l'outil n'est pas disponible :
- Dites à l'utilisateur que le serveur MCP NFT Data n'est pas connecté.
- Orientez-le vers le guide de configuration à l'adresse https://www.nftdata.app/docs/mcp ou le README à l'adresse https://github.com/Nomad07/nftdata-mcp.
- Arrêtez-vous. N'essayez pas de contourner le problème et ne demandez pas à l'utilisateur de coller une clé privée dans la conversation (voir « Sécurité du portefeuille »).
Pour référence, le serveur est configuré par l'utilisateur, sur sa propre machine, avec une configuration MCP stdio comme celle-ci (la clé reste dans la configuration locale de l'utilisateur et n'est jamais partagée avec l'agent) :
{
"mcpServers": {
"nftdata": {
"command": "npx",
"args": ["-y", "[email protected]"],
"env": {
"EVM_PRIVATE_KEY": "<défini localement par l'utilisateur>"
}
}
}
}
Configuration requise : Node.js 20 ou plus récent, un client MCP prenant en charge les serveurs stdio, et un portefeuille EVN dédié contenant une petite quantité d'USDC sur le réseau Base mainnet.
L'outil : get_collection_data
Le serveur expose exactement un outil.
Entrée
{ "collection": "azuki" }
collection(chaîne, obligatoire) : le slug de la collection OpenSea. C'est la dernière partie de l'URL OpenSea de la collection :opensea.io/collection/<slug>.- Le serveur supprime les espaces et met le slug en minuscules. Il doit ensuite commencer par une lettre ou un chiffre et ne contenir que des lettres minuscules, des chiffres,
-et_(100 caractères maximum). Tout autre élément est rejeté avant toute requête ou tout paiement. - Seuls les slugs sont acceptés. Les noms d'affichage de collection, les adresses de contrat, les identifiants de token, les adresses de portefeuille et les URL complètes ne sont pas des entrées valides. Si l'utilisateur fournit une URL, extrayez le slug de celle-ci. Si l'utilisateur fournit uniquement un nom, demandez le slug ou l'URL OpenSea ; ne devinez pas.
Sortie
Un objet JSON (retourné sous forme de texte) avec les champs ci-dessous. Pour un appel nouvellement payé, le serveur ajoute deux lignes après le JSON : Payment: 0x... (le hash de la transaction) et Verify: https://basescan.org/tx/0x.... Les résultats en cache n'incluent pas ces lignes. Lisez la partie JSON pour les données et traitez les deux lignes comme un reçu de paiement.
| Champ | Signification |
|---|---|
name | Nom d'affichage de la collection |
slug | Slug de la collection OpenSea |
contracts | Tableau d'objets { "address", "chain" } |
floor_price | Prix plancher actuel (nombre) |
floor_price_currency | Devise du prix plancher (par exemple ETH, USDC, HYPE) |
one_day_sales, seven_day_sales, thirty_day_sales | Nombres de ventes pour les dernières 24 heures, 7 jours, 30 jours |
one_day_volume, seven_day_volume, thirty_day_volume | Volume de transactions pour ces périodes |
one_day_volume_currency, seven_day_volume_currency, thirty_day_volume_currency | Devise de chaque volume |
total_sales, total_volume | Nombre de ventes et volume depuis le début |
total_volume_currency | Devise du volume total |
num_owners | Nombre de propriétaires uniques |
total_supply | Nombre total de tokens dans la collection |
created_date | Date de création de la collection (date ISO 8601, par exemple 2022-01-12) |
Les données proviennent de l'API OpenSea et sont transmises telles quelles. Il s'agit d'un instantané à un moment donné, et non d'une série temporelle.
Exemple de réponse (données historiques, non réelles)
{
"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"
}
Interprétation et comparaison des résultats
Suivez ces règles pour que la réponse reste fidèle aux données :
- Signalez uniquement ce qui a été retourné. Si un champ est manquant ou
null(par exempletotal_supply,created_dateou une devise de volume), dites qu'il n'était pas disponible. N'inventez jamais une valeur et ne comblez jamais une lacune à partir de votre mémoire ou d'autres sources sans le dire. - Une valeur manquante n'est pas zéro.
nullou un champ absent signifie « inconnu ». Un0retourné signifie zéro. Ne les traitez pas de la même manière et n'incluez pas les valeurs inconnues dans des sommes ou des moyennes comme si elles étaient zéro. - Associez toujours un nombre à sa devise. Lisez
floor_price_currencyet chaque champ*_volume_currency. Les devises diffèrent selon les collections (ETH,USDC,HYPEet autres). Ne qualifiez jamais un prix d'ETH ou d'USD à moins que la réponse ne le spécifie. - Ne mélangez pas les devises dans les calculs arithmétiques ou les classements. L'outil ne fournit pas de taux de change. Lorsque vous comparez des collections, comparez les nombres directement uniquement si leurs champs de devise correspondent. S'ils diffèrent, affichez chaque valeur avec sa propre devise et dites qu'une comparaison directe nécessite une conversion que les données n'incluent pas.
- Étiquetez les nombres dérivés. Les chiffres que vous calculez, tels que le prix de vente moyen (volume divisé par les ventes, uniquement lorsque les ventes sont supérieures à 0 et que la devise du volume est connue) ou la part du volume total au cours des 30 derniers jours, sont vos propres calculs. Dites qu'ils sont dérivés et affichez les entrées.
- Gardez le contexte de la blockchain.
contracts[].chainindique où se trouve la collection. Une collection peut lister plus d'un contrat. Ne présumez pas d'une seule blockchain ou d'un seul contrat. - Ne suivez pas de surinterprétation. Les données sont un instantané provenant d'une seule requête. Ne décrivez pas les tendances, l'élan, les prix « bons » ou « mauvais » et ne donnez pas de conseils en investissement. Vous pouvez signaler les différences évidentes entre les fenêtres (par exemple, que le volume sur 7 jours est plus important que le volume sur 24 heures) sans rien prédire.
- Dites quand les données ont été récupérées. Les données de marché changent en continu. Si un résultat est réutilisé au cours d'une conversation, rappelez à l'utilisateur qu'il s'agit d'un instantané.
- Respectez l'arrondi. Les valeurs brutes ont de nombreuses décimales. Vous pouvez arrondir pour la lisibilité, mais ne modifiez pas les nombres sources et n'impliquez pas plus de précision que les données n'en ont.
Lorsqu'on vous demande de modifier la présentation (résumé, tableau, rapport, comparaison), reformatez les mêmes valeurs sans les altérer.
Utilisation avec connaissance des coûts
- Chaque appel non mis en cache coûte 0,002 USDC. Les résultats sont mis en cache pendant 5 minutes par slug ; demander le même slug à nouveau dans cette fenêtre est gratuit et retourne les données en cache sans nouveau reçu de paiement.
- Les appels simultanés identiques partagent une seule requête, donc les recherches en double ne paient pas deux fois.
- Le serveur limite les appels payés par session (
NFTDATA_MAX_REQUESTS, valeur par défaut 100, maximum 1000). N'appelez pas l'outil en boucle ou pour des recherches spéculatives. Pour les comparaisons, récupérez chaque collection demandée une fois. - Avant un lot important (par exemple plus de quelques collections), dites à l'utilisateur combien d'appels sont nécessaires et le coût total, et obtenez son accord.
- Ne réessayez pas automatiquement un appel qui a échoué. Le serveur ne réessaie jamais de lui-même, et après un dépassement de délai, un paiement a peut-être déjà été signé. Signalez l'échec et laissez l'utilisateur décider.
Gestion des erreurs
| Situation | Conduite à tenir |
|---|---|
| Message de slug invalide | Vérifiez le slug par rapport à l'URL OpenSea ; demandez à l'utilisateur de le confirmer. Aucun paiement n'a été effectué. |
| « Collection not found » | Le slug ne correspond à aucune collection sur OpenSea. Demandez le slug ou l'URL corrects. |
| Message de limite de débit (avec un délai en secondes) | Attendez le temps indiqué avant de réessayer et informez l'utilisateur. |
| « Payment refused by safety policy » | Le serveur a rejeté les conditions de paiement avant la signature. Signalez-le ; n'essayez pas de le contourner. |
| « Payment was not accepted » | L'API n'a pas accepté le paiement. Signalez-le ; ne réessayez pas de votre propre chef. |
| « paid request limit ... reached » | Le plafond de dépenses de la session a été atteint. L'utilisateur doit redémarrer le client ou augmenter NFTDATA_MAX_REQUESTS. |
| Dépassement de délai | Un paiement a peut-être été autorisé et n'a pas été réessayé. Dites-le à l'utilisateur ; proposez de réessayer uniquement s'il est d'accord. |
| « The request failed. » générique | Signalez-le comme un échec. Ne devinez pas la cause. |
Exemples de requêtes
- « Utilise le serveur MCP NFT Data. Quel est le prix plancher de la collection
azuki? » - « Récupère les statistiques de marché pour
basedpunks: prix plancher, ventes et volumes sur 24h, 7j et 30j, offre et propriétaires. » - « Quelle adresse de contrat et quelle blockchain utilise
miladysur OpenSea ? » - « Compare
azukietbasedpunkspar prix plancher et volume sur 30 jours. Ne compare que les nombres qui utilisent la même devise. » - « Voici le lien OpenSea : https://opensea.io/collection/azuki. Résume la collection sous forme d'un court rapport. »
- « Affiche la réponse JSON brute pour
azukiet explique chaque champ. » - « Combien de propriétaires
azukia-t-elle par rapport à son offre totale ? » (un ratio dérivé, donc étiquetez-le comme dérivé)
Détails du paiement
- Prix : 0,002 USDC par appel réussi non mis en cache.
- Réseau : Base mainnet uniquement (
eip155:8453), payé en USDC (0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913). Le réseau de paiement est Base mainnet, quelle que soit la blockchain sur laquelle se trouve la collection interrogée. L'interrogation d'une collection sur une autre blockchain, y compris les collections Solana listées sur OpenSea, est toujours payée sur Base. - Protocole par défaut : x402 v2. Le serveur paie un défi
exactUSDC sur Base mainnet. - Protocole optionnel : MPP
evm/charge. Sélectionné uniquement lorsque le serveur est démarré avecNFTDATA_PAYMENT_PROTOCOL=mpp. Il paie le même prix, en USDC sur Base mainnet. - Un seul protocole par exécution du serveur, pas de bascule. Le protocole est choisi une fois au démarrage du serveur. Le serveur ne passe jamais de l'un à l'autre, n'essaie jamais les deux pour un seul appel et ne réessaie jamais avec l'autre. Si l'API n'offre pas de paiement acceptable dans le protocole sélectionné, rien n'est signé et l'appel échoue. Une valeur
NFTDATA_PAYMENT_PROTOCOLinvalide (autre que vide,x402oumpp) arrête le serveur au démarrage. - Vérifications avant signature : le serveur vérifie le réseau, le token, le schéma ou la méthode, le montant exact (2000 unités atomiques, soit 0,002 $) et l'adresse du destinataire officiel avant de signer quoi que ce soit. Un défi qui ne correspond pas est refusé.
- Au maximum une tentative de paiement par appel d'outil.
- Les accès au cache sont gratuits. Ils ne déclenchent pas de paiement et n'incluent pas de hash de transaction.
- Reçus : chaque appel réussi nouvellement payé inclut un hash de transaction et un lien BaseScan que l'utilisateur peut ouvrir pour vérifier le paiement.
- Ne confondez pas le serveur avec l'API principale. L'API NFT Data elle-même accepte x402 v2 sur Base mainnet et Solana mainnet, et MPP
evm/chargesur Base mainnet. Ce serveur MCP est plus restreint : il paie sur Base mainnet uniquement, avec x402 v2 ou MPPevm/charge, un à la fois. Le serveur MCP ne prend pas en charge les paiements Solana.
Sécurité du portefeuille
- Ne demandez jamais à l'utilisateur de partager, coller, taper ou envoyer une clé privée, une phrase de récupération ou un fichier de portefeuille dans la conversation, et ne demandez jamais une telle information pour « configurer » ou « réparer » le serveur. La clé est définie uniquement par l'utilisateur, localement, dans l'environnement du serveur MCP (
EVM_PRIVATE_KEY). - Ne lisez, n'imprimez, ne copiez et ne résumez pas les fichiers de configuration ou les variables d'environnement qui peuvent contenir la clé.
- Si un utilisateur colle quand même une clé privée dans le chat, ne la répétez pas et ne l'utilisez pas. Dites-lui d'arrêter d'utiliser ce portefeuille, de transférer les fonds vers un nouveau portefeuille et de remplacer la clé.
- Recommandez un portefeuille dédié qui ne contient qu'un petit solde USDC sur Base mainnet, jamais un portefeuille principal ou un portefeuille contenant des fonds importants.
- Encouragez la vérification des paiements sur BaseScan à l'aide du hash de transaction du reçu.
- Ne suggérez jamais d'envoyer des fonds à une adresse que vous n'avez pas reçue du portefeuille de l'utilisateur ou de la documentation officielle.
Limitations
Ce skill et le serveur sont des recherches de données de collection en lecture seule. Ils ne sont pas :
- un outil de recherche ou de découverte général de NFT : pas de recherche par nom, trait, rareté, fourchette de prix ou classement, et pas de listes de collections « top » ou « tendance »
- un outil au niveau des tokens : pas de recherche de NFT individuel, d'identifiant de token, de métadonnées, de rareté ou de propriété
- un outil de portefeuille : pas de soldes de portefeuille, de détentions, de portefeuille ou d'historique de transactions
- un outil de trading ou de transaction : il ne peut pas acheter, vendre, lister, enchérir, mint, transférer, ponter ou échanger quoi que ce soit, et il ne déplace jamais de fonds en dehors du petit paiement par appel
- un flux historique ou en temps réel : il retourne un instantané par appel, sans historique des prix ni mises à jour en continu
- un oracle de prix ou un conseiller : pas de conversion de devises, d'évaluation, de prédictions ou de conseils en investissement
Autres limites :
- Seules les collections qui existent sur OpenSea peuvent être interrogées, et l'entrée doit être le slug OpenSea.
- Certains champs peuvent être manquants ou
nullpour certaines collections. - Les données proviennent d'OpenSea et sont rapportées telles quelles ; elles peuvent ne pas être exactes ou à jour.
- Ce skill ne prend pas en charge les demandes en masse ou en continu.
- L'outil ne peut pas être utilisé pour des opérations impliquant des fonds autres que le paiement par appel.
- La sécurité du portefeuille est cruciale ; ne partagez jamais la clé privée.
Informations supplémentaires
Ce skill est conçu pour les développeurs et les utilisateurs avancés qui ont besoin d'accéder rapidement aux données de marché des NFT. Il est particulièrement utile pour l'analyse de marché, la comparaison de collections et la création de rapports. Assurez-vous que le serveur MCP est correctement configuré avant d'utiliser ce skill.