{"openapi":"3.0.3","info":{"title":"Logos Indexer Explorer API","version":"0.1.2","description":"Read-only explorer API for the Logos blockchain indexer. All list endpoints default to canonical, finalized rows; pass `canonical=all` or `finalized=all` to include orphans / hot-tail blocks.","contact":{"name":"Citizen Web3","url":"https://github.com/citizenweb3/chain-data-indexer"}},"servers":[{"url":"/","description":"Current host"},{"url":"http://localhost:3001","description":"Local indexer"}],"tags":[{"name":"system","description":"Health, metrics, OpenAPI"},{"name":"stats","description":"Aggregate chain statistics"},{"name":"blocks","description":"Indexed blocks (canonical chain by default)"},{"name":"transactions","description":"Indexed transactions with safe explorer decode"},{"name":"leader-keys","description":"Per-block proof-of-leadership keys (NOT validator identities)"},{"name":"validators","description":"Reserved (not exposed by Logos v0.1.2)"}],"paths":{"/health":{"get":{"tags":["system"],"summary":"Liveness + lag report","responses":{"200":{"description":"Healthy","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Health"}}}},"503":{"description":"Degraded (node unreachable)"}}}},"/metrics":{"get":{"tags":["system"],"summary":"Prometheus metrics (text exposition)","responses":{"200":{"description":"Prometheus exposition format","content":{"text/plain":{}}},"404":{"description":"Disabled (METRICS_ENABLED=false)"}}}},"/openapi.json":{"get":{"tags":["system"],"summary":"This OpenAPI document","responses":{"200":{"description":"OpenAPI 3.0 spec","content":{"application/json":{}}}}}},"/docs":{"get":{"tags":["system"],"summary":"Swagger UI for this API","responses":{"200":{"description":"HTML page","content":{"text/html":{}}}}}},"/api/v1/stats":{"get":{"tags":["stats"],"summary":"Aggregate stats over canonical chain","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Stats"}}}}}}},"/api/v1/blocks":{"get":{"tags":["blocks"],"summary":"List blocks (canonical + finalized by default)","parameters":[{"$ref":"#/components/parameters/Limit"},{"$ref":"#/components/parameters/Offset"},{"$ref":"#/components/parameters/Order"},{"name":"sort","in":"query","schema":{"type":"string","enum":["height","slot"],"default":"height"},"description":"Primary sort column."},{"$ref":"#/components/parameters/Finalized"},{"$ref":"#/components/parameters/Canonical"},{"name":"leader_key","in":"query","schema":{"type":"string"},"description":"Filter by per-block proof-of-leadership key (hex)."}],"responses":{"200":{"description":"Page of block summaries","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BlockListResponse"}}}}}}},"/api/v1/blocks/{id}":{"get":{"tags":["blocks"],"summary":"Block detail with transactions and raw payload","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Block id (hex header hash)."}],"responses":{"200":{"description":"Block detail","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BlockDetail"}}}},"404":{"$ref":"#/components/responses/NotFound"}}}},"/api/v1/transactions":{"get":{"tags":["transactions"],"summary":"List transactions (canonical + finalized by default)","parameters":[{"$ref":"#/components/parameters/Limit"},{"$ref":"#/components/parameters/Offset"},{"$ref":"#/components/parameters/Order"},{"name":"sort","in":"query","schema":{"type":"string","enum":["height","slot"],"default":"height"},"description":"Primary sort column on the joined block."},{"$ref":"#/components/parameters/Finalized"},{"$ref":"#/components/parameters/Canonical"},{"name":"block_id","in":"query","schema":{"type":"string"},"description":"Filter by block id."}],"responses":{"200":{"description":"Page of tx summaries","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TransactionListResponse"}}}}}}},"/api/v1/transactions/{id}":{"get":{"tags":["transactions"],"summary":"Transaction by id or hash (with safe decode + raw)","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Transaction id or tx_hash."}],"responses":{"200":{"description":"Transaction detail","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TransactionDetail"}}}},"404":{"$ref":"#/components/responses/NotFound"}}}},"/api/v1/leader-keys":{"get":{"tags":["leader-keys"],"summary":"Per-block proof-of-leadership keys (diagnostics, NOT validator identities)","parameters":[{"$ref":"#/components/parameters/Limit"},{"$ref":"#/components/parameters/Offset"}],"responses":{"200":{"description":"Page of leader keys","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LeaderKeyListResponse"}}}}}}},"/api/v1/leader-keys/{leader_key}":{"get":{"tags":["leader-keys"],"summary":"Single leader-key diagnostics row","parameters":[{"name":"leader_key","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Leader-key row","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LeaderKey"}}}},"404":{"$ref":"#/components/responses/NotFound"}}}},"/api/v1/leader-keys/{leader_key}/blocks":{"get":{"tags":["leader-keys"],"summary":"Blocks produced under a given leader key","parameters":[{"name":"leader_key","in":"path","required":true,"schema":{"type":"string"}},{"$ref":"#/components/parameters/Limit"},{"$ref":"#/components/parameters/Offset"},{"$ref":"#/components/parameters/Finalized"},{"$ref":"#/components/parameters/Canonical"}],"responses":{"200":{"description":"Page of block summaries","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BlockListResponse"}}}}}}},"/api/v1/validators":{"get":{"tags":["validators"],"summary":"Reserved — not available on Logos v0.1.2","description":"Logos v0.1.2 block headers expose `proof_of_leadership.leader_key`, which is a per-block ephemeral proof key, not a stable validator identity. Use `/api/v1/leader-keys` for diagnostics.","responses":{"410":{"description":"Validator identity unavailable in current network release"}}}}},"components":{"parameters":{"Limit":{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":20},"description":"Page size (max 100)."},"Offset":{"name":"offset","in":"query","schema":{"type":"integer","minimum":0,"default":0},"description":"Page offset."},"Order":{"name":"order","in":"query","schema":{"type":"string","enum":["asc","desc"],"default":"desc"}},"Finalized":{"name":"finalized","in":"query","schema":{"type":"string","enum":["true","false","all"],"default":"true"},"description":"Filter by LIB-ancestry finality. `all` includes hot-tail blocks."},"Canonical":{"name":"canonical","in":"query","schema":{"type":"string","enum":["true","false","all"],"default":"true"},"description":"Filter by canonical-chain membership. `all` includes orphan siblings."}},"responses":{"NotFound":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]},"Pagination":{"type":"object","properties":{"limit":{"type":"integer"},"offset":{"type":"integer"},"order":{"type":"string","enum":["asc","desc"]},"sort":{"type":"string"},"has_more":{"type":"boolean"},"total":{"type":"integer","nullable":true}},"required":["limit","offset","has_more"]},"Health":{"type":"object","properties":{"status":{"type":"string","enum":["ok","degraded","error"]},"last_slot":{"type":"integer"},"node_tip_slot":{"type":"integer","nullable":true},"node_height":{"type":"integer","nullable":true},"node_mode":{"type":"string","nullable":true},"lag_slots":{"type":"integer","nullable":true},"uptime_s":{"type":"integer"}}},"Stats":{"type":"object","properties":{"total_blocks":{"type":"integer","description":"Canonical blocks indexed."},"total_transactions":{"type":"integer","description":"Transactions on canonical blocks."},"finalized_blocks":{"type":"integer"},"latest_slot":{"type":"integer","nullable":true},"latest_height":{"type":"integer","nullable":true},"leader_keys_count":{"type":"integer"},"last_indexed_slot":{"type":"integer"},"node_tip_slot":{"type":"integer","nullable":true},"node_height":{"type":"integer","nullable":true},"node_mode":{"type":"string","nullable":true},"lag_slots":{"type":"integer","nullable":true}}},"BlockSummary":{"type":"object","properties":{"id":{"type":"string","description":"Block id (header hash, hex)."},"parent_block":{"type":"string"},"slot":{"type":"integer"},"height":{"type":"integer","nullable":true,"description":"Derived from canonical anchors; never aliased to slot."},"block_root":{"type":"string"},"leader_key":{"type":"string","description":"Per-block proof-of-leadership key (NOT a validator identity)."},"voucher_cm":{"type":"string"},"entropy":{"type":"string"},"tx_count":{"type":"integer"},"finalized":{"type":"boolean","description":"Member of LIB ancestry."},"is_canonical":{"type":"boolean","description":"Member of current tip ancestry."},"indexed_at":{"type":"string","format":"date-time"}}},"BlockDetail":{"allOf":[{"$ref":"#/components/schemas/BlockSummary"},{"type":"object","properties":{"transactions":{"type":"array","items":{"$ref":"#/components/schemas/TransactionSummary"}},"raw":{"description":"Full raw block payload from /cryptarchia/blocks.","nullable":true}}}]},"BlockListResponse":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/BlockSummary"}},"pagination":{"$ref":"#/components/schemas/Pagination"}},"required":["data","pagination"]},"DecodedOp":{"type":"object","properties":{"opcode":{"type":"integer"},"opcode_name":{"type":"string","description":"Stable name from upstream opcode table."},"payload":{"description":"Normalized known fields + hex_preview / ascii_fragments for opaque bytes."}}},"TransactionSummary":{"type":"object","properties":{"id":{"type":"string"},"hash":{"type":"string"},"tx_hash":{"type":"string","nullable":true},"block_id":{"type":"string"},"position":{"type":"integer"},"slot":{"type":"integer"},"height":{"type":"integer","nullable":true},"finalized":{"type":"boolean"},"is_canonical":{"type":"boolean"},"op_count":{"type":"integer"},"op_types":{"type":"array","items":{"type":"string"}},"proof_types":{"type":"array","items":{"type":"string"}},"storage_gas_price":{"type":"integer"},"execution_gas_price":{"type":"integer"},"indexed_at":{"type":"string","format":"date-time"}}},"TransactionDetail":{"allOf":[{"$ref":"#/components/schemas/TransactionSummary"},{"type":"object","properties":{"decoded":{"type":"object","description":"Safe explorer decode (opcode names, normalized known fields, byte previews). NOT a semantic decode of UTXO/note state.","properties":{"ops":{"type":"array","items":{"$ref":"#/components/schemas/DecodedOp"}},"proofs":{"type":"array","items":{"type":"object"}}}},"raw":{"description":"Full raw transaction payload."}}}]},"TransactionListResponse":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/TransactionSummary"}},"pagination":{"$ref":"#/components/schemas/Pagination"}},"required":["data","pagination"]},"LeaderKey":{"type":"object","properties":{"leader_key":{"type":"string"},"blocks_with_key":{"type":"integer"},"first_seen_slot":{"type":"integer","nullable":true},"last_seen_slot":{"type":"integer","nullable":true},"stable_validator_identity":{"type":"boolean","description":"Always false on Logos v0.1.2."},"identity_scope":{"type":"string"},"updated_at":{"type":"string","format":"date-time"}}},"LeaderKeyListResponse":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/LeaderKey"}},"pagination":{"$ref":"#/components/schemas/Pagination"}},"required":["data","pagination"]}}}}