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()

Opens a sign-in dialog overlay. The user can close the dialog without signing in.

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

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

const result = await elements.authorise();

if (result) {
  console.log("Signed in as", result.verseUsername);
  console.log("User ID:", result.verseUserId);
} else {
  console.log("User closed the dialog");
}

---

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.

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 minted edition details.
• 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.

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.

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");
    },
  }
);