Entity Model
The Verse platform is built around three core entities: Collections, Artworks, and Editions.
Entity Hierarchy
Collections
A Collection (also referred to as a "series" in the UI) is the top-level container. It groups one or more artworks under a single project.
For projects released on Verse, each collection is tied to a smart contract — one contract per collection. All editions across all artworks in the collection are minted on that same contract. For imported works (and some older Verse releases), multiple collections may reference the same contract.
In the API, collections are queried via collectionsPage, explore, or search. See the Schema Reference for full details.
Display behavior on verse.works:
- If a collection has an artwork with an active/upcoming primary sale, the sale is featured at the top of the page.
- If multiple artworks have active sales, a grid of artworks is shown.
- If no active sales exist, a grid of editions is displayed.
When embedding via Verse Frame, we recommend embedding by collection slug (verse-series-slug) rather than individual artwork ID.
Artworks
An Artwork is a container for editions and the entity on which primary market sales are configured.
The most common setup is a collection with a single artwork, where the artwork holds all the editions (e.g., a generative project with 500 editions). However, multiple artworks within one collection are useful when you want to sell many unique 1/1 pieces under the same collection and contract.
Each artwork can have:
- A primary market listing (the sale configuration)
- Multiple editions (the NFTs that collectors receive)
- Features/traits (for generative or curated projects)
- Cover and banner assets
Artworks are queried via artworksPage or accessed through their parent collection. See the Schema Reference.
Editions
An Edition is an individual asset that a collector owns after making a purchase. In most cases, an edition is an NFT minted on-chain, but editions can also be off-chain (e.g., physical or digital assets that don't require blockchain minting).
An edition is created on Verse at the time of purchase, before the on-chain NFT mint takes place. The on-chain mint happens asynchronously — typically within 20 seconds to 5 minutes after purchase. Once minted, the edition's status moves to ON_PLATFORM and the tokenId (the on-chain token ID) becomes available. Note that editionNumber (Verse's internal numbering) and tokenId may differ.
Each edition belongs to an artwork and has:
- An edition number (assigned at purchase time)
- A token ID (available once minted on-chain — may differ from edition number)
- An owner
- A status (see lifecycle below)
- Optional features/traits
Editions can be queried via editionByNumber, editionByContract, or assetsPage. See the Schema Reference.
Edition Lifecycle
Terminology Mapping
While the UI and community may use different terms, the API consistently uses:
| API Term | Alternative Names | Description |
|---|---|---|
Collection | Series | Top-level grouping, tied to a smart contract |
Artwork | Release | Container for editions and sales |
Edition | NFT, Token | Individual owned asset |
Relationships with Sales
See Primary Sales and Secondary Sales for details on how sales work.