Bankless Onchain Context Provider Service

Model Context Protocol (MCP) orchestration layer for accessing decentralized ledger data through the Bankless API gateway.

Conceptual Overview

The Bankless Onchain Context Provider Service establishes a programmatic foundation for engaging with immutable ledger data using the Bankless API endpoints. It rigorously implements the Model Context Protocol (MCP) specification, enabling sophisticated artificial intelligence agents to obtain structured access to the current blockchain state and historical event streams.

https://github.com/user-attachments/assets/95732dff-ae5f-45a6-928a-1ae17c0ddf9d

Operational Capabilities

This service exposes the following functionalities for retrieving ledger data:

Contract Interactions

• Retrieve State Variables (read_contract): Query the current value of specified variables within smart contracts across supported networks.

  • Arguments: network designation, target contract identifier, function signature, input payload configuration, expected output type specifications
  • Output: Contract execution outcomes with resolved, typified values

• Lookup Proxy Implementation (get_proxy): Discover the address of the underlying implementation contract associated with a proxy.

  • Arguments: network designation, proxy contract identifier
  • Output: The resolved implementation contract address

• Fetch Contract Schema (get_abi): Acquire the Application Binary Interface (ABI) definition for a contract.

  • Arguments: network designation, contract identifier
  • Output: Contract ABI serialized in JSON format

• Obtain Source Code (get_source): Retrieve the human-readable source code for a verified artifact.

  • Arguments: network designation, contract identifier
  • Output: Source code text, accompanying ABI, compiler version details, and supplementary metadata

Event Stream Analysis

• Query Log Emissions (get_events): Retrieve filtered streams of event logs emitted by contracts based on specified criteria.

  • Arguments: network designation, list of originating addresses, primary topic filter, supplementary topic filters (optional)
  • Output: A collection of matching event records

• Generate Topic Signature (build_event_topic): Compute the Keccak-256 hash signature for a defined event signature.

  • Arguments: network designation, canonical event signature string (e.g., 'Transfer(address,address,uint256)'), data types of event arguments
  • Output: The calculated event topic hash string

Transaction Tracing

• Fetch Transaction Ledger (get_transaction_history): Obtain a chronological sequence of transactions linked to a specific public key.

  • Arguments: network designation, account identifier, optional contract filter, optional method signature identifier, optional starting block number, flag to include raw data
  • Output: A list of transaction records detailing hash, payload, network context, and execution timestamp

• Examine Transaction Details (get_transaction_info): Secure granular metadata for an individual transaction record.

  • Arguments: network designation, transaction identification hash
  • Output: Comprehensive transaction metadata including block number, time of inclusion, sender/recipient addresses, value transferred, gas consumption statistics, success status, and receipt data

Available Toolsets

• read_contract

  • Execute a read-only query against a specific blockchain asset's state
  • Input Schema:
    • network (string, mandatory): The ledger environment (e.g., "ethereum", "polygon")
    • contract (string, mandatory): The asset's immutable address
    • method (string, mandatory): The contract function selector name
    • inputs (array, mandatory): Parameter values for the function call, structured as:
      • type (string): Data type descriptor (e.g., "address", "uint256")
      • value (any): The actual parameter payload
    • outputs (array, mandatory): Definition of expected return types, structured as:
      • type (string): The anticipated output data type descriptor
  • Returns an array containing the interpreted contract execution outputs

• get_proxy

  • Resolve the true implementation address linked to a proxy wrapper on a specified network
  • Input Schema:
    • network (string, mandatory): The ledger environment (e.g., "ethereum", "base")
    • contract (string, mandatory): The proxy asset's address
  • Returns the address pointing to the proxy's underlying logic module

• get_events

  • Retrieve transaction emissions matching specific filtering parameters for a given ledger
  • Input Schema:
    • network (string, mandatory): The ledger environment (e.g., "ethereum", "base")
    • addresses (array, mandatory): A list of source contract identifiers for log filtering
    • topic (string, mandatory): The primary event signature hash for filtering
    • optionalTopics (array, optional): Secondary topic filters (may contain null placeholders)
  • Returns an object encapsulating the retrieved, filtered log entries

• build_event_topic

  • Computes the standardized Keccak256 topic hash from an event's textual signature and argument types
  • Input Schema:
    • network (string, mandatory): The ledger environment (e.g., "ethereum", "base")
    • name (string, mandatory): The event's canonical signature, including types (e.g., "Transfer(address,address,uint256)")
    • arguments (array, mandatory): Sequential listing of argument data types, structured as:
      • type (string): The argument type descriptor (e.g., "address", "uint256")
  • Returns a string representing the calculated cryptographic hash value

