API Reference

Constructor

const elements = new VerseElements({
  baseUrl: "https://iframe.verse.works",
});

Option	Type	Description
baseUrl	string	Required. The Verse iframe origin URL

For debugging, use https://iframe.demo.verse.works as the baseUrl and https://demo.verse.works/query as the GraphQL API endpoint.

---

checkAuth()

Check if the current user is authenticated on Verse.

Returns: Promise<boolean>

const isSignedIn = await elements.checkAuth();

if (isSignedIn) {
  // User has an active Verse session
} else {
  // User is not signed in
}

---

authorise(options?)

Opens a sign-in or sign-up dialog overlay. The user can close the dialog without completing authentication.

Parameters:

Parameter	Type	Default	Description
options.mode	"signin" | "signup"	"signin"	Which authentication page to show

Returns: Promise<VerseAuthResult | null> — returns null if the user closes the dialog.

// VerseAuthResult
{
  success: boolean
  verseUserId?: string
  verseUsername?: string
}

// Open sign-in (default)
const result = await elements.authorise();
if (result) {
  console.log("Signed in as", result.verseUsername);
}

// Open sign-up
const result = await elements.authorise({ mode: "signup" });
if (result) {
  console.log("Signed up as", result.verseUsername);
}

---

signOut()

Signs out the currently authenticated user.

Returns: Promise<void>

Throws: if no user is signed in or the sign-out operation fails.

await elements.signOut();

---

openPurchaseDialog(artworkId, payload, callbacks)

Shows a full-screen purchase dialog. A loading spinner overlay is displayed while the dialog loads.

info

Each purchase dialog handles a single edition — batch or multi-quantity mints are not supported. To purchase multiple editions, the collector must complete separate transactions.

Parameters:

Parameter	Type	Description
artworkId	string	The artwork to purchase
payload	PurchasePayload	Purchase configuration
callbacks	PurchaseCallbacks	Event handlers

Returns: Promise<{ destroy: () => void }> — call destroy() to programmatically close the dialog.

PurchasePayload

{
  amount?: {
    value: string;     // e.g. "100"
    currency: string;  // e.g. "USD", "ETH"
  }
  userInput?: Array<{
    key: string;
    value: string;
    signedToken?: string;
  }>
  isReservation?: boolean
}

Recognised userInput keys

Key	Used for	Value
$curated_project:item_id	Artist-curated projects with user selection	The id of the selected ProjectItem
$user_hash	Collector-curated projects	The signedToken from createBookmark()

PurchaseCallbacks

{
  onSuccess(data: {
    editionId: string;
    editionNumber: number;
    artworkId: string;
  }): void

  onTerminalFailure(data: {
    title: string;
    message: string;
  }): void

  onClose(): void
}

• onSuccess — Called when the purchase completes. Provides the edition details (see note below on minting timing).
• onTerminalFailure — Called only for irrecoverable errors (sold out, payment timeout). Retryable errors (e.g. outbid in auction) are handled within the dialog UI.
• onClose — Called when the user closes the dialog.

Minting timing

onSuccess fires when the purchase is confirmed, but the on-chain NFT mint happens asynchronously — typically within 20 seconds to 5 minutes. At the time onSuccess fires:

• editionNumber is available immediately. This is Verse's internal edition number and may differ from the on-chain tokenId.
• tokenId is not yet available. It becomes available on the Edition entity once the mint completes and the edition status moves to ON_PLATFORM.

To check minting status and retrieve the tokenId, poll the edition via the GraphQL API:

query EditionStatus($editionId: ID!) {
  asset(id: $editionId, assetType: EDITION) {
    asset {
      ... on Edition {
        editionNumber
        tokenId
        status
      }
    }
  }
}

See Edition Lifecycle for the full status progression.

Example

const { destroy } = await elements.openPurchaseDialog(
  artworkId,
  {
    amount: { currency: "USD", value: "100" },
    userInput: [],
  },
  {
    onSuccess({ editionId, editionNumber, artworkId }) {
      console.log("Purchase succeeded", { editionId, editionNumber, artworkId });
    },
    onTerminalFailure({ title, message }) {
      console.error(`Purchase failed: ${title} — ${message}`);
    },
    onClose() {
      console.log("User closed the dialog");
    },
  }
);

// Optionally close the dialog programmatically
// destroy();

---

checkReserves(artworkId, reserveId?)

Check whether the current user has reserve access for an artwork.

warning

The user must be authenticated via authorise() before calling checkReserves(). The check runs against the signed-in Verse account. For wallet reserves, the collector must have the relevant wallet connected to their Verse account.

Parameters:

Parameter	Type	Description
artworkId	string	The artwork to check
reserveId	string (optional)	A specific reserve ID to check against

Returns: Promise<ReservesResult>

// ReservesResult
{
  hasAccess: boolean;            // Whether the user can purchase
  reserveAccess: {
    hasAccess: boolean;          // Whether the user has reserve access
    reserveRequired: boolean;    // Whether a reserve is required to purchase
    reserves: number | null;     // Number of reserves available for this user
  }
}

Throws: if the artwork has no active listing or the query fails.

const result = await elements.checkReserves(artworkId);

const reserves = result.reserveAccess?.reserves ?? 0;

if (!result.hasAccess) {
  // Sale is gated and user has no reserve → block purchase
  console.log("Reserve required — user is not eligible");
} else if (reserves > 0) {
  // User holds reserves for this drop
  console.log(`User has ${reserves} reserve(s)`);
} else {
  // Sale is open to the public, no reserve needed
  console.log("Open to all — no reserve required");
}

---

createBookmark(artworkId)

Generate a bookmark token for an artwork. Used with collector-curated projects where collectors save their favorite algorithm output before purchase.

The returned signedToken can be passed as $user_hash in userInput when opening a purchase dialog.

Parameters:

Parameter	Type	Description
artworkId	string	The artwork to bookmark

Returns: Promise<BookmarkResult>

// BookmarkResult
{
  hash: string;
  signedToken: string;
}

Example: Bookmark + Purchase

// 1. User picks their favorite output — create a bookmark
const bookmark = await elements.createBookmark(artworkId);

// 2. Open purchase dialog with the bookmark token
elements.openPurchaseDialog(
  artworkId,
  {
    userInput: [{ key: "$user_hash", value: bookmark.signedToken }],
  },
  {
    onSuccess({ editionId }) {
      console.log("Purchased edition:", editionId);
    },
    onTerminalFailure({ title, message }) {
      console.error(`Failed: ${title} — ${message}`);
    },
    onClose() {
      console.log("Closed");
    },
  }
);