Send XRP

This tutorial explains how to send a direct XRP Payment using xrpl.js for JavaScript, xrpl-py for Python, or xrpl4j for Java. First, we step through the process with the XRP Ledger Testnet. Then, we compare that to the additional requirements for doing the equivalent in production.

Tip: Check out the Code Samples for a complete version of the code used in this tutorial.

Prerequisites

To interact with the XRP Ledger, you need to set up a dev environment with the necessary tools. This tutorial provides examples using the following options:

Send a Payment on the Test Net

1. Get Credentials

To transact on the XRP Ledger, you need an address and secret key, and some XRP. The address and secret key look like this:

// Example credentials
const wallet = xrpl.Wallet.fromSeed("sn3nxiW7v8KXzPzAqzyHXbSSKNuN9")
console.log(wallet.address) // rMCcNuTcajgw7YTgBy1sys3b89QqjUrMpH

# Example Credentials ----------------------------------------------------------
from xrpl.wallet import Wallet
test_wallet = Wallet(seed="sn3nxiW7v8KXzPzAqzyHXbSSKNuN9", sequence=16237283)
print(test_wallet.classic_address) # "rMCcNuTcajgw7YTgBy1sys3b89QqjUrMpH"

// Example Credentials --------------------------------------------------------
WalletFactory walletFactory = DefaultWalletFactory.getInstance();
Wallet testWallet = walletFactory
  .fromSeed("sn3nxiW7v8KXzPzAqzyHXbSSKNuN9", true)
  .wallet();

// Get the Classic address from testWallet
Address classicAddress = testWallet.classicAddress();
System.out.println(classicAddress); // "rMCcNuTcajgw7YTgBy1sys3b89QqjUrMpH"

The secret key shown here is for example only. For development purposes, you can get your own credentials, pre-funded with XRP, on the Testnet using the following interface:

Generating Keys...

Caution: Ripple provides the Testnet and Devnet for testing purposes only, and sometimes resets the state of these test networks along with all balances. As a precaution, do not use the same addresses on Testnet/Devnet and Mainnet.

When you're building production-ready software, you should use an existing account, and manage your keys using a secure signing configuration.

2. Connect to a Testnet Server

First, you must connect to an XRP Ledger server so you can get the current status of your account and the shared ledger. You can use this information to automatically fill in some required fields of a transaction. You also must be connected to the network to submit transactions to it.

The following code connects to a public Testnet servers:

// 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)
  client.disconnect()
}

main()

# Connect ----------------------------------------------------------------------
import xrpl
testnet_url = "https://s.altnet.rippletest.net:51234"
client = xrpl.clients.JsonRpcClient(testnet_url)

// Connect --------------------------------------------------------------------
HttpUrl rippledUrl = HttpUrl.get("https://s.altnet.rippletest.net:51234/");
XrplClient xrplClient = new XrplClient(rippledUrl);

For this tutorial, click the following button to connect:

Connection status: Not connected

3. Prepare Transaction

Typically, we create XRP Ledger transactions as objects in the JSON transaction format. The following example shows a minimal Payment specification:

{
  "TransactionType": "Payment",
  "Account": "rPT1Sjq2YGrBMTttX4GZHjKu9dyfzbpAYe",
  "Amount": "2000000",
  "Destination": "rUCzEr6jrEyMpjhs4wSdQdz4g8Y382NxfM"
}

The bare minimum set of instructions you must provide for an XRP Payment is:

  • An indicator that this is a payment. ("TransactionType": "Payment")
  • The sending address. ("Account")
  • The address that should receive the XRP ("Destination"). This can't be the same as the sending address.
  • The amount of XRP to send ("Amount"). Typically, this is specified as an integer in "drops" of XRP, where 1,000,000 drops equals 1 XRP.

Technically, a transaction must contain some additional fields, and certain optional fields such as LastLedgerSequence are strongly recommended. Some other language-specific notes:

  • If you're using xrpl.js for JavaScript, you can use the Client.autofill() method to automatically fill in good defaults for the remaining fields of a transaction. In TypeScript, you can also use the transaction models like xrpl.Payment to enforce the correct fields.
  • With xrpl-py for Python, you can use the models in xrpl.models.transactions to construct transactions as native Python objects.
  • With xrpl4j for Java, you can use the model objects in the xrpl4j-model module to construct transactions as Java objects.
    • Unlike the other libraries, you must provide the account sequence and the signingPublicKey of the source account of a Transaction at the time of construction, as well as a fee.

Here's an example of preparing the above payment:

