feat: add wallet vanity command for generating vanity addresses

Author: k4m4

README.md

@@ -1476,6 +1476,30 @@ xrpl wallet verify-message "I own this account" 48F3E8... ED01FA...
 # Valid
 ```
 
+#### `wallet vanity`
+
+Generate a vanity address matching a prefix and/or suffix pattern. Uses brute-force search.
+
+> **WARNING:** Vanity addresses should NOT be used for mainnet accounts holding real value.
+
+```bash
+xrpl wallet vanity [--starts-with <pattern>] [--ends-with <pattern>] [--algorithm <ed25519|secp256k1>]
+```
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `--starts-with` | `string` | — | Prefix pattern to match after the leading `r` (case-insensitive regex) |
+| `--ends-with` | `string` | — | Suffix pattern to match (case-insensitive regex) |
+| `--algorithm` | `string` | `"ed25519"` | Key algorithm: `ed25519` or `secp256k1` |
+
+At least one of `--starts-with` or `--ends-with` is required.
+
+```bash
+xrpl wallet vanity --starts-with Nick
+xrpl wallet vanity --ends-with XRP
+xrpl wallet vanity --starts-with N --ends-with XRP
+```
+
 #### `wallet import`
 
 Import a wallet into an encrypted local keystore. Supports seeds, BIP39 mnemonics (with optional passphrase and derivation path), and interactive input. Secrets are encrypted with scrypt + AES-128-CTR.
@@ -2046,7 +2070,6 @@ Contributions are welcome! Please:
 Features that aren't planned for the initial release but worth exploring later:
 
 - **`watch` mode** — poll a command at an interval and stream changes, e.g. `xrpl watch balance rAddr --interval 5s`. Useful for scripting and monitoring.
-- **`wallet vanity`** — generate a vanity address matching a prefix/suffix pattern (e.g. `xrpl wallet vanity --starts-with rXRP`).
 - **Ledger hardware wallet signing** — sign transactions using a connected Ledger device, as an alternative to providing a seed or keyfile.
 - **`--private-key` option** — accept a raw hex private key directly for signing, in addition to seeds. Requires algorithm detection or an `--algorithm` flag to derive the public key.
 - **Niche developer utilities** — expose more from xrpl.js sub-packages: RFC1751 mnemonic encode/decode, seed encoding/decoding (`encodeSeed`/`decodeSeed`), raw keypair derivation (`deriveKeypair`), account ID encoding from hex public key, and low-level binary codec operations.

src/commands/wallet/index.ts

@@ -7,6 +7,7 @@ import { registerImport } from "./import.js";
 import { registerList } from "./list.js";
 import { registerRemove } from "./remove.js";
 import { registerSignMessage } from "./sign-message.js";
+import { registerVanity } from "./vanity.js";
 import { registerVerifyMessage } from "./verify-message.js";
 
 export function registerWalletCommands(program: Command) {
@@ -22,5 +23,6 @@ export function registerWalletCommands(program: Command) {
 	registerList(wallet, program);
 	registerRemove(wallet, program);
 	registerSignMessage(wallet, program);
+	registerVanity(wallet, program);
 	registerVerifyMessage(wallet, program);
 }

src/commands/wallet/vanity.ts

@@ -0,0 +1,86 @@
+import { type Command, Option } from "commander";
+import { Wallet } from "xrpl";
+import { info, output } from "../../lib/output.js";
+import type { GlobalOptions } from "../../lib/types.js";
+import { formatWallet, parseAlgorithm } from "./shared.js";
+
+function toRegex(pattern: string, template: string, label: string): RegExp {
+	try {
+		return new RegExp(template.replace("{}", pattern), "i");
+	} catch {
+		throw new Error(`Invalid regex in ${label}: ${pattern}`);
+	}
+}
+
+function buildMatcher(
+	startsWith?: string,
+	endsWith?: string,
+): (address: string) => boolean {
+	const startsRe = startsWith
+		? toRegex(startsWith, "^r{}", "--starts-with")
+		: null;
+	const endsRe = endsWith ? toRegex(endsWith, "{}$", "--ends-with") : null;
+
+	return (address: string) => {
+		if (startsRe && !startsRe.test(address)) return false;
+		if (endsRe && !endsRe.test(address)) return false;
+		return true;
+	};
+}
+
+async function vanityWallet(
+	opts: { algorithm: string; startsWith?: string; endsWith?: string },
+	globalOpts: GlobalOptions,
+) {
+	if (!opts.startsWith && !opts.endsWith) {
+		throw new Error("At least one of --starts-with or --ends-with is required");
+	}
+
+	const matches = buildMatcher(opts.startsWith, opts.endsWith);
+	const algorithm = parseAlgorithm(opts.algorithm);
+
+	info(
+		"WARNING: Vanity addresses should NOT be used for mainnet accounts holding real value.\n",
+		globalOpts,
+	);
+	info("Searching for matching address...", globalOpts);
+
+	let attempts = 0;
+	let wallet: Wallet;
+
+	do {
+		wallet = Wallet.generate(algorithm);
+		attempts++;
+		if (attempts % 10000 === 0) {
+			info(`  ${attempts.toLocaleString()} attempts...`, globalOpts);
+		}
+	} while (!matches(wallet.address));
+
+	info(`Found after ${attempts.toLocaleString()} attempts.\n`, globalOpts);
+	output(formatWallet(wallet), globalOpts);
+}
+
+export function registerVanity(wallet: Command, program: Command) {
+	wallet
+		.command("vanity")
+		.description(
+			"Generate a vanity address matching a pattern (NOT safe for mainnet use)",
+		)
+		.option(
+			"--starts-with <pattern>",
+			"Prefix pattern to match after the leading 'r' (case-insensitive regex)",
+		)
+		.option(
+			"--ends-with <pattern>",
+			"Suffix pattern to match (case-insensitive regex)",
+		)
+		.addOption(
+			new Option("--algorithm <algorithm>", "Key algorithm")
+				.choices(["ed25519", "secp256k1"])
+				.default("ed25519"),
+		)
+		.action(
+			(opts: { algorithm: string; startsWith?: string; endsWith?: string }) =>
+				vanityWallet(opts, program.opts() as GlobalOptions),
+		);
+}