Address Watch

Flow diagram

How an address is watched and how its transactions reach you. You add an address once; every transaction that touches it produces events until you remove it.

Errors

Failed calls answer { ok: false, error_code, error } with an HTTP status. A request that cannot be accepted (wrong body, bad query value) is 400 with an errors list: every field that failed is named in it, and error_code is common.validation_failed when more than one field failed.

watch.network_required and watch.address_required (400): network_slug or address is empty or too long. watch.scan_not_enabled (400): the network key cannot be watched. watch.no_plan (400): the account has no plan.

watch.address_unavailable (403): the plan has no address slots. watch.address_limit (403): all slots are taken. watch.quota (429): too many adds or deletes today, this week or this month.

watch.invalid_event_type (400): event_type is not payment, payout or other. watch.not_found (404): unknown watch_id on delete.

watch.ingest_unavailable (503): temporarily unavailable, retry later. watch.save_failed (500): the watch could not be saved, retry.

Validation error

{
  "ok": false,
  "error_code": "common.validation_failed",
  "error": "Validation failed",
  "errors": [
    { "field": "per_page", "error_code": "common.validation_failed", "error": "per_page must be a whole number, from 1 to 100." },
    { "field": "before_id", "error_code": "common.validation_failed", "error": "before_id must be a uuid." }
  ]
}

GET /v1/address-watches/account

Address slots of the plan: how many there are and how many are taken, plus the webhook state.

Campos de la respuesta

• Read-only summary. To change the webhook URL, secret or event networks use the Webhooks article (GET/PUT /v1/webhooks).

import { createHash, createHmac } from 'node:crypto'

const API_KEY = process.env.PUBLIC_API_KEY! // cabinet UUID
const SECRET = process.env.PUBLIC_API_SECRET! // sk_live_…
const BASE = 'https://api.rpcnode.dev'

// path: as the server receives it, with the query; body: the exact string that is sent
async function call(method: string, path: string, body = '') {
  const timestamp = Math.floor(Date.now() / 1000)
  const bodyHash = createHash('sha256').update(body).digest('hex')
  const signature = createHmac('sha256', SECRET)
    .update([timestamp, method, path, bodyHash].join('\n'))
    .digest('hex')
  const res = await fetch(BASE + path, {
    method,
    headers: {
      'X-Api-Key': API_KEY,
      'X-Timestamp': String(timestamp),
      'X-Signature': signature,
      ...(body ? { 'Content-Type': 'application/json' } : {}),
    },
    body: body || undefined,
  })
  return res.json()
}

console.log(await call('GET', '/v1/address-watches/account'))

Ejemplo de respuesta

{
  "ok": true,
  "account": {
    "webhook_address_slots": 10,
    "address_slots_used": 2,
    "webhook_url": "https://example.com/hooks/rpcnode",
    "webhook_enabled": true
  }
}

GET /v1/address-watches

List watched addresses (paginated, newest first). Filter by network and/or part of the address.

Parámetros de consulta

Campos de la respuesta

• Sign the path together with the query string (see Authentication): the query is part of the signature.
• A page, per_page or text value outside its bounds is rejected with 400 and an errors list naming the parameter; it is never replaced by a default.
• Only active and stopped watches are listed; deleted ones are not.

import { createHash, createHmac } from 'node:crypto'

const API_KEY = process.env.PUBLIC_API_KEY! // cabinet UUID
const SECRET = process.env.PUBLIC_API_SECRET! // sk_live_…
const BASE = 'https://api.rpcnode.dev'

// path: as the server receives it, with the query; body: the exact string that is sent
async function call(method: string, path: string, body = '') {
  const timestamp = Math.floor(Date.now() / 1000)
  const bodyHash = createHash('sha256').update(body).digest('hex')
  const signature = createHmac('sha256', SECRET)
    .update([timestamp, method, path, bodyHash].join('\n'))
    .digest('hex')
  const res = await fetch(BASE + path, {
    method,
    headers: {
      'X-Api-Key': API_KEY,
      'X-Timestamp': String(timestamp),
      'X-Signature': signature,
      ...(body ? { 'Content-Type': 'application/json' } : {}),
    },
    body: body || undefined,
  })
  return res.json()
}

