xrpl-up

CLI for XRPL local development and scripting. Spin up a local sandbox with pre-funded accounts, run scripts, manage snapshots, and interact with remote testnet/devnet endpoints from one tool.

Prerequisites

Node.js v20 or later
Docker (required for --local mode only)

Installation

~~From npm (global):~~

~~npm install -g xrpl-up~~

Not available yet: package has not been published to npm.

From source (development):

git clone https://github.com/ripple/xrpl-up.git
cd xrpl-up
npm install
npm run build
npm link

Quick Start

# Scaffold a new project (select "local" as default network)
xrpl-up init my-project
cd my-project && npm install

# Start a local sandbox with 10 pre-funded accounts (local is the default)
xrpl-up start

# In another terminal — list accounts with live balances
xrpl-up accounts

# Run a script against the local sandbox
xrpl-up run scripts/example-payment.ts

# Create an AMM pool in one command (local by default)
xrpl-up amm create XRP USD

# Mint a transferable NFT
xrpl-up nft mint --uri https://example.com/meta.json --transferable

# Create an MPT issuance (Multi-Purpose Token)
xrpl-up mptoken issuance create --node local --max-amount 1000000 --asset-scale 6

# Open a payment channel
xrpl-up channel create rDestination... 10

Commands

xrpl-up has two command sets:

Sandbox operation commands: environment lifecycle and state control (start, stop, reset, snapshot, status, accounts, logs, config, run, init, faucet, amendment).
XRPL interaction commands: transaction submission and account management (wallet, account, payment, trust, offer, amm, nft, mptoken, escrow, check, channel, ticket, clawback, credential, did, multisig, oracle, deposit-preauth, permissioned-domain, vault).

XRPL interaction commands are intentionally non-exhaustive. For complex or production-grade flows, use xrpl.js directly or call rippled RPC endpoints.

Global flag: `--node`

All XRPL interaction commands accept a global --node option that sets the network target:

Value	Connects to
`testnet` (default)	XRPL Testnet
`devnet`	XRPL Devnet (may include pre-release amendments not yet supported by this tool)
`local`	Local sandbox (`ws://localhost:6006`)
`wss://...`	Any custom WebSocket URL

# Use local sandbox (start first with: xrpl-up start)
xrpl-up account info rMyAddress --node local

# Use testnet (default — no --node needed)
xrpl-up account info rMyAddress

# Use a custom WebSocket URL
xrpl-up account info rMyAddress --node ws://my-node:6006

# Set via environment variable
export XRPL_NODE=local
xrpl-up payment --to rDest --amount 10

--node only applies to XRPL interaction commands; sandbox lifecycle commands (start, stop, reset, etc.) use --local / --local-network for the local sandbox and --network for remote networks.

`xrpl-up start`

Starts a sandbox environment and funds accounts. Supports a fully local rippled node (via Docker) or a connection to XRPL Testnet/Devnet.

Two local modes are available:

Mode	Command	Ledger close	State	Best for
Standalone (default)	`xrpl-up start`	Instant	Ephemeral	CI, quick tests, scripting
Local network	`xrpl-up start --local-network`	~4s (consensus)	Persistent	Long dev sessions, snapshots

Standalone is a single rippled node with instant ledger closes. State is wiped on each start. Use this for CI pipelines, quick sanity checks, and any workflow where you don't need state to survive restarts.

Local network (--local-network) runs a 2-node private consensus network. Ledgers close via real consensus (~4s), state persists across stop/start, and snapshots are supported. Use this when you're building an app over hours or days against a stable environment — set up AMM pools, trust lines, and funded accounts once, snapshot the state, and roll back when you need to.

# Quick sandbox — fast, ephemeral (CI, scripting, sanity tests)
xrpl-up start

# Persistent local network — real consensus, snapshots, survives restarts
xrpl-up start --local-network

# Connect to Testnet instead
xrpl-up start --network testnet

# Connect to Devnet instead
xrpl-up start --network devnet

Local mode options:

Flag	Default	Description
`--local`	—	Run a local rippled node via Docker
`--local-network`	off	Start a 2-node consensus network (persistent state, snapshot support)
`--image <image>`	`xrpllabsofficial/xrpld:latest`	rippled Docker image
`--ledger-interval <ms>`	`1000`	Auto-advance ledger every N milliseconds (standalone only)
`--no-auto-advance`	—	Disable automatic ledger closing
`--no-secrets`	—	Suppress seeds and private keys from stdout (auto-enabled with `--detach`)
`--debug`	—	Enable rippled debug logging
`--detach`	—	Start in background and exit (for CI/CD)
`--config <path>`	—	Use a custom `rippled.cfg` instead of the auto-generated one
`--exit-on-crash`	—	Exit with code 134 when rippled crashes (SIGABRT); disables container auto-restart
`-a, --accounts <n>`	`10`	Number of accounts to pre-fund

Note: The local sandbox is a clean-room environment — ledger starts at index 1 with only the genesis wallet. It is not a mirror of the public ledger. What matters is that transaction validation rules match the rippled version in use.

AMM / XLS-30 and MPT / XLS-33: Both AMM and MPT (Multi-Purpose Token) are enabled by default in the local sandbox. xrpl-up uses the [amendments] section in rippled.cfg to force-enable the required amendments at genesis creation. No voting or ledger advancement is needed.

Hardware: A typical developer laptop is sufficient (~2 GB RAM, ~500 MB disk for the Docker image). The local sandbox has no internet requirement and only processes transactions you submit locally.

