What is 1scan

1scan is a unified API gateway designed to integrate multiple etherscan-like blockchain explorer APIs, providing support for the Model Context Protocol (MCP) to facilitate AI assistants in querying blockchain data.

Use cases

Use cases for 1scan include building AI assistants that provide real-time blockchain data, developing analytics tools for DeFi projects, and integrating blockchain data queries into applications for enhanced user experience.

How to use

To use 1scan, developers need to apply for an API key from the respective blockchain explorer. Once they have the key, they can access the unified API gateway to query blockchain data through the MCP server.

Key features

Key features of 1scan include a unified endpoint for accessing various blockchain explorer APIs, direct querying capabilities for AI models, and support for multiple blockchain networks such as Ethereum, Binance Smart Chain, and Polygon.

Where to use

1scan can be used in various fields including decentralized finance (DeFi), blockchain analytics, and AI-driven applications that require real-time access to blockchain data.

1scan - Blockchain Explorer API Gateway & MCP Server

A unified API gateway for integrating multiple etherscan-like blockchain explorer APIs with Model Context Protocol (MCP) support for AI assistants.

Overview

1scan provides two main components:

1. API Gateway: A unified endpoint for accessing multiple blockchain explorer APIs
2. MCP Server: Allows AI models (like Claude in Cursor IDE) to directly query blockchain data

Supported Blockchain Networks

Apply for your own API key from the corresponding blockchain explorer

Features

• 🔄 Unified API endpoint for multiple blockchain explorers
• ⚖️ API load balancing
• 🔑 API rate limit management
• 🎯 Custom API key support via URL parameters
• 🤖 MCP server for AI assistants to query blockchain data

Installation

From Go

go install github.com/huahuayu/1scan@latest

From Source

# Clone the repository
git clone https://github.com/huahuayu/1scan.git
cd 1scan

# Build both 1scan API server and MCP server
make build

Quick Start

1. Create Configuration File

Create a config.json file with your API keys:

{
  "1": {
    "endpoint": "api.etherscan.io",
    "keys": {
      "YOUR_ETHERSCAN_API_KEY_1": 5,
      "YOUR_ETHERSCAN_API_KEY_2": 10
    }
  },
  "56": {
    "endpoint": "api.bscscan.com",
    "keys": {
      "YOUR_BSCSCAN_API_KEY": 5
    }
  }
}

Each chain entry contains:

• chainID: The blockchain network ID
• endpoint: The API endpoint for the blockchain explorer
• keys: Map of API keys and their rate limits (requests per second)

2. Run the API Server

# Run with default settings
1scan -config /path/to/config.json

# Or using make
make run-1scan

3. Run the MCP Server

# Run with default settings
1scanmcp -config /path/to/config.json # default serve at port 3000

# Or using make
make run-1scanmcp

# With custom settings
1scanmcp -config /path/to/config.json -port 3000 -path /mcp

Integrating with Cursor IDE

To use 1scan MCP in Cursor IDE:

1. Start both the API server and MCP server

   # Terminal 1
   make run-1scan
   
   # Terminal 2
   make run-1scanmcp
   

2. In Cursor IDE, go to Settings → AI → MCP Servers

3. Add a new MCP server with the URL:

{
  "mcpServers": {
    "1scan": {
      "url": "http://localhost:3000/mcp/sse"
    }
  }
}

4. Restart Cursor IDE if necessary

5. Now you can use blockchain data in your AI conversations:

   Can you check the balance of address 0x742d35Cc6634C0532925a3b844Bc454e4438f44e on Ethereum?
   

MCP Server Configuration

When running the MCP server, you can customize it with these parameters:

• -port: Port to run the MCP server on (default: “3000”)
• -path: Path for the MCP server endpoint (default: “/mcp”)
• -config: Path to configuration file (default: “config.json”)
• -transport: Transport type (sse or stdio) (default: “sse”)

Example:

1scanmcp -port 3000 -config /path/to/config.json

Available MCP Tools