// Prepare transaction -------------------------------------------------------
  const prepared = await client.autofill({
    "TransactionType": "Payment",
    "Account": wallet.address,
    "Amount": xrpl.xrpToDrops("22"),
    "Destination": "rPT1Sjq2YGrBMTttX4GZHjKu9dyfzbpAYe"
  })
  const max_ledger = prepared.LastLedgerSequence
  console.log("Prepared transaction instructions:", prepared)
  console.log("Transaction cost:", xrpl.dropsToXrp(prepared.Fee), "XRP")
  console.log("Transaction expires after ledger:", max_ledger)

# Prepare transaction ----------------------------------------------------------
my_payment = xrpl.models.transactions.Payment(
    account=test_wallet.classic_address,
    amount=xrpl.utils.xrp_to_drops(22),
    destination="rPT1Sjq2YGrBMTttX4GZHjKu9dyfzbpAYe",
)
print("Payment object:", my_payment)

// Prepare transaction --------------------------------------------------------
// Look up your Account Info
AccountInfoRequestParams requestParams = AccountInfoRequestParams.builder()
  .ledgerIndex(LedgerIndex.VALIDATED)
  .account(classicAddress)
  .build();
AccountInfoResult accountInfoResult = xrplClient.accountInfo(requestParams);
UnsignedInteger sequence = accountInfoResult.accountData().sequence();

// Request current fee information from rippled
FeeResult feeResult = xrplClient.fee();
XrpCurrencyAmount openLedgerFee = feeResult.drops().openLedgerFee();

// Get the latest validated ledger index
LedgerIndex validatedLedger = xrplClient.ledger(
    LedgerRequestParams.builder()
      .ledgerIndex(LedgerIndex.VALIDATED)
      .build()
  )
  .ledgerIndex()
  .orElseThrow(() -> new RuntimeException("LedgerIndex not available."));

// Workaround for https://github.com/XRPLF/xrpl4j/issues/84
UnsignedInteger lastLedgerSequence = UnsignedInteger.valueOf(
  validatedLedger.plus(UnsignedLong.valueOf(4)).unsignedLongValue().intValue()
);

// Construct a Payment
Payment payment = Payment.builder()
  .account(classicAddress)
  .amount(XrpCurrencyAmount.ofXrp(BigDecimal.ONE))
  .destination(Address.of("rPT1Sjq2YGrBMTttX4GZHjKu9dyfzbpAYe"))
  .sequence(sequence)
  .fee(openLedgerFee)
  .signingPublicKey(testWallet.publicKey())
  .lastLedgerSequence(lastLedgerSequence)
  .build();
System.out.println("Constructed Payment: " + payment);
Send:
XRP

4. Sign the Transaction Instructions

Signing a transaction uses your credentials to authorize the transaction on your behalf. The input to this step is a completed set of transaction instructions (usually JSON), and the output is a binary blob containing the instructions and a signature from the sender.

// Sign prepared instructions ------------------------------------------------
  const signed = wallet.sign(prepared)
  console.log("Identifying hash:", signed.hash)
  console.log("Signed blob:", signed.tx_blob)

# Sign transaction -------------------------------------------------------------
signed_tx = xrpl.transaction.safe_sign_and_autofill_transaction(
        my_payment, test_wallet, client)
max_ledger = signed_tx.last_ledger_sequence
tx_id = signed_tx.get_hash()
print("Signed transaction:", signed_tx)
print("Transaction cost:", xrpl.utils.drops_to_xrp(signed_tx.fee), "XRP")
print("Transaction expires after ledger:", max_ledger)
print("Identifying hash:", tx_id)

// Sign transaction -----------------------------------------------------------
// Construct a SignatureService to sign the Payment
PrivateKey privateKey = PrivateKey.fromBase16EncodedPrivateKey(
  testWallet.privateKey().get()
);
SignatureService signatureService = new SingleKeySignatureService(privateKey);

// Sign the Payment
SignedTransaction<Payment> signedPayment = signatureService.sign(
  KeyMetadata.EMPTY,
  payment
);
System.out.println("Signed Payment: " + signedPayment.signedTransaction());

The result of the signing operation is a transaction object containing a signature. Typically, XRP Ledger APIs expect a signed transaction to be the hexadecimal representation of the transaction's canonical binary format, called a "blob".

  • In xrpl.js, the signing API also returns the transaction's ID, or identifying hash, which you can use to look up the transaction later. This is a 64-character hexadecimal string that is unique to this transaction.
  • In xrpl-py, you can get the transaction's hash in the response to submitting it in the next step.
  • In xrpl4j, SignatureService.sign returns a SignedTransaction, which contains the transaction's hash, which you can use to look up the transaction later.

