Get Started Using TypeScript Library

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 along with the TypeScript compiler and the Node.js type definitions:

npm install xrpl
npm install --save-dev typescript @types/node

This updates your package.json file, or creates a new one if it didn't already exist.

Your package.json file should look something like this:

{
  "name": "get-started-typescript",
  "description": "Example code for the Get Started Using TypeScript tutorial.",
  "dependencies": {
    "xrpl": "^4.4.0"
  },
  "devDependencies": {
    "typescript": "^5.5.0",
    "@types/node": "^22.0.0"
  },
  "type": "module"
}

Add a tsconfig.json file to tell the compiler how to build your project. The settings below target modern JavaScript, enable strict type checking, and write the compiled output to a dist folder.

{
  "compilerOptions": {
    "target": "ES2020",
    "module": "NodeNext",
    "moduleResolution": "NodeNext",
    "lib": ["ES2020", "DOM"],
    "outDir": "dist",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true
  },
  "include": ["*.ts"]
}

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. Because you import the class directly, TypeScript infers the correct type for your client.

The sample code 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 (xrpld) 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 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 Client(PUBLIC_SERVER)
  await client.connect()

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 as shown in the example. Annotating the result with the Wallet type lets the compiler check every property you access.

If you want to generate a wallet without funding it, you can create a new Wallet instance. Keep in mind that you need to send XRP to the wallet for it to be a valid account on the ledger.

To use an existing wallet seed encoded in base58, you can create a Wallet instance from it.

Use the Client's request() method to access the XRP Ledger's WebSocket API. Typing the request as an AccountInfoRequest verifies the command name and its fields, and the library infers the matching AccountInfoResponse for the result so you get autocomplete on the response too.

One of the biggest advantages of TypeScript is turning your own input into a well-formed transaction. Typing an object as a Payment makes the compiler require every field and reject values of the wrong type before you run the code. The xrpToDrops() helper converts an XRP amount into the drops string the ledger expects, and validate() runs the same structural checks the server does at runtime.

This example builds and validates the transaction without submitting it. To send it, sign and submit in one call with submitAndWait(). Before submitting real transactions, read Set up Secure Signing.

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. The callback's ledger argument is typed for you, so fields like ledger_index and txn_count are checked as you use them.

Call the disconnect() function so Node.js can end the process. The example code waits 10 seconds before disconnecting to allow time for the ledger event listener to receive and display events.

Finally, in your terminal, compile the TypeScript to JavaScript and run the result:

npx tsc
node dist/get-acct-info.js

You should see output similar to the following:

Connected to Testnet

Creating a new wallet and funding it with Testnet XRP...
Wallet: rKTfqsMZTPWNYWrzFjUwDNLa8XTeA45wvB
Balance: 100
Account Testnet Explorer URL:
  https://testnet.xrpl.org/accounts/rKTfqsMZTPWNYWrzFjUwDNLa8XTeA45wvB

Getting account info...
{
  "api_version": 2,
  "id": 4,
  "result": {
    "account_data": {
      "Account": "rKTfqsMZTPWNYWrzFjUwDNLa8XTeA45wvB",
      "Balance": "100000000",
      "Flags": 0,
      "LedgerEntryType": "AccountRoot",
      "OwnerCount": 0,
      "PreviousTxnID": "C791975AB1FA811DD7C2A958F71629C3EB830545B25C11F488249D0AEADAA04C",
      "PreviousTxnLgrSeq": 18910118,
      "Sequence": 18910118,
      "index": "0553BF36D48179C15297E1087002B6D33E076D71CAFEA7F0BB1362B9502C851D"
    },
    "ledger_hash": "CC057AE6CF43485107EA0E4184DE48D73DC4C8A742577964462AB49EDA8EC84E",
    "ledger_index": 18910118,
    "validated": true
  },
  "type": "response"
}

Built and validated a Payment transaction:
{
  "TransactionType": "Payment",
  "Account": "rKTfqsMZTPWNYWrzFjUwDNLa8XTeA45wvB",
  "Amount": "22000000",
  "Destination": "rPT1Sjq2YGrBMTttX4GZHjKu9dyfzbpAYe"
}

Listening for ledger close events...
Ledger #18910119 validated with 0 transactions!
Ledger #18910120 validated with 1 transactions!
Ledger #18910121 validated with 1 transactions!

Disconnected