---
title: "Coin Days Metrics"
method: GET
path: "/v1/coindays"
tags: ["Coin Days"]
---

# Coin Days Metrics

`GET /v1/coindays`

## Request

- Base URL: `https://api.blocklens.co` (the document declares no server; this is the origin it was published from)
- URL: `https://api.blocklens.co/v1/coindays`
- Auth: none declared

Provides daily **Coin Days** metrics that measure the economic weight of Bitcoin transactions by accounting for how long coins were held before being spent.

- **Coin Days Destroyed (CDD)**: The total coin-days destroyed when UTXOs are spent. A UTXO holding 2 BTC for 100 days destroys 200 coin-days when spent. High CDD indicates long-dormant coins are moving.
- **Net Coin Days**: CDC − CDD, where Coin Days Created (CDC) equals the circulating supply (each BTC creates exactly 1 coin-day per calendar day). Positive values indicate net accumulation; negative values indicate heavy spending of old coins.
- **Coin Days Accumulated**: Cumulative sum of Net Coin Days from genesis. Represents the total "stored time-value" in the UTXO set.
- **Liveliness**: cumCDD / (CDA + cumCDD). Measures the fraction of all possible coin-days that have been destroyed. Values near 1 indicate a high-velocity economy; values near 0 indicate strong HODLing.
- **Vaultedness**: 1 − Liveliness = CDA / (CDA + cumCDD). Measures the fraction of coin-days stored (not yet destroyed). High values indicate coins are being held long-term.
- **Transfer Volume**: Total BTC spent (changed hands) on-chain each day.
- **Dormancy**: Average age (in days) of coins spent: CDD / Transfer Volume. Higher values mean older coins are moving.
- **Dormancy Flow**: Dormancy normalized by its 365-day moving average. Values above 1 indicate unusually old coins are moving.

## Query parameters

- `start_date` string, date, nullable: Start date (YYYY-MM-DD)
- `end_date` string, date, nullable: End date (YYYY-MM-DD)
- `limit` integer: Number of records to return
- `fields` string, nullable: Comma-separated field names to include (date columns always kept)

## Response `200`

Successful Response

- ApiResponse: Standard API response model
  - `success` boolean, required
  - `data` unknown, required
  - `message` string, nullable
  - `count` integer, nullable
  - `timestamp` string, date-time

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/blocklens/apis/blocklens-on-chain-api.md) · [All operations](https://skmtc.dev/blocklens/apis/blocklens-on-chain-api/llms.txt) · [OpenAPI document](https://skmtc.dev/blocklens/apis/blocklens-on-chain-api/revisions/dacc02ae0f9a?raw)