Le Collection Blueprint

KURV fonctionne aujourd’hui sur Base Sepolia et Solana Devnet. Cette page est le guide de terrain issu d’une construction complète (HANI the Dog, 1 000 pièces, 20 uniques), écrit pour un créateur qui travaille avec un agent d’IA via le connecteur KURV à l’adresse https://mcp.kurv.fun/mcp. Le connecteur sert le même guide aux agents sous la forme de la ressource kurv://blueprint, et l’outil kurv_builder_spec fait foi : là où cette page et l’outil divergent, fiez-vous à l’outil.

Connecter un agent

1. Ajoutez https://mcp.kurv.fun/mcp comme serveur MCP distant dans un client qui prend en charge le MCP distant avec OAuth. Connecter un agent avec MCP liste les clients et leurs étapes.
2. Connectez-vous à KURV dans le navigateur et approuvez la connexion. Vous choisissez ce qu’elle peut faire (lecture seule, lecture et brouillons, ou lecture, brouillons et préparation de lancement) et combien de temps elle dure.
3. Demandez à l’agent de lire kurv://blueprint, puis d’appeler kurv_account et kurv_builder_spec pour votre réseau. Le connecteur propose aussi le prompt build-kurv-collection, qui guide l’agent le long de cette page avec chaque arrêt d’approbation en place.

Qui fait quoi

L’agent planifie, valide, crée le brouillon, envoie l’art, prévisualise et prépare le lancement. Vous approuvez l’art, les échantillons et chaque avertissement, puis vous ouvrez le lien de vérification et signez le lancement avec votre propre portefeuille. L’agent ne déploie jamais, ne signe jamais et ne demande jamais de clé privée ni de phrase de récupération. Une fois l’art terminé et approuvé, la partie KURV (valider, créer, envoyer, prévisualiser, préparer) prend environ 20 minutes. Faire de l’art de qualité prend plus de temps, et c’est normal.

Les limites

Élément	Limite
Taille de la collection	De 1 à 1 000 pièces, uniques comprises : 980 pièces aléatoires et 20 uniques font une taille de 1 000.
Calques	Jusqu’à 12.
Images d’attributs	Jusqu’à 240 au total sur l’ensemble des calques, art utilisé uniquement par les uniques compris. Un calque vide ne coûte rien.
Uniques	Jusqu’à 32.
Règles	Jusqu’à 48, les mêmes sur chaque réseau.
Taille des fichiers image	Jusqu’à 2 Mio par image envoyée une à une ; jusqu’à 20 Mio pour une image dans un zip.
Canevas	Carré, jusqu’à 2 048 sur 2 048 pixels. Chaque fichier fait exactement la taille du canevas.
Formats	Background : PNG, JPEG ou WebP. Tous les autres calques : PNG avec une vraie transparence.
Le nom None	Réservé, quelle que soit la casse. Jamais un attribut appelé None, jamais une image vide : un calque devient facultatif grâce à noneWeight.
Description	À considérer comme obligatoire : de 1 à 2 000 caractères. Elle figure dans les métadonnées de chaque pièce.
Brouillons	20 actifs par compte. kurv_archive_draft libère un emplacement aussitôt ; l’art du brouillon archivé est conservé 30 jours, puis supprimé.
Aperçus	Jusqu’à 9 échantillons aléatoires par appel, ou jusqu’à 9 numéros de pièces choisis, de 64 à 512 pixels.

L’agent lit validCombinations après chaque validation : le nombre de pièces distinctes que permettent les calques et les règles. Il est compté exactement jusqu’à environ 50 millions de combinaisons et indiqué comme une estimation au-delà. Gardez-le largement au-dessus de la taille de la collection.

Le parcours, étape par étape

Les étapes marquées Approbation signifient que l’agent s’arrête et attend votre oui explicite.

