# Blockscout Parameters and Endpoints Guide

**Date**: December 23, 2025  
**Domain**: https://explorer.d-bis.org

---

## 🔍 Current Status

### ✅ Working: API Endpoints
- ✅ API endpoints respond correctly **WITH parameters**
- ✅ `/api?module=block&action=eth_block_number` - ✅ Working
- ✅ `/api/v2/stats` - ✅ Working
- ✅ Blockscout is indexing: 115,954+ blocks

### ⚠️ Web Interface: Page Not Found
- ⚠️ Root path (`/`) returns 404
- ⚠️ Web interface routes return 404
- **Reason**: Web interface may need more initialization time or more indexed data

---

## 📋 Required Parameters for Blockscout API

### API Endpoint Format

```
GET /api?module=<MODULE>&action=<ACTION>&<ADDITIONAL_PARAMETERS>
```

**All API calls require**:
- `module` (required): Module name
- `action` (required): Action to perform

---

## 🔧 Working API Endpoints

### 1. **Get Latest Block Number** ✅

```bash
GET /api?module=block&action=eth_block_number
```

**Example**:
```bash
curl "https://explorer.d-bis.org/api?module=block&action=eth_block_number"
```

**Response**:
```json
{"jsonrpc":"2.0","result":"0x1c4fd","id":1}
```

**Result**: `0x1c4fd` = 115,965 (decimal)

---

### 2. **Get Network Statistics** ✅

```bash
GET /api/v2/stats
```

**Example**:
```bash
curl "https://explorer.d-bis.org/api/v2/stats"
```

**Response**:
```json
{
  "total_blocks": "115937",
  "total_transactions": "46",
  "total_addresses": "32",
  "average_block_time": 2000.0,
  "coin_price": "2920.55",
  ...
}
```

---

### 3. **Get Block by Number** ✅

```bash
GET /api?module=block&action=eth_get_block_by_number&tag=<BLOCK_NUMBER>&boolean=true
```

**Parameters**:
- `module=block` (required)
- `action=eth_get_block_by_number` (required)
- `tag=<BLOCK_NUMBER>` (required) - Hex format (e.g., `0x1` for block 1, `0x64` for block 100)
- `boolean=true` (optional) - Include full transaction objects

**Example**:
```bash
# Get block 1
curl "https://explorer.d-bis.org/api?module=block&action=eth_get_block_by_number&tag=0x1&boolean=true"

# Get block 100 (decimal = 0x64 hex)
curl "https://explorer.d-bis.org/api?module=block&action=eth_get_block_by_number&tag=0x64&boolean=true"
```

---

### 4. **Get Transaction by Hash** ✅

```bash
GET /api?module=transaction&action=eth_getTransactionByHash&txhash=<TRANSACTION_HASH>
```

**Parameters**:
- `module=transaction` (required)
- `action=eth_getTransactionByHash` (required)
- `txhash=<HASH>` (required) - Transaction hash (0x-prefixed hex)

**Example**:
```bash
curl "https://explorer.d-bis.org/api?module=transaction&action=eth_getTransactionByHash&txhash=0x..."
```

---

### 5. **Get Address Balance** ✅

```bash
GET /api?module=account&action=eth_get_balance&address=<ADDRESS>&tag=latest
```

**Parameters**:
- `module=account` (required)
- `action=eth_get_balance` (required)
- `address=<ADDRESS>` (required) - Ethereum address (0x-prefixed)
- `tag=latest` (required) - Block tag (`latest`, `earliest`, `pending`, or block number)

**Example**:
```bash
curl "https://explorer.d-bis.org/api?module=account&action=eth_get_balance&address=0x0000000000000000000000000000000000000000&tag=latest"
```

---

### 6. **Get Address Transactions** ✅

```bash
GET /api?module=account&action=txlist&address=<ADDRESS>&startblock=0&endblock=99999999&page=1&offset=10
```

**Parameters**:
- `module=account` (required)
- `action=txlist` (required)
- `address=<ADDRESS>` (required)
- `startblock=0` (optional) - Start block number
- `endblock=99999999` (optional) - End block number
- `page=1` (optional) - Page number
- `offset=10` (optional) - Results per page

**Example**:
```bash
curl "https://explorer.d-bis.org/api?module=account&action=txlist&address=0x...&startblock=0&endblock=99999999&page=1&offset=10"
```

---

## 🎯 Common API Module/Action Combinations

### Block Module

| Action | Parameters | Description |
|--------|------------|-------------|
| `eth_block_number` | None | Get latest block number |
| `eth_get_block_by_number` | `tag`, `boolean` | Get block details |
| `get_block_reward` | `blockno` | Get block reward (if available) |

### Transaction Module

| Action | Parameters | Description |
|--------|------------|-------------|
| `eth_getTransactionByHash` | `txhash` | Get transaction by hash |
| `gettxreceiptstatus` | `txhash` | Get transaction receipt status |
| `getstatus` | `txhash` | Get transaction status |

