SUBTC-CLI V2 — Unified Bitcoin Interface (Testnet & Mainnet)
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> <address> 50000
Wait for payment:
./subtc wait <wallet_id> <address> 30000
Poll until confirmed:
./subtc poll <wallet_id> <address> 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> <addr> 50000
Custom idempotency key (safe to retry):
./subtc send <wid> <addr> 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> <addr> 30000 # 300s timeout
./subtc wait <wid> <addr> 30000 600 # Custom timeout
Webhook mode:
./subtc wait <wid> <addr> 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> <addr> 30000
Loop until confirmed:
./subtc poll <wid> <addr> 30000 --loop
./subtc poll <wid> <addr> 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
1. Create key:
./subtc key create
2. Set network to testnet:
./subtc config set-net test
3. Create wallet:
./subtc wallet create
wallet_id: w_acfd7aa7e54f31d533c4f6eed2cf18c9c192957c2f2e
4. Generate address:
./subtc wallet receive w_acfd7aa7e...
address: tb1qhcy9w09yk22ppf3fdg6twnjh2zvgarf4zlsw4s
5. Check balance:
./subtc wallet balance w_acfd7aa7e...
balance: 191849 sat
6. Wait for incoming payment:
./subtc wait w_acfd7aa7e... tb1qhcy9w09... 30000
received: 191849 sat
7. Send BTC:
./subtc send w_acfd7aa7e... tb1qjcr7lc... 50000
✓ Transaction broadcast
txid: 26c2645616...
8. Check final balance:
./subtc wallet balance w_acfd7aa7e...
balance: 91849 sat
9. Health check:
./subtc health
10. 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.