Skip to content

Ripple USD uses the Issued Tokens functionality that is native to the XRP Ledger.

On the XRP Ledger, a stablecoin is created by an issuer holding real-world assets as collateral, and creating equivalent tokens on the ledger. Users establish a trust line with the issuer to receive, hold, and transfer issued stablecoin. Transactions are fast and secure, benefiting from the efficiency of the XRP Ledger.

To learn more about the XRP Ledger issuer settings, see the Ripple USD GitHub repository.

Networks

The Ripple USD stablecoin is available on the XRP Ledger Mainnet and Testnet networks.

Mainnet

A Mainnet, short for main network, is the primary and fully functional blockchain network where real transactions are processed and actual value is transferred. The Mainnet is the live environment that operates the main ledger, as opposed to Testnets which are used for development and testing purposes. Ripple USD tokens on a Mainnet are backed by real-word assets.

Mainnet tokens

Mainnet Ripple USD tokens hold real financial value, therefore you should not use Mainnet for testing purposes.

Below you can find the Mainnet details for the Ripple USD token:

Testnet

A Testnet, short for test network, operates similarly to a Mainnet but without the associated real-world value and financial risk. Testnets allow developers to test out features in a safe environment. For example, a developer can simulate transferring Ripple USD between wallets on the XRP Ledger without risking real money in case of errors.

Testnet tokens

Ripple USD tokens on a Testnet hold no financial value, are intended for testing purposes only, and are not backed by real-world assets.

Here are the Testnet details for the Ripple USD token:

  • Network name: XRP Ledger Testnet
  • JSON-RPC URL: https://s.altnet.rippletest.net:51234/
  • Websocket: wss://s.altnet.rippletest.net:51233/
  • Issuer account address: rQhWct2fv4Vc4KRjRgMrxa8xPN9Zx9iLKV

Set up RLUSD trust line on the XRPL

Before an account can hold or receive RLUSD on the XRP Ledger, it must establish a trust line with the RLUSD issuer. A trust line is a relationship between two accounts that allows one account to hold tokens issued by the other. Without a trust line to the RLUSD issuer, your account cannot receive RLUSD payments.

Account reserve requirement: To set up a trust line, your account must first be active on the XRP Ledger. This requires a base reserve of 1 XRP. Each trust line also increases the account's owner reserve by 0.2 XRP. This means you need at least 1.2 XRP in your account to create a single RLUSD trust line. These reserves are held in your account and cannot be spent while the trust line exists. For more details, see Reserves.

This section shows you how to set up a trust line for RLUSD on the XRPL Testnet using either TypeScript or Python.

Prerequisites

Choose your preferred language:

RLUSD currency details

On the XRP Ledger, non-standard currency codes (longer than 3 characters) must be represented as a 40-character hex string. The hex representation for RLUSD is:

524C555344000000000000000000000000000000

Option 1: TypeScript

1. Set up your project

Create and initialize your project:

mkdir xrpl-rlusd-trustline
cd xrpl-rlusd-trustline
npm init -y

Install the required dependencies:

npm install xrpl typescript ts-node

2. Configure TypeScript

Create a tsconfig.json file:

{
  "compilerOptions": {
    "target": "ES2020",
    "module": "CommonJS",
    "lib": ["ES2020"],
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true,
    "outDir": "./dist",
    "rootDir": "./"
  },
  "include": ["*.ts"],
  "exclude": ["node_modules"]
}

Update the scripts section in your package.json:

"scripts": {
  "start": "ts-node main.ts"
}

3. Write the trust line setup code

Create a main.ts file with the following code:

import {
  Client,
  IssuedCurrencyAmount,
  TransactionMetadata,
  TrustSetFlags,
  Wallet,
} from "xrpl";

// RLUSD token details (Testnet)
const RLUSD: IssuedCurrencyAmount = {
  currency: "524C555344000000000000000000000000000000",
  issuer: "rQhWct2fv4Vc4KRjRgMrxa8xPN9Zx9iLKV",
  value: "1000000000",
};

