Unleashing Onchain Insights: The Bankless MCP Server for Blockchain Data Mastery

Harness the power of AI-driven blockchain analysis with the Bankless Onchain MCP (Model Context Protocol) Server. This robust tool empowers Large Language Models (LLMs) to seamlessly interact with on-chain data, unlocking a new era of intelligent applications for the decentralized world.

Overview

The Bankless Onchain MCP Server acts as a bridge between LLMs and the vast landscape of blockchain data, leveraging the Bankless API to provide structured access to on-chain information. By implementing the Model Context Protocol (MCP), this server enables AI models to understand and analyze blockchain state and event data with unprecedented accuracy and efficiency.

Key Capabilities

This server offers a comprehensive suite of onchain data operations, categorized into contract, event, and transaction functionalities:

Contract Operations: Deep Dive into Smart Contract Logic

• read_contract: Execute read-only calls to smart contracts across various blockchain networks.
  • Use Case: Retrieve the current balance of a specific token holder, query contract parameters, or fetch on-chain governance data.
  • Parameters:
    • network (string): Target blockchain network (e.g., "ethereum", "polygon").
    • contract (string): Address of the smart contract.
    • method (string): Name of the contract method to invoke.
    • inputs (array): Input parameters for the method call, defined by type and value.
    • outputs (array): Expected output types, specifying the type of each return value.
  • Returns: An array of contract call results, with each result containing the value and type.
• get_proxy: Uncover the implementation address behind proxy contracts.
  • Use Case: Identify the underlying logic of upgradeable contracts, enabling accurate analysis of contract behavior.
  • Parameters:
    • network (string): Blockchain network.
    • contract (string): Address of the proxy contract.
  • Returns: The implementation contract address.
• get_abi: Obtain the Application Binary Interface (ABI) of a contract.
  • Use Case: Decode transaction data, understand contract functions, and dynamically interact with smart contracts.
  • Parameters:
    • network (string): Blockchain network.
    • contract (string): Address of the smart contract.
  • Returns: The contract ABI in JSON format.
• get_source: Retrieve the verified source code of a contract.
  • Use Case: Audit contract security, analyze contract logic, and gain a comprehensive understanding of contract functionality.
  • Parameters:
    • network (string): Blockchain network.
    • contract (string): Address of the smart contract.
  • Returns: Source code, ABI, compiler version, and other contract metadata.

Event Operations: Real-time Insights into Onchain Activity

• get_events: Fetch event logs for a contract based on specified topics.
  • Use Case: Track token transfers, monitor contract interactions, and analyze on-chain activity patterns.
  • Parameters:
    • network (string): Blockchain network.
    • addresses (array): List of contract addresses to filter events.
    • topic (string): Primary topic to filter events.
    • optionalTopics (array, optional): Optional additional topics (can include null values).
  • Returns: Filtered event logs matching the specified criteria.
• build_event_topic: Generate an event topic signature from the event name and argument types.
  • Use Case: Construct precise event filters for targeted data retrieval.
  • Parameters:
    • network (string): Blockchain network.
    • name (string): Event name (e.g., "Transfer(address,address,uint256)").
    • arguments (array): Event argument types, each defined by type.
  • Returns: The keccak256 hash of the event signature.

Transaction Operations: Unraveling Onchain History

• get_transaction_history: Retrieve the transaction history for a given user address.
  • Use Case: Track user activity, analyze transaction patterns, and identify potential security risks.
  • Parameters:
    • network (string): Blockchain network.
    • user address (string): User's blockchain address.
    • optional contract (string, optional): Contract address to filter transactions.
    • optional method ID (string, optional): Method ID to filter transactions.
    • optional start block (number, optional): Starting block number for the history.
    • include data flag (boolean): Flag to include transaction data.
  • Returns: A list of transactions with hash, data, network, and timestamp.
• get_transaction_info: Obtain detailed information about a specific transaction.
  • Use Case: Analyze transaction details, verify transaction status, and troubleshoot potential issues.
  • Parameters:
    • network (string): Blockchain network.
    • transaction hash (string): Hash of the transaction.
  • Returns: Transaction details including block number, timestamp, from/to addresses, value, gas info, status, and receipt data.

Installation

npm install @bankless/onchain-mcp

Getting Started

Prerequisites

• A Bankless API token is required. Obtain your token at https://docs.bankless.com/bankless-api/other-services/onchain-mcp.

Configuration

1. Set the Bankless API Token:

   export BANKLESS_API_TOKEN=your_api_token_here

Execution

1. Run the Server:

   npx @bankless/onchain-mcp

Integration with LLMs: Examples

The following examples demonstrate how to interact with the Bankless Onchain MCP Server using JSON payloads within an LLM environment.

read_contract Example

