Skip to main content

Schema Reference

This page documents all types, queries, inputs, and enums available in the Verse public GraphQL API.

Queries​

type Query {
  # Editions
  editionByNumber(artworkId: ID!, editionNumber: String!): Edition
  editionByContract(contractAddress: String!, tokenId: String!): Edition

  # Assets
  assetsPage(filter: AssetFilter, sorting: AssetSorting, after: Cursor, first: Int!): AssetConnection!
  asset(id: ID!, assetType: AssetType!): Asset

  # Primary Market
  primaryMarketListing(artworkId: ID!): PrimaryMarketListing
  primaryMarketListings(artworkId: ID!): [PrimaryMarketListing!]
  primaryMarketSale(pmSaleId: ID!): PrimaryMarketSale!

  # Secondary Market
  secondaryMarketSale(smSaleId: ID!): SecondaryMarketSale!
  smOfferMatchesPage(request: SMOfferMatchRequest!): SMOfferMatchConnection!

  # Fees
  artworkFees(artworkId: ID!): Fees!
  estimateSecondaryMarketFees(artworkId: ID!, price: InputAmount!, assetType: AssetType! = EDITION): FeeEstimation!
  mintPassConfiguration(pmListingId: ID!): MintPassConfiguration!

  # Marketplace
  stats(period: MarketplaceStatsPeriod!): MarketplaceStats!
  activityPage(filter: ActivityPageFilter, after: Cursor, first: Int!): ActivityEntryConnection!
  orders(request: MarketplaceOrdersRequest!): MarketplaceOrderConnection!

  # Discovery
  explore(filter: ExploreFilter, sorting: ExploreSorting, after: Cursor, first: Int! = 20): CollectionConnection!
  search(query: String!, params: SearchParams): SearchResult!

  # Entities
  artworksPage(request: ArtworksPageRequest!): ArtworkConnection!
  collectionsPage(request: CollectionsPageRequest!): CollectionConnection!
  exhibitionsPage(request: ExhibitionsPageRequest!): ExhibitionConnection!
  galleriesPage(request: GalleriesPageRequest!): GalleryConnection!
  linksPage(request: LinksPageRequest!): LinkConnection!
  personsPage(request: PersonsPageRequest!): PersonConnection!

  # Users
  userByUsername(username: String!): UserPublic
  userById(id: String!): UserPublic
  userByLinkedWallet(network: LinkedWalletNetwork!, address: String!): UserPublic
  usersByLinkedWallet(network: LinkedWalletNetwork!, addresses: [String]!): [UserPublic]!

  # Utility
  projectStaticAssetByHash(artworkId: ArtworkID!, hash: String!, editionNumber: Int, totalEditions: Int, userInput: [PreviewUserInput!]): StaticAsset!
  reverseResolveENS(addresses: [String!]!): [String!]!
}

Core Types​

Collection​

type Collection {
  id: ID!
  name: String
  slug: String!
  year: String
  description: Markdown
  blockchain: ProductChain!
  artworkIds: [ArtworkID!]!
  artworks: [Artwork!]!
  artists: [Person!]!
  persons: [Person!]!
  features: [Feature!]
  contract: ContractInfo
  previewAsset: StaticAsset
  banner: StaticAsset
  tags: [String!]
  isHidden: Boolean!
  updatedAt: Time
  featuredScore: Float!
  saleType: ArtworkSaleType!
  saleDetails: String
  license: String
  links: [Link!]!
  exhibitions: [Exhibition!]!
  tabs: [ExploreTabFilter!]

  # Statistics
  stats(filter: StatsFilter): CollectionStats!
  floorEdition: Edition
  floorListing: MarketplaceOrder
  bestOffer: MarketplaceOrder
  highestGlobalOffer: SecondaryMarketOffer
  osSlug: String
  contractAddress: String

  # Permissions
  canEdit: Boolean!
  canMint: Boolean!
}

Artwork​

