@moon-x/react-sdk

React SDK for MoonX — embedded wallets with passkey-protected MPC signing for Ethereum, Solana, Tron, and Bitcoin, drop-in auth UI flows, and headless wallet methods.

npm install @moon-x/react-sdk
# or
pnpm add @moon-x/react-sdk

Quick start

Wrap your app with MoonXProvider and import the CSS bundle once:

import { MoonXProvider, mainnet, sepolia } from "@moon-x/react-sdk";
import "@moon-x/react-sdk/style.css";

export default function App() {
  return (
    <MoonXProvider
      publishableKey={process.env.NEXT_PUBLIC_MOONX_PUBLISHABLE_KEY!}
      config={{
        appearance: {
          accentColor: "#6366f1",
          backgroundColor: "#ffffff",
        },
        // One unified list for EVM, Solana, Tron, and Bitcoin. A bare viem chain uses
        // its built-in RPC; non-EVM entries carry a CAIP-style id.
        chains: [
          mainnet,
          sepolia,
          { id: "solana:mainnet", rpcUrl: "https://api.mainnet-beta.solana.com" },
          { id: "tron:mainnet", rpcUrl: "https://api.trongrid.io" },
          {
            id: "bitcoin:mainnet",
            rpcUrl: process.env.NEXT_PUBLIC_BITCOIN_BLOCKBOOK_RPC!,
            network: "mainnet",
          },
        ],
        defaultChain: "eip155:1", // CAIP-2 | numeric (1) | name alias ("eth:sepolia")
      }}
    >
      <YourApp />
    </MoonXProvider>
  );
}

Open the auth modal and read user state:

import { useMoonX } from "@moon-x/react-sdk";

function LoginButton() {
  const { ready, isAuthenticated, user, start, logout } = useMoonX();

  if (!ready) return null;
  if (isAuthenticated) {
    return <button onClick={() => logout()}>Sign out ({user?.id})</button>;
  }
  return <button onClick={() => start?.()}>Sign in</button>;
}

Sign a message with one of the user's wallets:

import { useWallets } from "@moon-x/react-sdk";
import { useSignMessage } from "@moon-x/react-sdk/ethereum";

function SignDemo() {
  const { wallets } = useWallets();
  const { signMessage } = useSignMessage();

  const onSign = async () => {
    const wallet = wallets.find((w) => w.wallet_type === "ethereum");
    if (!wallet) return;
    const { signature } = await signMessage({
      message: "Hello world",
      wallet,
      options: { uiOptions: { showWalletUI: true } }, // opens the modal
    });
    console.log(signature);
  };

  return <button onClick={onSign}>Sign</button>;
}

Configuration

MoonXProvider accepts publishableKey (required) plus a config object:

| Field | Type | Purpose | |---|---|---| | iframeUrl | string | Secure iframe base URL override for local, preview, or staging deployments. Omit it to use the hosted production iframe. | | apiUrl | string | API base URL override for the same non-production deployment. Configure it together with iframeUrl so browser and iframe calls target the same stack. | | appearance | AuthAppearance | The single theming surface — branding (accentColor, backgroundColor, displayMode, logo, loginHeaderTitle, fontFamily) and all design tokens inline (colors, borderRadius, typography, card, backdrop, components, per-mode light / dark). See Theming. | | loginMethods | ("email" \| "google" \| "apple" \| "wallet")[] | Which auth methods to show in the modal. | | walletChainType | "ethereum" \| "solana" \| "ethereum-or-solana" | Which wallet type to create at signup. | | chains | ChainConfigItem[] | Unified RPC / chain config for EVM, Solana, Tron, and Bitcoin. Bitcoin entries are { id, rpcUrl, network } and require Blockbook JSON-RPC methods for balance/broadcast. Common viem chains are re-exported by this package. See docs/rpc-configuration.md. | | defaultChain | string \| number | Which configured chain is the default. Referenced by alias, CAIP-2 id, or numeric chainId — e.g. "eth:base", "solana:mainnet", "tron:mainnet", or "bitcoin:mainnet". Defaults to the first entry in chains. | | walletConnect.projectId | string | WalletConnect v2 project ID. When set, the connect-wallet modal offers a WalletConnect (EVM) option (QR) so mobile / non-injected wallets can connect using the configured/default EVM chain. | | emailConfig, passkeyEnrollConfig, signMessageConfig, signTransactionConfig, sendTransactionConfig, exportKeyConfig | various | Per-flow UI overrides — titles, button text, etc. | | security | Record<string, never> | Reserved for future per-app security knobs. The previously-configurable assertionCacheTtlMs was removed in Phase 4 of the presence-token gating work — every sensitive op now does a fresh WebAuthn ceremony and mints scope-bound single-use JWTs via the iframe's internal orchestrator, so there is no parent-side cache left to configure. See Security below. |

