API Reference | SUBTC Protocol

Health

GET health — Node Status

curl -sS "https://api.subtc.net/health"

1 — Key Management

POST key_create

Create a new API key. Store it — required for all subsequent requests.

RESP=$(curl -sS -X POST "https://api.subtc.net/v1/btc?mode=key_create" \ -H "Content-Type: application/json") KEY=$(echo "$RESP" | sed -n 's/.*"key":"$[^"]*$".*/\1/p') echo "KEY=$KEY"

POST key_status

Verify an existing key is valid and active.

curl -sS -X POST "https://api.subtc.net/v1/btc?mode=key_status" \ -H "X-SUBTC-KEY: $KEY" \ -H "Content-Type: application/json"

2 — Wallet

POST wallet_create

Create wallet on mainnet. Returns wallet_id.

RESP=$(curl -sS -X POST "https://api.subtc.net/v1/btc?mode=wallet_create" \ -H "X-SUBTC-KEY: $KEY" \ -H "Content-Type: application/json" \ -d '{"net":"main"}') WID=$(echo "$RESP" | sed -n 's/.*"wallet_id":"$[^"]*$".*/\1/p') echo "WID=$WID"

POST wallet_list

curl -sS -X POST "https://api.subtc.net/v1/btc?mode=wallet_list" \ -H "X-SUBTC-KEY: $KEY" \ -H "Content-Type: application/json"

POST wallet_receive — Generate Address

RESP=$(curl -sS -X POST "https://api.subtc.net/v1/btc?mode=wallet_receive" \ -H "X-SUBTC-KEY: $KEY" \ -H "Content-Type: application/json" \ -d "{\"wallet_id\":\"$WID\"}") ADDR=$(echo "$RESP" | sed -n 's/.*"address":"$[^"]*$".*/\1/p') echo "ADDR=$ADDR"

POST wallet_balance

curl -sS -X POST "https://api.subtc.net/v1/btc?mode=wallet_balance" \ -H "X-SUBTC-KEY: $KEY" \ -H "Content-Type: application/json" \ -d "{\"wallet_id\":\"$WID\"}"

3 — Send

POST wallet_send — Idempotent Send

Safe to retry. Same X-SUBTC-IDEMPOTENCY = same tx, no double-spend.

curl -sS -X POST "https://api.subtc.net/v1/btc?mode=wallet_send" \ -H "X-SUBTC-KEY: $KEY" \ -H "X-SUBTC-IDEMPOTENCY: send-$(date +%s)" \ -H "Content-Type: application/json" \ -d "{\"wallet_id\":\"$WID\",\"to\":\"bc1qDESTINATION\",\"amount_sat\":50000}"

4 — Inbox

POST inbox_create — Pre-configured Receive

Creates a ready inbox waiting for a specific amount.

curl -sS -X POST "https://api.subtc.net/v1/btc?mode=inbox_create" \ -H "X-SUBTC-KEY: $KEY" \ -H "Content-Type: application/json" \ -d "{\"wallet_id\":\"$WID\",\"expected_sat\":20000}"

5 — Wait for Funds

POST wallet_wait_event — Long Poll

Blocks until expected_sat arrives or timeout. Best for server-to-server.

curl -sS -X POST "https://api.subtc.net/v1/btc?mode=wallet_wait_event" \ -H "X-SUBTC-KEY: $KEY" \ -H "Content-Type: application/json" \ -d "{\"wallet_id\":\"$WID\",\"address\":\"$ADDR\",\"expected_sat\":20000,\"timeout_sec\":300}"

POST wallet_wait_event — Webhook

SUBTC calls your server when funds arrive. Fire and forget.

curl -sS -X POST "https://api.subtc.net/v1/btc?mode=wallet_wait_event" \ -H "X-SUBTC-KEY: $KEY" \ -H "Content-Type: application/json" \ -d "{\"wallet_id\":\"$WID\",\"address\":\"$ADDR\",\"expected_sat\":20000,\"timeout_sec\":600,\"callback_url\":\"https://yourserver.com/webhook\"}"

6 — Poll

POST wallet_poll — Single Check

curl -sS -X POST "https://api.subtc.net/v1/btc?mode=wallet_poll" \ -H "X-SUBTC-KEY: $KEY" \ -H "Content-Type: application/json" \ -d "{\"wallet_id\":\"$WID\",\"address\":\"$ADDR\",\"expected_sat\":20000}"

POST wallet_poll — Loop

Pull-based. Returns reached:true when threshold met.

while true; do RESP=$(curl -sS -X POST "https://api.subtc.net/v1/btc?mode=wallet_poll" \ -H "X-SUBTC-KEY: $KEY" \ -H "Content-Type: application/json" \ -d "{\"wallet_id\":\"$WID\",\"address\":\"$ADDR\",\"expected_sat\":20000}") REACHED=$(echo "$RESP" | sed -n 's/.*"reached":$[a-z]*$.*/\1/p') RECEIVED=$(echo "$RESP" | sed -n 's/.*"received_sat":$[0-9]*$.*/\1/p') echo "received=$RECEIVED reached=$REACHED" [ "$REACHED" = "true" ] && echo "✅ confirmed" && break sleep 3 done

7 — Units & Fees

Network	Min Send	Fee	1 BTC
mainnet	50,000 SAT	3%	100,000,000 SAT
testnet	50,000 SAT	3%	100,000,000 SAT

Integer atomic units only — no floats. Deterministic fee calculation. Idempotency guaranteed via X-SUBTC-IDEMPOTENCY.

SUBTC Protocol — Bitcoin curl API