Wallet

​

How provisioning works

• The frame is on an Endstate origin. Once the wallet is enabled, the SDK appends a hidden iframe pointed at https://wallet.endstate.io. Because the wallet’s own document owns the key material, that material is isolated from your page by the browser’s origin boundary. Your page can ask for an account and a session; it can never read a private key.
• The origins are compiled in. The frame origins ship inside the published bundle and are not configurable. Every message the bridge sends is addressed to that one origin, and every message it accepts is checked against it. This is a security property of the design, not a default you can override.
• There is no signing surface. The account address is the whole of what the wallet exposes. Nothing in the API accepts bytes to sign or a transaction to authorize.

​

Provisioning the wallet

• account - the WalletAccount ({ address }), or null until provisioning finishes.
• status - a WalletStatus: "unconfigured", "idle", "provisioning", "ready", or "error". It stays "unconfigured" while the wallet is not enabled, moves through "provisioning" as the frame mounts and the first session is established, and lands on "ready" once the account exists.
• error - the failure when status is "error", otherwise null.
• ready() - resolves with the WalletAccount once it exists; await it where you first need the address.
• refresh() - establishes a fresh session and resolves with the account.
• expiresAt - a Date for when the current session lapses, or null before it is ready.

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

// Wrap your tree once. The wallet config takes getIdentityToken and enabled;
// getIdentityToken is called only once enabled is true (here, after sign-in).
function App() {
  return (
    <EndstateProvider
      publishableKey="end_pk_..."
      wallet={{
        getIdentityToken: () => mintIdentityToken(),
        // Your auth state - getIdentityToken runs only once this is true.
        enabled: isSignedIn,
      }}
    >
      <WalletAddress />
    </EndstateProvider>
  );
}

// Read the account anywhere inside the provider.
function WalletAddress() {
  const { account, status, error } = useWallet();
  if (status === "unconfigured") return <SignInPrompt />; // enabled is still false
  if (status === "idle" || status === "provisioning") return <Spinner />;
  if (status === "error") return <Failed message={error?.message} />;
  return <code>{account?.address}</code>; // status is "ready"
}

import { createWallet } from "@endstate-sdk/web";

// Mount the frame and start session establishment at page load; first-time
// setup can take seconds, so do not put this inside a user action.
const wallet = createWallet({
  publishableKey: "end_pk_...",
  // Called fresh for every session establishment; never return a cached value.
  getIdentityToken: () => mintIdentityToken(),
});

// Elsewhere, where the address is needed:
const { address } = await wallet.ready();

​

Gating on sign-in

​

The identity credential

{
  "iss": "https://auth.brand.example",
  "aud": "endstate:user",
  "sub": "your-stable-customer-id",
  "email": "customer@brand.example",
  "jti": "unique-per-token",
  "iat": 1755640000,
  "exp": 1755640060
}

• Bring your own auth. Your backend mints and signs it from your own login. See Bring your own auth for the exact claim contract - the accepted algorithms, the 300-second age ceiling, and the JWKS Endstate verifies against - and how to register your issuer.
• Endstate-managed identity. Endstate issues the credential against the customer’s Endstate sign-in, so the page must be an Endstate-hosted surface. You still return it through the same callback.

​

Refreshing and expiry

const { refresh, expiresAt } = useWallet();
// Ahead of expiry, or after a wallet.session_expired failure:
await refresh();

​

Error handling

import { EndstateWalletError } from "@endstate-sdk/web";

// `error` is useWallet().error in React, or the rejection from a lifecycle
// method in Vanilla. Branch on its stable `code`.
if (error instanceof EndstateWalletError) {
  switch (error.code) {
    case "wallet.session_expired":
      // Refresh and retry: refresh() in React, wallet.refreshSession() in Vanilla.
      break;
    case "wallet.timeout":
      // No response within the wait budget; retry or surface a failure.
      break;
    default:
    // Wallet and API codes pass through verbatim.
  }
}

• A wallet.* code from the frame, such as wallet.session_expired.
• An API error code, forwarded verbatim from the Endstate API.
• A code this package produced locally: wallet.timeout (no response within budget), wallet.destroyed (teardown settled the call), and - when the wallet’s reply could not be used - wallet.unsupported_protocol_version or wallet.internal_error.

​

Next steps