{"openapi":"3.1.0","info":{"title":"ShorScan Public API","version":"1.1.0","description":"ShorScan is the block explorer for the QRL 2.0 public testnet. This API is free to use: no API key, no signup. On-chain data reflects the QRL 2.0 testnet, and testnet coins have no monetary value. The market order-book endpoint serves public QRL/USDT spot data from MEXC.\n\nCORS: GET endpoints respond with Access-Control-Allow-Origin: * and can be called directly from any web page. POST endpoints allow cross-origin browser access only from the explorer's own origins and from browser-extension origins, so browser apps hosted elsewhere should treat POST endpoints as server-side calls.\n\nPagination: list endpoints take page and limit query parameters, and limit is capped at 100 items. Most list endpoints number pages from 1; the contract and token list endpoints number pages from 0. Each operation documents its own defaults.\n\nNumeric encoding: on-chain quantities (block fields, gas values, raw transaction values) are 0x-prefixed hexadecimal strings. Indexed aggregates are decimal strings or JSON numbers. Coin amounts are denominated in Quanta (1 Quanta = 10^9 Shor = 10^18 Planck); fields carrying exact amounts use decimal strings.\n\nCaching and limits: hot endpoints are cached server side for 3 to 30 seconds, noted per operation. The four POST contract endpoints carry per-IP rate limits and return 429 with body {\"error\": \"rate limit exceeded\"} when exhausted."},"servers":[{"url":"https://shorscan.com"}],"tags":[{"name":"Status","description":"Service health."},{"name":"Overview & Market","description":"Network overview and QRL market data."},{"name":"Blocks","description":"Block lists, block details, and block size history."},{"name":"Transactions & Mempool","description":"Confirmed transactions, the latest-transactions feed, and pending mempool transactions."},{"name":"Addresses","description":"Address details, balances, per-address history, and wallet statistics."},{"name":"Tokens & NFTs","description":"Deployed contracts, token summaries, holders, transfers, and NFT metadata."},{"name":"Validators & Epochs","description":"Proof of stake validator set and beacon chain epoch data."},{"name":"Gas","description":"Gas price snapshots and history."},{"name":"Contract Verification","description":"Source verification for deployed contracts (Hyperion compiler)."},{"name":"Contract Interaction","description":"Read calls against known contracts and AI explanations of verified source."},{"name":"Faucet & Site","description":"Endpoints served by the explorer web app itself: search redirect and the testnet faucet."}],"paths":{"/api/slashings":{"get":{"tags":["Validators & Epochs"],"operationId":"getSlashings","summary":"Slashings","description":"Finalized slashing evidence, ordered by slot descending with a stable ID tie-breaker.","parameters":[{"name":"page","in":"query","schema":{"type":"integer","default":1,"minimum":1,"maximum":1000000}},{"name":"limit","in":"query","schema":{"type":"integer","default":20,"minimum":1,"maximum":100}},{"name":"validator","in":"query","description":"Optional validator index, including zero.","schema":{"type":"string","pattern":"^[0-9]+$"}}],"responses":{"200":{"description":"Paginated records. Empty lists are arrays.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SlashingsResponse"}}}},"400":{"description":"Invalid pagination, validator index, epoch range, or kind.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"$ref":"#/components/responses/InternalError"}}}},"/api/validator-set-changes":{"get":{"tags":["Validators & Epochs"],"operationId":"getValidatorSetChanges","summary":"Validator set changes","description":"Validator set milestones, ordered by epoch descending with a stable ID tie-breaker. Epoch bounds are inclusive.","parameters":[{"name":"page","in":"query","schema":{"type":"integer","default":1,"minimum":1,"maximum":1000000}},{"name":"limit","in":"query","schema":{"type":"integer","default":20,"minimum":1,"maximum":100}},{"name":"validator","in":"query","description":"Optional validator index, including zero.","schema":{"type":"string","pattern":"^[0-9]+$"}},{"name":"fromEpoch","in":"query","schema":{"type":"integer","minimum":0,"format":"int64"}},{"name":"toEpoch","in":"query","schema":{"type":"integer","minimum":0,"format":"int64"}},{"name":"kind","in":"query","description":"Ejected selects unslashed validators whose effective balance at exit is at or below the beacon EJECTION_BALANCE. Exited includes all other exits.","schema":{"type":"string","enum":["activated","exited","slashed","ejected"]}}],"responses":{"200":{"description":"Paginated records. Empty lists are arrays.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidatorSetChangesResponse"}}}},"400":{"description":"Invalid pagination, validator index, epoch range, or kind.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"$ref":"#/components/responses/InternalError"}}}},"/api/health":{"get":{"tags":["Status"],"operationId":"getHealth","summary":"Service health check","description":"Pings the database with a 3 second budget. Returns 200 when the API can reach its data store and 503 when it cannot.","responses":{"200":{"description":"Service is healthy.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","const":"ok"}},"required":["status"]},"example":{"status":"ok"}}}},"503":{"description":"Database unreachable.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","const":"error"},"error":{"type":"string"}}},"example":{"status":"error","error":"database unreachable"}}}}}}},"/api/overview":{"get":{"tags":["Overview & Market"],"operationId":"getOverview","summary":"Network and market overview","description":"Homepage hero data: market figures, wallet count, circulating supply, daily volume, validator count, and contract count in one call. Cached server side for 10 seconds.","responses":{"200":{"description":"Aggregated overview.","content":{"application/json":{"schema":{"type":"object","properties":{"marketcap":{"type":"number","description":"Market capitalization in USD."},"currentPrice":{"type":"number","description":"Spot price in USD."},"priceChange24h":{"type":"number","description":"24 hour price change in percent."},"countwallets":{"type":"integer","description":"Number of indexed wallet addresses."},"circulating":{"type":"string","description":"Circulating supply in Quanta as a decimal string."},"volume":{"type":"number","description":"Daily on-chain transferred volume."},"tradingVolume":{"type":"number","description":"24 hour trading volume in USD."},"validatorCount":{"type":"integer"},"contractCount":{"type":"integer"},"status":{"type":"object","properties":{"syncing":{"type":"boolean"},"dataInitialized":{"type":"boolean","description":"False while the indexer has not yet written its first market and supply samples."}}}}},"example":{"marketcap":32500000,"currentPrice":0.42,"priceChange24h":-1.8,"countwallets":10412,"circulating":"65000000","volume":1532,"tradingVolume":210034,"validatorCount":128,"contractCount":342,"status":{"syncing":true,"dataInitialized":true}}}}},"500":{"$ref":"#/components/responses/InternalError"}}}},"/api/price-history":{"get":{"tags":["Overview & Market"],"operationId":"getPriceHistory","summary":"Historical price samples","description":"Price, market cap, and volume snapshots for charts and wallet apps.","parameters":[{"name":"interval","in":"query","description":"Time window for the returned samples.","schema":{"type":"string","enum":["4h","12h","24h","7d","30d","all"],"default":"24h"}}],"responses":{"200":{"description":"Price history for the requested interval.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"timestamp":{"type":"string","description":"RFC 3339 timestamp."},"priceUSD":{"type":"number"},"marketCapUSD":{"type":"number"},"volumeUSD":{"type":"number"}}}},"interval":{"type":"string"},"count":{"type":"integer"}}}}}},"400":{"description":"Invalid interval value.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"$ref":"#/components/responses/InternalError"}}}},"/api/market/orderbook":{"get":{"tags":["Overview & Market"],"operationId":"getMarketOrderBook","summary":"Live QRL/USDT order book","description":"Returns a server-side snapshot of the fixed MEXC QRLUSDT spot market: up to 100 bid levels, 100 ask levels, 100 recent trades, and 24-hour ticker data. Successful snapshots and upstream failures are cached for 3 seconds, limiting MEXC request bursts during rate limits or outages. This public endpoint requires no MEXC API key and accepts no venue, symbol, or upstream URL parameters.","responses":{"200":{"description":"Normalized MEXC QRLUSDT market snapshot.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarketOrderBook"},"example":{"venue":"MEXC","symbol":"QRLUSDT","fetchedAt":"2026-08-09T12:14:58.123Z","lastUpdateId":905062254,"bids":[{"price":"0.75744","quantity":"2.17"}],"asks":[{"price":"0.76112","quantity":"2.2"}],"recentTrades":[{"id":"synthetic-8aa7a9881988250bd4110726-0","price":"0.76117","quantity":"11.52","quoteQuantity":"8.7686784","time":1786290460978,"aggressorSide":"buy"}],"ticker":{"high":"0.80336","low":"0.7271","last":"0.76117","change":"-0.00088","changePercent":"-0.0011","baseVolume":"16478.3","quoteVolume":"12623.92215"}}}}},"500":{"$ref":"#/components/responses/InternalError"},"502":{"description":"MEXC returned an invalid response or could not be reached within the request budget.","headers":{"Retry-After":{"description":"Seconds before ShorScan will attempt another MEXC fetch.","schema":{"type":"integer","const":3}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"market data temporarily unavailable"}}}}}}},"/api/market/fundflow":{"get":{"tags":["Overview & Market"],"operationId":"getMarketFundFlow","summary":"Collected fund flow by trade size","description":"Aggregates retained venue executions into taker buy and sell volume by trade size and a net buy volume series. Net buy volume is buy quantity minus sell quantity in QRL; deposits and withdrawals are excluded. The 7d window uses 6-hour intervals and the 30d window uses daily intervals. The daily series spans 7 or 30 UTC days for those windows, and five UTC days for shorter windows, including the current partial day. Size bands are ShorScan's own classification by quote notional. History is limited to recorded executions with 45-day retention; no historical backfill is performed. Coverage timestamps describe retained history and do not establish uninterrupted collection. Results are cached for 30 seconds per venue and window.","parameters":[{"name":"venue","in":"query","required":false,"description":"Venue id to roll up. Defaults to the first configured venue.","schema":{"type":"string","default":"mexc"}},{"name":"window","in":"query","required":false,"description":"Rollup window.","schema":{"type":"string","enum":["15m","30m","1h","2h","4h","1d","7d","30d"],"default":"1d"}}],"responses":{"200":{"description":"Fund-flow rollup for the requested venue and window.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarketFundFlow"},"example":{"venue":{"id":"mexc","name":"MEXC","symbol":"QRLUSDT","quoteAsset":"USDT"},"venues":[{"id":"mexc","name":"MEXC","symbol":"QRLUSDT","quoteAsset":"USDT"}],"window":"1d","windows":["15m","30m","1h","2h","4h","1d","7d","30d"],"windowStart":1787054541000,"windowEnd":1787140941000,"seriesStepMs":3600000,"bands":{"mediumFrom":10,"largeFrom":100,"quoteAsset":"USDT"},"buckets":[{"bucket":"large","buyQuantity":1566.72,"sellQuantity":565.36,"netQuantity":1001.36,"buyQuote":1284.71,"sellQuote":463.59,"netQuote":821.12,"buyTradeCount":6,"sellTradeCount":3}],"totals":{"bucket":"total","buyQuantity":2376.53,"sellQuantity":2757.33,"netQuantity":-380.8,"buyQuote":1948.75,"sellQuote":2261.03,"netQuote":-312.28,"buyTradeCount":85,"sellTradeCount":116},"series":[{"time":1787137341000,"buyQuantity":41.88,"sellQuantity":0,"netQuantity":41.88}],"daily":[{"time":1787011200000,"buyQuantity":1204.5,"sellQuantity":1560.25,"netQuantity":-355.75}],"dailyDays":5,"dailyStart":1786752000000,"dailyEnd":1787140941000,"coverage":{"firstTradeAt":1787109737460,"lastTradeAt":1787140595875,"tradeCount":201,"complete":false}}}}},"400":{"description":"Unknown venue or window.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"invalid window; expected one of 15m, 30m, 1h, 2h, 4h, 1d, 7d, 30d"}}}},"500":{"$ref":"#/components/responses/InternalError"}}}},"/api/latestblock":{"get":{"tags":["Blocks"],"operationId":"getLatestBlock","summary":"Latest indexed block height","description":"Returns the latest synced block number as a decimal integer, plus the current QRL/USD price so fee displays need no second request. Cached server side for 5 seconds.","responses":{"200":{"description":"Latest block height and spot price.","content":{"application/json":{"schema":{"type":"object","properties":{"blockNumber":{"type":"integer"},"qrlUsdPrice":{"type":"number"}}},"example":{"blockNumber":148512,"qrlUsdPrice":0.42}}}},"500":{"$ref":"#/components/responses/InternalError"}}}},"/api/blocks":{"get":{"tags":["Blocks"],"operationId":"getBlocks","summary":"Paginated block list","description":"Newest blocks first, with a per-block activity rollup (token transfers and internal calls). The reported total is capped at 300 pages worth of blocks. Cached server side for 10 seconds.","parameters":[{"name":"page","in":"query","description":"Page number, starting at 1.","schema":{"type":"integer","default":1,"minimum":1}},{"name":"limit","in":"query","description":"Blocks per page. Capped at 100.","schema":{"type":"integer","default":5,"maximum":100}}],"responses":{"200":{"description":"One page of blocks.","content":{"application/json":{"schema":{"type":"object","properties":{"blocks":{"type":"array","items":{"$ref":"#/components/schemas/BlockResult"}},"total":{"type":"integer","description":"Total block count, capped at 300 pages at the current limit."},"blockActivity":{"type":"object","description":"Map keyed by the block's 0x-prefixed hex number. Present only for blocks with token or internal-call activity.","additionalProperties":{"type":"object","properties":{"tokenTransfers":{"type":"integer"},"internalCalls":{"type":"integer"}}}}}},"example":{"blocks":[{"number":"0x24420","hash":"0x8a4f0c2b7d1e5f3a9c6b8d0e2f4a6c8e0b2d4f6a8c0e2b4d6f8a0c2e4b6d8f0a","parentHash":"0x7b3e0d1a6c0d4e2f8b5a7c9d1e3f5a7b9d1f3a5c7e9b1d3f5a7c9e1b3d5f7a9c","timestamp":"0x6a743280","gasUsed":"0x5208","gasLimit":"0x1c9c380","baseFeePerGas":"0x3b9aca00","miner":"QaaaAAaaaAAaAaaAaAAAAaAAAaAaAaAAaAaaAaaaaAAAAAAAAaAAAAaAaAAaaAAaaaaAaAAAAaaAaAAaaaaaaAaAAaaaaAaAaaaaAaaaAAAAaAAAAaAaAaaAAAaAaaaAA","size":"0x2d0","transactions":[]}],"total":1500,"blockActivity":{"0x24420":{"tokenTransfers":2,"internalCalls":1}}}}}},"500":{"$ref":"#/components/responses/InternalError"}}}},"/api/block/{query}":{"get":{"tags":["Blocks"],"operationId":"getBlock","summary":"Block detail","description":"Fetches one block by number, in decimal or 0x-prefixed hex form, or by its 0x + 64 hex block hash, plus per-transaction activity counts.","parameters":[{"name":"query","in":"path","required":true,"description":"Block number as a decimal integer or 0x-prefixed hex string (up to 16 hex digits), or a block hash as 0x followed by 64 hex characters.","schema":{"type":"string"}}],"responses":{"200":{"description":"Block detail with per-transaction activity map.","content":{"application/json":{"schema":{"type":"object","properties":{"block":{"type":"object","properties":{"jsonrpc":{"type":"string"},"id":{"type":"integer"},"result":{"$ref":"#/components/schemas/BlockResult"}}},"txActivity":{"type":"object","description":"Map keyed by transaction hash. Present only for transactions with token or internal-call activity.","additionalProperties":{"type":"object","properties":{"tokenTransfers":{"type":"integer"},"internalCalls":{"type":"integer"}}}}}},"example":{"block":{"jsonrpc":"2.0","id":1,"result":{"number":"0x24420","hash":"0x8a4f0c2b7d1e5f3a9c6b8d0e2f4a6c8e0b2d4f6a8c0e2b4d6f8a0c2e4b6d8f0a","timestamp":"0x6a743280","gasUsed":"0x5208","gasLimit":"0x1c9c380","transactions":[]}},"txActivity":{}}}}},"400":{"description":"Invalid block number format.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Block not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"$ref":"#/components/responses/InternalError"}}}},"/api/blocksizes":{"get":{"tags":["Blocks"],"operationId":"getBlockSizes","summary":"Block size time series","description":"Precomputed block size samples for charts, sorted by timestamp ascending and capped at 2000 points. Cached server side for 30 seconds.","responses":{"200":{"description":"Block size samples.","content":{"application/json":{"schema":{"type":"object","properties":{"response":{"type":"array","items":{"type":"object","description":"One sample per block. blockNumber, timestamp, and size are 0x-prefixed hex strings; transactionCount is an integer.","additionalProperties":true}}}}}}},"500":{"$ref":"#/components/responses/InternalError"}}}},"/api/txs":{"get":{"tags":["Transactions & Mempool"],"operationId":"getTxs","summary":"Paginated network transaction list","description":"Network-wide confirmed transactions, newest first, with the total count and the latest block height for confirmation math. Cached server side for 10 seconds.","parameters":[{"name":"page","in":"query","description":"Page number, starting at 1.","schema":{"type":"integer","default":1,"minimum":1}},{"name":"limit","in":"query","description":"Items per page. Capped at 100.","schema":{"type":"integer","default":10,"maximum":100}}],"responses":{"200":{"description":"One page of transactions.","content":{"application/json":{"schema":{"type":"object","properties":{"txs":{"type":"array","items":{"$ref":"#/components/schemas/TransactionByAddress"}},"total":{"type":"integer"},"latestBlock":{"type":"integer"}}}}}},"500":{"$ref":"#/components/responses/InternalError"}}}},"/api/transactions":{"get":{"tags":["Transactions & Mempool"],"operationId":"getLatestTransactions","summary":"Latest transactions feed","description":"Fixed-size feed of the most recent confirmed transactions, used by the homepage. Cached server side for 5 seconds.","responses":{"200":{"description":"Latest transactions.","content":{"application/json":{"schema":{"type":"object","properties":{"response":{"type":"array","items":{"$ref":"#/components/schemas/TransactionByAddress"}}}}}}},"500":{"$ref":"#/components/responses/InternalError"}}}},"/api/tx/{query}":{"get":{"tags":["Transactions & Mempool"],"operationId":"getTransaction","summary":"Transaction detail","description":"Full detail for one confirmed transaction: transfer record, indexed receipt accounting with live enrichment for legacy gaps, event logs, calldata, token transfers, internal calls, and contract metadata for decoding. This endpoint is deliberately uncached so a newly mined transaction shows its true confirmation count immediately.","parameters":[{"name":"query","in":"path","required":true,"description":"Transaction hash: 0x followed by 64 hex characters.","schema":{"type":"string","pattern":"^0x[0-9a-fA-F]{64}$"}}],"responses":{"200":{"description":"Transaction detail. Optional fields appear only when the transaction has the corresponding data.","content":{"application/json":{"schema":{"type":"object","properties":{"response":{"$ref":"#/components/schemas/Transfer"},"latestBlock":{"type":"integer","description":"Latest indexed block height as a decimal integer."},"receiptStatus":{"type":"string","description":"EVM receipt status: 0x1 success, 0x0 reverted. Indexed status survives receipt fetch failure. Absent only when neither storage nor a matching live receipt supplies it."},"logs":{"type":"array","items":{"type":"object","properties":{"address":{"type":"string"},"topics":{"type":"array","items":{"type":"string"}},"data":{"type":"string"},"logIndex":{"type":"string"},"removed":{"type":"boolean"},"contract":{"$ref":"#/components/schemas/ContractMeta"}}}},"input":{"type":"string","description":"Transaction calldata as a 0x-prefixed hex string. Present for contract calls."},"targetContract":{"$ref":"#/components/schemas/ContractMeta"},"contractCreated":{"type":"object","properties":{"address":{"type":"string"},"isToken":{"type":"boolean"},"name":{"type":"string"},"symbol":{"type":"string"},"decimals":{"type":"integer"},"tokenStandard":{"type":"string"}}},"tokenTransfers":{"type":"array","items":{"type":"object","properties":{"contractAddress":{"type":"string"},"from":{"type":"string"},"to":{"type":"string"},"amount":{"type":"string"},"tokenName":{"type":"string"},"tokenSymbol":{"type":"string"},"tokenDecimals":{"type":"integer"},"tokenStandard":{"type":"string"},"tokenID":{"type":"string"},"logIndex":{"type":"string"}}}},"internalTransactions":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"callType":{"type":"string"},"from":{"type":"string"},"to":{"type":"string"},"input":{"type":"string"},"output":{"type":"string"},"value":{"type":"string"},"gas":{"type":"string"},"gasUsed":{"type":"string"},"traceAddress":{"type":"array","items":{"type":"integer"}}}}}}},"example":{"response":{"ID":"665f1c2ab3d4e5f60718293a","BlockNumber":"0x24420","BlockTimestamp":"0x6a743280","From":"QaaaAAaaaAAaAaaAaAAAAaAAAaAaAaAAaAaaAaaaaAAAAAAAAaAAAAaAaAAaaAAaaaaAaAAAAaaAaAAaaaaaaAaAAaaaaAaAaaaaAaaaAAAAaAAAAaAaAaaAAAaAaaaAA","To":"QBbBbbBBbBbBBBBbBbBbBBbBBBbBBBbBbBBBbbbBBbBBbBbbBBBBbBBbbbbbBbbBBbbBBBbbBBbbbBbBBbBBbbbbBBbBBBbBbBBbbBbbBBbBBBBbbBBbbbbBBBbbBbbBb","TxHash":"0x9c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d","Value":"0x2386f26fc10000","GasUsed":"0x5208","GasPrice":"0x3b9aca00","Nonce":"0x4","Size":"0x2d0"},"latestBlock":148512,"receiptStatus":"0x1"}}}},"400":{"description":"Invalid transaction hash format.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Transaction not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"$ref":"#/components/responses/InternalError"}}}},"/api/coinbase/{query}":{"get":{"tags":["Transactions & Mempool"],"operationId":"getCoinbaseTransaction","summary":"Raw transfer record lookup","description":"Returns the stored transfer record for one transaction hash. A missing transaction still returns 200 with an empty record; this preserves the endpoint's historical behavior.","parameters":[{"name":"query","in":"path","required":true,"description":"Transaction hash: 0x followed by 64 hex characters.","schema":{"type":"string","pattern":"^0x[0-9a-fA-F]{64}$"}}],"responses":{"200":{"description":"Transfer record, empty when the hash is unknown.","content":{"application/json":{"schema":{"type":"object","properties":{"response":{"$ref":"#/components/schemas/Transfer"}}}}}},"400":{"description":"Invalid transaction hash format.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"$ref":"#/components/responses/InternalError"}}}},"/api/pending-transactions":{"get":{"tags":["Transactions & Mempool"],"operationId":"getPendingTransactions","summary":"Paginated mempool transactions","description":"Transactions currently observed in the mempool. Cached server side for 5 seconds, matching mempool turnover.","parameters":[{"name":"page","in":"query","description":"Page number, starting at 1.","schema":{"type":"integer","default":1,"minimum":1}},{"name":"limit","in":"query","description":"Items per page. Capped at 100.","schema":{"type":"integer","default":10,"maximum":100}}],"responses":{"200":{"description":"One page of pending transactions.","content":{"application/json":{"schema":{"type":"object","properties":{"transactions":{"type":"array","items":{"$ref":"#/components/schemas/PendingTransaction"}},"total":{"type":"integer"},"page":{"type":"integer"},"limit":{"type":"integer"},"totalPages":{"type":"integer"}}}}}},"500":{"$ref":"#/components/responses/InternalError"}}}},"/api/pending-transaction/{hash}":{"get":{"tags":["Transactions & Mempool"],"operationId":"getPendingTransaction","summary":"Pending transaction detail","description":"Detail for one mempool transaction, including verified-contract metadata for the recipient when available. Returns 404 once the transaction has been mined or dropped; clients then fetch /api/tx/{hash} for the confirmed payload.","parameters":[{"name":"hash","in":"path","required":true,"description":"Transaction hash: 0x followed by 64 hex characters.","schema":{"type":"string","pattern":"^0x[0-9a-fA-F]{64}$"}}],"responses":{"200":{"description":"Pending transaction detail.","content":{"application/json":{"schema":{"type":"object","properties":{"transaction":{"$ref":"#/components/schemas/PendingTransaction"},"targetContract":{"$ref":"#/components/schemas/ContractMeta"}}}}}},"400":{"description":"Invalid transaction hash format.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Transaction has been mined, dropped, or was never seen. The body's status field is \"mined\" when the transaction confirmed.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"status":{"type":"string"},"details":{"type":"string"}}}}}},"500":{"$ref":"#/components/responses/InternalError"}}}},"/api/pending-tx-eta/{hash}":{"get":{"tags":["Transactions & Mempool"],"operationId":"getPendingTxEta","summary":"Inclusion ETA for a pending transaction","description":"Best-effort estimate of when a pending transaction will be included, derived from recent block statistics and the gas queued ahead of it in the mempool. Cached server side for 5 seconds.","parameters":[{"name":"hash","in":"path","required":true,"description":"Transaction hash: 0x followed by 64 hex characters.","schema":{"type":"string","pattern":"^0x[0-9a-fA-F]{64}$"}}],"responses":{"200":{"description":"ETA and the supporting numbers.","content":{"application/json":{"schema":{"type":"object","properties":{"etaSec":{"type":"number","nullable":true,"description":"Estimated seconds until inclusion, at minimum one average block time. Null when block timing is unavailable."},"avgBlockTimeSec":{"type":"number","nullable":true,"description":"Mean interval between recent blocks, falling back to the stored seconds per slot. Null when both are unavailable."},"avgGasUsedHex":{"type":"string","description":"0x-prefixed hex."},"pendingCount":{"type":"integer"},"gasAheadHex":{"type":"string","description":"0x-prefixed hex sum of gas queued at a higher or equal gas price."},"medianGasPriceHex":{"type":"string","description":"0x-prefixed hex."},"yourGasPriceHex":{"type":"string","description":"0x-prefixed hex gas price of the queried transaction."}}}}}},"400":{"description":"Invalid transaction hash format.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"The transaction is no longer pending.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"$ref":"#/components/responses/InternalError"}}}},"/api/address/aggregate/{query}":{"get":{"tags":["Addresses"],"operationId":"getAddressAggregate","summary":"Address detail aggregation","description":"Everything the address page needs in one call: balance record, transaction counts, activity range, richlist rank, paginated transaction and internal-transaction lists, and contract metadata when the address is a contract. Cached server side for 10 seconds.","parameters":[{"name":"query","in":"path","required":true,"description":"Address alias: Q/q or 0x/0X followed by 128 hex characters. Mixed-case bodies require a valid QIP-55 checksum.","schema":{"type":"string","pattern":"^([Qq]|0x|0X)[0-9a-fA-F]{128}$"}},{"name":"page","in":"query","description":"Page number for the transaction lists, starting at 1.","schema":{"type":"integer","default":1,"minimum":1}},{"name":"limit","in":"query","description":"Items per page. Capped at 100.","schema":{"type":"integer","default":10,"maximum":100}}],"responses":{"200":{"description":"Aggregated address detail.","content":{"application/json":{"schema":{"type":"object","properties":{"address":{"type":"object","description":"Indexed balance record. balance is a JSON number denominated in Quanta.","properties":{"ObjectId":{"type":"string"},"id":{"type":"string"},"balance":{"type":"number"},"nonce":{"type":"integer"}}},"transactions_count":{"type":"integer"},"internal_transactions_count":{"type":"integer"},"first_seen":{"type":"integer","description":"Unix timestamp of the first indexed activity, 0 when none."},"last_seen":{"type":"integer","description":"Unix timestamp of the latest indexed activity, 0 when none."},"rank":{"type":"integer","description":"Richlist rank by balance."},"transactions_by_address":{"type":"array","items":{"$ref":"#/components/schemas/TransactionByAddress"}},"internal_transactions_by_address":{"type":"array","items":{"type":"object","properties":{"Type":{"type":"string"},"CallType":{"type":"string"},"Hash":{"type":"string"},"From":{"type":"string"},"To":{"type":"string"},"Input":{"type":"string"},"Output":{"type":"string"},"Value":{"type":"string"},"Gas":{"type":"string"},"GasUsed":{"type":"string"},"AddressFunctionIdentifier":{"type":"string"},"AmountFunctionIdentifier":{"type":"string"},"BlockTimestamp":{"type":"string"},"TraceAddress":{"type":"array","items":{"type":"integer"}}}}},"contract_code":{"type":"object","description":"Contract record when the address is a contract, empty otherwise.","additionalProperties":true},"latestBlock":{"type":"integer"},"page":{"type":"integer"},"limit":{"type":"integer"}}},"example":{"address":{"ObjectId":"665f1c2ab3d4e5f60718293a","id":"QaaaAAaaaAAaAaaAaAAAAaAAAaAaAaAAaAaaAaaaaAAAAAAAAaAAAAaAaAAaaAAaaaaAaAAAAaaAaAAaaaaaaAaAAaaaaAaAaaaaAaaaAAAAaAAAAaAaAaaAAAaAaaaAA","balance":12.5,"nonce":3},"transactions_count":2,"internal_transactions_count":0,"first_seen":1782300000,"last_seen":1786000000,"rank":57,"transactions_by_address":[{"InOut":1,"TxType":"transfer","Address":"QaaaAAaaaAAaAaaAaAAAAaAAAaAaAaAAaAaaAaaaaAAAAAAAAaAAAAaAaAAaaAAaaaaAaAAAAaaAaAAaaaaaaAaAAaaaaAaAaaaaAaaaAAAAaAAAAaAaAaaAAAaAaaaAA","From":"QaaaAAaaaAAaAaaAaAAAAaAAAaAaAaAAaAaaAaaaaAAAAAAAAaAAAAaAaAAaaAAaaaaAaAAAAaaAaAAaaaaaaAaAAaaaaAaAaaaaAaaaAAAAaAAAAaAaAaaAAAaAaaaAA","To":"QBbBbbBBbBbBBBBbBbBbBBbBBBbBBBbBbBBBbbbBBbBBbBbbBBBBbBBbbbbbBbbBBbbBBBbbBBbbbBbBBbBBbbbbBBbBBBbBbBBbbBbbBBbBBBBbbBBbbbbBBBbbBbbBb","TxHash":"0x9c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d","TimeStamp":"1786000000","Amount":"3.300000000000000000","PaidFees":"0.000021000000000000","BlockNumber":"148512"}],"internal_transactions_by_address":[],"contract_code":{},"latestBlock":148512,"page":1,"limit":10}}}},"400":{"description":"Invalid address format.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"$ref":"#/components/responses/InternalError"},"503":{"description":"The indexed native balance was invalidated by a chain reorganization and is being reconciled. Retry-After is 5 seconds.","headers":{"Retry-After":{"description":"Suggested retry delay in seconds.","schema":{"type":"integer","example":5}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/qns/resolve/{name}":{"get":{"tags":["Addresses"],"operationId":"resolveQnsName","summary":"Resolve a QNS name","description":"Resolves a conservatively normalized ASCII name below .qrl to its canonical checksummed QIP-55 address. Resolution is enabled only when the backend has a registry address and expected chain ID configured, and it verifies both the connected chain and registry bytecode before reading records. Successful deployment checks and name resolutions are cached server side for 15 seconds. Rate limited per IP: bucket of 30 requests, refilling 30 per minute, independent of reverse lookups. Server callers with a matching nonempty QNS_INTERNAL_TOKEN in X-QNS-Internal-Token bypass this limit without consuming its allowance.","parameters":[{"name":"name","in":"path","required":true,"description":"QNS name below .qrl. ASCII uppercase folds to lowercase; labels accept a-z, 0-9, and hyphen. Empty labels, Unicode, and the reserved double-hyphen pattern in positions three and four are rejected.","schema":{"type":"string","minLength":5,"maxLength":255},"example":"moscowchill.qrl"}],"responses":{"200":{"description":"The normalized name and its canonical QIP-55 address.","content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"Normalized lowercase QNS name."},"address":{"type":"string","description":"Canonical uppercase-Q, SHAKE256-checksummed QIP-55 address."}},"required":["name","address"]},"example":{"name":"moscowchill.qrl","address":"QaaaAAaaaAAaAaaAaAAAAaAAAaAaAaAAaAaaAaaaaAAAAAAAAaAAAAaAaAAaaAAaaaaAaAAAAaaAaAAaaaaaaAaAAaaaaAaAaaaaAaaaAAAAaAAAAaAaAaaAAAaAaaaAA"}}}},"400":{"description":"Invalid or unsupported QNS name.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"invalid QNS name"}}}},"404":{"description":"The name has no resolver, or its resolver has no address record or fails addr(bytes32) deterministically (a revert or another VM error). Cached for the normal 15-second TTL.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["QNS name has no resolver","QNS name has no address record"]},"name":{"type":"string","description":"Normalized QNS name."}},"required":["error","name"]},"example":{"error":"QNS name has no address record","name":"moscowchill.qrl"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"},"502":{"description":"The node connection or a registry call failed, or the node returned an unknown RPC error or a malformed QNS response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"QNS resolution failed"}}}},"503":{"description":"QNS is unconfigured, the configured chain does not match, or registry bytecode is unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"unconfigured":{"value":{"error":"QNS resolution is not configured"}},"chainMismatch":{"value":{"error":"QNS deployment does not match the connected chain"}},"registryUnavailable":{"value":{"error":"QNS registry is unavailable on the connected chain"}}}}}},"504":{"description":"The bounded QNS lookup timed out.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"QNS resolution timed out"}}}}}}},"/api/qns/reverse/{address}":{"get":{"tags":["Addresses"],"operationId":"reverseQnsAddress","summary":"Look up a verified QNS primary name","description":"Reads the address's addr.reverse resolver and name record, normalizes the name, and verifies that its forward address record resolves to the same canonical QIP-55 address. A name is returned only after this verification succeeds. Uses the forward resolver's configured registry, chain and bytecode checks and bounded timeouts. Its independent per-IP bucket holds 60 requests and refills 60 per minute. Server callers with a matching nonempty QNS_INTERNAL_TOKEN in X-QNS-Internal-Token bypass this limit without consuming its allowance. Successful deployment checks, verified names, and real negative records are cached server side for 15 seconds. Transport failures return 502 and remain uncached.","parameters":[{"name":"address","in":"path","required":true,"description":"Address alias: Q/q or 0x/0X followed by 128 hex characters. Mixed-case bodies require a valid QIP-55 checksum.","schema":{"type":"string","pattern":"^([Qq]|0x|0X)[0-9a-fA-F]{128}$"}}],"responses":{"200":{"description":"The canonical QIP-55 address and its normalized, forward-verified primary name.","content":{"application/json":{"schema":{"type":"object","properties":{"address":{"type":"string","description":"Canonical uppercase-Q, SHAKE256-checksummed QIP-55 address."},"name":{"type":"string","description":"Normalized lowercase QNS name verified by forward resolution."}},"required":["address","name"]},"example":{"address":"QaaaAAaaaAAaAaaAaAAAAaAAAaAaAaAAaAaaAaaaaAAAAAAAAaAAAAaAaAAaaAAaaaaAaAAAAaaAaAAaaaaaaAaAAaaaaAaAaaaaAaaaAAAAaAAAAaAaAaaAAAaAaaaAA","name":"alice.qrl"}}}},"400":{"description":"Invalid or unsupported address.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"invalid QNS address"}}}},"404":{"description":"The reverse resolver or name is missing, the name resolver or forward address resolver has a deterministic execution failure (such as a revert, invalid opcode, out of gas, stack underflow or overflow, or write protection) or returns an empty or malformed record, the forward resolver is missing, or forward resolution resolves to a different address. Cached for the normal 15-second TTL.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["QNS address has no verified primary name"]},"address":{"type":"string","description":"Canonical QIP-55 address."}},"required":["error","address"]}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"},"502":{"description":"The node RPC failed, timed out, was canceled, returned an unknown RPC error or malformed RPC envelope, or a registry lookup failed or returned a malformed resolver word during the reverse lookup or its forward verification. Uncached so the next request retries.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"QNS resolution failed"}}}},"503":{"description":"QNS is unconfigured, the configured chain does not match, or registry bytecode is unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/qns/node/{node}":{"get":{"tags":["Addresses"],"operationId":"lookupQnsNode","summary":"Look up a QNS name hash","description":"Reads owner(bytes32) and resolver(bytes32) for a 32-byte QNS node (EIP-137 namehash) from the configured registry, then the resolver's name(bytes32) record. The name is returned only when the normalized name hashes back to the requested node; otherwise name is null. Uses the forward resolver's registry, chain and bytecode checks, bounded timeouts and 15-second server cache. Its independent per-IP bucket holds 60 requests and refills 60 per minute. Server callers with a matching nonempty QNS_INTERNAL_TOKEN in X-QNS-Internal-Token bypass this limit without consuming its allowance.","parameters":[{"name":"node","in":"path","required":true,"description":"QNS node: 0x or 0X followed by 64 hex characters.","schema":{"type":"string","pattern":"^0[xX][0-9a-fA-F]{64}$"}}],"responses":{"200":{"description":"The node has a nonzero registry owner.","content":{"application/json":{"schema":{"type":"object","properties":{"node":{"type":"string","description":"The node as 0x followed by 64 lowercase hex characters."},"owner":{"type":"string","description":"Canonical QIP-55 address of the registry owner."},"resolver":{"type":["string","null"],"description":"Canonical QIP-55 resolver address, or null when no resolver is set."},"name":{"type":["string","null"],"description":"Normalized name published by the resolver whose namehash equals the node, or null."}},"required":["node","owner","resolver","name"]},"example":{"node":"0xefe3586aa9a851831a32d38044822af21cc5380e38f05cdc0dd562b4cfada103","owner":"QaaaAAaaaAAaAaaAaAAAAaAAAaAaAaAAaAaaAaaaaAAAAAAAAaAAAAaAaAAaaAAaaaaAaAAAAaaAaAAaaaaaaAaAAaaaaAaAaaaaAaaaAAAAaAAAAaAaAaaAAAaAaaaAA","resolver":"Q2222222222222222222222222222222222222222222222222222222222222222222222222222222222222222222222222222222222222222222222222222222222","name":"alice.qrl"}}}},"400":{"description":"The node is not 0x followed by 64 hex characters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"invalid QNS node"}}}},"404":{"description":"The registry owner of the node is the zero address. Cached for the normal 15-second TTL.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["QNS node has no owner"]},"node":{"type":"string"}},"required":["error","node"]}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"},"502":{"description":"The node RPC failed, returned an unknown RPC error or malformed envelope, or a registry owner or resolver lookup failed. A deterministic execution failure or malformed record from the resolver's name call yields name null. Uncached so the next request retries.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"QNS resolution failed"}}}},"503":{"description":"QNS is unconfigured, the configured chain does not match, or registry bytecode is unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"504":{"description":"The bounded lookup timed out.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/address/{address}/transactions":{"get":{"tags":["Addresses"],"operationId":"getAddressTransactions","summary":"Non-zero transactions for an address","description":"Paginated list of value-moving transactions touching the address.","parameters":[{"name":"address","in":"path","required":true,"description":"Address alias: Q/q or 0x/0X followed by 128 hex characters. Mixed-case bodies require a valid QIP-55 checksum.","schema":{"type":"string","pattern":"^([Qq]|0x|0X)[0-9a-fA-F]{128}$"}},{"name":"page","in":"query","description":"Page number, starting at 1.","schema":{"type":"integer","default":1,"minimum":1}},{"name":"limit","in":"query","description":"Items per page. Capped at 100.","schema":{"type":"integer","default":5,"maximum":100}}],"responses":{"200":{"description":"One page of transactions.","content":{"application/json":{"schema":{"type":"object","properties":{"transactions":{"type":"array","items":{"$ref":"#/components/schemas/TransactionByAddress"}},"total":{"type":"integer"},"page":{"type":"integer"},"limit":{"type":"integer"}}}}}},"400":{"description":"Invalid address format.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"$ref":"#/components/responses/InternalError"}}}},"/api/address/{address}/token-transfers":{"get":{"tags":["Addresses"],"operationId":"getAddressTokenTransfers","summary":"Token transfers touching an address","description":"Token and NFT transfer events where the address is sender or recipient, across every contract.","parameters":[{"name":"address","in":"path","required":true,"description":"Address alias: Q/q or 0x/0X followed by 128 hex characters. Mixed-case bodies require a valid QIP-55 checksum.","schema":{"type":"string","pattern":"^([Qq]|0x|0X)[0-9a-fA-F]{128}$"}},{"name":"page","in":"query","description":"Page number, starting at 1.","schema":{"type":"integer","default":1,"minimum":1}},{"name":"limit","in":"query","description":"Items per page. Capped at 100.","schema":{"type":"integer","default":5,"maximum":100}}],"responses":{"200":{"description":"One page of token transfers.","content":{"application/json":{"schema":{"type":"object","properties":{"address":{"type":"string"},"transfers":{"type":"array","items":{"$ref":"#/components/schemas/TokenTransfer"}},"total":{"type":"integer"},"page":{"type":"integer"},"limit":{"type":"integer"}}}}}},"400":{"description":"Invalid address format.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"$ref":"#/components/responses/InternalError"}}}},"/api/address/{address}/tokens":{"get":{"tags":["Addresses"],"operationId":"getAddressTokens","summary":"Token balances for an address","description":"All indexed token holdings for a wallet. By default every standard is returned (ERC-20 plus per-id ERC-721 and ERC-1155 rows); use the standard filter to scope to one.","parameters":[{"name":"address","in":"path","required":true,"description":"Address alias: Q/q or 0x/0X followed by 128 hex characters. Mixed-case bodies require a valid QIP-55 checksum.","schema":{"type":"string","pattern":"^([Qq]|0x|0X)[0-9a-fA-F]{128}$"}},{"name":"standard","in":"query","description":"Scope the response to one token standard.","schema":{"type":"string","enum":["ERC-20","ERC-721","ERC-1155"]}}],"responses":{"200":{"description":"Token balances.","content":{"application/json":{"schema":{"type":"object","properties":{"address":{"type":"string"},"tokens":{"type":"array","items":{"$ref":"#/components/schemas/TokenBalance"}},"count":{"type":"integer"}}}}}},"400":{"description":"Invalid address or standard value.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"$ref":"#/components/responses/InternalError"}}}},"/api/address/{address}/nfts":{"get":{"tags":["Addresses"],"operationId":"getAddressNfts","summary":"NFT holdings for an address","description":"Per (contract, tokenID) NFT holdings joined with collection metadata and per-token off-chain metadata (name, image, attributes) in one call. Covers ERC-721 and ERC-1155.","parameters":[{"name":"address","in":"path","required":true,"description":"Address alias: Q/q or 0x/0X followed by 128 hex characters. Mixed-case bodies require a valid QIP-55 checksum.","schema":{"type":"string","pattern":"^([Qq]|0x|0X)[0-9a-fA-F]{128}$"}},{"name":"standard","in":"query","description":"Scope the response to one NFT standard.","schema":{"type":"string","enum":["ERC-721","ERC-1155"]}}],"responses":{"200":{"description":"NFT holdings.","content":{"application/json":{"schema":{"type":"object","properties":{"address":{"type":"string"},"nfts":{"type":"array","items":{"$ref":"#/components/schemas/NFTBalance"}},"count":{"type":"integer"}}}}}},"400":{"description":"Invalid address or standard value.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"$ref":"#/components/responses/InternalError"}}}},"/api/richlist":{"get":{"tags":["Addresses"],"operationId":"getRichlist","summary":"Top addresses by balance","description":"Wallet ranking by indexed balance, with contract flag, first-seen timestamp, and supply share per row. Cached server side for 30 seconds.","responses":{"200":{"description":"Richlist rows.","content":{"application/json":{"schema":{"type":"object","properties":{"richlist":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Q-prefixed address."},"balance":{"type":"number","description":"Balance denominated in Quanta."},"isContract":{"type":"boolean"},"firstSeen":{"type":"integer","description":"Unix timestamp."},"supplyPercent":{"type":"number"}}}}}}}}},"500":{"$ref":"#/components/responses/InternalError"}}}},"/api/walletdistribution/{query}":{"get":{"tags":["Addresses"],"operationId":"getWalletDistribution","summary":"Count addresses above a balance threshold","description":"Returns the number of indexed addresses whose balance exceeds a threshold derived from the supplied value. The value is scaled by 10^12 before comparison against the indexed balance.","parameters":[{"name":"query","in":"path","required":true,"description":"Threshold value as a decimal integer.","schema":{"type":"string","pattern":"^[0-9]+$"}}],"responses":{"200":{"description":"Matching address count.","content":{"application/json":{"schema":{"type":"object","properties":{"response":{"type":"integer"}}}}}},"400":{"description":"Value is invalid as a decimal integer.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"$ref":"#/components/responses/InternalError"}}}},"/api/getBalance":{"post":{"tags":["Addresses"],"operationId":"postGetBalance","summary":"Live balance lookup via the node","description":"Form-encoded balance lookup proxied to the node's qrl_getBalance. Always returns 200: on success balance is a JSON number denominated in Quanta, and on failure balance is an error message string. Because POST endpoints carry a restricted CORS policy, cross-origin browser apps should use GET /api/address/aggregate/{address} instead; it is open to every origin and includes the indexed balance.","requestBody":{"required":true,"content":{"application/x-www-form-urlencoded":{"schema":{"type":"object","properties":{"address":{"type":"string","description":"Q or 0x prefixed address."}},"required":["address"]}}}},"responses":{"200":{"description":"Balance in Quanta as a number, or an error message string in the same field.","content":{"application/json":{"schema":{"type":"object","properties":{"balance":{"oneOf":[{"type":"number"},{"type":"string"}]}}},"example":{"balance":12.5}}}}}}},"/api/contracts":{"get":{"tags":["Tokens & NFTs"],"operationId":"getContracts","summary":"Paginated contract list","description":"Deployed contracts with optional search and filters. Pagination is 0-indexed on this endpoint.","parameters":[{"name":"page","in":"query","description":"Page number, starting at 0.","schema":{"type":"integer","default":0,"minimum":0}},{"name":"limit","in":"query","description":"Items per page. Capped at 100.","schema":{"type":"integer","default":10,"maximum":100}},{"name":"search","in":"query","description":"Free-text filter over contract fields.","schema":{"type":"string"}},{"name":"isToken","in":"query","description":"Filter to token contracts (true) or non-token contracts (any other value).","schema":{"type":"string"}},{"name":"standard","in":"query","description":"Filter by token standard.","schema":{"type":"string","enum":["ERC-20","ERC-721","ERC-1155"]}}],"responses":{"200":{"description":"One page of contracts.","content":{"application/json":{"schema":{"type":"object","properties":{"response":{"type":"array","items":{"$ref":"#/components/schemas/ContractInfo"}},"total":{"type":"integer"}}}}}},"400":{"description":"Invalid standard value.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"$ref":"#/components/responses/InternalError"}}}},"/api/contracts/counts":{"get":{"tags":["Tokens & NFTs"],"operationId":"getContractCounts","summary":"Contract counts by standard","description":"Counts of deployed contracts bucketed by token standard, plus an \"other\" bucket for non-token contracts. Cached server side for 30 seconds.","responses":{"200":{"description":"Per-standard counts.","content":{"application/json":{"schema":{"type":"object","properties":{"erc20":{"type":"integer"},"erc721":{"type":"integer"},"erc1155":{"type":"integer"},"other":{"type":"integer"}}},"example":{"erc20":120,"erc721":34,"erc1155":12,"other":176}}}},"500":{"$ref":"#/components/responses/InternalError"}}}},"/api/token/{address}/info":{"get":{"tags":["Tokens & NFTs"],"operationId":"getTokenInfo","summary":"Token summary","description":"Summary statistics for one token contract: identity, supply, holder count, transfer count, and creation provenance.","parameters":[{"name":"address","in":"path","required":true,"description":"Contract address alias: Q/q or 0x/0X followed by 128 hex characters. Mixed-case bodies require a valid QIP-55 checksum.","schema":{"type":"string","pattern":"^([Qq]|0x|0X)[0-9a-fA-F]{128}$"}}],"responses":{"200":{"description":"Token summary.","content":{"application/json":{"schema":{"type":"object","properties":{"contractAddress":{"type":"string"},"name":{"type":"string"},"symbol":{"type":"string"},"decimals":{"type":"integer"},"totalSupply":{"type":"string","description":"Raw supply as a decimal string, before dividing by decimals."},"holderCount":{"type":"integer"},"transferCount":{"type":"integer"},"creatorAddress":{"type":"string"},"creationTxHash":{"type":"string"},"creationBlock":{"type":"string","description":"0x-prefixed hex block number."},"genesisContract":{"type":"boolean","description":"True for contracts baked into the genesis allocation."}}},"example":{"contractAddress":"QCCCccccCcCcCccCcCccCCCccCcCcCcccccCCccCccCccccCcCCcCcccCCcCcccccccCccCcCccccCCcCccCccCcccCcCCCccCcCccCcCccccccCcCcCcccCcCcCCCccC","name":"Example Token","symbol":"EXT","decimals":18,"totalSupply":"1000000000000000000000000","holderCount":42,"transferCount":310,"creatorAddress":"QaaaAAaaaAAaAaaAaAAAAaAAAaAaAaAAaAaaAaaaaAAAAAAAAaAAAAaAaAAaaAAaaaaAaAAAAaaAaAAaaaaaaAaAAaaaaAaAaaaaAaaaAAAAaAAAAaAaAaaAAAaAaaaAA","creationTxHash":"0x9c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d","creationBlock":"0x1a2b3"}}}},"400":{"description":"Invalid address format.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Token not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/token/{address}/holders":{"get":{"tags":["Tokens & NFTs"],"operationId":"getTokenHolders","summary":"Token holders","description":"Holders of a token contract. For NFT contracts an optional tokenID filter scopes to holders of one id; without it holders are aggregated across all ids. Pagination is 0-indexed on this endpoint.","parameters":[{"name":"address","in":"path","required":true,"description":"Contract address alias: Q/q or 0x/0X followed by 128 hex characters. Mixed-case bodies require a valid QIP-55 checksum.","schema":{"type":"string","pattern":"^([Qq]|0x|0X)[0-9a-fA-F]{128}$"}},{"name":"tokenID","in":"query","description":"Filter holders to one NFT token id (decimal string).","schema":{"type":"string"}},{"name":"page","in":"query","description":"Page number, starting at 0.","schema":{"type":"integer","default":0,"minimum":0}},{"name":"limit","in":"query","description":"Items per page. Capped at 100.","schema":{"type":"integer","default":25,"maximum":100}}],"responses":{"200":{"description":"One page of holders.","content":{"application/json":{"schema":{"type":"object","properties":{"contractAddress":{"type":"string"},"holders":{"type":"array","items":{"$ref":"#/components/schemas/TokenBalance"}},"totalHolders":{"type":"integer"},"page":{"type":"integer"},"limit":{"type":"integer"}}}}}},"400":{"description":"Invalid address format.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"$ref":"#/components/responses/InternalError"}}}},"/api/token/{address}/tokens":{"get":{"tags":["Tokens & NFTs"],"operationId":"getTokenIds","summary":"Minted token ids on an NFT contract","description":"Distinct token ids minted on an NFT contract with per-id holder counts and, when fetched, off-chain metadata (name, image, description). Returns an empty list for ERC-20 contracts. Pagination is 0-indexed on this endpoint.","parameters":[{"name":"address","in":"path","required":true,"description":"Contract address alias: Q/q or 0x/0X followed by 128 hex characters. Mixed-case bodies require a valid QIP-55 checksum.","schema":{"type":"string","pattern":"^([Qq]|0x|0X)[0-9a-fA-F]{128}$"}},{"name":"page","in":"query","description":"Page number, starting at 0.","schema":{"type":"integer","default":0,"minimum":0}},{"name":"limit","in":"query","description":"Items per page. Capped at 100.","schema":{"type":"integer","default":25,"maximum":100}}],"responses":{"200":{"description":"One page of token ids.","content":{"application/json":{"schema":{"type":"object","properties":{"contractAddress":{"type":"string"},"tokens":{"type":"array","items":{"type":"object","properties":{"tokenID":{"type":"string"},"holderCount":{"type":"integer"},"tokenStandard":{"type":"string"},"blockNumber":{"type":"string"},"updatedAt":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"image":{"type":"string"}}}},"totalTokenIDs":{"type":"integer"},"page":{"type":"integer"},"limit":{"type":"integer"}}}}}},"400":{"description":"Invalid address format.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"$ref":"#/components/responses/InternalError"}}}},"/api/token/{address}/transfers":{"get":{"tags":["Tokens & NFTs"],"operationId":"getTokenTransfers","summary":"Transfers of one token contract","description":"Transfer events emitted by one token contract, newest first. Pagination is 0-indexed on this endpoint.","parameters":[{"name":"address","in":"path","required":true,"description":"Contract address alias: Q/q or 0x/0X followed by 128 hex characters. Mixed-case bodies require a valid QIP-55 checksum.","schema":{"type":"string","pattern":"^([Qq]|0x|0X)[0-9a-fA-F]{128}$"}},{"name":"page","in":"query","description":"Page number, starting at 0.","schema":{"type":"integer","default":0,"minimum":0}},{"name":"limit","in":"query","description":"Items per page. Capped at 100.","schema":{"type":"integer","default":25,"maximum":100}}],"responses":{"200":{"description":"One page of transfers.","content":{"application/json":{"schema":{"type":"object","properties":{"contractAddress":{"type":"string"},"transfers":{"type":"array","items":{"$ref":"#/components/schemas/TokenTransfer"}},"totalTransfers":{"type":"integer"},"page":{"type":"integer"},"limit":{"type":"integer"}}}}}},"400":{"description":"Invalid address format.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"$ref":"#/components/responses/InternalError"}}}},"/api/token/{address}/{id}":{"get":{"tags":["Tokens & NFTs"],"operationId":"getTokenMetadata","summary":"Per-token NFT metadata","description":"Full off-chain metadata for one (contract, tokenID) pair, including OpenSea-style attributes. The id must be a decimal integer; the concrete sibling segments (info, holders, tokens, transfers) take priority over this route.","parameters":[{"name":"address","in":"path","required":true,"description":"Contract address alias: Q/q or 0x/0X followed by 128 hex characters. Mixed-case bodies require a valid QIP-55 checksum.","schema":{"type":"string","pattern":"^([Qq]|0x|0X)[0-9a-fA-F]{128}$"}},{"name":"id","in":"path","required":true,"description":"Token id as a decimal integer, at most 80 characters.","schema":{"type":"string","pattern":"^[0-9]+$"}}],"responses":{"200":{"description":"Token metadata document.","content":{"application/json":{"schema":{"type":"object","properties":{"contractAddress":{"type":"string"},"tokenID":{"type":"string"},"tokenStandard":{"type":"string"},"uri":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"image":{"type":"string"},"externalURL":{"type":"string"},"attributes":{"type":"array","items":{"type":"object","properties":{"trait_type":{"type":"string"},"value":{"type":"string"},"display_type":{"type":"string"}}}},"fetchedAt":{"type":"string"},"fetchError":{"type":"string"},"updatedAt":{"type":"string"}}}}}},"400":{"description":"Invalid address or token id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No metadata stub exists for this token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"$ref":"#/components/responses/InternalError"}}}},"/api/validators":{"get":{"tags":["Validators & Epochs"],"operationId":"getValidators","summary":"Validator set","description":"The full validator set with per-validator status, age, and stake, plus the current epoch and the total staked amount. Cached server side for 30 seconds.","parameters":[{"name":"page_token","in":"query","description":"Reserved for future server-side pagination. The full set is returned today.","schema":{"type":"string"}}],"responses":{"200":{"description":"Validator set.","content":{"application/json":{"schema":{"type":"object","properties":{"validators":{"type":"array","items":{"type":"object","properties":{"index":{"type":"string","description":"Validator index as a decimal string."},"address":{"type":"string","description":"Validator public key as unprefixed hex: ML-DSA-87, 5184 hex characters. Examples are truncated for readability."},"withdrawalCredentialsHex":{"type":"string"},"status":{"type":"string","enum":["active","pending","exited","slashed"]},"age":{"type":"integer","description":"Age in epochs."},"stakedAmount":{"type":"string","description":"Effective balance as a decimal string, as reported by the beacon chain."},"isActive":{"type":"boolean"}}}},"validatorCount":{"type":"integer"},"epoch":{"type":"string","description":"Current epoch as a decimal string."},"totalStaked":{"type":"string","description":"Sum of effective balances as a decimal string."}}},"example":{"validators":[{"index":"1","address":"93f1c2d3e4a5b6c7d8e9f0a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1","withdrawalCredentialsHex":"0100000000000000000000004a5b6c7d8e9f0a1b2c3d4e5f6a7b8c9d0e1f2a3b","status":"active","age":1042,"stakedAmount":"40000000000000","isActive":true}],"validatorCount":1,"epoch":"1160","totalStaked":"40000000000000"}}}},"500":{"$ref":"#/components/responses/InternalError"}}}},"/api/validators/history":{"get":{"tags":["Validators & Epochs"],"operationId":"getValidatorsHistory","summary":"Validator count history","description":"Per-epoch historical validator counts for charts.","parameters":[{"name":"limit","in":"query","description":"Number of history records. Capped at 100.","schema":{"type":"integer","default":100,"maximum":100}}],"responses":{"200":{"description":"History records.","content":{"application/json":{"schema":{"type":"object","properties":{"history":{"type":"array","items":{"type":"object","properties":{"_id":{"type":"string"},"epoch":{"type":"string"},"source":{"type":"string","const":"beacon-state","description":"Only first-slot beacon-state summaries are returned, ordered by numeric epoch newest first."},"timestamp":{"type":"integer"},"validatorsCount":{"type":"integer"},"activeCount":{"type":"integer"},"pendingCount":{"type":"integer"},"exitedCount":{"type":"integer"},"slashedCount":{"type":"integer"},"totalStaked":{"type":"string"}}}}}}}}},"500":{"$ref":"#/components/responses/InternalError"}}}},"/api/validators/stats":{"get":{"tags":["Validators & Epochs"],"operationId":"getValidatorsStats","summary":"Aggregated validator statistics","description":"Totals across the validator set: counts per status, total staked, and the current epoch.","responses":{"200":{"description":"Validator statistics.","content":{"application/json":{"schema":{"type":"object","properties":{"totalValidators":{"type":"integer"},"activeCount":{"type":"integer"},"pendingCount":{"type":"integer"},"exitedCount":{"type":"integer"},"slashedCount":{"type":"integer"},"totalStaked":{"type":"string"},"currentEpoch":{"type":"string"}}}}}},"500":{"$ref":"#/components/responses/InternalError"}}}},"/api/validator/{id}":{"get":{"tags":["Validators & Epochs"],"operationId":"getValidator","summary":"Validator detail","description":"Detail for one validator, addressed by decimal index.","parameters":[{"name":"id","in":"path","required":true,"description":"Validator index as a decimal integer.","schema":{"type":"string"}}],"responses":{"200":{"description":"Validator detail.","content":{"application/json":{"schema":{"type":"object","properties":{"index":{"type":"string"},"publicKeyHex":{"type":"string"},"withdrawalCredentialsHex":{"type":"string"},"effectiveBalance":{"type":"string"},"slashed":{"type":"boolean"},"activationEligibilityEpoch":{"type":"string"},"activationEpoch":{"type":"string"},"exitEpoch":{"type":"string"},"withdrawableEpoch":{"type":"string"},"status":{"type":"string"},"age":{"type":"integer"},"currentEpoch":{"type":"string"},"slashingEvents":{"type":"array","maxItems":20,"items":{"$ref":"#/components/schemas/SlashingEvent"},"description":"Newest 20 records for this validator. Use the corresponding list endpoint with validator=<index> for further pages."},"slashingEventsTotal":{"type":"integer","minimum":0,"format":"int64"},"validatorSetChanges":{"type":"array","maxItems":20,"items":{"$ref":"#/components/schemas/ValidatorSetChange"},"description":"Newest 20 records for this validator. Use the corresponding list endpoint with validator=<index> for further pages."},"validatorSetChangesTotal":{"type":"integer","minimum":0,"format":"int64"}}}}}},"400":{"description":"Invalid validator id format.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Validator not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"$ref":"#/components/responses/InternalError"}}}},"/api/epochs":{"get":{"tags":["Validators & Epochs"],"operationId":"getEpochs","summary":"Paginated epoch list","description":"Beacon chain epochs with verified first-slot beacon-state summaries, sorted by numeric epoch newest first. Legacy unmarked records are excluded from both results and total. The list grows as finalized history is indexed.","parameters":[{"name":"page","in":"query","description":"Page number, starting at 1.","schema":{"type":"integer","default":1,"minimum":1}},{"name":"limit","in":"query","description":"Items per page. Capped at 100.","schema":{"type":"integer","default":15,"maximum":100}}],"responses":{"200":{"description":"One page of epochs.","content":{"application/json":{"schema":{"type":"object","properties":{"epochs":{"type":"array","items":{"type":"object","properties":{"epoch":{"type":"string"},"timestamp":{"type":"integer"},"status":{"type":"string","enum":["finalized","justified","pending"]},"validatorsCount":{"type":"integer"},"activeCount":{"type":"integer"},"totalStaked":{"type":"string"}}}},"total":{"type":"integer"},"finalizedEpoch":{"type":"string"},"justifiedEpoch":{"type":"string"}}}}}},"500":{"$ref":"#/components/responses/InternalError"}}}},"/api/epoch":{"get":{"tags":["Validators & Epochs"],"operationId":"getCurrentEpoch","summary":"Current epoch information","description":"Head slot and epoch from the beacon, with finality checkpoints and authoritative chain timing from sync_state.chain_timing. The endpoint requires the syncer to have initialized timing.","responses":{"200":{"description":"Current epoch state.","content":{"application/json":{"schema":{"type":"object","properties":{"headEpoch":{"type":"string"},"headSlot":{"type":"string"},"finalizedEpoch":{"type":"string"},"justifiedEpoch":{"type":"string"},"slotsPerEpoch":{"type":"integer","minimum":1},"secondsPerSlot":{"type":"integer","minimum":1},"genesisTime":{"type":"integer","description":"Beacon genesis Unix timestamp in seconds."},"slotInEpoch":{"type":"integer"},"timeToNextEpoch":{"type":"integer","description":"Seconds until the next epoch."},"updatedAt":{"type":"integer"}}}}}},"500":{"$ref":"#/components/responses/InternalError"}}}},"/api/epoch/{id}":{"get":{"tags":["Validators & Epochs"],"operationId":"getEpoch","summary":"Epoch detail","description":"Slots and timestamps use the chain timing returned by /api/epoch. Blocks are matched by their consensus timestamp. Validator summaries come from the first slot of each finalized epoch. Missing or legacy unmarked summaries have summaryAvailable=false and null counts and totalStaked; the epoch timestamp is still calculated from the beacon clock. Duties fill independently, with unknown proposers for slot zero and unavailable duties.","parameters":[{"name":"id","in":"path","required":true,"description":"Epoch number as a decimal integer.","schema":{"type":"string"}}],"responses":{"200":{"description":"Epoch detail.","content":{"application/json":{"schema":{"type":"object","properties":{"epoch":{"type":"string"},"timestamp":{"type":"integer"},"status":{"type":"string"},"validatorsCount":{"type":["integer","null"]},"activeCount":{"type":["integer","null"]},"pendingCount":{"type":["integer","null"]},"exitedCount":{"type":["integer","null"]},"slashedCount":{"type":["integer","null"]},"totalStaked":{"type":["string","null"],"description":"Sum of effective balances in Shor, or null while the summary is unavailable."},"summaryAvailable":{"type":"boolean"},"startSlot":{"type":"integer"},"endSlot":{"type":"integer"},"blocks":{"type":"array","items":{"type":"object","properties":{"slot":{"type":"integer"},"status":{"type":"string","enum":["proposed","missed"]},"timestamp":{"type":"string"},"proposer":{"type":"string","deprecated":true,"description":"Legacy execution coinbase for proposed slots."},"proposerIndex":{"type":"string","pattern":"^[0-9]+$","description":"Assigned validator index as a decimal string, present for proposed and missed slots when known."},"proposerPubkey":{"type":"string","description":"Assigned validator public key as 0x-prefixed hex, present when known."},"blockNumber":{"type":"string","pattern":"^[0-9]+$","description":"Execution block number as a decimal string, present only for proposed slots."},"transactions":{"type":"integer"},"gasUsed":{"type":"string"},"blockHash":{"type":"string"}}}},"finalizedEpoch":{"type":"string"},"justifiedEpoch":{"type":"string"},"headEpoch":{"type":"string"},"proposedCount":{"type":"integer"},"missedCount":{"type":"integer"}}}}}},"404":{"description":"The epoch is invalid or has not yet occurred.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"$ref":"#/components/responses/InternalError"}}}},"/api/gas/summary":{"get":{"tags":["Gas"],"operationId":"getGasSummary","summary":"Live gas snapshot","description":"Headline gas price plus block and mempool statistics and a gas price histogram. Gas values are 0x-prefixed hex strings. Cached server side for 5 seconds.","responses":{"200":{"description":"Gas snapshot.","content":{"application/json":{"schema":{"type":"object","properties":{"avgGasPriceHex":{"type":"string","description":"Headline gas price: median over recent transfers, 0x-prefixed hex."},"recentTxMedianHex":{"type":"string"},"recentTxSampleSize":{"type":"integer"},"recentMedianGasPriceHex":{"type":"string","description":"Median over the last 30 blocks."},"mempoolMedianGasPriceHex":{"type":"string"},"recentTxCount":{"type":"integer"},"qrlUsdPrice":{"type":"number"},"avgGasUsedHex":{"type":"string"},"avgGasLimitHex":{"type":"string"},"avgBlockTimeSec":{"type":"number","nullable":true,"description":"Mean interval between recent blocks, falling back to the stored seconds per slot. Null when both are unavailable."},"pendingCount":{"type":"integer"},"lastBlockNumberHex":{"type":"string"},"lastGasUsedHex":{"type":"string"},"lastGasLimitHex":{"type":"string"},"gasPriceHistogram":{"type":"array","items":{"type":"object","additionalProperties":true}}}},"example":{"avgGasPriceHex":"0x3b9aca00","recentTxMedianHex":"0x3b9aca00","recentTxSampleSize":20,"recentMedianGasPriceHex":"0x3b9aca00","mempoolMedianGasPriceHex":"0x0","recentTxCount":14,"qrlUsdPrice":0.42,"avgGasUsedHex":"0x5208","avgGasLimitHex":"0x1c9c380","avgBlockTimeSec":15.2,"pendingCount":0,"lastBlockNumberHex":"0x24420","lastGasUsedHex":"0x5208","lastGasLimitHex":"0x1c9c380","gasPriceHistogram":[]}}}},"500":{"$ref":"#/components/responses/InternalError"}}}},"/api/gas/history":{"get":{"tags":["Gas"],"operationId":"getGasHistory","summary":"Gas usage time series","description":"Per-block gas history for the last 24 hours, or hourly buckets for the 7 day range. Unrecognized range values fall back to 24h. Cached server side for 30 seconds.","parameters":[{"name":"range","in":"query","description":"Time range for the series.","schema":{"type":"string","enum":["24h","7d"],"default":"24h"}}],"responses":{"200":{"description":"Gas history rows, oldest first.","content":{"application/json":{"schema":{"type":"object","properties":{"range":{"type":"string"},"data":{"type":"array","items":{"type":"object","properties":{"blockNumber":{"type":"integer"},"timestamp":{"type":"integer","description":"Unix seconds."},"gasUsed":{"type":"string","description":"0x-prefixed hex."},"gasLimit":{"type":"string","description":"0x-prefixed hex."},"baseFeePerGas":{"type":"string","description":"0x-prefixed hex."},"txCount":{"type":"integer"}}}}}}}}},"500":{"$ref":"#/components/responses/InternalError"}}}},"/api/contract/verify":{"post":{"tags":["Contract Verification"],"operationId":"verifyContract","summary":"Submit contract source for verification","description":"Enqueues an async source-verification job compiled with the Hyperion toolchain. Request bodies are capped at 1 MiB. Rate limited per IP: bucket of 5 requests, refilling 5 per minute. Poll GET /api/contract/verify/{jobId} for the outcome.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"address":{"type":"string","description":"Canonical QIP-55 contract address (uppercase Q plus 128 checksum-cased hex characters)."},"sourceCode":{"type":"string"},"contractName":{"type":"string","pattern":"^[A-Za-z_$][A-Za-z0-9_$]*$","description":"Hyperion identifier. Dollar signs are valid in both the first and subsequent positions."},"compilerVersion":{"type":"string","description":"Build id from /api/contract/compiler-info. Empty selects the default build."},"optimizerEnabled":{"type":"boolean"},"optimizerRuns":{"type":"integer","description":"Effective optimizer run count. When optimization is enabled, zero or a negative value is canonicalized to 200 before enqueue, compilation, and persistence."},"evmVersion":{"type":"string"},"constructorArguments":{"type":"string"},"libraries":{"type":"object","additionalProperties":{"type":"string"}},"primarySourcePath":{"type":"string","maxLength":256,"pattern":"^[A-Za-z0-9._@+~/ -]+$","description":"Repo-relative path the primary source was compiled under, e.g. contracts/core/Token.hyp. Omit it to compile sourceCode as <contractName>.hyp at the root. The clean path must name a .hyp file, stay inside the source root, and have at most 32 segments. A value equal to <contractName>.hyp is stored as absent."},"viaIR":{"type":"boolean","description":"Compile through the via-IR pipeline (Hyperion standard JSON settings.viaIR). Defaults to false."},"imports":{"type":"object","maxProperties":127,"description":"Every source except the primary one, keyed by its repo-relative path in the same virtual tree as primarySourcePath, so relative imports such as ../lib/Math.hyp resolve as they did in the deployer's build. Paths use ASCII letters, digits, spaces, and . _ - @ + ~ separated by /, are at most 256 bytes and 32 segments long, and are canonicalized before compilation and persistence. Absolute paths, root escapes, control characters, collisions with the primary source, paths that differ only by letter case (one file on case-insensitive macOS and Windows checkouts), and a path used as both a file and a directory are rejected. With a nested primarySourcePath, a root import named <contractName>.hyp in any letter case is rejected too, because the verified source bundle labels the primary source with that name. At most 128 sources in total.","additionalProperties":{"type":"string"}},"license":{"type":"string"}},"required":["address","sourceCode","contractName"]}}}},"responses":{"200":{"description":"The contract is already verified; no new job was created.","content":{"application/json":{"schema":{"type":"object","properties":{"alreadyVerified":{"type":"boolean"},"address":{"type":"string"}}}}}},"202":{"description":"Job accepted.","content":{"application/json":{"schema":{"type":"object","properties":{"jobId":{"type":"string"},"status":{"type":"string"},"address":{"type":"string"}}},"example":{"jobId":"9f2c4a6e8b0d1f3a","status":"pending","address":"QCCCccccCcCcCccCcCccCCCccCcCcCcccccCCccCccCccccCcCCcCcccCCcCcccccccCccCcCccccCCcCccCccCcccCcCCCccCcCccCcCccccccCcCcCcccCcCcCCCccC"}}}},"400":{"description":"Invalid body, invalid address, missing required fields, an invalid primarySourcePath or imports path, sources whose standard JSON input exceeds the compiler input limit, or unsupported compilerVersion (the body lists supported builds).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"A verification job is already in flight, or the stored verification record is invalid and requires operator repair. Public re-verification never overwrites an invalid stored record.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"description":"Contract verification is not configured on this deployment.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/contract/verify/{jobId}":{"get":{"tags":["Contract Verification"],"operationId":"getVerificationJob","summary":"Verification job status","description":"Returns the verification job document. Status moves through pending, compiling, and then success or failed.","parameters":[{"name":"jobId","in":"path","required":true,"description":"Job id returned by POST /api/contract/verify.","schema":{"type":"string"}}],"responses":{"200":{"description":"Job document.","content":{"application/json":{"schema":{"type":"object","properties":{"jobId":{"type":"string"},"address":{"type":"string"},"status":{"type":"string","enum":["pending","compiling","success","failed"]},"error":{"type":"string"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"target":{"type":"object","description":"Canonical deployment generation captured before compilation and revalidated before publication.","properties":{"address":{"type":"string","pattern":"^Q[0-9a-f]{128}$"},"creationTransaction":{"type":"string","pattern":"^(?:|0x[0-9a-f]{64})$"},"creationBlockNumber":{"type":"string","pattern":"^0x(?:0|[1-9a-f][0-9a-f]*)$"},"creationBlockHash":{"type":"string","pattern":"^0x[0-9a-f]{64}$"},"chainId":{"type":"string","pattern":"^0x(?:0|[1-9a-f][0-9a-f]*)$"},"deployedCodeSha256":{"type":"string","pattern":"^[0-9a-f]{64}$"},"genesisContract":{"type":"boolean"}},"required":["address","creationBlockNumber","creationBlockHash","chainId","deployedCodeSha256","genesisContract"],"additionalProperties":false},"payload":{"type":"object","description":"Echo of the submitted request.","properties":{"sourceCode":{"type":"string"},"contractName":{"type":"string"},"compilerVersion":{"type":"string"},"compilerProvenance":{"$ref":"#/components/schemas/CompilerProvenance"},"optimizationEnabled":{"type":"boolean"},"optimizationRuns":{"type":"integer"},"evmVersion":{"type":"string"},"constructorArguments":{"type":"string"},"libraries":{"type":"object","additionalProperties":{"type":"string"}},"imports":{"type":"object","description":"Canonical effective import sources used for compilation.","additionalProperties":{"type":"string"}},"primarySourcePath":{"type":"string","description":"Canonical primary source path. Absent for the default <contractName>.hyp layout."},"viaIR":{"type":"boolean","description":"Present and true when the job compiles via IR."},"license":{"type":"string"},"verificationMethod":{"type":"string","const":"full-source"}},"additionalProperties":true},"result":{"type":"object","properties":{"abi":{"type":"string"},"bytecodeHash":{"type":"string"},"artifactDigest":{"type":"string","pattern":"^qrl\\.contract-verification-artifact\\.v[23]:sha256:[0-9a-f]{64}$","description":"V2 or V3 digest binding the source bundle, ABI, compiler identity and settings, and canonical deployment target. The job uses V3 when its payload carries primarySourcePath or viaIR."},"compilerProvenance":{"$ref":"#/components/schemas/CompilerProvenance"},"verifiedAt":{"type":"string"}}}},"required":["jobId","address","status","target","payload"]}}}},"404":{"description":"Job not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"$ref":"#/components/responses/InternalError"}}}},"/api/contract/compiler-info":{"get":{"tags":["Contract Verification"],"operationId":"getCompilerInfo","summary":"Available compiler builds","description":"Lists every selectable Hyperion compiler build and identifies the default. Use a listed buildId as the compilerVersion in verify submissions.","responses":{"200":{"description":"Compiler registry.","content":{"application/json":{"schema":{"type":"object","properties":{"language":{"type":"string"},"buildId":{"type":"string"},"kind":{"type":"string","enum":["native"]},"sha256":{"type":"string","pattern":"^[0-9a-f]{64}$"},"provenance":{"$ref":"#/components/schemas/CompilerProvenance"},"default":{"type":"string"},"compilers":{"type":"array","items":{"type":"object","properties":{"buildId":{"type":"string"},"language":{"type":"string"},"kind":{"type":"string","enum":["native"]},"sha256":{"type":"string","pattern":"^[0-9a-f]{64}$"},"provenance":{"$ref":"#/components/schemas/CompilerProvenance"},"default":{"type":"boolean"}}}}}}}}},"503":{"description":"Contract verification is not configured on this deployment.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/contract/call":{"post":{"tags":["Contract Interaction"],"operationId":"callContract","summary":"Read-only contract call","description":"Typed proxy for qrl_call against the latest block, scoped to addresses the explorer knows as contracts. Calldata is capped at 8 KiB of hex, request bodies at 32 KiB, gas at 50 million, and each call at an 8 second timeout. Rate limited per IP: bucket of 60 requests, refilling 60 per minute.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"to":{"type":"string","description":"Canonical QIP-55 contract address."},"data":{"type":"string","description":"ABI-encoded calldata: 0x-prefixed, even-length, lowercase hex. 0x alone is allowed for zero-argument functions."}},"required":["to","data"]}}}},"responses":{"200":{"description":"Call result. A reverted execution also returns 200, with reverted true and the upstream error message.","content":{"application/json":{"schema":{"oneOf":[{"type":"object","properties":{"result":{"type":"string","description":"Return data as a 0x-prefixed hex string."}},"required":["result"]},{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"integer"},"data":{},"reverted":{"type":"boolean","const":true}},"required":["error","reverted"]}]},"example":{"result":"0x0000000000000000000000000000000000000000000000000000000000000012"}}}},"400":{"description":"Invalid body, address, or calldata encoding.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"The to address is unknown as a contract to the explorer.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Calldata exceeds the size cap.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"502":{"description":"The node call failed or returned an undecodable response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/contract/explain/{address}":{"post":{"tags":["Contract Interaction"],"operationId":"explainContract","summary":"AI explanation of a verified contract","description":"Generates or returns a cached plain-language explanation of a verified contract's complete source bundle. The stored compiler provenance and source-bundle identity must both be digest-backed. Rate limited per IP: bucket of 10 requests, refilling 4 per minute. Regeneration is capped at 5 per contract per 7 day window.","parameters":[{"name":"address","in":"path","required":true,"description":"Uppercase-Q QIP-55 contract address. Mixed-case bodies require a valid checksum.","schema":{"type":"string","pattern":"^Q[0-9a-fA-F]{128}$"}},{"name":"regenerate","in":"query","description":"Set the exact raw query to regenerate=1 to force a fresh explanation instead of the cached one.","schema":{"type":"string","const":"1"}}],"requestBody":{"required":false,"description":"Required only for regeneration. Contains the one-use creator challenge and its bound qrl_signMessage proof.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContractExplainAuthorizationRequest"}}}},"responses":{"200":{"description":"Explanation, fresh or cached.","content":{"application/json":{"schema":{"type":"object","properties":{"address":{"type":"string"},"explanation":{"type":"string"},"generatedAt":{"type":"string"},"model":{"type":"string"},"cached":{"type":"boolean"}}}}}},"400":{"description":"Invalid address, query string, or regeneration authorization body.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The regeneration authorization proof is invalid, expired, or already used.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The contract exists and is unverified, so it cannot be analyzed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"The address is unknown as a contract.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"The verification lacks digest-backed compiler or source-bundle provenance, or the source bundle changed during generation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"The regeneration authorization body exceeds 24 KiB.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Per-IP rate limit exceeded, or the per-contract regeneration cap (5 per 7 day window) was reached.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"The explanation provider failed; retry shortly.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The AI explainer or regeneration authorization dependency is unavailable on this deployment.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/contract/explain/{address}/challenge":{"post":{"tags":["Contract Interaction"],"operationId":"createContractExplainChallenge","summary":"Issue a creator authorization challenge","description":"Creates a five-minute, one-use qrl_signMessage challenge for contract-creator AI regeneration. The signed bytes bind the trusted explorer origin, execution chain, HTTP method and route, contract, creator, nonce, issue time, and expiry. The request body must be empty. Responses are never cached.","parameters":[{"name":"address","in":"path","required":true,"description":"Uppercase-Q QIP-55 contract address. Mixed-case bodies require a valid checksum.","schema":{"type":"string","pattern":"^Q[0-9a-fA-F]{128}$"}}],"responses":{"200":{"description":"A fresh creator-bound challenge. Sign messageHex verbatim.","headers":{"Cache-Control":{"schema":{"type":"string","const":"no-store"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContractExplainChallenge"}}}},"400":{"description":"Invalid address or a non-empty request body.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"The address is unknown as a contract.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"The contract creator is unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"description":"The explainer, authorization service, execution-chain check, or challenge store is unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/search":{"get":{"tags":["Faucet & Site"],"operationId":"searchRedirect","summary":"Search redirect","description":"Resolves a free-form query (address, transaction hash, or block number) and responds with a 302 redirect to the matching explorer page. Unresolvable queries redirect to the homepage. Served by the explorer web app.","parameters":[{"name":"q","in":"query","description":"Address (Q/q, 0x/0X, or bare 128 hex; mixed case requires a valid QIP-55 checksum), transaction hash (64 hex, 0x optional), or block number (decimal or 0x hex).","schema":{"type":"string"}}],"responses":{"302":{"description":"Redirect to the resolved detail page, or to the homepage when the query cannot be resolved.","headers":{"Location":{"description":"Absolute URL of the matching page on https://shorscan.com.","schema":{"type":"string"}}}}}}},"/faucet/claim":{"get":{"tags":["Faucet & Site"],"operationId":"getFaucetStatus","summary":"Faucet status","description":"Public faucet configuration so clients can render the claim form or a disabled state. Served by the explorer web app.","responses":{"200":{"description":"Faucet configuration.","content":{"application/json":{"schema":{"type":"object","properties":{"configured":{"type":"boolean"},"captchaEnabled":{"type":"boolean"},"turnstileSiteKey":{"type":"string","nullable":true,"description":"Public Cloudflare Turnstile site key read at runtime. Null when absent or malformed. Clients require this key when captchaEnabled is true. Secrets and RPC configuration are never returned."},"dripQuanta":{"type":"string","description":"Whole-Quanta amount sent per successful claim, as a decimal string."},"cooldownHours":{"type":"integer","description":"Cooldown window in hours, enforced per address and per IP."}}},"example":{"configured":true,"captchaEnabled":true,"turnstileSiteKey":"1x00000000000000000000AA","dripQuanta":"10","cooldownHours":24}}}}}},"post":{"tags":["Faucet & Site"],"operationId":"claimFaucet","summary":"Claim testnet Quanta","description":"Sends a drip of testnet Quanta to the given address. Gated by a Cloudflare Turnstile captcha token, a per-address and per-IP cooldown (default 24 hours), and an optional rolling 24 hour global cap on total dripped Quanta. Testnet coins have no monetary value. Served by the explorer web app.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"address":{"type":"string","description":"Recipient address alias: Q/q, 0x/0X, or bare 128 hex. Mixed-case bodies require a valid QIP-55 checksum."},"turnstileToken":{"type":"string","description":"Cloudflare Turnstile response token."}},"required":["address"]}}}},"responses":{"200":{"description":"Drip broadcast.","content":{"application/json":{"schema":{"type":"object","properties":{"txHash":{"type":"string"},"amount":{"type":"string","description":"Amount sent, in whole Quanta as a decimal string."},"to":{"type":"string"},"explorerUrl":{"type":"string","description":"Relative explorer path for the broadcast transaction."}}},"example":{"txHash":"0x9c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d","amount":"10","to":"QaaaAAaaaAAaAaaAaAAAAaAAAaAaAaAAaAaaAaaaaAAAAAAAAaAAAAaAaAAaaAAaaaaAaAAAAaaAaAAaaaaaaAaAAaaaaAaAaaaaAaaaAAAAaAAAAaAaAaaAAAaAaaaAA","explorerUrl":"/tx/0x9c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d"}}}},"400":{"description":"Invalid body, invalid address, or failed captcha verification.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Cooldown active for this address or IP. The body carries retryAfterSeconds and the response sets a Retry-After header.","headers":{"Retry-After":{"description":"Seconds until the cooldown expires.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"retryAfterSeconds":{"type":"integer"}}}}}},"500":{"$ref":"#/components/responses/InternalError"},"502":{"description":"The signed transaction could not be broadcast.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Faucet unavailable: unconfigured, captcha missing in production, out of funds, or the daily cap was reached.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"responses":{"InternalError":{"description":"Internal server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"RateLimited":{"description":"Per-IP rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"rate limit exceeded"}}}}},"schemas":{"SlashingEvent":{"type":"object","required":["id","slot","epoch","type","validatorIndices","whistleblower","conflictingRoots"],"properties":{"id":{"type":"string"},"slot":{"type":"integer","minimum":0,"format":"int64"},"epoch":{"type":"integer","minimum":0,"format":"int64"},"type":{"type":"string","enum":["proposer","attester"]},"validatorIndices":{"type":"array","items":{"type":"string","pattern":"^[0-9]+$"}},"whistleblower":{"type":"string","pattern":"^[0-9]+$","description":"Validator index of the including beacon block proposer."},"conflictingRoots":{"type":"array","minItems":2,"maxItems":2,"items":{"type":"string","pattern":"^0x[0-9a-f]{64}$"},"description":"SSZ roots of the two unsigned headers or AttestationData containers."}}},"ValidatorSetChange":{"type":"object","required":["id","epoch","kind","validatorIndex","pubkey"],"properties":{"id":{"type":"string"},"epoch":{"type":"integer","minimum":0,"format":"int64"},"kind":{"type":"string","description":"At exit_epoch, an unslashed validator at or below EJECTION_BALANCE is ejected; every other exiting validator is exited. Slashed validators retain their separate slashed change.","enum":["activated","exited","slashed","ejected"]},"validatorIndex":{"type":"string","pattern":"^[0-9]+$"},"pubkey":{"type":"string"}},"description":"Milestones derived from finalized first-slot validator records. Slashed uses the first observed epoch. Ejected classifies unslashed exits at or below the beacon EJECTION_BALANCE using effective balance at the exit epoch; balance regained in the exit queue can produce an exited row. Withdrawability creates no change. Slashing event epochs identify actual block inclusion."},"SlashingsResponse":{"type":"object","required":["events","total","page","limit","backfillComplete","slashedValidatorCount"],"properties":{"events":{"type":"array","items":{"$ref":"#/components/schemas/SlashingEvent"}},"total":{"type":"integer","minimum":0,"format":"int64"},"page":{"type":"integer"},"limit":{"type":"integer"},"backfillComplete":{"type":"boolean","description":"True after the version 2 history walker has reached epoch zero."},"slashedValidatorCount":{"type":"integer","minimum":0,"format":"int64","description":"Network-wide slashed count from the current validator records, independent of page and filters."}}},"ValidatorSetChangesResponse":{"type":"object","required":["changes","total","page","limit","backfillComplete"],"properties":{"changes":{"type":"array","items":{"$ref":"#/components/schemas/ValidatorSetChange"}},"total":{"type":"integer","minimum":0,"format":"int64"},"page":{"type":"integer"},"limit":{"type":"integer"},"backfillComplete":{"type":"boolean","description":"True after the version 2 history walker has reached epoch zero."}}},"Error":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]},"MarketPriceLevel":{"type":"object","description":"One aggregated order-book price level. Decimal strings preserve exact values without floating-point conversion.","properties":{"price":{"type":"string","pattern":"^(?:0|[1-9][0-9]*)(?:\\.[0-9]+)?$"},"quantity":{"type":"string","pattern":"^(?:0|[1-9][0-9]*)(?:\\.[0-9]+)?$"}},"required":["price","quantity"],"additionalProperties":false},"MarketTrade":{"type":"object","description":"One recent MEXC public trade. The API synthesizes a stable id when MEXC returns null. aggressorSide is the taker side inferred from isBuyerMaker.","properties":{"id":{"type":"string"},"price":{"type":"string","pattern":"^(?:0|[1-9][0-9]*)(?:\\.[0-9]+)?$"},"quantity":{"type":"string","pattern":"^(?:0|[1-9][0-9]*)(?:\\.[0-9]+)?$"},"quoteQuantity":{"type":"string","pattern":"^(?:0|[1-9][0-9]*)(?:\\.[0-9]+)?$"},"time":{"type":"integer","format":"int64","description":"Unix timestamp in milliseconds."},"aggressorSide":{"type":"string","enum":["buy","sell"]}},"required":["id","price","quantity","quoteQuantity","time","aggressorSide"],"additionalProperties":false},"MarketTicker":{"type":"object","description":"Normalized decimal-string fields from MEXC's 24-hour ticker.","properties":{"high":{"type":"string"},"low":{"type":"string"},"last":{"type":"string"},"change":{"type":"string","description":"Absolute 24-hour price change."},"changePercent":{"type":"string","description":"MEXC's raw 24-hour change rate. Multiply by 100 for percent units."},"baseVolume":{"type":"string","description":"24-hour QRL volume."},"quoteVolume":{"type":["string","null"],"description":"24-hour USDT volume. MEXC can return null."}},"required":["high","low","last","change","changePercent","baseVolume","quoteVolume"],"additionalProperties":false},"MarketOrderBook":{"type":"object","properties":{"venue":{"type":"string","const":"MEXC"},"symbol":{"type":"string","const":"QRLUSDT"},"fetchedAt":{"type":"string","format":"date-time"},"lastUpdateId":{"type":"integer","format":"int64","minimum":0},"bids":{"type":"array","maxItems":500,"description":"Bid levels in MEXC order, highest price first. Up to 500 per side; QRLUSDT's resting bid book is smaller than that, so this side is usually complete.","items":{"$ref":"#/components/schemas/MarketPriceLevel"}},"asks":{"type":"array","maxItems":500,"description":"Ask levels in MEXC order, lowest price first. Up to 500 per side.","items":{"$ref":"#/components/schemas/MarketPriceLevel"}},"recentTrades":{"type":"array","maxItems":100,"items":{"$ref":"#/components/schemas/MarketTrade"}},"ticker":{"$ref":"#/components/schemas/MarketTicker"}},"required":["venue","symbol","fetchedAt","lastUpdateId","bids","asks","recentTrades","ticker"],"additionalProperties":false},"MarketVenue":{"type":"object","properties":{"id":{"type":"string","description":"Stable venue key accepted by the venue query parameter."},"name":{"type":"string"},"symbol":{"type":"string"},"quoteAsset":{"type":"string"}},"required":["id","name","symbol","quoteAsset"]},"MarketSizeBands":{"type":"object","description":"ShorScan's own trade-size thresholds in quote notional, reported so clients can label bands with real numbers.","properties":{"mediumFrom":{"type":"number","description":"Inclusive floor of the medium band."},"largeFrom":{"type":"number","description":"Inclusive floor of the large band."},"quoteAsset":{"type":"string"}},"required":["mediumFrom","largeFrom","quoteAsset"]},"MarketFlowBucket":{"type":"object","description":"Buy and sell split for one size band. Quantities are in the base asset (QRL); quote values are in the venue quote asset.","properties":{"bucket":{"type":"string","enum":["large","medium","small","total"]},"buyQuantity":{"type":"number"},"sellQuantity":{"type":"number"},"netQuantity":{"type":"number","description":"buyQuantity minus sellQuantity."},"buyQuote":{"type":"number"},"sellQuote":{"type":"number"},"netQuote":{"type":"number"},"buyTradeCount":{"type":"integer"},"sellTradeCount":{"type":"integer"}},"required":["bucket","buyQuantity","sellQuantity","netQuantity","buyQuote","sellQuote","netQuote","buyTradeCount","sellTradeCount"]},"MarketFlowPoint":{"type":"object","properties":{"time":{"type":"integer","description":"Inclusive start of the step, as Unix milliseconds."},"buyQuantity":{"type":"number"},"sellQuantity":{"type":"number"},"netQuantity":{"type":"number"}},"required":["time","buyQuantity","sellQuantity","netQuantity"]},"MarketFlowCoverage":{"type":"object","description":"Observed range and count of retained venue executions across all stored history. These fields do not detect collection gaps or establish uninterrupted coverage of the selected window.","properties":{"firstTradeAt":{"type":["integer","null"],"description":"Timestamp of the oldest stored trade for this venue."},"lastTradeAt":{"type":["integer","null"]},"tradeCount":{"type":"integer"},"complete":{"type":"boolean","description":"Legacy range flag: true when the oldest retained trade is at or before the selected window start. It does not establish continuity or freshness."}},"required":["firstTradeAt","lastTradeAt","tradeCount","complete"]},"MarketFundFlow":{"type":"object","properties":{"venue":{"$ref":"#/components/schemas/MarketVenue"},"venues":{"type":"array","description":"Every configured venue, so a client can offer a venue switcher.","items":{"$ref":"#/components/schemas/MarketVenue"}},"window":{"type":"string"},"windows":{"type":"array","items":{"type":"string"}},"windowStart":{"type":"integer"},"windowEnd":{"type":"integer"},"seriesStepMs":{"type":"integer","description":"Width of one series step in milliseconds."},"bands":{"$ref":"#/components/schemas/MarketSizeBands"},"buckets":{"type":"array","description":"One entry per size band, largest first, zero-filled when a band saw no trades.","items":{"$ref":"#/components/schemas/MarketFlowBucket"}},"totals":{"$ref":"#/components/schemas/MarketFlowBucket"},"series":{"type":"array","description":"Net buy volume per interval across the selected window. Empty intervals contain zero recorded volume; this does not establish collection continuity.","items":{"$ref":"#/components/schemas/MarketFlowPoint"}},"daily":{"type":"array","description":"Net buy volume per UTC day over dailyDays, including the current partial day. This UTC-aligned range is declared separately from the rolling selected window.","items":{"$ref":"#/components/schemas/MarketFlowPoint"}},"dailyDays":{"type":"integer","enum":[5,7,30],"description":"Number of UTC days in the daily series, including today."},"dailyStart":{"type":"integer","description":"Inclusive daily-series start as Unix milliseconds, aligned to UTC midnight."},"dailyEnd":{"type":"integer","description":"Exclusive end of the daily query, as Unix milliseconds."},"coverage":{"$ref":"#/components/schemas/MarketFlowCoverage"}},"required":["venue","venues","window","windows","windowStart","windowEnd","seriesStepMs","bands","buckets","totals","series","daily","coverage"]},"BlockResult":{"type":"object","description":"One execution-layer block. All numeric fields are 0x-prefixed hex strings.","properties":{"baseFeePerGas":{"type":"string"},"gasLimit":{"type":"string"},"gasUsed":{"type":"string"},"hash":{"type":"string"},"number":{"type":"string"},"parentHash":{"type":"string"},"receiptsRoot":{"type":"string"},"stateRoot":{"type":"string"},"timestamp":{"type":"string"},"transactions":{"type":"array","items":{"$ref":"#/components/schemas/BlockTransaction"}},"transactionsRoot":{"type":"string"},"extraData":{"type":"string"},"logsBloom":{"type":"string"},"miner":{"type":"string"},"size":{"type":"string"},"prevRandao":{"type":"string"},"withdrawals":{"type":"array","items":{"type":"object","properties":{"index":{"type":"string"},"validatorIndex":{"type":"string"},"address":{"type":"string"},"amount":{"type":"string"}}}},"withdrawalsRoot":{"type":"string"}}},"BlockTransaction":{"type":"object","description":"A transaction as embedded in a block document. Numeric fields are 0x-prefixed hex strings. The signature and publicKey fields carry the ML-DSA-87 signature material.","properties":{"blockHash":{"type":"string"},"blockNumber":{"type":"string"},"from":{"type":"string"},"gas":{"type":"string"},"gasPrice":{"type":"string"},"hash":{"type":"string"},"nonce":{"type":"string"},"to":{"type":"string"},"transactionIndex":{"type":"string"},"type":{"type":"string"},"value":{"type":"string"},"chainId":{"type":"string"},"signature":{"type":"string"},"publicKey":{"type":"string"},"input":{"type":"string","description":"Transaction calldata, stored internally under the legacy BSON data key."},"data":{"type":"string","description":"Compatibility alias of input for existing block-response clients."},"status":{"type":"string"},"gasUsed":{"type":"string","description":"Optional indexed actual receipt gas consumption."},"effectiveGasPrice":{"type":"string","description":"Optional indexed effective gas price."}}},"Transfer":{"type":"object","description":"Transaction detail projected from the indexed block. Available numeric quantities are 0x-prefixed hex strings; receipt quantities are empty when unavailable. PaidFees is an optional exact Quanta decimal string. Signature is the transaction's ML-DSA-87 signature and Pk is the signer's public key.","properties":{"ID":{"type":"string","description":"Internal record id."},"BlockNumber":{"type":"string"},"BlockTimestamp":{"type":"string"},"From":{"type":"string"},"To":{"type":"string"},"TxHash":{"type":"string"},"Value":{"type":"string"},"GasUsed":{"type":"string","description":"Actual receipt gas consumed, or an empty string when unavailable."},"GasLimit":{"type":"string","description":"Transaction gas limit, separate from consumption."},"GasPrice":{"type":"string"},"EffectiveGasPrice":{"type":"string","description":"Receipt effective gas price, or an empty string when unavailable."},"Status":{"type":"string","description":"Receipt execution status: 0x1 success, 0x0 revert, empty when unavailable."},"PaidFees":{"type":"string","description":"Exact Quanta fee from receipt accounting. Omitted when unavailable."},"BlockHash":{"type":"string"},"Nonce":{"type":"string"},"Signature":{"type":"string"},"Pk":{"type":"string"},"Size":{"type":"string"},"Input":{"type":"string","description":"Calldata as a 0x-prefixed hex string. Present for contract calls."}}},"TransactionByAddress":{"type":"object","description":"One indexed transaction row. Amount and verified PaidFees are decimal strings denominated in Quanta with 18 fractional digits. PaidFees is omitted for legacy rows lacking receipt provenance. BlockNumber and TimeStamp are decimal strings.","properties":{"ID":{"type":"string","description":"Internal record id."},"InOut":{"type":"integer","description":"Direction flag relative to the indexed address."},"TxType":{"type":"string"},"Address":{"type":"string"},"From":{"type":"string"},"To":{"type":"string"},"TxHash":{"type":"string"},"TimeStamp":{"type":"string"},"Amount":{"type":"string"},"PaidFees":{"type":"string","description":"Exact receipt-derived fee. Omitted when unavailable."},"Status":{"type":"string","description":"Optional receipt execution status: 0x1 success or 0x0 revert. Legacy rows may omit it."},"BlockNumber":{"type":"string"}}},"PendingTransaction":{"type":"object","description":"A mempool transaction. Gas, value, and nonce fields are 0x-prefixed hex strings; lastSeen and createdAt are Unix timestamps.","properties":{"accessList":{"type":"array","items":{}},"blockHash":{},"blockNumber":{},"chainId":{"type":"string"},"from":{"type":"string"},"gas":{"type":"string"},"gasPrice":{"type":"string"},"hash":{"type":"string"},"input":{"type":"string"},"maxFeePerGas":{"type":"string"},"maxPriorityFeePerGas":{"type":"string"},"nonce":{"type":"string"},"publicKey":{"type":"string"},"to":{"type":"string"},"transactionIndex":{},"type":{"type":"string"},"value":{"type":"string"},"status":{"type":"string","enum":["pending","mined","dropped"]},"lastSeen":{"type":"integer"},"createdAt":{"type":"integer"}}},"TokenTransfer":{"type":"object","description":"One token transfer event. amount is a raw decimal string, before dividing by tokenDecimals.","properties":{"contractAddress":{"type":"string"},"from":{"type":"string"},"to":{"type":"string"},"amount":{"type":"string"},"blockNumber":{"type":"string","description":"0x-prefixed hex."},"blockHash":{"type":"string","description":"Exact canonical block hash for this event."},"blockNumberInt":{"type":"integer"},"txHash":{"type":"string"},"logIndex":{"type":"string"},"timestamp":{"type":"string"},"tokenSymbol":{"type":"string"},"tokenDecimals":{"type":"integer"},"tokenName":{"type":"string"},"transferType":{"type":"string"},"tokenStandard":{"type":"string"},"tokenID":{"type":"string"}}},"TokenBalance":{"type":"object","description":"One token holding. balance is a raw decimal string, before dividing by decimals. NFT rows carry tokenID and tokenStandard.","properties":{"contractAddress":{"type":"string"},"holderAddress":{"type":"string"},"balance":{"type":"string"},"blockNumber":{"type":"string"},"updatedAt":{"type":"string"},"tokenID":{"type":"string"},"tokenStandard":{"type":"string"},"name":{"type":"string"},"symbol":{"type":"string"},"decimals":{"type":"integer"}}},"NFTBalance":{"type":"object","description":"One NFT holding joined with collection and per-token metadata.","properties":{"contractAddress":{"type":"string"},"holderAddress":{"type":"string"},"tokenID":{"type":"string"},"tokenStandard":{"type":"string"},"balance":{"type":"string"},"blockNumber":{"type":"string"},"updatedAt":{"type":"string"},"collectionName":{"type":"string"},"collectionSymbol":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"image":{"type":"string"},"externalURL":{"type":"string"},"attributes":{"type":"array","items":{"type":"object","properties":{"trait_type":{"type":"string"},"value":{"type":"string"},"display_type":{"type":"string"}}}}}},"ContractMeta":{"type":"object","description":"Compact contract metadata attached to logs and call targets. Verified records carry provenanceStatus. The abi field is suppressed when recorded compiler or source-bundle metadata is invalid; legacy-unrecorded ABI remains available with an explicit warning state.","properties":{"name":{"type":"string"},"symbol":{"type":"string"},"tokenStandard":{"type":"string"},"verified":{"type":"boolean"},"contractName":{"type":"string"},"abi":{"type":"string"},"provenanceStatus":{"type":"string","enum":["digest-backed","legacy-unrecorded","invalid-recorded"],"description":"Trust classification over compact recorded compiler provenance and versioned source-bundle digest metadata. Compact reads validate digest syntax and reserve exact source recomputation for full contract reads."}}},"CompilerProvenanceComponent":{"type":"object","description":"One content-addressed runtime component that affected compiler output.","required":["name","sha256"],"properties":{"name":{"type":"string","enum":["hypc","nsjail","policy"]},"sha256":{"type":"string","pattern":"^[0-9a-f]{64}$"}},"additionalProperties":false},"CompilerProvenance":{"type":"object","description":"Content-addressed identity of the sealed native compiler, static NsJail launcher, and embedded sandbox policy persisted at verification time. Schema v2 binds the exact ordered components with a length-prefixed SHA-256 execution digest. Its absence on an older record means legacy-unrecorded and must not be inferred from the current registry.","required":["schema","kind","buildId","executionDigest","components"],"properties":{"schema":{"type":"string","const":"qrl.contract-compiler-provenance.v2"},"kind":{"type":"string","const":"native"},"buildId":{"type":"string","minLength":1},"executionDigest":{"type":"string","pattern":"^[0-9a-f]{64}$"},"components":{"type":"array","minItems":3,"maxItems":3,"prefixItems":[{"allOf":[{"$ref":"#/components/schemas/CompilerProvenanceComponent"},{"type":"object","properties":{"name":{"const":"hypc"}}}]},{"allOf":[{"$ref":"#/components/schemas/CompilerProvenanceComponent"},{"type":"object","properties":{"name":{"const":"nsjail"}}}]},{"allOf":[{"$ref":"#/components/schemas/CompilerProvenanceComponent"},{"type":"object","properties":{"name":{"const":"policy"}}}]}],"items":false}},"additionalProperties":false},"ContractExplainChallenge":{"type":"object","required":["challengeId","messageHex","signer","contract","origin","chainId","expiresAt"],"properties":{"challengeId":{"type":"string","pattern":"^[0-9a-f]{64}$"},"messageHex":{"type":"string","pattern":"^0x(?:[0-9a-f]{2})+$","maxLength":32770},"signer":{"type":"string","pattern":"^Q[0-9a-fA-F]{128}$","description":"Canonical checksum-cased QIP-55 contract creator address."},"contract":{"type":"string","pattern":"^Q[0-9a-fA-F]{128}$","description":"Canonical checksum-cased QIP-55 contract address."},"origin":{"type":"string","format":"uri"},"chainId":{"type":"string","pattern":"^0x[1-9a-f][0-9a-f]*$","maxLength":66},"expiresAt":{"type":"string","format":"date-time","pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}Z$"}},"additionalProperties":false},"ContractExplainSignedMessageProof":{"type":"object","required":["signature","publicKey","descriptor","signer","digest","schemeVersion"],"properties":{"signature":{"type":"string","pattern":"^0x[0-9a-fA-F]{9254}$"},"publicKey":{"type":"string","pattern":"^0x[0-9a-fA-F]{5184}$"},"descriptor":{"type":"string","const":"0x010000"},"signer":{"type":"string","pattern":"^Q[0-9a-fA-F]{128}$","description":"Canonical checksum-cased QIP-55 contract creator address."},"digest":{"type":"string","pattern":"^0x[0-9a-fA-F]{128}$"},"schemeVersion":{"type":"string","const":"QRL-SIGN-MSG-v1"}},"additionalProperties":false},"ContractExplainAuthorizationRequest":{"type":"object","required":["challengeId","proof"],"properties":{"challengeId":{"type":"string","pattern":"^[0-9a-f]{64}$"},"proof":{"$ref":"#/components/schemas/ContractExplainSignedMessageProof"}},"additionalProperties":false},"ContractInfo":{"type":"object","description":"A contract record. Verified contracts additionally carry source, ABI, and compiler settings; token contracts carry name, symbol, decimals, and standard.","properties":{"creatorAddress":{"type":"string"},"address":{"type":"string","pattern":"^Q[0-9a-f]{128}$","description":"Canonical lowercase-hex QIP-55 contract address."},"contractCode":{"type":"string"},"contractCodeSha256":{"type":"string","pattern":"^[0-9a-f]{64}$"},"creationTransaction":{"type":"string","pattern":"^(?:|0x[0-9a-f]{64})$"},"creationBlockNumber":{"type":"string","pattern":"^0x(?:0|[1-9a-f][0-9a-f]*)$"},"creationBlockHash":{"type":"string","pattern":"^0x[0-9a-f]{64}$"},"chainId":{"type":"string","pattern":"^0x(?:0|[1-9a-f][0-9a-f]*)$"},"isToken":{"type":"boolean"},"status":{"type":"string"},"decimals":{"type":"integer"},"name":{"type":"string"},"symbol":{"type":"string"},"totalSupply":{"type":"string"},"updatedAt":{"type":"string"},"tokenStandard":{"type":"string"},"genesisContract":{"type":"boolean"},"verified":{"type":"boolean"},"verificationRecordSchema":{"type":["string","null"],"enum":["qrl.contract-verification-record.v1","qrl.contract-verification-record.v2","qrl.contract-verification-record.v3",null],"description":"V2 and V3 records bind the source bundle and compiler settings to one canonical deployment generation. V3 is used only when the verification compiled a nested primarySourcePath or via IR; it additionally binds both. V1 and genuinely absent historical records remain legacy-unrecorded; explicit null or any unrecognized value is invalid-recorded."},"sourceCode":{"type":"string"},"abi":{"type":"string","description":"Exact compact JSON ABI bytes included in the V2 verification artifact digest."},"contractName":{"type":"string"},"compilerVersion":{"type":"string"},"compilerProvenance":{"anyOf":[{"$ref":"#/components/schemas/CompilerProvenance"},{"type":"null"}]},"imports":{"type":"object","description":"Canonical effective import sources used to reproduce verified bytecode.","additionalProperties":{"type":"string"}},"primarySourcePath":{"type":"string","description":"Repo-relative path the primary source was compiled under. Only V3 records carry it; absent means <contractName>.hyp at the root."},"viaIR":{"type":"boolean","description":"True when the contract was compiled via IR. Only V3 records carry it; absent means false."},"sourceBundleDigest":{"type":["string","null"],"description":"Versioned SHA-256 identity of the exact primary and canonical import source bytes for this verification.","pattern":"^qrl\\.verified-source-bundle\\.v1:sha256:[0-9a-f]{64}$"},"verificationArtifactDigest":{"type":"string","pattern":"^qrl\\.contract-verification-artifact\\.v[23]:sha256:[0-9a-f]{64}$","description":"SHA-256 over uint64 big-endian length-prefixed verification fields: record schema marker, canonical deployment target, source bundle, ABI, compiler provenance and settings, and sorted libraries. V3 digests append the effective primary source path and the via-IR flag."},"optimizationEnabled":{"type":"boolean"},"optimizationRuns":{"type":"integer"},"evmVersion":{"type":"string"},"constructorArguments":{"type":"string"},"libraries":{"type":"object","additionalProperties":{"type":"string"}},"license":{"type":"string"},"verificationMethod":{"type":"string","const":"full-source"},"verifiedAt":{"type":"string","format":"date-time"},"aiExplanationSourceDigest":{"type":"string","description":"Source-bundle identity used to generate the cached AI explanation. Legacy unbound explanations omit this field and are not served.","pattern":"^qrl\\.verified-source-bundle\\.v1:sha256:[0-9a-f]{64}$"}},"allOf":[{"if":{"properties":{"verificationRecordSchema":{"const":"qrl.contract-verification-record.v2"}},"required":["verificationRecordSchema"]},"then":{"properties":{"verificationArtifactDigest":{"pattern":"^qrl\\.contract-verification-artifact\\.v2:sha256:[0-9a-f]{64}$"},"primarySourcePath":false,"viaIR":false},"required":["address","contractCodeSha256","creationTransaction","creationBlockNumber","creationBlockHash","chainId","sourceCode","abi","contractName","compilerVersion","compilerProvenance","sourceBundleDigest","verificationArtifactDigest","optimizationEnabled","optimizationRuns","verificationMethod"]}},{"if":{"properties":{"verificationRecordSchema":{"const":"qrl.contract-verification-record.v3"}},"required":["verificationRecordSchema"]},"then":{"properties":{"verificationArtifactDigest":{"pattern":"^qrl\\.contract-verification-artifact\\.v3:sha256:[0-9a-f]{64}$"},"viaIR":{"const":true}},"anyOf":[{"required":["primarySourcePath"]},{"required":["viaIR"]}],"required":["address","contractCodeSha256","creationTransaction","creationBlockNumber","creationBlockHash","chainId","sourceCode","abi","contractName","compilerVersion","compilerProvenance","sourceBundleDigest","verificationArtifactDigest","optimizationEnabled","optimizationRuns","verificationMethod"]}}],"additionalProperties":true}}}}