Get Started Using JavaScript Library
This tutorial guides you through the basics of building an XRP Ledger-connected application in JavaScript or TypeScript using the xrpl.js
client library in either Node.js or web browsers.
The scripts and config files used in this guide are available in this website's GitHub Repository.
Learning Goals
In this tutorial, you'll learn:
- The basic building blocks of XRP Ledger-based applications.
- How to connect to the XRP Ledger using
xrpl.js
. - How to get an account on the Testnet using
xrpl.js
. - How to use the
xrpl.js
library to look up information about an account on the XRP Ledger. - How to put these steps together to create a JavaScript app or web-app.
Requirements
To follow this tutorial, you should have some familiarity with writing code in JavaScript and managing small JavaScript projects. In browsers, any modern web browser with JavaScript support should work fine. In Node.js, version 14 is recommended. Node.js versions 12 and 16 are also regularly tested.
Install with npm
Start a new project by creating an empty folder, then move into that folder and use NPM to install the latest version of xrpl.js:
npm install xrpl
Start Building
When you're working with the XRP Ledger, there are a few things you'll need to manage, whether you're adding XRP to your account, integrating with the decentralized exchange, or issuing tokens. This tutorial walks you through basic patterns common to getting started with all of these use cases and provides sample code for implementing them.
Here are some steps you use in many XRP Ledger projects:
1. Import the Library
How you load xrpl.js
into your project depends on your development environment:
Web Browsers
Add a <script>
tag such as the following to your HTML:
<script src="https://unpkg.com/xrpl/build/xrpl-latest-min.js"></script>
You can load the library from a CDN as in the above example, or download a release and host it on your own website.
This loads the module into the top level as xrpl
.
Node.js
Add the library using npm. This updates your package.json
file, or creates a new one if it didn't already exist:
npm install xrpl
Then import the library:
const xrpl = require("xrpl")
2. Connect to the XRP Ledger
To make queries and submit transactions, you need to connect to the XRP Ledger. To do this with xrpl.js
, you create an instance of the Client
class and use the connect()
method.
Tip: Many network functions in xrpl.js
use Promises to return values asynchronously. The code samples here use the async/await
pattern to wait for the actual result of the Promises.
// In browsers, use a <script> tag. In Node.js, uncomment the following line: // const xrpl = require('xrpl') // Wrap code in an async function so we can use await async function main() { // Define the network client const client = new xrpl.Client("wss://s.altnet.rippletest.net:51233") await client.connect() // ... custom code goes here // Disconnect when done (If you omit this, Node.js won't end the process) await client.disconnect() } main()
Connect to the XRP Ledger Mainnet
The sample code in the previous section shows you how to connect to the Testnet, which is one of the available parallel networks. When you're ready to move to production, you'll need to connect to the XRP Ledger Mainnet. You can do that in two ways:
By installing the core server (
rippled
) and running a node yourself. The core server connects to the Mainnet by default, but you can change the configuration to use Testnet or Devnet. There are good reasons to run your own core server. If you run your own server, you can connect to it like so:const MY_SERVER = "ws://localhost:6006/" const client = new xrpl.Client(MY_SERVER) await client.connect()
See the example core server config file for more information about default values.
By using one of the available public servers:
const PUBLIC_SERVER = "wss://xrplcluster.com/" const client = new xrpl.Client(PUBLIC_SERVER) await client.connect()
3. Get Account
The xrpl.js
library has a Wallet
class for handling the keys and address of an XRP Ledger account. On Testnet, you can fund a new account like this:
// Create a wallet and fund it with the Testnet faucet: const fund_result = await client.fundWallet() const test_wallet = fund_result.wallet console.log(fund_result)
If you only want to generate keys, you can create a new Wallet
instance like this:
const test_wallet = xrpl.Wallet.generate()
Or, if you already have a seed encoded in base58, you can make a Wallet
instance from it like this:
const test_wallet = xrpl.Wallet.fromSeed("sn3nxiW7v8KXzPzAqzyHXbSSKNuN9") // Test secret; don't use for real
4. Query the XRP Ledger
Use the Client's request()
method to access the XRP Ledger's WebSocket API. For example:
// Get info from the ledger about the address we just funded const response = await client.request({ "command": "account_info", "account": test_wallet.address, "ledger_index": "validated" }) console.log(response)
5. Listen for Events
You can set up handlers for various types of events in xrpl.js
, such as whenever the XRP Ledger's consensus process produces a new ledger version. To do that, first call the subscribe method to get the type of events you want, then attach an event handler using the on(eventType, callback)
method of the client.
// Listen to ledger close events client.request({ "command": "subscribe", "streams": ["ledger"] }) client.on("ledgerClosed", async (ledger) => { console.log(`Ledger #${ledger.ledger_index} validated with ${ledger.txn_count} transactions!`) })
Keep on Building
Now that you know how to use xrpl.js
to connect to the XRP Ledger, get an account, and look up information about it, you can also:
- Send XRP.
- Issue a Fungible Token
- Set up secure signing for your account.