async function main() {
  const client = new Client("wss://s.altnet.rippletest.net:51233");
  await client.connect();

  try {
    // Step 1: Create and fund a wallet on Testnet
    console.log("Creating and funding a wallet on Testnet...");
    const userWallet = Wallet.generate();
    await client.fundWallet(userWallet);

    console.log("======= Wallet Details =======");
    console.log("Address:", userWallet.address);
    console.log("Seed:", userWallet.seed);
    console.log("NOTE: Store the seed securely. Do not share it.");
    console.log("==============================\n");

    // Step 2: Create a trust line for RLUSD
    console.log("Creating a trust line for RLUSD...");
    const response = await client.submitAndWait(
      {
        TransactionType: "TrustSet",
        Account: userWallet.address,
        LimitAmount: RLUSD,
        Flags: TrustSetFlags.tfSetNoRipple,
      },
      { autofill: true, wallet: userWallet }
    );

    if (
      response.result.validated &&
      (response.result.meta as TransactionMetadata).TransactionResult !==
        "tesSUCCESS"
    ) {
      throw new Error(`Transaction failed: ${JSON.stringify(response)}`);
    }

    console.log(
      `Trustline created successfully: https://testnet.xrpl.org/transactions/${response.result.hash}`
    );
    console.log("\nYour wallet is now ready to receive RLUSD on Testnet!");
  } finally {
    await client.disconnect();
  }
}

main().catch(console.error);

4. Run the script

npm start

After running the script, your terminal displays the wallet address, seed, and a transaction link confirming the trust line was created. Your wallet is now ready to receive RLUSD on the XRPL Testnet.

Option 2: Python

1. Set up your project

Create a project directory and install the XRPL Python library:

mkdir xrpl-rlusd-trustline
cd xrpl-rlusd-trustline
pip install xrpl-py

2. Write the trust line setup code

Create a setup_rlusd_trustline.py file with the following code:

from xrpl.clients import JsonRpcClient
from xrpl.models.transactions import TrustSet
from xrpl.models.amounts import IssuedCurrencyAmount
from xrpl.transaction import submit_and_wait
from xrpl.wallet import generate_faucet_wallet

# RLUSD token details (Testnet)
RLUSD_CURRENCY_HEX = "524C555344000000000000000000000000000000"
RLUSD_ISSUER = "rQhWct2fv4Vc4KRjRgMrxa8xPN9Zx9iLKV"

def setup_rlusd_trustline():
    """Creates a wallet and sets up a trust line for RLUSD on XRPL Testnet."""

    # Connect to XRPL Testnet
    client = JsonRpcClient("https://s.altnet.rippletest.net:51234")

    # Step 1: Create and fund a wallet on Testnet
    print("Creating and funding a wallet on Testnet...")
    wallet = generate_faucet_wallet(client)

    print("======= Wallet Details =======")
    print(f"Address: {wallet.classic_address}")
    print(f"Seed: {wallet.seed}")
    print("NOTE: Store the seed securely. Do not share it.")
    print("==============================\n")

    # Step 2: Create a trust line for RLUSD
    print("Creating a trust line for RLUSD...")
    trust_set_tx = TrustSet(
        account=wallet.classic_address,
        limit_amount=IssuedCurrencyAmount(
            currency=RLUSD_CURRENCY_HEX,
            issuer=RLUSD_ISSUER,
            value="1000000000",
        ),
        flags=131072,  # tfSetNoRipple
    )

    try:
        response = submit_and_wait(trust_set_tx, client, wallet)

        if response.is_successful():
            print("Trustline created successfully!")
            print(f"Transaction hash: {response.result['hash']}")
            print(
                f"View on explorer: https://testnet.xrpl.org/transactions/{response.result['hash']}"
            )
            print("\nYour wallet is now ready to receive RLUSD on Testnet!")
        else:
            print("Trustline creation failed.")
            print(f"Error: {response.result.get('engine_result_message')}")

    except Exception as e:
        print(f"Error creating trust line: {str(e)}")

if __name__ == "__main__":
    setup_rlusd_trustline()

3. Run the script

python setup_rlusd_trustline.py

After running the script, your terminal displays the wallet address, seed, and a transaction link confirming the trust line was created. Your wallet is now ready to receive RLUSD on the XRPL Testnet.

Get Testnet RLUSD