Hooks

Authentication & user state

| Hook | What it does | |---|---| | useMoonX() | The big one. { ready, isAuthenticated, user, start, logout, setAppearance, getSessionTokens, refreshUser, ... } + every SDK method on the same instance. | | useUser() | Just { user, refreshUser }. Re-subscribes to user changes. | | useLoginWithEmail({ onComplete?, onError? }) | Headless email-OTP. Returns { state, sendCode, loginWithCode, reset }. state is a discriminated union: idle / sending / awaiting-code / verifying / complete / error. | | useLoginWithOAuth() | Google + Apple flows. Returns { state, loginWithOAuth, reset }. | | useLogout() | { logout } — also clears local storage + iframe session. |

useMoonX().getCurrentSession() returns the current session or null when the iframe authoritatively reports that no session exists. Starting with @moon-x/core 0.15.0, bridge/transport failures reject instead of resolving to null. Direct polling code should catch those failures and retain its last-known auth state rather than treating an unavailable iframe as a logout.

MoonPay Consumer session exchange

Use loginWithMoonPayCustomerToken when the parent application already has a MoonPay Consumer customerToken. The SDK exchanges the token for a MoonX session. The iframe stores the session credentials. The method returns only userCreated.

import {
  MOONPAY_CONSUMER_SESSION_ERROR_CODES,
  type MoonPayConsumerSessionError,
  useMoonX,
} from "@moon-x/react-sdk";

const { loginWithMoonPayCustomerToken } = useMoonX();

try {
  const { userCreated } = await loginWithMoonPayCustomerToken({
    customerToken,
  });
} catch (error) {
  const code = (error as MoonPayConsumerSessionError).error_code;
  if (code === MOONPAY_CONSUMER_SESSION_ERROR_CODES.SESSION_INVALID) {
    // Get a new Consumer token and try again.
  }
}

The promise resolves after the MoonX session is stored. At that time, isAuthenticated is true. The SDK then loads the user profile in the background. Thus, user can be null for a short time. It can also stay null if the profile request fails. Use refreshUser when the application must have the profile.

The iframe uses the publishable key from its own URL for the backend exchange. It rejects the request if the key in the parent message does not match that key. A 401 response from the backend becomes the stable moonpay_consumer_session_invalid error code. Do not parse HTTP status numbers from error messages.

Passkeys

| Hook | What it does | |---|---| | usePasskeyStatus() | { status, refresh }. status.passkeys lists the user's enrolled passkeys with provider labels (e.g. "1Password on Chrome"). | | useRegisterPasskey() | First-time passkey enrollment for a user who signed in via OTP/OAuth without one. | | useAddPasskey() | Add an additional passkey to an authenticated user. | | useRemovePasskey() | Remove a passkey by its credential ID. |

Wallets

| Hook | What it does | |---|---| | useWallets() | Chain-pinned wallet list from the /ethereum, /solana, /tron, or /bitcoin subpath. | | useCreateWallet() | Mint a new MPC wallet for the imported chain subpath. | | useImportKey() | Two-mode: headless if you pass a key, modal-driven if you don't. | | useConnectWallet() | Prebuilt wallet modal. Injected EVM (EIP-6963), Solana (Wallet Standard), and EVM WalletConnect (QR, when walletConnect.projectId is set). mode defaults to "connect" (client-side connection, no session); "signIn" runs the SIWE/SIWS login ceremony and "link" attaches the wallet to the current user without replacing the session. | | useWalletLogin({ chain? }) | Headless external-wallet authentication: { wallets, signIn(walletId, chain?), link(walletId, chain?), status, error, refresh }. Both operations connect transiently and run SIWE/SIWS; sign-in establishes a session, while link requires and preserves the current session. | | useExternalWallets({ chain? }) | Headless external-wallet connection (no session): { wallets, connect, disconnect, connected, status, refresh }. Covers injected EVM + Solana Wallet Standard. For WalletConnect, use the modal or the standalone connectWalletConnect(). | | useConnectedExternalWallets() | The external wallets explicitly connected this session (shared app-wide) for a picker / account switcher; each exposes signMessage. A login wallet is not listed here — sign-in connects transiently. | | useAttachOAuth() / useDetachOAuth() | Link / unlink an OAuth provider on an existing user. |

External-wallet login (SIWE / SIWS)

