{
  "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 released closed-bucket Bitcoin metric time-series reads. Basic API keys use supported 1h and 1d intervals from 30 min with 100,000 API credits per month. Research API keys use supported 1h and 1d intervals from 30 min with 500,000 API credits per month. Premium API keys support real-time closed-bucket 10m, 1h, and 1d intervals for supported metrics with 2,000,000 API credits per month. Returned UTC timestamps identify the latest released point for each series.",
    "version": "2026-07-04"
  },
  "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"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/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"
          },
          "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 public metric routes.",
        "responses": {
          "200": {
            "description": "Supported metrics",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MetricCatalog"
                },
                "example": [
                  {
                    "path": "/v1/metrics/market/exchange_premium_gap",
                    "category": "market",
                    "metric": "exchange_premium_gap",
                    "name": "Exchange Premium Gap",
                    "description": "Difference between the supported exchange pair prices for BTC.",
                    "assets": [
                      "BTC"
                    ],
                    "intervals": [
                      "1h",
                      "1d"
                    ],
                    "required_params": [
                      "a",
                      "i",
                      "ex",
                      "ref_ex"
                    ],
                    "optional_params": [
                      "s",
                      "u",
                      "limit"
                    ],
                    "status": "current",
                    "response_shape": "stored_metric_point_series"
                  },
                  {
                    "path": "/v1/metrics/addresses/active_count",
                    "category": "addresses",
                    "metric": "active_count",
                    "name": "Active Addresses",
                    "description": "Count of distinct Bitcoin addresses active in the closed UTC interval.",
                    "assets": [
                      "BTC"
                    ],
                    "intervals": [
                      "10m",
                      "1h",
                      "1d"
                    ],
                    "required_params": [
                      "a",
                      "i"
                    ],
                    "optional_params": [
                      "s",
                      "u",
                      "limit"
                    ],
                    "status": "current",
                    "response_shape": "stored_metric_point_series"
                  }
                ]
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/metrics/{category}/{metric}": {
      "get": {
        "tags": [
          "metrics"
        ],
        "summary": "Metric time-series",
        "description": "API-keyed released closed-bucket metric time-series points. Metric responses return points shaped as t and v. Basic API keys support 1h and 1d reads from 30 min with limited history. Research API keys support 1h and 1d reads from 30 min with deeper history. Premium API keys support real-time closed-bucket 10m, 1h, and 1d intervals for supported metrics and full supported history. Returned UTC timestamps identify the latest released point for each series. Missing-source buckets are omitted rather than synthesized. Stored null rows can appear as v: 0.0 for public numeric compatibility. Rexilion API is not a tick feed, order-book feed, WebSocket stream, current partial candle feed, or trade execution system.",
        "parameters": [
          {
            "$ref": "#/components/parameters/CategoryPath"
          },
          {
            "$ref": "#/components/parameters/MetricPath"
          },
          {
            "$ref": "#/components/parameters/Asset"
          },
          {
            "$ref": "#/components/parameters/Interval"
          },
          {
            "$ref": "#/components/parameters/Exchange"
          },
          {
            "$ref": "#/components/parameters/MarketExchange"
          },
          {
            "$ref": "#/components/parameters/ReferenceExchange"
          },
          {
            "$ref": "#/components/parameters/StartMs"
          },
          {
            "$ref": "#/components/parameters/UntilMs"
          },
          {
            "$ref": "#/components/parameters/Limit"
          }
        ],
        "responses": {
          "200": {
            "description": "Stored metric points",
            "headers": {
              "x-rate-limit-limit": {
                "description": "Maximum requests allowed in the effective fixed window when a rate bucket applies.",
                "schema": {
                  "type": "integer",
                  "minimum": 0
                }
              },
              "x-rate-limit-remaining": {
                "description": "Requests remaining in the effective fixed window after this request when a rate bucket applies.",
                "schema": {
                  "type": "integer",
                  "minimum": 0
                }
              },
              "x-rate-limit-reset": {
                "description": "Seconds until the effective fixed window resets when a rate bucket applies.",
                "schema": {
                  "type": "integer",
                  "minimum": 0
                }
              }
            },
            "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"
          },
          "500": {
            "$ref": "#/components/responses/InternalServerError"
          },
          "502": {
            "$ref": "#/components/responses/SourceUnavailable"
          },
          "503": {
            "$ref": "#/components/responses/ServiceUnavailable"
          }
        }
      }
    }
  },
  "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"
        },
        "required": true
      },
      "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, 1h, or 1d depending on the metric and plan. Basic and Research support 1d and 1h. Premium supports 10m, 1h, and 1d for supported metrics.",
        "schema": {
          "type": "string",
          "example": "1h"
        },
        "required": true
      },
      "Exchange": {
        "name": "e",
        "in": "query",
        "description": "Exchange selector for exchange-scoped metric categories. Options routes require e=deribit.",
        "schema": {
          "type": "string",
          "enum": [
            "deribit"
          ],
          "example": "deribit"
        }
      },
      "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
        }
      },
      "Limit": {
        "name": "limit",
        "in": "query",
        "description": "Optional positive last-N stored row cap after filters. Default is 1000 when omitted. Maximum is 100000.",
        "schema": {
          "type": "integer",
          "minimum": 1,
          "default": 1000,
          "example": 500,
          "maximum": 100000
        }
      },
      "MarketExchange": {
        "name": "ex",
        "in": "query",
        "description": "Market exchange selector for market premium routes. Market routes require ex=coinbase_spot.",
        "schema": {
          "type": "string",
          "enum": [
            "coinbase_spot"
          ],
          "example": "coinbase_spot"
        }
      },
      "ReferenceExchange": {
        "name": "ref_ex",
        "in": "query",
        "description": "Reference exchange selector for market premium routes. Market routes require ref_ex=binance_spot.",
        "schema": {
          "type": "string",
          "enum": [
            "binance_spot"
          ],
          "example": "binance_spot"
        }
      }
    },
    "schemas": {
      "HealthResponse": {
        "type": "object",
        "properties": {
          "status": {
            "type": "string",
            "example": "ok"
          }
        },
        "required": [
          "status"
        ]
      },
      "MetricCategory": {
        "type": "string",
        "enum": [
          "addresses",
          "blocks",
          "chain",
          "fees",
          "market",
          "mining",
          "options",
          "supply",
          "transactions",
          "utxo"
        ]
      },
      "AssetList": {
        "type": "array",
        "items": {
          "$ref": "#/components/schemas/AssetDefinition"
        }
      },
      "MetricCatalog": {
        "type": "array",
        "items": {
          "$ref": "#/components/schemas/PublicMetricDefinition"
        },
        "description": "Metric definitions returned by the public Rexilion API metric catalog."
      },
      "MetricPoint": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "t": {
            "type": "integer",
            "format": "int64",
            "description": "UTC millisecond timestamp."
          },
          "v": {
            "type": "number",
            "format": "double",
            "description": "Numeric metric value for the requested public stored row, serialized from the canonical decimal value and metric precision contract when available. Source-missing timestamp buckets are omitted rather than synthesized."
          }
        },
        "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"
          },
          "code": {
            "type": "string",
            "description": "Optional stable machine-readable reason for specific validation failures.",
            "enum": [
              "unsupported_parameter"
            ]
          }
        },
        "required": [
          "error",
          "message"
        ]
      },
      "AssetDefinition": {
        "type": "object",
        "properties": {
          "asset": {
            "type": "string",
            "example": "BTC"
          },
          "display_name": {
            "type": "string",
            "example": "Bitcoin"
          },
          "asset_type": {
            "type": "string",
            "example": "crypto_asset"
          },
          "status": {
            "type": "string",
            "example": "current"
          }
        },
        "required": [
          "asset",
          "display_name",
          "asset_type",
          "status"
        ],
        "description": "Asset catalog entry returned by /v1/assets."
      },
      "PublicMetricDefinition": {
        "type": "object",
        "properties": {
          "path": {
            "type": "string",
            "example": "/v1/metrics/market/exchange_premium_gap"
          },
          "category": {
            "$ref": "#/components/schemas/MetricCategory"
          },
          "metric": {
            "type": "string",
            "example": "exchange_premium_gap"
          },
          "name": {
            "type": "string",
            "example": "Exchange Premium Gap"
          },
          "description": {
            "type": "string"
          },
          "assets": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "example": [
              "BTC"
            ]
          },
          "intervals": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "example": [
              "1h",
              "1d"
            ]
          },
          "required_params": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "example": [
              "a",
              "i",
              "ex",
              "ref_ex"
            ]
          },
          "optional_params": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "example": [
              "s",
              "u",
              "limit"
            ]
          },
          "status": {
            "type": "string",
            "example": "current"
          },
          "response_shape": {
            "type": "string",
            "example": "stored_metric_point_series"
          }
        },
        "required": [
          "path",
          "category",
          "metric",
          "name",
          "description",
          "assets",
          "intervals",
          "required_params",
          "optional_params",
          "status",
          "response_shape"
        ],
        "additionalProperties": false,
        "description": "Public metric definition returned by /v1/metadata/metrics."
      }
    },
    "responses": {
      "BadRequest": {
        "description": "Invalid category, metric, interval, asset, time bounds, or removed query alias. Removed aliases return code unsupported_parameter.",
        "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": "Rate or quota window exhausted.",
        "headers": {
          "x-rate-limit-limit": {
            "description": "Configured request limit for the exhausted or active window.",
            "schema": {
              "type": "integer",
              "example": 30
            }
          },
          "x-rate-limit-remaining": {
            "description": "Requests remaining in the current window after the decision.",
            "schema": {
              "type": "integer",
              "example": 0
            }
          },
          "x-rate-limit-reset": {
            "description": "Seconds until the rate or quota window resets.",
            "schema": {
              "type": "integer",
              "example": 60
            }
          },
          "retry-after": {
            "description": "Seconds to wait before retrying.",
            "schema": {
              "type": "integer",
              "example": 60
            }
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            },
            "examples": {
              "tooManyRequests": {
                "summary": "Rate or quota limit reached",
                "value": {
                  "error": "too_many_requests",
                  "message": "Rate or quota window exhausted"
                }
              }
            }
          }
        }
      },
      "SourceUnavailable": {
        "description": "Upstream source is temporarily unavailable.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            },
            "example": {
              "error": "upstream_error",
              "message": "Upstream source is temporarily unavailable"
            }
          }
        }
      },
      "InternalServerError": {
        "description": "Unexpected server error.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            },
            "example": {
              "error": "internal_error",
              "message": "Unexpected server-side failure"
            }
          }
        }
      },
      "ServiceUnavailable": {
        "description": "Quota, cache, control-plane, or storage dependency is unavailable.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            },
            "example": {
              "error": "service_unavailable",
              "message": "API quota enforcement unavailable"
            }
          }
        }
      }
    }
  },
  "x-rexilion-public-metrics": [
    {
      "category": "addresses",
      "routePattern": "/v1/metrics/addresses/{metric}",
      "intervals": [
        "10m",
        "1h",
        "1d"
      ],
      "metrics": [
        "receiving_count",
        "sending_count",
        "active_count"
      ],
      "requiredParameters": {
        "a": "BTC",
        "i": "10m or 1h or 1d"
      }
    },
    {
      "category": "blocks",
      "routePattern": "/v1/metrics/blocks/{metric}",
      "intervals": [
        "10m",
        "1h",
        "1d"
      ],
      "metrics": [
        "count",
        "transaction_count_mean",
        "fee_total_mean",
        "weight_utilization_mean",
        "blockspace_feerate_mean",
        "transaction_density_mean",
        "weight_total",
        "weight_mean"
      ],
      "requiredParameters": {
        "a": "BTC",
        "i": "10m or 1h or 1d"
      }
    },
    {
      "category": "chain",
      "routePattern": "/v1/metrics/chain/{metric}",
      "intervals": [
        "10m",
        "1h",
        "1d"
      ],
      "metrics": [
        "block_interval_mean"
      ],
      "requiredParameters": {
        "a": "BTC",
        "i": "10m or 1h or 1d"
      }
    },
    {
      "category": "fees",
      "routePattern": "/v1/metrics/fees/{metric}",
      "intervals": [
        "10m",
        "1h",
        "1d"
      ],
      "metrics": [
        "total",
        "rate_mean",
        "transaction_mean",
        "fee_paying_transaction_mean",
        "feerate_mean",
        "high_fee_vbytes_share"
      ],
      "requiredParameters": {
        "a": "BTC",
        "i": "10m or 1h or 1d"
      }
    },
    {
      "category": "market",
      "routePattern": "/v1/metrics/market/{metric}",
      "intervals": [
        "1h",
        "1d"
      ],
      "metrics": [
        "exchange_premium_gap",
        "exchange_premium_index"
      ],
      "requiredParameters": {
        "a": "BTC",
        "i": "1h or 1d",
        "ex": "coinbase_spot",
        "ref_ex": "binance_spot"
      }
    },
    {
      "category": "mining",
      "routePattern": "/v1/metrics/mining/{metric}",
      "intervals": [
        "10m",
        "1h",
        "1d"
      ],
      "metrics": [
        "subsidy_total",
        "revenue_total",
        "fee_revenue_share",
        "revenue_rate_mean",
        "fee_to_subsidy_ratio",
        "hash_rate_mean",
        "subsidy_mean",
        "revenue_mean"
      ],
      "requiredParameters": {
        "a": "BTC",
        "i": "10m or 1h or 1d"
      }
    },
    {
      "category": "options",
      "routePattern": "/v1/metrics/options/{metric}",
      "intervals": [
        "10m",
        "1h",
        "1d"
      ],
      "requiredParameters": {
        "a": "BTC",
        "i": "10m or 1h or 1d",
        "e": "deribit"
      },
      "metrics": [
        "volume",
        "call_volume",
        "put_volume",
        "buy_volume",
        "sell_volume",
        "call_buy_volume_usd",
        "call_sell_volume_usd",
        "put_buy_volume_usd",
        "put_sell_volume_usd",
        "call_premium_paid_usd",
        "call_premium_received_usd",
        "put_premium_paid_usd",
        "put_premium_received_usd",
        "trade_iv_weighted",
        "trade_iv_call_weighted",
        "trade_iv_put_weighted",
        "trade_iv_put_call_spread",
        "trade_mark_premium_usd",
        "trade_vs_mark_premium_usd",
        "block_trade_volume",
        "combo_trade_volume",
        "rfq_trade_volume",
        "uptick_volume",
        "downtick_volume",
        "option_tick_imbalance"
      ]
    },
    {
      "category": "supply",
      "routePattern": "/v1/metrics/supply/{metric}",
      "intervals": [
        "10m",
        "1h",
        "1d"
      ],
      "metrics": [
        "issuance_rate_mean",
        "issued_total",
        "utxo_total_amount",
        "unspendable_total_amount"
      ],
      "requiredParameters": {
        "a": "BTC",
        "i": "10m or 1h or 1d"
      }
    },
    {
      "category": "transactions",
      "routePattern": "/v1/metrics/transactions/{metric}",
      "intervals": [
        "10m",
        "1h",
        "1d"
      ],
      "metrics": [
        "count",
        "fee_paying_count",
        "input_count",
        "output_count",
        "rate_mean",
        "fee_paying_rate_mean",
        "fee_paying_share",
        "size_total",
        "size_mean",
        "segwit_count"
      ],
      "requiredParameters": {
        "a": "BTC",
        "i": "10m or 1h or 1d"
      }
    },
    {
      "category": "utxo",
      "routePattern": "/v1/metrics/utxo/{metric}",
      "intervals": [
        "10m",
        "1h",
        "1d"
      ],
      "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"
      ],
      "requiredParameters": {
        "a": "BTC",
        "i": "10m or 1h or 1d"
      }
    }
  ]
}