Quickstart

npm install @endstate-sdk/core @endstate-sdk/web react

bun add @endstate-sdk/core @endstate-sdk/web react

pnpm add @endstate-sdk/core @endstate-sdk/web react

"use client";
import {
  EndstateProvider,
  useSession,
  useWallet,
  useClaim,
} from "@endstate-sdk/web/react";

// Wrap your app once. The provider builds the browser client, provisions the wallet,
// and (autoVerify, on by default) captures + verifies the landing tap on mount.
function App() {
  return (
    <EndstateProvider
      publishableKey="end_pk_..."
      wallet={{
        // A fresh, single-use token proving your signed-in user's identity, minted by
        // your own backend. Called on every session, so never return a cached value.
        getIdentityToken: () => mintIdentityToken(),
        // Your auth state - getIdentityToken runs only once this is true.
        enabled: isSignedIn,
      }}
    >
      <Claim />
    </EndstateProvider>
  );
}

// A child reads the verified tap, the wallet address, and drives the claim.
function Claim() {
  const { item, status: sessionStatus } = useSession();
  const { account } = useWallet();
  const { claim, status, data } = useClaim();

  // sessionStatus runs "idle" -> "capturing" -> "verifying" -> "verified".
  if (sessionStatus !== "verified" || !item) {
    return <p>Tap your item to begin.</p>;
  }

  return (
    <div>
      <h1>{item.name}</h1>
      {/* claim() with no args hands the item to the wallet address. status drives the button. */}
      <button
        disabled={!account || status === "claiming" || status === "settling"}
        onClick={() => claim()}
      >
        Claim
      </button>
      {status === "claimed" && <p>Claimed. {data?.id}</p>}
      {(status === "expired" || status === "failed") && (
        <p>That did not go through - tap again to retry.</p>
      )}
    </div>
  );
}

import { type TapSession } from "@endstate-sdk/core";
import {
  createEndstateClient,
  defaultTapSources,
  createWallet,
} from "@endstate-sdk/web";

// A browser client holding only the publishable key, wired to the browser tap sources.
const client = createEndstateClient({
  publishableKey: "end_pk_...",
  tapSources: defaultTapSources(),
});

// 1. Provision the wallet on PAGE LOAD (not inside the click): createWallet mounts the
// frame and starts session establishment immediately; first-time setup can take seconds.
const wallet = createWallet({
  publishableKey: "end_pk_...",
  // A fresh, single-use token proving your signed-in user's identity, minted by
  // your own backend. Called on every session, so never return a cached value.
  getIdentityToken: () => mintIdentityToken(),
});

async function claimOnTap(): Promise<void> {
  // 2. Capture a tap. Call inside a user gesture so an in-page NFC scan can prompt.
  const tap = await client.captureTap();
  if (!tap) return; // no tap on this page (direct visit / nothing to scan)

  // 3. Verify against Endstate: records the tap and opens a session bound to it.
  const session: TapSession = await client.verify(tap);

  // 4. Read the verified item straight off the session - no extra request.
  const item = session.item; // TapResponse["unit"] | null
  if (!item) return;
  console.log("Genuine item:", item.id, item.name);

  // 5. Resolve the customer's wallet address (provisioning started at step 1).
  const account = await wallet.ready(); // WalletAccount { address }

  // 6. Claim ownership into the wallet address. unit_id is bound to the session
  // scope automatically; only `to` (the recipient) is supplied.
  const claim = await session.claims.create({ to: account.address });
  console.log("Claim:", claim.id, claim.status); // "claiming" first

  // (optional) Wait for settlement: "claimed" | "expired" | "failed".
  const settled = await session.claims.waitUntilSettled(claim.id);
  console.log("Settled:", settled.status);
}