Let users authenticate by signing a message with an existing wallet — SIWE for EVM, SIWS for Solana. Enable it per app with the enable_external_wallets dashboard setting; when it's off, the wallet login entry is hidden and the endpoints reject.

• Prebuilt UI — add "wallet" to loginMethods and the login modal shows a wallet option, or open it directly:

  const sdk = useMoonX();
  await sdk.connectWallet({ mode: "signIn", walletChainType: "ethereum-and-solana" });
  // On success useMoonX().isAuthenticated === true and the session survives reload.

• Headless — build your own picker with useWalletLogin():

  const { wallets, signIn } = useWalletLogin({ chain: "all" });
  // render `wallets`, then on click:
  await signIn(wallet.id, wallet.chain);

• Link to the current user — use either surface while authenticated:

  await sdk.connectWallet({ mode: "link" });
  
  // Or headless:
  const { link } = useWalletLogin({ chain: "all" });
  const linkedWallet = await link(wallet.id, wallet.chain);

Wallet users have no email — the compliance gate is sanctions/AML screening of the connecting address for sign-in and link (both chains). A screened-out wallet fails with a clear, non-retryable message ("This wallet can't be used.") and no identity or session change is made. The identity token's sub is the internal MoonX user ID; it does not expose the wallet provider or address.

The wallet used to sign in is transient — it is not added to useConnectedExternalWallets(). Adding an external wallet for on-going use is a separate, explicit connect action. Connected external wallets are cleared on logout().

Linking is idempotent for a wallet already attached to the same user. A wallet owned by another MoonX user rejects with wallet_already_linked.

Per-chain wallet methods — /ethereum, /solana, /tron, and /bitcoin

Chain-aware hooks live under subpaths so they don't pull in the other chain's adapters if you only use one:

import { useSignMessage, useSignTransaction, useSendTransaction } from "@moon-x/react-sdk/ethereum";
import { useSignMessage as useSignSolanaMessage } from "@moon-x/react-sdk/solana";
import { useSignMessage as useSignTronMessage } from "@moon-x/react-sdk/tron";
import {
  useSignMessage as useSignBitcoinMessage,
  useSignTransaction as useSignBitcoinTransaction,
} from "@moon-x/react-sdk/bitcoin";

Ethereum hooks:

• useSignMessage — EIP-191 personal_sign. Returns { signature: "0x..." }.
• useSignTransaction — Signs an EIP-1559 tx. Returns { signature, serializedSigned, hash }.
• useSignTypedData — EIP-712. Returns { signature: "0x..." }.
• useSignHash — Raw ECDSA digest sign (Privy parity — secp256k1_sign).
• useSign7702Authorization — EIP-7702 delegation auth.
• useSendTransaction — Sign + broadcast. Accepts a per-call chain selector and an inline rpcUrl override (both fall back to provider config).
• useGetBalance — Native token balance. Same per-call chain / rpcUrl options.

Solana hooks:

• useSignMessage — Ed25519 signature.
• useSignTransaction — Signs a serialized base58 tx. Returns { signedTransaction: Uint8Array }.
• useSendTransaction — Sign + broadcast. Accepts a per-call chain selector and an inline rpcUrl override.
• useGetBalance — Lamport balance. Same per-call chain / rpcUrl options.
• useGetTokenAccounts — SPL token accounts by owner. Same per-call chain / rpcUrl options.

Tron hooks:

• useSignMessage — TIP-191 message signature.
• useSignTransaction — Signs a Tron transaction JSON object.
• useSendTransaction — Sign + broadcast through the configured Tron fullnode.
• useGetBalance — Native TRX balance using the configured Tron fullnode.

Bitcoin hooks:

• useCreateWallet / useImportKey — Accept addressType: "p2tr" | "p2wpkh" | "p2pkh".
• Bitcoin import accepts compressed mainnet WIF or 32-byte hex; export returns compressed mainnet WIF. WIF does not encode the address type, so re-import with the same addressType to reproduce the original address. Taproot (bc1p) is the backwards-compatible default; Native SegWit (bc1q) and Legacy P2PKH (1) use separate ECDSA wallets with BIP84- and BIP44-shaped derivation paths respectively.
• useSignMessage — Produces an smp-prefixed BIP322 Simple proof for P2TR and P2WPKH, or a ful-prefixed BIP322 Full proof for P2PKH, and returns { signature, messageHash, address, scheme }.
• useSignTransaction — Validates, batch-signs, and finalizes a base64/hex PSBT v0. Every input must match the selected single-key wallet. P2TR supports BIP86 key-path DEFAULT/ALL with witnessUtxo; P2WPKH supports BIP143 ALL with witnessUtxo; P2PKH supports legacy ALL with the complete previous transaction in nonWitnessUtxo. Taproot script paths, multisig, and unsafe sighash modes are rejected. The iframe derives and verifies the wallet key before signing, so callers do not need to include MoonX's internal Taproot key.
• useSendTransaction — Signs and broadcasts through the configured Blockbook-compatible RPC, refusing a returned txid mismatch.
• useGetBalance — Confirmed native BTC balance through bb_getAddress.
• useGetUtxos — Confirmed spendable outputs through bb_getUTXOs, for PSBT construction.

