Poll a BTC Mainnet Address for Payment Status

2026-03-16 permalink SUBTC

SUBTC provides wallet_poll for a single instant check of a payment condition.
Unlike wallet_wait_event, this request does not block or wait.

Command:

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}"

Example response:

{
 "ok": true,
 "request_id": "e260b6197a84badc",
 "result": {
  "address": "bc1q59ct7xwn0qa7kl722vdedaa2ajzkmmu78gm9jl",
  "coin": "btc",
  "net": "main",
  "expected_sat": 20000,
  "received_sat": 30000,
  "reached": true,
  "wallet_id": "w_87d2a561cdd665948c1d756106f7b2179327927c3b8c"
 }
}

What happened:

The gateway checked the wallet address once.

Expected payment:
20,000 SAT

Detected payment:
30,000 SAT

Because the received amount is greater than the expected amount, the API returned:

reached = true

Developers commonly use wallet_poll inside background jobs, loops, or cron checks.

API Base:
https://subtc.net/api

Poll a BTC Mainnet Address for Payment Status

Related Articles