1. Photos. Rassemblez de 3 à 10 photos nettes de l’animal ou du personnage réel : visage, yeux, dents et gueule, marques, oreilles. Choisissez une photo principale avec le visage de trois quarts.
2. Direction artistique. Un seul style, une seule pose (le trois-quarts marche le mieux), un seul canevas carré (2 048 sur 2 048 recommandé), une courte charte de style : trait, ombrage, palette, ambiance. Approbation : le personnage maître, avant la création du moindre attribut.
3. La base maître. Le personnage dans sa pose finale sur un fond uni d’une seule couleur, centré, à la taille du canevas, immédiatement reconnaissable comme l’animal réel. Chaque attribut est une retouche de ce maître, avec la même pose, la même échelle et le même cadrage.
4. Calques. Les calques se peignent de bas en haut : Background, Skin (le calque de base), Collar, Teeth, Eyes, Headwear (facultatif). Environ six calques ; c’est le personnage qui porte la collection, pas les accessoires. L’agent nomme le calque de base dans base_layer et donne à chaque calque une zone d’ancrage où ses attributs doivent se placer.
5. Attributs. Chaque attribut est une retouche d’une copie du maître, détourée pour que seuls les pixels propres à l’attribut soient visibles et que tout le reste soit transparent. Générer les attributs sur une copie du corps en couleur unie évite d’y laisser de la fourrure. Un attribut qui dérive en position ou en échelle est refusé.
6. Uniques. Des corps entièrement transformés (diamant, chrome, lave, bronze), chacun avec un fond assorti et sans collier. Leur art va dans son calque comme un attribut de poids 0, pour qu’il n’apparaisse jamais dans les pièces aléatoires ; il compte dans les 240 images.
7. Règles. Des planches contact de chaque Skin avec chaque attribut de Collar, Teeth, Eyes et Headwear. Chaque mauvaise paire (chevauchement, invisible, laide) devient une règle d’exclusion groupée, avec une note qui explique pourquoi.
8. Approbation : les planches des calques, au moins 9 échantillons composés, la planche des uniques, la configuration et les conditions de vente, avant la création du brouillon.
9. Configuration et validation. kurv_builder_spec avec le réseau, puis kurv_validate_collection avec la configuration jusqu’à ce que sa liste issues ne contienne plus aucune erreur. Les avertissements nomment ce dont vous devez être informé. La réponse contient required_assets, les clés exactes à envoyer, et validCombinations.
10. Le brouillon. kurv_create_collection avec version: 3, le réseau, la configuration, les conditions de vente et une clé d’idempotence, d’abord avec check_only à true, puis pour de bon. Un appel échoué est relancé avec la même clé. Les conditions de vente ont la même forme sur chaque réseau : voir Conditions de vente.
11. L’art. Une image à la fois avec kurv_upload_trait (le fond, la base et un attribut par calque d’abord, puis un aperçu, puis le reste), ou tout d’un coup au format de dossier du site via kurv_upload_collection_zip. Un calque vide est un noneWeight, jamais un PNG transparent.
12. Contrôle et aperçu. kurv_validate_collection avec le brouillon lance les contrôles de l’art. kurv_preview_collection avec 9 échantillons après le dernier envoi, plus les numéros de pièce de chaque unique et des combinaisons les plus risquées. L’agent regarde chaque image. Un premier aperçu long répond retry_after et les échantillons en attente ; l’agent rappelle.
13. Corrections sans nouveau brouillon. kurv_update_collection modifie sur place les règles, les uniques, les poids, les indications ou la description ; le canevas ne peut pas changer. kurv_replace_trait_image remplace une image, kurv_rename_trait renomme un attribut et met à jour ses règles et ses uniques, kurv_delete_trait supprime un attribut que rien ne référence. Puis un nouvel aperçu.
14. Approbation : les échantillons finaux et chaque avertissement, lus à voix haute pour vous.
15. Préparation. kurv_prepare_launch avec le brouillon. Sur warnings_need_review, l’agent explique chaque avertissement ; ce n’est qu’après votre accord qu’il rappelle avec acknowledge_warnings à true. Vous recevez un lien à ouvrir dans le navigateur.
16. Vous signez. Ouvrez le seul lien, vérifiez ce qui est rempli, choisissez Publier et lancer et signez avec votre propre portefeuille à la dernière étape. Chaque réponse est à un Retour de distance. Aucun outil ne signe pour vous.

Règles

Une règle sépare ou associe les attributs de deux calques : {"type", "when", "target", "note"}, où type vaut exclude ou require, et où when et target nomment chacun un calque et, en option, un attribut : un nom ou une liste de noms. Sans attribut, la règle porte sur tout le calque, et when et target doivent être des calques différents. La clé est trait : une règle écrite avec traits est refusée en nommant la bonne clé, au lieu de s’appliquer en silence à tout le calque. None ne peut désigner un calque vide que là où ce calque a un noneWeight supérieur à 0. Regroupez les paires en listes pour rester sous 48 : une règle par groupe de skins, avec la liste de tous les colliers qu’ils ne doivent jamais porter.

{"type": "exclude", "note": "Thick fur hides these collars", "when": {"layer": "Skin", "trait": ["Lion Mane", "Fire Fur"]}, "target": {"layer": "Collar", "trait": ["Bow Tie", "Name Tag"]}}