### Account Module

| Action | Parameters | Description |
|--------|------------|-------------|
| `eth_get_balance` | `address`, `tag` | Get address balance |
| `txlist` | `address`, `startblock`, `endblock`, `page`, `offset` | Get address transactions |
| `tokentx` | `address`, `startblock`, `endblock`, `page`, `offset` | Get token transfers |

### Token Module

| Action | Parameters | Description |
|--------|------------|-------------|
| `tokeninfo` | `contractaddress` | Get token information |
| `tokenbalance` | `contractaddress`, `address` | Get token balance |

---

## 🌐 Web Interface Routes (When Available)

Once the web interface is fully operational, these routes will be available:

### Block Routes
- `https://explorer.d-bis.org/` - Homepage (shows latest blocks)
- `https://explorer.d-bis.org/blocks` - All blocks
- `https://explorer.d-bis.org/block/<BLOCK_NUMBER>` - Specific block
- `https://explorer.d-bis.org/block/<BLOCK_HASH>` - Block by hash

### Transaction Routes
- `https://explorer.d-bis.org/transactions` - All transactions
- `https://explorer.d-bis.org/tx/<TRANSACTION_HASH>` - Specific transaction

### Address Routes
- `https://explorer.d-bis.org/address/<ADDRESS>` - Address details
- `https://explorer.d-bis.org/address/<ADDRESS>/transactions` - Address transactions

### Token Routes
- `https://explorer.d-bis.org/tokens` - All tokens
- `https://explorer.d-bis.org/token/<CONTRACT_ADDRESS>` - Token details

---

## ⚠️ Why "Page Not Found" on Root Path?

### Current Situation

1. **API is Working** ✅
   - All API endpoints respond correctly with proper parameters
   - Blockscout is indexing blocks (115,954+ blocks)

2. **Web Interface Returns 404** ⚠️
   - Root path (`/`) returns "Page not found"
   - Web interface routes return 404

### Possible Reasons

1. **Static Assets Not Generated**
   - Static files directory (`/app/apps/explorer/priv/static/`) may be empty
   - Blockscout may need to compile static assets

2. **Web Interface Initialization**
   - Web interface may need more time to fully initialize
   - May require restart or specific initialization

3. **Data Requirements**
   - Web interface may need minimum amount of indexed data
   - May need transactions/addresses in addition to blocks

4. **Route Configuration**
   - Blockscout web interface may have specific route requirements
   - May need specific configuration for root path

---

## 🔧 Solution: Use API Endpoints

**Immediate Solution**: Use the **API endpoints** which are working correctly!

### Example Usage

```bash
# Get network stats
curl "https://explorer.d-bis.org/api/v2/stats"

# Get latest block number
curl "https://explorer.d-bis.org/api?module=block&action=eth_block_number"

# Get block 100
curl "https://explorer.d-bis.org/api?module=block&action=eth_get_block_by_number&tag=0x64&boolean=true"

# Get address balance
curl "https://explorer.d-bis.org/api?module=account&action=eth_get_balance&address=0x...&tag=latest"
```

---

## 📝 Quick Reference

### Minimum Required Parameters

**All API calls need**:
```
module=<MODULE_NAME>&action=<ACTION_NAME>
```

**Common Modules**:
- `module=block` - Block operations
- `module=transaction` - Transaction operations
- `module=account` - Address/account operations
- `module=token` - Token operations
- `module=stats` - Statistics (v2 API)

**Common Actions**:
- Block: `eth_block_number`, `eth_get_block_by_number`
- Transaction: `eth_getTransactionByHash`
- Account: `eth_get_balance`, `txlist`
- Token: `tokeninfo`, `tokenbalance`

---

## 🎯 Recommended Approach

### For Now: Use API Endpoints ✅

The API endpoints are **fully functional** and provide all the data you need:

1. **Network Stats**: `/api/v2/stats`
2. **Block Data**: `/api?module=block&action=...`
3. **Transaction Data**: `/api?module=transaction&action=...`
4. **Address Data**: `/api?module=account&action=...`

### For Web Interface: Wait or Investigate

1. **Wait**: The web interface may become available as more data is indexed
2. **Investigate**: Check if static assets need to be generated
3. **Monitor**: Watch logs for web interface initialization messages

---

## ✅ Summary

**What Works NOW**:
- ✅ API endpoints (with proper parameters)
- ✅ Block data retrieval
- ✅ Network statistics
- ✅ Indexing (115,954+ blocks)

**What's Not Working**:
- ⚠️ Web interface root path (returns 404)
- ⚠️ Web interface routes (may need more data/time)

**Solution**: **Use the API endpoints** - they're fully functional and provide all the data you need!

---

**Last Updated**: December 23, 2025

