HederaToolbox

The intelligence layer for AI agents on Hedera.

23 tools. 7 modules. Pay per call in HBAR. No registration.

HederaToolbox is a production Model Context Protocol server. It gives AI agents structured, metered access to the full Hedera ecosystem — HCS topics, tokens, identity, smart contracts, governance, compliance, and Fixatum DID registration.

Built for agents that need to reason about Hedera, not just interact with it.

Demo

Claude Desktop — one business objective, no steps specified, agent decides everything:

Terminal agent — autonomous compliance workflow running headless:

Autonomous Agent Examples

Five production-ready agents in examples/. Clone the repo, fund once, run. Zero dependencies beyond Node.js 18+.

One-time setup for all agents:

bash

git clone https://github.com/mountainmystic/hederatoolbox.git
cd hederatoolbox

# Send any HBAR to the platform wallet from your Hedera account.
# Your account ID becomes your API key automatically within 10 seconds.
# Platform wallet: 0.0.10309126

Windows users: set env vars before running: set HEDERA_ACCOUNT_ID=0.0.YOUR_ID && set TOKEN_ID=0.0.731861 && node examples/whale-alert-agent.mjs Or edit the config constants directly at the top of each file.

👁️ Agent Reputation Monitor

examples/agent-reputation-monitor.mjs

Watches a list of Fixatum-registered AI agents on a schedule. Detects grade changes and significant score drops — then writes a tamper-proof record to your HCS topic when a change is observed.

Built for platforms that accept agents as counterparties, DAOs monitoring delegate agents, and operators tracking a deployed agent fleet. Polling is free (fixatum_score costs nothing) — you only pay 0.1 HBAR when an alert actually fires.

Create a watched-agents.json file next to the script:

config.json

[
  { "did": "did:hedera:mainnet:z..._0.0.123456", "label": "MyAgent" },
  { "did": "did:hedera:mainnet:z..._0.0.789012", "label": "PartnerAgent" }
]

Then run:

bash

HEDERA_ACCOUNT_ID=0.0.YOUR_ID HCS_TOPIC_ID=0.0.YOUR_TOPIC node examples/agent-reputation-monitor.mjs

# Single agent via env var:
HEDERA_ACCOUNT_ID=0.0.YOUR_ID HCS_TOPIC_ID=0.0.YOUR_TOPIC WATCH_DID=did:hedera:mainnet:z... node examples/agent-reputation-monitor.mjs

First run establishes baselines only — no alerts fire on startup. State is saved to agents-state.json and survives restarts.

Config	Default	Description
`HCS_TOPIC_ID`	required	Your HCS topic for alert records
`CHECK_INTERVAL_H`	`6`	Hours between checks
`DROP_THRESHOLD`	`10`	Point drop that triggers alert regardless of grade
`WATCH_FILE`	`watched-agents.json`	Path to your watch list

Cost: Free to poll · 0.1 ℏ per alert written to HCS

Agents without a Fixatum DID cannot be monitored. Get one at fixatum.com/register.

🔎 Compliance + KYA Onboarding

examples/compliance-kya-onboarding-agent.mjs

Screens any Hedera account before doing business with them. Runs identity resolution, on-chain risk screening, and optional KYC verification — then pulls a live Fixatum KYA trust score (0–100) for free as part of the same run. The full result is written as a single tamper-proof record to your own HCS topic.

Returns APPROVED, REJECTED, PENDING_REVIEW, or PENDING_KYC.

Designed for token issuers, DEXes, DAOs, and treasury managers who want auditable counterparty screening with a reputation layer, not just a binary pass/fail.

bash

HEDERA_ACCOUNT_ID=0.0.YOUR_ID HCS_TOPIC_ID=0.0.YOUR_TOPIC SUBJECT=0.0.999999 node examples/compliance-kya-onboarding-agent.mjs

# With KYC check and tamper verification:
HEDERA_ACCOUNT_ID=0.0.YOUR_ID HCS_TOPIC_ID=0.0.YOUR_TOPIC SUBJECT=0.0.999999 KYC_TOKEN_ID=0.0.731861 node examples/compliance-kya-onboarding-agent.mjs

HCS_TOPIC_ID is required — records write to your own topic, not a shared one. If you have a Fixatum DID, your agent_topic_id works here. Get one at fixatum.com/register.

Config	Default	Description
`SUBJECT`	`0.0.7925398`	Account to screen
`HCS_TOPIC_ID`	required	Your HCS topic for compliance records
`KYC_TOKEN_ID`	none	Optional: your token ID for KYC check
`SKIP_VERIFY`	`false`	Set `true` to skip tamper verification

Cost: ~1.3 ℏ base · ~2.3 ℏ with verify · ~2.8 ℏ with verify + KYC

Note: identity_check_sanctions is on-chain behavioural analysis of Hedera transaction patterns only. It is not a legal sanctions check against any government watchlist.

