Installation via package manager

For any project with a bundler: install the packages, set the config in a module that runs first, and import the components you use.

Prerequisites

1. A package manager (npm, yarn, pnpm, or bun) and a bundler.
2. A merchant account on the Frak business dashboard with your domain registered. The main domain is registered at sign-up; add subdomains under Allowed Domains.

If you have not done that yet, start with the Get started guide.

1. Install

Package	What it gives you
@frak-labs/components	The <frak-*> web components. Importing one registers it and boots the SDK.
@frak-labs/core-sdk	The client and the actions, for anything you drive yourself.

npm

npm install @frak-labs/components @frak-labs/core-sdk

yarn

yarn add @frak-labs/components @frak-labs/core-sdk

pnpm

pnpm add @frak-labs/components @frak-labs/core-sdk

bun

bun add @frak-labs/components @frak-labs/core-sdk

viem is a peer dependency

@frak-labs/core-sdk declares viem@^2.x as a peer dependency. Most bundlers install it for you; add it explicitly if yours does not.

2. Configure

Put the config in its own module so it runs before anything imports a component:

frak-setup.ts

import type { FrakWalletSdkConfig } from "@frak-labs/core-sdk";

declare global {
  interface Window {
    FrakSetup: { config?: FrakWalletSdkConfig };
  }
}

window.FrakSetup = {
  config: {
    metadata: {
      name: "Your Store",
      currency: "eur",
    },
  },
};

Targeting the dev stage

env states both origins the SDK talks to: "prod" (the default), "dev", or an explicit { wallet, backend } pair for local development. It replaces walletUrl and lands in the next major of the SDK, so on the version published today use walletUrl instead. See Configuration.

Every field is listed on the FrakSetup reference and in Configuration.

3. Register the components

Import your config module first, then each component you use. The imports are side-effectful: they register the custom element and boot the SDK from window.FrakSetup.config.

main.ts

import "./frak-setup";
import "@frak-labs/components/banner";
import "@frak-labs/components/buttonShare";
import "@frak-labs/components/postPurchase";

Available subpaths: banner, buttonShare, buttonWallet, openInApp, postPurchase. There is no root import, so import the subpath you need.

Then use the elements in your markup:

<frak-banner></frak-banner>
<frak-button-share classname="button"></frak-button-share>

Attributes are kebab-case, properties are camelCase

In HTML, write no-reward-text, not noRewardText. To update a value after the element is rendered, set the JS property (el.products = [...]), because a later attribute mutation does not re-render.

4. Call the actions

Actions live in @frak-labs/core-sdk/actions. All of them except trackPurchaseStatus take the client as their first argument, and the client is published on window.FrakSetup.client once the SDK is ready:

import { displayModal, watchWalletStatus } from "@frak-labs/core-sdk/actions";
import type { FrakClient } from "@frak-labs/core-sdk";

function waitForClient(): Promise<FrakClient> {
  if (window.FrakSetup?.client) return Promise.resolve(window.FrakSetup.client);
  return new Promise((resolve) => {
    window.addEventListener(
      "frak:client",
      () => resolve(window.FrakSetup.client as FrakClient),
      { once: true }
    );
  });
}

const client = await waitForClient();

await watchWalletStatus(client, (status) => {
  console.log(status.key === "connected" ? status.wallet : "not connected");
});

await displayModal(client, {
  steps: {
    login: {},
    final: { action: { key: "sharing" } },
  },
});

Track a purchase

import { trackPurchaseStatus } from "@frak-labs/core-sdk/actions";

await trackPurchaseStatus({
  customerId: "cust_123",
  orderId: "order_456",
  token: "a-unique-order-token",
});

Rewards are only released once your backend confirms the order with a signed webhook. See Validate purchases from your backend.

What is available

Action	Purpose
watchWalletStatus	Current wallet status, plus every change
displayModal	Open a modal built from steps (login, final, and more)
displaySharingPage	Open the sharing page directly
displayEmbeddedWallet	Open the embedded wallet view
sendInteraction	Send an interaction, fire and forget
trackPurchaseStatus	Register an order so a confirmed sale can pay a reward
referralInteraction, processReferral, setupReferral	Handle an inbound referral
getMerchantInformation	Your merchant data as resolved by the backend
getUserReferralStatus, getMergeToken	Referral state and wallet merge token
openSso, prepareSso, prepareSsoUrl	Single sign-on flows
siweAuthenticate	Sign-In with Ethereum
sendTransaction	Ask the wallet to send a transaction
modalBuilder	Fluent builder for modal steps

Full signatures live in the generated SDK reference.

Other entry points

@frak-labs/core-sdk also exposes /rewards and /identity subpaths, and /bundle (index plus actions in one import) for CDN-style consumption.

Advanced: create the client yourself

If you do not use the components package, create the client by hand. Call setupClient once and reuse the promise: each call recreates the listener iframe.

frak-client.ts

import { setupClient, type FrakWalletSdkConfig } from "@frak-labs/core-sdk";

const config: FrakWalletSdkConfig = {
  metadata: { name: "Your Store" },
};

let clientPromise: ReturnType<typeof setupClient> | undefined;

export function getFrakClient() {
  clientPromise ??= setupClient({ config });
  return clientPromise;
}

Next steps

Components referenceEvery element and every attribute.

React integrationProviders and hooks for a React app.

CDN setupThe same integration with a single script tag.

InteractionsWhat each interaction means and when to send it.