XRPL-GO

xrpl-go is a Go SDK for interacting with the XRP Ledger. It provides address codecs, key management, binary serialization, typed transaction models, RPC and WebSocket clients, wallet helpers, local transaction signing, and multisigning.

Choose a module

The repository contains two independently versioned Go modules:

Module	Provides	Native toolchain
github.com/Peersyst/xrpl-go	Transaction and ledger models, codecs, clients, key management, and wallet signing	Not required
github.com/Peersyst/xrpl-go/confidential	Confidential MPT builders, encryption, balance decryption, commitments, and proofs	Required for cryptographic operations

Core includes the confidential transaction models and ledger fields. It can encode, sign, and submit these transactions when your application supplies the ciphertexts and proofs. Install the optional module when you want the SDK to generate those fields or decrypt balances.

The dependency goes from confidential to core only. Starting with core v0.3.1, core Go module downloads exclude the confidential module and its native bundles. Repository clones and GitHub source archives still contain both modules.

Reference documentation

See the xrpl-go documentation for guides and package docs, or browse the core Go API reference. The optional helpers have their own README, API reference, and changelog.

Installation

Both modules require Go 1.25.13 or later. Run installation commands from your application directory, which must contain a go.mod file. For a new application, run go mod init <your-module-path> first.

Core SDK

go get github.com/Peersyst/xrpl-go@latest

Core does not require cgo, including for wallet signing and confidential transaction serialization.

Optional confidential helpers

The first independent helper release is v0.1.0 and requires core v0.3.1 or later. Once both releases are published, install it with:

go get github.com/Peersyst/xrpl-go/confidential@v0.1.0

Go also selects the required core dependency. Package imports remain unchanged, such as github.com/Peersyst/xrpl-go/confidential/builder. After adding imports, run go mod tidy.

Native operations require cgo and a C/C++ toolchain on Linux or macOS with amd64 or arm64. Linux also needs the zlib development library. Unsupported targets and builds with CGO_ENABLED=0 compile, but native operations return mptcrypto.ErrCgoRequired.

See confidential installation and migration for details. Before the release tags are available, use the development workspace.

Quickstart

This example creates and funds a Testnet wallet, builds a payment, autofills the network fields, signs it locally, and submits it to a validated ledger.

package main

import (
	"fmt"
	"log"
	"strconv"

	"github.com/Peersyst/xrpl-go/pkg/crypto"
	"github.com/Peersyst/xrpl-go/xrpl/currency"
	"github.com/Peersyst/xrpl-go/xrpl/faucet"
	"github.com/Peersyst/xrpl-go/xrpl/rpc"
	"github.com/Peersyst/xrpl-go/xrpl/transaction"
	"github.com/Peersyst/xrpl-go/xrpl/transaction/types"
	"github.com/Peersyst/xrpl-go/xrpl/wallet"
)

func main() {
	cfg, err := rpc.NewClientConfig(
		"https://s.altnet.rippletest.net:51234/",
		rpc.WithFaucetProvider(faucet.NewTestnetFaucetProvider()),
	)
	if err != nil {
		log.Fatal(err)
	}
	client := rpc.NewClient(cfg)

	sender, err := wallet.New(crypto.ED25519())
	if err != nil {
		log.Fatal(err)
	}

	if err := client.FundWallet(&sender); err != nil {
		log.Fatal(err)
	}

	drops, err := currency.XrpToDrops("1")
	if err != nil {
		log.Fatal(err)
	}
	amount, err := strconv.ParseUint(drops, 10, 64)
	if err != nil {
		log.Fatal(err)
	}

	payment := transaction.Payment{
		BaseTx: transaction.BaseTx{
			Account: sender.ClassicAddress,
		},
		Destination: types.Address("rPT1Sjq2YGrBMTttX4GZHjKu9dyfzbpAYe"),
		Amount:      types.XRPCurrencyAmount(amount),
		DeliverMax:  types.XRPCurrencyAmount(amount),
	}

	flatTx := payment.Flatten()
	if err := client.Autofill(&flatTx); err != nil {
		log.Fatal(err)
	}

	txBlob, txHash, err := sender.Sign(flatTx)
	if err != nil {
		log.Fatal(err)
	}

	res, err := client.SubmitTxBlobAndWait(txBlob, false)
	if err != nil {
		log.Fatal(err)
	}

	fmt.Printf("submitted hash: %s\n", txHash)
	fmt.Printf("validated: %t, ledger: %d\n", res.Validated, res.LedgerIndex)
}

Never print, log, commit, or send real seeds, private keys, or mnemonics to telemetry. Anyone with those values can control the account.

Transaction lifecycle

The usual write path is:

1. Build a typed transaction, such as transaction.Payment.
2. Call Flatten() to get a transaction.FlatTransaction.
3. Call client.Autofill() to add network fields like Fee, Sequence, and LastLedgerSequence.
4. Sign locally with wallet.Sign().
5. Submit with client.SubmitTxBlobAndWait(), or use client.SubmitTxAndWait() to autofill, sign, submit, and wait in one call.

A transaction is a command you submit. Ledger entries are durable state you query after validation. The validated transaction response includes metadata that explains which ledger entries were created, modified, or deleted.

For offline signing, keep the Autofill() and Sign() boundary explicit: autofill needs network access, signing only needs the transaction data and wallet credentials.

See examples/send-xrp/rpc for a longer payment example.

Core packages

Package	Use it for
address-codec	Encode and decode XRPL classic addresses and X-addresses
binary-codec	Encode and decode XRPL objects and transactions in canonical binary format
keypairs	Generate seeds, derive keypairs, sign payloads, and verify signatures
xrpl/rpc	Send JSON-RPC requests, autofill transactions, submit transactions, and fund Testnet or Devnet wallets
xrpl/websocket	Connect to WebSocket servers, make requests, submit transactions, and subscribe to ledger streams
xrpl/transaction	Build typed XRPL transaction models
xrpl/ledger-entry-types	Read typed ledger state
xrpl/wallet	Create wallets, derive wallets from seeds or mnemonics, sign transactions, multisign transactions, and authorize payment channels

Guides and resources

• Create wallets and sign transactions
• Use the RPC client
• Use the WebSocket client
• Build transactions
• Build confidential MPT transactions
• Core examples and confidential examples
• Core changelog and confidential changelog
• Learn XRPL concepts and protocol rules

Security and audits

The signing functionality in this repository has not been independently audited. Treat local signing as security-sensitive code: protect wallet secrets, test on Testnet or Devnet first, and review signing behavior before using it to control production funds.

Contributing

Development setup, test commands, docs-site commands, and pull request guidance are in CONTRIBUTING.md.

Root go test ./... only tests core. To develop both modules together, run these commands from the repository root after installing the native toolchain:

make workspace
make test-ci
make test-confidential
make test-confidential-nocgo

The ignored go.work file links the two local checkouts, including before core v0.3.1 is published. Confidential examples and integration tests live in confidential/examples/ and confidential/integration/.

Each module has its own changelog and release tag: vX.Y.Z for core and confidential/vX.Y.Z for the optional helpers. Core updates do not automatically update confidential. See RELEASING.md for independent releases and the release picker.

Report an issue

If you find a bug or documentation gap, please open an issue in the XRPL-GO GitHub repository.

License

The xrpl-go library is licensed under the MIT License.