🐋 Whale Alert Monitor

examples/whale-alert-agent.mjs

Monitors any Hedera token for unusual whale concentration on a schedule. When top-10 holders exceed your threshold, writes a tamper-proof whale_alert record to HCS and prints the Hashscan proof URL.

bash

HEDERA_ACCOUNT_ID=0.0.YOUR_ID TOKEN_ID=0.0.731861 node examples/whale-alert-agent.mjs

Config	Default	Description
`TOKEN_ID`	`0.0.731861`	Token to monitor
`THRESHOLD_PCT`	`80`	Alert if top-10 holders exceed this %
`CHECK_INTERVAL_MS`	`3600000`	Check every hour

Cost: 0.2 ℏ per check · 5 ℏ only when anomaly fires

🔍 Token Due Diligence

examples/token-due-diligence-agent.mjs

Full investment and listing due diligence on any Hedera token in one run. Pulls price data, deep holder analysis, admin key risks, and treasury account identity — outputs a structured risk report with an overall verdict.

bash

HEDERA_ACCOUNT_ID=0.0.YOUR_ID TOKEN_ID=0.0.731861 node examples/token-due-diligence-agent.mjs

Cost: ~1.0 ℏ per report (token_price + token_analyze + identity_resolve on treasury)

🗳️ DAO Governance Monitor

examples/dao-monitor-agent.mjs

Watches active governance proposals for a Hedera token on a schedule. Alerts when a proposal is closing within 24 hours. Pass --analyze with a PROPOSAL_ID for deep vote tally and outcome prediction.

bash

# Monitor proposals
HEDERA_ACCOUNT_ID=0.0.YOUR_ID TOKEN_ID=0.0.731861 node examples/dao-monitor-agent.mjs

# Deep-analyze a specific proposal (requires HCS topic)
HEDERA_ACCOUNT_ID=0.0.YOUR_ID TOKEN_ID=0.0.731861 TOPIC_ID=0.0.999 PROPOSAL_ID=42 node examples/dao-monitor-agent.mjs --analyze

Cost: 0.2 ℏ per check · 1.0 ℏ for deep analysis · 10 ℏ covers ~12 days at 4 checks/day

Connect

MCP endpoint:

Code

https://api.hederatoolbox.com/mcp

Claude.ai (web or mobile) Settings → Connectors → Add → paste the endpoint URL above.

Claude Desktop app

Step 1 — install the package globally (required, do this once):

Terminal

npm install -g @hederatoolbox/platform

Step 2 — add to claude_desktop_config.json under mcpServers:

config.json

{
  "mcpServers": {
    "hederatoolbox": {
      "command": "npx",
      "args": ["-y", "@hederatoolbox/platform"]
    }
  }
}

Restart Claude Desktop after saving the config.

Windows users: if you see npm error could not determine executable to run, your npm global directory may not exist yet. Run these first:
Code
mkdir %APPDATA%\npm
npm config set prefix %APPDATA%\npm
npm install -g @hederatoolbox/platform

OpenClaw / ClawHub

Install the HederaToolbox skill directly from ClawHub:

bash

clawhub install mountainmystic/hederatoolbox

Then add your Hedera account ID to your OpenClaw environment:

Code

HEDERA_ACCOUNT_ID=0.0.YOUR_ACCOUNT_ID

Skill listing: clawhub.ai/mountainmystic/hederatoolbox

Cursor / other MCP-compatible clients Use the endpoint URL directly in your MCP server config.

How It Works

HederaToolbox uses agent-native HBAR payments. No accounts, no OAuth, no email.

Code

1. get_terms        -> read the Terms of Service         (free)
2. confirm_terms    -> record consent                    (free)
3. account_info     -> get platform wallet + pricing     (free)
4. send HBAR        -> your account ID becomes your key  (auto-provisioned)
5. call any tool    -> pass your Hedera account ID as api_key

Platform wallet: 0.0.10309126 (mainnet)

Credits are persistent. Unused balance carries over indefinitely.

Safety Architecture

All safety controls run server-side and cannot be bypassed by modifying the npm package.

Consent gate — confirm_terms required before any paid tool executes
Atomic balance deduction — balance check and deduct are a single SQL operation, race-condition proof
Loop guard — same tool called >20 times in 60s by the same key is blocked automatically
No private keys — we never see your private key and never ask for it. You authenticate with your Hedera account ID — a public identifier, like a username. Your key stays in your wallet.

Tools

Free — Onboarding and Legal

Tool	Description
`get_terms`	Machine-readable Terms of Service. Call before anything else.
`confirm_terms`	Record consent. Required before any paid tool.
`account_info`	Platform wallet address, full pricing table, your balance.

Module 1 — HCS Topic Intelligence