type Artwork {
  id: ArtworkID!
  title: String
  year: String
  bio: Markdown
  blockchain: ProductChain!
  saleType: ArtworkSaleType!
  saleDetails: String
  displayStyle: DisplayStyle!
  license: String
  isHidden: Boolean!
  featuredScore: Float!
  updatedAt: Time
  expectedSaleDate: Time
  requiresShippingDetails: Boolean!
  secondaryMarketSaleWithPhysical: Boolean!
  secondaryMarketDisabled: Boolean!

  # Relationships
  artist: Person
  collection: Collection
  editions(first: Int! = 50000, editionId: ID): [Edition!]!
  myEditions: [Edition!]!
  features: [Feature!]
  links: [Link!]!
  exhibitions: [Exhibition!]!
  artworkKind: ArtworkKind
  cover: StaticAsset
  banner: StaticAsset

  # Sales
  primaryMarketListing: PrimaryMarketListing
  primaryMarketListings: [PrimaryMarketListing!]
  fees: Fees
  smSellingOptions: SMArtworkSellingOptions!

  # Market data
  stats(filter: StatsFilter): ArtworkStats!
  floorEdition: Edition
  floorListing: MarketplaceOrder
  bestOffer: MarketplaceOrder
  highestGlobalOffer: SecondaryMarketOffer
  osSlug: String
  contractAddress: String
}

ArtworkKind​

The artworkKind field on Artwork resolves to one of these project types:

union ArtworkKind =
  | ProjectArtworkKind
  | GenerativeProjectArtworkKind
  | ArtblocksProjectArtworkKind
  | QuasiDragonsCompositeArtworkKind

ProjectArtworkKind​

Represents an artist-curated project — a set of pre-selected artworks listed for sale.

type ProjectArtworkKind {
  items: [ProjectItem!]!
  withRepetitions: Boolean!
  allowUserSelection: Boolean!
}

type ProjectItem {
  id: ID!
  staticAssetId: StaticAssetID!
  staticAsset: StaticAsset!
  isAvailable: Boolean!
  probability: Float
  featuresJson: String
}
  • allowUserSelection — When true, collectors choose which item to buy. When false, a random item is assigned on purchase.
  • withRepetitions — When true, the same item can be sold multiple times.
  • isAvailable — Whether the item can still be purchased.
  • featuresJson — JSON string containing trait/feature attributes for the item.

Edition​

type Edition {
  id: ID!
  artworkId: ID!
  artwork: Artwork!
  editionNumber: Int!
  hash: String
  tokenId: String
  title: String
  description: String
  status: EditionStatus!
  mintingOptionType: MintingOptionType!
  createdAt: Time!
  tokenUri: String
  likes: Int!
  isLiked: Boolean!
  primaryMarketListingId: ID!

  # Asset
  asset: Asset!
  staticAsset: StaticAsset
  features: [FeatureValue!]
  userInput: [EditionUserInput!]

  # Ownership
  owner: EditionOwner!
  contractInfo: ContractInfo
  events: [EditionEvent!]!

  # Market
  smListing: SecondaryMarketListing
  osListing: OpenseaListing
  floorListing: MarketplaceOrder
  bestOffer: MarketplaceOrder
  stats: EditionStats!
}

Edition Status​

enum EditionStatus {
  NOT_MINTED          # Created but not yet minted
  MINTING             # Minting transaction in progress
  ON_PLATFORM         # Minted and held on Verse
  WITHDRAWAL_REQUESTED # User requested withdrawal
  WITHDRAWING         # Withdrawal transaction in progress
  WITHDRAWN           # Sent to user's wallet
  DEPOSIT_REQUESTED   # Deposit back to Verse requested
  BURNED              # Token burned
}

Primary Market Types​

PrimaryMarketListing​

type PrimaryMarketListing {
  id: ID!
  artwork: Artwork!
  strategy: PrimaryMarketStrategy!
  createdAt: Time!
  startedAt: Time
  endedAt: Time
  endReason: PMListingEndReason
  startsAt: Time!
  endsAt: Time!
  pmSales: [PrimaryMarketSale!]!
  editionTarget: Edition
}

# Strategy is one of:
union PrimaryMarketStrategy =
  | PMBuyNowLimitedEditionStrategy
  | PMBuyNowOpenEditionStrategy
  | PMAuctionStrategy

Buy Now (Limited Edition)​

type PMBuyNowLimitedEditionStrategy {
  pmListingId: ID!
  price: Amount!
  maxEditions: Int!
  reservedEditions: Int!
  stats: PMBuyNowStats!
  dutchAuction: DutchAuctionSettings      # if dutch auction enabled
  decreasingSupply: DecreasingSupplySettings # if decreasing supply enabled
  purchaseQueue: PurchaseQueueStatus        # if queue enabled
}