Les règles s’appliquent aux pièces : le même moteur génère l’aperçu et les fichiers publiés, et le mint distribue ces fichiers. Un unique peut ignorer les règles avec ignoreRules à true ; l’unicité reste garantie.

Uniques

Les uniques sont des specials : un nom, chaque calque avec son attribut ou None, un numéro de pièce épinglé facultatif et une description facultative. Un unique qui omet un calque reçoit ce calque au hasard, et la validation signale lesquels. null est refusé, de même qu’un nom d’attribut qui n’existe pas.

{"name": "Diamond Grail", "tokenId": 1, "traits": {"Background": "Diamond Vault", "Skin": "Pave Diamond", "Collar": "None", "Teeth": "Diamond Grill", "Eyes": "None"}}

L’art qui donne envie

• Un art soigné, travaillé. Pas d’aspect plat, terne ou visiblement généré.
• Des fonds forts : des couleurs franches ou des scènes riches. Évitez les thèmes de lieux (villes, plages), sauf s’ils sont voulus.
• Une pose de trois quarts et une ressemblance reconnaissable avec l’animal réel : marques, couleur des yeux, forme des oreilles.
• Des attributs marqués, ajustés au corps du personnage, dessinés sur la forme du maître. Les dents épousent exactement la gueule.
• Pas de couvre-chef qui flotte. Les chapeaux reposent sur la tête avec une ombre de contact ; les grandes oreilles passent par-dessus le bord.
• Les vêtements tombent souvent mal sur les animaux. Préférez les colliers, les chaînes et les accessoires de cou, et vérifiez-les sur chaque skin.
• Les uniques premium sont entièrement transformés, avec des fonds assortis et sans collier.

Le connecteur contrôle l’art à son arrivée. Les erreurs refusent un envoi : une taille de canevas différente, un calque au-dessus du fond qui n’est pas un PNG avec transparence, une image sans aucun pixel visible. Les avertissements vous sont renvoyés pour examen : un attribut hors de sa zone d’ancrage, un attribut à une autre échelle que son calque, un attribut décalé par rapport à la grille de pixels de la base, un attribut qui contient encore tout ou partie de l’image de base, un attribut qui couvre tout le canevas. Un avertissement peut être faux : des yeux naturels dans le même calque que des lunettes de soleil ont volontairement une autre taille. L’agent règle mixedScales sur ce calque, ou acknowledge sur l’attribut une fois que vous êtes d’accord, et l’art reste tel qu’il doit être.

Ce que l’agent reçoit en retour

Chaque outil de validation renvoie tous les problèmes d’un coup dans une seule liste issues, chacun avec un chemin, un code, une gravité, un message et une solution. Une clé inconnue est refusée en la nommant, avec la clé valide la plus proche. Le réseau est nommé (base-sepolia, solana-devnet, solana-localnet), et un brouillon qui n’en a pas utilise Base Sepolia et le signale. Les modes de vente portent les noms du site (fixed, mystery, rising, falling, auction) : via le connecteur, Base propose fixed, mystery et rising, Solana propose fixed et rising, et les ventes falling et auction se configurent sur le site. Un champ de vente que le réseau n’a pas, comme un symbole sur Solana, est refusé en le nommant. Les métadonnées sont vérifiées par un contrôle automatisé : chaque pièce respecte les règles, un unique atterrit sur la pièce à laquelle il est épinglé, et un calque vide est écrit {"trait_type": "<layer>", "value": "None"}.

Pièces finies

Les pièces qui existent déjà sous forme d’images finies se passent des calques : kurv_finished_art_limits, puis kurv_upload_finished_file_part pour chaque image et pour le metadata.json, puis kurv_import_finished_collection. Les octets sont conservés tels quels, animation comprise, et les limites des calques ne s’appliquent pas ; les limites de publication actuelles du site, si. Les œuvres finies explique les fichiers.

Limites connues de cette version

• Les valeurs d’une vente Solana en version 2 sont contrôlées par l’analyseur propre à l’app après les clés, une à la fois ; une vente en version 3 renvoie tous les problèmes d’un coup.
• Un brouillon d’œuvres finies ne peut pas être modifié sur place ; une correction demande un nouvel envoi et une nouvelle clé.
• Un brouillon archivé ne peut pas être restauré via le connecteur ; son art est conservé 30 jours.
• Robinhood Chain n’est pas disponible via le connecteur : aucune configuration de réseau et aucun schéma de vente. Elle viendra après les lancements sur Base et Solana.

Les chiffres d’une collection sont des instantanés, et un lancement déplace une valeur réelle sur son réseau ; lisez Risques et avertissement avant de conseiller qui que ce soit sur des questions d’argent.