{ "openapi": "3.1.0", "info": { "title": "Quantascan API", "version": "1.0.0", "description": "REST API for QRL (legacy, Proof-of-Work) and QRL 2.0 (Proof-of-Stake): blocks, transactions, addresses, tokens, validators and QRL-native analytics, with full history since 2018. Free API key required: create one at https://quantascan.io/account/api-keys and send it as `Authorization: Bearer qs_…`. Free use, including commercial use, requires a visible \"Powered by Quantascan\" link: https://quantascan.io/api-pricing. Reference: https://quantascan.io/api-docs", "contact": { "name": "Quantascan", "url": "https://quantascan.io/enterprise" } }, "servers": [ { "url": "https://quantascan.io" } ], "tags": [ { "name": "Addresses" }, { "name": "Analytics" }, { "name": "Beacon" }, { "name": "Blocks" }, { "name": "Contracts" }, { "name": "Explorer compatible" }, { "name": "Fees" }, { "name": "JSON-RPC" }, { "name": "Market price" }, { "name": "Mempool" }, { "name": "Messages" }, { "name": "Mining" }, { "name": "NFT" }, { "name": "Names" }, { "name": "Richlist" }, { "name": "Token Transfers" }, { "name": "Tokens" }, { "name": "Transactions" }, { "name": "Transactions (QRL2)" }, { "name": "Trends" }, { "name": "Usage" }, { "name": "Validators" }, { "name": "Wallets" }, { "name": "Withdrawals" } ], "paths": { "/api/v1/qrl2/addresses/stats/summary": { "get": { "tags": [ "Addresses" ], "summary": "Get Address Stats", "operationId": "get_address_stats_api_v1_qrl2_addresses_stats_summary_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddressStats" } } } } }, "security": [ { "apiKey": [] } ] } }, "/api/v1/qrl2/addresses/top/burners": { "get": { "tags": [ "Addresses" ], "summary": "Get Top Burners", "description": "Top gas-burning addresses (qrl2 only).\n\nReturns addresses ordered by total fees paid in the look-back window.\nPowers a \"who's loading the chain\" widget and helps spot high-volume\nbots / contract-callers.\n\nWindow: pass `?window=7d` (default), `?window=30d`, etc.", "operationId": "get_top_burners_api_v1_qrl2_addresses_top_burners_get", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 500, "minimum": 1, "default": 50, "title": "Limit" } }, { "name": "window", "in": "query", "required": false, "schema": { "type": "string", "description": "Look-back window for gas burners ranking. Default 7d.", "default": "7d", "title": "Window" }, "description": "Look-back window for gas burners ranking. Default 7d." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ItemsList_GenericObject_" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "apiKey": [] } ] } }, "/api/v1/qrl2/addresses/top/active": { "get": { "tags": [ "Addresses" ], "summary": "Get Top Addresses", "description": "Top addresses on the chain — opinionated leaderboard.\n\nSort options (via `?sort=`): tx_count, balance, total_received,\ntotal_sent (default `-tx_count`). Use `?sort=-field` for descending,\n`?sort=field` for ascending. The underlying Gold view only indexes\nDESC variants today, so an ASC sort still serves the same data set\nordered DESC under the hood.\n\nPagination is offset-based (this is a stable Gold-projection\nleaderboard, not a live feed).", "operationId": "get_top_addresses_api_v1_qrl2_addresses_top_active_get", "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "default": 1, "title": "Page" } }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "default": 25, "title": "Page Size" } }, { "name": "q", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 129 }, { "type": "null" } ], "description": "Optional case-insensitive substring filter on address.", "title": "Q" }, "description": "Optional case-insensitive substring filter on address." }, { "name": "with_labels", "in": "query", "required": false, "schema": { "type": "boolean", "description": "When true, include `label` + `label_category` per row.", "default": false, "title": "With Labels" }, "description": "When true, include `label` + `label_category` per row." }, { "name": "with_delta_30d", "in": "query", "required": false, "schema": { "type": "boolean", "description": "When true, include `received_30d` + `sent_30d` UInt256 strings (30-day window).", "default": false, "title": "With Delta 30D" }, "description": "When true, include `received_30d` + `sent_30d` UInt256 strings (30-day window)." }, { "name": "positive_only", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Richlist mode: only addresses with a strictly positive balance (matches the supply 'holders' count). Off by default so tx_count / received sorts still see every address.", "default": false, "title": "Positive Only" }, "description": "Richlist mode: only addresses with a strictly positive balance (matches the supply 'holders' count). Off by default so tx_count / received sorts still see every address." }, { "name": "exclude_sentinel", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Drop sentinel wallets (coinbase / zero-address) so behaviour leaderboards (most-active / top-senders) aren't dominated by the non-organic block-reward sender.", "default": false, "title": "Exclude Sentinel" }, "description": "Drop sentinel wallets (coinbase / zero-address) so behaviour leaderboards (most-active / top-senders) aren't dominated by the non-organic block-reward sender." }, { "name": "exclude", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 2048 }, { "type": "null" } ], "description": "Comma-separated list of addresses to exclude by exact match (e.g. a known migration/genesis wallet).", "title": "Exclude" }, "description": "Comma-separated list of addresses to exclude by exact match (e.g. a known migration/genesis wallet)." }, { "name": "min_balance_pct", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "number", "minimum": 0 }, { "type": "null" } ], "description": "Legacy: keep only addresses whose balance is >= this percentage of total supply. Superseded by `whale_only` (the site-wide whale line is now a fixed 100,000-coin tier, not a % of supply). Still honoured for back-compat when `whale_only` is not set.", "title": "Min Balance Pct" }, "description": "Legacy: keep only addresses whose balance is >= this percentage of total supply. Superseded by `whale_only` (the site-wide whale line is now a fixed 100,000-coin tier, not a % of supply). Still honoured for back-compat when `whale_only` is not set." }, { "name": "whale_only", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Keep only 'whales' — the fixed >= 100,000-coin Whale tier (whale_metrics._FIXED_WHALE_THRESHOLDS, the single site-wide whale definition shared with /whales and the per-wallet Whale badge). Powers the 'large account' leaderboards (newest / dormant whales).", "default": false, "title": "Whale Only" }, "description": "Keep only 'whales' — the fixed >= 100,000-coin Whale tier (whale_metrics._FIXED_WHALE_THRESHOLDS, the single site-wide whale definition shared with /whales and the per-wallet Whale badge). Powers the 'large account' leaderboards (newest / dormant whales)." }, { "name": "sort", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Sort spec: '' (asc) or '-' (desc). Allowed: tx_count, balance, total_received, total_sent, total_fees_paid, first_seen, first_seen_asc, last_seen_asc. Default: -tx_count.", "default": "-tx_count", "title": "Sort" }, "description": "Sort spec: '' (asc) or '-' (desc). Allowed: tx_count, balance, total_received, total_sent, total_fees_paid, first_seen, first_seen_asc, last_seen_asc. Default: -tx_count." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddressTopActiveResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "apiKey": [] } ] } }, "/api/v1/qrl2/addresses/{address}/counterparties": { "get": { "tags": [ "Addresses" ], "summary": "Get Address Counterparties", "description": "Top counterparties for an address.\n\nReturns the top `limit` addresses that this address interacted with,\nsorted by transaction count. Each row carries `tx_count_with`,\n`total_sent_to_them`, `total_received_from_them`, and `last_interaction`.\n\nUX: powers a \"Top counterparties\" panel on the address-detail page.", "operationId": "get_address_counterparties_api_v1_qrl2_addresses__address__counterparties_get", "parameters": [ { "name": "address", "in": "path", "required": true, "schema": { "type": "string", "title": "Address" } }, { "name": "direction", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^(sent|received|both)$", "description": "sent=outgoing only, received=incoming only, both=either", "default": "both", "title": "Direction" }, "description": "sent=outgoing only, received=incoming only, both=either" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 200, "minimum": 1, "default": 20, "title": "Limit" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenericListResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "apiKey": [] } ] } }, "/api/v1/qrl2/addresses/{address}/slaves": { "get": { "tags": [ "Addresses" ], "summary": "Get Address Slaves", "description": "Slave XMSS-keys registered under this master address (QRL-only).\n\nReturns the addresses that named this address as their master (the inverse\nof the \"Slave of QXXX\" chip), with each slave's tx count + first/last\nactivity. Non-qrl chains return an empty list.", "operationId": "get_address_slaves_api_v1_qrl2_addresses__address__slaves_get", "parameters": [ { "name": "address", "in": "path", "required": true, "schema": { "type": "string", "title": "Address" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 200, "minimum": 1, "default": 25, "title": "Limit" } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "default": 0, "title": "Offset" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenericListResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "apiKey": [] } ] } }, "/api/v1/qrl2/addresses/{address}/provenance": { "get": { "tags": [ "Addresses" ], "summary": "Get Address Provenance", "description": "Provenance signals for the address page — the first wallet to fund this\naddress (Etherscan \"Funded by\"), plus its first and last transactions.", "operationId": "get_address_provenance_api_v1_qrl2_addresses__address__provenance_get", "parameters": [ { "name": "address", "in": "path", "required": true, "schema": { "type": "string", "title": "Address" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenericObject" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "apiKey": [] } ] } }, "/api/v1/qrl2/addresses/{address}/transactions": { "get": { "tags": [ "Addresses" ], "summary": "Get Address Transactions", "description": "Per-address tx history (newest first).\n\nPages by `cursor` (cheapest, sequential) or by `offset` (random access).\nThe response carries `total`, so callers can show \"page N of M\".\n\nEvery row carries `confirmations` (indexed tip − height + 1) and, on\nQRL 2.0, `finalized` (block at or below the finalized checkpoint; null\non QRL legacy, which has no finality).", "operationId": "get_address_transactions_api_v1_qrl2_addresses__address__transactions_get", "parameters": [ { "name": "address", "in": "path", "required": true, "schema": { "type": "string", "title": "Address" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Opaque pagination token from a previous response's `next_cursor`. Omit to start at the address's newest transaction.", "title": "Cursor" }, "description": "Opaque pagination token from a previous response's `next_cursor`. Omit to start at the address's newest transaction." }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "description": "Skip this many items (random access — powers 'page N of M' and jump-to-oldest). Takes precedence over `cursor` when both are set.", "default": 0, "title": "Offset" }, "description": "Skip this many items (random access — powers 'page N of M' and jump-to-oldest). Takes precedence over `cursor` when both are set." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "description": "Items per page (1-100).", "default": 25, "title": "Limit" }, "description": "Items per page (1-100)." }, { "name": "direction", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^(in|out|both)$", "description": "in=received, out=sent, both=either side", "default": "both", "title": "Direction" }, "description": "in=received, out=sent, both=either side" }, { "name": "tx_type", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter: tx_type", "title": "Tx Type" }, "description": "Filter: tx_type" }, { "name": "time_from", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Filter: timestamp >= Unix seconds", "title": "Time From" }, "description": "Filter: timestamp >= Unix seconds" }, { "name": "time_to", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Filter: timestamp < Unix seconds", "title": "Time To" }, "description": "Filter: timestamp < Unix seconds" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedAddressCursor_TransactionDetail_" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "apiKey": [] } ] } }, "/api/v1/qrl2/addresses/{address}/internal-transactions": { "get": { "tags": [ "Addresses" ], "summary": "Get Address Internal Transactions", "description": "Internal (contract-initiated) native-Quanta transfers touching this\naddress (qrl2 only) — Etherscan-style \"Internal Txns\" tab.\n\nThese move Quanta inside nested EVM call frames (NFT-sale payouts, faucet\nclaims, DEX proceeds, `withdraw()`, SELFDESTRUCT refunds) with NO top-level\nfootprint, so they are DISJOINT from the `/transactions` feed (the parent\ntx's own value is never re-listed here). A single from-OR-to filter means a\nself-transfer appears exactly once. Offset-paginated, newest first.\n\nReturns an empty page on qrl (no EVM contracts) or a pre-mig-111 deploy.", "operationId": "get_address_internal_transactions_api_v1_qrl2_addresses__address__internal_transactions_get", "parameters": [ { "name": "address", "in": "path", "required": true, "schema": { "type": "string", "title": "Address" } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "default": 1, "title": "Page" } }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "default": 25, "title": "Page Size" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddressInternalTxPaginated" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "apiKey": [] } ] } }, "/api/v1/qrl2/addresses/{address}": { "get": { "tags": [ "Addresses" ], "summary": "Get Address", "operationId": "get_address_api_v1_qrl2_addresses__address__get", "parameters": [ { "name": "address", "in": "path", "required": true, "schema": { "type": "string", "title": "Address" } }, { "name": "with_labels", "in": "query", "required": false, "schema": { "type": "boolean", "description": "When true, JOINs `quantascan.address_labels` and includes the primary label (`label`, `label_category`) on the response. Saves a round-trip vs calling `/labels/{address}` separately.", "default": false, "title": "With Labels" }, "description": "When true, JOINs `quantascan.address_labels` and includes the primary label (`label`, `label_category`) on the response. Saves a round-trip vs calling `/labels/{address}` separately." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddressDetail" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "apiKey": [] } ] } }, "/api/v1/qrl2/addresses/{address}/insights": { "get": { "tags": [ "Addresses" ], "summary": "Get Address Insights", "description": "Bundle for Blocks 1, 8, 11 of the wallet flagship.\n\nReturns: cohort badges, rank dimensions, concentration warning, and\nXMSS info (qrl only). Single round-trip from the frontend.", "operationId": "get_address_insights_api_v1_qrl2_addresses__address__insights_get", "parameters": [ { "name": "address", "in": "path", "required": true, "schema": { "type": "string", "title": "Address" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenericObject" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "apiKey": [] } ] } }, "/api/v1/qrl2/addresses/{address}/balance-history": { "get": { "tags": [ "Addresses" ], "summary": "Get Address Balance History", "description": "Daily balance trajectory for the address-detail balance chart.\n\nItems have shape:\n { day, received, sent_with_fees, tx_count_in, tx_count_out,\n net_delta_cumulative }\n\nFull history by default; pass `?window=90d` to cap server-side.", "operationId": "get_address_balance_history_api_v1_qrl2_addresses__address__balance_history_get", "parameters": [ { "name": "address", "in": "path", "required": true, "schema": { "type": "string", "title": "Address" } }, { "name": "window", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional look-back window with unit suffix (e.g. 30d, 90d, 365d). Omit (or pass 'all') for the wallet's FULL history — the default. The chart filters ranges client-side, so the server returns everything by default and never hides a wallet whose only activity predates a rolling window.", "title": "Window" }, "description": "Optional look-back window with unit suffix (e.g. 30d, 90d, 365d). Omit (or pass 'all') for the wallet's FULL history — the default. The chart filters ranges client-side, so the server returns everything by default and never hides a wallet whose only activity predates a rolling window." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ItemsList_GenericObject_" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "apiKey": [] } ] } }, "/api/v1/qrl2/addresses/{address}/token-holdings": { "get": { "tags": [ "Addresses" ], "summary": "Get Address Token Holdings", "description": "QRC-20 tokens currently held by this address (qrl2 only), richest first.\n\nEach item: { token_contract, token_name, token_symbol, token_decimals,\nbalance_raw, balance_display, transfer_count, last_activity }.\nReturns an empty list on qrl (no QRC tokens) or when the address holds none.", "operationId": "get_address_token_holdings_api_v1_qrl2_addresses__address__token_holdings_get", "parameters": [ { "name": "address", "in": "path", "required": true, "schema": { "type": "string", "title": "Address" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 500, "minimum": 1, "default": 100, "title": "Limit" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ItemsList_GenericObject_" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "apiKey": [] } ] } }, "/api/v1/qrl2/addresses/{address}/activity-heatmap": { "get": { "tags": [ "Addresses" ], "summary": "Get Address Activity Heatmap", "description": "7×24 grid (Mon-Sun × 0-23h UTC) of tx counts for Block 3 heatmap.\n\nSparse — only hour/day buckets that ever saw activity are returned.\nFrontend pads missing cells with zeros.", "operationId": "get_address_activity_heatmap_api_v1_qrl2_addresses__address__activity_heatmap_get", "parameters": [ { "name": "address", "in": "path", "required": true, "schema": { "type": "string", "title": "Address" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenericListResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "apiKey": [] } ] } }, "/api/v1/qrl/addresses/stats/summary": { "get": { "tags": [ "Addresses" ], "summary": "Get Address Stats", "operationId": "get_address_stats_api_v1_qrl_addresses_stats_summary_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddressStats" } } } } }, "security": [ { "apiKey": [] } ] } }, "/api/v1/qrl/addresses/top/burners": { "get": { "tags": [ "Addresses" ], "summary": "Get Top Burners", "description": "Top gas-burning addresses (qrl2 only).\n\nReturns addresses ordered by total fees paid in the look-back window.\nPowers a \"who's loading the chain\" widget and helps spot high-volume\nbots / contract-callers.\n\nWindow: pass `?window=7d` (default), `?window=30d`, etc.", "operationId": "get_top_burners_api_v1_qrl_addresses_top_burners_get", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 500, "minimum": 1, "default": 50, "title": "Limit" } }, { "name": "window", "in": "query", "required": false, "schema": { "type": "string", "description": "Look-back window for gas burners ranking. Default 7d.", "default": "7d", "title": "Window" }, "description": "Look-back window for gas burners ranking. Default 7d." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ItemsList_GenericObject_" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "apiKey": [] } ] } }, "/api/v1/qrl/addresses/top/active": { "get": { "tags": [ "Addresses" ], "summary": "Get Top Addresses", "description": "Top addresses on the chain — opinionated leaderboard.\n\nSort options (via `?sort=`): tx_count, balance, total_received,\ntotal_sent (default `-tx_count`). Use `?sort=-field` for descending,\n`?sort=field` for ascending. The underlying Gold view only indexes\nDESC variants today, so an ASC sort still serves the same data set\nordered DESC under the hood.\n\nPagination is offset-based (this is a stable Gold-projection\nleaderboard, not a live feed).", "operationId": "get_top_addresses_api_v1_qrl_addresses_top_active_get", "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "default": 1, "title": "Page" } }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "default": 25, "title": "Page Size" } }, { "name": "q", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 129 }, { "type": "null" } ], "description": "Optional case-insensitive substring filter on address.", "title": "Q" }, "description": "Optional case-insensitive substring filter on address." }, { "name": "with_labels", "in": "query", "required": false, "schema": { "type": "boolean", "description": "When true, include `label` + `label_category` per row.", "default": false, "title": "With Labels" }, "description": "When true, include `label` + `label_category` per row." }, { "name": "with_delta_30d", "in": "query", "required": false, "schema": { "type": "boolean", "description": "When true, include `received_30d` + `sent_30d` UInt256 strings (30-day window).", "default": false, "title": "With Delta 30D" }, "description": "When true, include `received_30d` + `sent_30d` UInt256 strings (30-day window)." }, { "name": "positive_only", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Richlist mode: only addresses with a strictly positive balance (matches the supply 'holders' count). Off by default so tx_count / received sorts still see every address.", "default": false, "title": "Positive Only" }, "description": "Richlist mode: only addresses with a strictly positive balance (matches the supply 'holders' count). Off by default so tx_count / received sorts still see every address." }, { "name": "exclude_sentinel", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Drop sentinel wallets (coinbase / zero-address) so behaviour leaderboards (most-active / top-senders) aren't dominated by the non-organic block-reward sender.", "default": false, "title": "Exclude Sentinel" }, "description": "Drop sentinel wallets (coinbase / zero-address) so behaviour leaderboards (most-active / top-senders) aren't dominated by the non-organic block-reward sender." }, { "name": "exclude", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 2048 }, { "type": "null" } ], "description": "Comma-separated list of addresses to exclude by exact match (e.g. a known migration/genesis wallet).", "title": "Exclude" }, "description": "Comma-separated list of addresses to exclude by exact match (e.g. a known migration/genesis wallet)." }, { "name": "min_balance_pct", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "number", "minimum": 0 }, { "type": "null" } ], "description": "Legacy: keep only addresses whose balance is >= this percentage of total supply. Superseded by `whale_only` (the site-wide whale line is now a fixed 100,000-coin tier, not a % of supply). Still honoured for back-compat when `whale_only` is not set.", "title": "Min Balance Pct" }, "description": "Legacy: keep only addresses whose balance is >= this percentage of total supply. Superseded by `whale_only` (the site-wide whale line is now a fixed 100,000-coin tier, not a % of supply). Still honoured for back-compat when `whale_only` is not set." }, { "name": "whale_only", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Keep only 'whales' — the fixed >= 100,000-coin Whale tier (whale_metrics._FIXED_WHALE_THRESHOLDS, the single site-wide whale definition shared with /whales and the per-wallet Whale badge). Powers the 'large account' leaderboards (newest / dormant whales).", "default": false, "title": "Whale Only" }, "description": "Keep only 'whales' — the fixed >= 100,000-coin Whale tier (whale_metrics._FIXED_WHALE_THRESHOLDS, the single site-wide whale definition shared with /whales and the per-wallet Whale badge). Powers the 'large account' leaderboards (newest / dormant whales)." }, { "name": "sort", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Sort spec: '' (asc) or '-' (desc). Allowed: tx_count, balance, total_received, total_sent, total_fees_paid, first_seen, first_seen_asc, last_seen_asc. Default: -tx_count.", "default": "-tx_count", "title": "Sort" }, "description": "Sort spec: '' (asc) or '-' (desc). Allowed: tx_count, balance, total_received, total_sent, total_fees_paid, first_seen, first_seen_asc, last_seen_asc. Default: -tx_count." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddressTopActiveResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "apiKey": [] } ] } }, "/api/v1/qrl/addresses/{address}/counterparties": { "get": { "tags": [ "Addresses" ], "summary": "Get Address Counterparties", "description": "Top counterparties for an address.\n\nReturns the top `limit` addresses that this address interacted with,\nsorted by transaction count. Each row carries `tx_count_with`,\n`total_sent_to_them`, `total_received_from_them`, and `last_interaction`.\n\nUX: powers a \"Top counterparties\" panel on the address-detail page.", "operationId": "get_address_counterparties_api_v1_qrl_addresses__address__counterparties_get", "parameters": [ { "name": "address", "in": "path", "required": true, "schema": { "type": "string", "title": "Address" } }, { "name": "direction", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^(sent|received|both)$", "description": "sent=outgoing only, received=incoming only, both=either", "default": "both", "title": "Direction" }, "description": "sent=outgoing only, received=incoming only, both=either" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 200, "minimum": 1, "default": 20, "title": "Limit" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenericListResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "apiKey": [] } ] } }, "/api/v1/qrl/addresses/{address}/slaves": { "get": { "tags": [ "Addresses" ], "summary": "Get Address Slaves", "description": "Slave XMSS-keys registered under this master address (QRL-only).\n\nReturns the addresses that named this address as their master (the inverse\nof the \"Slave of QXXX\" chip), with each slave's tx count + first/last\nactivity. Non-qrl chains return an empty list.", "operationId": "get_address_slaves_api_v1_qrl_addresses__address__slaves_get", "parameters": [ { "name": "address", "in": "path", "required": true, "schema": { "type": "string", "title": "Address" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 200, "minimum": 1, "default": 25, "title": "Limit" } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "default": 0, "title": "Offset" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenericListResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "apiKey": [] } ] } }, "/api/v1/qrl/addresses/{address}/provenance": { "get": { "tags": [ "Addresses" ], "summary": "Get Address Provenance", "description": "Provenance signals for the address page — the first wallet to fund this\naddress (Etherscan \"Funded by\"), plus its first and last transactions.", "operationId": "get_address_provenance_api_v1_qrl_addresses__address__provenance_get", "parameters": [ { "name": "address", "in": "path", "required": true, "schema": { "type": "string", "title": "Address" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenericObject" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "apiKey": [] } ] } }, "/api/v1/qrl/addresses/{address}/transactions": { "get": { "tags": [ "Addresses" ], "summary": "Get Address Transactions", "description": "Per-address tx history (newest first).\n\nPages by `cursor` (cheapest, sequential) or by `offset` (random access).\nThe response carries `total`, so callers can show \"page N of M\".\n\nEvery row carries `confirmations` (indexed tip − height + 1) and, on\nQRL 2.0, `finalized` (block at or below the finalized checkpoint; null\non QRL legacy, which has no finality).", "operationId": "get_address_transactions_api_v1_qrl_addresses__address__transactions_get", "parameters": [ { "name": "address", "in": "path", "required": true, "schema": { "type": "string", "title": "Address" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Opaque pagination token from a previous response's `next_cursor`. Omit to start at the address's newest transaction.", "title": "Cursor" }, "description": "Opaque pagination token from a previous response's `next_cursor`. Omit to start at the address's newest transaction." }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "description": "Skip this many items (random access — powers 'page N of M' and jump-to-oldest). Takes precedence over `cursor` when both are set.", "default": 0, "title": "Offset" }, "description": "Skip this many items (random access — powers 'page N of M' and jump-to-oldest). Takes precedence over `cursor` when both are set." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "description": "Items per page (1-100).", "default": 25, "title": "Limit" }, "description": "Items per page (1-100)." }, { "name": "direction", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^(in|out|both)$", "description": "in=received, out=sent, both=either side", "default": "both", "title": "Direction" }, "description": "in=received, out=sent, both=either side" }, { "name": "tx_type", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter: tx_type", "title": "Tx Type" }, "description": "Filter: tx_type" }, { "name": "time_from", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Filter: timestamp >= Unix seconds", "title": "Time From" }, "description": "Filter: timestamp >= Unix seconds" }, { "name": "time_to", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Filter: timestamp < Unix seconds", "title": "Time To" }, "description": "Filter: timestamp < Unix seconds" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedAddressCursor_TransactionDetail_" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "apiKey": [] } ] } }, "/api/v1/qrl/addresses/{address}/internal-transactions": { "get": { "tags": [ "Addresses" ], "summary": "Get Address Internal Transactions", "description": "Internal (contract-initiated) native-Quanta transfers touching this\naddress (qrl2 only) — Etherscan-style \"Internal Txns\" tab.\n\nThese move Quanta inside nested EVM call frames (NFT-sale payouts, faucet\nclaims, DEX proceeds, `withdraw()`, SELFDESTRUCT refunds) with NO top-level\nfootprint, so they are DISJOINT from the `/transactions` feed (the parent\ntx's own value is never re-listed here). A single from-OR-to filter means a\nself-transfer appears exactly once. Offset-paginated, newest first.\n\nReturns an empty page on qrl (no EVM contracts) or a pre-mig-111 deploy.", "operationId": "get_address_internal_transactions_api_v1_qrl_addresses__address__internal_transactions_get", "parameters": [ { "name": "address", "in": "path", "required": true, "schema": { "type": "string", "title": "Address" } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "default": 1, "title": "Page" } }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "default": 25, "title": "Page Size" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddressInternalTxPaginated" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "apiKey": [] } ] } }, "/api/v1/qrl/addresses/{address}": { "get": { "tags": [ "Addresses" ], "summary": "Get Address", "operationId": "get_address_api_v1_qrl_addresses__address__get", "parameters": [ { "name": "address", "in": "path", "required": true, "schema": { "type": "string", "title": "Address" } }, { "name": "with_labels", "in": "query", "required": false, "schema": { "type": "boolean", "description": "When true, JOINs `quantascan.address_labels` and includes the primary label (`label`, `label_category`) on the response. Saves a round-trip vs calling `/labels/{address}` separately.", "default": false, "title": "With Labels" }, "description": "When true, JOINs `quantascan.address_labels` and includes the primary label (`label`, `label_category`) on the response. Saves a round-trip vs calling `/labels/{address}` separately." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddressDetail" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "apiKey": [] } ] } }, "/api/v1/qrl/addresses/{address}/insights": { "get": { "tags": [ "Addresses" ], "summary": "Get Address Insights", "description": "Bundle for Blocks 1, 8, 11 of the wallet flagship.\n\nReturns: cohort badges, rank dimensions, concentration warning, and\nXMSS info (qrl only). Single round-trip from the frontend.", "operationId": "get_address_insights_api_v1_qrl_addresses__address__insights_get", "parameters": [ { "name": "address", "in": "path", "required": true, "schema": { "type": "string", "title": "Address" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenericObject" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "apiKey": [] } ] } }, "/api/v1/qrl/addresses/{address}/balance-history": { "get": { "tags": [ "Addresses" ], "summary": "Get Address Balance History", "description": "Daily balance trajectory for the address-detail balance chart.\n\nItems have shape:\n { day, received, sent_with_fees, tx_count_in, tx_count_out,\n net_delta_cumulative }\n\nFull history by default; pass `?window=90d` to cap server-side.", "operationId": "get_address_balance_history_api_v1_qrl_addresses__address__balance_history_get", "parameters": [ { "name": "address", "in": "path", "required": true, "schema": { "type": "string", "title": "Address" } }, { "name": "window", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional look-back window with unit suffix (e.g. 30d, 90d, 365d). Omit (or pass 'all') for the wallet's FULL history — the default. The chart filters ranges client-side, so the server returns everything by default and never hides a wallet whose only activity predates a rolling window.", "title": "Window" }, "description": "Optional look-back window with unit suffix (e.g. 30d, 90d, 365d). Omit (or pass 'all') for the wallet's FULL history — the default. The chart filters ranges client-side, so the server returns everything by default and never hides a wallet whose only activity predates a rolling window." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ItemsList_GenericObject_" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "apiKey": [] } ] } }, "/api/v1/qrl/addresses/{address}/token-holdings": { "get": { "tags": [ "Addresses" ], "summary": "Get Address Token Holdings", "description": "QRC-20 tokens currently held by this address (qrl2 only), richest first.\n\nEach item: { token_contract, token_name, token_symbol, token_decimals,\nbalance_raw, balance_display, transfer_count, last_activity }.\nReturns an empty list on qrl (no QRC tokens) or when the address holds none.", "operationId": "get_address_token_holdings_api_v1_qrl_addresses__address__token_holdings_get", "parameters": [ { "name": "address", "in": "path", "required": true, "schema": { "type": "string", "title": "Address" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 500, "minimum": 1, "default": 100, "title": "Limit" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ItemsList_GenericObject_" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "apiKey": [] } ] } }, "/api/v1/qrl/addresses/{address}/activity-heatmap": { "get": { "tags": [ "Addresses" ], "summary": "Get Address Activity Heatmap", "description": "7×24 grid (Mon-Sun × 0-23h UTC) of tx counts for Block 3 heatmap.\n\nSparse — only hour/day buckets that ever saw activity are returned.\nFrontend pads missing cells with zeros.", "operationId": "get_address_activity_heatmap_api_v1_qrl_addresses__address__activity_heatmap_get", "parameters": [ { "name": "address", "in": "path", "required": true, "schema": { "type": "string", "title": "Address" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenericListResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "apiKey": [] } ] } }, "/api/v1/qrl2/blocks/": { "get": { "tags": [ "Blocks" ], "summary": "Get Blocks", "description": "Cursor-paginated block list (live feed — newest first).\n\nPass `cursor` from the previous response to get older blocks. The cursor\nencodes the last block's height; the next page is `WHERE height < cursor`\nordered by height DESC. No offset/page params — blocks are inserted at\nthe head continuously and offset paging would skip or duplicate rows\nbetween page-clicks.", "operationId": "get_blocks_api_v1_qrl2_blocks__get", "parameters": [ { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Opaque pagination token from a previous response's `next_cursor`. Omit to start at the chain head (newest). Do not decode/construct.", "title": "Cursor" }, "description": "Opaque pagination token from a previous response's `next_cursor`. Omit to start at the chain head (newest). Do not decode/construct." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "description": "Items per page (1-100).", "default": 25, "title": "Limit" }, "description": "Items per page (1-100)." }, { "name": "min_height", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Filter: height >=", "title": "Min Height" }, "description": "Filter: height >=" }, { "name": "max_height", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Filter: height <=", "title": "Max Height" }, "description": "Filter: height <=" }, { "name": "miner", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter: block proposer / miner address", "title": "Miner" }, "description": "Filter: block proposer / miner address" }, { "name": "min_gas_used", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Filter: gas_used >=", "title": "Min Gas Used" }, "description": "Filter: gas_used >=" }, { "name": "time_from", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Filter: timestamp >= Unix seconds", "title": "Time From" }, "description": "Filter: timestamp >= Unix seconds" }, { "name": "time_to", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Filter: timestamp < Unix seconds", "title": "Time To" }, "description": "Filter: timestamp < Unix seconds" }, { "name": "has_withdrawals", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "qrl2 only: True=only blocks with withdrawals, False=only without", "title": "Has Withdrawals" }, "description": "qrl2 only: True=only blocks with withdrawals, False=only without" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedCursor_BlockSummary_" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "apiKey": [] } ] } }, "/api/v1/qrl2/blocks/latest": { "get": { "tags": [ "Blocks" ], "summary": "Get Latest Block", "operationId": "get_latest_block_api_v1_qrl2_blocks_latest_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BlockDetail" } } } } }, "security": [ { "apiKey": [] } ] } }, "/api/v1/qrl2/blocks/stats/summary": { "get": { "tags": [ "Blocks" ], "summary": "Get Block Stats", "operationId": "get_block_stats_api_v1_qrl2_blocks_stats_summary_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChainStats" } } } } }, "security": [ { "apiKey": [] } ] } }, "/api/v1/qrl2/blocks/stats/daily": { "get": { "tags": [ "Blocks" ], "summary": "Get Daily Activity", "description": "Per-day rollup of block_count, tx_count, gas_used — Gold layer.\n\nWindow: pass `?window=30d` (default), `?window=90d`, etc.", "operationId": "get_daily_activity_api_v1_qrl2_blocks_stats_daily_get", "parameters": [ { "name": "window", "in": "query", "required": false, "schema": { "type": "string", "description": "Look-back window for per-day rollups. Default 30d. Examples: 7d, 30d, 90d, 365d.", "default": "30d", "title": "Window" }, "description": "Look-back window for per-day rollups. Default 30d. Examples: 7d, 30d, 90d, 365d." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ItemsList_DailyActivityItem_" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "apiKey": [] } ] } }, "/api/v1/qrl2/blocks/hash/{block_hash}": { "get": { "tags": [ "Blocks" ], "summary": "Get Block By Hash", "description": "Get a block by its hash. Mounted under /blocks/hash/{hash} (not\n/blocks/{hash}) to avoid ambiguity with the integer-height route below.\nRoutes are matched in declaration order, so this specific path wins\nover the catch-all /{height} when the URL starts with `hash/`.", "operationId": "get_block_by_hash_api_v1_qrl2_blocks_hash__block_hash__get", "parameters": [ { "name": "block_hash", "in": "path", "required": true, "schema": { "type": "string", "title": "Block Hash" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BlockDetail" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "apiKey": [] } ] } }, "/api/v1/qrl2/blocks/{height}": { "get": { "tags": [ "Blocks" ], "summary": "Get Block By Height", "operationId": "get_block_by_height_api_v1_qrl2_blocks__height__get", "parameters": [ { "name": "height", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 0, "title": "Height" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BlockDetail" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "apiKey": [] } ] } }, "/api/v1/qrl/blocks/": { "get": { "tags": [ "Blocks" ], "summary": "Get Blocks", "description": "Cursor-paginated block list (live feed — newest first).\n\nPass `cursor` from the previous response to get older blocks. The cursor\nencodes the last block's height; the next page is `WHERE height < cursor`\nordered by height DESC. No offset/page params — blocks are inserted at\nthe head continuously and offset paging would skip or duplicate rows\nbetween page-clicks.", "operationId": "get_blocks_api_v1_qrl_blocks__get", "parameters": [ { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Opaque pagination token from a previous response's `next_cursor`. Omit to start at the chain head (newest). Do not decode/construct.", "title": "Cursor" }, "description": "Opaque pagination token from a previous response's `next_cursor`. Omit to start at the chain head (newest). Do not decode/construct." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "description": "Items per page (1-100).", "default": 25, "title": "Limit" }, "description": "Items per page (1-100)." }, { "name": "min_height", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Filter: height >=", "title": "Min Height" }, "description": "Filter: height >=" }, { "name": "max_height", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Filter: height <=", "title": "Max Height" }, "description": "Filter: height <=" }, { "name": "miner", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter: block proposer / miner address", "title": "Miner" }, "description": "Filter: block proposer / miner address" }, { "name": "min_gas_used", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Filter: gas_used >=", "title": "Min Gas Used" }, "description": "Filter: gas_used >=" }, { "name": "time_from", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Filter: timestamp >= Unix seconds", "title": "Time From" }, "description": "Filter: timestamp >= Unix seconds" }, { "name": "time_to", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Filter: timestamp < Unix seconds", "title": "Time To" }, "description": "Filter: timestamp < Unix seconds" }, { "name": "has_withdrawals", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "qrl2 only: True=only blocks with withdrawals, False=only without", "title": "Has Withdrawals" }, "description": "qrl2 only: True=only blocks with withdrawals, False=only without" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedCursor_BlockSummary_" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "apiKey": [] } ] } }, "/api/v1/qrl/blocks/latest": { "get": { "tags": [ "Blocks" ], "summary": "Get Latest Block", "operationId": "get_latest_block_api_v1_qrl_blocks_latest_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BlockDetail" } } } } }, "security": [ { "apiKey": [] } ] } }, "/api/v1/qrl/blocks/stats/summary": { "get": { "tags": [ "Blocks" ], "summary": "Get Block Stats", "operationId": "get_block_stats_api_v1_qrl_blocks_stats_summary_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChainStats" } } } } }, "security": [ { "apiKey": [] } ] } }, "/api/v1/qrl/blocks/stats/daily": { "get": { "tags": [ "Blocks" ], "summary": "Get Daily Activity", "description": "Per-day rollup of block_count, tx_count, gas_used — Gold layer.\n\nWindow: pass `?window=30d` (default), `?window=90d`, etc.", "operationId": "get_daily_activity_api_v1_qrl_blocks_stats_daily_get", "parameters": [ { "name": "window", "in": "query", "required": false, "schema": { "type": "string", "description": "Look-back window for per-day rollups. Default 30d. Examples: 7d, 30d, 90d, 365d.", "default": "30d", "title": "Window" }, "description": "Look-back window for per-day rollups. Default 30d. Examples: 7d, 30d, 90d, 365d." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ItemsList_DailyActivityItem_" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "apiKey": [] } ] } }, "/api/v1/qrl/blocks/hash/{block_hash}": { "get": { "tags": [ "Blocks" ], "summary": "Get Block By Hash", "description": "Get a block by its hash. Mounted under /blocks/hash/{hash} (not\n/blocks/{hash}) to avoid ambiguity with the integer-height route below.\nRoutes are matched in declaration order, so this specific path wins\nover the catch-all /{height} when the URL starts with `hash/`.", "operationId": "get_block_by_hash_api_v1_qrl_blocks_hash__block_hash__get", "parameters": [ { "name": "block_hash", "in": "path", "required": true, "schema": { "type": "string", "title": "Block Hash" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BlockDetail" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "apiKey": [] } ] } }, "/api/v1/qrl/blocks/{height}": { "get": { "tags": [ "Blocks" ], "summary": "Get Block By Height", "operationId": "get_block_by_height_api_v1_qrl_blocks__height__get", "parameters": [ { "name": "height", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 0, "title": "Height" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BlockDetail" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "apiKey": [] } ] } }, "/api/v1/qrl2/transactions/": { "get": { "tags": [ "Transactions" ], "summary": "Get Transactions", "description": "Cursor-paginated transaction list (live feed — newest first).\n\nIncludes QRL coinbase transactions (block rewards) unless a `method`\nfilter says otherwise (`method=sent` leaves them out).\n\nPass `cursor` from the previous response to get older transactions.\nNo offset/page params — transactions arrive at the head continuously\nand offset paging would skip or duplicate rows between page-clicks.", "operationId": "get_transactions_api_v1_qrl2_transactions__get", "parameters": [ { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Opaque pagination token from a previous response's `next_cursor`. Omit to start at the chain head (newest). Do not decode/construct.", "title": "Cursor" }, "description": "Opaque pagination token from a previous response's `next_cursor`. Omit to start at the chain head (newest). Do not decode/construct." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "description": "Items per page (1-100).", "default": 25, "title": "Limit" }, "description": "Items per page (1-100)." }, { "name": "from", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter: sender address", "title": "From" }, "description": "Filter: sender address" }, { "name": "to", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter: recipient address", "title": "To" }, "description": "Filter: recipient address" }, { "name": "tx_type", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter: tx_type (transfer/coinbase/slave/...)", "title": "Tx Type" }, "description": "Filter: tx_type (transfer/coinbase/slave/...)" }, { "name": "status", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "maximum": 1, "minimum": 0 }, { "type": "null" } ], "description": "Filter: 1=success, 0=reverted", "title": "Status" }, "description": "Filter: 1=success, 0=reverted" }, { "name": "min_value", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter: value >= (decimal UInt256 string)", "title": "Min Value" }, "description": "Filter: value >= (decimal UInt256 string)" }, { "name": "max_value", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter: value <= (decimal UInt256 string)", "title": "Max Value" }, "description": "Filter: value <= (decimal UInt256 string)" }, { "name": "time_from", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Filter: timestamp >= Unix seconds", "title": "Time From" }, "description": "Filter: timestamp >= Unix seconds" }, { "name": "time_to", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Filter: timestamp < Unix seconds", "title": "Time To" }, "description": "Filter: timestamp < Unix seconds" }, { "name": "method", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "pattern": "^(sent|coinbase|transfer|token_transfer|multi_recipient|slave|message|token_creation|other|contract_call|contract_creation|failed)$" }, { "type": "null" } ], "description": "High-level method filter for the chip-bar UI. Valid values: sent | coinbase | transfer | token_transfer | multi_recipient | slave | message | token_creation | other | contract_call | contract_creation | failed. Omit for every transaction, block rewards included. `sent` = everything except the QRL coinbase (block reward); `coinbase` = only block rewards. `sent`, `coinbase`, `multi_recipient`, `slave`, `message`, `token_creation` and `other` (multisig, lattice keys and any other subtype) are qrl-only; `contract_call`, `contract_creation` and `failed` are qrl2-only. `token_transfer` maps to the QRC-20 transfer() call on qrl2 and the transfer_token subtype on qrl. Counts per value: `/transactions/type-counts`.", "title": "Method" }, "description": "High-level method filter for the chip-bar UI. Valid values: sent | coinbase | transfer | token_transfer | multi_recipient | slave | message | token_creation | other | contract_call | contract_creation | failed. Omit for every transaction, block rewards included. `sent` = everything except the QRL coinbase (block reward); `coinbase` = only block rewards. `sent`, `coinbase`, `multi_recipient`, `slave`, `message`, `token_creation` and `other` (multisig, lattice keys and any other subtype) are qrl-only; `contract_call`, `contract_creation` and `failed` are qrl2-only. `token_transfer` maps to the QRC-20 transfer() call on qrl2 and the transfer_token subtype on qrl. Counts per value: `/transactions/type-counts`." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedCursor_TransactionDetail_" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "apiKey": [] } ] } }, "/api/v1/qrl2/transactions/whales": { "get": { "tags": [ "Transactions" ], "summary": "Get Whale Transactions", "description": "Recent transactions above a value threshold (\"whale alert\" feed).\n\nThin wrapper over /transactions/ with a sensible per-chain default\nthreshold. Frontend can render a dedicated \"Whale moves\" widget\nwithout hardcoding the threshold itself.", "operationId": "get_whale_transactions_api_v1_qrl2_transactions_whales_get", "parameters": [ { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Opaque pagination token from a previous response's `next_cursor`.", "title": "Cursor" }, "description": "Opaque pagination token from a previous response's `next_cursor`." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "description": "Items per page (1-100).", "default": 25, "title": "Limit" }, "description": "Items per page (1-100)." }, { "name": "min_value", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Threshold (decimal UInt256 string). Default per-chain: 10k QRL for qrl, 1k QRL2 for qrl2.", "title": "Min Value" }, "description": "Threshold (decimal UInt256 string). Default per-chain: 10k QRL for qrl, 1k QRL2 for qrl2." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedCursor_TransactionDetail_" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "apiKey": [] } ] } }, "/api/v1/qrl2/transactions/failed": { "get": { "tags": [ "Transactions" ], "summary": "Get Failed Transactions", "description": "Reverted transactions feed (status=0).\n\nWrapper over /transactions/?status=0. QRL2-only in practice — QRL\nPoW txs don't have an EVM revert concept (status hardcoded to\n\"success\" in canonical_schema).", "operationId": "get_failed_transactions_api_v1_qrl2_transactions_failed_get", "parameters": [ { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Opaque pagination token from a previous response's `next_cursor`.", "title": "Cursor" }, "description": "Opaque pagination token from a previous response's `next_cursor`." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "description": "Items per page (1-100).", "default": 25, "title": "Limit" }, "description": "Items per page (1-100)." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedCursor_TransactionDetail_" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "apiKey": [] } ] } }, "/api/v1/qrl2/transactions/type-counts": { "get": { "tags": [ "Transactions" ], "summary": "Get Transaction Type Counts", "description": "How many transactions match each `method` filter of the list endpoint.\n\n`all` counts every transaction including QRL block rewards (coinbase).\nOn QRL, `counts.sent` + `counts.coinbase` == `all`; the type counts do not\nadd up to `all` because `multi_recipient` is a subset of `transfer`.\nExact counts, refreshed every 10 minutes. `available` is false when a\npart could not be computed; the missing numbers are then left out.", "operationId": "get_transaction_type_counts_api_v1_qrl2_transactions_type_counts_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransactionTypeCounts" } } } } }, "security": [ { "apiKey": [] } ] } }, "/api/v1/qrl2/transactions/block/{block_height}": { "get": { "tags": [ "Transactions" ], "summary": "Get Transactions By Block", "operationId": "get_transactions_by_block_api_v1_qrl2_transactions_block__block_height__get", "parameters": [ { "name": "block_height", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 0, "title": "Block Height" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BlockTransactionsList" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "apiKey": [] } ] } }, "/api/v1/qrl2/transactions/{tx_hash}": { "get": { "tags": [ "Transactions" ], "summary": "Get Transaction By Hash", "description": "One transaction by hash, all recipients flattened into `recipients[]`.\n\n`confirmations` = indexed tip − block height + 1 (the including block\ncounts as one; 0 while the block is not yet fully indexed).\n`finalized` (QRL 2.0 only) is true once the block is at or below the\nlatest Casper-FFG finalized checkpoint — irreversible, not just deep.\nIt is null on QRL legacy (Proof-of-Work has no finality: judge by\n`confirmations`) and when finality data is unavailable.", "operationId": "get_transaction_by_hash_api_v1_qrl2_transactions__tx_hash__get", "parameters": [ { "name": "tx_hash", "in": "path", "required": true, "schema": { "type": "string", "title": "Tx Hash" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransactionDetailResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "apiKey": [] } ] } }, "/api/v1/qrl/transactions/": { "get": { "tags": [ "Transactions" ], "summary": "Get Transactions", "description": "Cursor-paginated transaction list (live feed — newest first).\n\nIncludes QRL coinbase transactions (block rewards) unless a `method`\nfilter says otherwise (`method=sent` leaves them out).\n\nPass `cursor` from the previous response to get older transactions.\nNo offset/page params — transactions arrive at the head continuously\nand offset paging would skip or duplicate rows between page-clicks.", "operationId": "get_transactions_api_v1_qrl_transactions__get", "parameters": [ { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Opaque pagination token from a previous response's `next_cursor`. Omit to start at the chain head (newest). Do not decode/construct.", "title": "Cursor" }, "description": "Opaque pagination token from a previous response's `next_cursor`. Omit to start at the chain head (newest). Do not decode/construct." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "description": "Items per page (1-100).", "default": 25, "title": "Limit" }, "description": "Items per page (1-100)." }, { "name": "from", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter: sender address", "title": "From" }, "description": "Filter: sender address" }, { "name": "to", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter: recipient address", "title": "To" }, "description": "Filter: recipient address" }, { "name": "tx_type", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter: tx_type (transfer/coinbase/slave/...)", "title": "Tx Type" }, "description": "Filter: tx_type (transfer/coinbase/slave/...)" }, { "name": "status", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "maximum": 1, "minimum": 0 }, { "type": "null" } ], "description": "Filter: 1=success, 0=reverted", "title": "Status" }, "description": "Filter: 1=success, 0=reverted" }, { "name": "min_value", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter: value >= (decimal UInt256 string)", "title": "Min Value" }, "description": "Filter: value >= (decimal UInt256 string)" }, { "name": "max_value", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter: value <= (decimal UInt256 string)", "title": "Max Value" }, "description": "Filter: value <= (decimal UInt256 string)" }, { "name": "time_from", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Filter: timestamp >= Unix seconds", "title": "Time From" }, "description": "Filter: timestamp >= Unix seconds" }, { "name": "time_to", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Filter: timestamp < Unix seconds", "title": "Time To" }, "description": "Filter: timestamp < Unix seconds" }, { "name": "method", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "pattern": "^(sent|coinbase|transfer|token_transfer|multi_recipient|slave|message|token_creation|other|contract_call|contract_creation|failed)$" }, { "type": "null" } ], "description": "High-level method filter for the chip-bar UI. Valid values: sent | coinbase | transfer | token_transfer | multi_recipient | slave | message | token_creation | other | contract_call | contract_creation | failed. Omit for every transaction, block rewards included. `sent` = everything except the QRL coinbase (block reward); `coinbase` = only block rewards. `sent`, `coinbase`, `multi_recipient`, `slave`, `message`, `token_creation` and `other` (multisig, lattice keys and any other subtype) are qrl-only; `contract_call`, `contract_creation` and `failed` are qrl2-only. `token_transfer` maps to the QRC-20 transfer() call on qrl2 and the transfer_token subtype on qrl. Counts per value: `/transactions/type-counts`.", "title": "Method" }, "description": "High-level method filter for the chip-bar UI. Valid values: sent | coinbase | transfer | token_transfer | multi_recipient | slave | message | token_creation | other | contract_call | contract_creation | failed. Omit for every transaction, block rewards included. `sent` = everything except the QRL coinbase (block reward); `coinbase` = only block rewards. `sent`, `coinbase`, `multi_recipient`, `slave`, `message`, `token_creation` and `other` (multisig, lattice keys and any other subtype) are qrl-only; `contract_call`, `contract_creation` and `failed` are qrl2-only. `token_transfer` maps to the QRC-20 transfer() call on qrl2 and the transfer_token subtype on qrl. Counts per value: `/transactions/type-counts`." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedCursor_TransactionDetail_" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "apiKey": [] } ] } }, "/api/v1/qrl/transactions/whales": { "get": { "tags": [ "Transactions" ], "summary": "Get Whale Transactions", "description": "Recent transactions above a value threshold (\"whale alert\" feed).\n\nThin wrapper over /transactions/ with a sensible per-chain default\nthreshold. Frontend can render a dedicated \"Whale moves\" widget\nwithout hardcoding the threshold itself.", "operationId": "get_whale_transactions_api_v1_qrl_transactions_whales_get", "parameters": [ { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Opaque pagination token from a previous response's `next_cursor`.", "title": "Cursor" }, "description": "Opaque pagination token from a previous response's `next_cursor`." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "description": "Items per page (1-100).", "default": 25, "title": "Limit" }, "description": "Items per page (1-100)." }, { "name": "min_value", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Threshold (decimal UInt256 string). Default per-chain: 10k QRL for qrl, 1k QRL2 for qrl2.", "title": "Min Value" }, "description": "Threshold (decimal UInt256 string). Default per-chain: 10k QRL for qrl, 1k QRL2 for qrl2." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedCursor_TransactionDetail_" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "apiKey": [] } ] } }, "/api/v1/qrl/transactions/failed": { "get": { "tags": [ "Transactions" ], "summary": "Get Failed Transactions", "description": "Reverted transactions feed (status=0).\n\nWrapper over /transactions/?status=0. QRL2-only in practice — QRL\nPoW txs don't have an EVM revert concept (status hardcoded to\n\"success\" in canonical_schema).", "operationId": "get_failed_transactions_api_v1_qrl_transactions_failed_get", "parameters": [ { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Opaque pagination token from a previous response's `next_cursor`.", "title": "Cursor" }, "description": "Opaque pagination token from a previous response's `next_cursor`." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "description": "Items per page (1-100).", "default": 25, "title": "Limit" }, "description": "Items per page (1-100)." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedCursor_TransactionDetail_" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "apiKey": [] } ] } }, "/api/v1/qrl/transactions/type-counts": { "get": { "tags": [ "Transactions" ], "summary": "Get Transaction Type Counts", "description": "How many transactions match each `method` filter of the list endpoint.\n\n`all` counts every transaction including QRL block rewards (coinbase).\nOn QRL, `counts.sent` + `counts.coinbase` == `all`; the type counts do not\nadd up to `all` because `multi_recipient` is a subset of `transfer`.\nExact counts, refreshed every 10 minutes. `available` is false when a\npart could not be computed; the missing numbers are then left out.", "operationId": "get_transaction_type_counts_api_v1_qrl_transactions_type_counts_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransactionTypeCounts" } } } } }, "security": [ { "apiKey": [] } ] } }, "/api/v1/qrl/transactions/block/{block_height}": { "get": { "tags": [ "Transactions" ], "summary": "Get Transactions By Block", "operationId": "get_transactions_by_block_api_v1_qrl_transactions_block__block_height__get", "parameters": [ { "name": "block_height", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 0, "title": "Block Height" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BlockTransactionsList" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "apiKey": [] } ] } }, "/api/v1/qrl/transactions/{tx_hash}": { "get": { "tags": [ "Transactions" ], "summary": "Get Transaction By Hash", "description": "One transaction by hash, all recipients flattened into `recipients[]`.\n\n`confirmations` = indexed tip − block height + 1 (the including block\ncounts as one; 0 while the block is not yet fully indexed).\n`finalized` (QRL 2.0 only) is true once the block is at or below the\nlatest Casper-FFG finalized checkpoint — irreversible, not just deep.\nIt is null on QRL legacy (Proof-of-Work has no finality: judge by\n`confirmations`) and when finality data is unavailable.", "operationId": "get_transaction_by_hash_api_v1_qrl_transactions__tx_hash__get", "parameters": [ { "name": "tx_hash", "in": "path", "required": true, "schema": { "type": "string", "title": "Tx Hash" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransactionDetailResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "apiKey": [] } ] } }, "/api/v1/qrl2/tokens/stats/summary": { "get": { "tags": [ "Tokens" ], "summary": "Get Token Stats", "description": "Headline metrics for the tokens-landing page.", "operationId": "get_token_stats_api_v1_qrl2_tokens_stats_summary_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TokenStatsSummary" } } } } }, "security": [ { "apiKey": [] } ] } }, "/api/v1/qrl2/tokens/": { "get": { "tags": [ "Tokens" ], "summary": "List Tokens", "description": "Paginated list of tokens for a given chain (stable Gold-projection).\n\nqrl2 supports the full sort/filter surface. qrl only supports\n`?sort=-newest` / `?sort=-supply` and ignores `type`, `metadata_status`\n(qrl native tokens have no per-holder / per-event index).\n\nWave 4 of the API consistency refactor: `?sort_by=` + `?sort_dir=` →\n`?sort=` with `-` prefix for desc (D5). `?age_lte_days=` → `?max_age=`\nduration (D4).", "operationId": "list_tokens_api_v1_qrl2_tokens__get", "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "default": 1, "title": "Page" } }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "default": 25, "title": "Page Size" } }, { "name": "type", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "qrc20|qrc721|qrc1155 (qrl2 only)", "title": "Type" }, "description": "qrc20|qrc721|qrc1155 (qrl2 only)" }, { "name": "metadata_status", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "ok|partial|failed (qrl2 only)", "title": "Metadata Status" }, "description": "ok|partial|failed (qrl2 only)" }, { "name": "q", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 64 }, { "type": "null" } ], "description": "Substring match on symbol/name", "title": "Q" }, "description": "Substring match on symbol/name" }, { "name": "max_age", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "duration" }, { "type": "null" } ], "description": "Optional max-age filter (D4 duration). When set, returns only tokens whose first_seen_at falls within the window. Examples: 30d, 90d, 1y.", "title": "Max Age" }, "description": "Optional max-age filter (D4 duration). When set, returns only tokens whose first_seen_at falls within the window. Examples: 30d, 90d, 1y." }, { "name": "sort", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Sort spec: '' (asc) or '-' (desc). qrl2 allowed: transfers, transfers_24h, holders, supply, newest. qrl allowed: newest, supply. Default qrl2 = -transfers, qrl = -newest.", "title": "Sort" }, "description": "Sort spec: '' (asc) or '-' (desc). qrl2 allowed: transfers, transfers_24h, holders, supply, newest. qrl allowed: newest, supply. Default qrl2 = -transfers, qrl = -newest." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TokensPaginated" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "apiKey": [] } ] } }, "/api/v1/qrl2/tokens/{token_id}": { "get": { "tags": [ "Tokens" ], "summary": "Get Token", "description": "Single-token detail.\n\nThe id-format depends on chain (determined by URL prefix):\n - /api/v1/qrl2/tokens/{id} → qrl2; id is the contract address (Q + 40 or 128 hex)\n - /api/v1/qrl/tokens/{id} → qrl; id is the creation tx-hash", "operationId": "get_token_api_v1_qrl2_tokens__token_id__get", "parameters": [ { "name": "token_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Token Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TokenDetail" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "apiKey": [] } ] } }, "/api/v1/qrl2/tokens/{token_contract}/distribution": { "get": { "tags": [ "Tokens" ], "summary": "Get Token Distribution", "description": "Token holder distribution / concentration stats.\n\nReturns top-10 / top-50 / top-100 cumulative share + HHI\n(Herfindahl-Hirschman Index) over the top-100. Powers a\n\"concentration\" widget on the token-detail page.", "operationId": "get_token_distribution_api_v1_qrl2_tokens__token_contract__distribution_get", "parameters": [ { "name": "token_contract", "in": "path", "required": true, "schema": { "type": "string", "title": "Token Contract" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TokenDistribution" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "apiKey": [] } ] } }, "/api/v1/qrl2/tokens/{token_contract}/holders": { "get": { "tags": [ "Tokens" ], "summary": "Get Token Holders", "description": "Top holders by balance for a QRL2 QRC-20 token. Zero-address (burn sink)\nis excluded via the underlying `qrl2_token_top_holders` view filter.", "operationId": "get_token_holders_api_v1_qrl2_tokens__token_contract__holders_get", "parameters": [ { "name": "token_contract", "in": "path", "required": true, "schema": { "type": "string", "title": "Token Contract" } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "default": 1, "title": "Page" } }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "default": 20, "title": "Page Size" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TokenHoldersList" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "apiKey": [] } ] } }, "/api/v1/qrl2/tokens/{token_contract}/transfers": { "get": { "tags": [ "Tokens" ], "summary": "Get Token Transfers", "description": "Decoded transfer events for a QRL2 token. Returns QRC-20/721/1155 transfers\nvia the unified `qrl2_qrc_transfers_all` view.", "operationId": "get_token_transfers_api_v1_qrl2_tokens__token_contract__transfers_get", "parameters": [ { "name": "token_contract", "in": "path", "required": true, "schema": { "type": "string", "title": "Token Contract" } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "default": 1, "title": "Page" } }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "default": 20, "title": "Page Size" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TokenTransfersList" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "apiKey": [] } ] } }, "/api/v1/qrl2/tokens/{token_contract}/balance/{address}": { "get": { "tags": [ "Tokens" ], "summary": "Get Token Balance", "description": "Balance of a single (token, holder) pair, decimals-corrected for display.", "operationId": "get_token_balance_api_v1_qrl2_tokens__token_contract__balance__address__get", "parameters": [ { "name": "token_contract", "in": "path", "required": true, "schema": { "type": "string", "title": "Token Contract" } }, { "name": "address", "in": "path", "required": true, "schema": { "type": "string", "title": "Address" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TokenHolderBalance" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "apiKey": [] } ] } }, "/api/v1/qrl/tokens/stats/summary": { "get": { "tags": [ "Tokens" ], "summary": "Get Token Stats", "description": "Headline metrics for the tokens-landing page.", "operationId": "get_token_stats_api_v1_qrl_tokens_stats_summary_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TokenStatsSummary" } } } } }, "security": [ { "apiKey": [] } ] } }, "/api/v1/qrl/tokens/": { "get": { "tags": [ "Tokens" ], "summary": "List Tokens", "description": "Paginated list of tokens for a given chain (stable Gold-projection).\n\nqrl2 supports the full sort/filter surface. qrl only supports\n`?sort=-newest` / `?sort=-supply` and ignores `type`, `metadata_status`\n(qrl native tokens have no per-holder / per-event index).\n\nWave 4 of the API consistency refactor: `?sort_by=` + `?sort_dir=` →\n`?sort=` with `-` prefix for desc (D5). `?age_lte_days=` → `?max_age=`\nduration (D4).", "operationId": "list_tokens_api_v1_qrl_tokens__get", "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "default": 1, "title": "Page" } }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "default": 25, "title": "Page Size" } }, { "name": "type", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "qrc20|qrc721|qrc1155 (qrl2 only)", "title": "Type" }, "description": "qrc20|qrc721|qrc1155 (qrl2 only)" }, { "name": "metadata_status", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "ok|partial|failed (qrl2 only)", "title": "Metadata Status" }, "description": "ok|partial|failed (qrl2 only)" }, { "name": "q", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 64 }, { "type": "null" } ], "description": "Substring match on symbol/name", "title": "Q" }, "description": "Substring match on symbol/name" }, { "name": "max_age", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "duration" }, { "type": "null" } ], "description": "Optional max-age filter (D4 duration). When set, returns only tokens whose first_seen_at falls within the window. Examples: 30d, 90d, 1y.", "title": "Max Age" }, "description": "Optional max-age filter (D4 duration). When set, returns only tokens whose first_seen_at falls within the window. Examples: 30d, 90d, 1y." }, { "name": "sort", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Sort spec: '' (asc) or '-' (desc). qrl2 allowed: transfers, transfers_24h, holders, supply, newest. qrl allowed: newest, supply. Default qrl2 = -transfers, qrl = -newest.", "title": "Sort" }, "description": "Sort spec: '' (asc) or '-' (desc). qrl2 allowed: transfers, transfers_24h, holders, supply, newest. qrl allowed: newest, supply. Default qrl2 = -transfers, qrl = -newest." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TokensPaginated" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "apiKey": [] } ] } }, "/api/v1/qrl/tokens/{token_id}": { "get": { "tags": [ "Tokens" ], "summary": "Get Token", "description": "Single-token detail.\n\nThe id-format depends on chain (determined by URL prefix):\n - /api/v1/qrl2/tokens/{id} → qrl2; id is the contract address (Q + 40 or 128 hex)\n - /api/v1/qrl/tokens/{id} → qrl; id is the creation tx-hash", "operationId": "get_token_api_v1_qrl_tokens__token_id__get", "parameters": [ { "name": "token_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Token Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TokenDetail" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "apiKey": [] } ] } }, "/api/v1/qrl/tokens/{token_contract}/distribution": { "get": { "tags": [ "Tokens" ], "summary": "Get Token Distribution", "description": "Token holder distribution / concentration stats.\n\nReturns top-10 / top-50 / top-100 cumulative share + HHI\n(Herfindahl-Hirschman Index) over the top-100. Powers a\n\"concentration\" widget on the token-detail page.", "operationId": "get_token_distribution_api_v1_qrl_tokens__token_contract__distribution_get", "parameters": [ { "name": "token_contract", "in": "path", "required": true, "schema": { "type": "string", "title": "Token Contract" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TokenDistribution" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "apiKey": [] } ] } }, "/api/v1/qrl/tokens/{token_contract}/holders": { "get": { "tags": [ "Tokens" ], "summary": "Get Token Holders", "description": "Top holders by balance for a QRL2 QRC-20 token. Zero-address (burn sink)\nis excluded via the underlying `qrl2_token_top_holders` view filter.", "operationId": "get_token_holders_api_v1_qrl_tokens__token_contract__holders_get", "parameters": [ { "name": "token_contract", "in": "path", "required": true, "schema": { "type": "string", "title": "Token Contract" } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "default": 1, "title": "Page" } }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "default": 20, "title": "Page Size" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TokenHoldersList" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "apiKey": [] } ] } }, "/api/v1/qrl/tokens/{token_contract}/transfers": { "get": { "tags": [ "Tokens" ], "summary": "Get Token Transfers", "description": "Decoded transfer events for a QRL2 token. Returns QRC-20/721/1155 transfers\nvia the unified `qrl2_qrc_transfers_all` view.", "operationId": "get_token_transfers_api_v1_qrl_tokens__token_contract__transfers_get", "parameters": [ { "name": "token_contract", "in": "path", "required": true, "schema": { "type": "string", "title": "Token Contract" } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "default": 1, "title": "Page" } }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "default": 20, "title": "Page Size" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TokenTransfersList" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "apiKey": [] } ] } }, "/api/v1/qrl/tokens/{token_contract}/balance/{address}": { "get": { "tags": [ "Tokens" ], "summary": "Get Token Balance", "description": "Balance of a single (token, holder) pair, decimals-corrected for display.", "operationId": "get_token_balance_api_v1_qrl_tokens__token_contract__balance__address__get", "parameters": [ { "name": "token_contract", "in": "path", "required": true, "schema": { "type": "string", "title": "Token Contract" } }, { "name": "address", "in": "path", "required": true, "schema": { "type": "string", "title": "Address" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TokenHolderBalance" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "apiKey": [] } ] } }, "/api/v1/qrl2/wallets/": { "get": { "tags": [ "Wallets" ], "summary": "List Wallets", "description": "Paginated wallet registry. Sentinels excluded by default — set\n`include_sentinel=true` to see the `coinbase` and zero-address rows.", "operationId": "list_wallets_api_v1_qrl2_wallets__get", "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "default": 1, "title": "Page" } }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "default": 20, "title": "Page Size" } }, { "name": "address_type", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter: eoa | contract | validator | qrl_master | qrl_slave | coinbase | zero_address", "title": "Address Type" }, "description": "Filter: eoa | contract | validator | qrl_master | qrl_slave | coinbase | zero_address" }, { "name": "include_sentinel", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Include sentinels (coinbase / zero-address) in results", "default": false, "title": "Include Sentinel" }, "description": "Include sentinels (coinbase / zero-address) in results" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletsPaginated" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "apiKey": [] } ] } }, "/api/v1/qrl2/wallets/classification-distribution": { "get": { "tags": [ "Wallets" ], "summary": "Classification Distribution", "description": "Entity-class breakdown of the wallet population (mig 080) — backs the\n/charts/wallet-types chart. One bucket per class (others / miner /\nminingpool / stakingpool / staker / exchange / contract / foundation /\nburn) with count + share. Empty list if the classification job hasn't\nbeen run on this deploy yet.", "operationId": "classification_distribution_api_v1_qrl2_wallets_classification_distribution_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletClassDistribution" } } } } }, "security": [ { "apiKey": [] } ] } }, "/api/v1/qrl2/wallets/signature-scheme-distribution": { "get": { "tags": [ "Wallets" ], "summary": "Signature Scheme Distribution", "description": "Post-quantum signature-scheme breakdown of the key-holding wallet\npopulation — % wallets and % coins per type. Buckets: XMSS (qrl),\nML-DSA-87 (qrl2 addresses that have signed), and 'unknown' (qrl2\nreceive-only addresses with no observable scheme yet). Sentinels and\ncontracts are excluded. Empty list (graceful) if the source views are\nmissing on this deploy.", "operationId": "signature_scheme_distribution_api_v1_qrl2_wallets_signature_scheme_distribution_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletSchemeDistribution" } } } } }, "security": [ { "apiKey": [] } ] } }, "/api/v1/qrl2/wallets/{address}/summary": { "get": { "tags": [ "Wallets" ], "summary": "Wallet Summary", "description": "Dashboard-widget bundle. Single round-trip for the wallet page header\n(identity + counts + related-address count). For deep lists call the\nsub-endpoints.", "operationId": "wallet_summary_api_v1_qrl2_wallets__address__summary_get", "parameters": [ { "name": "address", "in": "path", "required": true, "schema": { "type": "string", "title": "Address" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletSummary" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "apiKey": [] } ] } }, "/api/v1/qrl2/wallets/{address}/related": { "get": { "tags": [ "Wallets" ], "summary": "Wallet Related", "description": "QRL slave-key sibling set: every address sharing the same master_addr.\nNo-op for QRL2 (XMSS slave-key concept doesn't exist on EVM).", "operationId": "wallet_related_api_v1_qrl2_wallets__address__related_get", "parameters": [ { "name": "address", "in": "path", "required": true, "schema": { "type": "string", "title": "Address" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 500, "minimum": 1, "default": 50, "title": "Limit" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RelatedWalletsList" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "apiKey": [] } ] } }, "/api/v1/qrl2/wallets/{address}/tokens": { "get": { "tags": [ "Wallets" ], "summary": "Wallet Tokens", "description": "QRL2 token-portfolio: every non-zero QRC-20 balance with display values.\nAliased from /addresses/{addr}/tokens for discoverability.", "operationId": "wallet_tokens_api_v1_qrl2_wallets__address__tokens_get", "parameters": [ { "name": "address", "in": "path", "required": true, "schema": { "type": "string", "title": "Address" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletTokensList" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "apiKey": [] } ] } }, "/api/v1/qrl2/wallets/{address}/reputation": { "get": { "tags": [ "Wallets" ], "summary": "Wallet Reputation", "description": "0-100 trust score + signal-flags for an address.\n\nCombines:\n - age (first_seen_at)\n - tx volume / in:out ratio\n - infinite-approval count (qrl2 only)\n - label signals (official / scam)\n - validator status\n\nReturns the underlying `signals` + per-flag `weight` + `message` so the\nUI can render a \"why\" tooltip — the score alone is intentionally\nadvisory, never used to block actions on the chain.", "operationId": "wallet_reputation_api_v1_qrl2_wallets__address__reputation_get", "parameters": [ { "name": "address", "in": "path", "required": true, "schema": { "type": "string", "title": "Address" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletReputation" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "apiKey": [] } ] } }, "/api/v1/qrl2/wallets/{address}": { "get": { "tags": [ "Wallets" ], "summary": "Get Wallet", "description": "Wallet identity. Per Q2 design: thin — does NOT include tokens / txs /\ncontracts inline; client calls dedicated sub-endpoints for those.\nUse /summary if you want the dashboard-bundle.", "operationId": "get_wallet_api_v1_qrl2_wallets__address__get", "parameters": [ { "name": "address", "in": "path", "required": true, "schema": { "type": "string", "title": "Address" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletDetail" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "apiKey": [] } ] } }, "/api/v1/qrl/wallets/": { "get": { "tags": [ "Wallets" ], "summary": "List Wallets", "description": "Paginated wallet registry. Sentinels excluded by default — set\n`include_sentinel=true` to see the `coinbase` and zero-address rows.", "operationId": "list_wallets_api_v1_qrl_wallets__get", "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "default": 1, "title": "Page" } }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "default": 20, "title": "Page Size" } }, { "name": "address_type", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter: eoa | contract | validator | qrl_master | qrl_slave | coinbase | zero_address", "title": "Address Type" }, "description": "Filter: eoa | contract | validator | qrl_master | qrl_slave | coinbase | zero_address" }, { "name": "include_sentinel", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Include sentinels (coinbase / zero-address) in results", "default": false, "title": "Include Sentinel" }, "description": "Include sentinels (coinbase / zero-address) in results" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletsPaginated" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "apiKey": [] } ] } }, "/api/v1/qrl/wallets/classification-distribution": { "get": { "tags": [ "Wallets" ], "summary": "Classification Distribution", "description": "Entity-class breakdown of the wallet population (mig 080) — backs the\n/charts/wallet-types chart. One bucket per class (others / miner /\nminingpool / stakingpool / staker / exchange / contract / foundation /\nburn) with count + share. Empty list if the classification job hasn't\nbeen run on this deploy yet.", "operationId": "classification_distribution_api_v1_qrl_wallets_classification_distribution_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletClassDistribution" } } } } }, "security": [ { "apiKey": [] } ] } }, "/api/v1/qrl/wallets/signature-scheme-distribution": { "get": { "tags": [ "Wallets" ], "summary": "Signature Scheme Distribution", "description": "Post-quantum signature-scheme breakdown of the key-holding wallet\npopulation — % wallets and % coins per type. Buckets: XMSS (qrl),\nML-DSA-87 (qrl2 addresses that have signed), and 'unknown' (qrl2\nreceive-only addresses with no observable scheme yet). Sentinels and\ncontracts are excluded. Empty list (graceful) if the source views are\nmissing on this deploy.", "operationId": "signature_scheme_distribution_api_v1_qrl_wallets_signature_scheme_distribution_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletSchemeDistribution" } } } } }, "security": [ { "apiKey": [] } ] } }, "/api/v1/qrl/wallets/{address}/summary": { "get": { "tags": [ "Wallets" ], "summary": "Wallet Summary", "description": "Dashboard-widget bundle. Single round-trip for the wallet page header\n(identity + counts + related-address count). For deep lists call the\nsub-endpoints.", "operationId": "wallet_summary_api_v1_qrl_wallets__address__summary_get", "parameters": [ { "name": "address", "in": "path", "required": true, "schema": { "type": "string", "title": "Address" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletSummary" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "apiKey": [] } ] } }, "/api/v1/qrl/wallets/{address}/related": { "get": { "tags": [ "Wallets" ], "summary": "Wallet Related", "description": "QRL slave-key sibling set: every address sharing the same master_addr.\nNo-op for QRL2 (XMSS slave-key concept doesn't exist on EVM).", "operationId": "wallet_related_api_v1_qrl_wallets__address__related_get", "parameters": [ { "name": "address", "in": "path", "required": true, "schema": { "type": "string", "title": "Address" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 500, "minimum": 1, "default": 50, "title": "Limit" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RelatedWalletsList" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "apiKey": [] } ] } }, "/api/v1/qrl/wallets/{address}/tokens": { "get": { "tags": [ "Wallets" ], "summary": "Wallet Tokens", "description": "QRL2 token-portfolio: every non-zero QRC-20 balance with display values.\nAliased from /addresses/{addr}/tokens for discoverability.", "operationId": "wallet_tokens_api_v1_qrl_wallets__address__tokens_get", "parameters": [ { "name": "address", "in": "path", "required": true, "schema": { "type": "string", "title": "Address" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletTokensList" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "apiKey": [] } ] } }, "/api/v1/qrl/wallets/{address}/reputation": { "get": { "tags": [ "Wallets" ], "summary": "Wallet Reputation", "description": "0-100 trust score + signal-flags for an address.\n\nCombines:\n - age (first_seen_at)\n - tx volume / in:out ratio\n - infinite-approval count (qrl2 only)\n - label signals (official / scam)\n - validator status\n\nReturns the underlying `signals` + per-flag `weight` + `message` so the\nUI can render a \"why\" tooltip — the score alone is intentionally\nadvisory, never used to block actions on the chain.", "operationId": "wallet_reputation_api_v1_qrl_wallets__address__reputation_get", "parameters": [ { "name": "address", "in": "path", "required": true, "schema": { "type": "string", "title": "Address" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletReputation" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "apiKey": [] } ] } }, "/api/v1/qrl/wallets/{address}": { "get": { "tags": [ "Wallets" ], "summary": "Get Wallet", "description": "Wallet identity. Per Q2 design: thin — does NOT include tokens / txs /\ncontracts inline; client calls dedicated sub-endpoints for those.\nUse /summary if you want the dashboard-bundle.", "operationId": "get_wallet_api_v1_qrl_wallets__address__get", "parameters": [ { "name": "address", "in": "path", "required": true, "schema": { "type": "string", "title": "Address" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletDetail" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "apiKey": [] } ] } }, "/api/v1/qrl2/names/directory": { "get": { "tags": [ "Names" ], "summary": "Label Directory", "description": "All curated Quantascan labels for the chain — fetch once, join locally.", "operationId": "label_directory_api_v1_qrl2_names_directory_get", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 10000, "minimum": 1, "default": 2000, "title": "Limit" } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "default": 0, "title": "Offset" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LabelDirectory" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "apiKey": [] } ] } }, "/api/v1/qrl2/names/resolve": { "post": { "tags": [ "Names" ], "summary": "Resolve Names", "description": "Resolve display names for many addresses in one call.\n\nOne request = one metered API call, so a view with thousands of wallets\ncosts a handful of calls rather than thousands.", "operationId": "resolve_names_api_v1_qrl2_names_resolve_post", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "title": "Body", "examples": [ { "addresses": [ "Qc0e6dd0e844e0048dcb0bd3fdcc44a970beca38d" ] } ] } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddressNamesList" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "apiKey": [] } ] } }, "/api/v1/qrl2/names/{address}": { "get": { "tags": [ "Names" ], "summary": "Name For Address", "description": "The display name for one address.\n\nAlways returns a name, also for an address we have never indexed: the\nnickname depends on the address alone.", "operationId": "name_for_address_api_v1_qrl2_names__address__get", "parameters": [ { "name": "address", "in": "path", "required": true, "schema": { "type": "string", "title": "Address" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddressName" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "apiKey": [] } ] } }, "/api/v1/qrl/names/directory": { "get": { "tags": [ "Names" ], "summary": "Label Directory", "description": "All curated Quantascan labels for the chain — fetch once, join locally.", "operationId": "label_directory_api_v1_qrl_names_directory_get", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 10000, "minimum": 1, "default": 2000, "title": "Limit" } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "default": 0, "title": "Offset" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LabelDirectory" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "apiKey": [] } ] } }, "/api/v1/qrl/names/resolve": { "post": { "tags": [ "Names" ], "summary": "Resolve Names", "description": "Resolve display names for many addresses in one call.\n\nOne request = one metered API call, so a view with thousands of wallets\ncosts a handful of calls rather than thousands.", "operationId": "resolve_names_api_v1_qrl_names_resolve_post", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "title": "Body", "examples": [ { "addresses": [ "Qc0e6dd0e844e0048dcb0bd3fdcc44a970beca38d" ] } ] } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddressNamesList" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "apiKey": [] } ] } }, "/api/v1/qrl/names/{address}": { "get": { "tags": [ "Names" ], "summary": "Name For Address", "description": "The display name for one address.\n\nAlways returns a name, also for an address we have never indexed: the\nnickname depends on the address alone.", "operationId": "name_for_address_api_v1_qrl_names__address__get", "parameters": [ { "name": "address", "in": "path", "required": true, "schema": { "type": "string", "title": "Address" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddressName" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "apiKey": [] } ] } }, "/api/v1/qrl2/addresses/{address}/export.csv": { "get": { "tags": [ "Addresses" ], "summary": "Export an address's history as CSV (tax / accounting)", "description": "Streams the address's history for one UTC date range as CSV: `date_utc, block, tx_hash, direction, from, to, value, fee, token_symbol, tx_type, status, price_usd, value_usd` (+ type-specific columns). Values are decimals in QRL (qrl) or Quanta (qrl2); a fee appears only on the paying side, once per transaction. Max 366 days and 100,000 rows per file (422 when exceeded — narrow the range). Prices are daily USD closes where stored, otherwise empty (always empty for QRL 2.0 until it has a market). `type=withdrawals` is QRL 2.0 only.", "operationId": "export_address_csv_api_v1_qrl2_addresses__address__export_csv_get", "parameters": [ { "name": "address", "in": "path", "required": true, "schema": { "type": "string", "title": "Address" } }, { "name": "from", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Start date (UTC, inclusive), YYYY-MM-DD. Default: 365 days before `to`.", "title": "From" }, "description": "Start date (UTC, inclusive), YYYY-MM-DD. Default: 365 days before `to`." }, { "name": "to", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "End date (UTC, inclusive), YYYY-MM-DD. Default: today.", "title": "To" }, "description": "End date (UTC, inclusive), YYYY-MM-DD. Default: today." }, { "name": "type", "in": "query", "required": false, "schema": { "type": "string", "description": "transactions | internal | tokens | withdrawals", "default": "transactions", "title": "Type" }, "description": "transactions | internal | tokens | withdrawals" } ], "responses": { "200": { "description": "CSV file", "content": { "text/csv": {} } }, "400": { "description": "Invalid address, date or type for this chain." }, "422": { "description": "Range longer than 366 days or more than 100,000 rows." }, "429": { "description": "Too many exports from this address (no API key)." } }, "security": [ { "apiKey": [] } ] } }, "/api/v1/qrl/addresses/{address}/export.csv": { "get": { "tags": [ "Addresses" ], "summary": "Export an address's history as CSV (tax / accounting)", "description": "Streams the address's history for one UTC date range as CSV: `date_utc, block, tx_hash, direction, from, to, value, fee, token_symbol, tx_type, status, price_usd, value_usd` (+ type-specific columns). Values are decimals in QRL (qrl) or Quanta (qrl2); a fee appears only on the paying side, once per transaction. Max 366 days and 100,000 rows per file (422 when exceeded — narrow the range). Prices are daily USD closes where stored, otherwise empty (always empty for QRL 2.0 until it has a market). `type=withdrawals` is QRL 2.0 only.", "operationId": "export_address_csv_api_v1_qrl_addresses__address__export_csv_get", "parameters": [ { "name": "address", "in": "path", "required": true, "schema": { "type": "string", "title": "Address" } }, { "name": "from", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Start date (UTC, inclusive), YYYY-MM-DD. Default: 365 days before `to`.", "title": "From" }, "description": "Start date (UTC, inclusive), YYYY-MM-DD. Default: 365 days before `to`." }, { "name": "to", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "End date (UTC, inclusive), YYYY-MM-DD. Default: today.", "title": "To" }, "description": "End date (UTC, inclusive), YYYY-MM-DD. Default: today." }, { "name": "type", "in": "query", "required": false, "schema": { "type": "string", "description": "transactions | internal | tokens | withdrawals", "default": "transactions", "title": "Type" }, "description": "transactions | internal | tokens | withdrawals" } ], "responses": { "200": { "description": "CSV file", "content": { "text/csv": {} } }, "400": { "description": "Invalid address, date or type for this chain." }, "422": { "description": "Range longer than 366 days or more than 100,000 rows." }, "429": { "description": "Too many exports from this address (no API key)." } }, "security": [ { "apiKey": [] } ] } }, "/api/v1/qrl2/addresses/balances": { "post": { "tags": [ "Addresses" ], "summary": "Current native balances for up to 100 addresses", "description": "Current balance, transaction count and first/last activity for up to\n100 addresses of this chain in ONE call (Etherscan `balancemulti` allows\n20). Addresses are validated per chain — QRL 2.0: `Q` + 40 hex (20-byte)\nor `Q` + 128 hex (64-byte); QRL legacy: `Q` + 78 hex — and an address of the other chain is rejected, not\ntranslated. An address with no indexed activity returns `balance: \"0\"`\nand `found: false`. Items come back in request order, duplicates once.", "operationId": "post_batch_balances_api_v1_qrl2_addresses_balances_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchBalancesRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchBalancesResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "apiKey": [] } ] } }, "/api/v1/qrl2/addresses/{address}/balance": { "get": { "tags": [ "Addresses" ], "summary": "Native balance at a block or a point in time", "description": "Exact native balance of an address after a given block (or at a given\ntime) — Etherscan's Pro-only `balancehistory`, on both chains.\n\nSame definition as the current balance on `/addresses/{address}`: it\nincludes fees, validator withdrawals (QRL 2.0), internal contract\ntransfers and QRL multisig executions, contract-creation value and the\ngenesis allocation, so at the tip it equals that endpoint's `balance`.\n`components` shows the received / sent / fees totals it was built from.\n\nOmit both parameters for the balance at the indexed tip. A block or time\nbeyond the indexed tip → 422 `beyond_indexed_tip` (retry later). In the\nrare case block timestamps around the target day are out of height order\nthe answer cannot be guaranteed exact and the endpoint returns 422\n`balance_inexact` instead of an approximation.", "operationId": "get_balance_at_api_v1_qrl2_addresses__address__balance_get", "parameters": [ { "name": "address", "in": "path", "required": true, "schema": { "type": "string", "description": "Address of this chain (case-insensitive).", "title": "Address" }, "description": "Address of this chain (case-insensitive)." }, { "name": "block", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "minimum": 0 }, { "type": "null" } ], "description": "Block height. The balance is the state AFTER this block.", "title": "Block" }, "description": "Block height. The balance is the state AFTER this block." }, { "name": "timestamp", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "minimum": 0 }, { "type": "null" } ], "description": "Unix seconds. Resolved to the latest indexed block with a timestamp at or before it. Mutually exclusive with `block`.", "title": "Timestamp" }, "description": "Unix seconds. Resolved to the latest indexed block with a timestamp at or before it. Mutually exclusive with `block`." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HistoricalBalanceResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "apiKey": [] } ] } }, "/api/v1/qrl/addresses/balances": { "post": { "tags": [ "Addresses" ], "summary": "Current native balances for up to 100 addresses", "description": "Current balance, transaction count and first/last activity for up to\n100 addresses of this chain in ONE call (Etherscan `balancemulti` allows\n20). Addresses are validated per chain — QRL 2.0: `Q` + 40 hex (20-byte)\nor `Q` + 128 hex (64-byte); QRL legacy: `Q` + 78 hex — and an address of the other chain is rejected, not\ntranslated. An address with no indexed activity returns `balance: \"0\"`\nand `found: false`. Items come back in request order, duplicates once.", "operationId": "post_batch_balances_api_v1_qrl_addresses_balances_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchBalancesRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchBalancesResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "apiKey": [] } ] } }, "/api/v1/qrl/addresses/{address}/balance": { "get": { "tags": [ "Addresses" ], "summary": "Native balance at a block or a point in time", "description": "Exact native balance of an address after a given block (or at a given\ntime) — Etherscan's Pro-only `balancehistory`, on both chains.\n\nSame definition as the current balance on `/addresses/{address}`: it\nincludes fees, validator withdrawals (QRL 2.0), internal contract\ntransfers and QRL multisig executions, contract-creation value and the\ngenesis allocation, so at the tip it equals that endpoint's `balance`.\n`components` shows the received / sent / fees totals it was built from.\n\nOmit both parameters for the balance at the indexed tip. A block or time\nbeyond the indexed tip → 422 `beyond_indexed_tip` (retry later). In the\nrare case block timestamps around the target day are out of height order\nthe answer cannot be guaranteed exact and the endpoint returns 422\n`balance_inexact` instead of an approximation.", "operationId": "get_balance_at_api_v1_qrl_addresses__address__balance_get", "parameters": [ { "name": "address", "in": "path", "required": true, "schema": { "type": "string", "description": "Address of this chain (case-insensitive).", "title": "Address" }, "description": "Address of this chain (case-insensitive)." }, { "name": "block", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "minimum": 0 }, { "type": "null" } ], "description": "Block height. The balance is the state AFTER this block.", "title": "Block" }, "description": "Block height. The balance is the state AFTER this block." }, { "name": "timestamp", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "minimum": 0 }, { "type": "null" } ], "description": "Unix seconds. Resolved to the latest indexed block with a timestamp at or before it. Mutually exclusive with `block`.", "title": "Timestamp" }, "description": "Unix seconds. Resolved to the latest indexed block with a timestamp at or before it. Mutually exclusive with `block`." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HistoricalBalanceResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "apiKey": [] } ] } }, "/api/v1/qrl2/validators/top": { "get": { "tags": [ "Validators" ], "summary": "Top Validators", "description": "Top validators ranked by lifetime withdrawn rewards.", "operationId": "top_validators_api_v1_qrl2_validators_top_get", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 1000, "minimum": 1, "default": 100, "title": "Limit" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TopValidatorsList" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "apiKey": [] } ] } }, "/api/v1/qrl2/validators/stake-concentration": { "get": { "tags": [ "Validators" ], "summary": "Stake Concentration", "description": "Stake-distribution KPI bundle for the /validators hub.\n\nReturns active validator count, total effective balance (gwei + QRL2),\nand the top-10 concentration ratio (0..1). Empty/null-filled on a\npre-mig-035 deploy (gracefully degraded).", "operationId": "stake_concentration_api_v1_qrl2_validators_stake_concentration_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StakeConcentrationResponse" } } } } }, "security": [ { "apiKey": [] } ] } }, "/api/v1/qrl2/validators/status-breakdown": { "get": { "tags": [ "Validators" ], "summary": "Status Breakdown", "description": "Validator-count breakdown by lifecycle bucket for the /validators hub\nstrip: entering (activation queue), active, exiting (leaving the active\nset) and exited. More meaningful than a static stake total — it shows\nchurn. Zero-filled gracefully on a pre-mig-035 deploy or before the beacon\nindexer snapshots the registry.", "operationId": "status_breakdown_api_v1_qrl2_validators_status_breakdown_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidatorStatusBreakdown" } } } } }, "security": [ { "apiKey": [] } ] } }, "/api/v1/qrl2/validators/": { "get": { "tags": [ "Validators" ], "summary": "List Validators", "description": "Paginated list of QRL2 validators with consensus-layer columns\njoined in (status, effective_balance, blocks_proposed_count, slashed).\n\nWave 6: `?sort_by=` + `?sort_dir=` → `?sort=field` / `?sort=-field`\n(D5). The validator registry is a stable Gold projection, so we keep\npage/page_size offset pagination (D1).", "operationId": "list_validators_api_v1_qrl2_validators__get", "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "default": 1, "title": "Page" } }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "default": 20, "title": "Page Size" } }, { "name": "status", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter to one validator-lifecycle state (e.g. active_ongoing, exited_slashed). Accepts any of the 9 spec states.", "title": "Status" }, "description": "Filter to one validator-lifecycle state (e.g. active_ongoing, exited_slashed). Accepts any of the 9 spec states." }, { "name": "sort", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Sort spec: '' (asc) or '-' (desc). Allowed fields: index, balance, proposals, withdrawn, activity. Default `index`.", "default": "index", "title": "Sort" }, "description": "Sort spec: '' (asc) or '-' (desc). Allowed fields: index, balance, proposals, withdrawn, activity. Default `index`." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidatorsPaginated" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "apiKey": [] } ] } }, "/api/v1/qrl2/validators/{validator_index}/performance": { "get": { "tags": [ "Validators" ], "summary": "Validator Performance", "description": "Combined execution + consensus bundle for the validator-detail page.\n\nAlways returns the execution side (withdrawals from EIP-4895). The\n`consensus` field is populated only when migration 035 is applied AND\n`ETL_INDEX_BEACON=1` has been running long enough to capture this\nvalidator (proposal or registry snapshot). Returns 404 only when both\nsides are empty (validator unknown to us).", "operationId": "validator_performance_api_v1_qrl2_validators__validator_index__performance_get", "parameters": [ { "name": "validator_index", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 0, "title": "Validator Index" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidatorFullPerformance" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "apiKey": [] } ] } }, "/api/v1/qrl2/validators/{validator_index}/income": { "get": { "tags": [ "Validators" ], "summary": "Validator Income", "description": "Per-day income timeline for one validator: proposed blocks +\nwithdrawal payouts (in planck). Powers a \"validator income chart\" on\nthe validator detail page.\n\nWave 6: `?days=N` → `?window=DURATION` (D4).\nEmpty `items` when beacon indexer hasn't run (graceful — no 500).", "operationId": "validator_income_api_v1_qrl2_validators__validator_index__income_get", "parameters": [ { "name": "validator_index", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 0, "title": "Validator Index" } }, { "name": "window", "in": "query", "required": false, "schema": { "type": "string", "description": "Look-back window for validator income timeline. Default 90d.", "default": "90d", "title": "Window" }, "description": "Look-back window for validator income timeline. Default 90d." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenericListResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "apiKey": [] } ] } }, "/api/v1/qrl2/validators/{validator_index}/withdrawals": { "get": { "tags": [ "Validators" ], "summary": "Per-validator withdrawal history (UI label: \"Validator Rewards\")", "description": "EIP-4895 withdrawal history for a single validator. Public-name mapping: surfaced as \"Validator Rewards\" in the UI (`/validator/{idx}` and `/rewards`).", "operationId": "validator_withdrawals_api_v1_qrl2_validators__validator_index__withdrawals_get", "parameters": [ { "name": "validator_index", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 0, "title": "Validator Index" } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "default": 1, "title": "Page" } }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 200, "minimum": 1, "default": 50, "title": "Page Size" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidatorWithdrawalsList" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "apiKey": [] } ] } }, "/api/v1/qrl2/validators/{validator_index}": { "get": { "tags": [ "Validators" ], "summary": "Get Validator", "description": "Single validator detail: rewards totals, first/last withdrawal,\nlatest recipient address.", "operationId": "get_validator_api_v1_qrl2_validators__validator_index__get", "parameters": [ { "name": "validator_index", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 0, "title": "Validator Index" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidatorDetail" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "apiKey": [] } ] } }, "/api/v1/qrl2/beacon/summary": { "get": { "tags": [ "Beacon" ], "summary": "Consensus-layer summary (UI label: \"Beacon Chain · Network status\")", "description": "Headline metrics for the consensus layer. Public-name mapping: the Quantascan UI surfaces this widget as \"Network status\" on the `/beacon` hub. API uses the spec-aligned `beacon` namespace.", "operationId": "beacon_summary_api_v1_qrl2_beacon_summary_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BeaconSummary" } } } } }, "security": [ { "apiKey": [] } ] } }, "/api/v1/qrl2/beacon/blocks": { "get": { "tags": [ "Beacon" ], "summary": "List beacon blocks (UI label: \"Beacon Chain · Blocks\")", "description": "Latest beacon (consensus-layer) blocks, newest first. Public-name mapping: surfaced under `/beacon/blocks` in the UI. API uses the spec-aligned `beacon/blocks` path.", "operationId": "list_beacon_blocks_api_v1_qrl2_beacon_blocks_get", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 200, "minimum": 1, "default": 20, "title": "Limit" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Opaque pagination token from a previous response's `next_cursor`. Omit to start at the chain head (newest).", "title": "Cursor" }, "description": "Opaque pagination token from a previous response's `next_cursor`. Omit to start at the chain head (newest)." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BeaconBlocksList" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "apiKey": [] } ] } }, "/api/v1/qrl2/beacon/epochs": { "get": { "tags": [ "Beacon" ], "summary": "List consensus epochs (UI: \"Epochs\" page)", "description": "Recent QRL 2.0 beacon-chain epochs, newest-first.\n\nEach epoch is `SLOTS_PER_EPOCH × SECONDS_PER_SLOT` long — for QRL2\nthat's 128 × 60s = 2h 8min (NOT Ethereum's 6m 24s). Rows are\naggregated from `etl_silver.qrl2_beacon_blocks` at query-time; when\nthat table is empty we still emit synthetic epoch entries computed\nfrom `genesis_time` so the UI has something to render.\n\nWave 5: `?before_epoch=N` → `?cursor=...` (opaque token).", "operationId": "list_beacon_epochs_api_v1_qrl2_beacon_epochs_get", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 200, "minimum": 1, "default": 25, "title": "Limit" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Opaque pagination token from a previous response's `next_cursor`. Omit to start at the current epoch.", "title": "Cursor" }, "description": "Opaque pagination token from a previous response's `next_cursor`. Omit to start at the current epoch." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BeaconEpochsList" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "apiKey": [] } ] } }, "/api/v1/qrl2/beacon/epochs/{epoch}": { "get": { "tags": [ "Beacon" ], "summary": "Single epoch detail (UI: `/epoch/{epoch}`)", "description": "Single epoch detail: per-slot grid (128 slots) + aggregated counts.\nReturns 404 for negative epoch numbers, otherwise always returns a\npayload (with empty `blocks` array when the indexer hasn't caught up).", "operationId": "get_beacon_epoch_api_v1_qrl2_beacon_epochs__epoch__get", "parameters": [ { "name": "epoch", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 0, "title": "Epoch" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BeaconEpochDetail" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "apiKey": [] } ] } }, "/api/v1/qrl2/beacon/blocks/{slot}": { "get": { "tags": [ "Beacon" ], "summary": "Single beacon block by slot (UI: `/beacon/blocks/{slot}`)", "description": "Single beacon block by slot. 404 when the slot is empty\n(legitimately — beacon-chain slots can be skipped) OR when the\nindexer hasn't reached this slot yet.", "operationId": "get_beacon_block_api_v1_qrl2_beacon_blocks__slot__get", "parameters": [ { "name": "slot", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 0, "title": "Slot" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BeaconBlock" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "apiKey": [] } ] } }, "/api/v1/qrl2/beacon/slashings": { "get": { "tags": [ "Beacon" ], "summary": "List validator slashings (UI label: \"Validator Penalties\")", "description": "Slashings newest-first, with optional type filter. Public-name mapping: the Quantascan UI labels these \"Validator Penalties\" on `/penalties`. The API uses the spec-aligned `slashings` term (matches the Beacon API `/eth/v1/beacon/pool/{proposer,attester}_slashings`).", "operationId": "list_beacon_slashings_api_v1_qrl2_beacon_slashings_get", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 200, "minimum": 1, "default": 50, "title": "Limit" } }, { "name": "slashing_type", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "pattern": "^(proposer|attester)$" }, { "type": "null" } ], "description": "Optional filter: 'proposer' or 'attester'", "title": "Slashing Type" }, "description": "Optional filter: 'proposer' or 'attester'" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BeaconSlashingsList" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "apiKey": [] } ] } }, "/api/v1/qrl2/beacon/slashings/daily": { "get": { "tags": [ "Beacon" ], "summary": "Slashings histogram per day (UI: penalties bar chart)", "description": "Daily slashings histogram split proposer vs attester. Powers the\n\"Slashings over time\" bar chart on /penalties. Empty buckets included\nso the UI gets a continuous timeline.\n\nWave 5: `?days=N` → `?window=30d` (D4).", "operationId": "slashings_daily_api_v1_qrl2_beacon_slashings_daily_get", "parameters": [ { "name": "window", "in": "query", "required": false, "schema": { "type": "string", "description": "Look-back window for the slashings histogram. Default 30d.", "default": "30d", "title": "Window" }, "description": "Look-back window for the slashings histogram. Default 30d." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BeaconSlashingsDaily" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "apiKey": [] } ] } }, "/api/v1/qrl2/beacon/attestation/daily": { "get": { "tags": [ "Beacon" ], "summary": "Daily attestation participation rate (UI: validator-health chart)", "description": "Network-wide daily attestation participation rate (included/expected\nacross all validators). A liveness/health metric — distinct from the\nvalidator registry/count. Powers /charts/attestation-rate. Empty list\nwhen the beacon attestation indexer hasn't run on this deploy.", "operationId": "attestation_daily_api_v1_qrl2_beacon_attestation_daily_get", "parameters": [ { "name": "window", "in": "query", "required": false, "schema": { "type": "string", "description": "Look-back window for the attestation participation rate. Default 90d.", "default": "90d", "title": "Window" }, "description": "Look-back window for the attestation participation rate. Default 90d." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BeaconAttestationDaily" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "apiKey": [] } ] } }, "/api/v1/qrl2/beacon/validators/{validator_index}": { "get": { "tags": [ "Beacon" ], "summary": "Get Beacon Validator", "description": "Latest registry snapshot for a validator: status, pubkey,\neffective_balance, activation/exit epochs, slashed flag. Distinct\nfrom `/validators/{idx}/performance` which is the combined\nexecution+consensus rollup; this is the raw registry row.", "operationId": "get_beacon_validator_api_v1_qrl2_beacon_validators__validator_index__get", "parameters": [ { "name": "validator_index", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 0, "title": "Validator Index" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BeaconValidatorRegistry" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "apiKey": [] } ] } }, "/api/v1/qrl2/contracts/by-deployer/{deployer}": { "get": { "tags": [ "Contracts" ], "summary": "List By Deployer", "description": "All contracts ever deployed by a given QRL2 EOA. Useful for proving\nauthorship: \"wallet X deployed these N tokens\".", "operationId": "list_by_deployer_api_v1_qrl2_contracts_by_deployer__deployer__get", "parameters": [ { "name": "deployer", "in": "path", "required": true, "schema": { "type": "string", "title": "Deployer" } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "default": 1, "title": "Page" } }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "default": 50, "title": "Page Size" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContractsPaginated" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "apiKey": [] } ] } }, "/api/v1/qrl2/contracts/stats/summary": { "get": { "tags": [ "Contracts" ], "summary": "Contracts Summary", "description": "KPI bundle for the /smart-contracts hub hero strip — 4 counts:\ntotal_deployed, deployed_24h, active_24h, token_contracts.\n\nServer-side cached (repo `@cached(ttl=60)`) so N concurrent hero loads\ncollapse to one ClickHouse query per minute; the response also carries a\nmatching Cache-Control so browser/CDN avoid re-fetching within the window.", "operationId": "contracts_summary_api_v1_qrl2_contracts_stats_summary_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContractsSummary" } } } } }, "security": [ { "apiKey": [] } ] } }, "/api/v1/qrl2/contracts/": { "get": { "tags": [ "Contracts" ], "summary": "List Contracts", "description": "Paginated QRL2 contract list with verification + token-metadata +\n24h event-count joined in.\n\nWave 6: `?sort_by=` → `?sort=` (D5). The four sort keys (newest,\noldest, active, verified) already encode their preferred direction\nat the repo layer; the `-` prefix is accepted for compatibility but\nsemantically redundant.\n\nStatus filter:\n - all (default) — every indexed contract\n - verified — match_grade != 'unverified'\n - unverified — no verification submitted (yet)\n - token — implements QRC-20 / QRC-721 / QRC-1155 interface\n - recent — deployed in last 24h", "operationId": "list_contracts_api_v1_qrl2_contracts__get", "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "default": 1, "title": "Page" } }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "default": 20, "title": "Page Size" } }, { "name": "status", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "all (default) | verified | unverified | token | recent (24h deploys). Filters layer on top of pagination.", "title": "Status" }, "description": "all (default) | verified | unverified | token | recent (24h deploys). Filters layer on top of pagination." }, { "name": "sort", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Sort spec. Allowed: newest (default), oldest, active, verified, txns. `-` prefix is accepted for compatibility but each key already encodes its preferred direction.", "default": "newest", "title": "Sort" }, "description": "Sort spec. Allowed: newest (default), oldest, active, verified, txns. `-` prefix is accepted for compatibility but each key already encodes its preferred direction." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContractsPaginated" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "apiKey": [] } ] } }, "/api/v1/qrl2/contracts/recent": { "get": { "tags": [ "Contracts" ], "summary": "List Recent Contracts", "description": "Recently-deployed contracts with inline token-metadata.\n\nSame shape as `/contracts/` but filtered to deployments within the\nlook-back window AND joined with token-metadata so the frontend can\nshow \"is this a QRC-20 / -721 / -1155 launch?\" without a second call.\n\nWave 6: `?hours=N` → `?window=24h` (D4 duration).\n\nPowers a \"New contracts (24h)\" homepage widget.", "operationId": "list_recent_contracts_api_v1_qrl2_contracts_recent_get", "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "default": 1, "title": "Page" } }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "default": 20, "title": "Page Size" } }, { "name": "window", "in": "query", "required": false, "schema": { "type": "string", "description": "Look-back window for the /contracts/recent feed. Default 24h. Examples: 1h, 24h, 7d, 30d.", "default": "24h", "title": "Window" }, "description": "Look-back window for the /contracts/recent feed. Default 24h. Examples: 1h, 24h, 7d, 30d." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContractsPaginated" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "apiKey": [] } ] } }, "/api/v1/qrl2/contracts/{address}/logs": { "get": { "tags": [ "Contracts" ], "summary": "Get Contract Logs", "description": "Raw events emitted BY this contract. Decoded transfer events are\navailable via /tokens/{address}/transfers — this endpoint is the\n\"show me everything, decoded or not\" escape hatch.", "operationId": "get_contract_logs_api_v1_qrl2_contracts__address__logs_get", "parameters": [ { "name": "address", "in": "path", "required": true, "schema": { "type": "string", "title": "Address" } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "default": 1, "title": "Page" } }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "default": 20, "title": "Page Size" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContractLogsList" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "apiKey": [] } ] } }, "/api/v1/qrl2/contracts/{address}": { "get": { "tags": [ "Contracts" ], "summary": "Get Contract", "description": "Single contract detail. Returns deployment metadata + (if available)\ntoken metadata for QRC-20/721/1155 contracts.", "operationId": "get_contract_api_v1_qrl2_contracts__address__get", "parameters": [ { "name": "address", "in": "path", "required": true, "schema": { "type": "string", "title": "Address" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContractDetail" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "apiKey": [] } ] } }, "/api/v1/qrl2/contracts/{address}/verify": { "post": { "tags": [ "Contracts" ], "summary": "Submit Hyperion source for verification", "description": "Queue a verification job. Returns 202 with `job_id` you can poll at\n`GET /verify/{job_id}`. Live progress is also pushed via the WS channel\n`verify:{address}:{job_id}` (subscribe at `/api/v1/ws/live`).\n\nPer-IP rate limit: 5/min dedicated limit on top of the global one (a\nsubmit triggers a sandboxed compile job, not a cheap read). Per-address\nsingle-flight: a second submit while one is in-flight returns 409 with\nthe existing job_id so callers poll the live job instead of duplicating\nwork.", "operationId": "submit_verification_api_v1_qrl2_contracts__address__verify_post", "parameters": [ { "name": "address", "in": "path", "required": true, "schema": { "type": "string", "title": "Address" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerifyRequest" } } } }, "responses": { "202": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerifyJobCreated" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "apiKey": [] } ] } }, "/api/v1/qrl2/contracts/{address}/verify/{job_id}": { "get": { "tags": [ "Contracts" ], "summary": "Poll verification status", "description": "Latest audit-log + (if completed) the match-grade. Polling-friendly:\nthe response is cheap to compute. Prefer WebSocket subscription for\nlive progress; this endpoint is the fallback for clients without WS.", "operationId": "get_verification_status_api_v1_qrl2_contracts__address__verify__job_id__get", "parameters": [ { "name": "address", "in": "path", "required": true, "schema": { "type": "string", "title": "Address" } }, { "name": "job_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Job Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerifyJobStatus" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "apiKey": [] } ] } }, "/api/v1/qrl2/contracts/{address}/source": { "get": { "tags": [ "Contracts" ], "summary": "Verified source + ABI + metadata for a contract", "description": "The full verified payload — source files, ABI, compiler settings,\nmatch grade, optional metadata. 404 if the address has never been\nverified.", "operationId": "get_contract_source_api_v1_qrl2_contracts__address__source_get", "parameters": [ { "name": "address", "in": "path", "required": true, "schema": { "type": "string", "title": "Address" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContractSource" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "apiKey": [] } ] } }, "/api/v1/qrl2/contracts/{address}/abi": { "get": { "tags": [ "Contracts" ], "summary": "ABI-only (lighter than /source)", "description": "Just the ABI + verification provenance — for tooling that doesn't\nneed the source body (wallet `eth_call` builders, type-codegen, etc.).", "operationId": "get_contract_abi_api_v1_qrl2_contracts__address__abi_get", "parameters": [ { "name": "address", "in": "path", "required": true, "schema": { "type": "string", "title": "Address" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContractAbi" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "apiKey": [] } ] } }, "/api/v1/qrl2/contracts/{address}/clones": { "get": { "tags": [ "Contracts" ], "summary": "Other contracts with the same on-chain bytecode_hash", "description": "All addresses (besides this one) sharing the same `bytecode_hash`.\nUse-case: notice that 20 other contracts run the same bytecode, only\none is verified — auto-suggest verification for the rest (admin-only).", "operationId": "get_contract_clones_api_v1_qrl2_contracts__address__clones_get", "parameters": [ { "name": "address", "in": "path", "required": true, "schema": { "type": "string", "title": "Address" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Pass `next_cursor` from a previous page.", "title": "Cursor" }, "description": "Pass `next_cursor` from a previous page." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "default": 20, "title": "Limit" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContractClones" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "apiKey": [] } ] } }, "/api/v1/qrl2/contracts/{address}/call": { "post": { "tags": [ "Contracts" ], "summary": "Proxy qrl_call for a verified view/pure function", "description": "Read-only contract call. Requires that the contract has been\nsource-verified (so we have an ABI to gate against), and that the\nnamed function is `view` or `pure`. State-changing functions are\nrefused — the Write tab handles those.", "operationId": "call_contract_api_v1_qrl2_contracts__address__call_post", "parameters": [ { "name": "address", "in": "path", "required": true, "schema": { "type": "string", "title": "Address" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContractCallRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContractCallResult" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "apiKey": [] } ] } }, "/api/v1/qrl2/contracts/{address}/badge": { "get": { "tags": [ "Contracts" ], "summary": "Shareable SVG badge for GitHub READMEs ('Verify on Quantascan')", "description": "Returns an SVG badge — meant to be embedded in a token-issuer's\nGitHub README. Renders 'source verified' (cyan/blue) or 'unverified'\n(gray) based on the most recent verification row.\n\nCached publicly for an hour; clients can append a query-string nonce\nto bust the cache when a freshly-verified contract should show the\nnew state immediately.", "operationId": "get_contract_badge_api_v1_qrl2_contracts__address__badge_get", "parameters": [ { "name": "address", "in": "path", "required": true, "schema": { "type": "string", "title": "Address" } }, { "name": "style", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^(flat|for-the-badge)$", "description": "Badge layout.", "default": "flat", "title": "Style" }, "description": "Badge layout." } ], "responses": { "200": { "description": "SVG badge reflecting current verification state.", "content": { "image/svg+xml": {} } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "apiKey": [] } ] } }, "/api/v1/qrl2/contracts/{address}/verify-hint": { "get": { "tags": [ "Contracts" ], "summary": "Hints to pre-fill the verify form (compiler version, metadata hash)", "description": "Fetches on-chain runtime bytecode via `qrl_getCode` and inspects\nthe CBOR-tail. Returns a hint payload the verify-form uses to pre-fill\ncompiler-version, surface the embedded metadata-IPFS hash, and warn\nwhen an address has no deployed code.\n\nCached briefly on the client side (revalidate=60 on the verify-page).", "operationId": "get_verify_hint_api_v1_qrl2_contracts__address__verify_hint_get", "parameters": [ { "name": "address", "in": "path", "required": true, "schema": { "type": "string", "title": "Address" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "apiKey": [] } ] } }, "/api/v1/qrl2/fees/burned/daily": { "get": { "tags": [ "Fees" ], "summary": "Burn Daily", "description": "Per-day EIP-1559 burn for the \"supply-deflation\" line on the\nQRL2 dashboard.\n\nWave 6: `?days=N` → `?window=30d` (D4).", "operationId": "burn_daily_api_v1_qrl2_fees_burned_daily_get", "parameters": [ { "name": "window", "in": "query", "required": false, "schema": { "type": "string", "description": "Look-back window for daily EIP-1559 burn. Default 30d.", "default": "30d", "title": "Window" }, "description": "Look-back window for daily EIP-1559 burn. Default 30d." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FeeBurnDailyList" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "apiKey": [] } ] } }, "/api/v1/qrl2/fees/burned/summary": { "get": { "tags": [ "Fees" ], "summary": "Burn Summary", "description": "All-time burn totals + 24h/7d/30d rolling windows in one response.", "operationId": "burn_summary_api_v1_qrl2_fees_burned_summary_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FeeBurnSummary" } } } } }, "security": [ { "apiKey": [] } ] } }, "/api/v1/qrl2/nft/top-mints": { "get": { "tags": [ "NFT" ], "summary": "List Top Mints", "description": "Top NFT collections by mint count in the look-back window.\n\nA mint is a QRC-721 / QRC-1155 / QRC-1155-batch Transfer event where\n`from_addr` is the zero address. We aggregate by `token_contract` and\njoin contract-level metadata (symbol/name) so the frontend can render\nthe leaderboard without N+1 fetches.\n\nWave 4: `?window_hours=24` → `?window=24h` (D4 duration). The SQL\nlayer still operates on integer hours, so we convert at the edge.\n\nQRL Legacy has no smart-contract NFTs, so this endpoint is qrl2-only\nby virtue of the underlying view (mounted only under /api/v1/qrl2/nft/).", "operationId": "list_top_mints_api_v1_qrl2_nft_top_mints_get", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 50, "minimum": 1, "description": "Top-N collections to return", "default": 10, "title": "Limit" }, "description": "Top-N collections to return" }, { "name": "window", "in": "query", "required": false, "schema": { "type": "string", "description": "Sliding window for the top-mints leaderboard (D4 duration). Default 24h. Examples: 1h, 24h, 7d, 30d.", "default": "24h", "title": "Window" }, "description": "Sliding window for the top-mints leaderboard (D4 duration). Default 24h. Examples: 1h, 24h, 7d, 30d." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenericListResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "apiKey": [] } ] } }, "/api/v1/qrl2/nft/mints/summary": { "get": { "tags": [ "NFT" ], "summary": "Nft Mints Summary", "description": "Hero metrics for the /nft-mints page (QRL2 QRC-721/QRC-1155 mints).\n\nAll-time mint count + 7d/30d pulse, distinct minting collections, distinct\nminters, the QRC-721 vs QRC-1155 split, the most-minted collection, and the\nlatest mint time (freshness). ``mints_24h`` is returned for completeness but\nthe UI omits it (chronically 0 on the sparse testnet). Mint =\n``from_addr = Q000…000`` (the zero-address); QRL legacy has no NFTs, so this\nroute is qrl2-only by mount.\n\nDeclared BEFORE ``/{contract}/owners`` so the literal ``mints`` segment is\nnot captured as a ``{contract}`` path param. Returns zero-filled (no 500) on\na missing view; the frontend hero hides itself when ``total_mints == 0``.", "operationId": "nft_mints_summary_api_v1_qrl2_nft_mints_summary_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NftMintsSummary" } } } } }, "security": [ { "apiKey": [] } ] } }, "/api/v1/qrl2/nft/{contract}/owners": { "get": { "tags": [ "NFT" ], "summary": "List Nft Owners", "description": "For a QRC-721 contract, return the current owner per token_id.\n\n\"Current owner\" = `to_addr` of the most-recent transfer per token_id.\nTokens that were minted and then burned (last transfer's `to_addr =\n0x0`) are excluded from the result.\n\nPagination is offset-based; for large NFT collections (10k+) consider\n`?page_size=200` and walk pages.", "operationId": "list_nft_owners_api_v1_qrl2_nft__contract__owners_get", "parameters": [ { "name": "contract", "in": "path", "required": true, "schema": { "type": "string", "title": "Contract" } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "default": 1, "title": "Page" } }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 200, "minimum": 1, "default": 50, "title": "Page Size" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenericListResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "apiKey": [] } ] } }, "/api/v1/qrl2/nft/{contract}/{token_id}/history": { "get": { "tags": [ "NFT" ], "summary": "Get Nft History", "description": "Full transfer chain for a single NFT.\n\nReturns every transfer of `token_id` in chronological order (oldest\nfirst), starting with the mint (`from_addr = 0x0..0`) if present and\nending at the current owner. Useful for ownership-provenance / \"who\nheld this NFT\" visualisations.", "operationId": "get_nft_history_api_v1_qrl2_nft__contract___token_id__history_get", "parameters": [ { "name": "contract", "in": "path", "required": true, "schema": { "type": "string", "title": "Contract" } }, { "name": "token_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Token Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenericObject" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "apiKey": [] } ] } }, "/api/v1/qrl2/mempool": { "get": { "tags": [ "Mempool" ], "summary": "List Pending", "description": "Pending qrl2 transactions (mempool view).\n\nWave 8: cursor-only pagination. The mempool churns constantly (txs\nenter, get confirmed, get evicted), so offset paging is meaningless.\nCursor anchors to the `seen_at` timestamp of the last row returned.\n\nThe view auto-excludes pending txs that have already landed in a\nblock within the last hour, so the result is \"actually still pending\"\nrather than \"ever-seen\". Sort: most-recently-seen first.", "operationId": "list_pending_api_v1_qrl2_mempool_get", "parameters": [ { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Opaque pagination token from a previous response's `next_cursor`. Omit to start at the mempool head (most-recently-seen).", "title": "Cursor" }, "description": "Opaque pagination token from a previous response's `next_cursor`. Omit to start at the mempool head (most-recently-seen)." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 200, "minimum": 1, "description": "Items per page (1-200).", "default": 50, "title": "Limit" }, "description": "Items per page (1-200)." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenericListResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "apiKey": [] } ] } }, "/api/v1/qrl2/token-transfers": { "get": { "tags": [ "Token Transfers" ], "summary": "List Transfers", "description": "Cursor-paginated decoded transfers across all QRC token standards.\n\nWave 8 of the API consistency refactor: token-transfers is a live feed\n(every new block can emit new Transfer events), so offset paging is\nbroken — page 2 would skip events that arrived between page-clicks.\nCursor anchors to (block_height, log_index) so subsequent pages are\nstable as the head advances.\n\nThe unified view collapses QRC-20/721/1155 into one shape, but the\n`token_standard` column lets callers filter. `involved` is the common\n\"show me this wallet's transfer history\" filter (in OR out). The repo\ndegrades to an empty page on a missing view, so this never 500s on a\npartial deploy.", "operationId": "list_transfers_api_v1_qrl2_token_transfers_get", "parameters": [ { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Opaque pagination token from a previous response's `next_cursor`. Omit to start at the chain head (newest). Do not decode/construct.", "title": "Cursor" }, "description": "Opaque pagination token from a previous response's `next_cursor`. Omit to start at the chain head (newest). Do not decode/construct." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "description": "Items per page (1-100).", "default": 25, "title": "Limit" }, "description": "Items per page (1-100)." }, { "name": "token_contract", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter to one token", "title": "Token Contract" }, "description": "Filter to one token" }, { "name": "from", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "From" } }, { "name": "to", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "To" } }, { "name": "involved", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Either from_addr OR to_addr equals this address", "title": "Involved" }, "description": "Either from_addr OR to_addr equals this address" }, { "name": "token_standard", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "pattern": "^(qrc20|qrc721|qrc1155|qrc1155_batch)(,(qrc20|qrc721|qrc1155|qrc1155_batch))*$" }, { "type": "null" } ], "description": "qrc20 | qrc721 | qrc1155 | qrc1155_batch — also accepts a CSV (e.g. 'qrc721,qrc1155,qrc1155_batch' for the /top-nft hub).", "title": "Token Standard" }, "description": "qrc20 | qrc721 | qrc1155 | qrc1155_batch — also accepts a CSV (e.g. 'qrc721,qrc1155,qrc1155_batch' for the /top-nft hub)." }, { "name": "since_block", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Only transfers with block_height >= this", "title": "Since Block" }, "description": "Only transfers with block_height >= this" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransfersPaginated" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "apiKey": [] } ] } }, "/api/v1/qrl2/token-transfers/summary": { "get": { "tags": [ "Token Transfers" ], "summary": "Transfers Summary", "description": "Hero metrics for the token-transfers / nft-transfers feed.\n\n24h + 7d transfer counts (the 7d anchors a daily-average comparison),\nall-time total, distinct active contracts, the Mint/Burn/Transfer split, and\nthe single most-active contract. ``token_standard`` selects the feed\n(default qrc20; pass the NFT CSV for the /nft-transfers hero). Zero-filled on\na missing view.", "operationId": "transfers_summary_api_v1_qrl2_token_transfers_summary_get", "parameters": [ { "name": "token_standard", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "pattern": "^(qrc20|qrc721|qrc1155|qrc1155_batch)(,(qrc20|qrc721|qrc1155|qrc1155_batch))*$" }, { "type": "null" } ], "description": "qrc20 (default) | qrc721 | qrc1155 | qrc1155_batch — also accepts a CSV (e.g. 'qrc721,qrc1155,qrc1155_batch' for the /nft-transfers hero).", "title": "Token Standard" }, "description": "qrc20 (default) | qrc721 | qrc1155 | qrc1155_batch — also accepts a CSV (e.g. 'qrc721,qrc1155,qrc1155_batch' for the /nft-transfers hero)." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransfersFeedSummary" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "apiKey": [] } ] } }, "/api/v1/qrl2/withdrawals/": { "get": { "tags": [ "Withdrawals" ], "summary": "List validator withdrawals (UI label: \"Validator Rewards\")", "description": "Paginated EIP-4895 withdrawal feed, newest first. Public-name mapping: surfaced as \"Validator Rewards\" in the UI (`/rewards`). The API uses the spec-aligned `withdrawals` term.", "operationId": "list_withdrawals_api_v1_qrl2_withdrawals__get", "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "default": 1, "title": "Page" } }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "default": 25, "title": "Page Size" } }, { "name": "address", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter by recipient address", "title": "Address" }, "description": "Filter by recipient address" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WithdrawalsPaginated" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "apiKey": [] } ] } }, "/api/v1/qrl2/withdrawals/daily": { "get": { "tags": [ "Withdrawals" ], "summary": "Per-day withdrawal rollup (UI label: \"Daily rewards\")", "description": "Per-day rollup: count, total amount (planck), unique recipients.\n\nWave 6: `?days=N` → `?window=30d` (D4).", "operationId": "daily_withdrawals_api_v1_qrl2_withdrawals_daily_get", "parameters": [ { "name": "window", "in": "query", "required": false, "schema": { "type": "string", "description": "Look-back window for daily withdrawals. Default 30d.", "default": "30d", "title": "Window" }, "description": "Look-back window for daily withdrawals. Default 30d." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DailyWithdrawalsList" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "apiKey": [] } ] } }, "/api/v1/qrl2/withdrawals/top-recipients": { "get": { "tags": [ "Withdrawals" ], "summary": "Top operators by rewards received (UI label: \"Top operators\")", "description": "Recipient (withdrawal) addresses ranked by total EIP-4895 rewards received. One address can serve many validators run by the same operator, so this ranks operators rather than individual validators.", "operationId": "top_withdrawal_recipients_api_v1_qrl2_withdrawals_top_recipients_get", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "default": 10, "title": "Limit" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TopWithdrawalRecipientsList" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "apiKey": [] } ] } }, "/api/v1/qrl2/withdrawals/summary": { "get": { "tags": [ "Withdrawals" ], "summary": "All-time withdrawal totals (UI label: \"Rewards summary\")", "description": "All-time totals (count, amount, recipients, first/last day).", "operationId": "withdrawal_summary_api_v1_qrl2_withdrawals_summary_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WithdrawalSummaryResponse" } } } } }, "security": [ { "apiKey": [] } ] } }, "/api/v1/qrl2/transactions/{tx_hash}/revert-reason": { "get": { "tags": [ "Transactions (QRL2)" ], "summary": "Decoded EVM revert reason for a reverted QRL2 transaction", "description": "Return the decoded revert reason for a failed QRL2 transaction.\n\nFlow:\n 1. Verify the tx exists and has status=0 (avoid wasting RPC on success txs).\n 2. Hit `debug_traceTransaction(callTracer)` against the qrl2 node.\n 3. Decode the top-level frame's `output` (Error(string) / Panic(uint256) / custom).\n 4. Cache the result for 24h in Redis (or in-memory if Redis is down).\n\nQRL2 (EVM) only — mounted under /api/v1/qrl2/transactions/, no chain\nselection needed.", "operationId": "get_transaction_revert_reason_api_v1_qrl2_transactions__tx_hash__revert_reason_get", "parameters": [ { "name": "tx_hash", "in": "path", "required": true, "schema": { "type": "string", "title": "Tx Hash" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RevertReasonResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "apiKey": [] } ] } }, "/api/v1/qrl2/rpc": { "post": { "tags": [ "JSON-RPC" ], "summary": "QRL 2.0 JSON-RPC proxy (API key required)", "description": "Standard JSON-RPC 2.0 endpoint for QRL 2.0, so wallets and ethers-style libraries can use Quantascan as their node. Accepts one request object or a batch of up to 20; each batch item counts as one API call. Requires `Authorization: Bearer qs_…`.\n\nSupported methods: `net_version`, `qrl_blockNumber`, `qrl_call`, `qrl_chainId`, `qrl_estimateGas`, `qrl_feeHistory`, `qrl_gasPrice`, `qrl_getBalance`, `qrl_getBlockByHash`, `qrl_getBlockByNumber`, `qrl_getBlockReceipts`, `qrl_getBlockTransactionCountByHash`, `qrl_getBlockTransactionCountByNumber`, `qrl_getCode`, `qrl_getHeaderByHash`, `qrl_getHeaderByNumber`, `qrl_getLogs`, `qrl_getStorageAt`, `qrl_getTransactionByBlockHashAndIndex`, `qrl_getTransactionByBlockNumberAndIndex`, `qrl_getTransactionByHash`, `qrl_getTransactionCount`, `qrl_getTransactionReceipt`, `qrl_maxPriorityFeePerGas`, `qrl_sendRawTransaction`, `qrl_syncing`, `web3_clientVersion`. Any other method returns error -32601. QRL 2.0 uses the `qrl_` namespace; `eth_*` names are not supported.\n\nLimits: `qrl_getLogs` needs an address or topic and spans at most 5,000 blocks; `qrl_call`/`qrl_estimateGas` take no state overrides; `qrl_sendRawTransaction` is limited to 10 per minute per key; responses are capped at 5 MB.", "operationId": "json_rpc_api_v1_qrl2_rpc_post", "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "properties": { "jsonrpc": { "type": "string", "enum": [ "2.0" ] }, "id": { "oneOf": [ { "type": "string" }, { "type": "integer" }, { "type": "null" } ] }, "method": { "type": "string", "enum": [ "net_version", "qrl_blockNumber", "qrl_call", "qrl_chainId", "qrl_estimateGas", "qrl_feeHistory", "qrl_gasPrice", "qrl_getBalance", "qrl_getBlockByHash", "qrl_getBlockByNumber", "qrl_getBlockReceipts", "qrl_getBlockTransactionCountByHash", "qrl_getBlockTransactionCountByNumber", "qrl_getCode", "qrl_getHeaderByHash", "qrl_getHeaderByNumber", "qrl_getLogs", "qrl_getStorageAt", "qrl_getTransactionByBlockHashAndIndex", "qrl_getTransactionByBlockNumberAndIndex", "qrl_getTransactionByHash", "qrl_getTransactionCount", "qrl_getTransactionReceipt", "qrl_maxPriorityFeePerGas", "qrl_sendRawTransaction", "qrl_syncing", "web3_clientVersion" ] }, "params": { "items": {}, "type": "array" } }, "type": "object", "required": [ "jsonrpc", "method" ] }, { "items": { "properties": { "jsonrpc": { "type": "string", "enum": [ "2.0" ] }, "id": { "oneOf": [ { "type": "string" }, { "type": "integer" }, { "type": "null" } ] }, "method": { "type": "string", "enum": [ "net_version", "qrl_blockNumber", "qrl_call", "qrl_chainId", "qrl_estimateGas", "qrl_feeHistory", "qrl_gasPrice", "qrl_getBalance", "qrl_getBlockByHash", "qrl_getBlockByNumber", "qrl_getBlockReceipts", "qrl_getBlockTransactionCountByHash", "qrl_getBlockTransactionCountByNumber", "qrl_getCode", "qrl_getHeaderByHash", "qrl_getHeaderByNumber", "qrl_getLogs", "qrl_getStorageAt", "qrl_getTransactionByBlockHashAndIndex", "qrl_getTransactionByBlockNumberAndIndex", "qrl_getTransactionByHash", "qrl_getTransactionCount", "qrl_getTransactionReceipt", "qrl_maxPriorityFeePerGas", "qrl_sendRawTransaction", "qrl_syncing", "web3_clientVersion" ] }, "params": { "items": {}, "type": "array" } }, "type": "object", "required": [ "jsonrpc", "method" ] }, "type": "array", "maxItems": 20 } ] }, "example": { "jsonrpc": "2.0", "id": 1, "method": "qrl_blockNumber", "params": [] } } }, "required": true }, "responses": { "200": { "description": "JSON-RPC response object, or array for a batch.", "content": { "application/json": { "schema": {} } } }, "400": { "description": "Empty batch or batch larger than the maximum." }, "401": { "description": "No valid API key." }, "429": { "description": "Daily quota or per-minute limit reached." }, "502": { "description": "The node returned an invalid response." }, "503": { "description": "The node is unreachable." } }, "security": [ { "apiKey": [] } ] } }, "/api/v1/qrl2/addresses/{address}/nfts": { "get": { "tags": [ "NFT" ], "summary": "QRC-721 / QRC-1155 tokens held by an address", "description": "Every NFT the address holds right now, one row per (collection,\ntoken id): `balance` is 1 for QRC-721 and the unit count for QRC-1155.\nDerived from the raw `Transfer` / `TransferSingle` / `TransferBatch`\nevents (batch transfers included), so it works for any standards-\ncompliant contract whether or not its metadata is indexed. Sorted by\ncollection, then token id.", "operationId": "get_address_nfts_api_v1_qrl2_addresses__address__nfts_get", "parameters": [ { "name": "address", "in": "path", "required": true, "schema": { "type": "string", "description": "QRL 2.0 address (Q + 40 or 128 hex).", "title": "Address" }, "description": "QRL 2.0 address (Q + 40 or 128 hex)." }, { "name": "standard", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "pattern": "^(721|1155)$" }, { "type": "null" } ], "description": "Only QRC-721 or only QRC-1155 positions.", "title": "Standard" }, "description": "Only QRC-721 or only QRC-1155 positions." }, { "name": "contract", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Only positions in this collection.", "title": "Contract" }, "description": "Only positions in this collection." }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "default": 1, "title": "Page" } }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 200, "minimum": 1, "default": 50, "title": "Page Size" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NftHoldingsResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "apiKey": [] } ] } }, "/api/v1/qrl2/gas/oracle": { "get": { "tags": [ "Fees" ], "summary": "Next-block base fee and priority-fee suggestions", "description": "Fee estimate for the next QRL 2.0 block.\n\n`next_base_fee` is exact: the EIP-1559 rule applied to the newest indexed\nblock (validated against every indexed block). `slow` / `standard` /\n`fast` are the 25th / 50th / 90th percentile of the priority fee\n(effective gas price − base fee) paid by successful transactions in the\nlast ~200 blocks, widened to the last 200 transactions when the chain is\nquiet. All amounts in planck, with the same value in shor (1 shor =\n1e9 planck, QRL's equivalent of gwei). Refreshed every ~12 s.", "operationId": "get_gas_oracle_api_v1_qrl2_gas_oracle_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GasOracleResponse" } } } } }, "security": [ { "apiKey": [] } ] } }, "/api/v1/qrl2/logs": { "get": { "tags": [ "Contracts" ], "summary": "Event logs across contracts (getLogs)", "description": "Raw event logs, oldest first, filtered by contract and/or topics — the\nequivalent of Etherscan's `getLogs`, with cursor paging instead of a\n1,000-row cap.\n\nAt least `address` or `topic0` is required. With both, any block range\nis allowed. With only `address` the range is limited to 100,000 blocks;\nwith only `topic0`, to 10,000 blocks (`from_block` defaults to the start\nof that window). topic1..3 narrow further and match exactly (32-byte\nhex with an address left-padded with zeros on 20-byte networks; the\nfull 64-byte address on 64-byte (VM64) networks). Logs the node\nreported as removed by a reorg are excluded. `data` and `topics` are\nreturned undecoded.", "operationId": "get_logs_api_v1_qrl2_logs_get", "parameters": [ { "name": "address", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Emitting contract (Q + 40 or 128 hex).", "title": "Address" }, "description": "Emitting contract (Q + 40 or 128 hex)." }, { "name": "topic0", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Event signature hash (0x + 64 hex). Also matches 64-byte VM64 logs, where it is stored left-aligned; 0x + 128 hex matches exactly.", "title": "Topic0" }, "description": "Event signature hash (0x + 64 hex). Also matches 64-byte VM64 logs, where it is stored left-aligned; 0x + 128 hex matches exactly." }, { "name": "topic1", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "First indexed argument (0x + 64 or 128 hex).", "title": "Topic1" }, "description": "First indexed argument (0x + 64 or 128 hex)." }, { "name": "topic2", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Second indexed argument (0x + 64 or 128 hex).", "title": "Topic2" }, "description": "Second indexed argument (0x + 64 or 128 hex)." }, { "name": "topic3", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Third indexed argument (0x + 64 or 128 hex).", "title": "Topic3" }, "description": "Third indexed argument (0x + 64 or 128 hex)." }, { "name": "from_block", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "minimum": 0 }, { "type": "null" } ], "description": "First block (inclusive).", "title": "From Block" }, "description": "First block (inclusive)." }, { "name": "to_block", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "minimum": 0 }, { "type": "null" } ], "description": "Last block (inclusive). Defaults to the indexed tip.", "title": "To Block" }, "description": "Last block (inclusive). Defaults to the indexed tip." }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Opaque token from a previous response's `next_cursor`.", "title": "Cursor" }, "description": "Opaque token from a previous response's `next_cursor`." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 1000, "minimum": 1, "description": "Logs per page (1-1000).", "default": 100, "title": "Limit" }, "description": "Logs per page (1-1000)." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventLogsResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "apiKey": [] } ] } }, "/api/v1/qrl/mining/summary": { "get": { "tags": [ "Mining" ], "summary": "Mining KPI summary", "description": "Network-health KPIs: difficulty, hashrate, block time, emission, miner/pool\ncounts. Network-health fields are None until the mining-stats poller runs.", "operationId": "mining_summary_api_v1_qrl_mining_summary_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MiningSummary" } } } } }, "security": [ { "apiKey": [] } ] } }, "/api/v1/qrl/mining/top-miners": { "get": { "tags": [ "Mining" ], "summary": "Top miners & pools leaderboard", "description": "Leaderboard of coinbase addresses by blocks mined, with wallet-class label\n(miner / miningpool) and reward earned. `window=all` is all-time.", "operationId": "top_miners_api_v1_qrl_mining_top_miners_get", "parameters": [ { "name": "window", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^(all|24h|7d|30d|90d)$", "default": "all", "title": "Window" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 200, "minimum": 1, "default": 50, "title": "Limit" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TopMinersList" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "apiKey": [] } ] } }, "/api/v1/qrl/mining/pool-distribution": { "get": { "tags": [ "Mining" ], "summary": "Pool / miner block-share distribution (donut)", "description": "Share of blocks mined per top-N pool/miner over the window, with the tail\nbucketed as 'Other miners'.", "operationId": "pool_distribution_api_v1_qrl_mining_pool_distribution_get", "parameters": [ { "name": "window", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^(all|24h|7d|30d|90d)$", "default": "30d", "title": "Window" } }, { "name": "top", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 20, "minimum": 3, "default": 10, "title": "Top" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PoolDistribution" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "apiKey": [] } ] } }, "/api/v1/qrl/mining/block-reward-daily": { "get": { "tags": [ "Mining" ], "summary": "Daily block-reward emission (subsidy + fees)", "description": "Per-day mined emission (shor): protocol subsidy vs collected fees.", "operationId": "block_reward_daily_api_v1_qrl_mining_block_reward_daily_get", "parameters": [ { "name": "window", "in": "query", "required": false, "schema": { "type": "string", "description": "Look-back window for mining timelines. Default 90d.", "default": "90d", "title": "Window" }, "description": "Look-back window for mining timelines. Default 90d." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BlockRewardDailyList" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "apiKey": [] } ] } }, "/api/v1/qrl/mining/network-stats-daily": { "get": { "tags": [ "Mining" ], "summary": "Daily difficulty & hashrate (node-RPC)", "description": "Per-day average/max difficulty + hash power from GetStats snapshots.\nEmpty until the mining-stats poller has accumulated history.", "operationId": "network_stats_daily_api_v1_qrl_mining_network_stats_daily_get", "parameters": [ { "name": "window", "in": "query", "required": false, "schema": { "type": "string", "description": "Look-back window for mining timelines. Default 90d.", "default": "90d", "title": "Window" }, "description": "Look-back window for mining timelines. Default 90d." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NetworkStatsDailyList" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "apiKey": [] } ] } }, "/api/v1/qrl/mining/pool-dominance-daily": { "get": { "tags": [ "Mining" ], "summary": "Pool dominance over time (stacked)", "description": "Per-day blocks mined by each top-N pool + an 'other' bucket — for a stacked\ndecentralization-over-time chart.", "operationId": "pool_dominance_daily_api_v1_qrl_mining_pool_dominance_daily_get", "parameters": [ { "name": "top", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 12, "minimum": 3, "default": 8, "title": "Top" } }, { "name": "window", "in": "query", "required": false, "schema": { "type": "string", "description": "Look-back window for mining timelines. Default 90d.", "default": "90d", "title": "Window" }, "description": "Look-back window for mining timelines. Default 90d." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PoolDominanceResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "apiKey": [] } ] } }, "/api/v1/qrl/messages/": { "get": { "tags": [ "Messages" ], "summary": "On-chain message feed", "description": "Paginated feed of QRL on-chain text, newest first — both dedicated\n`message` transactions and memos attached to transfers. The payload is\nreturned both as verbatim hex and as best-effort UTF-8 text.", "operationId": "list_messages_api_v1_qrl_messages__get", "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 10000, "minimum": 1, "default": 1, "title": "Page" } }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "default": 25, "title": "Page Size" } }, { "name": "address", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "minLength": 3, "maxLength": 100 }, { "type": "null" } ], "description": "Filter: sender, recipient or master address.", "title": "Address" }, "description": "Filter: sender, recipient or master address." }, { "name": "q", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 200 }, { "type": "null" } ], "description": "Case-insensitive substring search in the decoded text.", "title": "Q" }, "description": "Case-insensitive substring search in the decoded text." }, { "name": "readable_only", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Only messages that decode to clean UTF-8 text.", "default": false, "title": "Readable Only" }, "description": "Only messages that decode to clean UTF-8 text." }, { "name": "type", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "pattern": "^(message|transfer_memo)$" }, { "type": "null" } ], "description": "Filter by kind: 'message' (dedicated subtype) or 'transfer_memo' (memo on a transfer). Omit for both.", "title": "Type" }, "description": "Filter by kind: 'message' (dedicated subtype) or 'transfer_memo' (memo on a transfer). Omit for both." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QrlMessagesList" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "apiKey": [] } ] } }, "/api/v1/qrl/messages/stats/summary": { "get": { "tags": [ "Messages" ], "summary": "Message stats", "description": "Headline stats: total messages, readable share, bytes anchored,\nunique senders, first/last message time.", "operationId": "messages_summary_api_v1_qrl_messages_stats_summary_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QrlMessagesSummary" } } } } }, "security": [ { "apiKey": [] } ] } }, "/api/v1/analytics/total_supply": { "get": { "tags": [ "Analytics" ], "summary": "Total Supply", "description": "Cross-chain mint per day. Today QRL coinbase + QRL2 withdrawals;\nthe migration columns (`*_via_migration`) stay 0 until the bridge\nparser is built (Fase 6+).", "operationId": "total_supply_api_v1_analytics_total_supply_get", "parameters": [ { "name": "window", "in": "query", "required": false, "schema": { "type": "string", "description": "Look-back window with unit suffix (m=min, h=hour, d=day, w=week). Default 90d. Examples: 24h, 7d, 90d.", "default": "90d", "title": "Window" }, "description": "Look-back window with unit suffix (m=min, h=hour, d=day, w=week). Default 90d. Examples: 24h, 7d, 90d." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenericListResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "apiKey": [] } ] } }, "/api/v1/analytics/cross-chain/history/{address}": { "get": { "tags": [ "Analytics" ], "summary": "Cross Chain History", "description": "Unified wallet history across both chains. Returns rows from QRL +\nQRL2 sorted by timestamp DESC. Uses `unified_account_history` view —\nwhile address_linkage is empty, returns per-chain history for the\nsingle address. Post-bridge: combined history of all linked addresses.", "operationId": "cross_chain_history_api_v1_analytics_cross_chain_history__address__get", "parameters": [ { "name": "address", "in": "path", "required": true, "schema": { "type": "string", "title": "Address" } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "default": 1, "title": "Page" } }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 200, "minimum": 1, "default": 50, "title": "Page Size" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenericListResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "apiKey": [] } ] } }, "/api/v1/analytics/network/health": { "get": { "tags": [ "Analytics" ], "summary": "Network Health", "description": "Composite per-chain health signal. Returns:\n - latest_block_time\n - tip_lag_seconds (now - latest_block_time)\n - dlq_open_count (failed_blocks_open)\n - silver_blocks_24h (rows written in the last 24h via ingested_at)\n - status: 'ok' | 'degraded' | 'stalled' | 'unknown'\n\nFrontend renders this as the dashboard traffic-light. Real ops alerting\nhappens via Prometheus (alert_rules.yml), not this endpoint — this is\nfor UX, not paging.", "operationId": "network_health_api_v1_analytics_network_health_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsHealthCheck" } } } } }, "security": [ { "apiKey": [] } ] } }, "/api/v1/analytics/network/gas-trends": { "get": { "tags": [ "Analytics" ], "summary": "Gas Trends", "description": "QRL2 EIP-1559 base-fee + burn trend per day. Wraps the underlying\n`qrl2_fee_burned_daily` Gold table; exposed here for the analytics\nnamespace so dashboards have one root for all chart endpoints.", "operationId": "gas_trends_api_v1_analytics_network_gas_trends_get", "parameters": [ { "name": "window", "in": "query", "required": false, "schema": { "type": "string", "description": "Look-back window with unit suffix (m=min, h=hour, d=day, w=week). Default 30d. Examples: 24h, 7d, 90d.", "default": "30d", "title": "Window" }, "description": "Look-back window with unit suffix (m=min, h=hour, d=day, w=week). Default 30d. Examples: 24h, 7d, 90d." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsGasTrends" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "apiKey": [] } ] } }, "/api/v1/analytics/fees/percentiles": { "get": { "tags": [ "Analytics" ], "summary": "Fees Percentiles", "description": "Daily fee p50/p95/p99 + max + total.\n\nSurfaces what the typical user actually paid (vs a sum-of-fees view\nthat's dominated by single big txs). Powers a \"Fee distribution\"\nchart with three percentile lines per day.", "operationId": "fees_percentiles_api_v1_analytics_fees_percentiles_get", "parameters": [ { "name": "chain", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^(qrl|qrl2)$", "description": "Which chain to query: qrl (legacy PoW) or qrl2 (PoS EVM). Defaults to qrl2.", "default": "qrl2", "title": "Chain" }, "description": "Which chain to query: qrl (legacy PoW) or qrl2 (PoS EVM). Defaults to qrl2." }, { "name": "window", "in": "query", "required": false, "schema": { "type": "string", "description": "Look-back window with unit suffix (m=min, h=hour, d=day, w=week). Default 30d. Examples: 24h, 7d, 90d.", "default": "30d", "title": "Window" }, "description": "Look-back window with unit suffix (m=min, h=hour, d=day, w=week). Default 30d. Examples: 24h, 7d, 90d." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenericListResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "apiKey": [] } ] } }, "/api/v1/analytics/exchange/summary": { "get": { "tags": [ "Analytics" ], "summary": "Exchange Summary", "description": "Exchange-activity snapshot for the /exchange-flow page.\n\nPer-exchange leaderboard (current balance + address count), aggregate net\nand gross flow (7d/30d), and the share of held supply on exchanges.\n\n\"An exchange\" means its curated wallets PLUS its confirmed deposit relays —\nthe personal deposit addresses users are handed, which are swept into the\nmain wallet later. Balances therefore include coins parked in those deposit\naddresses; `relay_addresses` and `relay_balance_quanta` report that part\nseparately per venue. qrl-primary — QRL2 exchange labels populate at\nmainnet. Defaults to chain=qrl since that is where the curated exchange\nlabels live today.\n\nA venue whose curated wallets have been silent for `inactive_after_days`\nis flagged `inactive` and carries `wallet_last_seen`. Its custody is still\nincluded in `total_balance_quanta` (the coins are really there) but not in\n`supply_pct` / `active_balance_quanta`, which describe sell-ready supply.\n`supply_pct_all` keeps the whole-custody share available.", "operationId": "exchange_summary_api_v1_analytics_exchange_summary_get", "parameters": [ { "name": "chain", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^(qrl|qrl2)$", "description": "Which chain to query: qrl (legacy PoW) or qrl2 (PoS EVM). Defaults to qrl.", "default": "qrl", "title": "Chain" }, "description": "Which chain to query: qrl (legacy PoW) or qrl2 (PoS EVM). Defaults to qrl." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenericObject" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "apiKey": [] } ] } }, "/api/v1/analytics/exchange/side": { "get": { "tags": [ "Analytics" ], "summary": "Exchange Side", "description": "Which of these addresses belong to an exchange, and to which one.\n\nAn address is on the exchange side when it is a curated exchange wallet\n(`kind` = \"wallet\") or a detected deposit address of one (`kind` =\n\"relay\"; see the /exchange-flow methodology). Addresses that are not on\nthe exchange side are simply absent from `items`. This is the same\ndefinition the exchange-flow figures and the public whale alerts use.", "operationId": "exchange_side_api_v1_analytics_exchange_side_get", "parameters": [ { "name": "address", "in": "query", "required": true, "schema": { "type": "array", "items": { "type": "string" }, "description": "Up to 4 addresses", "title": "Address" }, "description": "Up to 4 addresses" }, { "name": "chain", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^(qrl|qrl2)$", "description": "Which chain to query: qrl (legacy PoW) or qrl2 (PoS EVM). Defaults to qrl.", "default": "qrl", "title": "Chain" }, "description": "Which chain to query: qrl (legacy PoW) or qrl2 (PoS EVM). Defaults to qrl." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenericListResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "apiKey": [] } ] } }, "/api/v1/analytics/exchange/largest-transfers": { "get": { "tags": [ "Analytics" ], "summary": "Exchange Largest Transfers", "description": "Largest single deposits and withdrawals within the window.\n\nConcrete deposit/withdrawal feed for /exchange-flow — sorted by value, each\nrow tagged deposit (into an exchange) or withdrawal (out of one).\n\nDeposits are matched at the DEPOSIT ADDRESS, not at the later sweep into\nthe exchange main wallet, so `from_addr` is the actual depositor and the\ntimestamp is when the coins actually moved. `exchange_label` names the\nvenue even when the counterparty is one of its deposit addresses, and\n`via_relay` marks exactly those rows. Transfers internal to one exchange\n(sweeps, hot/cold rebalances) are excluded. qrl-primary; degrades to an\nempty feed on chains without curated exchange labels (e.g. QRL2 testnet).", "operationId": "exchange_largest_transfers_api_v1_analytics_exchange_largest_transfers_get", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "default": 20, "title": "Limit" } }, { "name": "direction", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^(both|deposit|withdrawal)$", "default": "both", "title": "Direction" } }, { "name": "chain", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^(qrl|qrl2)$", "description": "Which chain to query: qrl (legacy PoW) or qrl2 (PoS EVM). Defaults to qrl.", "default": "qrl", "title": "Chain" }, "description": "Which chain to query: qrl (legacy PoW) or qrl2 (PoS EVM). Defaults to qrl." }, { "name": "window", "in": "query", "required": false, "schema": { "type": "string", "description": "Look-back window with unit suffix (m=min, h=hour, d=day, w=week). Default 30d. Examples: 24h, 7d, 90d.", "default": "30d", "title": "Window" }, "description": "Look-back window with unit suffix (m=min, h=hour, d=day, w=week). Default 30d. Examples: 24h, 7d, 90d." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenericListResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "apiKey": [] } ] } }, "/api/v1/analytics/gas-distribution": { "get": { "tags": [ "Analytics" ], "summary": "Gas Distribution", "description": "Per-day gas-used bucketed distribution (qrl2 EVM only).\n\n7 buckets aligned to common EVM ops (simple value transfer / QRC-20 /\ncontract call / contract swap / complex contract call / deploy / 1M+).\nPowers a stacked-bar chart and surfaces what kind of workload the chain\nhandles over time.", "operationId": "gas_distribution_api_v1_analytics_gas_distribution_get", "parameters": [ { "name": "window", "in": "query", "required": false, "schema": { "type": "string", "description": "Look-back window with unit suffix (m=min, h=hour, d=day, w=week). Default 30d. Examples: 24h, 7d, 90d.", "default": "30d", "title": "Window" }, "description": "Look-back window with unit suffix (m=min, h=hour, d=day, w=week). Default 30d. Examples: 24h, 7d, 90d." }, { "name": "chain", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^(qrl|qrl2)$", "description": "Which chain to query: qrl (legacy PoW) or qrl2 (PoS EVM). Defaults to qrl2.", "default": "qrl2", "title": "Chain" }, "description": "Which chain to query: qrl (legacy PoW) or qrl2 (PoS EVM). Defaults to qrl2." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenericListResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "apiKey": [] } ] } }, "/api/v1/analytics/block-times": { "get": { "tags": [ "Analytics" ], "summary": "Block Times", "description": "Per-day mean block-interval (seconds) + block count.\n\nUseful for catching block-time degradation on PoW (qrl ~60s target)\nor slot-skipping on PoS (qrl2 ~12s target).", "operationId": "block_times_api_v1_analytics_block_times_get", "parameters": [ { "name": "window", "in": "query", "required": false, "schema": { "type": "string", "description": "Look-back window with unit suffix (m=min, h=hour, d=day, w=week). Default 30d. Examples: 24h, 7d, 90d.", "default": "30d", "title": "Window" }, "description": "Look-back window with unit suffix (m=min, h=hour, d=day, w=week). Default 30d. Examples: 24h, 7d, 90d." }, { "name": "chain", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^(qrl|qrl2)$", "description": "Which chain to query: qrl (legacy PoW) or qrl2 (PoS EVM). Defaults to qrl.", "default": "qrl", "title": "Chain" }, "description": "Which chain to query: qrl (legacy PoW) or qrl2 (PoS EVM). Defaults to qrl." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenericListResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "apiKey": [] } ] } }, "/api/v1/analytics/block-size": { "get": { "tags": [ "Analytics" ], "summary": "Block Size", "description": "Per-day average / max / sum block size in bytes.\n\nBacks /charts/daily-block-size on the frontend. Reads\nquantascan.block_size_daily (mig 062).", "operationId": "block_size_api_v1_analytics_block_size_get", "parameters": [ { "name": "chain", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^(qrl|qrl2)$", "description": "Which chain to query: qrl (legacy PoW) or qrl2 (PoS EVM). Defaults to qrl2.", "default": "qrl2", "title": "Chain" }, "description": "Which chain to query: qrl (legacy PoW) or qrl2 (PoS EVM). Defaults to qrl2." }, { "name": "window", "in": "query", "required": false, "schema": { "type": "string", "description": "Look-back window with unit suffix (m=min, h=hour, d=day, w=week). Default 30d. Examples: 24h, 7d, 90d.", "default": "30d", "title": "Window" }, "description": "Look-back window with unit suffix (m=min, h=hour, d=day, w=week). Default 30d. Examples: 24h, 7d, 90d." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenericListResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "apiKey": [] } ] } }, "/api/v1/analytics/wallet-count": { "get": { "tags": [ "Analytics" ], "summary": "Wallet Count", "description": "Per-day new-wallets + cumulative wallet count (every distinct wallet\never seen on-chain).\n\nBacks the /charts/wallet-count thumbnail + the growth widget. Cumulative\ncount uses a window function over `quantascan.wallets.first_seen_at`\n(mig 062, view renamed mig 075). The detail page's \"with balance (> 0)\"\ntoggle is served separately via /timeline/active-wallets.", "operationId": "wallet_count_api_v1_analytics_wallet_count_get", "parameters": [ { "name": "chain", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^(qrl|qrl2)$", "description": "Which chain to query: qrl (legacy PoW) or qrl2 (PoS EVM). Defaults to qrl2.", "default": "qrl2", "title": "Chain" }, "description": "Which chain to query: qrl (legacy PoW) or qrl2 (PoS EVM). Defaults to qrl2." }, { "name": "window", "in": "query", "required": false, "schema": { "type": "string", "description": "Look-back window with unit suffix (m=min, h=hour, d=day, w=week). Default 30d. Examples: 24h, 7d, 90d.", "default": "30d", "title": "Window" }, "description": "Look-back window with unit suffix (m=min, h=hour, d=day, w=week). Default 30d. Examples: 24h, 7d, 90d." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenericListResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "apiKey": [] } ] } }, "/api/v1/analytics/transactions/user-daily": { "get": { "tags": [ "Analytics" ], "summary": "Transactions User Daily", "description": "Per-day economic USER transactions (mig 070 quantascan.user_tx_daily).\n\nThe PURE daily-txs definition: QRL excludes coinbase (block-reward) and\nadmin txs (slave/message/token/...); QRL2 counts all EVM txs. Backs the\n/charts/daily-txs single-chain thumbnail; the cross-chain detail page uses\nthe stitched /timeline/transactions, which reads the same view.", "operationId": "transactions_user_daily_api_v1_analytics_transactions_user_daily_get", "parameters": [ { "name": "chain", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^(qrl|qrl2)$", "description": "Which chain to query: qrl (legacy PoW) or qrl2 (PoS EVM). Defaults to qrl2.", "default": "qrl2", "title": "Chain" }, "description": "Which chain to query: qrl (legacy PoW) or qrl2 (PoS EVM). Defaults to qrl2." }, { "name": "window", "in": "query", "required": false, "schema": { "type": "string", "description": "Look-back window with unit suffix (m=min, h=hour, d=day, w=week). Default 30d. Examples: 24h, 7d, 90d.", "default": "30d", "title": "Window" }, "description": "Look-back window with unit suffix (m=min, h=hour, d=day, w=week). Default 30d. Examples: 24h, 7d, 90d." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenericListResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "apiKey": [] } ] } }, "/api/v1/analytics/transactions/by-type": { "get": { "tags": [ "Analytics" ], "summary": "Transactions By Type", "description": "Per-day distinct transaction count grouped by tx_type (mig 070).\n\nPowers the stacked \"transaction types\" composition chart. QRL surfaces its\nreal subtype mix (coinbase / transfer / slave / ...); QRL2 surfaces derived\nEVM categories (transfer / contract_call / contract_create).", "operationId": "transactions_by_type_api_v1_analytics_transactions_by_type_get", "parameters": [ { "name": "window", "in": "query", "required": false, "schema": { "type": "string", "description": "Look-back window with unit suffix (m=min, h=hour, d=day, w=week). Default 30d. Examples: 24h, 7d, 90d.", "default": "30d", "title": "Window" }, "description": "Look-back window with unit suffix (m=min, h=hour, d=day, w=week). Default 30d. Examples: 24h, 7d, 90d." }, { "name": "chain", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^(qrl|qrl2)$", "description": "Which chain to query: qrl (legacy PoW) or qrl2 (PoS EVM). Defaults to qrl.", "default": "qrl", "title": "Chain" }, "description": "Which chain to query: qrl (legacy PoW) or qrl2 (PoS EVM). Defaults to qrl." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenericListResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "apiKey": [] } ] } }, "/api/v1/analytics/timeline/{metric}": { "get": { "tags": [ "Analytics" ], "summary": "Unified Timeline", "description": "Cross-chain QRL → QRL2 stitched timeline for one metric.\n\nmetric ∈ {transactions, blocks, gas, wallets, active-wallets,\nactive-wallets-100, active-wallets-1000, supply,\nblock_time, block_size, active-addresses,\nactive-addresses-excl-payouts}.\n\nWave 7: `?days=N` → `?window=DURATION` (D4). The legacy `days=0`\n\"all-time\" sentinel maps to `?window=10y` (3650d, the max cap) —\nno real chain history exceeds that. The day-count snaps UP to the\nnearest UI tier (_snap_days) to keep the cache-key space bounded.\n\nOn testnet (no cutover set) returns the QRL mainnet series in `points`\nplus the QRL2 testnet series in `preview` (rendered separately so the\nwall-clock overlap isn't concatenated). Once the migration cutover block\nis configured (mainnet launch) the two chains are stitched into a single\ncontinuous `points` series with `cutover_block` / `cutover_date` set.", "operationId": "unified_timeline_api_v1_analytics_timeline__metric__get", "parameters": [ { "name": "metric", "in": "path", "required": true, "schema": { "type": "string", "title": "Metric" } }, { "name": "window", "in": "query", "required": false, "schema": { "type": "string", "description": "Look-back window with unit suffix (m=min, h=hour, d=day, w=week). Default 90d. Examples: 24h, 7d, 90d.", "default": "90d", "title": "Window" }, "description": "Look-back window with unit suffix (m=min, h=hour, d=day, w=week). Default 90d. Examples: 24h, 7d, 90d." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenericObject" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "apiKey": [] } ] } }, "/api/v1/analytics/network/reorgs": { "get": { "tags": [ "Analytics" ], "summary": "Network Reorgs", "description": "Reorg event history (P3 #20, migration 037).\n\nEach row = one detected chain-reorg, with the old hash (`prev_hash`)\nthat got swapped out and the new hash (`new_hash`) that replaced it\nat that height. Returns empty on pre-mig-037 deploys or chains that\nhaven't reorged.", "operationId": "network_reorgs_api_v1_analytics_network_reorgs_get", "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "default": 1, "title": "Page" } }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 200, "minimum": 1, "default": 50, "title": "Page Size" } }, { "name": "chain", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^(qrl|qrl2)$", "description": "Which chain to query: qrl (legacy PoW) or qrl2 (PoS EVM). Defaults to qrl2.", "default": "qrl2", "title": "Chain" }, "description": "Which chain to query: qrl (legacy PoW) or qrl2 (PoS EVM). Defaults to qrl2." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenericListResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "apiKey": [] } ] } }, "/api/v1/analytics/network/page-summary": { "get": { "tags": [ "Analytics" ], "summary": "Network Page Summary", "description": "Bundle for the /network hero strip: KPIs + sparse-data flag.\n\nReads the user-DAU rollup (etl_gold.active_addresses_daily, mig 078) for\nDAU/MAU and quantascan.daily_activity for the 30d tx count + delta. Single\nround-trip from the frontend on initial page load.", "operationId": "network_page_summary_api_v1_analytics_network_page_summary_get", "parameters": [ { "name": "chain", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^(qrl|qrl2)$", "description": "Which chain to query: qrl (legacy PoW) or qrl2 (PoS EVM). Defaults to qrl2.", "default": "qrl2", "title": "Chain" }, "description": "Which chain to query: qrl (legacy PoW) or qrl2 (PoS EVM). Defaults to qrl2." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenericObject" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "apiKey": [] } ] } }, "/api/v1/analytics/network/active-addresses-daily": { "get": { "tags": [ "Analytics" ], "summary": "Active Addresses Daily", "description": "Daily/weekly/monthly active addresses (DAU/WAU/MAU) per day.\n\nExact distinct active addresses from the mig-078 user-tx Gold states\n(same definition as the /timeline/active-addresses metric: no\ncoinbase, no EIP-4895 withdrawals). DAU = that exact day; WAU/MAU =\ntrailing 7/30 calendar days (exact uniques, not a sum-of-DAU\napproximation). Backs the weekly-monthly chart, /growth lead and\n/network sparse-gate. Day-count snaps to UI tiers (_snap_days)\nagainst cache-key enumeration.", "operationId": "active_addresses_daily_api_v1_analytics_network_active_addresses_daily_get", "parameters": [ { "name": "chain", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^(qrl|qrl2)$", "description": "Which chain to query: qrl (legacy PoW) or qrl2 (PoS EVM). Defaults to qrl2.", "default": "qrl2", "title": "Chain" }, "description": "Which chain to query: qrl (legacy PoW) or qrl2 (PoS EVM). Defaults to qrl2." }, { "name": "window", "in": "query", "required": false, "schema": { "type": "string", "description": "Look-back window with unit suffix (m=min, h=hour, d=day, w=week). Default 90d. Examples: 24h, 7d, 90d.", "default": "90d", "title": "Window" }, "description": "Look-back window with unit suffix (m=min, h=hour, d=day, w=week). Default 90d. Examples: 24h, 7d, 90d." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenericListResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "apiKey": [] } ] } }, "/api/v1/analytics/supply/summary": { "get": { "tags": [ "Analytics" ], "summary": "Supply Summary", "description": "Hero KPI strip for the /supply page: total supply, holders count,\ntop-10 share, dormant-1y %.\n\nBacked by app.core.supply_metrics.get_supply_summary — single CH query\nover quantascan.address_summary. Cached 5 minutes.", "operationId": "supply_summary_api_v1_analytics_supply_summary_get", "parameters": [ { "name": "chain", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^(qrl|qrl2)$", "description": "Which chain to query: qrl (legacy PoW) or qrl2 (PoS EVM). Defaults to qrl2.", "default": "qrl2", "title": "Chain" }, "description": "Which chain to query: qrl (legacy PoW) or qrl2 (PoS EVM). Defaults to qrl2." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenericObject" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "apiKey": [] } ] } }, "/api/v1/analytics/supply/curve": { "get": { "tags": [ "Analytics" ], "summary": "Supply Curve", "description": "Historical cumulative minted supply per day. Reads from the existing\ntotal_supply_timeline Gold MV (no new migration). Halving-projection\nand burn-via-migration tracking deferred to backlog.", "operationId": "supply_curve_api_v1_analytics_supply_curve_get", "parameters": [ { "name": "chain", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^(qrl|qrl2)$", "description": "Which chain to query: qrl (legacy PoW) or qrl2 (PoS EVM). Defaults to qrl2.", "default": "qrl2", "title": "Chain" }, "description": "Which chain to query: qrl (legacy PoW) or qrl2 (PoS EVM). Defaults to qrl2." }, { "name": "window", "in": "query", "required": false, "schema": { "type": "string", "description": "Look-back window with unit suffix (m=min, h=hour, d=day, w=week). Default 365d. Examples: 24h, 7d, 90d.", "default": "365d", "title": "Window" }, "description": "Look-back window with unit suffix (m=min, h=hour, d=day, w=week). Default 365d. Examples: 24h, 7d, 90d." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenericListResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "apiKey": [] } ] } }, "/api/v1/analytics/supply/holders-distribution": { "get": { "tags": [ "Analytics" ], "summary": "Supply Holders Distribution", "description": "Top 10 / 100 / 1k / 10k holder % of supply + Gini + Nakamoto.\n\nPulls all positive-balance address balances and computes inequality\nmetrics in Python. ~13k addresses on qrl, ~50 on qrl2 — fits comfortably\nin memory. Cached 10 minutes (distribution moves slowly).", "operationId": "supply_holders_distribution_api_v1_analytics_supply_holders_distribution_get", "parameters": [ { "name": "chain", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^(qrl|qrl2)$", "description": "Which chain to query: qrl (legacy PoW) or qrl2 (PoS EVM). Defaults to qrl2.", "default": "qrl2", "title": "Chain" }, "description": "Which chain to query: qrl (legacy PoW) or qrl2 (PoS EVM). Defaults to qrl2." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenericObject" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "apiKey": [] } ] } }, "/api/v1/analytics/supply/dormant-buckets": { "get": { "tags": [ "Analytics" ], "summary": "Supply Dormant Buckets", "description": "Positive-balance holders bucketed by last_seen age.\n\nBuckets: <1m / 1m-1y / 1-2y / 2-5y / >5y. Each returns holder-count +\ntotal-balance-% held — answers \"how much supply is in deeply-dormant\naddresses (likely lost)\".", "operationId": "supply_dormant_buckets_api_v1_analytics_supply_dormant_buckets_get", "parameters": [ { "name": "chain", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^(qrl|qrl2)$", "description": "Which chain to query: qrl (legacy PoW) or qrl2 (PoS EVM). Defaults to qrl2.", "default": "qrl2", "title": "Chain" }, "description": "Which chain to query: qrl (legacy PoW) or qrl2 (PoS EVM). Defaults to qrl2." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenericListResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "apiKey": [] } ] } }, "/api/v1/analytics/supply/age-daily": { "get": { "tags": [ "Analytics" ], "summary": "Supply Age Daily", "description": "Per-day supply-by-age buckets (HODL waves / dormant supply over time, mig 089).\n\nThe over-time companion to /supply/dormant-buckets: each day's positive-balance\nsupply split by last-activity age (<1m / 1m-1y / 1-2y / 2-5y / >5y), as % of\nsupply. Powers a stacked composition chart. Consensus-banned addresses (mig 077)\nare excluded by the backfill, so it matches the dormant-buckets snapshot.", "operationId": "supply_age_daily_api_v1_analytics_supply_age_daily_get", "parameters": [ { "name": "window", "in": "query", "required": false, "schema": { "type": "string", "description": "Look-back window with unit suffix (m=min, h=hour, d=day, w=week). Default 365d. Examples: 24h, 7d, 90d.", "default": "365d", "title": "Window" }, "description": "Look-back window with unit suffix (m=min, h=hour, d=day, w=week). Default 365d. Examples: 24h, 7d, 90d." }, { "name": "chain", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^(qrl|qrl2)$", "description": "Which chain to query: qrl (legacy PoW) or qrl2 (PoS EVM). Defaults to qrl2.", "default": "qrl2", "title": "Chain" }, "description": "Which chain to query: qrl (legacy PoW) or qrl2 (PoS EVM). Defaults to qrl2." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenericListResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "apiKey": [] } ] } }, "/api/v1/analytics/staking/daily": { "get": { "tags": [ "Analytics" ], "summary": "Staking Daily", "description": "Per-day PoS decentralisation (qrl2-only, mig 091): staking ratio %, active\nvalidator count, and validator-Nakamoto (min validators to control >33% of\nstake). From the per-epoch beacon balances; QRL Legacy (PoW) has no validators.", "operationId": "staking_daily_api_v1_analytics_staking_daily_get", "parameters": [ { "name": "window", "in": "query", "required": false, "schema": { "type": "string", "description": "Look-back window with unit suffix (m=min, h=hour, d=day, w=week). Default 365d. Examples: 24h, 7d, 90d.", "default": "365d", "title": "Window" }, "description": "Look-back window with unit suffix (m=min, h=hour, d=day, w=week). Default 365d. Examples: 24h, 7d, 90d." }, { "name": "chain", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^(qrl|qrl2)$", "description": "Which chain to query: qrl (legacy PoW) or qrl2 (PoS EVM). Defaults to qrl2.", "default": "qrl2", "title": "Chain" }, "description": "Which chain to query: qrl (legacy PoW) or qrl2 (PoS EVM). Defaults to qrl2." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenericListResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "apiKey": [] } ] } }, "/api/v1/analytics/staking/apr-daily": { "get": { "tags": [ "Analytics" ], "summary": "Staking Apr Daily", "description": "Per-day validator APR % (qrl2-only, mig 092) — net beacon rewards\n(rewards minus penalties) annualized over staked principal. Can be negative\non a low-participation testnet (inactivity leak). QRL Legacy (PoW) has no APR.", "operationId": "staking_apr_daily_api_v1_analytics_staking_apr_daily_get", "parameters": [ { "name": "window", "in": "query", "required": false, "schema": { "type": "string", "description": "Look-back window with unit suffix (m=min, h=hour, d=day, w=week). Default 365d. Examples: 24h, 7d, 90d.", "default": "365d", "title": "Window" }, "description": "Look-back window with unit suffix (m=min, h=hour, d=day, w=week). Default 365d. Examples: 24h, 7d, 90d." }, { "name": "chain", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^(qrl|qrl2)$", "description": "Which chain to query: qrl (legacy PoW) or qrl2 (PoS EVM). Defaults to qrl2.", "default": "qrl2", "title": "Chain" }, "description": "Which chain to query: qrl (legacy PoW) or qrl2 (PoS EVM). Defaults to qrl2." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenericListResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "apiKey": [] } ] } }, "/api/v1/analytics/staking/slashings-daily": { "get": { "tags": [ "Analytics" ], "summary": "Staking Slashings Daily", "description": "Per-day validator slashing count (qrl2-only). 0-filled flat-zero line on a\nhealthy network (QRL 2.0 has had zero slashings to date). QRL Legacy has none.", "operationId": "staking_slashings_daily_api_v1_analytics_staking_slashings_daily_get", "parameters": [ { "name": "window", "in": "query", "required": false, "schema": { "type": "string", "description": "Look-back window with unit suffix (m=min, h=hour, d=day, w=week). Default 365d. Examples: 24h, 7d, 90d.", "default": "365d", "title": "Window" }, "description": "Look-back window with unit suffix (m=min, h=hour, d=day, w=week). Default 365d. Examples: 24h, 7d, 90d." }, { "name": "chain", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^(qrl|qrl2)$", "description": "Which chain to query: qrl (legacy PoW) or qrl2 (PoS EVM). Defaults to qrl2.", "default": "qrl2", "title": "Chain" }, "description": "Which chain to query: qrl (legacy PoW) or qrl2 (PoS EVM). Defaults to qrl2." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenericListResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "apiKey": [] } ] } }, "/api/v1/analytics/supply/lorenz": { "get": { "tags": [ "Analytics" ], "summary": "Supply Lorenz", "description": "Lorenz-curve points (cumulative %-holders vs cumulative %-supply) + the\nexact Gini. Backs the /distribution Lorenz chart — the visual companion to\nthe Gini number. Down-sampled to ~100 points; computed on-demand over\nquantascan.address_summary (no new table). Cached 10 min.", "operationId": "supply_lorenz_api_v1_analytics_supply_lorenz_get", "parameters": [ { "name": "chain", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^(qrl|qrl2)$", "description": "Which chain to query: qrl (legacy PoW) or qrl2 (PoS EVM). Defaults to qrl2.", "default": "qrl2", "title": "Chain" }, "description": "Which chain to query: qrl (legacy PoW) or qrl2 (PoS EVM). Defaults to qrl2." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenericObject" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "apiKey": [] } ] } }, "/api/v1/analytics/supply/cohorts": { "get": { "tags": [ "Analytics" ], "summary": "Supply Cohorts", "description": "The ten \"ocean\" holder tiers (plankton → leviathan) by each wallet's\nABSOLUTE coin balance (whale ≥ 100,000, orca ≥ 40,000, up to leviathan\n≥ 5,000,000; the single ladder in app.core.tiers), with holder-count AND\nsupply-% per tier. On-demand over address_summary. Cached 10 min.", "operationId": "supply_cohorts_api_v1_analytics_supply_cohorts_get", "parameters": [ { "name": "individuals_only", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Exclude the wallets that are not a single private holder — custodial/treasury classes (exchange + foundation) and confirmed exchange deposit relays — the same set the /whales cohort excludes, so the size-tier 'whale' population matches the /whales count. Powers the 'Individuals only' toggle on the /distribution tier chart. Default false = all holders (consistent with the Gini/Nakamoto/top-N metrics on the same page).", "default": false, "title": "Individuals Only" }, "description": "Exclude the wallets that are not a single private holder — custodial/treasury classes (exchange + foundation) and confirmed exchange deposit relays — the same set the /whales cohort excludes, so the size-tier 'whale' population matches the /whales count. Powers the 'Individuals only' toggle on the /distribution tier chart. Default false = all holders (consistent with the Gini/Nakamoto/top-N metrics on the same page)." }, { "name": "chain", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^(qrl|qrl2)$", "description": "Which chain to query: qrl (legacy PoW) or qrl2 (PoS EVM). Defaults to qrl2.", "default": "qrl2", "title": "Chain" }, "description": "Which chain to query: qrl (legacy PoW) or qrl2 (PoS EVM). Defaults to qrl2." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenericObject" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "apiKey": [] } ] } }, "/api/v1/analytics/supply/entity-distribution": { "get": { "tags": [ "Analytics" ], "summary": "Supply Entity Distribution", "description": "Supply share per wallet entity-class (mig 080) + a recomputed\nconcentration EXCLUDING custodial/protocol entities. Answers \"are the big\nholders exchanges/foundation/pools or individuals?\". Joins\nquantascan.wallet_class with address_summary. Cached 10 min.", "operationId": "supply_entity_distribution_api_v1_analytics_supply_entity_distribution_get", "parameters": [ { "name": "chain", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^(qrl|qrl2)$", "description": "Which chain to query: qrl (legacy PoW) or qrl2 (PoS EVM). Defaults to qrl2.", "default": "qrl2", "title": "Chain" }, "description": "Which chain to query: qrl (legacy PoW) or qrl2 (PoS EVM). Defaults to qrl2." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenericObject" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "apiKey": [] } ] } }, "/api/v1/analytics/supply/distribution-timeline": { "get": { "tags": [ "Analytics" ], "summary": "Supply Distribution Timeline", "description": "Daily concentration timeseries (top-10 share, Gini, Nakamoto) from the\nforward-only snapshot table `etl_gold.distribution_daily` (mig 084).\nDegrades to an empty series if the table/job isn't live yet. Cached 10 min.", "operationId": "supply_distribution_timeline_api_v1_analytics_supply_distribution_timeline_get", "parameters": [ { "name": "window", "in": "query", "required": false, "schema": { "type": "string", "description": "Look-back window with unit suffix (m=min, h=hour, d=day, w=week). Default 90d. Examples: 24h, 7d, 90d.", "default": "90d", "title": "Window" }, "description": "Look-back window with unit suffix (m=min, h=hour, d=day, w=week). Default 90d. Examples: 24h, 7d, 90d." }, { "name": "chain", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^(qrl|qrl2)$", "description": "Which chain to query: qrl (legacy PoW) or qrl2 (PoS EVM). Defaults to qrl2.", "default": "qrl2", "title": "Chain" }, "description": "Which chain to query: qrl (legacy PoW) or qrl2 (PoS EVM). Defaults to qrl2." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenericListResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "apiKey": [] } ] } }, "/api/v1/analytics/supply/overview": { "get": { "tags": [ "Analytics" ], "summary": "Supply Overview", "description": "Combined cross-chain ecosystem-supply KPIs for the /supply hub page.\n\nChain-less by design (like every analytics endpoint): one migration-adjusted\ntotal across QRL Legacy + QRL 2.0, a 3-way \"where supply lives\" split, per-\nchain emission/cap, and the `migration_measurable` flag that drives the\n\"not yet measurable\" UI state (CLAUDE.md:153). Backed by\napp.core.supply_metrics.get_combined_supply_overview — existing Gold views\nonly, no new migration. Degrades to a zeroed shape if views are missing.", "operationId": "supply_overview_api_v1_analytics_supply_overview_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenericObject" } } } } }, "security": [ { "apiKey": [] } ] } }, "/api/v1/analytics/migration/summary": { "get": { "tags": [ "Analytics" ], "summary": "Migration Summary", "description": "Where the QRL → QRL 2.0 migration stands, for the /qrl2-migration tracker.\n\n`snapshot` = the frozen QRL legacy total (null until the operator runs\n`etl snapshot-legacy`). `claimed_coins` / `unclaimed_coins` are MEASURED —\nfrom on-chain claim rows, or from the registered escrow balance — and are\nnull (never 0) while neither source exists, with `measurable: false`.\n`invariant_delta_coins` (claimed + escrow − snapshot) checks the claim\nparser against the escrow once both exist. Backed by\napp.core.migration_status; degrades to nulls before migration 140.", "operationId": "migration_summary_api_v1_analytics_migration_summary_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenericObject" } } } } }, "security": [ { "apiKey": [] } ] } }, "/api/v1/analytics/supply/combined-curve": { "get": { "tags": [ "Analytics" ], "summary": "Supply Combined Curve", "description": "Stacked dual-series cumulative supply (QRL PoW + QRL2 PoS) per day.\n\nChain-less and ALWAYS full history — a cumulative total-supply curve only\nmakes sense from genesis, so no window parameter. QRL2 is plotted net of\nthe re-homed migration mirror so the cumulative line has no cutover jump\nonce the snapshot lands.", "operationId": "supply_combined_curve_api_v1_analytics_supply_combined_curve_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenericListResponse" } } } } }, "security": [ { "apiKey": [] } ] } }, "/api/v1/analytics/period-summary": { "get": { "tags": [ "Analytics" ], "summary": "Period Summary", "description": "QRL mainnet figures for one period: the data behind the weekly digest\nand the monthly \"State of QRL\" report.\n\nA week answers \"what moved?\": what the top 300 holders did (who reduced,\nwho added, how much went to exchanges), exchange flows, the largest\ntransfers and coin-days destroyed against the usual level. A month adds\nactivity, mining, supply and a separate QRL 2.0 testnet section. `sections`\nlists what the period carries; a section that could not be computed is\nnull and listed in `unavailable_sections`. `complete` is false while the\nperiod is still running.", "operationId": "period_summary_api_v1_analytics_period_summary_get", "parameters": [ { "name": "period", "in": "query", "required": true, "schema": { "type": "string", "maxLength": 8, "description": "ISO week (2026-W41), month (2026-10), year (2026) or 'all' (QRL genesis up to today)", "title": "Period" }, "description": "ISO week (2026-W41), month (2026-10), year (2026) or 'all' (QRL genesis up to today)" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenericObject" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "apiKey": [] } ] } }, "/api/v1/analytics/pq-signatures": { "get": { "tags": [ "Analytics" ], "summary": "Pq Signatures", "description": "Number of transactions signed with post-quantum cryptography, per chain.\n\nQRL counts every XMSS-signed transaction since its 2018 genesis. Coinbase\nblock rewards are minted by the protocol and carry no signature, so they\nare not counted, nor are unsigned rows in the genesis block. QRL 2.0\ncounts its ML-DSA-87-signed transactions. `mainnet_signed_txs` sums\nmainnet chains only: while QRL 2.0 runs on testnet, its count is reported\nin `chains` but left out of the total. `degraded` is true when a source\nquery failed; treat the counts as unavailable then.", "operationId": "pq_signatures_api_v1_analytics_pq_signatures_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PqSignatureStats" } } } } }, "security": [ { "apiKey": [] } ] } }, "/api/v1/analytics/whales/summary": { "get": { "tags": [ "Analytics" ], "summary": "Whales Summary", "description": "Hero KPIs for the /whales page: whale-count, total whale balance,\nmovers in 7d, biggest tx in 30d.\n\nWhale threshold can be the legacy 100K fixed value (when threshold_pct\nis omitted) or computed as a percentage of current total supply via\nthe slider on /whales. Dynamic mode keeps the \"Whale\" badge on\n/address/[hash] in sync only when called without threshold_pct.", "operationId": "whales_summary_api_v1_analytics_whales_summary_get", "parameters": [ { "name": "threshold_pct", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "number", "maximum": 50, "minimum": 0.0001 }, { "type": "null" } ], "description": "If set, threshold = this %% of current total supply. None = legacy 100K floor.", "title": "Threshold Pct" }, "description": "If set, threshold = this %% of current total supply. None = legacy 100K floor." }, { "name": "chain", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^(qrl|qrl2)$", "description": "Which chain to query: qrl (legacy PoW) or qrl2 (PoS EVM). Defaults to qrl2.", "default": "qrl2", "title": "Chain" }, "description": "Which chain to query: qrl (legacy PoW) or qrl2 (PoS EVM). Defaults to qrl2." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenericObject" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "apiKey": [] } ] } }, "/api/v1/analytics/whales/leaderboard": { "get": { "tags": [ "Analytics" ], "summary": "Whales Leaderboard", "description": "Top N wallets by balance, with 7-day net-flow delta.\n\nPowers the \"accumulating / distributing / stable\" insight on the\n/whales page. Delta uses address_balance_daily (W2 MV).", "operationId": "whales_leaderboard_api_v1_analytics_whales_leaderboard_get", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 200, "minimum": 1, "default": 50, "title": "Limit" } }, { "name": "threshold_pct", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "number", "maximum": 50, "minimum": 0.0001 }, { "type": "null" } ], "title": "Threshold Pct" } }, { "name": "chain", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^(qrl|qrl2)$", "description": "Which chain to query: qrl (legacy PoW) or qrl2 (PoS EVM). Defaults to qrl2.", "default": "qrl2", "title": "Chain" }, "description": "Which chain to query: qrl (legacy PoW) or qrl2 (PoS EVM). Defaults to qrl2." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenericListResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "apiKey": [] } ] } }, "/api/v1/analytics/whales/biggest": { "get": { "tags": [ "Analytics" ], "summary": "Whales Biggest Txs", "description": "Largest single transactions by value within the time window.\n\nDistinct from /transactions/whales (which is a recency feed) — this\nis sorted-by-value within a window. Used for \"biggest tx today / 7d /\n30d / all-time\" feed. Not threshold-aware on purpose.", "operationId": "whales_biggest_txs_api_v1_analytics_whales_biggest_get", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "default": 20, "title": "Limit" } }, { "name": "chain", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^(qrl|qrl2)$", "description": "Which chain to query: qrl (legacy PoW) or qrl2 (PoS EVM). Defaults to qrl2.", "default": "qrl2", "title": "Chain" }, "description": "Which chain to query: qrl (legacy PoW) or qrl2 (PoS EVM). Defaults to qrl2." }, { "name": "window", "in": "query", "required": false, "schema": { "type": "string", "description": "Look-back window with unit suffix (m=min, h=hour, d=day, w=week). Default 30d. Examples: 24h, 7d, 90d.", "default": "30d", "title": "Window" }, "description": "Look-back window with unit suffix (m=min, h=hour, d=day, w=week). Default 30d. Examples: 24h, 7d, 90d." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenericListResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "apiKey": [] } ] } }, "/api/v1/analytics/whales/sentiment": { "get": { "tags": [ "Analytics" ], "summary": "Whales Sentiment", "description": "Signed net-flow across the whale cohort over the window.\n\nPowers the bull/bear barometer hero on /whales. Positive net_flow =\nwhales accumulating; negative = distributing. Also returns split\ncounts (accumulators vs distributors) so the UI can show \"X buying /\nY selling\" alongside the headline figure.", "operationId": "whales_sentiment_api_v1_analytics_whales_sentiment_get", "parameters": [ { "name": "threshold_pct", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "number", "maximum": 50, "minimum": 0.0001 }, { "type": "null" } ], "title": "Threshold Pct" } }, { "name": "chain", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^(qrl|qrl2)$", "description": "Which chain to query: qrl (legacy PoW) or qrl2 (PoS EVM). Defaults to qrl2.", "default": "qrl2", "title": "Chain" }, "description": "Which chain to query: qrl (legacy PoW) or qrl2 (PoS EVM). Defaults to qrl2." }, { "name": "window", "in": "query", "required": false, "schema": { "type": "string", "description": "Look-back window with unit suffix (m=min, h=hour, d=day, w=week). Default 7d. Examples: 24h, 7d, 90d.", "default": "7d", "title": "Window" }, "description": "Look-back window with unit suffix (m=min, h=hour, d=day, w=week). Default 7d. Examples: 24h, 7d, 90d." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenericObject" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "apiKey": [] } ] } }, "/api/v1/analytics/whales/exchange-flow": { "get": { "tags": [ "Analytics" ], "summary": "Whales Exchange Flow", "description": "Net flow between the whale cohort and labeled exchanges over the window.\n\ndeposits (whale→exchange) = distribution/bearish; withdrawals\n(exchange→whale) = accumulation/bullish; net = withdrawals − deposits. A\nvery large window reads as \"all time\" (`all_time=true`). Depends on curated\nexchange labels — returns a neutral `exchange_labeled=false` shape on chains\nwithout any (e.g. QRL2 testnet).", "operationId": "whales_exchange_flow_api_v1_analytics_whales_exchange_flow_get", "parameters": [ { "name": "threshold_pct", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "number", "maximum": 50, "minimum": 0.0001 }, { "type": "null" } ], "title": "Threshold Pct" } }, { "name": "chain", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^(qrl|qrl2)$", "description": "Which chain to query: qrl (legacy PoW) or qrl2 (PoS EVM). Defaults to qrl2.", "default": "qrl2", "title": "Chain" }, "description": "Which chain to query: qrl (legacy PoW) or qrl2 (PoS EVM). Defaults to qrl2." }, { "name": "window", "in": "query", "required": false, "schema": { "type": "string", "description": "Look-back window with unit suffix (m=min, h=hour, d=day, w=week). Default 30d. Examples: 24h, 7d, 90d.", "default": "30d", "title": "Window" }, "description": "Look-back window with unit suffix (m=min, h=hour, d=day, w=week). Default 30d. Examples: 24h, 7d, 90d." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenericObject" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "apiKey": [] } ] } }, "/api/v1/analytics/whales/cohorts": { "get": { "tags": [ "Analytics" ], "summary": "Whales Cohorts", "description": "Per-cohort breakdown of the whale population.\n\nBuckets: new / active / hodler / distributor / dormant. Each entry\nreturns holder-count + balance-share-of-cohort. Sums to ~100%.", "operationId": "whales_cohorts_api_v1_analytics_whales_cohorts_get", "parameters": [ { "name": "threshold_pct", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "number", "maximum": 50, "minimum": 0.0001 }, { "type": "null" } ], "title": "Threshold Pct" } }, { "name": "chain", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^(qrl|qrl2)$", "description": "Which chain to query: qrl (legacy PoW) or qrl2 (PoS EVM). Defaults to qrl2.", "default": "qrl2", "title": "Chain" }, "description": "Which chain to query: qrl (legacy PoW) or qrl2 (PoS EVM). Defaults to qrl2." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenericObject" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "apiKey": [] } ] } }, "/api/v1/analytics/whales/heatmap": { "get": { "tags": [ "Analytics" ], "summary": "Whales Heatmap", "description": "Daily count of whales who moved at all, last N days.\n\nReturns one row per calendar day in the window (including zero days)\nwith movers, volume and normalised intensity (0..1). Frontend renders\nas a GitHub-style calendar heatmap.", "operationId": "whales_heatmap_api_v1_analytics_whales_heatmap_get", "parameters": [ { "name": "threshold_pct", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "number", "maximum": 50, "minimum": 0.0001 }, { "type": "null" } ], "title": "Threshold Pct" } }, { "name": "chain", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^(qrl|qrl2)$", "description": "Which chain to query: qrl (legacy PoW) or qrl2 (PoS EVM). Defaults to qrl2.", "default": "qrl2", "title": "Chain" }, "description": "Which chain to query: qrl (legacy PoW) or qrl2 (PoS EVM). Defaults to qrl2." }, { "name": "window", "in": "query", "required": false, "schema": { "type": "string", "description": "Look-back window with unit suffix (m=min, h=hour, d=day, w=week). Default 90d. Examples: 24h, 7d, 90d.", "default": "90d", "title": "Window" }, "description": "Look-back window with unit suffix (m=min, h=hour, d=day, w=week). Default 90d. Examples: 24h, 7d, 90d." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenericListResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "apiKey": [] } ] } }, "/api/v1/analytics/whales/sparklines": { "get": { "tags": [ "Analytics" ], "summary": "Whales Sparklines", "description": "Per-whale daily balance series, reconstructed from daily flows.\n\nReturns top-N whales by current balance with a chronological\n[{day, balance}] series. Used to render inline 30d trend sparklines\nnext to each leaderboard row.", "operationId": "whales_sparklines_api_v1_analytics_whales_sparklines_get", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "default": 25, "title": "Limit" } }, { "name": "threshold_pct", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "number", "maximum": 50, "minimum": 0.0001 }, { "type": "null" } ], "title": "Threshold Pct" } }, { "name": "chain", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^(qrl|qrl2)$", "description": "Which chain to query: qrl (legacy PoW) or qrl2 (PoS EVM). Defaults to qrl2.", "default": "qrl2", "title": "Chain" }, "description": "Which chain to query: qrl (legacy PoW) or qrl2 (PoS EVM). Defaults to qrl2." }, { "name": "window", "in": "query", "required": false, "schema": { "type": "string", "description": "Look-back window with unit suffix (m=min, h=hour, d=day, w=week). Default 30d. Examples: 24h, 7d, 90d.", "default": "30d", "title": "Window" }, "description": "Look-back window with unit suffix (m=min, h=hour, d=day, w=week). Default 30d. Examples: 24h, 7d, 90d." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenericListResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "apiKey": [] } ] } }, "/api/v1/analytics/whales/movers": { "get": { "tags": [ "Analytics" ], "summary": "Whales Movers", "description": "Biggest accumulators & distributors within the whale cohort.\n\nReplaces the old \"top wallets by balance\" leaderboard (a duplicate of\n/richlist) with a behavioural angle: who moved the most net coins over\nthe window. Exchanges are excluded so the lists are individual holders.", "operationId": "whales_movers_api_v1_analytics_whales_movers_get", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 50, "minimum": 1, "default": 10, "title": "Limit" } }, { "name": "threshold_pct", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "number", "maximum": 50, "minimum": 0.0001 }, { "type": "null" } ], "title": "Threshold Pct" } }, { "name": "chain", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^(qrl|qrl2)$", "description": "Which chain to query: qrl (legacy PoW) or qrl2 (PoS EVM). Defaults to qrl2.", "default": "qrl2", "title": "Chain" }, "description": "Which chain to query: qrl (legacy PoW) or qrl2 (PoS EVM). Defaults to qrl2." }, { "name": "window", "in": "query", "required": false, "schema": { "type": "string", "description": "Look-back window with unit suffix (m=min, h=hour, d=day, w=week). Default 7d. Examples: 24h, 7d, 90d.", "default": "7d", "title": "Window" }, "description": "Look-back window with unit suffix (m=min, h=hour, d=day, w=week). Default 7d. Examples: 24h, 7d, 90d." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenericObject" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "apiKey": [] } ] } }, "/api/v1/analytics/home/highlights": { "get": { "tags": [ "Analytics" ], "summary": "Home Highlights", "description": "Curated \"Today's highlights\" for the home page.\n\n4 small facts: biggest tx recent, busiest hour today, newest whale,\nblock cadence. Each fact returns null when no data — frontend hides\nnull entries gracefully so a sparse chain doesn't break the page.", "operationId": "home_highlights_api_v1_analytics_home_highlights_get", "parameters": [ { "name": "chain", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^(qrl|qrl2)$", "description": "Which chain to query: qrl (legacy PoW) or qrl2 (PoS EVM). Defaults to qrl2.", "default": "qrl2", "title": "Chain" }, "description": "Which chain to query: qrl (legacy PoW) or qrl2 (PoS EVM). Defaults to qrl2." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenericObject" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "apiKey": [] } ] } }, "/api/v1/analytics/network/new-vs-returning-daily": { "get": { "tags": [ "Analytics" ], "summary": "New Vs Returning Daily", "description": "Per-day new-address vs returning-address breakdown.\n\nAdoption-health signal — when returning > new sustained, the network is\nseeing real organic stickiness rather than churn.", "operationId": "new_vs_returning_daily_api_v1_analytics_network_new_vs_returning_daily_get", "parameters": [ { "name": "chain", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^(qrl|qrl2)$", "description": "Which chain to query: qrl (legacy PoW) or qrl2 (PoS EVM). Defaults to qrl2.", "default": "qrl2", "title": "Chain" }, "description": "Which chain to query: qrl (legacy PoW) or qrl2 (PoS EVM). Defaults to qrl2." }, { "name": "window", "in": "query", "required": false, "schema": { "type": "string", "description": "Look-back window with unit suffix (m=min, h=hour, d=day, w=week). Default 30d. Examples: 24h, 7d, 90d.", "default": "30d", "title": "Window" }, "description": "Look-back window with unit suffix (m=min, h=hour, d=day, w=week). Default 30d. Examples: 24h, 7d, 90d." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenericListResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "apiKey": [] } ] } }, "/api/v1/analytics/dashboard/summary": { "get": { "tags": [ "Analytics" ], "summary": "Dashboard Summary", "description": "Single-call bundle for the landing page. Per chain returns:\n - headline counts (blocks, txs, tokens, validators)\n - latest_block_time\n - 24h fee_burned (qrl2)\n - 7-day activity sparkline data\n\nDesigned so the homepage server-component can fetch once + render\neverything above-the-fold without orchestrating multiple calls.", "operationId": "dashboard_summary_api_v1_analytics_dashboard_summary_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsDashboardSummary" } } } } }, "security": [ { "apiKey": [] } ] } }, "/api/v1/richlist": { "get": { "tags": [ "Richlist" ], "summary": "Get Richlist", "description": "Cross-chain richlist — both chains interleaved, ranked by whole-coin balance.\n\nPagination is offset-based (stable Gold projection). Each row carries its own\n`chain` so the client picks the right decimals / address link / unit.", "operationId": "get_richlist_api_v1_richlist_get", "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "default": 1, "title": "Page" } }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "default": 25, "title": "Page Size" } }, { "name": "chain", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "pattern": "^(qrl|qrl2)$" }, { "type": "null" } ], "description": "Optional chain filter: qrl, qrl2, or omitted = both (mixed).", "title": "Chain" }, "description": "Optional chain filter: qrl, qrl2, or omitted = both (mixed)." }, { "name": "with_labels", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Include `label` + `label_category` per row.", "default": false, "title": "With Labels" }, "description": "Include `label` + `label_category` per row." }, { "name": "with_delta_30d", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Include `received_30d` + `sent_30d` (30-day net flow, both chains). Zero means no movement in the window; `null` means the enrichment was not requested.", "default": false, "title": "With Delta 30D" }, "description": "Include `received_30d` + `sent_30d` (30-day net flow, both chains). Zero means no movement in the window; `null` means the enrichment was not requested." }, { "name": "positive_only", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Holders only (balance > 0). Default true — richlist semantics.", "default": true, "title": "Positive Only" }, "description": "Holders only (balance > 0). Default true — richlist semantics." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedOffset_RichlistRow_" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "apiKey": [] } ] } }, "/api/v1/price/qrl": { "get": { "tags": [ "Market price" ], "summary": "Latest QRL market price", "description": "Returns the most recent cached QRL price for the requested fiat / crypto. Cache TTL is ~10 minutes; a background task refreshes from CoinGecko every 5 minutes. `price` is null on cold start — callers should render a placeholder rather than treat null as an error.", "operationId": "get_qrl_price_api_v1_price_qrl_get", "parameters": [ { "name": "vs", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^[a-zA-Z]{3,5}$", "description": "Currency code: usd, eur, or btc.", "default": "usd", "title": "Vs" }, "description": "Currency code: usd, eur, or btc." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QrlPriceResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "apiKey": [] } ] } }, "/api/v1/price/qrl/history": { "get": { "tags": [ "Market price" ], "summary": "QRL price history (downsampled OHLC)", "description": "Time-bucketed QRL price over the last N days. Data comes from `etl_silver.market_prices` (mig 050) — written every 5 minutes by the same poller that fills the live cache. Empty `items` on cold start (no data persisted yet) or pre-mig-050 deploys.", "operationId": "get_qrl_price_history_api_v1_price_qrl_history_get", "parameters": [ { "name": "vs", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^[a-zA-Z]{3,5}$", "description": "Currency code: usd, eur, or btc.", "default": "usd", "title": "Vs" }, "description": "Currency code: usd, eur, or btc." }, { "name": "interval", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^[0-9]{1,2}[mhd]$", "description": "Bucket size: 5m | 15m | 1h | 4h | 1d.", "default": "1h", "title": "Interval" }, "description": "Bucket size: 5m | 15m | 1h | 4h | 1d." }, { "name": "window", "in": "query", "required": false, "schema": { "type": "string", "description": "Look-back window for the QRL price history (D4 duration).", "default": "30d", "title": "Window" }, "description": "Look-back window for the QRL price history (D4 duration)." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QrlPriceHistoryResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "apiKey": [] } ] } }, "/api/v1/trends/google": { "get": { "tags": [ "Trends" ], "summary": "Google Trends relative interest over time", "description": "Relative search interest (0-100) per keyword per day for QRL and quantum-computing topics. Interest is normalized within Google's query window — relative, not absolute volume.", "operationId": "google_trends_api_v1_trends_google_get", "parameters": [ { "name": "window", "in": "query", "required": false, "schema": { "type": "string", "description": "Look-back window for trends. Default 90d.", "default": "90d", "title": "Window" }, "description": "Look-back window for trends. Default 90d." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ItemsList_GoogleTrendPoint_" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "apiKey": [] } ] } }, "/api/v1/trends/reddit": { "get": { "tags": [ "Trends" ], "summary": "Reddit discussion volume over time", "description": "Reddit posts/comments/score per keyword per day, summed across the tracked subreddits. Empty while the Reddit source is dormant.", "operationId": "reddit_trends_api_v1_trends_reddit_get", "parameters": [ { "name": "window", "in": "query", "required": false, "schema": { "type": "string", "description": "Look-back window for trends. Default 90d.", "default": "90d", "title": "Window" }, "description": "Look-back window for trends. Default 90d." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ItemsList_RedditTrendPoint_" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "apiKey": [] } ] } }, "/api/v1/usage": { "get": { "tags": [ "Usage" ], "summary": "Plan and quota of the calling API key", "description": "Plan, today's quota and the last 30 days for the calling API key's\naccount or organisation. Requires `Authorization: Bearer qs_…`.", "operationId": "api_self_usage_api_v1_usage_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiSelfUsageResponse" } } } } }, "security": [ { "apiKey": [] } ] } }, "/api/v1/compat/etherscan": { "get": { "tags": [ "Explorer compatible" ], "summary": "Explorer-compatible API (module/action) for QRL 2.0", "description": "Accepts the widely used `?module=…&action=…&apikey=…` explorer API so existing client libraries and scripts work against QRL 2.0 by changing only the base URL (`https://quantascan.io/api`). An API key is required (`apikey=qs_…`).\n\nSupported: **account** balance, balancemulti (100), balancehistory, txlist, txlistinternal, tokentx, tokennfttx, token1155tx, txsBeaconWithdrawal, tokenbalance, addresstokenbalance, addresstokennftbalance, addresstokennftinventory · **contract** getabi, getsourcecode, getcontractcreation · **transaction** getstatus, gettxreceiptstatus · **block** getblocknobytime, getblockreward, getblockcountdown · **logs** getLogs · **stats** ethsupply, tokensupply · **gastracker** gasoracle · **proxy** eth_blockNumber, eth_getBlockByNumber, eth_getTransactionByHash, eth_getTransactionReceipt, eth_call, eth_getCode, eth_getStorageAt, eth_gasPrice, eth_estimateGas, eth_getTransactionCount, eth_sendRawTransaction, eth_getBlockTransactionCountByNumber, eth_getTransactionByBlockNumberAndIndex (translated to the node's qrl_* methods) · **getapilimit**.\n\nAmounts are in planck (1 Quanta = 1e18 planck); gas prices in gastracker are in shor (1e9 planck). Addresses are `Q` + 40 or 128 hex; `0x` + the same hex is accepted as input. Errors use real HTTP status codes with the `{status, message, result}` body.", "operationId": "explorer_compat_api_v1_compat_etherscan_get", "parameters": [ { "name": "module", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "account, contract, transaction, block, logs, stats, gastracker, proxy, getapilimit", "title": "Module" }, "description": "account, contract, transaction, block, logs, stats, gastracker, proxy, getapilimit" }, { "name": "action", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Action within the module, e.g. txlist.", "title": "Action" }, "description": "Action within the module, e.g. txlist." }, { "name": "chainid", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional. Must be the QRL 2.0 chain id.", "title": "Chainid" }, "description": "Optional. Must be the QRL 2.0 chain id." }, { "name": "apikey", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Your API key (qs_…).", "title": "Apikey" }, "description": "Your API key (qs_…)." } ], "responses": { "200": { "description": "`{status, message, result}` (or a JSON-RPC envelope for module=proxy).", "content": { "application/json": { "schema": {} } } }, "400": { "description": "Invalid module, action or parameter." }, "401": { "description": "Missing or invalid API key." }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "429": { "description": "Daily quota or per-minute limit reached." }, "503": { "description": "Temporarily unavailable." } }, "security": [ { "apiKey": [] } ] } } }, "components": { "securitySchemes": { "apiKey": { "type": "http", "scheme": "bearer", "description": "Your personal Quantascan API key (starts with qs_)." } }, "schemas": { "AddressBalanceItem": { "properties": { "address": { "type": "string", "title": "Address", "description": "Normalised address (lowercase hex)." }, "balance": { "type": "string", "title": "Balance", "description": "Balance in base units (planck on qrl2, shor on qrl)." }, "balance_display": { "type": "string", "title": "Balance Display", "description": "Balance in Quanta (qrl2) / QRL (qrl), exact decimal." }, "tx_count": { "type": "integer", "title": "Tx Count", "description": "Transactions sent + received (qrl2 counts validator withdrawals as received)." }, "first_seen": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "First Seen", "description": "ISO-8601 UTC of the first activity, null when never seen." }, "last_seen": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Last Seen", "description": "ISO-8601 UTC of the latest activity, null when never seen." }, "found": { "type": "boolean", "title": "Found", "description": "False when the address has no indexed activity (balance is then '0')." } }, "type": "object", "required": [ "address", "balance", "balance_display", "tx_count", "found" ], "title": "AddressBalanceItem" }, "AddressDetail": { "properties": { "chain": { "type": "string", "title": "Chain" }, "network": { "type": "string", "title": "Network" }, "address": { "type": "string", "title": "Address" }, "balance": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Balance", "description": "UInt256 as decimal string (smallest unit)" }, "total_received": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Total Received", "description": "UInt256 as decimal string" }, "total_sent": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Total Sent", "description": "UInt256 as decimal string" }, "total_fees_paid": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Total Fees Paid", "description": "UInt256 as decimal string" }, "tx_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Tx Count" }, "tx_received_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Tx Received Count" }, "tx_sent_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Tx Sent Count" }, "first_seen": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "First Seen" }, "last_seen": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Last Seen" }, "master_address": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Master Address", "description": "QRL only --master that registered this slave, if any." }, "wallet_class": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Wallet Class" }, "wallet_class_method": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Wallet Class Method" }, "wallet_class_reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Wallet Class Reason" }, "is_deployer": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Is Deployer" }, "withdrawal_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Withdrawal Count" }, "withdrawal_total": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Withdrawal Total" }, "internal_tx_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Internal Tx Count" } }, "additionalProperties": true, "type": "object", "required": [ "chain", "network", "address" ], "title": "AddressDetail", "description": "Address summary from `quantascan.address_summary` Gold view. Includes\nper-chain extras (validator flags on qrl2, master/slave key info on qrl)\nvia `extra='allow'`." }, "AddressInternalTxItem": { "properties": { "height": { "type": "integer", "title": "Height" }, "block_hash": { "type": "string", "title": "Block Hash" }, "tx_hash": { "type": "string", "title": "Tx Hash" }, "trace_address": { "type": "string", "title": "Trace Address" }, "call_type": { "type": "string", "title": "Call Type" }, "from_addr": { "type": "string", "title": "From Addr" }, "to_addr": { "type": "string", "title": "To Addr" }, "value": { "type": "string", "title": "Value" }, "timestamp": { "type": "string", "title": "Timestamp" }, "direction": { "type": "string", "title": "Direction" } }, "additionalProperties": true, "type": "object", "required": [ "height", "block_hash", "tx_hash", "trace_address", "call_type", "from_addr", "to_addr", "value", "timestamp", "direction" ], "title": "AddressInternalTxItem", "description": "One internal (contract-initiated) native-Quanta transfer touching an\naddress — a nested EVM call frame from `debug_traceBlockByNumber`\n(mig 111). Disjoint from the top-level tx feed: the parent tx's own\n`value` lives in etl_silver.transactions, these are only the nested\nframes, so surfacing them here never double-shows the top-level value." }, "AddressInternalTxPaginated": { "properties": { "items": { "items": { "$ref": "#/components/schemas/AddressInternalTxItem" }, "type": "array", "title": "Items" }, "total": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Total" }, "page": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Page" }, "page_size": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Page Size" }, "total_pages": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Total Pages" } }, "type": "object", "title": "AddressInternalTxPaginated" }, "AddressName": { "properties": { "address": { "type": "string", "title": "Address" }, "chain": { "type": "string", "title": "Chain" }, "name": { "type": "string", "title": "Name" }, "source": { "type": "string", "title": "Source", "description": "'official_label' or 'nickname'" }, "category": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Category", "description": "Label category when source='official_label'" }, "nickname": { "type": "string", "title": "Nickname", "description": "The auto-generated name, regardless of source" }, "assigned": { "type": "boolean", "title": "Assigned", "description": "Deprecated, always true. Under spec v3 the nickname is a pure function of the address and final the moment it is computed." }, "attempt": { "type": "integer", "title": "Attempt", "description": "Deprecated, always 0. Spec v3 has no collision attempts.", "default": 0 }, "ruleset_version": { "type": "string", "title": "Ruleset Version" } }, "type": "object", "required": [ "address", "chain", "name", "source", "nickname", "assigned", "ruleset_version" ], "title": "AddressName", "description": "The display name for one address, resolved the way the UI resolves it.\n\n`source` tells the consumer what they got: a curated Quantascan label, or\nthe deterministic auto-nickname. A signed-in user's private name tag is\nnever part of this response — it is personal data, not a public name." }, "AddressNamesList": { "properties": { "items": { "items": { "$ref": "#/components/schemas/AddressName" }, "type": "array", "title": "Items" }, "count": { "type": "integer", "title": "Count", "default": 0 } }, "type": "object", "title": "AddressNamesList", "description": "Bulk name resolution result." }, "AddressStats": { "properties": { "chain": { "type": "string", "title": "Chain" }, "network": { "type": "string", "title": "Network" }, "total_addresses": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Total Addresses" }, "active_24h": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Active 24H" } }, "additionalProperties": true, "type": "object", "required": [ "chain", "network" ], "title": "AddressStats" }, "AddressSummaryRow": { "properties": { "address": { "type": "string", "title": "Address" }, "chain": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Chain" }, "network": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Network" }, "balance": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Balance" }, "total_received": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Total Received" }, "total_sent": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Total Sent" }, "total_fees_paid": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Total Fees Paid" }, "tx_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Tx Count" }, "tx_received_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Tx Received Count" }, "tx_sent_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Tx Sent Count" }, "first_seen": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "First Seen" }, "last_seen": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Last Seen" }, "label": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Label" }, "label_category": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Label Category" }, "received_30d": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Received 30D" }, "sent_30d": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Sent 30D" } }, "additionalProperties": true, "type": "object", "required": [ "address" ], "title": "AddressSummaryRow", "description": "One row of the address leaderboard / richlist.\n\nRead from quantascan.address_summary (Gold). UInt256 money columns are\nStrings to preserve precision through JSON. `extra=\"allow\"` keeps the\nshape chain-polymorphic (qrl vs qrl2 may carry extra columns) without a\nstrict-validation failure, while the declared fields give the frontend a\ntyped contract via `make api-types`." }, "AddressTopActiveResponse": { "properties": { "addresses": { "items": { "$ref": "#/components/schemas/AddressSummaryRow" }, "type": "array", "title": "Addresses" }, "total": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Total" }, "sort_by": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Sort By" }, "page": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Page" }, "page_size": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Page Size" }, "q": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Q" }, "chain": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Chain" }, "network": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Network" } }, "type": "object", "title": "AddressTopActiveResponse", "description": "Top-N addresses ranked by configurable sort_by field." }, "AnalyticsDashboardSummary": { "properties": {}, "additionalProperties": true, "type": "object", "title": "AnalyticsDashboardSummary", "description": "Composite dashboard bundle --many fields, all optional." }, "AnalyticsGasTrends": { "properties": { "items": { "items": { "additionalProperties": true, "type": "object" }, "type": "array", "title": "Items" }, "days": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Days" }, "chain": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Chain" } }, "type": "object", "title": "AnalyticsGasTrends" }, "AnalyticsHealthCheck": { "properties": { "chains": { "additionalProperties": true, "type": "object", "title": "Chains" }, "checked_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Checked At" } }, "additionalProperties": true, "type": "object", "title": "AnalyticsHealthCheck", "description": "Multi-chain health snapshot for /api/v1/analytics/health." }, "ApiKeyUsagePoint": { "properties": { "day": { "type": "string", "title": "Day" }, "count": { "type": "integer", "title": "Count" } }, "type": "object", "required": [ "day", "count" ], "title": "ApiKeyUsagePoint" }, "ApiSelfUsageResponse": { "properties": { "plan": { "type": "string", "title": "Plan" }, "subject": { "type": "string", "enum": [ "user", "org" ], "title": "Subject" }, "key_name": { "type": "string", "title": "Key Name" }, "daily_limit": { "type": "integer", "title": "Daily Limit" }, "burst_per_minute": { "type": "integer", "title": "Burst Per Minute" }, "used_today": { "type": "integer", "title": "Used Today" }, "remaining_today": { "type": "integer", "title": "Remaining Today" }, "reset_at": { "type": "integer", "title": "Reset At", "description": "Unix time the daily quota resets (00:00 UTC)" }, "days": { "items": { "$ref": "#/components/schemas/ApiKeyUsagePoint" }, "type": "array", "title": "Days", "description": "Last 30 days, all keys of the subject" } }, "type": "object", "required": [ "plan", "subject", "key_name", "daily_limit", "burst_per_minute", "used_today", "remaining_today", "reset_at" ], "title": "ApiSelfUsageResponse", "description": "What `GET /api/v1/usage` returns to the key that calls it — the\nequivalent of Etherscan's `getapilimit`, but with the plan spelled out." }, "BalanceComponents": { "properties": { "received": { "type": "string", "title": "Received", "description": "Native value received: transfers in, coinbase rewards (qrl), validator withdrawals (qrl2), internal/contract transfers in, contract-creation value, genesis allocation." }, "sent": { "type": "string", "title": "Sent", "description": "Native value sent: transfers out + internal/contract transfers out." }, "fees": { "type": "string", "title": "Fees", "description": "Transaction fees paid as sender." } }, "type": "object", "required": [ "received", "sent", "fees" ], "title": "BalanceComponents", "description": "How the balance was assembled — the same terms as the current balance\nin `address_summary` (received − sent − fees), so a client can audit it." }, "BatchBalancesRequest": { "properties": { "addresses": { "items": { "type": "string" }, "type": "array", "maxItems": 100, "minItems": 1, "title": "Addresses", "description": "1–100 addresses of THIS chain. qrl2: 'Q' + 40 hex (41 chars) or 'Q' + 128 hex (129 chars, 64-byte addresses); qrl: 'Q' + 78 hex (79 chars). Case-insensitive; duplicates are answered once." } }, "type": "object", "required": [ "addresses" ], "title": "BatchBalancesRequest" }, "BatchBalancesResponse": { "properties": { "chain": { "type": "string", "title": "Chain" }, "network": { "type": "string", "title": "Network" }, "base_unit": { "type": "string", "title": "Base Unit", "description": "'planck' (qrl2) or 'shor' (qrl)." }, "display_unit": { "type": "string", "title": "Display Unit", "description": "'Quanta' (qrl2) or 'QRL' (qrl)." }, "indexed_tip_height": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Indexed Tip Height", "description": "Newest fully indexed block when the balances were read (null if unknown)." }, "items": { "items": { "$ref": "#/components/schemas/AddressBalanceItem" }, "type": "array", "title": "Items" } }, "type": "object", "required": [ "chain", "network", "base_unit", "display_unit", "items" ], "title": "BatchBalancesResponse" }, "BeaconAttestationDaily": { "properties": { "items": { "items": { "$ref": "#/components/schemas/BeaconAttestationDailyBucket" }, "type": "array", "title": "Items" }, "days": { "type": "integer", "title": "Days" }, "network": { "type": "string", "title": "Network" } }, "type": "object", "required": [ "items", "days", "network" ], "title": "BeaconAttestationDaily", "description": "Daily attestation participation rate for the validator-health chart." }, "BeaconAttestationDailyBucket": { "properties": { "day": { "type": "string", "title": "Day", "description": "ISO date (YYYY-MM-DD)" }, "included": { "type": "integer", "title": "Included", "default": 0 }, "expected": { "type": "integer", "title": "Expected", "default": 0 }, "participation_rate": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Participation Rate", "description": "included/expected as a percentage (0-100)" } }, "type": "object", "required": [ "day" ], "title": "BeaconAttestationDailyBucket", "description": "One day of network-wide attestation participation." }, "BeaconBlock": { "properties": { "slot": { "type": "integer", "title": "Slot" }, "epoch": { "type": "integer", "title": "Epoch" }, "block_root": { "type": "string", "title": "Block Root" }, "parent_root": { "type": "string", "title": "Parent Root" }, "proposer_index": { "type": "integer", "title": "Proposer Index" }, "execution_block_number": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Execution Block Number" }, "execution_block_hash": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Execution Block Hash" }, "attestations_count": { "type": "integer", "title": "Attestations Count", "default": 0 }, "deposits_count": { "type": "integer", "title": "Deposits Count", "default": 0 }, "voluntary_exits_count": { "type": "integer", "title": "Voluntary Exits Count", "default": 0 }, "proposer_slashings_count": { "type": "integer", "title": "Proposer Slashings Count", "default": 0 }, "attester_slashings_count": { "type": "integer", "title": "Attester Slashings Count", "default": 0 }, "sync_committee_participants": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Sync Committee Participants" }, "timestamp": { "type": "string", "title": "Timestamp" }, "proposer_withdrawal_address": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Proposer Withdrawal Address", "description": "Reward recipient of this block's proposer — the execution (withdrawal) address where the validator's staking rewards are paid (EIP-4895 withdrawals), decoded from its withdrawal_credentials (last 20 bytes of an execution-type credential). Null when the validator uses a non-execution credential or its registry snapshot is unavailable. Many validators can share one recipient." } }, "additionalProperties": true, "type": "object", "required": [ "slot", "epoch", "block_root", "parent_root", "proposer_index", "timestamp" ], "title": "BeaconBlock", "description": "One slot's beacon block (header + body counts). Skipped slots\ndon't appear. Sourced from `quantascan.qrl2_beacon_blocks`." }, "BeaconBlocksList": { "properties": { "items": { "items": { "$ref": "#/components/schemas/BeaconBlock" }, "type": "array", "title": "Items" }, "limit": { "type": "integer", "title": "Limit" }, "network": { "type": "string", "title": "Network" }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Next Cursor", "description": "Opaque pagination token — pass back unchanged as ?cursor=... to fetch the next (older) page. Null when there are no older blocks. The token encodes the slot internally; callers MUST NOT decode or construct it." } }, "type": "object", "required": [ "items", "limit", "network" ], "title": "BeaconBlocksList" }, "BeaconEpoch": { "properties": { "epoch": { "type": "integer", "title": "Epoch" }, "first_slot": { "type": "integer", "title": "First Slot" }, "last_slot": { "type": "integer", "title": "Last Slot" }, "start_time": { "type": "string", "title": "Start Time" }, "end_time": { "type": "string", "title": "End Time" }, "slots_total": { "type": "integer", "title": "Slots Total", "default": 128 }, "blocks_proposed": { "type": "integer", "title": "Blocks Proposed", "default": 0 }, "unique_proposers": { "type": "integer", "title": "Unique Proposers", "default": 0 }, "attestations_count": { "type": "integer", "title": "Attestations Count", "default": 0 }, "deposits_count": { "type": "integer", "title": "Deposits Count", "default": 0 }, "voluntary_exits_count": { "type": "integer", "title": "Voluntary Exits Count", "default": 0 }, "proposer_slashings_count": { "type": "integer", "title": "Proposer Slashings Count", "default": 0 }, "attester_slashings_count": { "type": "integer", "title": "Attester Slashings Count", "default": 0 }, "avg_sync_participants": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Avg Sync Participants" }, "sync_participation_pct": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Sync Participation Pct", "description": "avg_sync_participants / SyncCommitteeSize(128) × 100." }, "status": { "type": "string", "enum": [ "complete", "current", "pending" ], "title": "Status", "description": "Wall-clock lifecycle status." }, "finality_state": { "anyOf": [ { "type": "string", "enum": [ "finalized", "justified" ] }, { "type": "null" } ], "title": "Finality State", "description": "Casper-FFG state: 'finalized' | 'justified' | null." }, "indexed": { "type": "boolean", "title": "Indexed", "default": false } }, "type": "object", "required": [ "epoch", "first_slot", "last_slot", "start_time", "end_time", "status" ], "title": "BeaconEpoch", "description": "One consensus epoch (128 slots × 60s = 2h 8min on QRL 2.0). Headline\ncounters come Gold-first from `quantascan.qrl2_epoch_summary`; finality\nis joined from `quantascan.qrl2_beacon_finality`. `indexed=False` rows\nare synthetic placeholders for epochs the beacon-indexer hasn't reached." }, "BeaconEpochDetail": { "properties": { "epoch": { "type": "integer", "title": "Epoch" }, "first_slot": { "type": "integer", "title": "First Slot" }, "last_slot": { "type": "integer", "title": "Last Slot" }, "start_time": { "type": "string", "title": "Start Time" }, "end_time": { "type": "string", "title": "End Time" }, "slots_total": { "type": "integer", "title": "Slots Total", "default": 128 }, "blocks_indexed": { "type": "integer", "title": "Blocks Indexed", "default": 0 }, "status": { "type": "string", "enum": [ "complete", "current", "pending" ], "title": "Status" }, "finality_state": { "anyOf": [ { "type": "string", "enum": [ "finalized", "justified" ] }, { "type": "null" } ], "title": "Finality State" }, "blocks": { "items": { "$ref": "#/components/schemas/BeaconBlock" }, "type": "array", "title": "Blocks" }, "network": { "type": "string", "title": "Network" } }, "type": "object", "required": [ "epoch", "first_slot", "last_slot", "start_time", "end_time", "status", "blocks", "network" ], "title": "BeaconEpochDetail", "description": "Single epoch: counters + the 128-slot grid (`blocks` = indexed slots,\nmissing slots are skipped/empty and filled client-side)." }, "BeaconEpochsList": { "properties": { "items": { "items": { "$ref": "#/components/schemas/BeaconEpoch" }, "type": "array", "title": "Items" }, "limit": { "type": "integer", "title": "Limit" }, "network": { "type": "string", "title": "Network" }, "current_epoch": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Current Epoch" }, "latest_data_epoch": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Latest Data Epoch", "description": "Highest epoch with indexed data (None when none indexed)." }, "indexer_lag_epochs": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Indexer Lag Epochs", "description": "current_epoch − latest_data_epoch; drives a catch-up banner." }, "slots_per_epoch": { "type": "integer", "title": "Slots Per Epoch", "default": 128 }, "seconds_per_slot": { "type": "integer", "title": "Seconds Per Slot", "default": 60 }, "sync_committee_size": { "type": "integer", "title": "Sync Committee Size", "default": 128 }, "finalized_epoch": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Finalized Epoch" }, "current_justified_epoch": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Current Justified Epoch" }, "finality_lag_epochs": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Finality Lag Epochs" }, "finality_snapshot_age_seconds": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Finality Snapshot Age Seconds" }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Next Cursor", "description": "Opaque token for the next (older) page; null at the end." } }, "type": "object", "required": [ "items", "limit", "network" ], "title": "BeaconEpochsList", "description": "Newest-first epoch listing. Cursor paging via the opaque `next_cursor`\ntoken (decode/encode is server-side; clients relay it verbatim)." }, "BeaconSlashing": { "properties": { "slot": { "type": "integer", "title": "Slot" }, "epoch": { "type": "integer", "title": "Epoch" }, "slashing_type": { "type": "string", "title": "Slashing Type", "description": "'proposer' | 'attester'" }, "slashed_validator_index": { "type": "integer", "title": "Slashed Validator Index" }, "reporter_proposer_index": { "type": "integer", "title": "Reporter Proposer Index" }, "timestamp": { "type": "string", "title": "Timestamp" } }, "type": "object", "required": [ "slot", "epoch", "slashing_type", "slashed_validator_index", "reporter_proposer_index", "timestamp" ], "title": "BeaconSlashing", "description": "Proposer or attester slashing event." }, "BeaconSlashingsDaily": { "properties": { "items": { "items": { "$ref": "#/components/schemas/BeaconSlashingsDailyBucket" }, "type": "array", "title": "Items" }, "days": { "type": "integer", "title": "Days" }, "network": { "type": "string", "title": "Network" }, "total_proposer": { "type": "integer", "title": "Total Proposer", "default": 0 }, "total_attester": { "type": "integer", "title": "Total Attester", "default": 0 } }, "type": "object", "required": [ "items", "days", "network" ], "title": "BeaconSlashingsDaily", "description": "Daily slashings histogram for the /penalties bar chart. Distinct\nfrom `BeaconSlashingsList`: buckets carry per-day counts, not events." }, "BeaconSlashingsDailyBucket": { "properties": { "day": { "type": "string", "title": "Day", "description": "ISO date (YYYY-MM-DD)" }, "proposer_count": { "type": "integer", "title": "Proposer Count", "default": 0 }, "attester_count": { "type": "integer", "title": "Attester Count", "default": 0 } }, "type": "object", "required": [ "day" ], "title": "BeaconSlashingsDailyBucket", "description": "One day in the slashings histogram (empty days included)." }, "BeaconSlashingsList": { "properties": { "items": { "items": { "$ref": "#/components/schemas/BeaconSlashing" }, "type": "array", "title": "Items" }, "limit": { "type": "integer", "title": "Limit" }, "network": { "type": "string", "title": "Network" }, "total": { "type": "integer", "title": "Total", "description": "Total slashings matching the filter (ignores `limit`). The table shows the latest `limit`; `total` is the all-time count so the UI can say 'N of M'.", "default": 0 } }, "type": "object", "required": [ "items", "limit", "network" ], "title": "BeaconSlashingsList" }, "BeaconSummary": { "properties": { "network": { "type": "string", "title": "Network" }, "head_slot": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Head Slot" }, "blocks_indexed": { "type": "integer", "title": "Blocks Indexed", "default": 0 }, "validators_known": { "type": "integer", "title": "Validators Known", "default": 0 }, "validators_active": { "type": "integer", "title": "Validators Active", "default": 0 }, "validators_slashed": { "type": "integer", "title": "Validators Slashed", "default": 0 }, "slashings_total": { "type": "integer", "title": "Slashings Total", "default": 0 }, "total_active_effective_balance_gwei": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Total Active Effective Balance Gwei" }, "total_active_effective_balance_qrl": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Total Active Effective Balance Qrl" }, "indexer_lag_slots": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Indexer Lag Slots" }, "finalized_epoch": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Finalized Epoch" }, "current_justified_epoch": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Current Justified Epoch" }, "previous_justified_epoch": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Previous Justified Epoch" }, "finality_snapshot_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Finality Snapshot At" }, "finality_lag_epochs": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Finality Lag Epochs" }, "finality_snapshot_age_seconds": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Finality Snapshot Age Seconds" } }, "type": "object", "required": [ "network" ], "title": "BeaconSummary", "description": "Headline metrics for a beacon-overview widget." }, "BeaconValidatorRegistry": { "properties": { "validator_index": { "type": "integer", "title": "Validator Index" }, "pubkey": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Pubkey" }, "status": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Status" }, "effective_balance": { "type": "integer", "title": "Effective Balance", "default": 0 }, "balance": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Balance" }, "slashed": { "type": "boolean", "title": "Slashed", "default": false }, "activation_eligibility_epoch": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Activation Eligibility Epoch" }, "activation_epoch": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Activation Epoch" }, "exit_epoch": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Exit Epoch" }, "withdrawable_epoch": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Withdrawable Epoch" }, "withdrawal_credentials": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Withdrawal Credentials" }, "snapshot_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Snapshot At" } }, "additionalProperties": true, "type": "object", "required": [ "validator_index" ], "title": "BeaconValidatorRegistry", "description": "Latest registry snapshot for one validator. ML-DSA-87 pubkey\nsurfaced as opaque hex string." }, "BlockDetail": { "properties": { "chain": { "type": "string", "title": "Chain" }, "network": { "type": "string", "title": "Network" }, "height": { "type": "integer", "title": "Height" }, "block_hash": { "type": "string", "title": "Block Hash" }, "timestamp": { "type": "string", "title": "Timestamp", "description": "ISO-8601 UTC" } }, "additionalProperties": true, "type": "object", "required": [ "chain", "network", "height", "block_hash", "timestamp" ], "title": "BlockDetail", "description": "Full block row from `quantascan.blocks` (Silver FINAL). Column-set\nvaries per chain; `extra='allow'` keeps chain-specific fields visible." }, "BlockRewardDailyItem": { "properties": { "day": { "type": "string", "title": "Day" }, "block_count": { "type": "integer", "title": "Block Count", "default": 0 }, "subsidy_shor": { "type": "string", "title": "Subsidy Shor", "default": "0" }, "fees_shor": { "type": "string", "title": "Fees Shor", "default": "0" }, "total_reward_shor": { "type": "string", "title": "Total Reward Shor", "default": "0" } }, "type": "object", "required": [ "day" ], "title": "BlockRewardDailyItem" }, "BlockRewardDailyList": { "properties": { "items": { "items": { "$ref": "#/components/schemas/BlockRewardDailyItem" }, "type": "array", "title": "Items" }, "count": { "type": "integer", "title": "Count", "default": 0 } }, "type": "object", "title": "BlockRewardDailyList" }, "BlockSummary": { "properties": { "chain": { "type": "string", "title": "Chain" }, "network": { "type": "string", "title": "Network" }, "height": { "type": "integer", "title": "Height" }, "block_hash": { "type": "string", "title": "Block Hash" }, "timestamp": { "type": "string", "title": "Timestamp", "description": "ISO-8601 UTC" }, "tx_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Tx Count" }, "miner": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Miner" }, "gas_used": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Gas Used" } }, "additionalProperties": true, "type": "object", "required": [ "chain", "network", "height", "block_hash", "timestamp" ], "title": "BlockSummary", "description": "Minimal block record returned by /blocks/latest and inside paginated\nlists. Extra fields are allowed because qrl2 carries gas/withdrawal\ncounts that qrl doesn't." }, "BlockTransactionsList": { "properties": { "items": { "items": { "$ref": "#/components/schemas/TransactionDetailResponse" }, "type": "array", "title": "Items" }, "total": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Total" }, "block_height": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Block Height" }, "chain": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Chain" }, "network": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Network" } }, "type": "object", "title": "BlockTransactionsList", "description": "All transactions in a single block." }, "ChainStats": { "properties": { "total_blocks": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Total Blocks" }, "min_height": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Min Height" }, "max_height": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Max Height" }, "total_txs": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Total Txs", "description": "Raw sum of block tx_count. On QRL this includes the coinbase (block reward) of every block; use non_coinbase_txs for a transaction count." }, "non_coinbase_txs": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Non Coinbase Txs", "description": "Transactions excluding coinbase block rewards. Equal to total_txs on QRL 2.0, which has no coinbase transaction." }, "latest_block_time": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Latest Block Time", "description": "ISO-8601 UTC" }, "avg_tx_count": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Avg Tx Count", "description": "non_coinbase_txs / total_blocks." } }, "type": "object", "title": "ChainStats", "description": "Pre-aggregated chain headline stats (Gold)." }, "ContractAbi": { "properties": { "address": { "type": "string", "title": "Address" }, "chain": { "type": "string", "title": "Chain" }, "network": { "type": "string", "title": "Network" }, "verified_at": { "type": "string", "title": "Verified At" }, "compiler": { "type": "string", "title": "Compiler" }, "compiler_version": { "type": "string", "title": "Compiler Version" }, "abi": { "items": { "additionalProperties": true, "type": "object" }, "type": "array", "title": "Abi" } }, "type": "object", "required": [ "address", "chain", "network", "verified_at", "compiler", "compiler_version", "abi" ], "title": "ContractAbi", "description": "GET /api/v1/contracts/{addr}/abi response." }, "ContractCallRequest": { "properties": { "function_name": { "type": "string", "title": "Function Name", "description": "ABI function name; must exist and be view/pure." }, "data": { "type": "string", "title": "Data", "description": "Hex-encoded ABI call data (with 0x prefix)." }, "block": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Block", "description": "Block tag: 'latest', 'earliest', 'pending', or hex height.", "default": "latest" } }, "type": "object", "required": [ "function_name", "data" ], "title": "ContractCallRequest", "description": "POST /api/v1/contracts/{addr}/call body.\n\nThe frontend ABI-encodes the call via viem and sends both the\nfunction name (for backend validation) and the pre-encoded `data`.\nBackend rejects unknown functions, state-changing functions, and\ncontracts without a verified ABI." }, "ContractCallResult": { "properties": { "function_name": { "type": "string", "title": "Function Name" }, "function_signature": { "type": "string", "title": "Function Signature", "description": "Solidity-style signature for the called function, e.g. 'balanceOf(address)'." }, "raw": { "type": "string", "title": "Raw", "description": "Hex-encoded raw `qrl_call` return value (with 0x prefix)." }, "block": { "type": "string", "title": "Block" }, "abi_word_bytes": { "type": "integer", "title": "Abi Word Bytes", "description": "ABI slot width of `raw` (and of the calldata): 32 on 20-byte-address networks, 64 on 64-byte-address (VM64) networks. Decode `raw` with this word size.", "default": 32 } }, "type": "object", "required": [ "function_name", "function_signature", "raw", "block" ], "title": "ContractCallResult", "description": "POST /api/v1/contracts/{addr}/call response." }, "ContractClone": { "properties": { "address": { "type": "string", "title": "Address" }, "chain": { "type": "string", "title": "Chain" }, "network": { "type": "string", "title": "Network" }, "bytecode_hash": { "type": "string", "title": "Bytecode Hash" }, "deployer": { "type": "string", "title": "Deployer" }, "deployment_block": { "type": "integer", "title": "Deployment Block" }, "is_verified": { "type": "boolean", "title": "Is Verified" } }, "type": "object", "required": [ "address", "chain", "network", "bytecode_hash", "deployer", "deployment_block", "is_verified" ], "title": "ContractClone", "description": "One row of `/clones` response." }, "ContractClones": { "properties": { "bytecode_hash": { "type": "string", "title": "Bytecode Hash" }, "items": { "items": { "$ref": "#/components/schemas/ContractClone" }, "type": "array", "title": "Items" }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Next Cursor" }, "total": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Total" } }, "type": "object", "required": [ "bytecode_hash" ], "title": "ContractClones", "description": "GET /api/v1/contracts/{addr}/clones response." }, "ContractDetail": { "properties": {}, "additionalProperties": true, "type": "object", "title": "ContractDetail", "description": "Deployment record + (optional) token metadata." }, "ContractLogsList": { "properties": { "items": { "items": { "additionalProperties": true, "type": "object" }, "type": "array", "title": "Items" }, "limit": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Limit" }, "offset": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Offset" }, "address": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Address" } }, "type": "object", "title": "ContractLogsList" }, "ContractRow": { "properties": { "address": { "type": "string", "title": "Address" }, "deployer": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Deployer" }, "deployment_tx": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Deployment Tx" }, "deployment_block": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Deployment Block" }, "bytecode_hash": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Bytecode Hash" }, "created_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Created At" }, "is_verified": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Is Verified" }, "compiler": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Compiler" }, "compiler_version": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Compiler Version" }, "optimization_enabled": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Optimization Enabled" }, "optimization_runs": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Optimization Runs" }, "license": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "License" }, "match_grade": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Match Grade" }, "verified_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Verified At" }, "main_contract": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Main Contract" }, "token_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Token Name" }, "token_symbol": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Token Symbol" }, "token_decimals": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Token Decimals" }, "is_qrc20": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Is Qrc20" }, "is_qrc721": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Is Qrc721" }, "is_qrc1155": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Is Qrc1155" }, "tx_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Tx Count" }, "balance_planck": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Balance Planck" }, "last_seen": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Last Seen" }, "events_24h": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Events 24H" }, "similar_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Similar Count" } }, "additionalProperties": true, "type": "object", "required": [ "address" ], "title": "ContractRow", "description": "One row of the /smart-contracts list — deployment registry joined with\nverification (mig 064), token metadata, address aggregate and 24h log\nactivity. `extra=\"allow\"` keeps the shape forward-compatible (the repo may\nadd columns) without breaking the typed client." }, "ContractSource": { "properties": { "address": { "type": "string", "title": "Address" }, "chain": { "type": "string", "title": "Chain" }, "network": { "type": "string", "title": "Network" }, "verified_at": { "type": "string", "title": "Verified At" }, "compiler": { "type": "string", "title": "Compiler" }, "compiler_version": { "type": "string", "title": "Compiler Version" }, "optimization_enabled": { "type": "boolean", "title": "Optimization Enabled" }, "optimization_runs": { "type": "integer", "title": "Optimization Runs" }, "evm_version": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Evm Version" }, "license": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "License" }, "main_contract": { "type": "string", "title": "Main Contract" }, "source_files": { "additionalProperties": { "type": "string" }, "type": "object", "title": "Source Files", "description": "path → source." }, "abi": { "items": { "additionalProperties": true, "type": "object" }, "type": "array", "title": "Abi" }, "constructor_args_hex": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Constructor Args Hex" }, "libraries": { "anyOf": [ { "additionalProperties": { "type": "string" }, "type": "object" }, { "type": "null" } ], "title": "Libraries" }, "metadata": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Metadata", "description": "Parsed metadata.json from compiler output." }, "metadata_ipfs_hash": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Metadata Ipfs Hash" }, "match_grade": { "type": "string", "title": "Match Grade", "description": "unverified | partial | full" }, "creation_bytecode_sha256": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Creation Bytecode Sha256" }, "runtime_bytecode_sha256": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Runtime Bytecode Sha256" }, "verifier_version": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Verifier Version" } }, "type": "object", "required": [ "address", "chain", "network", "verified_at", "compiler", "compiler_version", "optimization_enabled", "optimization_runs", "main_contract", "source_files", "abi", "match_grade" ], "title": "ContractSource", "description": "GET /api/v1/contracts/{addr}/source response." }, "ContractsPaginated": { "properties": { "items": { "items": { "$ref": "#/components/schemas/ContractRow" }, "type": "array", "title": "Items" }, "total": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Total" }, "limit": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Limit" }, "offset": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Offset" }, "network": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Network" } }, "type": "object", "title": "ContractsPaginated" }, "ContractsSummary": { "properties": { "network": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Network" }, "total_deployed": { "type": "integer", "title": "Total Deployed", "default": 0 }, "deployed_24h": { "type": "integer", "title": "Deployed 24H", "default": 0 }, "active_24h": { "type": "integer", "title": "Active 24H", "default": 0 }, "token_contracts": { "type": "integer", "title": "Token Contracts", "default": 0 } }, "additionalProperties": true, "type": "object", "title": "ContractsSummary", "description": "KPI bundle for the /smart-contracts hub hero strip." }, "DailyActivityItem": { "properties": { "day": { "type": "string", "title": "Day", "description": "ISO date (YYYY-MM-DD)" }, "block_count": { "type": "integer", "title": "Block Count" }, "tx_count": { "type": "integer", "title": "Tx Count", "description": "Raw sum of block tx_count. On QRL this includes one coinbase (block reward) per block; use non_coinbase_tx_count." }, "non_coinbase_tx_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Non Coinbase Tx Count", "description": "Transactions that day excluding coinbase block rewards." }, "total_gas_used": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Total Gas Used" } }, "type": "object", "required": [ "day", "block_count", "tx_count" ], "title": "DailyActivityItem", "description": "One day's roll-up from `quantascan.daily_activity`." }, "DailyWithdrawalItem": { "properties": { "day": { "type": "string", "title": "Day" }, "withdrawal_count": { "type": "integer", "title": "Withdrawal Count" }, "total_amount": { "type": "string", "title": "Total Amount" }, "unique_recipients": { "type": "integer", "title": "Unique Recipients" } }, "type": "object", "required": [ "day", "withdrawal_count", "total_amount", "unique_recipients" ], "title": "DailyWithdrawalItem" }, "DailyWithdrawalsList": { "properties": { "items": { "items": { "$ref": "#/components/schemas/DailyWithdrawalItem" }, "type": "array", "title": "Items" }, "count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Count" } }, "type": "object", "title": "DailyWithdrawalsList" }, "EventLogItem": { "properties": { "address": { "type": "string", "title": "Address", "description": "Emitting contract." }, "topics": { "items": { "type": "string" }, "type": "array", "title": "Topics", "description": "Indexed topics, topic0 first: 0x + 64 hex on 20-byte-address networks, 0x + 128 hex (64-byte slots) on VM64 networks." }, "data": { "type": "string", "title": "Data", "description": "Non-indexed data, 0x-hex." }, "block_height": { "type": "integer", "title": "Block Height" }, "block_hash": { "type": "string", "title": "Block Hash" }, "tx_hash": { "type": "string", "title": "Tx Hash" }, "tx_index": { "type": "integer", "title": "Tx Index" }, "log_index": { "type": "integer", "title": "Log Index" }, "timestamp": { "type": "string", "title": "Timestamp" } }, "type": "object", "required": [ "address", "topics", "data", "block_height", "block_hash", "tx_hash", "tx_index", "log_index", "timestamp" ], "title": "EventLogItem" }, "EventLogsResponse": { "properties": { "chain": { "type": "string", "const": "qrl2", "title": "Chain", "default": "qrl2" }, "network": { "type": "string", "title": "Network" }, "from_block": { "type": "integer", "title": "From Block" }, "to_block": { "type": "integer", "title": "To Block" }, "items": { "items": { "$ref": "#/components/schemas/EventLogItem" }, "type": "array", "title": "Items" }, "limit": { "type": "integer", "title": "Limit" }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Next Cursor", "description": "Opaque token for the next page (ascending block order); null when exhausted." }, "has_more": { "type": "boolean", "title": "Has More" } }, "type": "object", "required": [ "network", "from_block", "to_block", "items", "limit", "has_more" ], "title": "EventLogsResponse" }, "FeeBurnDailyList": { "properties": { "items": { "items": { "additionalProperties": true, "type": "object" }, "type": "array", "title": "Items" }, "days": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Days" }, "network": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Network" } }, "type": "object", "title": "FeeBurnDailyList" }, "FeeBurnSummary": { "properties": { "network": { "type": "string", "title": "Network" }, "total_planck": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Total Planck", "default": "0" }, "total_qrl2": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Total Qrl2", "default": "0" }, "total_blocks": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Total Blocks", "default": 0 }, "planck_24h": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Planck 24H" }, "planck_7d": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Planck 7D" }, "planck_30d": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Planck 30D" }, "latest_day": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Latest Day" } }, "additionalProperties": true, "type": "object", "required": [ "network" ], "title": "FeeBurnSummary", "description": "All-time totals + 24h/7d/30d windows for QRL2 fee-burn." }, "GasOracleResponse": { "properties": { "chain": { "type": "string", "const": "qrl2", "title": "Chain", "default": "qrl2" }, "network": { "type": "string", "title": "Network" }, "last_block": { "type": "integer", "title": "Last Block", "description": "Newest indexed block the estimate is based on." }, "last_block_timestamp": { "type": "string", "title": "Last Block Timestamp" }, "last_block_base_fee": { "type": "string", "title": "Last Block Base Fee", "description": "Base fee per gas of `last_block`, planck." }, "last_block_gas_used": { "type": "integer", "title": "Last Block Gas Used" }, "last_block_gas_limit": { "type": "integer", "title": "Last Block Gas Limit" }, "next_base_fee": { "type": "string", "title": "Next Base Fee", "description": "Base fee per gas of the NEXT block, planck — exact EIP-1559 rule (elasticity 2, change denominator 8), validated against every indexed qrl2 block." }, "next_base_fee_shor": { "type": "string", "title": "Next Base Fee Shor", "description": "`next_base_fee` in shor (exact decimal)." }, "slow": { "$ref": "#/components/schemas/GasPrioritySuggestion" }, "standard": { "$ref": "#/components/schemas/GasPrioritySuggestion" }, "fast": { "$ref": "#/components/schemas/GasPrioritySuggestion" }, "suggested_max_fee_per_gas": { "type": "string", "title": "Suggested Max Fee Per Gas", "description": "2 × next_base_fee + standard priority fee, planck (the usual wallet default; covers six consecutive full blocks of base-fee growth)." }, "sample_blocks": { "type": "integer", "title": "Sample Blocks", "description": "Number of blocks the priority-fee sample spans." }, "sample_txs": { "type": "integer", "title": "Sample Txs", "description": "Successful transactions in the sample." }, "sample_from_block": { "type": "integer", "title": "Sample From Block" }, "insufficient_data": { "type": "boolean", "title": "Insufficient Data", "description": "True when fewer than the minimum number of transactions were observed; suggestions then fall back to the node's own oracle or 0." }, "node_max_priority_fee": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Node Max Priority Fee", "description": "The node's own `qrl_maxPriorityFeePerGas` answer in planck, when reachable." } }, "type": "object", "required": [ "network", "last_block", "last_block_timestamp", "last_block_base_fee", "last_block_gas_used", "last_block_gas_limit", "next_base_fee", "next_base_fee_shor", "slow", "standard", "fast", "suggested_max_fee_per_gas", "sample_blocks", "sample_txs", "sample_from_block", "insufficient_data" ], "title": "GasOracleResponse" }, "GasPrioritySuggestion": { "properties": { "planck": { "type": "string", "title": "Planck", "description": "Suggested max priority fee per gas, in planck." }, "shor": { "type": "string", "title": "Shor", "description": "Same amount in shor (1 shor = 1e9 planck — QRL's 'gwei')." }, "percentile": { "type": "integer", "title": "Percentile", "description": "Percentile of observed priority fees this suggestion uses." } }, "type": "object", "required": [ "planck", "shor", "percentile" ], "title": "GasPrioritySuggestion" }, "GenericListResponse": { "properties": { "items": { "items": { "additionalProperties": true, "type": "object" }, "type": "array", "title": "Items" }, "total": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Total" }, "limit": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Limit" }, "offset": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Offset" }, "page": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Page" }, "has_next": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Has Next" }, "has_prev": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Has Prev" }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Next Cursor" } }, "additionalProperties": true, "type": "object", "title": "GenericListResponse", "description": "Paginated list with mixed offset+cursor pagination conventions.\nItem shape is loose; use a specific `XxxPaginated` when shape is fixed." }, "GenericObject": { "properties": {}, "additionalProperties": true, "type": "object", "title": "GenericObject", "description": "Catch-all loose dict. Use sparingly --prefer named models when the\nshape is stable. OpenAPI sees this as `{additionalProperties: true}`." }, "GoogleTrendPoint": { "properties": { "day": { "type": "string", "title": "Day", "description": "ISO date (YYYY-MM-DD) the reading represents" }, "keyword": { "type": "string", "title": "Keyword", "description": "Search term, e.g. 'QRL' or 'XMSS'" }, "interest": { "type": "number", "title": "Interest", "description": "Relative search interest, 0-100" } }, "type": "object", "required": [ "day", "keyword", "interest" ], "title": "GoogleTrendPoint", "description": "One Google Trends reading: relative search interest (0-100) for a keyword\non a given day. Interest is normalized within Google's query window, so it\nis RELATIVE, not absolute volume (surfaced as a caveat on /trends)." }, "HTTPValidationError": { "properties": { "detail": { "items": { "$ref": "#/components/schemas/ValidationError" }, "type": "array", "title": "Detail" } }, "type": "object", "title": "HTTPValidationError" }, "HistoricalBalanceResponse": { "properties": { "chain": { "type": "string", "title": "Chain" }, "network": { "type": "string", "title": "Network" }, "address": { "type": "string", "title": "Address" }, "block": { "type": "integer", "title": "Block", "description": "Block height the balance is valid AFTER (all transactions in this block applied)." }, "block_hash": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Block Hash" }, "timestamp": { "type": "string", "title": "Timestamp", "description": "ISO-8601 UTC timestamp of that block." }, "balance": { "type": "string", "title": "Balance", "description": "Balance in base units (planck / shor)." }, "balance_display": { "type": "string", "title": "Balance Display", "description": "Balance in Quanta (qrl2) / QRL (qrl)." }, "components": { "$ref": "#/components/schemas/BalanceComponents" }, "consensus_override": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Consensus Override", "description": "Set when a consensus rule force-zeroes this address at this height (QRL hard fork #3 banned address); the balance is then '0', matching the node." }, "indexed_tip_height": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Indexed Tip Height" } }, "type": "object", "required": [ "chain", "network", "address", "block", "timestamp", "balance", "balance_display", "components" ], "title": "HistoricalBalanceResponse" }, "ItemsList_DailyActivityItem_": { "properties": { "items": { "items": { "$ref": "#/components/schemas/DailyActivityItem" }, "type": "array", "title": "Items" } }, "type": "object", "required": [ "items" ], "title": "ItemsList[DailyActivityItem]" }, "ItemsList_GenericObject_": { "properties": { "items": { "items": { "$ref": "#/components/schemas/GenericObject" }, "type": "array", "title": "Items" } }, "type": "object", "required": [ "items" ], "title": "ItemsList[GenericObject]" }, "ItemsList_GoogleTrendPoint_": { "properties": { "items": { "items": { "$ref": "#/components/schemas/GoogleTrendPoint" }, "type": "array", "title": "Items" } }, "type": "object", "required": [ "items" ], "title": "ItemsList[GoogleTrendPoint]" }, "ItemsList_RedditTrendPoint_": { "properties": { "items": { "items": { "$ref": "#/components/schemas/RedditTrendPoint" }, "type": "array", "title": "Items" } }, "type": "object", "required": [ "items" ], "title": "ItemsList[RedditTrendPoint]" }, "LabelDirectory": { "properties": { "items": { "items": { "$ref": "#/components/schemas/LabelDirectoryItem" }, "type": "array", "title": "Items" }, "total": { "type": "integer", "title": "Total", "default": 0 }, "chain": { "type": "string", "title": "Chain" } }, "type": "object", "required": [ "chain" ], "title": "LabelDirectory", "description": "Every curated official label for a chain, for local joining." }, "LabelDirectoryItem": { "properties": { "address": { "type": "string", "title": "Address" }, "label": { "type": "string", "title": "Label" }, "category": { "type": "string", "title": "Category" } }, "type": "object", "required": [ "address", "label", "category" ], "title": "LabelDirectoryItem" }, "MiningSummary": { "properties": { "chain": { "type": "string", "title": "Chain", "default": "qrl" }, "network": { "type": "string", "title": "Network", "default": "mainnet" }, "difficulty": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Difficulty" }, "hash_power": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Hash Power" }, "block_time_mean": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Block Time Mean" }, "block_time_sd": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Block Time Sd" }, "block_last_reward_shor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Block Last Reward Shor" }, "coins_emitted_shor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Coins Emitted Shor" }, "max_supply_qrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Max Supply Qrl" }, "emission_pct": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Emission Pct" }, "stats_updated_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Stats Updated At" }, "total_blocks": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Total Blocks" }, "last_block_time": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Last Block Time" }, "miner_count": { "type": "integer", "title": "Miner Count", "default": 0 }, "pool_count": { "type": "integer", "title": "Pool Count", "default": 0 }, "node_tip_height": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Node Tip Height" }, "indexed_height": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Indexed Height" }, "index_lag_blocks": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Index Lag Blocks" }, "is_fully_indexed": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Is Fully Indexed" } }, "additionalProperties": true, "type": "object", "title": "MiningSummary", "description": "KPI bundle for the QRL-legacy Mining overview page.\n\nNetwork-health fields (difficulty / hash_power / block_time_*) come from the\nnode via GetStats (etl_silver.qrl_network_stats, mig 104) and are None when\nthe mining-stats poller hasn't run yet. coins_emitted / coins_total_supply /\nblock_last_reward are shor strings (precision). Counts come from the\nwallet-class + chain-stats views." }, "NetworkStatsDailyItem": { "properties": { "day": { "type": "string", "title": "Day" }, "avg_difficulty": { "type": "number", "title": "Avg Difficulty", "default": 0 }, "avg_hash_power": { "type": "number", "title": "Avg Hash Power", "default": 0 }, "max_difficulty": { "type": "number", "title": "Max Difficulty", "default": 0 }, "max_hash_power": { "type": "number", "title": "Max Hash Power", "default": 0 } }, "type": "object", "required": [ "day" ], "title": "NetworkStatsDailyItem" }, "NetworkStatsDailyList": { "properties": { "items": { "items": { "$ref": "#/components/schemas/NetworkStatsDailyItem" }, "type": "array", "title": "Items" }, "count": { "type": "integer", "title": "Count", "default": 0 } }, "type": "object", "title": "NetworkStatsDailyList" }, "NftHoldingItem": { "properties": { "contract": { "type": "string", "title": "Contract", "description": "Collection (token contract) address." }, "standard": { "type": "string", "enum": [ "721", "1155" ], "title": "Standard", "description": "QRC-721 or QRC-1155." }, "token_id": { "type": "string", "title": "Token Id", "description": "Token id as a decimal string (uint256)." }, "balance": { "type": "string", "title": "Balance", "description": "Units held: always '1' for QRC-721, the amount for QRC-1155." }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Name", "description": "Collection name from token metadata, if indexed." }, "symbol": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Symbol", "description": "Collection symbol from token metadata, if indexed." }, "last_transfer_block": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Last Transfer Block", "description": "Block of the latest transfer of this token involving the address." } }, "type": "object", "required": [ "contract", "standard", "token_id", "balance" ], "title": "NftHoldingItem" }, "NftHoldingsResponse": { "properties": { "chain": { "type": "string", "title": "Chain" }, "network": { "type": "string", "title": "Network" }, "address": { "type": "string", "title": "Address" }, "standard": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Standard" }, "items": { "items": { "$ref": "#/components/schemas/NftHoldingItem" }, "type": "array", "title": "Items" }, "page": { "type": "integer", "title": "Page" }, "page_size": { "type": "integer", "title": "Page Size" }, "total": { "type": "integer", "title": "Total", "description": "Distinct (contract, token_id) positions held." }, "total_pages": { "type": "integer", "title": "Total Pages" }, "indexed_tip_height": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Indexed Tip Height" } }, "type": "object", "required": [ "chain", "network", "address", "items", "page", "page_size", "total", "total_pages" ], "title": "NftHoldingsResponse" }, "NftMintsSummary": { "properties": { "network": { "type": "string", "title": "Network" }, "total_mints": { "type": "integer", "title": "Total Mints", "default": 0 }, "mints_24h": { "type": "integer", "title": "Mints 24H", "default": 0 }, "mints_7d": { "type": "integer", "title": "Mints 7D", "default": 0 }, "mints_30d": { "type": "integer", "title": "Mints 30D", "default": 0 }, "collections_minting": { "type": "integer", "title": "Collections Minting", "default": 0 }, "unique_minters": { "type": "integer", "title": "Unique Minters", "default": 0 }, "qrc721_count": { "type": "integer", "title": "Qrc721 Count", "default": 0 }, "qrc1155_count": { "type": "integer", "title": "Qrc1155 Count", "default": 0 }, "top_collection": { "anyOf": [ { "$ref": "#/components/schemas/NftTopCollection" }, { "type": "null" } ] }, "latest_mint": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Latest Mint" } }, "type": "object", "required": [ "network" ], "title": "NftMintsSummary", "description": "Hero metrics for the /nft-mints page (QRL2 QRC-721/QRC-1155 mints).\n\nAll-time mint count + 7d/30d pulse, distinct minting collections, distinct\nminters, the QRC-721 vs QRC-1155 split, the most-minted collection, and the\nlatest mint time (freshness). ``mints_24h`` is returned for completeness but\nthe UI omits it (chronically 0 on the sparse testnet). Zero-filled on a\nmissing view." }, "NftTopCollection": { "properties": { "token_contract": { "type": "string", "title": "Token Contract" }, "mints": { "type": "integer", "title": "Mints" }, "token_symbol": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Token Symbol" }, "token_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Token Name" } }, "type": "object", "required": [ "token_contract", "mints" ], "title": "NftTopCollection", "description": "Most-minted NFT collection (hero tile). Symbol/name may be null when the\ncontract's metadata fetch failed — the frontend falls back to a short\ncontract address." }, "PaginatedAddressCursor_TransactionDetail_": { "properties": { "items": { "items": { "$ref": "#/components/schemas/TransactionDetail" }, "type": "array", "title": "Items" }, "limit": { "type": "integer", "title": "Limit", "description": "Maximum number of items in this page" }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Next Cursor", "description": "Opaque pagination token for the next page; null when the current page is the last one. Pass back unchanged in ?cursor=." }, "has_more": { "type": "boolean", "title": "Has More", "description": "True when at least one more page is available." }, "total": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Total", "description": "Total logical transactions matching the same filters, or null when the address index is unavailable. Multi-recipient transactions count once, matching how items are paged." }, "offset": { "type": "integer", "title": "Offset", "description": "Number of items skipped before this page.", "default": 0 } }, "type": "object", "required": [ "items", "limit", "has_more" ], "title": "PaginatedAddressCursor[TransactionDetail]" }, "PaginatedCursor_BlockSummary_": { "properties": { "items": { "items": { "$ref": "#/components/schemas/BlockSummary" }, "type": "array", "title": "Items" }, "limit": { "type": "integer", "title": "Limit", "description": "Maximum number of items in this page" }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Next Cursor", "description": "Opaque pagination token for the next page; null when the current page is the last one. Pass back unchanged in ?cursor=." }, "has_more": { "type": "boolean", "title": "Has More", "description": "True when at least one more page is available." } }, "type": "object", "required": [ "items", "limit", "has_more" ], "title": "PaginatedCursor[BlockSummary]" }, "PaginatedCursor_TransactionDetail_": { "properties": { "items": { "items": { "$ref": "#/components/schemas/TransactionDetail" }, "type": "array", "title": "Items" }, "limit": { "type": "integer", "title": "Limit", "description": "Maximum number of items in this page" }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Next Cursor", "description": "Opaque pagination token for the next page; null when the current page is the last one. Pass back unchanged in ?cursor=." }, "has_more": { "type": "boolean", "title": "Has More", "description": "True when at least one more page is available." } }, "type": "object", "required": [ "items", "limit", "has_more" ], "title": "PaginatedCursor[TransactionDetail]" }, "PaginatedOffset_RichlistRow_": { "properties": { "items": { "items": { "$ref": "#/components/schemas/RichlistRow" }, "type": "array", "title": "Items" }, "page": { "type": "integer", "title": "Page", "description": "1-indexed page number" }, "page_size": { "type": "integer", "title": "Page Size", "description": "Number of items per page" }, "total": { "type": "integer", "title": "Total", "description": "Total number of items across all pages" }, "total_pages": { "type": "integer", "title": "Total Pages", "description": "Total number of pages at this page_size" } }, "type": "object", "required": [ "items", "page", "page_size", "total", "total_pages" ], "title": "PaginatedOffset[RichlistRow]" }, "PoolDistribution": { "properties": { "items": { "items": { "$ref": "#/components/schemas/PoolDistributionItem" }, "type": "array", "title": "Items" }, "window": { "type": "string", "title": "Window", "default": "30d" }, "total_blocks": { "type": "integer", "title": "Total Blocks", "default": 0 }, "total_reward_shor": { "type": "string", "title": "Total Reward Shor", "default": "0" } }, "type": "object", "title": "PoolDistribution" }, "PoolDistributionItem": { "properties": { "address": { "type": "string", "title": "Address" }, "label": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Label" }, "wallet_class": { "type": "string", "title": "Wallet Class", "default": "miner" }, "blocks_mined": { "type": "integer", "title": "Blocks Mined", "default": 0 }, "reward_shor": { "type": "string", "title": "Reward Shor", "default": "0" }, "share": { "type": "number", "title": "Share", "default": 0 } }, "type": "object", "required": [ "address" ], "title": "PoolDistributionItem" }, "PoolDominancePoint": { "properties": { "day": { "type": "string", "title": "Day" }, "values": { "items": { "type": "integer" }, "type": "array", "title": "Values" } }, "type": "object", "required": [ "day" ], "title": "PoolDominancePoint" }, "PoolDominanceResponse": { "properties": { "series": { "items": { "$ref": "#/components/schemas/PoolDominanceSeries" }, "type": "array", "title": "Series" }, "points": { "items": { "$ref": "#/components/schemas/PoolDominancePoint" }, "type": "array", "title": "Points" }, "count": { "type": "integer", "title": "Count", "default": 0 } }, "type": "object", "title": "PoolDominanceResponse" }, "PoolDominanceSeries": { "properties": { "key": { "type": "string", "title": "Key" }, "label": { "type": "string", "title": "Label" }, "wallet_class": { "type": "string", "title": "Wallet Class", "default": "miningpool" } }, "type": "object", "required": [ "key", "label" ], "title": "PoolDominanceSeries" }, "PqChainSignatures": { "properties": { "chain": { "type": "string", "title": "Chain", "description": "'qrl' or 'qrl2'" }, "network": { "type": "string", "title": "Network", "description": "'mainnet' or 'testnet'" }, "scheme": { "type": "string", "title": "Scheme", "description": "Signature scheme: 'XMSS' (QRL) or 'ML-DSA-87' (QRL 2.0)" }, "signed_txs": { "type": "integer", "title": "Signed Txs", "description": "Distinct transactions carrying a post-quantum signature (QRL excludes the unsigned coinbase and unsigned genesis rows)" }, "since": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Since", "description": "First indexed day (ISO date)" }, "as_of": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "As Of", "description": "Last indexed day (ISO date)" }, "days_running": { "type": "integer", "title": "Days Running", "description": "Days from `since` to `as_of`, inclusive", "default": 0 } }, "type": "object", "required": [ "chain", "network", "scheme", "signed_txs" ], "title": "PqChainSignatures", "description": "Post-quantum-signed transaction count for one chain." }, "PqSignatureStats": { "properties": { "mainnet_signed_txs": { "type": "integer", "title": "Mainnet Signed Txs", "description": "Signed transactions on mainnet chains only; QRL 2.0 testnet is excluded" }, "as_of": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "As Of", "description": "Latest indexed day across chains" }, "since": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Since", "description": "First day of the mainnet track record: the earliest mainnet chain's first indexed day (the QRL genesis, 2018)" }, "days_running": { "type": "integer", "title": "Days Running", "description": "Days from `since` to the latest day any mainnet chain has indexed, inclusive; keeps counting on QRL 2.0 mainnet after the cutover", "default": 0 }, "chains": { "items": { "$ref": "#/components/schemas/PqChainSignatures" }, "type": "array", "title": "Chains" }, "degraded": { "type": "boolean", "title": "Degraded", "description": "True when a source query failed; counts may be missing", "default": false } }, "type": "object", "required": [ "mainnet_signed_txs" ], "title": "PqSignatureStats", "description": "Post-quantum signature counter (homepage, embed, share card)." }, "QrlMessageItem": { "properties": { "tx_hash": { "type": "string", "title": "Tx Hash" }, "height": { "type": "integer", "title": "Height" }, "message_type": { "type": "string", "title": "Message Type", "default": "message" }, "from_addr": { "type": "string", "title": "From Addr", "default": "" }, "master_addr": { "type": "string", "title": "Master Addr", "default": "" }, "to_addr": { "type": "string", "title": "To Addr", "default": "" }, "message_data_hex": { "type": "string", "title": "Message Data Hex", "default": "" }, "message_data_text": { "type": "string", "title": "Message Data Text", "default": "" }, "message_size_bytes": { "type": "integer", "title": "Message Size Bytes", "default": 0 }, "is_readable": { "type": "boolean", "title": "Is Readable", "default": false }, "value": { "type": "string", "title": "Value", "default": "0" }, "fee": { "type": "string", "title": "Fee", "default": "0" }, "timestamp": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Timestamp" } }, "type": "object", "required": [ "tx_hash", "height" ], "title": "QrlMessageItem", "description": "One on-chain QRL text entry (etl_silver.qrl_messages, mig 046 + 121).\n\nCovers two kinds, distinguished by `message_type`:\n · 'message' — the dedicated MessageTransaction subtype (`value` 0).\n · 'transfer_memo' — a memo riding on a coin transfer (`value` = Shor\n moved, `to_addr` = first recipient).\n\n`message_data_text` is the best-effort UTF-8 decode (binary payloads show\nU+FFFD replacement chars — `is_readable` flags clean decodes); the hex is\nalways the verbatim on-chain payload." }, "QrlMessagesList": { "properties": { "items": { "items": { "$ref": "#/components/schemas/QrlMessageItem" }, "type": "array", "title": "Items" }, "total": { "type": "integer", "title": "Total", "default": 0 }, "page": { "type": "integer", "title": "Page", "default": 1 }, "page_size": { "type": "integer", "title": "Page Size", "default": 25 } }, "type": "object", "title": "QrlMessagesList" }, "QrlMessagesSummary": { "properties": { "total": { "type": "integer", "title": "Total", "default": 0 }, "message_count": { "type": "integer", "title": "Message Count", "default": 0 }, "memo_count": { "type": "integer", "title": "Memo Count", "default": 0 }, "readable_count": { "type": "integer", "title": "Readable Count", "default": 0 }, "total_bytes": { "type": "integer", "title": "Total Bytes", "default": 0 }, "unique_senders": { "type": "integer", "title": "Unique Senders", "default": 0 }, "first_message_time": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "First Message Time" }, "last_message_time": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Last Message Time" } }, "type": "object", "title": "QrlMessagesSummary" }, "QrlPriceHistoryItem": { "properties": { "bucket": { "type": "string", "title": "Bucket", "description": "ISO-8601 start of the time bucket (UTC)." }, "open": { "type": "number", "title": "Open", "description": "First price in the bucket." }, "high": { "type": "number", "title": "High", "description": "Max price in the bucket." }, "low": { "type": "number", "title": "Low", "description": "Min price in the bucket." }, "close": { "type": "number", "title": "Close", "description": "Last price in the bucket." }, "avg": { "type": "number", "title": "Avg", "description": "Mean price in the bucket." }, "samples": { "type": "integer", "title": "Samples", "description": "Number of raw datapoints in the bucket." } }, "type": "object", "required": [ "bucket", "open", "high", "low", "close", "avg", "samples" ], "title": "QrlPriceHistoryItem", "description": "One downsampled OHLC bucket from etl_silver.market_prices." }, "QrlPriceHistoryResponse": { "properties": { "asset": { "type": "string", "title": "Asset", "description": "Asset symbol; 'qrl' for the legacy chain." }, "currency": { "type": "string", "title": "Currency", "description": "Quote currency: usd, eur, or btc." }, "interval": { "type": "string", "title": "Interval", "description": "Bucket size: 5m, 15m, 1h, 4h, or 1d." }, "days": { "type": "integer", "title": "Days", "description": "Lookback window in days." }, "items": { "items": { "$ref": "#/components/schemas/QrlPriceHistoryItem" }, "type": "array", "title": "Items" } }, "type": "object", "required": [ "asset", "currency", "interval", "days" ], "title": "QrlPriceHistoryResponse", "description": "Time-bucketed QRL price history. Empty `items` on cold-start or\npre-migration-050 deploys --render an empty-state, not an error." }, "QrlPriceResponse": { "properties": { "currency": { "type": "string", "title": "Currency", "description": "Lower-case currency code, e.g. 'usd'" }, "price": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Price", "description": "Latest price in the requested currency. None when cache is cold." }, "change_24h_pct": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Change 24H Pct", "description": "24h % change. None if upstream omitted it." }, "source": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Source", "description": "Upstream provider, currently 'coingecko'." }, "fetched_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Fetched At", "description": "ISO-8601 UTC timestamp when our poller stored this snapshot." }, "source_updated_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Source Updated At", "description": "ISO-8601 UTC timestamp the upstream reports for the price tick." } }, "type": "object", "required": [ "currency" ], "title": "QrlPriceResponse", "description": "Latest cached QRL market price from /api/v1/price/qrl.\n\nAll fields are Optional because the cache may be cold (just-started\nbackend, upstream outage). Callers should render a placeholder when\n`price` is None rather than treating it as an error." }, "RedditTrendPoint": { "properties": { "day": { "type": "string", "title": "Day", "description": "ISO date (YYYY-MM-DD) the reading represents" }, "keyword": { "type": "string", "title": "Keyword", "description": "Keyword filter, e.g. 'QRL'" }, "posts": { "type": "integer", "title": "Posts", "description": "Matching posts in the week" }, "comments": { "type": "integer", "title": "Comments", "description": "Total comments on those posts" }, "score": { "type": "integer", "title": "Score", "description": "Total post score (net upvotes)" } }, "type": "object", "required": [ "day", "keyword", "posts", "comments", "score" ], "title": "RedditTrendPoint", "description": "Reddit discussion volume for a keyword on a given day, summed across the\ntracked subreddits. Counts are absolute (posts/comments) over the collection\nweek; score is the summed post score." }, "RelatedWalletsList": { "properties": { "items": { "items": { "additionalProperties": true, "type": "object" }, "type": "array", "title": "Items" }, "address": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Address" }, "network": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Network" } }, "type": "object", "title": "RelatedWalletsList" }, "RevertReasonResponse": { "properties": { "tx_hash": { "type": "string", "title": "Tx Hash" }, "chain": { "type": "string", "title": "Chain" }, "network": { "type": "string", "title": "Network" }, "kind": { "type": "string", "title": "Kind" }, "decoded": { "type": "string", "title": "Decoded" }, "raw_output": { "type": "string", "title": "Raw Output", "default": "" }, "tracer_error": { "type": "string", "title": "Tracer Error", "default": "" }, "source": { "type": "string", "title": "Source", "default": "live" } }, "type": "object", "required": [ "tx_hash", "chain", "network", "kind", "decoded" ], "title": "RevertReasonResponse", "description": "Decoded EVM revert reason for a reverted (status=0) transaction.\n\nSource: on-demand `debug_traceTransaction` (callTracer) against node-qrl2.\nMay be persisted to `etl_silver.transactions.revert_reason` later (Fase 2);\nthe response shape stays the same regardless of source." }, "RichlistRow": { "properties": { "chain": { "type": "string", "title": "Chain", "description": "qrl or qrl2 — drives per-row decimals + links" }, "network": { "type": "string", "title": "Network" }, "address": { "type": "string", "title": "Address" }, "balance": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Balance", "description": "Raw base units: shor (qrl) / planck (qrl2)." }, "balance_shor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Balance Shor", "description": "Balance normalised to shor (common unit) for cross-chain ranking + % supply." }, "total_received": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Total Received" }, "total_sent": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Total Sent" }, "total_fees_paid": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Total Fees Paid" }, "tx_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Tx Count" }, "first_seen": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "First Seen" }, "last_seen": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Last Seen" }, "label": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Label" }, "label_category": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Label Category" }, "exchange_relay_of": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Exchange Relay Of", "description": "Set when this address is a detected exchange DEPOSIT address (quantascan.exchange_relay, high/medium confidence) — the value is the exchange it sweeps into. Such a row is exchange custody in transit, not a holder's stack. Rides along with with_labels; null means either 'not a deposit address' or 'enrichment not requested'." }, "received_30d": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Received 30D" }, "sent_30d": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Sent 30D" } }, "additionalProperties": true, "type": "object", "required": [ "chain", "network", "address" ], "title": "RichlistRow", "description": "One row of the CROSS-CHAIN richlist (`GET /api/v1/richlist`).\n\nUnlike `AddressSummaryRow` (single-chain, chain implicit in the URL path),\nthis list interleaves QRL and QRL 2.0 holders, so every row carries its own\n`chain` — REQUIRED, because the frontend derives per-row decimals (qrl=9\nshor, qrl2=18 planck), the right /address link prefix, and the unit label\nfrom it.\n\n`balance` is the raw base-unit UInt256 string (shor on qrl, planck on qrl2)\nfor exact per-chain display. `balance_shor` is the SAME balance normalised to\na common unit (shor) so the list can be ranked and a wallet's share computed\nacross both chains on one scale without re-deriving decimals client-side:\n qrl → balance (already shor)\n qrl2 → balance / 1e9 (planck → shor; 1 Quanta = 1e9 shor = 1e18 planck)" }, "StakeConcentrationResponse": { "properties": { "network": { "type": "string", "title": "Network" }, "active_validator_count": { "type": "integer", "title": "Active Validator Count", "default": 0 }, "total_effective_balance_gwei": { "type": "string", "title": "Total Effective Balance Gwei", "default": "0" }, "total_effective_balance_qrl2": { "type": "string", "title": "Total Effective Balance Qrl2", "default": "0" }, "top10_concentration_pct": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Top10 Concentration Pct" }, "operator_count": { "type": "integer", "title": "Operator Count", "default": 0 }, "top10_operator_share_pct": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Top10 Operator Share Pct" }, "largest_operator_validators": { "type": "integer", "title": "Largest Operator Validators", "default": 0 } }, "type": "object", "required": [ "network" ], "title": "StakeConcentrationResponse", "description": "Stake-distribution KPI bundle for the /validators hub strip.\n\nOn QRL 2.0 every active validator holds the SAME fixed effective stake\n(the 40,000-Quanta maximum), so a \"top-10 by stake\" share is meaningless —\nit is just 10/validator_count. The decentralisation signal that matters is\nby OPERATOR: one withdrawal address can run many validators. The\n`*_operator_*` fields group active validators by `withdrawal_credentials`\n(the operator identity) and report how concentrated control is.\n\n`top10_concentration_pct` (legacy, by stake) is kept for back-compat but is\nno longer surfaced in the UI. `top10_operator_share_pct` is a 0..1 ratio\n(None when no operator data — e.g. a sparse/pre-mig-035 deploy or when no\nvalidator has withdrawal credentials set). Big balances are carried as\ndecimal strings to avoid JS/JSON integer-precision loss." }, "TokenDetail": { "properties": { "id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Id" }, "symbol": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Symbol" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Name" }, "decimals": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Decimals" }, "first_seen_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "First Seen At" }, "owner": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Owner" }, "height": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Height" }, "block_hash": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Block Hash" }, "total_supply": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Total Supply" }, "initial_balances": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Initial Balances" }, "total_supply_raw": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Total Supply Raw" }, "total_supply_display": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Total Supply Display" }, "circulating_raw": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Circulating Raw" }, "circulating_display": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Circulating Display" }, "holders": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Holders" }, "transfer_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Transfer Count" }, "is_qrc20": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Is Qrc20" }, "is_qrc721": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Is Qrc721" }, "is_qrc1155": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Is Qrc1155" }, "metadata_status": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Metadata Status" }, "refresh_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Refresh Count" }, "metadata_refreshed_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Metadata Refreshed At" }, "deployer": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Deployer" }, "deployment_block": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Deployment Block" }, "deployment_timestamp": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Deployment Timestamp" } }, "additionalProperties": true, "type": "object", "title": "TokenDetail", "description": "A token record --chain-polymorphic (QRL native vs QRL2 QRC-*).\n`id` is tx-hash on QRL, contract address on QRL2. Not every field is\npopulated on every chain -- see token_repository.get_token() for the\nexact per-chain SELECT. `extra=\"allow\"` kept as a forward-compat\nsafety net, not a substitute for declaring the known shape." }, "TokenDistribution": { "properties": { "token_contract": { "type": "string", "title": "Token Contract" }, "network": { "type": "string", "title": "Network" }, "total_supply": { "type": "string", "title": "Total Supply", "default": "0" }, "max_supply": { "type": "string", "title": "Max Supply", "default": "0" }, "supply_basis": { "type": "string", "title": "Supply Basis", "default": "circulating" }, "holders_count": { "type": "integer", "title": "Holders Count", "default": 0 }, "top_10_share": { "type": "number", "title": "Top 10 Share", "default": 0 }, "top_50_share": { "type": "number", "title": "Top 50 Share", "default": 0 }, "top_100_share": { "type": "number", "title": "Top 100 Share", "default": 0 }, "hhi": { "type": "number", "title": "Hhi", "default": 0 }, "concentration_note": { "type": "string", "title": "Concentration Note", "default": "" }, "cohorts": { "items": { "additionalProperties": true, "type": "object" }, "type": "array", "title": "Cohorts" } }, "additionalProperties": true, "type": "object", "required": [ "token_contract", "network" ], "title": "TokenDistribution", "description": "Concentration stats for a QRL2 QRC-20 token (see get_distribution())." }, "TokenHolderBalance": { "properties": {}, "additionalProperties": true, "type": "object", "title": "TokenHolderBalance", "description": "Single (token, address) balance with decimals-corrected display." }, "TokenHoldersList": { "properties": { "items": { "items": { "additionalProperties": true, "type": "object" }, "type": "array", "title": "Items" }, "total": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Total" }, "limit": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Limit" }, "offset": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Offset" }, "token_contract": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Token Contract" } }, "type": "object", "title": "TokenHoldersList" }, "TokenStatsSummary": { "properties": { "chain": { "type": "string", "title": "Chain" }, "network": { "type": "string", "title": "Network" }, "tokens_total": { "type": "integer", "title": "Tokens Total", "default": 0 }, "tokens_with_metadata": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Tokens With Metadata" }, "transfers_24h": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Transfers 24H" } }, "additionalProperties": true, "type": "object", "required": [ "chain", "network" ], "title": "TokenStatsSummary" }, "TokenTransfersList": { "properties": { "items": { "items": { "additionalProperties": true, "type": "object" }, "type": "array", "title": "Items" }, "total": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Total" }, "limit": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Limit" }, "offset": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Offset" }, "token_contract": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Token Contract" } }, "type": "object", "title": "TokenTransfersList" }, "TokensPaginated": { "properties": { "items": { "items": { "$ref": "#/components/schemas/TokenDetail" }, "type": "array", "title": "Items" }, "total": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Total" }, "page": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Page" }, "page_size": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Page Size" }, "total_pages": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Total Pages" }, "limit": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Limit" }, "offset": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Offset" }, "chain": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Chain" }, "network": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Network" } }, "type": "object", "title": "TokensPaginated" }, "TopMinerItem": { "properties": { "address": { "type": "string", "title": "Address" }, "label": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Label" }, "wallet_class": { "type": "string", "title": "Wallet Class", "default": "miner" }, "wallet_class_method": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Wallet Class Method" }, "blocks_mined": { "type": "integer", "title": "Blocks Mined", "default": 0 }, "reward_shor": { "type": "string", "title": "Reward Shor", "default": "0" }, "share": { "type": "number", "title": "Share", "default": 0 }, "last_block_time": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Last Block Time" } }, "type": "object", "required": [ "address" ], "title": "TopMinerItem" }, "TopMinersList": { "properties": { "items": { "items": { "$ref": "#/components/schemas/TopMinerItem" }, "type": "array", "title": "Items" }, "count": { "type": "integer", "title": "Count", "default": 0 }, "window": { "type": "string", "title": "Window", "default": "all" }, "total_blocks": { "type": "integer", "title": "Total Blocks", "default": 0 } }, "type": "object", "title": "TopMinersList" }, "TopValidatorsList": { "properties": { "items": { "items": { "$ref": "#/components/schemas/ValidatorDetail" }, "type": "array", "title": "Items" }, "limit": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Limit" }, "network": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Network" } }, "type": "object", "title": "TopValidatorsList" }, "TopWithdrawalRecipient": { "properties": { "address": { "type": "string", "title": "Address" }, "total_amount": { "type": "string", "title": "Total Amount" }, "withdrawal_count": { "type": "integer", "title": "Withdrawal Count" }, "validator_count": { "type": "integer", "title": "Validator Count" }, "last_withdrawal_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Last Withdrawal At" } }, "type": "object", "required": [ "address", "total_amount", "withdrawal_count", "validator_count" ], "title": "TopWithdrawalRecipient", "description": "One operator (withdrawal address) in the top-rewards ranking.\n\n`total_amount` is in planck (1e18); `validator_count` is the distinct\nvalidators paying out to this address (one operator can run many)." }, "TopWithdrawalRecipientsList": { "properties": { "items": { "items": { "$ref": "#/components/schemas/TopWithdrawalRecipient" }, "type": "array", "title": "Items" }, "count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Count" }, "network": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Network" } }, "type": "object", "title": "TopWithdrawalRecipientsList" }, "TransactionDetail": { "properties": { "chain": { "type": "string", "title": "Chain" }, "network": { "type": "string", "title": "Network" }, "tx_hash": { "type": "string", "title": "Tx Hash" }, "height": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Height" }, "timestamp": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Timestamp" }, "from_addr": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "From Addr" }, "to_addr": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "To Addr" }, "confirmations": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Confirmations", "description": "Indexed tip height - block height + 1 (0 = block not yet fully indexed)." }, "finalized": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Finalized", "description": "QRL 2.0: block is at/below the Casper-FFG finalized checkpoint. Null on QRL legacy (PoW, no finality) or when unknown." } }, "additionalProperties": true, "type": "object", "required": [ "chain", "network", "tx_hash" ], "title": "TransactionDetail", "description": "Tx row from `quantascan.transactions`. Heavy chain divergence (qrl\nhas XMSS-specific fields like master_addr/slave_idx; qrl2 has\nEIP-1559 max_fee_per_gas etc.) so `extra='allow'`." }, "TransactionDetailResponse": { "properties": { "chain": { "type": "string", "title": "Chain" }, "network": { "type": "string", "title": "Network" }, "tx_hash": { "type": "string", "title": "Tx Hash" }, "height": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Height" }, "block_hash": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Block Hash" }, "confirmations": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Confirmations", "description": "Indexed tip height - block height + 1 (the including block counts as 1; 0 = block not yet fully indexed)." }, "finalized": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Finalized", "description": "QRL 2.0 only: true once the block is at/below the latest Casper-FFG finalized checkpoint (irreversible). Null on QRL legacy (Proof-of-Work has no finality) or when finality data is unavailable." }, "indexed_tip_height": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Indexed Tip Height", "description": "Indexed tip height `confirmations` was computed against." }, "tx_index": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Tx Index" }, "recipient_index": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Recipient Index" }, "from_addr": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "From Addr" }, "to_addr": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "To Addr" }, "value": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Value" }, "fee": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Fee" }, "nonce": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Nonce" }, "tx_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Tx Type" }, "status": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Status" }, "timestamp": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Timestamp" }, "master_addr": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Master Addr" }, "transaction_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Transaction Type" }, "public_key": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Public Key" }, "payload_json": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Payload Json" }, "gas": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Gas" }, "gas_used": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Gas Used" }, "cumulative_gas_used": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Cumulative Gas Used" }, "gas_price": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Gas Price" }, "effective_gas_price": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Effective Gas Price" }, "max_fee_per_gas": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Max Fee Per Gas" }, "max_priority_fee_per_gas": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Max Priority Fee Per Gas" }, "tx_type_evm": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Tx Type Evm" }, "access_list": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Access List" }, "contract_address": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Contract Address" }, "input_data": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Input Data" }, "recipients": { "anyOf": [ { "items": { "additionalProperties": true, "type": "object" }, "type": "array" }, { "type": "null" } ], "title": "Recipients" }, "recipient_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Recipient Count" }, "logs": { "anyOf": [ { "items": { "additionalProperties": true, "type": "object" }, "type": "array" }, { "type": "null" } ], "title": "Logs" }, "internal_transfers": { "anyOf": [ { "items": { "additionalProperties": true, "type": "object" }, "type": "array" }, { "type": "null" } ], "title": "Internal Transfers" } }, "additionalProperties": true, "type": "object", "required": [ "chain", "network", "tx_hash" ], "title": "TransactionDetailResponse", "description": "Single tx --extra=allow because qrl/qrl2 fields differ and the\ndetail endpoint also flattens multi-recipient txs with `recipients[]`.\n\nExplicit fields below are documented in OpenAPI (and consumed by\n`make api-types` for the generated TS interface). Anything else the\nview exposes (raw_ref_hint, ingested_at, …) still passes through via\n`extra=\"allow\"` for hand-typed consumers." }, "TransactionTypeCounts": { "properties": { "chain": { "type": "string", "title": "Chain" }, "network": { "type": "string", "title": "Network" }, "all": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "All", "description": "Every transaction, QRL block rewards (coinbase) included." }, "counts": { "additionalProperties": { "type": "integer" }, "type": "object", "title": "Counts", "description": "Per `method` value (sent, coinbase, transfer, token_transfer, multi_recipient, slave, message, token_creation, other on QRL; transfer, token_transfer, contract_call, contract_creation, failed on QRL 2.0). multi_recipient is a subset of transfer." }, "available": { "type": "boolean", "title": "Available", "description": "False when part of the counts failed.", "default": true } }, "type": "object", "required": [ "chain", "network" ], "title": "TransactionTypeCounts", "description": "Number of transactions behind each /transactions `method` filter." }, "TransferEvent": { "properties": { "block_height": { "type": "integer", "title": "Block Height" }, "tx_hash": { "type": "string", "title": "Tx Hash" }, "log_index": { "type": "integer", "title": "Log Index" }, "token_standard": { "type": "string", "title": "Token Standard" }, "token_contract": { "type": "string", "title": "Token Contract" }, "from_addr": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "From Addr" }, "to_addr": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "To Addr" }, "amount": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Amount" } }, "additionalProperties": true, "type": "object", "required": [ "block_height", "tx_hash", "log_index", "token_standard", "token_contract" ], "title": "TransferEvent" }, "TransfersFeedSummary": { "properties": { "network": { "type": "string", "title": "Network" }, "total": { "type": "integer", "title": "Total", "default": 0 }, "transfers_24h": { "type": "integer", "title": "Transfers 24H", "default": 0 }, "transfers_7d": { "type": "integer", "title": "Transfers 7D", "default": 0 }, "active_tokens": { "type": "integer", "title": "Active Tokens", "default": 0 }, "mint_count": { "type": "integer", "title": "Mint Count", "default": 0 }, "burn_count": { "type": "integer", "title": "Burn Count", "default": 0 }, "transfer_count": { "type": "integer", "title": "Transfer Count", "default": 0 }, "top_token": { "anyOf": [ { "$ref": "#/components/schemas/TransfersTopToken" }, { "type": "null" } ] } }, "type": "object", "required": [ "network" ], "title": "TransfersFeedSummary", "description": "Hero metrics for the /token-transfers QRC-20 transfer feed." }, "TransfersPaginated": { "properties": { "items": { "items": { "$ref": "#/components/schemas/TransferEvent" }, "type": "array", "title": "Items" }, "limit": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Limit" }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Next Cursor", "description": "Opaque pagination token for the next page; null when this is the last page. Pass back unchanged in ?cursor=." }, "has_more": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Has More", "description": "True when at least one more page is available." }, "network": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Network" }, "filters_applied": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Filters Applied" } }, "type": "object", "title": "TransfersPaginated", "description": "Cursor-paginated decoded-transfer feed.\n\nCursor-only (Wave 8): `next_cursor` is an opaque base64 token — callers\npass it back unchanged in `?cursor=` to advance; `has_more` is true when\nanother page exists. No offset/page (the feed churns at the head)." }, "TransfersTopToken": { "properties": { "token_contract": { "type": "string", "title": "Token Contract" }, "transfers": { "type": "integer", "title": "Transfers" }, "symbol": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Symbol" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Name" } }, "type": "object", "required": [ "token_contract", "transfers" ], "title": "TransfersTopToken", "description": "Most-active QRC-20 token in the transfer feed (hero tile)." }, "ValidationError": { "properties": { "loc": { "items": { "anyOf": [ { "type": "string" }, { "type": "integer" } ] }, "type": "array", "title": "Location" }, "msg": { "type": "string", "title": "Message" }, "type": { "type": "string", "title": "Error Type" }, "input": { "title": "Input" }, "ctx": { "type": "object", "title": "Context" } }, "type": "object", "required": [ "loc", "msg", "type" ], "title": "ValidationError" }, "ValidatorBeaconPerformance": { "properties": { "validator_index": { "type": "integer", "title": "Validator Index" }, "blocks_proposed_count": { "type": "integer", "title": "Blocks Proposed Count", "default": 0 }, "first_proposal_slot": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "First Proposal Slot" }, "last_proposal_slot": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Last Proposal Slot" }, "first_proposal_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "First Proposal At" }, "last_proposal_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Last Proposal At" }, "current_status": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Current Status" }, "slashed": { "type": "boolean", "title": "Slashed", "default": false }, "current_effective_balance": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Current Effective Balance" }, "pubkey": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Pubkey" }, "proposals_scheduled": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Proposals Scheduled" }, "proposals_missed": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Proposals Missed" }, "last_missed_slot": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Last Missed Slot" } }, "type": "object", "required": [ "validator_index" ], "title": "ValidatorBeaconPerformance", "description": "Consensus-layer rollup per validator (Gold). Empty for validators\nthat haven't proposed AND aren't in any snapshot (effectively\n\"unknown to the beacon indexer\")." }, "ValidatorDetail": { "properties": { "validator_index": { "type": "integer", "title": "Validator Index" }, "total_withdrawn_planck": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Total Withdrawn Planck" }, "total_withdrawn_qrl2": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Total Withdrawn Qrl2" }, "withdrawal_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Withdrawal Count" }, "last_recipient": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Last Recipient" }, "first_withdrawal_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "First Withdrawal At" }, "last_withdrawal_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Last Withdrawal At" }, "current_status": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Current Status" }, "current_effective_balance": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Current Effective Balance" }, "blocks_proposed_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Blocks Proposed Count" }, "slashed": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Slashed" }, "first_proposal_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "First Proposal At" }, "last_proposal_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Last Proposal At" } }, "additionalProperties": true, "type": "object", "required": [ "validator_index" ], "title": "ValidatorDetail", "description": "Single validator row from `quantascan.qrl2_validators` (execution\nside), optionally enriched with consensus-layer columns when the list\nendpoint LEFT-JOINs `quantascan.qrl2_validator_performance` (mig 035).\n\nThe consensus fields are `None` when the beacon indexer is off or the\nvalidator hasn't been seen on the consensus layer yet." }, "ValidatorExecutionSide": { "properties": { "validator_index": { "type": "integer", "title": "Validator Index" }, "total_withdrawn_planck": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Total Withdrawn Planck" }, "total_withdrawn_qrl2": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Total Withdrawn Qrl2" }, "withdrawal_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Withdrawal Count" }, "last_recipient": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Last Recipient" }, "first_withdrawal_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "First Withdrawal At" }, "last_withdrawal_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Last Withdrawal At" } }, "additionalProperties": true, "type": "object", "required": [ "validator_index" ], "title": "ValidatorExecutionSide", "description": "Execution-layer withdrawal totals (already exposed via\n`/validators/{idx}`). Re-used here so the combined endpoint has a\ntyped `execution` field." }, "ValidatorFullPerformance": { "properties": { "validator_index": { "type": "integer", "title": "Validator Index" }, "network": { "type": "string", "title": "Network" }, "execution": { "anyOf": [ { "$ref": "#/components/schemas/ValidatorExecutionSide" }, { "type": "null" } ] }, "consensus": { "anyOf": [ { "$ref": "#/components/schemas/ValidatorBeaconPerformance" }, { "type": "null" } ] } }, "type": "object", "required": [ "validator_index", "network" ], "title": "ValidatorFullPerformance", "description": "Combined execution + consensus bundle for the validator-detail\npage. `consensus` is None when the beacon indexer is disabled or\nthe validator hasn't been seen on the beacon side yet." }, "ValidatorStatusBreakdown": { "properties": { "network": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Network" }, "total": { "type": "integer", "title": "Total", "default": 0 }, "entering": { "type": "integer", "title": "Entering", "default": 0 }, "active": { "type": "integer", "title": "Active", "default": 0 }, "exiting": { "type": "integer", "title": "Exiting", "default": 0 }, "exited": { "type": "integer", "title": "Exited", "default": 0 }, "slashed": { "type": "integer", "title": "Slashed", "default": 0 } }, "type": "object", "title": "ValidatorStatusBreakdown", "description": "Validator-count breakdown by lifecycle bucket for the /validators hub\nstrip. `entering` = activation queue, `exiting` = leaving the active set —\nthe churn view a reader cares about. Zero-filled gracefully on a\npre-mig-035 deploy or before the beacon indexer snapshots the registry." }, "ValidatorWithdrawalsList": { "properties": { "items": { "items": { "additionalProperties": true, "type": "object" }, "type": "array", "title": "Items" }, "limit": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Limit" }, "offset": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Offset" }, "validator_index": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Validator Index" } }, "type": "object", "title": "ValidatorWithdrawalsList" }, "ValidatorsPaginated": { "properties": { "items": { "items": { "$ref": "#/components/schemas/ValidatorDetail" }, "type": "array", "title": "Items" }, "total": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Total" }, "limit": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Limit" }, "offset": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Offset" }, "network": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Network" } }, "type": "object", "title": "ValidatorsPaginated" }, "VerifyJobCreated": { "properties": { "job_id": { "type": "string", "title": "Job Id" }, "status": { "type": "string", "title": "Status", "description": "Always 'pending' on creation." }, "ws_channel": { "type": "string", "title": "Ws Channel", "description": "Subscribe to this WS channel for live progress (verify:{addr}:{jobId})." } }, "type": "object", "required": [ "job_id", "status", "ws_channel" ], "title": "VerifyJobCreated", "description": "202 response on POST /verify." }, "VerifyJobDiff": { "properties": { "first_divergence_offset": { "type": "integer", "title": "First Divergence Offset" }, "expected_hex": { "type": "string", "title": "Expected Hex", "description": "Window of expected bytes (≤64 bytes hex)." }, "actual_hex": { "type": "string", "title": "Actual Hex", "description": "Window of actual on-chain bytes (≤64 bytes hex)." } }, "type": "object", "required": [ "first_divergence_offset", "expected_hex", "actual_hex" ], "title": "VerifyJobDiff", "description": "Bytecode mismatch diff for the wow-tab on the frontend." }, "VerifyJobError": { "properties": { "code": { "type": "string", "title": "Code", "description": "Whitelisted error code from verifier (COMPILE_ERROR, TIMEOUT, …)." }, "detail": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Detail" } }, "type": "object", "required": [ "code" ], "title": "VerifyJobError" }, "VerifyJobStatus": { "properties": { "job_id": { "type": "string", "title": "Job Id" }, "address": { "type": "string", "title": "Address" }, "chain": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Chain" }, "network": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Network" }, "status": { "type": "string", "title": "Status", "description": "pending | completed | failed | rejected" }, "progress": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Progress", "description": "Stage hint: 'queued', 'compiling', 'matching', 'writing'." }, "match_grade": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Match Grade", "description": "unverified | partial | full" }, "compiler_version": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Compiler Version" }, "verified_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Verified At" }, "errors": { "items": { "$ref": "#/components/schemas/VerifyJobError" }, "type": "array", "title": "Errors" }, "diff": { "anyOf": [ { "$ref": "#/components/schemas/VerifyJobDiff" }, { "type": "null" } ] } }, "type": "object", "required": [ "job_id", "address", "status" ], "title": "VerifyJobStatus", "description": "GET /api/v1/contracts/{addr}/verify/{jobId} response." }, "VerifyOptimizer": { "properties": { "enabled": { "type": "boolean", "title": "Enabled", "default": true }, "runs": { "type": "integer", "maximum": 10000000, "minimum": 0, "title": "Runs", "default": 200 } }, "type": "object", "title": "VerifyOptimizer" }, "VerifyRequest": { "properties": { "language": { "type": "string", "title": "Language", "description": "Always 'Hyperion'.", "default": "Hyperion" }, "compiler_version": { "type": "string", "title": "Compiler Version", "description": "hypc version string; must be in HYPC_ALLOWED_VERSIONS." }, "main_contract": { "type": "string", "title": "Main Contract", "description": "':' selector for the contract being verified." }, "sources": { "additionalProperties": { "$ref": "#/components/schemas/VerifySourceFile" }, "type": "object", "title": "Sources", "description": "Map of file-path → source. Max 25 entries, total 4 MiB." }, "settings": { "$ref": "#/components/schemas/VerifySettings" }, "constructor_args": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Constructor Args", "description": "Hex-encoded ABI bytes (without 0x prefix is OK)." }, "license": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "License", "description": "SPDX identifier (MIT, GPL-3.0-only, …). Free-text accepted; UI shows verbatim." } }, "type": "object", "required": [ "compiler_version", "main_contract", "sources" ], "title": "VerifyRequest", "description": "POST /api/v1/contracts/{addr}/verify body." }, "VerifySettings": { "properties": { "optimizer": { "$ref": "#/components/schemas/VerifyOptimizer" }, "libraries": { "anyOf": [ { "additionalProperties": { "type": "string" }, "type": "object" }, { "type": "null" } ], "title": "Libraries" } }, "type": "object", "title": "VerifySettings", "description": "Standard-JSON `settings` subset. evmVersion is intentionally absent\nbecause hypc 0.0.2 rejects it (probed 2026-05-31 --see\ndocs/verifier/compiler-config.md)." }, "VerifySourceFile": { "properties": { "content": { "type": "string", "title": "Content", "description": "Raw source text (UTF-8). Capped to VERIFIER_MAX_SOURCE_BYTES." } }, "type": "object", "required": [ "content" ], "title": "VerifySourceFile", "description": "A single Hyperion (Solidity-fork) source file." }, "WalletClassBucket": { "properties": { "wallet_class": { "type": "string", "title": "Wallet Class" }, "wallet_count": { "type": "integer", "title": "Wallet Count" }, "share": { "type": "number", "maximum": 1, "minimum": 0, "title": "Share" } }, "type": "object", "required": [ "wallet_class", "wallet_count", "share" ], "title": "WalletClassBucket", "description": "One entity-class slice of the wallet population (mig 080)." }, "WalletClassDistribution": { "properties": { "items": { "items": { "$ref": "#/components/schemas/WalletClassBucket" }, "type": "array", "title": "Items" }, "total": { "type": "integer", "title": "Total", "default": 0 }, "chain": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Chain" }, "network": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Network" } }, "type": "object", "title": "WalletClassDistribution", "description": "Entity-class breakdown for /charts/wallet-types (mig 080)." }, "WalletDetail": { "properties": { "chain": { "type": "string", "title": "Chain" }, "network": { "type": "string", "title": "Network" }, "address": { "type": "string", "title": "Address" }, "address_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Address Type" }, "is_sentinel": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Is Sentinel" }, "first_seen_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "First Seen At" }, "last_seen_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Last Seen At" }, "tx_count_out": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Tx Count Out" }, "tx_count_in": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Tx Count In" }, "is_contract": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Is Contract" }, "is_validator": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Is Validator" }, "wallet_class": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Wallet Class" }, "wallet_class_method": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Wallet Class Method" }, "wallet_class_reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Wallet Class Reason" }, "is_deployer": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Is Deployer" }, "signature_scheme": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Signature Scheme" } }, "additionalProperties": true, "type": "object", "required": [ "chain", "network", "address" ], "title": "WalletDetail", "description": "A wallet record from `quantascan.wallets`." }, "WalletReputation": { "properties": { "address": { "type": "string", "title": "Address" }, "chain": { "type": "string", "title": "Chain" }, "network": { "type": "string", "title": "Network" }, "score": { "type": "integer", "maximum": 100, "minimum": 0, "title": "Score" }, "classification": { "type": "string", "title": "Classification" }, "flags": { "items": { "additionalProperties": true, "type": "object" }, "type": "array", "title": "Flags" }, "signals": { "additionalProperties": true, "type": "object", "title": "Signals" } }, "additionalProperties": true, "type": "object", "required": [ "address", "chain", "network", "score", "classification" ], "title": "WalletReputation", "description": "0-100 trust score + signal flags. Used by /wallets/{addr}/reputation." }, "WalletSchemeBucket": { "properties": { "scheme": { "type": "string", "title": "Scheme" }, "wallet_count": { "type": "integer", "title": "Wallet Count" }, "wallet_share": { "type": "number", "maximum": 1, "minimum": 0, "title": "Wallet Share" }, "coins": { "type": "number", "title": "Coins" }, "coins_share": { "type": "number", "maximum": 1, "minimum": 0, "title": "Coins Share" } }, "type": "object", "required": [ "scheme", "wallet_count", "wallet_share", "coins", "coins_share" ], "title": "WalletSchemeBucket", "description": "One signature-scheme slice of the key-holding wallet population." }, "WalletSchemeDistribution": { "properties": { "items": { "items": { "$ref": "#/components/schemas/WalletSchemeBucket" }, "type": "array", "title": "Items" }, "total_wallets": { "type": "integer", "title": "Total Wallets", "default": 0 }, "total_coins": { "type": "number", "title": "Total Coins", "default": 0 }, "chain": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Chain" }, "network": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Network" } }, "type": "object", "title": "WalletSchemeDistribution", "description": "Post-quantum signature-scheme breakdown (% wallets / % coins per type).\n\nSentinels and contracts are excluded (no signing key). On qrl every\nholder is XMSS; on qrl2 a signer is ML-DSA-87 and a receive-only address\nis 'unknown' until it signs." }, "WalletSummary": { "properties": {}, "additionalProperties": true, "type": "object", "title": "WalletSummary", "description": "Dashboard-bundle for the wallet page header. Composite shape:\nidentity + counts + related-address count." }, "WalletTokensList": { "properties": { "items": { "items": { "additionalProperties": true, "type": "object" }, "type": "array", "title": "Items" }, "address": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Address" }, "network": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Network" } }, "additionalProperties": true, "type": "object", "title": "WalletTokensList", "description": "QRL2 token-portfolio for a single address." }, "WalletsPaginated": { "properties": { "items": { "items": { "$ref": "#/components/schemas/WalletDetail" }, "type": "array", "title": "Items" }, "total": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Total" }, "limit": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Limit" }, "offset": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Offset" }, "has_next": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Has Next" }, "has_prev": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Has Prev" } }, "type": "object", "title": "WalletsPaginated" }, "WithdrawalItem": { "properties": { "chain": { "type": "string", "title": "Chain" }, "network": { "type": "string", "title": "Network" }, "height": { "type": "integer", "title": "Height" }, "block_hash": { "type": "string", "title": "Block Hash" }, "withdrawal_index": { "type": "integer", "title": "Withdrawal Index" }, "chain_index": { "type": "integer", "title": "Chain Index" }, "validator_index": { "type": "integer", "title": "Validator Index" }, "address": { "type": "string", "title": "Address" }, "amount": { "type": "string", "title": "Amount" }, "timestamp": { "type": "string", "title": "Timestamp" } }, "additionalProperties": true, "type": "object", "required": [ "chain", "network", "height", "block_hash", "withdrawal_index", "chain_index", "validator_index", "address", "amount", "timestamp" ], "title": "WithdrawalItem" }, "WithdrawalSummaryResponse": { "properties": { "total_withdrawals": { "type": "integer", "title": "Total Withdrawals", "default": 0 }, "total_amount": { "type": "string", "title": "Total Amount", "default": "0" }, "unique_recipients": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Unique Recipients" }, "approx_unique_recipients": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Approx Unique Recipients" }, "first_day": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "First Day" }, "last_day": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Last Day" } }, "additionalProperties": true, "type": "object", "title": "WithdrawalSummaryResponse" }, "WithdrawalsPaginated": { "properties": { "items": { "items": { "$ref": "#/components/schemas/WithdrawalItem" }, "type": "array", "title": "Items" }, "total": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Total" }, "page": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Page" }, "page_size": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Page Size" }, "total_pages": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Total Pages" }, "limit": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Limit" }, "offset": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Offset" }, "has_next": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Has Next" }, "has_prev": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Has Prev" } }, "type": "object", "title": "WithdrawalsPaginated" } } } }