{
  "name": "read_contract",
  "arguments": {
    "network": "ethereum",
    "contract": "0xdAC17F958D2ee523a2206206994597C13D831ec7",
    "method": "balanceOf",
    "inputs": [
      { "type": "address", "value": "0x6B175474E89094C44Da98b954EedeAC495271d0F" }
    ],
    "outputs": [
      { "type": "uint256" }
    ]
  }
}

Expected Response:

[
  {
    "value": "1234567890",
    "type": "uint256"
  }
]

get_proxy Example

{
  "name": "get_proxy",
  "arguments": {
    "network": "ethereum",
    "contract": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48"
  }
}

Expected Response:

{
  "implementation": "0x596B0e021775e97e39a66c988473fa201a785367"
}

get_events Example

{
  "name": "get_events",
  "arguments": {
    "network": "ethereum",
    "addresses": ["0xdAC17F958D2ee523a2206206994597C13D831ec7"],
    "topic": "0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef",
    "optionalTopics": ["0x0000000000000000000000006b175474e89094c44da98b954eedeac495271d0f", null]
  }
}

Expected Response:

{
  "result": [
    {
      "removed": false,
      "logIndex": 123,
      "transactionIndex": 45,
      "transactionHash": "0x...",
      "blockHash": "0x...",
      "blockNumber": 1234567,
      "address": "0xdAC17F958D2ee523a2206206994597C13D831ec7",
      "data": "0x...",
      "topics": ["0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef", "0x...", "0x..."]
    }
  ]
}

build_event_topic Example

{
  "name": "build_event_topic",
  "arguments": {
    "network": "ethereum",
    "name": "Transfer(address,address,uint256)",
    "arguments": [
      { "type": "address" },
      { "type": "address" },
      { "type": "uint256" }
    ]
  }
}

Expected Response:

"0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef"

Development

Building from Source

git clone https://github.com/Bankless/onchain-mcp.git
cd onchain-mcp
npm install
npm run build

Debug Mode

npm run debug

Integrating with AI Applications

To integrate the Bankless Onchain MCP Server with AI applications that support MCP, configure your application's server settings as follows:

{
  "mcpServers": {
    "bankless": {
      "command": "npx",
      "args": [
        "@bankless/onchain-mcp"
      ],
      "env": {
        "BANKLESS_API_TOKEN": "your_api_token_here"
      }
    }
  }
}

Error Handling

The server provides specific error types to facilitate robust error management:

• BanklessValidationError: Indicates invalid input parameters.
• BanklessAuthenticationError: Signals issues with the API token.
• BanklessResourceNotFoundError: Denotes that the requested resource was not found.
• BanklessRateLimitError: Indicates that the API rate limit has been exceeded.

Optimizing LLM Interactions: Prompt Engineering

To effectively guide an LLM to utilize the Bankless Onchain MCP Server, consider incorporating the following elements into your prompts:

ROLE:
• You are Kompanion, a blockchain expert and EVM sleuth. 
• You specialize in navigating and analyzing smart contracts using your tools and resources.

HOW KOMPANION CAN HANDLE PROXY CONTRACTS:
• If a contract is a proxy, call your “get_proxy” tool to fetch the implementation contract.  
• If that fails, try calling the “implementation” method on the proxy contract.  
• If that also fails, try calling the “_implementation” function.  
• After obtaining the implementation address, call “get_contract_source” with that address to fetch its source code.  
• When reading or modifying the contract state, invoke implementation functions on the proxy contract address (not directly on the implementation).

HOW KOMPANION CAN HANDLE EVENTS:
• Get the ABI and Source of the relevant contracts
• From the event types in the ABI, construct the correct topics for the event relevant to the question
• use the "get_event_logs" tool to fetch logs for the contract

KOMPANION'S RULES:
• Do not begin any response with “Great,” “Certainly,” “Okay,” or “Sure.”  
• Maintain a direct, technical style. Do not add conversational flourishes.  
• If the user’s question is unrelated to smart contracts, do not fetch any contracts.  
• If you navigate contracts, explain each step in bullet points.  
• Solve tasks iteratively, breaking them into steps.  
• Use bullet points for lists of steps.  
• Never assume a contract’s functionality. Always verify with examples using your tools to read the contract state.  
• Before responding, consider which tools might help you gather better information.  
• Include as much relevant information as possible in your final answer, depending on your findings.

HOW KOMPANION CAN USE TOOLS:
• You can fetch contract source codes, ABIs, and read contract data by using your tools and functions.  
• Always verify the source or ABI to understand the contract rather than making assumptions.  
• If you need to read contract state, fetch its ABI (especially if the source is lengthy).  

FINAL INSTRUCTION:
• Provide the best possible, concise answer to the user’s request. If it's not an immediate question but an instruction, follow it directly.
• Use your tools to gather any necessary clarifications or data.  
• Offer a clear, direct response and add a summary of what you did (how you navigated the contracts) at the end.

By incorporating these guidelines, you can significantly enhance the LLM's ability to effectively utilize the Bankless Onchain MCP Server for blockchain data analysis.