The Collection Blueprint

KURV runs on Base Sepolia and Solana Devnet today. This page is the field guide from a complete build (HANI the Dog, 1,000 pieces, 20 uniques), written for a creator who works with an AI agent through the KURV connector at https://mcp.kurv.fun/mcp. The connector serves the same guide to agents as the resource kurv://blueprint, and the tool kurv_builder_spec is the source of truth: where this page and the tool disagree, trust the tool.

Connect an agent

1. Add https://mcp.kurv.fun/mcp as a remote MCP server in a client that supports remote MCP with OAuth. Connect an agent with MCP lists the clients and their steps.
2. Log in to KURV in the browser and approve the connection. You choose what it may do (read only, read and drafts, or read, drafts and launch preparation) and how long it lasts.
3. Ask the agent to read kurv://blueprint, then to call kurv_account and kurv_builder_spec for your network. The connector also offers the prompt build-kurv-collection, which walks the agent along this page with every approval stop in place.

Who does what

The agent plans, validates, creates the draft, uploads the art, previews and prepares the launch. You approve the art, the samples and every warning, then open the review link and sign the launch with your own wallet. The agent never deploys, never signs and never asks for a private key or seed phrase. Once the art is finished and approved, the KURV side (validate, create, upload, preview, prepare) takes about 20 minutes. Making good art takes longer, and it should.

The limits

Item	Limit
Collection size	1 to 1,000 pieces, uniques included: 980 random pieces and 20 uniques is a size of 1,000.
Layers	Up to 12.
Trait images	Up to 240 in total across all layers, art used only by uniques included. An empty layer costs nothing.
Uniques	Up to 32.
Rules	Up to 48, the same on every network.
Image file size	Up to 2 MiB per image sent one at a time; up to 20 MiB for one image inside a zip.
Canvas	Square, up to 2,048 by 2,048 pixels. Every file is exactly the canvas size.
Formats	Background: PNG, JPEG or WebP. Every other layer: PNG with real transparency.
The name None	Reserved in any capitalisation. Never a trait called None, never an empty image: a layer becomes optional through noneWeight.
Description	Treat as required: 1 to 2,000 characters. It goes into every piece’s metadata.
Drafts	20 active per account. kurv_archive_draft frees a slot at once; the archived draft’s art is kept 30 days and then removed.
Previews	Up to 9 random samples per call, or up to 9 chosen piece numbers, at 64 to 512 pixels.

The agent reads validCombinations after every validation: how many distinct pieces the layers and rules allow. It is counted exactly for spaces up to about 50 million combinations and labelled as an estimate above that. Keep it comfortably above the collection size.

The path, step by step

Steps marked Approval mean: the agent stops and waits for your explicit yes.

1. Photos. Collect 3 to 10 sharp photos of the real pet or character: face, eyes, teeth and mouth, markings, ears. Pick one hero photo with the face in a three-quarter view.
2. Art direction. One style, one pose (three-quarter works best), one square canvas (2,048 by 2,048 recommended), a short style sheet: line work, shading, palette, mood. Approval: the master character, before any trait is made.
3. The master base. The character in its final pose on a flat single-colour background, centred, at full canvas size, instantly recognisable as the real pet. Every trait is an edit of this master, with the same pose, scale and framing.
4. Layers. Layers paint from bottom to top: Background, Skin (the base layer), Collar, Teeth, Eyes, Headwear (optional). About six layers; the character carries the collection, not the props. The agent names the base layer in base_layer and gives each layer an anchor box where its traits must sit.
5. Traits. Each trait is an edit of a copy of the master, cut out so only the trait’s own pixels are visible and everything else is transparent. Generating traits on a flat-colour copy of the body keeps fur out of them. A trait that drifts in position or scale is rejected.
6. Uniques. Fully transformed bodies (diamond, chrome, lava, bronze), each with a matching background and no collar. Their art goes into its layer as a trait with a weight of 0, so it never appears in random pieces; it counts towards the 240 images.
7. Rules. Contact sheets of every skin with every collar, teeth, eye and headwear trait. Every bad pair (clipping, invisible, ugly) becomes a grouped exclude rule with a note that says why.
8. Approval: the layer sheets, at least 9 composited samples, the uniques sheet, the config and the sale terms, before the draft is created.
9. Config and validation. kurv_builder_spec with the network, then kurv_validate_collection with the config until its issues list holds no error. Warnings name what you should hear about. The answer carries required_assets, the exact keys to upload, and validCombinations.
10. The draft. kurv_create_collection with version: 3, the network, the config, the sale terms and an idempotency key, first with check_only set to true, then for real. A failed call is retried with the same key. The sale terms are one shape on every network: see Sale terms.
11. The art. One at a time with kurv_upload_trait (background, base and one trait per layer first, then a preview, then the rest), or all at once as the web folder format through kurv_upload_collection_zip. An empty layer is a noneWeight, never a transparent PNG.
12. Check and preview. kurv_validate_collection with the draft runs the art checks. kurv_preview_collection with 9 samples after the last upload, plus the piece numbers of every unique and the riskiest combinations. The agent looks at every image. A long first preview answers retry_after and the pending samples; the agent calls again.
13. Fixes without a new draft. kurv_update_collection changes rules, uniques, weights, hints or the description in place; the canvas cannot change. kurv_replace_trait_image swaps one image, kurv_rename_trait renames a trait and updates its rules and uniques, kurv_delete_trait removes a trait nothing references. Then a new preview.
14. Approval: the final samples and every warning, read out to you.
15. Prepare. kurv_prepare_launch with the draft. On warnings_need_review the agent explains each warning; only after you accept does it call again with acknowledge_warnings set to true. You get a browser link.
16. You sign. Open the one link, check what is filled in, choose Publish and launch, and sign with your own wallet on the final step. Every answer is one Back away. No tool signs for you.

