# Register a transaction for merkle proof delivery.

> For the complete documentation index, see [llms.txt](https://bsvblockchain.com/docs/llms.txt).

**POST** `/watch`

Base URL: `http://{host}:{port}`

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

Content type: `application/json`

- `txid` (string, required)
  Transaction ID of the Bitcoin transaction to monitor.
  Must be a 64-character lowercase or uppercase hexadecimal string.
- `callbackUrl` (string<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.

Example:

```json
{
  "txid": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2",
  "callbackUrl": "https://example.com/callback"
}
```

## Responses

### 200

Registration accepted.

- `status` ("ok", required)
  Indicates successful registration.
- `message` (string, required)
  Human-readable confirmation message.

Example:

```json
{
  "status": "ok",
  "message": "registration successful"
}
```

### 400

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

- `error` (string, required)
  Human-readable description of the error.

Example:

```json
{
  "error": "invalid txid format: must be a 64-character hex string"
}
```

### 500

Storage failure or other internal error.

- `error` (string, required)
  Human-readable description of the error.

Example:

```json
{
  "error": "invalid txid format: must be a 64-character hex string"
}
```