`xrpl-up stop`

Stops the local Docker sandbox stack.

xrpl-up stop

`xrpl-up reset`

Wipes all local sandbox state and starts with a clean slate. Useful after a --local-network session or when you want to discard all ledger state and funded accounts.

# Wipe containers, ledger volume, and accounts — keep snapshots
xrpl-up reset

# Wipe everything including saved snapshots
xrpl-up reset --snapshots

What xrpl-up reset removes:

Running Docker containers (docker compose down)
Ledger volumes (xrpl-up-local-db and xrpl-up-local-peer-db in consensus mode)
~/.xrpl-up/local-accounts.json
With --snapshots: ~/.xrpl-up/snapshots/ and all snapshot files

Snapshots are kept by default since they are the only way to recover a previous state. Use --snapshots only when you want a complete wipe.

`xrpl-up accounts`

Lists funded accounts with their live XRP balances.

xrpl-up accounts                          # local (default)
xrpl-up accounts --network testnet

# Query any address directly
xrpl-up accounts --address rSomeAddress...

`xrpl-up faucet`

Funds a new or existing account via the local sandbox faucet or a public testnet/devnet faucet. Funded accounts are automatically saved to ~/.xrpl-up/{network}-accounts.json so they appear in xrpl-up accounts.

# Generate and fund a new wallet on the local sandbox (default)
xrpl-up faucet

# Fund an existing wallet by seed on the local sandbox
xrpl-up faucet --seed sn3nxiW7v8KXzPzAqzyHXbSSKNuN9

# Use the public Testnet faucet
xrpl-up faucet --network testnet

Faucet targets supported by this command: local (default), testnet, devnet.

`xrpl-up status`

Shows rippled server info and faucet health.

xrpl-up status                     # local (default)
xrpl-up status --network testnet

Displays rippled version, current ledger index, and faucet availability.

`xrpl-up run <script>`

Runs a TypeScript or JavaScript script with the network URL injected as environment variables. TypeScript is executed directly via tsx (no build step needed).

xrpl-up run scripts/example-payment.ts --network local
xrpl-up run scripts/my-script.js --network testnet

Injected environment variables:

Variable	Description
`XRPL_NETWORK`	Network key (e.g. `local`, `testnet`)
`XRPL_NETWORK_URL`	WebSocket URL (e.g. `ws://localhost:6006`)
`XRPL_NETWORK_NAME`	Human-readable name

Example script:

// scripts/send-payment.ts
import { Client, xrpToDrops, Wallet } from 'xrpl';

async function main() {
  const client = new Client(process.env.XRPL_NETWORK_URL!);
  await client.connect();

  const sender = Wallet.fromSeed('sn3nxiW7v8KXzPzAqzyHXbSSKNuN9'); // from xrpl-up accounts

  await client.submitAndWait(
    {
      TransactionType: 'Payment',
      Account: sender.address,
      Amount: xrpToDrops('10'),
      Destination: 'rDestinationAddress...',
    },
    { wallet: sender }
  );

  console.log('Payment sent!');
  await client.disconnect();
}

main().catch(console.error);

`xrpl-up logs`

Streams Docker Compose logs from the running local sandbox.

xrpl-up logs           # all services
xrpl-up logs rippled   # rippled only (useful with --debug)
xrpl-up logs faucet    # faucet server only

`xrpl-up amm`

Manage AMM pools (XLS-30). AMM is enabled by default in the local sandbox — no extra configuration needed.

`xrpl-up amm create <asset1> <asset2>`

Creates a ready-to-use AMM pool with fresh funded accounts. Automatically handles issuer creation, trust lines, token issuance, and pool creation.

# XRP/USD pool with defaults (100 XRP, 100 USD, 0.5% fee)
xrpl-up amm create XRP USD

# Custom amounts and fee
xrpl-up amm create XRP USD --amount1 500 --amount2 1000 --fee 0.3

# IOU/IOU pool (creates two separate issuers)
xrpl-up amm create USD EUR --amount1 100 --amount2 100

# On testnet
xrpl-up amm create XRP USD -n testnet

Flag	Default	Description
`--amount1 <n>`	`100`	Amount of asset1 to deposit
`--amount2 <n>`	`100`	Amount of asset2 to deposit
`--fee <pct>`	`0.5`	Trading fee in % (max 1%)

The command prints the exact amm info query to use afterward, with the issuer address filled in.

Note: For non-XRP assets, amm create mints a fresh token on your local ledger. The issuer address is randomly generated — it has no relation to any real-world or testnet issuer.

`xrpl-up amm info <asset1> <asset2>`

Shows current pool state: reserves, LP token supply, trading fee, and AMM account.

# Query by asset pair (use the issuer address printed by amm create)
xrpl-up amm info XRP USD.rIssuerAddress

# Query by AMM account address
xrpl-up amm info --account rAMMAccountAddress

# Query on testnet
xrpl-up amm info XRP USD.rHb9... -n testnet

Asset format: XRP for native currency, CURRENCY.rIssuerAddress for IOUs (e.g. USD.rHb9CJ...).

`xrpl-up nft`

NFT lifecycle operations (XLS-20). Supports mint, list, buy/sell offers, and burn on local sandbox or remote networks.

`xrpl-up nft mint`

Mints a new NFT. When --seed is omitted a wallet is auto-funded — via the local genesis faucet by default, or the public testnet/devnet faucet on remote networks.