console.log(await call('GET', '/v1/address-watches'))

Ejemplo de respuesta

{
  "ok": true,
  "items": [
    {
      "watch_id": "c9fd242d-525b-4b81-9a99-b2a95be331c9",
      "network_slug": "ethereum",
      "address": "0x28c6c06298d514db089934071355e5743bf21d60",
      "status": "active",
      "created_at": "2026-08-22T10:15:00+00:00"
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 20,
    "total": 1,
    "has_more": false
  }
}

POST /v1/address-watches

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

Cuerpo de la solicitud

Campos de la respuesta

• Body fields are exact: a misspelled or unknown field is rejected with 400 and named in errors. Send Content-Type: application/json and sign the raw body.
• Adding an address that is already watched is not an error: the existing active watch is returned and no extra slot is taken. Adding an address again after deleting it takes a slot again.
• Adds and deletes are rate-limited per account (day, week and month budgets that grow with the number of slots); over the budget the call fails with 429 watch.quota.

import { createHash, createHmac } from 'node:crypto'

const API_KEY = process.env.PUBLIC_API_KEY! // cabinet UUID
const SECRET = process.env.PUBLIC_API_SECRET! // sk_live_…
const BASE = 'https://api.rpcnode.dev'

// path: as the server receives it, with the query; body: the exact string that is sent
async function call(method: string, path: string, body = '') {
  const timestamp = Math.floor(Date.now() / 1000)
  const bodyHash = createHash('sha256').update(body).digest('hex')
  const signature = createHmac('sha256', SECRET)
    .update([timestamp, method, path, bodyHash].join('\n'))
    .digest('hex')
  const res = await fetch(BASE + path, {
    method,
    headers: {
      'X-Api-Key': API_KEY,
      'X-Timestamp': String(timestamp),
      'X-Signature': signature,
      ...(body ? { 'Content-Type': 'application/json' } : {}),
    },
    body: body || undefined,
  })
  return res.json()
}

console.log(await call('POST', '/v1/address-watches', '{"network_slug":"string","address":"string"}'))

Ejemplo de respuesta

{
  "ok": true,
  "address": {
    "watch_id": "c9fd242d-525b-4b81-9a99-b2a95be331c9",
    "network_slug": "tron",
    "address": "TU4vEruvZwLLkSfV9bNw12EJTPvNr7Pvaa",
    "status": "active",
    "created_at": "2026-08-22T10:15:00+00:00"
  }
}

DELETE /v1/address-watches/{watchId}

Stop watching an address. The watch id goes in the path; there is no request body.

• watchId is the watch_id returned by add or list (a uuid). An unknown, foreign or malformed id returns 404 watch.not_found.
• Deleting frees the slot at once, but counts against the delete budget (429 watch.quota when exceeded).
• Events already recorded for the watch stay readable through the events route.

import { createHash, createHmac } from 'node:crypto'

const API_KEY = process.env.PUBLIC_API_KEY! // cabinet UUID
const SECRET = process.env.PUBLIC_API_SECRET! // sk_live_…
const BASE = 'https://api.rpcnode.dev'

// path: as the server receives it, with the query; body: the exact string that is sent
async function call(method: string, path: string, body = '') {
  const timestamp = Math.floor(Date.now() / 1000)
  const bodyHash = createHash('sha256').update(body).digest('hex')
  const signature = createHmac('sha256', SECRET)
    .update([timestamp, method, path, bodyHash].join('\n'))
    .digest('hex')
  const res = await fetch(BASE + path, {
    method,
    headers: {
      'X-Api-Key': API_KEY,
      'X-Timestamp': String(timestamp),
      'X-Signature': signature,
      ...(body ? { 'Content-Type': 'application/json' } : {}),
    },
    body: body || undefined,
  })
  return res.json()
}

console.log(await call('DELETE', '/v1/address-watches/00000000-0000-0000-0000-000000000000'))

Ejemplo de respuesta

{
  "ok": true
}

GET /v1/address-watches/events

Recent events of your watched addresses, newest first. The transaction details are flattened onto each event (no nested payload).

Parámetros de consulta

Campos de la respuesta

• Sign the path together with the query string (see Authentication).
• This is a recent log, not an archive. Use a webhook or WebSocket for delivery.
• The id of an event is a uuid and is stable: the same transaction event always has the same id. To read the log page by page without gaps while new events arrive, pass the id of the last event you received as before_id instead of increasing page.
• Empty or unknown values are never written as empty strings: unknown fields are null or absent (see the field list). The set of keys after created_at follows the Address Watch event format (schema_version "2"), the same keys as the webhook body.

import { createHash, createHmac } from 'node:crypto'

const API_KEY = process.env.PUBLIC_API_KEY! // cabinet UUID
const SECRET = process.env.PUBLIC_API_SECRET! // sk_live_…
const BASE = 'https://api.rpcnode.dev'

// path: as the server receives it, with the query; body: the exact string that is sent
async function call(method: string, path: string, body = '') {
  const timestamp = Math.floor(Date.now() / 1000)
  const bodyHash = createHash('sha256').update(body).digest('hex')
  const signature = createHmac('sha256', SECRET)
    .update([timestamp, method, path, bodyHash].join('\n'))
    .digest('hex')
  const res = await fetch(BASE + path, {
    method,
    headers: {
      'X-Api-Key': API_KEY,
      'X-Timestamp': String(timestamp),
      'X-Signature': signature,
      ...(body ? { 'Content-Type': 'application/json' } : {}),
    },
    body: body || undefined,
  })
  return res.json()
}

console.log(await call('GET', '/v1/address-watches/events'))

Ejemplo de respuesta

{
  "ok": true,
  "items": [
    {
      "id": "3f0c1a52-7a4e-3d0f-9a1b-52c7f4a8e611",
      "watch_id": "c9fd242d-525b-4b81-9a99-b2a95be331c9",
      "network_slug": "tron",
      "address": "TU4vEruvZwLLkSfV9bNw12EJTPvNr7Pvaa",
      "tx_hash": "bb08e86bca3219613b2d10f8b731c139aebc74c7a85f2a736b18bed50a2c320c",
      "block_height": 85558636,
      "created_at": "2026-08-22T10:15:03+00:00",
      "schema_version": "2",
      "network": "tron",
      "block_hash": "0000000005193f6c0f1e2b6d5c4e8a7b1d3c9e2f4a6b8c0d1e2f3a4b5c6d7e8f",
      "block_time": 1787393700,
      "from_address": "TU4vEruvZwLLkSfV9bNw12EJTPvNr7Pvaa",
      "to_address": "TH7uGJPN4Dy8XBBNkSuPtiZL1QMTB7jsJv",
      "type": "payout",
      "token": { "contract": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t", "symbol": "USDT", "standard": "trc20", "decimals": 6 },
      "currency": "USDT",
      "amount": "30",
      "amount_raw": "30000000",
      "fee": "13.3",
      "fee_raw": "13300000",
      "status": "check",
      "method": "transfer",
      "is_payment": true,
      "direction": "out",
      "risk": [],
      "confirmation_status": "finalized",
      "required_confirmations": 19,
      "confirmations": 19,
      "final_block": 85558654,
      "confirmed": true
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 50,
    "total": 1,
    "has_more": false
  }
}

Consejos

• network_slug is the watch network key: the base catalog slug on mainnet (ethereum, tron) and {network}-{env} on other environments (ethereum-sepolia, tron-nile). Only environments available for watching can be used.
• DELETE takes the watch id in the path (/v1/address-watches/{watchId}) and no body. The old body-based form no longer exists.
• Fields without a value are not written. Read an absent field as "no value", for example account.webhook_url when no webhook is configured.
• The query string is part of the signed path, so sign exactly the path and query you send.
• Event delivery (webhook URL, secret, which networks fire) is configured with GET/PUT /v1/webhooks, not here. See the Webhooks article; for a live socket see WebSockets.

Relacionado

• Public API
• Public API overview
• Authentication & signing
• Transaction watch
• Webhooks
• WebSockets
• Networks
• Account (plan / usage)
• Endpoints