XRPL Integration

A lightweight TypeScript wrapper for the XRP Ledger using xrpl.js. Implements a singleton pattern for easy integration into any application.

Features

• Singleton client pattern for connection management
• XRP and IOU token balance queries
• XRP and IOU token transfers
• Trustline verification
• Full TypeScript support with exported types
• Works with Mainnet, Testnet, and Devnet

Installation

npm install @blockbima/xrpl-integration

Quick Start

import { XRPLClient, NETWORKS } from "xrpl-integration";
import { Wallet } from "xrpl";

// Get singleton instance (defaults to testnet)
const client = XRPLClient.getInstance(NETWORKS.TESTNET);

// Connect to the network
await client.connect();

// Check XRP balance
const balance = await client.getXRPBalance("rAddress...");
console.log(`Balance: ${balance.balance} XRP`);

// Disconnect when done
await client.disconnect();

API Reference

Connection

// Get client instance
const client = XRPLClient.getInstance(networkUrl?: string);

// Connect/disconnect
await client.connect();
await client.disconnect();

// Check connection status
client.isConnected; // boolean

// Reset instance (for switching networks)
await XRPLClient.resetInstance();

Balance Queries

// XRP balance
const xrpBalance = await client.getXRPBalance(address);
// Returns: { address, balance, balanceDrops }

// IOU token balance
const iouBalance = await client.getIOUBalance(address, currency, issuer);
// Returns: { address, currency, issuer, balance }

Transfers

// Send XRP
const result = await client.sendXRP({
  wallet,           // xrpl Wallet instance
  destination,      // recipient address
  amount,           // amount in XRP (not drops)
  destinationTag?,  // optional
  memo?,            // optional
});

// Send IOU tokens
const result = await client.sendIOU({
  wallet,
  destination,
  currency,         // e.g., "USD"
  issuer,           // token issuer address
  amount,
  destinationTag?,
  memo?,
});

// Returns: { success, hash, ledgerIndex, response }

Trustlines

// Check specific trustline
const trustline = await client.checkTrustline(address, currency, issuer);
// Returns: { exists, currency, issuer, balance, limit, ... }

// Get all trustlines for an account
const trustlines = await client.getAllTrustlines(address);

Testnet Utilities

// Fund a wallet on testnet/devnet
const wallet = await client.fundWallet();
// Or fund an existing wallet
const funded = await client.fundWallet(existingWallet);

Network Constants

import { NETWORKS } from "xrpl-integration";

NETWORKS.MAINNET       // wss://xrplcluster.com/
NETWORKS.MAINNET_RIPPLE // wss://s1.ripple.com/
NETWORKS.TESTNET       // wss://s.altnet.rippletest.net:51233/
NETWORKS.DEVNET        // wss://s.devnet.rippletest.net:51233/

Error Handling

All methods throw XRPLClientError with specific error types:

import { XRPLClientError, XRPLClientErrorType } from "xrpl-integration";

try {
  await client.getXRPBalance("invalid");
} catch (error) {
  if (error instanceof XRPLClientError) {
    switch (error.type) {
      case XRPLClientErrorType.NOT_CONNECTED:
      case XRPLClientErrorType.INVALID_ADDRESS:
      case XRPLClientErrorType.ACCOUNT_NOT_FOUND:
      case XRPLClientErrorType.TRANSACTION_FAILED:
        // Handle specific error
    }
  }
}

License

MIT