Deployment Instructions

bash npm install @bankless/onchain-mcp

Operationalizing the Service

Pre-requisite Configuration

Ensure that your Bankless API access credential is set in the environment variables. Guidance on obtaining this credential is available at https://docs.bankless.com/bankless-api/other-services/onchain-mcp

bash export BANKLESS_API_TOKEN=your_api_token_here

Launching the Server

The service can be initialized directly via the command line interface:

bash npx @bankless/onchain-mcp

Integration with Autonomous Agents (Tools)

This server adheres to the Model Context Protocol (MCP) specification, permitting its incorporation as a utility provider for compliant AI agents. Below are illustrative invocation examples for each exposed function:

read_contract

javascript // Illustrative invocation { "name": "read_contract", "arguments": { "network": "ethereum", "contract": "0x1234...", "method": "balanceOf", "inputs": [ { "type": "address", "value": "0xabcd..." } ], "outputs": [ { "type": "uint256" } ] } }

// Illustrative response structure [ { "value": "1000000000000000000", "type": "uint256" } ]

get_proxy

javascript // Illustrative invocation { "name": "get_proxy", "arguments": { "network": "ethereum", "contract": "0x1234..." } }

// Illustrative response structure { "implementation": "0xefgh..." }

get_events

javascript // Illustrative invocation { "name": "get_events", "arguments": { "network": "ethereum", "addresses": ["0x1234..."], "topic": "0xabcd...", "optionalTopics": ["0xef01...", null] } }

// Illustrative response structure { "result": [ { "removed": false, "logIndex": 5, "transactionIndex": 2, "transactionHash": "0x123...", "blockHash": "0xabc...", "blockNumber": 12345678, "address": "0x1234...", "data": "0x...", "topics": ["0xabcd...", "0xef01...", "0x..."] } ] }

build_event_topic

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

// Illustrative response structure "0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef"

Source Code Development

Compiling from Source

bash

Obtain repository copy

git clone https://github.com/Bankless/onchain-mcp.git cd onchain-mcp

Install dependencies

npm install

Perform build process

npm run build

Debugging Mode

bash npm run debug

Interfacing with Intelligent Systems

To integrate this data service with AI applications that recognize the MCP standard, modify your application's configuration manifest as follows:

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

Error Classification

The service yields distinct error identifiers for various failure modes:

• BanklessValidationError: Indicates malformed input arguments provided to a function.
• BanklessAuthenticationError: Signifies issues related to the API access credential.
• BanklessResourceNotFoundError: Denotes that the requested ledger entity does not exist.
• BanklessRateLimitError: Signals that the configured quota for API requests has been surpassed.

Agent Guidance Prompts

To optimize the utilization of the Bankless Onchain Context Provider Service by a Language Model Agent, employ directive language such as the following:

ROLE: • You are 'EVM Sentinel,' an authoritative analyst specializing in decentralized ledger forensics and smart contract examination, utilizing provided instrumentation. • Your core competency is navigating and interpreting on-chain artifacts via your integrated utilities.

HOW EVM SENTINEL HANDLES PROXY ARTIFACTS: • If a contract address is identified as a proxy mechanism, initiate a call to your “get_proxy” utility to ascertain the true implementation address. • If the direct proxy lookup fails, attempt to invoke the "implementation" function signature against the proxy address. • Should that also fail, probe for the internal, often private, function signature "_implementation". • Upon successful acquisition of the implementation identifier, subsequently invoke the 'get_source' utility targeting that implementation address to retrieve its source structure. • Crucially, when executing read operations or state modifications, direct all calls toward the original proxy identifier, not the resolved implementation address.

HOW EVM SENTINEL HANDLES EVENT LOGS: • Secure the ABI and source code for all pertinent contracts. • Based on the event definitions present in the ABI, construct the exact topic filters required for the event under investigation. • Employ the "get_events" utility to procure logs matching the constructed criteria for the relevant contract(s).

EVM SENTINEL OPERATIONAL DIRECTIVES: • Never commence any output with affirmative conversational openers such as “Affirmative,” “Indeed,” “Understood,” or “Pleased to.” • Maintain a strictly technical, concise communication modality; eliminate extraneous conversational padding. • If the user inquiry pertains to subjects outside the scope of smart contracts or ledger data, refrain entirely from tool invocation. • When tracing contract interactions, document every investigative step taken using enumerated lists. • Resolve complex tasks through iterative decomposition into discrete, manageable sub-steps. • Utilize bullet points extensively when presenting procedural sequences. • Never presume contract behavior. Verification via utility calls that read state or source is mandatory for all functional assumptions. • Prior to formulating a final response, dedicate a moment to evaluate which available utilities can yield superior supporting intelligence. • Incorporate the maximum relevant analytical data derived from utility execution into the final summary.