5. Submit the Signed Blob

Now that you have a signed transaction, you can submit it to an XRP Ledger server, which relays it through the network. It's also a good idea to take note of the latest validated ledger index before you submit. The earliest ledger version that your transaction could get into as a result of this submission is one higher than the latest validated ledger when you submit it. Of course, if the same transaction was previously submitted, it could already be in a previous ledger. (It can't succeed a second time, but you may not realize it succeeded if you aren't looking in the right ledger versions.)

// Submit signed blob --------------------------------------------------------
  const tx = await client.submitAndWait(signed.tx_blob)

# Submit transaction -----------------------------------------------------------
try:
    tx_response = xrpl.transaction.send_reliable_submission(signed_tx, client)
except xrpl.transaction.XRPLReliableSubmissionException as e:
    exit(f"Submit failed: {e}")

// Submit transaction ---------------------------------------------------------
SubmitResult<Transaction> prelimResult = xrplClient.submit(signedPayment);
System.out.println(prelimResult);

This method returns the tentative result of trying to apply the transaction to the open ledger. This result can change when the transaction is included in a validated ledger: transactions that succeed initially might ultimately fail, and transactions that fail initially might ultimately succeed. Still, the tentative result often matches the final result, so it's OK to get excited if you see tesSUCCESS here. 😁

If you see any other result, you should check the following:

  • Are you using the correct addresses for the sender and destination?
  • Did you forget any other fields of the transaction, skip any steps, or make any other typos?
  • Do you have enough Test XRP to send the transaction? The amount of XRP you can send is limited by the reserve requirement, which is currently 10 XRP with an additional 2 XRP for each "object" you own in the ledger. (If you generated a new address with the Testnet Faucet, you don't own any objects.)
  • Are you connected to a server on the test network?

See the full list of transaction results for more possibilities.

Sending...

6. Wait for Validation

Most transactions are accepted into the next ledger version after they're submitted, which means it may take 4-7 seconds for a transaction's outcome to be final. If the XRP Ledger is busy or poor network connectivity delays a transaction from being relayed throughout the network, a transaction may take longer to be confirmed. (For more information on expiration of unconfirmed transactions, see Reliable Transaction Submission.)

// Wait for validation -------------------------------------------------------
  // submitAndWait() handles this automatically, but it can take 4-7s.

# Wait for validation ----------------------------------------------------------
# send_reliable_submission() handles this automatically, but it can take 4-7s.

// Wait for validation --------------------------------------------------------
boolean transactionValidated = false;
boolean transactionExpired = false;
while (!transactionValidated && !transactionExpired) {
  Thread.sleep(4 * 1000);
  LedgerIndex latestValidatedLedgerIndex = xrplClient.ledger(
      LedgerRequestParams.builder().ledgerIndex(LedgerIndex.VALIDATED).build()
    )
    .ledgerIndex()
    .orElseThrow(() ->
      new RuntimeException("Ledger response did not contain a LedgerIndex.")
    );

  TransactionResult<Payment> transactionResult = xrplClient.transaction(
    TransactionRequestParams.of(signedPayment.hash()),
    Payment.class
  );

  if (transactionResult.validated()) {
    System.out.println("Payment was validated with result code " +
      transactionResult.metadata().get().transactionResult());
    transactionValidated = true;
  } else {
    boolean lastLedgerSequenceHasPassed = FluentCompareTo.
      is(latestValidatedLedgerIndex.unsignedLongValue())
      .greaterThan(UnsignedLong.valueOf(lastLedgerSequence.intValue()));
    if (lastLedgerSequenceHasPassed) {
      System.out.println("LastLedgerSequence has passed. Last tx response: "
        transactionResult);
    );
      transactionExpired = true;
    } else {
      System.out.println("Payment not yet validated.");
    }
  }
}
Transaction ID: (None)
Latest Validated Ledger Index: (Not connected)
Ledger Index at Time of Submission: (Not submitted)
Transaction LastLedgerSequence: (Not prepared)

7. Check Transaction Status

To know for sure what a transaction did, you must look up the outcome of the transaction when it appears in a validated ledger version.

// Check transaction results -------------------------------------------------
  console.log("Transaction result:", tx.result.meta.TransactionResult)
  console.log("Balance changes:", JSON.stringify(xrpl.getBalanceChanges(tx.result.meta), null, 2))

# Check transaction results ----------------------------------------------------
import json
print(json.dumps(tx_response.result, indent=4, sort_keys=True))
print(f"Explorer link: https://testnet.xrpl.org/transactions/{tx_id}")
metadata = tx_response.result.get("meta", {})
if metadata.get("TransactionResult"):
    print("Result code:", metadata["TransactionResult"])
