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.

💡
Key Insight: Realms are NFTs on Bitcoin. They are Atomicals Digital Objects with special naming properties. Every Realm is an NFT, but not every NFT is a Realm. This means Realms can carry attached data, state, files, and dynamic content — making them far more than just names.

Realm vs. Traditional Domain Names

FeatureRealm Names (RNS)DNS (Traditional)ENS (Ethereum)
BlockchainBitcoin (Layer 1)N/A (Centralized)Ethereum
OwnershipPermanent, self-sovereignRented annuallyRented annually
Format+namename.comname.eth
RegistrarNone (protocol-enforced)ICANN accreditedENS DAO
Sub-domainsInfinite hierarchy, owner-controlled rulesManaged by registrarLimited support
Data StorageOn-chain files, state, profilesDNS records onlyLimited records
PaymentBuilt-in Payname systemN/AVia resolver
TransferableYes (Bitcoin tx)Via registrarYes (ERC-721)

Quick Start

Get up and running in minutes. Choose your preferred path:

Install the Atomicals CLI

bash
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

bash (cURL)
# 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

python
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:

Source: atomical-format-helpers.ts
// 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
RuleDescriptionExample
PrefixAlways starts with ++alice
CharactersLowercase a-z, digits 0-9, hyphens -+my-realm-01
Min lengthAt least 1 character+a
Max lengthUp to 64 characters+a-very-long-name...
TLR startTop-level Realm must start with a letter (a-z)+alice ✔ / +007a
SubRealm startSubRealms can start with a letter or digit+realm.007
HyphensCannot begin or end with a hyphen+a-b ✔ / +-ab
CaseAlways lowercase (auto-converted)+Alice+alice

Hierarchy Structure

Realms use a dot-separated hierarchy, similar to DNS but with more powerful semantics:

Hierarchy Example
+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:

STEP 1
Commit TX
STEP 2
Reveal TX
STEP 3
3 Confirmations
STEP 4
Verified ✔

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.

Important: Only the commit transaction's block position determines the winner. A faster reveal or higher fee does not help if someone else's commit was included in an earlier block.

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:

STEP 1
Mint Claim
commit+reveal
STEP 2
Wait 4 Blocks
confirm candidate
STEP 3
Make Payment
within 11 blocks
STEP 4
Verified ✔
~15 blocks total
Fee Warning: Use a fee rate at least 50-100% higher than prevailing network conditions for the payment transaction. If the payment doesn't confirm within the 15-block window, another candidate can take the SubRealm.

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:

Bitwork Examples
# "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 ValueMeaningDifficulty Multiplier
"7777"First 4 hex chars must be 77771x (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 7777716x

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

TypeFieldApplied To
Commit BitworkbitworkcThe commit transaction hash must match the prefix
Reveal BitworkbitworkrThe 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

JSON — rules.json
{
  "subrealms": {
    "rules": [
      {
        "p": "^[a-z0-9]{6,64}$",
        "bitworkc": "8888.8"
      },
      {
        "p": ".*",
        "o": {
          "5120a976...90e4": {
            "v": 10000
          }
        }
      }
    ]
  }
}

Rule Fields Reference

FieldTypeDescription
pString (regex)Python 3.9 regex pattern. Matches the SubRealm name in full string mode (start to end).
bitworkcStringRequired Bitwork prefix for the commit transaction.
bitworkrStringRequired Bitwork prefix for the reveal transaction.
oObjectOutput payment requirements. Keys are hex-encoded output scripts, values specify amounts.
o.{script}.vNumberSatoshi amount to pay to this output script.
o.{script}.idStringARC20 token Atomical ID for token-based payment.

Pattern Matching Examples

Regex Patterns
".*"                 # 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:

JSON — tiered-rules.json
{
  "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

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

JSON — Payname Configuration
{
  "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:

JSON — Delegation
{
  "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

URN Syntax
atom:<chain>:<ref_type>:<identifier> [$ or /[file]]

# $ = original mint data (immutable)
# / = latest dynamic data (mutable)

Reference Types

TypeExampleDescription
idatom:btc:id:<atomical_id>Reference by Atomical ID
realmatom:btc:realm:myrealmReference by Realm name
containeratom:btc:container:mycolReference by Container name
datatom:btc:dat:<data_id>/img.pngImmutable data file reference
arcatom:btc:arc:<ticker>Reference by ARC20 ticker

Realm-Specific URN Examples

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

Active Public Proxy
https://ep.wizz.cash/proxy
Deprecated: 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

HTTP GET
GET /proxy/<method>?params=["value1","value2"]

Parameters are passed as a JSON-encoded array in the params query string.

HTTP POST
POST /proxy/<method>
Content-Type: application/json

{
  "params": ["value1", "value2"]
}

Response Format

JSON Response
{
  "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.

GET
/proxy/blockchain.atomicals.get_by_realm
Params: [realm_name] — Returns status, atomical_id, candidates
ParamTypeDescription
realm_namestringThe realm name to look up (without + prefix)
Response FieldDescription
status"verified" if claimed, otherwise "pending" or empty candidates
atomical_idThe verified Atomical ID (null if not verified)
candidate_atomical_idLeading candidate even if not yet verified
candidatesArray of all candidates with commit_height, txid, etc.
typeAlways "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.

GET
/proxy/blockchain.atomicals.get_realm_info
Params: [full_name] — Returns full hierarchy path, rules, candidates
ParamTypeDescription
full_namestringFull realm path, e.g. "myrealm" or "myrealm.sub"
Response FieldDescription
atomical_idFound Atomical ID (null if not found)
top_level_realm_atomical_idThe TLR's Atomical ID
top_level_realm_nameThe TLR name
nearest_parent_realm_atomical_idClosest existing parent in the path
request_full_realm_nameExactly what was queried
found_full_realm_nameThe deepest existing path found
missing_name_partsParts of the path that don't exist yet
nearest_parent_realm_subrealm_mint_allowedWhether the parent allows SubRealm minting
nearest_parent_realm_subrealm_mint_rulesActive minting rules (if any)

blockchain.atomicals.get_by_subrealm

Query a specific SubRealm by its parent and name.

GET
/proxy/blockchain.atomicals.get_by_subrealm
Params: [parent_atomical_id, subrealm_name]

blockchain.atomicals.find_realms

Search for Realms by name prefix.

GET
/proxy/blockchain.atomicals.find_realms
Params: [prefix, reverse, limit, offset, is_verified_only]
ParamTypeDefaultDescription
prefixstringnullName prefix to search
reverseboolfalseReverse ordering
limitint100Max results to return
offsetint0Pagination offset
is_verified_onlyboolfalseOnly return verified realms

blockchain.atomicals.find_subrealms

Search SubRealms under a given parent.

GET
/proxy/blockchain.atomicals.find_subrealms
Params: [parent_atomical_id, prefix, reverse, limit, offset, is_verified_only]

blockchain.atomicals.get

Get full details of any Atomical by its ID or number.

GET
/proxy/blockchain.atomicals.get
Params: [compact_atomical_id_or_number] — Returns full Atomical details

Complete API Endpoint Reference

All available endpoints on the Atomicals ElectrumX HTTP proxy:

Realm & Name Endpoints

GET
blockchain.atomicals.get_by_realm
Look up a top-level realm by name
GET
blockchain.atomicals.get_by_subrealm
Look up a subrealm by parent ID and name
GET
blockchain.atomicals.get_realm_info
Get comprehensive realm info with hierarchy resolution
GET
blockchain.atomicals.find_realms
Search realms by name prefix
GET
blockchain.atomicals.find_subrealms
Search subrealms under a parent

Atomical Query Endpoints

GET
blockchain.atomicals.get
Get full Atomical details by ID or number
GET
blockchain.atomicals.get_location
Get current UTXO location of an Atomical
GET
blockchain.atomicals.get_state
Get current dynamic state of an Atomical
GET
blockchain.atomicals.get_state_history
Get full state modification history
GET
blockchain.atomicals.get_events
Get event log for an Atomical
GET
blockchain.atomicals.get_tx_history
Get transaction history of an Atomical
GET
blockchain.atomicals.at_location
Get all Atomicals at a specific UTXO location

Token & Container Endpoints

GET
blockchain.atomicals.get_by_ticker
Look up ARC20 token by ticker name
GET
blockchain.atomicals.find_tickers
Search ARC20 tickers by prefix
GET
blockchain.atomicals.get_ft_info
Get fungible token details
GET
blockchain.atomicals.get_dft_mints
Get decentralized mint history
GET
blockchain.atomicals.get_by_container
Look up container by name
GET
blockchain.atomicals.get_by_container_item
Look up a specific item in a container
GET
blockchain.atomicals.find_containers
Search containers by name prefix
GET
blockchain.atomicals.get_container_items
List items in a container (paginated)

Address & Balance Endpoints

GET
blockchain.atomicals.listscripthash
List all Atomical UTXOs for an address scripthash
GET
blockchain.atomicals.get_ft_balances_scripthash
Get FT (fungible token) balances for an address
GET
blockchain.atomicals.get_nft_balances_scripthash
Get NFT balances for an address
GET
blockchain.atomicals.get_holders
Get holder list for an Atomical

Global & Block Endpoints

GET
blockchain.atomicals.get_global
Get global summary (block height, counts, hashes)
GET
blockchain.atomicals.list
List Atomicals (paginated)
GET
blockchain.atomicals.get_numbers
Get Atomical number-to-ID mapping
GET
blockchain.atomicals.get_block_hash
Get block hash at height
GET
blockchain.atomicals.get_block_txs
Get Atomicals transactions in a block

Transaction & Validation Endpoints

POST
blockchain.atomicals.validate
Validate and broadcast a transaction
POST
blockchain.atomicals.decode_tx
Decode a raw transaction for Atomicals operations
POST
blockchain.atomicals.validate_psbt_blueprint
Validate a PSBT blueprint
GET
blockchain.atomicals.transaction
Get Atomicals transaction details

API Playground

Test the Realm APIs directly from your browser. All requests go to the public Wizz Cash proxy.

GET blockchain.atomicals.get_by_realm
GET blockchain.atomicals.get_realm_info
GET blockchain.atomicals.find_realms
GET blockchain.atomicals.get
GET blockchain.atomicals.get_global

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

bash
git clone https://github.com/atomicals/atomicals-js.git
cd atomicals-js
yarn install
yarn run build

Step 2: Initialize Your Wallet

bash
yarn cli wallet-init

This creates a wallet.json with a new P2TR (Taproot) address. Back up the mnemonic phrase securely!

Security: Never share your wallet.json or mnemonic phrase. Only fund the wallet with amounts you can afford to lose during beta.

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

bash
# 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

bash
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)

bash
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

bash
curl -s "https://ep.wizz.cash/proxy/blockchain.atomicals.get_by_realm?params=%5B%22bitcoin%22%5D" | python3 -m json.tool

Interpreting the Response

json
{
  "success": true,
  "response": {
    "result": {
      "status": "verified",       // "verified" = claimed
      "atomical_id": "abc15f...i0", // non-null = exists
      "type": "realm"
    }
  }
}

Decision Logic

ConditionMeaning
status == "verified" && atomical_id != nullRealm is taken and confirmed
status == "pending"Someone has claimed but not yet confirmed (wait 3 blocks)
candidates is emptyRealm 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

rules.json
{
  "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

bash
yarn cli enable-subrealms +myrealm rules.json --satsbyte=100

Step 3: Verify Rules Are Active

bash
yarn cli realm-info myrealm

Convert Between Addresses and Scripts

bash
# 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

bash
yarn cli realm-info myrealm.mysubrealm

Step 2: Mint the SubRealm

bash
yarn cli mint-subrealm +myrealm.mysubrealm --satsbyte=100

Step 3: Make Payment (if required)

bash
# Check pending subrealms that need payment
yarn cli pending-subrealms

# Follow on-screen instructions to complete payment
💡
Payment Window: After your claim is confirmed (4 blocks), you have 11 additional blocks (~110 minutes) to make the payment. Total window: 15 blocks from the original commit transaction.

Tutorial 5: Python Integration

A complete Python module for interacting with the Realm API.

python — realm_client.py
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.

javascript — realmClient.js
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

Note on Extensions: The following Extension sections describe conceptual designs and illustrative examples of what can be built with the Realm Name System. The JSON structures, data models, and implementation patterns shown here are not official protocol specifications — they are practical design proposals based on the protocol's capabilities. Actual implementations may vary.

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:

JSON — Profile Data (Illustrative Example)
{
  "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

  1. User presents their Realm name: +alice
  2. Service queries get_by_realm("alice") to get the Atomical ID
  3. Service queries get_location to find the current UTXO owner
  4. User signs a challenge message with the UTXO's private key
  5. 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)

DAO Structure (Illustrative Example)
+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:

JSON — Governance State (Illustrative Example)
{
  "governance": {
    "voting_period_blocks": 1000,
    "quorum_percent": 51,
    "treasury_address": "bc1q...treasury"
  },
  "proposals": {
    "active": ["atom:btc:realm:mydao.proposals.001"]
  }
}

Extension: Social Profiles

Build decentralized social applications where every user has a verifiable Bitcoin-native identity.

Profile Integration with Realm App

Realm App is an existing social application built on Atomicals SubRealms. Users:

  1. Connect their Wizz or OKX wallet
  2. Select a SubRealm as their profile identity
  3. The app verifies ownership through on-chain verification
  4. Users can post, interact, and build reputation under their Realm identity

Social Data Model (Conceptual)

JSON — Social Profile (Illustrative Example)
{
  "profile": {
    "display_name": "Alice",
    "bio": "Exploring the Bitcoin metaverse",
    "avatar": "atom:btc:dat:<id>/avatar.png",
    "banner": "atom:btc:dat:<id>/banner.jpg"
  },
  "social": {
    "following": ["atom:btc:realm:bob", "atom:btc:realm:carol"],
    "posts_ref": "atom:btc:id:<atomical_id>/posts"
  }
}

Extension: Web Hosting on Bitcoin

Realm Names can serve as entry points to Bitcoin-hosted websites and content via the Atom Shuttle concept.

💡
Status: Atom Shuttle and the 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:// URLs
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

  1. Store HTML, CSS, JS files as immutable data on Bitcoin (dat command)
  2. Reference files from your Realm's dynamic state using URNs
  3. Atom Shuttle resolves the Realm name and renders the content
  4. Updates are made by modifying the Realm's dynamic state to point to new dat files

Website Data Structure (Conceptual)

JSON — Web Hosting Config (Illustrative Example)
{
  "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

MethodDescriptionTrust Model
PSBT Atomic SwapBuyer and seller co-sign a single transaction. Truly trustless.Trustless
Marketplace ListingList on platforms like atomicalmarket.com that escrow the swap.Semi-trusted
Direct TransferTransfer 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

Project Tree
+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

Enterprise Tree
+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

  1. User connects wallet and presents Realm/SubRealm ownership
  2. Service verifies on-chain that the user controls the UTXO
  3. Access is granted based on which Realm hierarchy the user belongs to

Implementation Pattern (Conceptual)

python — Token Gating Check (Illustrative Example)
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 PatternAccess LevelExample
+project.members.*Basic memberView content, participate
+project.vip.*VIP memberPremium features, early access
+project.team.*Team memberAdmin dashboard, management
+project (TLR owner)Owner / AdminFull 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:

JSON — Recursive References
{
  "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.

github.com/atomicals/atomicals-js

🔌

ElectrumX Indexer

Self-host your own Atomicals indexer for production use.

github.com/atomicals/atomicals-electrumx

📖

Protocol Guide

Official Atomicals Protocol documentation and specification.

Atomicals Guide

🌐

Realm Name Explorer

Search and browse registered Realm names.

realm.name

💰

Wizz Wallet

Browser wallet with Atomicals support and public API proxy.

wizz.cash

💬

Realm Social App

Bitcoin-native social application built on Realm SubRealms.

realmapp.pro

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.

Realm Name Docs — Comprehensive documentation for the Atomicals Realm Name System on Bitcoin.

GitHub · Realm Explorer · Protocol Guide · Wizz Wallet

Built for the Bitcoin community. Not affiliated with or endorsed by any specific project.
API Proxy: https://ep.wizz.cash/proxy — provided by Wizz Wallet team.

AI Assistant ×