Skip to main content

GraphQL API

The Verse Public GraphQL API provides read access to collections, artworks, editions, sales, marketplace data, and more. It is designed for developers building applications, dashboards, or integrations on top of Verse.

Before integrating sale logic, read Release & Sales Mapping and Glossary and Name Mapping.

Endpoint​

https://verse.works/query

Authentication​

The public API requires no authentication. All queries return publicly available data.

info

If you need to perform actions on behalf of authenticated users (e.g., checking reserves, purchase eligibility), use the Verse Elements integration instead.

Quick Start​

Send a POST request with a JSON body containing your GraphQL query:

curl -X POST https://verse.works/query \
  -H "Content-Type: application/json" \
  -d '{
    "query": "{ collectionsPage(request: { first: 5 }) { nodes { name slug blockchain } } }"
  }'

Or use any GraphQL client:

const response = await fetch("https://verse.works/query", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    query: `
      query GetCollection($slug: String!) {
        collectionsPage(request: {
          filter: { slugs: [$slug] }
          first: 1
        }) {
          nodes {
            id
            name
            slug
            blockchain
            artworks {
              id
              title
              primaryMarketListing {
                startsAt
                endsAt
              }
            }
            stats {
              issuedEditions
              ownersCount
              floorPrice { value currency }
              tradedVolume { value currency }
            }
          }
        }
      }
    `,
    variables: { slug: "fields-by-erik-swahn" },
  }),
});

Core Query Types​

Collections & Artworks​

QueryDescription
collectionsPagePaginated list of collections with filtering
artworksPagePaginated list of artworks with filtering
editionByNumberSingle edition by artwork ID and edition number
editionByContractSingle edition by contract address and token ID
searchFull-text search across artists, collections, and exhibitions
exploreBrowse collections with market/tab filters

Sales & Marketplace​

QueryDescription
primaryMarketListingActive primary sale for an artwork
primaryMarketListingsAll primary sales for an artwork
primaryMarketSaleSingle completed primary sale
secondaryMarketSaleSingle completed secondary sale
ordersMarketplace orders (listings and offers)
activityPageActivity feed (sales, listings, offers, transfers)
statsMarketplace statistics by time period

Users & Assets​

QueryDescription
assetsPagePaginated assets (editions, bookmarks) with filtering
assetSingle asset by ID
userByUsernameUser profile by username
userByIdUser profile by ID
userByLinkedWalletUser by wallet address

Additional​

QueryDescription
artworkFeesFee structure for an artwork
estimateSecondaryMarketFeesEstimate fees for a secondary sale
mintPassConfigurationMint pass requirements
personsPageArtists, curators, and galleries
exhibitionsPageExhibitions and curated shows
galleriesPageGallery profiles

Pagination​

The API uses cursor-based pagination. All paginated queries accept first (page size) and after (cursor) parameters:

query {
  collectionsPage(request: { first: 20, after: "cursor-value" }) {
    pageInfo {
      endCursor
      hasNextPage
    }
    nodes {
      id
      name
    }
  }
}

Filtering​

Most page queries support rich filtering. Example for assets:

query {
  assetsPage(
    filter: {
      artworkIds: ["artwork-uuid"]
      availability: [BUY_NOW]
      features: [{ name: "Color", value: "Blue" }]
    }
    sorting: { sort: LIST_PRICE, direction: ASC }
    first: 20
  ) {
    totalCount
    nodes {
      id
      assetType
      asset {
        ... on Edition {
          editionNumber
          tokenId
        }
      }
    }
  }
}

Supported Blockchains​

The ProductChain enum indicates which blockchain a collection or artwork is deployed on:

enum ProductChain {
  ETHEREUM
  BASE
  TEZOS
  SOLANA
  BITCOIN
  PHYSICAL
  NONE
}
note

Primary market releases on Verse are currently available on Ethereum mainnet and off-chain (PHYSICAL / NONE). Other chain values exist in the schema for secondary market data surfaced from external platforms.

Error Handling​

The API returns standard GraphQL errors. Check the errors array in the response:

{
  "data": null,
  "errors": [
    {
      "message": "artwork not found",
      "path": ["artworksPage"]
    }
  ]
}

Working with Media​

When you query artwork covers or static assets, the returned baseUrl is a template URL — not a direct link. You must replace {{SIZE}} and {{FORMAT}} placeholders before displaying the image. See Static Assets for the full guide, including which field to use for each asset type and how to handle videos, SVGs, and iframes.

Next Steps​