{
  "endpoint": "synternet.tbtc-dapp.history",
  "description": "Retrieve historical TVL, supply, and reserve data including collateralization ratio and chain distribution metrics",

  "payload": {
    "type": "object",
    "properties": {
      "start_time": {
        "type": "string",
        "format": "date-time",
        "description": "Optional - Start time for historical data (defaults to 6 months ago)",
        "example": "2024-01-01T00:00:00Z"
      },
      "end_time": {
        "type": "string",
        "format": "date-time",
        "description": "Optional - End time for historical data (defaults to current time)",
        "example": "2024-02-01T00:00:00Z"
      }
    }
  },

  "response": {
    "type": "object",
    "properties": {
      "start_time": {
        "type": "string",
        "format": "date-time",
        "description": "Start time of the returned data range"
      },
      "end_time": {
        "type": "string",
        "format": "date-time",
        "description": "End time of the returned data range"
      },
      "metrics": {
        "type": "array",
        "items": {
          "type": "object",
          "properties": {
            "date": {
              "type": "string",
              "format": "date-time",
              "description": "Date of the metrics (UTC)"
            },
            "total_btc_reserves": {
              "type": "number",
              "format": "decimal",
              "description": "Total BTC in custodial wallets"
            },
            "total_minted_supply": {
              "type": "number",
              "format": "decimal",
              "description": "Total tBTC minted across all chains"
            },
            "discrepancy": {
              "type": "number",
              "format": "decimal",
              "description": "Difference between custodial balances and minted supply (in BTC)"
            },
            "discrepancy_usd": {
              "type": "number",
              "format": "decimal",
              "description": "USD value of the discrepancy"
            },
            "collateralization_ratio": {
              "type": "number",
              "format": "decimal",
              "description": "Ratio of custodial BTC to minted supply as percentage (custodial/minted * 100)"
            },
            "price_snapshot": {
              "type": "number",
              "format": "decimal",
              "description": "BTC price in USD at the time of the snapshot"
            },
            "chains": {
              "type": "array",
              "items": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string",
                    "description": "Name of the blockchain network"
                  },
                  "amount": {
                    "type": "number",
                    "description": "Amount of tBTC on the chain"
                  },
                  "usd_amount": {
                    "type": "number",
                    "description": "USD value of tBTC on the chain"
                  }
                }
              },
              "description": "Distribution of tBTC across different chains"
            }
          }
        }
      }
    }
  },

  "examples": {
    "default_request": {
      "description": "Fetch last 6 months of TVL history",
      "payload": {},
      "response": {
        "start_time": "2023-08-04T00:00:00Z",
        "end_time": "2024-02-04T00:00:00Z",
        "metrics": [
          {
            "date": "2023-08-04T00:00:00Z",
            "total_btc_reserves": 560.50,
            "total_minted_supply": 532.20,
            "discrepancy": 28.30,
            "discrepancy_usd": 1216900.00,
            "collateralization_ratio": 105.32,
            "price_snapshot": 43000.00,
            "chains": [
              {
                "name": "Ethereum",
                "amount": 200.75,
                "usd_amount": 8632250.00
              },
              {
                "name": "Arbitrum",
                "amount": 150.25,
                "usd_amount": 6460750.00
              },
              {
                "name": "Base",
                "amount": 75.50,
                "usd_amount": 3246500.00
              },
              {
                "name": "Optimism",
                "amount": 50.25,
                "usd_amount": 2160750.00
              },
              {
                "name": "Polygon",
                "amount": 30.12,
                "usd_amount": 1295160.00
              },
              {
                "name": "Solana",
                "amount": 25.33,
                "usd_amount": 1089190.00
              }
            ]
          }
        ]
      }
    },
    "custom_range_request": {
      "description": "Fetch TVL history for a specific date range",
      "payload": {
        "start_time": "2024-01-01T00:00:00Z",
        "end_time": "2024-02-01T00:00:00Z"
      },
      "response": {
        "start_time": "2024-01-01T00:00:00Z",
        "end_time": "2024-02-01T00:00:00Z",
        "metrics": [
          {
            "date": "2024-01-01T00:00:00Z",
            "total_btc_reserves": 560.00,
            "total_minted_supply": 532.20,
            "discrepancy": 27.80,
            "discrepancy_usd": 1197286.32,
            "collateralization_ratio": 105.22,
            "price_snapshot": 43067.89,
            "chains": [
              {
                "name": "Ethereum",
                "amount": 200.75,
                "usd_amount": 8642000.75
              },
              {
                "name": "Arbitrum",
                "amount": 150.25,
                "usd_amount": 6481500.25
              },
              {
                "name": "Base",
                "amount": 75.50,
                "usd_amount": 3251500.50
              },
              {
                "name": "Optimism",
                "amount": 50.25,
                "usd_amount": 2165775.25
              },
              {
                "name": "Polygon",
                "amount": 30.12,
                "usd_amount": 1297270.83
              },
              {
                "name": "Solana",
                "amount": 25.33,
                "usd_amount": 1090910.56
              }
            ]
          }
        ]
      }
    }
  },

  "notes": {
    "data_availability": [
      "Data is available from the feature deployment date",
      "Metrics are calculated daily",
      "Days with no transactions will use the last known values",
      "Missing days (no data) are not included in the response"
    ],
    "time_handling": [
      "All timestamps are in UTC",
      "Data points represent daily snapshots",
      "Maximum supported date range is one year",
      "Default range is last 6 months if not specified"
    ],
    "calculation_details": [
      "Collateralization ratio = (total_btc_reserves / total_minted_supply) * 100",
      "Discrepancy = total_btc_reserves - total_minted_supply",
      "Chain amounts show the distribution of tBTC across networks",
      "All BTC amounts use 8 decimal precision",
      "USD amounts use 2 decimal precision",
      "L2 networks (Arbitrum, Base, Optimism, Polygon) metrics include cross-chain transfers via Wormhole",
      "Solana metrics track tBTC SPL token mints and burns"
    ]
  },
  "update_frequency": "Data is updated daily"
}