SUBTC-CLI V2 — Unified Bitcoin Interface (Testnet & Mainnet)

2026-03-18 permalink SUBTC

#bitcoin #cli #developer-tools #idempotent #mainnet #opensource #payment-api #polling #testnet #webhook

SUBTC-CLI V2 is a unified command-line tool for Bitcoin payments on both testnet and mainnet.

It is:

· Single binary (Go, zero external dependencies) · Idempotent — safe to retry, never double-spend · Multi-network — switch between testnet/mainnet seamlessly · Event-driven — long-poll, webhooks, and polling loops · Curl-first — works with any stack, any language

What's New in V2

Mainnet Support: V1 No, V2 Yes Testnet Support: V1 Yes, V2 Yes Network Switching: V1 No, V2 Yes (config, flag, env) Idempotent Sends: V1 Yes, V2 Yes (enhanced) Webhook Callbacks: V1 No, V2 Yes Configurable Polling: V1 No, V2 Yes (--interval) Mainnet Confirmation: V1 No, V2 Yes (YES prompt) Persistent Config: V1 Limited, V2 Yes (~/.subtc.json)

Quick Start

Build from source: go build -o subtc subtc-cli.go

Create API key: ./subtc key create

Set network (testnet for testing): ./subtc config set-net test

Create wallet: ./subtc wallet create

Generate receive address: ./subtc wallet receive <wallet_id>

Check balance: ./subtc wallet balance <wallet_id>

Send Bitcoin: ./subtc send <wallet_id> 50000

Wait for payment: ./subtc wait <wallet_id> 30000

Poll until confirmed: ./subtc poll <wallet_id> 30000 --loop

Network Control

Set default network: ./subtc config set-net test ./subtc config set-net main

Per-command override: ./subtc --net=main wallet create SUBTC_NET=main ./subtc wallet create

Precedence: flag > env > config

Key Management

./subtc key create # Generate & save new API key ./subtc key status # Verify current key

Example: $ ./subtc key create Key Created ✓ Key saved → ~/.subtc.json

$ ./subtc key status { "ok": true, "result": { "key": "SUBTC-KEY-79821c194c...", "wallet_count": 0 } }

Wallet Operations

./subtc wallet create # New wallet (active network) ./subtc wallet list # List all wallets ./subtc wallet receive <wid> # Generate receive address ./subtc wallet balance <wid> # Check balance

Example: $ ./subtc wallet create Wallet Created · testnet wallet_id: w_acfd7aa7e54f31d533c4f6eed2cf18c9c192957c2f2e

$ ./subtc wallet receive w_acfd7aa7e54f... Receive Address · testnet address: tb1qhcy9w09yk22ppf3fdg6twnjh2zvgarf4zlsw4s

$ ./subtc wallet balance w_acfd7aa7e54f... balance: 191849 sat

Send Bitcoin

Auto idempotency key: ./subtc send <wid> 50000

Custom idempotency key (safe to retry): ./subtc send <wid> 50000 my-unique-id

Rules: Minimum: 50,000 sat Fee: 3% (service + network) Mainnet requires YES confirmation prompt

Example: $ ./subtc send w_acfd7aa7e... tb1qjcr7lc... 50000 Send BTC · testnet ✓ Transaction broadcast txid: 26c264561605408253edec687c2f159f8c6dd0091f03b12b68969892e0086b1d sent_sat: 48500 sat fee_sat: 1500 sat

Inbox (Payment Intent)

Create a pre-configured receive target — perfect for apps, bots, and automation.

./subtc inbox <wallet_id> <expected_sat>

Example: $ ./subtc inbox w_acfd7aa7e... 20000 Inbox · testnet ✓ Inbox ready address: tb1qhcy9w09yk22ppf3fdg6twnjh2zvgarf4zlsw4s expected: 20000 sat

Wait (Long-Poll / Webhook)

Blocking mode: ./subtc wait <wid> 30000 # 300s timeout ./subtc wait <wid> 30000 600 # Custom timeout

