Verse Elements

Verse Elements is a lightweight SDK that lets your website perform authenticated user actions on Verse — sign in, sign out, show a purchase dialog, check reserves — without embedding the full Verse UI.

Under the hood, Verse Elements uses hidden iframes and penpal to communicate with Verse. The iframes are sandboxed and managed by the SDK — you don't need to deal with them directly.

Verse Elements vs Verse Frame

	Verse Frame	Verse Elements
Approach	Embed the Verse website as an iframe	Use Verse as an API from your own website
UI	Verse's UI, with optional style tweaks	You build all the UI and logic
Data fetching	Handled by the iframe	Use Verse GraphQL API for public data (artworks, prices, artists) and Verse Elements for auth-related actions
Control	Limited — the overall flow stays the same	Full — you decide the layout, flow, and UX

Use Verse Frame when you want a quick, drop-in integration that looks and works like Verse out of the box.

Use Verse Elements when you need full control over the user experience and only need Verse for authenticated operations.

Quick Start

Add the script from the verse-embedded npm package and initialize:

<script src="https://unpkg.com/verse-embedded@1.1.4/dist/verse-elements.js"></script>

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

Then call methods directly on the elements instance:

// Check if user is signed in
const isSignedIn = await elements.checkAuth();

// Sign in
const result = await elements.authorise();

// Open a purchase dialog
elements.openPurchaseDialog(artworkId, payload, callbacks);

// Check reserve access
const reserves = await elements.checkReserves(artworkId);

Available Methods

Method	Description
checkAuth()	Check if the user is authenticated
authorise()	Open sign-in dialog
signOut()	Sign out the current user
openPurchaseDialog()	Show a full-screen purchase dialog
checkReserves()	Check reserve access for an artwork
createBookmark()	Generate a bookmark token for collector-curated projects

See the API Reference for full details on each method.

Debugging

For development and debugging, use the sandbox iframe origin and the sandbox API:

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

// Demo API endpoint for debugging
const apiUrl = "https://demo.verse.works/query";

See the Sandbox Environment guide for test accounts and Stripe test cards.

Requirements

• Production (iframe.verse.works): Your domain must be on the Verse origin allowlist (localhost:3000 is allowlisted by default; contact the Verse team for other domains)
• Sandbox (iframe.demo.verse.works): No allowlisting needed — works from any domain, including localhost
• HTTPS is required in production

Next Steps

• API Reference — Full method documentation with types
• Integration Guide — End-to-end example combining Elements with the GraphQL API