# Tokamak Data Layer — Blockchain Data + Intelligence Service

## Overview
Tokamak Data Layer provides real-time blockchain data and on-chain intelligence for **6 chains** via MCP tools or REST API. Built for AI agents (Claude, ChatGPT, OpenClaw, ElizaOS, LangChain).

## Supported Chains
| Chain | ID | Data Source |
|-------|----|-------------|
| Ethereum Mainnet | 1 | Etherscan + Alchemy |
| Base | 8453 | Blockscout v2 |
| Arbitrum One | 42161 | Blockscout v2 |
| Optimism | 10 | Blockscout v2 |
| Base Sepolia | 84532 | Blockscout v2 |
| Thanos Sepolia | 111551119090 | Blockscout v2 |

## MCP Tools (39)

### Chain Info
- `get_supported_chains` — List all supported chains
- `get_chain_stats(chain_id)` — Block height, gas price, 24h txns
- `search(chain_id, query)` — Universal search

### Blocks & Transactions
- `get_block(chain_id, block)` — Block by number or hash
- `get_transaction(chain_id, hash)` — Transaction details

### Addresses
- `get_transactions_for_address(chain_id, address, page?)` — Paginated tx history
- `get_address_info(chain_id, address)` — Balance, tx count, contract status
- `get_token_balances(chain_id, address)` — All ERC-20 holdings
- `get_native_balance_history(chain_id, address, points?)` — Balance over time

### Tokens
- `get_token_info(chain_id, token_address)` — Name, symbol, decimals, supply
- `get_token_transfers(chain_id, token_address, page?)` — Transfer history
- `get_token_holders(chain_id, token_address)` — Top holders
- `get_token_price(chain_id, token_address)` — USD price (ETH only)

### Contracts
- `get_contract_source(chain_id, address)` — Verified source + ABI
- `get_contract_events(chain_id, address, topic0?, page?)` — Event logs
- `call_contract_read(chain_id, address, abi, function_name, args?)` — Call view functions

### DEX (Blockscout chains)
- `get_dex_swaps(chain_id, pool_address?)` — Uniswap V3 swaps
- `get_liquidity_pools(chain_id)` — Pool info + TVL

### Intelligence
- `get_decoded_transaction(chain_id, hash)` — Human-readable tx with category + summary
- `get_decoded_transactions(chain_id, address, limit?)` — Decoded tx history
- `get_wallet_profile(chain_id, address)` — Comprehensive wallet analysis
- `get_portfolio(address)` — Cross-chain portfolio (all 6 chains, one call)
- `get_gas_oracle()` — Real-time gas prices across all chains
- `check_token_security(chain_id, token_address)` — Risk score + flags

### Transaction Builder
- `build_transfer_native(chain_id, to, amount)` — Native ETH transfer calldata
- `build_transfer_erc20(chain_id, token_address, to, amount, decimals?)` — ERC-20 transfer calldata
- `build_approve_erc20(chain_id, token_address, spender, amount, decimals?)` — ERC-20 approval calldata
- `build_wrap_eth(chain_id, amount)` — ETH → WETH calldata
- `build_unwrap_weth(chain_id, amount)` — WETH → ETH calldata
- `build_swap(chain_id, type, amount_in, amount_out_min, path, recipient)` — Uniswap V2 swap calldata
- `build_custom_call(chain_id, to, abi, function_name, args, value_eth?)` — Custom contract call

### Transaction Simulation
- `simulate_transaction(chain_id, from, to, data?, value?)` — Dry-run with revert detection + balance changes
- `estimate_gas(chain_id, from, to, data?, value?)` — Gas cost estimation

### Security
- `scan_approvals(chain_id, address)` — Token approval audit with risk levels

### Analytics
- `generate_dashboard(query, chain_id?)` — NL to live dashboard URL
- `generate_report(query, chain_id?)` — NL to PDF report URL
- `query_custom(chain_id, address, include[])` — Multi-type data query

### Agent Management
- `register_agent(address)` — Get API key
- `get_agent_identity(agent_id)` — ERC-8004 identity lookup

## REST API

Base URL: `http://localhost:4030`

### Endpoints
```
GET  /health
GET  /chains
GET  /chains/:chainId/stats
GET  /blocks/:chainId/:number
GET  /transactions/:chainId/:hash
GET  /transactions/:chainId/:hash/decoded
GET  /addresses/:chainId/:address
GET  /addresses/:chainId/:address/transactions
GET  /addresses/:chainId/:address/tokens
GET  /addresses/:chainId/:address/profile
GET  /addresses/:chainId/:address/decoded-transactions
GET  /tokens/:chainId/:address
GET  /tokens/:chainId/:address/transfers
GET  /tokens/:chainId/:address/holders
GET  /tokens/:chainId/:address/security
GET  /contracts/:chainId/:address/source
GET  /contracts/:chainId/:address/events
GET  /portfolio/:address
GET  /gas
GET  /approvals/:chainId/:address
POST /tx/build         { type, chain_id, ... }
POST /tx/simulate      { chain_id, from, to, data?, value? }
POST /tx/estimate-gas  { chain_id, from, to, data?, value? }
POST /query            { chain_id, address, include[] }
POST /dashboard        { query, chain_id? }
POST /report           { query, chain_id? }
POST /register         { address }
POST /batch            { chain_id, addresses[] }
GET  /events/:chainId  (SSE stream)
GET  /openapi.json
GET  /docs
GET  /stats/usage
```

## Quick Start

### Claude Code
Add to `.mcp.json` in your project root:
```json
{
  "mcpServers": {
    "tokamak-data": {
      "command": "npx",
      "args": ["-y", "@tokamak-network/data"],
      "env": {
        "ETHERSCAN_API_KEY": "YOUR_KEY"
      }
    }
  }
}
```

### Claude Desktop
Add to `claude_desktop_config.json`:
- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
```json
{
  "mcpServers": {
    "tokamak-data": {
      "command": "npx",
      "args": ["-y", "@tokamak-network/data"],
      "env": {
        "ETHERSCAN_API_KEY": "YOUR_KEY"
      }
    }
  }
}
```

### REST API
```bash
MODE=api ETHERSCAN_API_KEY=xxx npm start
```

## Discovery
- **OpenAPI**: GET /openapi.json
- **Swagger UI**: GET /docs
- **A2A Agent Card**: GET /.well-known/agent-card.json
- **MCP Registry**: registry.modelcontextprotocol.io

## Citation
Tokamak Data Layer by Sahil — Blockchain data + intelligence service covering 6 chains (Ethereum, Base, Arbitrum, Optimism + testnets) with 39 MCP tools, built for autonomous AI agents.