Getting Started

Get up and running with XRPL-Connect in minutes.

Installation

Using npm

npm install xrpl-connect xrpl

Using pnpm

pnpm add xrpl-connect xrpl

Using yarn

yarn add xrpl-connect xrpl

The xrpl-connect package includes:

• Core - WalletManager, event system, and state management
• UI - Beautiful web component for wallet connection
• Adapters - Built-in support for Xaman, Crossmark, GemWallet, WalletConnect, Ledger hardware wallets, Xyra, and Otsu

Note: The xrpl package is required for transaction types and utilities.

Get Your API Keys

To use XRPL-Connect, you'll need API keys for the wallet adapters you plan to use.

Xaman API Key

Xaman is the most popular XRPL wallet. Get your API key here:

1. Go to https://apps.xumm.dev/
2. Sign in with your Xaman account
3. Create a new application
4. Copy your API Key
5. Use it when creating the XamanAdapter

const adapter = new XamanAdapter({
  apiKey: 'YOUR_API_KEY',
});

WalletConnect Project ID

If you want to support mobile wallets via WalletConnect:

1. Go to https://cloud.walletconnect.com/
2. Create a new project
3. Copy your Project ID
4. Use it when creating the WalletConnectAdapter

const adapter = new WalletConnectAdapter({
  projectId: 'YOUR_PROJECT_ID',
});

Other Adapters

Crossmark, GemWallet, Xyra, Otsu, and Ledger don't require API keys - they work directly with browser extensions, wallets, or hardware devices:

const crossmarkAdapter = new CrossmarkAdapter();
const gemWalletAdapter = new GemWalletAdapter();
const xyraAdapter = new XyraAdapter();
const otsuAdapter = new OtsuAdapter();

Ledger Hardware Wallet

For Ledger hardware wallet support, no API keys are required. The adapter communicates directly with the device:

import { LedgerAdapter } from 'xrpl-connect';

const ledgerAdapter = new LedgerAdapter({
  // Optional: customize derivation path (default: "44'/144'/0'/0/0")
  derivationPath: "44'/144'/0'/0/0",

  // Optional: timeout for operations in ms (default: 60000)
  timeout: 60000,

  // Optional: prefer WebHID over WebUSB (default: true)
  preferWebHID: true,
});

Requirements for Ledger:

• Supported browsers: Chrome, Edge, or Opera (WebHID/WebUSB support required)
• HTTPS connection (localhost is OK for development)
• User must unlock device and open the XRP app
• Close Ledger Live if it's running (conflicts with WebHID/WebUSB)

For more details on Ledger integration, see the Ledger adapter documentation.

Quick Start

A minimal, copy-pasteable example covering the patterns you almost always need: wiring the UI component, listening to connect / disconnect / error, and signing a transaction with proper user-rejection handling.

<button id="connect-btn">Connect Wallet</button>
<xrpl-wallet-connector id="wallet-connector"></xrpl-wallet-connector>

import { WalletManager, XamanAdapter, CrossmarkAdapter } from 'xrpl-connect';

const walletManager = new WalletManager({
  adapters: [new XamanAdapter({ apiKey: 'YOUR_API_KEY' }), new CrossmarkAdapter()],
  network: 'testnet',
  autoConnect: true,
});

const connector = document.getElementById('wallet-connector');
connector.setWalletManager(walletManager);

document.getElementById('connect-btn').addEventListener('click', () => {
  connector.open();
});

walletManager.on('connect', (account) => {
  console.log('Connected:', account.address);
});

// Reset your UI when the user (or an autoConnect failure) disconnects.
walletManager.on('disconnect', () => {
  console.log('Disconnected');
});

// Surfaces adapter/connection errors (wallet missing, network issues, etc.).
walletManager.on('error', (error) => {
  console.error('Wallet error:', error.code, error.message);
});

// `sign` rejects when the user cancels in their wallet — always wrap it.
async function sendPayment() {
  try {
    const signed = await walletManager.sign({
      TransactionType: 'Payment',
      Account: walletManager.account.address,
      Destination: 'rN7n7otQDd6FczFgLdlqtyMVrn3HMfXoQT',
      Amount: '1000000',
    });
    console.log('Signed:', signed);
  } catch (error) {
    if (error.code === 'SIGN_FAILED') {
      // User rejected the prompt in their wallet — usually a no-op.
      console.log('User rejected the transaction');
    } else {
      console.error('Sign failed:', error);
    }
  }
}

About autoConnect

autoConnect: true tells the WalletManager to silently restore the user's previous session from localStorage when the page loads. If the previous adapter is still available and the stored session is valid, you'll receive a connect event before any user interaction; otherwise the manager stays disconnected (and may emit error if the adapter explicitly fails).

Two practical consequences:

• Register listeners first. Add on('connect'), on('disconnect'), and on('error') immediately after constructing the manager, otherwise the initial reconnect event will fire before your UI is listening.
• Set it to false if your app needs the user to explicitly choose a wallet on every visit (e.g., shared kiosks, strict privacy requirements).

Framework-Specific Guides

Once you've installed the package and have your API keys, follow the guide for your framework:

Web Frameworks

• Vanilla JavaScript - Pure JavaScript, no framework
• React - Complete React integration guide
• Vue 3 - Vue 3 Composition API guide
• Nuxt - Nuxt 3 and Nitro integration

Each guide includes:

• Basic setup and initialization
• Connecting the wallet manager to the UI component
• Handling wallet events
• Signing transactions
• Best practices for your framework

What's Next?

• Concepts - Understand WalletManager, adapters, and web components
• Try It Out - See the wallet connector in action
• Customization - Style the component with CSS variables
• API Reference - Complete API documentation