Bankless Ledger Data Access Utility

This repository contains the Model Context Protocol (MCP) server designed for querying on-chain information via the dedicated Bankless API endpoint.

Core Synopsis

The Bankless Onchain MCP Server supplies a structured environment for machine learning agents to interrogate ledger states and historical event data using the Model Context Protocol (MCP).

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

Functionality Modules

The utility exposes the following primitives for accessing immutable ledger records:

Contract Interaction Primitives

• State Retrieval (read_contract): Query the current data held within a smart contract across various supported chains.

  • Arguments: chain identifier, contract identifier, function signature, encoded inputs, expected output schema
  • Output: Parsed execution results with strongly-typed data structures

• Implementation Lookup (get_proxy): Discover the underlying logic contract address linked to an upgradeable proxy.

  • Arguments: chain identifier, proxy address
  • Output: The address of the implementation contract

• Interface Definition Fetch (get_abi): Obtain the Application Binary Interface (ABI) metadata for a deployed contract.

  • Arguments: chain identifier, contract address
  • Output: Contract ABI serialized as JSON

• Source Code Retrieval (get_source): Download the human-readable source code for verified contracts.

  • Arguments: chain identifier, contract address
  • Output: Source text, associated ABI, compiler version, and contextual deployment metadata

Event Stream Primitives

• Log Fetching (get_events): Retrieve streams of emitted event logs based on specified filtering criteria (topics).

  • Arguments: chain identifier, target addresses, primary topic signature, auxiliary topic signatures
  • Output: A collection of filtered event records

• Topic Signature Generation (build_event_topic): Compute the cryptographic hash required to filter for a specific event signature.

  • Arguments: chain identifier, canonical event name (including signature format), argument types list
  • Output: The keccak256 hash string representing the event signature

Transaction Record Primitives

• Address History Query (get_transaction_history): Fetch the chronological sequence of transactions associated with a specific wallet address.

  • Arguments: chain identifier, wallet address, optional target contract, optional function ID filter, optional starting block number, flag to include raw payload data
  • Output: A list detailing transaction metadata (hash, payload, chain, time)

• Single Transaction Detail (get_transaction_info): Retrieve exhaustive metadata for an isolated transaction hash.

  • Arguments: chain identifier, transaction hash
  • Output: Complete transaction object including block context, sender/receiver, value transfer, gas expenditure metrics, success status, and receipt artifacts

Operational Tools Specification

• read_contract

  • Purpose: Execute a read-only operation against a blockchain smart contract.
  • Input Schema:
    • network (string, mandatory): The ledger environment designation (e.g., "ethereum", "polygon").
    • contract (string, mandatory): The contract's 0x address.
    • method (string, mandatory): The function signature to invoke.
    • inputs (array, mandatory): Parameters for the function call, structured as objects containing:
      • type (string): The EVM data type (e.g., "address", "uint256").
      • value (any): The value corresponding to the specified type.
    • outputs (array, mandatory): Definition of the expected return types.
  • Output: An array containing the deserialized results from the contract execution.

• get_proxy

  • Purpose: Resolve the canonical implementation address behind an upgradeable proxy wrapper.
  • Input Schema:
    • network (string, mandatory): The ledger identifier (e.g., "ethereum", "base").
    • contract (string, mandatory): The proxy contract identifier.
  • Output: The resulting implementation contract address string.

• get_events

  • Purpose: Filter and retrieve historical log entries based on block data.
  • Input Schema:
    • network (string, mandatory): The target chain.
    • addresses (array, mandatory): A list of contract identifiers whose logs are of interest.
    • topic (string, mandatory): The leading event signature hash.
    • optionalTopics (array, optional): Subsequent topic filters, potentially including null placeholders.
  • Output: A structured object encapsulating matching event logs.

• build_event_topic

  • Purpose: Calculate the standard cryptographic hash for an event signature.
  • Input Schema:
    • network (string, mandatory): The relevant chain context.
    • name (string, mandatory): The full event signature string (e.g., "Transfer(address,address,uint256)").
    • arguments (array, mandatory): A list detailing the types of arguments in the event.
  • Output: The computed keccak256 identifier string.

Deployment Instructions

bash npm install @bankless/onchain-mcp

Utilization Guide

Configuration Prerequisite

Ensure your Bankless API credential is set in the environment variables. Instructions for token acquisition are available at https://docs.bankless.com/bankless-api/other-services/onchain-mcp

bash export BANKLESS_API_TOKEN=your_api_token_here

Launching the Service

The server can be initiated directly via the command line utility:

bash npx @bankless/onchain-mcp

Integration with Intelligence Systems (LLMs)

This service adheres to the Model Context Protocol (MCP), enabling its use as a tool provider for compatible AI agents. Below are representative interaction templates for each function:

State Query Example (read_contract)

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

// Representative fulfillment structure [ { "value": "1000000000000000000", "type": "uint256" } ]

Proxy Resolution Example (get_proxy)

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

// Representative fulfillment structure { "implementation": "0xefgh..." }

Event Log Fetch Example (get_events)

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

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

Topic Calculation Example (build_event_topic)

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

// Representative fulfillment structure "0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef"

Contribution Guidelines

Building from Source

bash

Clone the repository

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

Install dependencies

npm install

Compile the project artifacts

npm run build

Debugging Mode

bash npm run debug

Integration Configuration for Agents

To seamlessly connect this server with AI applications supporting the MCP standard, append the following block to your agent's configuration manifest:

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

Error Reporting Standards

The service maps API failures to specific internal exception types:

