xrpl.js getting started: install, connect, fund a wallet and send XRP

The fastest way to understand the XRP Ledger as a developer is to run a few calls against the Testnet, so every step below uses a throwaway wallet. Do not paste a real seed into any of it.

What xrpl.js is

xrpl.js is a JavaScript and TypeScript API for interacting with the XRP Ledger in Node.js and the browser. The repository calls it the recommended library for integrating a JavaScript or TypeScript app with the ledger, especially for advanced functionality such as issued tokens, payment paths, the decentralized exchange, account settings, payment channels, escrows and multi-signing. It works in Node.js, tested for v20 and later, and in web browsers, tested for Chrome.

Client libraries in general simplify the common work of accessing and processing ledger data and present it in the native conventions of each language. The source repository is where to file issues, and the maintainers aim to respond within about 3 days.

Step 1: Install it

In an existing project with a package.json, install xrpl.js with npm:

npm install xrpl

For a new project, create an empty folder, move into it, and use NPM to install the latest version. You need Node.js version 20 or later, and the repository recommends v22 while also supporting v20.

Step 2: Connect to a network

Create an instance of the Client class and call connect(). The sample code connects to the Testnet, one of the available parallel networks. For Mainnet, the tutorial’s example uses a public server.

import xrpl from "xrpl"

const SERVER_URL = "wss://s.altnet.rippletest.net:51233/"
const client = new xrpl.Client(SERVER_URL)
await client.connect()

That is the Testnet URL exactly as the tutorial defines it. Many network functions in xrpl.js return values asynchronously through Promises, so the samples use async and await.

On an outside network, always use wss or https. Call disconnect() when you are done so Node.js can end the process. The Testnet faucet guide explains the network choices in more detail.

Step 3: Create and fund a wallet

The xrpl.js Wallet class handles the keys and address of an account. On the Testnet, one call creates a wallet and funds it:

const fund_result = await client.fundWallet()
const test_wallet = fund_result.wallet
console.log(`Wallet: ${test_wallet.address}`)
console.log(`Balance: ${fund_result.balance}`)

Those lines come from the tutorial’s sample. For a wallet without funding, generate one with xrpl.Wallet.generate(). Generating an address and secret does not get you any XRP; you are only choosing a random number. To use an existing base58 seed, create a Wallet instance from it.

Use only an address and secret you generated securely, on your local machine. As a precaution, do not use the same addresses on Testnet or Devnet and on Mainnet. The wallets guide explains how keys and seeds relate.

Why your seed gives a different address in another tool

The ledger supports more than one signing algorithm. secp256k1 is the scheme Bitcoin uses and the ledger’s default. Ed25519 is newer, with better performance and other convenient properties, and many client libraries, xrpl.js among them, default to it. So the same seed can produce a different address in a different tool unless you name the algorithm.

One naming trap: in a wallet_propose response, master_key, master_seed and master_seed_hex all represent the same seed in different formats. Despite the prefix, the keys that seed represents are not necessarily the account’s master keys. The wallets guide covers what keys and seeds are in plain terms.

Step 4: Read the ledger with request()

The Client’s request() method reaches the XRP Ledger’s WebSocket API. This is how the tutorial looks up an account:

const response = await client.request({
  "command": "account_info",
  "account": test_wallet.address,
  "ledger_index": "validated"
})

In any response, look for “validated”: true to confirm the data comes from a validated ledger version.

To follow events instead, first call subscribe to choose the type of events you want, then attach a handler with the on(eventType, callback) method of the client:

client.request({
  "command": "subscribe",
  "streams": ["ledger"]
})
client.on("ledgerClosed", async (ledger) => {
  console.log(`Ledger #${ledger.ledger_index} validated`) // trimmed from the tutorial sample
})

The tutorial’s full sample prints a line each time the consensus process produces a new ledger version, and this snippet is trimmed to the first part of that line. It makes a quick check that the connection is live.

Step 5: Send XRP

To send a direct XRP Payment with xrpl.js, follow the Send XRP tutorial; it also covers xrpl-py for Python, xrpl4j for Java and XRPL_PHP for PHP. Typically you create ledger transactions as objects in the JSON transaction format.

Prepare

The bare minimum for an XRP Payment is the transaction type, the sender, the destination and the amount. The destination cannot be the sending address. The amount is typically an integer in drops of XRP, where 1,000,000 drops equals 1 XRP. Client.autofill() fills in good defaults for the remaining fields, and certain optional fields, such as LastLedgerSequence, are strongly recommended.

const prepared = await client.autofill({
  "TransactionType": "Payment",
  "Account": wallet.address,
  "DeliverMax": xrpl.xrpToDrops("22"),
  "Destination": "rPT1Sjq2YGrBMTttX4GZHjKu9dyfzbpAYe"
})

Here wallet is the funded Wallet; in the earlier snippet the same object is called test_wallet. In TypeScript you can also use transaction models such as xrpl.Payment to enforce the correct fields.

Sign

Signing uses your credentials to produce a binary blob containing the instructions and a signature from the sender. In JavaScript, call the sign() method of a Wallet instance. The signing API also returns the transaction’s ID, or hash, which you can use to look the transaction up later.

const signed = wallet.sign(prepared)

Submit and wait

Use the Client’s submitAndWait() to submit a signed transaction and wait for the response, or submitSigned() to submit and get only the preliminary response.

const tx = await client.submitAndWait(signed.tx_blob)

Initial results can change: transactions that succeed initially might ultimately fail, and transactions that fail initially might ultimately succeed. It may take 4-7 seconds for a transaction’s outcome to be final. The sending account must also keep its reserve, which the send-XRP tutorial gives as 1 XRP plus 0.2 XRP for each object it owns, matching the Mainnet amounts checked 2026-10-21. The account reserve guide explains why.

Mistakes that cost an afternoon

• Forgetting disconnect(): without it, Node.js will not end the process.
• Trusting a first result: check for validated data, not only the preliminary response.
• Reusing a funded Testnet identity on Mainnet: do not use the same addresses across networks.
• Using plain ws on an outside network: always use wss or https.
• Assuming an unfunded wallet is an account: you still need to send XRP to it.

Where to read more

The other developer guides cover networks and test funds. xrpl.org is the primary source for ledger concepts and tutorials, and the library reference lives on a separate site. The reference covers managing keys and creating test credentials with Wallet and Client.fundWallet(), submitting transactions, sending requests to observe the ledger, subscribing to changes, and helper functions such as xrpToDrops and rippleTimeToISOTime. Libraries for other languages are listed on the client libraries page, and the HTTP APIs cover languages without a library. For production, the repository advises running a rippled server and subscribing to the ripple-server mailing list. Primary documentation: Get Started Using JavaScript and Send XRP.