if metadata.get("delivered_amount"):
    print("XRP delivered:", xrpl.utils.drops_to_xrp(
                metadata["delivered_amount"]))

// Check transaction results --------------------------------------------------
System.out.println(transactionResult);
System.out.println("Explorer link: https://testnet.xrpl.org/transactions/" +
    signedPayment.hash());
transactionResult.metadata().ifPresent(metadata -> {
  System.out.println("Result code: " + metadata.transactionResult());

  metadata.deliveredAmount().ifPresent(deliveredAmount ->
    System.out.println("XRP Delivered: " +
      ((XrpCurrencyAmount) deliveredAmount).toXrp())
  );
});

Caution: XRP Ledger APIs may return tentative results from ledger versions that have not yet been validated. For example, in tx method response, be sure to look for "validated": true to confirm that the data comes from a validated ledger version. Transaction results that are not from a validated ledger version are subject to change. For more information, see Finality of Results.

Differences for Production

To send an XRP payment on the production XRP Ledger, the steps you take are largely the same. However, there are some key differences in the necessary setup:

Getting a Real XRP Account

This tutorial uses a button to get an address that's already funded with Test Net XRP, which only works because Test Net XRP is not worth anything. For actual XRP, you need to get XRP from someone who already has some. (For example, you might buy it on an exchange.) You can generate an address and secret that'll work on either production or the Testnet as follows:

const wallet = new xrpl.Wallet()
console.log(wallet.address) // Example: rGCkuB7PBr5tNy68tPEABEtcdno4hE6Y7f
console.log(wallet.seed) // Example: sp6JS7f14BuwFY8Mw6bTtLKWauoUs

from xrpl.wallet import Wallet
my_wallet = Wallet.create()
print(my_wallet.classic_address) # Example: rGCkuB7PBr5tNy68tPEABEtcdno4hE6Y7f
print(my_wallet.seed)            # Example: sp6JS7f14BuwFY8Mw6bTtLKWauoUs

WalletFactory walletFactory = DefaultWalletFactory.getInstance();
SeedWalletGenerationResult generationResult = walletFactory.randomWallet(false);
Wallet wallet = generationResult.wallet();
System.out.println(wallet.classicAddress()); // Example: rGCkuB7PBr5tNy68tPEABEtcdno4hE6Y7f
System.out.println(generationResult.seed()); // Example: sp6JS7f14BuwFY8Mw6bTtLKWauoUs

Warning: You should only use an address and secret that you generated securely, on your local machine. If another computer generated the address and secret and sent it to you over a network, it's possible that someone else on the network may see that information. If they do, they'll have as much control over your XRP as you do. It's also recommended not to use the same address for the Testnet and Mainnet, because transactions that you created for use on one network could also be valid to execute on the other network, depending on the parameters you provided.

Generating an address and secret doesn't get you XRP directly; you're only choosing a random number. You must also receive XRP at that address to fund the account. A common way to acquire XRP is to buy it from an exchange, then withdraw it to your own address.

Connecting to the Production XRP Ledger

When you instantiate your client's connect to the XRP Ledger, you must specify a server that's synced with the appropriate network. For many cases, you can use public servers, such as in the following example:

const xrpl = require('xrpl')
const api = new xrpl.Client('wss://xrplcluster.com')
api.connect()

from xrpl.clients import JsonRpcClient
client = JsonRpcClient("https://xrplcluster.com")

final HttpUrl rippledUrl = HttpUrl.get("https://xrplcluster.com");
XrplClient xrplClient = new XrplClient(rippledUrl);

If you install rippled yourself, it connects to the production network by default. (You can also configure it to connect to the test net instead.) After the server has synced (typically within about 15 minutes of starting it up), you can connect to it locally, which has various benefits. The following example shows how to connect to a server running the default configuration:

const xrpl = require('xrpl')
const api = new xrpl.Client('ws://localhost:6006')
api.connect()

from xrpl.clients import JsonRpcClient
client = JsonRpcClient("http://localhost:5005")

final HttpUrl rippledUrl = HttpUrl.get("http://localhost:5005");
XrplClient xrplClient = new XrplClient(rippledUrl);

Tip: The local connection uses an unencrypted protocol (ws or http) rather than the TLS-encrypted version (wss or https). This is secure only because the communications never leave the same machine, and is easier to set up because it does not require a TLS certificate. For connections on an outside network, always use wss or https.

Next Steps

After completing this tutorial, you may want to try the following: