Realm Name System
The complete documentation for Atomicals Protocol Realm Names — Bitcoin-native decentralized identity, naming, and organizational infrastructure.
What are Realm Names?
Realm Names are human-readable identifiers minted directly on the Bitcoin blockchain using the Atomicals Protocol. They function as a fully decentralized naming system — no registrars, no middlemen, no renewal fees. Once you claim a Realm, it's yours forever (or until you choose to transfer it).
A Realm name begins with a plus + sign and must contain at least one alphabetical character. For example, +alice, +company, and +agent007 are all valid top-level Realm names (TLRs).
Decentralized DNS
A naming system that lives entirely on Bitcoin. No ICANN, no renewals, no centralized authority.
Digital Identity
Use your Realm as a verifiable on-chain identity for social profiles, authentication, and reputation.
Hierarchical System
Realms support infinite SubRealm nesting: +org.team.member — perfect for organizations and projects.
Payment Names
Receive crypto with human-readable addresses: +hello@myrealm instead of long hex strings.
DAO Infrastructure
Build decentralized organizations with SubRealm-based membership, role assignment, and governance.
Proof of Work
Realm minting uses Bitwork — CPU/GPU mining for the commit transaction, ensuring fair distribution.
Realm vs. Traditional Domain Names
| Feature | Realm Names (RNS) | DNS (Traditional) | ENS (Ethereum) |
|---|---|---|---|
| Blockchain | Bitcoin (Layer 1) | N/A (Centralized) | Ethereum |
| Ownership | Permanent, self-sovereign | Rented annually | Rented annually |
| Format | +name | name.com | name.eth |
| Registrar | None (protocol-enforced) | ICANN accredited | ENS DAO |
| Sub-domains | Infinite hierarchy, owner-controlled rules | Managed by registrar | Limited support |
| Data Storage | On-chain files, state, profiles | DNS records only | Limited records |
| Payment | Built-in Payname system | N/A | Via resolver |
| Transferable | Yes (Bitcoin tx) | Via registrar | Yes (ERC-721) |
Quick Start
Get up and running in minutes. Choose your preferred path:
Install the Atomicals CLI
git clone https://github.com/atomicals/atomicals-js.git
cd atomicals-js
yarn install
yarn run build
# Initialize wallet
yarn cli wallet-init
# Check if a realm is available
yarn cli get +myname
# Mint a realm
yarn cli mint-realm "myname"
Query via HTTP API
# Check if realm "abc" exists
curl "https://ep.wizz.cash/proxy/blockchain.atomicals.get_by_realm?params=[%22abc%22]"
# Get comprehensive realm info
curl "https://ep.wizz.cash/proxy/blockchain.atomicals.get_realm_info?params=[%22abc%22]"
# Search realms by prefix
curl "https://ep.wizz.cash/proxy/blockchain.atomicals.find_realms?params=[%22bit%22]"
Python Quick Example
import requests, json
PROXY = "https://ep.wizz.cash/proxy"
def check_realm(name):
url = f"{PROXY}/blockchain.atomicals.get_by_realm"
r = requests.get(url, params={"params": json.dumps([name])})
result = r.json()["response"]["result"]
if result.get("atomical_id"):
print(f"Realm +{name} is TAKEN (ID: {result['atomical_id'][:16]}...)")
else:
print(f"Realm +{name} is AVAILABLE!")
check_realm("abc") # Taken
check_realm("zzz999") # Check availability
Naming System Architecture
Name Format & Validation
Realm names follow strict validation rules enforced at the protocol level. The exact regex patterns from the atomicals-js source code:
// Top-Level Realm (TLR): must start with a letter
isValidRealmName: /^[a-z][a-z0-9\-]{0,63}$/
// SubRealm: can start with a letter or digit
isValidSubRealmName: /^[a-z0-9][a-z0-9\-]{0,63}$/
// Additional base rules (isValidNameBase):
// - Cannot begin or end with a hyphen
// - Max 64 characters, min 1 character
// - TLR cannot start with a number
| Rule | Description | Example |
|---|---|---|
| Prefix | Always starts with + | +alice |
| Characters | Lowercase a-z, digits 0-9, hyphens - | +my-realm-01 |
| Min length | At least 1 character | +a |
| Max length | Up to 64 characters | +a-very-long-name... |
| TLR start | Top-level Realm must start with a letter (a-z) | +alice ✔ / +007a ❌ |
| SubRealm start | SubRealms can start with a letter or digit | +realm.007 ✔ |
| Hyphens | Cannot begin or end with a hyphen | +a-b ✔ / +-ab ❌ |
| Case | Always lowercase (auto-converted) | +Alice → +alice |
Hierarchy Structure
Realms use a dot-separated hierarchy, similar to DNS but with more powerful semantics:
+company # Top-Level Realm (TLR)
+company.engineering # SubRealm (department)
+company.engineering.frontend # Sub-SubRealm (team)
+company.engineering.frontend.bob # Sub-Sub-SubRealm (member)
Each level in the hierarchy is an independent Atomical NFT, owned by its creator. The parent Realm owner sets the rules for who can mint SubRealms beneath it.
First-is-First Candidate System
Realm claiming uses a first-is-first (not first-come-first-served) system based on the Bitcoin blockchain ordering:
The commit transaction locks in the claim. Multiple users may try to claim the same name — the one whose commit appears first in the blockchain wins. After 3 block confirmations, the Realm status changes from pending to verified.
SubRealms
Every Realm and SubRealm can mint any number of SubRealms below them. This creates an infinitely nestable hierarchy, enabling complex organizational structures.
SubRealm Minting Modes
Bitwork Mining
Require CPU/GPU proof-of-work on the commit and/or reveal transactions. Fair and censorship-resistant.
Satoshi Payment
Require BTC payment to one or more specified addresses. Revenue model for realm owners.
ARC20 Token Payment
Accept ARC20 fungible token payments. Integrate your project's token economy.
Combined Rules
Mix Bitwork + Payment with regex pattern matching for flexible pricing tiers.
SubRealm Payment Flow
When a payment rule is in effect, the minting process uses a two-step candidate system to prevent front-running:
commit+reveal
confirm candidate
within 11 blocks
~15 blocks total
Bitwork Mining
Bitwork is the Atomicals Protocol's proof-of-work system that requires transaction hashes to match specific prefixes. It serves as both a spam prevention mechanism and a way to create provably rare tokens.
How Bitwork Works
When you mine a Realm or SubRealm with Bitwork, the CLI generates random nonces until the resulting transaction hash begins with the required prefix:
# "abc1" prefix - approximately 65,536 hashes needed (~seconds on desktop)
bitworkc: "abc1"
# "77777" prefix - approximately 1,048,576 hashes (~minutes on desktop)
bitworkc: "77777"
# "68656C6C6F" encodes "hello" - ~1.1 trillion hashes (~10-20 min on GPU)
bitworkc: "68656c6c6f"
Fine-Tuning Difficulty
Use the dot notation to fine-tune difficulty between 2x and 16x increments:
| Bitwork Value | Meaning | Difficulty Multiplier |
|---|---|---|
"7777" | First 4 hex chars must be 7777 | 1x (baseline) |
"7777.1" | 4 chars + 5th char ≥ 1 | ~1.07x |
"7777.8" | 4 chars + 5th char ≥ 8 | ~2x |
"7777.10" | 4 chars + 5th char ≥ a | ~2.67x |
"7777.15" | 4 chars + 5th char = f | ~16x (= "77777") |
"77777" | First 5 hex chars must be 77777 | 16x |
The number after the dot (1–15) indicates the minimum value the next hex character must have. 10 = hex a, 11 = hex b, etc.
Bitwork Types
| Type | Field | Applied To |
|---|---|---|
| Commit Bitwork | bitworkc | The commit transaction hash must match the prefix |
| Reveal Bitwork | bitworkr | The reveal transaction hash must match the prefix |
Rules Engine
The Rules Engine is the core mechanism that controls SubRealm and DMINT minting. Realm owners define rules using a JSON data structure that specifies pattern matching, Bitwork requirements, and payment conditions.
Rules Data Structure
{
"subrealms": {
"rules": [
{
"p": "^[a-z0-9]{6,64}$",
"bitworkc": "8888.8"
},
{
"p": ".*",
"o": {
"5120a976...90e4": {
"v": 10000
}
}
}
]
}
}
Rule Fields Reference
| Field | Type | Description |
|---|---|---|
p | String (regex) | Python 3.9 regex pattern. Matches the SubRealm name in full string mode (start to end). |
bitworkc | String | Required Bitwork prefix for the commit transaction. |
bitworkr | String | Required Bitwork prefix for the reveal transaction. |
o | Object | Output payment requirements. Keys are hex-encoded output scripts, values specify amounts. |
o.{script}.v | Number | Satoshi amount to pay to this output script. |
o.{script}.id | String | ARC20 token Atomical ID for token-based payment. |
Pattern Matching Examples
".*" # Matches ANY name
"^[a-z]{3,10}$" # 3-10 lowercase letters only
"^[a-z0-9]{6,64}$" # 6-64 alphanumeric characters
"^vip-.*" # Names starting with "vip-"
"^0|\.gif$" # Names starting with "0" OR ending with ".gif"
"^(alice|bob|carol)$" # Only specific allowed names
Tiered Pricing Example
Different rules can set different costs based on name length or pattern:
{
"subrealms": {
"rules": [
{
"p": "^[a-z]{1,3}$",
"o": {
"5120abc...def": { "v": 100000 }
},
"bitworkc": "abcd"
},
{
"p": "^[a-z]{4,5}$",
"o": {
"5120abc...def": { "v": 50000 }
}
},
{
"p": "^[a-z0-9]{6,64}$",
"bitworkc": "7777"
}
]
}
}
In this example: 1–3 letter names require 100,000 sats + Bitwork, 4–5 letter names cost 50,000 sats, and 6+ character names only need mining.
Paynames
Paynames enable human-readable payment addresses powered by Realm Names. Instead of sharing long Bitcoin addresses, you can share a simple Payname.
Format
+[inbox]@[realm_name]
# Examples:
+hello@samplerealm # inbox "hello" at Realm "samplerealm"
+main@mycompany # primary inbox
+support@mycompany # support payment inbox
[email protected] # inbox at a SubRealm
On-Chain Data Format
{
"paynames": {
"main": {
"types": {
"btc": {
"value": "bc1q...your-btc-address"
},
"ltc": {
"value": "ltc1q...your-ltc-address",
"notes": "Litecoin payments accepted"
}
}
},
"donations": {
"types": {
"btc": {
"value": "bc1q...donation-address",
"instructions": "Any amount appreciated!"
}
}
}
}
}
The delegate field allows you to delegate the entire paynames configuration (or individual inboxes) to another NFT:
{
"paynames": {
"delegate": "atom:btc:id:<atomical_id>/paynames"
}
}
URN & Resource References
Atomicals defines a Universal Resource Name (URN) system for referencing digital objects across the ecosystem. This is the backbone for recursion, cross-linking, and composable assets.
URN Format
atom:<chain>:<ref_type>:<identifier> [$ or /[file]]
# $ = original mint data (immutable)
# / = latest dynamic data (mutable)
Reference Types
| Type | Example | Description |
|---|---|---|
id | atom:btc:id:<atomical_id> | Reference by Atomical ID |
realm | atom:btc:realm:myrealm | Reference by Realm name |
container | atom:btc:container:mycol | Reference by Container name |
dat | atom:btc:dat:<data_id>/img.png | Immutable data file reference |
arc | atom:btc:arc:<ticker> | Reference by ARC20 ticker |
Realm-Specific URN Examples
# General info about a realm
atom:btc:realm:myrealm
# Get the latest profile data
atom:btc:realm:myrealm/profile
# SubRealm reference
atom:btc:realm:myrealm.subrealm
# Specific version of a file (by txid, version, or block height)
atom:btc:realm:myrealm/profile@v1
atom:btc:realm:myrealm/profile@808142
# Use in the ctx field for recursion
{
"ctx": {
"theme": "atom:btc:realm:mydesign/theme.css",
"logo": "atom:btc:dat:<data_id>/logo.png"
}
}
API Overview
The Atomicals ElectrumX API is served via HTTP proxy endpoints. You can query Realm data, search names, validate transactions, and more.
Base URL
https://ep.wizz.cash/proxy
https://ep.atomicals.xyz/proxy is no longer available (DNS unresolvable). Use the Wizz Cash proxy or self-host your own ElectrumX node.
Request Format
GET /proxy/<method>?params=["value1","value2"]
Parameters are passed as a JSON-encoded array in the params query string.
POST /proxy/<method>
Content-Type: application/json
{
"params": ["value1", "value2"]
}
Response Format
{
"success": true,
"response": {
"result": { ... },
"global": { // present in some endpoints
"height": 936045,
"network": "mainnet",
...
}
}
}
Rate Limits
The public Wizz Cash proxy enforces rate limiting: 25 requests per window (see x-ratelimit-limit header). For production use, consider running your own ElectrumX node.
Realm-Specific API Endpoints
blockchain.atomicals.get_by_realm
Check if a top-level Realm exists and get its status.
| Param | Type | Description |
|---|---|---|
realm_name | string | The realm name to look up (without + prefix) |
| Response Field | Description |
|---|---|
status | "verified" if claimed, otherwise "pending" or empty candidates |
atomical_id | The verified Atomical ID (null if not verified) |
candidate_atomical_id | Leading candidate even if not yet verified |
candidates | Array of all candidates with commit_height, txid, etc. |
type | Always "realm" |
blockchain.atomicals.get_realm_info
Get comprehensive realm info including full hierarchy, SubRealm minting rules, and path resolution. Supports dot-separated names for SubRealm lookup.
| Param | Type | Description |
|---|---|---|
full_name | string | Full realm path, e.g. "myrealm" or "myrealm.sub" |
| Response Field | Description |
|---|---|
atomical_id | Found Atomical ID (null if not found) |
top_level_realm_atomical_id | The TLR's Atomical ID |
top_level_realm_name | The TLR name |
nearest_parent_realm_atomical_id | Closest existing parent in the path |
request_full_realm_name | Exactly what was queried |
found_full_realm_name | The deepest existing path found |
missing_name_parts | Parts of the path that don't exist yet |
nearest_parent_realm_subrealm_mint_allowed | Whether the parent allows SubRealm minting |
nearest_parent_realm_subrealm_mint_rules | Active minting rules (if any) |
blockchain.atomicals.get_by_subrealm
Query a specific SubRealm by its parent and name.
blockchain.atomicals.find_realms
Search for Realms by name prefix.
| Param | Type | Default | Description |
|---|---|---|---|
prefix | string | null | Name prefix to search |
reverse | bool | false | Reverse ordering |
limit | int | 100 | Max results to return |
offset | int | 0 | Pagination offset |
is_verified_only | bool | false | Only return verified realms |
blockchain.atomicals.find_subrealms
Search SubRealms under a given parent.
blockchain.atomicals.get
Get full details of any Atomical by its ID or number.
Complete API Endpoint Reference
All available endpoints on the Atomicals ElectrumX HTTP proxy:
Realm & Name Endpoints
Atomical Query Endpoints
Token & Container Endpoints
Address & Balance Endpoints
Global & Block Endpoints
Transaction & Validation Endpoints
API Playground
Test the Realm APIs directly from your browser. All requests go to the public Wizz Cash proxy.
Tutorial 1: Mint a Realm
This tutorial walks you through minting your first Realm name on Bitcoin mainnet.
Prerequisites
- Node.js v16+ and Yarn installed
- Some Bitcoin (BTC) for transaction fees (~5,000-10,000 sats recommended)
Step 1: Install the CLI
git clone https://github.com/atomicals/atomicals-js.git
cd atomicals-js
yarn install
yarn run build
Step 2: Initialize Your Wallet
yarn cli wallet-init
This creates a wallet.json with a new P2TR (Taproot) address. Back up the mnemonic phrase securely!
Step 3: Fund Your Wallet
Send BTC to the P2TR address shown after wallet initialization. Wait for at least 1 confirmation.
Step 4: Check Realm Availability
# Check if the name is available
yarn cli get +yourdesiredname
# Or use the realm-info command for more detail
yarn cli realm-info yourdesiredname
Step 5: Mint the Realm
yarn cli mint-realm "yourdesiredname" --satsbyte=50
Follow the on-screen instructions. The CLI will perform Bitwork mining on your CPU, then broadcast the commit and reveal transactions.
Step 6: Verify (after 3 confirmations)
yarn cli get +yourdesiredname
Tutorial 2: Query Realm Information
Learn how to query Realm data using the HTTP API directly.
Check if a Realm Exists
curl -s "https://ep.wizz.cash/proxy/blockchain.atomicals.get_by_realm?params=%5B%22bitcoin%22%5D" | python3 -m json.tool
Interpreting the Response
{
"success": true,
"response": {
"result": {
"status": "verified", // "verified" = claimed
"atomical_id": "abc15f...i0", // non-null = exists
"type": "realm"
}
}
}
Decision Logic
| Condition | Meaning |
|---|---|
status == "verified" && atomical_id != null | Realm is taken and confirmed |
status == "pending" | Someone has claimed but not yet confirmed (wait 3 blocks) |
candidates is empty | Realm is available for minting |
Tutorial 3: Enable SubRealm Minting
If you own a Realm, you can allow others to mint SubRealms under it.
Step 1: Create Rules File
{
"subrealms": {
"rules": [
{
"p": "^[a-z0-9]{6,64}$",
"bitworkc": "8888.8"
},
{
"p": "^[a-z0-9]{1,5}$",
"o": {
"YOUR_OUTPUT_SCRIPT_HEX": {
"v": 10000
}
}
}
]
}
}
This configuration: names with 6+ chars require mining (~1-2 min CPU), short names (1-5 chars) cost 10,000 sats.
Step 2: Enable SubRealms
yarn cli enable-subrealms +myrealm rules.json --satsbyte=100
Step 3: Verify Rules Are Active
yarn cli realm-info myrealm
Convert Between Addresses and Scripts
# Address to output script hex
yarn cli address-script bc1p49mrdne5j2j5dktkupflvx6s0z8027ssk2yg2f6mvzand8nzjrjqschm45
# Output script hex to address
yarn cli script-address 5120a97636cf3492a546d976e053f61b50788ef57a10b28885275b60bb369e6290e4
Tutorial 4: Mint a SubRealm
Step 1: Check Availability
yarn cli realm-info myrealm.mysubrealm
Step 2: Mint the SubRealm
yarn cli mint-subrealm +myrealm.mysubrealm --satsbyte=100
Step 3: Make Payment (if required)
# Check pending subrealms that need payment
yarn cli pending-subrealms
# Follow on-screen instructions to complete payment
Tutorial 5: Python Integration
A complete Python module for interacting with the Realm API.
import json
import requests
class RealmClient:
"""Client for the Atomicals Realm API via ElectrumX proxy."""
def __init__(self, proxy_url="https://ep.wizz.cash/proxy"):
self.proxy = proxy_url
def _call(self, method, params=None):
url = f"{self.proxy}/{method}"
r = requests.get(url, params={"params": json.dumps(params or [])}, timeout=15)
r.raise_for_status()
data = r.json()
if not data.get("success"):
raise Exception(f"API error: {data}")
return data["response"]
def get_by_realm(self, name):
"""Check if a realm exists. Returns (is_taken, atomical_id, status)."""
result = self._call("blockchain.atomicals.get_by_realm", [name])["result"]
return {
"taken": result.get("atomical_id") is not None,
"atomical_id": result.get("atomical_id"),
"status": result.get("status"),
"candidates": result.get("candidates", [])
}
def get_realm_info(self, full_name):
"""Get comprehensive realm info with hierarchy resolution."""
return self._call("blockchain.atomicals.get_realm_info", [full_name])["result"]
def get_atomical(self, atomical_id_or_number):
"""Get full Atomical details."""
return self._call("blockchain.atomicals.get", [atomical_id_or_number])
def search_realms(self, prefix="", limit=20, verified_only=False):
"""Search realms by prefix."""
return self._call("blockchain.atomicals.find_realms",
[prefix, False, limit, 0, verified_only])
def get_global(self):
"""Get global network info (block height, counts)."""
return self._call("blockchain.atomicals.get_global", [10])
def is_available(self, name):
"""Simple check: is this realm name available?"""
return not self.get_by_realm(name)["taken"]
def batch_check(self, names):
"""Check availability of multiple realm names."""
results = {}
for name in names:
try:
info = self.get_by_realm(name)
results[name] = {"available": not info["taken"], "status": info["status"]}
except Exception as e:
results[name] = {"error": str(e)}
return results
# === Usage Example ===
if __name__ == "__main__":
client = RealmClient()
# Check single realm
info = client.get_by_realm("abc")
print(f"+abc taken: {info['taken']}, status: {info['status']}")
# Get detailed info
detail = client.get_realm_info("abc")
print(f"Atomical ID: {detail.get('atomical_id')}")
# Search realms starting with "bit"
results = client.search_realms("bit", limit=5)
print(json.dumps(results, indent=2))
# Batch availability check
checks = client.batch_check(["abc", "hello", "zzzzrandomname999"])
for name, status in checks.items():
print(f"+{name}: {status}")
Tutorial 6: JavaScript Integration
Browser and Node.js compatible JavaScript client for Realm APIs.
const PROXY = "https://ep.wizz.cash/proxy";
async function callAPI(method, params = []) {
const url = `${PROXY}/${method}?params=${encodeURIComponent(JSON.stringify(params))}`;
const res = await fetch(url);
const data = await res.json();
if (!data.success) throw new Error(`API error: ${JSON.stringify(data)}`);
return data.response;
}
async function checkRealm(name) {
const { result } = await callAPI("blockchain.atomicals.get_by_realm", [name]);
return {
taken: result.atomical_id !== null,
status: result.status,
atomicalId: result.atomical_id,
candidates: result.candidates
};
}
async function getRealmInfo(fullName) {
const { result } = await callAPI("blockchain.atomicals.get_realm_info", [fullName]);
return result;
}
async function searchRealms(prefix, limit = 20) {
return await callAPI("blockchain.atomicals.find_realms",
[prefix, false, limit, 0, false]);
}
// Usage
(async () => {
const info = await checkRealm("abc");
console.log(`+abc taken: ${info.taken}, ID: ${info.atomicalId}`);
const detail = await getRealmInfo("abc");
console.log("Realm Info:", detail);
})();
Extension: Digital Identity
Realm Names form the foundation of a self-sovereign identity system on Bitcoin. Here's how to use them as a decentralized identity layer.
Identity Profile Structure
Profile data can be stored on-chain as part of the Realm's dynamic state. Below is an illustrative schema design:
{
"profile": {
"name": "Alice",
"bio": "Bitcoin builder & Atomicals enthusiast",
"image": "atom:btc:dat:<data_id>/avatar.png",
"links": {
"website": "https://alice.dev",
"nostr": "npub1...",
"github": "alice"
}
},
"paynames": {
"main": { "types": { "btc": { "value": "bc1q...addr" } } }
}
}
Verification Flow
- User presents their Realm name:
+alice - Service queries
get_by_realm("alice")to get the Atomical ID - Service queries
get_locationto find the current UTXO owner - User signs a challenge message with the UTXO's private key
- Service verifies signature matches the UTXO owner — identity confirmed
Use Cases
- Authentication: Sign-in with your Realm instead of email/password
- Reputation: On-chain history proves account age and activity
- Cross-platform: Same identity across wallets, marketplaces, and dApps
- Delegation: SubRealms as employee badges or membership cards
Extension: DAO & Governance
Realm hierarchy naturally maps to organizational structures. A DAO can use a Realm as its namespace and SubRealms as membership tokens.
Architecture (Conceptual Design)
+mydao # DAO root (treasury, governance rules)
+mydao.treasury # Treasury management
+mydao.governance # Governance parameters
+mydao.members # Membership namespace
+mydao.members.alice # Member: alice
+mydao.members.bob # Member: bob
+mydao.proposals # Proposals namespace
+mydao.proposals.001 # Proposal #001
+mydao.teams # Teams namespace
+mydao.teams.dev # Development team
+mydao.teams.dev.carol # Team member
Membership via SubRealm Rules
The DAO owner configures SubRealm rules to control membership:
- Free (Bitwork): Open membership — anyone who mines can join
- Paid (Sats): Membership fee paid to DAO treasury address
- Token-gated (ARC20): Require holding specific governance tokens
- Invite-only: Restrict minting to manual approval (no public rules)
Governance Data
Proposals, votes, and configuration could be stored as dynamic state on the Realm. Example design:
{
"governance": {
"voting_period_blocks": 1000,
"quorum_percent": 51,
"treasury_address": "bc1q...treasury"
},
"proposals": {
"active": ["atom:btc:realm:mydao.proposals.001"]
}
}
Extension: Web Hosting on Bitcoin
Realm Names can serve as entry points to Bitcoin-hosted websites and content via the Atom Shuttle concept.
btc:// URL scheme are a community proposal (planned for submission as an Atomicals Improvement Proposal / AIP). This is not yet a finalized protocol standard. The concept is documented at Atomicals Land.
btc:// Protocol (Proposed)
The Atom Shuttle browser gateway concept proposes URLs like:
btc://+myrealm # Homepage
btc://+myrealm/about # About page
btc://+myrealm/blog/post-1 # Blog post
btc://+company.docs/api # API docs at a SubRealm
Hosting Architecture
- Store HTML, CSS, JS files as immutable data on Bitcoin (
datcommand) - Reference files from your Realm's dynamic state using URNs
- Atom Shuttle resolves the Realm name and renders the content
- Updates are made by modifying the Realm's dynamic state to point to new
datfiles
Website Data Structure (Conceptual)
{
"ctx": {
"index": "atom:btc:dat:<data_id>/index.html",
"style": "atom:btc:dat:<data_id>/style.css",
"script": "atom:btc:dat:<data_id>/app.js",
"favicon": "atom:btc:dat:<data_id>/favicon.png"
}
}
Extension: Marketplace & Trading
Realms are NFTs and can be traded on any Atomicals-compatible marketplace using Partially Signed Bitcoin Transactions (PSBTs).
Trading Methods
| Method | Description | Trust Model |
|---|---|---|
| PSBT Atomic Swap | Buyer and seller co-sign a single transaction. Truly trustless. | Trustless |
| Marketplace Listing | List on platforms like atomicalmarket.com that escrow the swap. | Semi-trusted |
| Direct Transfer | Transfer Realm's UTXO directly to a new owner. | Requires trust |
Revenue Model for Realm Owners
Realm owners can generate revenue through SubRealm minting fees:
- Set payment rules requiring BTC or ARC20 tokens
- Tiered pricing based on name length/pattern (short names cost more)
- Split revenue across multiple addresses (e.g., creator + platform)
- Combine with Bitwork for hybrid free/paid models
Extension: Project Trees
Use the Realm hierarchy to model entire project ecosystems, product lines, or content libraries.
Example: Open Source Project
+myproject # Project root
+myproject.docs # Documentation
+myproject.docs.api # API docs
+myproject.docs.guides # User guides
+myproject.releases # Release namespace
+myproject.releases.v1 # Version 1.x
+myproject.releases.v2 # Version 2.x
+myproject.contributors # Contributors
+myproject.contributors.alice # Contributor: alice
+myproject.issues # Issue tracking
+myproject.bounties # Bug bounties
Example: Brand / Enterprise
+brand # Corporate identity
+brand.products # Product catalog
+brand.products.widget-pro # Individual product
+brand.support # Customer support
+brand.loyalty # Loyalty program
+brand.loyalty.gold # Gold tier members
+brand.partners # Partner network
+brand.events # Events and conferences
+brand.events.2025-summit # Specific event
Extension: Token Gating
Use Realm/SubRealm ownership as access control for content, services, and communities.
How It Works
- User connects wallet and presents Realm/SubRealm ownership
- Service verifies on-chain that the user controls the UTXO
- Access is granted based on which Realm hierarchy the user belongs to
Implementation Pattern (Conceptual)
def check_access(realm_client, user_atomical_id, required_parent):
"""Check if user's Realm/SubRealm is under the required parent."""
atomical = realm_client.get_atomical(user_atomical_id)
result = atomical.get("result", {})
# Check if it's a realm or subrealm
realm_name = result.get("$full_realm_name", "")
# Verify it belongs to the required hierarchy
if realm_name.startswith(required_parent + ".") or realm_name == required_parent:
return True # Access granted
return False # Access denied
# Example: Only +mydao.members.* can access
has_access = check_access(client, user_id, "mydao.members")
Access Tiers
| SubRealm Pattern | Access Level | Example |
|---|---|---|
+project.members.* | Basic member | View content, participate |
+project.vip.* | VIP member | Premium features, early access |
+project.team.* | Team member | Admin dashboard, management |
+project (TLR owner) | Owner / Admin | Full control |
Extension: Recursive & Composable Assets
Realms support recursion via the URN system, enabling composable digital assets where one Realm references data from other Atomicals.
Composability with ctx
The ctx field in an Atomical's data is reserved for importing and referencing other Atomicals:
{
"ctx": {
// Import theme from another Realm
"theme": "atom:btc:realm:designsystem/theme.css",
// Reference immutable on-chain image
"logo": "atom:btc:dat:<data_id>/logo.png",
// Import JS library from another Realm
"utils.js": "atom:btc:realm:codelib/utils.js",
// Reference collection metadata
"collection": "atom:btc:container:mycollection $name"
}
}
Use Cases
- Shared design systems: Multiple Realms reference the same theme
- Component libraries: Reusable on-chain code modules
- NFT layering: Compose complex NFTs from multiple on-chain assets
- Version management: Pin to specific versions or always use latest
Resources & Links
Atomicals JS CLI
Official command-line tool for minting and managing Atomicals.
ElectrumX Indexer
Self-host your own Atomicals indexer for production use.
Frequently Asked Questions
What is the cost to mint a Realm?
Minting a top-level Realm requires only the Bitcoin transaction fees (typically 2,000–10,000 sats depending on network conditions) plus CPU time for Bitwork mining. There is no registration fee paid to any centralized entity.
Can I lose my Realm?
No. Realm ownership is tied to a Bitcoin UTXO. As long as you control the private key, you own the Realm forever. There are no renewal fees. The only way to lose it is if someone gains access to your private key or you voluntarily transfer it.
What happens if two people try to mint the same Realm?
The first-is-first candidate system resolves conflicts. The person whose commit transaction appears first in the blockchain wins. After 3 confirmations, the winner's Realm becomes "verified".
How long does Bitwork mining take?
It depends on the prefix length: a 4-character prefix (e.g., "7777") takes seconds on a modern CPU. A 5-character prefix takes minutes. The Atomicals CLI handles mining automatically.
Can SubRealms be nested infinitely?
Yes. There is no protocol limit on nesting depth. +a.b.c.d.e.f.g is valid. Each level is independently owned and can have its own SubRealm rules.
Is ep.atomicals.xyz still working?
No. The ep.atomicals.xyz proxy is offline (DNS unresolvable). Use https://ep.wizz.cash/proxy or run your own ElectrumX node.
Can I update data stored in my Realm?
Yes. Atomicals support dynamic state updates. The owner can modify the Realm's data (profile, settings, files) by broadcasting update transactions. The URN system uses / to reference the latest state and $ for the original mint data.
What wallets support Realm Names?
Currently, Wizz Wallet and OKX Wallet have Atomicals support. The Atomicals CLI tool also functions as a basic wallet for advanced users.