# Mint a transferable NFT with a metadata URI (local by default, auto-funds wallet)
xrpl-up nft mint --uri https://example.com/nft-meta.json --transferable

# Mint on testnet
xrpl-up nft mint -n testnet --uri https://example.com/meta.json \
  --transferable --transfer-fee 5 --taxon 42

Flag	Default	Description
`--uri <uri>`	—	Metadata URI (hex-encoded automatically)
`--transferable`	off	Allow the NFT to be transferred (`tfTransferable`)
`--burnable`	off	Allow the issuer to burn it (`tfBurnable`)
`--taxon <n>`	`0`	NFToken taxon
`--transfer-fee <pct>`	`0`	Royalty fee percentage, 0–50
`-s, --seed <seed>`	—	Minter wallet seed (omit to auto-fund via faucet)

`xrpl-up nft list`

Lists NFTs owned by an account.

# List NFTs for the first local account
xrpl-up nft list

# List NFTs for a specific address
xrpl-up nft list --account rSomeAddress...

`xrpl-up nft offers <nftokenId>`

Shows all open buy and sell offers for an NFT.

xrpl-up nft offers 000800006B9C0B...

`xrpl-up nft sell <nftokenId> <price>`

Creates a sell offer for an NFT. Price is "1" for 1 XRP or "10.USD.rIssuer" for an IOU amount.

# Sell for 5 XRP
xrpl-up nft sell 000800006B9C0B... 5 --seed sn3nxiW7...

# Sell for 10 USD (IOU)
xrpl-up nft sell 000800006B9C0B... 10.USD.rHb9CJA... --seed sn3nxiW7...

`xrpl-up nft accept <offerId>`

Accepts a sell offer (or a buy offer with --buy). On local a buyer wallet is auto-funded if --seed is omitted.

xrpl-up nft accept A1B2C3D4...

# Accept with an explicit buyer seed
xrpl-up nft accept A1B2C3D4... --seed sBuyerSeed...

# Accept a buy offer
xrpl-up nft accept A1B2C3D4... --seed sHolderSeed... --buy

`xrpl-up nft burn <nftokenId>`

Permanently destroys an NFT.

xrpl-up nft burn 000800006B9C0B... --seed sHolderSeed...

`xrpl-up channel`

Payment channel operations. Payment channels allow fast, off-chain micropayments with on-chain settlement.

`xrpl-up channel create <destination> <amount>`

Opens a payment channel funded with <amount> XRP. The source wallet is auto-funded if --seed is omitted (local only).

# Create a 10 XRP channel to a destination (local by default, auto-funds source)
xrpl-up channel create rDestination... 10

# Create with a custom settle delay (1 hour)
xrpl-up channel create rDestination... 10 --seed sSourceSeed... --settle-delay 3600

Flag	Default	Description
`--settle-delay <s>`	`86400`	Settlement delay in seconds (default: 1 day)
`-s, --seed <seed>`	—	Source wallet seed (omit to auto-fund on local)

`xrpl-up channel list`

Lists payment channels for an account.

xrpl-up channel list
xrpl-up channel list --account rSomeAddress...

`xrpl-up channel fund <channelId> <amount>`

Adds more XRP to an existing channel.

xrpl-up channel fund ABC123... 5 --seed sSourceSeed...

`xrpl-up channel sign <channelId> <amount>`

Signs an off-chain claim authorizing the destination to claim up to <amount> XRP. No on-chain transaction — prints the signature, the signer's public key, and ready-to-use verify and claim commands.

xrpl-up channel sign ABC123... 3 --seed sSourceSeed...

The output includes the --public-key value needed for channel claim. Pass the signature and public key to the destination out-of-band; the destination then runs the printed claim command.

`xrpl-up channel verify <channelId> <amount> <signature> <publicKey>`

Verifies an off-chain claim signature. Exits with code 1 if invalid.

xrpl-up channel verify ABC123... 3 <hex-signature> <public-key>

`xrpl-up channel claim <channelId>`

Submits a PaymentChannelClaim on-chain. Optionally redeems an off-chain claim or closes the channel.

# Close the channel (no claim amount)
xrpl-up channel claim ABC123... --seed sDestSeed... --close

# Redeem an off-chain claim
# --public-key is the source wallet's public key (printed by channel sign)
xrpl-up channel claim ABC123... --seed sDestSeed... \
  --amount 3 --signature <hex-sig> --public-key <source-public-key>

`xrpl-up mptoken`

Multi-Purpose Token (MPT / XLS-33) operations. MPT is enabled automatically in the local sandbox. Use --node local to target the local sandbox, or --node testnet for Testnet.

`xrpl-up mptoken issuance create`

Creates a new MPT issuance.

# Local sandbox
xrpl-up mptoken issuance create --node local --seed sIssuerSeed... \
  --max-amount 1000000 --asset-scale 6 --transfer-fee 100 --metadata "My Token"

# Minimal (no supply cap, non-transferable by default)
xrpl-up mptoken issuance create --node local --seed sIssuerSeed...

Flag	Default	Description
`--max-amount <n>`	unlimited	Maximum token supply
`--asset-scale <n>`	`0`	Decimal places, 0–19
`--transfer-fee <n>`	`0`	Fee in hundredths of a percent, 0–50000
`--metadata <string>`	—	Metadata string (hex-encoded on-chain)
`--seed / --mnemonic / --account`	—	Key material

`xrpl-up mptoken issuance destroy <issuanceId>`

Destroys an MPT issuance. Outstanding supply must be zero.

