OpenAlias Toolkit (openalias-kit)

Zero-dependency JavaScript/TypeScript library, CLI resolver, and DNS setup guide for OpenAlias (oa1:xmr) human-readable Monero (XMR) addresses with DNSSEC (AD flag) verification and Keccak-256 address checksum validation.

Works in Node.js (>=18), Deno, Bun, Cloudflare Workers, and modern browsers using standard DNS-over-HTTPS (DoH) endpoints.

Using OpenAlias in a browser wallet? MonkStash resolves OpenAlias domains and user@domain handles natively on the Send screen with DNSSEC verification, or you can inspect the resolved XMR address with the Online Monero Address Validator.

---

How OpenAlias Works for Monero

OpenAlias maps a domain name (donate.getmonero.org) or an email-style handle (donate@getmonero.org) to a 95-character Monero address using a standard DNS TXT record:

1. Email-to-FQDN translation: If the user types pay@example.com, the wallet replaces @ with . and queries the DNS TXT records for pay.example.com.
2. oa1:xmr record parsing: The wallet looks for a TXT record beginning with oa1:xmr and extracts recipient_address, recipient_name, and tx_description.
3. DNSSEC (AD flag) check: Because unauthenticated DNS can be spoofed by a rogue router or ISP, strict Monero wallets check that the DNS response is cryptographically signed via DNSSEC (AD: true / Authenticated Data) before filling in the recipient address.
4. Monero Base58 & Keccak-256 check: Finally, the wallet decodes the recipient_address and verifies its 4-byte Keccak-256 checksum.

---

OpenAlias oa1:xmr Syntax Reference

oa1:xmr recipient_address=888tNkZrPN6JsEgekjMnABU4TBzc2Dt29EPAvkRxbANsAnjyPbb3iQ1YBRk1UXcdRsiKc9dhwMVgN5S9cQUiyoogDavup3H; recipient_name=Acme Store; tx_description=Invoice payment;

Field	Required	Description
oa1:xmr	Yes	Prefix identifying the OpenAlias v1 protocol and the xmr cryptocurrency ticker.
recipient_address	Yes	Valid 95-character Monero primary (4...) or subaddress (8...), or 106-character integrated address.
recipient_name	Optional	Display label shown to the sender in their wallet UI. Escape literal semicolons as \;.
tx_description	Optional	Default transaction note/description populated in the sender's wallet.

---

Quick Start

1. Resolve an OpenAlias Domain or Handle (with DNSSEC)

import { resolveOpenAlias } from "openalias-kit";

// Accepts either "donate.getmonero.org" or "donate@getmonero.org"
const result = await resolveOpenAlias("donate@getmonero.org");

console.log(result);
/*
{
  valid: true,
  alias: "donate@getmonero.org",
  fqdn: "donate.getmonero.org",
  address: "888tNkZrPN6JsEgekjMnABU4TBzc2Dt29EPAvkRxbANsAnjyPbb3iQ1YBRk1UXcdRsiKc9dhwMVgN5S9cQUiyoogDavup3H",
  recipientName: "Monero Development",
  description: "Donation to Monero Core Team",
  dnssecValid: true,
  addressInfo: {
    valid: true,
    network: "mainnet",
    type: "subaddress",
    networkByte: 42,
    error: null
  },
  rawRecord: "oa1:xmr recipient_address=888tNkZrPN6JsEgekjMnABU4TBzc2Dt29EPAvkRxbANsAnjyPbb3iQ1YBRk1UXcdRsiKc9dhwMVgN5S9cQUiyoogDavup3H; recipient_name=Monero Development; tx_description=Donation to Monero Core Team;",
  warnings: [],
  error: null
}
*/

To allow domains that do not have DNSSEC enabled (while still returning a warning in result.warnings):

const res = await resolveOpenAlias("pay@example.com", { requireDnssec: false });

2. Generate a Valid oa1:xmr DNS TXT Record

import { formatOpenAliasRecord } from "openalias-kit";

const record = formatOpenAliasRecord({
  address: "888tNkZrPN6JsEgekjMnABU4TBzc2Dt29EPAvkRxbANsAnjyPbb3iQ1YBRk1UXcdRsiKc9dhwMVgN5S9cQUiyoogDavup3H",
  alias: "pay@example.com",
  recipientName: "Example Store",
  description: "XMR Checkout"
});

console.log(record.fqdn);       // "pay.example.com"
console.log(record.txtValue);   // "oa1:xmr recipient_address=888t...; recipient_name=Example Store; tx_description=XMR Checkout;"
console.log(record.bindRecord); // 'pay.example.com. 3600 IN TXT "oa1:xmr recipient_address=888t...; recipient_name=Example Store; tx_description=XMR Checkout;"'

3. Parse & Verify an Existing TXT Record Offline

import { parseOpenAliasRecord } from "openalias-kit";

const parsed = parseOpenAliasRecord(
  "oa1:xmr recipient_address=44AFFq5kSiGBoZ4NMDwYtN18obc8AemS33DBLWs3H7otXft3XjrpDtQGv7SqSsaBYBb98uNbr2VBBEt7f2wfn3RVGQBEP3A; recipient_name=General Fund;"
);

console.log(parsed.valid);            // true
console.log(parsed.addressInfo.type); // "primary"

---

CLI Usage (openalias)

# Resolve a live OpenAlias domain or handle and verify DNSSEC + XMR checksum
node bin/openalias.mjs resolve donate.getmonero.org

# Resolve and output JSON
node bin/openalias.mjs resolve donate@getmonero.org --json

# Generate a ready-to-paste DNS TXT record and BIND zone entry
node bin/openalias.mjs generate 888tNkZrPN6JsEgekjMnABU4TBzc2Dt29EPAvkRxbANsAnjyPbb3iQ1YBRk1UXcdRsiKc9dhwMVgN5S9cQUiyoogDavup3H --domain pay@yourdomain.com --name "Your Store" --desc "Monero Payment"

# Validate a raw TXT string offline
node bin/openalias.mjs verify-txt "oa1:xmr recipient_address=44AFFq5kSiGBoZ4NMDwYtN18obc8AemS33DBLWs3H7otXft3XjrpDtQGv7SqSsaBYBb98uNbr2VBBEt7f2wfn3RVGQBEP3A; recipient_name=Test;"

---

Step-by-Step DNS & DNSSEC Setup Guide

Step 1: Add the TXT Record

Choose whether you want people to send XMR to your root domain (yourdomain.com) or a handle/subdomain (pay@yourdomain.com / pay.yourdomain.com):

Target Handle	DNS Record Type	Host / Name Field	Value / Content Field
yourdomain.com	TXT	@	oa1:xmr recipient_address=8...; recipient_name=Your Name;
pay@yourdomain.com	TXT	pay	oa1:xmr recipient_address=8...; recipient_name=Your Name;

Step 2: Enable DNSSEC (Required by Monero Wallets)

Without DNSSEC, Monero GUI, Feather Wallet, Cake Wallet, and MonkStash will either reject the OpenAlias lookup or warn the sender that the DNS record is unverified.

• Cloudflare:
  1. Open your domain in the Cloudflare dashboard and go to DNS -> Settings.
  2. Click Enable DNSSEC.
  3. If your domain is registered outside Cloudflare, copy the DS Record values (Key Tag, Algorithm 13, Digest Type 2 / SHA-256, and Digest) into your domain registrar's DNSSEC panel.
• Porkbun:
  1. If using Porkbun Authoritative Nameservers, open Domain Management -> Details -> DNSSEC and click Enable (one-click automatic DS provisioning).
• Namecheap:
  1. Go to Domain List -> Manage -> Advanced DNS.
  2. Scroll to DNSSEC and toggle it on (if using Namecheap BasicDNS/PremiumDNS) or paste the DS record from your external DNS host.

Step 3: Verify Your Setup

Run the CLI resolver to confirm that both the oa1:xmr TXT record and DNSSEC (AD=true) are active:

node bin/openalias.mjs resolve pay@yourdomain.com

---

Running Tests

npm test

---

Related Monero Resources & Tools

• MonkStash Web Wallet - Self-custodial browser Monero wallet with built-in OpenAlias + DNSSEC resolution.
• Online Monero Address Validator - Verify primary (4...), subaddress (8...), and integrated XMR addresses in your browser.
• Monero Payment Links & QR Codes - Generate shareable #fragment payment links when you do not own a custom domain.
• monero-address-toolkit - Zero-dependency Monero Base58 codec, integrated address splitter, and monero: URI parser.

---

License

MIT