94 lines
4.6 KiB
Markdown
94 lines
4.6 KiB
Markdown
# 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](EXPLORER_ADDITIONAL_RECOMMENDATIONS.md).
|
||
|
||
## See Also
|
||
|
||
- [EXPLORER_API_ACCESS.md](EXPLORER_API_ACCESS.md) — Troubleshooting API connectivity and 502s
|
||
- [Blockscout API docs](https://docs.blockscout.com/) — Official Blockscout API documentation
|