xrpl-up mptoken issuance destroy 00070C44... --node local --seed sIssuerSeed...

`xrpl-up mptoken authorize <issuanceId>`

Authorizes (or unauthorizes) a holder to hold the token.

# Issuer side: authorize a holder
xrpl-up mptoken authorize 00070C44... --holder rHolderAddress... \
  --node local --seed sIssuerSeed...

# Holder side: opt in (no --holder flag)
xrpl-up mptoken authorize 00070C44... --node local --seed sHolderSeed...

# Revoke authorization
xrpl-up mptoken authorize 00070C44... --holder rHolderAddress... --unauthorize \
  --node local --seed sIssuerSeed...

`xrpl-up mptoken issuance set <issuanceId>`

Locks or unlocks an MPT issuance or a specific holder's balance. Requires the issuance to have been created with --can-lock.

xrpl-up mptoken issuance set 00070C44... --lock --node local --seed sIssuerSeed...
xrpl-up mptoken issuance set 00070C44... --lock --holder rAddr... --node local --seed sIssuerSeed...
xrpl-up mptoken issuance set 00070C44... --unlock --node local --seed sIssuerSeed...

`xrpl-up mptoken issuance get <issuanceId>`

Shows on-ledger details of an MPT issuance: issuer, outstanding supply, flags, and metadata.

xrpl-up mptoken issuance get 00070C4495F14B0E... --node local

`xrpl-up mptoken issuance list <address>`

Lists MPT issuances created by an account.

xrpl-up mptoken issuance list rMyAddress... --node local

Sending MPT payments

Use the payment command with an MPT amount format <amount>/<issuanceId>:

xrpl-up payment --to rDestAddress --amount "500/00070C44..." \
  --node local --seed sHolderSeed...

For querying MPT balances held by an account, use xrpl-up account mptokens.

`xrpl-up offer`

DEX (decentralized exchange) offer operations. The XRPL DEX is a built-in order book — no smart contracts needed.

`xrpl-up offer create <pays> <gets>`

Creates a limit order. <pays> is what you put in; <gets> is what you want out. When --seed is omitted a wallet is auto-funded via faucet.

Asset format: "5" = 5 XRP, "10.USD.rIssuer" = IOU (same as AMM). Decimal values like "10.5.USD.rIssuer" are supported.

# Offer 10 USD for 5 XRP (local by default, auto-funds wallet)
xrpl-up offer create "10.USD.rHb9..." "5"

# Offer 5 XRP for 10 USD on testnet
xrpl-up offer create "5" "10.USD.rHb9..." -n testnet --seed sn3nxiW7...

# Immediate-or-cancel sell offer
xrpl-up offer create "5" "10.USD.rHb9..." --sell --immediate-or-cancel --seed sn3nxiW7...

Flag	Description
`--passive`	Do not consume matching offers at equal price
`--sell`	Sell exactly `TakerPays` regardless of `TakerGets` minimum
`--immediate-or-cancel`	Fill what is possible immediately, cancel the rest
`--fill-or-kill`	Fill the full amount or cancel entirely

`xrpl-up offer cancel <sequence>`

Cancels an open offer by its sequence number (printed by offer create).

xrpl-up offer cancel 42 --seed sn3nxiW7...

`xrpl-up offer list`

Lists all open DEX offers for an account.

xrpl-up offer list
xrpl-up offer list --account rSomeAddress...

`xrpl-up trust`

Trust line operations (renamed from trustline). Use xrpl-up account trust-lines to query existing trust lines.

`xrpl-up trust set`

Creates or updates a trust line.

# Set a USD trust line with a 1000 limit (local sandbox)
xrpl-up trust set --currency USD --issuer rHb9CJAWyB4rj91VRWn96DkukG4bwdtyTh \
  --limit 1000 --node local --seed sn3nxiW7...

# With NoRipple flag
xrpl-up trust set --currency USD --issuer rHb9... --limit 1000 \
  --no-ripple --node local --seed sn3nxiW7...

# Freeze a trust line (issuer only)
xrpl-up trust set --currency USD --issuer rHolderAddress... \
  --limit 0 --freeze --node local --seed sIssuerSeed...

# Unfreeze
xrpl-up trust set --currency USD --issuer rHolderAddress... \
  --limit 0 --unfreeze --node local --seed sIssuerSeed...

Flag	Description
`--currency <code>`	Currency code (3-char ASCII or 40-char hex)
`--issuer <address>`	Issuer address
`--limit <value>`	Trust line limit (0 removes the trust line)
`--no-ripple`	Set NoRipple flag
`--clear-no-ripple`	Clear NoRipple flag
`--freeze`	Freeze the trust line (issuer only)
`--unfreeze`	Unfreeze the trust line
`--auth`	Authorize the trust line

Query trust lines

xrpl-up account trust-lines rMyAddress... --node local

To enable DefaultRipple (rippling on all new trust lines), use xrpl-up account set defaultRipple.

`xrpl-up escrow`

Escrow operations. Escrows lock XRP until a time condition or crypto-condition is met.

`xrpl-up escrow create <destination> <amount>`

Creates an escrow. At least one of --finish-after, --cancel-after, or --condition is required. When --seed is omitted a wallet is auto-funded.

Time expressions: +30m, +1h, +1d, +7d (relative from now), or an absolute Unix timestamp.

# Time-locked: can finish after 1 hour, auto-cancels after 7 days
xrpl-up escrow create rDest... 10 \
  --finish-after +1h --cancel-after +7d