Tool	Cost	Description
`hcs_monitor`	0.10 HBAR	Topic status, message count, recent activity
`hcs_query`	0.10 HBAR	Natural language Q&A over topic messages, AI-ranked
`hcs_understand`	1.00 HBAR	Anomaly detection, trend analysis, entity extraction

Module 2 — Compliance and Audit Trail

Tool	Cost	Description
`hcs_write_record`	0.10 HBAR	Write tamper-evident record to HCS — optionally signed with your DID key
`hcs_verify_record`	1.00 HBAR	Check a record's hash, and re-check its agent signature if it has one
`hcs_audit_trail`	2.00 HBAR	Full chronological audit history for an entity

Module 3 — Governance Intelligence

Tool	Cost	Description
`governance_monitor`	0.20 HBAR	Active proposals, deadlines, current vote tallies
`governance_analyze`	1.00 HBAR	Voter sentiment, participation rate, outcome prediction

Module 4 — Token Intelligence

Tool	Cost	Description
`token_price`	0.10 HBAR	Spot price, 1h/24h/7d change, liquidity — via SaucerSwap
`token_monitor`	0.20 HBAR	Recent transfers, whale movements, unusual patterns
`token_analyze`	0.60 HBAR	Holder distribution, velocity, concentration, risk score

Module 5 — Identity Resolution

Tool	Cost	Description
`identity_resolve`	0.20 HBAR	Account profile: age, holdings, transaction history
`identity_verify_kyc`	0.50 HBAR	KYC grant status and verification history for a token
`identity_check_sanctions`	1.00 HBAR	On-chain risk screening, counterparty patterns

Module 6 — Smart Contract Intelligence

Tool	Cost	Description
`contract_read`	0.20 HBAR	Metadata, bytecode size, recent callers, gas stats
`contract_call`	1.00 HBAR	Read-only function call — no gas, no transaction
`contract_analyze`	1.50 HBAR	Activity patterns, caller distribution, risk classification

Accepts both Hedera native IDs (0.0.123456) and EVM addresses (0x...).

Module 7 — Fixatum DID Identity

Tool	Cost	Description
`fixatum_register`	100 HBAR	Register for a permanent W3C DID anchored to Hedera HCS and a live KYA trust score
`fixatum_score`	Free	Query live KYA score (0–100, grade A–F) and component breakdown for any registered agent
`fixatum_status`	Free	Check registration status, current score, and whether provenance is actively building

Call fixatum_register without ed25519_public_key to get key generation instructions first — no charge until registration proceeds.

Changelog

v4.0.0 — Agent-signed HCS records. Pass agent_did and agent_signature to hcs_write_record to write a record signed with your Fixatum DID key — records are now marked agent_signed or platform_witnessed, and hcs_verify_record re-checks the signature independently. A signature that does not match is rejected and the call is not charged.

Breaking: hcs_verify_record no longer returns the top-level verified field. Read tamper_check instead — it returns "intact" or "mismatch". The hash_valid and tampered fields are unchanged, so callers reading those need no change.

v3.5.3 — Fixatum DID module added (fixatum_register, fixatum_score, fixatum_status) — 23 tools, 7 modules

v3.4.5 — Agent examples improved, xagent persona rewrite

v3.4.2 — X agent (Telegram-gated autonomous tweet drafting), agent examples added to repo

v3.4.0 — Repriced all tools across all 6 modules

v3.3.1 — Full security audit: SQLite-backed rate limiting, API key validation, 1MB body cap, separate BACKUP_SECRET, 90-day PII purge, HITL removed, legal pages deployed

Known Limitations

Mirror node balance endpoint occasionally returns empty for high-holder tokens. Metadata unaffected.

Links


npm	https://www.npmjs.com/package/@hederatoolbox/platform
MCP Registry	https://registry.modelcontextprotocol.io/?q=hederatoolbox
Glama	https://glama.ai/mcp/servers/mountainmystic/hederatoolbox
ClawHub	https://clawhub.ai/mountainmystic/hederatoolbox
Live endpoint	https://api.hederatoolbox.com/mcp
Terms	https://api.hederatoolbox.com/terms

Note: The old package @hederaintel/platform is deprecated. Update your config to use @hederatoolbox/platform.

License

npm package — provided for integration use only.

Remote server and all backend logic — Proprietary. See LICENSE.md.

Enterprise licensing and SLA inquiries: open an issue titled [Enterprise].

Website

hederatoolbox.com

On-Chain Identity

HederaToolbox has a permanent platform identity record written to Hedera mainnet.

Field	Value
HCS Topic	`0.0.10353855`
Record ID	`c420c3b9-408e-4f87-a9e1-1dcbb54facfa`
Transaction	`0.0.10309126@1773623419.733217779`
Written	16 March 2026
Verify	hashscan.io/mainnet/topic/0.0.10353855