Hermes Blockchain Oracle: On-Chain Solana Data for Hermes Agent

How It Works

Both sources describe the architecture in detail. The Model Context Protocol (MCP) is a standardized interface that allows LLM agents to discover and invoke external tools. The integration follows a five-step flow:

1. Registration. When Hermes Agent starts with --mcp blockchain=hermes-blockchain-oracle, the oracle registers its seven tools with the agent, including full JSON schemas describing each tool's parameters and return types.

2. Discovery. Hermes Agent understands what tools are available and what they can do. When a user asks a blockchain-related question, the LLM autonomously decides which tool or tools to call.

3. Invocation. The agent constructs a structured tool call (for example, solana_wallet_info(address="GsBd49...")) and sends it to the oracle server via the MCP transport layer.

4. Execution. The oracle queries the Solana RPC, processes the raw data, and returns a structured response.

5. Synthesis. Hermes Agent incorporates the on-chain data into a natural language response for the user.

The architecture diagram from the README shows the full stack:

┌─────────────────────────────────────────────────────────┐
│                      USER                               │
│              "Check this wallet..."                     │
└──────────────────────┬──────────────────────────────────┘
                       │
                       ▼
┌─────────────────────────────────────────────────────────┐
│                  HERMES AGENT                           │
│           (Nous Research LLM Runtime)                   │
│                                                         │
│   ┌─────────────────────────────────────────────────┐   │
│   │         Model Context Protocol (MCP)            │   │
│   │     Tool Discovery · Schema Negotiation         │   │
│   │      Request Routing · Response Formatting      │   │
│   └──────────────────────┬──────────────────────────┘   │
└──────────────────────────┼──────────────────────────────┘
                           │
                           ▼
┌─────────────────────────────────────────────────────────┐
│            HERMES BLOCKCHAIN ORACLE                     │
│              (This MCP Server)                          │
│                                                         │
│   ┌───────────┐ ┌───────────┐ ┌───────────────────┐    │
│   │  Wallet   │ │   Token   │ │   Transaction     │    │
│   │  Tools    │ │   Tools   │ │   Tools           │    │
│   └─────┬─────┘ └─────┬─────┘ └────────┬──────────┘    │
│   ┌─────┴─────┐ ┌─────┴─────┐ ┌────────┴──────────┐    │
│   │   NFT     │ │   Whale   │ │   Network         │    │
│   │   Tools   │ │  Detector │ │   Stats           │    │
│   └─────┬─────┘ └─────┬─────┘ └────────┬──────────┘    │
│         └──────────────┼────────────────┘               │
└────────────────────────┼────────────────────────────────┘
                         │
                         ▼
┌─────────────────────────────────────────────────────────┐
│               SOLANA BLOCKCHAIN                         │
│     RPC Nodes · Mainnet-Beta · On-Chain Programs        │
└─────────────────────────────────────────────────────────┘

The documentation emphasizes that this architecture makes the oracle stateless, composable, and independently deployable. You can upgrade the oracle without touching the agent, or swap in a different blockchain oracle entirely.

Requirements and Limitations

Based on the sources, the following requirements and limitations apply:

• Python version. The badge in the README indicates Python 3.10+ is required.
• Solana mainnet-beta. The default RPC endpoint points to mainnet-beta. The sources do not mention devnet or testnet support, though you could point SOLANA_RPC_URL at a different endpoint at your own risk.
• Network access. The oracle must have outbound access to a Solana RPC node. Without internet connectivity to an RPC endpoint, the tools will fail.
• Rate limits. The public Solana RPC endpoint has rate limits. For production use, the documentation recommends a dedicated RPC provider.
• Whale detection is real-time but polling-based. The whale detector checks for large transfers in real-time, but the exact polling mechanism is not detailed in the sources. The CACHE_TTL_SECONDS setting of 30 seconds suggests a polling interval or cache refresh cycle.
• No multi-chain support. The oracle is Solana-only. The sources do not mention any other blockchain.
• Experimental status. The project is licensed under MIT and carries no warranty. The README invites contributions for bug fixes and new tools, implying it is under active development.

Troubleshooting

The sources do not document specific failure modes or error messages. However, based on the configuration and architecture described, you can infer common issues and their fixes:

• RPC connection failure. If the oracle cannot reach the Solana RPC node, all tools will fail. Verify that SOLANA_RPC_URL is set correctly and that the endpoint is reachable from your network. Test with curl: curl -X POST -H "Content-Type: application/json" -d '{"jsonrpc":"2.0","id":1,"method":"getHealth"}' $SOLANA_RPC_URL.
• Rate limiting. If you see timeouts or "429 Too Many Requests" errors, switch to a dedicated RPC provider with higher rate limits.
• Port conflict. If the MCP server fails to start, check that port 8420 (or the port set via ORACLE_PORT) is not already in use. Change the port with export ORACLE_PORT=8421.
• Hermes Agent not recognizing the oracle. Ensure the --mcp flag is formatted exactly as blockchain=hermes-blockchain-oracle. If the package is installed in a different Python environment, Hermes Agent may not find it. Install the oracle in the same environment as Hermes Agent.
• Cache returning stale data. If you suspect cached responses, reduce CACHE_TTL_SECONDS or set it to 0 to disable caching entirely.
• Whale alerts not firing. Check that both WHALE_THRESHOLD_SOL and WHALE_THRESHOLD_USD are set to values that match the transfers you expect to detect. Both thresholds must be met.

For debugging, the sources recommend running the server standalone:

python -m hermes_blockchain_oracle --debug

This starts the MCP server in debug mode, which sets LOG_LEVEL to DEBUG and prints detailed logs to the console.