Atomicals Wallet Deployment and Private Node Setup: A Simplified Guide

·

Atomicals is a lightweight, flexible protocol designed to mint, transfer, and update digital objects—commonly known as non-fungible tokens (NFTs)—on UTXO-based blockchains like Bitcoin. At its core, an "atom" represents a chain of digital ownership, defined by simple rules that govern how digital assets are created, moved, and modified. This guide walks you through setting up a local Atomicals wallet and deploying a private node for full control over your digital asset interactions.

Prerequisites for Setup

Before diving into the deployment process, ensure your system meets the following software requirements:

👉 Get started with essential developer tools for blockchain projects.

While Node.js is mandatory, VS Code is optional—you can use any terminal or command-line interface. However, using Git and VS Code streamlines future updates via the Source Control > Pull feature when the project evolves.

Cloning and Building the Atomicals-JS Project

Begin by cloning the official atomicals-js repository:

git clone https://github.com/atomicals/atomicals-js.git

Open the project in VS Code:

  1. Click File > New Window
  2. Go to Source Control > Clone Repository, then paste the URL.

Next, open a new terminal:

Now install dependencies and build:

yarn install
yarn build

This completes the initial setup of the atomicals-js environment.

Creating Your Atomicals Wallet

To generate a new wallet, run:

yarn cli wallet-init

This command creates a wallet.json file in your project directory, securely storing your mnemonic phrase and private key. Keep this file encrypted and backed up—losing it means losing access to your assets.

Essential CLI Commands for Interacting with Atomicals

The atomicals-js CLI supports various operations for managing digital assets. Below are commonly used commands:

Mint a Fungible Token (FT)

yarn cli mint-dft dmint --satsbyte 30
Note: The actual on-chain fee is approximately 1.86 sats/vB.

Mint a Realm (Top-Level Digital Namespace)

yarn cli mint-realm "btc" --satsbyte 30 --satsoutput 1000 --bitworkc 3165

Mint an NFT from a Local Image

yarn cli mint-nft "E:\Crypto\NFT\CryptoPunks\punk0000.png" --satsbyte 30 --satsoutput 1000 --bitworkc 3165

Check Wallet Balance

yarn cli balances

For a full list of available commands and parameters, explore dist/cli.js, starting at line 167.

Setting Up a Bitcoin Full Node

To interact directly with the Bitcoin blockchain, you must run a synchronized full node. This section assumes you’ve already installed and synced Bitcoin Core. (A detailed guide on node setup will be covered separately.)

Configure Bitcoin Core for RPC Access

  1. Open Settings > Options in Bitcoin Core.
  2. Click Open Configuration File (bitcoin.conf).

  3. Add the following lines:

    txindex=1
server=1
rpcuser=electrumx
rpcpassword=electrumx
  4. Save with Ctrl + S and restart Bitcoin Core.
⚠️ Remove or comment out any other rpc* settings to avoid conflicts. For simplicity, we use default credentials (electrumx), though production environments should use encrypted, unique values.

Installing Docker

Docker simplifies running services in isolated containers. Download based on your OS:

During installation:

Deploying the Atomicals-ElectrumX Proxy via Docker

We’ll use a pre-built Docker image that includes both atomicals-electrumx and its proxy server.

👉 Learn how containerization enhances blockchain node reliability.

Clone the repository:

git clone https://github.com/Next-DAO/atomicals-electrumx-proxy-docker.git

In VS Code:

  1. Open the cloned folder.
  2. Edit docker-compose.yml

  3. Update the DAEMON_URL line (fifth from bottom) to:

    DAEMON_URL=electrumx:[email protected]:8332
  4. Save with Ctrl + S

This configuration connects the container to your local Bitcoin node using RPC credentials (electrumx:electrumx) at port 8332. The host.docker.internal alias ensures the container can reach your host machine.

Start the services:

docker-compose pull
docker-compose up -d

To stop later:

docker-compose down

Or use the Docker Desktop UI: click the ■ Stop button under Actions.

Syncing with Pre-Built Index Data (Optional but Recommended)

Instead of waiting days for index synchronization, download pre-indexed data via BitTorrent.

Use tools like qBittorrent Enhanced Edition, FDM, or Aria2 to download:

magnet:?xt=urn:btih:7KW5OXSWUQ2EFF57URE42GBRL2XCN5AI

Once downloaded:

  1. Extract the archive using Bandizip or similar.
  2. Place the resulting electrumx-data folder inside the atomicals-electrumx-proxy-docker directory.
  3. Restart Docker: docker-compose down && docker-compose up -d

Check logs to monitor sync progress—initial indexing may take additional time.

Connecting Atomicals-JS to Your Local Node

Return to your atomicals-js project in VS Code:

  1. Open .env (or copy .env.example to .env if missing)

  2. Comment out this line:

    # ELECTRUMX_PROXY_BASE_URL=http://some-remote-url

  3. Add:

    ELECTRUMX_PROXY_BASE_URL=http://localhost:8080/proxy
  4. Save

This tells the CLI to communicate with your locally running ElectrumX proxy on port 8080.

Frequently Asked Questions (FAQ)

Q: How do I know if the Docker service is running properly?
A: Run docker-compose ps. If electrumx shows "healthy", the service is active. If "unhealthy", check logs for messages like INFO:DB:closing DBs to re-open for serving—this indicates finalization before becoming healthy.

Q: Where can I view real-time logs?
A: Open Docker Desktop, select the running container, and click its name (electrumx-1 or proxy-1). Logs show indexing status and proxy activity.

Q: I'm getting “ERROR: Daemon service refused: Unauthorized” — what should I do?
A: This indicates an authentication failure. Double-check:

Q: Can I use this setup on mainnet safely?
A: Yes, but never expose default credentials (electrumx) publicly. For production use, generate strong passwords and enable firewall rules.

Q: Is it possible to run without Docker?
A: Technically yes—by compiling and running ElectrumX manually—but Docker significantly reduces complexity and dependency issues.

Q: How long does full sync take without pre-downloaded data?
A: Depending on hardware and bandwidth, expect several days to over a week for complete indexing of Bitcoin history.

Final Notes and Best Practices

Running your own Atomicals node empowers you with censorship-resistant access to Bitcoin-based digital assets. By controlling both wallet and infrastructure, you eliminate reliance on third-party services.

👉 Discover how self-hosted nodes strengthen decentralization in Web3 ecosystems.

Core Keywords:

With this setup complete, you’re ready to mint, transfer, and manage Atomicals assets directly on Bitcoin—with full ownership and transparency.