Once your trust line is set up, you can obtain Testnet RLUSD tokens by visiting the RLUSD faucet at https://tryrlusd.com/.

Send an RLUSD payment

Once your trust line is established, you can send RLUSD to another account that also has an RLUSD trust line.

First, create a .env file at the root of your project:

WALLET_SEED=sYourSeedHere
DESTINATION_ADDRESS=rDestinationAddressHere
RLUSD_AMOUNT=10

TypeScript

import "dotenv/config";
import { Client, Payment, Wallet, TransactionMetadata } from "xrpl";

const RLUSD_CURRENCY = "524C555344000000000000000000000000000000";
const RLUSD_ISSUER = "rQhWct2fv4Vc4KRjRgMrxa8xPN9Zx9iLKV"; // Testnet issuer

async function sendRlusd(
  seed: string,
  destination: string,
  amount: string
) {
  const client = new Client("wss://s.altnet.rippletest.net:51233");
  await client.connect();

  try {
    const wallet = Wallet.fromSeed(seed);

    console.log(`\nSending ${amount} RLUSD from ${wallet.address} to ${destination}...`);

    const response = await client.submitAndWait(
      {
        TransactionType: "Payment",
        Account: wallet.address,
        Destination: destination,
        Amount: {
          currency: RLUSD_CURRENCY,
          issuer: RLUSD_ISSUER,
          value: amount,
        },
      },
      { autofill: true, wallet }
    );

    if (
      response.result.validated &&
      (response.result.meta as TransactionMetadata).TransactionResult ===
        "tesSUCCESS"
    ) {
      console.log("Payment successful!");
      console.log(`Transaction hash: ${response.result.hash}`);
    } else {
      console.log("Payment failed.");
      console.log(`Result: ${JSON.stringify(response.result)}`);
    }
  } finally {
    await client.disconnect();
  }
}

// Load values from .env file
const seed = process.env.WALLET_SEED!;
const destination = process.env.DESTINATION_ADDRESS!; // Must have an RLUSD trust line
const amount = process.env.RLUSD_AMOUNT || "10";

sendRlusd(seed, destination, amount).catch(console.error);

Python

from xrpl.clients import JsonRpcClient
from xrpl.models.transactions import Payment
from xrpl.transaction import submit_and_wait
from xrpl.wallet import Wallet

def send_rlusd(seed, destination_address, amount, issuer_address):
    """
    Sends RLUSD from a wallet to a destination address.

    Parameters:
        seed: The seed of the sending wallet.
        destination_address: The address to send RLUSD to.
        amount: Amount of RLUSD to send.
        issuer_address: The address of the RLUSD issuer.
    """
    client = JsonRpcClient("https://s.altnet.rippletest.net:51234")
    wallet = Wallet.from_seed(seed)

    currency_hex = "524C555344000000000000000000000000000000"

    payment = Payment(
        account=wallet.classic_address,
        amount={
            "currency": currency_hex,
            "value": str(amount),
            "issuer": issuer_address,
        },
        destination=destination_address,
    )

    print(f"\nSending {amount} RLUSD from {wallet.classic_address} to {destination_address}...")

    try:
        response = submit_and_wait(payment, client, wallet)

        if response.is_successful():
            print("Payment successful!")
            print(f"Transaction hash: {response.result['hash']}")
        else:
            print("Payment failed.")
            print(f"Error: {response.result.get('engine_result_message')}")

    except Exception as e:
        print(f"Error sending payment: {str(e)}")

if __name__ == "__main__":
    import os
    from dotenv import load_dotenv

    load_dotenv()

    seed = os.environ["WALLET_SEED"]
    destination = os.environ["DESTINATION_ADDRESS"]  # Must have an RLUSD trust line
    amount = int(os.getenv("RLUSD_AMOUNT", "10"))
    issuer = "rQhWct2fv4Vc4KRjRgMrxa8xPN9Zx9iLKV"  # RLUSD Testnet issuer

    send_rlusd(seed, destination, amount, issuer)

Important: The destination account must have an RLUSD trust line set up before it can receive RLUSD payments. Transactions to accounts without a trust line will fail.

Further reading

Glossary

RLUSD on EVM blockchains