x40docs — docs for x402 paid APIs and x403 Harbinger notify  |  Our sites: x402 Marketplace · Smithery migration · grokzilla.shop · Harbinger app · Harbinger docs

How x403 notify works

  1. GET /v1/stream with X-Harbinger-Watch: <id>.
  2. Edge answers 403 with X-Harbinger-Forbidden: grant-required, X-Harbinger-Price, X-Harbinger-Event and X-Harbinger-Advantage-Window.
  3. Pay: send a USDC transfer on Base to payTo totaling at least the watch price.
  4. Sign an hp2 grant (below) and retry with X-Harbinger-Grant.
  5. Edge answers 200 with X-Harbinger-Receipt and opens the stream. When the watch fires you get one ping; if the window ends with no move, the grant is not consumed.

Grant format (X403-HP-2)

X-Harbinger-Grant: hp2.<BaseTxHash>.<unixSeconds>.<eip191Signature>

message signed (EIP-191 personal_sign) by the payer of the USDC transfer:
X403-HP-2 grant
tx: <txHash lowercase>
route: /v1/stream
ts: <unixSeconds>

Max clock skew 300 s; each signed header is accepted once. The older hp1.<txHash> form is deprecated (replayable) and accepted only until 2026-11-04 00:00 UTC. The demo grant hp1.demo is rejected in production.

Delivery

SSE (Accept: text/event-stream) is the hot path; Accept: application/json returns a single correlate object. Some watches also deliver by webhook to /v1/hooks (signed body, retries never double-charge). The mail rail is currently paused.

Correlation

A watch is all or any over one or more conditions inside a window. Fired pings include X-Harbinger-Correlation (0–1; null for one-leg watches) and X-Harbinger-Advantage-Window (ms). These are estimates, not investment advice.