Buy Now (Open Edition)​

type PMBuyNowOpenEditionStrategy {
  pmListingId: ID!
  price: Amount!
  stats: PMBuyNowStats!
  dutchAuction: DutchAuctionSettings      # if dutch auction enabled
}

Auction​

type PMAuctionStrategy {
  pmListingId: ID!
  minimumBid: Amount!
  bids: [PrimaryMarketBid!]!
  stats: PMAuctionStats!
  auctionBrackets: [PMAuctionBracket!]
  rankedAuctionSettings: RankedAuctionSettings  # if ranked auction
  extensionSettings: ExtensionSettings
  currentStep: Decimal
  entryBid: Amount
  myWinningBids: [PrimaryMarketBid!]!
  leaders: [PrimaryMarketBid!]!
  lowestWinningBid: PrimaryMarketBid
}

Secondary Market Types​

SecondaryMarketListing​

type SecondaryMarketListing {
  id: ID!
  edition: Edition
  asset: Asset!
  artwork: Artwork!
  isActive: Boolean!
  offersStrategy: SMOfferStrategy!
  additionalStrategies: [AdditionalSecondaryMarketStrategy!]!
  owner: UserPublic!
  smSale: SecondaryMarketSale
  createdAt: Time!
  endedAt: Time
  listedAt: Time
}

MarketplaceOrder​

type MarketplaceOrder {
  id: ID!
  orderSide: MarketplaceOrderSide!  # ASK or BID
  usdPrice: Decimal!
  price: Amount!
  source: String!
  sourceOrderId: String!
  createdAt: Time!
  expiresAt: Time!
  updatedAt: Time!
  quantity: Decimal!
  filledQuantity: Decimal!
  chain: Chain!
  artwork: Artwork
  asset: Asset
  collection: Collection
  maker: UserOrBlockchainAddress!
}

Marketplace & Activity Types​

ActivityEntry​

type ActivityEntry {
  id: ID!
  entryType: ActivityEntryType!
  timestamp: Time!
  amount: String!
  edition: Edition
  asset: Asset
  assetType: AssetType!
  artwork: Artwork!
  artworks: [Artwork!]!
  fromUserId: UserPublic
  toUserId: UserPublic
  fromBlockchainAddress: String
  toBlockchainAddress: String
  transactionHash: String
  offerId: ID
}

enum ActivityEntryType {
  PM_SALE             # Primary market purchase
  SM_LISTED           # Listed on secondary market
  SM_DELISTED         # Removed from secondary market
  SM_SALE             # Sold on secondary market
  SM_OFFER            # Offer made
  SM_GLOBAL_OFFER     # Global offer on artwork
  OS_SALE             # Sold on OpenSea
  OS_OFFER            # Offer on OpenSea
  OS_COLLECTION_OFFER # Collection offer on OpenSea
  OS_LISTED           # Listed on OpenSea
  NEW_FLOOR_PRICE     # Floor price changed
}

Filtering & Sorting Inputs​

AssetFilter​

input AssetFilter {
  ids: [ID!]
  assetType: AssetType! = EDITION
  artworkIds: [ID!]
  artistIds: [ID!]
  hashes: [String!]
  availability: [AssetFilterAvailabilityOption!]  # BUY_NOW, ACCEPTING_OFFERS
  owners: [AssetFilterOwner!]
  features: [AssetFilterFeature!]
  advancedFeatures: AssetAdvancedFeatureFilter
  includeCollectionTags: [String!]
  excludeCollectionTags: [String!]
}

enum AssetSortOption {
  CREATED_AT
  LIST_PRICE
  EDITION_NUMBER
  LAST_SALE_PRICE
  LAST_SALE_TIME
  OWNER
  LIKED
  TITLE
  LISTED_AT
  LAST_TRANSFERRED_AT
}

ExploreFilter​

input ExploreFilter {
  exploreTab: [ExploreTabFilter!]  # LIVE, UPCOMING, OPEN, CLOSED, CLOSING_SOON
  market: [ExploreFilterMarket!]   # PRIMARY, SECONDARY
  assetType: [ExploreFilterAssetType!]  # IMAGE, VIDEO, OTHER
  artistIds: [PersonID!]
  personIds: [PersonID!]
  containsTags: [String!]
  notContainsTags: [String!]
}

