CDD API

Real-time Coin Days Destroyed, classified and scored against its trailing baseline. The signal you trade off — not the raw metric you have to interpret yourself.

Why CDD, not raw on-chain volume

Plain on-chain volume is dominated by exchange hot-wallet churn and internal rebalancing. CDD weights every moved satoshi by how long it sat still: a 1 BTC payment of fresh coins barely registers, a 1 BTC payment of 10-year-old coins is worth 3,650 BTC·days. Big CDD prints almost always come from someone whose decision matters — long-term holders moving, governments forfeiting seized stashes, exchange cold-wallet migrations, post-bankruptcy distributions like Mt. Gox.

CDD and raw volume look similar in calm markets and diverge sharply at the edges — exactly where you need signal:

And like fee pressure, CDD is reconstructible from on-chain data — every spent input records its prevout age. The classifier and its bands are calibrated against 16 years of real chain history, not the window your provider happened to be running.

Endpoint

GET https://signals.chainquery.com/v1/signals/cdd
Authorization: Bearer <your-token>

Response shape

Standard ChainQuery.com envelope. The data object carries the state classifier, z-score, raw metric, and comparable historical events.

{
  "schema_version": "1",
  "ts_utc": "2026-05-21T20:00:00Z",
  "data_age_sec": 12,
  "stale": false,
  "data": { ... }
}

Live sample

● Live data, fetched server-side just now (cached up to 60s).

{
  "data": {
    "comparable_events": [],
    "data_age_sec": 6,
    "last_change_at": "2026-05-21T11:26:55.413043Z",
    "metric_unit": "BTC\u00b7days",
    "metric_value": 10314185.383148467,
    "name": "cdd",
    "score": 0.20457158342809809,
    "stale": false,
    "state": "normal",
    "ts_utc": "2026-05-21T21:12:59.169761Z"
  },
  "data_age_sec": 6,
  "schema_version": "1",
  "stale": false,
  "ts_utc": "2026-05-21T21:12:59.173064Z"
}

State classifier

Each new block at 3-confirmation depth produces a single label from per-block CDD against its trailing baseline. Bands escalate from normal through extreme; exact thresholds are calibrated against the full 16-year chain history. Trade the label, skip the math.

Comparable historical events

When the state escalates above normal, the response includes a comparable_events array with 1-3 historical prints the classifier judged most similar to the current one. Each entry carries the date, state at the time, headline metric value, a short summary, and a permalink to /events/<slug> on chainquery.com for the full narrative — what moved, who moved it, what the market did next. The classifier ships with curated coverage of the Mt. Gox collapse and trustee distributions, the FTX collapse cascade, German government BTC sales, and other historically significant CDD events.

Empty when the signal is in its normal band — comparable_events only fires when there is something to compare.

Threshold webhooks

We wire per-consumer webhooks that fire on state transitions or score bands you configure. Bearer-gated POST, schema-versioned envelope, idempotent retry, signed with a per-consumer HMAC secret. Email us your endpoint and the conditions you want to alert on; we set them up by hand during onboarding.

Contract guarantees

• Hard-fail on schema_version mismatch in your client; schema bumps are breaking.
• Treat stale: true as no-data; the upstream classifier may have lost its bitcoind connection.
• Treat data_age_sec > 1200 with suspicion even if stale: false — we score per-block at ~10-min cadence.
• Tokens are revocable independently per consumer; ask for one rather than sharing.

Get a token

Email [email protected] with the use case. Tokens are issued per consumer and revocable independently. Bundles with the Fee Pressure API as the ChainQuery Signal Suite.

Educational view of the underlying metric, full daily history charted: /reports/cdd.