HOW EVM SENTINEL UTILIZES INSTRUMENTS: • You are authorized to fetch contract source artifacts, interface definitions (ABIs), and query contract runtime data through your designated utilities. • Prioritize the inspection of source or ABI data over relying on prior knowledge or assumptions about contract functionality. • If a state query is necessitated, retrieve the contract's ABI first (especially if the source code is extensive).

FINAL MANDATE: • Deliver the most accurate and maximally concise solution to the user's directive. If the input is an operational command rather than a question, execute the command directly. • Leverage your toolset to resolve all ambiguities or gather required contextual data. • Present a clear, unambiguous conclusion, followed by a concluding synopsis detailing the path taken through contract investigation.

Licensing Information

MIT

WIKIPEDIA: XMLHttpRequest (XHR) is an Application Programming Interface implemented as a JavaScript construct. Its methods facilitate the transmission of Hypertext Transfer Protocol (HTTP) queries originating from a web browser environment to a designated web server. These methods empower browser-based software components to dispatch requests to the backend persistence layer subsequent to initial page rendering, and subsequently receive data payload back. XMLHttpRequest forms a fundamental pillar of Asynchronous JavaScript and XML (Ajax) methodologies. Before the widespread adoption of Ajax, traditional mechanisms for server communication relied predominantly upon navigational hyperlinks and form submissions, actions that typically mandated a complete page refresh to present new content.

== Chronology == The conceptual underpinning for XMLHttpRequest was formulated in the year 2000 by the development team responsible for Microsoft Outlook. This concept was subsequently realized within the Internet Explorer 5 browser iteration (released in 1999). However, the initial syntactic structure did not utilize the standardized XMLHttpRequest identifier. Developers instead employed object instantiations such as ActiveXObject("Msxml2.XMLHTTP") and ActiveXObject("Microsoft.XMLHTTP"). By the release of Internet Explorer 7 (2006), standardized support for the XMLHttpRequest identifier became universal across all major browser platforms. The XMLHttpRequest identifier has since solidified its position as the dominant convention across all leading browser engines, including Mozilla's Gecko rendering engine (since 2002), Apple's Safari 1.2 (since 2004), and Opera 8.0 (since 2005).

=== Standardization Efforts === The World Wide Web Consortium (W3C) formally published a Working Draft specification detailing the XMLHttpRequest object on April 5, 2006. On February 25, 2008, the W3C advanced this to the Level 2 specification Working Draft. This Level 2 iteration introduced enhanced capabilities, specifically methods for monitoring transmission progress events, enabling cross-origin resource sharing (CORS) requests, and facilitating the processing of raw byte streams. Towards the close of 2011, the features defined in the Level 2 specification were integrated back into the foundational specification. At the conclusion of 2012, stewardship for the document's maintenance transitioned to the WHATWG group, which sustains a continuously evolving document leveraging the Web Interface Definition Language (Web IDL).

== Operational Mechanics == Generally, invoking a request using XMLHttpRequest necessitates adherence to several sequential programming stages.

1. Object instantiation: Create an XMLHttpRequest entity by invoking its constructor function.
2. Connection specification: Invoke the "open" method to define the transmission protocol (request method), designate the target resource Uniform Resource Identifier (URI), and specify the execution mode (synchronous or asynchronous).
3. Asynchronous listener configuration: For asynchronous operation, register a callback function to be invoked upon changes in the request's state transition lifecycle.
4. Request initiation: Trigger the actual data transfer by executing the "send" method.
5. State transition handling: Monitor events within the registered listener. Upon successful data reception from the server, the payload is typically stored within the "responseText" property by default. When the object completes its processing lifecycle, it transitions to state 4, designated as the "done" state. Beyond these fundamental steps, XMLHttpRequest provides extensive configuration points to govern request transmission parameters and response processing methodology. Custom header fields can be appended to the outgoing request to convey specific server instructions. Data can be uploaded to the server by provisioning it as an argument within the "send" invocation. The resulting server response can be interpreted directly from JSON formatting into an immediately usable JavaScript object structure, or it can be processed incrementally as the data stream arrives, bypassing the need to wait for complete buffer saturation. Furthermore, the request can be terminated prematurely or configured to automatically fail if a defined time limit is surpassed.

== Inter-domain Communication ==

During the nascent phases of the World Wide Web's evolution, observations indicated the possibility of breaching s