# Crypto-condition escrow
xrpl-up escrow create rDest... 10 \
  --condition A0258020... --cancel-after +7d --seed sn3nxiW7...

`xrpl-up escrow finish <owner> <sequence>`

Releases the escrowed funds to the destination after the FinishAfter time has passed. For crypto-condition escrows, --fulfillment and --condition are required.

# Time-based finish
xrpl-up escrow finish rOwner... 42 --seed sDestSeed...

# Crypto-condition finish
xrpl-up escrow finish rOwner... 42 --seed sDestSeed... \
  --fulfillment A0228020... --condition A0258020...

`xrpl-up escrow cancel <owner> <sequence>`

Cancels an expired escrow (after CancelAfter time) and returns XRP to the owner.

xrpl-up escrow cancel rOwner... 42 --seed sn3nxiW7...

`xrpl-up escrow list`

Lists escrows for an account, showing amounts, times, and conditions.

xrpl-up escrow list
xrpl-up escrow list --account rSomeAddress...

`xrpl-up check`

Check operations. Checks are a deferred payment mechanism — the sender authorizes a maximum amount that the destination can cash at any time before expiry.

`xrpl-up check create <destination> <sendMax>`

Creates a check. <sendMax> is the maximum the destination can receive.

# Create a 5 XRP check (valid for 7 days)
xrpl-up check create rDest... 5 --seed sn3nxiW7... --expiry +7d

# Create an IOU check
xrpl-up check create rDest... "10.USD.rHb9..." --seed sn3nxiW7...

`xrpl-up check cash <checkId> [amount]`

Cashes a check. Provide an exact [amount] or --deliver-min for a flexible minimum (the destination receives as much as possible up to SendMax).

# Cash exactly 5 XRP
xrpl-up check cash ABC123... 5 --seed sDestSeed...

# Cash flexibly — receive at least 3 XRP
xrpl-up check cash ABC123... --deliver-min 3 --seed sDestSeed...

`xrpl-up check cancel <checkId>`

Cancels a check (sender or destination can cancel; anyone can cancel after expiry).

xrpl-up check cancel ABC123... --seed sn3nxiW7...

`xrpl-up check list`

Lists outstanding checks for an account.

xrpl-up check list
xrpl-up check list --account rSomeAddress...

`xrpl-up account set`

Enable or disable account flags (replaces the old accountset command).

xrpl-up account set requireDest --node local --seed sn3nxiW7...
xrpl-up account set requireDest --clear --node local --seed sn3nxiW7...

Flag name	Description
`requireDest`	Require a destination tag on all incoming payments
`requireAuth`	Require the issuer to authorize all trust lines
`disallowXRP`	Signal that this account does not accept direct XRP payments
`disableMaster`	Disable the master key (use only after setting a signer list)
`defaultRipple`	Enable rippling on all new trust lines (issuers)
`depositAuth`	Only accept payments from pre-authorized senders
`allowClawback`	Allow the issuer to clawback IOU tokens from trust line holders (irreversible)

Note: Set a signer list before disabling the master key (disableMaster). For signer list management, use xrpl-up multisig. To query account settings, use xrpl-up account info.

Transaction history

The tx command has been removed. Use xrpl-up account transactions:

xrpl-up account transactions rMyAddress... --node local
xrpl-up account transactions rMyAddress... --node testnet

`xrpl-up deposit-preauth`

Manage DepositPreauth entries (renamed from depositpreauth). Required when an account has the depositAuth flag set.

# Enable deposit authorization on your account first
xrpl-up account set depositAuth --node local --seed sn3nxiW7...

# Pre-authorize a specific sender
xrpl-up deposit-preauth set --authorize rSender... \
  --node local --seed sn3nxiW7...

# Revoke a pre-authorization
xrpl-up deposit-preauth set --unauthorize rSender... \
  --node local --seed sn3nxiW7...

# List all pre-authorizations
xrpl-up deposit-preauth list rMyAddress... --node local

`xrpl-up ticket`

Ticket operations. Tickets reserve sequence numbers, allowing transactions to be submitted out-of-order or in parallel — useful for multi-sig workflows.

`xrpl-up ticket create`

Reserves 1–250 sequence numbers as tickets. Returns the allocated TicketSequence numbers.

`xrpl-up ticket list [account]`

Lists existing tickets (reserved sequence numbers) for an account.

# Reserve 5 ticket sequences
xrpl-up ticket create --count 5 --seed sn3nxiW7...

# Auto-fund a new wallet and reserve tickets (local only)
xrpl-up ticket create --count 3 --auto-fund

# List existing tickets
xrpl-up ticket list
xrpl-up ticket list rSomeAddress...

Usage: To use a ticket in a transaction, set Sequence = 0 and TicketSequence = <n>.

`xrpl-up clawback`

Issuer clawback operations. The issuer account must have clawback enabled before use.

Prerequisites:

IOU clawback: Enable asfAllowTrustLineClawback with xrpl-up account set allowClawback --node local --seed <issuer-seed>

MPT clawback: The issuance must have been created with xrpl-up mptoken issuance create --can-clawback

`xrpl-up clawback iou <amount> <currency> <holder>`

Reclaims IOU tokens from a trust line holder. The signing wallet must be the token issuer.

`xrpl-up clawback mpt <issuanceId> <holder> <amount>`

Reclaims MPT tokens from a holder. The signing wallet must be the MPT issuer.

