Bitview

URPD at block height or date

get_urpd

Read-onlyIdempotent

URPD for a cohort at a block height or the last block of a UTC day. Returns { height, hash, date, cohort, weight, aggregation, close, supply, buckets } where buckets is columns, { price, supply, realized_cap, unrealized_pnl }, one entry per bucket in ascending price: the same block header and columnar layout as GET /api/utxo-set/{point}. close, price, realized_cap, and unrealized_pnl are USD; supply is BTC. unrealized_pnl can be negative. Bucket realized_cap and unrealized_pnl value each coin at its creation price on the price grid (four significant digits of the price in cents, within 0.05% of the exact price), rounded to the cent per bucket, so the buckets need not sum to the realized cap series. With a wakefulness or mobility weight, supply is the weighted supply (whole satoshis) and the bucket values follow it.

REST operation: GET /api/urpd/{cohort}/{point}.

Input Schema

Name	Required	Description	Default
`agg`	No	Aggregation strategy. Default: raw (no aggregation).	raw
`point`	Yes	Confirmed block height (`840000`) or UTC calendar day (`YYYY-MM-DD`)
`cohort`	Yes
`weight`	No	Supply weighting. Default: none (unweighted).	none

Output Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

Changed39 schema fields changedOct 30, 2026

removedInput schema / $defs / Cohort

Removed value: -{
-  "description": "URPD cohort identifier. Use `GET /api/urpd` to list available cohorts.\n\nValidated at construction: non-empty, ASCII `[a-z0-9_]+`. Matches the\nschemars enum value set; the type therefore proves \"this is a valid\ncohort name\" wherever a `Cohort` is held.",
-  "enum": [
-    "all",
-    "sth",
-    "lth",
-    "utxos_under_1h_old",
-    "utxos_1h_to_1d_old",
-    "utxos_1d_to_1w_old",
-    "utxos_1w_to_1m_old",
-    "utxos_1m_to_2m_old",
-    "utxos_2m_to_3m_old",
-    "utxos_3m_to_4m_old",
-    "utxos_4m_to_5m_old",
-    "utxos_5m_to_6m_old",
-    "utxos_6m_to_9m_old",
-    "utxos_9m_to_1y_old",
-    "utxos_1y_to_18m_old",
-    "utxos_18m_to_2y_old",
-    "utxos_2y_to_3y_old",
-    "utxos_3y_to_4y_old",
-    "utxos_4y_to_5y_old",
-    "utxos_5y_to_6y_old",
-    "utxos_6y_to_7y_old",
-    "utxos_7y_to_8y_old",
-    "utxos_8y_to_10y_old",
-    "utxos_10y_to_12y_old",
-    "utxos_12y_to_15y_old",
-    "utxos_over_15y_old"
-  ],
-  "type": "string"
-}

addedInput schema / $defs / Date

Added value: +{
+  "description": "Calendar date in YYYY-MM-DD format.",
+  "examples": [
+    "2009-01-03",
+    "2024-04-20"
+  ],
+  "format": "date",
+  "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
+  "type": "string"
+}

addedInput schema / $defs / Height

Added value: +{
+  "description": "A block height: how many blocks came before it.",
+  "examples": [
+    0,
+    210000,
+    420000,
+    840000
+  ],
+  "minimum": 0,
+  "type": "integer"
+}

addedInput schema / $defs / HeightOrDate

Added value: +{
+  "anyOf": [
+    {
+      "$ref": "#/$defs/Height"
+    },
+    {
+      "$ref": "#/$defs/Date"
+    }
+  ],
+  "description": "A confirmed point of the chain: a block height (`840000`) or a UTC calendar day (`YYYY-MM-DD`)."
+}

changedInput schema / $defs / UrpdAggregation / description

