CoinGraphDocs

API reference · Watch

Monitors & webhooks

Get a signed webhook when a signal fires, a verdict changes or a brief is written.

PremiumMCP tool: watch_tokens

Create a monitor for up to 50 tokens. CoinGraph POSTs to your HTTPS endpoint and signs every message with HMAC-SHA256 in the X-CoinGraph-Signature header. The secret is returned once; keep it to verify messages and to manage the monitor.

Create a monitor #

POST/v1/monitor

Parameters

  • tokensstring[] (1–50)· bodyrequired

    Token ids to watch.

  • webhook_urlhttps URL· bodyrequired

    Public HTTPS endpoint. Private and internal addresses are rejected.

  • conditionsobject· bodyoptional

    kinds[] (signal kinds), min_severity 1–3 (default 2), verdict_changes, new_briefs.

Watch ADA, LINK and SOL

Request
curl -X POST "https://coingraph.ai/api/v1/monitor" \
  -H "content-type: application/json" \
  -d '{"tokens":["cardano","chainlink","solana"],"webhook_url":"https://example.com/hooks/coingraph","conditions":{"min_severity":2,"new_briefs":true}}'
Response · real, captured 2026-10-06 23:24 UTC · long lists trimmed
{
  "object": "monitor",
  "id": null,
  "as_of": "2026-10-06T23:21:34.485Z",
  "data": {
    "id": "mon_a562088007ce5e2721f5",
    "secret": "whsec_••••••••••••••••",
    "tokens": [
      "cardano",
      "chainlink",
      "… 1 more"
    ],
    "conditions": {
      "min_severity": 2,
      "verdict_changes": true,
      "new_briefs": true
    },
    "webhook_url": "https://example.com/hooks/coingraph",
    "created_at": "2026-10-06T23:21:34.485Z",
    "note": "Keep the secret: it is shown once and used to sign every webhook (X-CoinGraph-Signature = HMAC-SHA256 of the body)."
  },
  "sources": []
}

List your monitors #

GET/v1/monitor

Parameters

  • X-Monitor-Secretstring· headerrequired

    The secret from creation.
Request
curl "https://coingraph.ai/api/v1/monitor" \
  -H "X-Monitor-Secret: whsec_your_secret"

Stop a monitor #

DELETE/v1/monitor/{id}

Parameters

  • idstring· pathrequired

    Monitor id.

  • X-Monitor-Secretstring· headerrequired

    The secret from creation.
Request
curl -X DELETE "https://coingraph.ai/api/v1/monitor/mon_fc71a6d43e785693a658" \
  -H "X-Monitor-Secret: whsec_your_secret"

Response #

Inside data:

FieldContents
id, secretThe monitor id and its signing secret (shown once).
tokens, conditions, created_atWhat is watched and how.

Webhook messages #

Each message is a POST with a JSON body and an X-CoinGraph-Signature header: the HMAC-SHA256 of the raw body, keyed with your monitor secret, in hex. kind is signal or brief; a brief message carries its headline, direction, severity, summary and a link to the full brief.

Example message
{
  "monitor_id": "mon_…",
  "kind": "signal",
  "token": "chainlink",
  "object": {
    "id": 241,
    "kind": "exchange_inflow",
    "direction": "down",
    "severity": 2,
    "value": 4200000,
    "ratio": 3.4,
    "at": "2026-10-07T01:15:00Z",
    "details": {
      "…": "rule-specific detail"
    }
  },
  "as_of": "2026-10-07T01:15:04Z"
}

Verify the signature (Node.js) #

verify.js
import crypto from "node:crypto";

export function isFromCoinGraph(rawBody, signature, secret) {
  const expected = crypto.createHmac("sha256", secret).update(rawBody).digest("hex");
  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signature));
}
!

Important

Reject messages whose signature does not match, and never log the secret.

Pricing #

Premium tier: 5 tADA per call via x402 (mainnet $0.05). Without payment a paid call answers 402 with a PAYMENT-REQUIRED header; design partners send Authorization: Bearer cg_… instead. How payment works.