# Clawback 10 USD from a holder trust line
xrpl-up clawback iou 10 USD rHolder... --seed sIssuerSeed...

# Clawback 500 units of an MPT
xrpl-up clawback mpt 00000001AABBCCDD... rHolder... 500 --seed sIssuerSeed...

`xrpl-up wallet`

Wallet management — create, import, and manage XRPL key pairs in a local keystore (~/.xrpl/keystore/ by default).

Subcommand	Description
`new`	Generate a new random wallet
`new-mnemonic`	Generate a wallet from a BIP39 mnemonic
`import`	Import a wallet by seed or mnemonic
`list`	List all wallets in the keystore
`address`	Print the address for a wallet
`private-key`	Print the private key (requires password)
`public-key`	Print the public key
`sign`	Sign arbitrary data
`verify`	Verify a signature
`alias`	Set or clear a human-readable alias for a wallet
`fund`	Fund a wallet from the testnet faucet
`change-password`	Change keystore encryption password
`decrypt-keystore`	Export keystore contents (decrypt to plaintext)
`remove`	Remove a wallet from the keystore

xrpl-up wallet new
xrpl-up wallet fund --account rMyAddress
xrpl-up wallet list

`xrpl-up account`

Account query and management. The account command provides both query subcommands and mutation subcommands.

Subcommand	Description
`info`	Account flags, sequence, balance, signer list
`balance`	XRP and IOU balances
`transactions`	Recent transaction history (replaces `tx list`)
`offers`	Open offers on the DEX
`trust-lines`	Trust lines (replaces `trustline list`)
`channels`	Open payment channels
`nfts`	NFTs owned by the account
`mptokens`	MPT balances held by the account
`set`	Enable/disable account flags (replaces `accountset set/clear`)
`set-regular-key`	Set or remove the regular key
`delete`	Delete the account

xrpl-up account info rMyAddress --node local
xrpl-up account transactions rMyAddress --node local
xrpl-up account trust-lines rMyAddress --node local
xrpl-up account balance rMyAddress --node testnet

`xrpl-up payment`

Send a Payment transaction. Alias: xrpl-up send.

# Send XRP
xrpl-up payment --to rDest... --amount 10 --node local --seed sSrc...

# Send IOU
xrpl-up payment --to rDest... --amount "10/USD/rIssuer..." \
  --node local --seed sSrc...

# Send MPT
xrpl-up payment --to rDest... --amount "500/00070C44..." \
  --node local --seed sSrc...

Flag	Description
`--to <address>`	Destination address or alias
`--amount <amount>`	Amount: `10` = XRP, `10/USD/rIssuer` = IOU, `500/<issuanceId>` = MPT
`--destination-tag <n>`	Destination tag
`--memo <text>`	Memo to attach (repeatable)
`--send-max <amount>`	SendMax for cross-currency payments
`--deliver-min <amount>`	Minimum delivery (enables partial payments)
`--partial`	Set tfPartialPayment flag
`--dry-run`	Print signed transaction without submitting

`xrpl-up multisig`

Multi-signature signer list management (replaces accountset signer-list).

xrpl-up multisig --help

`xrpl-up credential`

Manage DID-based credentials on the XRP Ledger.

xrpl-up credential --help

`xrpl-up did`

Manage Decentralized Identifiers (DID) on the XRP Ledger.

xrpl-up did --help

`xrpl-up oracle`

Price oracle management on the XRP Ledger.

xrpl-up oracle --help

`xrpl-up permissioned-domain`

Manage Permissioned Domains on the XRP Ledger (XLS-80d).

xrpl-up permissioned-domain --help

`xrpl-up vault`

Manage vaults on the XRP Ledger.

xrpl-up vault --help

`xrpl-up amendment`

Inspect and manage XRPL amendments in the local sandbox. The local sandbox starts with a set of amendments baked into its genesis config; use enable to queue additional amendments (takes effect after xrpl-up reset && xrpl-up start).

Devnet compatibility: XRPL Devnet may enable pre-release amendments that are not yet supported by the rippled version bundled with this tool. If you encounter unsupported transaction types or behaviors on devnet, check whether the amendment is available in the local sandbox with xrpl-up amendment list --local --diff devnet.

Local only for mutations: enable writes to the genesis config and only applies to the local sandbox. list and info work on any network.

`xrpl-up amendment list`

Lists all amendments known to the target node with their enabled/supported status.

# List amendments on the local sandbox
xrpl-up amendment list --local

# List disabled amendments only
xrpl-up amendment list --local --disabled

# Side-by-side diff: local vs testnet
xrpl-up amendment list --local --diff testnet

# List amendments on testnet
xrpl-up amendment list --network testnet

`xrpl-up amendment info <nameOrHash>`

Shows full details for a single amendment. Accepts the amendment name or a hash prefix.

xrpl-up amendment info PermissionedDomains --local
xrpl-up amendment info AMM --network testnet
xrpl-up amendment info A730EB18 --local   # hash prefix lookup

`xrpl-up amendment enable <nameOrHash>`

Queues an amendment for activation in the local sandbox genesis config. Because the local node runs in standalone mode (no consensus), amendments cannot be activated via validator voting — they must be present in the genesis config from the very first ledger. The command writes the amendment hash to ~/.xrpl-up/genesis-amendments.txt, regenerates rippled.cfg, then prompts you to reset and restart.

