@xrpl-wallet-kit/core

Headless XRPL wallet manager, adapter contract, event system, storage helpers, network registry, and transaction lifecycle primitives for XRPL Wallet Kit.

Use this package when you want full control over wallet UI or when building a custom adapter, framework binding, or server-aware integration.

Install

npm install @xrpl-wallet-kit/core xrpl

Most apps should install @xrpl-wallet-kit/client instead. It wires the manager, official adapters, modal UI, connect button, toast, identity, balance, and recent transaction options for you.

Manager

import { WalletManager, MAINNET, isWalletKitError } from "@xrpl-wallet-kit/core";
import { createGemWalletAdapter } from "@xrpl-wallet-kit/adapter-gemwallet";

const manager = new WalletManager({
  network: MAINNET,
  adapters: [createGemWalletAdapter()],
  autoReconnect: true,
});

await manager.connect("gemwallet");

Signing

const messageResult = await manager.signMessage({
  message: "Sign in to My XRPL App",
});

const txResult = await manager.signAndSubmit({
  txJson: {
    TransactionType: "Payment",
    Account: manager.getSession()?.account.address,
    Destination: "r...",
    Amount: "1000000",
  },
});

Transaction request types are generic. Applications can opt into an exact XRPL transaction type while custom amendments can continue using a record payload:

import type { Payment } from "xrpl";
import type { SignAndSubmitRequest } from "@xrpl-wallet-kit/core";

const request: SignAndSubmitRequest<Payment> = {
  txJson: {
    TransactionType: "Payment",
    Account: "r...",
    Destination: "r...",
    Amount: "1000000",
  },
};

Networks

Adapters can advertise supported networks and network-switching support through granular capability metadata. Switching is rejected before invoking the wallet when the target is not supported.

const details = manager.getCapabilityDetails();
if (manager.can("switchNetwork") && details?.supportedNetworks?.includes("testnet")) {
  await manager.switchNetwork("testnet");
}

signMessage() returns a normalized proof shape:

{
  signatureKind: "signature" | "signedTx",
  proof: string,
  signature?: string,
  txBlob?: string,
  publicKey?: string,
  raw?: unknown
}

Apps should read signatureKind. Some wallets return compact message signatures, while Xaman, WalletConnect, and XRPL Snap may return signed transaction proofs.

Transaction Lifecycle

When signAndSubmit() returns a hash, the manager records the transaction and emits lifecycle events.

manager.on("tx_submitted", ({ hash, transaction }) => {});
manager.on("tx_confirmed", ({ hash, transaction }) => {});
manager.on("tx_failed", ({ hash, error, transaction }) => {});

Custom flows can register or update transactions manually:

manager.addTransaction({
  hash: "A1B2...",
  status: "submitted",
  account: manager.getSession()?.account,
});

const transactions = manager.getTransactions();

The transaction confirmer is best-effort. If confirmation is inconclusive, keep an explorer link available instead of marking the transaction failed too early.

Errors

All typed errors expose both a specific code and a broader category so apps can render stable recovery UI without parsing wallet-specific messages.

try {
  await manager.connect("xaman");
} catch (error) {
  if (isWalletKitError(error) && error.category === "NETWORK") {
    // Ask the user to switch networks or reconnect on the requested ledger.
  }
}

Network mismatches are rejected before a session is persisted. If a wallet reports a different network id or network type than the app requested, the manager throws NETWORK_MISMATCH.

Adapter Contract

Adapters implement the WalletAdapter interface and declare capabilities for the methods they truly support.

import { assertWalletAdapter } from "@xrpl-wallet-kit/core";

assertWalletAdapter(myAdapter);

Capability rules:

• signMessage: true requires a real signMessage() implementation.
• signTransaction: true requires signing without submitting.
• signAndSubmit: true requires submitting or delegating submission to the wallet.
• switchNetwork: true requires a real switchNetwork() implementation.
• details can declare supported networks, transaction types, wallet methods, and transaction modes.
• Adapters should throw typed WalletKitErrors for rejected, unsupported, unavailable, or failed flows.
• Adapter availability checks are bounded by the manager so one slow extension cannot block the full wallet list.

Storage and Auto Reconnect

WalletManager stores session state through WalletStorage. Auto reconnect is passive: adapters should restore only from wallet state they can read without opening popups, QR panels, deep links, or approval prompts.

Related

• @xrpl-wallet-kit/client - all-in-one app integration
• @xrpl-wallet-kit/ui - framework-agnostic modal, button, inline picker, and toast
• @xrpl-wallet-kit/auth - Sign-In with XRPL helpers and verification