BSV blockchainBSV blockchain

Register a transaction for merkle proof delivery.

POST/watch

Registers a transaction ID (txid) for merkle proof monitoring. When the merkle proof for the transaction becomes available (i.e. the transaction is confirmed in a block), the service delivers the proof to the supplied callbackUrl via HTTP POST.

Idempotency: Registering the same txid with the same callbackUrl more than once is safe; subsequent registrations are deduplicated by the store.

Validation errors: The service validates both the txid format (must be a 64-character hex string) and the callbackUrl format (must be a valid HTTP or HTTPS URL). Invalid input returns 400 with a JSON error object.

Body application/json

txidstringrequired

Transaction ID of the Bitcoin transaction to monitor. Must be a 64-character lowercase or uppercase hexadecimal string.

callbackUrlstring<uri>required

HTTP or HTTPS URL that will receive the merkle proof when it becomes available. The service issues an HTTP POST to this URL with the proof payload.

Response

Registration accepted.

status"ok"

Indicates successful registration.

messagestring

Human-readable confirmation message.

Validation failure. Possible error messages:

  • "txid is required"
  • "invalid txid format: must be a 64-character hex string"
  • "callbackUrl is required"
  • "invalid callbackUrl: must be a valid HTTP/HTTPS URL"
  • "invalid request body"
errorstring

Human-readable description of the error.

Storage failure or other internal error.

errorstring

Human-readable description of the error.

Request
curl -X POST "http://{host}:{port}/watch" \
  -H "Content-Type: application/json" \
  -d '{
  "txid": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2",
  "callbackUrl": "https://example.com/callback"
}'
Response
{
  "status": "ok",
  "message": "registration successful"
}