Previous value: -"Aggregation strategy for URPD buckets.\nOptions: raw (no aggregation), lin200/lin500/lin1000 (linear $200/$500/$1000),\nlog10/log50/log100/log200/log500/log1000/log2000 (logarithmic with 10/50/100/200/500/1000/2000 buckets per decade)."New value: +"Aggregation strategy for URPD buckets.\nOptions: raw (no aggregation), lin200/lin500/lin1000 (linear $200/$500/$1000),\nlog10/log50/log100/log200/log500/log1000/log2000 (logarithmic, that many buckets per decade)."

addedInput schema / $defs / UrpdCohort

Added value: +{
+  "description": "A URPD cohort, by its series' prefix: an age aggregate (`all`, `sth`, `lth`, `age_under_4m`, ...) or an age band (`age_under_1h`, `age_1h_to_1d`, ...).",
+  "enum": [
+    "all",
+    "sth",
+    "lth",
+    "age_under_4m",
+    "age_under_6m",
+    "age_over_4m",
+    "age_over_6m",
+    "age_under_1h",
+    "age_1h_to_1d",
+    "age_1d_to_1w",
+    "age_1w_to_1m",
+    "age_1m_to_2m",
+    "age_2m_to_3m",
+    "age_3m_to_4m",
+    "age_4m_to_5m",
+    "age_5m_to_6m",
+    "age_6m_to_9m",
+    "age_9m_to_1y",
+    "age_1y_to_18m",
+    "age_18m_to_2y",
+    "age_2y_to_3y",
+    "age_3y_to_4y",
+    "age_4y_to_5y",
+    "age_5y_to_6y",
+    "age_6y_to_7y",
+    "age_7y_to_8y",
+    "age_8y_to_10y",
+    "age_10y_to_12y",
+    "age_12y_to_15y",
+    "age_over_15y"
+  ],
+  "type": "string"
+}

changedInput schema / $defs / UrpdWeight / description

Previous value: -"Weighting applied to a URPD: raw (unweighted), cointime, or coinflow."New value: +"The weight applied to a URPD's age bands: `none` (every satoshi counts once), `wakefulness` (each band\nweighted by the share of its coin days already consumed, Cointime's; the distribution behind the\n`*_awake_*` series) or `mobility` (each band weighted by the estimated probability its coins are ever\nspent, Coinflow's; behind `*_mobile_*`)."

changedInput schema / $defs / UrpdWeight / enum

Previous value: -[
-  "raw",
-  "cointime",
-  "coinflow"
-]New value: +[
+  "none",
+  "wakefulness",
+  "mobility"
+]

addedInput schema / properties / agg / default
```
Added value: +"raw"
```

changedInput schema / properties / agg / description

Previous value: -"Aggregation strategy. Default: raw (no aggregation). Accepts `bucket` as alias."New value: +"Aggregation strategy. Default: raw (no aggregation)."

changedInput schema / properties / cohort / $ref

Previous value: -"#/$defs/Cohort"New value: +"#/$defs/UrpdCohort"

addedInput schema / properties / point

Added value: +{
+  "$ref": "#/$defs/HeightOrDate",
+  "description": "Confirmed block height (`840000`) or UTC calendar day (`YYYY-MM-DD`)"
+}

addedInput schema / properties / weight / default
```
Added value: +"none"
```

changedInput schema / properties / weight / description

Previous value: -"Supply weighting. Default: raw (unweighted)."New value: +"Supply weighting. Default: none (unweighted)."

changedInput schema / required

Previous value: -[
-  "cohort"
-]New value: +[
+  "cohort",
+  "point"
+]

removedOutput schema / $defs / Bitcoin / format
```
Removed value: -"double"
```

addedOutput schema / $defs / BlockHash

Added value: +{
+  "pattern": "^[0-9a-f]{64}$",
+  "type": "string"
+}

removedOutput schema / $defs / Cohort

