# HederaToolbox — Agent Onboarding Guide

**Version:** 3.5.3 · **Endpoint:** `https://api.hederatoolbox.com/mcp`
**Transport:** SSE (Server-Sent Events) · **Protocol:** MCP (Model Context Protocol)

HederaToolbox gives AI agents metered, pay-per-call access to live Hedera blockchain data via HBAR micropayments. No registration, no API keys to manage — your Hedera account ID is your API key.

---

## Quick Start (3 steps)

### Step 1 — Fund your account
Send any amount of HBAR to the platform wallet:
```
0.0.10309126
```
No memo required. Your Hedera account ID becomes your API key within ~10 seconds.

### Step 2 — Accept terms
Call `confirm_terms` once before using any paid tool:
```json
{
  "name": "confirm_terms",
  "arguments": {
    "api_key": "0.0.YOUR_ACCOUNT_ID"
  }
}
```
This is required. Paid tools will return an error until this is done.

### Step 3 — Call tools
```json
{
  "name": "token_price",
  "arguments": {
    "token_id": "0.0.786931",
    "api_key": "0.0.YOUR_ACCOUNT_ID"
  }
}
```

---

## Connecting via MCP

**Endpoint:** `https://api.hederatoolbox.com/mcp`
**Method:** POST
**Headers:**
```
Content-Type: application/json
Accept: application/json, text/event-stream
```

**Request format (JSON-RPC 2.0):**
```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "TOOL_NAME",
    "arguments": {
      "api_key": "0.0.YOUR_ACCOUNT_ID",
      ...other args
    }
  }
}
```

The endpoint returns Server-Sent Events. Parse `data:` lines, scan backward for the last valid JSON frame — that is your tool result.

---

## Tool List & Pricing

### Free Tools (no balance required)
| Tool | Description |
|---|---|
| `get_terms` | Returns current Terms of Service |
| `confirm_terms` | Accepts ToS — call once before paid tools |
| `account_info` | Check your balance and account status |

### HCS Module
| Tool | Cost | Description |
|---|---|---|
| `hcs_monitor` | 0.10 ħ | Topic status, message count, metadata |
| `hcs_query` | 0.10 ħ | Natural language query on an HCS topic |
| `hcs_understand` | 1.00 ħ | Deep pattern analysis, anomaly detection |
| `hcs_write_record` | 0.10 ħ | Write a tamper-evident record to an HCS topic |
| `hcs_verify_record` | 1.00 ħ | Verify a record has not been tampered |
| `hcs_audit_trail` | 2.00 ħ | Full chronological audit trail for an entity |

> **Note:** `hcs_write_record` requires `topic_id` — there is no default fallback topic. You must own or have access to the topic you write to.

### Token Module
| Tool | Cost | Description |
|---|---|---|
| `token_price` | 0.10 ħ | Spot price, 24h change, market cap |
| `token_monitor` | 0.20 ħ | Whale movements, unusual transfer patterns |
| `token_analyze` | 0.60 ħ | Deep holder distribution, velocity, liquidity |

### Identity Module
| Tool | Cost | Description |
|---|---|---|
| `identity_resolve` | 0.20 ħ | Resolve account to on-chain profile |
| `identity_verify_kyc` | 0.50 ħ | KYC status for a token |
| `identity_check_sanctions` | 1.00 ħ | On-chain behavioural risk screening |

> **Important:** `identity_check_sanctions` is on-chain behavioural analysis of Hedera transaction patterns only. It is NOT a legal sanctions check against OFAC, UN, EU, or any government watchlist.

### Governance Module
| Tool | Cost | Description |
|---|---|---|
| `governance_monitor` | 0.20 ħ | Active proposals, vote deadlines |
| `governance_analyze` | 1.00 ħ | Deep proposal analysis, voter sentiment |

### Contract Module
| Tool | Cost | Description |
|---|---|---|
| `contract_read` | 0.20 ħ | Contract info, bytecode, recent activity |
| `contract_call` | 1.00 ħ | Read-only call to a contract function |
| `contract_analyze` | 1.50 ħ | Deep analysis: caller distribution, gas, risk |

### Fixatum Module
| Tool | Cost | Description |
|---|---|---|
| `fixatum_register` | 100 ħ | Register a Fixatum DID for this account |
| `fixatum_score` | Free | Query credibility score for a DID |
| `fixatum_status` | Free | Check registration status for an account |

---

## Common Errors

| Error | Cause | Fix |
|---|---|---|
| `Terms not accepted` | `confirm_terms` not called | Call `confirm_terms` first |
| `Insufficient balance` | Account balance too low | Send more HBAR to `0.0.10309126` |
| `Invalid API key format` | Key not in `0.0.XXXXXX` format | Use your full Hedera account ID |
| `API key required` | No `api_key` in arguments | Add `api_key` to every tool call |
| `topic_id required` | Missing topic for `hcs_write_record` | Pass a valid HCS topic ID |

---

## Checking Your Balance
```json
{
  "name": "account_info",
  "arguments": {
    "api_key": "0.0.YOUR_ACCOUNT_ID"
  }
}
```
Returns balance in HBAR, account creation date, and last activity.

---

## Topping Up
Send any amount of HBAR to `0.0.10309126` at any time. No memo. Balance updates within ~10 seconds. There is no minimum — send what you need.

---

## Getting a Fixatum DID (Identity Layer)

If you want a permanent, verifiable on-chain identity and credibility score, register with Fixatum:

1. Call `fixatum_register` (100 HBAR, deducted from your Toolbox balance)
2. Your DID is issued, anchored to HCS, and a dedicated topic is created for your agent
3. Every Toolbox call you make builds your provenance score automatically
4. Query your score anytime: `https://did.fixatum.com/score/YOUR_DID`

Or register directly at `https://fixatum.com`

---

## Full Stack Context

- **HederaToolbox** — data layer. Live Hedera blockchain queries, metered per call.
- **Fixatum** — identity layer. DIDs and credibility scores built on Toolbox provenance.
- Both are built for autonomous agents. No human steps required in any pipeline.

**More info:**
- Website: `https://hederatoolbox.com`
- Machine-readable spec: `https://hederatoolbox.com/agent.txt`
- Fixatum: `https://fixatum.com`