{
  "openapi": "3.1.0",
  "info": {
    "title": "Rexilion API",
    "summary": "Bitcoin market and on-chain metrics API for integration teams.",
    "description": "Public sanitized OpenAPI reference for Rexilion API. Authenticated accounts use X-API-Key to access catalog discovery and real-time Bitcoin metric time-series reads across 53 public metric routes. Returned UTC timestamps identify the latest available point for each series.",
    "version": "2026-06-26"
  },
  "servers": [
    {
      "url": "https://api.rexilion.com",
      "description": "Rexilion API production base URL"
    }
  ],
  "security": [
    {
      "ApiKeyAuth": []
    }
  ],
  "tags": [
    {
      "name": "health",
      "description": "Process liveness"
    },
    {
      "name": "catalog",
      "description": "Asset and metric discovery"
    },
    {
      "name": "metrics",
      "description": "Stored Bitcoin metric time-series reads"
    }
  ],
  "paths": {
    "/health": {
      "get": {
        "tags": [
          "health"
        ],
        "summary": "Health check",
        "description": "Anonymous process liveness check.",
        "security": [],
        "responses": {
          "200": {
            "description": "Service is reachable",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HealthResponse"
                },
                "example": {
                  "status": "ok"
                }
              }
            }
          }
        }
      }
    },
    "/openapi.json": {
      "get": {
        "tags": [
          "catalog"
        ],
        "summary": "Sanitized OpenAPI contract",
        "description": "API-keyed sanitized OpenAPI contract.",
        "responses": {
          "200": {
            "description": "OpenAPI document",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      }
    },
    "/v1/assets": {
      "get": {
        "tags": [
          "catalog"
        ],
        "summary": "Asset catalog",
        "description": "API-keyed asset catalog.",
        "responses": {
          "200": {
            "description": "Supported assets",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AssetList"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/metadata/metrics": {
      "get": {
        "tags": [
          "catalog"
        ],
        "summary": "Metric catalog",
        "description": "API-keyed metric catalog with categories, metric names, supported intervals, assets, and integration parameters for 53 public metric routes.",
        "parameters": [
          {
            "$ref": "#/components/parameters/Asset"
          },
          {
            "$ref": "#/components/parameters/Category"
          }
        ],
        "responses": {
          "200": {
            "description": "Supported metrics",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MetricCatalog"
                },
                "example": [
                  {
                    "category": "market",
                    "routePattern": "/v1/metrics/market/{metric}",
                    "asset": "BTC",
                    "intervals": [
                      "1h"
                    ],
                    "metrics": [
                      "exchange_premium_gap",
                      "exchange_premium_index"
                    ]
                  },
                  {
                    "category": "addresses",
                    "routePattern": "/v1/metrics/addresses/{metric}",
                    "asset": "BTC",
                    "intervals": [
                      "1h"
                    ],
                    "metrics": [
                      "receiving_count",
                      "sending_count",
                      "active_count"
                    ]
                  },
                  {
                    "category": "blocks",
                    "routePattern": "/v1/metrics/blocks/{metric}",
                    "asset": "BTC",
                    "intervals": [
                      "10m",
                      "1h"
                    ],
                    "metrics": [
                      "count",
                      "transaction_count_mean",
                      "fee_total_mean",
                      "weight_utilization_mean",
                      "blockspace_feerate_mean",
                      "transaction_density_mean",
                      "weight_total",
                      "weight_mean"
                    ]
                  },
                  {
                    "category": "transactions",
                    "routePattern": "/v1/metrics/transactions/{metric}",
                    "asset": "BTC",
                    "intervals": [
                      "10m",
                      "1h"
                    ],
                    "metrics": [
                      "count",
                      "fee_paying_count",
                      "input_count",
                      "output_count",
                      "rate_mean",
                      "fee_paying_rate_mean",
                      "fee_paying_share",
                      "size_total",
                      "size_mean",
                      "segwit_count"
                    ]
                  },
                  {
                    "category": "fees",
                    "routePattern": "/v1/metrics/fees/{metric}",
                    "asset": "BTC",
                    "intervals": [
                      "10m",
                      "1h"
                    ],
                    "metrics": [
                      "total",
                      "rate_mean",
                      "transaction_mean",
                      "fee_paying_transaction_mean",
                      "feerate_mean",
                      "high_fee_vbytes_share"
                    ]
                  },
                  {
                    "category": "chain",
                    "routePattern": "/v1/metrics/chain/{metric}",
                    "asset": "BTC",
                    "intervals": [
                      "10m",
                      "1h"
                    ],
                    "metrics": [
                      "block_interval_mean"
                    ]
                  },
                  {
                    "category": "mining",
                    "routePattern": "/v1/metrics/mining/{metric}",
                    "asset": "BTC",
                    "intervals": [
                      "10m",
                      "1h"
                    ],
                    "metrics": [
                      "subsidy_total",
                      "revenue_total",
                      "fee_revenue_share",
                      "revenue_rate_mean",
                      "fee_to_subsidy_ratio",
                      "hash_rate_mean",
                      "subsidy_mean",
                      "revenue_mean"
                    ]
                  },
                  {
                    "category": "supply",
                    "routePattern": "/v1/metrics/supply/{metric}",
                    "asset": "BTC",
                    "intervals": [
                      "10m",
                      "1h"
                    ],
                    "metrics": [
                      "issuance_rate_mean",
                      "issued_total",
                      "utxo_total_amount",
                      "unspendable_total_amount"
                    ]
                  },
                  {
                    "category": "utxo",
                    "routePattern": "/v1/metrics/utxo/{metric}",
                    "asset": "BTC",
                    "intervals": [
                      "10m",
                      "1h"
                    ],
                    "metrics": [
                      "change_count_actual",
                      "size_change_bytes_actual",
                      "set_output_count",
                      "block_spent_value",
                      "block_created_value",
                      "block_unspendable_value",
                      "net_created_value",
                      "turnover_ratio",
                      "coin_days_destroyed",
                      "spent_value_total",
                      "average_spent_age_days"
                    ]
                  }
                ]
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/metrics/{category}/{metric}": {
      "get": {
        "tags": [
          "metrics"
        ],
        "summary": "Metric time-series",
        "description": "API-keyed real-time metric time-series points. Metric responses return points shaped as t and v. Returned UTC timestamps identify the latest available point for each series. Missing-source buckets are not synthesized.",
        "parameters": [
          {
            "$ref": "#/components/parameters/CategoryPath"
          },
          {
            "$ref": "#/components/parameters/MetricPath"
          },
          {
            "$ref": "#/components/parameters/Asset"
          },
          {
            "$ref": "#/components/parameters/Interval"
          },
          {
            "$ref": "#/components/parameters/StartMs"
          },
          {
            "$ref": "#/components/parameters/UntilMs"
          }
        ],
        "responses": {
          "200": {
            "description": "Stored metric points",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MetricPointList"
                },
                "example": [
                  {
                    "t": 1718582400000,
                    "v": 62.14
                  }
                ]
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "502": {
            "$ref": "#/components/responses/SourceUnavailable"
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      }
    },
    "parameters": {
      "Asset": {
        "name": "a",
        "in": "query",
        "description": "Asset symbol. Public Bitcoin series use BTC.",
        "schema": {
          "type": "string",
          "example": "BTC"
        }
      },
      "Category": {
        "name": "category",
        "in": "query",
        "description": "Optional metric category filter.",
        "schema": {
          "$ref": "#/components/schemas/MetricCategory"
        }
      },
      "CategoryPath": {
        "name": "category",
        "in": "path",
        "required": true,
        "description": "Metric category.",
        "schema": {
          "$ref": "#/components/schemas/MetricCategory"
        }
      },
      "MetricPath": {
        "name": "metric",
        "in": "path",
        "required": true,
        "description": "Metric name from the public metric catalog. Exact available slugs are listed in x-rexilion-public-metrics and returned by /v1/metadata/metrics.",
        "schema": {
          "type": "string",
          "example": "hash_rate_mean"
        }
      },
      "Interval": {
        "name": "i",
        "in": "query",
        "description": "Metric interval, such as 10m or 1h depending on the metric.",
        "schema": {
          "type": "string",
          "example": "10m"
        }
      },
      "StartMs": {
        "name": "s",
        "in": "query",
        "description": "Optional lower UTC millisecond bound.",
        "schema": {
          "type": "integer",
          "format": "int64",
          "example": 1718582400000
        }
      },
      "UntilMs": {
        "name": "u",
        "in": "query",
        "description": "Optional upper UTC millisecond bound.",
        "schema": {
          "type": "integer",
          "format": "int64",
          "example": 1718668800000
        }
      }
    },
    "schemas": {
      "HealthResponse": {
        "type": "object",
        "properties": {
          "status": {
            "type": "string",
            "example": "ok"
          }
        },
        "required": [
          "status"
        ]
      },
      "MetricCategory": {
        "type": "string",
        "enum": [
          "market",
          "addresses",
          "blocks",
          "transactions",
          "fees",
          "chain",
          "mining",
          "supply",
          "utxo"
        ]
      },
      "AssetList": {
        "type": "array",
        "items": {
          "type": "object",
          "properties": {
            "asset": {
              "type": "string",
              "example": "BTC"
            },
            "name": {
              "type": "string",
              "example": "Bitcoin"
            }
          }
        }
      },
      "MetricCatalog": {
        "type": "array",
        "items": {
          "type": "object",
          "properties": {
            "category": {
              "$ref": "#/components/schemas/MetricCategory"
            },
            "metric": {
              "type": "string",
              "example": "hash_rate_mean"
            },
            "asset": {
              "type": "string",
              "example": "BTC"
            },
            "intervals": {
              "type": "array",
              "items": {
                "type": "string"
              },
              "example": [
                "10m",
                "1h"
              ]
            },
            "description": {
              "type": "string"
            }
          },
          "required": [
            "category",
            "metric"
          ]
        },
        "description": "Metric catalog entries for the 53 public Rexilion API metric routes."
      },
      "MetricPoint": {
        "type": "object",
        "properties": {
          "t": {
            "type": "integer",
            "format": "int64",
            "description": "UTC millisecond timestamp."
          },
          "v": {
            "type": "number",
            "description": "Stored metric value."
          }
        },
        "required": [
          "t",
          "v"
        ]
      },
      "MetricPointList": {
        "type": "array",
        "items": {
          "$ref": "#/components/schemas/MetricPoint"
        }
      },
      "ErrorResponse": {
        "type": "object",
        "properties": {
          "error": {
            "type": "string",
            "example": "unauthorized"
          },
          "message": {
            "type": "string",
            "example": "X-API-Key header is required"
          }
        }
      }
    },
    "responses": {
      "BadRequest": {
        "description": "Invalid category, metric, interval, asset, or time bounds.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            }
          }
        }
      },
      "Unauthorized": {
        "description": "Missing, expired, or invalid API key.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            }
          }
        }
      },
      "Forbidden": {
        "description": "Valid key, but the requested access is not enabled.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            }
          }
        }
      },
      "RateLimited": {
        "description": "Request pacing limit reached.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            }
          }
        }
      },
      "SourceUnavailable": {
        "description": "Upstream source is temporarily unavailable.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            }
          }
        }
      }
    }
  },
  "x-rexilion-public-metrics": [
    {
      "category": "market",
      "routePattern": "/v1/metrics/market/{metric}",
      "intervals": [
        "1h"
      ],
      "metrics": [
        "exchange_premium_gap",
        "exchange_premium_index"
      ]
    },
    {
      "category": "addresses",
      "routePattern": "/v1/metrics/addresses/{metric}",
      "intervals": [
        "1h"
      ],
      "metrics": [
        "receiving_count",
        "sending_count",
        "active_count"
      ]
    },
    {
      "category": "blocks",
      "routePattern": "/v1/metrics/blocks/{metric}",
      "intervals": [
        "10m",
        "1h"
      ],
      "metrics": [
        "count",
        "transaction_count_mean",
        "fee_total_mean",
        "weight_utilization_mean",
        "blockspace_feerate_mean",
        "transaction_density_mean",
        "weight_total",
        "weight_mean"
      ]
    },
    {
      "category": "transactions",
      "routePattern": "/v1/metrics/transactions/{metric}",
      "intervals": [
        "10m",
        "1h"
      ],
      "metrics": [
        "count",
        "fee_paying_count",
        "input_count",
        "output_count",
        "rate_mean",
        "fee_paying_rate_mean",
        "fee_paying_share",
        "size_total",
        "size_mean",
        "segwit_count"
      ]
    },
    {
      "category": "fees",
      "routePattern": "/v1/metrics/fees/{metric}",
      "intervals": [
        "10m",
        "1h"
      ],
      "metrics": [
        "total",
        "rate_mean",
        "transaction_mean",
        "fee_paying_transaction_mean",
        "feerate_mean",
        "high_fee_vbytes_share"
      ]
    },
    {
      "category": "chain",
      "routePattern": "/v1/metrics/chain/{metric}",
      "intervals": [
        "10m",
        "1h"
      ],
      "metrics": [
        "block_interval_mean"
      ]
    },
    {
      "category": "mining",
      "routePattern": "/v1/metrics/mining/{metric}",
      "intervals": [
        "10m",
        "1h"
      ],
      "metrics": [
        "subsidy_total",
        "revenue_total",
        "fee_revenue_share",
        "revenue_rate_mean",
        "fee_to_subsidy_ratio",
        "hash_rate_mean",
        "subsidy_mean",
        "revenue_mean"
      ]
    },
    {
      "category": "supply",
      "routePattern": "/v1/metrics/supply/{metric}",
      "intervals": [
        "10m",
        "1h"
      ],
      "metrics": [
        "issuance_rate_mean",
        "issued_total",
        "utxo_total_amount",
        "unspendable_total_amount"
      ]
    },
    {
      "category": "utxo",
      "routePattern": "/v1/metrics/utxo/{metric}",
      "intervals": [
        "10m",
        "1h"
      ],
      "metrics": [
        "change_count_actual",
        "size_change_bytes_actual",
        "set_output_count",
        "block_spent_value",
        "block_created_value",
        "block_unspendable_value",
        "net_created_value",
        "turnover_ratio",
        "coin_days_destroyed",
        "spent_value_total",
        "average_spent_age_days"
      ]
    }
  ]
}