Removed value: -{
-  "enum": [
-    "all",
-    "sth",
-    "lth",
-    "utxos_under_1h_old",
-    "utxos_1h_to_1d_old",
-    "utxos_1d_to_1w_old",
-    "utxos_1w_to_1m_old",
-    "utxos_1m_to_2m_old",
-    "utxos_2m_to_3m_old",
-    "utxos_3m_to_4m_old",
-    "utxos_4m_to_5m_old",
-    "utxos_5m_to_6m_old",
-    "utxos_6m_to_9m_old",
-    "utxos_9m_to_1y_old",
-    "utxos_1y_to_18m_old",
-    "utxos_18m_to_2y_old",
-    "utxos_2y_to_3y_old",
-    "utxos_3y_to_4y_old",
-    "utxos_4y_to_5y_old",
-    "utxos_5y_to_6y_old",
-    "utxos_6y_to_7y_old",
-    "utxos_7y_to_8y_old",
-    "utxos_8y_to_10y_old",
-    "utxos_10y_to_12y_old",
-    "utxos_12y_to_15y_old",
-    "utxos_over_15y_old"
-  ],
-  "type": "string"
-}

removedOutput schema / $defs / Dollars / format
```
Removed value: -"double"
```

addedOutput schema / $defs / Height

Added value: +{
+  "minimum": 0,
+  "type": "integer"
+}

addedOutput schema / $defs / Urpd / properties / aggregation / $ref
```
Added value: +"#/$defs/UrpdAggregation"
```

removedOutput schema / $defs / Urpd / properties / aggregation / allOf

Removed value: -[
-  {
-    "$ref": "#/$defs/UrpdAggregation"
-  }
-]

addedOutput schema / $defs / Urpd / properties / buckets / $ref
```
Added value: +"#/$defs/UrpdBuckets"
```
removedOutput schema / $defs / Urpd / properties / buckets / items
```
Removed value: -{
-  "$ref": "#/$defs/UrpdBucket"
-}
```
removedOutput schema / $defs / Urpd / properties / buckets / type
```
Removed value: -"array"
```

changedOutput schema / $defs / Urpd / properties / cohort / $ref

Previous value: -"#/$defs/Cohort"New value: +"#/$defs/UrpdCohort"

removedOutput schema / $defs / Urpd / properties / date / $ref
```
Removed value: -"#/$defs/Date"
```
addedOutput schema / $defs / Urpd / properties / date / allOf
```
Added value: +[
+  {
+    "$ref": "#/$defs/Date"
+  }
+]
```

addedOutput schema / $defs / Urpd / properties / hash

Added value: +{
+  "allOf": [
+    {
+      "$ref": "#/$defs/BlockHash"
+    }
+  ]
+}

addedOutput schema / $defs / Urpd / properties / height

Added value: +{
+  "allOf": [
+    {
+      "$ref": "#/$defs/Height"
+    }
+  ]
+}

addedOutput schema / $defs / Urpd / properties / supply

Added value: +{
+  "allOf": [
+    {
+      "$ref": "#/$defs/Bitcoin"
+    }
+  ]
+}

removedOutput schema / $defs / Urpd / properties / total_supply

Removed value: -{
-  "allOf": [
-    {
-      "$ref": "#/$defs/Bitcoin"
-    }
-  ]
-}

addedOutput schema / $defs / Urpd / properties / weight / $ref
```
Added value: +"#/$defs/UrpdWeight"
```

removedOutput schema / $defs / Urpd / properties / weight / allOf

Removed value: -[
-  {
-    "$ref": "#/$defs/UrpdWeight"
-  }
-]

changedOutput schema / $defs / Urpd / required

Previous value: -[
-  "cohort",
-  "date",
-  "weight",
-  "aggregation",
-  "close",
-  "total_supply",
-  "buckets"
-]New value: +[
+  "height",
+  "hash",
+  "date",
+  "cohort",
+  "weight",
+  "aggregation",
+  "close",
+  "supply",
+  "buckets"
+]

removedOutput schema / $defs / UrpdBucket