xrpl-up amendment enable PermissionedDomains --local
# ⚠  Activating this amendment requires a full node reset.
#    All ledger data, funded accounts, and snapshots will be wiped.
#  Reset and restart the local node now? [y/N]

# Skip the prompt and reset automatically:
xrpl-up amendment enable PermissionedDomains --local --auto-reset

Standalone mode only. enable modifies the genesis config and only takes effect after a reset — it requires standalone mode (xrpl-up start without --local-network). In --local-network (consensus) mode, all production amendments are pre-activated in the genesis ledger and cannot be changed — once activated, amendments are permanent. To undo an enable, simply run xrpl-up reset without re-enabling the amendment.

`xrpl-up init [directory]`

Scaffolds a new project with config, TypeScript setup, and example scripts. Prompts for a default network; choose local for local-sandbox-ready scripts out of the box.

Prerequisite: xrpl-up must be available on PATH. Until the package is published to npm, install from source with npm link (see Installation). The generated package.json scripts (npm run start, npm run accounts) call xrpl-up from PATH and do not re-install it locally.

xrpl-up init
xrpl-up init my-project

Generated files:

my-project/
├── xrpl-up.config.js          # Network configuration defaults + custom network support
├── package.json
├── tsconfig.json
├── .gitignore
└── scripts/
    ├── example-payment.ts     # Send XRP + verify sender/receiver balances
    ├── example-token.ts       # Issue a custom IOU token (DefaultRipple + TrustSet + Payment)
    ├── example-dex.ts         # Place a DEX order, list it, cancel it (⚠ needs counterparty to fill)
    ├── example-nft.ts         # Full NFT lifecycle: mint → sell offer → accept → burn
    ├── example-mpt.ts         # Issue a Multi-Purpose Token: create issuance → opt in → transfer
    └── example-amm.ts         # Create an AMM pool and execute a swap (local only)

