Getting Started

Getting Started

This guide shows the fastest way to run brc721 against Bitcoin mainnet. Regtest/testnet workflows are still possible, but the focus here is operating the daemon with a real node.

Prerequisites

• Rust toolchain via rustup (stable 1.78+). Verify with rustc --version.
• Cargo (bundled with rustup) plus a C compiler and SQLite headers (build-essential, libsqlite3-dev, etc.).
• Either:
  • Bitcoin Core v26+ installed locally, or
  • Docker + Docker Compose to run the bundled containers.
• curl for quick REST checks (optional but handy).

Native Quickstart (Mainnet)

1. Clone and enter the repo

   git clone https://github.com/laosfoundation/brc721.git
   cd brc721

2. Ensure Bitcoin Core mainnet is running
   • If you already operate a node, make sure RPC is reachable and has -txindex=1 enabled.
   • To start a fresh local node:

     bitcoind -daemon \
       -server=1 -txindex=1 \
       -rpcbind=127.0.0.1 -rpcallowip=127.0.0.1 \
       -rpcuser=brc721 -rpcpassword=change-me

     Wait for it to sync (or connect to a trusted remote node over LAN/VPN).
3. Create a .env with RPC details

   BITCOIN_RPC_URL=http://127.0.0.1:8332
   BITCOIN_RPC_USER=brc721
   BITCOIN_RPC_PASS=change-me
   # Optional overrides:
   # BRC721_START_BLOCK=923580
   # BRC721_LOG_FILE=/var/log/brc721/mainnet.log

4. Run the daemon (no subcommand)

   cargo run --release

   • Running brc721 with no subcommand starts the scanner and REST API.
   • Wallet and tx commands are one-shot subcommands and do not start the daemon.
5. Verify it works

   curl -s http://127.0.0.1:8083/health
   curl -s http://127.0.0.1:8083/state

Docker Quickstart (Mainnet)

1. Start the stack

   docker compose up -d
   docker compose logs -f app

   • bitcoin-mainnet syncs the chain and exposes RPC to the app container.
   • app runs brc721 and publishes the REST API on 127.0.0.1:8083.
2. Stop it later

   docker compose down

   Add -v if you also want to delete the bitcoind data volume (be careful on mainnet).

Next Steps

• Initialize a wallet with brc721 wallet init.
• Register collections or ownership, or send assets using the tx commands.
• See Wallet Guide and Protocol Messages for details.