explorer-monorepo/docs/EXPLORER_API_REFERENCE.md

SolaceScanScout Explorer — API Reference

The SolaceScanScout frontend uses the Blockscout v2 API for chain data. When the explorer is served from the same origin (e.g. https://explorer.d-bis.org or VM IP), requests go to /api and are proxied to Blockscout (port 4000). This document lists the endpoints used by the frontend.

Base URL

• Same-origin: window.location.origin + '/api' (e.g. https://explorer.d-bis.org/api)
• Fallback: https://explorer.d-bis.org/api

All paths below are relative to this base (e.g. /v2/stats → {base}/v2/stats).

---

Stats & Network

Endpoint	Method	Purpose
/v2/stats	GET	Total blocks, transactions, addresses; optional average_block_time, transactions_per_second
/v2/blocks?page=1&page_size=N	GET	Paginated blocks (N = 5–50). Used for stats, gas widget, block list
/v2/blocks/{blockNumber}	GET	Single block by number. Used for block detail and export

---

Transactions

Endpoint	Method	Purpose
/v2/transactions?page=1&page_size=N	GET	Paginated transactions (list, CSV export)
/v2/transactions?address={address}&page=1&page_size=N	GET	Transactions for an address (address detail tab, CSV export)
/v2/transactions?filter=to&page=1&page_size=10	GET	Latest transactions (home feed)
/v2/transactions/{txHash}	GET	Single transaction (detail, CSV/JSON export)
/v2/transactions/{txHash}/internal-transactions	GET	Internal transactions for a tx (alternate: internal_transactions)
/v2/transactions/{txHash}/logs	GET	Event logs for a tx (alternate: log_entries)

---

Addresses

Endpoint	Method	Purpose
/v2/addresses/{address}	GET	Address balance, tx count, token count, is_contract, is_verified
/v2/addresses/{address}/token-balances	GET	Token balances (ERC-20/721/1155). Alternate: token_balances
/v2/addresses/{address}/nft-inventory	GET	NFT inventory (alternates: nft_tokens, or filter token-balances by type)
/v2/addresses/{address}/internal-transactions	GET	Internal transactions (alternate: internal_transactions)

---

Contracts & Tokens

Endpoint	Method	Purpose
/v2/smart-contracts/{address}	GET	Contract ABI, bytecode, verification (alternate: /v2/contracts/{address})
/v2/tokens/{tokenAddress}	GET	Token info (name, symbol, decimals, total supply, holders). Alternate: /v2/token/{tokenAddress}
/v2/tokens/{tokenAddress}/transfers?page=1&page_size=N	GET	Token transfers (token profile page)
/v2/tokens/{contractAddress}/nft/{tokenId}	GET	NFT instance (metadata, image, owner). Alternate: /v2/nft/{contractAddress}/{tokenId}

---

Search

Endpoint	Method	Purpose
/v2/search?q={query}	GET	Search by token/contract name, symbol, address, tx hash, block number

---

Response Shapes (summary)

• Lists: Usually { items: [...] } or array. Frontend normalizes with normalizeBlock, normalizeTransaction, normalizeAddress.
• Single block: height/number, hash, timestamp, miner, transaction_count, gas_used, gas_limit, base_fee_per_gas, burnt_fees, parent_hash, nonce, etc. Optional: consensus, finality, validated for finality.
• Single transaction: hash, from, to, value, block_number, gas_used, gas_limit, input, decoded_input, revert_reason, status, etc.
• Address: hash/address, balance/coin_balance, transactions_count, token_count, is_contract, is_verified.

---

Rate Limits & API Keys

The frontend does not send API keys. Rate limits are determined by the Blockscout/nginx deployment. For premium or authenticated access, a separate backend (e.g. Go API) would be required (Tier 3).

---

OpenAPI / Swagger

If your Blockscout instance exposes an OpenAPI (Swagger) spec, it is often at {base}/api-docs or {base}/swagger. Document that URL for your deployment (e.g. https://explorer.d-bis.org/api-docs if enabled).

Recent changes

• Search results list; Tokens page; Token approvals link; Contract creation / first-last tx on address; Pagination (blocks/txs); Event log decoding; Failed tx rate in Gas widget; More i18n + FR; Copy buttons; Known-address labels. See EXPLORER_ADDITIONAL_RECOMMENDATIONS.md.

See Also

• EXPLORER_API_ACCESS.md — Troubleshooting API connectivity and 502s
• Blockscout API docs — Official Blockscout API documentation