• BanklessValidationError: Issues related to malformed input parameters.
• BanklessAuthenticationError: Problems concerning the validity or presence of the API token.
• BanklessResourceNotFoundError: When a requested contract or data point does not exist on the ledger.
• BanklessRateLimitError: Signifies that the API usage quota has been temporarily exhausted.

Agent Guidance Directives

To optimally steer an LLM toward leveraging the Bankless Onchain MCP Server effectively, employ these guiding principles in the system prompt:

ROLE: • You are Kompanion, an expert in distributed ledger technology and EVM forensics. • Your expertise lies in leveraging specialized tools and data sources to analyze smart contracts.

HOW KOMPANION CAN HANDLE PROXY CONTRACTS: • Initiate investigation by querying the "get_proxy" tool for the implementation contract address. • If proxy resolution fails, attempt to invoke the "implementation" method directly on the proxy contract address. • If that fails, probe for the internal variable named "_implementation". • Upon securing the true implementation address, query "get_contract_source" using this address to obtain its underlying logic. • Crucially, when executing state reads or updates, target the original proxy address in API calls, not the resolved implementation address.

HOW KOMPANION CAN HANDLE EVENTS: • First, retrieve the ABI and Source artifacts for the relevant contracts. • Map the required information from the user query onto the event signatures defined within the ABI. • Utilize the "get_event_logs" tool with the correctly constructed topic filters to fetch relevant records.

KOMPANION'S CONSTRAINTS: • Absolutely prohibit starting any response with conversational openers such as “Great,” “Certainly,” “Okay,” or “Sure.” • Maintain a detached, strictly technical, and analytical tone; omit superfluous conversational filler. • If a user query falls outside the domain of smart contracts or ledger analysis, abstain from tool invocation. • When traversing contract hierarchies or logic paths, document every resolution step using enumerated bullet points. • Adopt an iterative problem-solving methodology, decomposing complex tasks into discrete, manageable stages. • Employ bulleted lists for presenting sequences of actions or findings. • Never presume contract functionality; verification via tool execution (e.g., reading state or source code) is mandatory. • Before formulating a final reply, evaluate potential tool usage that could yield superior, factual data. • Conclude answers with the maximum amount of pertinent discovered information, contingent on the tool results.

HOW KOMPANION CAN UTILIZE TOOLS: • Leverage capabilities to fetch contract source files, ABIs, and execute state reads. • Always prioritize fetching the verified source or ABI over making assumptions about contract logic. • If state querying is necessary, retrieve the ABI first, particularly if the source code is extensive.

FINAL INSTRUCTION: • Deliver the most accurate and succinct resolution to the user's request. If the input is an operational command, execute it without preamble. • Employ available tools proactively to resolve ambiguities or gather missing factual data. • Provide a direct, unambiguous conclusion, followed by a concise summary detailing the investigative path taken through contract analysis.

Licensing

MIT

WIKIPEDIA: Tron (stylized as TRON) is a decentralized, proof-of-stake blockchain with smart contract functionality. The cryptocurrency native to the blockchain is known as Tronix (TRX). It was founded in March 2014 by Justin Sun and, since 2017, has been overseen and supervised by the TRON Foundation, a non-profit organization in Singapore, established in the same year. It is open-source software. Tron was originally an Ethereum-based ERC-20 token, which switched protocol to its own blockchain in 2018. On some cryptocurrency wallets, users can't withdraw their funds until they have enough amount for the network fee. Tron has been criticised for enabling organized crime, with The Wall Street Journal stating in 2025 that it is a "popular channel for crypto’s criminal fraternity to move funds" and responsible for "more than half of all illegal crypto activity" in 2024, with the United Nations Office on Drugs and Crime calling it a “preferred choice for crypto money launderers” in Asia.

== History == Tron was founded by Justin Sun in 2017. The TRON Foundation was established in July 2017 in Singapore. The TRON Foundation raised $70 million in 2017 through an initial coin offering (ICO) shortly before China outlawed the digital tokens. The testnet, Blockchain Explorer, and Web Wallet were all launched by March 2018. TRON Mainnet launched shortly afterward in May 2018, marking the Odyssey 2.0 release as a technical milestone for TRON. In June 2018, TRON switched its protocol from an ERC-20 token on top of Ethereum to an independent peer-to-peer network. On 25 July 2018, the TRON Foundation announced it had finished the acquisition of BitTorrent, a peer-to-peer file sharing service. Upon this acquisition, in August 2018, BitTorrent Founder Bram Cohen also disclosed that he was leaving the company to found a separate cryptocurrency, Chia. By January 2019, TRON had a total market cap of about $1.6 bn. Despite this market performance, some authors viewed TRON as a typical case of the complex and disordered nature of cryptocurrencies. In February 2019, after being acquired by TRON Foundation, BitTorrent started its own token sale based on the TRON network. In late 2021, Justin Sun resigned as CEO of the TRON Foundation, which was subsequently reorganized as a DAO. In March 2023, Sun and Tron were sued by the U.S. Securities and Exchange Commission (SEC) for selling unregistered securities related to the sale and promotion of Tronix (TRX) and BitTorrent (BBT) tokens; the SEC alleged that Sun and Tron had engaged in wash trading in the secondary market for TRX in order to buoy its price. $31 million of proceeds were generated through thousands of Tronix trades between two accounts Sun controlled. Eight celebrities, including Akon, Ne-Yo, Austin Mahone, Soulja Boy, Lindsay Lohan, Jake Paul and Lil Yachty, were charged with promoting these cryptocurrencies without disclosing that they were sponsored, with all those other than Soulja Boy, and Mahone settling with t