{"openapi":"3.1.0","info":{"title":"blocklens On-Chain API","license":{"name":"License","url":"https://blocklens.co/terms"},"version":"1.0.0"},"paths":{"/v1/chart/renders/{render_id}.png":{"get":{"tags":["Chart Snapshots"],"summary":"Get a rendered chart image","description":"Serve a previously rendered chart PNG by its render ID. Renders expire after 1 hour.","operationId":"get_chart_render_v1_chart_renders__render_id__png_get","parameters":[{"name":"render_id","in":"path","required":true,"schema":{"type":"string","title":"Render Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}},"image/png":{"schema":{"type":"string","format":"binary"}}}},"404":{"description":"Render expired or not found"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/chart/renders/{render_id}.svg":{"get":{"tags":["Chart Snapshots"],"summary":"Get a rendered chart SVG","description":"Serve a previously rendered chart SVG by its render ID. Renders expire after 1 hour.","operationId":"get_chart_render_svg_v1_chart_renders__render_id__svg_get","parameters":[{"name":"render_id","in":"path","required":true,"schema":{"type":"string","title":"Render Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}},"image/svg+xml":{"schema":{"type":"string"}}}},"404":{"description":"Render expired or not found"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/chart/snapshot":{"get":{"tags":["Chart Snapshots"],"summary":"Render chart snapshot","description":"Render an on-chain analytics chart as a PNG image, SVG vector graphic, or JSON metadata.\n\nProvide exactly one of: `metric` (single), `metrics` (comma-separated), or `template`.\n\n**Output format** is controlled via the `Accept` header:\n- `image/png` (default) — PNG image\n- `image/svg+xml` — SVG vector graphic\n- `application/json` — chart metadata (no image rendered)\n\n**Examples:**\n- `GET /v1/chart/snapshot?metric=price` — BTC price chart\n- `GET /v1/chart/snapshot?metrics=lth_supply,sth_supply&style=area&days=730` — multi-metric area chart\n- `GET /v1/chart/snapshot?template=mvrv_ratio&theme=dark` — dark-themed MVRV template\n\n**Access:** Requires Pro or Enterprise tier. Rate limits: 60/hour (Pro), 300/hour (Enterprise).\n\nSmart defaults: colors, axis placement, chart styles, and titles are auto-configured from the metrics registry.\n\n**Formula warmup:** When using formulas with rolling windows (e.g., `sma(m1, 200)`), set `warmup_days` to\nthe rolling window period. This fetches extra historical data before the start date so that formula values\nare computed from the very first displayed data point (instead of showing nulls).","operationId":"get_chart_snapshot_v1_chart_snapshot_get","parameters":[{"name":"metric","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Single metric ID","examples":["price","lth_supply","mvrv"],"title":"Metric"},"description":"Single metric ID"},{"name":"metrics","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Comma-separated metric IDs (max 6)","examples":["lth_supply,sth_supply","price,market_cap"],"title":"Metrics"},"description":"Comma-separated metric IDs (max 6)"},{"name":"template","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Chart template ID","examples":["mvrv_ratio","holder_supply","price_volume"],"title":"Template"},"description":"Chart template ID"},{"name":"days","in":"query","required":false,"schema":{"type":"integer","maximum":10000,"minimum":7,"description":"Days of history (default 365)","default":365,"title":"Days"},"description":"Days of history (default 365)"},{"name":"start_date","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Start date (YYYY-MM-DD)","examples":["2024-01-01"],"title":"Start Date"},"description":"Start date (YYYY-MM-DD)"},{"name":"end_date","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"End date (YYYY-MM-DD)","examples":["2025-12-31"],"title":"End Date"},"description":"End date (YYYY-MM-DD)"},{"name":"style","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Chart style: line, area, bar","title":"Style"},"description":"Chart style: line, area, bar"},{"name":"scale","in":"query","required":false,"schema":{"type":"string","description":"Y-axis scale: linear or log","default":"linear","title":"Scale"},"description":"Y-axis scale: linear or log"},{"name":"overlay","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Add price overlay as a subtle dashed line on the right axis (use 'price')","title":"Overlay"},"description":"Add price overlay as a subtle dashed line on the right axis (use 'price')"},{"name":"width","in":"query","required":false,"schema":{"type":"integer","maximum":2400,"minimum":600,"description":"Image width in pixels (default 1200)","default":1200,"title":"Width"},"description":"Image width in pixels (default 1200)"},{"name":"height","in":"query","required":false,"schema":{"type":"integer","maximum":1200,"minimum":300,"description":"Image height in pixels (default 600)","default":600,"title":"Height"},"description":"Image height in pixels (default 600)"},{"name":"title","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":120},{"type":"null"}],"description":"Custom chart title (auto-generated if omitted)","title":"Title"},"description":"Custom chart title (auto-generated if omitted)"},{"name":"theme","in":"query","required":false,"schema":{"type":"string","description":"Color theme: light or dark","default":"light","title":"Theme"},"description":"Color theme: light or dark"},{"name":"warmup_days","in":"query","required":false,"schema":{"type":"integer","maximum":730,"minimum":0,"description":"Extra days before start_date for formula rolling window warmup (0-730)","default":0,"title":"Warmup Days"},"description":"Extra days before start_date for formula rolling window warmup (0-730)"}],"responses":{"200":{"description":"Chart image (PNG/SVG) or JSON metadata, depending on Accept header","content":{"application/json":{"schema":{"type":"object"},"example":{"success":true,"title":"BTC Price","metrics":[{"id":"price","label":"Price"}],"days":365,"theme":"light","width":1200,"height":600,"formulas":[],"data_points":365,"cached":false,"render_time_ms":0}},"image/png":{"schema":{"type":"string","format":"binary"},"example":"(binary PNG image data)"},"image/svg+xml":{"schema":{"type":"string"},"example":""}}},"400":{"description":"Invalid parameters (e.g., unknown metric, conflicting inputs)","content":{"application/json":{"examples":{"missing_source":{"summary":"No metric source specified","value":{"success":false,"error":"invalid_params","message":"Exactly one of 'metric', 'metrics', or 'template' must be provided"}},"unknown_metric":{"summary":"Unknown metric ID","value":{"success":false,"error":"invalid_params","message":"Unknown metric 'foo_bar'"}}}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"example":{"success":false,"error":"unauthorized","message":"API key required"}}}},"403":{"description":"Requires Pro+ tier, or insufficient grade for requested metrics","content":{"application/json":{"example":{"success":false,"error":"insufficient_tier","message":"Snapshot API requires Pro or Enterprise tier","current_tier":"free","upgrade_url":"https://blocklens.co/pricing"}}}},"429":{"description":"Snapshot rate limit exceeded (per-tier hourly limit)","content":{"application/json":{"example":{"success":false,"error":"rate_limited","message":"Snapshot rate limit exceeded. Max 60 per hour for pro tier.","retry_after":120}}}},"504":{"description":"Chart rendering timed out — try a shorter date range","content":{"application/json":{"example":{"success":false,"error":"render_timeout","message":"Chart rendering timed out after 20.0s. Try a shorter date range."}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"post":{"tags":["Chart Snapshots"],"summary":"Render custom chart snapshot","description":"Render a fully customized chart snapshot from a JSON body. Returns PNG, SVG, or JSON.\n\nDesigned for AI agents (MCP), automated pipelines, and advanced users. Supports per-metric styling,\ncustom Y-axes, formulas (SMA, EMA, ratios), dark theme, stack groups, and stroke patterns.\n\n**`metrics` field supports mixed types:**\n- Strings (shorthand): `[\"price\", \"lth_supply\"]`\n- Objects (full config): `[{\"id\": \"price\", \"axis\": \"right\", \"style\": \"line\"}]`\n- Mixed: `[\"price\", {\"id\": \"lth_supply\", \"axis\": \"left\", \"style\": \"area\"}]`\n\n**Output format** is controlled via the `format` field or `Accept` header:\n- `\"png\"` (default) — PNG image\n- `\"svg\"` — SVG vector graphic\n- `\"json\"` — chart metadata (no image rendered)\n\nAll fields except `metrics` (or `metric`/`template`) are optional with smart defaults.\n\n**Formula warmup:** When using formulas with rolling windows, set `warmup_days` (0-730) to the largest\nrolling window period used. Extra data is fetched before the display range and trimmed after evaluation.","operationId":"post_chart_snapshot_v1_chart_snapshot_post","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SnapshotPostRequest"}}}},"responses":{"200":{"description":"Chart image (PNG/SVG) or JSON metadata, depending on format field or Accept header","content":{"application/json":{"schema":{"type":"object"},"example":{"success":true,"title":"LTH Supply vs STH Supply","metrics":[{"id":"lth_supply","label":"LTH Supply"},{"id":"sth_supply","label":"STH Supply"}],"days":730,"theme":"dark","width":1200,"height":600,"formulas":[{"id":"sma_200","expression":"sma(m1, 200)","label":"200d SMA"}],"data_points":730,"cached":false,"render_time_ms":0}},"image/png":{"schema":{"type":"string","format":"binary"},"example":"(binary PNG image data)"},"image/svg+xml":{"schema":{"type":"string"},"example":""}}},"400":{"description":"Invalid parameters (e.g., unknown metric, conflicting inputs)","content":{"application/json":{"examples":{"missing_source":{"summary":"No metric source specified","value":{"success":false,"error":"invalid_params","message":"Exactly one of 'metric', 'metrics', or 'template' must be provided"}},"unknown_metric":{"summary":"Unknown metric ID","value":{"success":false,"error":"invalid_params","message":"Unknown metric 'foo_bar'"}}}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"example":{"success":false,"error":"unauthorized","message":"API key required"}}}},"403":{"description":"Requires Pro+ tier, or insufficient grade for requested metrics","content":{"application/json":{"example":{"success":false,"error":"insufficient_tier","message":"Snapshot API requires Pro or Enterprise tier","current_tier":"free","upgrade_url":"https://blocklens.co/pricing"}}}},"429":{"description":"Snapshot rate limit exceeded (per-tier hourly limit)","content":{"application/json":{"example":{"success":false,"error":"rate_limited","message":"Snapshot rate limit exceeded. Max 60 per hour for pro tier.","retry_after":120}}}},"504":{"description":"Chart rendering timed out — try a shorter date range","content":{"application/json":{"example":{"success":false,"error":"render_timeout","message":"Chart rendering timed out after 20.0s. Try a shorter date range."}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/":{"get":{"tags":["Public"],"summary":"API Root & Status","description":"Provides basic information about the API, its version, and a list of available endpoint categories. This is a good starting point for exploring the API's capabilities.","operationId":"root__get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse"}}}}}}},"/health":{"get":{"tags":["Public"],"summary":"Health Check","description":"Performs a health check of the API and its critical dependencies, such as the database and Redis cache. Returns a 200 status code with component statuses, which can be used for automated monitoring.","operationId":"health_check_health_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/v1/prices":{"get":{"tags":["Market Data"],"summary":"Historical Market Data","description":"Retrieves historical price and volume data for a given cryptocurrency symbol. This includes daily **open, high, low, close (OHLC)** prices, as well as trading volume and market capitalization.\n\nThis endpoint is fundamental for any quantitative analysis, backtesting trading strategies, or charting applications.","operationId":"get_prices_v1_prices_get","parameters":[{"name":"symbol","in":"query","required":false,"schema":{"type":"string","description":"Cryptocurrency symbol","default":"BTC","title":"Symbol"},"description":"Cryptocurrency symbol"},{"name":"start_date","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"description":"Start date (YYYY-MM-DD)","title":"Start Date"},"description":"Start date (YYYY-MM-DD)"},{"name":"end_date","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"description":"End date (YYYY-MM-DD)","title":"End Date"},"description":"End date (YYYY-MM-DD)"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":10000,"minimum":1,"description":"Number of records to return","default":100,"title":"Limit"},"description":"Number of records to return"},{"name":"fields","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Comma-separated field names to include (date columns always kept)","title":"Fields"},"description":"Comma-separated field names to include (date columns always kept)"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/cycle-performance":{"get":{"tags":["Market Data"],"summary":"Cycle Performance Comparison","description":"Compares Bitcoin price performance across historical market cycles. Aligns cycles by a common\nevent (cycle low, all-time high, or halving) and shows percentage change from the starting price.\n\nReturns data indexed by `day_offset` from the cycle event, with one field per cycle.\nHistorical cycles that lasted longer than the current one extend beyond today's date.","operationId":"get_cycle_performance_v1_cycle_performance_get","parameters":[{"name":"type","in":"query","required":true,"schema":{"type":"string","pattern":"^(low|ath|halving)$","description":"Cycle type: low, ath, or halving","title":"Type"},"description":"Cycle type: low, ath, or halving"},{"name":"symbol","in":"query","required":false,"schema":{"type":"string","description":"Cryptocurrency symbol","default":"BTC","title":"Symbol"},"description":"Cryptocurrency symbol"},{"name":"days","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Number of days to show from cycle start (0 = full range)","default":365,"title":"Days"},"description":"Number of days to show from cycle start (0 = full range)"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/cycle-boundaries":{"get":{"tags":["Market Data"],"summary":"Cycle Boundaries","description":"Returns summary data for each Bitcoin market cycle: start date/price, peak date/price,\nbottom date/price, max drawdown, days to bottom, days to recovery, and total cycle duration.\n\nCycles are defined by three reference points: ATH (all-time high), halving, and cycle low.\nFor the current (incomplete) cycle, `is_current=true` and current drawdown from peak is provided.","operationId":"get_cycle_boundaries_v1_cycle_boundaries_get","parameters":[{"name":"type","in":"query","required":false,"schema":{"anyOf":[{"type":"string","pattern":"^(low|ath|halving)$"},{"type":"null"}],"description":"Cycle type filter: low, ath, or halving. Returns all if omitted.","title":"Type"},"description":"Cycle type filter: low, ath, or halving. Returns all if omitted."},{"name":"symbol","in":"query","required":false,"schema":{"type":"string","description":"Cryptocurrency symbol","default":"BTC","title":"Symbol"},"description":"Cryptocurrency symbol"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/holder/supply":{"get":{"tags":["Holder Analytics"],"summary":"LTH & STH Supply","description":"Retrieves the historical supply held by **Long-Term Holders (LTH)** and **Short-Term Holders (STH)**. This metric segments the market into cohorts based on coin lifespan, providing powerful insights into market sentiment.\n\n- A rising **LTH supply** often indicates accumulation and holder conviction.\n- A rising **STH supply** can signal market tops as long-term holders distribute to new, speculative participants.","operationId":"get_holder_supply_v1_holder_supply_get","parameters":[{"name":"start_date","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"description":"Start date (YYYY-MM-DD)","title":"Start Date"},"description":"Start date (YYYY-MM-DD)"},{"name":"end_date","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"description":"End date (YYYY-MM-DD)","title":"End Date"},"description":"End date (YYYY-MM-DD)"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":10000,"minimum":1,"description":"Number of records to return","default":100,"title":"Limit"},"description":"Number of records to return"},{"name":"fields","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Comma-separated field names to include (date columns always kept)","title":"Fields"},"description":"Comma-separated field names to include (date columns always kept)"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/holder/valuation":{"get":{"tags":["Valuation Metrics"],"summary":"Holder Valuation Metrics","description":"Provides key valuation metrics segmented by LTH and STH, including **Realized Price** and **MVRV Ratio**.\n\n- **Realized Price**: The average price at which coins held by a cohort were last moved. It represents the collective cost basis.\n- **MVRV (Market Value to Realized Value)**: The ratio of Market Price to Realized Price. High values suggest the market is overheated, while low values suggest undervaluation.","operationId":"get_holder_valuation_v1_holder_valuation_get","parameters":[{"name":"start_date","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"description":"Start date (YYYY-MM-DD)","title":"Start Date"},"description":"Start date (YYYY-MM-DD)"},{"name":"end_date","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"description":"End date (YYYY-MM-DD)","title":"End Date"},"description":"End date (YYYY-MM-DD)"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":10000,"minimum":1,"description":"Number of records to return","default":100,"title":"Limit"},"description":"Number of records to return"},{"name":"fields","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Comma-separated field names to include (date columns always kept)","title":"Fields"},"description":"Comma-separated field names to include (date columns always kept)"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/holder/profit":{"get":{"tags":["Profitability Metrics"],"summary":"Holder Profitability Metrics","description":"Retrieves metrics related to the profitability of LTH and STH cohorts, primarily the **SOPR (Spent Output Profit Ratio)**.\n\n- **SOPR**: Measures the average profit or loss of coins spent on-chain.\n- A **SOPR > 1** indicates that coins are being sold at a profit, typical in bull markets.\n- A **SOPR < 1** indicates coins are being sold at a loss, often seen during capitulation events in bear markets.","operationId":"get_holder_profit_v1_holder_profit_get","parameters":[{"name":"start_date","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"description":"Start date (YYYY-MM-DD)","title":"Start Date"},"description":"Start date (YYYY-MM-DD)"},{"name":"end_date","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"description":"End date (YYYY-MM-DD)","title":"End Date"},"description":"End date (YYYY-MM-DD)"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":10000,"minimum":1,"description":"Number of records to return","default":100,"title":"Limit"},"description":"Number of records to return"},{"name":"fields","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Comma-separated field names to include (date columns always kept)","title":"Fields"},"description":"Comma-separated field names to include (date columns always kept)"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/coindays":{"get":{"tags":["Coin Days"],"summary":"Coin Days Metrics","description":"Provides daily **Coin Days** metrics that measure the economic weight of Bitcoin transactions by accounting for how long coins were held before being spent.\n\n- **Coin Days Destroyed (CDD)**: The total coin-days destroyed when UTXOs are spent. A UTXO holding 2 BTC for 100 days destroys 200 coin-days when spent. High CDD indicates long-dormant coins are moving.\n- **Net Coin Days**: CDC − CDD, where Coin Days Created (CDC) equals the circulating supply (each BTC creates exactly 1 coin-day per calendar day). Positive values indicate net accumulation; negative values indicate heavy spending of old coins.\n- **Coin Days Accumulated**: Cumulative sum of Net Coin Days from genesis. Represents the total \"stored time-value\" in the UTXO set.\n- **Liveliness**: cumCDD / (CDA + cumCDD). Measures the fraction of all possible coin-days that have been destroyed. Values near 1 indicate a high-velocity economy; values near 0 indicate strong HODLing.\n- **Vaultedness**: 1 − Liveliness = CDA / (CDA + cumCDD). Measures the fraction of coin-days stored (not yet destroyed). High values indicate coins are being held long-term.\n- **Transfer Volume**: Total BTC spent (changed hands) on-chain each day.\n- **Dormancy**: Average age (in days) of coins spent: CDD / Transfer Volume. Higher values mean older coins are moving.\n- **Dormancy Flow**: Dormancy normalized by its 365-day moving average. Values above 1 indicate unusually old coins are moving.","operationId":"get_coindays_v1_coindays_get","parameters":[{"name":"start_date","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"description":"Start date (YYYY-MM-DD)","title":"Start Date"},"description":"Start date (YYYY-MM-DD)"},{"name":"end_date","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"description":"End date (YYYY-MM-DD)","title":"End Date"},"description":"End date (YYYY-MM-DD)"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":10000,"minimum":1,"description":"Number of records to return","default":100,"title":"Limit"},"description":"Number of records to return"},{"name":"fields","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Comma-separated field names to include (date columns always kept)","title":"Fields"},"description":"Comma-separated field names to include (date columns always kept)"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/utxo/history":{"get":{"tags":["UTXO Analytics"],"summary":"UTXO Cohort History","description":"Provides a detailed breakdown of the UTXO (Unspent Transaction Output) set by age cohort. This allows for deep analysis of coin dormancy and accumulation patterns.\n\nThis endpoint is powerful for tracking the behavior of \"old hands\" and identifying when dormant supply begins to move, which can often precede significant price action.","operationId":"get_utxo_history_v1_utxo_history_get","parameters":[{"name":"date_processed","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"description":"Specific processing date","title":"Date Processed"},"description":"Specific processing date"},{"name":"cohort_start","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"description":"Start of cohort date range","title":"Cohort Start"},"description":"Start of cohort date range"},{"name":"cohort_end","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"description":"End of cohort date range","title":"Cohort End"},"description":"End of cohort date range"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":50000,"minimum":1,"description":"Number of records to return","default":1000,"title":"Limit"},"description":"Number of records to return"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/cohort/metrics/{cohort}":{"get":{"tags":["Holder Analytics"],"summary":"Age Cohort Metrics (path param)","description":"Same as /v1/cohort/metrics?cohort=X but with cohort as path parameter.","operationId":"get_cohort_metrics_path_v1_cohort_metrics__cohort__get","parameters":[{"name":"cohort","in":"path","required":true,"schema":{"type":"string","title":"Cohort"}},{"name":"start_date","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"Start Date"}},{"name":"end_date","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"End Date"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":10000,"minimum":1,"default":100,"title":"Limit"}},{"name":"fields","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Comma-separated field names to include (date columns always kept)","title":"Fields"},"description":"Comma-separated field names to include (date columns always kept)"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/cohort/metrics":{"get":{"tags":["Holder Analytics"],"summary":"Age Cohort Metrics","description":"Retrieves supply, realized cap, and realized price for a specific UTXO age cohort.\n\nAvailable cohorts: `24h`, `1d_1w`, `1w_1m`, `1m_3m`, `3m_6m`, `6m_12m`, `1y_2y`, `2y_3y`, `3y_5y`, `5y_7y`, `7y_10y`, `10y_plus`.\n\nResponse fields are dynamically named based on the cohort parameter. For example, `cohort=24h` returns `supply_24h`, `realized_cap_24h`, `realized_price_24h`.","operationId":"get_cohort_metrics_v1_cohort_metrics_get","parameters":[{"name":"cohort","in":"query","required":true,"schema":{"type":"string","description":"Age cohort (e.g. '24h', '1d_1w', '10y_plus')","title":"Cohort"},"description":"Age cohort (e.g. '24h', '1d_1w', '10y_plus')"},{"name":"start_date","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"description":"Start date (YYYY-MM-DD)","title":"Start Date"},"description":"Start date (YYYY-MM-DD)"},{"name":"end_date","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"description":"End date (YYYY-MM-DD)","title":"End Date"},"description":"End date (YYYY-MM-DD)"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":10000,"minimum":1,"description":"Number of records to return","default":100,"title":"Limit"},"description":"Number of records to return"},{"name":"fields","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Comma-separated field names to include (date columns always kept)","title":"Fields"},"description":"Comma-separated field names to include (date columns always kept)"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/blockchain/{metric_id}":{"get":{"tags":["Blockchain Metrics"],"summary":"Blockchain Metric Data","description":"Retrieves time-series data for blockchain-level metrics stored in the unified `metric_data` table.\n\nThe response uses the metric's own field name as the JSON key (e.g., `block_height`) for frontend compatibility.\n\nAvailable metrics: `block_height` (more coming soon).","operationId":"get_blockchain_metric_v1_blockchain__metric_id__get","parameters":[{"name":"metric_id","in":"path","required":true,"schema":{"type":"string","description":"Metric ID (e.g., 'block_height')","title":"Metric Id"},"description":"Metric ID (e.g., 'block_height')"},{"name":"start_date","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"description":"Start date (YYYY-MM-DD)","title":"Start Date"},"description":"Start date (YYYY-MM-DD)"},{"name":"end_date","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"description":"End date (YYYY-MM-DD)","title":"End Date"},"description":"End date (YYYY-MM-DD)"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":10000,"minimum":1,"description":"Number of records to return","default":100,"title":"Limit"},"description":"Number of records to return"},{"name":"fields","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Comma-separated field names to include (date columns always kept)","title":"Fields"},"description":"Comma-separated field names to include (date columns always kept)"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/metrics/latest":{"get":{"tags":["Aggregated Metrics"],"summary":"Latest Metrics Snapshot","description":"A convenience endpoint that retrieves the single most recent data point from all major metric categories: **prices, supply, valuation, and profitability.**\n\nThis is ideal for powering dashboards or applications that need a quick, up-to-date snapshot of the overall market health without making multiple API calls.","operationId":"get_latest_metrics_v1_metrics_latest_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse"}}}}}}},"/v1/metrics":{"get":{"tags":["Metrics Registry"],"summary":"List All Metric Definitions","description":"Retrieves the complete list of available metrics with their definitions, including:\n- **Metadata**: name, description, category, documentation links\n- **Data source**: API endpoint, database field, table\n- **Display settings**: default color, unit, format, supported chart types\n- **Access control**: grade level (0=basic, 1=pro, 2=enterprise)\n\nUse the `category` parameter to filter by metric category, or `grade` to filter by access level.\nThis endpoint is essential for building dynamic UIs that need to know what metrics are available.","operationId":"get_metrics_registry_v1_metrics_get","parameters":[{"name":"category","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Filter by category (price, supply, valuation, profit)","title":"Category"},"description":"Filter by category (price, supply, valuation, profit)"},{"name":"grade","in":"query","required":false,"schema":{"anyOf":[{"type":"integer","maximum":2,"minimum":0},{"type":"null"}],"description":"Filter by grade (0=basic, 1=pro, 2=enterprise)","title":"Grade"},"description":"Filter by grade (0=basic, 1=pro, 2=enterprise)"},{"name":"active_only","in":"query","required":false,"schema":{"type":"boolean","description":"Only return active metrics","default":true,"title":"Active Only"},"description":"Only return active metrics"},{"name":"include_docs","in":"query","required":false,"schema":{"type":"boolean","description":"Include the heavy docs_description field. Set false to shrink the payload — the list can exceed 200KB with docs, which stalls on the blocklens.ru path; clients that page per-category use false.","default":true,"title":"Include Docs"},"description":"Include the heavy docs_description field. Set false to shrink the payload — the list can exceed 200KB with docs, which stalls on the blocklens.ru path; clients that page per-category use false."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/metrics/categories":{"get":{"tags":["Metrics Registry"],"summary":"List Metric Categories","description":"Returns a summary of all metric categories with counts and the list of metric IDs in each category.\n\nCategories include:\n- **price**: Market price, volume, market cap\n- **supply**: LTH/STH supply distribution\n- **valuation**: Realized cap, realized price, MVRV\n- **profit**: Realized/unrealized P&L, SOPR","operationId":"get_metrics_categories_v1_metrics_categories_get","parameters":[{"name":"active_only","in":"query","required":false,"schema":{"type":"boolean","description":"Only count active metrics","default":true,"title":"Active Only"},"description":"Only count active metrics"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/metrics/{metric_id}":{"get":{"tags":["Metrics Registry"],"summary":"Get Single Metric Definition","description":"Retrieves the full definition for a specific metric by its ID.\n\nExamples of metric IDs:\n- `price` - Bitcoin market price\n- `lth_supply` - Long-term holder supply\n- `lth_mvrv` - LTH Market Value to Realized Value ratio\n- `sth_sopr` - STH Spent Output Profit Ratio","operationId":"get_metric_by_id_v1_metrics__metric_id__get","parameters":[{"name":"metric_id","in":"path","required":true,"schema":{"type":"string","description":"Metric identifier (e.g., 'lth_supply', 'price')","title":"Metric Id"},"description":"Metric identifier (e.g., 'lth_supply', 'price')"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/heatmap/{heatmap_id}":{"get":{"tags":["Heatmap"],"summary":"Get Heatmap Data","description":"Returns 2D heatmap matrix data. Currently supports: cost-basis-distribution.","operationId":"get_heatmap_v1_heatmap__heatmap_id__get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"heatmap_id","in":"path","required":true,"schema":{"type":"string","description":"Heatmap identifier (e.g., 'cost-basis-distribution')","title":"Heatmap Id"},"description":"Heatmap identifier (e.g., 'cost-basis-distribution')"},{"name":"start","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Start date (YYYY-MM-DD)","title":"Start"},"description":"Start date (YYYY-MM-DD)"},{"name":"end","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"End date (YYYY-MM-DD)","title":"End"},"description":"End date (YYYY-MM-DD)"},{"name":"period","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Period for optimized bins: all, 10y, 5y, 3y, 1y, 6m, 3m, 1m, 1w","title":"Period"},"description":"Period for optimized bins: all, 10y, 5y, 3y, 1y, 6m, 3m, 1m, 1w"},{"name":"resolution","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Resolution: 1d","default":"1d","title":"Resolution"},"description":"Resolution: 1d"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/etf/aggregate":{"get":{"tags":["ETF Analytics"],"summary":"ETF Aggregate Metrics","description":"Provides daily aggregate metrics for all Bitcoin ETFs tracked by Blocklens.\n\n- **total_btc_holdings**: Total BTC held across all ETFs\n- **total_aum**: Total Assets Under Management (USD)\n- **net_flow_btc**: Daily change in total BTC holdings\n- **cumulative_flow_btc**: Running sum of net flows from inception\n- **cumulative_money_flow**: Cumulative net USD flow of all ETFs — exact creations minus redemptions at NAV for US spot ETFs since 2024-01-11, ΔBTC × BTC price estimate for non-US ETPs and earlier years\n- **etf_realized_price**: Average BTC acquisition price across ETFs (weighted-average cost of per-fund realized caps / total_btc_holdings)\n- **btc_dominance**: ETF BTC holdings as % of circulating supply\n- **etf_count**: Number of ETFs reporting data that day\n- **us_btc_holdings / us_aum**: US-listed ETFs only\n- **us_spot_cumulative_money_flow**: Running sum of us_spot_net_flow_usd since 2024-01-11 (last value = sum of the daily values)\n- **us_spot_realized_price**: Average cost basis for US spot ETF cohort from Jan 10, 2024\n- **us_spot_net_flow_usd**: Daily USD net flow of US spot ETFs since 2024-01-11 — Σ per fund (shares outstanding after the day − before) × NAV, by trade date (newest day provisional until every fund's figure is published)","operationId":"get_etf_aggregate_v1_etf_aggregate_get","parameters":[{"name":"from_date","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"description":"Start date (YYYY-MM-DD)","title":"From Date"},"description":"Start date (YYYY-MM-DD)"},{"name":"to_date","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"description":"End date (YYYY-MM-DD)","title":"To Date"},"description":"End date (YYYY-MM-DD)"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":10000,"minimum":1,"description":"Number of records to return","default":100,"title":"Limit"},"description":"Number of records to return"},{"name":"fields","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Comma-separated field names to include (date columns always kept)","title":"Fields"},"description":"Comma-separated field names to include (date columns always kept)"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/etf/ticker":{"get":{"tags":["ETF Analytics"],"summary":"Per-Ticker ETF Data","description":"Returns daily snapshot data for a single ETF ticker.\n\n**Parameters:**\n- **ticker** (required): ETF ticker symbol (e.g. IBIT, FBTC, GBTC)\n- **from_date**: Start date filter (YYYY-MM-DD)\n- **to_date**: End date filter (YYYY-MM-DD)\n- **limit**: Number of records (default 100, max 10000)\n\n**Fields returned:**\n- **btc_holdings**: BTC held by the fund\n- **aum**: Assets under management (USD)\n- **nav_per_share**: Net asset value per share\n- **shares_out**: Shares outstanding\n- **net_flow_btc**: Daily change in BTC holdings\n- **cumulative_flow_btc**: Running sum of net flows\n- **market_share_pct**: Fund's share of total ETF BTC holdings (%)\n- **realized_cap**: Realized capitalization (USD)\n- **realized_price**: Average BTC acquisition price\n- **flow_usd**: Daily USD net flow — change in shares outstanding × NAV per share, by trade date (US spot funds, since 2024-01-11; newest day provisional until published)","operationId":"get_etf_ticker_v1_etf_ticker_get","parameters":[{"name":"ticker","in":"query","required":true,"schema":{"type":"string","description":"ETF ticker symbol (e.g. IBIT, FBTC, GBTC)","title":"Ticker"},"description":"ETF ticker symbol (e.g. IBIT, FBTC, GBTC)"},{"name":"from_date","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"description":"Start date (YYYY-MM-DD)","title":"From Date"},"description":"Start date (YYYY-MM-DD)"},{"name":"to_date","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"description":"End date (YYYY-MM-DD)","title":"To Date"},"description":"End date (YYYY-MM-DD)"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":10000,"minimum":1,"description":"Number of records to return","default":100,"title":"Limit"},"description":"Number of records to return"},{"name":"fields","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Comma-separated field names to include (date columns always kept)","title":"Fields"},"description":"Comma-separated field names to include (date columns always kept)"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/etf/registry":{"get":{"tags":["ETF Analytics"],"summary":"ETF Registry","description":"Returns metadata for all Bitcoin ETFs tracked by Blocklens, including ticker, issuer, country, exchange, and active status.","operationId":"get_etf_registry_v1_etf_registry_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse"}}}}}}},"/v1/dat/aggregate":{"get":{"tags":["DAT Analytics"],"summary":"DAT BTC Aggregate Metrics","description":"Provides daily aggregate metrics for all institutional/sovereign Bitcoin holdings\ntracked by Blocklens.\n\n- **total_btc**: Total BTC held by all tracked entities\n- **total_companies**: Number of entities holding BTC that day\n- **total_usd_value**: Total USD value of all holdings\n- **net_change_btc**: Daily change in total BTC holdings\n- **cumulative_btc**: Running total BTC held\n- **public_company_btc / public_company_count**: Public company breakdown\n- **private_company_btc / private_company_count**: Private company breakdown\n- **government_btc / government_count**: Government entity breakdown\n- **top_holder_btc / top_holder_name**: Largest holder that day\n- **pct_of_supply**: Total holdings as % of circulating supply\n- **btc_price**: BTC price for context","operationId":"get_dat_aggregate_v1_dat_aggregate_get","parameters":[{"name":"from_date","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"description":"Start date (YYYY-MM-DD)","title":"From Date"},"description":"Start date (YYYY-MM-DD)"},{"name":"to_date","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"description":"End date (YYYY-MM-DD)","title":"To Date"},"description":"End date (YYYY-MM-DD)"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":10000,"minimum":1,"description":"Number of records to return","default":100,"title":"Limit"},"description":"Number of records to return"},{"name":"fields","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Comma-separated field names to include (date columns always kept)","title":"Fields"},"description":"Comma-separated field names to include (date columns always kept)"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/dat/registry":{"get":{"tags":["DAT Analytics"],"summary":"DAT Entity Registry","description":"Returns a list of companies/entities holding Bitcoin with their latest holdings.\n\n**Parameters:**\n- **entity_type**: Filter by entity type (e.g. 'public_company', 'private_company', 'government')\n- **country**: Filter by country code (e.g. 'US', 'DE')\n- **limit**: Number of records (default 100, max 1000)\n- **offset**: Pagination offset\n- **sort_by**: Sort field (amount desc by default)","operationId":"get_dat_companies_v1_dat_registry_get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"entity_type","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Filter by entity type","title":"Entity Type"},"description":"Filter by entity type"},{"name":"country","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Filter by country code","title":"Country"},"description":"Filter by country code"},{"name":"search","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Search by name, ticker, or country (case-insensitive)","title":"Search"},"description":"Search by name, ticker, or country (case-insensitive)"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":1000,"minimum":1,"description":"Number of records to return","default":100,"title":"Limit"},"description":"Number of records to return"},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Pagination offset","default":0,"title":"Offset"},"description":"Pagination offset"},{"name":"sort_by","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Sort field (amount, name)","default":"amount","title":"Sort By"},"description":"Sort field (amount, name)"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/dat/company/{company_id}/holdings":{"get":{"tags":["DAT Analytics"],"summary":"Company Holdings History","description":"Returns historical BTC holdings for a specific company.\n\n**Parameters:**\n- **company_id** (path): Company ID\n- **from_date**: Start date filter (YYYY-MM-DD)\n- **to_date**: End date filter (YYYY-MM-DD)\n- **limit**: Number of records (default 1000, max 10000)","operationId":"get_dat_company_holdings_v1_dat_company__company_id__holdings_get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"company_id","in":"path","required":true,"schema":{"type":"integer","description":"Company ID","title":"Company Id"},"description":"Company ID"},{"name":"from_date","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"description":"Start date (YYYY-MM-DD)","title":"From Date"},"description":"Start date (YYYY-MM-DD)"},{"name":"to_date","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"description":"End date (YYYY-MM-DD)","title":"To Date"},"description":"End date (YYYY-MM-DD)"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":10000,"minimum":1,"description":"Number of records to return","default":1000,"title":"Limit"},"description":"Number of records to return"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/dat/entity":{"get":{"tags":["DAT Analytics"],"summary":"Per-Entity DAT Data","description":"Returns daily BTC holdings data for a single entity (bitcoin only).\n\n**Parameters:**\n- **id**: Entity/company ID (integer)\n- **entity**: Entity name or ticker (e.g., 'strategy', 'MSTR', 'tesla') — alternative to id\n- **from_date**: Start date filter (YYYY-MM-DD)\n- **to_date**: End date filter (YYYY-MM-DD)\n- **limit**: Number of records (default 100, max 10000)\n\n**Fields returned:**\n- **amount**: BTC held by the entity\n- **total_current_value_usd**: Current USD value of holdings\n- **percentage_of_total_supply**: Percentage of total BTC supply held\n- **net_flow_btc**: Daily change in BTC holdings\n- **cumulative_flow_btc**: Running sum of daily BTC flow changes\n- **market_share_pct**: Entity share of total DAT BTC holdings\n- **aum**: Assets under management (BTC × price)\n- **realized_price**: Average cost basis (purchase price) per BTC","operationId":"get_dat_entity_v1_dat_entity_get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"id","in":"query","required":false,"schema":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"Entity/company ID","title":"Id"},"description":"Entity/company ID"},{"name":"entity","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Entity name or ticker (e.g., 'strategy', 'MSTR', 'tesla')","title":"Entity"},"description":"Entity name or ticker (e.g., 'strategy', 'MSTR', 'tesla')"},{"name":"from_date","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"description":"Start date (YYYY-MM-DD)","title":"From Date"},"description":"Start date (YYYY-MM-DD)"},{"name":"to_date","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"description":"End date (YYYY-MM-DD)","title":"To Date"},"description":"End date (YYYY-MM-DD)"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":10000,"minimum":1,"description":"Number of records to return","default":100,"title":"Limit"},"description":"Number of records to return"},{"name":"fields","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Comma-separated field names to include (date columns always kept)","title":"Fields"},"description":"Comma-separated field names to include (date columns always kept)"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/dat/realized-price":{"get":{"tags":["DAT Analytics"],"summary":"DAT Realized Price by Entity Type","description":"Returns daily realized price (weighted average cost basis per BTC)\nby entity type from precomputed daily_dat_realized_price table.","operationId":"get_dat_realized_price_v1_dat_realized_price_get","parameters":[{"name":"from_date","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"From Date"}},{"name":"to_date","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"To Date"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":10000,"minimum":1,"default":100,"title":"Limit"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/dat/stats":{"get":{"tags":["DAT Analytics"],"summary":"DAT BTC Summary Stats","description":"Returns summary statistics for DAT BTC holdings: totals, breakdowns by entity type, and top countries.","operationId":"get_dat_stats_v1_dat_stats_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse"}}}}}}},"/v1/enterprise/sopr":{"post":{"tags":["Enterprise"],"summary":"SOPR Cohort Distribution","description":"Returns SOPR distribution across custom age cohorts. Enterprise only (grade >= 2).","operationId":"post_enterprise_sopr_v1_enterprise_sopr_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SoprRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"HTTPBearer":[]}]}},"/v1/enterprise/dashboards":{"get":{"tags":["Enterprise"],"summary":"List Enterprise Dashboards","description":"Returns available enterprise dashboards. Enterprise only (grade >= 2).","operationId":"get_enterprise_dashboards_v1_enterprise_dashboards_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}},"security":[{"HTTPBearer":[]}]}},"/v1/funding/aggregate":{"get":{"tags":["Funding Rate Analytics"],"summary":"Funding Rate Aggregate Metrics","description":"Returns daily aggregate funding rates across all exchanges for a given symbol.\n\n- **avg_funding_rate**: Average funding rate across exchanges\n- **median_funding_rate**: Median funding rate\n- **min_funding_rate / max_funding_rate**: Range of rates\n- **exchange_count**: Number of exchanges reporting\n- **annualized_rate**: Annualized funding rate\n\nFree tier (grade 0) for BTC with up to 60 days of history.\nPro tier (grade 1) for all symbols with unlimited history.","operationId":"get_funding_aggregate_v1_funding_aggregate_get","parameters":[{"name":"symbol","in":"query","required":false,"schema":{"type":"string","description":"Asset symbol (e.g. BTC, ETH)","default":"BTC","title":"Symbol"},"description":"Asset symbol (e.g. BTC, ETH)"},{"name":"network","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Alias for symbol (used by frontend proxy)","title":"Network"},"description":"Alias for symbol (used by frontend proxy)"},{"name":"from_date","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"description":"Start date (YYYY-MM-DD)","title":"From Date"},"description":"Start date (YYYY-MM-DD)"},{"name":"to_date","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"description":"End date (YYYY-MM-DD)","title":"To Date"},"description":"End date (YYYY-MM-DD)"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":10000,"minimum":1,"description":"Number of records to return","default":100,"title":"Limit"},"description":"Number of records to return"},{"name":"fields","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Comma-separated field names to include (date columns always kept)","title":"Fields"},"description":"Comma-separated field names to include (date columns always kept)"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/funding/exchange":{"get":{"tags":["Funding Rate Analytics"],"summary":"Per-Exchange Funding Rates","description":"Returns daily per-exchange funding rates and OI from daily_funding_exchange.\n\n- **annualized_apr**: Daily average annualized funding rate for the exchange\n- **close_oi_usd**: Close-of-day open interest in USD for the exchange\n\nRequires Pro tier (grade 1).","operationId":"get_funding_exchange_v1_funding_exchange_get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"exchange","in":"query","required":true,"schema":{"type":"string","description":"Exchange ID (e.g. binance, bybit)","title":"Exchange"},"description":"Exchange ID (e.g. binance, bybit)"},{"name":"symbol","in":"query","required":false,"schema":{"type":"string","description":"Asset symbol (e.g. BTC, ETH)","default":"BTC","title":"Symbol"},"description":"Asset symbol (e.g. BTC, ETH)"},{"name":"network","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Alias for symbol (used by frontend proxy)","title":"Network"},"description":"Alias for symbol (used by frontend proxy)"},{"name":"from_date","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"description":"Start date (YYYY-MM-DD)","title":"From Date"},"description":"Start date (YYYY-MM-DD)"},{"name":"to_date","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"description":"End date (YYYY-MM-DD)","title":"To Date"},"description":"End date (YYYY-MM-DD)"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":10000,"minimum":1,"description":"Number of records to return","default":100,"title":"Limit"},"description":"Number of records to return"},{"name":"fields","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Comma-separated field names to include (date columns always kept)","title":"Fields"},"description":"Comma-separated field names to include (date columns always kept)"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/funding/exchanges":{"get":{"tags":["Funding Rate Analytics"],"summary":"List Available Exchanges","description":"Returns list of exchanges with funding rate data","operationId":"get_funding_exchanges_v1_funding_exchanges_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse"}}}}}}},"/v1/oi/exchange":{"get":{"tags":["Futures Analytics"],"summary":"Per-Exchange Open Interest","description":"Returns daily per-exchange open interest from daily_oi_exchange.\n\n- **close_oi_usd**: Close-of-day open interest in USD for the exchange\n\nRequires Pro tier (grade 1).","operationId":"get_oi_exchange_v1_oi_exchange_get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"exchange","in":"query","required":true,"schema":{"type":"string","description":"Exchange ID (e.g. binance, bybit)","title":"Exchange"},"description":"Exchange ID (e.g. binance, bybit)"},{"name":"symbol","in":"query","required":false,"schema":{"type":"string","description":"Asset symbol","default":"BTC","title":"Symbol"},"description":"Asset symbol"},{"name":"network","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Alias for symbol","title":"Network"},"description":"Alias for symbol"},{"name":"from_date","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"From Date"}},{"name":"to_date","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"To Date"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":10000,"minimum":1,"default":100,"title":"Limit"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/oi/exchanges":{"get":{"tags":["Futures Analytics"],"summary":"List Exchanges with OI Data","description":"Returns list of exchanges with open interest data","operationId":"get_oi_exchanges_v1_oi_exchanges_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse"}}}}}}},"/v1/futures/oi":{"get":{"tags":["Futures Analytics"],"summary":"Futures Open Interest Aggregate","description":"Returns daily aggregate futures open interest across all exchanges for a given symbol.\n\n- **total_oi_usd**: Total open interest in USD\n- **oi_delta_usd**: Day-over-day change in OI (USD)\n- **oi_delta_pct**: Day-over-day change in OI (percent)\n- **exchange_count**: Number of exchanges reporting\n\nFree tier (grade 0) for BTC with up to 60 days of history.\nPro tier (grade 1) for all symbols with unlimited history.","operationId":"get_futures_oi_v1_futures_oi_get","parameters":[{"name":"symbol","in":"query","required":false,"schema":{"type":"string","description":"Asset symbol (e.g. BTC, ETH)","default":"BTC","title":"Symbol"},"description":"Asset symbol (e.g. BTC, ETH)"},{"name":"network","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Alias for symbol","title":"Network"},"description":"Alias for symbol"},{"name":"from_date","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"description":"Start date (YYYY-MM-DD)","title":"From Date"},"description":"Start date (YYYY-MM-DD)"},{"name":"to_date","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"description":"End date (YYYY-MM-DD)","title":"To Date"},"description":"End date (YYYY-MM-DD)"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":10000,"minimum":1,"description":"Number of records to return","default":100,"title":"Limit"},"description":"Number of records to return"},{"name":"fields","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Comma-separated field names to include (date columns always kept)","title":"Fields"},"description":"Comma-separated field names to include (date columns always kept)"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/macro/rates":{"get":{"tags":["Macro Economics"],"summary":"Interest Rates","description":"Federal funds target rate and US Treasury yields (2Y, 10Y, 30Y, plus CBOE ^TNX/^IRX). All rates in percent.","operationId":"_route_v1_macro_rates_get","parameters":[{"name":"from_date","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"description":"Start date (YYYY-MM-DD)","title":"From Date"},"description":"Start date (YYYY-MM-DD)"},{"name":"to_date","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"description":"End date (YYYY-MM-DD)","title":"To Date"},"description":"End date (YYYY-MM-DD)"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":10000,"minimum":1,"description":"Number of records to return","default":365,"title":"Limit"},"description":"Number of records to return"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/macro/spreads":{"get":{"tags":["Macro Economics"],"summary":"Yield Curve & Credit Spreads","description":"10Y-2Y spread, 10Y-3M spread (recession indicators) and BofA US High Yield Index OAS. All in percent.","operationId":"_route_v1_macro_spreads_get","parameters":[{"name":"from_date","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"description":"Start date (YYYY-MM-DD)","title":"From Date"},"description":"Start date (YYYY-MM-DD)"},{"name":"to_date","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"description":"End date (YYYY-MM-DD)","title":"To Date"},"description":"End date (YYYY-MM-DD)"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":10000,"minimum":1,"description":"Number of records to return","default":365,"title":"Limit"},"description":"Number of records to return"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/macro/monetary":{"get":{"tags":["Macro Economics"],"summary":"Central Bank Balance Sheets & Money Supply","description":"Fed balance sheet (WALCL), M2 (NSA & SA), reverse repo, TGA, and global central bank assets (ECB, BOJ, China M2).","operationId":"_route_v1_macro_monetary_get","parameters":[{"name":"from_date","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"description":"Start date (YYYY-MM-DD)","title":"From Date"},"description":"Start date (YYYY-MM-DD)"},{"name":"to_date","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"description":"End date (YYYY-MM-DD)","title":"To Date"},"description":"End date (YYYY-MM-DD)"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":10000,"minimum":1,"description":"Number of records to return","default":365,"title":"Limit"},"description":"Number of records to return"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/macro/inflation":{"get":{"tags":["Macro Economics"],"summary":"Inflation Indicators","description":"Headline CPI (CPIAUCSL) and core PCE (PCEPILFE). Index values, monthly.","operationId":"_route_v1_macro_inflation_get","parameters":[{"name":"from_date","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"description":"Start date (YYYY-MM-DD)","title":"From Date"},"description":"Start date (YYYY-MM-DD)"},{"name":"to_date","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"description":"End date (YYYY-MM-DD)","title":"To Date"},"description":"End date (YYYY-MM-DD)"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":10000,"minimum":1,"description":"Number of records to return","default":365,"title":"Limit"},"description":"Number of records to return"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/macro/employment":{"get":{"tags":["Macro Economics"],"summary":"Employment Indicators","description":"Unemployment rate, manufacturing employment and weekly initial jobless claims.","operationId":"_route_v1_macro_employment_get","parameters":[{"name":"from_date","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"description":"Start date (YYYY-MM-DD)","title":"From Date"},"description":"Start date (YYYY-MM-DD)"},{"name":"to_date","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"description":"End date (YYYY-MM-DD)","title":"To Date"},"description":"End date (YYYY-MM-DD)"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":10000,"minimum":1,"description":"Number of records to return","default":365,"title":"Limit"},"description":"Number of records to return"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/macro/sentiment":{"get":{"tags":["Macro Economics"],"summary":"Sentiment & Growth","description":"U Michigan Consumer Sentiment Index and Real GDP QoQ annualized growth rate.","operationId":"_route_v1_macro_sentiment_get","parameters":[{"name":"from_date","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"description":"Start date (YYYY-MM-DD)","title":"From Date"},"description":"Start date (YYYY-MM-DD)"},{"name":"to_date","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"description":"End date (YYYY-MM-DD)","title":"To Date"},"description":"End date (YYYY-MM-DD)"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":10000,"minimum":1,"description":"Number of records to return","default":365,"title":"Limit"},"description":"Number of records to return"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/macro/markets":{"get":{"tags":["Macro Economics"],"summary":"Markets, Commodities & FX","description":"Equity ETFs (SPY/QQQ/IWM), VIX, gold/silver, oil futures, DXY, major FX pairs, and TLT.","operationId":"_route_v1_macro_markets_get","parameters":[{"name":"from_date","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"description":"Start date (YYYY-MM-DD)","title":"From Date"},"description":"Start date (YYYY-MM-DD)"},{"name":"to_date","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"description":"End date (YYYY-MM-DD)","title":"To Date"},"description":"End date (YYYY-MM-DD)"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":10000,"minimum":1,"description":"Number of records to return","default":365,"title":"Limit"},"description":"Number of records to return"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/macro/liquidity":{"get":{"tags":["Macro Economics"],"summary":"Net Liquidity & Real Yield","description":"Net Liquidity (Fed BS - RRP - TGA) and Real 10Y Yield (10Y Treasury - CPI YoY).","operationId":"_route_v1_macro_liquidity_get","parameters":[{"name":"from_date","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"description":"Start date (YYYY-MM-DD)","title":"From Date"},"description":"Start date (YYYY-MM-DD)"},{"name":"to_date","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"description":"End date (YYYY-MM-DD)","title":"To Date"},"description":"End date (YYYY-MM-DD)"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":10000,"minimum":1,"description":"Number of records to return","default":365,"title":"Limit"},"description":"Number of records to return"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/macro":{"get":{"tags":["Macro Economics"],"summary":"All Macro Metrics","description":"Returns every macro metric merged by date across all theme endpoints.","operationId":"get_macro_all_v1_macro_get","parameters":[{"name":"from_date","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"description":"Start date (YYYY-MM-DD)","title":"From Date"},"description":"Start date (YYYY-MM-DD)"},{"name":"to_date","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"description":"End date (YYYY-MM-DD)","title":"To Date"},"description":"End date (YYYY-MM-DD)"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":10000,"minimum":1,"description":"Number of records to return","default":365,"title":"Limit"},"description":"Number of records to return"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}},"components":{"schemas":{"ApiResponse":{"properties":{"success":{"type":"boolean","title":"Success"},"data":{"title":"Data"},"message":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Message"},"count":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Count"},"timestamp":{"type":"string","format":"date-time","title":"Timestamp"}},"type":"object","required":["success","data"],"title":"ApiResponse","description":"Standard API response model"},"FormulaConfig":{"properties":{"id":{"anyOf":[{"type":"string","maxLength":60},{"type":"null"}],"title":"Id","description":"Unique formula ID. Auto-generated if omitted."},"expression":{"type":"string","maxLength":200,"title":"Expression","description":"Formula expression, e.g. 'sma(m1, 200)'"},"label":{"type":"string","maxLength":60,"title":"Label","description":"Display label"},"color":{"anyOf":[{"type":"string","pattern":"^#[0-9a-fA-F]{6}$"},{"type":"null"}],"title":"Color","description":"Hex color"},"style":{"type":"string","enum":["line","area","bar"],"title":"Style","description":"Chart style: line, area, bar","default":"line"},"axis":{"type":"string","enum":["left","right"],"title":"Axis","description":"Y-axis side: left or right","default":"left"},"y_axis_id":{"anyOf":[{"type":"string","maxLength":30},{"type":"null"}],"title":"Y Axis Id","description":"Exact Y-axis ID (e.g. 'axis-diff'). Overrides 'axis' when set."},"stroke_width":{"anyOf":[{"type":"integer","maximum":5.0,"minimum":0.0},{"type":"null"}],"title":"Stroke Width"},"fill_opacity":{"anyOf":[{"type":"number","maximum":1.0,"minimum":0.0},{"type":"null"}],"title":"Fill Opacity"},"stroke_dash":{"anyOf":[{"type":"string","pattern":"^[\\d\\s]*$"},{"type":"null"}],"title":"Stroke Dash","description":"Dash pattern"},"stack_group":{"anyOf":[{"type":"string","maxLength":20},{"type":"null"}],"title":"Stack Group"},"visible":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Visible"},"show_in_legend":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Show In Legend","description":"Show in chart legend. Default true."}},"type":"object","required":["expression","label"],"title":"FormulaConfig","description":"Formula computed from metrics (evaluated client-side by formulaEngine).\n\nField names accept both snake_case (canonical) and camelCase forms — e.g.\n`y_axis_id` or `yAxisId`. The `style` field also accepts `chartStyle`."},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ReferenceAreaPostConfig":{"properties":{"y1":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Y1","description":"Static lower Y bound"},"y2":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Y2","description":"Static upper Y bound"},"y1Formula":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"title":"Y1Formula","description":"Formula for lower bound"},"y2Formula":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"title":"Y2Formula","description":"Formula for upper bound"},"yAxisId":{"anyOf":[{"type":"string","maxLength":30},{"type":"null"}],"title":"Yaxisid"},"fill":{"anyOf":[{"type":"string","pattern":"^#[0-9a-fA-F]{6}$"},{"type":"null"}],"title":"Fill","description":"Fill color (default: #3b82f6)"},"fillOpacity":{"anyOf":[{"type":"number","maximum":1.0,"minimum":0.0},{"type":"null"}],"title":"Fillopacity","description":"Fill opacity (default: 0.1)"},"label":{"anyOf":[{"type":"string","maxLength":60},{"type":"null"}],"title":"Label"}},"type":"object","title":"ReferenceAreaPostConfig","description":"Shaded reference zone between two Y values. Accepts snake_case or camelCase keys."},"ReferenceLinePostConfig":{"properties":{"y":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Y","description":"Static Y value"},"yFormula":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"title":"Yformula","description":"Formula expression for dynamic Y (e.g. 'sma(m1, 200)'). Uses same engine as formulas."},"yAxisId":{"anyOf":[{"type":"string","maxLength":30},{"type":"null"}],"title":"Yaxisid","description":"Y-axis ID (defaults to first left axis)"},"stroke":{"anyOf":[{"type":"string","pattern":"^#[0-9a-fA-F]{6}$"},{"type":"null"}],"title":"Stroke","description":"Line color (default: #9ca3af)"},"strokeDasharray":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Strokedasharray","description":"Dash pattern, e.g. '3 3' for dashed"},"label":{"anyOf":[{"type":"string","maxLength":60},{"type":"null"}],"title":"Label","description":"Label text"}},"type":"object","title":"ReferenceLinePostConfig","description":"Horizontal reference line on chart. Accepts snake_case or camelCase keys."},"SnapshotPostRequest":{"properties":{"metric":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Metric","description":"Single metric ID"},"metrics":{"anyOf":[{"items":{"anyOf":[{"type":"string"},{"additionalProperties":true,"type":"object"}]},"type":"array","maxItems":6},{"type":"null"}],"title":"Metrics","description":"Metric IDs or config objects (max 6)"},"template":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Template","description":"Template ID"},"days":{"anyOf":[{"type":"integer","maximum":10000.0,"minimum":7.0},{"type":"null"}],"title":"Days"},"startDate":{"anyOf":[{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},{"type":"null"}],"title":"Startdate"},"endDate":{"anyOf":[{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},{"type":"null"}],"title":"Enddate"},"warmupDays":{"type":"integer","maximum":730.0,"minimum":0.0,"title":"Warmupdays","description":"Extra days before start_date for formula rolling window warmup (0-730). Data is fetched from (start - warmup_days) but only displayed from start_date.","default":0},"title":{"anyOf":[{"type":"string","maxLength":120},{"type":"null"}],"title":"Title"},"width":{"type":"integer","maximum":2400.0,"minimum":600.0,"title":"Width","default":1200},"height":{"type":"integer","maximum":1200.0,"minimum":300.0,"title":"Height","default":600},"theme":{"type":"string","enum":["light","dark"],"title":"Theme","default":"light"},"format":{"type":"string","enum":["png","svg","json"],"title":"Format","default":"png"},"yAxes":{"anyOf":[{"items":{"$ref":"#/components/schemas/YAxisPostConfig"},"type":"array","maxItems":4},{"type":"null"}],"title":"Yaxes"},"overlay":{"anyOf":[{"type":"string","const":"price"},{"type":"null"}],"title":"Overlay"},"formulas":{"anyOf":[{"items":{"$ref":"#/components/schemas/FormulaConfig"},"type":"array","maxItems":4},{"type":"null"}],"title":"Formulas"},"referenceLines":{"anyOf":[{"items":{"$ref":"#/components/schemas/ReferenceLinePostConfig"},"type":"array","maxItems":10},{"type":"null"}],"title":"Referencelines","description":"Horizontal reference lines"},"referenceAreas":{"anyOf":[{"items":{"$ref":"#/components/schemas/ReferenceAreaPostConfig"},"type":"array","maxItems":10},{"type":"null"}],"title":"Referenceareas","description":"Shaded reference zones"},"layerOrder":{"anyOf":[{"items":{"type":"string"},"type":"array","maxItems":10},{"type":"null"}],"title":"Layerorder","description":"Render order (back to front)"},"params":{"anyOf":[{"additionalProperties":{"type":"string"},"type":"object"},{"type":"null"}],"title":"Params","description":"Runtime parameters for entity-filtered metrics (e.g., {\"ticker\": \"IBIT\"})"},"xAxis":{"anyOf":[{"type":"string","enum":["date","day_offset"]},{"type":"null"}],"title":"Xaxis","description":"X axis field. Default 'date'. Use 'day_offset' for indexed series (cycle performance)."},"heatmapId":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Heatmapid","description":"Heatmap ID (e.g., 'cost-basis-distribution'). When set, renders a heatmap PNG instead of a line chart. Mutually exclusive with metric/metrics/template."},"heatmapPeriod":{"anyOf":[{"type":"string","enum":["all","10y","5y","3y","1y","6m","3m","1m","1w"]},{"type":"null"}],"title":"Heatmapperiod","description":"Period for heatmap bin optimization (default: 'all')"},"heatmapColorScale":{"anyOf":[{"type":"string","enum":["soft","viridis","plasma"]},{"type":"null"}],"title":"Heatmapcolorscale","description":"Heatmap color scale (default: 'soft')"},"heatmapYScale":{"anyOf":[{"type":"string","enum":["linear","log"]},{"type":"null"}],"title":"Heatmapyscale","description":"Heatmap Y-axis scale (default: 'log')"},"style":{"anyOf":[{"type":"string","enum":["line","area","bar"]},{"type":"null"}],"title":"Style"},"scale":{"type":"string","enum":["linear","log"],"title":"Scale","default":"linear"}},"type":"object","title":"SnapshotPostRequest","description":"Full chart snapshot configuration (POST body).\n\nThe `metrics` field supports mixed types: strings (shorthand) and objects (full config).\nExample: [\"price\", {\"id\": \"lth_supply\", \"axis\": \"left\", \"style\": \"area\"}]\n\nField names accept both snake_case (canonical) and camelCase forms — e.g.\n`start_date` or `startDate`, `y_axes` or `yAxes`, `warmup_days` or `warmupDays`."},"SoprCohortDef":{"properties":{"name":{"type":"string","maxLength":50,"minLength":1,"title":"Name","description":"Cohort display name"},"min_days":{"type":"integer","minimum":0.0,"title":"Min Days","description":"Minimum UTXO age in days (inclusive lower bound)"},"max_days":{"anyOf":[{"type":"integer","minimum":1.0},{"type":"null"}],"title":"Max Days","description":"Maximum UTXO age in days (exclusive upper bound). Null = unbounded."}},"type":"object","required":["name","min_days"],"title":"SoprCohortDef","description":"A single age cohort definition for SOPR analysis."},"SoprRequest":{"properties":{"start_date":{"type":"string","format":"date","title":"Start Date","description":"Start date (YYYY-MM-DD)"},"end_date":{"type":"string","format":"date","title":"End Date","description":"End date (YYYY-MM-DD)"},"cohorts":{"items":{"$ref":"#/components/schemas/SoprCohortDef"},"type":"array","maxItems":20,"minItems":1,"title":"Cohorts","description":"Age cohort definitions"},"aggregation":{"type":"string","title":"Aggregation","description":"Time aggregation: daily, weekly, monthly, annual","default":"daily"},"analysis_mode":{"type":"string","title":"Analysis Mode","description":"Analysis mode: cohorts (custom age bands) or sth_lth (logistic weighting)","default":"cohorts"},"value_type":{"type":"string","title":"Value Type","description":"Volume type: btc or usd","default":"btc"}},"type":"object","required":["start_date","end_date","cohorts"],"title":"SoprRequest","description":"Request body for enterprise SOPR cohort distribution."},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"},"YAxisPostConfig":{"properties":{"id":{"anyOf":[{"type":"string","maxLength":30},{"type":"null"}],"title":"Id","description":"Axis ID. Auto-generated if omitted."},"side":{"type":"string","enum":["left","right"],"title":"Side","description":"left or right"},"scale":{"type":"string","enum":["linear","log"],"title":"Scale","description":"linear or log","default":"linear"},"format":{"anyOf":[{"type":"string","enum":["number","currency","percent","ratio"]},{"type":"null"}],"title":"Format","description":"Value format: number, currency, percent, ratio"},"label":{"anyOf":[{"type":"string","maxLength":40},{"type":"null"}],"title":"Label","description":"Axis label"},"domain":{"anyOf":[{"items":{"anyOf":[{"type":"number"},{"type":"integer"},{"type":"string","const":"auto"}]},"type":"array","maxItems":2,"minItems":2},{"type":"null"}],"title":"Domain","description":"[min, max] — use \"auto\" or number"},"range":{"anyOf":[{"items":{"anyOf":[{"type":"number"},{"type":"integer"}]},"type":"array","maxItems":2,"minItems":2},{"type":"null"}],"title":"Range","description":"[from%, to%] — vertical zone in % of chart height (0=bottom, 100=top)"},"domainMin":{"anyOf":[{"type":"number"},{"type":"integer"},{"type":"null"}],"title":"Domainmin","description":"Hard minimum domain value (clips from below)"},"domainMax":{"anyOf":[{"type":"number"},{"type":"integer"},{"type":"null"}],"title":"Domainmax","description":"Hard maximum domain value (clips from above)"},"noPadding":{"anyOf":[{"type":"string","enum":["top","bottom","both"]},{"type":"null"}],"title":"Nopadding","description":"Remove 10% padding from specified edges"}},"type":"object","required":["side"],"title":"YAxisPostConfig","description":"Custom Y-axis configuration for POST body. Accepts snake_case or camelCase keys."}},"securitySchemes":{"HTTPBearer":{"type":"http","scheme":"bearer"}}},"tags":[{"name":"Public","description":"Endpoints that do not require authentication."},{"name":"Market Data","description":"Endpoints for retrieving price, volume, and other market-related data."},{"name":"Holder Analytics","description":"Metrics focusing on the behavior of different holder cohorts (LTH/STH)."},{"name":"Valuation Metrics","description":"Endpoints for assessing the 'fair value' of a crypto asset."},{"name":"Profitability Metrics","description":"Metrics measuring the state of profit and loss in the system."},{"name":"UTXO Analytics","description":"Endpoints providing insights into the UTXO set."},{"name":"Aggregated Metrics","description":"Convenience endpoints that combine data from multiple categories."},{"name":"Blockchain Metrics","description":"Network fundamentals: block height, hash rate, difficulty, and other blockchain-level metrics."}]}