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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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

{
  "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

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

Get Account Token Balances

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

Get Token Holders

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

References

• Blockscout API Documentation
• Blockscout GitHub