Alerts

Open the agent's page, choose Is it yours?, and prove you control its domain or the wallet it is paid at. Once the claim is proven, the same page offers alerts. Agents with alerts are checked every ten minutes.

down

An endpoint stopped answering. Sent after a second failed check in a row (or an hour after the first), so a single timeout is not an alert.

up

It answers again. Sent only after a down was sent.

pay_to

The wallet its x402 answer asks to be paid at changed, on a given network.

price

The price changed. Prices in coins addrbook does not recognise by contract (it recognises USDC and EURC) move with exchange rates; those are left out.

options

A network or coin it accepts was added or removed.

tools

Its MCP tool list changed: tools added, removed or redescribed.

Changes on test networks are left out. Every alert links the evidence row it comes from, which anyone can check against the day's published root.

Each alert is a JSON POST. Answer with any 2xx within 8 seconds. Failed deliveries are retried after 2, 4, 8 minutes and so on, up to a day apart; after 20 failures in a row the alerts are paused until you save them again. addrbook-delivery names the delivery, so a retry can be recognised.

{
  "id": "evt_1042",
  "type": "agent.changed",
  "created_at": "2026-10-27T14:03:11Z",
  "agent": {
    "slug": "example-api",
    "name": "Example API",
    "url": "https://addrbook.com/agents/example-api"
  },
  "endpoint": "https://api.example.com/v1/search",
  "observed_at": "2026-10-27T14:02:58Z",
  "changes": [
    {
      "type": "pay_to",
      "network": "eip155:8453",
      "from": ["0x5aaeb6053f3e94c9b9a09f33669435e7ef1beaed"],
      "to": ["0xfb6916095ca1df60bb79ce92ce3ea74c37c5d359"],
      "sentence": "On Base, now asks to be paid at 0xfb6916095ca1df60bb79ce92ce3ea74c37c5d359 instead of 0x5aaeb6053f3e94c9b9a09f33669435e7ef1beaed.",
      "minor": false
    }
  ],
  "evidence_url": "https://addrbook.com/evidence/88213"
}

A test alert has "type": "test" and no changes.

The addrbook-signature header is t=<unix seconds>,v1=<hex>, where the hex is the HMAC-SHA256 of t, a dot and the raw body, keyed with the secret shown when you set the webhook. Reject a timestamp more than five minutes old.

import { createHmac, timingSafeEqual } from "node:crypto";

// header: the addrbook-signature header; body: the raw request body, as received.
export function fromAddrbook(header: string, body: string, secret: string): boolean {
  const parts = Object.fromEntries(header.split(",").map((p) => p.split("=", 2)));
  const t = Number(parts.t);
  if (!Number.isFinite(t) || Math.abs(Date.now() / 1000 - t) > 300) return false;
  const expected = createHmac("sha256", secret).update(`${parts.t}.${body}`).digest("hex");
  const given = Buffer.from(parts.v1 ?? "", "hex");
  return given.length === 32 && timingSafeEqual(given, Buffer.from(expected, "hex"));
}

An address is sent a confirmation link first and nothing else until it is followed. Every email carries a one-click unsubscribe. addrbook keeps the address only while alerts are on.