Each chain subpath also exports useCreateWallet, useWallets, useImportKey, useExportKey, and useFundWallet. Tron funding supports native TRX and USDT-TRC20; Bitcoin funding supports native BTC for all three address types through MoonPay.

Every signing hook accepts options.uiOptions.showWalletUI to toggle modal vs headless mode. With UI, the user sees the message/transaction in a modal and the biometric prompt fires only on the Sign tap. Headless skips the modal entirely.

Passkey-based operations use a fresh WebAuthn ceremony per call. See Security below.

Identity-backed ephemeral signers

useEphemeralSigner().provision() and .revoke() accept session-based presence when the app enables identity-backed encryption and the user has a usable KMS wrap. Users without passkeys can create, re-provision, and revoke signers without an email OTP or a verified email address.

The SDK prefers an enrolled passkey when one is available. If the passkey cannot assert, an eligible identity-backed session can authorize the operation. Passkey-only users still need a passkey assertion.

Provisioning and revocation each require a separate, scoped, single-use presence token. The SDK obtains these tokens internally. Key export and passkey management keep their existing authentication requirements.

Deploy the matching platform and wallets backend changes before releasing this SDK. Both services must accept session presence for ephemeral_signer_provision and ephemeral_signer_revoke.

Ephemeral signer list status

useEphemeralSigner().signers includes non-revoked signers with status active, needs_reauth, or expired. Expired signers remain visible and can be revoked. Provision a fresh signer for needs_reauth or expired.

Older backends can omit status. The SDK preserves their responses. Inspect expires_at and handle signing errors instead of treating a missing status as proof that a signer is usable.

Before the backend starts returning expired, update exhaustive status handling and runtime validators in your application. Updating the SDK alone does not change application logic. This status support can be released before backend PR #241.

Security

For passkey-only users, sensitive operations drive this server-verified ceremony per call:

1. Server-issued challenge. SDK posts to /auth/passkey/presence/begin, server inserts a row in app_user_passkey_challenges and returns the WebAuthn options.
2. Fresh WebAuthn assertion. The parent runs navigator.credentials.get; the user does a biometric. The assertor strips response.userHandle from the server-bound payload (DEK hygiene) and surfaces the userHandle separately for the iframe's local AES-GCM unwrap.
3. Scope-bound, single-use JWT mint. SDK posts to /auth/passkey/presence/verify with purpose: "internal" and the scope set this op needs (e.g. ["keyshare_read", "sign"]). Server consumes the challenge, verifies the signature against the credential's stored public key, mints one short-lived JWT per scope with a unique jti.
4. Per-endpoint enforcement. Each scoped JWT carries the X-MoonX-Presence header on its matching gated endpoint. MoonX middleware pins the JWT's op claim to the endpoint, then burns the jti in platform.app_presence_jti_used via INSERT ... ON CONFLICT DO NOTHING. Replay of the same token is rejected as presence token already consumed. Tokens have a 30-second TTL.

What this closes: captured userHandle + session JWT no longer unlocks DEK material offline. Even with both, an attacker can't fetch wraps / keyshares / drive the co-signer without producing a fresh WebAuthn signature for each op — which requires the credential's private key in the user's authenticator. See apps/platform/docs/notes/passkeys/presence-tokens.md (in the backend repo) for the full threat model and scope matrix.

The previously-configurable security.assertionCacheTtlMs and per-call requireFreshAssertion were removed entirely when presence-token gating shipped — they no longer exist on the public TypeScript surface. Every op is always-fresh by construction.

Theming

All theming flows through a single appearance object. Set a few high-level branding fields (accentColor, backgroundColor, displayMode, logo, loginHeaderTitle, fontFamily) — the SDK derives a full palette from accentColor / backgroundColor — and reach for the inline design tokens (colors, borderRadius, typography, card, backdrop, components, per-mode light / dark) when you want finer control.

