Quickstart - Blockworks Documentation

This page gets you a key and a first Monitoring response, then points you at push delivery. The key is the same one that authenticates every Blockworks product, so if you already have one you can skip the first step.

Get an API key

Create a key at app.blockworks.com/account/api.Keys are shown once at creation. Store yours in a secret manager or environment variable, and never commit it or send it from a browser.

export BLOCKWORKS_API_KEY="your-api-key"

Pull the latest developments

All Monitoring endpoints live under /monitoring/v2 on the shared Blockworks API host, and every one of them requires the X-Blockworks-API-Key header. Here we fetch the three most recent verified developments.

curl "https://api.blockworks.com/monitoring/v2/developments?limit=3&verified=true" \
  -H "X-Blockworks-API-Key: $BLOCKWORKS_API_KEY"

import os
import requests

response = requests.get(
    "https://api.blockworks.com/monitoring/v2/developments",
    params={"limit": 3, "verified": "true"},
    headers={"X-Blockworks-API-Key": os.environ["BLOCKWORKS_API_KEY"]},
    timeout=30,
)
response.raise_for_status()

payload = response.json()
for development in payload["data"]:
    assets = ", ".join(a["symbol"] for a in development["assets"])
    print(development["importance"], assets, development["title"])

const url = new URL("https://api.blockworks.com/monitoring/v2/developments");
url.searchParams.set("limit", "3");
url.searchParams.set("verified", "true");

const response = await fetch(url, {
  headers: { "X-Blockworks-API-Key": process.env.BLOCKWORKS_API_KEY },
});
if (!response.ok) throw new Error(`Request failed: ${response.status}`);

const { data } = await response.json();
for (const development of data) {
  const assets = development.assets.map((a) => a.symbol).join(", ");
  console.log(development.importance, assets, development.title);
}

Narrow the stream with assetIds (UUIDs or slugs), intelCategories, minimumImportance, start and end, or free-text search. Every parameter is listed on List Developments.

Read the response

Monitoring responses use the same envelope as every Blockworks API: error is null on success and a string on failure, data carries the payload, and list endpoints add a metadata object with paging totals. Each item is a development, the atomic unit of coverage: one dated, verified occurrence, tagged with its taxonomy, importance, resolved assets, and the parent event it belongs to.

Response (trimmed to one development and its key fields)

{
  "error": null,
  "data": [
    {
      "id": "3c8ad9eb-6ab8-4233-a06d-5c0c09e9506c",
      "title": "BTC e-mode Deprecation on SparkLend",
      "summary": "Phoenix Labs has shared a notice advising SparkLend users borrowing cbBTC through BTC e-mode to close their positions before Jun. 7, 2026 to avoid potential liquidations.",
      "verified": true,
      "intelCategories": ["protocol_management"],
      "intelSubcategories": ["discontinuation"],
      "importance": "low",
      "actionable": false,
      "governance": false,
      "startedAt": "2026-04-20T18:03:26Z",
      "assets": [
        { "name": "Coinbase Wrapped BTC", "slug": "coinbase-wrapped-btc", "symbol": "CBBTC", "class": "primary" },
        { "name": "Spark", "slug": "spark-sky-protocol", "symbol": "SPK", "class": "primary" }
      ],
      "event": {
        "slug": "btc-e-mode-deprecation-on-sparklend-cf1d1d",
        "title": "BTC e-mode Deprecation on SparkLend",
        "developmentCount": 1
      }
    }
  ],
  "metadata": { "limit": 3, "page": 1, "totalRows": 83302, "totalPages": 27768 }
}

Unresolved filter tokens are dropped silently, so an empty data array can mean “nothing matched” or “that asset slug does not exist”. See Filter semantics.

Subscribe instead of polling

A monitoring view is a saved filter over the stream. Create one in the Intel app, then either poll it or have matches pushed to you:

Poll a view

Page through the developments a saved view has matched.

Webhooks

Receive matches as signed HTTP POSTs, with HMAC verification and retries.

Access tiers, the legacy header, and key handling are covered in Authentication.