Removed value: -{
-  "properties": {
-    "price_floor": {
-      "allOf": [
-        {
-          "$ref": "#/$defs/Dollars"
-        }
-      ]
-    },
-    "realized_cap": {
-      "allOf": [
-        {
-          "$ref": "#/$defs/Dollars"
-        }
-      ]
-    },
-    "supply": {
-      "allOf": [
-        {
-          "$ref": "#/$defs/Bitcoin"
-        }
-      ]
-    },
-    "unrealized_pnl": {
-      "allOf": [
-        {
-          "$ref": "#/$defs/Dollars"
-        }
-      ]
-    }
-  },
-  "required": [
-    "price_floor",
-    "supply",
-    "realized_cap",
-    "unrealized_pnl"
-  ],
-  "type": "object"
-}

addedOutput schema / $defs / UrpdBuckets

Added value: +{
+  "properties": {
+    "price": {
+      "items": {
+        "$ref": "#/$defs/Dollars"
+      },
+      "type": "array"
+    },
+    "realized_cap": {
+      "items": {
+        "$ref": "#/$defs/Dollars"
+      },
+      "type": "array"
+    },
+    "supply": {
+      "items": {
+        "$ref": "#/$defs/Bitcoin"
+      },
+      "type": "array"
+    },
+    "unrealized_pnl": {
+      "items": {
+        "$ref": "#/$defs/Dollars"
+      },
+      "type": "array"
+    }
+  },
+  "required": [
+    "price",
+    "supply",
+    "realized_cap",
+    "unrealized_pnl"
+  ],
+  "type": "object"
+}

addedOutput schema / $defs / UrpdCohort

Added value: +{
+  "enum": [
+    "all",
+    "sth",
+    "lth",
+    "age_under_4m",
+    "age_under_6m",
+    "age_over_4m",
+    "age_over_6m",
+    "age_under_1h",
+    "age_1h_to_1d",
+    "age_1d_to_1w",
+    "age_1w_to_1m",
+    "age_1m_to_2m",
+    "age_2m_to_3m",
+    "age_3m_to_4m",
+    "age_4m_to_5m",
+    "age_5m_to_6m",
+    "age_6m_to_9m",
+    "age_9m_to_1y",
+    "age_1y_to_18m",
+    "age_18m_to_2y",
+    "age_2y_to_3y",
+    "age_3y_to_4y",
+    "age_4y_to_5y",
+    "age_5y_to_6y",
+    "age_6y_to_7y",
+    "age_7y_to_8y",
+    "age_8y_to_10y",
+    "age_10y_to_12y",
+    "age_12y_to_15y",
+    "age_over_15y"
+  ],
+  "type": "string"
+}

changedOutput schema / $defs / UrpdWeight / enum

Previous value: -[
-  "raw",
-  "cointime",
-  "coinflow"
-]New value: +[
+  "none",
+  "wakefulness",
+  "mobility"
+]

First observedOct 23, 2026

TDQS

A3.7/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), so the description's added context is what counts: units per field, the fact that `unrealized_pnl` may be negative, the price-grid valuation basis with its tolerance, and the caveat that buckets need not sum to the realized cap series. Those are non-obvious behaviors an agent could not infer from the annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with purpose and point-selection, which is good, but a large share of the body restates the return payload field-by-field even though an output schema exists. The information is useful but not maximally economical.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a four-parameter read tool with an output schema and full annotations, the description supplies the semantics an agent needs: point resolution, aggregation effect, weighting effect, units, and the non-summing bucket caveat. Only the relationship to sibling tools is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 75%, so the baseline is already near 3, and the description adds real meaning beyond the schema: it explains the consequence of `weight` on the output (`supply` becomes weighted whole satoshis and bucket values follow) and pins the price-grid basis for `realized_cap`/`unrealized_pnl`. It does not explain `agg` beyond what the enum description already says.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific resource (URPD), a specific scope (a cohort at a block height or the last block of a UTC day), and names the REST route. An agent can tell it fetches a historical URPD snapshot rather than the current one, though it never names `get_urpd_latest` as the sibling it differs from.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is implied by the point-selection rule (a height or a UTC day resolves to that day's last block), which is genuinely useful selection logic. But there is no explicit when-to-use guidance, no mention of `get_urpd_latest` or `list_urpd_cohorts` as alternatives, and no stated prerequisites.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

All Bitview tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.