Get Started Using Go Library

This tutorial walks you through the basics of building an XRP Ledger-connected application using xrpl-go, a pure Go library built to interact with the XRP Ledger.

This tutorial is intended for beginners and should take no longer than 30 minutes to complete.

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-go.
• How to get an account on the Testnet using xrpl-go.
• How to use the xrpl-go library to look up information about an account on the XRP Ledger.

Requirements

To follow this tutorial, you should have Go version 1.22.0 or later installed. Download latest Go version.

Installation

The xrpl-go library is available on pkg.go.dev.

Start a new project (or use an existing one) and install the xrpl-go library via Go modules:

# Initialize your module (if you haven't already)
go mod init your-module-name

# Fetch the latest version of xrpl-go
go get -u github.com/Peersyst/xrpl-go

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 the basic steps you'll need to cover for almost any XRP Ledger project:

1. Connect to the XRP Ledger.
2. Get an account.
3. Query the XRP Ledger.

1. Connect to the XRP Ledger

To make queries and submit transactions, you need to connect to the XRP Ledger. To do this with xrpl-go, you have two main options:

1. Via WebSocket:

   func main() {
   
       // Define the network client
   	client := websocket.NewClient(websocket.NewClientConfig().
   		WithHost("wss://s.altnet.rippletest.net:51233").
   		WithFaucetProvider(faucet.NewTestnetFaucetProvider()),
   	)
   
       // Disconnect the client when done. (Defer executes at the end of the function)
       defer client.Disconnect()
   
       // Connect to the network
       if err := client.Connect(); err != nil {
           panic(err)
       }
   
       // ... custom code goes here
   }

2. Via RPC:

   func main() {
       // Define the network client configuration
       cfg, err := rpc.NewClientConfig(
           "https://s.altnet.rippletest.net:51234/",
           rpc.WithFaucetProvider(faucet.NewTestnetFaucetProvider()),
       )
       if err != nil {
           panic(err)
       }
   
       // Initiate the network client
       client := rpc.NewClient(cfg)
   
       // Ping the network (used to avoid Go unused variable error, but useful to check connectivity)
       _, err = client.Ping(&utility.PingRequest{})
       if err != nil {
           panic(err)
       }
   
       // ... custom code goes here
   
   }

Connect to the production XRP Ledger

The sample code in the previous section shows you how to connect to the Testnet, which is a parallel network for testing where the money has no real value. When you're ready to integrate with the production XRP Ledger, you'll need to connect to the 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:

  import "github.com/Peersyst/xrpl-go/xrpl/websocket"
  
  const MY_SERVER = "ws://localhost:6006/"
  
  func main() {
    client := websocket.NewClient(websocket.NewClientConfig().WithHost(MY_SERVER))
  
    // ... custom code goes here
  }

  See the example core server config file for more information about default values.

• By using one of the available public servers:

  import "github.com/Peersyst/xrpl-go/xrpl/websocket"
  
  const PUBLIC_SERVER = "wss://xrplcluster.com/"
  
  func main() {
    client := websocket.NewClient(websocket.NewClientConfig().WithHost(PUBLIC_SERVER))
  
    // ... custom code goes here
  }

2. Get account

In xrpl-go, account creation and key management live in the wallet package, and on Testnet you can use the built-in faucet provider on your WebSocket (or RPC) client to fund a brand-new account immediately.

On Testnet, you can fund a new ED25519 account like this:

w, err := wallet.New(crypto.ED25519())
if err != nil {
	fmt.Println(err)
	return
}
if err := client.FundWallet(&w); err != nil {
	fmt.Println(err)
	return
}

This constructor returns a Go Wallet value with the following fields:

type Wallet struct {
    PublicKey      string          // the hex-encoded public key
    PrivateKey     string          // the hex-encoded private key
    ClassicAddress types.Address   // the XRPL “r…” address
    Seed           string          // the base58 seed
}

If you already have a seed encoded in base58, you can make a Wallet instance from it like this:

  w, err := wallet.FromSeed("sn3nxiW7v8KXzPzAqzyHXbSSKNuN9", "")

3. Query the XRP Ledger

You can query the XRP Ledger to get information about a specific account, a specific transaction, the state of a current or a historical ledger, and the XRP Ledger's decentralized exchange. You need to make these queries, among other reasons, to look up account info to follow best practices for reliable transaction submission.

Use the Client's Request() method to access the XRP Ledger's WebSocket API. For example:

    // Get the latest validated ledger
    led, err := client.GetLedger(&ledger.Request{
        Transactions: true,
        LedgerIndex:  common.Validated,
    })
    if err != nil {
        panic(err)
    }
    fmt.Println("Latest validated ledger:", led)

    // Get the first transaction hash from the ledger
    if len(led.Ledger.Transactions) > 0 {
        txHash := led.Ledger.Transactions[0].(string) // type assertion may be needed

        // Query the transaction details
        txResp, err := client.Request(&transactions.TxRequest{
            Transaction: txHash,
        })
        if err != nil {
            panic(err)
        }
        fmt.Println("First transaction in the ledger:")
        fmt.Println(txResp)
    }
}

Or, use the getter methods from the websocket or rpc packages:

    // Get info from the ledger about the address we just funded
    acc_info, err := client.GetAccountInfo(&account.InfoRequest{
        Account: w.GetAddress(),
    })
    if err != nil {
        panic(err)
    }
    fmt.Println("Account Balance:", acc_info.AccountData.Balance)
    fmt.Println("Account Sequence:", acc_info.AccountData.Sequence)

    

Keep on Building

Now that you know how to use xrpl-go to connect to the XRP Ledger, get an account, and look up information about it, you can also:

• Send XRP.