<MoonXProvider
  config={{
    appearance: {
      // Branding
      accentColor: "#6366f1",
      backgroundColor: "#0f172a",
      displayMode: "dark",            // "light" | "dark" | "auto"
      fontFamily: "Inter, sans-serif",
      logo: { src: "/logo.svg", srcDark: "/logo-dark.svg", height: 32 },

      // Design tokens (all inline on appearance)
      colors: { warning: "#f59e0b", info: "#3b82f6", link: "#6366f1", ring: "#6366f1" },
      borderRadius: { button: "9999px", card: "1rem", input: "0.5rem" }, // or "none" | "sm" | "md" | "lg"
      typography: {
        fontFamilyHeading: "Poppins, sans-serif",
        fontUrl: "https://fonts.googleapis.com/css2?family=Poppins&display=swap",
        letterSpacing: "0.01em",
        fontSize: { sm: "0.8125rem", lg: "1.0625rem", xl: "1.375rem" },
      },
      card: { shadow: "0 10px 25px -5px rgb(0 0 0 / 0.2)", padding: "1.5rem", maxWidth: "26rem" },
      backdrop: { color: "rgb(0 0 0 / 0.5)", blur: "8px" },

      // Per-mode overrides (merged on top of the base tokens for the resolved mode)
      dark: { colors: { background: "#0b0b0f" } },
    },
  }}
>

Update appearance at runtime — handy for a light/dark toggle:

const { setAppearance } = useMoonX();
setAppearance({ displayMode: colorScheme });

Merge order (low → high): base light/dark theme → accentColor / backgroundColor derivations → appearance tokens (colors, borderRadius, …) → per-mode appearance.light / appearance.dark. So an explicit appearance token always wins over the high-level derivations.

Token reference

All theming tokens emit --moonx-* CSS variables. The base palette/radius/font emit the core tokens (e.g. --moonx-color-*, --moonx-border-radius-*); the newer granular tokens each fall back to their base token (e.g. --moonx-radius-button → --moonx-border-radius-md), so defaults are unchanged until you set one.

| Group | Tokens | CSS variables | |---|---|---| | colors | accent, accentForeground, background, background2/3, foreground, foreground2–4, border, success, error, … | --moonx-color-* | | colors | warning, info, link, ring (focus) | --moonx-color-* | | borderRadius | sm, md, lg, full | --moonx-border-radius-* | | borderRadius | button, card, input | --moonx-radius-* | | typography | fontFamilyHeading, letterSpacing, fontSize.{sm,lg,xl}, fontWeight.{medium,bold} | --moonx-font-*, --moonx-letter-spacing | | typography | fontUrl | injected <link rel="stylesheet"> | | card | padding, shadow, borderWidth, maxWidth | --moonx-card-* | | backdrop | color, blur | --moonx-backdrop-* |

Per-component overrides

For finer control, appearance.components styles individual surfaces — card, button, input — independently of the global tokens. button and input accept background, text, border (color), borderWidth, and radius; card accepts the same minus background (the card surface is the global backgroundColor). Anything you omit falls through to the global tokens / --moonx-* defaults. The header is styled via the typography tokens instead (appearance.typography.colorHeading, fontFamilyHeading, …).

<MoonXProvider
  config={{
    appearance: {
      components: {
        card:   { border: "#23233a", radius: "1rem" },
        button: { background: "#a78bfa", text: "#0b0b14", radius: "9999px" },
        input:  { background: "#15151f", border: "#23233a", borderWidth: "1px" },
      },
    },
  }}
>

Each field maps to a --moonx-<component>-* CSS variable (e.g. --moonx-card-bg, --moonx-button-border-color); radius reuses --moonx-radius-<component>. Overrides layer on top of the global tokens, so you can restyle just the card while everything else follows the theme.

EVM chain helpers

The package re-exports gas / RPC utilities that work with any viem Chain:

import {
  getEvmGasPrice,
  getEvmMaxPriorityFeePerGas,
  getEvmNonce,
  estimateEvmGas,
  estimateEvmGasReserve,
  getRpcUrl,
  getChainById,
  isChainSupported,
  validateChainConfig,
  // Unified-config resolution (also used internally by the hooks):
  resolveChainEntry,
  resolveRpcUrl,
  resolveWsUrl,
  normalizeChainKey,
  buildChainIndex,
  isEvmEntry,
} from "@moon-x/react-sdk";

Useful when you need a pre-flight gas reserve estimate, want to resolve a configured chain's RPC yourself, or are building a custom chain-picker.

React Native

For React Native apps, use @moon-x/react-native-sdk — same hook shape with a WebView-backed transport.

License

UNLICENSED. All rights reserved.