Rules

A rule keeps two layers’ traits apart or together: {"type", "when", "target", "note"}, where type is exclude or require, and when and target each name a layer and, optionally, a trait: one name or a list of names. No trait means the whole layer, and when and target must be different layers. The key is trait: a rule written with traits is refused with the right key named, instead of applying silently to the whole layer. None may stand for an empty layer only where that layer has a noneWeight above 0. Group pairs into lists to stay under 48: one rule per group of skins, listing every collar they must never wear.

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

Rules reach the pieces: the same engine generates the preview and the published files, and minting hands out those files. A unique can skip the rules with ignoreRules set to true; uniqueness still holds.

Uniques

Uniques are specials: a name, every layer with its trait or None, an optional pinned piece number and an optional description. A unique that leaves a layer out gets that layer at random, and the validation warns which layers those are. null is refused, and so is a trait name that does not exist.

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

Art that people want

• High effort, polished art. No flat, muddy, obviously generated look.
• Strong backgrounds: bold colours or rich scenes. Avoid place themes (cities, beaches) unless they are intentional.
• Three-quarter pose and a recognisable likeness of the real pet: markings, eye colour, ear shape.
• Bold traits fitted to the character’s body, drawn on the master’s shape. Teeth match the mouth exactly.
• No floating headwear. Hats sit on the head with a contact shadow; big ears go over the brim.
• Clothing usually fits badly on animals. Prefer collars, chains and neckwear, and test them on every skin.
• Premium uniques are fully transformed, with matching backgrounds and no collar.

The connector checks the art as it arrives. Errors refuse an upload: a canvas size that differs, a layer above the background that is not a PNG with transparency, an image with no visible pixels. Warnings come back for you to review: a trait outside its anchor, a trait at another scale than its layer, a trait off the base’s pixel grid, a trait that still carries the base picture whole or in part, a trait covering the whole canvas. One warning can be false: natural eyes in the same layer as sunglasses are a different size on purpose. The agent sets mixedScales on that layer, or acknowledge on the trait once you agree, and the art stays as it should be.

What the agent reads back

Every validating tool answers every problem at once in one issues list, each with a path, a code, a severity, a message and a remediation. An unknown key is refused by name with the nearest valid one. The network is named (base-sepolia, solana-devnet, solana-localnet), and a draft without one uses Base Sepolia and says so. Sale methods use the website’s names (fixed, mystery, rising, falling, auction): through the connector Base offers fixed, mystery and rising, Solana offers fixed and rising, and falling and auction sales are set up on the website. A sale field the network has not, such as a ticker on Solana, is refused by name. The metadata is proven by a test: every piece honours the rules, a unique lands on the piece it is pinned to, and an empty layer is written as {"trait_type": "<layer>", "value": "None"}.

Finished pieces

Pieces that already exist as finished images skip the layers: kurv_finished_art_limits, then kurv_upload_finished_file_part for every image and the metadata.json, then kurv_import_finished_collection. The bytes are kept as given, animation included, and the layered limits do not apply; the website’s current publication limits do. Finished art explains the files.

Known limits of this build

• A version 2 Solana sale’s values are checked by the app’s own parser after the keys, one at a time; a version 3 sale answers every problem at once.
• A finished-art draft cannot be edited in place; a correction is a new upload and a new key.
• An archived draft cannot be restored through the connector; its art is kept 30 days.
• Robinhood Chain is not available through the connector: no network config and no sale schema. It comes after the Base and Solana launches.

Collection figures are snapshots and a launch moves real value on its network; read Risks and disclaimer before advising anyone on money.