enum ExploreSortOption {
  LAST_SALE_TIME
  RECENCY
  ENDED_AT
  FLOOR_PRICE
  FEATURED_SCORE
  UPCOMING
}

Common Types​

Amount​

type Amount {
  value: Decimal!
  currency: String!  # "ETH", "USD", "USDC", etc.
}

PageInfo​

type PageInfo {
  startCursor: Cursor
  endCursor: Cursor
  hasNextPage: Boolean!
  hasPreviousPage: Boolean!
}

StaticAsset​

union StaticAsset = VideoAsset | ImageAsset | SVGAsset | AudioAsset | IFrameAsset

Each asset type implements IStaticAsset with at minimum id, baseUrl, and internalTitle fields.

baseUrl is a template, not a ready-to-use URL

The baseUrl field contains {{SIZE}} and {{FORMAT}} placeholders that must be replaced before use. If you see literal {{SIZE}} in your network requests, you need to substitute the placeholders first:

// Replace placeholders to get a usable image URL
const imageUrl = baseUrl
  .replace("{{SIZE}}", "w640")        // width: w80, w160, w320, w480, w640, w980, w1400, w2400, w3840, or "source"
  .replace("{{FORMAT}}", "webp");     // format: webp, jpeg, png, gif, avif

// For SVGs and original files, strip the format segment:
const originalUrl = baseUrl
  .replace("{{SIZE}}", "source")
  .replace("@{{FORMAT}}", "");

For VideoAsset, baseUrl is a direct video URL (no placeholders). For thumbnails of non-image types, use previewImageUrl instead.

See Static Assets for the full guide on rendering each asset type.

ContractInfo​

type ContractInfo {
  contractAddress: String!
  contractType: ContractType!
  chain: ProductChain!
}

UserPublic​

type UserPublic {
  id: ID!
  username: String
  bio: String
  profilePic: String
  profileBanner: String
  twitterHandle: String
  linkedWallets: [LinkedWallet!]!
  editions: [Edition!]!
  withdrawnEditions: [Edition!]!
}

Person (Artist/Curator/Gallery)​

type Person {
  id: PersonID!
  slug: String!
  name: String
  bio: Markdown
  isArtist: Boolean!
  isCurator: Boolean!
  isGallery: Boolean!
  cover: ImageAsset
  artworks: [Artwork!]!
  collections: [Collection!]!
  exhibitions: [Exhibition!]!
  profileLinks: [String!]!
  location: String
  bioLine: String
}

Enums Reference​

Blockchain & Contract​

enum ProductChain { NONE, ETHEREUM, TEZOS, BASE, SOLANA, PHYSICAL, BITCOIN }
enum Chain { ETHEREUM, SOLANA, TEZOS, BITCOIN, BASE, NOT_SPECIFIED }
enum ContractType {
  ERC_721, ERC_721_CURATED, ERC_721v3, ERC_721v3_ON_CHAIN, ERC_721v3_CUSTOM_v1,
  ERC_1155, ERC_1155v2, SOLANA, ARTBLOCKS, TEZOS_FXHASH, TEZOS_OBJKT
}

Market​

enum Market { PRIMARY, SECONDARY, OPENSEA }
enum MarketplaceOrderSide { ASK, BID }
enum MarketplaceStatsPeriod { PERIOD_1D, PERIOD_7D, PERIOD_30D, PERIOD_ALL_TIME }

Sale Status​

enum ArtworkSaleType { REGULAR, PRIVATE, NOTFORSALE, SILENT }
enum PrimaryMarketSaleStatus { PENDING, SUCCESS, FAILED }
enum SecondaryMarketSaleStatus { PENDING, SUCCESS, FAILED }
enum PrimaryMarketBidStatus { PENDING, PLACED, OUTBID, WINNER, FAILED }

Sorting​

enum SortDirection { ASC, DESC }

Scalar Types​

ScalarDescription
CursorOpaque pagination cursor
DecimalArbitrary precision decimal
TimeISO 8601 datetime
MarkdownMarkdown-formatted text
ArtworkIDArtwork identifier
PersonIDPerson identifier
StaticAssetIDStatic asset identifier
ExhibitionIDExhibition identifier
GalleryIDGallery identifier
LinkIDLink identifier