# Bitcoin Monthly Return — Technical Specification & Schema

This document provides the exhaustive technical breakdown, data dictionary, and schema representations for the Bitcoin Monthly Return dataset.

## Data Dictionary & Calculation Methodology

### Fields
- **Year (Integer):** The 4-digit calendar year (e.g., 2024).
- **Month (String/Float):** January through December. Represented as a percentage change float.
- **YTD / Annual (Float):** The cumulative geometric return for the entire calendar year.

### Formula
Monthly returns are calculated using the asset's USD opening price on the 1st of the month ($P_{open}$) and the closing price on the final day of the month ($P_{close}$) based on UTC timestamps:

$$\text{Return } (\%) = \left( \frac{P_{close} - P_{open}}{P_{open}} \right) \times 100$$

Annual/YTD return is calculated geometrically across all completed months:

$$\text{YTD } (\%) = \left( \prod_{i=1}^{n} (1 + R_i) - 1 \right) \times 100$$
Where $R_i$ is the decimal return of month $i$.

---

## Data Schema (JSON Format)

If parsing the raw matrix or hitting the `/api/v1/returns` endpoint, the data adheres to the following structures.

### JSON Schema Definition
```json
{
  "$schema": "[https://json-schema.org/draft/2020-12/schema](https://json-schema.org/draft/2020-12/schema)",
  "title": "BitcoinMonthlyReturnDataset",
  "type": "object",
  "properties": {
    "updated_at": {
      "type": "string",
      "format": "date-time",
      "description": "ISO 8601 timestamp of the last data update."
    },
    "data": {
      "type": "array",
      "items": {
        "type": "object",
        "required": ["year", "months", "ytd"],
        "properties": {
          "year": {
            "type": "integer",
            "minimum": 2010,
            "maximum": 2030
          },
          "months": {
            "type": "object",
            "properties": {
              "jan": { "type": ["number", "null"] },
              "feb": { "type": ["number", "null"] },
              "mar": { "type": ["number", "null"] },
              "apr": { "type": ["number", "null"] },
              "may": { "type": ["number", "null"] },
              "jun": { "type": ["number", "null"] },
              "jul": { "type": ["number", "null"] },
              "aug": { "type": ["number", "null"] },
              "sep": { "type": ["number", "null"] },
              "oct": { "type": ["number", "null"] },
              "nov": { "type": ["number", "null"] },
              "dec": { "type": ["number", "null"] }
            },
            "additionalProperties": false
          },
          "ytd": {
            "type": "number",
            "description": "Year-to-date or final annual percentage return."
          }
        }
      }
    },
    "statistics": {
      "type": "object",
      "properties": {
        "monthly_averages": {
          "type": "object",
          "description": "The mean percentage return for each month across all historical years."
        },
        "win_rates": {
          "type": "object",
          "description": "The percentage of times a specific month closed positive historically."
        }
      }
    }
  },
  "required": ["updated_at", "data"]
}