Public API · Address Watch

Address Watch

Address Watch lets you subscribe to on-chain address activity, list events, and configure a delivery webhook. All routes require signed headers (see Authentication). Base: https://api.rpcnode.dev — paths start with /v1/address-watch/… (no /api). Success responses use ok: true plus the fields below.

addresseseventswebhookAddress Watch

← Public API

GET /v1/address-watch/account

Address Watch account: slot usage and current webhook URL / enabled flag.

Response fields

Name	Type	Description
account.user_id	number	Merchant user id.
account.webhook_address_slots	number	Plan cap for concurrent watched addresses.
account.address_slots_used	number	Number of watched addresses currently in use.
account.webhook_url	string \| null	Configured webhook URL, or null.
account.webhook_enabled	boolean	Whether outbound webhook delivery is enabled.

Response example

{
  "ok": true,
  "account": {
    "user_id": 1,
    "webhook_address_slots": 10,
    "address_slots_used": 2,
    "webhook_url": "https://example.com/hooks/address-watch",
    "webhook_enabled": true
  }
}

GET /v1/address-watch/addresses

List watched addresses (paginated). Filter by network and/or address prefix.

Query parameters

Name	Type	Description
network_slug	string	Exact network slug (normalized lowercase), e.g. ethereum. (optional)
address	string	Case-insensitive prefix after the same normalization as add (0x… lowercased). Example: 0xabc matches 0xabcdef… (optional)
page	integer	Page number (default 1). (optional)
per_page	integer	Page size 1–200 (default 50). (optional)

Response fields

Name	Type	Description
items[].id	number	Internal id.
items[].watch_id	string	Public watch identifier.
items[].network_slug	string	Network slug.
items[].address	string	Watched address.
items[].status	string	Watch status.
items[].created_at	string	Creation timestamp.
pagination.page	number	Current page.
pagination.per_page	number	Page size.
pagination.total	number	Total matching rows.
pagination.has_more	boolean	True if more pages exist.

Query string is not part of the signature — sign path /v1/address-watch/addresses with an empty body.
Response uses items + pagination (not a bare addresses array).

Response example

{
  "ok": true,
  "items": [
    {
      "id": 1,
      "watch_id": "aw_…",
      "network_slug": "ethereum",
      "address": "0x…",
      "status": "active",
      "created_at": "2026-01-01T00:00:00+00:00"
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 50,
    "total": 120,
    "has_more": true
  }
}

POST /v1/address-watch/addresses

Start watching an address on a network. Consumes one address slot.

Request body

Name	Type	Description
network_slug	string	Address Watch ingest key (max 80). Mainnet: base catalog slug (ethereum). Other envs: {network}-{env} (ethereum-sepolia).
address	string	Address to watch (max 255).

Response fields

Name	Type	Description
address	object	Same shape as list item (id, watch_id, …).

Mainnet watches use the base catalog slug (ethereum). Sepolia / other envs use a composite key (ethereum-sepolia) that must match a watch:targets field to be ingested.

Response example

{
  "ok": true,
  "address": {
    "id": 1,
    "watch_id": "aw_…",
    "network_slug": "ethereum",
    "address": "0x…",
    "status": "active",
    "created_at": "2026-01-01T00:00:00+00:00"
  }
}

DELETE /v1/address-watch/addresses

Stop watching an address. Pass watch_id in the JSON body (not the query string).

Request body

Name	Type	Description
watch_id	string	Watch id from list/add (max 64).

Include Content-Type: application/json and sign the raw body.
Success returns ok: true with no extra fields.

Response example

{
  "ok": true
}

GET /v1/address-watch/events

List recorded address-activity events (paginated). Hit payload fields are flattened onto each event (no nested payload).

Query parameters

Name	Type	Description
watch_id	string	Filter by watch id (max 64). (optional)
network_slug	string	Filter by network (max 80). (optional)
address	string	Filter by address (max 255). (optional)
page	integer	Page number (default 1). (optional)
per_page	integer	Page size 1–200 (default 50). (optional)

Response fields

Name	Type	Description
items[].id	number	Event id.
items[].watch_id	string	Related watch id.
items[].network_slug	string	Network slug.
items[].address	string	Address.
items[].tx_hash	string	Transaction hash.
items[].block_height	number	Block height.
items[].type	string	Event type: payment \| payout \| other \| block.
items[].direction	string	Direction (e.g. in / out).
items[].created_at	string	Creation timestamp.
pagination.page	number	Current page.
pagination.per_page	number	Page size.
pagination.total	number	Total matching rows.
pagination.has_more	boolean	True if more pages exist.

Query string is not part of the signature — sign path /v1/address-watch/events with an empty body.
type, direction, and other hit fields are top-level on each item (same shape as outbound webhooks).

Response example

{
  "ok": true,
  "items": [
    {
      "id": 100,
      "watch_id": "aw_…",
      "network_slug": "ethereum",
      "address": "0x…",
      "tx_hash": "0x…",
      "block_height": 12345678,
      "type": "payment",
      "direction": "in",
      "created_at": "2026-01-01T00:00:00+00:00"
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 50,
    "total": 120,
    "has_more": true
  }
}

GET /v1/address-watch/webhook

Read webhook URL and enabled flag.

Response fields

Name	Type	Description
webhook.url	string \| null	Callback URL, or null.
webhook.enabled	boolean	Whether delivery is enabled.

Response example

{
  "ok": true,
  "webhook": {
    "url": "https://example.com/hooks/address-watch",
    "enabled": true
  }
}

PUT /v1/address-watch/webhook

Set webhook URL and enabled flag. When enabled is true, url must be a valid URL.

Request body

Name	Type	Description
url	string \| null	HTTP or HTTPS callback URL (max 2048). Nullable; validated as url when present. (optional)
enabled	boolean	Enable or disable outbound delivery.

Response fields

Name	Type	Description
webhook.url	string \| null	Stored URL, or null.
webhook.enabled	boolean	Enabled flag after update.

GET/PUT responses return url, enabled, events (booleans plus optional payment_networks / payout_networks / block_networks), and egress_ips — no webhook secret is returned.
Network lists restrict which chains deliver each event type; boolean true with an empty list means all networks (legacy).
See Webhook delivery for payload shape and egress IP allowlisting.

Response example

{
  "ok": true,
  "webhook": {
    "url": "https://example.com/hooks/address-watch",
    "enabled": true
  }
}

Tips

Use network_slug as the Address Watch ingest key: mainnet is the base catalog slug (ethereum); other environments use {network}-{env} (ethereum-sepolia). Only networks with a watch:targets row are ingested today (typically mainnet).
DELETE requires a JSON body — unusual for REST, but required here for watch_id.
Business errors (e.g. slot limit) return HTTP 400 with ok: false and error.
Outbound delivery signing is documented under Webhook delivery — not duplicated here.

Address Watch

GET /v1/address-watch/account

Response fields

GET /v1/address-watch/addresses

Query parameters

Response fields

POST /v1/address-watch/addresses

Request body

Response fields

DELETE /v1/address-watch/addresses

Request body

GET /v1/address-watch/events

Query parameters

Response fields

GET /v1/address-watch/webhook

Response fields

PUT /v1/address-watch/webhook

Request body

Response fields

Tips

Related