The MCP server exposes these tools to AI models:

• getAccountBalance - Get the balance of an account on a specific blockchain
• getTokenBalance - Get the token balance of an account on a specific blockchain
• getTransactionByHash - Get transaction details by hash
• getBlockByNumber - Get block information by block number
• getContractABI - Get the ABI for a verified contract
• getContractSourceCode - Get the source code of a verified contract
• getTokenInfo - Get information about an ERC20 token
• getGasPrice - Get current gas price on a specific blockchain
• getLogs - Get event logs matching specified parameters
• getTransaction - Get details of a transaction by its hash
• getTransactionCount - Get the number of transactions sent from an address
• getTransactionReceipt - Get transaction receipt by transaction hash
• getBlockTransactionCountByNumber - Get the number of transactions in a block
• getBlockTransactionCountByHash - Get the number of transactions in a block by block hash
• getBlockByHash - Get information about a block by its hash
• getNormalTransactions - Get normal transactions by address
• getInternalTransactions - Get internal transactions by address or transaction hash
• getERC20Transfers - Get ERC-20 token transfer events by address or contract
• getERC721Transfers - Get ERC-721 NFT transfer events by address or contract
• getValidators - Get validator information (for networks with validator sets)
• getContractCreation - Get contract creation information
• getContractVerificationStatus - Check contract verification status

Example MCP Interactions

Here are examples of how to interact with blockchain data through the MCP interface:

# Get account balance
What's the ETH balance of vitalik.eth (0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045) on Ethereum?

# Check a token balance
What's the USDC balance of address 0x28C6c06298d514Db089934071355E5743bf21d60 on Ethereum?

# Examine a transaction
Can you analyze transaction 0xdd6d7f687c9821404ae8c2ea7de5cfb5a23fc4c01ef1e7f535748cb147aa76dd on Ethereum?

# Look up block information
What transactions were in Ethereum block 18700000?

# Get contract ABI
Can you show me the ABI for the USDC contract (0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48) on Ethereum?

# Analyze contract source code
I need to understand how the Uniswap V3 router works. Can you show me the source code for 0xE592427A0AEce92De3Edee1F18E0157C05861564 on Ethereum?

# Check multiple chains
What's the difference in gas fees between Ethereum and Arbitrum right now?

# Examine token information
Tell me about the tokenomics of the APE token on Ethereum.

Complete List of MCP Tools

The MCP server exposes these tools to AI models:

• getAccountBalance - Get the balance of an account on a specific blockchain
• getTokenBalance - Get the token balance of an account on a specific blockchain
• getTransactionByHash - Get transaction details by hash
• getBlockByNumber - Get block information by block number
• getContractABI - Get the ABI for a verified contract
• getContractSourceCode - Get the source code of a verified contract
• getTokenInfo - Get information about an ERC20 token
• getGasPrice - Get current gas price on a specific blockchain
• getLogs - Get event logs matching specified parameters
• getTransaction - Get details of a transaction by its hash
• getTransactionCount - Get the number of transactions sent from an address
• getTransactionReceipt - Get transaction receipt by transaction hash
• getBlockTransactionCountByNumber - Get the number of transactions in a block
• getBlockTransactionCountByHash - Get the number of transactions in a block by block hash
• getBlockByHash - Get information about a block by its hash
• getNormalTransactions - Get normal transactions by address
• getInternalTransactions - Get internal transactions by address or transaction hash
• getERC20Transfers - Get ERC-20 token transfer events by address or contract
• getERC721Transfers - Get ERC-721 NFT transfer events by address or contract
• getValidators - Get validator information (for networks with validator sets)
• getContractCreation - Get contract creation information
• getContractVerificationStatus - Check contract verification status

Troubleshooting MCP Integration

If you encounter issues connecting to the MCP server from Cursor:

1. Verify both servers are running:

   # Check if servers are running
   ps aux | grep 1scanmcp
   

2. Ensure the correct URL is configured in Cursor

License

MIT License