DEVELOPMENT

BTC Node Agent

Run your own Bitcoin Core node and use it for your own wallet operations — full sovereignty, no dependency on the platform's node.
1. WHAT IS THE BTC NODE AGENT

A lightweight container that runs Bitcoin Core (mainnet and testnet) plus a small agent process. The agent polls the SOBTC protocol for wallet operations tied to your identity and executes them against your own node — your keys never leave your server.

WHY RUN YOUR OWN NODE
No reliance on the platform's node for your own wallet operations. Your own peers, your own mempool view, your own uptime.
2. INSTALLATION

One command on any server with Docker (or where Docker can be installed):

RECOMMENDED OS
Tested and recommended on Ubuntu 24.04 LTS. Other distros may work but aren't verified against this installer.
curl -fsSL https://sobtc.net/install.sh | bash
01
Checks requirements
Installs Docker/Go if either is missing, then downloads and builds the agent
02
Asks for your identity
BTC_ID, PRIVATE_KEY, PUBLIC_KEY — shown once at /create
03
Asks for RPC_SECRET
Links this node to your identity for wallet operations. Bundled automatically at /create, or generate one anytime at /i/rpc
04
Asks for NODE_USER (optional)
Separate credential, only for status reporting — generate it at /i/node-license. Skip it and add it later if you prefer
05
Builds and starts
The container starts syncing both networks immediately
DECOMMISSIONING A NODE
RPC_SECRET can be revoked anytime at /i/rpc — it immediately stops that node from running wallet operations for your account. Necessary before retiring a server, or if you suspect a secret was exposed.
CREATING A NEW WALLET
If a node ever gets rebuilt from scratch, its old wallet file won't exist anymore even though the account record does. Create a fresh mainnet + testnet pair anytime at /i/wid — older sets stay available to switch back to, never deleted. Limited to one rotation every 15 days.
3. VERIFY IT'S SYNCED

Initial sync takes time — check progress anytime from the server:

docker exec btc-node-agent /scripts/status.sh
4. SWITCH TO YOUR OWN NODE

Order matters here. Install, let it fully sync, and confirm the link is active — before switching in BTC Core. Switching to a node that isn't up yet just means your wallet operations sit waiting on a node that can't answer.

✓ Node fully synced (both networks) — check with the command above
✓ RPC_SECRET linked — confirmed if /i/rpc shows "already generated"
✓ Only then — open BTC Core and use SWITCH TO MY OWN NODE
5. MONITOR YOUR NODE

Once synced and linked, your node sends a self-reported status heartbeat on its own schedule — no need to keep checking manually.

NODE STATUS PAGE
Sync state, RPC connectivity, and server health (RAM/swap, CPU load, disk) — self-reported from your own node, not a guess from the platform. Check it anytime at /i/status.
OPEN BTC CORE →
RPC License Node License API Docs