smom-dbis-138/docs/api/BLOCKSCOUT_API.md

# Blockscout API Documentation

API endpoints for Blockscout explorer on ChainID 138.

## Base URL

```
https://explorer.d-bis.org
```

## API Endpoints

### Token Metadata

#### Get Token Information

```
GET /api/v2/tokens/{address}
```

**Parameters**:
- `address` (path): Token contract address

**Response**:
```json
{
  "address": "0x...",
  "name": "Wrapped Ether",
  "symbol": "WETH",
  "decimals": 18,
  "total_supply": "1000000000000000000000",
  "holders_count": 100,
  "transactions_count": 1000
}
```

#### Get Token Holders

```
GET /api/v2/tokens/{address}/holders
```

**Parameters**:
- `address` (path): Token contract address
- `page` (query): Page number (default: 1)
- `offset` (query): Items per page (default: 50)

**Response**:
```json
{
  "items": [
    {
      "address": "0x...",
      "value": "100000000000000000000",
      "token": {
        "address": "0x...",
        "symbol": "WETH",
        "decimals": 18
      }
    }
  ],
  "next_page_path": "/api/v2/tokens/{address}/holders?page=2"
}
```

#### Get Token Transfers

```
GET /api/v2/tokens/{address}/transfers
```

**Parameters**:
- `address` (path): Token contract address
- `page` (query): Page number (default: 1)
- `offset` (query): Items per page (default: 50)

**Response**:
```json
{
  "items": [
    {
      "from": {
        "hash": "0x...",
        "name": null
      },
      "to": {
        "hash": "0x...",
        "name": null
      },
      "total": {
        "value": "100000000000000000000",
        "token": {
          "address": "0x...",
          "symbol": "WETH",
          "decimals": 18
        }
      },
      "tx_hash": "0x...",
      "timestamp": "2024-12-19T00:00:00Z"
    }
  ],
  "next_page_path": "/api/v2/tokens/{address}/transfers?page=2"
}
```

### Account Information

#### Get Account Balance

```
GET /api/v2/addresses/{address}
```

**Parameters**:
- `address` (path): Account address

**Response**:
```json
{
  "hash": "0x...",
  "balance": "1000000000000000000000",
  "tx_count": 100,
  "token_count": 10
}
```

#### Get Account Tokens

```
GET /api/v2/addresses/{address}/token-balances
```

**Parameters**:
- `address` (path): Account address
- `page` (query): Page number (default: 1)
- `offset` (query): Items per page (default: 50)

**Response**:
```json
{
  "items": [
    {
      "address": "0x...",
      "value": "100000000000000000000",
      "token": {
        "address": "0x...",
        "name": "Wrapped Ether",
        "symbol": "WETH",
        "decimals": 18,
        "logo_url": "https://explorer.d-bis.org/images/tokens/weth.png"
      }
    }
  ],
  "next_page_path": "/api/v2/addresses/{address}/token-balances?page=2"
}
```

### Contract Verification

#### Get Contract Source Code

```
GET /api/v2/smart-contracts/{address}
```

**Parameters**:
- `address` (path): Contract address

**Response**:
```json
{
  "address": "0x...",
  "name": "WETH",
  "compiler_version": "0.8.19",
  "optimization": true,
  "source_code": "// SPDX-License-Identifier: MIT\n...",
  "abi": [...],
  "verified": true
}
```

## CORS Configuration

Blockscout must allow CORS requests from:

- `https://portfolio.metamask.io` (MetaMask Portfolio)
- `https://metamask.io` (MetaMask website)
- `https://chainlist.org` (Chainlist)

### CORS Headers

```
Access-Control-Allow-Origin: https://portfolio.metamask.io
Access-Control-Allow-Methods: GET, OPTIONS
Access-Control-Allow-Headers: Content-Type
Access-Control-Max-Age: 3600
```

## Rate Limiting

### Limits

- **Default**: 120 requests/minute per IP
- **API Keys**: Higher limits for API key holders
- **Public**: Lower limits for public access

### Headers

```
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 100
X-RateLimit-Reset: 1638360000
```

## Token Logo Serving

### Logo URL Format

```
https://explorer.d-bis.org/images/tokens/{address}.png
```

### Fallback

If token logo is not found, use default token logo or logo from token list.

### Supported Formats

- PNG (preferred)
- SVG
- JPEG

### Size Requirements

- **Recommended**: 512x512 pixels
- **Minimum**: 128x128 pixels
- **Maximum**: 1024x1024 pixels

## MetaMask Portfolio Integration

### Required Endpoints

For MetaMask Portfolio to display tokens:

1. **Token Metadata**: `/api/v2/tokens/{address}`
2. **Token Holders**: `/api/v2/tokens/{address}/holders`
3. **Account Tokens**: `/api/v2/addresses/{address}/token-balances`
4. **Token Transfers**: `/api/v2/tokens/{address}/transfers`

### CORS Requirements

Blockscout must allow CORS from Portfolio domain.

### Token List Integration

Portfolio uses token lists for auto-detection. Ensure token metadata matches token list entries.

## Error Handling

### Error Responses

```json
{
  "error": "Error message",
  "status": 400
}
```

### Common Errors

- **400 Bad Request**: Invalid parameters
- **404 Not Found**: Resource not found
- **429 Too Many Requests**: Rate limit exceeded
- **500 Internal Server Error**: Server error

## Examples

### Get WETH Token Information

```bash
curl https://explorer.d-bis.org/api/v2/tokens/0xYourWETHAddress
```

### Get Account Token Balances

```bash
curl https://explorer.d-bis.org/api/v2/addresses/0xYourAddress/token-balances
```

### Get Token Holders

```bash
curl https://explorer.d-bis.org/api/v2/tokens/0xYourTokenAddress/holders
```

## References

- [Blockscout API Documentation](https://docs.blockscout.com/for-developers/api)
- [Blockscout GitHub](https://github.com/blockscout/blockscout)