Send XRP

This tutorial explains how to send a simple XRP Payment using ripple-lib for JavaScript or xrpl-py for Python. 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
let address = "rMCcNuTcajgw7YTgBy1sys3b89QqjUrMpH"
let secret = "sn3nxiW7v8KXzPzAqzyHXbSSKNuN9"

# Example Credentials ----------------------------------------------------------
from xrpl.wallet import Wallet
test_wallet = Wallet(seed="sn3nxiW7v8KXzPzAqzyHXbSSKNuN9", sequence=16237283)
print(test_wallet.classic_address) # "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, Ripple recommends not using the same addresses on Testnet/Devnet and Mainnet.

When you're building actual production-ready software, you'll instead 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 certain required fields of a transaction. (For more security, you can sign transactions from a machine that doesn't have an internet connection, but only if you can provide all of the necessary details.) You also must be connected to the network to submit transactions to it.

The following code connects to one of the public Testnet servers that Ripple runs:

// Connect ---------------------------------------------------------------------
// ripple = require('ripple-lib') // For Node.js. In browsers, use <script>.
api = new ripple.RippleAPI({server: 'wss://s.altnet.rippletest.net:51233'})
api.connect()
api.on('connected', async () => {

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

For this tutorial, you can connect directly from your browser by pressing the following button:

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 viable 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 ripple-lib for JavaScript, you can use the prepareTransaction() method to automatically fill in good defaults for the remaining fields of a transaction.
  • With xrpl-py for Python, you can use the models in xrpl.models.transactions to construct transactions as native Python objects.

Here's an example of preparing the above payment:

// Prepare transaction -------------------------------------------------------
  const preparedTx = await api.prepareTransaction({
    "TransactionType": "Payment",
    "Account": address,
    "Amount": api.xrpToDrops("22"), // Same as "Amount": "22000000"
    "Destination": "rUCzEr6jrEyMpjhs4wSdQdz4g8Y382NxfM"
  }, {
    // Expire this transaction if it doesn't execute within ~5 minutes:
    "maxLedgerVersionOffset": 75
  })
  const maxLedgerVersion = preparedTx.instructions.maxLedgerVersion
  console.log("Prepared transaction instructions:", preparedTx.txJSON)
  console.log("Transaction cost:", preparedTx.instructions.fee, "XRP")
  console.log("Transaction expires after ledger:", maxLedgerVersion)

# Prepare transaction ----------------------------------------------------------
import xrpl.utils # workaround for https://github.com/XRPLF/xrpl-py/issues/222
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)
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 = api.sign(preparedTx.txJSON, secret)
  const txID = signed.id
  const tx_blob = signed.signedTransaction
  console.log("Identifying hash:", txID)
  console.log("Signed blob:", 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
print("Signed transaction:", signed_tx)
print("Transaction cost:", xrpl.utils.drops_to_xrp(signed_tx.fee), "XRP")
print("Transaction expires after ledger:", max_ledger)

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 ripple-lib, 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.

5. Submit the Signed Blob

Now that you have a signed transaction, you can submit it to an XRP Ledger server, and that server will relay 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 --------------------------------------------------------
  // The earliest ledger a transaction could appear in is the first ledger
  // after the one that's already validated at the time it's *first* submitted.
  const earliestLedgerVersion = (await api.getLedgerVersion()) + 1
  const result = await api.submit(tx_blob)
  console.log("Tentative result code:", result.resultCode)
  console.log("Tentative result message:", result.resultMessage)

# Submit transaction -----------------------------------------------------------
validated_index = xrpl.ledger.get_latest_validated_ledger_sequence(client)
min_ledger = validated_index + 1
print(f"Can be validated in ledger range: {min_ledger} - {max_ledger}")

# Tip: you can use xrpl.transaction.send_reliable_submission(signed_tx, client)
#  to send the transaction and wait for the results to be validated.
try:
    prelim_result = xrpl.transaction.submit_transaction(signed_tx, client)
except xrpl.transaction.XRPLReliableSubmissionException as e:
    exit(f"Submit failed: {e}")
print("Preliminary transaction result:", prelim_result)
tx_id = prelim_result.result["tx_json"]["hash"]

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 Net XRP to send the transaction? The amount of XRP you can send is limited by the reserve requirement, which is currently 20 XRP with an additional 5 XRP for each "object" you own in the ledger. (If you generated a new address with the Test Net 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 -------------------------------------------------------
  let has_final_status = false
  api.request("subscribe", {accounts: [address]})
  api.connection.on("transaction", (event) => {
    if (event.transaction.hash == txID) {
      console.log("Transaction has executed!", event)
      has_final_status = true
    }
  })
  api.on('ledger', ledger => {
    if (ledger.ledgerVersion > maxLedgerVersion && !has_final_status) {
      console.log("Ledger version", ledger.ledgerVersion, "was validated.")
      console.log("If the transaction hasn't succeeded by now, it's expired")
      has_final_status = true
    }
  })

# Wait for validation ----------------------------------------------------------
# Note: If you used xrpl.transaction.send_reliable_submission, you can skip this
#  and use the result of that method directly.
from time import sleep
while True:
    sleep(1)
    validated_ledger = xrpl.ledger.get_latest_validated_ledger_sequence(client)
    tx_response = xrpl.transaction.get_transaction_from_hash(tx_id, client)
    if tx_response.is_successful():
        if tx_response.result.get("validated"):
            print("Got validated result!")
            break
        else:
            print(f"Results not yet validated... "
                  f"({validated_ledger}/{max_ledger})")
    if validated_ledger > max_ledger:
        print("max_ledger has passed. Last tx response:", tx_response)
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 -------------------------------------------------
  try {
    tx = await api.getTransaction(txID, {
        minLedgerVersion: earliestLedgerVersion})
    console.log("Transaction result:", tx.outcome.result)
    console.log("Balance changes:", JSON.stringify(tx.outcome.balanceChanges))
  } catch(error) {
    console.log("Couldn't get transaction outcome:", error)
  }

}) // End of api.on.('connected')

# 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"]))

The RippleAPI getTransaction() method only returns success if the transaction is in a validated ledger version. Otherwise, the await expression raises an exception.

Caution: Other APIs, including xrpl-py, may return tentative results from ledger versions that have not yet been validated. For example, if you use the rippled APIs' tx method, be sure to look for "validated": true in the response 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 generated = api.generateAddress()
console.log(generated.address) // Example: rGCkuB7PBr5tNy68tPEABEtcdno4hE6Y7f
console.log(generated.secret) // Example: sp6JS7f14BuwFY8Mw6bTtLKWauoUs

from xrpl.wallet import Wallet
my_wallet = Wallet.create()
print(my_wallet.classic_address) # Example: rGCkuB7PBr5tNy68tPEABEtcdno4hE6Y7f
print(my_wallet.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 potentially also be viable 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 the RippleAPI object, you must specify a server that's synced with the appropriate XRP Ledger. For many cases, you can use Ripple's public servers, such as in the following snippet:

ripple = require('ripple-lib')
api = new ripple.RippleAPI({server: 'wss://xrplcluster.com'})
api.connect()

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

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:

ripple = require('ripple-lib')
api = new ripple.RippleAPI({server: 'ws://localhost:6006'})
api.connect()

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

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: