explorer-monorepo/docs/EXPLORER_API_REFERENCE.md

# SolaceScan Explorer — API Reference

The SolaceScan frontend uses the **Blockscout v2 API** for chain data. When the explorer is served from the same origin (e.g. `https://blockscout.defi-oracle.io` 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://blockscout.defi-oracle.io/api`)
- **Fallback:** `https://blockscout.defi-oracle.io/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://blockscout.defi-oracle.io/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