---
title: "Watch up to 25 wallets and register one webhook (API key; a free key works, 3 wallets)"
method: POST
path: "/api/monitor/subscribe"
tags: ["Monitoring"]
---

# Watch up to 25 wallets and register one webhook (API key; a free key works, 3 wallets)

`POST /api/monitor/subscribe`

## Request

- Base URL: `https://www.xrplhub.io`
- URL: `https://www.xrplhub.io/api/monitor/subscribe`
- Auth: none declared

Body: { addresses: string[≤25], webhookUrl (https, port 443, public hostname), scoreDropPoints? (1–550; omit = no score_drop events — there is NO default threshold), subscriptionId? (add to an existing subscription), acknowledgement: { accepted: true, version } } — the consumer-use acknowledgement (no use for consumer credit/insurance/employment/housing decisions under FCRA/ECOA) is REQUIRED and stored with a timestamp. A test ping is sent first; if it is not answered 2xx nothing is created. The signing secret (X-XRPLHub-Signature: v1=HMAC-SHA256 over '<timestamp>.<body>') is returned ONCE. Events: score_drop, sanctions_hit, sanctions_delisted, first_loan_observed, loan_overdue, loan_impaired, loan_defaulted (the loan events are dormant until XLS-66 activates, then fire automatically) and monitoring_degraded. Attested observations are sparse (baseline / change / event / weekly heartbeat) under the frozen monitor-observation-v1 canon; a score is included only when freshly computed.

## Response `201`

Subscription, one-time webhookSecret, per-wallet baseline status, capabilities, limits.

## Other responses

- `400`: acknowledgement_required, batch_too_large, bad_webhook_url, webhook_ping_failed, bad_request.
- `401`: Missing or invalid API key.
- `403`: watch_slots_exceeded.
- `503`: monitoring_capacity_reached (shared platform limit).

---

[API](https://skmtc.dev/xrplhub/apis/xrplhub-xrplscore-and-prebuilt-xrpl-transactions.md) · [All operations](https://skmtc.dev/xrplhub/apis/xrplhub-xrplscore-and-prebuilt-xrpl-transactions/llms.txt) · [OpenAPI document](https://skmtc.dev/xrplhub/apis/xrplhub-xrplscore-and-prebuilt-xrpl-transactions/revisions/a5d4e13aff32?raw)