Webhook mode: ./subtc wait <wid> 30000 300 https://yourserver.com/webhook

Example: $ ./subtc wait w_acfd7aa7e... tb1qhcy9w09... 30000 Waiting for Funds · testnet ✓ Payment confirmed! received: 191849 sat

Poll (Check & Loop)

Single check: ./subtc poll <wid> 30000

Loop until confirmed: ./subtc poll <wid> 30000 --loop ./subtc poll <wid> 30000 --loop --interval=5

Example: $ ./subtc poll w_acfd7aa7e... tb1qhcy9w09... 30000 --loop Poll · testnet ⏳ received: 191849 sat reached: false ⏳ received: 191849 sat reached: false ✅ received: 191849 sat reached: true ✓ Payment confirmed — stopping loop

Configuration

Commands: ./subtc config show # View current config ./subtc config set-key <key> # Set API key ./subtc config set-net <test|main> # Set default network ./subtc health # Node health status

Config file (~/.subtc.json): { "key": "SUBTC-KEY-79821c194c...", "network": "test" }

Environment override: SUBTC_KEY=xxx ./subtc wallet list SUBTC_NET=main ./subtc wallet create

Example: $ ./subtc config show key: SUBTC-KEY-79•••••••• network: test testnet file: ~/.subtc.json env-override: SUBTC_KEY · SUBTC_NET

$ ./subtc health { "ok": true, "configured": true, "fee_bps": 300, "min_send_sat": 20000 }

Complete Workflow Example

Create key:

./subtc key create

Set network to testnet:

./subtc config set-net test

Create wallet:

./subtc wallet create wallet_id: w_acfd7aa7e54f31d533c4f6eed2cf18c9c192957c2f2e

Generate address:

./subtc wallet receive w_acfd7aa7e... address: tb1qhcy9w09yk22ppf3fdg6twnjh2zvgarf4zlsw4s

Check balance:

./subtc wallet balance w_acfd7aa7e... balance: 191849 sat

Wait for incoming payment:

./subtc wait w_acfd7aa7e... tb1qhcy9w09... 30000 received: 191849 sat

Send BTC:

./subtc send w_acfd7aa7e... tb1qjcr7lc... 50000 ✓ Transaction broadcast txid: 26c2645616...

Check final balance:

./subtc wallet balance w_acfd7aa7e... balance: 91849 sat

Health check:

./subtc health

Show config:

./subtc config show

Why SUBTC-CLI V2 Matters

· Simple for beginners — clear commands, helpful output · Powerful for developers — idempotent, webhooks, polling · Ready for automation — works with scripts, bots, APIs · Zero dependencies — single Go binary · curl-first design — integrate with any stack · Mainnet-safe — confirmation prompts prevent mistakes

Use Cases

· Payment bots (Telegram, Discord, Slack) · Donation systems · Testnet apps & prototyping · Automation scripts · AI agents (coming with V3 Docker support) · Point-of-sale integrations · Recurring payments · Webhook receivers

What's Next (V3 & V4)

V3: Docker containers — ready for AI agents V4: Tor support + .onion endpoints V5: AI agent integration (Open Claw, etc.)

Download & Docs

Download V2: https://subtc.net/post/subtc-cli-v2-unified-bitcoin-cli Full API Reference: https://subtc.net/api LLM-friendly version: https://subtc.net/llms-full.txt GitHub: https://github.com/subtc/SUBTC-CLI-V2-Unified-Bitcoin-CLI-

License

Apache 2.0 — free for commercial and personal use.

Built for Freedom

SUBTC-CLI works everywhere — regardless of geographic restrictions.

Combined with our distributed proxy infrastructure and upcoming Tor support, we're building tools that respect your right to access financial technology.

No borders. No blocks. Just Bitcoin.

One CLI. Both networks. Zero limits.

SUBTC-CLI V2 — Unified Bitcoin Interface (Testnet & Mainnet)

Related Articles