When local is selected as the default network, the example scripts use the local faucet (http://localhost:3001) instead of client.fundWallet(). example-amm.ts is only scaffolded for local mode since AMM is enabled by default there. The local example-dex.ts controls both sides of the trade so the order fills immediately; the remote variant places the order, lists it, then cancels it with a note that a real counterparty is required for fills.

`xrpl-up snapshot`

Save and restore ledger state checkpoints. Useful for complex test setups (AMM pools, issued currencies, multi-step escrows) where re-running setup from scratch is expensive.

Requires --local-network mode. Snapshots tar the named Docker volume (xrpl-up-local-db) into a self-contained .tar.gz file. Restore recreates the volume from that tarball — the volume does not need to have survived between runs. In standalone mode (default), there is no persistent volume to snapshot.

# Save the current ledger state
xrpl-up snapshot save before-amm

# List saved snapshots
xrpl-up snapshot list

# Restore to a previous checkpoint (~5–10s: rippled + faucet stop, volume restored, both restart)
xrpl-up snapshot restore before-amm

Each snapshot saves both the ledger volume and a copy of the account store (local-accounts.json), so xrpl-up accounts reflects the accounts that existed at snapshot time. The account store sidecar is copied as-is — it is not validated against the ledger. The snapshot list output shows +accounts for any snapshot that includes the account sidecar.

Typical workflow:

xrpl-up start --local-network --detach

# Run expensive setup (fund accounts, create AMM pool, set trust lines...)
xrpl-up faucet --network local
# Wait for funded accounts to appear on the validated ledger (~4s consensus close).
# Snapshot save stops services before archiving — unvalidated transactions may be lost.
xrpl-up accounts --local                        # confirm accounts are on-ledger
xrpl-up snapshot save after-setup

# Run tests, mutate state...

# Roll back to known-good state and run again
xrpl-up snapshot restore after-setup
xrpl-up accounts --local    # shows accounts as of snapshot time

Fresh start from a snapshot after reset:

xrpl-up reset                                    # wipe everything
xrpl-up start --local-network --detach          # start sandbox (creates new volume)
xrpl-up snapshot restore after-setup             # restore saved state
xrpl-up accounts --local                         # snapshot accounts restored

Snapshots are stored at ~/.xrpl-up/snapshots/ and are portable — copy them to any machine and restore. Each snapshot produces three files:

<name>.tar.gz — compressed node DB volume (typically 5–100 MB)
<name>-accounts.json — account store at snapshot time
<name>-meta.json — snapshot metadata (format version)

`xrpl-up config`

Manage and validate rippled configuration.

`xrpl-up config export`

Prints the auto-generated rippled.cfg to stdout, or writes it to a file. Use this as a starting point for a custom config.

# Print to stdout
xrpl-up config export

# Save to file
xrpl-up config export --output my-rippled.cfg

# Export with debug log level
xrpl-up config export --debug --output my-rippled.cfg

`xrpl-up config validate <file>`

Validates a rippled.cfg for compatibility with xrpl-up before you use it. Checks for blocking errors, warnings, and prints recommendations.

xrpl-up config validate my-rippled.cfg

What is checked:

Severity	Check
Error	WebSocket port must be `6006` (hardcoded by xrpl-up)
Error	WebSocket `ip` must be `0.0.0.0` (faucet container access)
Error	WebSocket `admin` must include `0.0.0.0` (admin commands)
Error	`[ssl_verify]` must be `0`
Error	`[node_db]` and `[database_path]` must be present
Warning	`node_size = large/huge` risks OOM on developer laptops
Warning	`send_queue_limit < 100` may throttle heavy test suites
Recommendation	Add `send_queue_limit = 500` for AMM testing

Exit code 1 if any errors are found, 0 otherwise.

Custom config workflow:

# 1. Export the default as a starting point
xrpl-up config export --output my-rippled.cfg

# 2. Edit — e.g. change node_size, send_queue_limit, log level
$EDITOR my-rippled.cfg

# 3. Validate before starting
xrpl-up config validate my-rippled.cfg

# 4. Start with the custom config
xrpl-up start --local --config my-rippled.cfg

Validation also runs automatically when --config is passed to xrpl-up start --local — the sandbox will not start if there are blocking errors.

CI/CD

Docker is available on all GitHub-hosted runners (ubuntu-latest, macos-latest).

Standalone mode (the default) is recommended for CI — it starts in seconds, has instant ledger closes, and needs no volume management.

# .github/workflows/test.yml
steps:
  - run: xrpl-up start --local --detach
  - run: npm test
  - run: xrpl-up stop
    if: always()

First run: xrpl-up start automatically pulls the rippled Docker image (~1 GB) on first run and shows download progress. Subsequent runs reuse the cached image.

Configuration

xrpl-up.config.js in your project root defines named networks used by run, accounts, status, and remote start/faucet flows:

module.exports = {
  networks: {
    local: {
      url: 'ws://localhost:6006',
      name: 'Local rippled (Docker)',
    },
    testnet: {
      url: 'wss://s.altnet.rippletest.net:51233',
      name: 'XRPL Testnet',
    },
    devnet: {
      url: 'wss://s.devnet.rippletest.net:51233',
      name: 'XRPL Devnet',
    },
  },
  defaultNetwork: 'local',
};

Add any custom WebSocket endpoint as a named network and use it with --network <name>.

Supported Networks

Key	Endpoint	Faucet
`local`	`ws://localhost:6006`	Yes (genesis wallet, no limits)
`testnet`	`wss://s.altnet.rippletest.net:51233`	Yes (rate limited)
`devnet`	`wss://s.devnet.rippletest.net:51233`	Yes (rate limited)

Local vs Testnet: The local sandbox is designed to cover most development workflows without needing testnet. Local mode has no transaction throttling, no faucet rate limits, and full reset control. Standalone mode (default) has instant ledger closes; --local-network has ~4s consensus closes but adds persistence and snapshot support. Use testnet for final validation against real network state.

Data Storage

Account seeds, generated configs, and snapshots are stored at:

~/.xrpl-up/
  local-accounts.json         # funded account seeds (local mode)
  testnet-accounts.json       # funded account seeds (testnet)
  devnet-accounts.json        # funded account seeds (devnet)
  docker-compose.yml          # generated on each start
  rippled.cfg                 # generated on each start (or custom via --config)
  snapshots/
    before-amm.tar.gz         # node DB volume snapshot (--local-network mode)
    before-amm-accounts.json  # account store at snapshot time
    before-amm-meta.json      # snapshot metadata
    after-setup.tar.gz
    after-setup-accounts.json
    after-setup-meta.json

xrpl-up start always recreates accounts fresh unless --local-network is used. xrpl-up faucet appends to the account store regardless of mode. xrpl-up reset clears the account store and Docker volume in one command.

License

MIT

Name		Name	Last commit message	Last commit date
Latest commit History 176 Commits
.claude-plugin		.claude-plugin
.github/workflows		.github/workflows
examples		examples
skills/xrpl-up		skills/xrpl-up
src		src
tests		tests
.gitignore		.gitignore
CURRENT-FEATURE-SETS.md		CURRENT-FEATURE-SETS.md
LICENSE		LICENSE
README.md		README.md
SPEC.md		SPEC.md
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json
vitest.config.local-network.ts		vitest.config.local-network.ts
vitest.config.local.ts		vitest.config.local.ts
vitest.config.snapshot.ts		vitest.config.snapshot.ts
vitest.config.ts		vitest.config.ts
xrpl-up-problem-space.md		xrpl-up-problem-space.md

Folders and files

Latest commit

History

Repository files navigation

xrpl-up

Prerequisites

Installation

Quick Start

Commands

Global flag: --node

xrpl-up start

xrpl-up stop

xrpl-up reset

xrpl-up accounts

xrpl-up faucet

xrpl-up status

xrpl-up run <script>

xrpl-up logs

xrpl-up amm

xrpl-up amm create <asset1> <asset2>

xrpl-up amm info <asset1> <asset2>

xrpl-up nft

xrpl-up nft mint

xrpl-up nft list

xrpl-up nft offers <nftokenId>

xrpl-up nft sell <nftokenId> <price>

xrpl-up nft accept <offerId>

xrpl-up nft burn <nftokenId>

xrpl-up channel

xrpl-up channel create <destination> <amount>

xrpl-up channel list

xrpl-up channel fund <channelId> <amount>

xrpl-up channel sign <channelId> <amount>

xrpl-up channel verify <channelId> <amount> <signature> <publicKey>

xrpl-up channel claim <channelId>

xrpl-up mptoken

xrpl-up mptoken issuance create

xrpl-up mptoken issuance destroy <issuanceId>

xrpl-up mptoken authorize <issuanceId>

xrpl-up mptoken issuance set <issuanceId>

xrpl-up mptoken issuance get <issuanceId>

xrpl-up mptoken issuance list <address>

Sending MPT payments

xrpl-up offer

xrpl-up offer create <pays> <gets>

xrpl-up offer cancel <sequence>

xrpl-up offer list

xrpl-up trust

xrpl-up trust set